@glassly/miniapp-cli 0.1.10-dev.0 → 0.1.11-beta.0

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.
@@ -0,0 +1,952 @@
1
+ import {
2
+ diffScene,
3
+ processScene,
4
+ resolveAnchors,
5
+ SceneStore,
6
+ TextMeasurer,
7
+ type FrameElement,
8
+ type SceneElementInput,
9
+ } from "@glassly/miniapp/display"
10
+ import type {MirrorElement, MirrorSnapshot} from "@glassly/miniapp/mirror"
11
+ import {
12
+ MiniappErrorCode,
13
+ MiniappRequestType,
14
+ MiniappResponseType,
15
+ MiniappStreamType,
16
+ } from "@glassly/miniapp/protocol"
17
+
18
+ import type {SimDevice} from "./device.js"
19
+ import type {SimStorage} from "./storage.js"
20
+
21
+ export type SimLogSource = "background" | "ui" | "host" | "bridge"
22
+
23
+ export interface SimLogEntry {
24
+ seq: number
25
+ timestamp: number
26
+ source: SimLogSource
27
+ level: string
28
+ message: string
29
+ }
30
+
31
+ export interface SimEffect {
32
+ kind: string
33
+ timestamp: number
34
+ [detail: string]: unknown
35
+ }
36
+
37
+ export type SimHostEvent =
38
+ | {type: "display"; snapshot: MirrorSnapshot}
39
+ | {type: "log"; entry: SimLogEntry}
40
+ | {type: "ui"; frame: Record<string, unknown>}
41
+ | {type: "effect"; effect: SimEffect}
42
+ | {type: "status"}
43
+ | {type: "exit"; reason: string}
44
+
45
+ export interface SimManifest {
46
+ packageName: string
47
+ name: string
48
+ version?: string
49
+ type?: string
50
+ permissions?: {type?: string}[]
51
+ }
52
+
53
+ export interface SimHostOptions {
54
+ manifest: SimManifest
55
+ device: SimDevice
56
+ storage: SimStorage
57
+ toBackground: (raw: string) => void
58
+ emit: (event: SimHostEvent) => void
59
+ frameLatencyMs?: number
60
+ speechMsPerChar?: number
61
+ }
62
+
63
+ export interface SimLocation {
64
+ lat: number
65
+ lng: number
66
+ accuracy?: number
67
+ timestamp: number
68
+ }
69
+
70
+ type View = "main" | "dashboard"
71
+
72
+ const LOG_LIMIT = 2000
73
+ const EFFECT_LIMIT = 200
74
+ const MAX_SETTLE_MS = 255 * 33
75
+
76
+ const PERMISSION_TYPE_TO_CANONICAL: Record<string, string> = {
77
+ MICROPHONE: "microphone",
78
+ CAMERA: "camera",
79
+ LOCATION: "location",
80
+ BACKGROUND_LOCATION: "location",
81
+ READ_NOTIFICATIONS: "notifications",
82
+ DISPLAY_MIRROR: "displayMirror",
83
+ POST_NOTIFICATIONS: "notifications",
84
+ CALENDAR: "calendar",
85
+ API_KEYS: "apiKeys",
86
+ MEMORY: "memory",
87
+ AI: "ai",
88
+ SPEAKERS: "speakers",
89
+ MANAGE_MINIAPPS: "manageMiniapps",
90
+ PLATFORM_SETTINGS: "platformSettings",
91
+ HOST_WIDGETS: "hostWidgets",
92
+ }
93
+
94
+ function permissionForStream(stream: string): string | null {
95
+ if (stream === MiniappStreamType.MIRROR_UPDATE) return "DISPLAY_MIRROR"
96
+ if (stream === "audio_chunk" || stream === "vad") return "MICROPHONE"
97
+ if (stream.startsWith("transcription") || stream.startsWith("translation")) return "MICROPHONE"
98
+ if (stream === "location_update" || stream === "heading_update") return "LOCATION"
99
+ if (stream === "phone_notification" || stream === "phone_notification_dismissed") return "READ_NOTIFICATIONS"
100
+ if (stream === MiniappStreamType.SETTINGS_CHANGED) return "PLATFORM_SETTINGS"
101
+ return null
102
+ }
103
+
104
+ function settleTimeOf(elements: FrameElement[]): number {
105
+ let ms = 0
106
+ for (const el of elements) {
107
+ const edge = el.transition?.exit !== undefined || (el.change === "created" && el.transition?.enter !== undefined)
108
+ if (el.change !== "updated" && el.change !== "moved" && !edge) continue
109
+ const duration = Math.min(el.transition?.durationMs ?? 0, el.rotation !== undefined ? 65535 : MAX_SETTLE_MS)
110
+ if (duration > ms) ms = duration
111
+ }
112
+ return ms
113
+ }
114
+
115
+ export function formatLogArgs(args: unknown[]): string {
116
+ return args
117
+ .map((arg) => {
118
+ if (typeof arg === "string") return arg
119
+ if (arg !== null && typeof arg === "object" && (arg as {__error?: boolean}).__error === true) {
120
+ const err = arg as {message?: string; stack?: string}
121
+ return err.stack || err.message || "Error"
122
+ }
123
+ try {
124
+ return JSON.stringify(arg)
125
+ } catch {
126
+ return String(arg)
127
+ }
128
+ })
129
+ .join(" ")
130
+ }
131
+
132
+ interface StreamRoute {
133
+ forceLocal: boolean
134
+ includeCloud: boolean
135
+ }
136
+
137
+ /**
138
+ * The phone side of one miniapp, mirroring the Glassly App's runtime for the
139
+ * requests it covers. No I/O of its own; the server and the tests drive it.
140
+ */
141
+ export class SimHost {
142
+ private readonly manifest: SimManifest
143
+ private readonly device: SimDevice
144
+ private readonly storage: SimStorage
145
+ private readonly toBackground: (raw: string) => void
146
+ private readonly emit: (event: SimHostEvent) => void
147
+ private readonly frameLatencyMs: number
148
+ private readonly speechMsPerChar: number
149
+ private readonly declared: Set<string>
150
+ private readonly measurer: TextMeasurer
151
+
152
+ private scenes = new SceneStore()
153
+ private handshook = false
154
+ private background: "stopped" | "running" | "crashed" = "stopped"
155
+ private subscriptions = new Map<string, StreamRoute>()
156
+ private claimedGestures: string[] = []
157
+ private overlay = false
158
+ private revision = 0
159
+ private frameSeq = 0
160
+ private expiry: Partial<Record<View, ReturnType<typeof setTimeout>>> = {}
161
+ private lastDropped = ""
162
+ private settlesAt = 0
163
+
164
+ private readonly uiClients = new Set<string>()
165
+ private readonly uiRequests = new Map<string, (reply: unknown) => void>()
166
+ private uiRequestSeq = 0
167
+
168
+ private logSeq = 0
169
+ private readonly logEntries: SimLogEntry[] = []
170
+ private readonly effects: SimEffect[] = []
171
+ private readonly unsimulated = new Set<string>()
172
+
173
+ private speakerState = "idle"
174
+ private speech: {timer: ReturnType<typeof setTimeout>; finish: (completed: boolean) => void} | null = null
175
+
176
+ private glassesConnected = true
177
+ private glassesBattery = {level: 80, charging: false}
178
+ private phoneBattery = {level: 90, charging: false}
179
+ private location: SimLocation = {lat: 37.7749, lng: -122.4194, accuracy: 5, timestamp: Date.now()}
180
+ private visibility: "foreground" | "background" = "foreground"
181
+ private colorScheme: "light" | "dark" = "dark"
182
+ private notificationSeq = 0
183
+
184
+ constructor(options: SimHostOptions) {
185
+ this.manifest = options.manifest
186
+ this.device = options.device
187
+ this.storage = options.storage
188
+ this.toBackground = options.toBackground
189
+ this.emit = options.emit
190
+ this.frameLatencyMs = options.frameLatencyMs ?? 30
191
+ this.speechMsPerChar = options.speechMsPerChar ?? 55
192
+ this.declared = new Set((options.manifest.permissions ?? []).map((p) => String(p.type ?? "").toUpperCase()))
193
+ this.measurer = new TextMeasurer(options.device.profile)
194
+ }
195
+
196
+ backgroundStarted(): void {
197
+ this.resetSession()
198
+ this.background = "running"
199
+ this.emit({type: "status"})
200
+ }
201
+
202
+ backgroundStopped(crashed: boolean): void {
203
+ this.resetSession()
204
+ this.background = crashed ? "crashed" : "stopped"
205
+ this.emit({type: "status"})
206
+ }
207
+
208
+ private resetSession(): void {
209
+ this.handshook = false
210
+ this.subscriptions.clear()
211
+ this.claimedGestures = []
212
+ this.overlay = false
213
+ this.scenes = new SceneStore()
214
+ for (const view of ["main", "dashboard"] as View[]) this.clearExpiry(view)
215
+ this.finishSpeech(false)
216
+ this.speakerState = "idle"
217
+ this.lastDropped = ""
218
+ for (const settle of [...this.uiRequests.values()]) settle({ok: false, error: {message: "background restarted"}})
219
+ this.uiRequests.clear()
220
+ this.uiClients.delete("cli")
221
+ this.publishDisplay()
222
+ }
223
+
224
+ fromBackground(raw: string): void {
225
+ let envelope: {payload?: Record<string, unknown>; requestId?: string}
226
+ try {
227
+ envelope = JSON.parse(raw)
228
+ } catch {
229
+ return
230
+ }
231
+ const payload = envelope.payload
232
+ if (!payload || typeof payload !== "object" || typeof payload.type !== "string") return
233
+ const requestId = typeof envelope.requestId === "string" ? envelope.requestId : undefined
234
+ try {
235
+ this.dispatch(payload.type, payload, requestId)
236
+ } catch (err) {
237
+ this.result(requestId, false, undefined, {
238
+ code: MiniappErrorCode.INTERNAL,
239
+ message: err instanceof Error ? err.message : String(err),
240
+ })
241
+ }
242
+ }
243
+
244
+ private dispatch(type: string, payload: Record<string, unknown>, requestId?: string): void {
245
+ switch (type) {
246
+ case MiniappRequestType.CONNECT:
247
+ return this.handleConnect(requestId)
248
+ case MiniappRequestType.SUBSCRIBE:
249
+ return this.handleSubscribe(payload, requestId)
250
+ case MiniappRequestType.CLAIM_GESTURES:
251
+ this.claimedGestures = Array.isArray(payload.gestures)
252
+ ? payload.gestures.filter((g): g is string => typeof g === "string")
253
+ : []
254
+ this.emit({type: "status"})
255
+ return this.result(requestId, true)
256
+ case MiniappRequestType.TEXT_FIELD:
257
+ return this.result(requestId, true)
258
+ case MiniappRequestType.RENDER:
259
+ return this.handleRender(payload, requestId)
260
+ case MiniappRequestType.SHOW_VIEW:
261
+ return this.handleShowView(payload, requestId)
262
+ case MiniappRequestType.MIRROR_GET:
263
+ if (!this.requirePermission(requestId, "DISPLAY_MIRROR", "to read the display mirror")) return
264
+ return this.result(requestId, true, this.snapshot())
265
+ case MiniappRequestType.PING:
266
+ return this.send({type: MiniappResponseType.PONG}, requestId)
267
+ case MiniappResponseType.PONG:
268
+ case MiniappRequestType.TRANSCRIPTION_CONFIG:
269
+ return
270
+ case MiniappRequestType.AUTH_REFRESH:
271
+ return this.result(requestId, false, undefined, {
272
+ code: MiniappErrorCode.NOT_CONNECTED,
273
+ message: "Miniapp auth is not configured in the simulator",
274
+ })
275
+
276
+ case MiniappRequestType.STORAGE_GET:
277
+ return this.result(requestId, true, {key: payload.key, value: this.storage.get(this.key(payload))})
278
+ case MiniappRequestType.STORAGE_SET:
279
+ this.storage.set(this.key(payload), payload.value == null ? null : String(payload.value))
280
+ return this.result(requestId, true)
281
+ case MiniappRequestType.STORAGE_DELETE:
282
+ this.storage.delete(this.key(payload))
283
+ return this.result(requestId, true)
284
+ case MiniappRequestType.STORAGE_LIST:
285
+ return this.result(requestId, true, {keys: this.storage.keys()})
286
+ case MiniappRequestType.STORAGE_CLEAR:
287
+ this.storage.clear()
288
+ return this.result(requestId, true)
289
+ case MiniappRequestType.STORAGE_HAS:
290
+ return this.result(requestId, true, {has: this.storage.get(this.key(payload)) !== null})
291
+ case MiniappRequestType.STORAGE_GET_ALL:
292
+ return this.result(requestId, true, {values: this.storage.getAll()})
293
+ case MiniappRequestType.STORAGE_SET_MULTIPLE: {
294
+ const values = payload.values
295
+ if (!values || typeof values !== "object") throw new Error("storage_set_multiple requires a values object")
296
+ for (const [key, value] of Object.entries(values)) this.storage.set(key, value == null ? null : String(value))
297
+ return this.result(requestId, true)
298
+ }
299
+ case MiniappRequestType.STORAGE_FLUSH:
300
+ return this.result(requestId, true)
301
+
302
+ case MiniappRequestType.LOCATION_POLL:
303
+ if (!this.requirePermission(requestId, "LOCATION", "to read the location")) return
304
+ return this.result(requestId, true, this.location)
305
+
306
+ case MiniappRequestType.SPEAK:
307
+ return this.handleSpeak(String(payload.text ?? ""), requestId)
308
+ case MiniappRequestType.PLAY_AUDIO:
309
+ this.effect("audio", {url: payload.audioUrl})
310
+ return this.startSpeech(1500, requestId, undefined)
311
+ case MiniappRequestType.STOP_AUDIO:
312
+ this.effect("stop_audio", {})
313
+ return this.finishSpeech(false)
314
+
315
+ case MiniappRequestType.RGB_LED:
316
+ this.effect("led", {...payload, type: undefined})
317
+ return this.result(requestId, true)
318
+ case MiniappRequestType.OPEN_URL:
319
+ this.effect("open_url", {url: payload.url})
320
+ return this.result(requestId, true)
321
+ case MiniappRequestType.COPY_CLIPBOARD:
322
+ this.effect("clipboard", {text: payload.text})
323
+ return this.result(requestId, true)
324
+ case MiniappRequestType.SHARE:
325
+ this.effect("share", {...payload, type: undefined})
326
+ return this.result(requestId, true, {success: true})
327
+ case MiniappRequestType.DOWNLOAD:
328
+ this.effect("download", {...payload, type: undefined})
329
+ return this.result(requestId, true, {success: true})
330
+
331
+ case MiniappRequestType.NOTIFICATION_POST: {
332
+ if (!this.requirePermission(requestId, "POST_NOTIFICATIONS", "to post a notification")) return
333
+ const id = typeof payload.id === "string" && payload.id ? payload.id : `sim-${++this.notificationSeq}`
334
+ this.effect("notification", {id, title: payload.title, content: payload.content})
335
+ return this.result(requestId, true, {id})
336
+ }
337
+ case MiniappRequestType.NOTIFICATION_DISMISS:
338
+ if (!this.requirePermission(requestId, "POST_NOTIFICATIONS", "to dismiss a notification")) return
339
+ this.effect("notification_dismiss", {id: payload.id})
340
+ return this.result(requestId, true)
341
+
342
+ case MiniappRequestType.SYSTEM_EXIT:
343
+ case MiniappRequestType.MINIAPPS_STOP_SELF:
344
+ this.result(requestId, true)
345
+ this.log("host", "info", "The miniapp asked to stop (session.system.exit)")
346
+ return this.emit({type: "exit", reason: "the miniapp called exit"})
347
+
348
+ case "UI_SEND":
349
+ return this.handleUiSend(payload)
350
+ case "UI_CANCEL":
351
+ return this.emit({type: "ui", frame: {type: "cancel", requestId: payload.requestId}})
352
+ }
353
+
354
+ if (!this.unsimulated.has(type)) {
355
+ this.unsimulated.add(type)
356
+ this.log("host", "warn", `"${type}" is not simulated; the request was answered with NOT_IMPLEMENTED`)
357
+ this.emit({type: "status"})
358
+ }
359
+ this.result(requestId, false, undefined, {
360
+ code: MiniappErrorCode.NOT_IMPLEMENTED,
361
+ message: `"${type}" is not simulated by glassly sim. Test it on a phone with glassly dev.`,
362
+ })
363
+ }
364
+
365
+ private key(payload: Record<string, unknown>): string {
366
+ if (typeof payload.key !== "string" || !payload.key) throw new Error("storage request requires a key")
367
+ return payload.key
368
+ }
369
+
370
+ private handleConnect(requestId?: string): void {
371
+ const permissions: Record<string, boolean> = {}
372
+ for (const canonical of new Set(Object.values(PERMISSION_TYPE_TO_CANONICAL))) permissions[canonical] = false
373
+ for (const type of this.declared) {
374
+ const canonical = PERMISSION_TYPE_TO_CANONICAL[type]
375
+ if (canonical) permissions[canonical] = true
376
+ }
377
+ this.handshook = true
378
+ this.send(
379
+ {
380
+ type: MiniappResponseType.CONNECT_ACK,
381
+ userId: "sim-user",
382
+ packageName: this.manifest.packageName,
383
+ capabilities: this.capabilities(),
384
+ preferences: {unitSystem: "metric", twelveHourTime: false},
385
+ visibility: this.visibility,
386
+ colorScheme: this.colorScheme,
387
+ paused: !this.glassesConnected,
388
+ ...(this.glassesConnected ? {} : {pauseReason: "glasses_disconnected"}),
389
+ permissions,
390
+ launchSource: "phone",
391
+ },
392
+ requestId,
393
+ )
394
+ this.log("host", "info", `${this.manifest.packageName} connected`)
395
+ if (this.uiClients.size > 0) this.toUi({type: "UI_OPEN"})
396
+ this.emit({type: "status"})
397
+ }
398
+
399
+ private capabilities(): Record<string, unknown> {
400
+ const display = this.device.capabilities.display as Record<string, unknown>
401
+ const views = this.manifest.type === "dashboard" ? ["main", "dashboard"] : ["main"]
402
+ return {...this.device.capabilities, display: {...display, views}}
403
+ }
404
+
405
+ private handleSubscribe(payload: Record<string, unknown>, requestId?: string): void {
406
+ const raw = (payload.subscriptions ?? payload.streams) as unknown
407
+ if (!Array.isArray(raw)) {
408
+ return this.result(requestId, false, undefined, {
409
+ code: MiniappErrorCode.INTERNAL,
410
+ message: "subscribe requires a subscriptions array",
411
+ })
412
+ }
413
+ const next = new Map<string, StreamRoute>()
414
+ for (const entry of raw) {
415
+ if (typeof entry === "string") {
416
+ next.set(entry, {forceLocal: false, includeCloud: true})
417
+ } else if (entry && typeof entry === "object" && typeof entry.stream === "string") {
418
+ const stream = entry.stream === "location_stream" ? "location_update" : entry.stream
419
+ const forceLocal = entry.forceLocal === true
420
+ next.set(stream, {forceLocal, includeCloud: !forceLocal || entry.includeCloud === true})
421
+ }
422
+ }
423
+ for (const stream of next.keys()) {
424
+ const required = permissionForStream(stream)
425
+ if (!required || this.declared.has(required)) continue
426
+ const error = {
427
+ code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
428
+ message: `${required} permission not declared in miniapp.json (required for "${stream}"). Add {"type": "${required}"} to the "permissions" array.`,
429
+ permission: required,
430
+ subscription: stream,
431
+ }
432
+ this.log("host", "error", error.message)
433
+ if (requestId) this.result(requestId, false, undefined, error)
434
+ else this.send({type: MiniappResponseType.ERROR, ...error})
435
+ return
436
+ }
437
+ this.subscriptions = next
438
+ this.result(requestId, true)
439
+ this.emit({type: "status"})
440
+ for (const stream of next.keys()) this.sendInitialSnapshot(stream)
441
+ }
442
+
443
+ private sendInitialSnapshot(stream: string): void {
444
+ if (stream === "glasses_battery") this.push(stream, {...this.glassesBattery, timestamp: Date.now()})
445
+ else if (stream === "phone_battery") this.push(stream, {...this.phoneBattery, timestamp: Date.now()})
446
+ else if (stream === "glasses_connection") this.push(stream, this.connectionData())
447
+ else if (stream === "glasses_wifi") this.push(stream, {connected: false})
448
+ else if (stream === MiniappStreamType.MIRROR_UPDATE) this.push(stream, this.snapshot())
449
+ }
450
+
451
+ private connectionData(): Record<string, unknown> {
452
+ return {
453
+ connected: this.glassesConnected,
454
+ modelName: this.device.capabilities.modelName,
455
+ deviceModel: this.device.capabilities.modelName,
456
+ batteryLevel: this.glassesBattery.level,
457
+ charging: this.glassesBattery.charging,
458
+ }
459
+ }
460
+
461
+ private requirePermission(requestId: string | undefined, permission: string, purpose: string): boolean {
462
+ if (this.declared.has(permission)) return true
463
+ const message = `${permission} permission not declared in miniapp.json (required ${purpose}). Add {"type": "${permission}"} to the "permissions" array.`
464
+ this.log("host", "error", message)
465
+ this.result(requestId, false, undefined, {code: MiniappErrorCode.PERMISSION_NOT_DECLARED, message, permission})
466
+ return false
467
+ }
468
+
469
+ private handleRender(payload: Record<string, unknown>, requestId?: string): void {
470
+ if (!Array.isArray(payload.elements)) {
471
+ return this.result(requestId, false, undefined, {
472
+ code: MiniappErrorCode.INTERNAL,
473
+ message: "render request missing elements array",
474
+ })
475
+ }
476
+ const view: View = payload.view === "dashboard" ? "dashboard" : "main"
477
+ if (view === "dashboard" && this.manifest.type !== "dashboard") {
478
+ return this.result(requestId, true, {
479
+ status: "displayed",
480
+ presented: false,
481
+ reason: "not the active dashboard",
482
+ })
483
+ }
484
+ const caps = this.device.scene
485
+ const appId = this.manifest.packageName
486
+ const input = resolveAnchors(payload.elements as SceneElementInput[], caps.width, caps.height)
487
+ const processed = processScene(input, caps, this.device.profile)
488
+ const {elements} = diffScene(
489
+ this.scenes.lastFrame(appId, view),
490
+ processed.elements,
491
+ this.scenes.nextSyntheticId(appId, view),
492
+ )
493
+ this.scenes.commit(appId, view, elements, {width: caps.width, height: caps.height})
494
+ this.frameSeq++
495
+
496
+ this.clearExpiry(view)
497
+ const durationMs = Number(payload.durationMs)
498
+ if (durationMs > 0 && elements.length > 0) {
499
+ this.expiry[view] = setTimeout(() => {
500
+ this.scenes.commit(appId, view, [])
501
+ if (this.visibleView() === view) this.publishDisplay()
502
+ }, durationMs)
503
+ }
504
+
505
+ const dropped = processed.dropped.join(", ")
506
+ if (dropped !== this.lastDropped) {
507
+ this.lastDropped = dropped
508
+ if (dropped) this.log("host", "warn", `render() dropped elements: ${dropped}`)
509
+ }
510
+
511
+ const base = {status: "displayed", degraded: processed.degraded, dropped: processed.dropped}
512
+ if (this.visibleView() !== view) {
513
+ return this.result(requestId, true, {
514
+ ...base,
515
+ presented: false,
516
+ reason: view === "main" ? "dashboard active" : "dashboard view not showing",
517
+ })
518
+ }
519
+ this.publishDisplay()
520
+ const settleMs = caps.animation ? settleTimeOf(elements) : 0
521
+ this.settlesAt = Date.now() + settleMs
522
+ if (!requestId) return
523
+ setTimeout(() => this.result(requestId, true, {...base, presented: true}), this.frameLatencyMs + settleMs)
524
+ }
525
+
526
+ private handleShowView(payload: Record<string, unknown>, requestId?: string): void {
527
+ const view = payload.view
528
+ if (view !== "main" && view !== "dashboard") {
529
+ return this.result(requestId, false, undefined, {
530
+ code: MiniappErrorCode.INVALID_ARGUMENT,
531
+ message: 'showView takes "main" or "dashboard"',
532
+ })
533
+ }
534
+ if (this.manifest.type !== "dashboard") {
535
+ return this.result(requestId, false, undefined, {
536
+ code: MiniappErrorCode.NOT_PERMITTED,
537
+ message: 'The dashboard view belongs to miniapps of type "dashboard"',
538
+ })
539
+ }
540
+ const overlay = view === "dashboard"
541
+ if (overlay !== this.overlay) {
542
+ this.overlay = overlay
543
+ this.publishDisplay()
544
+ this.push(MiniappStreamType.DISPLAY_VIEW, {kind: "change", view, reason: overlay ? "shown" : "hidden"})
545
+ this.emit({type: "status"})
546
+ }
547
+ this.result(requestId, true, {status: "shown"})
548
+ }
549
+
550
+ private clearExpiry(view: View): void {
551
+ const timer = this.expiry[view]
552
+ if (timer) clearTimeout(timer)
553
+ delete this.expiry[view]
554
+ }
555
+
556
+ private visibleView(): View {
557
+ return this.overlay ? "dashboard" : "main"
558
+ }
559
+
560
+ snapshot(): MirrorSnapshot {
561
+ const caps = this.device.scene
562
+ const view = this.visibleView()
563
+ const appId = this.manifest.packageName
564
+ const glyphWidths: Record<string, number> = {}
565
+ const elements: MirrorElement[] = this.scenes.lastFrame(appId, view).map((el) => {
566
+ const {path: _path, contentHash: _hash, ...rest} = el
567
+ if (el.type === "text") for (const char of el.text ?? "") glyphWidths[char] = this.measurer.measureChar(char)
568
+ return rest as MirrorElement
569
+ })
570
+ return {
571
+ revision: this.revision,
572
+ updatedAt: Date.now(),
573
+ connected: this.glassesConnected,
574
+ model: this.device.capabilities.modelName,
575
+ canvas: {width: caps.width, height: caps.height},
576
+ view,
577
+ appId: elements.length ? appId : null,
578
+ content: elements.length
579
+ ? {kind: "scene", elements, epoch: this.scenes.currentEpoch(appId, view)}
580
+ : {kind: "empty"},
581
+ glyphWidths,
582
+ }
583
+ }
584
+
585
+ displaySettlesAt(): number {
586
+ return this.settlesAt
587
+ }
588
+
589
+ private publishDisplay(): void {
590
+ this.revision++
591
+ const snapshot = this.snapshot()
592
+ this.emit({type: "display", snapshot})
593
+ this.push(MiniappStreamType.MIRROR_UPDATE, snapshot)
594
+ }
595
+
596
+ private handleSpeak(text: string, requestId?: string): void {
597
+ this.effect("speak", {text})
598
+ const durationMs = Math.max(400, Math.min(15_000, text.length * this.speechMsPerChar))
599
+ this.startSpeech(durationMs, requestId, {completed: true})
600
+ }
601
+
602
+ private startSpeech(durationMs: number, requestId: string | undefined, done: unknown): void {
603
+ this.finishSpeech(false)
604
+ this.setSpeakerState("playing")
605
+ const finish = (completed: boolean) => {
606
+ this.setSpeakerState("stopped", completed ? {durationMs} : undefined)
607
+ this.result(requestId, true, done === undefined ? undefined : {completed})
608
+ }
609
+ this.speech = {timer: setTimeout(() => this.finishSpeech(true), durationMs), finish}
610
+ }
611
+
612
+ private finishSpeech(completed: boolean): void {
613
+ const speech = this.speech
614
+ if (!speech) return
615
+ this.speech = null
616
+ clearTimeout(speech.timer)
617
+ speech.finish(completed)
618
+ }
619
+
620
+ private setSpeakerState(state: string, extra?: Record<string, unknown>): void {
621
+ if (this.speakerState === state) return
622
+ this.speakerState = state
623
+ this.send({type: MiniappResponseType.SPEAKER_STATE, state, ...extra})
624
+ this.emit({type: "status"})
625
+ }
626
+
627
+ fromUi(clientId: string, raw: string): void {
628
+ let env: Record<string, unknown>
629
+ try {
630
+ env = JSON.parse(raw)
631
+ } catch {
632
+ return
633
+ }
634
+ const tapped = env.payload as Record<string, unknown> | undefined
635
+ if (tapped && tapped.type === "dev_log") {
636
+ const args = Array.isArray(tapped.args) ? tapped.args : []
637
+ this.log("ui", typeof tapped.level === "string" ? tapped.level : "log", formatLogArgs(args))
638
+ return
639
+ }
640
+ if (env.type === "ready") {
641
+ this.uiClients.add(clientId)
642
+ this.toUi({type: "UI_OPEN"})
643
+ this.emit({type: "status"})
644
+ } else if (env.type === "msg" && typeof env.channel === "string") {
645
+ this.log("bridge", "debug", `ui → background ${env.channel} ${formatLogArgs([env.payload])}`)
646
+ this.toUi({
647
+ type: "UI_MESSAGE",
648
+ channel: env.channel,
649
+ payload: env.payload,
650
+ seq: env.seq,
651
+ ...(typeof env.requestId === "string" ? {requestId: env.requestId} : {}),
652
+ })
653
+ } else if (env.type === "cancel" && typeof env.requestId === "string") {
654
+ this.toUi({type: "UI_CANCEL", requestId: env.requestId})
655
+ }
656
+ }
657
+
658
+ uiClosed(clientId: string): void {
659
+ if (!this.uiClients.delete(clientId)) return
660
+ if (this.uiClients.size === 0) this.toUi({type: "UI_CLOSE"})
661
+ this.emit({type: "status"})
662
+ }
663
+
664
+ uiSend(channel: string, payload: unknown): void {
665
+ this.openCliUi()
666
+ this.fromUi("cli", JSON.stringify({type: "msg", channel, payload, seq: 0}))
667
+ }
668
+
669
+ uiRequest(channel: string, payload: unknown, timeoutMs = 10_000): Promise<unknown> {
670
+ this.openCliUi()
671
+ const requestId = `sim-${++this.uiRequestSeq}`
672
+ return new Promise((resolve, reject) => {
673
+ const timer = setTimeout(() => {
674
+ this.uiRequests.delete(requestId)
675
+ this.toUi({type: "UI_CANCEL", requestId})
676
+ reject(new Error(`No reply on "${channel}" within ${timeoutMs} ms`))
677
+ }, timeoutMs)
678
+ this.uiRequests.set(requestId, (reply) => {
679
+ clearTimeout(timer)
680
+ this.uiRequests.delete(requestId)
681
+ const r = reply as {ok?: boolean; result?: unknown; error?: {message?: string}} | null
682
+ if (r?.ok === true) resolve(r.result)
683
+ else reject(new Error(r?.error?.message ?? "RPC failed"))
684
+ })
685
+ this.fromUi("cli", JSON.stringify({type: "msg", channel, payload, seq: 0, requestId}))
686
+ })
687
+ }
688
+
689
+ /** The CLI stands in for a UI page: replies only flow while the background sees one open. */
690
+ private openCliUi(): void {
691
+ if (!this.uiClients.has("cli")) this.fromUi("cli", JSON.stringify({type: "ready"}))
692
+ }
693
+
694
+ private handleUiSend(payload: Record<string, unknown>): void {
695
+ const requestId = typeof payload.requestId === "string" ? payload.requestId : undefined
696
+ if (requestId && this.uiRequests.has(requestId)) {
697
+ this.uiRequests.get(requestId)?.(payload.payload)
698
+ return
699
+ }
700
+ if (!requestId) {
701
+ this.log("bridge", "debug", `background → ui ${String(payload.channel)} ${formatLogArgs([payload.payload])}`)
702
+ }
703
+ this.emit({
704
+ type: "ui",
705
+ frame: {
706
+ type: "msg",
707
+ seq: payload.seq ?? 0,
708
+ channel: payload.channel,
709
+ payload: payload.payload,
710
+ ...(requestId ? {requestId} : {}),
711
+ },
712
+ })
713
+ }
714
+
715
+ private toUi(data: Record<string, unknown>): void {
716
+ this.send({type: MiniappResponseType.EVENT, streamType: "_ui", data})
717
+ }
718
+
719
+ touch(gesture: string, extra: Record<string, unknown> = {}): void {
720
+ const data = {...extra, kind: gesture, gestureName: gesture, timestamp: Date.now()}
721
+ this.inject([MiniappStreamType.TOUCH_EVENT, `${MiniappStreamType.TOUCH_EVENT}:${gesture}`], data)
722
+ }
723
+
724
+ button(pressType: "short" | "long" = "short", buttonId = "main"): void {
725
+ this.inject([MiniappStreamType.BUTTON_PRESS], {buttonId, pressType, timestamp: Date.now()})
726
+ }
727
+
728
+ transcription(text: string, options: {isFinal?: boolean; language?: string; speakerId?: string} = {}): void {
729
+ const language = options.language ?? "en-US"
730
+ const base = language.split("-")[0].toLowerCase()
731
+ const data = {
732
+ text,
733
+ isFinal: options.isFinal ?? true,
734
+ language,
735
+ detectedLanguage: language,
736
+ transcribeLanguage: language,
737
+ ...(options.speakerId ? {speakerId: options.speakerId} : {}),
738
+ timestamp: Date.now(),
739
+ }
740
+ const streams = [...this.subscriptions.keys()].filter((stream) => stream.startsWith("transcription:"))
741
+ const explicit = streams.find(
742
+ (stream) => stream !== "transcription:auto" && stream.slice(14).split("-")[0].toLowerCase() === base,
743
+ )
744
+ const target = explicit ?? (streams.includes("transcription:auto") ? "transcription:auto" : null)
745
+ if (!target) return this.undelivered(`transcription:${language}`)
746
+ this.pushRouted(explicit ?? `transcription:${language}`, data, this.subscriptions.get(target))
747
+ }
748
+
749
+ translation(
750
+ text: string,
751
+ options: {source?: string; target?: string; isFinal?: boolean; originalText?: string} = {},
752
+ ): void {
753
+ const source = options.source ?? "en-US"
754
+ const target = options.target ?? "es-ES"
755
+ const patterns = [
756
+ `translation:${source}:${target}`,
757
+ "translation:auto",
758
+ "translation:*:*",
759
+ `translation:*:${target}`,
760
+ `translation:${source}:*`,
761
+ ]
762
+ const match = patterns.find((pattern) => this.subscriptions.has(pattern))
763
+ if (!match) return this.undelivered(patterns[0])
764
+ this.pushRouted(
765
+ patterns[0],
766
+ {
767
+ text,
768
+ isFinal: options.isFinal ?? true,
769
+ sourceLanguage: source,
770
+ targetLanguage: target,
771
+ ...(options.originalText ? {originalText: options.originalText} : {}),
772
+ timestamp: Date.now(),
773
+ },
774
+ this.subscriptions.get(match),
775
+ )
776
+ }
777
+
778
+ setLocation(lat: number, lng: number, accuracy = 5): void {
779
+ this.location = {lat, lng, accuracy, timestamp: Date.now()}
780
+ this.push(MiniappStreamType.LOCATION_UPDATE, this.location)
781
+ this.emit({type: "status"})
782
+ }
783
+
784
+ setHeading(degrees: number): void {
785
+ this.inject([MiniappStreamType.HEADING_UPDATE], {degrees})
786
+ }
787
+
788
+ setBattery(target: "glasses" | "phone", level: number, charging = false): void {
789
+ const battery = {level: Math.max(0, Math.min(100, Math.round(level))), charging}
790
+ if (target === "glasses") this.glassesBattery = battery
791
+ else this.phoneBattery = battery
792
+ this.push(target === "glasses" ? "glasses_battery" : "phone_battery", {...battery, timestamp: Date.now()})
793
+ this.emit({type: "status"})
794
+ }
795
+
796
+ /** The pause lands after the disconnect event and lifts before the reconnect event, as on a phone. */
797
+ setGlassesConnected(connected: boolean): void {
798
+ if (connected === this.glassesConnected) return
799
+ this.glassesConnected = connected
800
+ if (connected) {
801
+ this.send({type: MiniappResponseType.PAUSE_CHANGE, paused: false})
802
+ this.push("glasses_connection", this.connectionData())
803
+ } else {
804
+ this.push("glasses_connection", this.connectionData(), true)
805
+ this.send({type: MiniappResponseType.PAUSE_CHANGE, paused: true, reason: "glasses_disconnected"})
806
+ }
807
+ this.publishDisplay()
808
+ this.emit({type: "status"})
809
+ }
810
+
811
+ notification(input: {app?: string; title?: string; content?: string; packageName?: string}): string {
812
+ const notificationId = `sim-${++this.notificationSeq}`
813
+ this.inject([MiniappStreamType.PHONE_NOTIFICATION], {
814
+ notificationId,
815
+ app: input.app ?? "Messages",
816
+ title: input.title ?? "",
817
+ content: input.content ?? "",
818
+ priority: "",
819
+ timestamp: Date.now(),
820
+ packageName: input.packageName ?? "com.example.messages",
821
+ system: false,
822
+ })
823
+ return notificationId
824
+ }
825
+
826
+ setVisibility(visibility: "foreground" | "background"): void {
827
+ this.visibility = visibility
828
+ this.send({type: MiniappResponseType.VISIBILITY_CHANGE, visibility})
829
+ this.emit({type: "status"})
830
+ }
831
+
832
+ setColorScheme(colorScheme: "light" | "dark"): void {
833
+ this.colorScheme = colorScheme
834
+ this.send({type: MiniappResponseType.COLOR_SCHEME_CHANGE, colorScheme})
835
+ this.emit({type: "status"})
836
+ }
837
+
838
+ event(stream: string, data: unknown): void {
839
+ this.inject([stream], data)
840
+ }
841
+
842
+ private inject(streams: string[], data: unknown): void {
843
+ if (!streams.some((stream) => this.subscriptions.has(stream))) return this.undelivered(streams[0])
844
+ if (!this.glassesConnected) {
845
+ return this.log("host", "warn", `The miniapp is paused (glasses disconnected); "${streams[0]}" was not delivered`)
846
+ }
847
+ for (const stream of streams) this.push(stream, data)
848
+ }
849
+
850
+ private undelivered(stream: string): void {
851
+ this.log("host", "warn", `Nothing is subscribed to "${stream}"; the event was not delivered`)
852
+ }
853
+
854
+ private pushRouted(stream: string, data: unknown, route?: StreamRoute): void {
855
+ if (!this.deliverable()) return
856
+ const routes = [
857
+ ...(!route || route.includeCloud ? ["default"] : []),
858
+ ...(route?.forceLocal ? ["forceLocal"] : []),
859
+ ]
860
+ for (const transcriptionRoute of routes) {
861
+ this.send({type: MiniappResponseType.EVENT, streamType: stream, data, transcriptionRoute})
862
+ }
863
+ }
864
+
865
+ private push(stream: string, data: unknown, whilePaused = false): void {
866
+ if (!this.deliverable(whilePaused) || !this.subscriptions.has(stream)) return
867
+ this.send({type: MiniappResponseType.EVENT, streamType: stream, data})
868
+ }
869
+
870
+ /** Paused miniapps (glasses disconnected) hear no streams; the disconnect itself still lands. */
871
+ private deliverable(whilePaused = false): boolean {
872
+ return this.handshook && this.background === "running" && (this.glassesConnected || whilePaused)
873
+ }
874
+
875
+ private send(payload: Record<string, unknown>, requestId?: string): void {
876
+ if (this.background !== "running") return
877
+ this.toBackground(JSON.stringify(requestId ? {payload, requestId} : {payload}))
878
+ }
879
+
880
+ private result(requestId: string | undefined, ok: boolean, data?: unknown, error?: Record<string, unknown>): void {
881
+ if (!requestId) return
882
+ this.send(
883
+ {
884
+ type: MiniappResponseType.REQUEST_RESULT,
885
+ requestId,
886
+ ok,
887
+ ...(data !== undefined ? {data} : {}),
888
+ ...(error ? {error} : {}),
889
+ },
890
+ requestId,
891
+ )
892
+ }
893
+
894
+ private effect(kind: string, detail: Record<string, unknown>): void {
895
+ const effect: SimEffect = {kind, timestamp: Date.now(), ...detail}
896
+ delete effect.type
897
+ this.effects.push(effect)
898
+ if (this.effects.length > EFFECT_LIMIT) this.effects.shift()
899
+ const {timestamp: _t, kind: _k, ...rest} = effect
900
+ this.log("host", "info", `${kind} ${formatLogArgs([rest])}`)
901
+ this.emit({type: "effect", effect})
902
+ }
903
+
904
+ log(source: SimLogSource, level: string, message: string): void {
905
+ const entry: SimLogEntry = {seq: ++this.logSeq, timestamp: Date.now(), source, level, message}
906
+ this.logEntries.push(entry)
907
+ if (this.logEntries.length > LOG_LIMIT) this.logEntries.shift()
908
+ this.emit({type: "log", entry})
909
+ }
910
+
911
+ logs(sinceSeq = 0): SimLogEntry[] {
912
+ return this.logEntries.filter((entry) => entry.seq > sinceSeq)
913
+ }
914
+
915
+ recentEffects(): SimEffect[] {
916
+ return [...this.effects]
917
+ }
918
+
919
+ status(): Record<string, unknown> {
920
+ const snapshot = this.snapshot()
921
+ return {
922
+ packageName: this.manifest.packageName,
923
+ name: this.manifest.name,
924
+ version: this.manifest.version,
925
+ device: {id: this.device.id, model: this.device.capabilities.modelName, canvas: snapshot.canvas},
926
+ background: this.background,
927
+ connected: this.handshook,
928
+ paused: !this.glassesConnected,
929
+ subscriptions: [...this.subscriptions.keys()],
930
+ claimedGestures: this.claimedGestures,
931
+ permissions: [...this.declared],
932
+ ui: {open: this.uiClients.size > 0, clients: this.uiClients.size},
933
+ display: {
934
+ view: snapshot.view,
935
+ revision: snapshot.revision,
936
+ frames: this.frameSeq,
937
+ elements: snapshot.content.kind === "scene" ? snapshot.content.elements.length : 0,
938
+ },
939
+ speaker: this.speakerState,
940
+ sensors: {
941
+ glassesConnected: this.glassesConnected,
942
+ glassesBattery: this.glassesBattery,
943
+ phoneBattery: this.phoneBattery,
944
+ location: this.location,
945
+ },
946
+ visibility: this.visibility,
947
+ colorScheme: this.colorScheme,
948
+ unsimulated: [...this.unsimulated],
949
+ logSeq: this.logSeq,
950
+ }
951
+ }
952
+ }