@marver-design/marver 0.27.0 → 0.28.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 (111) hide show
  1. package/CHANGELOG.md +195 -0
  2. package/README.md +9 -4
  3. package/dist/{anchor-check-ChdDqL5z.mjs → anchor-check-PHUOFj1N.mjs} +1 -1
  4. package/dist/{audio-Dw1lfMdb.mjs → audio-DX4POHAj.mjs} +39 -4
  5. package/dist/{board-tree-DRioF94d.mjs → board-tree-BXR8dw4b.mjs} +3 -1
  6. package/dist/{boards-DlTcpF47.mjs → boards-BeWtjGUM.mjs} +50 -5
  7. package/dist/boards-EH2onUXM.mjs +995 -0
  8. package/dist/{build-DZnFysGU.mjs → build-BsAyLMT1.mjs} +9 -22
  9. package/dist/{capture-vadKjuCo.mjs → capture-DdZ6xgoz.mjs} +92 -30
  10. package/dist/cli.mjs +56 -21
  11. package/dist/{collab-Dxg2trOK.mjs → collab-BEAcXrBb.mjs} +1 -1
  12. package/dist/{comments-DxOkCSNE.mjs → comments-CrBHPEQl.mjs} +4 -4
  13. package/dist/config-BezZTiov.mjs +182 -0
  14. package/dist/conn-BMiHS42T.mjs +222 -0
  15. package/dist/connectors-MR9d-EBP.mjs +290 -0
  16. package/dist/{context-HQ4Giw58.mjs → context-BUnFiyA3.mjs} +3 -3
  17. package/dist/{daemon-BSA0lV8d.mjs → daemon-C5dg2R-V.mjs} +2188 -183
  18. package/dist/{dev-eQJhWsqg.mjs → dev-D7YS7iT2.mjs} +25 -14
  19. package/dist/{init-COD0x48i.mjs → init-WE5lQkQL.mjs} +8 -3
  20. package/dist/jam-Cj5gBvwD.mjs +373 -0
  21. package/dist/{link-DDXZVGtv.mjs → link-BFFRgrMt.mjs} +4 -4
  22. package/dist/listener-DdLEM79A.mjs +80 -0
  23. package/dist/{ls-D7O1G505.mjs → ls-BZ5TAtd5.mjs} +1 -1
  24. package/dist/{manifest-Nl3KSVOk.mjs → manifest-DPZ3WNg_.mjs} +2 -2
  25. package/dist/{marks-CWM3WJjc.mjs → marks-Dyn6tmjp.mjs} +3 -3
  26. package/dist/{marks-CKgzucHZ.mjs → marks-Kmdab_5w.mjs} +3 -3
  27. package/dist/{marver-id-gate-BjF6v4bT.mjs → marver-id-gate-D-R0hSt_.mjs} +1 -1
  28. package/dist/perf-Cn5LiRaY.mjs +1319 -0
  29. package/dist/perf-jam-QxD_UnzN.mjs +635 -0
  30. package/dist/permit-DDa6wqOs.mjs +187 -0
  31. package/dist/plugin-C_0yb-Fq.mjs +5089 -0
  32. package/dist/{poster-Bx83ZYVK.mjs → poster-DHi6I1fO.mjs} +1 -1
  33. package/dist/{profile-Bh5Y5zpW.mjs → profile-jIS6BcAs.mjs} +1 -1
  34. package/dist/{publish-bakes-aljgm45S.mjs → publish-bakes-r4PEZuPl.mjs} +3 -3
  35. package/dist/{queue-CAM_vNmX.mjs → queue-c-6aTHEz.mjs} +164 -25
  36. package/dist/{recover-t9Pno3u9.mjs → recover-nrLEVLyJ.mjs} +2 -2
  37. package/dist/{serve-C8rVheYk.mjs → serve-Dp3nHstu.mjs} +3 -3
  38. package/dist/{session-BAaJsK5c.mjs → session-DyVE7cCk.mjs} +1 -1
  39. package/dist/{share-W5H3BNvP.mjs → share-Ce4tP7ji.mjs} +1 -1
  40. package/dist/{shot-LFhC-WYD.mjs → shot-BrRtqaiS.mjs} +34 -8
  41. package/dist/{shot-DoHLl6ig.mjs → shot-DBWN8hPP.mjs} +1 -1
  42. package/dist/sizes-wjXDev3b.mjs +139 -0
  43. package/dist/{slots-DCDo3N0x.mjs → slots-CFNnegCc.mjs} +8 -1
  44. package/dist/speech-worker.mjs +23 -3
  45. package/dist/{sync-BQVlHZpx.mjs → sync-CQdGARJ9.mjs} +1 -1
  46. package/dist/transport-C5FnY9ni.mjs +203 -0
  47. package/dist/{work-BroFwnup.mjs → work-BYWD_1Zf.mjs} +3 -3
  48. package/dist/{work-Bp1p39kq.mjs → work-DJxH7cCX.mjs} +1 -1
  49. package/docs/jam-session.md +42 -16
  50. package/docs/live-jam.md +92 -10
  51. package/docs/performance.md +197 -35
  52. package/package.json +1 -1
  53. package/src/client/content/video.tsx +10 -2
  54. package/src/client/shell/App.tsx +10 -3
  55. package/src/client/shell/Comments.tsx +5 -3
  56. package/src/client/shell/ContextMenu.tsx +5 -3
  57. package/src/client/shell/JamSurface.tsx +56 -21
  58. package/src/client/shell/LockedApp.tsx +3 -0
  59. package/src/client/shell/Play.tsx +4 -2
  60. package/src/client/shell/Tip.tsx +3 -1
  61. package/src/client/shell/api.ts +47 -20
  62. package/src/client/shell/app-bridge.ts +254 -0
  63. package/src/client/shell/app-perf.ts +92 -0
  64. package/src/client/shell/canvas/Canvas.tsx +115 -22
  65. package/src/client/shell/canvas/FrameNode.tsx +10 -6
  66. package/src/client/shell/canvas/admission.ts +23 -8
  67. package/src/client/shell/canvas/ctl.ts +6 -0
  68. package/src/client/shell/canvas/sleep.ts +57 -17
  69. package/src/client/shell/canvas/updates.ts +2 -1
  70. package/src/client/shell/icons.tsx +1 -0
  71. package/src/client/shell/inset.ts +44 -0
  72. package/src/client/shell/jam-capture.ts +113 -33
  73. package/src/client/shell/jam-keys.ts +40 -9
  74. package/src/client/shell/jam-lane.tsx +14 -5
  75. package/src/client/shell/jam-lines.ts +66 -9
  76. package/src/client/shell/jam-panel.tsx +61 -6
  77. package/src/client/shell/jam-queue.ts +50 -8
  78. package/src/client/shell/jam-session.tsx +53 -4
  79. package/src/client/shell/jam-surface-parts.tsx +6 -3
  80. package/src/client/shell/jam-ui.tsx +6 -1
  81. package/src/client/shell/jam-voice-wait.ts +21 -0
  82. package/src/client/shell/jam-voice.ts +62 -15
  83. package/src/client/shell/main.tsx +14 -1
  84. package/src/client/shell/marks-ui.tsx +5 -3
  85. package/src/client/shell/marver-app.ts +21 -0
  86. package/src/client/shell/perf-run-probe.ts +34 -0
  87. package/src/client/shell/perf-run.ts +70 -0
  88. package/src/client/shell/perf.ts +11 -0
  89. package/src/client/shell/recorder.ts +45 -3
  90. package/src/client/shell/store.ts +52 -24
  91. package/src/client/shell/styles.css +65 -17
  92. package/src/client/shell/tidy.ts +3 -2
  93. package/src/client/shell/unsaved.ts +81 -0
  94. package/src/client/shell/whiteout-probes.ts +141 -0
  95. package/src/shared/app-api.ts +205 -0
  96. package/src/shared/app-perf.ts +308 -0
  97. package/src/shared/approval.ts +20 -0
  98. package/src/shared/events.ts +1 -1
  99. package/src/shared/logo-sniff.ts +86 -0
  100. package/src/shared/machine.ts +132 -0
  101. package/src/shared/perf-run.ts +177 -0
  102. package/templates/AGENTS-embedded.md +31 -1
  103. package/templates/AGENTS-studio.md +31 -1
  104. package/templates/instructions/boards.md +10 -2
  105. package/templates/instructions/jam.md +90 -0
  106. package/dist/bake-DM_uWgAA.mjs +0 -786
  107. package/dist/boards-CGg6piKF.mjs +0 -342
  108. package/dist/perf-BWzQwZqj.mjs +0 -369
  109. package/dist/perf-BoDSkbEb.mjs +0 -429
  110. package/dist/perf-jam-D55U3FZK.mjs +0 -242
  111. package/dist/plugin-C-E7omsh.mjs +0 -2762
