@mentra/miniapp 3.4.0-dev.999 → 3.5.0-dev.1238

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/README.md +7 -7
  2. package/dist/background/index.d.ts +5 -2
  3. package/dist/background/index.d.ts.map +1 -1
  4. package/dist/background/index.js.map +1 -1
  5. package/dist/background/register.d.ts +3 -1
  6. package/dist/background/register.d.ts.map +1 -1
  7. package/dist/background/register.js +19 -2
  8. package/dist/background/register.js.map +1 -1
  9. package/dist/index.d.ts +5 -2
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js.map +1 -1
  12. package/dist/modules/blob.d.ts +2 -1
  13. package/dist/modules/blob.d.ts.map +1 -1
  14. package/dist/modules/blob.js +2 -1
  15. package/dist/modules/blob.js.map +1 -1
  16. package/dist/modules/events.d.ts +16 -6
  17. package/dist/modules/events.d.ts.map +1 -1
  18. package/dist/modules/events.js +53 -47
  19. package/dist/modules/events.js.map +1 -1
  20. package/dist/modules/mic.d.ts +26 -4
  21. package/dist/modules/mic.d.ts.map +1 -1
  22. package/dist/modules/mic.js +13 -4
  23. package/dist/modules/mic.js.map +1 -1
  24. package/dist/modules/miniapps.d.ts +44 -57
  25. package/dist/modules/miniapps.d.ts.map +1 -1
  26. package/dist/modules/miniapps.js +21 -24
  27. package/dist/modules/miniapps.js.map +1 -1
  28. package/dist/modules/speaker.d.ts +41 -10
  29. package/dist/modules/speaker.d.ts.map +1 -1
  30. package/dist/modules/speaker.js +17 -6
  31. package/dist/modules/speaker.js.map +1 -1
  32. package/dist/modules/speechProcessing.d.ts +29 -0
  33. package/dist/modules/speechProcessing.d.ts.map +1 -0
  34. package/dist/modules/speechProcessing.js +22 -0
  35. package/dist/modules/speechProcessing.js.map +1 -0
  36. package/dist/modules/system.d.ts +8 -3
  37. package/dist/modules/system.d.ts.map +1 -1
  38. package/dist/modules/system.js +1 -1
  39. package/dist/modules/system.js.map +1 -1
  40. package/dist/modules/telemetry.d.ts +25 -0
  41. package/dist/modules/telemetry.d.ts.map +1 -0
  42. package/dist/modules/telemetry.js +61 -0
  43. package/dist/modules/telemetry.js.map +1 -0
  44. package/dist/modules/transcription.d.ts +70 -3
  45. package/dist/modules/transcription.d.ts.map +1 -1
  46. package/dist/modules/transcription.js +68 -2
  47. package/dist/modules/transcription.js.map +1 -1
  48. package/dist/protocol.d.ts +29 -15
  49. package/dist/protocol.d.ts.map +1 -1
  50. package/dist/protocol.js +30 -15
  51. package/dist/protocol.js.map +1 -1
  52. package/dist/react/MentraProvider.d.ts +13 -1
  53. package/dist/react/MentraProvider.d.ts.map +1 -1
  54. package/dist/react/MentraProvider.js +31 -1
  55. package/dist/react/MentraProvider.js.map +1 -1
  56. package/dist/session.d.ts +59 -6
  57. package/dist/session.d.ts.map +1 -1
  58. package/dist/session.js +203 -43
  59. package/dist/session.js.map +1 -1
  60. package/dist/transport/auto.js +6 -0
  61. package/dist/transport/auto.js.map +1 -1
  62. package/dist/transport/dispatch.d.ts +2 -0
  63. package/dist/transport/dispatch.d.ts.map +1 -1
  64. package/dist/transport/dispatch.js +7 -2
  65. package/dist/transport/dispatch.js.map +1 -1
  66. package/dist/transport/local-socket.d.ts +6 -0
  67. package/dist/transport/local-socket.d.ts.map +1 -1
  68. package/dist/transport/local-socket.js +34 -2
  69. package/dist/transport/local-socket.js.map +1 -1
  70. package/dist/transport/types.d.ts +4 -1
  71. package/dist/transport/types.d.ts.map +1 -1
  72. package/dist/ui/index.d.ts +7 -4
  73. package/dist/ui/index.d.ts.map +1 -1
  74. package/dist/ui/index.js.map +1 -1
  75. package/package.json +2 -2
  76. package/src/background/index.ts +6 -3
  77. package/src/background/register.ts +24 -2
  78. package/src/index.ts +11 -3
  79. package/src/modules/blob.ts +2 -1
  80. package/src/modules/events.ts +65 -51
  81. package/src/modules/mic.ts +30 -4
  82. package/src/modules/miniapps.ts +59 -71
  83. package/src/modules/speaker.ts +56 -12
  84. package/src/modules/speechProcessing.ts +42 -0
  85. package/src/modules/system.ts +8 -3
  86. package/src/modules/telemetry.ts +62 -0
  87. package/src/modules/transcription.ts +106 -9
  88. package/src/protocol.ts +32 -16
  89. package/src/react/MentraProvider.tsx +23 -2
  90. package/src/session.ts +206 -52
  91. package/src/transport/auto.ts +5 -0
  92. package/src/transport/dispatch.ts +7 -2
  93. package/src/transport/local-socket.ts +30 -1
  94. package/src/transport/types.ts +4 -1
  95. package/src/ui/index.ts +7 -4
