@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
@@ -8,6 +8,7 @@
8
8
  * a capture open E end (queued at once) · ⇧E end to review · S says to end it first · N notes card · I picture · Esc drop
9
9
  * a review open ⏎ looks good · ⇧⏎ more work · → later / next · ← back · B before/after ·
10
10
  * ⌥← ⌥→ frame tabs · Esc leave
11
+ * a thread panel open Esc close it
11
12
  * the lane has the keys ← → move · ⏎ open · ⌘⏎ do next · K keep · ⌫ drop · Esc leave
12
13
  * a session sheet open ⏎ start (the start sheet) · Esc close it
13
14
  * always S start a capture · J the session (start it, or end it) · Q the lane · V next capture to review
@@ -15,15 +16,23 @@
15
16
  * The same table says which keys the shell owns right now; they are mirrored into every frame (a
16
17
  * frame consumes an owned key - before a focused button sees ⏎ - and forwards it). `Tab` is never
17
18
  * owned. A tag's card never reaches `Q`, `V`, `K` or `⌘⏎`: it lives in its thread.
19
+ *
20
+ * A key the table takes is a command (spec 30 R12), named in its row and started before what it does; one no state takes
21
+ * records nothing here (the shell's own handler has it). State set in the key's turn ends two frames on (`sync`); work
22
+ * that answers a boolean ends on the answer (`endOnOk`).
18
23
  */
19
24
  import { useJamCapture, setOwnedKeys } from './jam-capture.ts'
20
25
  import { changedShots, useJamQueue, type JamCard } from './jam-queue.ts'
21
- import { DONE_CLOSE, DONE_GROUP, doneFold, useJamUi } from './jam-state.ts'
26
+ import { DONE_CLOSE, DONE_GROUP, doneFold, endOnOk, jamSurface, useJamUi } from './jam-state.ts'
22
27
  import { pressJ, startSession, wrapWrite } from './jam-session.tsx'
23
28
  import { clearMoreDraft } from './jam-panel.tsx'
24
29
  import { CONFIG, PUBLISHED, SOURCE_REVEALED, useStore } from './store.ts'
30
+ import { ALL_SCENES } from '../../shared/board-tree.ts'
25
31
  import { holdsReload } from './api.ts'
32
+ import { navigated, switchFor } from './goto.ts'
26
33
  import { unsavedWhen, workChanged } from './unsaved.ts'
34
+ import { cmd, endAfterFrames, type CmdHandle, type CmdOpts } from './commands.ts'
35
+ import type { CmdIn } from '../../shared/perf-records.ts'
27
36
 
28
37
  export interface KeyIn { key: string; shift?: boolean; alt?: boolean; meta?: boolean; ctrl?: boolean }
29
38
  /** `[Ctrl+][Meta+][Alt+][Shift+]key`, a letter lowercase - the frames' descriptor (keys.js). */
@@ -55,18 +64,20 @@ const latest = new Map<string, number>()
55
64
  let gen = 0
56
65
  /** The words written for a card that have not saved yet - the read-back keeps showing them. */
57
66
  export const pendingEdit = (id: string): string | undefined => unsaved.get(id)
58
- /** Save the read-back's edit (the text stays where it is if the save fails - see `decideDraft`). */
59
- export function saveEdit(c: JamCard, text: string) {
67
+ /** Save the read-back's edit (the text stays where it is if the save fails - see `decideDraft`): answers whether it saved. */
68
+ export function saveEdit(c: JamCard, text: string): Promise<boolean> {
60
69
  const g = ++gen
61
70
  latest.set(c.id, g)
62
71
  unsaved.set(c.id, text)
63
72
  workChanged()
64
73
  const before = saving.get(c.id) ?? Promise.resolve(true)
65
74
  // saves of one card run in order, each at the card's rev as the one before left it
66
- saving.set(c.id, before.then(() => {
75
+ const p = before.then(() => {
67
76
  const fresh = useJamQueue.getState().cards?.find((x) => x.id === c.id) ?? c
68
77
  return useJamQueue.getState().act(fresh, 'edit', text)
69
- }).then((ok) => { if (ok && latest.get(c.id) === g) { unsaved.delete(c.id); workChanged() } return ok }))
78
+ }).then((ok) => { if (ok && latest.get(c.id) === g) { unsaved.delete(c.id); workChanged() } return ok })
79
+ saving.set(c.id, p)
80
+ return p
70
81
  }
71
82
  /** Notes added in a read-back not saved yet, per card: each with its own id - one on its way, or one that failed
72
83
  * and waits to be sent again. Sent again (from the field, or before a decision) it keeps its id: the server
@@ -113,33 +124,34 @@ async function notesSaved(id: string): Promise<boolean> {
113
124
 
114
125
  /** Confirm or keep a draft AFTER its edit has saved - an edit that failed is saved again first, and
115
126
  * nothing is sent while it still fails; at the card's new rev; the panel closes once the decision
116
- * took, and a refusal says why. */
117
- export async function decideDraft(id: string, action: 'confirm' | 'keep' | 'drop') {
127
+ * took, and a refusal says why. Answers whether it took. */
128
+ export async function decideDraft(id: string, action: 'confirm' | 'keep' | 'drop'): Promise<boolean> {
118
129
  await saving.get(id)
119
130
  if (action !== 'drop' && unsaved.has(id)) {
120
131
  const c = useJamQueue.getState().cards?.find((x) => x.id === id)
121
132
  if (c) saveEdit(c, unsaved.get(id)!)
122
133
  await saving.get(id)
123
- if (unsaved.has(id)) { useStore.getState().toast('your edit could not be saved - look at it again before you send it'); return }
134
+ if (unsaved.has(id)) { useStore.getState().toast('your edit could not be saved - look at it again before you send it'); return false }
124
135
  }
125
136
  // a note added in its read-back goes with it: one that did not save is sent again, and nothing is sent without it
126
- if (action !== 'drop' && unsavedNotes.has(id) && !(await notesSaved(id))) { useStore.getState().toast('your note could not be added - try again before you send it'); return }
137
+ if (action !== 'drop' && unsavedNotes.has(id) && !(await notesSaved(id))) { useStore.getState().toast('your note could not be added - try again before you send it'); return false }
127
138
  if (action === 'drop') { unsaved.delete(id); unsavedNotes.delete(id); workChanged() }
128
139
  const fresh = useJamQueue.getState().cards?.find((c) => c.id === id)
129
- if (!fresh) return
130
- if (await useJamQueue.getState().act(fresh, action)) useJamUi.getState().close()
131
- else useStore.getState().toast(`the capture could not be ${action === 'confirm' ? 'queued' : action === 'keep' ? 'kept' : 'dropped'} - look again`)
140
+ if (!fresh) return false
141
+ if (await useJamQueue.getState().act(fresh, action)) { useJamUi.getState().close(); return true }
142
+ useStore.getState().toast(`the capture could not be ${action === 'confirm' ? 'queued' : action === 'keep' ? 'kept' : 'dropped'} - look again`)
143
+ return false
132
144
  }
133
145
 
134
146
  /** Leave a field in the open panel (its words save on blur) - before anything takes the panel away. */
135
147
  const leavePanelField = () => { const a = document.activeElement; if (a instanceof HTMLElement && a.closest('.jm-focus')) a.blur() }
136
148
 
137
149
  /** Resume a draft that ended too soon: its edit saves first (the resumed capture carries it on), the
138
- * read-back closes, and recording goes on where it stopped. */
139
- export async function resumeDraft(id: string) {
150
+ * read-back closes, and recording goes on where it stopped. Answers whether it did. */
151
+ export async function resumeDraft(id: string): Promise<boolean> {
140
152
  const cap = useJamCapture.getState()
141
- if (cap.current) { useStore.getState().toast('a capture is recording - press E to end it first'); return }
142
- if (cap.settling || cardById(id)?.state !== 'draft') return
153
+ if (cap.current) { useStore.getState().toast('a capture is recording - press E to end it first'); return false }
154
+ if (cap.settling || cardById(id)?.state !== 'draft') return false
143
155
  // first, at once: leave the editor (its words start saving) and lock the words - from here on nothing
144
156
  // typed can race the start; the lock holds through every wait and is let go at the end
145
157
  if (useJamUi.getState().panel?.id === id) leavePanelField()
@@ -153,73 +165,192 @@ export async function resumeDraft(id: string) {
153
165
  if (unsavedNotes.has(id) && !(await notesSaved(id))) { useStore.getState().toast('your note could not be added - try again before you resume'); return false }
154
166
  return cardById(id)?.state === 'draft'
155
167
  }
156
- if (!(await settled())) return
157
- if (await useJamCapture.getState().resume(id, settled)) {
158
- // as the UI is NOW (another panel may have opened meanwhile): only what points at it
159
- const ui = useJamUi.getState()
160
- if (ui.panel?.id === id) ui.close()
161
- // its tile has stepped aside: nothing points at it, and the lane gives its keys back
162
- if (ui.selected === id) { ui.select(null); ui.setLaneKeys(false) }
163
- }
168
+ if (!(await settled())) return false
169
+ if (!(await useJamCapture.getState().resume(id, settled))) return false
170
+ // as the UI is NOW (another panel may have opened meanwhile): only what points at it
171
+ const ui = useJamUi.getState()
172
+ if (ui.panel?.id === id) ui.close()
173
+ // its tile has stepped aside: nothing points at it, and the lane gives its keys back
174
+ if (ui.selected === id) { ui.select(null); ui.setLaneKeys(false) }
175
+ return true
164
176
  } finally { useJamCapture.setState({ settling: null }) }
165
177
  }
166
178
 
179
+ /** A request's life (spec 28 A4.6 #30): read before every step that moves the UI. A click passes none - always true. */
180
+ export type Alive = () => boolean
181
+ const always: Alive = () => true
182
+ /** How long a click waits for a board, a thread or a panel to draw; a notice's request has its own deadline in `alive`. */
183
+ const waitMs = (o: { alive?: Alive }, away = false) => (o.alive ? 10_000 : away ? 6_000 : 3_000)
184
+ /** Wait until `ok`, while `alive` holds and `ms` lasts: false once `alive` fails first, or the time is up. */
185
+ async function waitFor(ok: () => boolean, alive: Alive, ms: number): Promise<boolean> {
186
+ const until = performance.now() + ms
187
+ for (;;) {
188
+ if (!alive()) return false
189
+ if (ok()) return true
190
+ if (performance.now() > until) return false
191
+ await new Promise((r) => setTimeout(r, 30))
192
+ }
193
+ }
194
+ const drawn = (sel: string) => () => !!document.querySelector(sel)
195
+ /** A card's status popover, open (jam-ui.tsx TagStatus): its run's controls on the page. */
196
+ const statusOpen = (card: string) => `.cm-tstat.on[data-jam-card="${CSS.escape(card)}"]`
197
+
198
+ /** Another board (A4.6 #30). A request's switch commits only while its `alive` holds, read just before the board commits
199
+ * (store.ts switchBoard): words typed while the board loads, a hidden tab, the deadline or a later click leave the board,
200
+ * its draft and its open thread as they were - a hash set and left to the router would land whatever came after. A
201
+ * click (no request) follows the board's link, as before. True once the board is shown. */
202
+ export async function toBoard(board: string, alive?: Alive): Promise<boolean> {
203
+ if (!alive) {
204
+ location.hash = `#/b/${encodeURIComponent(board)}`
205
+ return waitFor(() => useStore.getState().board === board, always, waitMs({}, true))
206
+ }
207
+ if (!alive()) return false
208
+ // a stale overlay never survives into another board (App.tsx's router does the same)
209
+ if (useStore.getState().play) useStore.getState().setPlay(null)
210
+ // the wait is the request's too, however long the board's save or read takes (code review r2 P2) - and the switch,
211
+ // should it finish later, cannot commit: its predicate is alive, which never holds again once it failed (open-item.ts)
212
+ return (await whileAlive(switchFor(board, navigated(), alive), alive)) && alive()
213
+ }
214
+
215
+ /** `p`, or false as soon as `alive` fails, read every 30 ms: a request never waits past its own life - its deadline, or
216
+ * its end - whatever it waits on (a board's save or read, a hidden view's frames). The look stops once either settles. */
217
+ async function whileAlive<T>(p: Promise<T>, alive: Alive): Promise<T | false> {
218
+ // a click has no request to outlive: it waits on `p` alone, leaving no look behind in a hidden view (code review r4 P3)
219
+ if (alive === always) return p
220
+ let done = false
221
+ const ended = new Promise<false>((r) => { const look = () => { if (done) return; if (!alive()) { r(false); return } setTimeout(look, 30) }; look() })
222
+ try { return await Promise.race([p, ended]) } finally { done = true }
223
+ }
224
+
225
+ /** Play is left, then a frame passes for the layout (A4.6 r4 #1): what opens on the canvas - a thread card, a tile and
226
+ * its menu - is never drawn under the Play overlay, and the lane is folded there. Left with no way back to its frame
227
+ * (playCtl.leave, not Esc's exit): Esc's return - a fit, or a switch to the board a frame of another board lives on -
228
+ * would run outside the request, and land on another board over a reply typed after the thread opened (code review r2
229
+ * P1). False when `alive` failed, or when Play could not be left - a board locked to its mode has no way out (Play.tsx
230
+ * `noDoor`); the caller tells them apart by `alive()` and opens over Play instead. */
231
+ async function leavePlay(alive: Alive): Promise<boolean> {
232
+ if (!useStore.getState().play) return true
233
+ const { playCtl } = await import('./Play.tsx')
234
+ if (!alive()) return false
235
+ if (!playCtl.leave() || useStore.getState().play) return false
236
+ // two frames for the layout, under the request: a hidden view can hold its frames for good (code review r3 P2), and
237
+ // the frame asked for is cancelled once the request has ended
238
+ let raf = 0
239
+ const laid = await whileAlive(new Promise<true>((r) => { raf = requestAnimationFrame(() => { raf = requestAnimationFrame(() => r(true)) }) }), alive)
240
+ if (!laid) cancelAnimationFrame(raf)
241
+ return laid && alive()
242
+ }
243
+
167
244
  /** What clicking a tile (or ⏎ on it) does: a review opens the review detail, a card that asks opens
168
- * its thread, any other capture its detail - the read-back for a draft. */
169
- export function openTile(id: string) {
245
+ * its thread, any other capture its detail - the read-back for a draft. True once its surface is drawn. */
246
+ export async function openTile(id: string, o: { alive?: Alive } = {}): Promise<boolean> {
247
+ const alive = o.alive ?? always
170
248
  const c = cardById(id)
249
+ if (!c || !alive()) return false
171
250
  const ui = useJamUi.getState()
172
- if (!c) return
173
251
  if (c.state === 'asks' && c.thread) {
174
252
  ui.select(id)
175
- openThread(c)
176
- return
253
+ return openThreadAt(c.board, c.thread, { card: c, alive })
177
254
  }
255
+ // a request's card on another board: that board first, under the request (a click's reveal follows the link)
256
+ if (o.alive && c.board !== useStore.getState().board && !(await toBoard(c.board, o.alive))) return false
178
257
  ui.open({ kind: c.state === 'review' ? 'review' : c.kind === 'wrapup' ? 'wrapup' : 'capture', id })
179
- reveal(c)
258
+ reveal(c, o.alive)
259
+ return waitFor(() => useJamUi.getState().panel?.id === id && !!document.querySelector('[data-jam-focus]'), alive, waitMs(o))
180
260
  }
181
261
 
182
- /** Open a card's thread where you can see it, as a notification does - on another board, its link opens that board,
183
- * then the thread; on this one, its frame is brought into view (Comments.revealThread: since `E` moves nothing, the
184
- * canvas is often far from it). The board's comments still loading: tried again for a few seconds. A thread this
185
- * board cannot show (its frame is on no node here): the capture's own panel opens instead - for a card that asks,
186
- * with its question and a field to answer it - so a click is never a no-op. */
187
- export function openThread(c: JamCard) {
188
- if (!c.thread) return
189
- // on another board: its link opens that board (and the thread, when its frame is there) - then the same as here, so
190
- // a thread that board cannot show still opens the capture's panel on the first click
191
- const away = c.board !== useStore.getState().board
192
- if (away) location.hash = `#/b/${encodeURIComponent(c.board)}?c=${encodeURIComponent(c.thread)}`
193
- const thread = c.thread
194
- void Promise.all([import('./Comments.tsx'), import('./comments-store.ts')]).then(async ([{ revealThread }, { useComments }]) => {
195
- const until = performance.now() + (away ? 6_000 : 3_000)
196
- for (;;) {
197
- if (useStore.getState().board !== c.board) {
198
- // still on its way there - or another board opened meanwhile: this one's thread is not there to open
199
- if (!away || performance.now() > until) return
200
- await new Promise((r) => setTimeout(r, 250))
201
- continue
202
- }
203
- if (revealThread(thread)) return
204
- // known, and still not shown: its frame is on no node of this board - no wait helps
205
- if (useComments.getState().threads.some((t) => t.id === thread) || performance.now() > until) break
206
- await new Promise((r) => setTimeout(r, 250))
207
- }
208
- if (useStore.getState().board !== c.board || c.kind !== 'capture') return
262
+ /**
263
+ * Open a thread where you can see it (spec 28 A4.6 #30, r1 #3, r2 #2, r3 #1) - one helper for notices and every path
264
+ * that opens a thread. On another board, that board opens first (toBoard) - the legacy all-scenes log is no board a link
265
+ * lands on (App.tsx sends it elsewhere), so its threads open on the board shown. An open thread whose frame a node of
266
+ * the board hosts shows in its thread card: Play left first, comments hidden by Shift+C turned on (a hidden layer draws
267
+ * nothing), then revealed; Play that cannot be left (a board locked to its mode) keeps the canvas under it, so the
268
+ * thread opens over Play as an unhosted one does. A capture's thread with no host opens the capture's own panel - with
269
+ * its question and a field when it asks - as in 0.28. Every other thread - frameless, its frame gone, resolved - opens
270
+ * in the thread panel, a resolved one read-only. `status` (a card id) asks that card's status icon to open its popover once, in its thread
271
+ * card or the thread panel: the run's controls in view. True only once a surface for the thread is drawn - its card
272
+ * mounted, or a panel open on it, and with `status` that popover open; false when `alive` failed first.
273
+ */
274
+ export async function openThreadAt(board: string, thread: string, o: { card?: JamCard; status?: string; alive?: Alive } = {}): Promise<boolean> {
275
+ const alive = o.alive ?? always
276
+ const away = board !== ALL_SCENES && board !== useStore.getState().board
277
+ const ms = waitMs(o, away)
278
+ if (away && !(await toBoard(board, o.alive))) return false
279
+ const [{ revealThread }, { useComments }, { threadHostKey }] = await Promise.all([import('./Comments.tsx'), import('./comments-store.ts'), import('./keys.ts')])
280
+ const find = () => useComments.getState().threads.find((t) => t.id === thread && (!t.board || t.board === board))
281
+ // the board's comments may still be loading: known, or the time is up
282
+ await waitFor(() => !!find(), alive, ms)
283
+ if (!alive()) return false
284
+ const t = find()
285
+ const ok = (sel: string) => waitFor(() => drawn(sel)() && (!o.status || drawn(statusOpen(o.status))()), alive, ms)
286
+ // only an open thread has a card (the layer keeps open threads); Play kept, a card would draw under it
287
+ let host = t && !t.resolved ? threadHostKey(t, useStore.getState().nodes) : null
288
+ if (host && !(await leavePlay(alive))) {
289
+ if (!alive()) return false
290
+ host = null
291
+ }
292
+ if (host) {
293
+ if (!useComments.getState().show) { if (!alive()) return false; useComments.getState().setShow(true) }
294
+ if (!alive()) return false
295
+ if (o.status) useJamUi.getState().askStatus(o.status)
296
+ if (!revealThread(thread, alive)) return false
297
+ return ok(`.cm-card[data-thread="${CSS.escape(thread)}"]`)
298
+ }
299
+ const c = o.card
300
+ if (c?.kind === 'capture' && !t?.resolved) {
301
+ if (!alive()) return false
209
302
  useJamUi.getState().select(c.id)
210
303
  useJamUi.getState().open({ kind: 'capture', id: c.id })
211
- reveal(c)
212
- })
304
+ reveal(c, o.alive)
305
+ return ok('[data-jam-readback]')
306
+ }
307
+ if (!t || !alive()) return false
308
+ if (o.status) useJamUi.getState().askStatus(o.status)
309
+ useJamUi.getState().open({ kind: 'thread', id: thread, board })
310
+ return ok(`[data-jam-thread-panel="${CSS.escape(thread)}"]`)
311
+ }
312
+
313
+ /** Open a card's thread where you can see it, as a notification does (openThreadAt): a click is never a no-op. */
314
+ export function openThread(c: JamCard): Promise<boolean> {
315
+ return c.thread ? openThreadAt(c.board, c.thread, { card: c }) : Promise.resolve(false)
316
+ }
317
+
318
+ /**
319
+ * A failed or stalled run's controls in view (spec 28 A4.6 #30, r3 #1), true only once they are on the page. A comment
320
+ * card has no tile: its thread opens with its status popover open on Retry or the three choices - in its thread card,
321
+ * or the thread panel. A capture or a record (the cards with a tile): failed, its panel with Retry and Drop in its
322
+ * footer; stalled, its tile selected and the tile's menu opened at it (Play left first: Play folds the lane - Play that
323
+ * cannot be left opens its lane over the stage, as Q does there).
324
+ */
325
+ export async function openRunControls(c: JamCard, o: { alive?: Alive } = {}): Promise<boolean> {
326
+ const alive = o.alive ?? always
327
+ if (c.kind === 'comment') return c.thread ? openThreadAt(c.board, c.thread, { card: c, status: c.id, alive }) : false
328
+ if (c.state === 'failed') return (await openTile(c.id, o)) && waitFor(drawn('[data-jam-focus] [data-jam-run-act="retry"]'), alive, waitMs(o))
329
+ if (!(await leavePlay(alive))) {
330
+ if (!alive()) return false
331
+ useJamUi.getState().setLaneKeys(true)
332
+ }
333
+ if (!(await waitFor(drawn(`.jm-lane [data-tile="${CSS.escape(c.id)}"]`), alive, waitMs(o)))) return false
334
+ if (!alive()) return false
335
+ useJamUi.getState().select(c.id)
336
+ if (!jamSurface.tileMenu(c.id)) return false
337
+ return waitFor(drawn(`.sh-ctxmenu[data-menu="tile:${CSS.escape(c.id)}"]`), alive, waitMs(o))
213
338
  }
214
339
 
215
- /** Bring a card's frames into view beside the panel - on its own board (a frame link lands there). */
216
- export function reveal(c: JamCard) {
340
+ /** Bring a card's frames into view beside the panel - on its own board (a frame link lands there). A request's `alive`
341
+ * (A4.6 #30) is read again when the camera moves: one that ended meanwhile - a later click, a hidden tab, the deadline,
342
+ * words typed - moves nothing, and its board is switched under it (toBoard), never by a link. */
343
+ export function reveal(c: JamCard, alive?: Alive) {
217
344
  const s = useStore.getState()
218
345
  if (!c.frames.length) return
219
- if (c.board !== s.board) { location.hash = `#/b/${encodeURIComponent(c.board)}?f=${c.frames.map(encodeURIComponent).join(',')}`; return }
346
+ if (c.board !== s.board) {
347
+ if (!alive) location.hash = `#/b/${encodeURIComponent(c.board)}?f=${c.frames.map(encodeURIComponent).join(',')}`
348
+ else void toBoard(c.board, alive).then((ok) => { if (ok) reveal(c, alive) })
349
+ return
350
+ }
220
351
  const keys = s.nodes.filter((n) => c.frames.includes(n.frame)).map((n) => n.key)
221
352
  // after the panel has drawn, so the fit measures it and lands the frames in the space right of it
222
- if (keys.length) void import('./canvas/ctl.ts').then(({ canvasCtl }) => requestAnimationFrame(() => requestAnimationFrame(() => canvasCtl.fitNodes(keys))))
353
+ if (keys.length) void import('./canvas/ctl.ts').then(({ canvasCtl }) => requestAnimationFrame(() => requestAnimationFrame(() => { if (!alive || alive()) canvasCtl.fitNodes(keys) })))
223
354
  }
224
355
 
225
356
  /** The next capture to review after `from` (or the oldest), walking the lane left to right. */
@@ -233,7 +364,11 @@ function nextReview(from?: string, step = 1) {
233
364
  const act = (c: JamCard | undefined, action: Parameters<ReturnType<typeof useJamQueue.getState>['act']>[1], body?: string) =>
234
365
  c ? useJamQueue.getState().act(c, action, body) : Promise.resolve(false)
235
366
 
236
- interface Row { on(): boolean; keys: Record<string, () => void> }
367
+ /** A state, and what each of its keys does: given how the key arrived, each names its command (spec 30). */
368
+ interface Row { on(): boolean; keys: Record<string, (o: CmdOpts) => void> }
369
+
370
+ /** A key's effect that is state set in this turn: its `h` ends on the Jam state's transition, two frames on. */
371
+ const sync = (h: CmdHandle, change: () => void) => { change(); endAfterFrames(h) }
237
372
 
238
373
  /** The run on screen, when a review is open: a capture started now binds it. */
239
374
  function reviewNow(): { card: string; batch: string; rev: number } | undefined {
@@ -243,22 +378,32 @@ function reviewNow(): { card: string; batch: string; rev: number } | undefined {
243
378
  return ui.panel?.kind === 'review' && c?.kind === 'capture' && c.batch ? { card: c.id, batch: c.batch, rev: c.rev } : undefined
244
379
  }
245
380
 
246
- /** Esc while a laser (pointer or inspect) is on turns it off, and that is all it does. */
247
- const laserOff = (): boolean => { const st = useStore.getState(); if (!st.laser) return false; st.setLaser(false); return true }
381
+ /** Esc while a laser (pointer or inspect) is on turns it off, and that is all it does: the shell's `escape`. */
382
+ const laserOff = (o: CmdOpts): boolean => {
383
+ const st = useStore.getState()
384
+ if (!st.laser) return false
385
+ const h = cmd('escape', o)
386
+ h.step('laser-off')
387
+ sync(h, () => st.setLaser(false))
388
+ return true
389
+ }
248
390
 
249
391
  /** Start a capture, as S does: one made while a capture's review is open follows that review (its run).
250
392
  * `session`: the session it belongs to when the queue may not show it yet (a session's Start). */
251
393
  export const startCapture = (session?: string) => useJamCapture.getState().start(reviewNow(), session)
252
394
 
395
+ /** `jam-capture`, once it asked for one: a capture recording now, or refused - the canvas stopped, a wrap-up, no board. */
396
+ export const endOnRecording = (h: CmdHandle) => { if (useJamCapture.getState().current) endAfterFrames(h); else h.fail('refused') }
397
+
253
398
  /** A laser on (pointer or inspect): its keys come first - Esc turns it off before it closes, drops or leaves anything -
254
399
  * and are owned, so they work from inside a frame too (a laser click puts the focus there). The one row a published
255
400
  * canvas has (where its source is revealed - the only place a laser exists there). */
256
401
  const laserRow: Row = {
257
402
  on: () => useStore.getState().laser,
258
403
  keys: {
259
- l: () => useStore.getState().toggleLaser(false),
260
- 'Alt+l': () => useStore.getState().toggleLaser(true),
261
- Escape: () => useStore.getState().setLaser(false),
404
+ l: (o) => { cmd('laser', o); useStore.getState().toggleLaser(false) },
405
+ 'Alt+l': (o) => { cmd('inspect', o); useStore.getState().toggleLaser(true) },
406
+ Escape: (o) => { const h = cmd('escape', o); h.step('laser-off'); sync(h, () => useStore.getState().setLaser(false)) },
262
407
  },
263
408
  }
264
409
  const rowsNow = (): Row[] => (PUBLISHED ? (SOURCE_REVEALED ? [laserRow] : []) : rows())
@@ -267,63 +412,91 @@ const rows = (): Row[] => {
267
412
  const cap = useJamCapture.getState()
268
413
  const ui = useJamUi.getState()
269
414
  const panelCard = cardById(ui.panel?.id)
415
+ /** A frame tab, as far as there are tabs (⌥← ⌥→): at the ends nothing moves. */
416
+ const tabTo = (h: CmdHandle, i: number) => {
417
+ const to = Math.min(Math.max(1, changedShots(panelCard?.shots).length) - 1, Math.max(0, i))
418
+ if (to === ui.tab) h.noop('end'); else sync(h, () => ui.setTab(to))
419
+ }
270
420
  return [
271
421
  laserRow,
272
422
  { // a session sheet open: the start sheet's ⏎ starts; Esc closes either (the wrap-up's field keeps its own keys)
273
423
  on: () => ui.sheet === 'start' || ui.sheet === 'wrap',
274
424
  keys: {
275
- Enter: () => { if (ui.sheet === 'start') void startSession(); else wrapWrite.current?.() },
276
- Escape: () => ui.setSheet(null),
425
+ Enter: (o) => {
426
+ if (ui.sheet === 'start') { void endOnOk(cmd('jam-start', o), startSession()); return }
427
+ const h = cmd('jam-wrap-send', o)
428
+ if (wrapWrite.current) wrapWrite.current(h); else h.fail('refused')
429
+ },
430
+ Escape: (o) => { cmd('jam-sheet-close', o); ui.setSheet(null) },
277
431
  // over the wrap-up, no new capture starts (it would miss the record): close the sheet first
278
- ...(ui.sheet === 'wrap' ? { s: () => useStore.getState().toast('the session is wrapping up - close the sheet (Esc) to capture again') } : {}),
432
+ ...(ui.sheet === 'wrap' ? { s: (o: CmdOpts) => { cmd('jam-capture', o).fail('refused'); useStore.getState().toast('the session is wrapping up - close the sheet (Esc) to capture again') } } : {}),
279
433
  },
280
434
  },
281
435
  { // a read-back open
282
436
  on: () => ui.panel?.kind === 'capture' && panelCard?.state === 'draft',
283
437
  keys: {
284
- Enter: () => void decideDraft(panelCard!.id, 'confirm'),
285
- k: () => void decideDraft(panelCard!.id, 'keep'),
286
- r: () => void resumeDraft(panelCard!.id),
438
+ Enter: (o) => void endOnOk(cmd('jam-confirm', o), decideDraft(panelCard!.id, 'confirm')),
439
+ k: (o) => void endOnOk(cmd('jam-keep', o), decideDraft(panelCard!.id, 'keep')),
440
+ r: (o) => void endOnOk(cmd('jam-resume', o), resumeDraft(panelCard!.id)),
287
441
  // a laser on: Esc turns it off first - never a drop by the way
288
- Escape: () => { if (laserOff()) return; void decideDraft(panelCard!.id, 'drop') },
442
+ Escape: (o) => { if (laserOff(o)) return; void endOnOk(cmd('jam-drop', o), decideDraft(panelCard!.id, 'drop')) },
289
443
  },
290
444
  },
291
445
  { // the notes card open (in its field, the field handles its own keys)
292
446
  on: () => cap.noteOpen,
293
447
  keys: {
294
- Escape: () => cap.setNoteOpen(false),
295
- n: () => window.dispatchEvent(new CustomEvent('mv-jam-note-focus')),
448
+ Escape: (o) => { cmd('jam-notes-close', o); cap.setNoteOpen(false) },
449
+ n: (o) => sync(cmd('jam-notes', o), () => window.dispatchEvent(new CustomEvent('mv-jam-note-focus'))),
296
450
  },
297
451
  },
298
452
  { // a capture open
299
453
  on: () => !!cap.current,
300
454
  keys: {
301
- e: () => cap.end(), // straight to the queue
302
- 'Shift+e': () => cap.end(true), // stop to review: its read-back opens
303
- s: () => cap.start(), // one at a time: it says to end this one first
455
+ e: (o) => sync(cmd('jam-end', o), () => cap.end()), // straight to the queue
456
+ 'Shift+e': (o) => sync(cmd('jam-end-review', o), () => cap.end(true)), // stop to review: its read-back opens
457
+ s: (o) => { const h = cmd('jam-capture', o); cap.start(); h.fail('refused') }, // one at a time: it says to end this one first
304
458
  // L: laser picks - a pick inside a capture is its pick (frames forward it while interacting)
305
459
  // L: the pointer laser; ⌥L: inspect - a laser click inside a capture is its pick either way
306
- l: () => { void import('./comments-store.ts').then(({ useComments }) => useComments.getState().setMode(false)); useStore.getState().toggleLaser(false) },
307
- 'Alt+l': () => { void import('./comments-store.ts').then(({ useComments }) => useComments.getState().setMode(false)); useStore.getState().toggleLaser(true) },
308
- n: () => { cap.setNoteOpen(true); window.dispatchEvent(new CustomEvent('mv-jam-note-focus')) },
309
- i: () => cap.picture(),
460
+ l: (o) => { cmd('laser', o); void import('./comments-store.ts').then(({ useComments }) => useComments.getState().setMode(false)); useStore.getState().toggleLaser(false) },
461
+ 'Alt+l': (o) => { cmd('inspect', o); void import('./comments-store.ts').then(({ useComments }) => useComments.getState().setMode(false)); useStore.getState().toggleLaser(true) },
462
+ n: (o) => sync(cmd('jam-notes', o), () => { cap.setNoteOpen(true); window.dispatchEvent(new CustomEvent('mv-jam-note-focus')) }),
463
+ // no frame to picture, or at its limit: nothing was asked for (a picture asked for moves the capture's tick)
464
+ i: (o) => { const h = cmd('jam-picture', o); const was = useJamCapture.getState().tick; cap.picture(); if (useJamCapture.getState().tick === was) h.fail('refused'); else endAfterFrames(h) },
310
465
  // a laser on: Esc turns it off first - the recording goes on
311
- Escape: () => { if (laserOff()) return; cap.drop() },
466
+ Escape: (o) => { if (laserOff(o)) return; sync(cmd('jam-drop', o), () => cap.drop()) },
312
467
  },
313
468
  },
314
469
  { // a review open
315
470
  on: () => ui.panel?.kind === 'review' && !!panelCard,
316
471
  keys: {
317
- Enter: () => { if (ui.moreOpen) return; void act(panelCard, 'good'); const n = nextReview(panelCard!.id); if (n && n.id !== panelCard!.id) { ui.open({ kind: 'review', id: n.id }); reveal(n) } else ui.close() },
318
- 'Shift+Enter': () => ui.setMoreOpen(true),
319
- ArrowRight: () => { void act(panelCard, 'later'); const n = nextReview(panelCard!.id); if (n) { ui.open({ kind: 'review', id: n.id }); reveal(n); ui.follow() } },
320
- ArrowLeft: () => { const n = nextReview(panelCard!.id, -1); if (n) { ui.open({ kind: 'review', id: n.id }); reveal(n) } },
321
- b: () => ui.flip(),
322
- 'Alt+ArrowLeft': () => ui.setTab(Math.max(0, ui.tab - 1)),
323
- 'Alt+ArrowRight': () => ui.setTab(Math.min(Math.max(1, changedShots(panelCard?.shots).length) - 1, ui.tab + 1)),
324
- Escape: () => { if (ui.moreOpen) { clearMoreDraft(panelCard!.id); ui.setMoreOpen(false) } else ui.close() }, // Esc leaves the composer: its words go
472
+ Enter: (o) => {
473
+ const h = cmd('jam-good', o)
474
+ if (ui.moreOpen) { h.noop('more-open'); return }
475
+ void endOnOk(h, act(panelCard, 'good'))
476
+ const n = nextReview(panelCard!.id)
477
+ if (n && n.id !== panelCard!.id) { ui.open({ kind: 'review', id: n.id }); reveal(n) } else ui.close()
478
+ },
479
+ 'Shift+Enter': (o) => sync(cmd('jam-more', o), () => ui.setMoreOpen(true)),
480
+ ArrowRight: (o) => { void endOnOk(cmd('jam-later', o), act(panelCard, 'later')); const n = nextReview(panelCard!.id); if (n) { ui.open({ kind: 'review', id: n.id }); reveal(n); ui.follow() } },
481
+ ArrowLeft: (o) => {
482
+ const h = cmd('jam-back', o)
483
+ const n = nextReview(panelCard!.id, -1)
484
+ if (!n) { h.noop('end'); return }
485
+ sync(h, () => { ui.open({ kind: 'review', id: n.id }); reveal(n) })
486
+ },
487
+ b: (o) => sync(cmd('jam-before-after', o), () => ui.flip()),
488
+ 'Alt+ArrowLeft': (o) => tabTo(cmd('jam-frame-tab', o), ui.tab - 1),
489
+ 'Alt+ArrowRight': (o) => tabTo(cmd('jam-frame-tab', o), ui.tab + 1),
490
+ Escape: (o) => { // Esc leaves the composer: its words go
491
+ if (ui.moreOpen) { cmd('jam-field-discard', { ...o, arg: 'more' }); clearMoreDraft(panelCard!.id); ui.setMoreOpen(false) }
492
+ else { cmd('jam-close', o); ui.close() }
493
+ },
325
494
  },
326
495
  },
496
+ { // the thread panel open (a notice's thread no card can show): Esc closes it
497
+ on: () => ui.panel?.kind === 'thread',
498
+ keys: { Escape: (o) => { if (laserOff(o)) return; cmd('jam-close', o); ui.close() } },
499
+ },
327
500
  { // the lane has the keyboard
328
501
  on: () => ui.laneKeys,
329
502
  keys: (() => {
@@ -333,18 +506,26 @@ const rows = (): Row[] => {
333
506
  // acting keys act only on the tile you can see selected - never on a fallback
334
507
  const i = ui.selected ? stops.indexOf(ui.selected) : -1
335
508
  const sel = i >= 0 ? list.find((c) => c.id === stops[i]) : undefined
336
- const move = (d: number) => { const n = i < 0 ? stops[stops.length - 1] : stops[Math.min(stops.length - 1, Math.max(0, i + d))]; if (n) ui.select(n) }
509
+ const move = (h: CmdHandle, d: number) => {
510
+ const n = i < 0 ? stops[stops.length - 1] : stops[Math.min(stops.length - 1, Math.max(0, i + d))]
511
+ if (!n || n === ui.selected) h.noop('end'); else sync(h, () => ui.select(n))
512
+ }
337
513
  return {
338
- ArrowLeft: () => move(-1), ArrowRight: () => move(1),
339
- Enter: () => {
340
- if (stops[i] === DONE_GROUP) ui.setDoneOpen(true, done.map((c) => c.id))
341
- else if (stops[i] === DONE_CLOSE) ui.setDoneOpen(false, done.map((c) => c.id))
342
- else if (sel) openTile(sel.id)
514
+ ArrowLeft: (o: CmdOpts) => move(cmd('jam-lane-move', o), -1), ArrowRight: (o: CmdOpts) => move(cmd('jam-lane-move', o), 1),
515
+ Enter: (o: CmdOpts) => {
516
+ if (stops[i] === DONE_GROUP) { cmd('jam-done-fold', { ...o, arg: 'open' }); ui.setDoneOpen(true, done.map((c) => c.id)) }
517
+ else if (stops[i] === DONE_CLOSE) { cmd('jam-done-fold', { ...o, arg: 'fold' }); ui.setDoneOpen(false, done.map((c) => c.id)) }
518
+ else { const h = cmd('jam-open', o); if (sel) void endOnOk(h, openTile(sel.id)); else h.noop('no-selection') }
519
+ },
520
+ 'Meta+Enter': (o: CmdOpts) => { const h = cmd('jam-do-next', o); if (sel?.state === 'queued') void endOnOk(h, act(sel, 'first')); else h.noop('not-queued') },
521
+ k: (o: CmdOpts) => {
522
+ const h = cmd('jam-keep', o)
523
+ if (sel?.state === 'draft') void endOnOk(h, decideDraft(sel.id, 'keep'))
524
+ else if (sel?.state === 'queued') void endOnOk(h, act(sel, 'keep'))
525
+ else h.noop('not-keepable')
343
526
  },
344
- 'Meta+Enter': () => { if (sel?.state === 'queued') void act(sel, 'first') },
345
- k: () => { if (sel?.state === 'draft') void decideDraft(sel.id, 'keep'); else if (sel?.state === 'queued') void act(sel, 'keep') },
346
- Backspace: () => { if (sel) void act(sel, 'drop') },
347
- Escape: () => ui.setLaneKeys(false),
527
+ Backspace: (o: CmdOpts) => { const h = cmd('jam-drop', o); if (sel) void endOnOk(h, act(sel, 'drop')); else h.noop('no-selection') },
528
+ Escape: (o: CmdOpts) => { cmd('jam-close', o); ui.setLaneKeys(false) },
348
529
  }
349
530
  })(),
350
531
  },
@@ -352,22 +533,33 @@ const rows = (): Row[] => {
352
533
  // capture, and the toolbar shows no Jam button either
353
534
  on: () => !PUBLISHED && !!CONFIG.jam,
354
535
  keys: {
355
- s: () => startCapture(),
356
- j: () => pressJ(),
357
- q: () => { const list = lane(); if (!list.length) return; ui.setLaneKeys(!ui.laneKeys); if (!ui.selected) ui.select(list[list.length - 1].id) },
358
- v: () => { const n = nextReview(); if (n) { ui.open({ kind: 'review', id: n.id }); reveal(n); ui.follow() } else useStore.getState().toast('nothing to review') },
536
+ s: (o) => { const h = cmd('jam-capture', o); startCapture(); endOnRecording(h) },
537
+ j: (o) => pressJ(cmd('jam-session', o)),
538
+ q: (o) => {
539
+ const h = cmd('jam-lane', o)
540
+ const list = lane()
541
+ if (!list.length) { h.noop('empty'); return }
542
+ sync(h, () => { ui.setLaneKeys(!ui.laneKeys); if (!ui.selected) ui.select(list[list.length - 1].id) })
543
+ },
544
+ v: (o) => {
545
+ const h = cmd('jam-next-review', o)
546
+ const n = nextReview()
547
+ if (n) sync(h, () => { ui.open({ kind: 'review', id: n.id }); reveal(n); ui.follow() })
548
+ else { h.noop('nothing-to-review'); useStore.getState().toast('nothing to review') }
549
+ },
359
550
  },
360
551
  },
361
552
  ]
362
553
  }
363
554
 
364
- /** Apply Jam's key if a state takes it. True when it did - the caller stops there. */
365
- export function jamKey(k: KeyIn): boolean {
555
+ /** Apply Jam's key if a state takes it. True when it did - the caller stops there, and its row recorded the command;
556
+ * false records nothing. `from`: where the key arrived (#50): the shell, a frame's `sh:key`, the stage's. */
557
+ export function jamKey(k: KeyIn, from: CmdIn = 'shell'): boolean {
366
558
  const d = descriptor(k)
367
559
  for (const row of rowsNow()) {
368
560
  if (!row.on()) continue
369
561
  const f = row.keys[d] ?? (d.length === 1 ? row.keys[d] : undefined)
370
- if (f) { f(); syncOwned(); return true }
562
+ if (f) { f({ via: 'key', in: from, keys: d }); syncOwned(); return true }
371
563
  }
372
564
  return false
373
565
  }