@@ -0,0 +1,44 @@
1
+ /**
2
+ * The one usable-rectangle helper (spec 28 A2.9 v1.8 #6, A3.8 #31): where the shell may place what a person must
3
+ * see, under the Mac app's transparent strip. Owner: the one-ground stream (marver 0.27.2).
4
+ *
5
+ * `TOP` is 44 only when the app says this document must apply it (`topInset`, from `mv:doc`'s answer) **and** the
6
+ * presentation contract is whole (`onPresent` and `presented`): a shell never trusts half a contract, so in Chrome,
7
+ * on a published canvas, under `marver shot` and inside app 0.1 it is 0 and nothing moves. `--mv-top` goes on
8
+ * `:root` (some portals mount outside `.sh-app`), and every rule reads `var(--mv-top, 0px)`.
9
+ *
10
+ * FROZEN before the A3 streams split (A3.8 #53): `TOP`, `VISIBLE_TOP`, `usable()`, `onScreen()` and `applyInset()`.
11
+ * Consumers: the top-anchored layers, the selection bar, tips and menus (`TOP + 8`), insets(), focus, play sizes
12
+ * and Jam's fill use `usable()`; seen marks, visibleNodes(), A3.3's probes and A4.3's full-view test use `onScreen()`.
13
+ */
14
+ import { EDGE_FADE, TOP_INSET, type Inset } from '../../shared/app-api.ts'
15
+ import { APP } from './marver-app.ts'
16
+
17
+ /** 44 in app 0.2+ for a document main placed full height, with the presentation channel to match; else 0. */
18
+ export const TOP: Inset = APP?.topInset === TOP_INSET && typeof APP.onPresent === 'function' && typeof APP.presented === 'function' ? TOP_INSET : 0
19
+ /** Below the scroll edge: what counts as seen. 0 with no inset (Chrome is unchanged). */
20
+ export const VISIBLE_TOP = TOP ? TOP + EDGE_FADE : 0
21
+
22
+ /** main.tsx, before the first render: the variable every placement reads, on :root. Nothing without the inset. */
23
+ export function applyInset(): void {
24
+ if (!TOP) return
25
+ document.documentElement.style.setProperty('--mv-top', `${TOP}px`)
26
+ document.documentElement.classList.add('mv-inset')
27
+ }
28
+
29
+ /** The view below the strip, in client px. */
30
+ export function usable(): { top: number; left: number; width: number; height: number } {
31
+ return { top: TOP, left: 0, width: innerWidth, height: Math.max(0, innerHeight - TOP) }
32
+ }
33
+
34
+ /** The part of a client rect on screen below the scroll edge, or null when none is. */
35
+ export function onScreen(r: DOMRectReadOnly): DOMRect | null {
36
+ const top = Math.max(r.top, VISIBLE_TOP)
37
+ const bottom = Math.min(r.bottom, innerHeight)
38
+ const left = Math.max(r.left, 0)
39
+ const right = Math.min(r.right, innerWidth)
40
+ return bottom > top && right > left ? new DOMRect(left, top, right - left, bottom - top) : null
41
+ }
42
+
43
+ // dev-only inspection hook for tests (never installed in published builds)
44
+ if (typeof window !== 'undefined' && (import.meta as { env?: { DEV?: boolean } }).env?.DEV) (window as unknown as { __mvInset: unknown }).__mvInset = { TOP, VISIBLE_TOP, usable, onScreen }
@@ -13,6 +13,7 @@
13
13
  * starts nothing - it is ended (E) or dropped (Esc) first. Each message lands in the capture whose
