@mentra/miniapp 3.2.1-dev.314 → 3.3.0-beta.942

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 (132) hide show
  1. package/README.md +16 -0
  2. package/dist/background/index.d.ts +6 -3
  3. package/dist/background/index.d.ts.map +1 -1
  4. package/dist/background/index.js +1 -0
  5. package/dist/background/index.js.map +1 -1
  6. package/dist/background/register.d.ts +6 -0
  7. package/dist/background/register.d.ts.map +1 -1
  8. package/dist/background/register.js +19 -4
  9. package/dist/background/register.js.map +1 -1
  10. package/dist/index.d.ts +7 -4
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +2 -0
  13. package/dist/index.js.map +1 -1
  14. package/dist/modules/display.d.ts +26 -0
  15. package/dist/modules/display.d.ts.map +1 -1
  16. package/dist/modules/display.js +1 -0
  17. package/dist/modules/display.js.map +1 -1
  18. package/dist/modules/events.d.ts +8 -4
  19. package/dist/modules/events.d.ts.map +1 -1
  20. package/dist/modules/events.js +46 -6
  21. package/dist/modules/events.js.map +1 -1
  22. package/dist/modules/meeting.d.ts +129 -0
  23. package/dist/modules/meeting.d.ts.map +1 -1
  24. package/dist/modules/meeting.js +200 -14
  25. package/dist/modules/meeting.js.map +1 -1
  26. package/dist/modules/mic.d.ts +5 -4
  27. package/dist/modules/mic.d.ts.map +1 -1
  28. package/dist/modules/mic.js +5 -4
  29. package/dist/modules/mic.js.map +1 -1
  30. package/dist/modules/miniapps.d.ts +101 -4
  31. package/dist/modules/miniapps.d.ts.map +1 -1
  32. package/dist/modules/miniapps.js +59 -4
  33. package/dist/modules/miniapps.js.map +1 -1
  34. package/dist/modules/speaker.d.ts +2 -0
  35. package/dist/modules/speaker.d.ts.map +1 -1
  36. package/dist/modules/speaker.js +5 -0
  37. package/dist/modules/speaker.js.map +1 -1
  38. package/dist/modules/stream.d.ts +46 -0
  39. package/dist/modules/stream.d.ts.map +1 -1
  40. package/dist/modules/stream.js +107 -0
  41. package/dist/modules/stream.js.map +1 -1
  42. package/dist/protocol.d.ts +86 -1
  43. package/dist/protocol.d.ts.map +1 -1
  44. package/dist/protocol.js +82 -0
  45. package/dist/protocol.js.map +1 -1
  46. package/dist/react/StreamPreview.d.ts +41 -0
  47. package/dist/react/StreamPreview.d.ts.map +1 -0
  48. package/dist/react/StreamPreview.js +144 -0
  49. package/dist/react/StreamPreview.js.map +1 -0
  50. package/dist/react/index.d.ts +3 -0
  51. package/dist/react/index.d.ts.map +1 -1
  52. package/dist/react/index.js +2 -0
  53. package/dist/react/index.js.map +1 -1
  54. package/dist/react/stream-preview/PreviewConnection.d.ts +146 -0
  55. package/dist/react/stream-preview/PreviewConnection.d.ts.map +1 -0
  56. package/dist/react/stream-preview/PreviewConnection.js +493 -0
  57. package/dist/react/stream-preview/PreviewConnection.js.map +1 -0
  58. package/dist/react/stream-preview/controlChannel.d.ts +75 -0
  59. package/dist/react/stream-preview/controlChannel.d.ts.map +1 -0
  60. package/dist/react/stream-preview/controlChannel.js +55 -0
  61. package/dist/react/stream-preview/controlChannel.js.map +1 -0
  62. package/dist/react/stream-preview/creditLoop.d.ts +81 -0
  63. package/dist/react/stream-preview/creditLoop.d.ts.map +1 -0
  64. package/dist/react/stream-preview/creditLoop.js +146 -0
  65. package/dist/react/stream-preview/creditLoop.js.map +1 -0
  66. package/dist/react/stream-preview/protocol.d.ts +113 -0
  67. package/dist/react/stream-preview/protocol.d.ts.map +1 -0
  68. package/dist/react/stream-preview/protocol.js +148 -0
  69. package/dist/react/stream-preview/protocol.js.map +1 -0
  70. package/dist/react/stream-preview/resizeCoalescer.d.ts +38 -0
  71. package/dist/react/stream-preview/resizeCoalescer.d.ts.map +1 -0
  72. package/dist/react/stream-preview/resizeCoalescer.js +71 -0
  73. package/dist/react/stream-preview/resizeCoalescer.js.map +1 -0
  74. package/dist/react/stream-preview/testFrames.d.ts +38 -0
  75. package/dist/react/stream-preview/testFrames.d.ts.map +1 -0
  76. package/dist/react/stream-preview/testFrames.js +50 -0
  77. package/dist/react/stream-preview/testFrames.js.map +1 -0
  78. package/dist/react/stream-preview/tiers.d.ts +21 -0
  79. package/dist/react/stream-preview/tiers.d.ts.map +1 -0
  80. package/dist/react/stream-preview/tiers.js +33 -0
  81. package/dist/react/stream-preview/tiers.js.map +1 -0
  82. package/dist/react/stream-preview/trace.d.ts +23 -0
  83. package/dist/react/stream-preview/trace.d.ts.map +1 -0
  84. package/dist/react/stream-preview/trace.js +71 -0
  85. package/dist/react/stream-preview/trace.js.map +1 -0
  86. package/dist/react/stream-preview/transport.d.ts +79 -0
  87. package/dist/react/stream-preview/transport.d.ts.map +1 -0
  88. package/dist/react/stream-preview/transport.js +209 -0
  89. package/dist/react/stream-preview/transport.js.map +1 -0
  90. package/dist/react/stream-preview/yuvRenderer.d.ts +31 -0
  91. package/dist/react/stream-preview/yuvRenderer.d.ts.map +1 -0
  92. package/dist/react/stream-preview/yuvRenderer.js +398 -0
  93. package/dist/react/stream-preview/yuvRenderer.js.map +1 -0
  94. package/dist/react/useHistoryState.d.ts +35 -0
  95. package/dist/react/useHistoryState.d.ts.map +1 -0
  96. package/dist/react/useHistoryState.js +117 -0
  97. package/dist/react/useHistoryState.js.map +1 -0
  98. package/dist/session.d.ts +25 -0
  99. package/dist/session.d.ts.map +1 -1
  100. package/dist/session.js +61 -1
  101. package/dist/session.js.map +1 -1
  102. package/dist/ui/index.d.ts +3 -0
  103. package/dist/ui/index.d.ts.map +1 -1
  104. package/dist/ui/index.js +2 -0
  105. package/dist/ui/index.js.map +1 -1
  106. package/package.json +8 -3
  107. package/src/background/index.ts +28 -1
  108. package/src/background/register.ts +28 -6
  109. package/src/index.ts +29 -1
  110. package/src/modules/display.ts +29 -0
  111. package/src/modules/events.ts +51 -6
  112. package/src/modules/meeting.ts +292 -15
  113. package/src/modules/mic.ts +5 -4
  114. package/src/modules/miniapps.ts +145 -4
  115. package/src/modules/speaker.ts +10 -4
  116. package/src/modules/stream.ts +153 -1
  117. package/src/protocol.ts +125 -0
  118. package/src/react/StreamPreview.tsx +187 -0
  119. package/src/react/index.ts +3 -0
  120. package/src/react/stream-preview/PreviewConnection.ts +587 -0
  121. package/src/react/stream-preview/controlChannel.ts +119 -0
  122. package/src/react/stream-preview/creditLoop.ts +189 -0
  123. package/src/react/stream-preview/protocol.ts +227 -0
  124. package/src/react/stream-preview/resizeCoalescer.ts +88 -0
  125. package/src/react/stream-preview/testFrames.ts +86 -0
  126. package/src/react/stream-preview/tiers.ts +37 -0
  127. package/src/react/stream-preview/trace.ts +81 -0
  128. package/src/react/stream-preview/transport.ts +242 -0
  129. package/src/react/stream-preview/yuvRenderer.ts +453 -0
  130. package/src/react/useHistoryState.ts +135 -0
  131. package/src/session.ts +76 -0
  132. package/src/ui/index.ts +3 -0
