@marver-design/marver 0.29.0 → 0.30.1

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 (76) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +2 -1
  3. package/dist/{anchor-check-DhlpKl2K.mjs → anchor-check-Bv4o-R2T.mjs} +1 -1
  4. package/dist/{build-CWbrb2bl.mjs → build-zWGXSzly.mjs} +5 -4
  5. package/dist/cli.mjs +5 -5
  6. package/dist/{daemon-Sc_z8gT6.mjs → daemon-CChgWJNq.mjs} +2 -2
  7. package/dist/{dev-DWBKQhxf.mjs → dev-DOgIITpT.mjs} +8 -8
  8. package/dist/{perf-Denssrko.mjs → perf-6MOTHxay.mjs} +710 -99
  9. package/dist/perf-BCxAo0IS.mjs +1743 -0
  10. package/dist/{plugin-DqoZB-D6.mjs → plugin-CFWBcAba.mjs} +928 -539
  11. package/dist/{poster-CrsjqhY4.mjs → poster-DPPpQiva.mjs} +1 -1
  12. package/dist/{publish-bakes-DW-NDgU2.mjs → publish-bakes-_Zx8crP3.mjs} +2 -2
  13. package/dist/{recover-GtJ9UDAB.mjs → recover-mDUVsnPd.mjs} +1 -1
  14. package/dist/{shot-T04Ixrvq.mjs → shot-d4h_hJi9.mjs} +3 -3
  15. package/docs/app.md +194 -0
  16. package/docs/performance.md +100 -19
  17. package/package.json +1 -1
  18. package/src/client/frame-host/bridge.js +17 -8
  19. package/src/client/frame-host/inplace.ts +124 -0
  20. package/src/client/frame-host/inspect.d.ts +1 -0
  21. package/src/client/frame-host/inspect.js +13 -4
  22. package/src/client/frame-host/main.tsx +12 -3
  23. package/src/client/frame-host/messages.ts +85 -0
  24. package/src/client/frame-host/signals.d.ts +15 -0
  25. package/src/client/frame-host/signals.js +219 -0
  26. package/src/client/recorder-level.ts +41 -0
  27. package/src/client/shell/App.tsx +158 -88
  28. package/src/client/shell/BoardList.tsx +103 -48
  29. package/src/client/shell/Comments.tsx +66 -42
  30. package/src/client/shell/ContextMenu.tsx +3 -2
  31. package/src/client/shell/JamSurface.tsx +116 -71
  32. package/src/client/shell/LockedApp.tsx +19 -3
  33. package/src/client/shell/Play.tsx +94 -58
  34. package/src/client/shell/StatusPicker.tsx +19 -9
  35. package/src/client/shell/Toolbar.tsx +15 -7
  36. package/src/client/shell/api.ts +18 -4
  37. package/src/client/shell/app-bridge.ts +12 -6
  38. package/src/client/shell/app-perf.ts +31 -1
  39. package/src/client/shell/canvas/Canvas.tsx +17 -6
  40. package/src/client/shell/canvas/FrameNode.tsx +25 -12
  41. package/src/client/shell/canvas/Sticky.tsx +4 -2
  42. package/src/client/shell/canvas/ctl.ts +2 -0
  43. package/src/client/shell/canvas/ready-watch.ts +4 -0
  44. package/src/client/shell/canvas/sleep.ts +2 -0
  45. package/src/client/shell/canvas/updates.ts +13 -6
  46. package/src/client/shell/commands.ts +765 -0
  47. package/src/client/shell/comments-store.ts +42 -27
  48. package/src/client/shell/goto.ts +11 -6
  49. package/src/client/shell/jam-keys.ts +141 -75
  50. package/src/client/shell/jam-lane.tsx +19 -12
  51. package/src/client/shell/jam-panel.tsx +61 -48
  52. package/src/client/shell/jam-session.tsx +41 -37
  53. package/src/client/shell/jam-state.ts +9 -1
  54. package/src/client/shell/jam-surface-parts.tsx +8 -6
  55. package/src/client/shell/jam-ui.tsx +9 -6
  56. package/src/client/shell/jam-voice.ts +4 -2
  57. package/src/client/shell/main.tsx +7 -1
  58. package/src/client/shell/marks-ui.tsx +11 -0
  59. package/src/client/shell/perf.ts +51 -5
  60. package/src/client/shell/recorder-core.ts +4 -1
  61. package/src/client/shell/recorder-hmr.ts +36 -0
  62. package/src/client/shell/recorder-reloads.ts +264 -0
  63. package/src/client/shell/recorder-seams.ts +116 -0
  64. package/src/client/shell/recorder-self.ts +73 -0
  65. package/src/client/shell/recorder-signals-core.ts +139 -0
  66. package/src/client/shell/recorder-signals.ts +485 -0
  67. package/src/client/shell/recorder.ts +118 -43
  68. package/src/client/shell/store.ts +112 -32
  69. package/src/client/shell/whiteout-probes.ts +3 -1
  70. package/src/client/stage/main.tsx +10 -5
  71. package/src/shared/app-api.ts +28 -6
  72. package/src/shared/app-perf.ts +99 -6
  73. package/src/shared/app-report.ts +586 -0
  74. package/src/shared/perf-records.ts +445 -0
  75. package/src/shared/perf-run.ts +6 -2
  76. package/dist/perf-jam-CLkERSHo.mjs +0 -642
@@ -18,6 +18,9 @@ import { api, resumed, scoped, useLink } from './api.ts'
18
18
  import { animateLayout, Canvas, canvasCtl } from './canvas/Canvas.tsx'
19
19
  import { frameByWindow, fromLiveDocument } from './canvas/frame-registry.ts'
20
20
  import { recorder } from './recorder.ts'
21
+ import { perfSeams } from './recorder-seams.ts'
22
+ import { takeNavToken } from './recorder-reloads.ts'
23
+ import { cmd, endAfterFrames, endOnCamera, endOnLoad, endOnStage, foldsIntoSave, keysOf, shellReload, type CmdHandle, type CmdOpts } from './commands.ts'
21
24
  import { enterFocus, enterPlay, enterSlides, playCtl, PlayOverlay } from './Play.tsx'
22
25
  import { bootHash, linkTargets, parseHash, retargetBoot, UNPLACED, writeHash } from './hash.ts'
23
26
  import { isLegacyLink, landLegacy } from './legacy-links.ts'
@@ -30,7 +33,7 @@ import { goTo, isLatest, navigated, revealFrame, switchFor } from './goto.ts'
30
33
  import { useNotes } from './notes.ts'
31
34
  import { contentOnly } from '../../shared/frames.ts'
32
35
  import { nextToLook } from '../../shared/marks.ts'
33
- import { asksNow, Bubble, MarkedRow, useRollup, useSeenOnScreen } from './marks-ui.tsx'
36
+ import { asksNow, Bubble, MarkedRow, markSeenFrom, useRollup, useSeenOnScreen } from './marks-ui.tsx'
34
37
  import { CommentButton, DevicePicker, HideUIButton, LaserButton, Popover, ThemePicker, toggleHideUI, usePopover } from './Toolbar.tsx'
35
38
 
36
39
  const commentsStore = () => useComments.getState()
@@ -41,23 +44,24 @@ let booted = false // survives Fast Refresh; see the
41
44
  * selected frame - a quiet secondary wash so ancestry survives collapsing the group.
42
45
  * `renaming` swaps the label for an input: the scene's TITLE (its brief's front matter) -
43
46
  * the directory never moves from here. */
