@mentra/miniapp 3.2.1 → 3.3.0-beta.955

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 (44) hide show
  1. package/dist/background/index.d.ts +2 -1
  2. package/dist/background/index.d.ts.map +1 -1
  3. package/dist/background/index.js.map +1 -1
  4. package/dist/background/register.d.ts +6 -0
  5. package/dist/background/register.d.ts.map +1 -1
  6. package/dist/background/register.js +19 -4
  7. package/dist/background/register.js.map +1 -1
  8. package/dist/index.d.ts +2 -2
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js.map +1 -1
  11. package/dist/modules/events.d.ts +8 -4
  12. package/dist/modules/events.d.ts.map +1 -1
  13. package/dist/modules/events.js +46 -6
  14. package/dist/modules/events.js.map +1 -1
  15. package/dist/modules/meeting.d.ts +82 -0
  16. package/dist/modules/meeting.d.ts.map +1 -1
  17. package/dist/modules/meeting.js +137 -2
  18. package/dist/modules/meeting.js.map +1 -1
  19. package/dist/modules/miniapps.d.ts +101 -4
  20. package/dist/modules/miniapps.d.ts.map +1 -1
  21. package/dist/modules/miniapps.js +59 -4
  22. package/dist/modules/miniapps.js.map +1 -1
  23. package/dist/protocol.d.ts +48 -1
  24. package/dist/protocol.d.ts.map +1 -1
  25. package/dist/protocol.js +47 -0
  26. package/dist/protocol.js.map +1 -1
  27. package/dist/react/stream-preview/PreviewConnection.d.ts +7 -0
  28. package/dist/react/stream-preview/PreviewConnection.d.ts.map +1 -1
  29. package/dist/react/stream-preview/PreviewConnection.js +32 -1
  30. package/dist/react/stream-preview/PreviewConnection.js.map +1 -1
  31. package/dist/session.d.ts +20 -0
  32. package/dist/session.d.ts.map +1 -1
  33. package/dist/session.js +56 -1
  34. package/dist/session.js.map +1 -1
  35. package/package.json +2 -2
  36. package/src/background/index.ts +17 -0
  37. package/src/background/register.ts +28 -6
  38. package/src/index.ts +17 -1
  39. package/src/modules/events.ts +51 -6
  40. package/src/modules/meeting.ts +188 -2
  41. package/src/modules/miniapps.ts +145 -4
  42. package/src/protocol.ts +51 -0
  43. package/src/react/stream-preview/PreviewConnection.ts +36 -1
  44. package/src/session.ts +68 -0
@@ -1,11 +1,16 @@
1
1
  /**
2
2
  * @fileoverview MiniappsModule — `session.miniapps`.
3
3
  *
4
- * Discover and control the lifecycle of OTHER miniapps: list, start, stop.
5
- * SYSTEM-only — every call rejects with NOT_PERMITTED unless the caller is a
6
- * system app (Mentra AI is the first consumer). The action *capability* layer
7
- * (invoke / handle) lives on `session.actions`, not here — these three are
4
+ * Discover and control the lifecycle of OTHER miniapps: list, start, open,
5
+ * stop. SYSTEM-only — every call rejects with NOT_PERMITTED unless the caller
6
+ * is a system app (Mentra AI is the first consumer). The action *capability*
7
+ * layer (invoke / handle) lives on `session.actions`, not here — these are
8
8
  * operations on the app as a whole, not on a declared action.
9
+ *
10
+ * Installation (`install`, `checkInstallCompatibility`, `uninstall`) is
11
+ * narrower still: the host accepts it only from a Store miniapp bundled with
12
+ * the Mentra App build. The host downloads, verifies, and activates the
13
+ * release through its own installer; the Store only selects the release.
9
14
  */
10
15
 
11
16
  import {MiniappRequestType} from "../protocol"
@@ -22,6 +27,11 @@ export interface MiniappActionInfo {
22
27
  parameters?: Record<string, unknown>
23
28
  /** JSON-Schema descriptor for the structured value returned by the action. */
24
29
  outputSchema?: Record<string, unknown>
30
+ /**
31
+ * `persistent` (default) starts the target as normal user-visible activity.
32
+ * `transient` wakes it invisibly for the duration of the invocation only.
33
+ */
34
+ lifecycle: "persistent" | "transient"
25
35
  }
