@marver-design/marver 0.25.0 → 0.26.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 (92) hide show
  1. package/CHANGELOG.md +75 -0
  2. package/README.md +3 -1
  3. package/dist/{anchor-DVV732zR.mjs → anchor-5H1vnoLu.mjs} +6 -1
  4. package/dist/{anchor-check-BE5VVN6Q.mjs → anchor-check-Dg5xpNnU.mjs} +1 -1
  5. package/dist/audio-CmSRYFEs.mjs +429 -0
  6. package/dist/{auth-DdUKeVKt.mjs → auth-Dix8wrXV.mjs} +1 -1
  7. package/dist/{bake-D8byeRzB.mjs → bake-DtVlm0_F.mjs} +45 -6
  8. package/dist/{boards-Csxj2WJn.mjs → boards-DYG22tOe.mjs} +2 -2
  9. package/dist/{build-BHoWLvSj.mjs → build-C_gUgcdC.mjs} +16 -9
  10. package/dist/capture-CrqvU_jh.mjs +729 -0
  11. package/dist/cli.mjs +23 -17
  12. package/dist/{collab-gqNdScUE.mjs → collab-Dxg2trOK.mjs} +4 -3
  13. package/dist/{comments-Zoch254k.mjs → comments-0BSbb04K.mjs} +14 -3
  14. package/dist/{comments-pTLlhjh4.mjs → comments-BqXua-XL.mjs} +7 -7
  15. package/dist/{config-cKgZBRj0.mjs → config-Cf7EjAMf.mjs} +12 -1
  16. package/dist/{context-D2ugHqwO.mjs → context-HQ4Giw58.mjs} +1 -1
  17. package/dist/daemon-DZo6o3rU.mjs +2445 -0
  18. package/dist/{dev-DJdgow47.mjs → dev-_Nlsc6v9.mjs} +189 -18
  19. package/dist/dev-lock-DWSpa6nj.mjs +179 -0
  20. package/dist/{events-DnK_AnrW.mjs → events-CLH4ijKP.mjs} +14 -4
  21. package/dist/{init-DO4DhUt_.mjs → init-D8DtrK_F.mjs} +2 -2
  22. package/dist/{ledger-BNXW14Xw.mjs → ledger-D54iROST.mjs} +17 -1
  23. package/dist/{link-C-qUIuKU.mjs → link-BNzLvdhI.mjs} +2 -2
  24. package/dist/live-Cgzsicwi.mjs +4 -0
  25. package/dist/{manifest-DnAte_fB.mjs → manifest-Nl3KSVOk.mjs} +1 -1
  26. package/dist/{marks-koRsbHfe.mjs → marks-CKgzucHZ.mjs} +2 -2
  27. package/dist/{marks-DFuintmJ.mjs → marks-NQi0wZJ4.mjs} +23 -5
  28. package/dist/{marver-id-gate-DGANtVyC.mjs → marver-id-gate-BjF6v4bT.mjs} +4 -4
  29. package/dist/{perf-QJIWtTw1.mjs → perf-D6VmmJ2q.mjs} +1 -1
  30. package/dist/{perf-CCisg-ny.mjs → perf-DPbLGhhO.mjs} +1 -1
  31. package/dist/{plugin-CTyhjwoJ.mjs → plugin-CTD0rydA.mjs} +279 -38
  32. package/dist/{poster-D0cbV7hi.mjs → poster-ChjXGTS5.mjs} +1 -1
  33. package/dist/{profile-Do0nGkXO.mjs → profile-WU9qcbIo.mjs} +1 -1
  34. package/dist/{publish-bakes--l8ot2eQ.mjs → publish-bakes-CEP_2NRc.mjs} +3 -3
  35. package/dist/queue-BuiCKSX1.mjs +1319 -0
  36. package/dist/reserve-BURNQ2Y3.mjs +53 -0
  37. package/dist/{rolldown-runtime-D7D4PA-g.mjs → rolldown-runtime-8H4AJuhK.mjs} +1 -0
  38. package/dist/{serve-wv2QWdxB.mjs → serve-C8rVheYk.mjs} +12 -12
  39. package/dist/session-qZWKt_VA.mjs +191 -0
  40. package/dist/{share-ScamJcks.mjs → share--oFJ1bCI.mjs} +2 -2
  41. package/dist/{shot-jdO_B6Qw.mjs → shot-CNbHoZ6H.mjs} +1 -1
  42. package/dist/{shot-CckrGW-J.mjs → shot-DqcxJibP.mjs} +4 -3
  43. package/dist/speech-models-DomiLQcY.mjs +299 -0
  44. package/dist/speech-worker.mjs +319 -0
  45. package/dist/{summary-CrW88e3q.mjs → summary-Y8MY1Wuc.mjs} +2 -2
  46. package/dist/{sync-C3035OnJ.mjs → sync-DKk-yT1V.mjs} +9 -8
  47. package/dist/{work-GE88wb_3.mjs → work-F5u-twpJ.mjs} +28 -5
  48. package/dist/{work-CpJn1gwY.mjs → work-VvX_JIgl.mjs} +2 -2
  49. package/docs/jam-session.md +177 -0
  50. package/docs/live-jam.md +21 -3
  51. package/package.json +7 -1
  52. package/src/client/frame-host/bridge.js +20 -2
  53. package/src/client/frame-host/inspect.d.ts +4 -0
  54. package/src/client/frame-host/inspect.js +88 -3
  55. package/src/client/frame-host/keys.d.ts +6 -0
  56. package/src/client/frame-host/keys.js +55 -0
  57. package/src/client/frame-host/trail.d.ts +7 -0
  58. package/src/client/frame-host/trail.js +204 -0
  59. package/src/client/shell/App.tsx +45 -5
  60. package/src/client/shell/Comments.tsx +20 -6
  61. package/src/client/shell/JamSurface.tsx +340 -0
  62. package/src/client/shell/Play.tsx +22 -3
  63. package/src/client/shell/Tip.tsx +8 -3
  64. package/src/client/shell/canvas/Canvas.tsx +12 -2
  65. package/src/client/shell/canvas/FrameNode.tsx +11 -2
  66. package/src/client/shell/canvas/sleep.ts +19 -1
  67. package/src/client/shell/comments-store.ts +23 -16
  68. package/src/client/shell/icons.tsx +15 -0
  69. package/src/client/shell/jam-capture.ts +939 -0
  70. package/src/client/shell/jam-keys.ts +329 -0
  71. package/src/client/shell/jam-lane.tsx +208 -0
  72. package/src/client/shell/jam-lines.ts +115 -0
  73. package/src/client/shell/jam-panel.tsx +506 -0
  74. package/src/client/shell/jam-queue.ts +126 -0
  75. package/src/client/shell/jam-session.tsx +389 -0
  76. package/src/client/shell/jam-state.ts +61 -0
  77. package/src/client/shell/jam-surface-parts.tsx +102 -0
  78. package/src/client/shell/jam-ui.tsx +104 -0
  79. package/src/client/shell/jam-voice.ts +479 -0
  80. package/src/client/shell/sound.ts +22 -0
  81. package/src/client/shell/stage-size.ts +11 -0
  82. package/src/client/shell/store.ts +34 -13
  83. package/src/client/shell/styles.css +544 -2
  84. package/src/client/stage/main.tsx +16 -2
  85. package/src/shared/capture-frames.ts +41 -0
  86. package/src/shared/events.ts +19 -4
  87. package/src/shared/speech.ts +16 -0
  88. package/templates/AGENTS-embedded.md +10 -2
  89. package/templates/AGENTS-studio.md +10 -2
  90. package/templates/instructions/iterate.md +8 -6
  91. package/templates/instructions/jam.md +129 -59
  92. package/dist/daemon-Cl8KXGW4.mjs +0 -1523