44
- function SceneGroup({ name, label, count, held, renaming, onRename, onPick, onContextMenu, ids, children }: { name: string; label: string; count: number; held: boolean; renaming?: boolean; onRename?: (title: string | null) => void; onPick?: () => void; onContextMenu?: (e: ReactMouseEvent) => void; ids: string[]; children: ReactNode }) {
47
+ function SceneGroup({ name, label, count, held, renaming, onRename, onPick, onContextMenu, ids, children }: { name: string; label: string; count: number; held: boolean; renaming?: boolean; onRename?: (title: string | null, h: CmdHandle) => void; onPick?: () => void; onContextMenu?: (e: ReactMouseEvent) => void; ids: string[]; children: ReactNode }) {
45
48
  const [open, setOpen] = useState(true)
46
49
  const fold = useRollup(open ? [] : ids) // only a folded scene rolls up (spec 25)
47
50
  const done = useRef(false) // Enter then blur: one commit
48
51
  if (renaming) { done.current = false }
49
- const finish = (v: string | null) => { if (done.current) return; done.current = true; onRename?.(v) }
52
+ // the rename's command starts where it is decided: Enter or leaving the field saves, Esc backs out (spec 30)
53
+ const finish = (v: string | null, how: CmdOpts) => { if (done.current) return; done.current = true; onRename?.(v, cmd('scene-rename', how)) }
50
54
  return (
51
55
  <div>
52
56
  {renaming ? (
53
57
  <div className="it editing">
54
58
  <CaretIcon size={11} className="tw" style={{ transform: open ? undefined : 'rotate(-90deg)' }} />
55
59
  <input autoFocus defaultValue={label} spellCheck={false} onFocus={(e) => e.currentTarget.select()}
56
- onKeyDown={(e) => { if (e.key === 'Enter') { e.preventDefault(); finish(e.currentTarget.value) } else if (e.key === 'Escape') { e.preventDefault(); finish(null) } }}
57
- onBlur={(e) => finish(e.currentTarget.value)} />
60
+ onKeyDown={(e) => { if (e.key === 'Enter') { e.preventDefault(); finish(e.currentTarget.value, { via: 'key', in: 'shell', keys: keysOf(e) }) } else if (e.key === 'Escape') { e.preventDefault(); finish(null, { via: 'key', in: 'shell', keys: keysOf(e) }) } }}
61
+ onBlur={(e) => finish(e.currentTarget.value, { via: 'click', in: 'shell' })} />
58
62
  </div>
59
63
  ) : (
60
- <button className={`it${held ? ' held' : ''}`} onClick={() => setOpen(!open)} onContextMenu={onContextMenu}>
64
+ <button className={`it${held ? ' held' : ''}`} onClick={() => { cmd('scene-toggle', { via: 'click', in: 'shell' }); setOpen(!open) }} onContextMenu={onContextMenu}>
61
65
  <CaretIcon size={11} className="tw" style={{ transform: open ? undefined : 'rotate(-90deg)' }} />
62
66
  {/* the NAME selects every frame in the scene; the caret/row still collapses */}
63
67
  <span onClick={(e) => { if (!onPick) return; e.stopPropagation(); onPick() }}>{label || '(root)'}</span>
@@ -84,7 +88,7 @@ export class ShellBoundary extends Component<{ children: ReactNode }, { err: Err
84
88
  <div style={{ fontFamily: 'ui-monospace, monospace', padding: 32 }}>
85
89
  <b style={{ color: '#a81f16' }}>shell crashed</b>
86
90
  <pre style={{ whiteSpace: 'pre-wrap', fontSize: 12 }}>{this.state.err.message}</pre>
87
- <button onClick={() => location.reload()}>reload</button>
91
+ <button onClick={() => { shellReload(cmd('shell-reload', { via: 'click', in: 'shell' })); location.reload() }}>reload</button>
88
92
  </div>
89
93
  )
90
94
  }
@@ -141,11 +145,12 @@ function SelectionBar() {
141
145
  const { resizeSelected, toast } = useStore.getState()
142
146
  const multi = selection.length > 1
143
147
  const applyDevice = (name: string) => {
148
+ foldsIntoSave(cmd('device', { via: 'click', in: 'shell', arg: name, frames: selection.length }))
144
149
  animateLayout()
145
150
  resizeSelected(name)
146
151
  setTimeout(() => canvasCtl.fitNodes(useStore.getState().selection), 30)
147
152
  }
148
- const setNodeTheme = (t: string) => useStore.getState().setSelectedTheme(t)
153
+ const setNodeTheme = (t: string) => { foldsIntoSave(cmd('theme', { via: 'click', in: 'shell', frames: selection.length })); useStore.getState().setSelectedTheme(t) }
149
154
  const selectedFrames = () => {
150
155
  const st = useStore.getState()
151
156
  return st.selection
@@ -204,12 +209,13 @@ function SelectionBar() {
204
209
  <Tip label={<><b>{multi ? `Copy ${selection.length} paths` : 'Copy path'}</b><span className="k">⇧P</span></>}>
205
210
  <button className="icon"
206
211
  onClick={() => {
212
+ const h = cmd('copy-path', { via: 'click', in: 'shell', frames: selection.length })
207
213
  const brd = useStore.getState().board
208
214
  const text = selectedFrames().map((f) => framePath(brd, f)).join('\n')
209
215
  for (const f of selectedFrames()) recordCopy('path', f.id)
210
216
  navigator.clipboard.writeText(text).then(
211
- () => { toast(multi ? `${selection.length} paths copied` : 'path copied'); useStore.getState().pulsePath() },
212
- () => toast('copy blocked - click the canvas first'))
217
+ () => { h.done(); toast(multi ? `${selection.length} paths copied` : 'path copied'); useStore.getState().pulsePath() },
218
+ () => { h.fail('clipboard-blocked'); toast('copy blocked - click the canvas first') })
213
219
  }}>{copied ? <CheckIcon size={15} /> : <SignpostIcon size={15} />}</button>
214
220
  </Tip>
215
221
  {/* copy as image: dev only (the renderer is the dev server's headless Chrome) and one
@@ -218,7 +224,7 @@ function SelectionBar() {
218
224
  <Tip label={multi ? 'Select one frame to copy as image' : <><b>Copy as image</b><span className="k">⇧i</span></>}>
219
225
  <button className={`icon${imageBusy ? ' busy' : ''}`} disabled={multi || imageBusy} aria-label="Copy as image"
220
226
  data-state={copiedImage ? 'copied' : imageBusy ? 'busy' : 'idle'}
221
- onClick={(e) => useStore.getState().copyFrameImage(e.shiftKey ? 4 : 2)}>
227
+ onClick={(e) => useStore.getState().copyFrameImage(e.shiftKey ? 4 : 2, { via: 'click', in: 'shell' })}>
222
228
  {copiedImage ? <CheckIcon size={15} /> : <ImagesSquareIcon size={15} />}
223
229
  </button>
224
230
  </Tip>
@@ -236,8 +242,9 @@ function DeviceMenu() {
236
242
  const nodes = useStore((s) => s.nodes)
237
243
  const scoped = selection.length > 0
238
244
  const pick = (name: string | null) => {
239
- animateLayout()
240
245
  const st = useStore.getState()
246
+ foldsIntoSave(cmd('device', { via: 'click', in: 'pill', arg: name ?? 'default', frames: st.selection.length }))
247
+ animateLayout()
241
248
  if (scoped) {
242
249
  st.resizeSelected(name)
243
250
  setTimeout(() => canvasCtl.fitNodes(useStore.getState().selection), 30)
@@ -273,8 +280,9 @@ function UpdatePill() {
273
280
  }, [])
274
281
  if (!latest || play) return null
275
282
  // init rides along so managed files (AGENTS.md, instructions/) refresh with the code
276
- const cmd = `npm i -D ${PKG}@latest && npx marver init`
283
+ const command = `npm i -D ${PKG}@latest && npx marver init`
277
284
  const dismiss = () => {
285
+ cmd('update-dismiss', { via: 'click', in: 'shell' })
278
286
  try { localStorage.setItem(scoped('mv-update-seen'), latest) } catch { /* storage unavailable */ }
279
287
  setLatest(null)
280
288
  }
@@ -284,9 +292,10 @@ function UpdatePill() {
284
292
  <Tip side="top" label="Copy, then paste to your terminal or your agent">
285
293
  <button className="cmd" onClick={() => {
286
294
  const t = useStore.getState().toast
287
- navigator.clipboard?.writeText(cmd).then(() => t('update command copied'), () => t('copy blocked - select it manually'))
288
- ?? t('copy unavailable - select it manually')
289
- }}><code>{cmd}</code></button>
295
+ const h = cmd('update-copy', { via: 'click', in: 'shell' })
296
+ navigator.clipboard?.writeText(command).then(() => { h.done(); t('update command copied') }, () => { h.fail('clipboard-blocked'); t('copy blocked - select it manually') })
297
+ ?? (h.fail('clipboard-blocked'), t('copy unavailable - select it manually'))
298
+ }}><code>{command}</code></button>
290
299
  </Tip>
291
300
  <Tip side="top" label="Dismiss this version">
292
301
  <button className="x" onClick={dismiss}><XIcon size={13} /></button>
@@ -309,15 +318,15 @@ function ZoomMenu() {
309
318
  </Tip>
310
319
  <Popover pop={pop}>
311
320
  {ZOOMS.map((z) => (
312
- <button key={z} onClick={() => go(() => canvasCtl.zoomTo(z))}>
321
+ <button key={z} onClick={() => go(() => { cmd('zoom-to', { via: 'click', in: 'pill' }); canvasCtl.zoomTo(z) })}>
313
322
  <span>{z * 100}%</span>
314
323
  {z === 1 && <kbd>⇧0</kbd>}
315
324
  {Math.abs(scale - z) < 0.03 && <CheckIcon size={13} className="chk" />}
316
325
  </button>
317
326
  ))}
318
327
  <i className="div" />
319
- <button onClick={() => go(canvasCtl.fitAll)}><span>Fit all</span><kbd>⇧1</kbd></button>
320
- <button onClick={() => go(() => { const k = useStore.getState().selection; if (k.length) canvasCtl.fitNodes(k) })}>
328
+ <button onClick={() => go(() => { cmd('fit-all', { via: 'click', in: 'pill' }); canvasCtl.fitAll() })}><span>Fit all</span><kbd>⇧1</kbd></button>
329
+ <button onClick={() => go(() => { const h = cmd('fit-selection', { via: 'click', in: 'pill' }); const k = useStore.getState().selection; if (k.length) canvasCtl.fitNodes(k); else h.noop('no-selection') })}>
321
330
  <span>Fit selection</span><kbd>⇧2</kbd>
322
331
  </button>
323
332
  </Popover>
@@ -343,12 +352,32 @@ function ThemeMenu() {
343
352
  const uniform = scoped ? (scope.length && scope.every((n) => n.theme === scope[0].theme) ? scope[0].theme : null) : viewTheme
344
353
  const pick = (t: string) => {
345
354
  const st = useStore.getState()
355
+ foldsIntoSave(cmd('theme', { via: 'click', in: 'pill', frames: st.selection.length || undefined }))
346
356
  scoped ? st.setSelectedTheme(t) : st.setTheme(t)
347
357
  }
348
358
  const hint = scoped ? `${selection.length} selected · D` : 'all frames · D'
349
359
  return <ThemePicker value={majority} checked={uniform} onSelect={pick} hint={hint} />
350
360
  }
351
361
 
362
+ /** P and the pill's Prototype (spec 30): `play` or `slides` as the board plays; nothing to play is a noop. */
363
+ function enterPlayFrom(how: CmdOpts) {
364
+ const slides = playsAsSlides(useStore.getState().board)
365
+ const h = cmd(slides ? 'slides' : 'play', how)
366
+ if (slides) enterSlides(); else enterPlay()
367
+ if (!useStore.getState().play) h.noop('nothing-to-play')
368
+ }
369
+ /** T and the pill's Tidy (spec 30): `tidy` ends with the layout animation; a board already tidy moved nothing. */
370
+ function tidyFrom(how: CmdOpts) {
371
+ const h = cmd('tidy', how)
372
+ foldsIntoSave(h)
373
+ const before = useStore.getState().nodes
374
+ animateLayout()
375
+ useStore.getState().runTidy()
376
+ const after = useStore.getState().nodes
377
+ const at = new Map(before.map((n) => [n.key, n]))
378
+ if (after.every((n) => { const b = at.get(n.key); return b && b.x === n.x && b.y === n.y && b.w === n.w && b.h === n.h })) h.noop('nothing-moved')
379
+ }
380
+
352
381
  export function App() {
353
382
  // B0.1: per-field selectors, NOT `useStore()` (which subscribes to the whole store and
354
383
  // re-rendered the entire shell on every setScale tick during a pan/zoom).
@@ -370,7 +399,7 @@ export function App() {
370
399
  // lean cover would hide them, so a body class suppresses the cover while either mode is active.
371
400
  useEffect(() => { document.body.classList.toggle('sh-laser', laser) }, [laser])
372
401
  useEffect(() => { document.body.classList.toggle('sh-commenting', commentMode) }, [commentMode])
373
- const { boot, applyManifest, togglePanel, select, setInteract, runTidy, toast, spawn } = useStore.getState()
402
+ const { boot, applyManifest, togglePanel, select, setInteract, toast, spawn } = useStore.getState()
374
403
  const [pillOpen, setPillOpen] = useState(true)
375
404
  const cm = useContextMenu() // shared sidebar right-click menu (boards + scenes)
376
405
  const [sceneNaming, setSceneNaming] = useState<string | null>(null) // the scene whose title is being edited inline
@@ -467,11 +496,19 @@ export function App() {
467
496
  // fire popstate AND hashchange, and a second switch to the same board would supersede the first - a second board
468
497
  // fetch, and a load that never committed in perf --loads
469
498
  let routing: { hash: string; switches: number } | null = null
499
+ // the recorder's (spec 30): back/forward fires both events, a same-board one with no switch to tell them apart
500
+ let recorded: { hash: string; at: number; h: CmdHandle | null; run: number } = { hash: '', at: -1_000, h: null, run: 0 }
470
501
  const onPop = async () => {
471
502
  // the same hash, and no switch or cancel since this router started its own (a board picked, a goto, a newer
472
503
  // navigation): the second event of the navigation the first is carrying through - board, frame and view
473
504
  if (routing && routing.hash === location.hash && routing.switches === switchCount()) return
474
505
  const raw = location.hash
506
+ // the second event carries the first's command on; the first, overtaken by its own twin, does not end it
507
+ const again = raw === recorded.hash && performance.now() - recorded.at < 250
508
+ const run = recorded.run + 1
509
+ const nav_ = again ? recorded.h : cmd('history-nav', { via: 'click', in: 'shell' })
510
+ recorded = { hash: raw, at: performance.now(), h: nav_, run }
511
+ const giveUp = () => { if (recorded.run === run) nav_?.cancel('superseded') }
475
512
  const nav = navigated() // a reveal still looking up its board must not land after this
476
513
  // a lookup below still running when newer navigation lands - a link, a board picked, a step in play - is dropped
477
514
  const at = useStore.getState().board, step = useStore.getState().play?.at
@@ -484,19 +521,20 @@ export function App() {
484
521
  // once, though back/forward fires two events
485
522
  const r = await landLegacy(h)
486
523
  const board = r.hash.board ?? await landingBoard()
487
- if (overtaken()) return
524
+ if (overtaken()) return giveUp()
488
525
  h = { ...r.hash, board }
489
526
  writeHash(h)
490
527
  if (r.notice) toast(r.notice)
491
528
  } else if (!h.board && !h.focus && !h.invite) {
492
529
  // the bare #/ opens the landing board
493
530
  const board = await landingBoard()
494
- if (overtaken()) return
531
+ if (overtaken()) return giveUp()
495
532
  h = { ...h, board }
496
533
  }
497
534
  let s = useStore.getState()
498
535
  if (h.board && h.board !== s.board) {
499
536
  if (s.play) s.setPlay(null) // a stale overlay must never survive into another board
537
+ if (nav_) endOnLoad(nav_, h.board) // another board: its load's way ends it (#49)
500
538
  const switched = switchFor(h.board, nav)
501
539
  const mine = routing = { hash: raw, switches: switchCount() }
502
540
  const landed = await switched
@@ -504,11 +542,14 @@ export function App() {
504
542
  // the switch failed (the projection effect re-syncs the URL), or a newer navigation came while this one's board
505
543
  // was read - a link, a goto, a board picked - and may have landed on this same board first: the board is the
506
544
  // newer one's then, and so are the selection, the mode and the camera
507
- if (!landed) return
545
+ if (!landed) return giveUp()
508
546
  s = useStore.getState()
509
547
  }
548
+ // the same board: where it leads ends it; another board's load already does
549
+ const here = nav_ && h.board === at ? nav_ : null
510
550
  // the thread an old link names (Comments.tsx opens every other link's): now, or once the new board's comments load
511
551
  if (legacy && h.c) { if (s.board !== at) parkThread(h.c); else revealThread(h.c) }
552
+ if (here) { if (h.focus || h.play) endOnStage(here, h.play?.at ?? h.focus?.at); else endOnCamera(here) }
512
553
  if (h.focus) {
513
554
  enterFocus(h.focus.at, { ...h.focus, deep: true })
514
555
  } else if (h.play) {
@@ -629,7 +670,8 @@ export function App() {
629
670
  const s = useStore.getState()
630
671
  if (m?.name !== s.board || m?.sha256 === s.boardHash || s.dirty) return
631
672
  const sel = s.selection
632
- s.boot().then((ok) => {
673
+ // who may have written it (spec 30 #18): what the dev server's write match found, never proven
674
+ s.boot(undefined, 'disk', m?.writer ? { writer: m.writer, candidates: m.candidates } : undefined).then((ok) => {
633
675
  if (!ok) return
634
676
  const nodes = useStore.getState().nodes
635
677
  useStore.setState({ selection: sel.filter((k) => nodes.some((n) => n.key === k)) })
@@ -649,9 +691,11 @@ export function App() {
649
691
  if (!reg) return
650
692
  const { key: nodeKey, iframe: el } = reg
651
693
  const s = useStore.getState()
694
+ // the recorder's (spec 30): every frame message, before the shell acts on it - never consumed here
695
+ perfSeams.frameMessage.emit(nodeKey, data)
652
696
  // Jam (spec 27): a capture's trail, handshake, probes and flushes; a key the shell owns
653
697
  if (onFrameMessage(nodeKey, data)) return
654
- if (data.type === 'sh:key') { if (typeof data.key === 'string') jamKey({ key: data.key, shift: !!data.shift, alt: !!data.alt, meta: !!data.meta, ctrl: !!data.ctrl }); return }
698
+ if (data.type === 'sh:key') { if (typeof data.key === 'string') jamKey({ key: data.key, shift: !!data.shift, alt: !!data.alt, meta: !!data.meta, ctrl: !!data.ctrl }, 'frame'); return }
655
699
 
656
700
  if (data.type === 'sh:ready') {
657
701
  // a WindowProxy survives navigation, so a ready queued by a SUPERSEDED document (one the
@@ -659,6 +703,8 @@ export function App() {
659
703
  // dropped by generation and document before it touches anything, so a stale ready never marks
660
704
  // a reloading frame ready, frees its admission slot or counts as seen
661
705
  if (!fromLiveDocument(el, data)) return
706
+ // spec 30 #14: what started this document, taken before setStatus pumps the next job and setShown moves its wait
707
+ const nav = takeNavToken(nodeKey, data)
662
708
  // a document that loaded again on its own (a full reload) is a new source revision: the
663
709
  // sleeping override of the previous document must not be trusted for this one
664
710
  if (s.nodes.find((n) => n.key === nodeKey)?.status === 'ready') s.bumpRev(nodeKey)
@@ -669,7 +715,7 @@ export function App() {
669
715
  // than the frame's last edit reloads
670
716
  const before = s.nodes.find((n) => n.key === nodeKey)?.shown
671
717
  if (typeof data.doc === 'string') s.setShown(nodeKey, data.doc)
672
- logReload({ kind: 'ready', cause: takeReloadCause(nodeKey) ?? (before === undefined ? 'first' : 'self'), node: nodeKey, frame: String(data.id ?? ''), shown: typeof data.doc === 'string' ? data.doc : undefined, ms: Number(data.phases?.commit) })
718
+ logReload({ kind: 'ready', cause: takeReloadCause(nodeKey) ?? (before === undefined ? 'first' : 'self'), node: nodeKey, frame: String(data.id ?? ''), shown: typeof data.doc === 'string' ? data.doc : undefined, ms: Number(data.phases?.commit), ...nav })
673
719
  } else if (data.type === 'sh:error') {
674
720
  // the same guard as sh:ready: an error from a document since replaced fails nothing and is not recorded
675
721
  if (!fromLiveDocument(el, data)) return
@@ -678,7 +724,7 @@ export function App() {
678
724
  } else if (data.type === 'sh:boot') {
679
725
  recorder.booted(nodeKey, data) // a new document: its node's outcome starts over (spec 28 A1.7)
680
726
  } else if (data.type === 'sh:exit-interact') {
681
- if (s.interact === nodeKey) setInteract(null)
727
+ if (s.interact === nodeKey) { cmd('interact-off', { via: 'key', in: 'frame', keys: 'Escape' }); setInteract(null) }
682
728
  } else if (data.type === 'sh:theme-applied') {
683
729
  if (typeof data.theme === 'string') s.setThemeOn(nodeKey, data.theme)
684
730
  } else if (data.type === 'sh:hmr') {
@@ -702,29 +748,30 @@ export function App() {
702
748
  // drop a stale post that outran a frame swap (the sender echoes its frame id)
703
749
  if (f && String(data.id ?? '') === f.id) {
704
750
  const addr = `[${s.board} ▸ ${f.scene || '(root)'}] ${f.file} · ${String(data.path ?? '')}${data.source ? ` (${String(data.source)})` : ''}`
751
+ const h = cmd('laser-copy', { via: 'click', in: 'frame', frame: f.id })
705
752
  // success confirms IN the frame's hover label (right where the eyes are);
706
753
  // only failure needs the toast
707
754
  navigator.clipboard.writeText(addr).then(
708
- () => el.contentWindow?.postMessage({ type: 'sh:copy-ok', seq: data.seq }, location.origin),
709
- () => toast('copy blocked - click the canvas first'))
755
+ () => { h.done(); el.contentWindow?.postMessage({ type: 'sh:copy-ok', seq: data.seq }, location.origin) },
756
+ () => { h.fail('clipboard-blocked'); toast('copy blocked - click the canvas first') })
710
757
  }
711
758
  } else if (data.type === 'sh:frame-down') {
712
759
  // clicks INSIDE a frame never reach the shell document - the frame reports
713
760
  // them so an open thread card dismisses modal-style from anywhere
714
761
  const c = commentsStore()
715
- if (c.active) c.setActive(null)
716
- letGoOfTile() // and a lane tile selected with nothing open for it, as a canvas click does
762
+ if (c.active) { cmd('thread-close', { via: 'click', in: 'frame' }); c.setActive(null) }
763
+ letGoOfTile({ via: 'click', in: 'frame' }) // and a lane tile selected with nothing open for it, as a canvas click does
717
764
  } else if (data.type === 'sh:picked') {
718
765
  // comment mode: the frame reports the picked element - stage the draft on
719
766
  // that node (picking while a thread is open replaces it, modal-style);
720
767
  // the CommentLayer opens the composer at the pin
721
768
  const c = commentsStore()
722
769
  if (c.active) c.setActive(null)
723
- if (c.commentMode) c.setDraft({ nodeKey, frame: String(data.id ?? ''), anchor: data.anchor })
770
+ if (c.commentMode) { cmd('comment-pick', { via: 'click', in: 'frame', frame: String(data.id ?? '') }); c.setDraft({ nodeKey, frame: String(data.id ?? ''), anchor: data.anchor }) }
724
771
  } else if (data.type === 'sh:go') {
725
772
  // a goto from inside an interacting frame CARRIES interact mode to the target - walking
726
773
  // a flow must not eject you to design mode at every hop (and must survive a board switch)
727
- goTo(String(data.target ?? ''), s.interact === nodeKey)
774
+ goTo(String(data.target ?? ''), s.interact === nodeKey, cmd('goto', { via: 'click', in: 'frame' }))
728
775
  } else if (data.type === 'sh:wheel') {
729
776
  // B0.2: a passive frame forwarded a wheel event; the canvas owns it. Never for the
730
777
  // interact target or play (the app scrolls itself - the parent stays authoritative).
@@ -768,64 +815,77 @@ export function App() {
768
815
  // with Option a Mac types a symbol (⌥L is "¬"): an Alt shortcut is named by the key pressed
769
816
  const key = e.altKey && /^Key[A-Z]$/.test(e.code) ? e.code.slice(3).toLowerCase() : e.key
770
817
  if (!e.repeat && jamKey({ key, shift: e.shiftKey, alt: e.altKey, meta: e.metaKey, ctrl: e.ctrlKey })) { e.preventDefault(); return }
771
- if ((e.metaKey || e.ctrlKey) && e.key === '\\') { e.preventDefault(); togglePanel(); return }
772
- if ((e.metaKey || e.ctrlKey) && e.key === '/') { e.preventDefault(); setPillOpen((o) => !o); return }
773
- if ((e.metaKey || e.ctrlKey) && e.key === 'a') { e.preventDefault(); s.selectAll(); return }
818
+ // how this input arrived, for each command below (#50); a relayed menu item (#51) is told apart by cmd() itself
819
+ const how = (k = e.key): CmdOpts => ({ via: 'key', in: 'shell', keys: keysOf(e, k) })
820
+ if ((e.metaKey || e.ctrlKey) && e.key === '\\') { e.preventDefault(); cmd('panel', how()); togglePanel(); return }
821
+ if ((e.metaKey || e.ctrlKey) && e.key === '/') { e.preventDefault(); cmd('toolbar', how()); setPillOpen((o) => !o); return }
822
+ if ((e.metaKey || e.ctrlKey) && e.key === 'a') { e.preventDefault(); cmd('select-all', how()); s.selectAll(); return }
774
823
  if (e.metaKey || e.ctrlKey) return
775
824
  if (e.key === 'Escape') {
776
825
  const c = commentsStore()
777
- if (c.commentMode || c.active || c.draft) { c.setMode(false); c.setActive(null); c.setDraft(null) }
778
- else if (s.laser) s.setLaser(false) // Escape also exits laser mode (parity with comment)
779
- else s.interact ? setInteract(null) : select(null)
826
+ const h = cmd('escape', how())
827
+ if (c.commentMode || c.active || c.draft) { h.step('comments-off'); c.setMode(false); c.setActive(null); c.setDraft(null) }
828
+ else if (s.laser) { h.step('laser-off'); s.setLaser(false) } // Escape also exits laser mode (parity with comment)
829
+ else if (s.interact) { h.step('interact-off'); setInteract(null) }
830
+ else { h.step('deselect'); select(null) }
831
+ endAfterFrames(h)
780
832
  }
781
833
  // a slides board PLAYS as slides even when its landing is the canvas -
782
834
  // the deck is what the board IS; landing only says where viewers arrive
783
- if (e.key === 'p') { if (playsAsSlides(useStore.getState().board)) enterSlides(); else enterPlay() }
835
+ if (e.key === 'p') enterPlayFrom(how())
784
836
  // H hides all chrome (shared binary Hide-UI); press again to reveal. Not persisted,
785
837
  // so a refresh always restores it (the safety net for a forgotten toggle).
786
- if (e.key === 'h') { toggleHideUI(); return }
787
- if (e.key === 't') { animateLayout(); runTidy() }
838
+ if (e.key === 'h') { cmd('hide-ui', how()); toggleHideUI(); return }
839
+ if (e.key === 't') tidyFrom(how())
788
840
  // laser and comment mode are one-at-a-time: comment mode already highlights
789
841
  // what you'd click, so stacking the full rainbow on top only adds noise
790
842
  // L: the pointer laser (the element under the cursor); ⌥L: inspect (every element outlined)
791
- if (key === 'l' && !e.shiftKey && SOURCE_REVEALED) {
792
- e.preventDefault()
793
- commentsStore().setMode(false)
794
- s.toggleLaser(e.altKey)
843
+ if (key === 'l' && !e.shiftKey) {
844
+ const h = cmd(e.altKey ? 'inspect' : 'laser', how(key))
845
+ if (!SOURCE_REVEALED) h.noop('stripped')
846
+ else {
847
+ e.preventDefault()
848
+ commentsStore().setMode(false)
849
+ s.toggleLaser(e.altKey)
850
+ }
795
851
  }
796
852
  // C = comment mode (the Figma/Miro convention) · Shift+C = hide/show
797
853
  // pins · Shift+P = copy file path(s) (P alone is play; D6, changelog 0.4.0)
798
854
  if (e.key === 'c' && !e.shiftKey) {
799
855
  const c = commentsStore()
800
- if (!c.commentMode && s.board === UNPLACED) return void toast(NO_COMMENTS_HERE)
801
- if (!c.commentMode && stoppedFor('Comments need the canvas running')) return
856
+ const h = cmd('comments', how())
857
+ if (!c.commentMode && s.board === UNPLACED) { h.noop('unplaced'); return void toast(NO_COMMENTS_HERE) }
858
+ if (!c.commentMode && stoppedFor('Comments need the canvas running')) { h.noop('stopped'); return }
802
859
  if (!c.commentMode) s.setLaser(false)
803
860
  c.setMode(!c.commentMode)
804
861
  toast(c.commentMode ? 'comment mode off' : 'comment mode - click an element in a frame')
805
862
  }
806
- if (e.key === 'C' && e.shiftKey) { const c = commentsStore(); c.setShow(!c.show) }
863
+ if (e.key === 'C' && e.shiftKey) { const c = commentsStore(); cmd('pins', how()); c.setShow(!c.show) }
807
864
  // sticky notes (spec 18): any note visible -> hide all; none -> show all
808
865
  // U: the next frame that needs you, else the next new one (spec 25)
809
866
  if (e.key === 'u' && !e.shiftKey && !PUBLISHED) {
867
+ const h = cmd('next-new', how())
810
868
  const live = s.nodes.filter((n) => !n.missing).sort((a, b) => a.y - b.y || a.x - b.x)
811
869
  const from = s.selection.length ? s.nodes.find((n) => n.key === s.selection[s.selection.length - 1])?.frame ?? null : null
812
870
  const id = nextToLook(s.marks, asksNow(), [...new Set(live.map((n) => n.frame))], from)
813
871
  const n = id ? live.find((x) => x.frame === id) : null
814
- if (n) { s.select(n.key); canvasCtl.fitNode(n.key) } else toast('nothing new on this board')
872
+ if (n) { s.select(n.key); canvasCtl.fitNode(n.key) } else { h.noop('nothing-new'); toast('nothing new on this board') }
815
873
  return
816
874
  }
817
- if (e.key === 'n' && !e.shiftKey) { const visible = document.querySelectorAll('.sh-notes:not(.off)').length > 0; useNotes.getState().toggleAll(visible); toast(visible ? 'notes hidden' : 'notes shown'); return }
875
+ if (e.key === 'n' && !e.shiftKey) { cmd('notes', how()); const visible = document.querySelectorAll('.sh-notes:not(.off)').length > 0; useNotes.getState().toggleAll(visible); toast(visible ? 'notes hidden' : 'notes shown'); return }
818
876
  // Shift+L = laser comment: the laser-sharp lighting on the element a comment tags
819
877
  // (pick hover, compose lock, open-thread highlight). Pins and cards stay - this
820
878
  // only dims the lighting inside the artwork.
821
879
  if (e.key === 'L' && e.shiftKey) {
822
880
  const c = commentsStore()
881
+ cmd('laser-comment', how())
823
882
  c.setShowAnchor(!c.showAnchor)
824
883
  toast(c.showAnchor ? 'laser comment off' : 'laser comment on')
825
884
  }
826
885
  // I = copy the selected frame as a 2x PNG · Shift+I = 4x (dev only; one frame at a time)
827
- if ((e.key === 'i' || e.key === 'I') && !PUBLISHED && !e.altKey && !e.repeat) { s.copyFrameImage(e.shiftKey ? 4 : 2); return }
828
- if (e.key === 'P' && e.shiftKey && s.selection.length) {
886
+ if ((e.key === 'i' || e.key === 'I') && !PUBLISHED && !e.altKey && !e.repeat) { s.copyFrameImage(e.shiftKey ? 4 : 2, how()); return }
887
+ if (e.key === 'P' && e.shiftKey) {
888
+ const h = cmd('copy-path', { ...how(), frames: s.selection.length })
829
889
  const paths = s.selection
830
890
  .map((k) => { const n = s.nodes.find((x) => x.key === k); const f = n && s.frameFor(n); return f ? framePath(s.board, f) : undefined })
831
891
  .filter((p): p is string => !!p)
@@ -833,14 +893,17 @@ export function App() {
833
893
  // pulse the toolbar icon into a check ONLY on a real copy success
834
894
  for (const k of s.selection) { const f = s.frameFor(s.nodes.find((x) => x.key === k)!); if (f) recordCopy('path', f.id) }
835
895
  navigator.clipboard.writeText(paths.join('\n')).then(
836
- () => { toast(paths.length > 1 ? `${paths.length} paths copied` : 'path copied'); s.pulsePath() },
837
- () => toast('copy blocked - click the canvas first'))
838
- }
896
+ () => { h.done(); toast(paths.length > 1 ? `${paths.length} paths copied` : 'path copied'); s.pulsePath() },
897
+ () => { h.fail('clipboard-blocked'); toast('copy blocked - click the canvas first') })
898
+ } else h.noop('no-selection')
839
899
  }
840
- if (e.key === 'd' && CONFIG.themes.length > 1) {
900
+ if (e.key === 'd') {
901
+ const h = cmd('theme', { ...how(), frames: s.selection.length || undefined })
902
+ foldsIntoSave(h)
903
+ if (CONFIG.themes.length <= 1) h.noop('one-theme')
841
904
  // scoped like the device digits: selection pins those frames; no selection cycles
842
905
  // the global VIEW theme (sticky across boards - the user's preference)
843
- if (s.selection.length) {
906
+ else if (s.selection.length) {
844
907
  const scope = s.nodes.filter((n) => s.selection.includes(n.key))
845
908
  const cur = scope.length && scope.every((n) => n.theme === scope[0].theme) ? scope[0].theme : CONFIG.themes[0]
846
909
  s.setSelectedTheme(CONFIG.themes[(CONFIG.themes.indexOf(cur) + 1) % CONFIG.themes.length])
@@ -848,15 +911,17 @@ export function App() {
848
911
  s.setTheme(CONFIG.themes[(CONFIG.themes.indexOf(s.viewTheme) + 1) % CONFIG.themes.length])
849
912
  }
850
913
  }
851
- if (e.shiftKey && e.code === 'Digit0') canvasCtl.zoom100()
852
- if (e.shiftKey && e.code === 'Digit1') canvasCtl.fitAll()
853
- if (e.shiftKey && e.code === 'Digit2' && s.selection.length) canvasCtl.fitNodes(s.selection)
914
+ if (e.shiftKey && e.code === 'Digit0') { cmd('zoom-100', how('0')); canvasCtl.zoom100() }
915
+ if (e.shiftKey && e.code === 'Digit1') { cmd('fit-all', how('1')); canvasCtl.fitAll() }
916
+ if (e.shiftKey && e.code === 'Digit2') { const h = cmd('fit-selection', how('2')); if (s.selection.length) canvasCtl.fitNodes(s.selection); else h.noop('no-selection') }
854
917
  // plain digits: 0 = default, 1..n = devices. Scoped to the selection when one
855
918
  // exists, board-wide otherwise. Every path tidies - presets never scramble layout.
856
919
  if (!e.shiftKey && /^Digit[0-9]$/.test(e.code)) {
857
920
  const idx = Number(e.code.slice(5))
858
921
  const names = Object.keys(CONFIG.viewports)
859
- if (idx !== 0 && !names[idx - 1]) return
922
+ const h = cmd('device', { ...how(String(idx)), frames: s.selection.length || undefined })
923
+ if (idx !== 0 && !names[idx - 1]) { h.noop('unknown-device'); return }
924
+ foldsIntoSave(h)
860
925
  const name = idx === 0 ? null : names[idx - 1]
861
926
  animateLayout()
862
927
  if (s.selection.length) {
@@ -936,7 +1001,7 @@ export function App() {
936
1001
  </a>
937
1002
  </Tip>
938
1003
  <span className="name" title={CONFIG.projectName || 'Marver'}>{CANVAS_NAME}</span>
939
- <Tip side="bottom" label={<><b>Collapse panel</b><span>⌘\</span></>}><button className="sh-ibtn" onClick={togglePanel} tabIndex={panelOpen ? 0 : -1}><PanelFilledIcon size={17} /></button></Tip>
1004
+ <Tip side="bottom" label={<><b>Collapse panel</b><span>⌘\</span></>}><button className="sh-ibtn" onClick={() => { cmd('panel', { via: 'click', in: 'shell' }); togglePanel() }} tabIndex={panelOpen ? 0 : -1}><PanelFilledIcon size={17} /></button></Tip>
940
1005
  </div>
941
1006
  <div className="sh-panel-scroll">
942
1007
  <BoardList onMenu={cm.open} />
@@ -946,24 +1011,25 @@ export function App() {
946
1011
  ids={frames.filter((f) => f.scene === sc.name).map((f) => f.id)}
947
1012
  held={frames.some((f) => f.scene === sc.name && selFrames.has(f.id))}
948
1013
  renaming={sceneNaming === sc.name}
949
- onRename={(raw) => {
1014
+ onRename={(raw, h) => {
950
1015
  setSceneNaming(null)
951
1016
  const title = raw === null ? undefined : readTitle(raw)
952
- if (!title || title === sceneLabel(sc.name)) return // Escape, empty, or unchanged = never mind
953
- if (scenes.some((o) => o.name !== sc.name && sceneLabel(o.name) === title)) { toast(`a scene called "${title}" already exists`); return }
1017
+ if (!title || title === sceneLabel(sc.name)) { h.cancel(); return } // Escape, empty, or unchanged = never mind
1018
+ if (scenes.some((o) => o.name !== sc.name && sceneLabel(o.name) === title)) { h.fail('exists'); toast(`a scene called "${title}" already exists`); return }
954
1019
  // typing what the directory reads as anyway clears the title - the brief stays clean
955
- useStore.getState().renameScene(sc.name, title === slugLabel(sc.name) ? '' : title).then((r) => { if (!r.ok) toast(r.error ?? 'rename failed') })
1020
+ useStore.getState().renameScene(sc.name, title === slugLabel(sc.name) ? '' : title).then((r) => { if (r.ok) h.done(); else { h.fail('api'); toast(r.error ?? 'rename failed') } }, () => h.fail('api'))
956
1021
  }}
957
1022
  onContextMenu={(e) => cm.open(e, [{
958
1023
  label: 'Copy path',
959
1024
  icon: <SignpostIcon size={15} />,
960
1025
  onClick: () => copyToClipboard(sc.name
961
1026
  ? `board: ${useStore.getState().board} · scene: ${sc.name} (design/scenes/${sc.name}/)`
962
- : `board: ${useStore.getState().board} · scene: (root)`, 'path copied'),
1027
+ : `board: ${useStore.getState().board} · scene: (root)`, 'path copied', cmd('copy-path', { via: 'context', in: 'shell' })),
963
1028
  }, ...(!PUBLISHED && sc.name ? [{ label: 'Rename', icon: <PencilSimpleIcon size={15} />, onClick: () => setSceneNaming(sc.name) }] : []),
964
- ...(!PUBLISHED ? [{ label: 'Mark all as seen', icon: <CheckIcon size={15} />, onClick: () => useStore.getState().markSeen(frames.filter((f) => f.scene === sc.name).map((f) => f.id)) }] : [])])}
1029
+ ...(!PUBLISHED ? [{ label: 'Mark all as seen', icon: <CheckIcon size={15} />, onClick: () => markSeenFrom({ via: 'context', in: 'shell' }, frames.filter((f) => f.scene === sc.name).map((f) => f.id)) }] : [])])}
965
1030
  onPick={() => {
966
1031
  const keys = nodes.filter((n) => frames.some((f) => f.scene === sc.name && f.id === n.frame) && !n.missing).map((n) => n.key)
1032
+ cmd('scene-pick', { via: 'click', in: 'shell', frames: keys.length })
967
1033
  if (!keys.length) return
968
1034
  useStore.getState().selectMany(keys)
969
1035
  canvasCtl.fitNodes(keys)
@@ -991,11 +1057,12 @@ export function App() {
991
1057
  const go = (id: string, shift: boolean) => {
992
1058
  const n = nodeFor(id)
993
1059
  if (!n) return
1060
+ cmd('frame-pick', { via: 'click', in: 'shell', frame: id })
994
1061
  select(n.key, shift)
995
1062
  if (!shift) canvasCtl.fitNode(n.key)
996
1063
  }
997
1064
  const frameMenu = (fr: FrameEntry): MenuItem[] => [
998
- { label: 'Copy path', icon: <SignpostIcon size={15} />, onClick: () => { recordCopy('path', fr.id); copyToClipboard(framePath(useStore.getState().board, fr), 'path copied') } },
1065
+ { label: 'Copy path', icon: <SignpostIcon size={15} />, onClick: () => { recordCopy('path', fr.id); copyToClipboard(framePath(useStore.getState().board, fr), 'path copied', cmd('copy-path', { via: 'context', in: 'shell', frame: fr.id })) } },
999
1066
  // the Not on a board view (spec 26): put the frame where it belongs
1000
1067
  ...(useStore.getState().board === UNPLACED ? [{ label: 'Add to board…', icon: <PlusIcon size={15} />, panel: (close: () => void) => <AddToBoard frame={fr.id} close={close} /> }] : []),
1001
1068
  ]
@@ -1020,7 +1087,7 @@ export function App() {
1020
1087
  rows.push(
1021
1088
  <div key={`g:${f.variantGroup}`} className={`sub vgroup${allOn ? ' on' : ''}${held ? ' held' : ''}`}
1022
1089
  title="Select all variants"
1023
- onClick={() => { useStore.getState().selectMany(memberKeys); canvasCtl.fitNodes(memberKeys) }}>
1090
+ onClick={() => { cmd('group-fit', { via: 'click', in: 'shell', frames: memberKeys.length }); useStore.getState().selectMany(memberKeys); canvasCtl.fitNodes(memberKeys) }}>
1024
1091
  <VariantsIcon size={13} className="iicon" />
1025
1092
  <span className="glabel">{rel}</span>
1026
1093
  </div>,
@@ -1064,7 +1131,7 @@ export function App() {
1064
1131
  </div>
1065
1132
  </aside>
1066
1133
  <Tip side="bottom" label={<><b>Open panel</b><span>⌘\</span></>}>
1067
- <button className={`sh-fab${panelOpen ? ' hidden' : ''}`} onClick={togglePanel}
1134
+ <button className={`sh-fab${panelOpen ? ' hidden' : ''}`} onClick={() => { cmd('panel', { via: 'click', in: 'shell' }); togglePanel() }}
1068
1135
  aria-hidden={panelOpen} tabIndex={panelOpen ? -1 : 0}><PanelHollowIcon size={18} /></button>
1069
1136
  </Tip>
1070
1137
 
@@ -1076,7 +1143,7 @@ export function App() {
1076
1143
  {/* Jam V2 (spec 27 Part 5): the session - between Laser and Tidy */}
1077
1144
  {!PUBLISHED && CONFIG.jam && <JamButton />}
1078
1145
  <Tip side="bottom" label={<><b>Tidy layout</b><span>T</span></>}>
1079
- <button className="sh-pill-btn" onClick={() => { animateLayout(); runTidy() }}><ColumnsIcon size={16} /></button>
1146
+ <button className="sh-pill-btn" onClick={() => tidyFrom({ via: 'click', in: 'pill' })}><ColumnsIcon size={16} /></button>
1080
1147
  </Tip>
1081
1148
  <i className="sep" />
1082
1149
  <DeviceMenu />
@@ -1086,17 +1153,17 @@ export function App() {
1086
1153
  <i className="sep" />
1087
1154
  {/* far right: view management - prototype, hide, collapse */}
1088
1155
  <Tip side="bottom" label={<><b>Prototype view</b><span>P</span></>}>
1089
- <button className="sh-pill-btn" onClick={() => (playsAsSlides(useStore.getState().board) ? enterSlides() : enterPlay())}><PlayIcon size={15} /></button>
1156
+ <button className="sh-pill-btn" onClick={() => enterPlayFrom({ via: 'click', in: 'pill' })}><PlayIcon size={15} /></button>
1090
1157
  </Tip>
1091
1158
  <HideUIButton />
1092
1159
  <Tip side="bottom" label={<><b>Collapse toolbar</b><span>⌘/</span></>}>
1093
- <button className="sh-pill-btn" onClick={() => setPillOpen(false)} tabIndex={pillOpen ? 0 : -1}>
1160
+ <button className="sh-pill-btn" onClick={() => { cmd('toolbar', { via: 'click', in: 'pill' }); setPillOpen(false) }} tabIndex={pillOpen ? 0 : -1}>
1094
1161
  <PanelFilledIcon size={17} style={{ transform: 'rotate(90deg)' }} />
1095
1162
  </button>
1096
1163
  </Tip>
1097
1164
  </nav>
1098
1165
  <Tip side="bottom" label={<><b>Open toolbar</b><span>⌘/</span></>}>
1099
- <button className={`sh-pill-fab${pillOpen ? ' hidden' : ''}`} onClick={() => setPillOpen(true)}
1166
+ <button className={`sh-pill-fab${pillOpen ? ' hidden' : ''}`} onClick={() => { cmd('toolbar', { via: 'click', in: 'pill' }); setPillOpen(true) }}
1100
1167
  aria-hidden={pillOpen} tabIndex={pillOpen ? -1 : 0}><PanelHollowIcon size={18} style={{ transform: 'rotate(90deg)' }} />{recording && <i className="jm-live-dot jm-fab-dot" />}</button>
1101
1168
  </Tip>
1102
1169
 
@@ -1254,15 +1321,15 @@ function JamToasts({ toasts }: { toasts: import('./store.ts').Toast[] }) {
1254
1321
  <div className="sh-jam-list">
1255
1322
  <div className="sh-jam-listhead">
1256
1323
  <span>{jams.length} NOTIFICATIONS</span>
1257
- <button onClick={() => { useStore.getState().clearJamToasts(); setExpanded(false) }}>Clear all</button>
1258
- <button aria-label="Collapse" onClick={() => setExpanded(false)}><XIcon size={12} /></button>
1324
+ <button onClick={() => { cmd('notices-clear', { via: 'click', in: 'shell' }); useStore.getState().clearJamToasts(); setExpanded(false) }}>Clear all</button>
1325
+ <button aria-label="Collapse" onClick={() => { cmd('notices-collapse', { via: 'click', in: 'shell' }); setExpanded(false) }}><XIcon size={12} /></button>
1259
1326
  </div>
1260
1327
  {[...jams].reverse().map((t) => <JamToast key={t.id} id={t.id} note={t.jam!} />)}
1261
1328
  </div>
1262
1329
  )}
1263
1330
  {!expanded && (deck
1264
1331
  ? (
1265
- <div className="sh-jam-deck" onClick={() => setExpanded(true)} role="button" aria-label={`${jams.length} notifications - expand`}>
1332
+ <div className="sh-jam-deck" onClick={() => { cmd('notices-expand', { via: 'click', in: 'shell' }); setExpanded(true) }} role="button" aria-label={`${jams.length} notifications - expand`}>
1266
1333
  <div className="sh-jam-ghost g2" />
1267
1334
  <div className="sh-jam-ghost g1" />
1268
1335
  {newest?.jam && <JamToast id={newest.id} note={newest.jam} badge={jams.length - 1} inert />}
@@ -1286,27 +1353,30 @@ function JamAvatar({ author }: { author: { name?: string; avatar?: string; id?:
1286
1353
  * (the current board may show the thread's frame); only when it doesn't, switch to the
1287
1354
  * note's origin board and retry while its comments load. Dismiss only on success: a
1288
1355
  * cross-board note must never be a destructive no-op. */
1289
- async function viewNote(note: import('./store.ts').JamNote, dismiss: () => void) {
1290
- if (revealThread(note.threadId)) { dismiss(); return }
1356
+ async function viewNote(note: import('./store.ts').JamNote, dismiss: () => void, h: CmdHandle) {
1357
+ if (revealThread(note.threadId)) { h.done(); dismiss(); return }
1291
1358
  const s = useStore.getState()
1292
1359
  // a navigation: a link still finding its board gives way to it - and it to a newer one, wherever this one has got to
1293
1360
  const nav = navigated()
1294
1361
  // a thread in the old all-scenes log has no board of its own: its frame's board shows it (spec 26)
1295
1362
  if (note.board === ALL_SCENES) { if (note.frame) await revealFrame(note.frame, nav) }
1296
- else if (note.board && s.board !== note.board && !await switchFor(note.board, nav)) return
1363
+ else if (note.board && s.board !== note.board && !await switchFor(note.board, nav)) return h.fail('missing')
1297
1364
  for (let i = 0; i < 12 && isLatest(nav); i++) {
1298
- if (revealThread(note.threadId)) { dismiss(); return }
1365
+ if (revealThread(note.threadId)) { h.done(); dismiss(); return }
1299
1366
  await new Promise((r) => setTimeout(r, 250))
1300
1367
  }
1368
+ h.fail('missing')
1301
1369
  }
1302
1370
 
1303
1371
  /** Retry a batch's failed jam cards from their notice - each one still failed (a newer change wins). */
1304
- async function retryNote(failed: { card: string; rev: number }[]) {
1372
+ async function retryNote(failed: { card: string; rev: number }[], h: CmdHandle) {
1305
1373
  const { useJamQueue } = await import('./jam-queue.ts')
1374
+ let found = false, refused = false
1306
1375
  for (const f of failed) {
1307
1376
  const card = useJamQueue.getState().cards?.find((c) => c.id === f.card)
1308
- if (card && card.state === 'failed') await useJamQueue.getState().act(card, 'retry')
1377
+ if (card && card.state === 'failed') { found = true; if (!await useJamQueue.getState().act(card, 'retry')) refused = true }
1309
1378
  }
1379
+ if (refused) h.fail('refused'); else if (!found) h.fail('missing'); else h.done()
1310
1380
  }
1311
1381
 
1312
1382
  /** One jam pill, frame-first: row 1 = intent icon + FRAME TITLE (blue) · age; row 2 = Marver · preview.
@@ -1332,9 +1402,9 @@ function JamToast({ id, note, badge, inert }: { id: number; note: import('./stor
1332
1402
  {badge != null
1333
1403
  ? <span className="sh-jam-badge">+{badge}</span>
1334
1404
  : !inert && <>
1335
- {note.failed && <button className="sh-jam-view" onClick={() => { void retryNote(note.failed!); dismiss() }}>Retry</button>}
1336
- {note.threadId && <button className="sh-jam-view" onClick={() => void viewNote(note, () => useStore.getState().advanceToast(id))}>View</button>}
1337
- <button className="sh-jam-x" aria-label="Dismiss" onClick={dismiss}><XIcon size={13} /></button>
1405
+ {note.failed && <button className="sh-jam-view" onClick={() => { void retryNote(note.failed!, cmd('notice-retry', { via: 'click', in: 'shell' })); dismiss() }}>Retry</button>}
1406
+ {note.threadId && <button className="sh-jam-view" onClick={() => void viewNote(note, () => useStore.getState().advanceToast(id), cmd('notice-view', { via: 'click', in: 'shell' }))}>View</button>}
1407
+ <button className="sh-jam-x" aria-label="Dismiss" onClick={() => { cmd('notice-dismiss', { via: 'click', in: 'shell' }); dismiss() }}><XIcon size={13} /></button>
1338
1408
  </>}
1339
1409
  </div>
1340
1410
  )