@marver-design/marver 0.27.0 → 0.28.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.
Files changed (111) hide show
  1. package/CHANGELOG.md +195 -0
  2. package/README.md +9 -4
  3. package/dist/{anchor-check-ChdDqL5z.mjs → anchor-check-PHUOFj1N.mjs} +1 -1
  4. package/dist/{audio-Dw1lfMdb.mjs → audio-DX4POHAj.mjs} +39 -4
  5. package/dist/{board-tree-DRioF94d.mjs → board-tree-BXR8dw4b.mjs} +3 -1
  6. package/dist/{boards-DlTcpF47.mjs → boards-BeWtjGUM.mjs} +50 -5
  7. package/dist/boards-EH2onUXM.mjs +995 -0
  8. package/dist/{build-DZnFysGU.mjs → build-BsAyLMT1.mjs} +9 -22
  9. package/dist/{capture-vadKjuCo.mjs → capture-DdZ6xgoz.mjs} +92 -30
  10. package/dist/cli.mjs +56 -21
  11. package/dist/{collab-Dxg2trOK.mjs → collab-BEAcXrBb.mjs} +1 -1
  12. package/dist/{comments-DxOkCSNE.mjs → comments-CrBHPEQl.mjs} +4 -4
  13. package/dist/config-BezZTiov.mjs +182 -0
  14. package/dist/conn-BMiHS42T.mjs +222 -0
  15. package/dist/connectors-MR9d-EBP.mjs +290 -0
  16. package/dist/{context-HQ4Giw58.mjs → context-BUnFiyA3.mjs} +3 -3
  17. package/dist/{daemon-BSA0lV8d.mjs → daemon-C5dg2R-V.mjs} +2188 -183
  18. package/dist/{dev-eQJhWsqg.mjs → dev-D7YS7iT2.mjs} +25 -14
  19. package/dist/{init-COD0x48i.mjs → init-WE5lQkQL.mjs} +8 -3
  20. package/dist/jam-Cj5gBvwD.mjs +373 -0
  21. package/dist/{link-DDXZVGtv.mjs → link-BFFRgrMt.mjs} +4 -4
  22. package/dist/listener-DdLEM79A.mjs +80 -0
  23. package/dist/{ls-D7O1G505.mjs → ls-BZ5TAtd5.mjs} +1 -1
  24. package/dist/{manifest-Nl3KSVOk.mjs → manifest-DPZ3WNg_.mjs} +2 -2
  25. package/dist/{marks-CWM3WJjc.mjs → marks-Dyn6tmjp.mjs} +3 -3
  26. package/dist/{marks-CKgzucHZ.mjs → marks-Kmdab_5w.mjs} +3 -3
  27. package/dist/{marver-id-gate-BjF6v4bT.mjs → marver-id-gate-D-R0hSt_.mjs} +1 -1
  28. package/dist/perf-Cn5LiRaY.mjs +1319 -0
  29. package/dist/perf-jam-QxD_UnzN.mjs +635 -0
  30. package/dist/permit-DDa6wqOs.mjs +187 -0
  31. package/dist/plugin-C_0yb-Fq.mjs +5089 -0
  32. package/dist/{poster-Bx83ZYVK.mjs → poster-DHi6I1fO.mjs} +1 -1
  33. package/dist/{profile-Bh5Y5zpW.mjs → profile-jIS6BcAs.mjs} +1 -1
  34. package/dist/{publish-bakes-aljgm45S.mjs → publish-bakes-r4PEZuPl.mjs} +3 -3
  35. package/dist/{queue-CAM_vNmX.mjs → queue-c-6aTHEz.mjs} +164 -25
  36. package/dist/{recover-t9Pno3u9.mjs → recover-nrLEVLyJ.mjs} +2 -2
  37. package/dist/{serve-C8rVheYk.mjs → serve-Dp3nHstu.mjs} +3 -3
  38. package/dist/{session-BAaJsK5c.mjs → session-DyVE7cCk.mjs} +1 -1
  39. package/dist/{share-W5H3BNvP.mjs → share-Ce4tP7ji.mjs} +1 -1
  40. package/dist/{shot-LFhC-WYD.mjs → shot-BrRtqaiS.mjs} +34 -8
  41. package/dist/{shot-DoHLl6ig.mjs → shot-DBWN8hPP.mjs} +1 -1
  42. package/dist/sizes-wjXDev3b.mjs +139 -0
  43. package/dist/{slots-DCDo3N0x.mjs → slots-CFNnegCc.mjs} +8 -1
  44. package/dist/speech-worker.mjs +23 -3
  45. package/dist/{sync-BQVlHZpx.mjs → sync-CQdGARJ9.mjs} +1 -1
  46. package/dist/transport-C5FnY9ni.mjs +203 -0
  47. package/dist/{work-BroFwnup.mjs → work-BYWD_1Zf.mjs} +3 -3
  48. package/dist/{work-Bp1p39kq.mjs → work-DJxH7cCX.mjs} +1 -1
  49. package/docs/jam-session.md +42 -16
  50. package/docs/live-jam.md +92 -10
  51. package/docs/performance.md +197 -35
  52. package/package.json +1 -1
  53. package/src/client/content/video.tsx +10 -2
  54. package/src/client/shell/App.tsx +10 -3
  55. package/src/client/shell/Comments.tsx +5 -3
  56. package/src/client/shell/ContextMenu.tsx +5 -3
  57. package/src/client/shell/JamSurface.tsx +56 -21
  58. package/src/client/shell/LockedApp.tsx +3 -0
  59. package/src/client/shell/Play.tsx +4 -2
  60. package/src/client/shell/Tip.tsx +3 -1
  61. package/src/client/shell/api.ts +47 -20
  62. package/src/client/shell/app-bridge.ts +254 -0
  63. package/src/client/shell/app-perf.ts +92 -0
  64. package/src/client/shell/canvas/Canvas.tsx +115 -22
  65. package/src/client/shell/canvas/FrameNode.tsx +10 -6
  66. package/src/client/shell/canvas/admission.ts +23 -8
  67. package/src/client/shell/canvas/ctl.ts +6 -0
  68. package/src/client/shell/canvas/sleep.ts +57 -17
  69. package/src/client/shell/canvas/updates.ts +2 -1
  70. package/src/client/shell/icons.tsx +1 -0
  71. package/src/client/shell/inset.ts +44 -0
  72. package/src/client/shell/jam-capture.ts +113 -33
  73. package/src/client/shell/jam-keys.ts +40 -9
  74. package/src/client/shell/jam-lane.tsx +14 -5
  75. package/src/client/shell/jam-lines.ts +66 -9
  76. package/src/client/shell/jam-panel.tsx +61 -6
  77. package/src/client/shell/jam-queue.ts +50 -8
  78. package/src/client/shell/jam-session.tsx +53 -4
  79. package/src/client/shell/jam-surface-parts.tsx +6 -3
  80. package/src/client/shell/jam-ui.tsx +6 -1
  81. package/src/client/shell/jam-voice-wait.ts +21 -0
  82. package/src/client/shell/jam-voice.ts +62 -15
  83. package/src/client/shell/main.tsx +14 -1
  84. package/src/client/shell/marks-ui.tsx +5 -3
  85. package/src/client/shell/marver-app.ts +21 -0
  86. package/src/client/shell/perf-run-probe.ts +34 -0
  87. package/src/client/shell/perf-run.ts +70 -0
  88. package/src/client/shell/perf.ts +11 -0
  89. package/src/client/shell/recorder.ts +45 -3
  90. package/src/client/shell/store.ts +52 -24
  91. package/src/client/shell/styles.css +65 -17
  92. package/src/client/shell/tidy.ts +3 -2
  93. package/src/client/shell/unsaved.ts +81 -0
  94. package/src/client/shell/whiteout-probes.ts +141 -0
  95. package/src/shared/app-api.ts +205 -0
  96. package/src/shared/app-perf.ts +308 -0
  97. package/src/shared/approval.ts +20 -0
  98. package/src/shared/events.ts +1 -1
  99. package/src/shared/logo-sniff.ts +86 -0
  100. package/src/shared/machine.ts +132 -0
  101. package/src/shared/perf-run.ts +177 -0
  102. package/templates/AGENTS-embedded.md +31 -1
  103. package/templates/AGENTS-studio.md +31 -1
  104. package/templates/instructions/boards.md +10 -2
  105. package/templates/instructions/jam.md +90 -0
  106. package/dist/bake-DM_uWgAA.mjs +0 -786
  107. package/dist/boards-CGg6piKF.mjs +0 -342
  108. package/dist/perf-BWzQwZqj.mjs +0 -369
  109. package/dist/perf-BoDSkbEb.mjs +0 -429
  110. package/dist/perf-jam-D55U3FZK.mjs +0 -242
  111. package/dist/plugin-C-E7omsh.mjs +0 -2762