@@ -0,0 +1,939 @@
1
+ /**
2
+ * Captures in the shell (spec 27, Part 3): `S` starts one, `E` ends it - everything you say, write
3
+ * and do while it is open is one timeline, on one clock.
4
+ *
5
+ * The frames record what happens inside them (frame-host/trail.js) and post it here; this module
6
+ * owns everything else: the capture ids, the load-bound handshake per mounted instance (a frame can
7
+ * show twice; a document replaced mid-capture never binds), canvas-mode clicks and hovers (the
8
+ * shell's overlay keeps the click and asks the frame what is under it), the UI steps the shell
9
+ * itself takes (select, device, theme, copy, interactive mode), notes, pictures - and the end: the
10
+ * flush, the drain, the seal, and the post of the sealed record.
11
+ *
12
+ * A capture is recording, then draining, then sealed. One records at a time: `S` while one records
13
+ * starts nothing - it is ended (E) or dropped (Esc) first. Each message lands in the capture whose
14
+ * id it carries.
15
+ */
16
+ import { create } from 'zustand'
17
+ import { ROUTE, slideSize } from '../const.ts'
18
+ import { CONFIG, SLIDE_INTRINSIC, useStore, type Node } from './store.ts'
19
+ import { UNPLACED } from './hash.ts'
20
+ import type { Bundle, CaptureRecord, Step, View } from '../../server/jam/types.ts'
21
+ import { forgetHeard, RATE, setWordsListener, voiceBegin, voiceDrop, voiceEnd } from './jam-voice.ts'
22
+ import { touchedFrames } from '../../shared/capture-frames.ts'
23
+ import { onStageSize, stageSize } from './stage-size.ts'
24
+
25
+ const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
26
+ const now = () => performance.timeOrigin + performance.now()
27
+ const rand = (n = 6) => Math.random().toString(36).slice(2, 2 + n).padEnd(n, '0')
28
+ /** One recorder answers a flush within this; one that does not is noted in the record. */
29
+ const FLUSH_MS = 500
30
+ const PROBE_MS = 500
31
+ /** A picture is a render on the server: two at once in a cold browser on a busy Mac (a model downloading,
32
+ * words being transcribed) took 5-6 s in a trial, so the page waits long enough not to throw a good one away. */
33
+ const PICTURE_MS = 20_000
34
+ const MAX_PICTURES = 12
35
+
36
+ // ---- mounted instances: one per canvas node, and the play stage ------------------------------------
37
+
38
+ interface Instance { key: string; iframe: HTMLIFrameElement; nonce?: string; doc?: Document | null; captureDoc?: string }
39
+ const instances = new Map<string, Instance>()
40
+ const post = (inst: Instance, msg: unknown) => { try { inst.iframe.contentWindow?.postMessage(msg, location.origin) } catch { /* gone */ } }
41
+ /** Is this message from the document the instance bound to? Checked on EVERY message: a document
42
+ * replaced since - even before its `load` fired - is dropped. */
43
+ const current = (inst: Instance) => !!inst.doc && inst.iframe.contentDocument === inst.doc
44
+
45
+ /** The instance's iframe fired `load` - a new document: nothing from it is accepted until it answers
46
+ * a hello carrying the nonce sent now, while that exact Document is still current. */
47
+ export function frameLoaded(key: string, iframe: HTMLIFrameElement | null) {
48
+ if (!iframe) return
49
+ const inst: Instance = { key, iframe, nonce: `n-${rand(10)}`, doc: iframe.contentDocument }
50
+ instances.set(key, inst)
51
+ post(inst, { type: 'sh:capture-hello', nonce: inst.nonce })
52
+ }
53
+ export function frameGone(key: string) { instances.delete(key) }
54
+
55
+ /** A frame (or the stage) became ready: tell it whether a capture records, and the keys owned now. */
56
+ export function frameReady(key: string) {
57
+ const inst = instances.get(key)
58
+ if (!inst) return
59
+ // a recorder installed after `load` (the stage mounts late) missed the hello: ask again, while the
60
+ // Document the hello was bound to is still the one in the iframe
61
+ if (inst.nonce && current(inst)) post(inst, { type: 'sh:capture-hello', nonce: inst.nonce })
62
+ const cur = useJamCapture.getState().current
63
+ if (cur) post(inst, { type: 'sh:capture', id: cur, on: true })
64
+ post(inst, { type: 'sh:keys', owned: ownedNow })
65
+ }
66
+
67
+ // ---- owned keys, mirrored into every frame ------------------------------------------------------------
68
+
69
+ let ownedNow: string[] = []
70
+ /** The keys the shell owns right now (`[Ctrl+][Meta+][Alt+][Shift+]key`), posted to every instance on
71
+ * change: a frame consumes them itself (before a focused button sees ⏎) and forwards them. */
72
+ export function setOwnedKeys(keys: string[]) {
73
+ const next = [...new Set(keys)].sort()
74
+ if (next.join() === ownedNow.join()) return
75
+ ownedNow = next
76
+ for (const inst of instances.values()) post(inst, { type: 'sh:keys', owned: ownedNow })
77
+ }
78
+
79
+ // ---- the captures -------------------------------------------------------------------------------------
80
+
81
+ export interface Point { n: number; key: string; x: number; y: number } // a numbered point, in frame-local px
82
+ interface Cap {
83
+ id: string
84
+ state: 'recording' | 'draining'
85
+ board: string
86
+ t0: number
87
+ steps: (Step & { seq?: number; src?: string })[]
88
+ seen: Set<string> // `${instance}|${captureDoc}|${seq}` - dedupe
89
+ points: Point[]
90
+ pictures: string[]
91
+ probes: number // probe answers still out
92
+ shots: number // picture requests still out
93
+ shotFrames: string[] // frames pictured (or being pictured) in it: an automatic picture is taken once per frame
94
+ endShot?: boolean // its end pictures were asked for (once its steps were all in)
95
+ inherited?: string[] // Resume: the frames the capture it continues was about (its card's)
96
+ endSizes?: Record<string, { w: number; h: number; play?: true }> // the sizes as they were at E (what it was about, then)
97
+ endNodes?: { key: string; frame: string; w: number; h: number; visible: boolean }[] // every instance at E (a step answering late is sized by these)
98
+ sizes: Record<string, { w: number; h: number; play?: true }> // each frame's size when it was last touched (`play`: on the stage's device)
99
+ keys: Record<string, string> // each frame's instance last touched (a frame can sit on a board twice)
100
+ sizedAt: Record<string, number> // when the touch that sized each frame happened (a late answer of an older one is ignored)
101
+ hearing: boolean // its words are still coming (the microphone's `final` not in)
102
+ flushWait: Map<string, string> // instance -> the captureDoc whose flush we wait for
103
+ reviewing?: { card: string; batch: string; rev: number }
104
+ /** Resume: the draft this capture continues, and when recording resumed */
105
+ resumes?: { id: string; at: number }
106
+ /** the Jam session it was made in (Part 5) */
107
+ session?: string
108
+ }
109
+
110
+ interface CaptureState {
111
+ /** the capture recording now */
112
+ current: string | null
113
+ caps: Record<string, Cap>
114
+ /** the notes card: open, and the text not yet added (kept until the capture ends) */
115
+ noteOpen: boolean
116
+ noteDraft: string
117
+ /** a number that changes on every capture change - for components to redraw (timer, counts) */
118
+ tick: number
119
+ /** Start one - never while one records (it says so instead) */
120
+ /** `session`: the session it belongs to, when the caller knows it before the queue shows it (Start) */
121
+ start(reviewing?: Cap['reviewing'], session?: string): void
122
+ end(): void
123
+ drop(): void
124
+ note(text: string): void
125
+ setNoteOpen(open: boolean): void
126
+ setNoteDraft(text: string): void
127
+ picture(frame?: string): void
128
+ /** the drafts sealed, in order - their read-backs open when capturing stops */
129
+ sealed: { id: string; card?: { id: string; rev: number } }[]
130
+ /** sealed captures the server does not hold yet (kept, sent again until it takes them) */
131
+ unsent: string[]
132
+ /** Continue a draft that ended too soon: its record is loaded and recording goes on from where it
133
+ * stopped, under a new id that takes the draft's place when it seals. Dropping it leaves the draft. */
134
+ resume(draft: string, ready?: () => Promise<boolean>): Promise<boolean>
135
+ /** drafts being continued right now (recording, sealing or waiting to send) - the lane hides them */
136
+ resuming: string[]
137
+ /** the draft whose Resume is settling (its edits saving, its record loading): its read-back's words are
138
+ * locked meanwhile, so nothing typed can race the start - set by the caller (resumeDraft) before its
139
+ * first wait, cleared when the Resume is over */
140
+ settling: string | null
141
+ /** the capture ended last (E): its read-back is the one that opens, whatever seals first */
142
+ lastEnded: string | null
143
+ }
144
+
145
+ const mutate = (fn: (s: CaptureState) => void) => useJamCapture.setState((s) => { fn(s); return { caps: { ...s.caps }, tick: s.tick + 1 } })
146
+ const capOf = (id: string): Cap | undefined => useJamCapture.getState().caps[id]
147
+
148
+ /** Add a step to a capture (in place; the timeline is sorted at the seal, by `at` then `seq`). */
149
+ function addStep(id: string, step: Step & { seq?: number; src?: string }, keys?: string[], auto = false) {
150
+ mutate((s) => { const c = s.caps[id]; if (c) { c.steps.push(step); sample(c, step, keys, auto) } })
151
+ }
152
+ /** The stage laid out again (a resize, a device, Fill, a document's width): the frame on it, while a capture records,
153
+ * is measured as it is now - the last measurement before it leaves the stage is the one kept. */
154
+ if (typeof window !== 'undefined') onStageSize(() => {
155
+ const id = useJamCapture.getState().current
156
+ const st = useStore.getState()
157
+ if (!id || !st.play || st.play.at !== stageSize.at) return
158
+ mutate((s) => { const c = s.caps[id]; if (c && c.state === 'recording') c.sizes[stageSize.at] = { w: stageSize.w, h: stageSize.h, play: true } })
159
+ })
160
+ const sampleSize = sample // (the watcher has a `sample` of its own)
161
+ /** Leaving play selects the frame it ended on: that selection is the shell's, not a touch (until then) */
162
+ let playLeftAt = 0
163
+ /** A frame's size on screen now: in play the stage's device, on the canvas its node (the one in view). */
164
+ function sizeNow(f: string, key?: string): { w: number; h: number; play?: true } | undefined {
165
+ const st = useStore.getState()
166
+ if (st.play) {
167
+ if (st.play.at !== f) return undefined
168
+ // the stage as play last laid it out (a document's reading width, a slide's stage, the window when it fills);
169
+ // before play has laid this screen out, the same rules play follows: a slide's own stage, the window, the preset
170
+ if (stageSize.at === f && stageSize.w > 0 && stageSize.h > 0) return { w: stageSize.w, h: stageSize.h, play: true }
171
+ const entry = st.manifest?.frames.find((x) => x.id === f)
172
+ const slide = (entry && slideSize(entry, CONFIG.viewports)) ?? (st.play.slides ? SLIDE_INTRINSIC : null)
173
+ if (slide) return { w: Math.round(slide.width), h: Math.round(slide.height), play: true }
174
+ if (st.play.device === 'fill') return { w: window.innerWidth, h: window.innerHeight, play: true }
175
+ const v = CONFIG.viewports[st.play.device]
176
+ return v ? { w: Math.round(v.width), h: Math.round(v.height), play: true } : undefined
177
+ }
178
+ // the instance touched first; else the one in view; else any
179
+ const n = (key ? st.nodes.find((x) => x.key === key && x.frame === f) : undefined) ?? visibleNodes().find((x) => x.frame === f) ?? st.nodes.find((x) => x.frame === f)
180
+ return n && n.w > 0 && n.h > 0 ? { w: Math.round(n.w), h: Math.round(n.h) } : undefined
181
+ }
182
+ /** A frame as it was at E (a capture finishing): its touched instance, else the one then in view, else any. */
183
+ function sizeAtEnd(c: Cap, f: string, key?: string): { w: number; h: number; play?: true } | undefined {
184
+ const ns = (c.endNodes ?? []).filter((n) => n.frame === f)
185
+ // a touch of a canvas instance (it names one): that instance as it was at E - over a size seen on the stage
186
+ const touched = key ? ns.find((x) => x.key === key) : undefined
187
+ if (touched && touched.w > 0 && touched.h > 0) return { w: touched.w, h: touched.h }
188
+ if (c.sizes[f]?.play) return c.sizes[f]
189
+ const n = ns.find((x) => x.key === c.keys[f]) ?? ns.find((x) => x.visible) ?? ns[0]
190
+ return n && n.w > 0 && n.h > 0 ? { w: n.w, h: n.h } : undefined
191
+ }
192
+ /** Each frame a step touches, at the size it is as it is touched (a frame visited on a phone in play keeps the
193
+ * phone's size, wherever the capture ends). */
194
+ function sample(c: Cap, step: { at?: number; event: string; frame?: string; to?: string; frames?: string[]; src?: string; view?: { frames?: string[] } }, keys?: string[], auto = false) {
195
+ const nodes = useStore.getState().nodes
196
+ // (a view of one frame - the stage as play opens, a frame zoomed to - is a frame it is about)
197
+ const viewed = step.event === 'view' && step.view?.frames?.length === 1 ? step.view.frames : []
198
+ for (const f of [step.frame, step.to, ...(step.event === 'select' ? step.frames ?? [] : []), ...viewed]) {
199
+ if (!f) continue
200
+ // a touch older than the one that sized this frame (its answer came late) changes nothing
201
+ if (step.at !== undefined && (c.sizedAt[f] ?? -Infinity) > step.at) continue
202
+ // the instance it came from (a step's own frame document), or the selected one showing this frame
203
+ const k = [step.src, ...(keys ?? [])].find((x) => x && nodes.some((n) => n.key === x && n.frame === f))
204
+ if (k) c.keys[f] = k
205
+ const z = c.state === 'draining' && c.endNodes ? sizeAtEnd(c, f, k) : sizeNow(f, c.keys[f])
206
+ // a view (play left, a fit) is not a touch: what was seen on the stage keeps the stage's size until the frame is
207
+ // used on the canvas
208
+ if (z && !((auto || step.event === 'view') && c.sizes[f]?.play && !z.play)) {
209
+ c.sizes[f] = z
210
+ if (step.at !== undefined) c.sizedAt[f] = step.at
211
+ // a step answering after E (a hover in flight) was a touch at E: the size kept for E follows the instance it
212
+ // touched - for the seal and the end pictures alike
213
+ if (c.state === 'draining' && c.endSizes && !auto && step.event !== 'view') c.endSizes[f] = z
214
+ }
215
+ }
216
+ }
217
+
218
+ const frameIdOf = (key: string): string | undefined => useStore.getState().nodes.find((n) => n.key === key)?.frame
219
+ /** The view: in play the stage; on the canvas the frames on screen - or, at the start only, the frames
220
+ * selected (a selection is the capture's focus, not what it keeps seeing). */
221
+ const viewNow = (focus = false): View => {
222
+ const s = useStore.getState()
223
+ // in play or slides the surface is the stage: its screen, its device, its theme
224
+ if (s.play) {
225
+ const vp = CONFIG.viewports[s.play.device]
226
+ return { board: s.board, frames: [s.play.at], theme: s.play.theme, viewport: s.play.device, ...(vp ? { width: vp.width, height: vp.height } : {}), mode: s.play.slides ? 'slides' : 'play' }
227
+ }
228
+ const sel = s.selection.map((k) => s.nodes.find((n) => n.key === k)).filter((n): n is Node => !!n)
229
+ const shown = focus && sel.length ? sel : visibleNodes()
230
+ const first = shown[0]
231
+ return {
232
+ board: s.board, frames: [...new Set(shown.map((n) => n.frame))], theme: first?.theme ?? s.viewTheme,
233
+ ...(first ? { width: Math.round(first.w), height: Math.round(first.h) } : {}),
234
+ zoom: Math.round((s.scale ?? 1) * 100) / 100, mode: s.interact ? 'interact' : 'canvas',
235
+ }
236
+ }
237
+
238
+ /** The nodes actually on screen now - the canvas's instances whose box meets the viewport, left of
239
+ * nothing that covers it (the panel and the lane leave their own room). */
240
+ export function visibleNodes(): Node[] {
241
+ const s = useStore.getState()
242
+ const W = window.innerWidth, H = window.innerHeight
243
+ const out: Node[] = []
244
+ for (const n of s.nodes) {
245
+ if (n.missing) continue
246
+ const el = document.querySelector(`.sh-node[data-node="${CSS.escape(n.key)}"]`)
247
+ const r = el?.getBoundingClientRect()
248
+ if (r && r.right > 0 && r.bottom > 0 && r.left < W && r.top < H) out.push(n)
249
+ }
250
+ return out.slice(0, 20)
251
+ }
252
+
253
+ // ---- UI steps: the shell's own, written the moment they happen, only while recording ----------------
254
+
255
+ let unwatch: (() => void) | null = null
256
+ function watchUi() {
257
+ unwatch?.()
258
+ // the frames in view, once the camera has settled (two looks a beat apart agree): a pan to another
259
+ // frame, described without a click, still names it
260
+ const sig = () => { const v = viewNow(); return `${(v.frames ?? []).join()}@${Math.round((v.zoom ?? 1) * 20) / 20}` } // frames and zoom
261
+ let lastView = sig()
262
+ let sample = lastView
263
+ const settle = setInterval(() => {
264
+ const id = useJamCapture.getState().current
265
+ if (!id || useStore.getState().play) return
266
+ const now_ = sig()
267
+ if (now_ === sample && now_ !== lastView) { lastView = now_; addStep(id, { at: now(), event: 'view', view: viewNow() }) }
268
+ sample = now_
269
+ }, 600)
270
+ let prev = useStore.getState()
271
+ const unsub = useStore.subscribe((s) => {
272
+ const id = useJamCapture.getState().current
273
+ const p = prev
274
+ prev = s
275
+ if (!id) return
276
+ const at = now()
277
+ if (p.play && !s.play) playLeftAt = performance.now()
278
+ if (s.selection.join() !== p.selection.join() && s.selection.length) {
279
+ addStep(id, { at, event: 'select', frames: [...new Set(s.selection.map((k) => frameIdOf(k)).filter((f): f is string => !!f))] }, s.selection, performance.now() - playLeftAt < 200)
280
+ }
281
+ for (const n of s.nodes) {
282
+ const o = p.nodes.find((x) => x.key === n.key)
283
+ if (!o) continue
284
+ // a device change: the node took a preset's size (its width names the viewport)
285
+ if (o.w !== n.w && n.sizeMode === 'device') {
286
+ const vp = Object.entries(CONFIG.viewports).find(([, v]) => v.width === Math.round(n.w))
287
+ addStep(id, { at, frame: n.frame, event: 'device', viewport: vp?.[0] ?? 'custom', width: Math.round(n.w), height: Math.round(n.h), src: n.key })
288
+ } else if ((Math.round(o.w) !== Math.round(n.w) || Math.round(o.h) !== Math.round(n.h)) && n.sizeMode !== 'device' && s.resized !== p.resized && s.resized?.key === n.key) {
289
+ // (a person resized it - never a measurement: only a resize sets `resized`)
290
+ // dragged to a size of its own: a step like a device, and the size it is about now - one step per drag (a
291
+ // drag moves it on every frame: the last step of it, still going, takes the new size)
292
+ const lastSteps = capOf(id)?.steps ?? []
293
+ const last = lastSteps[lastSteps.length - 1] as (Step & { src?: string }) | undefined
294
+ if (last && last.event === 'device' && last.src === n.key && last.viewport === 'custom' && at - last.at < 1500) {
295
+ mutate((st) => { const c = st.caps[id]; const l = c?.steps[c.steps.length - 1] as (Step & { src?: string; width?: number; height?: number }) | undefined; if (c && l) { l.width = Math.round(n.w); l.height = Math.round(n.h); l.at = at; sampleSize(c, l) } })
296
+ } else addStep(id, { at, frame: n.frame, event: 'device', viewport: 'custom', width: Math.round(n.w), height: Math.round(n.h), src: n.key })
297
+ }
298
+ if (o.theme !== n.theme && s.viewTheme === p.viewTheme && (n.theme === 'light' || n.theme === 'dark')) addStep(id, { at, frame: n.frame, event: 'theme', theme: n.theme, src: n.key })
299
+ }
300
+ if (s.viewTheme !== p.viewTheme && (s.viewTheme === 'light' || s.viewTheme === 'dark')) addStep(id, { at, event: 'theme', theme: s.viewTheme })
301
+ // play: the stage's device and theme through the shell's controls (its screen comes from the stage)
302
+ if (s.play && p.play) {
303
+ if (s.play.theme !== p.play.theme && (s.play.theme === 'light' || s.play.theme === 'dark')) addStep(id, { at, frame: s.play.at, event: 'theme', theme: s.play.theme })
304
+ if (s.play.device !== p.play.device) { const vp = CONFIG.viewports[s.play.device]; addStep(id, { at, frame: s.play.at, event: 'device', viewport: s.play.device, width: vp?.width ?? 0, height: vp?.height ?? 0 }) }
305
+ }
306
+ // a screen change the SHELL made (arrows, the walker, a variant): the stage reports its own
307
+ // navigation itself, so a change it reported (sh:stage-at) is not recorded twice
308
+ if (s.play && p.play && s.play.at !== p.play.at) {
309
+ if (stageNav !== s.play.at) screenStep(id, at, s.play.at)
310
+ }
311
+ if (!!s.play !== !!p.play) addStep(id, { at, event: 'view', view: viewNow() })
312
+ if (!!s.interact !== !!p.interact) addStep(id, { at, ...(s.interact || p.interact ? { frame: frameIdOf((s.interact ?? p.interact)!), src: (s.interact ?? p.interact)! } : {}), event: 'interact', on: !!s.interact })
313
+ })
314
+ unwatch = () => { unsub(); clearInterval(settle) }
315
+ }
316
+
317
+ /** Words heard for a capture (recording or still draining): one `words` step per phrase, at its first
318
+ * word, each word with its time on the capture's clock (sample 0 = the capture's start). */
319
+ setWordsListener((capture, words) => {
320
+ const c = capOf(capture)
321
+ if (!c || !words.length) return
322
+ const ms = (sample: number) => c.t0 + (sample / RATE) * 1000
323
+ addStep(capture, { at: ms(words[0].at), event: 'words', text: words.map((w) => w.w).join(' '), words: words.map((w) => ({ w: w.w, at: ms(w.at) })) })
324
+ })
325
+
326
+ /** A copy happened (path or image, of which frame) - never what the clipboard holds. */
327
+ export function recordCopy(what: 'path' | 'image', frame: string) {
328
+ const id = useJamCapture.getState().current
329
+ if (id) addStep(id, { at: now(), frame, event: 'copied', what })
330
+ }
331
+
332
+ // ---- trail from the frames ---------------------------------------------------------------------------
333
+
334
+ /** A frame or the stage posted something about a capture. `key` is the instance it came from. Returns
335
+ * true when the message was a capture message (handled or dropped). */
336
+ export function onFrameMessage(key: string, data: Record<string, any>): boolean {
337
+ const t = data.type
338
+ if (t !== 'sh:capture-hello' && t !== 'sh:trail' && t !== 'sh:probe' && t !== 'sh:capture-flushed') return false
339
+ const inst = instances.get(key)
340
+ if (!inst || !current(inst)) return true
341
+ if (t === 'sh:capture-hello') {
342
+ if (inst.nonce && data.nonce === inst.nonce && typeof data.captureDoc === 'string') {
343
+ inst.captureDoc = data.captureDoc; inst.nonce = undefined
344
+ // bound: tell this document what it may have missed (a frame can be ready before its load fires)
345
+ frameReady(key)
346
+ }
347
+ return true
348
+ }
349
+ if (!inst.captureDoc || data.captureDoc !== inst.captureDoc) return true
350
+ if (t === 'sh:probe') { probeAnswered(key, data); return true }
351
+ const cap = typeof data.id === 'string' ? capOf(data.id) : undefined
352
+ if (!cap) return true // a capture neither recording nor draining
353
+ if (t === 'sh:capture-flushed') {
354
+ if (cap.flushWait.get(key) === data.captureDoc) { mutate((s) => { s.caps[cap.id]?.flushWait.delete(key) }); trySeal(cap.id) }
355
+ return true
356
+ }
357
+ const dedupe = `${key}|${data.captureDoc}|${data.seq}`
358
+ if (cap.seen.has(dedupe)) return true
359
+ cap.seen.add(dedupe)
360
+ const at = Number(data.at)
361
+ if (!Number.isFinite(at)) return true
362
+ const frame = typeof data.frame === 'string' ? data.frame : frameIdOf(key)
363
+ const base = { at, seq: Number(data.seq) || 0, src: key, ...(frame ? { frame } : {}) }
364
+ const mode = data.mode === 'play' ? 'play' : data.mode === 'canvas' ? 'canvas' : 'interact'
365
+ switch (data.event) {
366
+ case 'pick': case 'click': case 'hover': {
367
+ const pt = data.point && Number.isFinite(data.point.x) ? { x: data.point.x, y: data.point.y } : null
368
+ const n = data.event === 'hover' ? undefined : cap.points.length + 1
369
+ mutate((s) => {
370
+ const c = s.caps[cap.id]
371
+ if (!c) return
372
+ if (n && pt) c.points.push({ n, key, x: pt.x, y: pt.y })
373
+ c.steps.push({ ...base, event: data.event, bundle: cleanBundle(data.bundle), mode, ...(n ? { point: n } : {}) }); sample(c, { at: base.at, event: data.event, frame: base.frame, src: key })
374
+ })
375
+ if (data.event === 'pick' && frame) shoot(cap.id, frame, 'pick', key === 'stage' ? undefined : key)
376
+ return true
377
+ }
378
+ case 'field': addStep(cap.id, { ...base, event: 'field', bundle: cleanBundle(data.bundle), value: String(data.value ?? '') }); return true
379
+ case 'screen': screenStep(cap.id, at, String(data.to ?? ''), base.seq); return true
380
+ case 'scroll': if (Number.isFinite(Number(data.y))) addStep(cap.id, { ...base, event: 'scroll', y: Number(data.y) }); return true
381
+ default: return true
382
+ }
383
+ }
384
+
385
+ /** A frame's bundle (`{ el: { semantics: { tag, quote, testId, ariaLabel, role }, cssPath, source } }`,
386
+ * safeBundle) as the record keeps it: flat, strings only - a masked one keeps its '•••'. */
387
+ /** One screen change - each navigation once, by whoever made it (revisits are their own lines). */
388
+ function screenStep(id: string, at: number, to: string, seq?: number) {
389
+ if (!capOf(id) || !to) return
390
+ addStep(id, { at, frame: to, event: 'screen', to, ...(seq !== undefined ? { seq } : {}) })
391
+ }
392
+ /** The stage moved itself to `at` (sh:stage-at): its recorder has the step; the shell's play state
393
+ * follows without a second line. */
394
+ let stageNav: string | null = null
395
+ /** Run the play-state update the stage's own navigation causes: during it (and only during it) the
396
+ * shell does not record a second line. */
397
+ export function stageNavigated(at: string, update: () => void) { stageNav = at; try { update() } finally { stageNav = null } }
398
+
399
+ const cleanBundle = (b: unknown): Bundle => {
400
+ const o = (b && typeof b === 'object' ? b : {}) as Record<string, any>
401
+ const el = (o.el && typeof o.el === 'object' ? o.el : o) as Record<string, any>
402
+ const sem = (el.semantics && typeof el.semantics === 'object' ? el.semantics : el) as Record<string, unknown>
403
+ const out: Bundle = {}
404
+ for (const k of ['tag', 'quote', 'testId', 'ariaLabel', 'role'] as const) if (typeof sem[k] === 'string') out[k] = sem[k] as string
405
+ for (const k of ['cssPath', 'source'] as const) if (typeof el[k] === 'string') out[k] = el[k] as string
406
+ return out
407
+ }
408
+
409
+ // ---- canvas-mode clicks and hovers: the overlay keeps the click and asks the frame ------------------
410
+
411
+ const probes = new Map<string, { cap: string; key: string; at: number; event: 'click' | 'hover'; x: number; y: number; timer: ReturnType<typeof setTimeout>; selectStep?: Step }>()
412
+
413
+ const local = (iframe: HTMLIFrameElement, clientX: number, clientY: number) => {
414
+ const r = iframe.getBoundingClientRect()
415
+ const sx = iframe.clientWidth ? r.width / iframe.clientWidth : 1
416
+ const sy = iframe.clientHeight ? r.height / iframe.clientHeight : 1
417
+ return { x: (clientX - r.left) / sx, y: (clientY - r.top) / sy }
418
+ }
419
+
420
+ function probe(key: string, event: 'click' | 'hover', clientX: number, clientY: number, pressAt?: number) {
421
+ const id = useJamCapture.getState().current
422
+ const inst = instances.get(key)
423
+ if (!id || !inst || !current(inst)) return
424
+ const at = now()
425
+ const { x, y } = local(inst.iframe, clientX, clientY)
426
+ const req = `r-${rand(8)}`
427
+ // one act, one line: the select this very click made (the overlay selects on pointerdown) is folded
428
+ // into it when it answers - found now, by reference, whatever lands in the timeline meanwhile
429
+ const frameNow = frameIdOf(key)
430
+ const capNow = capOf(id)
431
+ // the select made between this press and its release (the overlay selects on pointerdown) - however
432
+ // long the press; a selection made before the press is its own line
433
+ const selectStep = event === 'click' && capNow && pressAt !== undefined ? [...capNow.steps].reverse().find((x) => x.event === 'select' && x.at >= pressAt - 5 && x.at <= at && x.frames.length === 1 && x.frames[0] === frameNow) : undefined
434
+ const timer = setTimeout(() => {
435
+ probes.delete(req)
436
+ mutate((s) => { const c = s.caps[id]; if (c) { c.probes -= 1; c.steps.push({ at, frame: frameIdOf(key), event: 'missing', what: `the ${event} at ${Math.round(x)},${Math.round(y)} never answered` }) } })
437
+ trySeal(id)
438
+ }, PROBE_MS)
439
+ probes.set(req, { cap: id, key, at, event, x, y, timer, selectStep })
440
+ mutate((s) => { const c = s.caps[id]; if (c) c.probes += 1 })
441
+ post(inst, { type: 'sh:probe', id, req, x, y })
442
+ }
443
+
444
+ function probeAnswered(key: string, data: Record<string, any>) {
445
+ const p = probes.get(String(data.req ?? ''))
446
+ if (!p || p.key !== key) return
447
+ probes.delete(String(data.req))
448
+ clearTimeout(p.timer)
449
+ const frame = frameIdOf(key)
450
+ mutate((s) => {
451
+ const c = s.caps[p.cap]
452
+ if (!c) return
453
+ c.probes -= 1
454
+ if (!data.bundle) return
455
+ const n = p.event === 'click' ? c.points.length + 1 : undefined
456
+ if (n) c.points.push({ n, key, x: p.x, y: p.y })
457
+ // one act, one line: a click that also selected its frame is one click that names the selection
458
+ const i = p.selectStep ? c.steps.indexOf(p.selectStep as (typeof c.steps)[number]) : -1
459
+ const selects = i >= 0
460
+ if (selects) c.steps.splice(i, 1)
461
+ c.steps.push({ at: p.at, ...(frame ? { frame } : {}), event: p.event, bundle: cleanBundle(data.bundle), mode: 'canvas', ...(n ? { point: n } : {}), ...(selects ? { selects: true } : {}) }); sample(c, { at: p.at, event: p.event, frame, src: key })
462
+ })
463
+ trySeal(p.cap)
464
+ // a click on a field: you mean to type there - the frame turns interactive and the caret goes in the
465
+ // field, so the letters you type are the field's and never end, restart or drop the capture
466
+ if (p.event === 'click' && data.field === true && useJamCapture.getState().current === p.cap) focusField(p.key, p.x, p.y)
467
+ }
468
+
469
+ function focusField(key: string, x: number, y: number) {
470
+ const st = useStore.getState()
471
+ if (st.play || !st.nodes.some((n) => n.key === key)) return
472
+ if (st.interact !== key) st.setInteract(key)
473
+ // after the overlay has stepped aside (interact removes it): focus the iframe, then the field in it
474
+ requestAnimationFrame(() => requestAnimationFrame(() => {
475
+ const inst = instances.get(key)
476
+ if (!inst || !current(inst)) return
477
+ try { inst.iframe.focus() } catch { /* gone */ }
478
+ post(inst, { type: 'sh:focus-at', x, y })
479
+ }))
480
+ }
481
+
482
+ /** The canvas overlay saw a click (not a drag) on a node while a capture records. */
483
+ export function canvasClick(key: string, clientX: number, clientY: number, pressAt?: number) { cancelDwell(); probe(key, 'click', clientX, clientY, pressAt) }
484
+ /** When the press began, on the capture clock - the overlay calls this on pointerdown. */
485
+ export const pressNow = (): number => now()
486
+
487
+ let dwell: { key: string; cap: string; x: number; y: number; timer: ReturnType<typeof setTimeout> } | null = null
488
+ /** A capture ending (or dropped) takes its pending hover with it: a dwell belongs to one capture. */
489
+ const cancelDwell = () => { if (dwell) { clearTimeout(dwell.timer); dwell = null } }
490
+ let lastHover = 0
491
+ /** The pointer moved over a node in canvas mode: a hold of 0.8 s without moving past 4 px is a hover
492
+ * (at most one every 2 s); moving or leaving cancels it. */
493
+ export function canvasPointer(key: string | null, clientX = 0, clientY = 0) {
494
+ if (dwell && (!key || key !== dwell.key || Math.hypot(clientX - dwell.x, clientY - dwell.y) > 4)) { clearTimeout(dwell.timer); dwell = null }
495
+ const cur = useJamCapture.getState().current
496
+ if (!key || dwell || !cur) return
497
+ dwell = { key, cap: cur, x: clientX, y: clientY, timer: setTimeout(() => {
498
+ const d = dwell
499
+ dwell = null
500
+ if (!d || d.cap !== useJamCapture.getState().current || performance.now() - lastHover < 2_000) return
501
+ lastHover = performance.now()
502
+ probe(d.key, 'hover', d.x, d.y)
503
+ }, 800) }
504
+ pointerAt = { key, at: performance.now() }
505
+ }
506
+ /** the node under the pointer lately - where `I` shoots */
507
+ let pointerAt: { key: string; at: number } | null = null
508
+
509
+ // ---- pictures ------------------------------------------------------------------------------------------
510
+
511
+ function shoot(id: string, frame: string, why: 'key' | 'pick' | 'end', key?: string) {
512
+ const c = capOf(id)
513
+ if (!c || c.pictures.length + c.shots >= MAX_PICTURES) return
514
+ // each picture is a render on the server, and the capture waits for it as it ends: a point or the end
515
+ // pictures a frame once - only I asks for another
516
+ if (why !== 'key' && c.shotFrames.includes(frame)) return
517
+ // the instance pictured is the one this frame is about (its size for the run's pictures)
518
+ // (an I picture is a touch at this instant: a hover from before it, answering late, never overrides it)
519
+ const touchAt = now()
520
+ mutate((s) => { const x = s.caps[id]; if (x) { if (!x.shotFrames.includes(frame)) x.shotFrames.push(frame); if (why === 'key') sample(x, { at: touchAt, event: 'picture', frame, src: key }) } })
521
+ const at = now()
522
+ // the instance it was seen in: its size (a responsive defect is shot as seen) and its theme
523
+ const st = useStore.getState()
524
+ const n = (key ? st.nodes.find((x) => x.key === key && x.frame === frame) : undefined) ?? st.nodes.find((x) => x.frame === frame)
525
+ // as it was seen: on the stage's device now, or as it was on the stage (left play since), or its node
526
+ const seen = c.sizes[frame]
527
+ // after E: as the frame was at E (a resize while it finishes is not part of it); else as it is seen now
528
+ const atEnd = c.state === 'draining' ? c.endSizes?.[frame] ?? (c.endNodes ? sizeAtEnd(c, frame) : undefined) ?? seen : undefined
529
+ const onStage = st.play && st.play.at === frame ? sizeNow(frame) : undefined
530
+ const size = atEnd ? { width: atEnd.w, height: atEnd.h } : onStage ? { width: onStage.w, height: onStage.h } : seen?.play && why !== 'key' ? { width: seen.w, height: seen.h } : n ? { width: n.w, height: n.h } : undefined
531
+ const theme = st.play && st.play.at === frame ? st.play.theme : n?.theme ?? st.viewTheme
532
+ mutate((s) => { const x = s.caps[id]; if (x) x.shots += 1 })
533
+ const done = (pid: string | null, late: boolean) => {
534
+ mutate((s) => {
535
+ const x = s.caps[id]
536
+ if (!x) return
537
+ x.shots -= 1
538
+ if (pid) { x.pictures.push(pid); x.steps.push({ at, frame, event: 'picture', id: pid, why }) }
539
+ else x.steps.push({ at, frame, event: 'missing', what: `no picture of ${frame} - ${late ? `it took over ${PICTURE_MS / 1000} s` : 'the render failed'}` })
540
+ })
541
+ trySeal(id)
542
+ }
543
+ const ctl = new AbortController()
544
+ const timer = setTimeout(() => ctl.abort(), PICTURE_MS)
545
+ // settled exactly once - a picture, or a missing one - whatever fails: the request, its body, the abort
546
+ let settled = false
547
+ const finish = (pid: string | null) => { if (settled) return; settled = true; clearTimeout(timer); done(pid, ctl.signal.aborted) }
548
+ fetch(`${ROUTE}/api/jam/picture`, {
549
+ method: 'POST', signal: ctl.signal, headers: { 'content-type': 'application/json', 'x-mv-c': csrf() },
550
+ body: JSON.stringify({ capture: id, frame, theme, ...(size ? { w: Math.round(size.width), h: Math.round(size.height) } : {}) }),
551
+ }).then(async (r) => (r.ok ? ((await r.json()) as { id?: string }).id ?? null : null))
552
+ .catch(() => null)
553
+ .then((pid) => finish(typeof pid === 'string' ? pid : null))
554
+ }
555
+
556
+ // ---- start, end, seal ----------------------------------------------------------------------------------
557
+
558
+ const broadcast = (msg: unknown) => { for (const inst of instances.values()) post(inst, msg) }
559
+
560
+ /** The session is being wrapped up (its talk flushing, its record being written): no capture starts. */
561
+ let sessionEnding = false
562
+ export const setSessionEnding = (on: boolean) => { sessionEnding = on }
563
+
564
+ /** A capture of a session tells the server it is open - recording, sealing, waiting to send - and renews
565
+ * that every 20 s until it lands or is dropped: the session's record waits for it, whatever tab ends it. */
566
+ const openOnServer = new Map<string, { session: string; timer: ReturnType<typeof setInterval> }>()
567
+ const tellOpen = (capture: string, session: string, on: boolean) => {
568
+ void fetch(`${ROUTE}/api/jam/capture-open`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() }, body: JSON.stringify({ capture, session, on }) })
569
+ .then(async (r) => { if (on && r.status === 409 && (await r.json().catch(() => null))?.ended) leftOutOfSession(capture) }, () => {})
570
+ }
571
+ /** The server had already written the session's record (in another tab) when it heard of this capture: it is
572
+ * not in that record - it goes on as a capture of its own, and you are told. */
573
+ const toldOutside = new Set<string>()
574
+ function leftOutOfSession(capture: string) {
575
+ // said once, whichever answer says it first (the registration's, or the upload's) - whatever order they come in
576
+ if (toldOutside.has(capture)) return
577
+ toldOutside.add(capture)
578
+ releaseOpen(capture, false)
579
+ useJamCapture.setState((st) => {
580
+ const c = st.caps[capture]
581
+ if (!c?.session) return {}
582
+ const { session: _gone, ...rest } = c
583
+ return { caps: { ...st.caps, [capture]: rest as Cap } }
584
+ })
585
+ useStore.getState().toast('the session ended in another tab - this capture is on its own, not in its record')
586
+ }
587
+ function holdOpen(capture: string, session: string) {
588
+ tellOpen(capture, session, true)
589
+ const timer = setInterval(() => {
590
+ const st = useJamCapture.getState()
591
+ if (st.current === capture || st.caps[capture] || st.unsent.includes(capture) || pendingUploads.has(capture)) tellOpen(capture, session, true)
592
+ else releaseOpen(capture, false)
593
+ }, 20_000)
594
+ openOnServer.set(capture, { session, timer })
595
+ }
596
+ /** Stop renewing (it landed - the server knows - or it was dropped: say so). */
597
+ function releaseOpen(capture: string, tell: boolean) {
598
+ const o = openOnServer.get(capture)
599
+ if (!o) return
600
+ clearInterval(o.timer)
601
+ openOnServer.delete(capture)
602
+ if (tell) tellOpen(capture, o.session, false)
603
+ }
604
+
605
+ /** The session running now (the queue view holds it), if any. */
606
+ let sessionNow: () => string | undefined = () => undefined
607
+ /** A card's frames as the server holds them (a resumed capture counts the ones it carries on). */
608
+ let cardFrames: (id: string) => string[] = () => []
609
+ void import('./jam-queue.ts').then(({ useJamQueue }) => {
610
+ sessionNow = () => useJamQueue.getState().session?.id
611
+ cardFrames = (id) => useJamQueue.getState().cards?.find((c) => c.id === id)?.frames ?? []
612
+ })
613
+
614
+ function begin(reviewing?: Cap['reviewing'], from?: CaptureRecord, session = sessionNow()): boolean {
615
+ const s = useStore.getState()
616
+ // checked here, as recording starts: a Resume that began loading before the session's wrap-up never
617
+ // starts recording into it
618
+ if (sessionEnding) { s.toast('the session is being wrapped up - a moment'); return false }
619
+ // a capture becomes a thread on a board: the Not on a board view takes none (as it takes no comment)
620
+ if (s.board === UNPLACED) { s.toast('captures need a board - open one first'); return false }
621
+ const id = `cap-${Date.now()}-${rand(6)}`
622
+ const t = now()
623
+ // Resume: the draft's steps, moved up so its last step meets this instant (the pause between the two
624
+ // is not part of the capture), its pictures and its numbered points; then recording goes on
625
+ // (to just before this instant: everything carried over is strictly before `resumes.at`, the new part after)
626
+ // (the latest instant in it: a step's, or a word's inside the last phrase - every carried word stays
627
+ // before the resume)
628
+ const latest = from ? Math.max(...from.timeline.flatMap((x) => [x.at, ...(x.event === 'words' && x.words ? x.words.map((w) => w.at) : [])]), -Infinity) : 0
629
+ const shift = from && Number.isFinite(latest) ? t - 1 - latest : 0
630
+ // (a phrase's words move with it - each word keeps its place in the phrase)
631
+ const steps = from ? from.timeline.map((x) => ({ ...x, at: x.at + shift, ...(x.event === 'words' && x.words ? { words: x.words.map((w) => ({ ...w, at: w.at + shift })) } : {}) }) as Step) : []
632
+ const cap: Cap = {
633
+ id, state: 'recording', board: s.board, t0: from ? (steps[0]?.at ?? t) : t, steps, seen: new Set(),
634
+ points: steps.flatMap((x) => ('point' in x && typeof x.point === 'number' ? [{ n: x.point, key: '', x: 0, y: 0 }] : [])), pictures: from ? [...from.pictures] : [],
635
+ sizes: { ...(from?.sizes ?? {}) }, keys: {}, sizedAt: {},
636
+ probes: 0, shots: 0, shotFrames: steps.flatMap((x) => (x.event === 'picture' && x.frame ? [x.frame] : [])), hearing: false, flushWait: new Map(), ...(reviewing ? { reviewing } : {}), ...(from ? { resumes: { id: from.id, at: t }, inherited: cardFrames(from.id) } : {}),
637
+ ...(session ? { session } : {}),
638
+ }
639
+ // what is on screen and selected as it starts - a resumed one too, just after the resume (you may have
640
+ // moved to another frame in the pause: the record names it)
641
+ const at0 = from ? t + 1 : cap.t0
642
+ cap.steps.push({ at: at0, event: 'view', view: viewNow(true) })
643
+ // starting with frames selected makes them its focus (on the canvas - in play the stage is the surface)
644
+ if (!s.play && s.selection.length) cap.steps.push({ at: at0, event: 'select', frames: [...new Set(s.selection.map((k) => frameIdOf(k)).filter((f): f is string => !!f))] })
645
+ // the sizes it starts with: the stage's device in play, the selected frames on the canvas
646
+ if (s.play) { const z = sizeNow(s.play.at); if (z) cap.sizes[s.play.at] = z } else if (s.selection.length) sample(cap, cap.steps[cap.steps.length - 1] as { event: string; frames?: string[] }, s.selection)
647
+ useJamCapture.setState((st) => ({ current: id, caps: { ...st.caps, [id]: cap }, tick: st.tick + 1, ...(from ? { resuming: [...st.resuming, from.id] } : {}) }))
648
+ if (cap.session) holdOpen(id, cap.session)
649
+ broadcast({ type: 'sh:capture', id, on: true })
650
+ watchUi()
651
+ void voiceBegin(id, cap.t0) // your words, if you said yes to the microphone (spec 27 Part 4)
652
+ return true
653
+ }
654
+
655
+ /** Stop recording `id`: flush every recorder that holds a captureDoc, wait for them, for every probe
656
+ * and picture still out, then seal. */
657
+ function drain(id: string) {
658
+ const c = capOf(id)
659
+ if (!c || c.state !== 'recording') return
660
+ const s = useJamCapture.getState()
661
+ // text written in the notes card and never added is the capture's last note
662
+ const draft = s.noteDraft.trim()
663
+ mutate((st) => {
664
+ const x = st.caps[id]
665
+ if (!x) return
666
+ x.state = 'draining'
667
+ // its frames' sizes as they are at E - a resize while it finishes is not part of it; and every instance as it
668
+ // is at E, for a step that answers late (a hover still in flight names a frame then)
669
+ x.endSizes = framesSizes(x)
670
+ const vis = new Set(visibleNodes().map((n) => n.key))
671
+ x.endNodes = useStore.getState().nodes.map((n) => ({ key: n.key, frame: n.frame, w: Math.round(n.w), h: Math.round(n.h), visible: vis.has(n.key) }))
672
+ if (draft) x.steps.push({ at: now(), event: 'note', text: draft })
673
+ for (const inst of instances.values()) if (inst.captureDoc && current(inst)) x.flushWait.set(inst.key, inst.captureDoc)
674
+ })
675
+ useJamCapture.setState({ noteDraft: '', noteOpen: false })
676
+ // in play the stage is what it is about: pictured now. On the canvas the end pictures wait until every frame
677
+ // has flushed and every probe answered (trySeal) - a hover still in flight may name the frame to picture
678
+ const st = useStore.getState()
679
+ if (st.play) { mutate((s) => { const x = s.caps[id]; if (x) x.endShot = true }); shoot(id, st.play.at, 'end') }
680
+ broadcast({ type: 'sh:capture', id, on: false })
681
+ // the audio is cut at the key press, then its last words are awaited (3 s at most)
682
+ mutate((st) => { const x = st.caps[id]; if (x) x.hearing = true })
683
+ void voiceEnd(id).then((complete) => {
684
+ mutate((st) => {
685
+ const x = st.caps[id]
686
+ if (!x) return
687
+ x.hearing = false
688
+ if (!complete) x.steps.push({ at: now(), event: 'missing', what: 'words may be incomplete' })
689
+ })
690
+ trySeal(id)
691
+ })
692
+ setTimeout(() => {
693
+ mutate((st) => {
694
+ const x = st.caps[id]
695
+ if (!x || !x.flushWait.size) return
696
+ for (const k of x.flushWait.keys()) x.steps.push({ at: now(), frame: frameIdOf(k), event: 'missing', what: 'a frame never flushed' })
697
+ x.flushWait.clear()
698
+ })
699
+ trySeal(id)
700
+ }, FLUSH_MS)
701
+ trySeal(id)
702
+ }
703
+
704
+ /** The end pictures, once the timeline is whole: the frames it is about not pictured in it yet, three at most -
705
+ * each as the instance on screen shows it (a narrow, dark second copy as itself); never every frame that
706
+ * happens to be in view. None touched: the one frame it began on. Returns whether any was asked for. */
707
+ function endPictures(id: string): boolean {
708
+ const c = capOf(id)
709
+ if (!c || c.endShot) return false
710
+ mutate((s) => { const x = s.caps[id]; if (x) x.endShot = true })
711
+ const onScreen = visibleNodes()
712
+ // resumed: the new part's frames (what the part before was about was pictured then - its pictures are carried);
713
+ // none touched in a fresh capture: the one frame it began on
714
+ const since = c.resumes?.at
715
+ const touched = touchedFrames(since === undefined ? c.steps : c.steps.filter((x) => x.at >= since), undefined, false)
716
+ const frames = (touched.length || since !== undefined ? touched : touchedFrames(c.steps).slice(0, 1)).filter((f) => !c.shotFrames.includes(f)).slice(0, 3)
717
+ // each as the instance it was touched on (else the one in view)
718
+ for (const f of frames) shoot(id, f, 'end', c.keys[f] ?? onScreen.find((n) => n.frame === f)?.key)
719
+ return frames.length > 0
720
+ }
721
+
722
+ /** Each frame the capture is about, at the size it is on screen now (the instance in view, else any): a device,
723
+ * or a width you dragged it to. In play, the stage's device. Its run is pictured at these sizes. */
724
+ function framesSizes(c: Cap): Record<string, { w: number; h: number; play?: true }> {
725
+ const st = useStore.getState()
726
+ const onScreen = visibleNodes()
727
+ const frames = new Set([...(c.inherited ?? []), ...touchedFrames(c.steps, undefined, true, c.resumes?.at)])
728
+ const out: Record<string, { w: number; h: number; play?: true }> = {}
729
+ for (const f of frames) {
730
+ // seen in play: as it was on the stage's device; on the canvas: as its node is now (a resize after the last
731
+ // touch counts); else as it was sampled
732
+ const sampled = c.sizes[f]
733
+ if (sampled?.play) { out[f] = sampled; continue }
734
+ // no instance known for it in this recording (carried on by a Resume, or seen without one): as measured then
735
+ if (!c.keys[f] && sampled) { out[f] = sampled; continue }
736
+ if (st.play && st.play.at === f) { const z = sizeNow(f); if (z) out[f] = z; continue }
737
+ const k = c.keys[f]
738
+ const n = (k ? st.nodes.find((x) => x.key === k && x.frame === f) : undefined) ?? onScreen.find((x) => x.frame === f) ?? st.nodes.find((x) => x.frame === f)
739
+ if (n && n.w > 0 && n.h > 0) out[f] = { w: Math.round(n.w), h: Math.round(n.h) }
740
+ else if (sampled) out[f] = { w: sampled.w, h: sampled.h }
741
+ }
742
+ return out
743
+ }
744
+
745
+ /** The sizes it seals with: as they were at E; a frame only named by a step that came in after (a hover still in
746
+ * flight) as it was sampled when that step came - never as it is now. */
747
+ function sealedSizes(c: Cap): Record<string, { w: number; h: number; play?: true }> {
748
+ if (!c.endSizes) return framesSizes(c)
749
+ const out = { ...c.endSizes }
750
+ for (const f of new Set([...(c.inherited ?? []), ...touchedFrames(c.steps, undefined, true, c.resumes?.at)])) if (!out[f] && c.sizes[f]) out[f] = c.sizes[f]
751
+ return out
752
+ }
753
+
754
+ function trySeal(id: string) {
755
+ const c = capOf(id)
756
+ if (!c || c.state !== 'draining' || c.flushWait.size || c.probes > 0) return
757
+ // every step is in: now the end pictures - sealing waits only for those actually under way (one refused at
758
+ // the picture limit is never waited for)
759
+ if (!c.endShot) endPictures(id)
760
+ const c2 = capOf(id)
761
+ if (!c2 || c2.shots > 0 || c2.hearing) return
762
+ const timeline = [...c2.steps].sort((a, b) => a.at - b.at || (a.seq ?? 0) - (b.seq ?? 0)).map(({ seq: _s, src: _k, ...step }) => step as Step)
763
+ const record: CaptureRecord = {
764
+ format: 'marver.jam.capture', v: 1, id,
765
+ context: { canvas: location.host, board: c.board, ...(c.session ? { session: c.session } : {}), ...(c.reviewing ? { reviewing: c.reviewing } : {}), ...(c.resumes ? { resumes: c.resumes } : {}) },
766
+ view: (timeline.find((x) => x.event === 'view') as Extract<Step, { event: 'view' }> | undefined)?.view ?? {},
767
+ timeline, pictures: c2.pictures, ...(() => { const sizes = sealedSizes(c2); return Object.keys(sizes).length ? { sizes } : {} })(),
768
+ }
769
+ // sealed: drop everything for this id that arrives later
770
+ useJamCapture.setState((st) => { const caps = { ...st.caps }; delete caps[id]; return { caps, tick: st.tick + 1, sealed: [...st.sealed, { id }] } })
771
+ forgetHeard(id)
772
+ keepSealed(record)
773
+ void upload(record)
774
+ }
775
+
776
+ // ---- the sealed record is kept until the server has it ----------------------------------------------
777
+
778
+ /** Kept per workspace: another project served later on the same port never receives this one's captures. */
779
+ const KEPT = `mv-jam-sealed:${CONFIG.workspace ?? 'unknown'}`
780
+ const syncUnsent = () => useJamCapture.setState({ unsent: [...pendingUploads.keys()] })
781
+ const keepSealed = (r: CaptureRecord) => { try { const all = JSON.parse(localStorage.getItem(KEPT) ?? '{}'); all[r.id] = r; localStorage.setItem(KEPT, JSON.stringify(all)) } catch { /* memory only */ } pendingUploads.set(r.id, r); syncUnsent() }
782
+ const forgetSealed = (id: string) => { pendingUploads.delete(id); syncUnsent(); try { const all = JSON.parse(localStorage.getItem(KEPT) ?? '{}'); delete all[id]; localStorage.setItem(KEPT, JSON.stringify(all)) } catch { /* memory only */ } }
783
+ const pendingUploads = new Map<string, CaptureRecord>()
784
+ let retryTimer: ReturnType<typeof setTimeout> | null = null
785
+ /** Post a sealed record - the same id, idempotent on the server - until it takes. A refusal about the
786
+ * record itself (not the network) is final and said once; a dev server that is away is waited for. */
787
+ async function upload(record: CaptureRecord): Promise<void> {
788
+ type Verdict = { ok?: boolean; card?: { id: string; rev: number }; error?: string; outside?: boolean }
789
+ let r: Verdict | null = null
790
+ try {
791
+ // the workspace it was made in travels with it: another project served on this port refuses it
792
+ const res = await fetch(`${ROUTE}/api/jam/capture`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() }, body: JSON.stringify({ record, workspace: CONFIG.workspace }) })
793
+ const body = (await res.json().catch(() => null)) as Verdict | null
794
+ // only an explicit verdict on THIS record is final: taken (200, naming its card) or refused as a
795
+ // record (400, saying why). Anything else - jam not running yet, another workspace, an unreadable
796
+ // answer, a gate, a server error - is the server being away: keep it and try again
797
+ r = res.ok && body?.ok === true && body.card?.id === record.id ? body
798
+ : res.status === 400 && body && typeof body.error === 'string' ? body : null
799
+ } catch { r = null }
800
+ if (!r) {
801
+ if (!retryTimer) useStore.getState().toast('the capture is kept here and will be sent when marver dev answers')
802
+ retryTimer ??= setTimeout(() => { retryTimer = null; for (const x of pendingUploads.values()) void upload(x) }, 5_000)
803
+ return
804
+ }
805
+ forgetSealed(record.id)
806
+ releaseOpen(record.id, !r.ok) // it landed (the server knows); refused, it is no longer open either
807
+ // the server holds it: a resumed draft is replaced now (or, refused, shows again)
808
+ const was = record.context.resumes?.id
809
+ useJamCapture.setState((st) => ({ sealed: st.sealed.map((x) => (x.id === record.id ? { ...x, ...(r!.card ? { card: r!.card } : {}) } : x)), ...(was ? { resuming: st.resuming.filter((x) => x !== was) } : {}) }))
810
+ void import('./jam-queue.ts').then(({ useJamQueue }) => useJamQueue.getState().load())
811
+ if (!r.ok) useStore.getState().toast(`the capture could not be kept: ${r.error ?? 'unknown error'}`)
812
+ // it reached the server after its session ended (another tab wrote the record): on its own
813
+ else if (r.outside) leftOutOfSession(record.id)
814
+ }
815
+
816
+ /** A capture still recording, or finishing (its pictures and words coming in), lives only in this page
817
+ * until it seals - a sealed one is kept in localStorage until it lands. Leaving the page asks first. */
818
+ let guarded = false
819
+ function guardUnload() {
820
+ if (guarded || typeof window === 'undefined') return
821
+ guarded = true
822
+ window.addEventListener('beforeunload', (e) => {
823
+ if (!Object.keys(useJamCapture.getState().caps).length) return
824
+ e.preventDefault()
825
+ e.returnValue = ''
826
+ })
827
+ }
828
+
829
+ /** Records sealed in an earlier page that never reached the server: sent again at boot. */
830
+ export function resendSealed() {
831
+ guardUnload()
832
+ try {
833
+ const all = JSON.parse(localStorage.getItem(KEPT) ?? '{}') as Record<string, CaptureRecord>
834
+ // a session's capture waiting to be sent is still open: the server is told again until it lands
835
+ for (const r of Object.values(all)) { pendingUploads.set(r.id, r); if (r.context?.session && !openOnServer.has(r.id)) holdOpen(r.id, r.context.session); void upload(r) }
836
+ syncUnsent()
837
+ // a resumed capture still to send keeps its draft off the lane until it lands
838
+ const was = Object.values(all).flatMap((r) => (r.context?.resumes?.id ? [r.context.resumes.id] : []))
839
+ if (was.length) useJamCapture.setState((st) => ({ resuming: [...new Set([...st.resuming, ...was])] }))
840
+ } catch { /* none */ }
841
+ }
842
+
843
+ /** Resume's work, while the caller holds `settling`: load the record, let the caller settle, start. */
844
+ async function resumeNow(draft: string, ready?: () => Promise<boolean>): Promise<boolean> {
845
+ let rec: CaptureRecord | null = null
846
+ try {
847
+ const r = await fetch(`${ROUTE}/api/jam/capture?id=${encodeURIComponent(draft)}`, { headers: { 'x-mv-c': csrf() } })
848
+ const body = r.ok ? ((await r.json()) as { record?: CaptureRecord; sealed?: boolean }) : null
849
+ if (body?.record && body.sealed !== true) { useStore.getState().toast('the capture changed after it was sealed - it cannot be resumed'); return false }
850
+ rec = body?.record ?? null
851
+ } catch { rec = null }
852
+ if (!rec) { useStore.getState().toast('the capture could not be loaded to resume it'); return false }
853
+ if (useJamCapture.getState().current) return false
854
+ if (rec.context.board !== useStore.getState().board) { useStore.getState().toast('open the capture\'s board to resume it'); return false }
855
+ // the caller's last word before recording starts (the draft's edit saved, it is still a draft)
856
+ if (ready && !(await ready())) return false
857
+ // as things are NOW: nothing recording, still on the capture's board
858
+ if (useJamCapture.getState().current) return false
859
+ if (rec.context.board !== useStore.getState().board) { useStore.getState().toast('open the capture\'s board to resume it'); return false }
860
+ return begin(rec.context.reviewing, rec)
861
+ }
862
+
863
+ export const useJamCapture = create<CaptureState>((set, get) => ({
864
+ current: null,
865
+ caps: {},
866
+ noteOpen: false,
867
+ noteDraft: '',
868
+ tick: 0,
869
+ sealed: [],
870
+ unsent: [],
871
+ resuming: [],
872
+ lastEnded: null,
873
+ settling: null,
874
+ async resume(draft, ready) {
875
+ if (get().current) { useStore.getState().toast('a capture is recording - press E to end it first'); return false }
876
+ if (sessionEnding) { useStore.getState().toast('the session is being wrapped up - a moment'); return false }
877
+ return resumeNow(draft, ready)
878
+ },
879
+ start(reviewing, session) {
880
+ // one capture at a time: the one recording is ended or dropped first
881
+ if (get().current) { useStore.getState().toast('a capture is recording - press E to end it first'); return }
882
+ if (sessionEnding) { useStore.getState().toast('the session is being wrapped up - a moment'); return }
883
+ begin(reviewing, undefined, session)
884
+ },
885
+ end() {
886
+ const id = get().current
887
+ if (!id) return
888
+ set({ current: null, lastEnded: id })
889
+ cancelDwell()
890
+ drain(id)
891
+ unwatch?.(); unwatch = null
892
+ },
893
+ drop() {
894
+ const id = get().current
895
+ if (!id) return
896
+ broadcast({ type: 'sh:capture', id, on: false })
897
+ cancelDwell()
898
+ voiceDrop(id)
899
+ releaseOpen(id, true)
900
+ // a resumed capture dropped: its draft is still there, as it was
901
+ const was = get().caps[id]?.resumes?.id
902
+ set((s) => { const caps = { ...s.caps }; delete caps[id]; return { current: null, caps, noteOpen: false, noteDraft: '', tick: s.tick + 1, ...(was ? { resuming: s.resuming.filter((x) => x !== was) } : {}) } })
903
+ unwatch?.(); unwatch = null
904
+ },
905
+ note(text) {
906
+ const id = get().current
907
+ const t = text.trim()
908
+ if (!id || !t) return
909
+ addStep(id, { at: now(), event: 'note', text: t })
910
+ set({ noteDraft: '' })
911
+ },
912
+ setNoteOpen(open) { set({ noteOpen: open && !!get().current }) },
913
+ setNoteDraft(text) { set({ noteDraft: text }) },
914
+ picture(frame) {
915
+ const id = get().current
916
+ if (!id) return
917
+ const s = useStore.getState()
918
+ if (s.play) { shoot(id, frame ?? s.play.at, 'key'); return } // in play: the screen on stage
919
+ const key = pointerAt && performance.now() - pointerAt.at < 5_000 ? pointerAt.key : s.selection[s.selection.length - 1]
920
+ const f = frame ?? (key ? frameIdOf(key) : undefined)
921
+ if (f) shoot(id, f, 'key', key)
922
+ },
923
+ }))
924
+
925
+ /** What the capture tile shows: the timer and the counts. */
926
+ export function captureCounts(c: Cap | undefined, t = now()): { time: string; counts: string; notes: number } {
927
+ if (!c) return { time: '0:00', counts: '', notes: 0 }
928
+ const sec = Math.max(0, Math.floor((t - c.t0) / 1000))
929
+ const steps = c.steps.filter((x) => ['select', 'device', 'theme', 'copied', 'interact'].includes(x.event)).length
930
+ const frames = new Set([...(c.inherited ?? []), ...touchedFrames(c.resumes ? c.steps.filter((x) => x.at >= c.resumes!.at) : c.steps, undefined, !c.resumes)]).size
931
+ const plural = (n: number, w: string) => (n ? `${n} ${w}${n === 1 ? '' : 's'}` : '')
932
+ return {
933
+ time: `${Math.floor(sec / 60)}:${String(sec % 60).padStart(2, '0')}`,
934
+ counts: [plural(c.points.length, 'point'), plural(c.pictures.length, 'picture'), plural(frames, 'frame'), plural(steps, 'step')].filter(Boolean).join(' · '),
935
+ notes: c.steps.filter((x) => x.event === 'note').length,
936
+ }
937
+ }
938
+
939
+ if (typeof window !== 'undefined' && (import.meta as any).env?.DEV) { (window as any).__mvJamCapture = useJamCapture; (window as any).__mvJamInstances = instances }