@marver-design/marver 0.28.0 → 0.30.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 (105) hide show
  1. package/CHANGELOG.md +103 -0
  2. package/README.md +4 -3
  3. package/dist/{anchor-check-PHUOFj1N.mjs → anchor-check-c52IDkiQ.mjs} +1 -1
  4. package/dist/{build-BsAyLMT1.mjs → build-C3mUtjEn.mjs} +7 -4
  5. package/dist/{capture-DdZ6xgoz.mjs → capture-DEtM4qm5.mjs} +168 -5
  6. package/dist/cli.mjs +11 -11
  7. package/dist/{comments-CrBHPEQl.mjs → comments-XNhMmSSu.mjs} +2 -2
  8. package/dist/{connectors-MR9d-EBP.mjs → connectors-DekQvKt9.mjs} +3 -1
  9. package/dist/{daemon-C5dg2R-V.mjs → daemon-B0Wi1OQ3.mjs} +30 -29
  10. package/dist/{dev-D7YS7iT2.mjs → dev-5dlxoW28.mjs} +19 -14
  11. package/dist/{init-WE5lQkQL.mjs → init-CYlFaRzG.mjs} +1 -1
  12. package/dist/logo-CXY-1yrn.mjs +305 -0
  13. package/dist/{ls-BZ5TAtd5.mjs → ls-NqmePKOf.mjs} +1 -1
  14. package/dist/{marks-Kmdab_5w.mjs → marks-BnNANic9.mjs} +20 -1
  15. package/dist/{marks-Dyn6tmjp.mjs → marks-DBp3h1Mc.mjs} +2 -5
  16. package/dist/{marver-id-gate-D-R0hSt_.mjs → marver-id-gate-vBLb_Icb.mjs} +1 -1
  17. package/dist/{perf-Cn5LiRaY.mjs → perf-6MOTHxay.mjs} +751 -122
  18. package/dist/perf-BCxAo0IS.mjs +1743 -0
  19. package/dist/{plugin-C_0yb-Fq.mjs → plugin-CXRoMA8g.mjs} +1382 -810
  20. package/dist/{poster-DHi6I1fO.mjs → poster-CYmCa00B.mjs} +1 -1
  21. package/dist/{profile-jIS6BcAs.mjs → profile-B1FKOM1e.mjs} +1 -1
  22. package/dist/{publish-bakes-r4PEZuPl.mjs → publish-bakes-C_2ZtHou.mjs} +3 -3
  23. package/dist/{queue-c-6aTHEz.mjs → queue-DeSQm24g.mjs} +29 -14
  24. package/dist/{recover-nrLEVLyJ.mjs → recover-XD8iXJOj.mjs} +2 -2
  25. package/dist/{serve-Dp3nHstu.mjs → serve-DQv3Ti6X.mjs} +8 -4
  26. package/dist/{session-DyVE7cCk.mjs → session-VDJfXEEm.mjs} +1 -1
  27. package/dist/{share-Ce4tP7ji.mjs → share-Bu_kuOKL.mjs} +1 -1
  28. package/dist/{shot-BrRtqaiS.mjs → shot-CRRGgxru.mjs} +3 -3
  29. package/dist/{slots-CFNnegCc.mjs → slots-Dn4Onb0V.mjs} +101 -3
  30. package/dist/{sync-CQdGARJ9.mjs → sync-CMozOwZ0.mjs} +1 -1
  31. package/docs/app.md +194 -0
  32. package/docs/boards-and-folders.md +11 -0
  33. package/docs/jam-session.md +12 -3
  34. package/docs/live-jam.md +3 -0
  35. package/docs/performance.md +99 -19
  36. package/docs/publish.md +7 -0
  37. package/package.json +1 -1
  38. package/src/client/frame-host/bridge.js +17 -8
  39. package/src/client/frame-host/inplace.ts +124 -0
  40. package/src/client/frame-host/inspect.d.ts +1 -0
  41. package/src/client/frame-host/inspect.js +13 -4
  42. package/src/client/frame-host/main.tsx +12 -3
  43. package/src/client/frame-host/messages.ts +85 -0
  44. package/src/client/frame-host/signals.d.ts +15 -0
  45. package/src/client/frame-host/signals.js +219 -0
  46. package/src/client/recorder-level.ts +41 -0
  47. package/src/client/shell/App.tsx +158 -88
  48. package/src/client/shell/BoardList.tsx +103 -48
  49. package/src/client/shell/Comments.tsx +71 -46
  50. package/src/client/shell/ContextMenu.tsx +8 -6
  51. package/src/client/shell/JamSurface.tsx +187 -71
  52. package/src/client/shell/LockedApp.tsx +19 -3
  53. package/src/client/shell/Play.tsx +110 -62
  54. package/src/client/shell/StatusPicker.tsx +19 -9
  55. package/src/client/shell/Toolbar.tsx +15 -7
  56. package/src/client/shell/api.ts +25 -7
  57. package/src/client/shell/app-bridge.ts +23 -9
  58. package/src/client/shell/app-perf.ts +31 -1
  59. package/src/client/shell/canvas/Canvas.tsx +17 -6
  60. package/src/client/shell/canvas/FrameNode.tsx +25 -12
  61. package/src/client/shell/canvas/Sticky.tsx +4 -2
  62. package/src/client/shell/canvas/ctl.ts +2 -0
  63. package/src/client/shell/canvas/ready-watch.ts +4 -0
  64. package/src/client/shell/canvas/sleep.ts +2 -0
  65. package/src/client/shell/canvas/updates.ts +13 -6
  66. package/src/client/shell/commands.ts +765 -0
  67. package/src/client/shell/comments-store.ts +56 -27
  68. package/src/client/shell/goto.ts +15 -9
  69. package/src/client/shell/jam-capture.ts +39 -15
  70. package/src/client/shell/jam-keys.ts +303 -111
  71. package/src/client/shell/jam-lane.tsx +19 -12
  72. package/src/client/shell/jam-lines.ts +10 -1
  73. package/src/client/shell/jam-panel.tsx +68 -53
  74. package/src/client/shell/jam-queue.ts +6 -1
  75. package/src/client/shell/jam-session.tsx +41 -37
  76. package/src/client/shell/jam-state.ts +28 -5
  77. package/src/client/shell/jam-surface-parts.tsx +8 -6
  78. package/src/client/shell/jam-ui.tsx +12 -5
  79. package/src/client/shell/jam-voice.ts +4 -2
  80. package/src/client/shell/live-picture.ts +134 -0
  81. package/src/client/shell/main.tsx +7 -1
  82. package/src/client/shell/marks-ui.tsx +11 -0
  83. package/src/client/shell/open-item.ts +83 -0
  84. package/src/client/shell/open-resolve.ts +50 -0
  85. package/src/client/shell/perf.ts +51 -5
  86. package/src/client/shell/recorder-core.ts +4 -1
  87. package/src/client/shell/recorder-hmr.ts +36 -0
  88. package/src/client/shell/recorder-reloads.ts +264 -0
  89. package/src/client/shell/recorder-seams.ts +116 -0
  90. package/src/client/shell/recorder-self.ts +73 -0
  91. package/src/client/shell/recorder-signals-core.ts +139 -0
  92. package/src/client/shell/recorder-signals.ts +485 -0
  93. package/src/client/shell/recorder.ts +115 -41
  94. package/src/client/shell/store.ts +62 -24
  95. package/src/client/shell/styles.css +2 -0
  96. package/src/client/shell/whiteout-probes.ts +3 -1
  97. package/src/client/stage/main.tsx +39 -12
  98. package/src/shared/app-api.ts +201 -9
  99. package/src/shared/app-perf.ts +103 -8
  100. package/src/shared/app-report.ts +586 -0
  101. package/src/shared/perf-records.ts +445 -0
  102. package/src/shared/perf-run.ts +6 -2
  103. package/templates/instructions/jam.md +4 -0
  104. package/dist/live-Cgzsicwi.mjs +0 -4
  105. package/dist/perf-jam-QxD_UnzN.mjs +0 -635
