@glassly/engine 0.3.2-beta.572 → 0.3.2-beta.597

package/src/services/LocalMiniappRuntime.ts

@@ -54,6 +54,7 @@ import {
 import {normalizeAiTier, resolveAiTier} from "./AiTierResolution"
 import type {AiTier, AiTierProvider, SavedLlmKeys} from "./AiTierResolution"
 import {HttpError} from "@glassly/cloud-client"
+import type {QuotaStatusPayload} from "@glassly/cloud-protocol"
 import localDisplayManager from "./LocalDisplayManager"
 import sttModelManager from "./STTModelManager"
 import localTranslationService, {type LocalTranslationSubscription} from "./LocalTranslationService"
@@ -108,7 +109,12 @@ import {phonePhotoCoordinator} from "./PhonePhotoCoordinator"
 import {phoneStreamCoordinator} from "./PhoneStreamCoordinator"
 import {phoneVideoCoordinator} from "./PhoneVideoCoordinator"
 import {runSentenceTtsPipeline} from "./SentenceTtsPipeline"
-import {summarizeTranscriptionRoutes, transcriptionDeliveryRoute} from "./TranscriptionRouting"
+import {
+  summarizeTranscriptionRoutes,
+  transcriptionDeliveryRoute,
+  type TranscriptionDeliveryRoute,
+  type TranscriptionSubscriberRoutes,
+} from "./TranscriptionRouting"
 import {prepareTtsSentences} from "./TtsTextSanitizer"
 import {handleWifiAdbRequest} from "./WifiAdbRequest"
 import {cloudClientService, setBlobNamespaceMigrator} from "./CloudClientService"
@@ -171,6 +177,8 @@ interface ConnectedMiniapp {
   forceLocalTranscriptionStreams: Set<string>
   /** Transcription/translation streams with at least one listener using the default/cloud route. */
   cloudTranscriptionStreams: Set<string>
+  /** Transcription streams whose default-route listeners all refuse on-device fallback text. */
+  noFallbackTranscriptionStreams: Set<string>
   sendMessage: (raw: string) => void
   lastPongAt: number
   unansweredPingRounds: number
@@ -213,6 +221,9 @@ interface SpeechRun {
 
 type TranscriptionEventSource = "cloud" | "local"
 
+/** The cloud snapshot miniapps see: the phone's connection state plus plan-quota blocks. */
+type MiniappCloudStatus = CloudClientStatusSnapshot & {quotaBlocked: QuotaStatusPayload["feature"][]}
+
 /** 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:")
@@ -286,7 +297,7 @@ const MINIAPP_AUTH_REFRESH_MIN_DELAY_MS = 5_000
 // (e.g. the cloud client had not finished its first-boot Core token exchange
 // when the miniapp connected). Exponential from base, capped, so a transient
 // not-yet-connected client self-heals within seconds instead of needing a full
-// manual Cloud V2 reconnect.
+// manual Cloud reconnect.
 const MINIAPP_AUTH_RETRY_BASE_MS = 1_000
 const MINIAPP_AUTH_RETRY_MAX_MS = 15_000
 const FOREGROUND_LIVENESS_PROBE_TIMEOUT_MS = 2_500
@@ -1048,6 +1059,7 @@ class LocalMiniappRuntime {
       subscriptions: new Set(),
       forceLocalTranscriptionStreams: new Set(),
       cloudTranscriptionStreams: new Set(),
+      noFallbackTranscriptionStreams: new Set(),
       sendMessage: sendFn,
       lastPongAt: Date.now(),
       unansweredPingRounds: 0,
@@ -1826,7 +1838,7 @@ class LocalMiniappRuntime {
       // right after app start. CONNECT_ACK already went out without auth; keep
       // trying to mint (and re-drive on cloud-connect) so the app authenticates
       // to its backend on its own, instead of staying dead until a full manual
-      // Cloud V2 reconnect re-runs the whole handshake.
+      // Cloud reconnect re-runs the whole handshake.
       this.deliverInitialMiniappAuth(packageName, authPromise, 0)
     }
     this.sendCloudStatusToMiniapp(packageName)
@@ -1988,7 +2000,7 @@ class LocalMiniappRuntime {
    * When the cloud client (re)connects, immediately re-attempt the initial mint
    * for any handshook app still missing its token, instead of waiting out the
    * backoff. This is what turns "scan a dev app before the cloud is ready" from
-   * "dead until you manually reconnect Cloud V2" into "authenticates on its own
+   * "dead until you manually reconnect Cloud" into "authenticates on its own
    * the instant the connection comes up".
    */
   private redriveMiniappAuthDelivery(): void {
@@ -2101,7 +2113,10 @@ class LocalMiniappRuntime {
     if (!app) return
 
     const rawStreams = (payload.subscriptions ?? payload.streams) as
-      | (string | {stream: string; rate?: string; forceLocal?: boolean; includeCloud?: boolean})[]
+      | (
+          | string
+          | {stream: string; rate?: string; forceLocal?: boolean; includeCloud?: boolean; localFallback?: boolean}
+        )[]
       | undefined
     // Normalize: objects like {stream: "location_stream", rate: "realtime"} → extract stream name
     // "location_stream" is the rate-bearing alias for "location_update".
@@ -2110,6 +2125,7 @@ class LocalMiniappRuntime {
     let requestedLocationRate: string | null = null
     const forceLocalTranscriptionStreams = new Set<string>()
     const cloudTranscriptionStreams = new Set<string>()
+    const noFallbackTranscriptionStreams = new Set<string>()
     const streams = rawStreams?.map((s) => {
       if (typeof s === "object" && s !== null) {
         if (s.stream === "location_stream") {
@@ -2123,6 +2139,7 @@ class LocalMiniappRuntime {
         }
         if (isSpeechTextStream(s.stream) && (s.forceLocal !== true || s.includeCloud === true)) {
           cloudTranscriptionStreams.add(s.stream)
+          if (s.localFallback === false) noFallbackTranscriptionStreams.add(s.stream)
         }
         return s.stream
       }
@@ -2190,6 +2207,9 @@ class LocalMiniappRuntime {
     app.cloudTranscriptionStreams = new Set(
       [...cloudTranscriptionStreams].filter((stream) => app.subscriptions.has(stream)),
     )
+    app.noFallbackTranscriptionStreams = new Set(
+      [...noFallbackTranscriptionStreams].filter((stream) => app.subscriptions.has(stream)),
+    )
     this.replaceStreamSubscribers(packageName, previousSubscriptions, app.subscriptions)
     // The overlay app presents phone notifications on the glasses while it
     // listens to them; recorded for every dashboard so the role can move.
@@ -4863,6 +4883,7 @@ class LocalMiniappRuntime {
     const previousSubscriptions = app.subscriptions
     app.subscriptions = new Set(streams)
     app.forceLocalTranscriptionStreams.clear()
+    app.noFallbackTranscriptionStreams.clear()
     app.cloudTranscriptionStreams = new Set(streams.filter(isSpeechTextStream))
     this.replaceStreamSubscribers(packageName, previousSubscriptions, app.subscriptions)
 
@@ -4929,6 +4950,7 @@ class LocalMiniappRuntime {
     let transcriptionLang: string | null = null
     let forceLocalTranscriptionLang: string | null = null
     let hasForceLocalTranscription = false
+    let hasFallbackTranscription = false
     const localTranslations: LocalTranslationSubscription[] = []
     for (const [stream, subscribers] of this.activeStreamSubscribers()) {
       if (subscribers.size === 0) continue
@@ -4960,6 +4982,7 @@ class LocalMiniappRuntime {
           hasForceLocalTranscription = true
           if (forceLocalTranscriptionLang === null) forceLocalTranscriptionLang = language
         }
+        if (routes.hasFallbackSubscriber) hasFallbackTranscription = true
         if (routes.hasCloudSubscriber) cloudStreams.add(stream)
       }
     }
@@ -4974,6 +4997,7 @@ class LocalMiniappRuntime {
       transcriptionLang !== null || localSourceLang !== null,
       forceLocalTranscriptionLang ?? transcriptionLang ?? localSourceLang,
       hasForceLocalTranscription || hasForceLocalTranslation,
+      hasFallbackTranscription || localSourceLang !== null,
     )
 
     // Mirror the same set as typed AudioSubscription[]. When Soniox-direct is
@@ -5134,12 +5158,15 @@ class LocalMiniappRuntime {
       if (q.feature !== "transcription") return
       if (!q.blocked) {
         this.lastSttQuotaNoticeAt = 0
-        void localSttFallbackCoordinator.onSttQuotaBlockedChange(false)
+        void localSttFallbackCoordinator.onSttQuotaBlockedChange(false).then(() => this.broadcastCloudStatus())
         this.onQuotaRestored?.("transcription")
         return
       }
       console.warn(`${LOG_TAG}: cloud transcription blocked by plan quota`)
       void localSttFallbackCoordinator.onSttQuotaBlockedChange(true).then(() => {
+        // Miniapps learn of the block through the status snapshot; the lens
+        // notice below is for the wearer.
+        this.broadcastCloudStatus()
         const localSttActive = localSttFallbackCoordinator.isActive()
         const now = Date.now()
         if (now - this.lastSttQuotaNoticeAt >= STT_QUOTA_NOTICE_DEBOUNCE_MS) {
@@ -5383,7 +5410,7 @@ class LocalMiniappRuntime {
     )
   }
 
-  private currentCloudStatus(): CloudClientStatusSnapshot {
+  private currentCloudStatus(): MiniappCloudStatus {
     const base = cloudClientService.getStatus()
     const fallbackActive =
       (useSettingsStore.getState().getSetting(ISLAND_SETTINGS_KEYS.localSttFallbackActive) as boolean | undefined) ===
@@ -5394,6 +5421,7 @@ class LocalMiniappRuntime {
     return {
       status: base.status,
       audioTransport: fallbackActive || sonioxDegraded ? "offline" : base.audioTransport,
+      quotaBlocked: localSttFallbackCoordinator.isSttQuotaBlocked() ? ["transcription"] : [],
     }
   }
 
@@ -5543,7 +5571,7 @@ class LocalMiniappRuntime {
 
     for (const packageName of matchedSubs) {
       if (only !== undefined && packageName !== only) continue
-      let transcriptionRoute: "default" | "forceLocal" | "all" | undefined
+      let transcriptionRoute: TranscriptionDeliveryRoute | undefined
       if (normalizedStream.startsWith("transcription:") && transcriptionSource) {
         const routes = this.appTranscriptionRoutesForEvent(packageName, normalizedStream)
         transcriptionRoute =
@@ -5638,17 +5666,12 @@ class LocalMiniappRuntime {
       })
   }
 
-  private appTranscriptionRoutesForSubscription(
-    packageName: string,
-    stream: string,
-  ): {
-    cloud: boolean
-    forceLocal: boolean
-  } {
+  private appTranscriptionRoutesForSubscription(packageName: string, stream: string): TranscriptionSubscriberRoutes {
     const app = this.connectedApps.get(packageName)
     return {
       cloud: app?.cloudTranscriptionStreams.has(stream) === true,
       forceLocal: app?.forceLocalTranscriptionStreams.has(stream) === true,
+      localFallback: app?.noFallbackTranscriptionStreams.has(stream) !== true,
     }
   }
 
@@ -5666,21 +5689,20 @@ class LocalMiniappRuntime {
     }
   }
 
-  private appTranscriptionRoutesForEvent(
-    packageName: string,
-    stream: string,
-  ): {
-    cloud: boolean
-    forceLocal: boolean
-  } {
+  private appTranscriptionRoutesForEvent(packageName: string, stream: string): TranscriptionSubscriberRoutes {
     const app = this.connectedApps.get(packageName)
     const autoStream = `${MiniappStreamType.TRANSCRIPTION}:auto`
+    const cloudExact = app?.cloudTranscriptionStreams.has(stream) === true
+    const cloudAuto = app?.cloudTranscriptionStreams.has(autoStream) === true
     return {
-      cloud:
-        app?.cloudTranscriptionStreams.has(stream) === true || app?.cloudTranscriptionStreams.has(autoStream) === true,
+      cloud: cloudExact || cloudAuto,
       forceLocal:
         app?.forceLocalTranscriptionStreams.has(stream) === true ||
         app?.forceLocalTranscriptionStreams.has(autoStream) === true,
+      // Fallback stays accepted while any matching default subscription takes it.
+      localFallback:
+        (cloudExact && app?.noFallbackTranscriptionStreams.has(stream) !== true) ||
+        (cloudAuto && app?.noFallbackTranscriptionStreams.has(autoStream) !== true),
     }
   }
 

package/src/services/LocalSttFallbackCoordinator.ts

@@ -8,7 +8,8 @@ import sttModelManager from "./STTModelManager"
  * Decides whether on-device Sherpa STT should produce transcripts for local
  * miniapps, instead of (or in addition to) cloud transcription. Local STT is
  * active when the cloud is unavailable (disconnected or refusing STT for plan
- * quota) or any subscription requires `forceLocal`.
+ * quota) and some subscriber accepts fallback text, or any subscription
+ * requires `forceLocal`.
  *
  * Activation flips `localSttFallbackActive` in the settings store, which
  * the bluetooth-sdk native side reads to decide whether to feed PCM into
@@ -37,6 +38,8 @@ class LocalSttFallbackCoordinator {
 
   private hasTranscriptionSubscription = false
   private hasForceLocalSubscription = false
+  /** Some default-route subscriber takes on-device text while the primary is down. */
+  private hasFallbackSubscription = false
   private activeLanguage: string | null = null
   /**
    * Default to "cloud is up" so we never accidentally activate local STT before
@@ -123,10 +126,18 @@ class LocalSttFallbackCoordinator {
     return this.localActive ? this.currentReason() : null
   }
 
-  onSubscriptionChange(hasTranscription: boolean, language: string | null, hasForceLocal = false): void {
-    this.log(`onSubscriptionChange(hasTx=${hasTranscription}, lang=${language}, forceLocal=${hasForceLocal})`)
+  onSubscriptionChange(
+    hasTranscription: boolean,
+    language: string | null,
+    hasForceLocal = false,
+    acceptsFallback = true,
+  ): void {
+    this.log(
+      `onSubscriptionChange(hasTx=${hasTranscription}, lang=${language}, forceLocal=${hasForceLocal}, fallback=${acceptsFallback})`,
+    )
     this.hasTranscriptionSubscription = hasTranscription
     this.hasForceLocalSubscription = hasTranscription && hasForceLocal
+    this.hasFallbackSubscription = hasTranscription && acceptsFallback
     this.activeLanguage = hasTranscription ? language : null
     void this.reconcile()
   }
@@ -256,7 +267,10 @@ class LocalSttFallbackCoordinator {
   }
 
   private shouldUseLocalStt(): boolean {
-    return this.hasTranscriptionSubscription && (this.hasForceLocalSubscription || !this.primaryUp())
+    return (
+      this.hasTranscriptionSubscription &&
+      (this.hasForceLocalSubscription || (this.hasFallbackSubscription && !this.primaryUp()))
+    )
   }
 
   private log(msg: string): void {

package/src/services/PhonePhotoCoordinator.ts

@@ -5,7 +5,7 @@
  *   miniapp → SDK → LocalMiniappRuntime → photo runtime hook
  *          → coordinator.takePhoto(packageName, opts)
  *            ├── (precheck) glasses connected + hasCamera
- *            ├── cloudClientService.startManagedPhoto → {requestId, uploadUrl, readUrl}  (cloud-v2 runtime presign)
+ *            ├── cloudClientService.startManagedPhoto → {requestId, uploadUrl, readUrl}  (cloud runtime presign)
  *            ├── BluetoothSdk.requestPhoto(requestId, size, uploadUrl, compress, sound)
  *            └── race:
  *                  - cloudClientService.awaitManagedPhotoReady(requestId) resolves on photo.ready push
@@ -179,8 +179,8 @@ export class PhonePhotoCoordinator {
     // high-capacity tier and let the glasses ignore the public size when mode=text.
     const captureSize = opts.size ?? "medium"
 
-    // 1) Presign via the cloud-v2 managed-photo service. Local miniapps use
-    //    ONLY the cloud-v2 path: the runtime presigns upload+read URLs and the
+    // 1) Presign via the cloud managed-photo service. Local miniapps use
+    //    ONLY the cloud path: the runtime presigns upload+read URLs and the
     //    phone (as the device controller) delivers the bytes; the legacy
     //    backend_url mint is gone from this flow.
     let requestId: string
@@ -419,7 +419,7 @@ export class PhonePhotoCoordinator {
     // Abort the in-flight long-poll first so we don't double-resolve.
     entry.abort.abort()
     entry.reject(new PhotoError(errorCode || "GLASSES_ERROR", errorMessage || "Glasses error", "capture", "ble"))
-    // cloud-v2 pending photo requests TTL out on their own; nothing to free.
+    // cloud pending photo requests TTL out on their own; nothing to free.
   }
 
   private toPhotoError(err: unknown, fallbackCode: string, stage?: PhotoStage, transport?: PhotoTransport): PhotoError {

package/src/services/PhoneStreamCoordinator.ts

@@ -4,7 +4,7 @@
  * Architecture:
  *   miniapp → SDK → LocalMiniappRuntime → coordinator
  *           coordinator → BluetoothSdk (BLE → glasses publisher)
- *           coordinator ↔ cloudStreamApi (managed only, cloud-v2 runtime provisioning)
+ *           coordinator ↔ cloudStreamApi (managed only, cloud runtime provisioning)
  *           coordinator ↔ StreamLifecycleController (keep-alive heartbeat)
  *           coordinator → status listeners → routed back to miniapp(s)
  *

package/src/services/SupportProfileSync.ts

@@ -26,7 +26,7 @@ let lastFailure: {code: string; stage: string} | null = null
 let lastConnectionState: string | null = null
 
 /**
- * Keep Cloud V2's canonical support snapshot current without creating an event
+ * Keep Cloud's canonical support snapshot current without creating an event
  * stream from noisy store updates. Only the explicitly selected fields below
  * leave the phone; Wi-Fi, Bluetooth addresses, location and diagnostics do not.
  */
@@ -110,7 +110,7 @@ async function sendCurrentSnapshot(force: boolean, generation = syncGeneration):
     consecutiveSendFailures += 1
     retryDelayMs = retryDelayForSendFailure(consecutiveSendFailures)
     console.warn(
-      `supportProfile: Cloud V2 update failed (retry in ${Math.round(retryDelayMs / 1_000)}s):`,
+      `supportProfile: Cloud update failed (retry in ${Math.round(retryDelayMs / 1_000)}s):`,
       error instanceof Error ? error.message : error,
     )
   } finally {

package/src/services/TranscriptionRouting.ts

@@ -1,14 +1,19 @@
 export interface TranscriptionRouteSummary {
   hasCloudSubscriber: boolean
   hasForceLocalSubscriber: boolean
+  /** A default-route subscriber that takes on-device text while the primary is down. */
+  hasFallbackSubscriber: boolean
 }
 
 export interface TranscriptionSubscriberRoutes {
   cloud: boolean
   forceLocal: boolean
+  /** Default-route fallback acceptance; absent means accepted. */
+  localFallback?: boolean
 }
 
-export type TranscriptionDeliveryRoute = "default" | "forceLocal" | "all"
+/** "fallback" is on-device text serving the default route because the primary is down. */
+export type TranscriptionDeliveryRoute = "default" | "forceLocal" | "fallback" | "all"
 
 export function summarizeTranscriptionRoutes<T>(
   subscribers: Iterable<T>,
@@ -16,12 +21,14 @@ export function summarizeTranscriptionRoutes<T>(
 ): TranscriptionRouteSummary {
   let hasCloudSubscriber = false
   let hasForceLocalSubscriber = false
+  let hasFallbackSubscriber = false
   for (const subscriber of subscribers) {
     const routes = routesFor(subscriber)
     if (routes.cloud) hasCloudSubscriber = true
     if (routes.forceLocal) hasForceLocalSubscriber = true
+    if (routes.cloud && routes.localFallback !== false) hasFallbackSubscriber = true
   }
-  return {hasCloudSubscriber, hasForceLocalSubscriber}
+  return {hasCloudSubscriber, hasForceLocalSubscriber, hasFallbackSubscriber}
 }
 
 /**
@@ -41,7 +48,8 @@ export function transcriptionDeliveryRoute(
 ): TranscriptionDeliveryRoute | null {
   if (source === "cloud") return routes.cloud ? "default" : null
   if (primaryUp) return routes.forceLocal ? "forceLocal" : null
-  if (routes.cloud && routes.forceLocal) return "all"
+  const fallback = routes.cloud && routes.localFallback !== false
+  if (fallback && routes.forceLocal) return "all"
   if (routes.forceLocal) return "forceLocal"
-  return routes.cloud ? "default" : null
+  return fallback ? "fallback" : null
 }

package/src/services/cloudStreamApi.ts

@@ -1,5 +1,5 @@
 /**
- * Managed-stream provisioning over the cloud-v2 runtime (cloud-client REST):
+ * Managed-stream provisioning over the cloud runtime (cloud-client REST):
  *
  *   POST   /api/camera/stream      -> provision (Cloudflare live input)
  *   GET    /api/camera/stream/:id  -> provider's ingest status
@@ -61,7 +61,7 @@ export class StreamApiError extends Error {
   }
 }
 
-/** The cloud-v2 runtime's ManagedStream wire shape (open records, see protocol). */
+/** The cloud runtime's ManagedStream wire shape (open records, see protocol). */
 interface ManagedStreamWire {
   streamId: string
   ingest: {
@@ -79,7 +79,7 @@ interface ManagedStreamWire {
 }
 
 /**
- * Provision a managed stream on the cloud-v2 runtime. Returns ready-to-publish
+ * Provision a managed stream on the cloud runtime. Returns ready-to-publish
  * ingest URLs (credentials embedded) plus the playback URLs.
  */
 export async function provisionManagedStream(

package/src/services/gestureDotGlyphs.ts

@@ -4,12 +4,17 @@
  */
 export const GESTURE_DOT_GLYPH_SIZE = 24
 
-export type GestureDotGlyph = "dot" | "up" | "down" | "hold" | "blank"
+export type GestureDotGlyph = "dot" | "double" | "ring" | "doubleRing" | "up" | "down" | "left" | "right" | "hold" | "blank"
 
 export const GESTURE_DOT_GLYPHS: Record<GestureDotGlyph, string> = {
   dot: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAALklEQVR4nM2QsQ0AAAjC/P/pmrhqZ+xIF6DqBQyWbwO3gduAmKjQuj7QL/ETEzQmMptl7Q9NBAAAAABJRU5ErkJggg==",
+  double: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAG0lEQVR4nGNgGD7gPxjgYkN4yOyBlcDp3GEBAB3sd4lPaQxDAAAAAElFTkSuQmCC",
+  ring: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAANElEQVR4nGNgGBTgPxjgEseUgQphyCD4qDL/kSX+Y9WApoWqEjgsx+lc3B7EHSS4A3EgAAC+cEu1JTNREQAAAABJRU5ErkJggg==",
+  doubleRing: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAIklEQVR4nGNgGD7gPxjgYkN4yGwGmBA6SV0JHJbjdO6wAADBMlep8zl7TAAAAABJRU5ErkJggg==",
   up: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAMElEQVR4nGNgoCv4////f1zi2GT+/4ciTHE4RhdHIlDFUUhkcTQKQx9WBw8PCVoBAIcbOcf3xeeBAAAAAElFTkSuQmCC",
   down: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAALUlEQVR4nGNgoC/4/3+4SkBFUCkkNjKJIoMg0GRgGEMGgrC4CQSwuxanR2gEAO1/Ocfgp8uvAAAAAElFTkSuQmCC",
+  left: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAI0lEQVR4nGNgoCv4j0sch8RAiTP8RwPESOAwajDI4JKgGQAAKO05x7DqJxIAAAAASUVORK5CYII=",
+  right: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAIElEQVR4nGNgoDf4j1NiMMn8RwOEJYizZKDEcQc7bQAAS7w5x+ro2lsAAAAASUVORK5CYII=",
   hold: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAR0lEQVR4nGNgIAj+gwF2UUy5//+xyyDzcLGRedjMhTEwXAKl0Z0Lof7DKbgMhBpQCZzOxedBHEGCMxAJBTXhKGRAA9hFMQEANr7jHQU9fO0AAAAASUVORK5CYII=",
   blank: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAD0lEQVR4nGNgGAWjgPoAAAJYAAGgxYwDAAAAAElFTkSuQmCC",
 }

package/src/services/neuralBand/MetaAuth.ts

@@ -0,0 +1,192 @@
+/**
+ * The Meta account sign-in a Neural Band claim needs, ported from callbacked/kinesis
+ * (MIT, Copyright (c) 2026 callbacked): Sources/Kinesis/MetaAuth.swift.
+ *
+ * The chain: an anonymous tokens query, a WebView sign-in on auth.meta.com whose
+ * fb-viewapp://…frl_login redirect carries a token and a blob, a blob decrypt, and
+ * the ar-genai exchange that yields the user session. The session then goes to the
+ * native Bluetooth SDK (keychain / keystore), which runs the ownership exchanges;
+ * nothing here persists it.
+ */
+import {sha256Hex} from "./sha256"
+
+// Meta's own client identifiers, the same in every copy of Meta's apps. They name the
+// app that asks, not a person. They are not secrets, and no account or session is in them.
+const FRL_CLIENT = "FRL|388177446008673|083800dd7efbbd42eab18c9886d79c18"
+const AR_CLIENT = "AR|306760944872162|a919421a55a8ea18080ab2f10f57f1be"
+const TOKENS_QUERY_URL = "https://meta.graph.meta.com/webview_tokens_query"
+const BLOBS_DECRYPT_URL = "https://meta.graph.meta.com/webview_blobs_decrypt"
+const LOGIN_URL = "https://ar-genai.graph.meta.com/login"
+const AUTH_ENTRY_BASE =
+  "https://auth.meta.com/?native_app_id=388177446008673&source_app_id=388177446008673&native_sso_etoken="
+
+export class MetaAuthError extends Error {}
+
+export interface MetaSsoTokens {
+  nativeSsoToken: string
+  etoken: string
+}
+
+export interface MetaSession {
+  accessToken: string
+  userId: string
+}
+
+export function authEntryUrl(tokens: MetaSsoTokens): string {
+  return AUTH_ENTRY_BASE + encodeURIComponent(tokens.etoken)
+}
+
+/** The redirect that ends the sign-in: a custom scheme, or the frl_login marker on https. */
+export function isLoginCallback(url: string): boolean {
+  return url.toLowerCase().startsWith("fb-viewapp:") || url.includes("frl_login")
+}
+
+export function callbackQuery(url: string): {token?: string; blob?: string} {
+  const query = url.includes("?") ? url.slice(url.indexOf("?") + 1) : ""
+  const out: {token?: string; blob?: string} = {}
+  for (const pair of query.split("&")) {
+    const [key, value = ""] = pair.split("=")
+    if (key === "token") out.token = decodeURIComponent(value)
+    if (key === "blob") out.blob = decodeURIComponent(value)
+  }
+  return out
+}
+
+/** The first 16 hex digits of the request token's SHA-256, which the callback must present. */
+export function expectedCallbackToken(nativeSsoToken: string): string {
+  return sha256Hex(nativeSsoToken).slice(0, 16)
+}
+
+export function callbackMatches(token: string | undefined, nativeSsoToken: string): boolean {
+  if (!token || token.length !== 16) return false
+  const expected = expectedCallbackToken(nativeSsoToken)
+  let difference = 0
+  for (let i = 0; i < 16; i++) difference |= token.charCodeAt(i) ^ expected.charCodeAt(i)
+  return difference === 0
+}
+
+export function makeLsd(): string {
+  let digits = ""
+  for (let i = 0; i < 6; i++) digits += Math.floor(Math.random() * 10)
+  return "S0." + digits
+}
+
+export function jazoest(lsd: string): string {
+  let sum = 0
+  for (const char of lsd) sum += char.codePointAt(0) ?? 0
+  return "2" + sum
+}
+
+export function multipartBody(fields: [string, string][], boundary: string): string {
+  let body = ""
+  for (const [name, value] of fields) {
+    body += `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`
+  }
+  return body + `--${boundary}--\r\n`
+}
+
+export function urlForm(fields: [string, string][]): string {
+  return fields.map(([name, value]) => `${name}=${encodeURIComponent(value)}`).join("&")
+}
+
+type Json = Record<string, unknown>
+
+async function post(url: string, headers: Record<string, string>, body: string): Promise<Json> {
+  const response = await fetch(url, {method: "POST", headers, body})
+  let json: Json | null = null
+  try {
+    json = (await response.json()) as Json
+  } catch {
+    json = null
+  }
+  if (response.status !== 200 || json === null) {
+    throw new MetaAuthError(`Meta sign-in failed (HTTP ${response.status}). Try again.`)
+  }
+  if (json.error !== undefined) {
+    const error = json.error as {code?: number; error_subcode?: number} | null
+    throw new MetaAuthError(
+      `Meta sign-in failed (code ${error?.code ?? "-"}, subcode ${error?.error_subcode ?? "-"}). Try again.`,
+    )
+  }
+  return json
+}
+
+async function postMultipart(url: string, fields: [string, string][]): Promise<Json> {
+  const boundary = `glassly.form.${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`
+  return post(
+    url,
+    {
+      "Content-Type": `multipart/form-data; boundary=${boundary}`,
+      "Accept": "application/json",
+      "Origin": "https://auth.meta.com",
+    },
+    multipartBody(fields, boundary),
+  )
+}
+
+/** Step 1: the anonymous WebView tokens query. */
+export async function tokensQuery(): Promise<MetaSsoTokens> {
+  const lsd = makeLsd()
+  const json = await postMultipart(TOKENS_QUERY_URL, [
+    ["access_token", FRL_CLIENT],
+    ["lsd", lsd],
+    ["jazoest", jazoest(lsd)],
+  ])
+  const nativeSsoToken = json.native_sso_token
+  const etoken = json.native_sso_etoken
+  if (typeof nativeSsoToken !== "string" || !nativeSsoToken || typeof etoken !== "string" || !etoken) {
+    throw new MetaAuthError("Meta didn't return sign-in tokens. Try again.")
+  }
+  return {nativeSsoToken, etoken}
+}
+
+/** Step 3: decrypt the login blob into the FRL access token. */
+export async function decryptBlob(blob: string, requestToken: string): Promise<string> {
+  const lsd = makeLsd()
+  const json = await postMultipart(BLOBS_DECRYPT_URL, [
+    ["blob", blob],
+    ["request_token", requestToken],
+    ["access_token", FRL_CLIENT],
+    ["lsd", lsd],
+    ["jazoest", jazoest(lsd)],
+  ])
+  const token = json.access_token
+  if (typeof token !== "string" || !token) throw new MetaAuthError("Meta didn't confirm the sign-in. Try again.")
+  return token
+}
+
+function randomId(): string {
+  const hex = () =>
+    Math.floor(Math.random() * 0x10000)
+      .toString(16)
+      .padStart(4, "0")
+  return `${hex()}${hex()}-${hex()}-${hex()}-${hex()}-${hex()}${hex()}${hex()}`.toUpperCase()
+}
+
+/** Step 4: exchange the FRL token for the ar user session. */
+export async function login(frlAccessToken: string): Promise<MetaSession> {
+  const json = await post(
+    LOGIN_URL,
+    {
+      "Content-Type": "application/x-www-form-urlencoded",
+      "Accept": "application/json",
+      "Authorization": "OAuth " + AR_CLIENT,
+    },
+    urlForm([
+      ["frl_access_token", frlAccessToken],
+      ["logging_session_id", randomId()],
+      ["format", "json"],
+      ["device_id", randomId()],
+      ["generate_session_cookies", "1"],
+      ["generate_analytics_claim", "1"],
+      ["method", "POST"],
+    ]),
+  )
+  const accessToken = json.access_token
+  const rawUserId = json.user_id
+  const userId = typeof rawUserId === "string" ? rawUserId : typeof rawUserId === "number" ? String(rawUserId) : ""
+  if (typeof accessToken !== "string" || !accessToken || !userId) {
+    throw new MetaAuthError("Meta didn't return an account session. Try again.")
+  }
+  return {accessToken, userId}
+}