package/src/protocol.ts CHANGED
@@ -26,7 +26,16 @@ export enum MiniappRequestType {
26
26
  /** Request a fresh miniapp-scoped backend auth token. */
27
27
  AUTH_REFRESH = "miniapp_auth_refresh",
28
28
 
29
- /** Update the set of streams the miniapp is subscribed to. */
29
+ /**
30
+ * Update the set of streams the miniapp is subscribed to. `subscriptions`
31
+ * lists stream names; a transcription stream is `{stream, processing}`, one
32
+ * entry per processing its listeners ask for, and `transcriptionListeners`
33
+ * lists every transcription listener as `{id, stream, processing}`. Both
34
+ * also carry `forceLocal: true` for `localOnly`, the form hosts before
35
+ * `processing` read. Hosts accept that older form,
36
+ * `{stream, forceLocal?, includeCloud?}`, from SDKs that predate
37
+ * `processing`.
38
+ */
30
39
  SUBSCRIBE = "miniapp_subscribe",
31
40
 
32
41
  /**
@@ -45,7 +54,7 @@ export enum MiniappRequestType {
45
54
  /** Stop any audio playback this miniapp initiated. */
46
55
  STOP_AUDIO = "miniapp_stop_audio",
47
56
 
48
- /** Speak text via cloud TTS — phone constructs the URL. */
57
+ /** Speak text via cloud or on-device TTS, as its `processing` says. */
49
58
  SPEAK = "miniapp_speak",
50
59
 
51
60
  /**
@@ -189,6 +198,17 @@ export enum MiniappRequestType {
189
198
  * so future reconnect logic can re-send.
190
199
  */
191
200
  TRANSCRIPTION_CONFIG = "miniapp_transcription_config",
201
+ /**
202
+ * End the current on-device utterance now (transcription.finishUtterance).
203
+ * Result: the final text, "" when nothing was pending, or null when the
204
+ * model can't finish early.
205
+ */
206
+ TRANSCRIPTION_FINISH = "miniapp_transcription_finish",
207
+
208
+ // ----- Telemetry -----
209
+
210
+ /** A miniapp's own analytics event (`session.telemetry.capture`). One-shot; hosts with `hostFeatures.telemetry`. */
211
+ TELEMETRY_CAPTURE = "miniapp_telemetry_capture",
192
212
 
193
213
  // ----- Deferred in v1 -----
194
214
 
@@ -225,11 +245,11 @@ export enum MiniappRequestType {
225
245
  MINIAPPS_START = "miniapp_apps_start",
226
246
  /** Stop another miniapp. */
227
247
  MINIAPPS_STOP = "miniapp_apps_stop",
228
- /** Install/update an approved bundle. Bundled host-trusted Stores only. */
248
+ /** Install the miniapp at a miniapp URL. System-list miniapps only. */
229
249
  MINIAPPS_INSTALL = "miniapp_apps_install",
230
250
  /** Preflight a release's host/SDK/hardware requirements without downloading it. */
231
251
  MINIAPPS_INSTALL_CHECK = "miniapp_apps_install_check",
232
- /** Uninstall a package owned by the calling Store. Bundled host-trusted Stores only. */
252
+ /** Uninstall a miniapp installed from a miniapp URL. System-list miniapps only. */
233
253
  MINIAPPS_UNINSTALL = "miniapp_apps_uninstall",
234
254
  /** Invoke a declared action on another miniapp; headless-wakes it if stopped. */
235
255
  ACTION_INVOKE = "miniapp_action_invoke",
@@ -294,9 +314,6 @@ export enum MiniappResponseType {
294
314
  /** Push: host color scheme (light/dark) changed. */
295
315
  COLOR_SCHEME_CHANGE = "miniapp_color_scheme_change",
296
316
 
297
- /** Push: a Store installation moved to another host-side phase. */
298
- MINIAPPS_INSTALL_PROGRESS = "miniapp_apps_install_progress",
299
-
300
317
  /**
301
318
  * Push: speaker playback state transitioned. Per-miniapp; the runtime sends
302
319
  * to the owning miniapp only. Carries {state, errorCode?, errorMessage?,
@@ -391,6 +408,10 @@ export enum MiniappStreamType {
391
408
  // Speech / audio (cloud or local)
392
409
  TRANSCRIPTION = "transcription", // language variant: "transcription:en-US"
393
410
  TRANSLATION = "translation", // language variant: "translation:en-US"
411
+ /** State of the on-device speech-to-text model (session.transcription.onModelStatus). */
412
+ TRANSCRIPTION_MODEL_STATUS = "transcription_model_status",
413
+ /** On-device "Hey Mentra" keyword spotter (session.mic.onWakeWord). */
414
+ WAKE_WORD = "wake_word",
394
415
  AUDIO_CHUNK = "audio_chunk",
395
416
  VAD = "vad",
396
417
 
@@ -444,7 +465,7 @@ export enum MiniappErrorCode {
444
465
  TTS_INVALID_VOICE = "TTS_INVALID_VOICE",
445
466
  TTS_UPSTREAM_ERROR = "TTS_UPSTREAM_ERROR",
446
467
 
447
- /** `speak({forceLocal: true})` but the on-device offline TTS model isn't downloaded/ready. */
468
+ /** `speak({processing: "localOnly"})` but the on-device TTS model isn't downloaded/ready. */
448
469
  TTS_LOCAL_UNAVAILABLE = "TTS_LOCAL_UNAVAILABLE",
449
470
 
450
471
  /** Not connected / pre-ACK and transport closed. */
@@ -459,21 +480,16 @@ export enum MiniappErrorCode {
459
480
  // ----- Inter-miniapp interop -----
460
481
  /**
461
482
  * Caller is not a system app — SYSTEM-only APIs (interop list/start/stop/invoke,
462
- * setWifiAdbState) reject with this code.
483
+ * setWifiAdbState) reject with this code, as installs do from any miniapp off
484
+ * the system list. Also: an uninstall of a miniapp that isn't a URL install.
463
485
  */
464
486
  NOT_PERMITTED = "NOT_PERMITTED",
465
487
  /** Target miniapp is not installed. */
466
488
  APP_NOT_FOUND = "APP_NOT_FOUND",
467
489
  /** Target miniapp is incompatible with the connected glasses. */
468
490
  APP_NOT_COMPATIBLE = "APP_NOT_COMPATIBLE",
469
- /** Bundle download, validation, or activation failed. */
491
+ /** The miniapp didn't install; the error's `reason` says why (`InstallMiniappFailureReason`). */
470
492
  INSTALL_FAILED = "INSTALL_FAILED",
471
- /** Another Store installation is already in progress for the same package. */
472
- INSTALL_IN_PROGRESS = "INSTALL_IN_PROGRESS",
473
- /** An automatic update was deferred because the target is running or starting. */
474
- APP_RUNNING = "APP_RUNNING",
475
- /** Another Store owns the installed package's update provenance. */
476
- STORE_OWNERSHIP_CONFLICT = "STORE_OWNERSHIP_CONFLICT",
477
493
  /** Target miniapp does not declare the requested action. */
478
494
  ACTION_NOT_FOUND = "ACTION_NOT_FOUND",
479
495
  /** Target connected but never registered a handler for the action (within the buffer window). */
@@ -5,6 +5,8 @@
5
5
  * miniapp. Currently:
6
6
  * - Keeps `<html class="dark">` in sync with the host's color scheme so the
7
7
  * shared theme CSS switches automatically.
8
+ * - Calls `mentra.ready()` once the app has mounted, which lifts the host's
9
+ * splash and fires the background's `session.ui.onOpen` handlers.
8
10
  *
9
11
  * Usage:
10
12
  * createRoot(root).render(
@@ -17,7 +19,7 @@
17
19
  * things themselves can opt out without forking the provider.
18
20
  */
19
21
 
20
- import {type ReactNode} from "react"
22
+ import {type ReactNode, useEffect} from "react"
21
23
 
22
24
  import {useColorScheme} from "./useColorScheme"
23
25
 
@@ -32,11 +34,30 @@ export interface MentraProviderProps {
32
34
  * (e.g. you integrate a theming library like next-themes).
33
35
  */
34
36
  syncColorScheme?: boolean
37
+ /**
38
+ * Call `mentra.ready()` after the first mount. A parent's effects run after
39
+ * its children's, so every `mentra.on` subscription the app makes on mount
40
+ * is attached before the background is told the UI is open. Without
41
+ * `ready()` the host keeps its splash up and reports the miniapp as failed.
42
+ *
43
+ * Default: true. Set to false to call `mentra.ready()` yourself, e.g. to keep
44
+ * the splash up until the first screen has its data.
45
+ */
46
+ autoReady?: boolean
35
47
  }
36
48
 
37
- export function MentraProvider({children, syncColorScheme = true}: MentraProviderProps) {
49
+ function getBridge(): {ready?: () => void} | null {
50
+ if (typeof window === "undefined") return null
51
+ return (window as unknown as {mentra?: {ready?: () => void}}).mentra ?? null
52
+ }
53
+
54
+ export function MentraProvider({children, syncColorScheme = true, autoReady = true}: MentraProviderProps) {
38
55
  const scheme = useColorScheme()
39
56
 
57
+ useEffect(() => {
58
+ if (autoReady) getBridge()?.ready?.()
59
+ }, [autoReady])
60
+
40
61
  // Runs during render — before children paint, before effects fire.
41
62
  if (syncColorScheme && typeof document !== "undefined") {
42
63
  const el = document.documentElement
package/src/session.ts CHANGED
@@ -26,6 +26,7 @@ import {ConfigurationModule} from "./modules/configuration"
26
26
  import {DashboardAPI} from "./modules/dashboard"
27
27
  import {DisplayManager} from "./modules/display"
28
28
  import {EventManager, type TranscriptionEventRoute, type UnsubscribeFn} from "./modules/events"
29
+ import type {SpeechProcessingOptions} from "./modules/speechProcessing"
29
30
  import {GlassesModule} from "./modules/glasses"
30
31
  import {HeadingModule} from "./modules/heading"
31
32
  import {ImuModule} from "./modules/imu"
@@ -45,6 +46,7 @@ import {StreamModule} from "./modules/stream"
45
46
  import {SystemModule} from "./modules/system"
46
47
  import {MiniappsModule} from "./modules/miniapps"
47
48
  import {ActionsModule} from "./modules/actions"
49
+ import {TelemetryModule} from "./modules/telemetry"
48
50
  import {BlobModule} from "./modules/blob"
49
51
  import {
50
52
  MeetingModule,
@@ -130,6 +132,13 @@ export interface HostFeatures {
130
132
  captureAudio?: boolean
131
133
  /** Host keeps the UI closed until a background session that announced it sends READY. */
132
134
  initReady?: boolean
135
+ /**
136
+ * Host installs miniapps from a miniapp URL through `session.miniapps.install({url})`. Only a miniapp on the
137
+ * Mentra App's system list may call it; older Mentra Apps answer NOT_PERMITTED.
138
+ */
139
+ miniappInstall?: boolean
140
+ /** Host takes the miniapp's own events from `session.telemetry.capture` (Fleet Management's miniapp telemetry). */
141
+ telemetry?: boolean
133
142
  }
134
143
 
135
144
  export interface MiniappAuthState {
@@ -171,9 +180,22 @@ export class NotConnectedError extends Error {
171
180
  }
172
181
  }
173
182
 
183
+ /**
184
+ * @internal — `connect()` rejects with this when the host did not answer CONNECT
185
+ * within `connectTimeoutMs`. The session stays usable: `connect()` sends CONNECT again.
186
+ */
187
+ export class ConnectAckTimeoutError extends Error {
188
+ constructor() {
189
+ super("MiniappSession: CONNECT_ACK timeout")
190
+ this.name = "ConnectAckTimeoutError"
191
+ }
192
+ }
193
+
174
194
  export interface MiniappRequestError {
175
195
  code: string
176
196
  message: string
197
+ /** A finer cause, where a request documents one (`INSTALL_FAILED` from `session.miniapps.install`). */
198
+ reason?: string
177
199
  }
178
200
 
179
201
  // ---------------------------------------------------------------------------
@@ -189,6 +211,8 @@ interface PendingRequest {
189
211
  }
190
212
 
191
213
  const DEFAULT_CONNECT_TIMEOUT_MS = 10_000
214
+ /** Pause before a `registerMiniapp` session sends CONNECT again after a CONNECT_ACK timeout. */
215
+ const CONNECT_RETRY_MS = 1_000
192
216
 
193
217
  // Hard ceiling on how long a single bridge request waits for the host's
194
218
  // REQUEST_RESULT. Without it, a host that never responds (a hung cloud call, a
@@ -283,6 +307,8 @@ export class MiniappSession<TChannels extends object = any> {
283
307
  * declared action; `handle` (open to all) exposes one of your own.
284
308
  */
285
309
  public readonly actions: ActionsModule
310
+ /** The miniapp's own analytics, shown in its organization's Fleet Management (see {@link TelemetryModule}). */
311
+ public readonly telemetry: TelemetryModule
286
312
 
287
313
  /** Phone-declared glasses capabilities. Null until CONNECT_ACK arrives. */
288
314
  public capabilities: GlassesCapabilities | null = null
@@ -315,11 +341,26 @@ export class MiniappSession<TChannels extends object = any> {
315
341
 
316
342
  /**
317
343
  * Outbound queue for anything sent before CONNECT_ACK. Flushed in FIFO order
318
- * once the phone responds with CONNECT_ACK.
344
+ * once the phone responds with CONNECT_ACK. A queued request carries its id so
345
+ * one that has already been rejected is dropped instead of sent.
319
346
  */
320
- private readonly outboundQueue: string[] = []
347
+ private readonly outboundQueue: Array<{raw: string; requestId?: string}> = []
321
348
  private readonly pendingRequests = new Map<string, PendingRequest>()
349
+ /** In flight or succeeded. A failed attempt clears it so `connect()` can send CONNECT again. */
322
350
  private connectPromise: Promise<void> | null = null
351
+ /**
352
+ * Set by the first CONNECT_ACK and never cleared: the handshake completes once
353
+ * per session. The host answers every CONNECT, so after a retry the ACK for
354
+ * another CONNECT of this session can still arrive, in either order. Unlike
355
+ * `ready`, this survives a transport drop, which a session does not recover from.
356
+ */
357
+ private handshakeComplete = false
358
+ /** Rejects the handshake in flight. Set only while waiting for CONNECT_ACK. */
359
+ private failHandshake: ((error: Error) => void) | null = null
360
+ /** Set by `registerMiniapp`: a CONNECT_ACK timeout sends CONNECT again instead of failing `connect()`. */
361
+ private retryHandshake = false
362
+ /** Ends the pause before CONNECT is sent again, with the failure that ended it if any. Set only during that pause. */
363
+ private endRetryPause: ((failure?: Error) => void) | null = null
323
364
  private disposed = false
324
365
  /**
325
366
  * Set by `registerMiniapp` to the host's id for this spawn: CONNECT tells the
@@ -375,6 +416,12 @@ export class MiniappSession<TChannels extends object = any> {
375
416
  this.ui = new UIModuleImpl<TChannels>(this)
376
417
  this.miniapps = new MiniappsModule(this)
377
418
  this.actions = new ActionsModule(this)
419
+ this.telemetry = new TelemetryModule(this)
420
+ }
421
+
422
+ /** @internal Whether CONNECT_ACK arrived, so `hostFeatures` is the host's answer and not just unknown. */
423
+ get handshakeDone(): boolean {
424
+ return this.handshakeComplete
378
425
  }
379
426
 
380
427
  /**
@@ -448,7 +495,7 @@ export class MiniappSession<TChannels extends object = any> {
448
495
  _subscribe(
449
496
  streamType: string,
450
497
  handler: (data: unknown) => void,
451
- options: {forceLocal?: boolean} = {},
498
+ options: SpeechProcessingOptions = {},
452
499
  ): UnsubscribeFn {
453
500
  return this.events.subscribe(streamType, handler, options)
454
501
  }
@@ -458,52 +505,158 @@ export class MiniappSession<TChannels extends object = any> {
458
505
  // -------------------------------------------------------------------------
459
506
 
460
507
  /**
461
- * Connect to LocalMiniappRuntime. Idempotent — calling multiple times
462
- * returns the same Promise.
508
+ * Connect to LocalMiniappRuntime. Idempotent while a handshake is in flight
509
+ * or has succeeded: repeat calls return the same Promise. A failed attempt
510
+ * (CONNECT_ACK timeout, transport failure) does not stick, so a later call
511
+ * sends CONNECT again. A session started by `registerMiniapp` keeps sending
512
+ * CONNECT after a timeout, so this Promise (and `waitForReady()`) settles
513
+ * only when the host answers, the transport fails, or the session ends.
463
514
  */
464
515
  connect(): Promise<void> {
465
516
  if (this.disposed) {
466
517
  return Promise.reject(new NotConnectedError("MiniappSession was disposed"))
467
518
  }
468
519
  if (this.connectPromise) return this.connectPromise
520
+ // A CONNECT_ACK that arrived after an earlier attempt timed out still completed the handshake.
521
+ if (this.handshakeComplete) {
522
+ this.connectPromise = Promise.resolve()
523
+ return this.connectPromise
524
+ }
525
+
526
+ const attempt = this.retryHandshake ? this.connectUntilAcknowledged() : this.sendConnect()
527
+ this.connectPromise = attempt
528
+ attempt.catch(() => {
529
+ // Registered before the caller's handlers, so a retry from a rejection handler sends CONNECT again.
530
+ if (this.connectPromise === attempt) this.connectPromise = null
531
+ })
532
+ return attempt
533
+ }
534
+
535
+ /**
536
+ * @internal — called by `registerMiniapp` before its handler runs. The host
537
+ * owns this context's lifetime, so a host that has not answered CONNECT is
538
+ * stalled rather than gone: send CONNECT again instead of failing.
539
+ */
540
+ retryHandshakeOnTimeout(): void {
541
+ this.retryHandshake = true
542
+ }
543
+
544
+ private async connectUntilAcknowledged(): Promise<void> {
545
+ for (;;) {
546
+ try {
547
+ await this.sendConnect()
548
+ return
549
+ } catch (err) {
550
+ if (this.disposed || !(err instanceof ConnectAckTimeoutError)) throw err
551
+ }
552
+ // eslint-disable-next-line no-console
553
+ console.warn("[mentra-miniapp] CONNECT_ACK timed out; sending CONNECT again")
554
+ const failure = await this.pauseBeforeRetry()
555
+ if (failure) throw failure
556
+ // The CONNECT_ACK for an earlier CONNECT can still land during the pause.
557
+ if (this.handshakeComplete) return
558
+ if (this.disposed) throw new NotConnectedError("MiniappSession: connect aborted")
559
+ }
560
+ }
469
561
 
562
+ /**
563
+ * Resolves after CONNECT_RETRY_MS, or as soon as CONNECT_ACK lands or the
564
+ * session ends. Resolves with the error when the transport failed meanwhile.
565
+ */
566
+ private pauseBeforeRetry(): Promise<Error | undefined> {
567
+ return new Promise<Error | undefined>((resolve) => {
568
+ const end = (failure?: Error) => {
569
+ clearTimeout(timer)
570
+ this.emitter.off("ready", onReady)
571
+ if (this.endRetryPause === end) this.endRetryPause = null
572
+ resolve(failure)
573
+ }
574
+ const onReady = () => end()
575
+ const timer = setTimeout(end, CONNECT_RETRY_MS)
576
+ this.emitter.on("ready", onReady)
577
+ this.endRetryPause = end
578
+ })
579
+ }
580
+
581
+ /** Send one CONNECT and wait for its CONNECT_ACK. */
582
+ private sendConnect(): Promise<void> {
583
+ // Only a host that received CONNECT can be waited out. Before that, the transport is what failed.
584
+ let connectSent = false
585
+ // This attempt's own outcome. A slow open() can finish after a newer attempt
586
+ // took over, so nothing below acts through the session-wide failHandshake.
587
+ let attemptSettled = false
588
+ let failAttempt: (error: Error) => void = () => {}
470
589
  // Register the readiness listener BEFORE any awaits so that a synchronous
471
590
  // CONNECT_ACK delivery in tests (or the phone) can't race the subscription.
472
591
  const readyPromise = new Promise<void>((resolve, reject) => {
592
+ const settle = (error?: Error) => {
593
+ if (attemptSettled) return
594
+ attemptSettled = true
595
+ clearTimeout(timer)
596
+ this.emitter.off("ready", onReady)
597
+ this.emitter.off("error", onError)
598
+ if (this.failHandshake === onError) this.failHandshake = null
599
+ if (error) reject(error)
600
+ else resolve()
601
+ }
602
+ const onReady = () => settle()
603
+ const onError = (error: Error) => settle(error)
473
604
  const timer = setTimeout(() => {
474
- const err = new Error("MiniappSession: CONNECT_ACK timeout")
605
+ const err = connectSent
606
+ ? new ConnectAckTimeoutError()
607
+ : new Error("MiniappSession: transport did not open before the CONNECT_ACK timeout")
608
+ // Settled before the public emit, so a throwing "error" listener cannot leave it pending.
609
+ settle(err)
610
+ // Requests queued for a retried handshake wait for it, bounded by their own timeouts.
611
+ if (connectSent && this.retryHandshake) return
475
612
  this.failAllPending({code: MiniappErrorCode.NOT_CONNECTED, message: err.message})
476
613
  this.emitter.emit("error", err)
477
- reject(err)
478
614
  }, this.connectTimeoutMs)
479
-
480
- this.emitter.once("ready", () => {
481
- clearTimeout(timer)
482
- resolve()
483
- })
484
- this.emitter.once("error", (err) => {
485
- clearTimeout(timer)
486
- reject(err)
487
- })
615
+ this.emitter.on("ready", onReady)
616
+ this.emitter.on("error", onError)
617
+ this.failHandshake = onError
618
+ failAttempt = onError
488
619
  })
489
-
490
- this.connectPromise = (async () => {
491
- this.transport.onMessage((raw) => this.handleIncoming(raw))
492
- this.transport.onDisconnect((reason) => this.handleTransportDisconnect(reason))
493
- await this.transport.open()
494
-
495
- const requestId = makeRequestId()
496
- const connectPayload = {
497
- type: MiniappRequestType.CONNECT,
498
- packageName: this.packageName,
499
- ...(this.initSessionId !== null ? {initReady: true, sessionId: this.initSessionId} : {}),
620
+ // Settles once CONNECT is sent, or rejects if opening or sending fails.
621
+ const sent = (async () => {
622
+ try {
623
+ this.transport.onMessage((raw) => this.handleIncoming(raw))
624
+ this.transport.onDisconnect((reason) => this.handleTransportDisconnect(reason))
625
+ // An open transport stays as it is: a retried handshake only sends CONNECT again.
626
+ const opening = this.transport.isOpen() ? Promise.resolve() : this.transport.open()
627
+ // An open that finishes after disconnect() must not leave the transport open.
628
+ opening.then(
629
+ () => {
630
+ if (this.disposed) this.transport.close()
631
+ },
632
+ () => {},
633
+ )
634
+ await opening
635
+ // Settled while opening: failed (the timeout, disconnect(), a transport drop),
636
+ // or completed by an earlier CONNECT's ACK. Either way, send nothing.
637
+ if (attemptSettled) return
638
+ if (this.disposed) throw new NotConnectedError("MiniappSession: connect aborted")
639
+
640
+ const requestId = makeRequestId()
641
+ const connectPayload = {
642
+ type: MiniappRequestType.CONNECT,
643
+ packageName: this.packageName,
644
+ ...(this.initSessionId !== null ? {initReady: true, sessionId: this.initSessionId} : {}),
645
+ }
646
+ connectSent = true
647
+ this.transport.send(serializeEnvelope({payload: connectPayload, requestId}))
648
+ } catch (err) {
649
+ // Already reported through readyPromise; a newer attempt may own the session now.
650
+ if (attemptSettled) return
651
+ const error = err instanceof Error ? err : new Error(String(err))
652
+ if (!this.disposed) this.failAllPending({code: MiniappErrorCode.NOT_CONNECTED, message: error.message})
653
+ failAttempt(error)
654
+ throw error
500
655
  }
501
- this.transport.send(serializeEnvelope({payload: connectPayload, requestId}))
502
-
503
- await readyPromise
504
656
  })()
505
-
506
- return this.connectPromise
657
+ // The handshake can fail while the transport is still opening (disconnect(),
658
+ // the timeout): the attempt settles then, without waiting for open().
659
+ return Promise.all([sent, readyPromise]).then(() => undefined)
507
660
  }
508
661
 
509
662
  /**
@@ -534,6 +687,10 @@ export class MiniappSession<TChannels extends object = any> {
534
687
  disconnect(): void {
535
688
  if (this.disposed) return
536
689
  this.disposed = true
690
+ // End a handshake still waiting for CONNECT_ACK. Its timer would otherwise
691
+ // report a timeout for a session that no longer exists.
692
+ this.failHandshake?.(new NotConnectedError("MiniappSession: connect aborted"))
693
+ this.endRetryPause?.()
537
694
  // Give listeners one synchronous chance to flush final messages
538
695
  // (e.g. display.render([])) before we tear down the transport.
539
696
  try {
@@ -602,7 +759,7 @@ export class MiniappSession<TChannels extends object = any> {
602
759
  reject,
603
760
  timer,
604
761
  })
605
- this.enqueueOrSend(serializeEnvelope(envelope))
762
+ this.enqueueOrSend(serializeEnvelope(envelope), requestId)
606
763
  })
607
764
  }
608
765
 
@@ -647,7 +804,7 @@ export class MiniappSession<TChannels extends object = any> {
647
804
  // Internal — transport glue
648
805
  // -------------------------------------------------------------------------
649
806
 
650
- private enqueueOrSend(raw: string): void {
807
+ private enqueueOrSend(raw: string, requestId?: string): void {
651
808
  if (this.ready) {
652
809
  try {
653
810
  this.transport.send(raw)
@@ -657,12 +814,15 @@ export class MiniappSession<TChannels extends object = any> {
657
814
  }
658
815
  return
659
816
  }
660
- this.outboundQueue.push(raw)
817
+ this.outboundQueue.push(requestId === undefined ? {raw} : {raw, requestId})
661
818
  }
662
819
 
663
820
  private flushQueue(): void {
664
821
  const queue = this.outboundQueue.splice(0)
665
- for (const raw of queue) {
822
+ for (const {raw, requestId} of queue) {
823
+ // Rejected while waiting for the handshake (a CONNECT_ACK timeout or its own
824
+ // timeout). Its caller has seen the failure, so the host must not run it.
825
+ if (requestId !== undefined && !this.pendingRequests.has(requestId)) continue
666
826
  try {
667
827
  this.transport.send(raw)
668
828
  } catch (err) {
@@ -680,6 +840,10 @@ export class MiniappSession<TChannels extends object = any> {
680
840
 
681
841
  switch (type) {
682
842
  case MiniappResponseType.CONNECT_ACK: {
843
+ // The answer to another CONNECT of this session (a retry, or one whose
844
+ // attempt timed out). Applying it would run the handshake again: emit
845
+ // "ready" twice and replace state that later updates may have changed.
846
+ if (this.handshakeComplete) return
683
847
  const ack = payload as unknown as ConnectAckPayload
684
848
  this.userId = ack.userId ?? ""
685
849
  if (ack.packageName) this.packageName = ack.packageName
@@ -698,6 +862,7 @@ export class MiniappSession<TChannels extends object = any> {
698
862
  // that don't send `permissions` leave the all-false default in place
699
863
  // — `hasPermission` getters will simply return false.
700
864
  if (ack.permissions) this.applyPermissions(ack.permissions)
865
+ this.handshakeComplete = true
701
866
  this.ready = true
702
867
  this.flushQueue()
703
868
  this.emitter.emit("ready")
@@ -853,22 +1018,6 @@ export class MiniappSession<TChannels extends object = any> {
853
1018
  return
854
1019
  }
855
1020
 
856
- case MiniappResponseType.MINIAPPS_INSTALL_PROGRESS: {
857
- const {packageName, version, phase} = payload as Record<string, unknown>
858
- if (
859
- typeof packageName === "string" &&
860
- typeof version === "string" &&
861
- (phase === "downloading" ||
862
- phase === "verifying" ||
863
- phase === "extracting" ||
864
- phase === "activating" ||
865
- phase === "complete")
866
- ) {
867
- this.miniapps._deliverInstallProgress({packageName, version, phase})
868
- }
869
- return
870
- }
871
-
872
1021
  case MiniappResponseType.REQUEST_RESULT: {
873
1022
  const requestId = envelope.requestId
874
1023
  if (!requestId) return
@@ -912,6 +1061,11 @@ export class MiniappSession<TChannels extends object = any> {
912
1061
 
913
1062
  private handleTransportDisconnect(reason: string): void {
914
1063
  this.ready = false
1064
+ // A transport that drops during the handshake has failed it. Sending CONNECT
1065
+ // again over a dead bridge would keep that failure from the host.
1066
+ const failure = new Error(`MiniappSession: transport disconnected: ${reason}`)
1067
+ this.failHandshake?.(failure)
1068
+ this.endRetryPause?.(failure)
915
1069
  this.failAllPending({code: MiniappErrorCode.NOT_CONNECTED, message: `Transport disconnected: ${reason}`})
916
1070
  this.emitter.emit("disconnect", reason)
917
1071
  }
@@ -84,6 +84,11 @@ class LocalSocketWithMockFallback implements Transport {
84
84
  constructor(private readonly options: LocalSocketTransportOptions) {}
85
85
 
86
86
  async open(): Promise<void> {
87
+ // A retried handshake opens again: keep the transport already selected.
88
+ if (this.active?.isOpen()) return
89
+ // One that dropped is replaced, so it cannot keep delivering to the handlers.
90
+ this.active?.close()
91
+ this.active = null
87
92
  const local = new LocalSocketTransport(this.options)
88
93
  let timedOut = false
89
94
  const timeout = new Promise<void>((_, reject) => {
@@ -43,6 +43,8 @@ export class DispatchTransport implements Transport {
43
43
  private messageHandler: TransportMessageHandler | null = null
44
44
  private disconnectHandler: TransportDisconnectHandler | null = null
45
45
  private open_ = false
46
+ /** The delivery hook this transport installed; another transport may own the global later. */
47
+ private deliverHook: ((raw: string) => void) | null = null
46
48
 
47
49
  /** True iff `__dispatch` is bound on the current globalThis. */
48
50
  static isAvailable(): boolean {
@@ -57,9 +59,10 @@ export class DispatchTransport implements Transport {
57
59
  // route bridge frames here. Installed lazily so multiple transports
58
60
  // can share the same global if a test spins up two.
59
61
  const g = globalThis as unknown as BridgeDeliverGlobal
60
- g.__mentraDeliverBridgeRaw = (raw: string) => {
62
+ this.deliverHook = (raw: string) => {
61
63
  if (this.messageHandler) this.messageHandler(raw)
62
64
  }
65
+ g.__mentraDeliverBridgeRaw = this.deliverHook
63
66
  this.open_ = true
64
67
  }
65
68
 
@@ -95,9 +98,11 @@ export class DispatchTransport implements Transport {
95
98
  close(): void {
96
99
  this.open_ = false
97
100
  const g = globalThis as unknown as BridgeDeliverGlobal
98
- if (g.__mentraDeliverBridgeRaw) {
101
+ // A replacement session's transport may have installed its own hook since.
102
+ if (this.deliverHook && g.__mentraDeliverBridgeRaw === this.deliverHook) {
99
103
  delete g.__mentraDeliverBridgeRaw
100
104
  }
105
+ this.deliverHook = null
101
106
  }
102
107
 
103
108
  isOpen(): boolean {