14
14
  * id it carries.
15
15
  */
16
+ import { onScreen, usable } from './inset.ts'
16
17
  import { create } from 'zustand'
17
18
  import { slideSize } from '../const.ts'
18
19
  import { CONFIG, SLIDE_INTRINSIC, stoppedFor, useStore, type Node } from './store.ts'
@@ -22,6 +23,7 @@ import { forgetHeard, RATE, setWordsListener, voiceBegin, voiceDrop, voiceEnd }
22
23
  import { touchedFrames } from '../../shared/capture-frames.ts'
23
24
  import { onStageSize, stageSize } from './stage-size.ts'
24
25
  import { api, holdsReload } from './api.ts'
26
+ import { unsavedWhen, workChanged } from './unsaved.ts'
25
27
  import { bytesOf } from './recorder-core.ts'
26
28
 
27
29
  const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
@@ -95,6 +97,7 @@ interface Cap {
95
97
  /** its timing (spec 27a Part D): when E was pressed, the wait for its last words, each picture's time, the missing ones */
96
98
  timing?: { endAt?: number; wordsMs?: number; pics: number[]; late: number; failed: number }
97
99
  shotFrames: string[] // frames pictured (or being pictured) in it: an automatic picture is taken once per frame
100
+ review?: boolean // ended with ⇧E: it waits for its read-back (E: queued once sealed)
98
101
  endShot?: boolean // its end pictures were asked for (once its steps were all in)
99
102
  inherited?: string[] // Resume: the frames the capture it continues was about (its card's)
100
103
  endSizes?: Record<string, { w: number; h: number; play?: true }> // the sizes as they were at E (what it was about, then)
@@ -123,16 +126,20 @@ interface CaptureState {
123
126
  /** Start one - never while one records (it says so instead) */
124
127
  /** `session`: the session it belongs to, when the caller knows it before the queue shows it (Start) */
125
128
  start(reviewing?: Cap['reviewing'], session?: string): void
126
- end(): void
129
+ /** E: it goes straight to the queue once it seals; ⇧E (`review`): its read-back opens to check and add to first */
130
+ end(review?: boolean): void
127
131
  drop(): void
128
132
  note(text: string): void
129
133
  setNoteOpen(open: boolean): void
130
134
  setNoteDraft(text: string): void
131
135
  picture(frame?: string): void
132
- /** the drafts sealed, in order - their read-backs open when capturing stops */
133
- sealed: { id: string; card?: { id: string; rev: number } }[]
136
+ /** the captures sealed, in order, and the card the server made of each - the read-back of one stopped to review
137
+ * (`review`: ⇧E, or J's wrap-up) opens when capturing stops; one stopped with E never opens anything */
138
+ sealed: { id: string; card?: { id: string; rev: number }; review?: true }[]
134
139
  /** sealed captures the server does not hold yet (kept, sent again until it takes them) */
135
140
  unsent: string[]
141
+ /** the server did not answer the last send: what is unsent waits for it (sent again every 5 s) */
142
+ away: boolean
136
143
  /** Continue a draft that ended too soon: its record is loaded and recording goes on from where it
137
144
  * stopped, under a new id that takes the draft's place when it seals. Dropping it leaves the draft. */
138
145
  resume(draft: string, ready?: () => Promise<boolean>): Promise<boolean>
@@ -142,7 +149,8 @@ interface CaptureState {
142
149
  * locked meanwhile, so nothing typed can race the start - set by the caller (resumeDraft) before its
143
150
  * first wait, cleared when the Resume is over */
144
151
  settling: string | null
145
- /** the capture ended last (E): its read-back is the one that opens, whatever seals first */
152
+ /** the capture ended last (E or ⇧E): if it was stopped to review, its read-back is the one that opens, whatever
153
+ * seals first */
146
154
  lastEnded: string | null
147
155
  }
148
156
 
@@ -175,7 +183,7 @@ function sizeNow(f: string, key?: string): { w: number; h: number; play?: true }
175
183
  const entry = st.manifest?.frames.find((x) => x.id === f)
176
184
  const slide = (entry && slideSize(entry, CONFIG.viewports)) ?? (st.play.slides ? SLIDE_INTRINSIC : null)
177
185
  if (slide) return { w: Math.round(slide.width), h: Math.round(slide.height), play: true }
178
- if (st.play.device === 'fill') return { w: window.innerWidth, h: window.innerHeight, play: true }
186
+ if (st.play.device === 'fill') { const u = usable(); return { w: u.width, h: u.height, play: true } }
179
187
  const v = CONFIG.viewports[st.play.device]
180
188
  return v ? { w: Math.round(v.width), h: Math.round(v.height), play: true } : undefined
181
189
  }
@@ -243,13 +251,13 @@ const viewNow = (focus = false): View => {
243
251
  * nothing that covers it (the panel and the lane leave their own room). */
244
252
  export function visibleNodes(): Node[] {
245
253
  const s = useStore.getState()
246
- const W = window.innerWidth, H = window.innerHeight
247
254
  const out: Node[] = []
248
255
  for (const n of s.nodes) {
249
256
  if (n.missing) continue
250
257
  const el = document.querySelector(`.sh-node[data-node="${CSS.escape(n.key)}"]`)
251
258
  const r = el?.getBoundingClientRect()
252
- if (r && r.right > 0 && r.bottom > 0 && r.left < W && r.top < H) out.push(n)
259
+ // on screen below the scroll edge (inset.ts): a frame under the Mac app's strip is not in view
260
+ if (r && onScreen(r)) out.push(n)
253
261
  }
254
262
  return out.slice(0, 20)
255
263
  }
@@ -686,7 +694,8 @@ function drain(id: string) {
686
694
  const st = useStore.getState()
687
695
  if (st.play) { mutate((s) => { const x = s.caps[id]; if (x) x.endShot = true }); shoot(id, st.play.at, 'end') }
688
696
  broadcast({ type: 'sh:capture', id, on: false })
689
- // the audio is cut at the key press, then its last words are awaited (3 s at most)
697
+ // the audio is cut at the key press, then its last words are awaited (15 s at most - E queues it only once they
698
+ // are in its record, as ⇧E's read-back shows them)
690
699
  mutate((st) => { const x = st.caps[id]; if (x) x.hearing = true })
691
700
  const tWords = performance.now()
692
701
  void voiceEnd(id).then((complete) => {
@@ -780,7 +789,7 @@ function buildRecord(c: Cap, steps: Cap['steps'], interrupted = false): CaptureR
780
789
  const timeline = [...steps].sort((a, b) => a.at - b.at || (a.seq ?? 0) - (b.seq ?? 0)).map(({ seq: _s, src: _k, ...step }) => step as Step)
781
790
  return {
782
791
  format: 'marver.jam.capture', v: 1, id: c.id,
783
- context: { canvas: location.host, board: c.board, ...(c.session ? { session: c.session } : {}), ...(c.reviewing ? { reviewing: c.reviewing } : {}), ...(c.resumes ? { resumes: c.resumes } : {}), ...(interrupted ? { interrupted: true as const } : {}) },
792
+ context: { canvas: location.host, board: c.board, ...(c.session ? { session: c.session } : {}), ...(c.reviewing ? { reviewing: c.reviewing } : {}), ...(c.resumes ? { resumes: c.resumes } : {}), ...(interrupted ? { interrupted: true as const } : {}), ...(c.review ? { review: true as const } : {}) },
784
793
  view: (timeline.find((x) => x.event === 'view') as Extract<Step, { event: 'view' }> | undefined)?.view ?? {},
785
794
  timeline, pictures: c.pictures, ...(() => { const sizes = sealedSizes(c); return Object.keys(sizes).length ? { sizes } : {} })(),
786
795
  }
@@ -797,7 +806,7 @@ function trySeal(id: string) {
797
806
  const record = buildRecord(c2, c2.steps)
798
807
  timeCapture(c2, false)
799
808
  // sealed: drop everything for this id that arrives later
800
- useJamCapture.setState((st) => { const caps = { ...st.caps }; delete caps[id]; return { caps, tick: st.tick + 1, sealed: [...st.sealed, { id }] } })
809
+ useJamCapture.setState((st) => { const caps = { ...st.caps }; delete caps[id]; return { caps, tick: st.tick + 1, sealed: [...st.sealed, { id, ...(c2.review ? { review: true as const } : {}) }] } })
801
810
  forgetHeard(id)
802
811
  keepSealed(record)
803
812
  void upload(record)
@@ -813,13 +822,19 @@ const syncUnsent = () => useJamCapture.setState({ unsent: [...pendingUploads.key
813
822
  * the pagehide listeners run in. */
814
823
  export const capturesPending = (): boolean => { const s = useJamCapture.getState(); return s.unsent.length > 0 || Object.keys(s.caps).length > 0 }
815
824
  const keepSealed = (r: CaptureRecord) => { try { const all = JSON.parse(localStorage.getItem(KEPT) ?? '{}'); all[r.id] = r; localStorage.setItem(KEPT, JSON.stringify(all)) } catch { /* memory only */ } pendingUploads.set(r.id, r); syncUnsent() }
816
- const forgetSealed = (id: string) => { pendingUploads.delete(id); syncUnsent(); try { const all = JSON.parse(localStorage.getItem(KEPT) ?? '{}'); delete all[id]; localStorage.setItem(KEPT, JSON.stringify(all)) } catch { /* memory only */ } }
825
+ const forgetKept = (id: string) => { try { const all = JSON.parse(localStorage.getItem(KEPT) ?? '{}'); delete all[id]; localStorage.setItem(KEPT, JSON.stringify(all)) } catch { /* memory only */ } }
817
826
  const pendingUploads = new Map<string, CaptureRecord>()
827
+ /** taken by the server, waiting only for its card on the page's queue: never posted again (a retry for another capture,
828
+ * a page shown again) - its one wait goes on, and its Sending tile with it */
829
+ const acked = new Set<string>()
830
+ /** posted, its answer not back yet: a retry round meanwhile leaves it alone (its answer starts the one wait) */
831
+ const inflight = new Set<string>()
818
832
  let retryTimer: ReturnType<typeof setTimeout> | null = null
819
833
  /** Post a sealed record - the same id, idempotent on the server - until it takes. A refusal about the
820
834
  * record itself (not the network) is final and said once; a dev server that is away is waited for. */
821
835
  async function upload(record: CaptureRecord, leaving = false): Promise<void> {
822
- type Verdict = { ok?: boolean; card?: { id: string; rev: number }; error?: string; outside?: boolean }
836
+ if (acked.has(record.id) || inflight.has(record.id)) return
837
+ type Verdict = { ok?: boolean; card?: { id: string; rev: number }; error?: string; outside?: boolean; held?: string }
823
838
  let r: Verdict | null = null
824
839
  try {
825
840
  // the workspace it was made in travels with it: another project served on this port refuses it
@@ -828,8 +843,12 @@ async function upload(record: CaptureRecord, leaving = false): Promise<void> {
828
843
  const payload = JSON.stringify({ record, workspace: CONFIG.workspace })
829
844
  // a page that is going sends with keepalive (64 kB at most, counted in UTF-8 bytes as the body carries it - not
830
845
  // `.length`: notes in another script are wider) so the request outlives it; a bigger one, the next page
831
- const res = await api('jam/capture', { method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() }, body: payload, ...(leaving && bytesOf(payload) < 60_000 ? { keepalive: true } : {}) })
832
- const body = (await res.json().catch(() => null)) as Verdict | null
846
+ inflight.add(record.id)
847
+ let res: Response, body: Verdict | null
848
+ try {
849
+ res = await api('jam/capture', { method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() }, body: payload, ...(leaving && bytesOf(payload) < 60_000 ? { keepalive: true } : {}) })
850
+ body = (await res.json().catch(() => null)) as Verdict | null
851
+ } finally { inflight.delete(record.id) }
833
852
  // only an explicit verdict on THIS record is final: taken (200, naming its card) or refused as a
834
853
  // record (400, saying why). Anything else - jam not running yet, another workspace, an unreadable
835
854
  // answer, a gate, a server error - is the server being away: keep it and try again
@@ -840,34 +859,81 @@ async function upload(record: CaptureRecord, leaving = false): Promise<void> {
840
859
  if (!r) {
841
860
  if (!retryTimer) useStore.getState().toast('the capture is kept here and will be sent when marver dev answers')
842
861
  retryTimer ??= setTimeout(() => { retryTimer = null; for (const x of pendingUploads.values()) void upload(x) }, 5_000)
862
+ if (!useJamCapture.getState().away) useJamCapture.setState({ away: true })
843
863
  return
844
864
  }
845
- forgetSealed(record.id)
865
+ if (useJamCapture.getState().away) useJamCapture.setState({ away: false })
866
+ forgetKept(record.id)
846
867
  releaseOpen(record.id, !r.ok) // it landed (the server knows); refused, it is no longer open either
847
- // the server holds it: a resumed draft is replaced now (or, refused, shows again)
868
+ useJamCapture.setState((st) => ({ sealed: st.sealed.map((x) => (x.id === record.id ? { ...x, ...(r!.card ? { card: r!.card } : {}) } : x)) }))
869
+ // what stands for it here - its Sending tile, a resumed draft kept off the lane - stays until the queue holds its
870
+ // card: the answer comes before the push that carries it, and in between the lane showed the old draft's To confirm
871
+ // in its place, or (nothing else on it) folded away and came back. A refresh that fails is not the end of the wait
872
+ if (r.ok) {
873
+ if (acked.has(record.id)) return // another answer for it already started its wait
874
+ acked.add(record.id); try { await untilQueued(record.id) } finally { acked.delete(record.id) }
875
+ }
876
+ pendingUploads.delete(record.id); syncUnsent()
877
+ // the resumed draft it replaced was dropped on the server - it leaves the lane for good; refused, it shows again
848
878
  const was = record.context.resumes?.id
849
- useJamCapture.setState((st) => ({ sealed: st.sealed.map((x) => (x.id === record.id ? { ...x, ...(r!.card ? { card: r!.card } : {}) } : x)), ...(was ? { resuming: st.resuming.filter((x) => x !== was) } : {}) }))
850
- void import('./jam-queue.ts').then(({ useJamQueue }) => useJamQueue.getState().load())
879
+ if (was) useJamCapture.setState((st) => ({ resuming: st.resuming.filter((x) => x !== was) }))
851
880
  if (!r.ok) useStore.getState().toast(`the capture could not be kept: ${r.error ?? 'unknown error'}`)
852
- // it reached the server after its session ended (another tab wrote the record): on its own
853
- else if (r.outside) leftOutOfSession(record.id)
881
+ else {
882
+ // stopped with E and the queue would not take it: it waits on the lane as a draft - said once, nothing opens
883
+ if (r.held) useStore.getState().toast(`the capture was not queued - it waits on the lane as a draft: ${r.held}`)
884
+ // it reached the server after its session ended (another tab wrote the record): on its own
885
+ if (r.outside) leftOutOfSession(record.id)
886
+ }
887
+ }
888
+
889
+ /** Until the page's queue holds this card: loaded now (a load that hangs is given 10 s), then again after 2, 4, 8 s and every 10 s on, unless a push
890
+ * brings it first - never given up on, so what stands for it never leaves the lane before its card is there. Any
891
+ * answer to a load ends it too: built after the canvas took the card, a view shows it (every card waiting or under way
892
+ * is shown, any other for a minute after it last changed) - unless it was finished elsewhere and has left the lane
893
+ * (another tab reviewed it while this page's refreshes failed), and then there is nothing left to wait for. */
894
+ async function untilQueued(id: string): Promise<void> {
895
+ const q = (await import('./jam-queue.ts')).useJamQueue
896
+ const held = () => !!q.getState().cards?.some((c) => c.id === id)
897
+ if (held()) return
898
+ // a push that brings the card ends the wait at any moment - a load that hangs never holds it up
899
+ let pushed = (): void => {}
900
+ const push = new Promise<true>((res) => { pushed = () => res(true) })
901
+ const un = q.subscribe(() => { if (held()) pushed() })
902
+ try {
903
+ const after = <T,>(ms: number, v: T) => new Promise<T>((res) => setTimeout(() => res(v), ms))
904
+ for (let wait = 2_000; !held(); wait = Math.min(wait * 2, 10_000)) {
905
+ // a refresh that hangs is given 10 s, then cancelled and the next one asked - it never stops the retries, and
906
+ // abandoned requests never pile up on the browser's connections. Only a refresh still unanswered at its 10 s is
907
+ // cancelled: one that answered, or that a push overtook, is left alone (it answers in a moment, and its view is
908
+ // applied only if newer than the push's). Cancelling those too (as each wait ended) reached whatever else on the
909
+ // page watches its requests - a browser extension's fetch hook - as a rejection it never handles, printed by Vite
910
+ // in the marver dev terminal on every E (29 Oct)
911
+ const ac = new AbortController()
912
+ const hang = setTimeout(() => ac.abort(), 10_000)
913
+ const answered = await Promise.race([q.getState().load({ signal: ac.signal }).finally(() => clearTimeout(hang)), push, after(10_000, false)])
914
+ if (answered) return
915
+ await Promise.race([push, after(wait, undefined)])
916
+ }
917
+ } finally { un() }
918
+ }
919
+
920
+ /** Was this capture (recording, sealing or not sent yet) stopped to review (⇧E, J)? E's never was. */
921
+ export function endedToReview(id: string): boolean {
922
+ const s = useJamCapture.getState()
923
+ return !!(s.caps[id]?.review ?? s.sealed.find((x) => x.id === id)?.review ?? pendingUploads.get(id)?.context.review)
854
924
  }
855
925
 
856
926
  /** A capture still recording, or finishing (its pictures and last words coming in), lives only in this page until it
857
- * seals; a sealed one is kept in localStorage until it lands. Leaving the page asks first - and if you leave anyway
858
- * (`pagehide`: a close, a reload, a navigation, the back-forward cache alike), every capture not sealed yet is sealed
859
- * at once, as it stood, for good: a missing step says so, the server keeps it as a draft, and it goes out like any
860
- * sealed record not sent yet - from the next page, or this one if it comes back. Carrying on is Resume, with a new id.
861
- * Best effort: a crash or a killed process fires nothing. */
927
+ * seals; a sealed one is kept in localStorage until it lands. Leaving the page asks first - unsaved.ts's one
928
+ * `beforeunload`, which hears this module's two reasons below - and if you leave anyway (`pagehide`: a close, a
929
+ * reload, a navigation, the back-forward cache alike), every capture not sealed yet is sealed at once, as it stood,
930
+ * for good: a missing step says so, the server keeps it as a draft (one already stopped with E is queued, as E does),
931
+ * and it goes out like any sealed record not sent yet - from the next page, or this one if it comes back. Carrying on
932
+ * is Resume, with a new id. Best effort: a crash or a killed process fires nothing. */
862
933
  let guarded = false
863
934
  function guardUnload() {
864
935
  if (guarded || typeof window === 'undefined') return
865
936
  guarded = true
866
- window.addEventListener('beforeunload', (e) => {
867
- if (!Object.keys(useJamCapture.getState().caps).length) return
868
- e.preventDefault()
869
- e.returnValue = ''
870
- })
871
937
  window.addEventListener('pagehide', () => sealOnLeave())
872
938
  // back from the back-forward cache: what was kept goes out now (never amended, never dropped)
873
939
  window.addEventListener('pageshow', (e) => { if (e.persisted) for (const r of pendingUploads.values()) void upload(r) })
@@ -886,7 +952,10 @@ export function sealOnLeave() {
886
952
  // text written in the notes card and never added is the capture's last note, as at E
887
953
  if (c.id === s.current && draft) steps.push({ at, event: 'note', text: draft })
888
954
  steps.push({ at, event: 'missing', what: c.state === 'recording' ? 'the page closed while it recorded' : 'the page closed before it finished' })
889
- records.push(buildRecord(c, steps, true))
955
+ // stopped with E and still finishing (its last words, its pictures): you sent it to work - it is queued as E does,
956
+ // the missing step saying what it lacks, never brought back as a draft to confirm. Recording, or stopped to
957
+ // review: a draft that waits for its read-back
958
+ records.push(buildRecord(c, steps, c.state === 'recording' || !!c.review))
890
959
  timeCapture(c, true)
891
960
  // its frames stop recording, its microphone is let go; a late picture or word finds nothing to change
892
961
  broadcast({ type: 'sh:capture', id: c.id, on: false })
@@ -916,6 +985,10 @@ export function resendSealed() {
916
985
  // the canvas answered again after it stopped (spec 28 A1.11): the page reloads only when no capture is
917
986
  // recording or finishing - a sealed one waits in localStorage and goes out from the next page
918
987
  holdsReload(() => capturesPending())
988
+ // leaving the page with a capture open, or one sealed and not taken by the server yet - a memory-only one too, its
989
+ // localStorage copy failed - asks first (spec 28 A2.9); the Mac app hears the same two reasons
990
+ unsavedWhen('capture-recording', () => Object.keys(useJamCapture.getState().caps).length > 0)
991
+ unsavedWhen('capture-unsent', () => useJamCapture.getState().unsent.length > 0)
919
992
 
920
993
  /** Resume's work, while the caller holds `settling`: load the record, let the caller settle, start. */
921
994
  async function resumeNow(draft: string, ready?: () => Promise<boolean>): Promise<boolean> {
@@ -945,6 +1018,7 @@ export const useJamCapture = create<CaptureState>((set, get) => ({
945
1018
  tick: 0,
946
1019
  sealed: [],
947
1020
  unsent: [],
1021
+ away: false,
948
1022
  resuming: [],
949
1023
  lastEnded: null,
950
1024
  settling: null,
@@ -962,9 +1036,12 @@ export const useJamCapture = create<CaptureState>((set, get) => ({
962
1036
  if (sessionEnding) { useStore.getState().toast('the session is being wrapped up - a moment'); return }
963
1037
  begin(reviewing, undefined, session)
964
1038
  },
965
- end() {
1039
+ end(review = false) {
966
1040
  const id = get().current
967
1041
  if (!id) return
1042
+ // ⇧E: its record says so, and it waits for its read-back; E: the server makes its card queued - no read-back,
1043
+ // nothing opens or moves here
1044
+ if (review) mutate((st) => { const x = st.caps[id]; if (x) x.review = true })
968
1045
  set({ current: null, lastEnded: id })
969
1046
  cancelDwell()
970
1047
  drain(id)
@@ -1002,6 +1079,9 @@ export const useJamCapture = create<CaptureState>((set, get) => ({
1002
1079
  },
1003
1080
  }))
1004
1081
 
1082
+ // a capture opened, sealed or taken by the server: what this page holds changed (unsaved.ts)
1083
+ useJamCapture.subscribe((s, p) => { if (Object.keys(s.caps).length !== Object.keys(p.caps).length || s.unsent.length !== p.unsent.length) workChanged() })
1084
+
1005
1085
  /** What the capture tile shows: the timer and the counts. */
1006
1086
  export function captureCounts(c: Cap | undefined, t = now()): { time: string; counts: string; notes: number } {
1007
1087
  if (!c) return { time: '0:00', counts: '', notes: 0 }
@@ -1016,4 +1096,4 @@ export function captureCounts(c: Cap | undefined, t = now()): { time: string; co
1016
1096
  }
1017
1097
  }
1018
1098
 
1019
- if (typeof window !== 'undefined' && (import.meta as any).env?.DEV) { (window as any).__mvJamCapture = useJamCapture; (window as any).__mvJamInstances = instances }
1099
+ if (typeof window !== 'undefined' && (import.meta as any).env?.DEV) { (window as any).__mvJamCapture = useJamCapture; (window as any).__mvJamInstances = instances; (window as any).__mvJamVisible = visibleNodes }
@@ -5,7 +5,7 @@
5
5
  *
6
6
  * a read-back open ⏎ confirm · K keep · R resume (it ended too soon) · Esc drop
7
7
  * the notes card open Esc closes the card · N puts the focus back in its field
8
- * a capture open E end · S says to end it first · N notes card · I picture · Esc drop
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
11
  * the lane has the keys ← → move · ⏎ open · ⌘⏎ do next · K keep · ⌫ drop · Esc leave
@@ -23,6 +23,7 @@ import { pressJ, startSession, wrapWrite } from './jam-session.tsx'
23
23
  import { clearMoreDraft } from './jam-panel.tsx'
24
24
  import { CONFIG, PUBLISHED, SOURCE_REVEALED, useStore } from './store.ts'
25
25
  import { holdsReload } from './api.ts'
26
+ import { unsavedWhen, workChanged } from './unsaved.ts'
26
27
 
27
28
  export interface KeyIn { key: string; shift?: boolean; alt?: boolean; meta?: boolean; ctrl?: boolean }
28
29
  /** `[Ctrl+][Meta+][Alt+][Shift+]key`, a letter lowercase - the frames' descriptor (keys.js). */
@@ -59,12 +60,13 @@ export function saveEdit(c: JamCard, text: string) {
59
60
  const g = ++gen
60
61
  latest.set(c.id, g)
61
62
  unsaved.set(c.id, text)
63
+ workChanged()
62
64
  const before = saving.get(c.id) ?? Promise.resolve(true)
63
65
  // saves of one card run in order, each at the card's rev as the one before left it
64
66
  saving.set(c.id, before.then(() => {
65
67
  const fresh = useJamQueue.getState().cards?.find((x) => x.id === c.id) ?? c
66
68
  return useJamQueue.getState().act(fresh, 'edit', text)
67
- }).then((ok) => { if (ok && latest.get(c.id) === g) unsaved.delete(c.id); return ok }))
69
+ }).then((ok) => { if (ok && latest.get(c.id) === g) { unsaved.delete(c.id); workChanged() } return ok }))
68
70
  }
69
71
  /** Notes added in a read-back not saved yet, per card: each with its own id - one on its way, or one that failed
70
72
  * and waits to be sent again. Sent again (from the field, or before a decision) it keeps its id: the server
@@ -74,6 +76,8 @@ const unsavedNotes = new Map<string, PendingNote[]>()
74
76
  // spec 28 A1.11: a page whose canvas came back reloads only once every edit and note of a read-back has saved -
75
77
  // one that failed while the canvas was away waits for the read-back's own retry (a decision saves it first)
76
78
  holdsReload(() => unsaved.size > 0 || unsavedNotes.size > 0)
79
+ // and leaving the page asks first (spec 28 A2.9): a read-back's edit or note not saved yet is words not sent
80
+ unsavedWhen('typing', () => unsaved.size > 0 || unsavedNotes.size > 0)
77
81
  const sendNote = (c: JamCard, n: PendingNote): Promise<boolean> => {
78
82
  n.failed = false
79
83
  const before = saving.get(c.id) ?? Promise.resolve(true)
@@ -82,7 +86,7 @@ const sendNote = (c: JamCard, n: PendingNote): Promise<boolean> => {
82
86
  return useJamQueue.getState().act(fresh, 'note', JSON.stringify({ id: n.id, text: n.text, order: n.order }))
83
87
  }).then((ok) => {
84
88
  const list = unsavedNotes.get(c.id) ?? []
85
- if (ok) { const left = list.filter((x) => x !== n); if (left.length) unsavedNotes.set(c.id, left); else unsavedNotes.delete(c.id) } else n.failed = true
89
+ if (ok) { const left = list.filter((x) => x !== n); if (left.length) unsavedNotes.set(c.id, left); else unsavedNotes.delete(c.id); workChanged() } else n.failed = true
86
90
  return ok
87
91
  }, () => { n.failed = true; return false })
88
92
  saving.set(c.id, p.then(() => true))
@@ -95,6 +99,7 @@ export function addNote(c: JamCard, text: string, id: string): Promise<boolean>
95
99
  const was = (unsavedNotes.get(c.id) ?? []).find((x) => x.id === id)
96
100
  const n: PendingNote = { id, text, failed: false, order: was?.order ?? Date.now() }
97
101
  unsavedNotes.set(c.id, [...(unsavedNotes.get(c.id) ?? []).filter((x) => x.id !== id), n])
102
+ workChanged()
98
103
  return sendNote(c, n)
99
104
  }
100
105
  /** Every note added to a draft saved (a failed one sent again, once): before it is sent, kept or resumed. */
@@ -119,7 +124,7 @@ export async function decideDraft(id: string, action: 'confirm' | 'keep' | 'drop
119
124
  }
120
125
  // a note added in its read-back goes with it: one that did not save is sent again, and nothing is sent without it
121
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 }
122
- if (action === 'drop') { unsaved.delete(id); unsavedNotes.delete(id) }
127
+ if (action === 'drop') { unsaved.delete(id); unsavedNotes.delete(id); workChanged() }
123
128
  const fresh = useJamQueue.getState().cards?.find((c) => c.id === id)
124
129
  if (!fresh) return
125
130
  if (await useJamQueue.getState().act(fresh, action)) useJamUi.getState().close()
@@ -174,12 +179,37 @@ export function openTile(id: string) {
174
179
  reveal(c)
175
180
  }
176
181
 
177
- /** Open a card's thread - on another board, its link opens that board, then the thread (as a
178
- * notification's does). */
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. */
179
187
  export function openThread(c: JamCard) {
180
188
  if (!c.thread) return
181
- if (c.board !== useStore.getState().board) { location.hash = `#/b/${encodeURIComponent(c.board)}?c=${encodeURIComponent(c.thread)}`; return }
182
- void import('./comments-store.ts').then(({ useComments }) => useComments.getState().setActive(c.thread!))
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
209
+ useJamUi.getState().select(c.id)
210
+ useJamUi.getState().open({ kind: 'capture', id: c.id })
211
+ reveal(c)
212
+ })
183
213
  }
184
214
 
185
215
  /** Bring a card's frames into view beside the panel - on its own board (a frame link lands there). */
@@ -268,7 +298,8 @@ const rows = (): Row[] => {
268
298
  { // a capture open
269
299
  on: () => !!cap.current,
270
300
  keys: {
271
- e: () => cap.end(),
301
+ e: () => cap.end(), // straight to the queue
302
+ 'Shift+e': () => cap.end(true), // stop to review: its read-back opens
272
303
  s: () => cap.start(), // one at a time: it says to end this one first
273
304
  // L: laser picks - a pick inside a capture is its pick (frames forward it while interacting)
274
305
  // L: the pointer laser; ⌥L: inspect - a laser click inside a capture is its pick either way
@@ -13,7 +13,7 @@ import { useEffect, useLayoutEffect, useRef, useState } from 'react'
13
13
  import { JamStateIcon, type JamGlyph } from './jam-ui.tsx'
14
14
  import { Tip } from './Tip.tsx'
15
15
  import { DONE_CLOSE, DONE_GROUP, doneFold, doneLine } from './jam-state.ts'
16
- import { ArrowsInLineHorizontalIcon, CursorClickIcon, FileCodeIcon, ImagesSquareIcon, LaserIcon, MicrophoneIcon, MicrophoneSlashIcon, PencilSimpleIcon } from './icons.tsx'
16
+ import { ArrowsInLineHorizontalIcon, CursorClickIcon, FileCodeIcon, ImagesSquareIcon, LaserIcon, MicrophoneIcon, MicrophoneSlashIcon, PauseIcon, PencilSimpleIcon } from './icons.tsx'
17
17
 
18
18
  /** The lane's height with its air: the 44 px tile + 12 px. While the lane shows, the sidebar stops
19
19
  * above it and everything else on the bottom edge (the Update pill, toasts, notices) rises this much. */
@@ -26,6 +26,8 @@ export interface LaneTile {
26
26
  title: string
27
27
  /** the status line - jam-lines.ts `laneLine` */
28
28
  line: string
29
+ /** a working tile's status line on hover: whose run it is (jam-lines.ts `laneTip`) */
30
+ tip?: string
29
31
  /** an exclusive card wears a file glyph: it changes how the queue runs */
30
32
  exclusive?: boolean
31
33
  /** a done tile: the frames it changed (not the ones it left as they were) - the Done group counts each frame once */
@@ -56,6 +58,7 @@ export interface LaneRecording {
56
58
  onMic?(): void
57
59
  onNote(): void
58
60
  onStop(): void
61
+ onStopReview(): void
59
62
  }
60
63
 
61
64
  /**
@@ -190,7 +193,7 @@ export function Lane({ tiles, recording, between, selected, keyboard, onOpen, on
190
193
  <span className="tx">
191
194
  {/* the whole title, in the shell's own tooltip - only when the tile cuts it short */}
192
195
  <Tip label={<span className="jm-tip-title">{t.title}</span>} only={(el) => el.scrollWidth > el.clientWidth + 1}><span className="t">{t.title}</span></Tip>
193
- <span className="m">{t.line}</span>
196
+ {t.tip ? <Tip label={<div className="sh-tip-lines">{t.tip}</div>}><span className="m">{t.line}</span></Tip> : <span className="m">{t.line}</span>}
194
197
  </span>
195
198
  {t.exclusive && <span className="x" aria-label="changes a shared file"><FileCodeIcon size={13} /></span>}
196
199
  </button>
@@ -218,8 +221,9 @@ export function BetweenTile({ since, mic, onCapture }: LaneBetween) {
218
221
  }
219
222
 
220
223
  /** The capture recording now: a pulsing teal dot, "Capturing" and the timer over what it holds so far,
221
- * then the Note button (N, with the count) and Stop (E). After E it reads "Finishing". */
222
- export function CaptureTile({ time, points, pictures = 0, picturesMax, steps, counts, notes, noteOn, finishing, mic, onMic, onNote, onStop }: LaneRecording) {
224
+ * then the Note button (N, with the count), Stop (E: queued at once) and Stop to review (⇧E, a pause icon: its read-back opens).
225
+ * After either it reads "Finishing". */
226
+ export function CaptureTile({ time, points, pictures = 0, picturesMax, steps, counts, notes, noteOn, finishing, mic, onMic, onNote, onStop, onStopReview }: LaneRecording) {
223
227
  return (
224
228
  <div className={`jm-chip${finishing ? ' finishing' : ''}`} data-tile="capturing">
225
229
  {finishing ? <JamStateIcon state="confirming" /> : <i className="jm-live-dot" />}
@@ -243,7 +247,12 @@ export function CaptureTile({ time, points, pictures = 0, picturesMax, steps, co
243
247
  <button className={`notebtn${noteOn ? ' on' : ''}`} onClick={onNote} disabled={finishing} aria-pressed={noteOn}>
244
248
  <PencilSimpleIcon size={13} />Note{notes ? <b>{notes}</b> : null}<kbd>N</kbd>
245
249
  </button>
246
- <button className="stop" onClick={onStop} disabled={finishing}>Stop<kbd>E</kbd></button>
250
+ <Tip label="Stop and queue it - the agent starts on it">
251
+ <button className="stop" onClick={onStop} disabled={finishing}>Stop<kbd>E</kbd></button>
252
+ </Tip>
253
+ <Tip label="Stop and look it over first - add notes, then queue it">
254
+ <button className="stop review" onClick={onStopReview} disabled={finishing}><PauseIcon size={12} />Stop to review<kbd>⇧E</kbd></button>
255
+ </Tip>
247
256
  </div>
248
257
  )
249
258
  }