26
36
 
27
37
  /**
@@ -43,6 +53,12 @@ export interface MiniappInfo {
43
53
  version: string
44
54
  running: boolean
45
55
  compatibility: MiniappCompatibility
56
+ /** True when this package identity is backed by a ZIP in the Mentra App build. */
57
+ system: boolean
58
+ /** Store package that owns updates of this active release, when it is Store-managed. */
59
+ storeOwnerPackageName?: string
60
+ /** Store the host build assigns to update this bundled package's active release, if any. */
61
+ systemStoreOwnerPackageName?: string
46
62
  /** Declared actions (empty if the miniapp declares none). */
47
63
  actions: MiniappActionInfo[]
48
64
  }
@@ -52,7 +68,76 @@ export interface ListMiniappsOptions {
52
68
  includeIncompatible?: boolean
53
69
  }
54
70
 
71
+ export interface MiniappHardwareRequirement {
72
+ type: string
73
+ level: string
74
+ description?: string
75
+ }
76
+
77
+ /** Backend-neutral release request, accepted only from a bundled, host-trusted Store. */
78
+ export interface InstallMiniappRequest {
79
+ packageName: string
80
+ version: string
81
+ bundleUrl: string
82
+ /** SHA-256 of the release ZIP; the host refuses any other bytes. */
83
+ bundleSha256: string
84
+ /**
85
+ * Bearer for `bundleUrl`, when the Store's backend requires one. The host
86
+ * forwards it untouched and keeps no Store address of its own: entitlement is
87
+ * settled between this miniapp and its backend, integrity by the SHA-256 and
88
+ * the bundle's publisher signature.
89
+ */
90
+ bundleAuthorization?: string
91
+ /**
92
+ * Automatic update: never stop a running miniapp. A running or starting
93
+ * target defers the request with `APP_RUNNING`.
94
+ */
95
+ onlyIfStopped?: boolean
96
+ /**
97
+ * With `onlyIfStopped`: when the target is running, the host stages the
98
+ * release and asks the user whether to update now. Declining, or a prompt the
99
+ * host does not show (the Mentra App is in the background, another prompt is
100
+ * open, or this miniapp was asked within the last day), still answers
101
+ * `APP_RUNNING`.
102
+ */
103
+ askIfRunning?: boolean
104
+ /** Minimum Mentra App version declared by the release manifest. */
105
+ minHostVersion?: string
106
+ /** Mentra Miniapp SDK version declared by the release manifest. */
107
+ sdkVersion?: string
108
+ /** Glasses hardware requirements declared by the release manifest. */
109
+ hardwareRequirements?: MiniappHardwareRequirement[]
110
+ releaseId?: string
111
+ channel?: string
112
+ }
113
+
114
+ export interface InstallMiniappResult {
115
+ packageName: string
116
+ version: string
117
+ installedByStore: string
118
+ }
119
+
120
+ export interface InstallMiniappCompatibilityRequest {
121
+ minHostVersion?: string | null
122
+ sdkVersion?: string | null
123
+ hardwareRequirements?: MiniappHardwareRequirement[]
124
+ }
125
+
126
+ export type InstallMiniappCompatibility =
127
+ | {compatible: true}
128
+ | {compatible: false; blocker: "host" | "sdk" | "hardware"; reason: string}
129
+
130
+ export type InstallMiniappPhase = "downloading" | "verifying" | "extracting" | "activating" | "complete"
131
+
132
+ export interface InstallMiniappProgress {
133
+ packageName: string
134
+ version: string
135
+ phase: InstallMiniappPhase
136
+ }
137
+
55
138
  export class MiniappsModule {
139
+ private readonly progressHandlers = new Set<(progress: InstallMiniappProgress) => void>()
140
+
56
141
  constructor(private readonly session: MiniappSession) {}
57
142
 
58
143
  /**
@@ -82,6 +167,15 @@ export class MiniappsModule {
82
167
  })
83
168
  }
84
169
 
170
+ /** Start another miniapp and foreground its phone UI. SYSTEM-only. */
171
+ async open(packageName: string): Promise<void> {
172
+ await this.session.sendRequest<void>({
173
+ type: MiniappRequestType.MINIAPPS_START,
174
+ packageName,
175
+ foreground: true,
176
+ })
177
+ }
178
+
85
179
  /** Stop another miniapp. SYSTEM-only. */
86
180
  async stop(packageName: string): Promise<void> {
87
181
  await this.session.sendRequest<void>({
@@ -89,4 +183,51 @@ export class MiniappsModule {
89
183
  packageName,
90
184
  })
91
185
  }
186
+
187
+ /**
188
+ * Download, verify, and install a release through the phone host. Accepted
189
+ * only from a Store bundled with the Mentra App build; other callers receive
190
+ * NOT_PERMITTED.
191
+ */
192
+ async install(request: InstallMiniappRequest): Promise<InstallMiniappResult> {
193
+ return this.session.sendRequest<InstallMiniappResult>(
194
+ {
195
+ ...request,
196
+ type: MiniappRequestType.MINIAPPS_INSTALL,
197
+ },
198
+ // Downloading, validating, extracting, asking the user and relaunching
199
+ // can legitimately outlast the SDK's default request timeout. The request
200
+ // still settles on the host response or session disconnect.
201
+ {timeoutMs: 0},
202
+ )
203
+ }
204
+
205
+ /** Check host, Mentra Miniapp SDK, and glasses compatibility before offering or applying an update. */
206
+ async checkInstallCompatibility(request: InstallMiniappCompatibilityRequest): Promise<InstallMiniappCompatibility> {
207
+ return this.session.sendRequest<InstallMiniappCompatibility>({
208
+ type: MiniappRequestType.MINIAPPS_INSTALL_CHECK,
209
+ minHostVersion: request.minHostVersion ?? undefined,
210
+ sdkVersion: request.sdkVersion ?? undefined,
211
+ hardwareRequirements: request.hardwareRequirements ?? [],
212
+ })
213
+ }
214
+
215
+ /** Subscribe to host-owned install progress. Returns an unsubscribe function. */
216
+ onInstallProgress(handler: (progress: InstallMiniappProgress) => void): () => void {
217
+ this.progressHandlers.add(handler)
218
+ return () => this.progressHandlers.delete(handler)
219
+ }
220
+
221
+ /** @internal */
222
+ _deliverInstallProgress(progress: InstallMiniappProgress): void {
223
+ for (const handler of this.progressHandlers) handler(progress)
224
+ }
225
+
226
+ /** Uninstall a package this Store installed. Bundled Stores only. */
227
+ async uninstall(packageName: string): Promise<void> {
228
+ await this.session.sendRequest<void>({
229
+ type: MiniappRequestType.MINIAPPS_UNINSTALL,
230
+ packageName,
231
+ })
232
+ }
92
233
  }
package/src/protocol.ts CHANGED
@@ -16,6 +16,13 @@ export enum MiniappRequestType {
16
16
  /** Handshake: miniapp announces itself and asks phone to bind the session. */
17
17
  CONNECT = "miniapp_connect",
18
18
 
19
+ /**
20
+ * One-shot: the background's `registerMiniapp` handler has settled, so its
21
+ * `session.ui.handle` handlers exist. Sent only to hosts advertising
22
+ * `hostFeatures.initReady`; the host keeps the UI closed until it arrives.
23
+ */
24
+ READY = "miniapp_ready",
25
+
19
26
  /** Request a fresh miniapp-scoped backend auth token. */
20
27
  AUTH_REFRESH = "miniapp_auth_refresh",
21
28
 
@@ -218,6 +225,12 @@ export enum MiniappRequestType {
218
225
  MINIAPPS_START = "miniapp_apps_start",
219
226
  /** Stop another miniapp. */
220
227
  MINIAPPS_STOP = "miniapp_apps_stop",
228
+ /** Install/update an approved bundle. Bundled host-trusted Stores only. */
229
+ MINIAPPS_INSTALL = "miniapp_apps_install",
230
+ /** Preflight a release's host/SDK/hardware requirements without downloading it. */
231
+ MINIAPPS_INSTALL_CHECK = "miniapp_apps_install_check",
232
+ /** Uninstall a package owned by the calling Store. Bundled host-trusted Stores only. */
233
+ MINIAPPS_UNINSTALL = "miniapp_apps_uninstall",
221
234
  /** Invoke a declared action on another miniapp; headless-wakes it if stopped. */
222
235
  ACTION_INVOKE = "miniapp_action_invoke",
223
236
  /** Target → host: the result of a delivered ACTION_CALL, correlated by callId. */
@@ -242,6 +255,20 @@ export enum MiniappRequestType {
242
255
  MEETING_SET_VIDEO_ENABLED = "miniapp_meeting_set_video_enabled",
243
256
  MEETING_UPDATE_VIDEO_SOURCE = "miniapp_meeting_update_video_source",
244
257
  MEETING_GET_STATE = "miniapp_meeting_get_state",
258
+ /** Stop the glasses publisher for a photo. The meeting, hotspot, and audio stay up. */
259
+ MEETING_PAUSE_VIDEO_PUBLISHER = "miniapp_meeting_pause_video_publisher",
260
+ MEETING_RESUME_VIDEO_PUBLISHER = "miniapp_meeting_resume_video_publisher",
261
+ /** Full-frame "Taking a photo..." card on the outgoing video. Resolves after the first card frame. */
262
+ MEETING_SHOW_CARD = "miniapp_meeting_show_card",
263
+ /** Replace the card with a still. `durationMs` is counted by the caller from `shownAt`. */
264
+ MEETING_SHOW_IMAGE = "miniapp_meeting_show_image",
265
+ /** Stop holding a card or still so glasses frames reach Teams again. */
266
+ MEETING_SHOW_LIVE = "miniapp_meeting_show_live",
267
+ /**
268
+ * Direct link only: card, full-size glasses photo, still, and live again, all run by the host
269
+ * without stopping the glasses publisher. Resolves after the still has been held `durationMs`.
270
+ */
271
+ MEETING_CAPTURE_STILL = "miniapp_meeting_capture_still",
245
272
  }
246
273
 
247
274
  // ============================================================================
@@ -267,6 +294,9 @@ export enum MiniappResponseType {
267
294
  /** Push: host color scheme (light/dark) changed. */
268
295
  COLOR_SCHEME_CHANGE = "miniapp_color_scheme_change",
269
296
 
297
+ /** Push: a Store installation moved to another host-side phase. */
298
+ MINIAPPS_INSTALL_PROGRESS = "miniapp_apps_install_progress",
299
+
270
300
  /**
271
301
  * Push: speaker playback state transitioned. Per-miniapp; the runtime sends
272
302
  * to the owning miniapp only. Carries {state, errorCode?, errorMessage?,
@@ -304,6 +334,19 @@ export enum MiniappResponseType {
304
334
  */
305
335
  MEETING_STATE = "miniapp_meeting_state",
306
336
 
337
+ /**
338
+ * Push: a photo pause hit its ceiling and the publisher was started again.
339
+ * Carries {pauseId, status: "expired"}. A resume the miniapp sends itself is not this event.
340
+ */
341
+ MEETING_VIDEO_PUBLISHER = "miniapp_meeting_video_publisher",
342
+
343
+ /**
344
+ * Push: progress of one `meeting.captureStill`. Carries {stillId, phase} with phase `card`
345
+ * (card on the tile), `uploading` (the glasses captured and are uploading), or `shown` (the
346
+ * still is on the tile). The request result still settles the call.
347
+ */
348
+ MEETING_STILL = "miniapp_meeting_still",
349
+
307
350
  /**
308
351
  * Push: a preview lease changed state. Carries {handleId, state: "held" | "ended", reason?}.
309
352
  * See PreviewHandle.onStatus().
@@ -423,6 +466,14 @@ export enum MiniappErrorCode {
423
466
  APP_NOT_FOUND = "APP_NOT_FOUND",
424
467
  /** Target miniapp is incompatible with the connected glasses. */
425
468
  APP_NOT_COMPATIBLE = "APP_NOT_COMPATIBLE",
469
+ /** Bundle download, validation, or activation failed. */
470
+ 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",
426
477
  /** Target miniapp does not declare the requested action. */
427
478
  ACTION_NOT_FOUND = "ACTION_NOT_FOUND",
428
479
  /** Target connected but never registered a handler for the action (within the buffer window). */
@@ -33,9 +33,14 @@ import {ackMessage, createPreviewTransport, type PreviewTransport, type PreviewT
33
33
  /** The only control protocol this SDK speaks. Anything else is reported as `unsupported`. */
34
34
  export const PREVIEW_PROTOCOL_VERSION = 1
35
35
 
36
- /** Automatic re-handshakes after a transport failure, per window, before giving up until remount. */
36
+ /**
37
+ * Immediate re-handshakes after a transport failure, per window. A burst past this waits
38
+ * {@link RECONNECT_COOLDOWN_MS} and tries again, so a stuck ack cannot hide the preview for the
39
+ * rest of the call.
40
+ */
37
41
  const RECONNECT_BUDGET = 3
38
42
  const RECONNECT_WINDOW_MS = 60_000
43
+ const RECONNECT_COOLDOWN_MS = 3_000
39
44
  /** Immediate re-handshakes after the host answers a handshake as stale. */
40
45
  const STALE_HANDSHAKE_RETRIES = 2
41
46
 
@@ -97,6 +102,8 @@ export interface PreviewConnectionDeps {
97
102
  /** Document event hookup; defaults to the real `document`/`window`. */
98
103
  listen?: (target: "document" | "window", type: string, handler: () => void) => () => void
99
104
  isDocumentVisible?: () => boolean
105
+ /** Delay helper. Returns a cancel function. Defaults to `setTimeout`. */
106
+ after?: (ms: number, fn: () => void) => () => void
100
107
  }
101
108
 
102
109
  function defaultListen(target: "document" | "window", type: string, handler: () => void): () => void {
@@ -117,6 +124,11 @@ function defaultIsVisible(): boolean {
117
124
  return typeof document === "undefined" || document.visibilityState !== "hidden"
118
125
  }
119
126
 
127
+ function defaultAfter(ms: number, fn: () => void): () => void {
128
+ const id = setTimeout(fn, ms)
129
+ return () => clearTimeout(id)
130
+ }
131
+
120
132
  interface Applied {
121
133
  epoch: number
122
134
  tier: PreviewTier | null
@@ -143,11 +155,13 @@ export class PreviewConnection {
143
155
  private handshaking: Promise<boolean> | null = null
144
156
  private opChain: Promise<void> = Promise.resolve()
145
157
  private reconnectTimes: number[] = []
158
+ private reconnectCooldown: (() => void) | null = null
146
159
  private paused = false
147
160
  private readonly creditLoop: CreditLoop
148
161
  private readonly createTransport: NonNullable<PreviewConnectionDeps["createTransport"]>
149
162
  private readonly now: () => number
150
163
  private readonly isVisible: () => boolean
164
+ private readonly after: (ms: number, fn: () => void) => () => void
151
165
  private readonly unsubscribers: Array<() => void> = []
152
166
  private counters = {handshakes: 0, reconnects: 0, staleReplies: 0, staleLocalOps: 0, tierChanges: 0}
153
167
 
@@ -155,6 +169,7 @@ export class PreviewConnection {
155
169
  this.createTransport = deps.createTransport ?? createPreviewTransport
156
170
  this.now = deps.now ?? (() => (typeof performance !== "undefined" ? performance.now() : Date.now()))
157
171
  this.isVisible = deps.isDocumentVisible ?? defaultIsVisible
172
+ this.after = deps.after ?? defaultAfter
158
173
  this.state = deps.channel ? "idle" : "unavailable"
159
174
  this.creditLoop = new CreditLoop({
160
175
  sendAck: (gen, seq) => this.transport?.sendText(ackMessage(gen, seq)),
@@ -237,6 +252,7 @@ export class PreviewConnection {
237
252
  close(reason: string): void {
238
253
  if (this.state === "closed") return
239
254
  previewTrace("connection_closed", {reason, docGen: this.docGen})
255
+ this.clearReconnectCooldown()
240
256
  this.dropTransport()
241
257
  this.setState("closed", {reason})
242
258
  }
@@ -244,6 +260,7 @@ export class PreviewConnection {
244
260
  /** Test seam: detach from the channel and document. */
245
261
  dispose(): void {
246
262
  for (const unsubscribe of this.unsubscribers.splice(0)) unsubscribe()
263
+ this.clearReconnectCooldown()
247
264
  this.dropTransport()
248
265
  }
249
266
 
@@ -510,14 +527,32 @@ export class PreviewConnection {
510
527
  this.reconnectTimes = this.reconnectTimes.filter((t) => at - t < RECONNECT_WINDOW_MS)
511
528
  if (this.reconnectTimes.length >= RECONNECT_BUDGET) {
512
529
  previewTraceWarn("reconnect_budget_exhausted", {reason, docGen: this.docGen})
530
+ this.armReconnectCooldown(reason)
513
531
  return
514
532
  }
533
+ this.clearReconnectCooldown()
515
534
  this.reconnectTimes.push(at)
516
535
  this.counters.reconnects += 1
517
536
  previewTrace("reconnect", {reason, docGen: this.docGen, reconnects: this.counters.reconnects})
518
537
  this.sync()
519
538
  }
520
539
 
540
+ /** After a burst of failures, try once more instead of leaving the preview on the uplink card. */
541
+ private armReconnectCooldown(reason: string): void {
542
+ if (this.reconnectCooldown) return
543
+ this.reconnectCooldown = this.after(RECONNECT_COOLDOWN_MS, () => {
544
+ this.reconnectCooldown = null
545
+ if (this.state !== "error" || !this.isVisible() || !this.wantsFrames()) return
546
+ this.reconnectTimes = []
547
+ this.scheduleReconnect(reason)
548
+ })
549
+ }
550
+
551
+ private clearReconnectCooldown(): void {
552
+ this.reconnectCooldown?.()
553
+ this.reconnectCooldown = null
554
+ }
555
+
521
556
  private dropTransport(): void {
522
557
  this.connectionGen += 1
523
558
  const transport = this.transport
package/src/session.ts CHANGED
@@ -124,8 +124,12 @@ export interface ConnectAckPayload {
124
124
  }
125
125
 
126
126
  export interface HostFeatures {
127
+ /** @internal Runtime projects transcription independently for each listener. */
128
+ transcriptionListeners?: boolean
127
129
  /** Host honors `startStream({captureAudio})` for the lifetime of a WHIP session. */
128
130
  captureAudio?: boolean
131
+ /** Host keeps the UI closed until a background session that announced it sends READY. */
132
+ initReady?: boolean
129
133
  }
130
134
 
131
135
  export interface MiniappAuthState {
@@ -213,6 +217,8 @@ type SessionEmitterEvents = {
213
217
  permissions: (perms: PermissionRecord) => void
214
218
  speakerState: (event: import("./modules/speaker").SpeakerStateEvent) => void
215
219
  meetingState: (event: import("./modules/meeting").MeetingState) => void
220
+ meetingVideoPublisher: (event: import("./modules/meeting").MeetingVideoPublisherEvent) => void
221
+ meetingStill: (event: import("./modules/meeting").MeetingStillProgressEvent) => void
216
222
  auth: (auth: MiniappAuthState) => void
217
223
  }
218
224
 
@@ -315,6 +321,12 @@ export class MiniappSession<TChannels extends object = any> {
315
321
  private readonly pendingRequests = new Map<string, PendingRequest>()
316
322
  private connectPromise: Promise<void> | null = null
317
323
  private disposed = false
324
+ /**
325
+ * Set by `registerMiniapp` to the host's id for this spawn: CONNECT tells the
326
+ * host to wait for READY, and both carry the id so the host can ignore
327
+ * frames from a previous context.
328
+ */
329
+ private initSessionId: string | null = null
318
330
 
319
331
  /** Manifest-declared permission cache. Updated on CONNECT_ACK / PERMISSIONS_UPDATE. */
320
332
  private _permissions: PermissionRecord = {
@@ -484,6 +496,7 @@ export class MiniappSession<TChannels extends object = any> {
484
496
  const connectPayload = {
485
497
  type: MiniappRequestType.CONNECT,
486
498
  packageName: this.packageName,
499
+ ...(this.initSessionId !== null ? {initReady: true, sessionId: this.initSessionId} : {}),
487
500
  }
488
501
  this.transport.send(serializeEnvelope({payload: connectPayload, requestId}))
489
502
 
@@ -493,6 +506,21 @@ export class MiniappSession<TChannels extends object = any> {
493
506
  return this.connectPromise
494
507
  }
495
508
 
509
+ /**
510
+ * @internal — called by `registerMiniapp` before `connect()`. The host then
511
+ * keeps the UI closed until {@link reportInitReady}, so UI requests cannot
512
+ * reach the background before its `session.ui.handle` handlers exist.
513
+ */
514
+ announceInitReady(sessionId: string): void {
515
+ this.initSessionId = sessionId
516
+ }
517
+
518
+ /** @internal — the `registerMiniapp` handler settled; let the host open the UI. */
519
+ reportInitReady(): void {
520
+ if (this.initSessionId === null || this.disposed || !this.hostFeatures?.initReady) return
521
+ this.sendOneShot({type: MiniappRequestType.READY, sessionId: this.initSessionId})
522
+ }
523
+
496
524
  /** Resolves when `ready` becomes true, or rejects if connect failed. */
497
525
  waitForReady(): Promise<void> {
498
526
  if (this.ready) return Promise.resolve()
@@ -709,8 +737,15 @@ export class MiniappSession<TChannels extends object = any> {
709
737
  case MiniappResponseType.MEETING_STATE: {
710
738
  const state = payload.state as import("./modules/meeting").MeetingPhase | undefined
711
739
  if (!state) return
740
+ const identityMode =
741
+ payload.identityMode === "guest" || payload.identityMode === "teams-user" ? payload.identityMode : undefined
712
742
  const event: import("./modules/meeting").MeetingState = {
713
743
  state,
744
+ identityMode,
745
+ guestReason:
746
+ identityMode === "guest"
747
+ ? (payload.guestReason as import("./modules/meeting").MeetingState["guestReason"])
748
+ : undefined,
714
749
  muted: Boolean(payload.muted),
715
750
  videoEnabled: typeof payload.videoEnabled === "boolean" ? payload.videoEnabled : undefined,
716
751
  error: payload.error as string | undefined,
@@ -732,6 +767,22 @@ export class MiniappSession<TChannels extends object = any> {
732
767
  return
733
768
  }
734
769
 
770
+ case MiniappResponseType.MEETING_VIDEO_PUBLISHER: {
771
+ const pauseId = typeof payload.pauseId === "string" ? payload.pauseId : ""
772
+ if (!pauseId || payload.status !== "expired") return
773
+ const event = {pauseId, status: "expired" as const}
774
+ this.emitter.emit("meetingVideoPublisher", event)
775
+ return
776
+ }
777
+
778
+ case MiniappResponseType.MEETING_STILL: {
779
+ const stillId = typeof payload.stillId === "string" ? payload.stillId : ""
780
+ const phase = payload.phase
781
+ if (!stillId || (phase !== "card" && phase !== "uploading" && phase !== "shown")) return
782
+ this.emitter.emit("meetingStill", {stillId, phase})
783
+ return
784
+ }
785
+
735
786
  case MiniappResponseType.STREAM_PREVIEW_STATUS: {
736
787
  this.stream._applyPreviewStatus(payload)
737
788
  return
@@ -759,6 +810,7 @@ export class MiniappSession<TChannels extends object = any> {
759
810
  streamType,
760
811
  payload.data,
761
812
  payload.transcriptionRoute as TranscriptionEventRoute | undefined,
813
+ payload.listenerId as string | undefined,
762
814
  )
763
815
  return
764
816
  }
@@ -801,6 +853,22 @@ export class MiniappSession<TChannels extends object = any> {
801
853
  return
802
854
  }
803
855
 
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
+
804
872
  case MiniappResponseType.REQUEST_RESULT: {
805
873
  const requestId = envelope.requestId
806
874
  if (!requestId) return