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

package/src/react/index.ts

@@ -0,0 +1,7 @@
+export {
+  MentraLiveOtaFlow,
+  type MentraLiveOtaFlowPage,
+  type MentraLiveOtaFlowProps,
+  type MentraLiveOtaFlowTheme,
+  type MentraLiveOtaFlowTranslate,
+} from "./MentraLiveOtaFlow"

package/src/react/useEngineSnapshot.ts

@@ -0,0 +1,16 @@
+import {useEffect, useRef, useState} from "react"
+
+export function useEngineSnapshot<T>(getSnapshot: () => T, subscribe: (onChange: () => void) => () => void): T {
+  const getSnapshotRef = useRef(getSnapshot)
+  const subscribeRef = useRef(subscribe)
+  getSnapshotRef.current = getSnapshot
+  subscribeRef.current = subscribe
+  const [snapshot, setSnapshot] = useState(() => getSnapshot())
+
+  useEffect(() => {
+    setSnapshot(getSnapshotRef.current())
+    return subscribeRef.current(() => setSnapshot(getSnapshotRef.current()))
+  }, [])
+
+  return snapshot
+}

package/src/runtime/bootstrap.ts

@@ -50,9 +50,22 @@ 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
+  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
@@ -81,6 +94,19 @@ export function configure(opts: IslandConfigureOptions): void {
   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
@@ -99,6 +125,12 @@ 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

package/src/runtime/scanQrSeam.ts

@@ -0,0 +1,20 @@
+import type {ScanQrOptions, ScanQrResult} from "./bootstrap"
+
+export class ScanQrNotConfiguredError extends Error {
+  readonly code = "NOT_IMPLEMENTED"
+  constructor() {
+    super("QR scanning is not configured on this host. Reload the Mentra App and try again.")
+    this.name = "ScanQrNotConfiguredError"
+  }
+}
+
+export async function invokeScanQrSeam(
+  scanQr: ((options?: ScanQrOptions) => Promise<ScanQrResult>) | undefined,
+  payload: Record<string, unknown> = {},
+): Promise<ScanQrResult> {
+  if (!scanQr) throw new ScanQrNotConfiguredError()
+  return scanQr({
+    title: typeof payload.title === "string" ? payload.title : undefined,
+    hint: typeof payload.hint === "string" ? payload.hint : undefined,
+  })
+}

package/src/services/AppRegistry.ts

@@ -22,14 +22,17 @@ import {unzip} from "react-native-zip-archive"
 import semver from "semver"
 import {AsyncResult, Result, result as Res} from "typesafe-ts"
 
-import type {AppletPermission, AppPermissionType, AppletType, ClientApp, DeclaredAction} from "../types/applet"
+import type {AppletPermission, AppPermissionType, AppletType, ClientApp} from "../types/applet"
 import {HardwareRequirement, HardwareRequirementLevel, HardwareType} from "../types"
-import {getConfigValues} from "../runtime/bootstrap"
+import {configuredDevHost} from "../utils/configuredDevHost"
 import {storage} from "../utils/storage/storage"
 import {printDirectory} from "../utils/storage/zip"
 import {checkManifestVersions} from "./manifestVersionGate"
+import {normalizeManifestActions} from "./manifestActions"
 import {miniappRunningRegistry} from "./MiniappRunningRegistry"
 
+export {normalizeManifestActions} from "./manifestActions"
+
 const ALLOWED_PERMISSION_TYPES: ReadonlySet<AppPermissionType> = new Set<AppPermissionType>([
   "MICROPHONE",
   "CAMERA",
@@ -73,29 +76,6 @@ function normalizeManifestType(raw: unknown): AppletType {
   return raw === "background" || raw === "system_dashboard" || raw === "standard" ? raw : "standard"
 }
 
-/**
- * Normalize a manifest's `actions` into DeclaredAction[]. Defensive — keeps only
- * well-formed `{id, description}` entries (installed/dev bundles may be
- * malformed). Shared by installed (disk) and dev-sideload projection so both
- * surface declared actions to session.miniapps.list + the invoke gate.
- */
-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}>) {
-    if (a && typeof a.id === "string" && typeof a.description === "string") {
-      out.push({
-        id: a.id,
-        description: a.description,
-        ...(a.parameters && typeof a.parameters === "object"
-          ? {parameters: a.parameters as Record<string, unknown>}
-          : {}),
-      })
-    }
-  }
-  return out
-}
-
 /**
  * Convert declared hardwareRequirements from a miniapp.json manifest into
  * runtime `HardwareRequirement[]`, always appending `{EXIST, REQUIRED}` so
@@ -159,6 +139,17 @@ interface InstalledLma {
   versions: Record<string, InstalledInfo>
 }
 
+export interface MiniappReleaseIdentity {
+  source: "direct_download" | "bundled_asset" | "preinstalled_registry" | "dev_snapshot"
+  releaseId?: string
+  bundleSha256?: string
+  channel?: string
+}
+
+function releaseIdentityKey(packageName: string, version: string): string {
+  return `miniapp_release_identity:${packageName}:${version}`
+}
+
 /**
  * Download a miniapp zip from `url` into the cache and return its local path.
  *
@@ -451,11 +442,18 @@ class AppRegistry {
    *   of `manifest.version`. The dev caching path uses `dev-<ms>` so multiple
    *   snapshots can coexist alongside semver-installed versions.
    */
