@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
@@ -7,18 +7,22 @@
7
7
  * glyph; the selected tile alone wears the accent ring. Every tile is one width - selecting one never
8
8
  * resizes it; a title cut short shows whole in a tooltip, and a right-click opens the tile's menu.
9
9
  *
10
- * Presentational only - the shell decides what is on it (jam-capture.ts and App mount it).
10
+ * Presentational only - the shell decides what is on it (jam-capture.ts and App mount it). A tile's button names its
11
+ * command here (spec 30); what the shell does with it ends it, from the handle it is handed.
11
12
  */
12
13
  import { useEffect, useLayoutEffect, useRef, useState } from 'react'
13
14
  import { JamStateIcon, type JamGlyph } from './jam-ui.tsx'
14
15
  import { Tip } from './Tip.tsx'
15
16
  import { DONE_CLOSE, DONE_GROUP, doneFold, doneLine } from './jam-state.ts'
17
+ import { cmd, endAfterFrames, type CmdHandle, type CmdOpts } from './commands.ts'
16
18
  import { ArrowsInLineHorizontalIcon, CursorClickIcon, FileCodeIcon, ImagesSquareIcon, LaserIcon, MicrophoneIcon, MicrophoneSlashIcon, PauseIcon, PencilSimpleIcon } from './icons.tsx'
17
19
 
18
20
  /** The lane's height with its air: the 44 px tile + 12 px. While the lane shows, the sidebar stops
19
21
  * above it and everything else on the bottom edge (the Update pill, toasts, notices) rises this much. */
20
22
  export const LANE_H = 56
21
23
 
