@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
@@ -12,6 +12,7 @@ import { ROUTE } from '../const.ts'
12
12
  import { ALL_SCENES } from '../../shared/board-tree.ts'
13
13
  import { UNPLACED } from './hash.ts'
14
14
  import { api as request, canvasStopped, scoped, stoppedLink, useLink } from './api.ts'
15
+ import type { CmdHandle } from './commands.ts'
15
16
 
16
17
  /** What the Not on a board view says when asked for a comment: a note needs a board to live on. */
17
18
  export const NO_COMMENTS_HERE = 'pin it on a board to comment'
@@ -64,20 +65,21 @@ interface CommentsState {
64
65
  refresh(board: string): Promise<boolean>
65
66
  /** A thread by id, from any board's log - one sweep first when it is not loaded yet. */
66
67
  findThread(id: string): Promise<Thread | null>
67
- /** `board` routes the write to a thread's ORIGIN log; default = the active board. */
68
- send(events: CommentEvent[], board?: string): Promise<boolean>
69
- create(body: string): Promise<void>
68
+ /** `board` routes the write to a thread's ORIGIN log; default = the active board. `h` (spec 30): the command behind the
69
+ * write, ended here on its answer - `done`, `failed signed-out` on a 401, else `failed send-failed`. */
70
+ send(events: CommentEvent[], board?: string, h?: CmdHandle): Promise<boolean>
71
+ create(body: string, h?: CmdHandle): Promise<void>
70
72
  reply(threadId: string, body: string): Promise<void>
71
- replyOk(threadId: string, body: string): Promise<boolean>
72
- resolve(threadId: string, reopen?: boolean): Promise<void>
73
+ replyOk(threadId: string, body: string, h?: CmdHandle): Promise<boolean>
74
+ resolve(threadId: string, reopen?: boolean, h?: CmdHandle): Promise<void>
73
75
  setMode(on: boolean): void
74
76
  setShow(show: boolean): void
75
77
  setShowAnchor(on: boolean): void
76
78
  setActive(id: string | null): void
77
79
  setDraft(d: CommentsState['draft']): void
78
- signIn(email: string, password: string): Promise<string | null>
79
- claim(token: string, password: string, name: string, avatar?: string): Promise<string | null>
80
- saveProfile(patch: Partial<Me>): Promise<string | null>
80
+ signIn(email: string, password: string, h?: CmdHandle): Promise<string | null>
81
+ claim(token: string, password: string, name: string, avatar?: string, h?: CmdHandle): Promise<string | null>
82
+ saveProfile(patch: Partial<Me>, h?: CmdHandle): Promise<string | null>
81
83
  dismissIdentity(): void
82
84
  /** The admitted viewer's "Ask to comment" - one request into the owner's queue. */
83
85
  askToComment(): Promise<boolean>
@@ -95,6 +97,15 @@ const api = async (path: string, body?: unknown) => {
95
97
  })
96
98
  return { ok: res.ok, status: res.status, data: await res.json().catch(() => ({})) }
97
99
  }
100
+ /** An identity write and the command behind it (spec 30's `sign-in`, `claim`, `profile-save`): ok → done, the answer
101
+ * said no → `rejected`, no answer → `api`. */
102
+ const identityWrite = async (path: string, body: unknown, h?: CmdHandle) => {
103
+ try {
104
+ const res = await api(path, body)
105
+ if (res.ok) h?.done(); else h?.fail(res.status < 500 ? 'rejected' : 'api')
106
+ return res
107
+ } catch (e) { h?.fail('api'); throw e }
108
+ }
98
109
 