@@ -19,9 +19,10 @@ import { create } from 'zustand'
19
19
  import { ROUTE } from '../const.ts'
20
20
  import { CONFIG, useStore } from './store.ts'
21
21
  import { api } from './api.ts'
22
+ import { finalWait, FINAL_MS, wordsWhole } from './jam-voice-wait.ts'
22
23
 
23
24
  export const RATE = 16_000
24
- const FINAL_MS = 3_000
25
+ // how long a segment's last words are waited for: jam-voice-wait.ts (FINAL_MS, longer while the engine is heard from)
25
26
  const CHUNK = 1_600 // 100 ms
26
27
 
27
28
  const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
@@ -145,8 +146,11 @@ interface Segment {
145
146
  }
146
147
  interface Mic { ctx: AudioContext; stream: MediaStream; node: AudioWorkletNode; seg: Segment | null; closed: boolean }
147
148
  let mic: Mic | null = null
148
- /** A microphone being opened (its permission, its worklet): a newer change cancels it. */
149
- let opening: { cancelled: boolean } | null = null
149
+ /** A microphone being opened (its permission, its worklet, its connection): a newer change cancels it. It holds
150
+ * what it has opened so far, so a cancel stops its track and closes its context in that same turn - an opening
151
+ * can wait on a request that never answers, and a track it holds is live until stopped (A2.14 #13). */
152
+ interface Opening { cancelled: boolean; stream: MediaStream | null; ctx: AudioContext | null }
153
+ let opening: Opening | null = null
150
154
  let segN = 0
151
155
  /** segment -> its owner (the words it brings back belong to it) */
152
156
  const owners = new Map<string, Owner>()
@@ -161,6 +165,8 @@ let wsOpen: Promise<WebSocket | null> | null = null
161
165
  const finals = new Map<string, (complete: boolean) => void>() // segment -> its final
162
166
  let toldUnavailable = false
163
167
  let takenOver = false
168
+ /** when the speech engine last answered (words or a final): a final still to come is waited for longer while it works */
169
+ let engineAt = 0
164
170
 
