@mentra/engine 3.4.0-dev.1181 → 3.4.0-dev.1183

package/build/services/TranscriptionRouting.js.map

@@ -1 +1 @@
-{"version":3,"file":"TranscriptionRouting.js","sourceRoot":"","sources":["../../src/services/TranscriptionRouting.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,4BAA4B,CAC1C,WAAwB,EACxB,SAA2D;IAE3D,IAAI,kBAAkB,GAAG,KAAK,CAAA;IAC9B,IAAI,uBAAuB,GAAG,KAAK,CAAA;IACnC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,CAAA;QACpC,IAAI,MAAM,CAAC,KAAK;YAAE,kBAAkB,GAAG,IAAI,CAAA;QAC3C,IAAI,MAAM,CAAC,UAAU;YAAE,uBAAuB,GAAG,IAAI,CAAA;IACvD,CAAC;IACD,OAAO,EAAC,kBAAkB,EAAE,uBAAuB,EAAC,CAAA;AACtD,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,MAAyB,EACzB,MAAqC,EACrC,cAAuB;IAEvB,IAAI,MAAM,KAAK,OAAO;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAA;IAC9D,IAAI,cAAc;QAAE,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAA;IAClE,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,UAAU;QAAE,OAAO,KAAK,CAAA;IACnD,IAAI,MAAM,CAAC,UAAU;QAAE,OAAO,YAAY,CAAA;IAC1C,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAA;AACxC,CAAC","sourcesContent":["export interface TranscriptionRouteSummary {\n  hasCloudSubscriber: boolean\n  hasForceLocalSubscriber: boolean\n}\n\nexport interface TranscriptionSubscriberRoutes {\n  cloud: boolean\n  forceLocal: boolean\n}\n\nexport type TranscriptionDeliveryRoute = \"default\" | \"forceLocal\" | \"all\"\n\nexport function summarizeTranscriptionRoutes<T>(\n  subscribers: Iterable<T>,\n  routesFor: (subscriber: T) => TranscriptionSubscriberRoutes,\n): TranscriptionRouteSummary {\n  let hasCloudSubscriber = false\n  let hasForceLocalSubscriber = false\n  for (const subscriber of subscribers) {\n    const routes = routesFor(subscriber)\n    if (routes.cloud) hasCloudSubscriber = true\n    if (routes.forceLocal) hasForceLocalSubscriber = true\n  }\n  return {hasCloudSubscriber, hasForceLocalSubscriber}\n}\n\nexport function transcriptionDeliveryRoute(\n  source: \"cloud\" | \"local\",\n  routes: TranscriptionSubscriberRoutes,\n  cloudConnected: boolean,\n): TranscriptionDeliveryRoute | null {\n  if (source === \"cloud\") return routes.cloud ? \"default\" : null\n  if (cloudConnected) return routes.forceLocal ? \"forceLocal\" : null\n  if (routes.cloud && routes.forceLocal) return \"all\"\n  if (routes.forceLocal) return \"forceLocal\"\n  return routes.cloud ? \"default\" : null\n}\n"]}
+{"version":3,"file":"TranscriptionRouting.js","sourceRoot":"","sources":["../../src/services/TranscriptionRouting.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Where each miniapp transcription listener gets its text: the cloud or the\n * phone's on-device recognizer.\n *\n * A listener asks for one of three behaviours (the SDK's `processing`):\n *   - preferCloud (default): the cloud; on-device only while the cloud is\n *     unreachable.\n *   - preferLocal: on-device while the running model transcribes the\n *     listener's language, otherwise the cloud.\n *   - localOnly: on-device only; never the cloud.\n *\n * Each listener receives one source at a time (`handoffStep`). A planned\n * switch, while its current source still works, waits for a pause in which\n * both sources have settled (`UtteranceTracker`), then for a drain of the\n * on-device recognizer (it reports everything it heard so far and starts\n * over). The drain is the boundary: on-device text from before it stays with\n * the old side, on-device text after it is new speech, and the listener's\n * cloud text starts at the cloud audio position where the drain began. So a\n * listener never misses or repeats speech. A model that cannot be drained\n * leaves the quiet window as the boundary. A forced switch, when the current\n * source stops, happens at once; a move to the cloud then starts at the\n * cloud audio position of the last on-device final, so an utterance cut short\n * on-device is completed in the cloud and finished ones are not repeated.\n * The listeners' sources and targets decide what runs: a stream is requested\n * from the cloud only while a listener on it needs the cloud, and the\n * on-device recognizer runs only while a listener needs it.\n */\n\nexport type SpeechProcessing = \"preferCloud\" | \"preferLocal\" | \"localOnly\"\nexport type TranscriptionSource = \"cloud\" | \"local\"\n\nconst PROCESSING: ReadonlySet<unknown> = new Set<SpeechProcessing>([\"preferCloud\", \"preferLocal\", \"localOnly\"])\nconst AUTO_STREAM = \"transcription:auto\"\nconst STREAM_PREFIX = \"transcription:\"\n\n/**\n * A source has settled once it has produced nothing for this long since its\n * last final (or since it started): a pause in speech, longer than the\n * recognizers' own end-of-speech delays.\n */\nexport const SOURCE_QUIET_MS = 3000\n/** An utterance whose final never came has ended after this long without transcripts. */\nexport const UTTERANCE_STALE_MS = 6000\n\n/**\n * The processing a listener, subscription or speak request asks for.\n * `processing` wins; without it, the `forceLocal: true` of SDKs before it\n * means localOnly. Anything else is preferCloud.\n */\nexport function readSpeechProcessing(request: {processing?: unknown; forceLocal?: unknown}): SpeechProcessing {\n  if (PROCESSING.has(request.processing)) return request.processing as SpeechProcessing\n  return request.forceLocal === true ? \"localOnly\" : \"preferCloud\"\n}\n\nexport interface RoutedListener {\n  /** `transcription:<language>` or `transcription:auto`. */\n  stream: string\n  processing: SpeechProcessing\n}\n\n/** What the phone can transcribe with right now, as one miniapp sees it. */\nexport interface TranscriptionRoutingState {\n  cloudConnected: boolean\n  /** On-device speech is allowed by this deployment. */\n  onDevice: boolean\n  /** BCP-47 language of the running on-device model, or null while none runs. */\n  localLanguage: string | null\n  /** BCP-47 language of the model picked on the Speech page. */\n  pickedLanguage: string\n  /** The miniapp's language hints (bare codes, from transcription.configure). */\n  hints: readonly string[]\n}\n\n/**\n * Whether an on-device model in `language` transcribes what the listener asks\n * for. A specific language must be the model's. Auto-detect follows the\n * model's language, the one the user picked; but a preferLocal listener whose\n * miniapp hinted at another language keeps the cloud, which tells them apart.\n */\nexport function onDeviceServes(listener: RoutedListener, language: string, hints: readonly string[]): boolean {\n  const requested = listener.stream.slice(STREAM_PREFIX.length).toLowerCase()\n  if (requested === language.toLowerCase()) return true\n  if (listener.stream !== AUTO_STREAM) return false\n  if (listener.processing !== \"preferLocal\") return true\n  const base = language.split(\"-\")[0].toLowerCase()\n  return hints.every((hint) => hint.toLowerCase() === base)\n}\n\n/** The source the listener should receive now. */\nexport function targetSource(listener: RoutedListener, state: TranscriptionRoutingState): TranscriptionSource {\n  if (listener.processing === \"localOnly\" || !state.cloudConnected) return \"local\"\n  if (listener.processing === \"preferCloud\") return \"cloud\"\n  return state.onDevice && state.localLanguage !== null && onDeviceServes(listener, state.localLanguage, state.hints)\n    ? \"local\"\n    : \"cloud\"\n}\n\n/**\n * What a listener on `current` does on its way to `target`:\n * - \"settle\": it has no source yet or is already there; take `target`.\n * - \"forced\": `current` can no longer deliver; move now.\n * - \"wait\": a source is still busy on its streams; stay.\n * - \"drain\": both settled, but the on-device recognizer has spoken since its\n *   last drain; stay until a drain completes.\n * - \"planned\": both settled and drained; move now.\n */\nexport type HandoffStep = \"settle\" | \"forced\" | \"wait\" | \"drain\" | \"planned\"\n\nexport function handoffStep(\n  current: TranscriptionSource | null,\n  target: TranscriptionSource,\n  canDeliver: (source: TranscriptionSource) => boolean,\n  busy: (source: TranscriptionSource) => boolean,\n  drained: boolean,\n): HandoffStep {\n  if (current === null || current === target) return \"settle\"\n  if (!canDeliver(current)) return \"forced\"\n  if (busy(current) || busy(target)) return \"wait\"\n  return drained ? \"planned\" : \"drain\"\n}\n\n/** Whether the listener needs its stream from the cloud. */\nexport function needsCloud(\n  listener: RoutedListener,\n  source: TranscriptionSource | null,\n  target: TranscriptionSource,\n): boolean {\n  if (listener.processing === \"localOnly\") return false\n  return listener.processing === \"preferCloud\" || source === \"cloud\" || target === \"cloud\"\n}\n\n/**\n * Whether the listener needs the on-device recognizer running. preferLocal\n * asks for it whenever the picked model transcribes its language, which is\n * what starts (and, when missing, downloads) that model.\n */\nexport function needsLocal(\n  listener: RoutedListener,\n  source: TranscriptionSource | null,\n  state: TranscriptionRoutingState,\n): boolean {\n  if (source === \"local\" || listener.processing === \"localOnly\" || !state.cloudConnected) return true\n  return (\n    listener.processing === \"preferLocal\" &&\n    state.onDevice &&\n    onDeviceServes(listener, state.pickedLanguage, state.hints)\n  )\n}\n\n/** When each source last produced a transcript on each stream, to tell when it has settled. */\nexport class UtteranceTracker {\n  /** `${source} ${stream}` -> its last transcript; stream \"*\" marks a source start, for every stream. */\n  private readonly last = new Map<string, {at: number; final: boolean}>()\n\n  constructor(\n    private readonly quietMs = SOURCE_QUIET_MS,\n    private readonly staleMs = UTTERANCE_STALE_MS,\n  ) {}\n\n  /** Records a transcript: an interim opens (or continues) an utterance, a final ends it. */\n  note(source: TranscriptionSource, stream: string, isFinal: boolean, now: number): void {\n    this.last.set(`${source} ${stream}`, {at: now, final: isFinal})\n  }\n\n  /**\n   * A source started (the cloud connected, or the on-device model loaded): it\n   * may already be working on speech it has not reported, so it settles only\n   * after a quiet window.\n   */\n  started(source: TranscriptionSource, now: number): void {\n    this.clear(source)\n    this.note(source, \"*\", true, now)\n  }\n\n  /** Forgets a source that stopped: it never reports anything more. */\n  clear(source: TranscriptionSource): void {\n    for (const key of [...this.last.keys()]) {\n      if (key.startsWith(`${source} `)) this.last.delete(key)\n    }\n  }\n\n  /** Whether `source` may still report speech that a listener on `stream` hears. */\n  busy(source: TranscriptionSource, stream: string, now: number): boolean {\n    for (const [key, last] of this.last) {\n      if (now >= this.settlesAt(last)) continue\n      const [keySource, keyStream] = key.split(\" \")\n      if (keySource !== source) continue\n      if (keyStream === \"*\" || stream === AUTO_STREAM || keyStream === stream) return true\n    }\n    return false\n  }\n\n  /** When the next busy stream settles, or null when every one has. */\n  nextSettle(now: number): number | null {\n    let next: number | null = null\n    for (const [key, last] of this.last) {\n      const at = this.settlesAt(last)\n      if (now >= at) this.last.delete(key)\n      else if (next === null || at < next) next = at\n    }\n    return next\n  }\n\n  private settlesAt(last: {at: number; final: boolean}): number {\n    return last.at + (last.final ? this.quietMs : this.staleMs)\n  }\n}\n"]}

package/build/services/TranscriptionSubscriptions.d.ts

@@ -1,18 +1,99 @@
 import type { AudioPosition, TranscriptionToken } from "@mentra/cloud-protocol";
+import { type RoutedListener, type SpeechProcessing, type TranscriptionSource } from "./TranscriptionRouting";
 export interface TranscriptionListenerRegistration {
     id: string;
     stream: string;
-    forceLocal?: boolean;
+    processing: SpeechProcessing;
+    /**
+     * Registered for an SDK that predates listener ids. It gets un-addressed
+     * events, which that SDK fans out to every listener of the same class, so
+     * all of a class's legacy registrations move between sources together.
+     */
     legacy?: boolean;
 }
-/** Runtime-owned text projection. Token detail never crosses the miniapp bridge. */
+/** A transcription stream's entry in SUBSCRIBE `subscriptions`. */
+export interface TranscriptionStreamEntry {
+    stream: string;
+    processing?: unknown;
+    /** SDKs before `processing`: the stream has localOnly listeners. */
+    forceLocal?: unknown;
+    /** SDKs before `processing`, with forceLocal: the stream also has cloud listeners. */
+    includeCloud?: unknown;
+}
+/** Records what one transcription stream entry asks for. */
+export declare function addStreamProcessing(byStream: Map<string, Set<SpeechProcessing>>, entry: TranscriptionStreamEntry): void;
+/**
+ * The transcription listeners of one SUBSCRIBE. SDKs register each listener
+ * (`transcriptionListeners`: `{id, stream, processing}`, or `forceLocal`
+ * before `processing`). A subscribed stream without registered listeners, as
+ * from SDKs that predate registration, gets one legacy registration per
+ * processing its stream entries ask for.
+ */
+export declare function transcriptionRegistrations(registered: unknown, streams: string[], streamProcessing: Map<string, Set<SpeechProcessing>>): TranscriptionListenerRegistration[];
+/** What `TranscriptionSubscriptions.route` moves listeners by. */
+export interface TranscriptionHandoff {
+    target: (listener: RoutedListener) => TranscriptionSource;
+    canDeliver: (source: TranscriptionSource) => boolean;
+    /** Whether `source` is still busy on `stream` (see UtteranceTracker). */
+    busy: (source: TranscriptionSource, stream: string) => boolean;
+    /** The on-device recognizer has been drained since it last spoke. */
+    drained: boolean;
+    /** Cloud audio position where the last drain began. */
+    plannedWatermark: AudioPosition | null;
+    /** Cloud audio position of the last on-device final. */
+    forcedWatermark: AudioPosition | null;
+}
+/**
+ * Class an SDK from before `processing` filters routed events on: localOnly
+ * listeners take "forceLocal", the others "default".
+ */
+export type TranscriptionDeliveryRoute = "default" | "forceLocal";
+export interface TranscriptionDelivery {
+    /** Absent for a legacy class: the SDK fans the event out by `route`. */
+    listenerId?: string;
+    route: TranscriptionDeliveryRoute;
+    text: string;
+}
+export interface TranscriptionListenerRoute extends RoutedListener {
+    id: string;
+    /** Where the listener gets its text now; null before its first routing. */
+    source: TranscriptionSource | null;
+    /** Where it is going (its source, unless a switch waits for a pause). */
+    target: TranscriptionSource;
+}
+/**
+ * One miniapp's transcription listeners: which source each one gets its text
+ * from, and its runtime-owned text projection. Token detail never crosses the
+ * miniapp bridge.
+ */
 export declare class TranscriptionSubscriptions {
     private listeners;
+    /** Routing of each group: a listener, or one legacy class. */
+    private routing;
     observe(current: AudioPosition | null): void;
     replace(registrations: TranscriptionListenerRegistration[], cutoff: AudioPosition | null): void;
-    project(stream: string, tokens: TranscriptionToken[], current: AudioPosition | null, route: "default" | "forceLocal" | "all"): {
-        listenerId?: string;
-        text: string;
-    }[];
+    /**
+     * Moves each group toward its target source (see `handoffStep`). A group
+     * that moves from on-device to the cloud starts its positioned cloud text
+     * at a watermark, so cloud tokens for speech it already got on-device are
+     * never projected to it: where the drain began after a planned move, the
+     * last on-device final after a forced one.
+     */
+    route(handoff: TranscriptionHandoff): {
+        changed: boolean;
+        needsDrain: boolean;
+    };
+    /** Whether a listener is waiting for its sources to settle before it switches. */
+    switching(): boolean;
+    /** Every listener with its current routing. */
+    routes(): TranscriptionListenerRoute[];
+    /**
+     * The events one transcript produces for this miniapp: one per listener
+     * that hears `stream` and currently gets its text from `source`. Cloud
+     * transcripts with token positions are trimmed to what each listener may
+     * hear; without positions (`tokens` undefined) the text goes as is.
+     */
+    deliveries(stream: string, source: TranscriptionSource, text: string, tokens: TranscriptionToken[] | undefined, current: AudioPosition | null): TranscriptionDelivery[];
+    private groups;
 }
 //# sourceMappingURL=TranscriptionSubscriptions.d.ts.map

package/build/services/TranscriptionSubscriptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TranscriptionSubscriptions.d.ts","sourceRoot":"","sources":["../../src/services/TranscriptionSubscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAE,kBAAkB,EAAC,MAAM,wBAAwB,CAAA;AAE7E,MAAM,WAAW,iCAAiC;IAChD,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAOD,oFAAoF;AACpF,qBAAa,0BAA0B;IACrC,OAAO,CAAC,SAAS,CAA8B;IAE/C,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI;IAK5C,OAAO,CAAC,aAAa,EAAE,iCAAiC,EAAE,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI;IAe/F,OAAO,CACL,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,kBAAkB,EAAE,EAC5B,OAAO,EAAE,aAAa,GAAG,IAAI,EAC7B,KAAK,EAAE,SAAS,GAAG,YAAY,GAAG,KAAK;qBAGL,MAAM;cAAQ,MAAM;;CAsBzD"}
+{"version":3,"file":"TranscriptionSubscriptions.d.ts","sourceRoot":"","sources":["../../src/services/TranscriptionSubscriptions.ts"],"names":[],"mappings":"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"}

package/build/services/TranscriptionSubscriptions.js

@@ -1,6 +1,52 @@
-/** Runtime-owned text projection. Token detail never crosses the miniapp bridge. */
+import { handoffStep, readSpeechProcessing, } from "./TranscriptionRouting";
+/** Records what one transcription stream entry asks for. */
+export function addStreamProcessing(byStream, entry) {
+    const processing = byStream.get(entry.stream) ?? new Set();
+    byStream.set(entry.stream, processing);
+    processing.add(readSpeechProcessing(entry));
+    if (entry.processing === undefined && entry.forceLocal === true && entry.includeCloud === true) {
+        processing.add("preferCloud");
+    }
+}
+/**
+ * The transcription listeners of one SUBSCRIBE. SDKs register each listener
+ * (`transcriptionListeners`: `{id, stream, processing}`, or `forceLocal`
+ * before `processing`). A subscribed stream without registered listeners, as
+ * from SDKs that predate registration, gets one legacy registration per
+ * processing its stream entries ask for.
+ */
+export function transcriptionRegistrations(registered, streams, streamProcessing) {
+    const subscribed = new Set(streams.filter((stream) => stream.startsWith("transcription:")));
+    const registrations = [];
+    for (const value of Array.isArray(registered) ? registered : []) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const listener = value;
+        if (typeof listener.id !== "string" || typeof listener.stream !== "string")
+            continue;
+        if (!subscribed.has(listener.stream))
+            continue;
+        registrations.push({ id: listener.id, stream: listener.stream, processing: readSpeechProcessing(listener) });
+    }
+    const registeredStreams = new Set(registrations.map((registration) => registration.stream));
+    for (const stream of subscribed) {
+        if (registeredStreams.has(stream))
+            continue;
+        for (const processing of streamProcessing.get(stream) ?? ["preferCloud"]) {
+            registrations.push({ id: `legacy:${processing}:${stream}`, stream, processing, legacy: true });
+        }
+    }
+    return registrations;
+}
+/**
+ * One miniapp's transcription listeners: which source each one gets its text
+ * from, and its runtime-owned text projection. Token detail never crosses the
+ * miniapp bridge.
+ */
 export class TranscriptionSubscriptions {
     listeners = new Map();
+    /** Routing of each group: a listener, or one legacy class. */
+    routing = new Map();
     observe(current) {
         if (!current)
             return;
@@ -12,43 +58,145 @@ export class TranscriptionSubscriptions {
         const next = new Map();
         for (const registration of registrations) {
             const existing = this.listeners.get(registration.id);
-            next.set(registration.id, existing?.stream === registration.stream && !!existing.forceLocal === !!registration.forceLocal
+            next.set(registration.id, existing?.stream === registration.stream &&
+                existing.processing === registration.processing &&
+                !!existing.legacy === !!registration.legacy
                 ? existing
                 : { ...registration, cutoff, sessions: new Set(cutoff ? [cutoff.sessionTag] : []) });
         }
         this.listeners = next;
+        const groups = new Set([...next.values()].map(groupOf));
+        for (const group of [...this.routing.keys()]) {
+            if (!groups.has(group))
+                this.routing.delete(group);
+        }
+    }
+    /**
+     * Moves each group toward its target source (see `handoffStep`). A group
+     * that moves from on-device to the cloud starts its positioned cloud text
+     * at a watermark, so cloud tokens for speech it already got on-device are
+     * never projected to it: where the drain began after a planned move, the
+     * last on-device final after a forced one.
+     */
+    route(handoff) {
+        let changed = false;
+        let needsDrain = false;
+        for (const [group, members] of this.groups()) {
+            // A legacy class moves on-device only when that serves all its streams.
+            const target = members.every((member) => handoff.target(member) === "local") ? "local" : "cloud";
+            const previous = this.routing.get(group);
+            const step = handoffStep(previous?.source ?? null, target, handoff.canDeliver, (candidate) => members.some((member) => handoff.busy(candidate, member.stream)), handoff.drained);
+            if (step === "drain")
+                needsDrain = true;
+            const source = step === "wait" || step === "drain" ? previous.source : target;
+            if (previous?.source === source && previous.target === target)
+                continue;
+            changed = true;
+            this.routing.set(group, { source, target });
+            const watermark = step === "planned" ? handoff.plannedWatermark : handoff.forcedWatermark;
+            if (previous?.source === "local" && source === "cloud" && watermark) {
+                for (const member of members)
+                    advanceCutoff(member, watermark);
+            }
+        }
+        return { changed, needsDrain };
     }
-    project(stream, tokens, current, route) {
+    /** Whether a listener is waiting for its sources to settle before it switches. */
+    switching() {
+        for (const routing of this.routing.values()) {
+            if (routing.source !== routing.target)
+                return true;
+        }
+        return false;
+    }
+    /** Every listener with its current routing. */
+    routes() {
+        return [...this.listeners.values()].map((listener) => {
+            const routing = this.routing.get(groupOf(listener));
+            return {
+                id: listener.id,
+                stream: listener.stream,
+                processing: listener.processing,
+                source: routing?.source ?? null,
+                target: routing?.target ?? (listener.processing === "localOnly" ? "local" : "cloud"),
+            };
+        });
+    }
+    /**
+     * The events one transcript produces for this miniapp: one per listener
+     * that hears `stream` and currently gets its text from `source`. Cloud
+     * transcripts with token positions are trimmed to what each listener may
+     * hear; without positions (`tokens` undefined) the text goes as is.
+     */
+    deliveries(stream, source, text, tokens, current) {
         this.observe(current);
-        const events = [];
+        const deliveries = [];
         for (const listener of this.listeners.values()) {
             if (listener.stream !== stream && listener.stream !== "transcription:auto")
                 continue;
-            if (listener.forceLocal ? route !== "forceLocal" && route !== "all" : route === "forceLocal")
+            if (this.routing.get(groupOf(listener))?.source !== source)
+                continue;
+            const listenerText = tokens ? projectTokens(listener, tokens) : text;
+            if (tokens && !listenerText)
+                continue;
+            const route = listener.processing === "localOnly" ? "forceLocal" : "default";
+            if (!listener.legacy) {
+                deliveries.push({ listenerId: listener.id, route, text: listenerText });
                 continue;
-            const eligible = tokens.filter((token) => {
-                const position = token.audioPosition;
-                if (!position)
-                    return false;
-                if (position.sessionTag === listener.cutoff?.sessionTag)
-                    return position.offsetMs >= listener.cutoff.offsetMs;
-                return listener.sessions.has(position.sessionTag);
-            });
-            const text = eligible
-                .map((token) => token.text)
-                .join("")
-                .trim();
-            if (text && listener.legacy) {
-                const existing = events.find((event) => event.listenerId === undefined);
-                if (!existing)
-                    events.push({ text });
-                else if (text.length > existing.text.length)
-                    existing.text = text;
             }
-            else if (text)
-                events.push({ listenerId: listener.id, text });
+            const existing = deliveries.find((delivery) => delivery.listenerId === undefined && delivery.route === route);
+            if (!existing)
+                deliveries.push({ route, text: listenerText });
+            else if (listenerText.length > existing.text.length)
+                existing.text = listenerText;
         }
-        return events;
+        return deliveries;
     }
+    groups() {
+        const groups = new Map();
+        for (const listener of this.listeners.values()) {
+            const group = groupOf(listener);
+            const members = groups.get(group);
+            if (members)
+                members.push(listener);
+            else
+                groups.set(group, [listener]);
+        }
+        return groups;
+    }
+}
+function groupOf(listener) {
+    return listener.legacy ? `legacy ${listener.processing}` : `listener ${listener.id}`;
+}
+/**
+ * Moves a listener's cloud text start up to `watermark`, never back before
+ * where it already starts (its registration, or an earlier handoff). A
+ * watermark in a session the listener never saw predates it.
+ */
+function advanceCutoff(listener, watermark) {
+    const cutoff = listener.cutoff;
+    if (cutoff?.sessionTag === watermark.sessionTag) {
+        if (watermark.offsetMs > cutoff.offsetMs)
+            listener.cutoff = watermark;
+        return;
+    }
+    if (!listener.sessions.has(watermark.sessionTag))
+        return;
+    listener.cutoff = watermark;
+    listener.sessions = new Set([watermark.sessionTag]);
+}
+function projectTokens(listener, tokens) {
+    return tokens
+        .filter((token) => {
+        const position = token.audioPosition;
+        if (!position)
+            return false;
+        if (position.sessionTag === listener.cutoff?.sessionTag)
+            return position.offsetMs >= listener.cutoff.offsetMs;
+        return listener.sessions.has(position.sessionTag);
+    })
+        .map((token) => token.text)
+        .join("")
+        .trim();
 }
 //# sourceMappingURL=TranscriptionSubscriptions.js.map

package/build/services/TranscriptionSubscriptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"TranscriptionSubscriptions.js","sourceRoot":"","sources":["../../src/services/TranscriptionSubscriptions.ts"],"names":[],"mappings":"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","sourcesContent":["import type {AudioPosition, TranscriptionToken} from \"@mentra/cloud-protocol\"\n\nexport interface TranscriptionListenerRegistration {\n  id: string\n  stream: string\n  forceLocal?: boolean\n  legacy?: boolean\n}\n\ninterface Listener extends TranscriptionListenerRegistration {\n  cutoff: AudioPosition | null\n  sessions: Set<number>\n}\n\n/** Runtime-owned text projection. Token detail never crosses the miniapp bridge. */\nexport class TranscriptionSubscriptions {\n  private listeners = new Map<string, Listener>()\n\n  observe(current: AudioPosition | null): void {\n    if (!current) return\n    for (const listener of this.listeners.values()) listener.sessions.add(current.sessionTag)\n  }\n\n  replace(registrations: TranscriptionListenerRegistration[], cutoff: AudioPosition | null): void {\n    this.observe(cutoff)\n    const next = new Map<string, Listener>()\n    for (const registration of registrations) {\n      const existing = this.listeners.get(registration.id)\n      next.set(\n        registration.id,\n        existing?.stream === registration.stream && !!existing.forceLocal === !!registration.forceLocal\n          ? existing\n          : {...registration, cutoff, sessions: new Set(cutoff ? [cutoff.sessionTag] : [])},\n      )\n    }\n    this.listeners = next\n  }\n\n  project(\n    stream: string,\n    tokens: TranscriptionToken[],\n    current: AudioPosition | null,\n    route: \"default\" | \"forceLocal\" | \"all\",\n  ) {\n    this.observe(current)\n    const events: Array<{listenerId?: string; text: string}> = []\n    for (const listener of this.listeners.values()) {\n      if (listener.stream !== stream && listener.stream !== \"transcription:auto\") continue\n      if (listener.forceLocal ? route !== \"forceLocal\" && route !== \"all\" : route === \"forceLocal\") continue\n      const eligible = tokens.filter((token) => {\n        const position = token.audioPosition\n        if (!position) return false\n        if (position.sessionTag === listener.cutoff?.sessionTag) return position.offsetMs >= listener.cutoff.offsetMs\n        return listener.sessions.has(position.sessionTag)\n      })\n      const text = eligible\n        .map((token) => token.text)\n        .join(\"\")\n        .trim()\n      if (text && listener.legacy) {\n        const existing = events.find((event) => event.listenerId === undefined)\n        if (!existing) events.push({text})\n        else if (text.length > existing.text.length) existing.text = text\n      } else if (text) events.push({listenerId: listener.id, text})\n    }\n    return events\n  }\n}\n"]}
+{"version":3,"file":"TranscriptionSubscriptions.js","sourceRoot":"","sources":["../../src/services/TranscriptionSubscriptions.ts"],"names":[],"mappings":"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","sourcesContent":["import type {AudioPosition, TranscriptionToken} from \"@mentra/cloud-protocol\"\nimport {\n  handoffStep,\n  readSpeechProcessing,\n  type RoutedListener,\n  type SpeechProcessing,\n  type TranscriptionSource,\n} from \"./TranscriptionRouting\"\n\nexport interface TranscriptionListenerRegistration {\n  id: string\n  stream: string\n  processing: SpeechProcessing\n  /**\n   * Registered for an SDK that predates listener ids. It gets un-addressed\n   * events, which that SDK fans out to every listener of the same class, so\n   * all of a class's legacy registrations move between sources together.\n   */\n  legacy?: boolean\n}\n\n/** A transcription stream's entry in SUBSCRIBE `subscriptions`. */\nexport interface TranscriptionStreamEntry {\n  stream: string\n  processing?: unknown\n  /** SDKs before `processing`: the stream has localOnly listeners. */\n  forceLocal?: unknown\n  /** SDKs before `processing`, with forceLocal: the stream also has cloud listeners. */\n  includeCloud?: unknown\n}\n\n/** Records what one transcription stream entry asks for. */\nexport function addStreamProcessing(\n  byStream: Map<string, Set<SpeechProcessing>>,\n  entry: TranscriptionStreamEntry,\n): void {\n  const processing = byStream.get(entry.stream) ?? new Set<SpeechProcessing>()\n  byStream.set(entry.stream, processing)\n  processing.add(readSpeechProcessing(entry))\n  if (entry.processing === undefined && entry.forceLocal === true && entry.includeCloud === true) {\n    processing.add(\"preferCloud\")\n  }\n}\n\n/**\n * The transcription listeners of one SUBSCRIBE. SDKs register each listener\n * (`transcriptionListeners`: `{id, stream, processing}`, or `forceLocal`\n * before `processing`). A subscribed stream without registered listeners, as\n * from SDKs that predate registration, gets one legacy registration per\n * processing its stream entries ask for.\n */\nexport function transcriptionRegistrations(\n  registered: unknown,\n  streams: string[],\n  streamProcessing: Map<string, Set<SpeechProcessing>>,\n): TranscriptionListenerRegistration[] {\n  const subscribed = new Set(streams.filter((stream) => stream.startsWith(\"transcription:\")))\n  const registrations: TranscriptionListenerRegistration[] = []\n  for (const value of Array.isArray(registered) ? registered : []) {\n    if (typeof value !== \"object\" || value === null) continue\n    const listener = value as {id?: unknown; stream?: unknown; processing?: unknown; forceLocal?: unknown}\n    if (typeof listener.id !== \"string\" || typeof listener.stream !== \"string\") continue\n    if (!subscribed.has(listener.stream)) continue\n    registrations.push({id: listener.id, stream: listener.stream, processing: readSpeechProcessing(listener)})\n  }\n  const registeredStreams = new Set(registrations.map((registration) => registration.stream))\n  for (const stream of subscribed) {\n    if (registeredStreams.has(stream)) continue\n    for (const processing of streamProcessing.get(stream) ?? [\"preferCloud\" as const]) {\n      registrations.push({id: `legacy:${processing}:${stream}`, stream, processing, legacy: true})\n    }\n  }\n  return registrations\n}\n\n/** What `TranscriptionSubscriptions.route` moves listeners by. */\nexport interface TranscriptionHandoff {\n  target: (listener: RoutedListener) => TranscriptionSource\n  canDeliver: (source: TranscriptionSource) => boolean\n  /** Whether `source` is still busy on `stream` (see UtteranceTracker). */\n  busy: (source: TranscriptionSource, stream: string) => boolean\n  /** The on-device recognizer has been drained since it last spoke. */\n  drained: boolean\n  /** Cloud audio position where the last drain began. */\n  plannedWatermark: AudioPosition | null\n  /** Cloud audio position of the last on-device final. */\n  forcedWatermark: AudioPosition | null\n}\n\n/**\n * Class an SDK from before `processing` filters routed events on: localOnly\n * listeners take \"forceLocal\", the others \"default\".\n */\nexport type TranscriptionDeliveryRoute = \"default\" | \"forceLocal\"\n\nexport interface TranscriptionDelivery {\n  /** Absent for a legacy class: the SDK fans the event out by `route`. */\n  listenerId?: string\n  route: TranscriptionDeliveryRoute\n  text: string\n}\n\nexport interface TranscriptionListenerRoute extends RoutedListener {\n  id: string\n  /** Where the listener gets its text now; null before its first routing. */\n  source: TranscriptionSource | null\n  /** Where it is going (its source, unless a switch waits for a pause). */\n  target: TranscriptionSource\n}\n\ninterface Listener extends TranscriptionListenerRegistration {\n  cutoff: AudioPosition | null\n  sessions: Set<number>\n}\n\ninterface GroupRoute {\n  source: TranscriptionSource\n  target: TranscriptionSource\n}\n\n/**\n * One miniapp's transcription listeners: which source each one gets its text\n * from, and its runtime-owned text projection. Token detail never crosses the\n * miniapp bridge.\n */\nexport class TranscriptionSubscriptions {\n  private listeners = new Map<string, Listener>()\n  /** Routing of each group: a listener, or one legacy class. */\n  private routing = new Map<string, GroupRoute>()\n\n  observe(current: AudioPosition | null): void {\n    if (!current) return\n    for (const listener of this.listeners.values()) listener.sessions.add(current.sessionTag)\n  }\n\n  replace(registrations: TranscriptionListenerRegistration[], cutoff: AudioPosition | null): void {\n    this.observe(cutoff)\n    const next = new Map<string, Listener>()\n    for (const registration of registrations) {\n      const existing = this.listeners.get(registration.id)\n      next.set(\n        registration.id,\n        existing?.stream === registration.stream &&\n          existing.processing === registration.processing &&\n          !!existing.legacy === !!registration.legacy\n          ? existing\n          : {...registration, cutoff, sessions: new Set(cutoff ? [cutoff.sessionTag] : [])},\n      )\n    }\n    this.listeners = next\n    const groups = new Set([...next.values()].map(groupOf))\n    for (const group of [...this.routing.keys()]) {\n      if (!groups.has(group)) this.routing.delete(group)\n    }\n  }\n\n  /**\n   * Moves each group toward its target source (see `handoffStep`). A group\n   * that moves from on-device to the cloud starts its positioned cloud text\n   * at a watermark, so cloud tokens for speech it already got on-device are\n   * never projected to it: where the drain began after a planned move, the\n   * last on-device final after a forced one.\n   */\n  route(handoff: TranscriptionHandoff): {changed: boolean; needsDrain: boolean} {\n    let changed = false\n    let needsDrain = false\n    for (const [group, members] of this.groups()) {\n      // A legacy class moves on-device only when that serves all its streams.\n      const target = members.every((member) => handoff.target(member) === \"local\") ? \"local\" : \"cloud\"\n      const previous = this.routing.get(group)\n      const step = handoffStep(\n        previous?.source ?? null,\n        target,\n        handoff.canDeliver,\n        (candidate) => members.some((member) => handoff.busy(candidate, member.stream)),\n        handoff.drained,\n      )\n      if (step === \"drain\") needsDrain = true\n      const source = step === \"wait\" || step === \"drain\" ? previous!.source : target\n      if (previous?.source === source && previous.target === target) continue\n      changed = true\n      this.routing.set(group, {source, target})\n      const watermark = step === \"planned\" ? handoff.plannedWatermark : handoff.forcedWatermark\n      if (previous?.source === \"local\" && source === \"cloud\" && watermark) {\n        for (const member of members) advanceCutoff(member, watermark)\n      }\n    }\n    return {changed, needsDrain}\n  }\n\n  /** Whether a listener is waiting for its sources to settle before it switches. */\n  switching(): boolean {\n    for (const routing of this.routing.values()) {\n      if (routing.source !== routing.target) return true\n    }\n    return false\n  }\n\n  /** Every listener with its current routing. */\n  routes(): TranscriptionListenerRoute[] {\n    return [...this.listeners.values()].map((listener) => {\n      const routing = this.routing.get(groupOf(listener))\n      return {\n        id: listener.id,\n        stream: listener.stream,\n        processing: listener.processing,\n        source: routing?.source ?? null,\n        target: routing?.target ?? (listener.processing === \"localOnly\" ? \"local\" : \"cloud\"),\n      }\n    })\n  }\n\n  /**\n   * The events one transcript produces for this miniapp: one per listener\n   * that hears `stream` and currently gets its text from `source`. Cloud\n   * transcripts with token positions are trimmed to what each listener may\n   * hear; without positions (`tokens` undefined) the text goes as is.\n   */\n  deliveries(\n    stream: string,\n    source: TranscriptionSource,\n    text: string,\n    tokens: TranscriptionToken[] | undefined,\n    current: AudioPosition | null,\n  ): TranscriptionDelivery[] {\n    this.observe(current)\n    const deliveries: TranscriptionDelivery[] = []\n    for (const listener of this.listeners.values()) {\n      if (listener.stream !== stream && listener.stream !== \"transcription:auto\") continue\n      if (this.routing.get(groupOf(listener))?.source !== source) continue\n      const listenerText = tokens ? projectTokens(listener, tokens) : text\n      if (tokens && !listenerText) continue\n      const route: TranscriptionDeliveryRoute = listener.processing === \"localOnly\" ? \"forceLocal\" : \"default\"\n      if (!listener.legacy) {\n        deliveries.push({listenerId: listener.id, route, text: listenerText})\n        continue\n      }\n      const existing = deliveries.find((delivery) => delivery.listenerId === undefined && delivery.route === route)\n      if (!existing) deliveries.push({route, text: listenerText})\n      else if (listenerText.length > existing.text.length) existing.text = listenerText\n    }\n    return deliveries\n  }\n\n  private groups(): Map<string, Listener[]> {\n    const groups = new Map<string, Listener[]>()\n    for (const listener of this.listeners.values()) {\n      const group = groupOf(listener)\n      const members = groups.get(group)\n      if (members) members.push(listener)\n      else groups.set(group, [listener])\n    }\n    return groups\n  }\n}\n\nfunction groupOf(listener: TranscriptionListenerRegistration): string {\n  return listener.legacy ? `legacy ${listener.processing}` : `listener ${listener.id}`\n}\n\n/**\n * Moves a listener's cloud text start up to `watermark`, never back before\n * where it already starts (its registration, or an earlier handoff). A\n * watermark in a session the listener never saw predates it.\n */\nfunction advanceCutoff(listener: Listener, watermark: AudioPosition): void {\n  const cutoff = listener.cutoff\n  if (cutoff?.sessionTag === watermark.sessionTag) {\n    if (watermark.offsetMs > cutoff.offsetMs) listener.cutoff = watermark\n    return\n  }\n  if (!listener.sessions.has(watermark.sessionTag)) return\n  listener.cutoff = watermark\n  listener.sessions = new Set([watermark.sessionTag])\n}\n\nfunction projectTokens(listener: Listener, tokens: TranscriptionToken[]): string {\n  return tokens\n    .filter((token) => {\n      const position = token.audioPosition\n      if (!position) return false\n      if (position.sessionTag === listener.cutoff?.sessionTag) return position.offsetMs >= listener.cutoff.offsetMs\n      return listener.sessions.has(position.sessionTag)\n    })\n    .map((token) => token.text)\n    .join(\"\")\n    .trim()\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/engine",
-  "version": "3.4.0-dev.1181",
+  "version": "3.4.0-dev.1183",
   "description": "Mentra Engine — miniapp registry, WebView bridge, and miniapp store",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -97,13 +97,13 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@mentra/acs-meeting": "3.4.0-dev.1181",
-    "@mentra/glasses-media": "3.4.0-dev.1181",
-    "@mentra/bluetooth-sdk": "3.4.0-dev.1181",
-    "@mentra/cloud-client": "3.4.0-dev.1181",
-    "@mentra/cloud-protocol": "3.4.0-dev.1181",
-    "@mentra/crust": "3.4.0-dev.1181",
-    "@mentra/miniapp": "3.4.0-dev.1181",
+    "@mentra/acs-meeting": "3.4.0-dev.1183",
+    "@mentra/glasses-media": "3.4.0-dev.1183",
+    "@mentra/bluetooth-sdk": "3.4.0-dev.1183",
+    "@mentra/cloud-client": "3.4.0-dev.1183",
+    "@mentra/cloud-protocol": "3.4.0-dev.1183",
+    "@mentra/crust": "3.4.0-dev.1183",
+    "@mentra/miniapp": "3.4.0-dev.1183",
     "buffer": "^6.0.3",
     "events": "^3.3.0",
     "jszip": "^3.10.1",

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface EngineReleaseMetadata {
 export const ENGINE_RELEASE_METADATA: Readonly<EngineReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "3.4.0",
-  "releaseIdentity": "3.4.0-dev.1181",
-  "releaseSetId": "mentra-3.4.0-dev.1181",
-  "sourceCommit": "486022c0a25c1d5b54ecce3725672afaeafae172",
-  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.4.0/mentra-live-ota-3.4.0-dev.1181.json",
-  "otaManifestSha256": "4266ae9fed494ab64870adec6aee8e5348be878ed74c30f4bc98ba48e6e90548"
+  "releaseIdentity": "3.4.0-dev.1183",
+  "releaseSetId": "mentra-3.4.0-dev.1183",
+  "sourceCommit": "3b1ea68f95843885e8b28c924d7245b6be3a3a84",
+  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.4.0/mentra-live-ota-3.4.0-dev.1183.json",
+  "otaManifestSha256": "63989883382aa713297879854ee1a2930cf2c61dc1d0c0e675dda1a8f9b25ff6"
 })

package/src/services/DeviceEventRouter.ts

@@ -250,8 +250,8 @@ export function startDeviceEventRouter(): void {
     }),
   )
   // On-device STT transcripts → local miniapps only while the local engine is
-  // active (cloud fallback or an explicit forceLocal subscription). The runtime
-  // filters mixed local/cloud delivery per miniapp to avoid double-delivery.
+  // active (a localOnly or preferLocal listener, or the cloud fallback). The
+  // runtime routes each listener to one source, so nothing arrives twice.
   // forwardEvent is subscriber-gated — a no-op when no miniapp listens.
   // (Was MantleManager.handle_local_transcription; its offline-captions display branch
   // went away with the pseudo captions renderer.)