@@ -12,19 +12,28 @@
12
12
  */
13
13
  import { api, isStopped } from './api.ts'
14
14
  import { CONFIG, PUBLISHED, geometryCause, knownHeight, recorderHooks, reflowIdle, settleRule, useStore, type LoadCause, type Manifest, type MeasureResult, type Node, type RequestCut } from './store.ts'
15
+ import type { BoardWriter, LoadTrigger } from '../../shared/perf-records.ts'
15
16
  import { admissionIdle, onAdmissionIdle } from './canvas/admission.ts'
16
17
  import { canvasCtl } from './canvas/ctl.ts'
17
18
  import { bootOf, iframeOf } from './canvas/frame-registry.ts'
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 { adopt, bound, bytesOf, 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
20
  import { PERF_RUN, type PerfRunStatus } from './perf-run.ts'
20
21
  import { displayHz } from './app-perf.ts'
21
-
22
- /** This document, in every record (and, in the app, in its hello: the app's records about this tab carry it). */
23
- export const PAGE_ID = newId()
22
+ import { nextSeq, PAGE_ID, perfSeams, type LoadPhase } from './recorder-seams.ts'
23
+ import type { DropReason, GestureFields } from '../../shared/perf-records.ts'
24
+ import { fullRecorder } from '../recorder-level.ts'
25
+ import { startReloads } from './recorder-reloads.ts'
26
+ import { errorCounted, modesOn, signalSink, startSignals, type SignalError } from './recorder-signals.ts'
27
+ import { currentCmd, startCommands } from './commands.ts'
28
+ import { selfCounts, startSelf } from './recorder-self.ts'
29
+
30
+ /** This document, in every record (and, in the app, in its hello: the app's records about this tab carry it). Minted in
31
+ * recorder-seams.ts, which the spec 30 streams read without importing this module. */
32
+ export { PAGE_ID }
24
33
 
25
34
  type State = ReturnType<typeof useStore.getState>
26
35
  type View = { x: number; y: number; w: number; h: number }
27
- type Gesture = { type: 'pan' | 'zoom' | 'layout'; ms: number; frames: number; p50: number; p95: number; max: number; over17ms: number; over33ms: number; longFrames: number }
36
+ type Gesture = { type: 'pan' | 'zoom' | 'layout'; ms: number; frames: number; p50: number; p95: number; max: number; over17ms: number; over33ms: number; longFrames: number } & Pick<GestureFields, 'scale' | 'loaf' | 'by'>
28
37
 
29
38
  interface Load {
30
39
  id: string; board: string; cause: LoadCause; t0: number
@@ -36,6 +45,8 @@ interface Load {
36
45
  quietSent: boolean
37
46
  /** the visible cohort: the nodes the first camera placement after the commit showed */
38
47
  cohort?: Set<string>
48
+ /** spec 30 #49: its cohort's frames all reached their outcome - `board-open`'s `visibleReady` step, said once */
49
+ visibleReady?: true
39
50
  /** store changes that moved a node (before drags are merged), their distance, by cause */
40
51
  moves: number; distance: number; causes: Record<string, number>
41
52
  errors: number; errAt: Map<string, number>
@@ -49,7 +60,6 @@ interface Load {
49
60
 
50
61
  let on = false
51
62
  let ws = ''
52
- let seq = 0
53
63
  let capturesPending = (): boolean => false
54
64
  let sealCaptures = (): void => {}
55
65
  /** requested, not committed (or cut) yet */
@@ -85,15 +95,19 @@ let sleeping = (): number => 0
85
95
  const unowned = { errors: 0, errAt: new Map<string, number>() }
86
96
 
87
97
  const env = (kind: Kind, load: string, body: Record<string, unknown>): PerfRecord =>
88
- ({ ...Object.fromEntries(Object.entries(body).filter(([, x]) => x !== undefined)), v: 1, ws, page: PAGE_ID, load, seq: seq++, ts: Date.now(), kind })
98
+ ({ ...Object.fromEntries(Object.entries(body).filter(([, x]) => x !== undefined)), v: 1, ws, page: PAGE_ID, load, seq: nextSeq(), ts: Date.now(), kind })
89
99
  function rec(kind: Kind, load: string, body: Record<string, unknown>): PerfRecord {
100
+ const t0 = selfCounts.on ? performance.now() : 0 // spec 30 #58: the page's `self`
90
101
  if (kind !== 'move') open.clear() // a merged drag ends at the next record of another kind
91
102
  const r = env(kind, load, body)
92
103
  outbox.push(r)
93
104
  armSend()
105
+ if (selfCounts.on) selfCounts.record(performance.now() - t0)
94
106
  return r
95
107
  }
96
108
  const ownerId = () => owner?.id ?? '-'
109
+ /** A load's phase, to whoever listens (spec 30: recorder-seams.ts `load`). */
110
+ const phase = (p: LoadPhase) => perfSeams.load.emit(p)
97
111
  /** ms from the load's request; undefined for a moment before it (a document kept from an earlier load) */
98
112
  const rel = (L: Load, at?: number) => (at === undefined || at < L.t0 ? undefined : Math.round(at - L.t0))
99
113
  const node = (key: string) => useStore.getState().nodes.find((n) => n.key === key)
@@ -117,10 +131,11 @@ export function startRecorder(opts: { capturesPending: () => boolean; sealCaptur
117
131
  if (on || PUBLISHED || !CONFIG.workspace || w.__mvRecorderOn) return // a hot-replaced module never records twice
118
132
  w.__mvRecorderOn = true
119
133
  on = true
134
+ perfSeams.on = true
120
135
  ws = CONFIG.workspace
121
136
  capturesPending = opts.capturesPending
122
137
  sealCaptures = opts.sealCaptures
123
- recorderHooks.request = (board, cause) => { try { return request(board, cause) } catch { return '' } }
138
+ recorderHooks.request = (board, cause, trigger, writer) => { try { return request(board, cause, trigger, writer) } catch { return '' } }
124
139
  recorderHooks.handover = guard(handover)
125
140
  recorderHooks.commit = guard(commit)
126
141
  recorderHooks.cut = guard(cutRequest)
@@ -138,6 +153,10 @@ export function startRecorder(opts: { capturesPending: () => boolean; sealCaptur
138
153
  }))
139
154
  addEventListener('pagehide', guard(leave))
140
155
  if (import.meta.env.DEV) (window as unknown as { __mvRecorder: unknown }).__mvRecorder = { page: PAGE_ID, ws, state, send }
156
+ // spec 30: the streams write through the page's envelope and outbox, and start only at the full level (#57, #58)
157
+ perfSeams.record = (kind, body, load) => { if (on) rec(kind, load ?? ownerId(), body) }
158
+ if (!fullRecorder()) return
159
+ for (const start of [startReloads, startSignals, startCommands, startSelf]) { try { start() } catch { /* one stream's start never stops another's, nor the page */ } }
141
160
  }
142
161
 
143
162
  /** What only the canvas knows, from Canvas.tsx when it mounts: when the camera or a layout animation starts and stops
@@ -150,13 +169,16 @@ export function attachCanvas(c: { onMotion: (fn: (m: { camera: boolean; preset:
150
169
 
151
170
  // ---- loads ------------------------------------------------------------------------------------------------------
152
171
 
153
- function request(board: string, cause: LoadCause): string {
172
+ function request(board: string, cause: LoadCause, trigger?: LoadTrigger, writer?: BoardWriter): string {
154
173
  if (!on) return ''
155
174
  const t0 = performance.now()
156
175
  const L: Load = { id: newId(), board, cause, t0, lastMoveAt: t0, quietSent: false, moves: 0, distance: 0, causes: {}, errors: 0, errAt: new Map(), reported: new Map() }
157
176
  pending.set(L.id, L)
158
177
  // `load`, its uncommitted `cut` and its `commit` carry the request's own id (the load's, once it commits)
159
- rec('load', L.id, { board, cause, request: L.id, ...(cause === 'boot' ? { sinceNav: Math.round(t0) } : {}) })
178
+ // spec 30 (#17, #18, `by`): why it read the board, who may have written it, the command behind it
179
+ const why = fullRecorder() ? { trigger, ...writer, by: currentCmd() } : {}
180
+ rec('load', L.id, { board, cause, request: L.id, ...(cause === 'boot' ? { sinceNav: Math.round(t0) } : {}), ...why })
181
+ phase({ phase: 'request', load: L.id, board, cause, ...(fullRecorder() ? { trigger } : {}) })
160
182
  // the deadline runs from the request: a load not settled 120 s after it was asked for is cut, committed or not - a
161
183
  // board fetch that never answers included
162
184
  L.timeout = setTimeout(guard(() => expire(L)), LOAD_MAX_MS)
@@ -180,6 +202,7 @@ function cutRequest(id: string, reason: RequestCut | 'timeout' | 'hidden'): void
180
202
  L.done = 'cut'
181
203
  L.cutReason = reason
182
204
  rec('cut', id, { reason, request: id, ms: Math.round(performance.now() - L.t0) })
205
+ phase({ phase: 'cut', load: id, reason, request: true })
183
206
  // its fetch may still answer and mount it
184
207
  if (reason === 'timeout' || reason === 'hidden') {
185
208
  lapsed.set(id, L)
@@ -213,6 +236,7 @@ function commit(id: string, nodes: readonly Node[], manifest: Manifest): void {
213
236
  // a request already cut (its deadline passed, the page hid) mounts all the same: said, its cut kept - its board's
214
237
  // geometry is its own from here, every move late
215
238
  rec('commit', id, { request: id, ms: Math.round(L.committedAt - L.t0), ...facts(nodes, manifest), ...(late ? { late: true } : {}) })
239
+ phase({ phase: 'commit', load: id, ...(late ? { late: true as const } : {}) })
216
240
  if (late) return
217
241
  L.quietTimer = setTimeout(guard(() => quiet(L)), QUIET_MS)
218
242
  // a page hidden already: cut once the set that mounts this load has run - its nodes, not the board it replaces
@@ -297,10 +321,18 @@ function progress(n: Node): void {
297
321
  if (L && !L.done && L.committedAt !== undefined) {
298
322
  const o = outcomeNow(n, useStore.getState().manifest)
299
323
  if (o && L.reported.get(n.key) !== said(n, o)) frameRecord(L, n, o)
324
+ visibleReadyNow(L)
300
325
  }
301
326
  settleSoon()
302
327
  }
303
328
 
329
+ /** Spec 30 #49: the cohort's frames all reached their outcome - `board-open`'s `visibleReady` step - once per load. */
330
+ function visibleReadyNow(L: Load): void {
331
+ if (L.visibleReady || !L.cohort || [...L.cohort].some((k) => !L.reported.has(k))) return
332
+ L.visibleReady = true
333
+ phase({ phase: 'visible-ready', load: L.id })
334
+ }
335
+
304
336
  function frameRecord(L: Load, n: Node, outcome: Outcome | 'cut'): void {
305
337
  const t = tracks.get(n.key)
306
338
  const times = [t?.admittedAt, t?.readyAt, t?.firstMeasureAt, t?.settled?.at]
@@ -347,18 +379,16 @@ function trySettle(): void {
347
379
  function settle(L: Load, s: State, outs: Outcome[]): void {
348
380
  ensureVisible(L)
349
381
  s.nodes.forEach((n, i) => { if (L.reported.get(n.key) !== said(n, outs[i])) frameRecord(L, n, outs[i]) })
350
- const lastReady = (ns: readonly Node[]) => {
351
- const xs = ns.map((n) => tracks.get(n.key)?.readyAt).filter((x): x is number => x !== undefined)
352
- return xs.length ? Math.max(0, Math.round(Math.max(...xs) - L.t0)) : undefined
353
- }
354
382
  if (!L.quietSent) { L.quietSent = true; rec('quiet', L.id, { ms: Math.round(L.lastMoveAt - L.t0) }) }
383
+ visibleReadyNow(L)
355
384
  rec('settled', L.id, {
356
385
  ms: Math.round(performance.now() - L.t0), moves: L.moves, distance: Math.round(L.distance), causes: L.causes, lastMove: rel(L, L.movedAt),
357
- visibleReadyMs: lastReady(s.nodes.filter((n) => L.cohort?.has(n.key))), allReadyMs: lastReady(s.nodes),
386
+ visibleReadyMs: lastReady(L, s.nodes.filter((n) => L.cohort?.has(n.key))), allReadyMs: lastReady(L, s.nodes),
358
387
  missing: outs.filter((o) => o === 'missing').length, neverReady: outs.filter((o) => o === 'never-ready').length, errors: outs.filter((o) => o === 'error').length,
359
388
  weight: weight(),
360
389
  })
361
390
  finish(L, 'settled')
391
+ phase({ phase: 'settled', load: L.id })
362
392
  }
363
393
 
364
394
  /** The load ended before it settled: another board, a reload of this one, the page hidden, or 120 s. What its nodes
@@ -369,15 +399,29 @@ function cut(L: Load, reason: 'switch' | 'reload' | 'hidden' | 'timeout'): void
369
399
  const s = useStore.getState()
370
400
  ensureVisible(L)
371
401
  let ready = 0
402
+ const readyNodes: Node[] = []
372
403
  for (const n of s.nodes) {
373
404
  const o = outcomeNow(n, s.manifest)
374
- if (o === 'settled' || o === 'ready') ready++
405
+ if (o === 'settled' || o === 'ready') { ready++; readyNodes.push(n) }
375
406
  if (!o) frameRecord(L, n, 'cut')
376
407
  else if (L.reported.get(n.key) !== said(n, o)) frameRecord(L, n, o)
377
408
  }
378
- rec('cut', L.id, { reason, ms: Math.round(performance.now() - L.t0), lastMove: rel(L, L.movedAt), frames: s.nodes.length, ready })
409
+ rec('cut', L.id, { reason, ms: Math.round(performance.now() - L.t0), lastMove: rel(L, L.movedAt), frames: s.nodes.length, ready, ...(fullRecorder() ? partialTimes(L, readyNodes) : {}) })
379
410
  L.cutReason = reason
380
411
  finish(L, 'cut')
412
+ phase({ phase: 'cut', load: L.id, reason })
413
+ }
414
+
415
+ /** Spec 30 #19: what a cut load had ready, as `settled` computes it, over the frames ready by then - `visibleReady` says
416
+ * how many of the cohort that is, so a partial time is never read as the whole. */
417
+ function partialTimes(L: Load, ready: readonly Node[]) {
418
+ const visible = ready.filter((n) => L.cohort?.has(n.key))
419
+ return { visibleReadyMs: lastReady(L, visible), allReadyMs: lastReady(L, ready), visibleReady: visible.length }
420
+ }
421
+ /** ms from the request to the last of these nodes' ready; none while none was. */
422
+ function lastReady(L: Load, ns: readonly Node[]): number | undefined {
423
+ const xs = ns.map((n) => tracks.get(n.key)?.readyAt).filter((x): x is number => x !== undefined)
424
+ return xs.length ? Math.max(0, Math.round(Math.max(...xs) - L.t0)) : undefined
381
425
  }
382
426
 
383
427
  function finish(L: Load, how: 'settled' | 'cut'): void {
@@ -407,47 +451,62 @@ function ensureVisible(L: Load): void {
407
451
  const v = canvasCtl.view()
408
452
  L.cohort = v ? cohortIn(v) : new Set()
409
453
  rec('visible', L.id, { nodes: L.cohort.size, ms: Math.round(performance.now() - L.t0), assumed: true })
454
+ phase({ phase: 'visible', load: L.id, nodes: L.cohort.size, assumed: true })
410
455
  }
411
456
 
412
457
  // ---- errors -----------------------------------------------------------------------------------------------------
413
458
 
414
459
  let inError = false
415
- /** the errors past a load's 50, counted in one `dropped` record while it waits to be sent (the next one adds to it) */
416
- let over: PerfRecord | null = null
417
- /** ≤ 50 per load (those past it counted), the same one at most once a second; messages and stack lines cut to 200
418
- * characters. An error after the load settled or was cut is `late` - the load owns the geometry for as long as its
419
- * board stays open. */
420
- function logError(e: { source: 'shell' | 'frame' | 'stage'; frame?: string; component?: string; message: unknown; stack?: unknown }): void {
460
+ /** each reason's `dropped` record while it waits to be sent (the next one adds to it): the errors past a load's 50, and
461
+ * what a source's rate or a frame's budget refused (spec 30 #33) */
462
+ const drops = new Map<DropReason, PerfRecord>()
463
+ function drop(reason: DropReason, n: number): void {
464
+ const d = drops.get(reason)
465
+ if (d && d.load === ownerId() && outbox.has(d)) { d.n = (d.n as number) + n; outbox.touch(d) }
466
+ else drops.set(reason, rec('dropped', ownerId(), { n, reason }))
467
+ }
468
+ /** Every source (spec 30 #27-#33): ≤ 50 per load (those past it counted), the same one at most once a second; messages and
469
+ * stack lines cut to 200 characters; the modes on with it. An error after the load settled or was cut is `late` - the
470
+ * load owns the geometry for as long as its board stays open. At the `core` level, what 0.29 did. */
471
+ function logError(e: SignalError): void {
421
472
  if (inError) return
422
473
  inError = true
423
474
  try {
424
475
  const message = bound(typeof e.message === 'string' ? e.message : String(e.message ?? ''))
425
476
  if (!message) return
426
477
  const L = owner, mine = L ?? unowned
478
+ const full = fullRecorder()
427
479
  const key = `${e.source}|${e.frame ?? ''}|${message}`, now = performance.now()
428
- if (now - (mine.errAt.get(key) ?? -Infinity) < 1000) return
429
- if (mine.errors >= 50) {
430
- if (over && over.load === ownerId() && outbox.has(over)) { over.n = (over.n as number) + 1; outbox.touch(over) }
431
- else over = rec('dropped', ownerId(), { n: 1, reason: 'errors' })
432
- return
433
- }
480
+ if (now - (mine.errAt.get(key) ?? -Infinity) < 1000) { if (full) drop(e.source, 1); return }
481
+ if (mine.errors >= 50) { drop('errors', 1); return }
434
482
  mine.errors++
435
483
  mine.errAt.set(key, now)
436
484
  const stack = Array.isArray(e.stack) ? e.stack.slice(0, 3).map((l) => bound(l)).filter((l): l is string => !!l) : stackLines(e.stack)
437
- rec('error', ownerId(), { source: e.source, frame: bound(e.frame), component: bound(e.component), message, ...(stack?.length ? { stack } : {}), ...(L?.done ? { late: true } : {}) })
485
+ const modes = full ? modesOn() : []
486
+ rec('error', ownerId(), { source: e.source, frame: bound(e.frame), component: bound(e.component), message, ...(stack?.length ? { stack } : {}), ...(L?.done ? { late: true } : {}), ...(full ? e.fields : {}), ...(modes.length ? { modes } : {}) })
487
+ if (modes.length) errorCounted(modes)
438
488
  } finally { inError = false }
439
489
  }
490
+ // the signals stream's way in (recorder-signals.ts never imports this module)
491
+ signalSink.error = (e) => { if (on) logError(e) }
492
+ signalSink.dropped = (reason, n) => { if (on) drop(reason, n) }
440
493
 
441
494
  // ---- sending ----------------------------------------------------------------------------------------------------
442
495
 
443
496
  const armSend = () => { if (!sending && sendTimer === undefined && outbox.size) sendTimer = setTimeout(() => { sendTimer = undefined; void send() }, SEND_MS) }
444
497
  const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
445
- const post = (records: PerfRecord[], keepalive = false) => api('perf/page', {
446
- method: 'POST',
447
- headers: { 'content-type': 'application/json', 'x-mv-c': csrf() },
448
- body: JSON.stringify({ records }),
449
- ...(keepalive ? { keepalive: true } : {}),
450
- })
498
+ const post = (records: PerfRecord[], keepalive = false) => {
499
+ const t0 = selfCounts.on ? performance.now() : 0 // spec 30 #58: `send`'s own work, and the bytes
500
+ const body = JSON.stringify({ records })
501
+ const sent = api('perf/page', {
502
+ method: 'POST',
503
+ headers: { 'content-type': 'application/json', 'x-mv-c': csrf() },
504
+ body,
505
+ ...(keepalive ? { keepalive: true } : {}),
506
+ })
507
+ if (selfCounts.on) { selfCounts.bytes += bytesOf(body); perfSeams.selfCost('send', performance.now() - t0) }
508
+ return sent
509
+ }
451
510
  const wait = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
452
511
  /** The `dropped` record that says how many went, when any did (the count starts over). */
453
512
  const droppedNow = (more = 0): PerfRecord[] => {
@@ -484,6 +543,8 @@ async function send(): Promise<void> {
484
543
  }
485
544
  } catch { /* never in the way: what it held is counted below */ }
486
545
  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) }
546
+ // spec 30 #58: every drop said by a `dropped` record that landed, whatever its reason
547
+ else if (selfCounts.on) selfCounts.dropped += batch.reduce((n, r) => n + (r.kind === 'dropped' ? (r.n as number) || 0 : 0), 0)
487
548
  inFlight = []
488
549
  sending = false
489
550
  armSend()
@@ -501,10 +562,13 @@ function leave(): void {
501
562
  if (capturesPending() || WARM) return
502
563
  // a send on its way may not outlive the page: its records again (the report drops a duplicate by its seq)
503
564
  const all = [...inFlight, ...outbox.takeAll()]
504
- if (!all.length) return
505
- // the cuts first, newest first: the load this page leaves in flight ends in the last of them
506
- const { fit, lost } = fitWithin(all.filter((r) => r.kind === 'cut').reverse(), all.filter((r) => r.kind !== 'cut'), KEEPALIVE_BYTES)
507
- try { void post([...fit, ...droppedNow(lost)], true).catch(() => {}) } catch { /* going anyway */ }
565
+ if (all.length) {
566
+ // the cuts first, newest first: the load this page leaves in flight ends in the last of them
567
+ const { fit, lost } = fitWithin(all.filter((r) => r.kind === 'cut').reverse(), all.filter((r) => r.kind !== 'cut'), KEEPALIVE_BYTES)
568
+ try { void post([...fit, ...droppedNow(lost)], true).catch(() => {}) } catch { /* going anyway */ }
569
+ }
570
+ // then the reload lines' share (spec 30 #7), after the page's own
571
+ perfSeams.leaving.emit()
508
572
  }
509
573
 
510
574
  // ---- a headless perf run (spec 28 A3.8 #17) ----------------------------------------------------------------------
@@ -596,9 +660,19 @@ export const recorder = {
596
660
  if (!L || L.committedAt === undefined || L.cohort) return
597
661
  L.cohort = cohortIn(view)
598
662
  rec('visible', L.id, { nodes: L.cohort.size, ms: Math.round(performance.now() - L.t0) })
663
+ phase({ phase: 'visible', load: L.id, nodes: L.cohort.size })
599
664
  }),
600
665
  /** A pan, zoom or layout animation ended (perf.ts). */
601
- gesture: guard((g: Gesture) => { rec('gesture', ownerId(), { ...g, hz: displayHz() ?? undefined }); settleSoon() }),
666
+ gesture: guard((g: Gesture) => {
667
+ let seen = {}
668
+ // spec 30 #34: what it ended showing, and the documents awake then (iframes minus asleep, as `weight()`)
669
+ if (fullRecorder()) {
670
+ const v = canvasCtl.view()
671
+ seen = { ...(v ? { visible: cohortIn(v).size } : {}), awake: Math.max(0, document.querySelectorAll('iframe.sh-live[src]').length - sleeping()) }
672
+ }
673
+ rec('gesture', ownerId(), { ...g, hz: displayHz() ?? undefined, ...seen })
674
+ settleSoon()
675
+ }),
602
676
  /** An error the shell saw: its own (window, ShellBoundary) or the play stage's. A shell error goes out at once. */
603
677
  error: guard((e: { source: 'shell' | 'stage'; message: unknown; stack?: unknown; component?: string }) => {
604
678
  logError(e)
@@ -6,6 +6,8 @@ import { stableNodeKey } from './keys.ts'
6
6
  import { canvasCtl } from './canvas/ctl.ts'
7
7
  import { api, beforeResume, canvasStopped, holdsReload, lostInResume, mvFetch, noteUnsaved, onLinkNotice, savedInResume, scoped, STOPPED_WAY, withWs } from './api.ts'
8
8
  import { unsavedWhen, workChanged } from './unsaved.ts'
9
+ import { nextSeq, PAGE_ID } from './recorder-seams.ts'
10
+ import type { BoardWriter, HeldBy, LoadTrigger } from '../../shared/perf-records.ts'
9
11
  // @ts-expect-error virtual module provided by the plugin
10
12
  import shConfig from 'virtual:sh-config'
11
13
  // @ts-expect-error virtual module: null in dev; a published build inlines manifest+boards
@@ -176,6 +178,7 @@ import { UNPLACED } from './hash.ts'
176
178
  import type { BoardType, StatusWord } from '../../shared/board-types.ts'
177
179
  import type { Phase, Status } from '../../shared/status.ts'
178
180
  import { isNew, type Marks } from '../../shared/marks.ts'
181
+ import { cmd, keepCmds, type CmdOpts } from './commands.ts'
179
182
 
180
183
  /** The CAS tokens a tree write echoes: the sha256 of every board file as last seen, and of
181
184
  * the folder registry (null = there was no file). */
@@ -272,11 +275,26 @@ const TAB = Math.random().toString(36).slice(2, 8)
272
275
  * means a first load, or a document that reloaded itself (the reload log tells them apart). */
273
276
  const reloadCause = new Map<string, 'job' | 'manual' | 'retry'>()
274
277
  export const takeReloadCause = (key: string) => { const c = reloadCause.get(key); reloadCause.delete(key); return c }
278
+ /** A reload line with its envelope (spec 30 #16): the tab, and the page and seq the `(page, seq)` dedupe reads. */
279
+ export const reloadLine = (entry: Record<string, unknown>): Record<string, unknown> => ({ tab: TAB, page: PAGE_ID, seq: nextSeq(), ts: Date.now(), ...entry })
280
+ /** The edit's way to the frames, as the recorder sees it: recorder-reloads.ts installs these at the full level (spec 30
281
+ * R1). Until then, and under `core`, a line goes as 0.29's did - one unconfirmed request - and the rest do nothing. */
282
+ export const reloadHooks = {
283
+ line: (l: Record<string, unknown>): void => {
284
+ const body = { records: [l] }
285
+ // a page's very first request may go before its request cookie exists: a GET primes it, then once more
286
+ void postOwner('perf/reload', body).then((r) => (r.status === 403 ? api('work').then(() => postOwner('perf/reload', body)) : r)).catch(() => {})
287
+ },
288
+ /** an edit reached these frames: before their nodes go stale */
289
+ invalidated: (_frames: ReadonlySet<string>, _revision: string): void => {},
290
+ /** a reload job started this navigation of a node */
291
+ started: (_key: string, _nav: number): void => {},
292
+ /** a stale node's turn was refused, and why (canvas/updates.ts) */
293
+ held: (_key: string, _why: HeldBy): void => {},
294
+ }
275
295
  export const logReload = (entry: Record<string, unknown>) => {
276
296
  if (PUBLISHED) return
277
- const body = { tab: TAB, ...entry }
278
- // a page's very first request may go before its request cookie exists: a GET primes it, then once more
279
- void postOwner('perf/reload', body).then((r) => (r.status === 403 ? api('work').then(() => postOwner('perf/reload', body)) : r)).catch(() => {})
297
+ reloadHooks.line(reloadLine(entry))
280
298
  }
281
299
  const postOwner = (path: string, body: unknown) =>
282
300
  api(path, { method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() }, body: JSON.stringify(body) })
@@ -285,11 +303,13 @@ const postOwner = (path: string, body: unknown) =>
285
303
  * `marver boards pin` does. The answer is said; the file change re-reads the sidebar and the view. */
286
304
  export async function addToBoard(board: string, frames: string[]): Promise<void> {
287
305
  const { toast } = useStore.getState()
306
+ const h = cmd('add-to-board', { via: 'click', in: 'shell', board, frames: frames.length })
288
307
  try {
289
308
  const r = await postOwner('boards/pin', { board, frames })
290
309
  const body = await r.json().catch(() => ({})) as { added?: string[]; error?: string }
310
+ if (r.ok) h.done(); else h.fail('api')
291
311
  toast(r.ok ? `${body.added?.length ? 'pinned' : 'already'} on ${boardLabel(board)}` : body.error ?? `could not pin (${r.status})`)
292
- } catch { toast('could not reach the dev server') }
312
+ } catch { h.fail('api'); toast('could not reach the dev server') }
293
313
  }
294
314
 
295
315
  const HEADER = 28
@@ -517,7 +537,8 @@ export type RequestCut = 'superseded' | 'error' | 'edited' | 'unsaved'
517
537
  * on a published one. A request owns the geometry from its commit, and `commit` runs right BEFORE the set that
518
538
  * mounts the load: mounting it is never a move. */
519
539
  export const recorderHooks = {
520
- request: (_board: string, _cause: LoadCause): string => '',
540
+ /** `trigger`, `writer`: why it read the board again, and who may have written it (spec 30 #17, #18) */
541
+ request: (_board: string, _cause: LoadCause, _trigger?: LoadTrigger, _writer?: BoardWriter): string => '',
521
542
  /** a request is about to commit: the load that was up ends - before the incoming sizes are installed, so it ends by
522
543
  * the sizes it read (which frames measure), its board's nodes still in the store */
523
544
  handover: (_request: string): void => {},
@@ -633,8 +654,9 @@ interface State {
633
654
  imageBusy: boolean // a copy-as-image render is in flight (one at a time)
634
655
 
635
656
  /** (re)load the open board from disk. `mayCommit`, when given, is asked again at the moment the
636
- * reload would land - a caller's own conditions (a status write's: nothing moved since its flush) */
637
- boot(mayCommit?: () => boolean): Promise<boolean>
657
+ * reload would land - a caller's own conditions (a status write's: nothing moved since its flush).
658
+ * `trigger`, `writer`: why it reads the board again, and who may have written it - the recorder's (spec 30 #17, #18) */
659
+ boot(mayCommit?: () => boolean, trigger?: LoadTrigger, writer?: BoardWriter): Promise<boolean>
638
660
  applyManifest(m: Manifest): void
639
661
  frameFor(node: Node): FrameEntry | undefined
640
662
  moveNode(key: string, x: number, y: number): void
@@ -667,7 +689,9 @@ interface State {
667
689
  setSelectedTheme(theme: string): void
668
690
  setDeviceView(name: string | null): void
669
691
  resizeSelected(name: string | null): void
670
- switchBoard(name: string): Promise<void>
692
+ /** `mayCommit`, read last before the new board commits: false leaves the board shown as it is (a notice's request,
693
+ * jam-keys.ts toBoard) */
694
+ switchBoard(name: string, mayCommit?: () => boolean): Promise<void>
671
695
  /** what the sidebar labels boards by: slug → title, off the last tree read */
672
696
  boardTitles: Record<string, string>
673
697
  /** what the sidebar draws beside a board: its type and status (spec 20), off the last tree read */
@@ -686,7 +710,7 @@ interface State {
686
710
  setScenes(scenes: Manifest['scenes']): void
687
711
  arrangeBoards(tree: TreeItem[], base: TreeBase): Promise<{ ok: true } | { ok: false; stale: boolean; error?: string }>
688
712
  pulsePath(): void
689
- copyFrameImage(scale: 2 | 4): void
713
+ copyFrameImage(scale: 2 | 4, how: CmdOpts): void
690
714
  setScale(s: number): void
691
715
  togglePanel(): void
692
716
  setTheme(theme: string): void
@@ -1166,12 +1190,12 @@ export const useStore = create<State>((set, get) => {
1166
1190
  panelOpen: true, scale: 1, toasts: [], working: [], workingSince: {}, workingBoards: [], workingSeq: -1, boardHash: null, dirty: false, boardTitles: DATA?.titles ?? {}, boardMeta: DATA?.meta ?? {},
1167
1191
  externalLeases: {}, playUpdateRevision: null, stageShown: null, playNav: 0, pathPulse: 0, imagePulse: 0, imageBusy: false,
1168
1192
 
1169
- async boot(mayCommit) {
1193
+ async boot(mayCommit, trigger, writer) {
1170
1194
  const seq = ++loadSeq
1171
1195
  recorderHooks.cut(bootRequest, 'superseded')
1172
1196
  const boardName = get().board
1173
1197
  // the recorder's request (spec 28 A1.7): the page's first load, else the open board read from disk again
1174
- const request = bootRequest = recorderHooks.request(boardName, firstLoad ? 'boot' : 'disk-reload')
1198
+ const request = bootRequest = recorderHooks.request(boardName, firstLoad ? 'boot' : 'disk-reload', firstLoad ? 'first' : trigger, writer)
1175
1199
  firstLoad = false
1176
1200
  const revAtStart = editRev, scenesAtStart = scenesRev
1177
1201
  const loaded = await loadBoardState(boardName)
@@ -1194,7 +1218,7 @@ export const useStore = create<State>((set, get) => {
1194
1218
  return true
1195
1219
  },
1196
1220
 
1197
- async switchBoard(name) {
1221
+ async switchBoard(name, mayCommit) {
1198
1222
  const mySwitch = ++switchSeq // also cancels any pending switch (incl. re-clicking the current board)
1199
1223
  switchCalls++
1200
1224
  recorderHooks.cut(switchRequest, 'superseded')
@@ -1224,6 +1248,8 @@ export const useStore = create<State>((set, get) => {
1224
1248
  for (let i = 0; i < 5 && get().dirty && ok; i++) { clearTimeout(saveTimer); ok = await get().save() }
1225
1249
  if (mySwitch !== switchSeq) return recorderHooks.cut(request, 'superseded')
1226
1250
  if (get().dirty) { recorderHooks.cut(request, 'unsaved'); get().toast('current board could not be saved - staying here'); return }
1251
+ // the caller's own condition, read last: words typed while the board loaded, or its request ended, keep this board
1252
+ if (mayCommit && !mayCommit()) return recorderHooks.cut(request, 'superseded')
1227
1253
  clearTimeout(saveTimer) // a scheduled-but-clean timer must not fire against the new board
1228
1254
  ++loadSeq // invalidate any in-flight boot of the old board
1229
1255
  recorderHooks.cut(bootRequest, 'superseded')
@@ -1241,6 +1267,7 @@ export const useStore = create<State>((set, get) => {
1241
1267
  },
1242
1268
 
1243
1269
  renameBoard(name, title, baseHash) {
1270
+ const sending = keepCmds() // spec 30 #18: this write names its command however long it waits for its turn and the flush
1244
1271
  return structural(async () => {
1245
1272
  const from = name
1246
1273
  const active = from === get().board
@@ -1259,12 +1286,12 @@ export const useStore = create<State>((set, get) => {
1259
1286
  try {
1260
1287
  // the active board's hash is freshest in the store (an autosave may have landed since
1261
1288
  // the sidebar looked); every other board's is the sidebar's
1262
- const send = (base: string | null | undefined) => postOwner('boards/rename', { from, title, ...(base ? { baseHash: base } : {}) })
1289
+ const send = (base: string | null | undefined) => sending(() => postOwner('boards/rename', { from, title, ...(base ? { baseHash: base } : {}) }))
1263
1290
  let res: Response
1264
1291
  try {
1265
1292
  res = await send(active && get().boardHash ? get().boardHash : baseHash)
1266
1293
  // the open board changed on disk: reload it, then once more (setBoardStatus's reasoning)
1267
- if (res.status === 409 && mayReload() && await get().boot(mayReload)) res = await send(get().boardHash)
1294
+ if (res.status === 409 && mayReload() && await get().boot(mayReload, 'save-conflict')) res = await send(get().boardHash)
1268
1295
  }
1269
1296
  catch { return { ok: false, error: 'could not reach the dev server' } }
1270
1297
  const body = await res.json().catch(() => ({} as { error?: string; sha256?: string }))
@@ -1281,6 +1308,7 @@ export const useStore = create<State>((set, get) => {
1281
1308
  },
1282
1309
 
1283
1310
  setBoardStatus(name, status, reason, baseHash) {
1311
+ const sending = keepCmds() // renameBoard's
1284
1312
  return structural(async () => {
1285
1313
  const active = name === get().board
1286
1314
  // the active board's file is rewritten under the autosave: flush first, hold across (renameBoard's pattern)
@@ -1295,14 +1323,14 @@ export const useStore = create<State>((set, get) => {
1295
1323
  const rev = editRev
1296
1324
  const mayReload = () => active && get().board === name && editRev === rev && !get().gesture
1297
1325
  try {
1298
- const send = (base: string | null | undefined) => postOwner('boards/status', { name, status, ...(reason ? { reason } : {}), ...(base ? { baseHash: base } : {}) })
1326
+ const send = (base: string | null | undefined) => sending(() => postOwner('boards/status', { name, status, ...(reason ? { reason } : {}), ...(base ? { baseHash: base } : {}) }))
1299
1327
  let res: Response
1300
1328
  try {
1301
1329
  res = await send(active && get().boardHash ? get().boardHash : baseHash)
1302
1330
  // the open board changed on disk (an agent wrote it): its hash in the store is behind, and a
1303
1331
  // retry with it would 409 again - reload the board (layout and hash together) when nothing
1304
1332
  // has changed here since the flush, then try once more against what is on disk now
1305
- if (res.status === 409 && mayReload() && await get().boot(mayReload)) res = await send(get().boardHash)
1333
+ if (res.status === 409 && mayReload() && await get().boot(mayReload, 'save-conflict')) res = await send(get().boardHash)
1306
1334
  }
1307
1335
  catch { return { ok: false, error: 'could not reach the dev server' } }
1308
1336
  const body = await res.json().catch(() => ({} as { error?: string; sha256?: string }))
@@ -1350,6 +1378,7 @@ export const useStore = create<State>((set, get) => {
1350
1378
  // true and the watcher's echo is filtered as our own. `base` carries the hashes the
1351
1379
  // sidebar last saw; a 409 (`stale`) means someone else wrote first - refetch and replay.
1352
1380
  arrangeBoards(tree, base) {
1381
+ const sending = keepCmds() // renameBoard's
1353
1382
  return structural(async () => {
1354
1383
  let ok = true
1355
1384
  for (let i = 0; i < 5 && get().dirty && ok; i++) { clearTimeout(saveTimer); ok = await get().save() }
@@ -1361,7 +1390,7 @@ export const useStore = create<State>((set, get) => {
1361
1390
  const active = get().board
1362
1391
  const boards = { ...base.boards, ...(get().boardHash && base.boards[active] !== undefined ? { [active]: get().boardHash } : {}) }
1363
1392
  let res: Response
1364
- try { res = await postOwner('boards/reorder', { tree: toWire(tree), base: { boards, folders: base.folders }, protocol: TREE_PROTOCOL }) }
1393
+ try { res = await sending(() => postOwner('boards/reorder', { tree: toWire(tree), base: { boards, folders: base.folders }, protocol: TREE_PROTOCOL })) }
1365
1394
  catch { return { ok: false as const, stale: false, error: 'could not reach the dev server' } }
1366
1395
  const body = await res.json().catch(() => ({} as { error?: string; sha256?: { boards?: Record<string, string> } }))
1367
1396
  if (!res.ok) return { ok: false as const, stale: res.status === 409, error: body?.error }
@@ -1758,6 +1787,7 @@ export const useStore = create<State>((set, get) => {
1758
1787
  // every document of these frames is behind - one loading too (one running, one waiting): a document
1759
1788
  // that shows the revision the edit made clears it when it is ready (setShown)
1760
1789
  const want = (f: string) => (docs?.epoch && typeof docs.docs?.[f] === 'number' ? `${docs.epoch}:${docs.docs[f]}` : undefined)
1790
+ reloadHooks.invalidated(ids, revision)
1761
1791
  const nodes = s.nodes.map((n) => (ids.has(n.frame) && !n.missing ? { ...n, stale: true, want: later(n.want, want(n.frame)) } : n))
1762
1792
  set({ nodes, ...(s.play ? { playUpdateRevision: revision } : {}) })
1763
1793
  pumpUpdates()
@@ -1772,6 +1802,7 @@ export const useStore = create<State>((set, get) => {
1772
1802
  set((s) => ({ nodes: s.nodes.map((x) => (x.key === key
1773
1803
  ? { ...x, stale: false, status: 'loading' as const, error: undefined, nav: (x.nav ?? 0) + 1, readyRetried: false }
1774
1804
  : x)) }))
1805
+ reloadHooks.started(key, (n.nav ?? 0) + 1)
1775
1806
  },
1776
1807
  setShown(key, shown) {
1777
1808
  set((s) => ({ nodes: s.nodes.map((x) => {
@@ -1812,15 +1843,19 @@ export const useStore = create<State>((set, get) => {
1812
1843
  // node shows, at 2x (or 4x). The ClipboardItem takes a PROMISE: clipboard.write runs
1813
1844
  // inside the click/keydown gesture and the browser waits for the bytes - a plain
1814
1845
  // await-then-write would have lost the transient activation during the 1-4s render.
1815
- copyFrameImage(scale) {
1846
+ copyFrameImage(scale, how) {
1816
1847
  const s = get()
1817
- if (PUBLISHED || s.imageBusy || s.selection.length !== 1) return
1848
+ if (PUBLISHED) return
1849
+ // spec 30: done when the clipboard holds it (60 s, the ceiling below); each refusal its code
1850
+ const h = cmd('copy-image', { ...how, frames: s.selection.length, arg: `${scale}x` })
1851
+ if (s.imageBusy) { h.noop('busy'); return }
1852
+ if (s.selection.length !== 1) { h.noop('multi'); return }
1818
1853
  const node = s.nodes.find((n) => n.key === s.selection[0])
1819
- if (!node || node.missing) return
1854
+ if (!node || node.missing) { h.noop('indexing'); return }
1820
1855
  const frame = s.frameFor(node)
1821
- if (!frame) { s.toast('frame is still indexing - try again in a second'); return }
1856
+ if (!frame) { h.noop('indexing'); s.toast('frame is still indexing - try again in a second'); return }
1822
1857
  const CI = (globalThis as { ClipboardItem?: typeof ClipboardItem }).ClipboardItem
1823
- if (!CI || !navigator.clipboard?.write || (CI.supports && !CI.supports('image/png'))) { s.toast("this browser can't put images on the clipboard - use Chrome, Edge or Safari"); return }
1858
+ if (!CI || !navigator.clipboard?.write || (CI.supports && !CI.supports('image/png'))) { h.fail('browser'); s.toast("this browser can't put images on the clipboard - use Chrome, Edge or Safari"); return }
1824
1859
  set({ imageBusy: true })
1825
1860
  void import('./jam-capture.ts').then(({ recordCopy }) => recordCopy('image', frame.id)) // a capture notes that it happened
1826
1861
  const done = () => set({ imageBusy: false })
@@ -1836,11 +1871,13 @@ export const useStore = create<State>((set, get) => {
1836
1871
  return r.blob()
1837
1872
  }).finally(() => clearTimeout(timer))
1838
1873
  let renderErr = ''
1839
- png.catch((e: Error) => { renderErr = e.name === 'AbortError' ? 'timed out - the renderer is busy' : e.message })
1874
+ let renderTimedOut = false
1875
+ png.catch((e: Error) => { renderTimedOut = e.name === 'AbortError'; renderErr = renderTimedOut ? 'timed out - the renderer is busy' : e.message })
1840
1876
  const fail = (err: unknown) => {
1841
1877
  done()
1842
1878
  // a prompt clipboard refusal (no gesture, focus lost) must not wait a minute on the
1843
1879
  // render: abandon the fetch, toast now. A render failure surfaces its own cause.
1880
+ h.fail(renderErr ? (renderTimedOut ? 'render-timeout' : 'render-failed') : (err as Error)?.name === 'NotAllowedError' ? 'clipboard-blocked' : 'render-failed')
1844
1881
  if (!renderErr) ctl.abort()
1845
1882
  s.toast(renderErr ? `render failed - ${renderErr}` : (err as Error)?.name === 'NotAllowedError' ? 'copy blocked - click the canvas first' : `copy failed - ${(err as Error)?.message ?? err}`)
1846
1883
  }
@@ -1848,6 +1885,7 @@ export const useStore = create<State>((set, get) => {
1848
1885
  navigator.clipboard.write([new CI({ 'image/png': png })]).then(
1849
1886
  () => {
1850
1887
  done()
1888
+ h.done()
1851
1889
  const used = meta.scale ?? scale
1852
1890
  s.toast(used < scale ? `image copied at ${used}x - frame too tall for ${scale}x` : scale === 4 ? 'image copied (4x)' : 'image copied')
1853
1891
  set((st) => ({ imagePulse: st.imagePulse + 1 }))
@@ -2146,7 +2184,7 @@ export const useStore = create<State>((set, get) => {
2146
2184
  lostInResume('gone') // a save while a resume is owed: the page after its reload says this, not "saved"
2147
2185
  return true
2148
2186
  }
2149
- const reloaded = await get().boot() // hash advances only when the authoritative reload commits
2187
+ const reloaded = await get().boot(undefined, 'save-conflict') // hash advances only when the authoritative reload commits
2150
2188
  if (reloaded) { get().toast(DISK_WON); lostInResume('disk') }
2151
2189
  return reloaded // false keeps dirty set; the next debounce retries once edits settle
2152
2190
  }
@@ -1891,6 +1891,8 @@ body.sh-commenting .sh-sticky-body { cursor: crosshair }
1891
1891
  /* the panel's middle scrolls; its head and its footer stay in view */
1892
1892
  .jm-panel .jm-body { display: flex; flex-direction: column; gap: 12px; min-height: 0; overflow-y: auto; margin: 0 -16px; padding: 0 16px }
1893
1893
  .jm-focus .jm-panel .jm-body { flex: 1 }
1894
+ /* the thread panel (spec 28 A4.6 #30): each Jam card's status icon on its own line, its popover opening under it */
1895
+ .jm-thread .jm-thread-status { display: flex; align-items: center; min-height: 20px; padding-left: 4px }
1894
1896
  .jm-review .jm-big { min-height: 160px }
1895
1897
  .jm-shot .pic img { display: block; width: 100%; height: 100%; object-fit: cover; object-position: top center }
1896
1898
  /* the review's one big picture: the shot at its own proportions, centred in the well, never cropped */
@@ -91,8 +91,10 @@ function cameraPath(): { path: PerfCam[]; stop(): void } {
91
91
  return { path, stop: () => { on = false } }
92
92
  }
93
93
 
94
- /** The `before` answer for `tick`: the points chosen now, the camera and the viewport. */
94
+ /** The `before` answer for `tick`: the points chosen now, the camera and the viewport. A covering play stage leaves no
95
+ * ground to probe, and says so (spec 30 #39): main takes no capture and records the time as uncovered. */
95
96
  export function pick(tick: number): Extract<PerfMsg, { kind: 'probes'; at: 'before' }> {
97
+ if (document.querySelector('.sh-play')) return { kind: 'probes', tick, at: 'before', points: [], cam: canvasCtl.transform(), view: view(), stage: true }
96
98
  const top = VISIBLE_TOP
97
99
  const w = innerWidth, h = Math.max(0, innerHeight - top)
98
100
  const rects = nodeRects()