-  public installFromUrl(url: string, opts?: {versionOverride?: string}): AsyncResult<void, Error> {
+  public installFromUrl(
+    url: string,
+    opts?: {versionOverride?: string; releaseIdentity?: MiniappReleaseIdentity},
+  ): AsyncResult<void, Error> {
     return Res.try_async(async () => {
       const {packageName, version} = await downloadAndInstallMiniApp(url, opts?.versionOverride)
       console.log("APP_REGISTRY: Downloaded and installed mini app")
-      this.finalizeInstall(packageName, version)
+      this.finalizeInstall(
+        packageName,
+        version,
+        opts?.releaseIdentity ?? {source: version.startsWith("dev-") ? "dev_snapshot" : "direct_download"},
+      )
     })
   }
 
@@ -468,12 +466,12 @@ class AppRegistry {
    */
   public installFromLocalZip(
     zipPath: string,
-    opts?: {versionOverride?: string},
+    opts?: {versionOverride?: string; releaseIdentity?: MiniappReleaseIdentity},
   ): AsyncResult<{packageName: string; version: string}, Error> {
     return Res.try_async(async () => {
       const {packageName, version} = await unpackMiniApp(zipPath, opts?.versionOverride)
       console.log("APP_REGISTRY: Installed mini app from local zip")
-      this.finalizeInstall(packageName, version)
+      this.finalizeInstall(packageName, version, opts?.releaseIdentity ?? {source: "bundled_asset"})
       return {packageName, version}
     })
   }
@@ -483,7 +481,7 @@ class AppRegistry {
    * artifacts on release installs, point the active-version at the just-
    * installed bundle, and notify subscribers to refresh.
    */
-  private finalizeInstall(packageName: string, version: string): void {
+  private finalizeInstall(packageName: string, version: string, releaseIdentity: MiniappReleaseIdentity): void {
     // If this is a release install (semver, not dev-*) of a package that
     // currently has dev-* snapshots, clear the dev state so the swap to
     // "released" is clean. Otherwise the dev version would keep winning
@@ -495,10 +493,16 @@ class AppRegistry {
     }
 
     this.setActiveVersion(packageName, version)
+    storage.save(releaseIdentityKey(packageName, version), releaseIdentity)
     this.refreshNeeded = true
     this.notify()
   }
 
+  public getReleaseIdentity(packageName: string, version: string): MiniappReleaseIdentity | null {
+    const result = storage.load<MiniappReleaseIdentity>(releaseIdentityKey(packageName, version))
+    return result.is_ok() ? result.value : null
+  }
+
   public installFromJsonUrl(baseUrl: string): AsyncResult<{packageName: string; version: string; name: string}, Error> {
     return Res.try_async(async () => {
       const trimmed = baseUrl.replace(/\/$/, "")
@@ -534,6 +538,7 @@ class AppRegistry {
         for (const item of pkgDir.list()) {
           if (item instanceof Directory && item.name.startsWith("dev-")) {
             try {
+              storage.remove(releaseIdentityKey(packageName, item.name))
               item.delete()
             } catch (e) {
               console.warn(`APP_REGISTRY: failed to delete ${item.name}:`, e)
@@ -546,6 +551,7 @@ class AppRegistry {
     }
     storage.remove(`${packageName}_dev_url`)
     storage.remove(`${packageName}_dev_port`)
+    storage.remove(`${packageName}_dev_mdns`)
     storage.remove(`${packageName}_dev_last_reachable`)
     // HTTP-direct dev miniapps are indexed by their real package name. A
     // release install/uninstall of that same package should remove only its
@@ -588,12 +594,16 @@ class AppRegistry {
         // Guard exists: a dev miniapp loads over HTTP and has no on-disk dir,
         // so an unconditional delete() would throw and abort the cleanup below.
         if (lmaDir.exists) lmaDir.delete()
+        storage.remove(releaseIdentityKey(packageName, version))
         console.log("APP_REGISTRY: Uninstalled mini app version", version)
         const packageDir = new Directory(Paths.document, "lmas", packageName)
         if (packageDir.exists && packageDir.list().length === 0) {
           packageDir.delete()
         }
       } else {
+        for (const installedVersion of this.getInstalledVersions(packageName)) {
+          storage.remove(releaseIdentityKey(packageName, installedVersion))
+        }
         const packageDir = new Directory(Paths.document, "lmas", packageName)
         if (packageDir.exists) {
           packageDir.delete()
@@ -732,7 +742,7 @@ class AppRegistry {
           permissions?: Array<string | {type: string; required?: boolean; description?: string}>
           hardwareRequirements?: Array<{type: string; level: string; description?: string}>
           type?: string
-          actions?: Array<{id?: unknown; description?: unknown; parameters?: unknown}>
+          actions?: Array<{id?: unknown; description?: unknown; parameters?: unknown; outputSchema?: unknown}>
         } | null
 
         const permissions = normalizeManifestPermissions(manifest?.permissions)
@@ -930,11 +940,17 @@ export interface DevAppRecord {
   iconUrl: string
   devUrl: string
   devPort?: number
+  /**
+   * Bonjour / mDNS hostname from the QR (`ComputerName.local`). Used as a
+   * failover host when the raw LAN IP in `devUrl` goes stale after a Wi-Fi
+   * change — phones that resolve `.local` can relaunch without re-scanning.
+   */
+  mdnsHost?: string
   type?: AppletType
   permissions?: Array<string | {type: string; required?: boolean; description?: string}>
   hardwareRequirements?: Array<{type: string; level: string; description?: string}>
   /** Manifest-declared actions — so dev-sideloaded miniapps can be invoked too. */
-  actions?: Array<{id?: unknown; description?: unknown; parameters?: unknown}>
+  actions?: Array<{id?: unknown; description?: unknown; parameters?: unknown; outputSchema?: unknown}>
   /** Legacy single-slot migration field. New records use the real packageName directly. */
   sourcePackageName?: string
   /**
@@ -948,22 +964,6 @@ export interface DevAppRecord {
 const DEV_APPS_INDEX_KEY = "dev_apps_index"
 const DEV_APP_ICONS_DIR = "dev-miniapp-icons"
 
-function configuredDevHost(): string | undefined {
-  // Explicit escape hatch first; otherwise the host-injected Metro host (the
-  // address this dev bundle was served from — always current for the network
-  // the phone is on). Deliberately NOT the EXPO_PUBLIC_CLOUD_* URLs: those are
-  // cloud endpoints, a different machine entirely from the laptop running the
-  // miniapp dev server, and rewriting a dev URL to a cloud host would break it.
-  const explicit = process.env.EXPO_PUBLIC_LOCAL_MINIAPP_HOST
-  if (explicit) {
-    try {
-      return new URL(explicit).hostname
-    } catch {
-      if (/^[\w.-]+$/.test(explicit)) return explicit
-    }
-  }
-  return getConfigValues().devServerHost?.()
-}
 
 function isPrivateLanHost(hostname: string): boolean {
   return (
@@ -1054,6 +1054,7 @@ function removeDevRecordKeys(packageName: string): void {
   storage.remove(`${packageName}_dev_meta`)
   storage.remove(`${packageName}_dev_url`)
   storage.remove(`${packageName}_dev_port`)
+  storage.remove(`${packageName}_dev_mdns`)
   storage.remove(`${packageName}_dev_last_reachable`)
 }
 
@@ -1092,16 +1093,28 @@ function migrateLegacyDevSlot(): void {
     const port = migrated.devPort ?? (legacyPort.is_ok() ? legacyPort.value : undefined)
     if (typeof port === "number" && Number.isFinite(port)) storage.save(`${targetPackage}_dev_port`, port)
   }
+  const legacyMdns = storage.load<string>(`${DEV_APP_PACKAGE_NAME}_dev_mdns`)
+  const targetMdns = storage.load<string>(`${targetPackage}_dev_mdns`)
+  if (!targetMdns.is_ok() && legacyMdns.is_ok() && legacyMdns.value.trim()) {
+    storage.save(`${targetPackage}_dev_mdns`, legacyMdns.value.trim())
+  }
 
   storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_meta`)
   storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_url`)
   storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_port`)
+  storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_mdns`)
   storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_last_reachable`)
 
   const index = Array.from(new Set(getDevAppIndex().map((pkg) => (pkg === DEV_APP_PACKAGE_NAME ? targetPackage : pkg))))
   storage.save(DEV_APPS_INDEX_KEY, JSON.stringify(index))
 }
 
+function readStoredMdnsHost(packageName: string): string | undefined {
+  const res = storage.load<string>(`${packageName}_dev_mdns`)
+  if (!res.is_ok()) return undefined
+  return res.value.trim() || undefined
+}
+
 /**
  * Register or update one dev miniapp under its real manifest package. Different
  * package names coexist; rescanning the same package updates that package only.
@@ -1112,12 +1125,18 @@ export async function registerDevApp(record: DevAppRecord): Promise<void> {
   if (!packageName) throw new Error("Dev miniapp manifest is missing packageName")
 
   const iconUrl = await cacheDevAppIcon(packageName, record.iconUrl)
+  // Relaunch paths (developer-URL screen, loadDevMiniapp) omit mdnsHost, so an
+  // omitted field keeps whatever the QR scan stored instead of wiping the
+  // `.local` failover host.
+  const mdnsHost =
+    record.mdnsHost !== undefined ? record.mdnsHost.trim() || undefined : readStoredMdnsHost(packageName)
   const devRecord: DevAppRecord = {
     ...record,
     packageName,
     sourcePackageName: packageName,
     name: record.name || DEV_APP_NAME,
     iconUrl,
+    mdnsHost,
   }
   storage.save(`${packageName}_dev_meta`, JSON.stringify(devRecord))
   storage.save(`${packageName}_dev_url`, record.devUrl)
@@ -1126,6 +1145,11 @@ export async function registerDevApp(record: DevAppRecord): Promise<void> {
   } else {
     storage.remove(`${packageName}_dev_port`)
   }
+  if (mdnsHost) {
+    storage.save(`${packageName}_dev_mdns`, mdnsHost)
+  } else {
+    storage.remove(`${packageName}_dev_mdns`)
+  }
   const idx = getDevAppIndex()
   if (!idx.includes(packageName)) {
     idx.push(packageName)

package/src/services/AudioCloudUplink.ts

@@ -21,9 +21,15 @@ let sub: {remove: () => void} | null = null
 const suppressionSources = new Set<string>()
 
 /**
- * Keep the glasses LC3 transport alive while preventing spoken TTS from being
- * ingested by cloud STT. Sources are reference-counted by id so overlapping
- * speech playback cannot reopen the uplink until every active prompt has ended.
+ * Keep the glasses LC3 transport alive while dropping mic audio before cloud
+ * STT. Sources are reference-counted by id so overlapping playback cannot
+ * reopen the uplink until every active source has released.
+ *
+ * Suppression is global to the uplink: one source silences STT for every app.
+ * That is why no platform path arms it any more (spoken TTS used to, which made
+ * every assistant reply punch a hole in Live Translation and Captions). The
+ * mechanism stays because it is the right primitive for an explicit,
+ * caller-scoped mute; see OS-1741 for the per-app opt-in that will use it.
  */
 export function setAudioCloudUplinkSuppressed(sourceId: string, suppressed: boolean): void {
   if (suppressed) suppressionSources.add(sourceId)

package/src/services/AudioPlaybackService.ts

@@ -1,8 +1,9 @@
 import {createAudioPlayer, AudioPlayer, AudioStatus, setAudioModeAsync} from "expo-audio"
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
-import {Platform} from "react-native"
+import {AppState, Platform} from "react-native"
 import {BgTimer} from "../utils/timers"
 import {setAudioCloudUplinkSuppressed} from "./AudioCloudUplink"
+import {SILENT_AUDIO_SOURCE} from "./audioPlaybackAssets"
 
 const RESTORE_GLASSES_VOLUME_AFTER_PLAYBACK = false
 
@@ -12,7 +13,12 @@ interface AudioPlayRequest {
   appId?: string
   volume?: number
   stopOtherAudio?: boolean
-  /** Suppress microphone audio sent to cloud STT while this audio is audible. */
+  /**
+   * Suppress microphone audio sent to cloud STT while this audio is audible.
+   * Opt-in and off by default: the suppression is global to the uplink, so a
+   * caller that sets this silences STT for every running app, not just itself.
+   * No platform path sets it today (see AudioCloudUplink and OS-1741).
+   */
   suppressCloudUplink?: boolean
 }
 
@@ -28,6 +34,7 @@ type AudioPlaybackCompletion = (
 
 interface PlaybackState {
   requestId: string
+  audioUrl: string
   uplinkSuppressionId: string
   appId?: string
   startTime: number
@@ -38,6 +45,9 @@ interface PlaybackState {
 
 interface PendingPlaybackState {
   cancelled: boolean
+  audioUrl: string
+  appId?: string
+  createdAt: number
 }
 
 /** Open request for a live PCM output stream (miniapp speaker.createStream). */
@@ -91,9 +101,9 @@ class AudioPlaybackService {
   // window after actual audio so we only pre-roll the first sound after idle.
   private audioRouteWarmUntil = 0
   private audioRouteWarmupPromise: Promise<void> | null = null
-  // Spoken playback remains suppressed briefly while its A2DP tail drains.
-  // Track those completed sources so a new non-spoken sound can resume
-  // listening immediately instead of inheriting the previous TTS gate.
+  // Playback that opted into suppression stays suppressed briefly while its
+  // A2DP tail drains. Track those completed sources so a later unsuppressed
+  // sound can resume listening immediately instead of inheriting that gate.
   private tailUplinkSuppressions = new Set<string>()
   // Original glasses media volume captured before we bump it for A2DP playback.
   private glassesVolumeRestoreLevel: number | null = null
@@ -102,13 +112,15 @@ class AudioPlaybackService {
   private static readonly AUDIO_ROUTE_WARM_WINDOW_MS = 1500
   private static readonly AUDIO_ROUTE_PREWARM_MS = 200
   private static readonly AUDIO_ROUTE_PREWARM_SAMPLE_RATE = 16_000
+  /** Break accidental same-app replay storms without affecting deliberate later replays. */
+  private static readonly DUPLICATE_PLAY_WINDOW_MS = 750
   private static readonly AUDIO_ROUTE_PREWARM_PCM_BASE64 =
-    "AAAA".repeat(Math.floor(
-      (AudioPlaybackService.AUDIO_ROUTE_PREWARM_MS *
-        AudioPlaybackService.AUDIO_ROUTE_PREWARM_SAMPLE_RATE *
-        2) /
-        (1000 * 3),
-    )) + "AA=="
+    "AAAA".repeat(
+      Math.floor(
+        (AudioPlaybackService.AUDIO_ROUTE_PREWARM_MS * AudioPlaybackService.AUDIO_ROUTE_PREWARM_SAMPLE_RATE * 2) /
+          (1000 * 3),
+      ),
+    ) + "AA=="
   /** If glasses report step volume at or below this, bump to FLOOR before A2DP playback. */
   private static readonly GLASSES_VOLUME_LOW_THRESHOLD = 2
   private static readonly GLASSES_VOLUME_FLOOR = 9
@@ -189,6 +201,14 @@ class AudioPlaybackService {
    */
   private async prewarmAudioRouteIfCold(): Promise<void> {
     if (Platform.OS !== "android" || this.isAudioRouteWarm()) return
+    // This silent PCM pre-roll is only an anti-clipping optimization. Some
+    // Android devices defer opening its AudioTrack until the host Activity
+    // resumes even though the real URL player supports background playback.
+    // Never let that optional pre-roll block a glasses-initiated prompt.
+    if (AppState.currentState !== "active") {
+      console.log(`AUDIO: Skipping cold-route prewarm while app is ${AppState.currentState}`)
+      return
+    }
     if (this.audioRouteWarmupPromise) return this.audioRouteWarmupPromise
 
     const streamId = `audio-route-prewarm-${Date.now()}-${Math.random().toString(36).slice(2)}`
@@ -321,6 +341,34 @@ class AudioPlaybackService {
     }
   }
 
+  private unloadPlaybackSource(playback: PlaybackState, reason: string): void {
+    if (this.loadedPlayback !== playback) return
+    const player = this.player
+    if (!player) {
+      this.loadedPlayback = null
+      return
+    }
+
+    try {
+      player.pause()
+    } catch (e) {
+      console.warn(`AUDIO: Error pausing ${playback.requestId} during ${reason}:`, e)
+    }
+
+    try {
+      // replace(null) fails native argument casting on iOS, while remove()
+      // destroys the ExoPlayer that Android must reuse to avoid AudioTrack
+      // exhaustion. Replacing with bundled silence detaches the previous media
+      // item on both platforms and leaves the native player alive.
+      player.replace(SILENT_AUDIO_SOURCE)
+      console.log(`AUDIO: Cleared source for ${playback.requestId} during ${reason}`)
+    } catch (e) {
+      console.warn(`AUDIO: Error clearing ${playback.requestId} during ${reason}:`, e)
+    } finally {
+      if (this.loadedPlayback === playback) this.loadedPlayback = null
+    }
+  }
+
   private clearFinishedPlayerAfterTail(playback: PlaybackState): void {
     if (playback.suppressCloudUplink) {
       this.tailUplinkSuppressions.add(playback.uplinkSuppressionId)
@@ -332,18 +380,7 @@ class AudioPlaybackService {
       if (playback.suppressCloudUplink && this.tailUplinkSuppressions.delete(playback.uplinkSuppressionId)) {
         setAudioCloudUplinkSuppressed(playback.uplinkSuppressionId, false)
       }
-      if (!this.player) return
-      if (this.loadedPlayback !== playback) return
-      try {
-        this.player.pause()
-        this.player.replace(null)
-        this.loadedPlayback = null
-        console.log(
-          `AUDIO: Cleared finished player for ${playback.requestId} after ${AudioPlaybackService.A2DP_TAIL_DRAIN_MS}ms tail drain`,
-        )
-      } catch (e) {
-        console.warn("AUDIO: Error clearing player after tail drain:", e)
-      }
+      this.unloadPlaybackSource(playback, `${AudioPlaybackService.A2DP_TAIL_DRAIN_MS}ms A2DP tail drain`)
     }, AudioPlaybackService.A2DP_TAIL_DRAIN_MS)
   }
 
@@ -360,7 +397,27 @@ class AudioPlaybackService {
    */
   public async play(request: AudioPlayRequest, onComplete: AudioPlaybackCompletion): Promise<void> {
     const {requestId, audioUrl, appId, volume = 1.0, stopOtherAudio = true, suppressCloudUplink = false} = request
-    const pending: PendingPlaybackState = {cancelled: false}
+    const now = Date.now()
+    const activeDuplicate =
+      this.currentPlayback &&
+      !this.currentPlayback.completed &&
+      this.currentPlayback.appId === appId &&
+      this.currentPlayback.audioUrl === audioUrl &&
+      now - this.currentPlayback.startTime < AudioPlaybackService.DUPLICATE_PLAY_WINDOW_MS
+    const pendingDuplicate = [...this.pendingPlaybacks.values()].some(
+      (candidate) =>
+        !candidate.cancelled &&
+        candidate.appId === appId &&
+        candidate.audioUrl === audioUrl &&
+        now - candidate.createdAt < AudioPlaybackService.DUPLICATE_PLAY_WINDOW_MS,
+    )
+    if (activeDuplicate || pendingDuplicate) {
+      console.warn(`AUDIO: Suppressed duplicate play request ${requestId}${appId ? ` from ${appId}` : ""}`)
+      onComplete(requestId, false, "Duplicate audio request suppressed", 0, "error")
+      return
+    }
+
+    const pending: PendingPlaybackState = {cancelled: false, audioUrl, appId, createdAt: now}
     this.pendingPlaybacks.set(requestId, pending)
 
     console.log(`AUDIO: Play request ${requestId}${appId ? ` from ${appId}` : ""}: ${audioUrl}`)
@@ -408,6 +465,7 @@ class AudioPlaybackService {
       // Store the new playback state
       const playback: PlaybackState = {
         requestId,
+        audioUrl,
         uplinkSuppressionId: `url:${requestId}`,
         appId,
         startTime: Date.now(),
@@ -450,9 +508,11 @@ class AudioPlaybackService {
       if (suppressCloudUplink) {
         setAudioCloudUplinkSuppressed(`url:${requestId}`, false)
       }
-      if (this.currentPlayback?.requestId === requestId) {
-        this.currentPlayback.completed = true
+      const failedPlayback = this.currentPlayback?.requestId === requestId ? this.currentPlayback : null
+      if (failedPlayback) {
+        failedPlayback.completed = true
         this.currentPlayback = null
+        this.unloadPlaybackSource(failedPlayback, "playback start failure")
       }
       if (pending.cancelled) {
         onComplete(requestId, true, null, 0, "interrupted")
@@ -497,14 +557,9 @@ class AudioPlaybackService {
     }
     this.markAudioRouteWarm()
 
-    // Stop the player
-    if (this.player) {
-      try {
-        this.player.pause()
-      } catch (error) {
-        console.error("AUDIO: Error pausing player:", error)
-      }
-    }
+    // Pausing alone leaves the URI available to OS/Bluetooth media Play.
+    // Unload it unless a newer request has already replaced this source.
+    this.unloadPlaybackSource(playback, "interruption")
 
     // Notify native that our app stopped playing audio (debounced)
     this.notifyAudioStopDebounced()
@@ -563,6 +618,7 @@ class AudioPlaybackService {
         if (playback.suppressCloudUplink) {
           setAudioCloudUplinkSuppressed(playback.uplinkSuppressionId, false)
         }
+        this.unloadPlaybackSource(playback, "playback failure")
         playback.onComplete(playback.requestId, false, "Playback failed (player went idle)", null, "error")
         this.markAudioRouteWarm()
         this.notifyAudioStopDebounced()
@@ -585,6 +641,10 @@ class AudioPlaybackService {
     // Uses BgTimer to work reliably when app is backgrounded on Android
     this.audioStopDebounceTimer = BgTimer.setTimeout(() => {
       this.audioStopDebounceTimer = null
+      // URL playback and live PCM streams may overlap when stopOtherAudio is false.
+      // A URL that ends must not clear the native playback signal while another
+      // source is still active, or the mic watchdog can interrupt that source.
+      if (this.isPlaying()) return
       BluetoothSdk.setOwnAppAudioPlaying(false).catch((e) => {
         console.warn("AUDIO: Failed to notify native of audio stop:", e)
       })