165
171
  const setLive = () => useJamVoice.setState({ live: !!mic && !mic.closed, hearing: mic && !mic.closed && mic.seg?.owner.kind === 'capture' ? mic.seg.owner.id : null })
166
172
 
@@ -180,6 +186,7 @@ function socket(reclaim = false): Promise<WebSocket | null> {
180
186
  let m: any
181
187
  try { m = JSON.parse(String(e.data)) } catch { return }
182
188
  if (typeof m?.capture !== 'string') return
189
+ if (m.type === 'words' || m.type === 'final') engineAt = Date.now()
183
190
  const owner = owners.get(m.capture)
184
191
  if (m.type === 'words' && Array.isArray(m.words)) {
185
192
  if (!owner || owner.kind !== 'capture' || !accepting.has(owner.id)) return // talk goes to the transcript on the server
@@ -303,8 +310,12 @@ function endSegment(s: Segment, at: { start: number; pcm: Int16Array; mark: numb
303
310
  const clean = !!at && s.from >= 0
304
311
  if (clean) sendChunk(s, at!.start, at!.pcm)
305
312
  const lastSample = clean ? s.base + at!.mark - s.from : s.sent
313
+ const cut = Date.now()
306
314
  const done = !ws || ws.readyState !== WebSocket.OPEN ? Promise.resolve(false) : new Promise<boolean>((res) => {
307
- const t = setTimeout(() => { finals.delete(s.seg); res(false) }, FINAL_MS)
315
+ // FINAL_MS after the cut - longer while the engine keeps answering (it is working through what came before)
316
+ let t: ReturnType<typeof setTimeout>
317
+ const wait = () => { const ms = finalWait(cut, engineAt, Date.now()); if (ms > 0) t = setTimeout(wait, ms); else { finals.delete(s.seg); res(false) } }
318
+ t = setTimeout(wait, FINAL_MS)
308
319
  finals.set(s.seg, (complete) => { clearTimeout(t); res(complete && clean) })
309
320
  ws!.send(JSON.stringify({ type: 'end', capture: s.seg, lastSample }))
310
321
  })
@@ -316,10 +327,30 @@ function endSegment(s: Segment, at: { start: number; pcm: Int16Array; mark: numb
316
327
  /** Who the microphone should hear now: what runs (a capture, else the session's talk) - if you said yes
317
328
  * and the engine can run. */
318
329
  const wanted = (): Owner | null => {
330
+ if (barred) return null
319
331
  const v = useJamVoice.getState()
320
332
  return v.choice === 'yes' && (v.server === 'ready' || v.server === 'loading') ? target() : null
321
333
  }
322
334
 
335
+ /** The page lost the Mac app's trust while it lives (spec 28 A2.14 #13, `mv:app-state untrusted`): the app can refuse
336
+ * every new microphone request, but only the page can stop a track it already holds. */
337
+ let barred = false
338
+ /** Every microphone track this page holds stops now - the way a lost connection stops it: the words heard so far
339
+ * are kept, marked maybe incomplete - an opening still waiting is cancelled, and nothing opens the microphone again
340
+ * in this document (the next one is proved afresh). */
341
+ export function voiceUntrusted(): void {
342
+ barred = true
343
+ cancelOpening()
344
+ const m = mic
345
+ if (m && !m.closed) {
346
+ if (m.seg) broken.add(m.seg.owner.id)
347
+ closeNow(m)
348
+ if (mic === m) mic = null
349
+ setLive()
350
+ }
351
+ useJamVoice.setState({ asking: false })
352
+ }
353
+
323
354
  /** Bring the microphone to what should be heard NOW. Every change - open, switch, close - is one step in
324
355
  * one chain, so no change overtakes another: a switch ends the current segment and starts the next at
325
356
  * the same worklet mark (nothing lost, nothing heard twice); an opening still waiting gives way to a
@@ -350,19 +381,20 @@ async function step() {
350
381
 
351
382
  /** Open the microphone for `owner` - one step of the chain; a newer state cancels it at its next wait. */
352
383
  async function open(owner: Owner) {
353
- const op = { cancelled: false }
384
+ const op: Opening = { cancelled: false, stream: null, ctx: null }
354
385
  opening = op
355
386
  const stale = () => op.cancelled || wanted()?.id !== owner.id
356
- let stream: MediaStream | null = null
357
- let ctx: AudioContext | null = null
358
- const undo = () => { stream?.getTracks().forEach((t) => t.stop()); void ctx?.close().catch(() => {}) }
387
+ const undo = () => release(op)
359
388
  try {
360
389
  // the microphone first (its permission, its worklet), the connection last: a page never holds the one
361
390
  // audio connection while it is still starting - and a reclaim takes it only if it is free
391
+ let stream: MediaStream
362
392
  try { stream = await navigator.mediaDevices.getUserMedia({ audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true } }) }
363
393
  catch { useJamVoice.setState({ denied: true }); useStore.getState().toast('the microphone is blocked for this page - typed notes only'); return }
394
+ op.stream = stream
364
395
  if (stale()) { undo(); return }
365
- ctx = new AudioContext({ sampleRate: RATE })
396
+ const ctx = new AudioContext({ sampleRate: RATE })
397
+ op.ctx = ctx
366
398
  await ctx.audioWorklet.addModule(URL.createObjectURL(new Blob([WORKLET], { type: 'application/javascript' })))
367
399
  if (stale()) { undo(); return }
368
400
  // a capture is something you just did here: it takes the connection; a session's talk only takes it if it
@@ -375,6 +407,9 @@ async function open(owner: Owner) {
375
407
  const node = new AudioWorkletNode(ctx, 'mv-pcm')
376
408
  ctx.createMediaStreamSource(stream).connect(node)
377
409
  const m: Mic = { ctx, stream, node, seg: null, closed: false }
410
+ // the microphone owns them now: closeNow stops them, never the opening
411
+ op.stream = null
412
+ op.ctx = null
378
413
  mic = m
379
414
  const seg = segmentFor(owner, -1)
380
415
  m.seg = seg
@@ -385,10 +420,21 @@ async function open(owner: Owner) {
385
420
  setLive()
386
421
  } catch {
387
422
  undo()
388
- useStore.getState().toast('the microphone could not start - typed notes only')
423
+ // a cancelled opening whose context closed under its worklet says nothing: nothing failed
424
+ if (!op.cancelled) useStore.getState().toast('the microphone could not start - typed notes only')
389
425
  } finally { if (opening === op) opening = null }
390
426
  }
391
- const cancelOpening = () => { if (opening) opening.cancelled = true }
427
+ /** What an opening holds goes, once: its tracks stopped, its context closed. */
428
+ function release(op: Opening) {
429
+ const { stream, ctx } = op
430
+ op.stream = null
431
+ op.ctx = null
432
+ stream?.getTracks().forEach((t) => t.stop())
433
+ void ctx?.close().catch(() => {})
434
+ }
435
+ /** A newer change, or the app's `untrusted`: the opening goes, and what it already holds stops now - not at its
436
+ * next wait, which may never come. The opening still sees itself cancelled when that wait ends, and opens nothing. */
437
+ const cancelOpening = () => { if (opening) { opening.cancelled = true; release(opening) } }
392
438
  /** The chain settled - but never longer than `ms` (an opening may wait on the browser's permission
393
439
  * question; what the caller needs - the cuts of its segments - is done before it). */
394
440
  const settle = (ms = 2_000) => Promise.race([reconcile(), new Promise<void>((r) => setTimeout(r, ms))])
@@ -410,12 +456,13 @@ async function begin() {
410
456
  await reconcile()
411
457
  }
412
458
 
413
- /** Every segment of an owner ended: true when all its words came back whole. */
459
+ /** Every segment of an owner ended: true when all its words came back whole - and, with the microphone on for this
460
+ * canvas, when it heard the owner at all (an engine not available, a microphone still opening or refused: none). */
414
461
  async function settled(owner: string): Promise<boolean> {
415
462
  const list = cuts.get(owner) ?? []
416
463
  cuts.delete(owner)
417
464
  const all = await Promise.all(list)
418
- const ok = all.every(Boolean) && !broken.has(owner)
465
+ const ok = wordsWhole(all, broken.has(owner), useJamVoice.getState().choice === 'yes')
419
466
  broken.delete(owner)
420
467
  return ok
421
468
  }
@@ -431,7 +478,7 @@ export async function voiceBegin(id: string, t0: number) {
431
478
  }
432
479
 
433
480
  /** A capture ends: its audio cut at this instant (in a session the talk goes on from it), its words awaited
434
- * (3 s at most). Resolves true when the words are complete, false when they may not be. */
481
+ * (jam-voice-wait.ts). Resolves true when the words are complete, false when they may not be. */
435
482
  export async function voiceEnd(id: string): Promise<boolean> {
436
483
  if (capture?.id === id) capture = null
437
484
  useJamVoice.setState((st) => ({ asking: st.asking && st.choice === null && !session ? false : st.asking }))
@@ -478,4 +525,4 @@ export async function voiceSessionEnd(): Promise<void> {
478
525
  await settled(s.id)
479
526
  }
480
527
 
481
- if (typeof window !== 'undefined' && (import.meta as any).env?.DEV) { (window as any).__mvJamVoice = useJamVoice; (window as any).__mvJamVoiceSession = voiceSessionId }
528
+ if (typeof window !== 'undefined' && (import.meta as any).env?.DEV) { (window as any).__mvJamVoice = useJamVoice; (window as any).__mvJamVoiceSession = voiceSessionId; (window as any).__mvJamVoiceTalk = voiceSession }
@@ -1,13 +1,26 @@
1
1
  import { createRoot } from 'react-dom/client'
2
- import { App, ShellBoundary } from './App.tsx'
2
+ // an all-boards-locked build gives LockedApp.tsx in App.tsx's place: what only the canvas uses comes through it
3
+ import { App, ShellBoundary, startPerfRunProbe } from './App.tsx'
3
4
  import { useStore } from './store.ts'
4
5
  import { startRecorder } from './recorder.ts'
5
6
  import { capturesPending, sealOnLeave } from './jam-capture.ts'
7
+ import { startAppBridge } from './app-bridge.ts'
8
+ import { startAppPerf } from './app-perf.ts'
9
+ import { applyInset } from './inset.ts'
6
10
  import './styles.css'
7
11
 
8
12
  // dev aid: inspectable store (harmless in builds; the canvas is a dev surface)
9
13
  ;(window as any).__sh = useStore
10
14
  // what each board load does, from the page (spec 28 A1.7): before the first load; nothing on a published canvas
11
15
  startRecorder({ capturesPending, sealCaptures: sealOnLeave })
16
+ // under the Mac app's transparent strip (0.27.2, A3.8 #31): --mv-top on :root before anything is placed; nothing
17
+ // anywhere else (Chrome, a published canvas, app 0.1)
18
+ applyInset()
19
+ // in the Mac app: hello, theme, busy and menu before the first render (spec 28 A2.9); nothing anywhere else
20
+ startAppBridge()
21
+ // in the Mac app 0.2: the recorder's probes and the board's frame count (spec 28 A3.8 #9, #16); nothing anywhere else
22
+ startAppPerf()
23
+ // a headless perf run (spec 28 A3.8 #17): what its driver reads and asks, through CDP - nothing without ?mvperfrun
24
+ startPerfRunProbe()
12
25
 
13
26
  createRoot(document.getElementById('root')!).render(<ShellBoundary><App /></ShellBoundary>)
@@ -3,6 +3,7 @@
3
3
  * carries the state (blue new, orange needs you); the row's one right-hand slot holds what matters
4
4
  * most: a question's numbered bubble, then the row's own count or status, then a frame's dot.
5
5
  */
6
+ import { onScreen } from './inset.ts'
6
7
  import { useEffect, type HTMLAttributes, type ReactNode } from 'react'
7
8
  import { create } from 'zustand'
8
9
  import { useStore, PUBLISHED, shownRev } from './store.ts'
@@ -95,13 +96,14 @@ export function useSeenOnScreen() {
95
96
  } else if (m && !document.hidden && s.scale >= 0.5) {
96
97
  // in view: some of it inside the window and not all of that under the open sidebar
97
98
  const P = document.querySelector('.sh-panel:not(.closed)')?.getBoundingClientRect()
98
- const W = window.innerWidth, H = window.innerHeight
99
99
  for (const n of s.nodes) {
100
100
  if (n.status !== 'ready' || n.stale || !isNew(m, n.frame) || shownRev(n, m) < (m.doc[n.frame] ?? 0)) continue
101
101
  const r = document.querySelector<HTMLElement>(`.sh-node[data-node="${CSS.escape(n.key)}"]`)?.getBoundingClientRect()
102
102
  if (!r) continue
103
- const x0 = Math.max(r.left, 0), x1 = Math.min(r.right, W), y0 = Math.max(r.top, 0), y1 = Math.min(r.bottom, H)
104
- if (x0 >= x1 || y0 >= y1) continue
103
+ // the part on screen below the scroll edge (inset.ts): under the Mac app's strip is not seen
104
+ const on = onScreen(r)
105
+ if (!on) continue
106
+ const x0 = on.left, x1 = on.right, y0 = on.top, y1 = on.bottom
105
107
  if (P && x0 >= P.left && x1 <= P.right && y0 >= P.top && y1 <= P.bottom) continue
106
108
  shown.set(`${n.key}@${m.changed[n.frame] ?? 0}:${n.shown}`, n.key)
107
109
  }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * `window.marverApp` - there only when this page is a verified local canvas in the Mac app (spec 28 A2.9; the app's
3
+ * canvas preload exposes it). Everywhere else - Chrome, Safari, a published canvas, `marver shot` - it is null, and
4
+ * nothing that reads it does anything. Kept apart from app-bridge.ts, so the canvas can read `reopen` without
5
+ * importing the bridge.
6
+ */
7
+ import type { MarverAppV1 } from '../../shared/app-api.ts'
8
+
9
+ /** The app's bridge, when it speaks this version of the contract and has every method this shell calls. */
10
+ export const APP: MarverAppV1 | null = (() => {
11
+ try {
12
+ const a = (globalThis as { marverApp?: Partial<MarverAppV1> }).marverApp
13
+ if (!a || a.v !== 1) return null
14
+ const calls = ['hello', 'theme', 'busy', 'menu', 'onAppState', 'onMenuClick'] as const
15
+ return calls.every((k) => typeof a[k] === 'function') ? a as MarverAppV1 : null
16
+ } catch { return null }
17
+ })()
18
+
19
+ /** The app reloaded this tab after a crash: the canvas opens on its saved camera, even when the link names a
20
+ * selection (A2.14 #9). */
21
+ export const APP_REOPEN = APP?.reopen === true
@@ -0,0 +1,34 @@
1
+ /**
2
+ * A headless perf run's probe (spec 28 A3.8 #17): what its driver reads and asks, through CDP - nothing without
3
+ * ?mvperfrun. Canvas code (the camera, the gestures, the sleeps): main.tsx reaches it through App.tsx, so an
4
+ * all-boards-locked bundle, which the build gives LockedApp.tsx in App.tsx's place, carries none of it - a run's page
5
+ * is always a dev canvas, never a locked one.
6
+ */
7
+ import { currentLoad, flush } from './recorder.ts'
8
+ import { installPerfRunProbe, PERF_RUN, postersSkipped, refusedInPage } from './perf-run.ts'
9
+ import { bakeIdle, bakeWork } from './canvas/sleep.ts'
10
+ import { canvasCtl } from './canvas/ctl.ts'
11
+ import { gestureRunning, gesturesEnded } from './perf.ts'
12
+
13
+ /** main.tsx, after startAppPerf(): the probe, installed only on a run's page. */
14
+ export function startPerfRunProbe(): void {
15
+ if (!PERF_RUN) return
16
+ const run = PERF_RUN
17
+ const moving = () => gestureRunning() || canvasCtl.cameraBusy()
18
+ const wait = (ms: number) => new Promise((r) => setTimeout(r, ms))
19
+ installPerfRunProbe({
20
+ status: () => ({ run: run.id, warm: run.warm, load: currentLoad(), bakeIdle: bakeIdle(), bake: bakeWork(), moving: moving(), gestures: gesturesEnded(), postersSkipped: postersSkipped(), refused: refusedInPage() }),
21
+ // the whole board, then the camera still (two looks 50 ms apart), 3 s at most
22
+ async fit() {
23
+ canvasCtl.fitAll()
24
+ const by = performance.now() + 3000
25
+ for (let still = 0; performance.now() < by; await wait(50)) if (moving()) still = 0; else if (++still >= 2) return true
26
+ return false
27
+ },
28
+ centre() {
29
+ const r = document.querySelector('.sh-canvas')?.getBoundingClientRect()
30
+ return r ? { x: Math.round(r.left + r.width / 2), y: Math.round(r.top + r.height / 2) } : { x: Math.round(innerWidth / 2), y: Math.round(innerHeight / 2) }
31
+ },
32
+ flush,
33
+ })
34
+ }
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Perf mode, the page's half of a headless run (spec 28 A3.4, A3.8 #17): `?mvperfrun=<16 hex>[&warm=1]` sets
3
+ * `PERF_RUN` at module load, before boot, in dev only. Owner: the headless stream; the contract is
4
+ * src/shared/perf-run.ts, which the server reads too.
5
+ *
6
+ * - The barrier sits in `mvFetch` (api.ts), before any `fetch`: GET and HEAD pass, and under `${ROUTE}/api/` only
7
+ * `POST perf/page` and `POST bakes`; anything else gets a synthetic 403, counted as `refused`, and never reaches
8
+ * `lost()`. Every request carries `x-mv-perfrun`; `withWs()` adds `mvperfrun` to frame URLs, the play stage and
9
+ * Jam pictures.
10
+ * - Warm mode: the recorder runs (the driver reads `settled` from it) and posts nothing; `flush()` sends until the
11
+ * outbox is empty and answers whether every batch landed.
12
+ * - In perf mode `beforeunload` never refuses, and the Video primitive never asks for a poster
13
+ * (`data-mv-poster-skipped`).
14
+ * - `window.__mvPerfRun` (`PerfRunProbe`): status(), fit(), centre(), flush().
15
+ *
16
+ * FROZEN (A3.8 #53): `PERF_RUN`, `runApiPath`, `perfRunGate` and `installPerfRunProbe`'s signature.
17
+ */
18
+ import { ROUTE } from '../const.ts'
19
+ import { allowedInRun, RUN_HEADER, RUN_ID, RUN_PARAM, WARM_PARAM, type PerfRunProbe } from '../../shared/perf-run.ts'
20
+
21
+ export * from '../../shared/perf-run.ts'
22
+
23
+ /**
24
+ * This page's run, or null: a published canvas (a production build), or no `mvperfrun`. Read with no import of
25
+ * api.ts, which calls `perfRunGate` (a cycle would read this before it exists).
26
+ */
27
+ export const PERF_RUN: { id: string; warm: boolean } | null = (() => {
28
+ if (!import.meta.env.DEV) return null
29
+ try {
30
+ const q = new URLSearchParams(location.search)
31
+ const id = q.get(RUN_PARAM)
32
+ return id && RUN_ID.test(id) ? { id, warm: q.get(WARM_PARAM) === '1' } : null
33
+ } catch { return null }
34
+ })()
35
+
36
+ /** The path under `${ROUTE}/api/` a URL names (no query), or null for any other path. */
37
+ export function runApiPath(url: string): string | null {
38
+ let p: string
39
+ try { p = new URL(url, location.href).pathname } catch { return null }
40
+ const base = `${ROUTE}/api/`
41
+ return p.startsWith(base) ? p.slice(base.length) : null
42
+ }
43
+
44
+ let refused = 0
45
+ /** Requests refused before sending, so far. */
46
+ export const refusedInPage = (): number => refused
47
+
48
+ /**
49
+ * The barrier, called first by `mvFetch` in perf mode: null lets the request go (it then carries `x-mv-perfrun`);
50
+ * a Response is the synthetic refusal, never sent.
51
+ */
52
+ export function perfRunGate(url: string, init: RequestInit = {}): Response | null {
53
+ if (!PERF_RUN) return null
54
+ if (allowedInRun(init.method ?? 'GET', runApiPath(url))) return null
55
+ refused += 1
56
+ return new Response('{"error":"a perf run is read-only"}', { status: 403, headers: { 'content-type': 'application/json', [RUN_HEADER]: 'refused' } })
57
+ }
58
+
59
+ /** Same-origin frames whose document skipped a missing poster (the Video primitive's `data-mv-poster-skipped`). */
60
+ export function postersSkipped(): number {
61
+ let n = 0
62
+ for (const f of document.querySelectorAll('iframe')) { try { if (f.contentDocument?.documentElement.hasAttribute('data-mv-poster-skipped')) n++ } catch { /* another origin */ } }
63
+ return n
64
+ }
65
+
66
+ /** main.tsx in perf mode: `window.__mvPerfRun`. */
67
+ export function installPerfRunProbe(probe: PerfRunProbe): void {
68
+ if (!PERF_RUN) return
69
+ ;(window as unknown as { __mvPerfRun?: PerfRunProbe }).__mvPerfRun = probe
70
+ }
@@ -12,6 +12,7 @@
12
12
  * perfMark(name) + counters are the plug points later stages use (blank-frame / warm-latency).
13
13
  */
14
14
  import { onMotion, type Motion } from './canvas/camera-broadcast.ts'
15
+ import { gestureOff, gestureOn } from './app-perf.ts'
15
16
  import { recorder } from './recorder.ts'
16
17
  import { gestureStats } from './recorder-core.ts'
17
18
 
@@ -34,6 +35,12 @@ const enabled = (): boolean => {
34
35
  interface Run { t0: number; last: number; dts: number[]; pan: boolean; zoom: boolean; layout: boolean; longs: number[]; obs?: PerformanceObserver; raf: number }
35
36
  /** the gesture running now */
36
37
  let g: Run | null = null
38
+ /** gestures ended so far, every one (a headless perf run waits for each of its three, spec 28 A3.8 #20) */
39
+ let ended = 0
40
+ /** How many gestures have ended since the page loaded. */
41
+ export const gesturesEnded = (): number => ended
42
+ /** Is a gesture (a pan, a zoom, a layout animation) running now? */
43
+ export const gestureRunning = (): boolean => g !== null
37
44
 
38
45
  function note(m: Motion) {
39
46
  if (!g) return
@@ -45,6 +52,8 @@ function begin(m: Motion) {
45
52
  const run: Run = { t0: performance.now(), last: 0, dts: [], pan: false, zoom: false, layout: false, longs: [], raf: 0 }
46
53
  g = run
47
54
  note(m)
55
+ // the Mac app's recorder hears it start (the white-out detector's window, spec 28 A3.8 #15); nothing elsewhere
56
+ gestureOn(run.pan ? 'pan' : run.zoom ? 'zoom' : run.layout ? 'layout' : undefined)
48
57
  try {
49
58
  run.obs = new PerformanceObserver((l) => { for (const e of l.getEntries()) if (e.startTime >= run.t0) run.longs.push(e.duration) })
50
59
  run.obs.observe({ type: LOAF ? 'long-animation-frame' : 'longtask', buffered: false })
@@ -62,10 +71,12 @@ function begin(m: Motion) {
62
71
  function end() {
63
72
  const run = g!
64
73
  g = null
74
+ ended++
65
75
  cancelAnimationFrame(run.raf)
66
76
  const t1 = performance.now()
67
77
  for (const e of run.obs?.takeRecords() ?? []) if (e.startTime >= run.t0 && e.startTime <= t1) run.longs.push(e.duration)
68
78
  run.obs?.disconnect()
79
+ gestureOff()
69
80
  for (const d of run.dts) { frames.push(d); if (frames.length > MAX) frames.shift() }
70
81
  for (const d of run.longs) { longs.push(d); if (longs.length > MAX) longs.shift() }
71
82
  if (run.dts.length < 2) return // a press that never moved the camera
@@ -16,6 +16,8 @@ import { admissionIdle, onAdmissionIdle } from './canvas/admission.ts'
16
16
  import { canvasCtl } from './canvas/ctl.ts'
17
17
  import { bootOf, iframeOf } from './canvas/frame-registry.ts'
18
18
  import { adopt, bound, fitWithin, KEEPALIVE_BYTES, LOAD_MAX_MS, newId, Outbox, outcomeOf, QUIET_MS, SEND_MS, stackLines, type Kind, type Outcome, type PerfRecord, type Track } from './recorder-core.ts'
19
+ import { PERF_RUN, type PerfRunStatus } from './perf-run.ts'
20
+ import { displayHz } from './app-perf.ts'
19
21
 
20
22
  /** This document, in every record (and, in the app, in its hello: the app's records about this tab carry it). */
21
23
  export const PAGE_ID = newId()
@@ -40,6 +42,8 @@ interface Load {
40
42
  /** node key -> `${outcome}:${boot}` its last frame record said */
41
43
  reported: Map<string, string>
42
44
  done?: 'settled' | 'cut'
45
+ /** why it was cut, request or load (a headless perf run's status says it) */
46
+ cutReason?: string
43
47
  quietTimer?: ReturnType<typeof setTimeout>; timeout?: ReturnType<typeof setTimeout>; retry?: ReturnType<typeof setTimeout>
44
48
  }
45
49
 
@@ -66,6 +70,14 @@ const open = new Map<string, PerfRecord>()
66
70
  let inFlight: PerfRecord[] = []
67
71
  let sendTimer: ReturnType<typeof setTimeout> | undefined
68
72
  let sending = false
73
+ /** sends whose records never landed, since the page loaded (a headless perf run's `flush()` answers with it) */
74
+ let failedSends = 0
75
+ /** records lost on this page's side since it loaded - the queue's bound, a send that never landed - however many
76
+ * `dropped` records said so: the count each one carries starts over, this one never does (`flush()`) */
77
+ let lostEver = 0
78
+ /** The warm-up load of a headless perf run (spec 28 A3.8 #17): the recorder runs - the driver reads `settled` from
79
+ * it - and posts nothing. */
80
+ const WARM = PERF_RUN?.warm === true
69
81
  /** what only the canvas knows (Canvas.tsx attaches it): is a pan, zoom or layout animation running; frames asleep */
70
82
  let motion = { camera: false, preset: false }
71
83
  let sleeping = (): number => 0
@@ -166,6 +178,7 @@ function cutRequest(id: string, reason: RequestCut | 'timeout' | 'hidden'): void
166
178
  clearTimeout(L.timeout)
167
179
  L.timeout = undefined
168
180
  L.done = 'cut'
181
+ L.cutReason = reason
169
182
  rec('cut', id, { reason, request: id, ms: Math.round(performance.now() - L.t0) })
170
183
  // its fetch may still answer and mount it
171
184
  if (reason === 'timeout' || reason === 'hidden') {
@@ -363,6 +376,7 @@ function cut(L: Load, reason: 'switch' | 'reload' | 'hidden' | 'timeout'): void
363
376
  else if (L.reported.get(n.key) !== said(n, o)) frameRecord(L, n, o)
364
377
  }
365
378
  rec('cut', L.id, { reason, ms: Math.round(performance.now() - L.t0), lastMove: rel(L, L.movedAt), frames: s.nodes.length, ready })
379
+ L.cutReason = reason
366
380
  finish(L, 'cut')
367
381
  }
368
382
 
@@ -439,6 +453,7 @@ const wait = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
439
453
  const droppedNow = (more = 0): PerfRecord[] => {
440
454
  const n = outbox.dropped + more
441
455
  outbox.dropped = 0
456
+ lostEver += n
442
457
  return n ? [env('dropped', ownerId(), { n })] : []
443
458
  }
444
459
 
@@ -449,6 +464,8 @@ async function send(): Promise<void> {
449
464
  clearTimeout(sendTimer)
450
465
  sendTimer = undefined
451
466
  if (!on || sending || !outbox.size) return
467
+ // a perf run's warm-up: what it recorded is the driver's to read, never the log's
468
+ if (WARM) { outbox.takeAll(); outbox.dropped = 0; open.clear(); return }
452
469
  sending = true
453
470
  let batch: PerfRecord[] = []
454
471
  let ok = false
@@ -466,7 +483,7 @@ async function send(): Promise<void> {
466
483
  } catch { /* the network: again */ }
467
484
  }
468
485
  } catch { /* never in the way: what it held is counted below */ }
469
- if (!ok) outbox.dropped += batch.filter((r) => r.kind !== 'dropped').length + batch.filter((r) => r.kind === 'dropped').reduce((n, r) => n + (r.n as number), 0)
486
+ if (!ok) { failedSends++; outbox.dropped += batch.filter((r) => r.kind !== 'dropped').length + batch.filter((r) => r.kind === 'dropped').reduce((n, r) => n + (r.n as number), 0) }
470
487
  inFlight = []
471
488
  sending = false
472
489
  armSend()
@@ -481,7 +498,7 @@ function leave(): void {
481
498
  clearTimeout(sendTimer)
482
499
  sendTimer = undefined
483
500
  sealCaptures()
484
- if (capturesPending()) return
501
+ if (capturesPending() || WARM) return
485
502
  // a send on its way may not outlive the page: its records again (the report drops a duplicate by its seq)
486
503
  const all = [...inFlight, ...outbox.takeAll()]
487
504
  if (!all.length) return
@@ -490,6 +507,31 @@ function leave(): void {
490
507
  try { void post([...fit, ...droppedNow(lost)], true).catch(() => {}) } catch { /* going anyway */ }
491
508
  }
492
509
 
510
+ // ---- a headless perf run (spec 28 A3.8 #17) ----------------------------------------------------------------------
511
+
512
+ /** The load the page has now - the newest request still waiting, else the one that owns the geometry - and where it
513
+ * is: requested, committed, settled or cut (with why). `sinceNav`, a boot load's request on the page's clock. */
514
+ export function currentLoad(): PerfRunStatus['load'] {
515
+ const L = [...pending.values()].at(-1) ?? owner
516
+ if (!L) return null
517
+ const state = L.done ?? (L.committedAt !== undefined ? 'committed' : 'requested')
518
+ return { id: L.id, state, ...(L.cutReason ? { reason: L.cutReason } : {}), ...(L.cause === 'boot' ? { sinceNav: Math.round(L.t0) } : {}) }
519
+ }
520
+
521
+ /** Everything recorded so far sent now, until nothing waits and nothing is on its way (15 s at most): whether every
522
+ * batch this page ever sent landed, and no record was ever lost to the queue's bound. The driver awaits it before it
523
+ * ends the page. A warm-up posts nothing: true. */
524
+ export async function flush(): Promise<boolean> {
525
+ if (!on) return false
526
+ if (WARM) return true
527
+ const by = performance.now() + 15_000
528
+ while ((sending || outbox.size) && performance.now() < by) {
529
+ if (!sending) await send()
530
+ else await wait(25)
531
+ }
532
+ return !sending && !outbox.size && !outbox.dropped && failedSends === 0 && lostEver === 0
533
+ }
534
+
493
535
  // ---- for tests --------------------------------------------------------------------------------------------------
494
536
 
495
537
  function state() {
@@ -556,7 +598,7 @@ export const recorder = {
556
598
  rec('visible', L.id, { nodes: L.cohort.size, ms: Math.round(performance.now() - L.t0) })
557
599
  }),
558
600
  /** A pan, zoom or layout animation ended (perf.ts). */
559
- gesture: guard((g: Gesture) => { rec('gesture', ownerId(), g); settleSoon() }),
601
+ gesture: guard((g: Gesture) => { rec('gesture', ownerId(), { ...g, hz: displayHz() ?? undefined }); settleSoon() }),
560
602
  /** An error the shell saw: its own (window, ShellBoundary) or the play stage's. A shell error goes out at once. */
561
603
  error: guard((e: { source: 'shell' | 'stage'; message: unknown; stack?: unknown; component?: string }) => {
562
604
  logError(e)