24
+ const CLICK: CmdOpts = { via: 'click', in: 'shell' }
25
+
22
26
  export interface LaneTile {
23
27
  id: string
24
28
  state: JamGlyph
@@ -55,7 +59,8 @@ export interface LaneRecording {
55
59
  finishing?: boolean
56
60
  /** the microphone: hearing you (`on`), or not (`off` - a click asks again); none when never asked */
57
61
  mic?: 'on' | 'off'
58
- onMic?(): void
62
+ /** a click asks again, once you were asked: it ends the handle when the voice state changed */
63
+ onMic?(h: CmdHandle): void
59
64
  onNote(): void
60
65
  onStop(): void
61
66
  onStopReview(): void
@@ -92,7 +97,8 @@ export interface LaneBetween {
92
97
  since: number
93
98
  /** the microphone hears the session's talk */
94
99
  mic: boolean
95
- onCapture(): void
100
+ /** ends the handle: a capture recording, or refused */
101
+ onCapture(h: CmdHandle): void
96
102
  }
97
103
 
98
104
  export function Lane({ tiles, recording, between, selected, keyboard, onOpen, onMenu, followEnd, doneOpen = false, onDoneOpen }: {
@@ -105,7 +111,8 @@ export function Lane({ tiles, recording, between, selected, keyboard, onOpen, on
105
111
  between?: LaneBetween
106
112
  selected?: string
107
113
  keyboard?: boolean
108
- onOpen(id: string): void
114
+ /** ends the handle once the tile's surface is drawn, or it could not be */
115
+ onOpen(id: string, h: CmdHandle): void
109
116
  /** a right-click on a tile: its menu */
110
117
  onMenu?(e: React.MouseEvent, id: string): void
111
118
  followEnd?: unknown
@@ -170,7 +177,7 @@ export function Lane({ tiles, recording, between, selected, keyboard, onOpen, on
170
177
  {fold && !doneOpen && (
171
178
  <button key={DONE_GROUP} data-tile={DONE_GROUP} data-state="done" data-jam-done="folded"
172
179
  className={`jm-card done group${selected === DONE_GROUP ? ' focus' : ''}`}
173
- onClick={() => onDoneOpen?.(true, done.map((t) => t.id))}>
180
+ onClick={() => { cmd('jam-done-fold', { ...CLICK, arg: 'open' }); onDoneOpen?.(true, done.map((t) => t.id)) }}>
174
181
  <JamStateIcon state="done" />
175
182
  <span className="tx">
176
183
  <span className="t">Done</span>
@@ -181,14 +188,14 @@ export function Lane({ tiles, recording, between, selected, keyboard, onOpen, on
181
188
  {fold && doneOpen && (
182
189
  <button key={DONE_CLOSE} data-tile={DONE_CLOSE} data-jam-done="open" aria-label="Fold the done captures"
183
190
  className={`jm-card close${selected === DONE_CLOSE ? ' focus' : ''}`}
184
- onClick={() => onDoneOpen?.(false, done.map((t) => t.id))}>
191
+ onClick={() => { cmd('jam-done-fold', { ...CLICK, arg: 'fold' }); onDoneOpen?.(false, done.map((t) => t.id)) }}>
185
192
  <ArrowsInLineHorizontalIcon size={15} /><span className="t">Done</span>
186
193
  </button>
187
194
  )}
188
195
  {shown.map((t) => (
189
196
  <button key={t.id} data-tile={t.id} data-state={t.state}
190
197
  className={`jm-card ${t.state}${selected === t.id ? ' focus' : ''}${fold && t.state === 'done' ? ' unfold' : ''}`}
191
- onClick={() => onOpen(t.id)} onContextMenu={onMenu ? (e) => onMenu(e, t.id) : undefined}>
198
+ onClick={() => onOpen(t.id, cmd('jam-open', CLICK))} onContextMenu={onMenu ? (e) => onMenu(e, t.id) : undefined}>
192
199
  <JamStateIcon state={t.state} />
193
200
  <span className="tx">
194
201
  {/* the whole title, in the shell's own tooltip - only when the tile cuts it short */}
@@ -215,7 +222,7 @@ export function BetweenTile({ since, mic, onCapture }: LaneBetween) {
215
222
  <span className="stats">{mic ? <><MicrophoneIcon size={12} />Listening between captures</> : <><MicrophoneSlashIcon size={12} />Between captures</>}</span>
216
223
  </span>
217
224
  <i className="sep" />
218
- <button className="go" onClick={onCapture}>Capture<kbd>S</kbd></button>
225
+ <button className="go" onClick={() => onCapture(cmd('jam-capture', CLICK))}>Capture<kbd>S</kbd></button>
219
226
  </div>
220
227
  )
221
228
  }
@@ -229,7 +236,7 @@ export function CaptureTile({ time, points, pictures = 0, picturesMax, steps, co
229
236
  {finishing ? <JamStateIcon state="confirming" /> : <i className="jm-live-dot" />}
230
237
  {mic && !finishing && (
231
238
  <Tip label={mic === 'on' ? 'Hearing you - words on this Mac' : 'Microphone off - click to use it'}>
232
- <button className={`mic${mic === 'off' ? ' off' : ''}`} data-jam-mic={mic} onClick={onMic} aria-label={mic === 'on' ? 'Microphone on' : 'Microphone off'}>
239
+ <button className={`mic${mic === 'off' ? ' off' : ''}`} data-jam-mic={mic} onClick={() => { const h = cmd('jam-mic', CLICK); if (onMic) onMic(h); else h.noop('on') }} aria-label={mic === 'on' ? 'Microphone on' : 'Microphone off'}>
233
240
  {mic === 'on' ? <MicrophoneIcon size={13} /> : <MicrophoneSlashIcon size={13} />}
234
241
  </button>
235
242
  </Tip>
@@ -244,14 +251,14 @@ export function CaptureTile({ time, points, pictures = 0, picturesMax, steps, co
244
251
  </span>
245
252
  </span>
246
253
  <i className="sep" />
247
- <button className={`notebtn${noteOn ? ' on' : ''}`} onClick={onNote} disabled={finishing} aria-pressed={noteOn}>
254
+ <button className={`notebtn${noteOn ? ' on' : ''}`} onClick={() => { const h = cmd('jam-notes', CLICK); onNote(); endAfterFrames(h) }} disabled={finishing} aria-pressed={noteOn}>
248
255
  <PencilSimpleIcon size={13} />Note{notes ? <b>{notes}</b> : null}<kbd>N</kbd>
249
256
  </button>
250
257
  <Tip label="Stop and queue it - the agent starts on it">
251
- <button className="stop" onClick={onStop} disabled={finishing}>Stop<kbd>E</kbd></button>
258
+ <button className="stop" onClick={() => { const h = cmd('jam-end', CLICK); onStop(); endAfterFrames(h) }} disabled={finishing}>Stop<kbd>E</kbd></button>
252
259
  </Tip>
253
260
  <Tip label="Stop and look it over first - add notes, then queue it">
254
- <button className="stop review" onClick={onStopReview} disabled={finishing}><PauseIcon size={12} />Stop to review<kbd>⇧E</kbd></button>
261
+ <button className="stop review" onClick={() => { const h = cmd('jam-end-review', CLICK); onStopReview(); endAfterFrames(h) }} disabled={finishing}><PauseIcon size={12} />Stop to review<kbd>⇧E</kbd></button>
255
262
  </Tip>
256
263
  </div>
257
264
  )
@@ -154,13 +154,22 @@ export function timelineLines(r: CaptureRecord, edited?: string): TimelineLine[]
154
154
  case 'interact': out.push({ t, kind: 'interact', text: s.on ? 'on' : 'off' }); break
155
155
  case 'picture':
156
156
  pictures++
157
- out.push({ t, kind: 'picture', text: `${frameName(s.frame).toLowerCase()}${s.why === 'end' ? ' at E' : s.why === 'pick' ? ' at a pick' : ''}`, point: pictures }); break
157
+ out.push({ t, kind: 'picture', text: `${frameName(s.frame).toLowerCase()}${s.why === 'end' ? ' at E' : s.why === 'pick' ? ' at a pick' : ''}${s.source === 'live' ? ` · ${AS_SEEN}` : ''}`, point: pictures }); break
158
158
  case 'missing': out.push({ t, kind: 'missing', text: s.what }); break
159
159
  }
160
160
  }
161
161
  return out
162
162
  }
163
163
 
164
+ /** A live picture's words (A4.6 #38): the Mac app's picture of the stage, as the owner saw it - not a render. */
165
+ const AS_SEEN = 'as you saw it'
166
+ /** A capture's picture as the read-back and the review's Capture tab caption it: "picture N", and "picture N · as you saw
167
+ * it" for a live one (its picture step says `source: 'live'`). */
168
+ export function pictureCaption(r: CaptureRecord, id: string, n: number): string {
169
+ const live = r.timeline.some((s) => s.event === 'picture' && s.id === id && s.source === 'live')
170
+ return `picture ${n}${live ? ` · ${AS_SEEN}` : ''}`
171
+ }
172
+
164
173
  /** A line as plain text, the spec's format: `[0:05] (pick 1) <span> "Save 20%" · file.tsx:48`,
165
174
  * `[0:04] "this badge"`, `[0:13] (interact on)`. */
166
175
  export function lineText(l: TimelineLine): string {
@@ -4,7 +4,8 @@
4
4
  * capture's marks on the canvas (the teal edge ring, numbered points).
5
5
  *
6
6
  * Presentational only: every component takes what it shows and calls back what was chosen. The shell
7
- * (jam-capture.ts, App) owns state, keys and the API.
7
+ * (jam-capture.ts, App) owns state, keys and the API. A button names its command here (spec 30) and hands the handle to
8
+ * the callback, whose work ends it. Never a note's, an answer's or a read-back's words in a command.
8
9
  */
9
10
  import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react'
10
11
  import { JamStateIcon } from './jam-ui.tsx'
@@ -20,6 +21,10 @@ import { Tip } from './Tip.tsx'
20
21
  import { useJamQueue } from './jam-queue.ts'
21
22
  import { holdsReload } from './api.ts'
22
23
  import { unsavedWhen, workChanged } from './unsaved.ts'
24
+ import { endOnOk } from './jam-state.ts'
25
+ import { cmd, endAfterFrames, keysOf, type CmdHandle, type CmdOpts } from './commands.ts'
26
+
27
+ const CLICK: CmdOpts = { via: 'click', in: 'shell' }
23
28
 
24
29
  /** A heading cut short by its ellipsis: its tooltip shows it whole (one that fits shows none). */
25
30
  const cutShort = (el: HTMLElement) => el.scrollWidth > el.clientWidth + 1
@@ -47,7 +52,7 @@ export function FocusPanel({ children, left, width = 580, onClose }: { children:
47
52
  return (
48
53
  <div className="jm-focus" data-jam-focus="" style={{ left, width: w, bottom: `calc(var(--edge) + ${LANE_H + 2}px)` }}>
49
54
  {children}
50
- {onClose && <button className="jm-iconbtn jm-focus-x" aria-label="Close" onClick={onClose}><XIcon size={13} /></button>}
55
+ {onClose && <button className="jm-iconbtn jm-focus-x" aria-label="Close" onClick={() => { cmd('jam-close', CLICK); onClose() }}><XIcon size={13} /></button>}
51
56
  </div>
52
57
  )
53
58
  }
@@ -111,11 +116,12 @@ function AddedNotes({ added, onAdd }: { added: { at: number; text: string }[]; o
111
116
  const [busy, setBusy] = useState(false)
112
117
  // the note in the field: one id until it saves (a failed one sent again is the same note)
113
118
  const nid = useRef(newNoteId())
114
- const add = async () => {
119
+ const add = async (o: CmdOpts) => {
115
120
  const t = text.trim()
116
121
  if (!t || busy || !onAdd) return
122
+ const h = cmd('jam-note-add', o)
117
123
  setBusy(true)
118
- const ok = await onAdd(t, nid.current)
124
+ const ok = await endOnOk(h, onAdd(t, nid.current))
119
125
  setBusy(false)
120
126
  if (ok) { setText(''); nid.current = newNoteId() }
121
127
  }
@@ -136,10 +142,10 @@ function AddedNotes({ added, onAdd }: { added: { at: number; text: string }[]; o
136
142
  onKeyDown={(e) => {
137
143
  e.stopPropagation()
138
144
  if ((e.nativeEvent as unknown as { isComposing?: boolean }).isComposing) return
139
- if (e.key === 'Enter') { e.preventDefault(); void add() }
140
- else if (e.key === 'Escape') { e.preventDefault(); setText(''); (e.target as HTMLInputElement).blur() }
145
+ if (e.key === 'Enter') { e.preventDefault(); void add({ via: 'key', in: 'shell', keys: keysOf(e) }) }
146
+ else if (e.key === 'Escape') { e.preventDefault(); cmd('jam-field-discard', { via: 'key', in: 'shell', keys: keysOf(e), arg: 'note' }); setText(''); (e.target as HTMLInputElement).blur() }
141
147
  }} />
142
- <button className="jm-btn" disabled={!text.trim() || busy} onClick={() => void add()}>Add note</button>
148
+ <button className="jm-btn" disabled={!text.trim() || busy} onClick={() => void add(CLICK)}>Add note</button>
143
149
  </div>
144
150
  )}
145
151
  </div>
@@ -180,8 +186,8 @@ export function Shot({ url, cap, alt, onSize }: { url?: string; cap?: ReactNode;
180
186
  const Walk = ({ of, onPrev, onNext }: { of?: [number, number]; onPrev?: () => void; onNext?: () => void }) => of ? (
181
187
  <>
182
188
  <span className="dim">{of[0]} of {of[1]}</span>
183
- <button className="jm-iconbtn" disabled={of[0] <= 1 || !onPrev} onClick={onPrev} aria-label="Previous"><ArrowLeftIcon size={13} /></button>
184
- <button className="jm-iconbtn" disabled={of[0] >= of[1] || !onNext} onClick={onNext} aria-label="Next"><ArrowRightIcon size={13} /></button>
189
+ <button className="jm-iconbtn" disabled={of[0] <= 1 || !onPrev} onClick={() => { cmd('jam-step', { ...CLICK, arg: 'prev' }); onPrev?.() }} aria-label="Previous"><ArrowLeftIcon size={13} /></button>
190
+ <button className="jm-iconbtn" disabled={of[0] >= of[1] || !onNext} onClick={() => { cmd('jam-step', { ...CLICK, arg: 'next' }); onNext?.() }} aria-label="Next"><ArrowRightIcon size={13} /></button>
185
191
  </>
186
192
  ) : null
187
193
 
@@ -217,20 +223,20 @@ export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, picture
217
223
  /** words written that have not saved yet - they win over `edited` */
218
224
  pending?: string
219
225
  /** a failed capture: its Retry (with Drop beside it) in the read-only footer */
220
- onRetry?: () => void
226
+ onRetry?: (h: CmdHandle) => void
221
227
  editing?: boolean
222
- onEdit?: (text: string) => void
223
- onConfirm?: () => void
224
- onKeep?: () => void
225
- onDrop?: () => void
228
+ onEdit?: (text: string, h: CmdHandle) => void
229
+ onConfirm?: (h: CmdHandle) => void
230
+ onKeep?: (h: CmdHandle) => void
231
+ onDrop?: (h: CmdHandle) => void
226
232
  /** ended too soon: recording goes on where it stopped (R) */
227
- onResume?: () => void
233
+ onResume?: (h: CmdHandle) => void
228
234
  agent?: string | null
229
235
  follows?: string
230
236
  readOnly?: boolean
231
237
  /** the words cannot be edited for now (its Resume is starting) - the rest stays as it is */
232
238
  locked?: boolean
233
- onOpenThread?: () => void
239
+ onOpenThread?: (h: CmdHandle) => void
234
240
  /** notes written here after it ended - under a divider, as the timeline shows its own */
235
241
  added?: { at: number; text: string }[]
236
242
  /** the title came from Claude Haiku (jam.names): its tooltip says so, and where the words went */
@@ -259,7 +265,8 @@ export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, picture
259
265
  const lastSent = useRef<string | undefined>(undefined)
260
266
  const save = () => {
261
267
  setOpen(false)
262
- if (text !== (lastSent.current ?? pending ?? edited ?? words)) { lastSent.current = text; onEdit?.(text) }
268
+ // blur: its words save (`jam-edit`), whatever took the focus
269
+ if (text !== (lastSent.current ?? pending ?? edited ?? words)) { lastSent.current = text; onEdit?.(text, cmd('jam-edit', CLICK)) }
263
270
  }
264
271
  // once the saved edit is what was last sent, the intent is settled
265
272
  useEffect(() => { if (lastSent.current !== undefined && edited === lastSent.current && pending === undefined) lastSent.current = undefined }, [edited, pending])
@@ -281,7 +288,7 @@ export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, picture
281
288
  {open && !readOnly && !locked ? (
282
289
  <textarea ref={field} className="jm-edit" value={text} rows={Math.min(10, Math.max(3, Math.ceil(text.length / 60)))}
283
290
  onChange={(e) => setText(e.target.value)} onBlur={save}
284
- onKeyDown={(e) => { e.stopPropagation(); if (e.key === 'Escape') { setText(edited ?? words); setOpen(false) } }} />
291
+ onKeyDown={(e) => { e.stopPropagation(); if (e.key === 'Escape') { cmd('jam-field-discard', { via: 'key', in: 'shell', keys: keysOf(e), arg: 'words' }); setText(edited ?? words); setOpen(false) } }} />
285
292
  ) : (
286
293
  <div className={readOnly || locked ? undefined : 'jm-editable'} title={readOnly || locked ? undefined : 'Click to edit the words'} onClick={readOnly || locked ? undefined : () => setOpen(true)}>
287
294
  {edited !== undefined && !readOnly && <div className="jm-edited"><PencilSimpleIcon size={12} />Your edit</div>}
@@ -293,16 +300,16 @@ export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, picture
293
300
  <div className="rule" />
294
301
  <div className="actions">
295
302
  {readOnly ? (
296
- <><span className="sp" />{onOpenThread && <button className="jm-btn" onClick={onOpenThread}>Open thread</button>}
297
- {onRetry && <><button className="jm-btn ghost" onClick={onDrop}>Drop</button><button className="jm-btn primary" onClick={onRetry}>Retry</button></>}</>
303
+ <><span className="sp" />{onOpenThread && <button className="jm-btn" onClick={() => onOpenThread(cmd('jam-thread', CLICK))}>Open thread</button>}
304
+ {onRetry && <><button className="jm-btn ghost" data-jam-run-act="drop" onClick={() => onDrop?.(cmd('jam-drop', CLICK))}>Drop</button><button className="jm-btn primary" data-jam-run-act="retry" onClick={() => onRetry(cmd('jam-retry', CLICK))}>Retry</button></>}</>
298
305
  ) : (
299
306
  <>
300
307
  <span className="dim">{agent ? <>For <b style={{ color: 'var(--glass-ink-2)', fontWeight: 600 }}>{agent}</b></> : 'No agent yet - it waits in the queue'}</span>
301
308
  <span className="sp" />
302
- {onResume && <button className="jm-btn ghost" onClick={onResume}>Resume <kbd>R</kbd></button>}
303
- <button className="jm-btn ghost" onClick={onDrop}>Drop <kbd>esc</kbd></button>
304
- <button className="jm-btn ghost" onClick={onKeep}>Keep <kbd>K</kbd></button>
305
- <button className="jm-btn primary" onClick={onConfirm}>Add to queue <kbd>⏎</kbd></button>
309
+ {onResume && <button className="jm-btn ghost" onClick={() => onResume(cmd('jam-resume', CLICK))}>Resume <kbd>R</kbd></button>}
310
+ <button className="jm-btn ghost" onClick={() => onDrop?.(cmd('jam-drop', CLICK))}>Drop <kbd>esc</kbd></button>
311
+ <button className="jm-btn ghost" onClick={() => onKeep?.(cmd('jam-keep', CLICK))}>Keep <kbd>K</kbd></button>
312
+ <button className="jm-btn primary" onClick={() => onConfirm?.(cmd('jam-confirm', CLICK))}>Add to queue <kbd>⏎</kbd></button>
306
313
  </>
307
314
  )}
308
315
  </div>
@@ -311,30 +318,33 @@ export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, picture
311
318
  }
312
319
 
313
320
  /** What a capture's run asked you, and your answer - for a thread this board cannot show (its frame is on no node
314
- * here). Sent with @marver in its thread: the answer goes back to the agent, as a tagged reply does. */
315
- function AsksAnswer({ question, onAnswer }: { question: string; onAnswer(text: string): Promise<boolean> }) {
321
+ * here). Sent with @marver in its thread: the answer goes back to the agent, as a tagged reply does. The thread panel
322
+ * (spec 28 A4.6 #30) draws its own messages (no `question`) and says `tag` only when a Jam card is on the thread - a
323
+ * tag anywhere else would start a run nobody asked for, so the answer goes as typed. */
324
+ export function AsksAnswer({ question, onAnswer, tag = true }: { question?: string; onAnswer(text: string): Promise<boolean>; tag?: boolean }) {
316
325
  const [text, setText] = useState('')
317
326
  const [sending, setSending] = useState(false)
318
- const send = () => {
327
+ const send = (o: CmdOpts) => {
319
328
  if (!text.trim() || sending) return
329
+ const h = cmd('jam-answer', o)
320
330
  setSending(true)
321
- void onAnswer(text.trim()).then((ok) => { setSending(false); if (ok) setText('') })
331
+ void endOnOk(h, onAnswer(text.trim()), 'send-failed').then((ok) => { setSending(false); if (ok) setText('') })
322
332
  }
323
333
  return (
324
334
  <div className="jm-asks" data-jam-asks="" style={{ display: 'flex', flexDirection: 'column', gap: 7 }}>
325
- <div className="jm-reply">
335
+ {question !== undefined && <div className="jm-reply">
326
336
  <Marver size={20} />
327
337
  <p>{question || 'It asks you something - see its thread.'}</p>
328
- </div>
338
+ </div>}
329
339
  <div className="jm-more">
330
- <span className="at">@marver</span>
340
+ {tag && <span className="at">@marver</span>}
331
341
  <textarea className="txt" rows={1} value={text} placeholder="Your answer" disabled={sending}
332
342
  onChange={(e) => setText(e.target.value)}
333
343
  onKeyDown={(e) => {
334
344
  e.stopPropagation()
335
- if (e.key === 'Enter' && !e.shiftKey && !(e.nativeEvent as unknown as { isComposing?: boolean }).isComposing) { e.preventDefault(); send() }
345
+ if (e.key === 'Enter' && !e.shiftKey && !(e.nativeEvent as unknown as { isComposing?: boolean }).isComposing) { e.preventDefault(); send({ via: 'key', in: 'shell', keys: keysOf(e) }) }
336
346
  }} />
337
- <button className="jm-send" disabled={!text.trim() || sending} onClick={send}>Send <kbd>⏎</kbd></button>
347
+ <button className="jm-send" disabled={!text.trim() || sending} onClick={() => send(CLICK)}>Send <kbd>⏎</kbd></button>
338
348
  </div>
339
349
  </div>
340
350
  )
@@ -373,11 +383,11 @@ export function ReviewDetail({ title, head, of, onPrev, onNext, frames, active,
373
383
  agent?: string
374
384
  when?: string
375
385
  more?: boolean
376
- onMore(text: string): void
386
+ onMore(text: string, h: CmdHandle): void
377
387
  onMoreOpen(open: boolean): void
378
- onGood(): void
379
- onLater(): void
380
- onOpenThread?: () => void
388
+ onGood(h: CmdHandle): void
389
+ onLater(h: CmdHandle): void
390
+ onOpenThread?: (h: CmdHandle) => void
381
391
  /** the card the More work words belong to (kept across the panel closing) */
382
392
  draftKey?: string
383
393
  style?: CSSProperties
@@ -431,7 +441,7 @@ export function ReviewDetail({ title, head, of, onPrev, onNext, frames, active,
431
441
  // elsewhere, the map still holds them
432
442
  useEffect(() => { if (more) field.current?.focus(); else if (draftKey && !moreDrafts.has(draftKey)) setTextState('') }, [more])
433
443
  // sent as More work, always: the canvas settles a note that only approves ("looks good") as Looks good
434
- const send = () => { if (text.trim()) onMore(text.trim()) }
444
+ const send = (o: CmdOpts) => { if (text.trim()) onMore(text.trim(), cmd('jam-more-send', o)) }
435
445
  return (
436
446
  <div className="jm-panel jm-review" data-jam-review="" style={style}>
437
447
  <div className="top">
@@ -445,19 +455,19 @@ export function ReviewDetail({ title, head, of, onPrev, onNext, frames, active,
445
455
  <Marver size={20} />
446
456
  <div style={{ display: 'flex', flexDirection: 'column', gap: 4, minWidth: 0 }}>
447
457
  <p>{reply}</p>
448
- {onOpenThread && <button className="jm-link" onClick={onOpenThread}>Open thread</button>}
458
+ {onOpenThread && <button className="jm-link" onClick={() => onOpenThread(cmd('jam-thread', CLICK))}>Open thread</button>}
449
459
  </div>
450
460
  </div>
451
461
  {names.length > 0 && (
452
462
  <div className="jm-fbar">
453
463
  {names.length > 1
454
- ? <div className="jm-ftabs" role="tablist">{names.map((f, i) => <button key={f} role="tab" aria-selected={i === active} className={i === active ? 'on' : undefined} onClick={() => onTab(i)}><FrameRectIcon size={12} />{label(f)}{isNew(f) && <span className="jm-newtag">New</span>}</button>)}</div>
464
+ ? <div className="jm-ftabs" role="tablist">{names.map((f, i) => <button key={f} role="tab" aria-selected={i === active} className={i === active ? 'on' : undefined} onClick={() => { const h = cmd('jam-frame-tab', CLICK); onTab(i); endAfterFrames(h) }}><FrameRectIcon size={12} />{label(f)}{isNew(f) && <span className="jm-newtag">New</span>}</button>)}</div>
455
465
  : <span className="jm-framehd"><FrameRectIcon size={12} />{label(names[0])}{isNew(names[0]) && <span className="jm-newtag">New</span>}</span>}
456
466
  <span className="sp" />
457
467
  {/* a frame the run made has nothing before it: no switch */}
458
468
  {shot?.new ? <span className="dim" data-jam-new="">New frame</span> : (
459
469
  <Tip side="bottom" label={<span>Both / Before / After<kbd style={{ marginLeft: 8 }}>B</kbd></span>}>
460
- <div className="jm-ftabs" data-jam-flip="">{(['both', 'before', 'after'] as const).map((v) => <button key={v} className={v === view ? 'on' : undefined} aria-pressed={v === view} onClick={() => onFlip(v)}>{v === 'both' ? 'Both' : v === 'before' ? 'Before' : 'After'}</button>)}</div>
470
+ <div className="jm-ftabs" data-jam-flip="">{(['both', 'before', 'after'] as const).map((v) => <button key={v} className={v === view ? 'on' : undefined} aria-pressed={v === view} onClick={() => { const h = cmd('jam-before-after', { ...CLICK, arg: v }); onFlip(v); endAfterFrames(h) }}>{v === 'both' ? 'Both' : v === 'before' ? 'Before' : 'After'}</button>)}</div>
461
471
  </Tip>
462
472
  )}
463
473
  </div>
@@ -480,18 +490,18 @@ export function ReviewDetail({ title, head, of, onPrev, onNext, frames, active,
480
490
  onChange={(e) => setText(e.target.value)}
481
491
  onKeyDown={(e) => {
482
492
  e.stopPropagation()
483
- if (e.key === 'Escape') { e.preventDefault(); setText(''); onMoreOpen(false) }
484
- else if (e.key === 'Enter' && !e.shiftKey && !(e.nativeEvent as unknown as { isComposing?: boolean }).isComposing) { e.preventDefault(); send() }
493
+ if (e.key === 'Escape') { e.preventDefault(); cmd('jam-field-discard', { via: 'key', in: 'shell', keys: keysOf(e), arg: 'more' }); setText(''); onMoreOpen(false) }
494
+ else if (e.key === 'Enter' && !e.shiftKey && !(e.nativeEvent as unknown as { isComposing?: boolean }).isComposing) { e.preventDefault(); send({ via: 'key', in: 'shell', keys: keysOf(e) }) }
485
495
  }} />
486
- <button className="jm-send" disabled={!text.trim()} onClick={send}>Send <kbd>⏎</kbd></button>
496
+ <button className="jm-send" disabled={!text.trim()} onClick={() => send(CLICK)}>Send <kbd>⏎</kbd></button>
487
497
  </div>
488
498
  <span className="dim" style={{ paddingLeft: 4 }}>Back to the agent, next in line - the tile keeps its place · esc to cancel</span>
489
499
  </div>
490
500
  ) : (
491
501
  <div className="actions">
492
- <button className="jm-btn primary" onClick={onGood}>Looks good <kbd>⏎</kbd></button>
493
- <button className="jm-btn" onClick={() => onMoreOpen(true)}>More work <kbd>⇧⏎</kbd></button>
494
- <button className="jm-btn ghost" onClick={onLater}>Later <kbd>→</kbd></button>
502
+ <button className="jm-btn primary" onClick={() => onGood(cmd('jam-good', CLICK))}>Looks good <kbd>⏎</kbd></button>
503
+ <button className="jm-btn" onClick={() => { const h = cmd('jam-more', CLICK); onMoreOpen(true); endAfterFrames(h) }}>More work <kbd>⇧⏎</kbd></button>
504
+ <button className="jm-btn ghost" onClick={() => onLater(cmd('jam-later', CLICK))}>Later <kbd>→</kbd></button>
495
505
  <span className="sp" /><kbd>esc</kbd>
496
506
  </div>
497
507
  )}
@@ -527,8 +537,9 @@ export function NotesCard({ notes, draft, onDraft, onAdd, onClose, style }: {
527
537
  onKeyDown={(e) => {
528
538
  e.stopPropagation()
529
539
  if ((e.nativeEvent as unknown as { isComposing?: boolean }).isComposing) return
530
- if (e.key === 'Escape') { e.preventDefault(); onClose() }
531
- else if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); if (draft.trim()) onAdd() }
540
+ if (e.key === 'Escape') { e.preventDefault(); cmd('jam-notes-close', { via: 'key', in: 'shell', keys: keysOf(e) }); onClose() }
541
+ // the note step is added in this turn
542
+ else if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); if (draft.trim()) { const h = cmd('jam-capture-note', { via: 'key', in: 'shell', keys: keysOf(e) }); onAdd(); h.done() } }
532
543
  }} />
533
544
  <div className="foot"><span>⏎ add</span><span>esc close</span></div>
534
545
  </div>
@@ -544,6 +555,10 @@ export const Caption = ({ old, live, style }: { old?: string; live?: string; sty
544
555
  </div>
545
556
  )
546
557
 
558
+ /** The microphone question's choices (the fixed name, spec 30): the callback ends the command when the consent or the
559
+ * download state changed. */
560
+ const voiceChoice = (arg: 'use-mic' | 'download' | 'try-again' | 'not-now' | 'typed-only') => cmd('jam-voice', { ...CLICK, arg })
561
+
547
562
  /** The one question words need (first `S` on a canvas), then the model's download if it is missing:
548
563
  * a header that says what is happening, a line on why, then what the model is (trial 3: "Words on this
549
564
  * Mac" said neither). */
@@ -552,7 +567,7 @@ export function VoiceAsk({ step, mb, progress, error, onYes, onNo, onDownload, s
552
567
  mb: number
553
568
  progress?: number
554
569
  error?: string
555
- onYes(): void; onNo(): void; onDownload(): void
570
+ onYes(h: CmdHandle): void; onNo(h: CmdHandle): void; onDownload(h: CmdHandle): void
556
571
  style?: CSSProperties
557
572
  }) {
558
573
  const pct = Math.round((progress ?? 0) * 100)
@@ -580,9 +595,9 @@ export function VoiceAsk({ step, mb, progress, error, onYes, onNo, onDownload, s
580
595
  {step === 'checking' && <div className="jm-progress busy"><i /></div>}
581
596
  <div className="actions">
582
597
  <span className="sp" />
583
- {step === 'ask' && <><button className="jm-btn ghost" onClick={onNo}>Not now</button><button className="jm-btn primary" onClick={onYes}>Use the microphone</button></>}
584
- {(step === 'download' || step === 'failed') && <><button className="jm-btn ghost" onClick={onNo}>Not now</button><button className="jm-btn primary" onClick={onDownload}>{step === 'failed' ? 'Try again' : `Download ${mb} MB`}</button></>}
585
- {step === 'unavailable' && <><button className="jm-btn ghost" onClick={onNo}>Typed notes only</button><button className="jm-btn primary" onClick={onYes}>Try again</button></>}
598
+ {step === 'ask' && <><button className="jm-btn ghost" onClick={() => onNo(voiceChoice('not-now'))}>Not now</button><button className="jm-btn primary" onClick={() => onYes(voiceChoice('use-mic'))}>Use the microphone</button></>}
599
+ {(step === 'download' || step === 'failed') && <><button className="jm-btn ghost" onClick={() => onNo(voiceChoice('not-now'))}>Not now</button><button className="jm-btn primary" onClick={() => onDownload(voiceChoice(step === 'failed' ? 'try-again' : 'download'))}>{step === 'failed' ? 'Try again' : `Download ${mb} MB`}</button></>}
600
+ {step === 'unavailable' && <><button className="jm-btn ghost" onClick={() => onNo(voiceChoice('typed-only'))}>Typed notes only</button><button className="jm-btn primary" onClick={() => onYes(voiceChoice('try-again'))}>Try again</button></>}
586
601
  </div>
587
602
  </div>
588
603
  )
@@ -27,8 +27,13 @@ export interface JamCard {
27
27
  file?: string
28
28
  /** who runs it now (spec 29b): your session, a copy of it, or a fresh agent - and where it stands */
29
29
  runner?: JamRunner
30
+ /** the occurrence counters a notice's click compares (spec 28 A4.6 #9, #30): how many times it entered review or
31
+ * failed, and its batch's failures. Absent reads 0 */
32
+ att?: number
33
+ fails?: number
30
34
  }
31
- export interface JamRunner { kind: 'session' | 'fork' | 'fresh'; agent: string; state?: 'offered' | 'claimed' | 'stalled' | 'stopping' | 'waiting'; why?: string; batch: string; gen?: number }
35
+ /** `stalls`: how many times its claim went quiet (A4.6 #9; absent reads 0) */
36
+ export interface JamRunner { kind: 'session' | 'fork' | 'fresh'; agent: string; state?: 'offered' | 'claimed' | 'stalled' | 'stopping' | 'waiting'; why?: string; batch: string; gen?: number; stalls?: number }
32
37
  /** A coding-agent session connected to this repo (spec 29b): the selected one takes the work while a Jam session runs. */
33
38
  export interface JamSession { id: string; agent: 'claude' | 'codex' | 'cursor'; busy: boolean; selected: boolean; since: number; mode?: string }
34
39
  /** What Jam does on this machine: the config with the start sheet's switches over it. */