@glassly/engine 0.3.1-dev.494 → 0.3.1-dev.523

package/src/services/LocalMiniappRuntime.ts

@@ -55,6 +55,9 @@ import {normalizeAiTier, resolveAiTier} from "./AiTierResolution"
 import type {AiTier, AiTierProvider, SavedLlmKeys} from "./AiTierResolution"
 import {HttpError} from "@glassly/cloud-client"
 import localDisplayManager from "./LocalDisplayManager"
+import sttModelManager from "./STTModelManager"
+import localTranslationService, {type LocalTranslationSubscription} from "./LocalTranslationService"
+import {offlineTranslationSupported} from "./OfflineTranslationManager"
 import {
   dropGestureClaims,
   emptyGestureClaims,
@@ -78,7 +81,6 @@ import {
   type DerivedSettingsKey,
 } from "./settingsBridge"
 import {mayUsePermission} from "./miniappPermissions"
-import {activeDashboardAmong} from "./pages/activeDashboard"
 import {
   activeDashboard,
   addDashboardApp,
@@ -87,7 +89,6 @@ import {
   isOverlayApp,
   onOverlayAppsChange,
   removeDashboardApp,
-  setActiveDashboard,
   setOverlayViewer,
 } from "./pages/overlayApps"
 import {pagesEligible} from "./pages/pageEligibility"
@@ -98,6 +99,7 @@ import glassesSensorService from "./GlassesSensorService"
 import localSttFallbackCoordinator from "./LocalSttFallbackCoordinator"
 import speakerLabelResolver from "./SpeakerLabelResolver"
 import micStateCoordinator from "./MicStateCoordinator"
+import {isMiniappsPaused, onMiniappsPauseChange} from "./MiniappPauseCoordinator"
 import sonioxDirectService from "./soniox/SonioxDirectService"
 import {BlobStore} from "./BlobStore"
 import {CloudAudioSubscriptionSync} from "./CloudAudioSubscriptionSync"
@@ -165,9 +167,9 @@ type SpeakerStateValue = "idle" | "loading" | "playing" | "stopped" | "error"
 
 interface ConnectedMiniapp {
   subscriptions: Set<string>
-  /** Transcription streams this app explicitly requires to stay on-device. */
+  /** Transcription/translation streams this app explicitly requires to stay on-device. */
   forceLocalTranscriptionStreams: Set<string>
-  /** Transcription streams with at least one listener using the default/cloud route. */
+  /** Transcription/translation streams with at least one listener using the default/cloud route. */
   cloudTranscriptionStreams: Set<string>
   sendMessage: (raw: string) => void
   lastPongAt: number
@@ -211,6 +213,10 @@ interface SpeechRun {
 
 type TranscriptionEventSource = "cloud" | "local"
 
+/** Streams that carry speech text and so have a cloud route and an on-device route. */
+const isSpeechTextStream = (stream: string): boolean =>
+  stream.startsWith("transcription:") || stream.startsWith("translation:")
+
 /**
  * Strictness ordering for `location_stream` rate values. Higher index =
  * higher accuracy and higher power cost. The aggregate tier applied to
@@ -598,6 +604,9 @@ class LocalMiniappRuntime {
    */
   private handshookApps: Set<string> = new Set()
 
+  /** Links that arrived before the target finished its handshake; sent right after CONNECT_ACK. */
+  private pendingLinks: Map<string, Record<string, string>> = new Map()
+
   /** Pending {@link waitForConnect} resolvers, keyed by packageName. */
   private connectWaiters: Map<string, Set<(err?: Error) => void>> = new Map()
 
@@ -612,6 +621,7 @@ class LocalMiniappRuntime {
   private cloudStatusWired = false
   private capabilitiesWired = false
   private preferencesWired = false
+  private pauseWired = false
   private settingsBridgeWired = false
   /** Last derived read-only values pushed on the settings stream, for change detection. */
   private derivedSettings = new Map<DerivedSettingsKey, string>()
@@ -1056,6 +1066,7 @@ class LocalMiniappRuntime {
     this.ensureCloudStatusWired()
     this.ensureCapabilitiesWired()
     this.ensurePreferencesWired()
+    this.ensurePauseWired()
     this.ensureSettingsBridgeWired()
     this.ensurePingLoop()
 
@@ -1173,6 +1184,7 @@ class LocalMiniappRuntime {
     // (e.g. a wake that's mid-handshake when the app is torn down). Done before
     // the early-return so it runs even if the connectedApps entry is already gone.
     this.handshookApps.delete(packageName)
+    this.pendingLinks.delete(packageName)
     this.flushConnectWaiters(packageName, new Error(`${packageName} unregistered before connect`))
     // Drop this app's transcription hints; the cloud subscription rebuild
     // below (via replaceStreamSubscribers) re-derives the hint union without it.
@@ -1325,7 +1337,7 @@ class LocalMiniappRuntime {
     // Console-tap forwarding. The miniapp's console.log/warn/etc is wrapped
     // (via injected shim from miniappGlobals.ts) to post a `dev_log`
     // envelope. We fan out to two destinations:
-    //   1. DevServerBridge — forwards to the laptop's `glassly-miniapp dev`
+    //   1. DevServerBridge — forwards to the laptop's `glassly dev`
     //      terminal. No-op when there's no sidecar (installed miniapps).
     //   2. React Native console — surfaces the log in Metro / Xcode console
     //      / adb logcat so installed-miniapp errors are still inspectable
@@ -1766,12 +1778,9 @@ class LocalMiniappRuntime {
     existing.lastPongAt = Date.now()
     existing.unansweredPingRounds = 0
 
-    // The dashboard that holds the role may take the overlay slot: its
-    // capabilities carry the dashboard view from the start.
-    if (existing.installedManifest?.type === "dashboard") {
-      addDashboardApp(packageName)
-      this.syncActiveDashboard()
-    }
+    // The connected dashboard holds the role and may take the overlay slot:
+    // its capabilities carry the dashboard view from the start.
+    if (existing.installedManifest?.type === "dashboard") addDashboardApp(packageName)
     const capabilities = this.capabilitiesFor(packageName)
 
     // Build the declared-permission record for the SDK's session.permissions
@@ -1802,6 +1811,8 @@ class LocalMiniappRuntime {
         capabilities,
         preferences: this.currentPreferences(),
         visibility: this.currentVisibility(),
+        paused: isMiniappsPaused(),
+        ...(isMiniappsPaused() ? {pauseReason: "glasses_disconnected"} : {}),
         permissions: declaredPermissions,
         ...(existing.launchSource ? {launchSource: existing.launchSource} : {}),
         ...(initialAuth ? {auth: initialAuth} : {}),
@@ -1823,6 +1834,11 @@ class LocalMiniappRuntime {
     // Handshake complete — unblock any launcher.waitForConnect() callers.
     this.handshookApps.add(packageName)
     this.flushConnectWaiters(packageName)
+    const pendingLink = this.pendingLinks.get(packageName)
+    if (pendingLink) {
+      this.pendingLinks.delete(packageName)
+      this.sendToMiniapp(packageName, {type: MiniappResponseType.LINK, params: pendingLink})
+    }
   }
 
   private async requestMiniappAuth(packageName: string, opts?: {minTtlMs?: number}): Promise<MiniappAuthToken | null> {
@@ -2102,15 +2118,15 @@ class LocalMiniappRuntime {
           }
           return "location_update"
         }
-        if (s.forceLocal === true && s.stream.startsWith("transcription:")) {
+        if (s.forceLocal === true && isSpeechTextStream(s.stream)) {
           forceLocalTranscriptionStreams.add(s.stream)
         }
-        if (s.stream.startsWith("transcription:") && (s.forceLocal !== true || s.includeCloud === true)) {
+        if (isSpeechTextStream(s.stream) && (s.forceLocal !== true || s.includeCloud === true)) {
           cloudTranscriptionStreams.add(s.stream)
         }
         return s.stream
       }
-      if (s.startsWith("transcription:")) cloudTranscriptionStreams.add(s)
+      if (isSpeechTextStream(s)) cloudTranscriptionStreams.add(s)
       return s
     }) as string[] | undefined
     if (!Array.isArray(streams)) {
@@ -2538,8 +2554,6 @@ class LocalMiniappRuntime {
         return localDisplayManager.foregroundAppOnScreen()
       case "ring_battery":
         return ringBatteryFrom(useGlassesStore.getState())
-      case "active_dashboard":
-        return activeDashboard()
     }
   }
 
@@ -4849,7 +4863,7 @@ class LocalMiniappRuntime {
     const previousSubscriptions = app.subscriptions
     app.subscriptions = new Set(streams)
     app.forceLocalTranscriptionStreams.clear()
-    app.cloudTranscriptionStreams = new Set(streams.filter((stream) => stream.startsWith("transcription:")))
+    app.cloudTranscriptionStreams = new Set(streams.filter(isSpeechTextStream))
     this.replaceStreamSubscribers(packageName, previousSubscriptions, app.subscriptions)
 
     this.recomputeMicRequirements()
@@ -4871,6 +4885,15 @@ class LocalMiniappRuntime {
     }
   }
 
+  /**
+   * Subscriptions that hold mic and transcription demand right now. A paused
+   * app keeps its subscriptions registered (they come back on resume) but
+   * demands nothing while the glasses are away.
+   */
+  private activeStreamSubscribers(): Iterable<[string, Set<string>]> {
+    return isMiniappsPaused() ? [] : this.streamSubscribers
+  }
+
   private recomputeMicRequirements(): void {
     // Soniox-direct (user API key) consumes decoded PCM on the phone, so
     // transcription/translation subscriptions request PCM instead of LC3 —
@@ -4878,7 +4901,7 @@ class LocalMiniappRuntime {
     const sonioxDirect = sonioxDirectService.isEnabled()
     let anyPcm = false
     let anyLc3 = false
-    for (const [stream, subscribers] of this.streamSubscribers) {
+    for (const [stream, subscribers] of this.activeStreamSubscribers()) {
       if (subscribers.size === 0) continue
       if (stream === "audio_chunk") anyPcm = true
       if (stream.startsWith("transcription:") || stream.startsWith("translation:")) {
@@ -4906,12 +4929,25 @@ class LocalMiniappRuntime {
     let transcriptionLang: string | null = null
     let forceLocalTranscriptionLang: string | null = null
     let hasForceLocalTranscription = false
-    for (const [stream, subscribers] of this.streamSubscribers) {
+    const localTranslations: LocalTranslationSubscription[] = []
+    for (const [stream, subscribers] of this.activeStreamSubscribers()) {
       if (subscribers.size === 0) continue
       // Only transcription / translation need cloud delivery. Location and
       // notifications are sourced natively on the phone — no cloud hop.
       if (stream.startsWith("translation:")) {
-        cloudStreams.add(stream)
+        const routes = summarizeTranscriptionRoutes(subscribers, (packageName) =>
+          this.appTranscriptionRoutesForSubscription(packageName, stream),
+        )
+        if (routes.hasCloudSubscriber) cloudStreams.add(stream)
+        const [, source, target, ...rest] = stream.split(":")
+        if (target && target !== "*" && rest.length === 0) {
+          localTranslations.push({
+            source,
+            target,
+            cloud: routes.hasCloudSubscriber,
+            forceLocal: routes.hasForceLocalSubscriber,
+          })
+        }
       }
       if (stream.startsWith("transcription:")) {
         const language = stream.substring("transcription:".length)
@@ -4927,10 +4963,17 @@ class LocalMiniappRuntime {
         if (routes.hasCloudSubscriber) cloudStreams.add(stream)
       }
     }
+    // On-device translation is fed by on-device transcripts, so a translation
+    // subscription it can serve keeps local STT eligible exactly like a
+    // transcription subscription does.
+    const translatesLocally = offlineTranslationSupported() ? localTranslations : []
+    localTranslationService.setSubscriptions(translatesLocally)
+    const hasForceLocalTranslation = translatesLocally.some((sub) => sub.forceLocal)
+    const localSourceLang = translatesLocally.length > 0 ? sttModelManager.getBcp47ForLanguage() : null
     localSttFallbackCoordinator.onSubscriptionChange(
-      transcriptionLang !== null,
-      forceLocalTranscriptionLang ?? transcriptionLang,
-      hasForceLocalTranscription,
+      transcriptionLang !== null || localSourceLang !== null,
+      forceLocalTranscriptionLang ?? transcriptionLang ?? localSourceLang,
+      hasForceLocalTranscription || hasForceLocalTranslation,
     )
 
     // Mirror the same set as typed AudioSubscription[]. When Soniox-direct is
@@ -5065,6 +5108,14 @@ class LocalMiniappRuntime {
       markTranscriptSourceRecent("direct")
       this.handleTranslationData(d)
     })
+    localTranslationService.attach({
+      deliver: (stream, data) => this.forwardEvent(stream, data, "local"),
+      primaryUp: () => this.transcriptionPrimaryUp(),
+      onPairUnavailable: () =>
+        localDisplayManager.showSystemNotice(
+          "Offline translation language not downloaded.\nGet it in Settings > Offline models.",
+        ),
+    })
     // When the user sets/clears their Soniox key mid-session, re-partition
     // subscriptions and mic requirements without waiting for a subscription
     // change.
@@ -5158,22 +5209,26 @@ class LocalMiniappRuntime {
   }
 
   private handleTranslationData(d: TranslationData): void {
-    this.forwardEvent(`translation:${d.source.language}:${d.target.language}`, {
-      type: "translation",
-      text: d.text,
-      originalText: d.originalText,
-      isFinal: d.isFinal,
-      utteranceId: d.utteranceId,
-      startTime: d.startMs,
-      endTime: d.endMs,
-      speakerId: d.speakerId,
-      duration: d.durationMs,
-      transcribeLanguage: d.source.language,
-      translateLanguage: d.target.language,
-      didTranslate: true,
-      provider: d.provider,
-      confidence: d.confidence,
-    })
+    this.forwardEvent(
+      `translation:${d.source.language}:${d.target.language}`,
+      {
+        type: "translation",
+        text: d.text,
+        originalText: d.originalText,
+        isFinal: d.isFinal,
+        utteranceId: d.utteranceId,
+        startTime: d.startMs,
+        endTime: d.endMs,
+        speakerId: d.speakerId,
+        duration: d.durationMs,
+        transcribeLanguage: d.source.language,
+        translateLanguage: d.target.language,
+        didTranslate: true,
+        provider: d.provider,
+        confidence: d.confidence,
+      },
+      "cloud",
+    )
   }
 
   /** Re-partition audio routing after a Soniox-direct enable/disable flip. */
@@ -5252,31 +5307,15 @@ class LocalMiniappRuntime {
     useSettingsStore.subscribe((s) => s.getSetting(SETTINGS.cfw_native_navigation.key), broadcast)
     // The dashboard master switch flips the dashboard view.
     useSettingsStore.subscribe((s) => s.getSetting(SETTINGS.custom_dashboard_enabled.key), broadcast)
-    // The wearer's choice and the installed dashboards decide who holds the role.
-    const syncRole = () => this.syncActiveDashboard()
-    useSettingsStore.subscribe((s) => s.getSetting(SETTINGS.active_dashboard.key), syncRole)
-    useAppStatusStore.subscribe(syncRole)
-    syncRole()
-  }
-
-  /**
-   * Recompute who holds the dashboard role (ADR-0009). The previous holder
-   * gives up the slot first, so it hears the view change while it is still
-   * the overlay app; then every app sees its views again.
-   */
-  private syncActiveDashboard(): void {
-    const candidates: Array<{packageName: string; type?: string}> = [...useAppStatusStore.getState().apps]
-    // A dashboard can connect at launch before the apps store has listed it.
-    for (const [packageName, app] of this.connectedApps) {
-      if (candidates.some((candidate) => candidate.packageName === packageName)) continue
-      candidates.push({packageName, type: app.installedManifest?.type})
-    }
-    const next = activeDashboardAmong(candidates)
-    const previous = activeDashboard()
-    if (next === previous) return
-    if (previous !== null) overlayPages.hide(previous, "replaced")
-    setActiveDashboard(next)
-    this.broadcastCapabilities()
+    // The role follows the connected dashboard: when it passes, every app
+    // sees its views again.
+    let role = activeDashboard()
+    onOverlayAppsChange(() => {
+      const next = activeDashboard()
+      if (next === role) return
+      role = next
+      broadcast()
+    })
   }
 
   /** Capabilities as `packageName` sees them: the model profile plus the views this app may draw. */
@@ -5296,6 +5335,30 @@ class LocalMiniappRuntime {
     }
   }
 
+  /**
+   * Pause/resume (MiniappPauseCoordinator) lands as one push per handshook
+   * app, and the mic and cloud transcription demand follow it.
+   */
+  private ensurePauseWired(): void {
+    if (this.pauseWired) return
+    this.pauseWired = true
+    onMiniappsPauseChange((paused) => {
+      this.broadcastPauseState(paused)
+      this.recomputeMicRequirements()
+      this.updateCloudSubscriptions()
+    })
+  }
+
+  private broadcastPauseState(paused: boolean): void {
+    for (const packageName of this.handshookApps) {
+      this.sendToMiniapp(packageName, {
+        type: MiniappResponseType.PAUSE_CHANGE,
+        paused,
+        ...(paused ? {reason: "glasses_disconnected"} : {}),
+      })
+    }
+  }
+
   /** Host user preferences miniapps follow by default (Settings > Appearance). */
   private currentPreferences(): MiniappPreferences {
     const settings = useSettingsStore.getState()
@@ -5367,6 +5430,10 @@ class LocalMiniappRuntime {
     /** Deliver to this subscriber alone (the designated dashboard app's gestures while it shows). */
     only?: string,
   ): void {
+    // Paused miniapps (glasses disconnected) hear no streams. The resume push
+    // lands before the reconnect's own glasses_connection event, so nothing
+    // a resumed app needs is lost here.
+    if (isMiniappsPaused()) return
     // Local sherpa results enter the runtime only through here (DeviceEventRouter's
     // local_transcription listener); cloud/direct are marked at their onTranscript
     // wiring, which never passes "local".
@@ -5395,6 +5462,7 @@ class LocalMiniappRuntime {
     //   translation:<source>:<target> — exact (TranslationModule.fromTo)
     //   translation:auto            — back-compat alias for *:*
     const matchedSubs = new Set<string>()
+    let translationPatterns: string[] = []
     const exact = this.streamSubscribers.get(normalizedStream)
     if (exact) for (const p of exact) matchedSubs.add(p)
 
@@ -5407,13 +5475,13 @@ class LocalMiniappRuntime {
       // parts[0] = "translation", parts[1] = source, parts[2] = target
       if (parts.length === 3) {
         const [, source, target] = parts
-        const patterns = [
+        translationPatterns = [
           "translation:auto", // legacy alias for *:*
           "translation:*:*", // cloud v3 "all pairs"
           `translation:*:${target}`, // cloud v3 "to <target>"
           `translation:${source}:*`, // cloud v3 "from <source>"
         ]
-        for (const pat of patterns) {
+        for (const pat of translationPatterns) {
           const subs = this.streamSubscribers.get(pat)
           if (subs) for (const p of subs) matchedSubs.add(p)
         }
@@ -5481,6 +5549,11 @@ class LocalMiniappRuntime {
         transcriptionRoute =
           transcriptionDeliveryRoute(transcriptionSource, routes, this.transcriptionPrimaryUp()) ?? undefined
         if (!transcriptionRoute) continue
+      } else if (normalizedStream.startsWith("translation:") && transcriptionSource) {
+        const routes = this.appTranslationRoutesForEvent(packageName, [normalizedStream, ...translationPatterns])
+        transcriptionRoute =
+          transcriptionDeliveryRoute(transcriptionSource, routes, this.transcriptionPrimaryUp()) ?? undefined
+        if (!transcriptionRoute) continue
       }
       if (TRANSCRIPT_TIMING_TELEMETRY && normalizedStream.startsWith("transcription:")) {
         const transcript = data as {text?: string; isFinal?: boolean; __hostReceivedAt?: number} | null
@@ -5579,6 +5652,20 @@ class LocalMiniappRuntime {
     }
   }
 
+  private appTranslationRoutesForEvent(
+    packageName: string,
+    patterns: string[],
+  ): {
+    cloud: boolean
+    forceLocal: boolean
+  } {
+    const app = this.connectedApps.get(packageName)
+    return {
+      cloud: patterns.some((pattern) => app?.cloudTranscriptionStreams.has(pattern) === true),
+      forceLocal: patterns.some((pattern) => app?.forceLocalTranscriptionStreams.has(pattern) === true),
+    }
+  }
+
   private appTranscriptionRoutesForEvent(
     packageName: string,
     stream: string,
@@ -6148,6 +6235,18 @@ class LocalMiniappRuntime {
     )
   }
 
+  /**
+   * Hand an external link's query parameters to a miniapp. A miniapp that is
+   * still spawning gets them once its handshake completes.
+   */
+  public deliverLink(packageName: string, params: Record<string, string>): void {
+    if (!this.handshookApps.has(packageName)) {
+      this.pendingLinks.set(packageName, params)
+      return
+    }
+    this.sendToMiniapp(packageName, {type: MiniappResponseType.LINK, params})
+  }
+
   /**
    * Send a VISIBILITY_CHANGE push to a miniapp.
    */

package/src/services/LocalTranslationService.ts

@@ -0,0 +1,184 @@
+import {offlineTranslationManager} from "./OfflineTranslationManager"
+
+/** One concrete-target `translation:<source>:<target>` stream and who listens to it. */
+export interface LocalTranslationSubscription {
+  /** Subscribed source: a language code, or `*` / `auto` for any. */
+  source: string
+  target: string
+  /** At least one listener on the default (cloud) route. */
+  cloud: boolean
+  /** At least one listener that requires on-device translation. */
+  forceLocal: boolean
+}
+
+export interface LocalTranscript {
+  text: string
+  isFinal?: boolean
+  speakerId?: number | string
+  startTime?: number
+  endTime?: number
+}
+
+interface Host {
+  /** Fan a `translation:<source>:<target>` event out to miniapps. */
+  deliver: (stream: string, data: Record<string, unknown>) => void
+  /** Whether the primary (cloud / Soniox-direct) path is up. */
+  primaryUp: () => boolean
+  /** A wanted pair has no language pack on the device. */
+  onPairUnavailable?: (source: string, target: string) => void
+}
+
+interface Job {
+  text: string
+  isFinal: boolean
+  utteranceId: string
+  transcript: LocalTranscript
+}
+
+interface Lane {
+  busy: boolean
+  finals: Job[]
+  pendingInterim: Job | null
+  lastInterimAt: number
+  retryAt: number
+  reportedUnavailable: boolean
+}
+
+/** Interims are translated at most this often; finals always are. */
+const INTERIM_MIN_INTERVAL_MS = 300
+const FAILURE_BACKOFF_MS = 5000
+
+const baseLanguage = (code: string): string => code.split("-")[0].toLowerCase()
+
+/**
+ * Turns on-device transcripts into on-device translations. Apple's Translation
+ * framework has no streaming API, so each update is a whole `translate` call:
+ * one runs at a time per language pair, a newer interim replaces a waiting
+ * one, and finals are never dropped.
+ *
+ * A pair is translated here when a subscriber forces local, or when the
+ * primary path is down and would otherwise leave default subscribers silent.
+ */
+export class LocalTranslationService {
+  private subscriptions: LocalTranslationSubscription[] = []
+  private lanes = new Map<string, Lane>()
+  private host: Host | null = null
+  private utteranceCounter = 0
+
+  attach(host: Host): void {
+    this.host = host
+  }
+
+  setSubscriptions(subscriptions: LocalTranslationSubscription[]): void {
+    this.subscriptions = subscriptions
+    const live = new Set(subscriptions.map((s) => s.target))
+    for (const key of this.lanes.keys()) {
+      if (!live.has(key.substring(key.indexOf(">") + 1))) this.lanes.delete(key)
+    }
+  }
+
+  onLocalTranscript(transcript: LocalTranscript, sourceLanguage: string): void {
+    const text = transcript.text?.trim()
+    if (!text || !this.host || !offlineTranslationManager.isSupported()) return
+    const isFinal = transcript.isFinal === true
+    const utteranceId = `local-${this.utteranceCounter}`
+    if (isFinal) this.utteranceCounter++
+
+    for (const target of this.wantedTargets(sourceLanguage)) {
+      const job: Job = {text, isFinal, utteranceId, transcript}
+      if (baseLanguage(target) === baseLanguage(sourceLanguage)) {
+        // Same-language passthrough, as the cloud emits it: no originalText.
+        this.emit(sourceLanguage, target, job, text, undefined)
+        continue
+      }
+      this.enqueue(sourceLanguage, target, job)
+    }
+  }
+
+  private wantedTargets(sourceLanguage: string): Set<string> {
+    const targets = new Set<string>()
+    let primaryUp: boolean | null = null
+    for (const sub of this.subscriptions) {
+      const anySource = sub.source === "*" || sub.source === "auto"
+      if (!anySource && baseLanguage(sub.source) !== baseLanguage(sourceLanguage)) continue
+      if (!sub.forceLocal) {
+        primaryUp ??= this.host!.primaryUp()
+        if (primaryUp || !sub.cloud) continue
+      }
+      targets.add(sub.target)
+    }
+    return targets
+  }
+
+  private enqueue(source: string, target: string, job: Job): void {
+    const key = `${source}>${target}`
+    let lane = this.lanes.get(key)
+    if (!lane) {
+      lane = {busy: false, finals: [], pendingInterim: null, lastInterimAt: 0, retryAt: 0, reportedUnavailable: false}
+      this.lanes.set(key, lane)
+    }
+    const now = Date.now()
+    if (now < lane.retryAt) return
+    if (job.isFinal) {
+      lane.pendingInterim = null
+      lane.finals.push(job)
+    } else {
+      if (now - lane.lastInterimAt < INTERIM_MIN_INTERVAL_MS) return
+      lane.lastInterimAt = now
+      lane.pendingInterim = job
+    }
+    if (!lane.busy) void this.drain(source, target, lane)
+  }
+
+  private async drain(source: string, target: string, lane: Lane): Promise<void> {
+    lane.busy = true
+    try {
+      for (;;) {
+        const job = lane.finals.shift() ?? lane.pendingInterim
+        if (!job) break
+        if (!job.isFinal) lane.pendingInterim = null
+        try {
+          const translated = await offlineTranslationManager.translate(job.text, source, target)
+          this.emit(source, target, job, translated, job.text)
+        } catch (err) {
+          this.handleFailure(source, target, lane, err)
+          break
+        }
+      }
+    } finally {
+      lane.busy = false
+    }
+  }
+
+  private handleFailure(source: string, target: string, lane: Lane, err: unknown): void {
+    const message = (err as Error)?.message ?? String(err)
+    console.warn(`[LocalTranslation] ${source}>${target} failed: ${message}`)
+    lane.finals = []
+    lane.pendingInterim = null
+    lane.retryAt = Date.now() + FAILURE_BACKOFF_MS
+    if (message.includes("not_installed") && !lane.reportedUnavailable) {
+      lane.reportedUnavailable = true
+      this.host?.onPairUnavailable?.(source, target)
+    }
+  }
+
+  private emit(source: string, target: string, job: Job, text: string, originalText: string | undefined): void {
+    this.host?.deliver(`translation:${source}:${target}`, {
+      type: "translation",
+      text,
+      originalText,
+      isFinal: job.isFinal,
+      utteranceId: job.utteranceId,
+      startTime: job.transcript.startTime,
+      endTime: job.transcript.endTime,
+      speakerId: job.transcript.speakerId,
+      transcribeLanguage: source,
+      translateLanguage: target,
+      didTranslate: originalText !== undefined,
+      provider: "apple-translation",
+    })
+  }
+}
+
+const localTranslationService = new LocalTranslationService()
+export default localTranslationService