99
110
  export const useComments = create<CommentsState>((set, get) => {
100
111
  // replay PER BOARD, then concatenate: replay keys threads by commentId alone, so a
@@ -315,45 +326,46 @@ export const useComments = create<CommentsState>((set, get) => {
315
326
  return () => stops.forEach((f) => f())
316
327
  },
317
328
 
318
- async send(events, board) {
329
+ async send(events, board, h) {
319
330
  const target = board ?? get().board
320
- if (!target) return false
331
+ if (!target) { h?.fail('send-failed'); return false }
321
332
  // stamp the origin board BEFORE the POST: the dev server fills it at origin, but
322
333
  // the published server stores events as sent - an unstamped event would come back
323
334
  // board-less on the next load and its replies could then route to the wrong log.
324
335
  // Stamping client-side keeps the stored bytes and the optimistic copy identical.
325
336
  const stamped = events.map((e) => ({ ...e, board: e.board ?? target }))
326
- const res = await api(`comments/${target}`, { events: stamped })
327
- if (res.status === 401) { set({ needsIdentity: true }); return false }
337
+ const res = await api(`comments/${target}`, { events: stamped }).catch((e: unknown) => { h?.fail('send-failed'); throw e })
338
+ if (res.status === 401) { h?.fail('signed-out'); set({ needsIdentity: true }); return false }
328
339
  // any other refusal gets said out loud - a silent dead Enter key reads as a bug
329
340
  // (the canonical case: a signed-in viewer on a read-only board)
330
341
  if (!res.ok) {
342
+ h?.fail('send-failed')
331
343
  const { useStore } = await import('./store.ts')
332
344
  useStore.getState().toast(String((res.data as any)?.error ?? 'comment rejected'))
333
345
  }
334
346
  // union only what the server took - a rejected send must not leave phantoms; the
335
347
  // store is global now, so an accepted write lands regardless of the viewed board
336
348
  // (client ids keep the eventual SSE/poll echo idempotent)
337
- if (res.ok) union(stamped)
349
+ if (res.ok) { union(stamped); h?.done() }
338
350
  return res.ok
339
351
  },
340
352
 
341
- async create(body) {
353
+ async create(body, h) {
342
354
  const { draft, me } = get()
343
- if (!draft || !body.trim()) return
355
+ if (!draft || !body.trim()) { h?.fail('send-failed'); return }
344
356
  const id = uuid()
345
357
  const mentions = mentionsIn(body.trim(), mentionPeople(get().events, me ?? undefined))
346
358
  const ok = await get().send([{
347
359
  id: uuid(), ts: Date.now(), type: 'create', commentId: id,
348
360
  nodeKey: draft.nodeKey, frame: draft.frame, anchor: draft.anchor,
349
361
  author: postAuthor(me), body: body.trim(), ...(mentions ? { mentions } : {}),
350
- }], draft.board)
362
+ }], draft.board, h)
351
363
  if (ok) set({ draft: null, active: id, commentMode: false })
352
364
  },
353
365
 
354
366
  async reply(threadId, body) { await get().replyOk(threadId, body) },
355
- async replyOk(threadId, body) {
356
- if (!body.trim()) return false
367
+ async replyOk(threadId, body, h) {
368
+ if (!body.trim()) { h?.fail('send-failed'); return false }
357
369
  // route to the thread's ORIGIN log - the viewer may be reading it from another
358
370
  // board (frame-scoped display); a reply landing in the wrong log would fork it
359
371
  const origin = get().threads.find((t) => t.id === threadId)?.board
@@ -361,12 +373,15 @@ export const useComments = create<CommentsState>((set, get) => {
361
373
  return get().send([{
362
374
  id: uuid(), ts: Date.now(), type: 'reply', commentId: uuid(), parentId: threadId,
363
375
  author: postAuthor(get().me), body: body.trim(), ...(mentions ? { mentions } : {}),
364
- }], origin)
376
+ }], origin, h)
365
377
  },
366
378
 
367
- async resolve(threadId, reopen = false) {
379
+ async resolve(threadId, reopen = false, h) {
368
380
  const origin = get().threads.find((t) => t.id === threadId)?.board
369
- await get().send([{ id: uuid(), ts: Date.now(), type: reopen ? 'reopen' : 'resolve', commentId: threadId }], origin)
381
+ // `comment-resolve`'s one code: a resolve refused for any reason did not send
382
+ const sent = await get().send([{ id: uuid(), ts: Date.now(), type: reopen ? 'reopen' : 'resolve', commentId: threadId }], origin)
383
+ .catch((e: unknown) => { h?.fail('send-failed'); throw e })
384
+ if (sent) h?.done(); else h?.fail('send-failed')
370
385
  },
371
386
 
372
387
  async findThread(id) {
@@ -394,20 +409,20 @@ export const useComments = create<CommentsState>((set, get) => {
394
409
  },
395
410
  dismissIdentity() { set({ needsIdentity: false }) }, // inviteToken survives dismissal - commenting later reopens the claim
396
411
 
397
- async signIn(email, password) {
398
- const res = await api('auth/signin', { email, password })
412
+ async signIn(email, password, h) {
413
+ const res = await identityWrite('auth/signin', { email, password }, h)
399
414
  if (!res.ok) return res.data?.error ?? 'sign-in failed'
400
415
  set({ me: res.data.user, needsIdentity: false })
401
416
  return null
402
417
  },
403
- async claim(token, password, name, avatar) {
404
- const res = await api('auth/claim', { token, password, name, avatar })
418
+ async claim(token, password, name, avatar, h) {
419
+ const res = await identityWrite('auth/claim', { token, password, name, avatar }, h)
405
420
  if (!res.ok) return res.data?.error ?? 'claim failed'
406
421
  set({ me: res.data.user, needsIdentity: false, inviteToken: null })
407
422
  return null
408
423
  },
409
- async saveProfile(patch) {
410
- const res = await api('profile', patch)
424
+ async saveProfile(patch, h) {
425
+ const res = await identityWrite('profile', patch, h)
411
426
  if (!res.ok) return res.data?.error ?? 'could not save - try again'
412
427
  set({ me: res.data.user })
413
428
  return null
@@ -6,10 +6,11 @@
6
6
  import { fetchMembership, useStore } from './store.ts'
7
7
  import { UNPLACED } from './hash.ts'
8
8
  import { canvasCtl } from './canvas/ctl.ts'
9
+ import { endOnCamera, endOnLoad, type CmdHandle } from './commands.ts'
9
10
 
10
11
  /** Navigate to a frame id. `carry` keeps interact mode across the hop (a link inside an
11
12
  * interacting frame walks a flow - it must not eject you to design mode). */
12
- export function goTo(target: string, carry = false): void {
13
+ export function goTo(target: string, carry = false, h?: CmdHandle): void {
13
14
  const s = useStore.getState()
14
15
  const existing = s.nodes.find((n) => n.frame === target && !n.missing)
15
16
  if (existing) {
@@ -17,7 +18,8 @@ export function goTo(target: string, carry = false): void {
17
18
  s.select(existing.key)
18
19
  if (carry) s.setInteract(existing.key)
19
20
  fitLater(existing.key, seq)
20
- } else void gotoAcrossBoards(target, carry)
21
+ if (h) endOnCamera(h) // the recorder's (spec 30): the camera lands
22
+ } else void gotoAcrossBoards(target, carry, h)
21
23
  }
22
24
 
23
25
  /** A data-goto whose target frame is not on the current board follows the frame HOME:
@@ -27,12 +29,12 @@ export function goTo(target: string, carry = false): void {
27
29
  * for unpinned targets); an id the manifest doesn't know stays a toast. Every goto
28
30
  * bumps `gotoSeq` so a slow older resolution can never override newer navigation. */
29
31
  let gotoSeq = 0
30
- async function gotoAcrossBoards(target: string, carry: boolean) {
32
+ async function gotoAcrossBoards(target: string, carry: boolean, h?: CmdHandle) {
31
33
  const s = useStore.getState()
32
34
  const from = s.board
33
35
  // an id the manifest doesn't know resolves NOWHERE - a tombstone pin on some board
34
36
  // must not send us on a trip that ends in a silent timeout
35
- if (!s.manifest?.frames.some((f) => f.id === target)) return s.toast(`unknown goto target "${target}"`)
37
+ if (!s.manifest?.frames.some((f) => f.id === target)) { h?.fail('no-target'); return s.toast(`unknown goto target "${target}"`) }
36
38
  const seq = navigated()
37
39
  let home: string | null = null
38
40
  try {
@@ -40,19 +42,22 @@ async function gotoAcrossBoards(target: string, carry: boolean) {
40
42
  } catch {
41
43
  // a transport failure is NOT proof the frame is unpinned - spawning here would
42
44
  // recreate the board mutation this function exists to prevent
45
+ h?.fail('no-target')
43
46
  return useStore.getState().toast(`goto: could not read the boards - try again`)
44
47
  }
45
- if (seq !== gotoSeq) return // superseded by newer navigation
48
+ if (seq !== gotoSeq) { h?.cancel('superseded'); return } // superseded by newer navigation
46
49
  if (!home) {
47
50
  // no curated board pins it - the original prototype behavior: spawn beside you
48
51
  const st = useStore.getState()
49
52
  const node = st.spawn(target)
50
- if (!node) return st.toast(`unknown goto target "${target}"`)
53
+ if (!node) { h?.fail('no-target'); return st.toast(`unknown goto target "${target}"`) }
51
54
  st.select(node.key)
52
55
  if (carry) st.setInteract(node.key)
53
56
  fitLater(node.key, seq)
57
+ if (h) endOnCamera(h)
54
58
  return
55
59
  }
60
+ if (h) endOnLoad(h, home, 'visible') // the recorder's (spec 30): the target board's `visible`
56
61
  await landOn(home, target, carry, seq, from)
57
62
  }
58
63
 
@@ -16,10 +16,14 @@
16
16
  * The same table says which keys the shell owns right now; they are mirrored into every frame (a
17
17
  * frame consumes an owned key - before a focused button sees ⏎ - and forwards it). `Tab` is never
18
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`).
19
23
  */
20
24
  import { useJamCapture, setOwnedKeys } from './jam-capture.ts'
21
25
  import { changedShots, useJamQueue, type JamCard } from './jam-queue.ts'
22
- import { DONE_CLOSE, DONE_GROUP, doneFold, jamSurface, useJamUi } from './jam-state.ts'
26
+ import { DONE_CLOSE, DONE_GROUP, doneFold, endOnOk, jamSurface, useJamUi } from './jam-state.ts'
23
27
  import { pressJ, startSession, wrapWrite } from './jam-session.tsx'
24
28
  import { clearMoreDraft } from './jam-panel.tsx'
25
29
  import { CONFIG, PUBLISHED, SOURCE_REVEALED, useStore } from './store.ts'
@@ -27,6 +31,8 @@ import { ALL_SCENES } from '../../shared/board-tree.ts'
27
31
  import { holdsReload } from './api.ts'
28
32
  import { navigated, switchFor } from './goto.ts'
29
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'
30
36
 
31
37
  export interface KeyIn { key: string; shift?: boolean; alt?: boolean; meta?: boolean; ctrl?: boolean }
32
38
  /** `[Ctrl+][Meta+][Alt+][Shift+]key`, a letter lowercase - the frames' descriptor (keys.js). */
@@ -58,18 +64,20 @@ const latest = new Map<string, number>()
58
64
  let gen = 0
59
65
  /** The words written for a card that have not saved yet - the read-back keeps showing them. */
60
66
  export const pendingEdit = (id: string): string | undefined => unsaved.get(id)
61
- /** Save the read-back's edit (the text stays where it is if the save fails - see `decideDraft`). */
62
- 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> {
63
69
  const g = ++gen
64
70
  latest.set(c.id, g)
65
71
  unsaved.set(c.id, text)
66
72
  workChanged()
67
73
  const before = saving.get(c.id) ?? Promise.resolve(true)
68
74
  // saves of one card run in order, each at the card's rev as the one before left it
69
- saving.set(c.id, before.then(() => {
75
+ const p = before.then(() => {
70
76
  const fresh = useJamQueue.getState().cards?.find((x) => x.id === c.id) ?? c
71
77
  return useJamQueue.getState().act(fresh, 'edit', text)
72
- }).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
73
81
  }
74
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
75
83
  * and waits to be sent again. Sent again (from the field, or before a decision) it keeps its id: the server
@@ -116,33 +124,34 @@ async function notesSaved(id: string): Promise<boolean> {
116
124
 
117
125
  /** Confirm or keep a draft AFTER its edit has saved - an edit that failed is saved again first, and
118
126
  * nothing is sent while it still fails; at the card's new rev; the panel closes once the decision
119
- * took, and a refusal says why. */
120
- 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> {
121
129
  await saving.get(id)
122
130
  if (action !== 'drop' && unsaved.has(id)) {
123
131
  const c = useJamQueue.getState().cards?.find((x) => x.id === id)
124
132
  if (c) saveEdit(c, unsaved.get(id)!)
125
133
  await saving.get(id)
126
- 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 }
127
135
  }
128
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
129
- 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 }
130
138
  if (action === 'drop') { unsaved.delete(id); unsavedNotes.delete(id); workChanged() }
131
139
  const fresh = useJamQueue.getState().cards?.find((c) => c.id === id)
132
- if (!fresh) return
133
- if (await useJamQueue.getState().act(fresh, action)) useJamUi.getState().close()
134
- 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
135
144
  }
136
145
 
137
146
  /** Leave a field in the open panel (its words save on blur) - before anything takes the panel away. */
138
147
  const leavePanelField = () => { const a = document.activeElement; if (a instanceof HTMLElement && a.closest('.jm-focus')) a.blur() }
139
148
 
140
149
  /** Resume a draft that ended too soon: its edit saves first (the resumed capture carries it on), the
141
- * read-back closes, and recording goes on where it stopped. */
142
- 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> {
143
152
  const cap = useJamCapture.getState()
144
- if (cap.current) { useStore.getState().toast('a capture is recording - press E to end it first'); return }
145
- 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
146
155
  // first, at once: leave the editor (its words start saving) and lock the words - from here on nothing
147
156
  // typed can race the start; the lock holds through every wait and is let go at the end
148
157
  if (useJamUi.getState().panel?.id === id) leavePanelField()
@@ -156,14 +165,14 @@ export async function resumeDraft(id: string) {
156
165
  if (unsavedNotes.has(id) && !(await notesSaved(id))) { useStore.getState().toast('your note could not be added - try again before you resume'); return false }
157
166
  return cardById(id)?.state === 'draft'
158
167
  }
159
- if (!(await settled())) return
160
- if (await useJamCapture.getState().resume(id, settled)) {
161
- // as the UI is NOW (another panel may have opened meanwhile): only what points at it
162
- const ui = useJamUi.getState()
163
- if (ui.panel?.id === id) ui.close()
164
- // its tile has stepped aside: nothing points at it, and the lane gives its keys back
165
- if (ui.selected === id) { ui.select(null); ui.setLaneKeys(false) }
166
- }
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
167
176
  } finally { useJamCapture.setState({ settling: null }) }
168
177
  }
169
178
 
@@ -302,8 +311,8 @@ export async function openThreadAt(board: string, thread: string, o: { card?: Ja
302
311
  }
303
312
 
304
313
  /** Open a card's thread where you can see it, as a notification does (openThreadAt): a click is never a no-op. */
305
- export function openThread(c: JamCard) {
306
- if (c.thread) void openThreadAt(c.board, c.thread, { card: c })
314
+ export function openThread(c: JamCard): Promise<boolean> {
315
+ return c.thread ? openThreadAt(c.board, c.thread, { card: c }) : Promise.resolve(false)
307
316
  }
308
317
 
309
318
  /**
@@ -355,7 +364,11 @@ function nextReview(from?: string, step = 1) {
355
364
  const act = (c: JamCard | undefined, action: Parameters<ReturnType<typeof useJamQueue.getState>['act']>[1], body?: string) =>
356
365
  c ? useJamQueue.getState().act(c, action, body) : Promise.resolve(false)
357
366
 
358
- 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) }
359
372
 
360
373
  /** The run on screen, when a review is open: a capture started now binds it. */
361
374
  function reviewNow(): { card: string; batch: string; rev: number } | undefined {
@@ -365,22 +378,32 @@ function reviewNow(): { card: string; batch: string; rev: number } | undefined {
365
378
  return ui.panel?.kind === 'review' && c?.kind === 'capture' && c.batch ? { card: c.id, batch: c.batch, rev: c.rev } : undefined
366
379
  }
367
380
 
368
- /** Esc while a laser (pointer or inspect) is on turns it off, and that is all it does. */
369
- 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
+ }
370
390
 
371
391
  /** Start a capture, as S does: one made while a capture's review is open follows that review (its run).
372
392
  * `session`: the session it belongs to when the queue may not show it yet (a session's Start). */
373
393
  export const startCapture = (session?: string) => useJamCapture.getState().start(reviewNow(), session)
374
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
+
375
398
  /** A laser on (pointer or inspect): its keys come first - Esc turns it off before it closes, drops or leaves anything -
376
399
  * and are owned, so they work from inside a frame too (a laser click puts the focus there). The one row a published
377
400
  * canvas has (where its source is revealed - the only place a laser exists there). */
378
401
  const laserRow: Row = {
379
402
  on: () => useStore.getState().laser,
380
403
  keys: {
381
- l: () => useStore.getState().toggleLaser(false),
382
- 'Alt+l': () => useStore.getState().toggleLaser(true),
383
- 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)) },
384
407
  },
385
408
  }
386
409
  const rowsNow = (): Row[] => (PUBLISHED ? (SOURCE_REVEALED ? [laserRow] : []) : rows())
@@ -389,66 +412,90 @@ const rows = (): Row[] => {
389
412
  const cap = useJamCapture.getState()
390
413
  const ui = useJamUi.getState()
391
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
+ }
392
420
  return [
393
421
  laserRow,
394
422
  { // a session sheet open: the start sheet's ⏎ starts; Esc closes either (the wrap-up's field keeps its own keys)
395
423
  on: () => ui.sheet === 'start' || ui.sheet === 'wrap',
396
424
  keys: {
397
- Enter: () => { if (ui.sheet === 'start') void startSession(); else wrapWrite.current?.() },
398
- 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) },
399
431
  // over the wrap-up, no new capture starts (it would miss the record): close the sheet first
400
- ...(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') } } : {}),
401
433
  },
402
434
  },
403
435
  { // a read-back open
404
436
  on: () => ui.panel?.kind === 'capture' && panelCard?.state === 'draft',
405
437
  keys: {
406
- Enter: () => void decideDraft(panelCard!.id, 'confirm'),
407
- k: () => void decideDraft(panelCard!.id, 'keep'),
408
- 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)),
409
441
  // a laser on: Esc turns it off first - never a drop by the way
410
- 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')) },
411
443
  },
412
444
  },
413
445
  { // the notes card open (in its field, the field handles its own keys)
414
446
  on: () => cap.noteOpen,
415
447
  keys: {
416
- Escape: () => cap.setNoteOpen(false),
417
- 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'))),
418
450
  },
419
451
  },
420
452
  { // a capture open
421
453
  on: () => !!cap.current,
422
454
  keys: {
423
- e: () => cap.end(), // straight to the queue
424
- 'Shift+e': () => cap.end(true), // stop to review: its read-back opens
425
- 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
426
458
  // L: laser picks - a pick inside a capture is its pick (frames forward it while interacting)
427
459
  // L: the pointer laser; ⌥L: inspect - a laser click inside a capture is its pick either way
428
- l: () => { void import('./comments-store.ts').then(({ useComments }) => useComments.getState().setMode(false)); useStore.getState().toggleLaser(false) },
429
- 'Alt+l': () => { void import('./comments-store.ts').then(({ useComments }) => useComments.getState().setMode(false)); useStore.getState().toggleLaser(true) },
430
- n: () => { cap.setNoteOpen(true); window.dispatchEvent(new CustomEvent('mv-jam-note-focus')) },
431
- 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) },
432
465
  // a laser on: Esc turns it off first - the recording goes on
433
- Escape: () => { if (laserOff()) return; cap.drop() },
466
+ Escape: (o) => { if (laserOff(o)) return; sync(cmd('jam-drop', o), () => cap.drop()) },
434
467
  },
435
468
  },
436
469
  { // a review open
437
470
  on: () => ui.panel?.kind === 'review' && !!panelCard,
438
471
  keys: {
439
- 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() },
440
- 'Shift+Enter': () => ui.setMoreOpen(true),
441
- ArrowRight: () => { void act(panelCard, 'later'); const n = nextReview(panelCard!.id); if (n) { ui.open({ kind: 'review', id: n.id }); reveal(n); ui.follow() } },
442
- ArrowLeft: () => { const n = nextReview(panelCard!.id, -1); if (n) { ui.open({ kind: 'review', id: n.id }); reveal(n) } },
443
- b: () => ui.flip(),
444
- 'Alt+ArrowLeft': () => ui.setTab(Math.max(0, ui.tab - 1)),
445
- 'Alt+ArrowRight': () => ui.setTab(Math.min(Math.max(1, changedShots(panelCard?.shots).length) - 1, ui.tab + 1)),
446
- 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
+ },
447
494
  },
448
495
  },
449
496
  { // the thread panel open (a notice's thread no card can show): Esc closes it
450
497
  on: () => ui.panel?.kind === 'thread',
451
- keys: { Escape: () => { if (laserOff()) return; ui.close() } },
498
+ keys: { Escape: (o) => { if (laserOff(o)) return; cmd('jam-close', o); ui.close() } },
452
499
  },
453
500
  { // the lane has the keyboard
454
501
  on: () => ui.laneKeys,
@@ -459,18 +506,26 @@ const rows = (): Row[] => {
459
506
  // acting keys act only on the tile you can see selected - never on a fallback
460
507
  const i = ui.selected ? stops.indexOf(ui.selected) : -1
461
508
  const sel = i >= 0 ? list.find((c) => c.id === stops[i]) : undefined
462
- 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
+ }
463
513
  return {
464
- ArrowLeft: () => move(-1), ArrowRight: () => move(1),
465
- Enter: () => {
466
- if (stops[i] === DONE_GROUP) ui.setDoneOpen(true, done.map((c) => c.id))
467
- else if (stops[i] === DONE_CLOSE) ui.setDoneOpen(false, done.map((c) => c.id))
468
- 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')
469
526
  },
470
- 'Meta+Enter': () => { if (sel?.state === 'queued') void act(sel, 'first') },
471
- k: () => { if (sel?.state === 'draft') void decideDraft(sel.id, 'keep'); else if (sel?.state === 'queued') void act(sel, 'keep') },
472
- Backspace: () => { if (sel) void act(sel, 'drop') },
473
- 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) },
474
529
  }
475
530
  })(),
476
531
  },
@@ -478,22 +533,33 @@ const rows = (): Row[] => {
478
533
  // capture, and the toolbar shows no Jam button either
479
534
  on: () => !PUBLISHED && !!CONFIG.jam,
480
535
  keys: {
481
- s: () => startCapture(),
482
- j: () => pressJ(),
483
- q: () => { const list = lane(); if (!list.length) return; ui.setLaneKeys(!ui.laneKeys); if (!ui.selected) ui.select(list[list.length - 1].id) },
484
- 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
+ },
485
550
  },
486
551
  },
487
552
  ]
488
553
  }
489
554
 
490
- /** Apply Jam's key if a state takes it. True when it did - the caller stops there. */
491
- 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 {
492
558
  const d = descriptor(k)
493
559
  for (const row of rowsNow()) {
494
560
  if (!row.on()) continue
495
561
  const f = row.keys[d] ?? (d.length === 1 ? row.keys[d] : undefined)
496
- if (f) { f(); syncOwned(); return true }
562
+ if (f) { f({ via: 'key', in: from, keys: d }); syncOwned(); return true }
497
563
  }
498
564
  return false
499
565
  }