@@ -0,0 +1,587 @@
1
+ /**
2
+ * The preview connection for this document.
3
+ *
4
+ * Three owners with three lifetimes meet here:
5
+ * - The **lease** belongs to the miniapp's background (`session.stream.preview()`). The page
6
+ * never creates or releases it; it only hears `lease_available` / `lease_ended`.
7
+ * - The **connection** belongs to this document: the host config (token, docGen), the frame
8
+ * transport and the credit loop. It is a module-scoped singleton so it survives
9
+ * `<StreamPreview>` unmounting and remounting; a remount sends `start` without a handshake.
10
+ * It ends with the document (reload, navigation, `pagehide`) or when the lease ends.
11
+ * - The **renderer** belongs to the component and is attached here only as a draw callback.
12
+ *
13
+ * Control is desired-state: the component says which mount epoch wants which tier and whether it
14
+ * wants frames, and `sync()` sends the difference to the host over `_preview`. A new document
15
+ * always needs a new handshake; a new mount never does.
16
+ */
17
+
18
+ import {createMentraControlChannel, PreviewControlError} from "./controlChannel"
19
+ import type {
20
+ PreviewControlChannel,
21
+ PreviewControlReply,
22
+ PreviewControlRequest,
23
+ PreviewDocumentConfig,
24
+ PreviewHandshakeResult,
25
+ PreviewHostEvent,
26
+ } from "./controlChannel"
27
+ import {CreditLoop, type CreditLoopStats} from "./creditLoop"
28
+ import type {ParsedFrame} from "./protocol"
29
+ import {sameTier, type PreviewTier} from "./tiers"
30
+ import {previewTrace, previewTraceWarn, previewTraceWarnLimited} from "./trace"
31
+ import {ackMessage, createPreviewTransport, type PreviewTransport, type PreviewTransportOptions} from "./transport"
32
+
33
+ /** The only control protocol this SDK speaks. Anything else is reported as `unsupported`. */
34
+ export const PREVIEW_PROTOCOL_VERSION = 1
35
+
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
+ */
41
+ const RECONNECT_BUDGET = 3
42
+ const RECONNECT_WINDOW_MS = 60_000
43
+ const RECONNECT_COOLDOWN_MS = 3_000
44
+ /** Immediate re-handshakes after the host answers a handshake as stale. */
45
+ const STALE_HANDSHAKE_RETRIES = 2
46
+
47
+ export type PreviewConnectionState =
48
+ /** No handshake attempted yet in this document, or the lease ended and nobody wants frames. */
49
+ | "idle"
50
+ | "handshaking"
51
+ /** The host has no lease for this miniapp yet. Not an error: `lease_available` will follow. */
52
+ | "waiting_for_lease"
53
+ | "connecting"
54
+ | "open"
55
+ /** A failure that a re-handshake may fix (transport lost, ack timeout, host refused). */
56
+ | "error"
57
+ /** Terminal for this document: unknown protocol version or missing platform support. */
58
+ | "unsupported"
59
+ /** Not running inside a Mentra App WebView. */
60
+ | "unavailable"
61
+ | "closed"
62
+
63
+ export interface PreviewConnectionStateDetail {
64
+ code?: string
65
+ reason?: string
66
+ paused?: boolean
67
+ }
68
+
69
+ /** What a mounted `<StreamPreview>` gives the connection. */
70
+ export interface PreviewSink {
71
+ readonly mountEpoch: number
72
+ /** Submit one frame; null when the renderer has no usable context. */
73
+ draw(frame: ParsedFrame): number | null
74
+ onState(state: PreviewConnectionState, detail: PreviewConnectionStateDetail): void
75
+ onStatus(status: Record<string, unknown>): void
76
+ onError(code: string): void
77
+ }
78
+
79
+ export interface PreviewDesiredState {
80
+ /** Rendered box in device pixels; only sent when `tier` changes. */
81
+ boxWidth: number
82
+ boxHeight: number
83
+ /** Null means hidden (zero-size box). */
84
+ tier: PreviewTier | null
85
+ /** False while the page is hidden (`visibilitychange`) or the component is unmounting. */
86
+ running: boolean
87
+ }
88
+
89
+ export interface PreviewConnectionCounters {
90
+ handshakes: number
91
+ reconnects: number
92
+ staleReplies: number
93
+ staleLocalOps: number
94
+ tierChanges: number
95
+ page: CreditLoopStats
96
+ }
97
+
98
+ export interface PreviewConnectionDeps {
99
+ channel: PreviewControlChannel | null
100
+ createTransport?: (transport: "websocket" | "webmessage", options: PreviewTransportOptions) => PreviewTransport
101
+ now?: () => number
102
+ /** Document event hookup; defaults to the real `document`/`window`. */
103
+ listen?: (target: "document" | "window", type: string, handler: () => void) => () => void
104
+ isDocumentVisible?: () => boolean
105
+ /** Delay helper. Returns a cancel function. Defaults to `setTimeout`. */
106
+ after?: (ms: number, fn: () => void) => () => void
107
+ }
108
+
109
+ function defaultListen(target: "document" | "window", type: string, handler: () => void): () => void {
110
+ const node =
111
+ target === "document"
112
+ ? typeof document === "undefined"
113
+ ? null
114
+ : document
115
+ : typeof window === "undefined"
116
+ ? null
117
+ : window
118
+ if (!node) return () => {}
119
+ node.addEventListener(type, handler)
120
+ return () => node.removeEventListener(type, handler)
121
+ }
122
+
123
+ function defaultIsVisible(): boolean {
124
+ return typeof document === "undefined" || document.visibilityState !== "hidden"
125
+ }
126
+
127
+ function defaultAfter(ms: number, fn: () => void): () => void {
128
+ const id = setTimeout(fn, ms)
129
+ return () => clearTimeout(id)
130
+ }
131
+
132
+ interface Applied {
133
+ epoch: number
134
+ tier: PreviewTier | null
135
+ running: boolean
136
+ }
137
+
138
+ const NOTHING_APPLIED: Applied = {epoch: -1, tier: null, running: false}
139
+
140
+ export class PreviewConnection {
141
+ private state: PreviewConnectionState
142
+ private detail: PreviewConnectionStateDetail = {}
143
+ private docGen = 0
144
+ private config: PreviewDocumentConfig | null = null
145
+ private transport: PreviewTransport | null = null
146
+ /** Bumped whenever the transport is dropped, so a stale async continuation can tell. */
147
+ private connectionGen = 0
148
+ private mountEpochCounter = 0
149
+ private latestEpoch = 0
150
+ private sink: PreviewSink | null = null
151
+ private desired: {epoch: number; state: PreviewDesiredState} | null = null
152
+ private applied: Applied = NOTHING_APPLIED
153
+ /** Epoch whose production the host halted on a non-recoverable error; not restarted until remount. */
154
+ private haltedEpoch = -1
155
+ private handshaking: Promise<boolean> | null = null
156
+ private opChain: Promise<void> = Promise.resolve()
157
+ private reconnectTimes: number[] = []
158
+ private reconnectCooldown: (() => void) | null = null
159
+ private paused = false
160
+ private readonly creditLoop: CreditLoop
161
+ private readonly createTransport: NonNullable<PreviewConnectionDeps["createTransport"]>
162
+ private readonly now: () => number
163
+ private readonly isVisible: () => boolean
164
+ private readonly after: (ms: number, fn: () => void) => () => void
165
+ private readonly unsubscribers: Array<() => void> = []
166
+ private counters = {handshakes: 0, reconnects: 0, staleReplies: 0, staleLocalOps: 0, tierChanges: 0}
167
+
168
+ constructor(private readonly deps: PreviewConnectionDeps) {
169
+ this.createTransport = deps.createTransport ?? createPreviewTransport
170
+ this.now = deps.now ?? (() => (typeof performance !== "undefined" ? performance.now() : Date.now()))
171
+ this.isVisible = deps.isDocumentVisible ?? defaultIsVisible
172
+ this.after = deps.after ?? defaultAfter
173
+ this.state = deps.channel ? "idle" : "unavailable"
174
+ this.creditLoop = new CreditLoop({
175
+ sendAck: (gen, seq) => this.transport?.sendText(ackMessage(gen, seq)),
176
+ onParseError: (reason) =>
177
+ previewTraceWarnLimited(`parse:${reason}`, "parse_reject", {reason, docGen: this.docGen}),
178
+ })
179
+ if (deps.channel) {
180
+ this.unsubscribers.push(deps.channel.onEvent((event) => this.handleHostEvent(event)))
181
+ const listen = deps.listen ?? defaultListen
182
+ this.unsubscribers.push(listen("window", "pagehide", () => this.close("pagehide")))
183
+ // A page restored from the back/forward cache is the same document with a dead transport.
184
+ this.unsubscribers.push(
185
+ listen("window", "pageshow", () => {
186
+ if (this.state !== "closed") return
187
+ this.setState("idle", {reason: "pageshow"})
188
+ this.sync()
189
+ }),
190
+ )
191
+ this.unsubscribers.push(listen("document", "visibilitychange", () => this.handleVisibility()))
192
+ }
193
+ }
194
+
195
+ get currentState(): PreviewConnectionState {
196
+ return this.state
197
+ }
198
+
199
+ get documentGeneration(): number {
200
+ return this.docGen
201
+ }
202
+
203
+ snapshot(): PreviewConnectionCounters {
204
+ return {...this.counters, page: this.creditLoop.snapshot()}
205
+ }
206
+
207
+ /** A fresh, strictly increasing epoch for a component mounting in this document. */
208
+ nextMountEpoch(): number {
209
+ this.mountEpochCounter += 1
210
+ return this.mountEpochCounter
211
+ }
212
+
213
+ /**
214
+ * Route frames to this component's renderer. The newest mount wins; an older sink detaching
215
+ * later cannot remove a newer one.
216
+ */
217
+ attach(sink: PreviewSink): () => void {
218
+ if (sink.mountEpoch < this.latestEpoch) {
219
+ this.counters.staleLocalOps += 1
220
+ return () => {}
221
+ }
222
+ this.latestEpoch = sink.mountEpoch
223
+ this.sink = sink
224
+ this.creditLoop.setDraw((frame) => sink.draw(frame))
225
+ sink.onState(this.state, {...this.detail, paused: this.paused})
226
+ return () => {
227
+ if (this.sink !== sink) return
228
+ this.sink = null
229
+ this.creditLoop.setDraw(null)
230
+ }
231
+ }
232
+
233
+ /** Declare what `mountEpoch` wants. Operations from a superseded epoch are ignored. */
234
+ update(mountEpoch: number, state: PreviewDesiredState): void {
235
+ if (mountEpoch < this.latestEpoch) {
236
+ this.counters.staleLocalOps += 1
237
+ previewTrace("stale_local_op", {mountEpoch, latestEpoch: this.latestEpoch})
238
+ return
239
+ }
240
+ this.latestEpoch = mountEpoch
241
+ this.desired = {epoch: mountEpoch, state}
242
+ this.sync()
243
+ }
244
+
245
+ reportRendererError(mountEpoch: number, message: string): void {
246
+ this.creditLoop.recordError(message)
247
+ if (this.state !== "open" || !this.config) return
248
+ void this.send({cmd: "rendererError", mountEpoch, message}).catch(() => undefined)
249
+ }
250
+
251
+ /** End of document. The lease is untouched; a new document will handshake again. */
252
+ close(reason: string): void {
253
+ if (this.state === "closed") return
254
+ previewTrace("connection_closed", {reason, docGen: this.docGen})
255
+ this.clearReconnectCooldown()
256
+ this.dropTransport()
257
+ this.setState("closed", {reason})
258
+ }
259
+
260
+ /** Test seam: detach from the channel and document. */
261
+ dispose(): void {
262
+ for (const unsubscribe of this.unsubscribers.splice(0)) unsubscribe()
263
+ this.clearReconnectCooldown()
264
+ this.dropTransport()
265
+ }
266
+
267
+ // ---------------------------------------------------------------------------
268
+
269
+ private sync(): void {
270
+ this.opChain = this.opChain
271
+ .then(() => this.syncOnce())
272
+ .catch((error: unknown) => {
273
+ previewTraceWarn("sync_failed", {error: error instanceof Error ? error.message : String(error)})
274
+ })
275
+ }
276
+
277
+ private wantsFrames(): boolean {
278
+ const desired = this.desired
279
+ return !!desired && desired.state.running && desired.state.tier !== null && desired.epoch !== this.haltedEpoch
280
+ }
281
+
282
+ private async syncOnce(): Promise<void> {
283
+ const desired = this.desired
284
+ if (!desired) return
285
+ if (this.state !== "open") {
286
+ // Hidden components never force a handshake; the next visible one will.
287
+ if (!this.wantsFrames()) return
288
+ if (!(await this.ensureOpen())) return
289
+ }
290
+ const gen = this.connectionGen
291
+ const {epoch, state} = desired
292
+ if (state.tier && !sameTier(state.tier, this.applied.tier)) {
293
+ const reply = await this.send({
294
+ cmd: "configure",
295
+ mountEpoch: epoch,
296
+ boxWidth: state.boxWidth,
297
+ boxHeight: state.boxHeight,
298
+ })
299
+ if (gen !== this.connectionGen || !this.accept(reply, "configure")) return
300
+ this.counters.tierChanges += 1
301
+ previewTrace("tier_sent", {
302
+ mountEpoch: epoch,
303
+ width: state.tier.width,
304
+ height: state.tier.height,
305
+ docGen: this.docGen,
306
+ })
307
+ this.applied = {...this.applied, tier: state.tier}
308
+ }
309
+ const running = this.wantsFrames()
310
+ if (running !== this.applied.running || (running && epoch !== this.applied.epoch)) {
311
+ const reply = await this.send({cmd: running ? "start" : "stop", mountEpoch: epoch})
312
+ if (gen !== this.connectionGen || !this.accept(reply, running ? "start" : "stop")) return
313
+ this.applied = {...this.applied, epoch, running}
314
+ }
315
+ }
316
+
317
+ /** False when the host dropped the op as stale; our identity is then out of date. */
318
+ private accept(reply: PreviewControlReply | null, cmd: string): boolean {
319
+ if (!reply) return false
320
+ if (!reply.stale) return true
321
+ this.counters.staleReplies += 1
322
+ previewTraceWarn("control_stale", {cmd, docGen: this.docGen})
323
+ // The host no longer recognises this document's credential: start over with a handshake.
324
+ this.dropTransport()
325
+ this.setState("idle", {reason: "stale_identity"})
326
+ this.scheduleReconnect("stale_identity")
327
+ return false
328
+ }
329
+
330
+ private async send(request: Omit<PreviewControlRequest, "docGen" | "token">): Promise<PreviewControlReply | null> {
331
+ const channel = this.deps.channel
332
+ if (!channel) return null
333
+ try {
334
+ const reply = await channel.request({...request, docGen: this.docGen, token: this.config?.token})
335
+ return (reply ?? {}) as PreviewControlReply
336
+ } catch (error) {
337
+ const code = error instanceof PreviewControlError ? error.code : "transport_failed"
338
+ previewTraceWarn("control_failed", {cmd: request.cmd, code, docGen: this.docGen})
339
+ this.sink?.onError(code)
340
+ return null
341
+ }
342
+ }
343
+
344
+ private ensureOpen(): Promise<boolean> {
345
+ if (this.state === "open") return Promise.resolve(true)
346
+ if (this.state === "unsupported" || this.state === "unavailable" || this.state === "closed") {
347
+ return Promise.resolve(false)
348
+ }
349
+ if (!this.handshaking) {
350
+ this.handshaking = this.handshake().finally(() => {
351
+ this.handshaking = null
352
+ })
353
+ }
354
+ return this.handshaking
355
+ }
356
+
357
+ private async handshake(staleRetries = STALE_HANDSHAKE_RETRIES): Promise<boolean> {
358
+ const channel = this.deps.channel
359
+ if (!channel) return false
360
+ const gen = this.connectionGen
361
+ const mountEpoch = this.desired?.epoch ?? 0
362
+ this.setState("handshaking")
363
+ previewTrace("handshake_attempt", {docGen: this.docGen, mountEpoch})
364
+ let result: PreviewHandshakeResult
365
+ try {
366
+ result = (await channel.request({cmd: "handshake", docGen: this.docGen, mountEpoch})) as PreviewHandshakeResult
367
+ } catch (error) {
368
+ const code = error instanceof PreviewControlError ? error.code : "transport_failed"
369
+ const message = error instanceof Error ? error.message.slice(0, 120) : undefined
370
+ previewTraceWarn("handshake_failed", {code, message, docGen: this.docGen})
371
+ // A bind that is not ready yet is reported as unsupported. That used to
372
+ // stick for the whole document. Treat it like a transport error and try again.
373
+ this.setState("error", {code})
374
+ this.sink?.onError(code)
375
+ if (this.isVisible() && this.wantsFrames()) this.scheduleReconnect(code)
376
+ return false
377
+ }
378
+ if (gen !== this.connectionGen) return false
379
+ if (!result || typeof result !== "object") {
380
+ this.setState("error", {code: "transport_failed"})
381
+ return false
382
+ }
383
+ if ("stale" in result) {
384
+ // The docGen this page claimed (or the one minted for it mid-handshake) was superseded,
385
+ // e.g. by the `ready` that follows `handshake_without_ready`. Ask again as a page that does
386
+ // not know its document yet; the host answers with its current one.
387
+ this.counters.staleReplies += 1
388
+ previewTraceWarn("handshake_stale", {docGen: this.docGen, staleRetries})
389
+ this.docGen = 0
390
+ if (staleRetries > 0) return this.handshake(staleRetries - 1)
391
+ this.setState("error", {reason: "stale_identity"})
392
+ return false
393
+ }
394
+ if (result.t === "waiting_for_lease") {
395
+ if (typeof result.docGen === "number") this.docGen = result.docGen
396
+ previewTrace("waiting_for_lease", {docGen: this.docGen})
397
+ this.setState("waiting_for_lease")
398
+ return false
399
+ }
400
+ return this.openTransport(result)
401
+ }
402
+
403
+ private async openTransport(config: PreviewDocumentConfig): Promise<boolean> {
404
+ if (config.protocolVersion !== PREVIEW_PROTOCOL_VERSION) {
405
+ previewTraceWarn("handshake_rejected", {reason: "unsupported_version", protocolVersion: config.protocolVersion})
406
+ this.setState("unsupported", {code: "unsupported"})
407
+ this.sink?.onError("unsupported")
408
+ return false
409
+ }
410
+ this.docGen = config.docGen
411
+ this.config = config
412
+ this.counters.handshakes += 1
413
+ this.setState("connecting")
414
+ const gen = ++this.connectionGen
415
+ let transport: PreviewTransport
416
+ try {
417
+ transport = this.createTransport(config.transport, {
418
+ url: config.url,
419
+ portName: config.portName,
420
+ token: config.token,
421
+ })
422
+ transport.onBinary((buffer) => this.creditLoop.handleBinary(buffer))
423
+ transport.onError((reason) => this.handleTransportError(gen, reason))
424
+ await transport.connect()
425
+ } catch (error) {
426
+ const reason = (error as {reason?: string}).reason ?? "connect_failed"
427
+ previewTraceWarn("transport_failed", {reason, docGen: this.docGen, transport: config.transport})
428
+ if (gen === this.connectionGen) {
429
+ this.config = null
430
+ this.setState("error", {code: "transport_failed", reason})
431
+ this.sink?.onError("transport_failed")
432
+ }
433
+ return false
434
+ }
435
+ if (gen !== this.connectionGen) {
436
+ transport.close()
437
+ return false
438
+ }
439
+ this.transport = transport
440
+ this.applied = NOTHING_APPLIED
441
+ previewTrace("handshake_ok", {
442
+ docGen: this.docGen,
443
+ transport: config.transport,
444
+ handshakes: this.counters.handshakes,
445
+ })
446
+ this.setState("open")
447
+ return true
448
+ }
449
+
450
+ private handleTransportError(gen: number, reason: string): void {
451
+ if (gen !== this.connectionGen) return
452
+ previewTraceWarn("transport_closed", {reason, docGen: this.docGen})
453
+ this.dropTransport()
454
+ this.setState("error", {code: "transport_failed", reason})
455
+ this.sink?.onError("transport_failed")
456
+ // A socket the OS tore down while suspended is re-established on foreground instead.
457
+ if (this.isVisible()) this.scheduleReconnect(reason)
458
+ }
459
+
460
+ private handleHostEvent(event: PreviewHostEvent): void {
461
+ switch (event.t) {
462
+ case "lease_available":
463
+ previewTrace("lease_available", {docGen: this.docGen, state: this.state})
464
+ if (
465
+ this.state === "waiting_for_lease" ||
466
+ this.state === "idle" ||
467
+ this.state === "error" ||
468
+ this.state === "unsupported"
469
+ ) {
470
+ this.setState("idle")
471
+ // Hidden stays connected-but-stopped, so handshake as soon as anyone has mounted.
472
+ if (this.desired) void this.ensureOpen().then((open) => open && this.sync())
473
+ }
474
+ return
475
+ case "lease_ended":
476
+ previewTrace("lease_ended", {reason: event.reason, docGen: this.docGen})
477
+ this.dropTransport()
478
+ this.setState("waiting_for_lease", {reason: event.reason})
479
+ if (event.reason === "source_ended") this.sink?.onError("source_ended")
480
+ return
481
+ case "error":
482
+ if (typeof event.docGen === "number" && event.docGen !== this.docGen) return
483
+ this.handleHostError(event.code)
484
+ return
485
+ case "status":
486
+ this.sink?.onStatus({...event, page: this.snapshot()})
487
+ return
488
+ case "paused_background":
489
+ this.paused = true
490
+ this.sink?.onState(this.state, {...this.detail, paused: true})
491
+ return
492
+ case "resumed":
493
+ this.paused = false
494
+ this.sink?.onState(this.state, {...this.detail, paused: false})
495
+ return
496
+ case "config":
497
+ if (event.docGen === this.docGen && this.state !== "open" && this.state !== "connecting") {
498
+ void this.openTransport(event).then((open) => open && this.sync())
499
+ }
500
+ return
501
+ }
502
+ }
503
+
504
+ private handleHostError(code: string): void {
505
+ previewTraceWarn("host_error", {code, docGen: this.docGen})
506
+ this.sink?.onError(code)
507
+ if (code === "transport_failed" || code === "ack_timeout") {
508
+ this.dropTransport()
509
+ this.setState("error", {code})
510
+ this.scheduleReconnect(code)
511
+ return
512
+ }
513
+ // The host halted production (pack_failed, diagnostics_disabled, ...). Restarting would only
514
+ // hit the same failure; a new mount epoch may try again.
515
+ this.applied = {...this.applied, running: false}
516
+ this.haltedEpoch = this.desired?.epoch ?? this.haltedEpoch
517
+ }
518
+
519
+ private handleVisibility(): void {
520
+ const visible = this.isVisible()
521
+ previewTrace("visibility", {visible, state: this.state, docGen: this.docGen})
522
+ if (visible && (this.state === "error" || this.state === "idle")) this.sync()
523
+ }
524
+
525
+ private scheduleReconnect(reason: string): void {
526
+ const at = this.now()
527
+ this.reconnectTimes = this.reconnectTimes.filter((t) => at - t < RECONNECT_WINDOW_MS)
528
+ if (this.reconnectTimes.length >= RECONNECT_BUDGET) {
529
+ previewTraceWarn("reconnect_budget_exhausted", {reason, docGen: this.docGen})
530
+ this.armReconnectCooldown(reason)
531
+ return
532
+ }
533
+ this.clearReconnectCooldown()
534
+ this.reconnectTimes.push(at)
535
+ this.counters.reconnects += 1
536
+ previewTrace("reconnect", {reason, docGen: this.docGen, reconnects: this.counters.reconnects})
537
+ this.sync()
538
+ }
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
+
556
+ private dropTransport(): void {
557
+ this.connectionGen += 1
558
+ const transport = this.transport
559
+ this.transport = null
560
+ this.config = null
561
+ this.applied = NOTHING_APPLIED
562
+ if (transport) {
563
+ transport.close()
564
+ previewTrace("transport_close", {docGen: this.docGen})
565
+ }
566
+ }
567
+
568
+ private setState(state: PreviewConnectionState, detail: PreviewConnectionStateDetail = {}): void {
569
+ this.state = state
570
+ this.detail = detail
571
+ this.sink?.onState(state, {...detail, paused: this.paused})
572
+ }
573
+ }
574
+
575
+ let shared: PreviewConnection | null = null
576
+
577
+ /** The connection for this document, created on first use. */
578
+ export function getPreviewConnection(): PreviewConnection {
579
+ if (!shared) shared = new PreviewConnection({channel: createMentraControlChannel()})
580
+ return shared
581
+ }
582
+
583
+ /** Test seam: replace (or clear) the document singleton, as a reload would. */
584
+ export function setPreviewConnectionForTests(next: PreviewConnection | null): void {
585
+ shared?.dispose()
586
+ shared = next
587
+ }