@marver-design/marver 0.28.0 → 0.29.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 (62) hide show
  1. package/CHANGELOG.md +59 -0
  2. package/README.md +2 -2
  3. package/dist/{anchor-check-PHUOFj1N.mjs → anchor-check-DhlpKl2K.mjs} +1 -1
  4. package/dist/{build-BsAyLMT1.mjs → build-CWbrb2bl.mjs} +5 -3
  5. package/dist/{capture-DdZ6xgoz.mjs → capture-DEtM4qm5.mjs} +168 -5
  6. package/dist/cli.mjs +10 -10
  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-Sc_z8gT6.mjs} +28 -29
  10. package/dist/{dev-D7YS7iT2.mjs → dev-DWBKQhxf.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-Denssrko.mjs} +43 -25
  18. package/dist/{perf-jam-QxD_UnzN.mjs → perf-jam-CLkERSHo.mjs} +8 -1
  19. package/dist/{plugin-C_0yb-Fq.mjs → plugin-DqoZB-D6.mjs} +511 -298
  20. package/dist/{poster-DHi6I1fO.mjs → poster-CrsjqhY4.mjs} +1 -1
  21. package/dist/{profile-jIS6BcAs.mjs → profile-B1FKOM1e.mjs} +1 -1
  22. package/dist/{publish-bakes-r4PEZuPl.mjs → publish-bakes-DW-NDgU2.mjs} +3 -3
  23. package/dist/{queue-c-6aTHEz.mjs → queue-DeSQm24g.mjs} +29 -14
  24. package/dist/{recover-nrLEVLyJ.mjs → recover-GtJ9UDAB.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-T04Ixrvq.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/boards-and-folders.md +11 -0
  32. package/docs/jam-session.md +12 -3
  33. package/docs/live-jam.md +3 -0
  34. package/docs/performance.md +1 -1
  35. package/docs/publish.md +7 -0
  36. package/package.json +1 -1
  37. package/src/client/shell/Comments.tsx +5 -4
  38. package/src/client/shell/ContextMenu.tsx +5 -4
  39. package/src/client/shell/JamSurface.tsx +80 -9
  40. package/src/client/shell/Play.tsx +16 -4
  41. package/src/client/shell/api.ts +7 -3
  42. package/src/client/shell/app-bridge.ts +11 -3
  43. package/src/client/shell/comments-store.ts +14 -0
  44. package/src/client/shell/goto.ts +4 -3
  45. package/src/client/shell/jam-capture.ts +39 -15
  46. package/src/client/shell/jam-keys.ts +166 -40
  47. package/src/client/shell/jam-lines.ts +10 -1
  48. package/src/client/shell/jam-panel.tsx +8 -6
  49. package/src/client/shell/jam-queue.ts +6 -1
  50. package/src/client/shell/jam-session.tsx +2 -2
  51. package/src/client/shell/jam-state.ts +19 -4
  52. package/src/client/shell/jam-ui.tsx +4 -0
  53. package/src/client/shell/live-picture.ts +134 -0
  54. package/src/client/shell/open-item.ts +83 -0
  55. package/src/client/shell/open-resolve.ts +50 -0
  56. package/src/client/shell/store.ts +6 -2
  57. package/src/client/shell/styles.css +2 -0
  58. package/src/client/stage/main.tsx +30 -8
  59. package/src/shared/app-api.ts +173 -3
  60. package/src/shared/app-perf.ts +4 -2
  61. package/templates/instructions/jam.md +4 -0
  62. package/dist/live-Cgzsicwi.mjs +0 -4
@@ -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
@@ -18,11 +19,13 @@
18
19
  */
19
20
  import { useJamCapture, setOwnedKeys } from './jam-capture.ts'
20
21
  import { changedShots, useJamQueue, type JamCard } from './jam-queue.ts'
21
- import { DONE_CLOSE, DONE_GROUP, doneFold, useJamUi } from './jam-state.ts'
22
+ import { DONE_CLOSE, DONE_GROUP, doneFold, jamSurface, useJamUi } from './jam-state.ts'
22
23
  import { pressJ, startSession, wrapWrite } from './jam-session.tsx'
23
24
  import { clearMoreDraft } from './jam-panel.tsx'
24
25
  import { CONFIG, PUBLISHED, SOURCE_REVEALED, useStore } from './store.ts'
26
+ import { ALL_SCENES } from '../../shared/board-tree.ts'
25
27
  import { holdsReload } from './api.ts'
28
+ import { navigated, switchFor } from './goto.ts'
26
29
  import { unsavedWhen, workChanged } from './unsaved.ts'
27
30
 
28
31
  export interface KeyIn { key: string; shift?: boolean; alt?: boolean; meta?: boolean; ctrl?: boolean }
@@ -164,62 +167,181 @@ export async function resumeDraft(id: string) {
164
167
  } finally { useJamCapture.setState({ settling: null }) }
165
168
  }
166
169
 
170
+ /** A request's life (spec 28 A4.6 #30): read before every step that moves the UI. A click passes none - always true. */
171
+ export type Alive = () => boolean
172
+ const always: Alive = () => true
173
+ /** 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`. */
174
+ const waitMs = (o: { alive?: Alive }, away = false) => (o.alive ? 10_000 : away ? 6_000 : 3_000)
175
+ /** Wait until `ok`, while `alive` holds and `ms` lasts: false once `alive` fails first, or the time is up. */
176
+ async function waitFor(ok: () => boolean, alive: Alive, ms: number): Promise<boolean> {
177
+ const until = performance.now() + ms
178
+ for (;;) {
179
+ if (!alive()) return false
180
+ if (ok()) return true
181
+ if (performance.now() > until) return false
182
+ await new Promise((r) => setTimeout(r, 30))
183
+ }
184
+ }
185
+ const drawn = (sel: string) => () => !!document.querySelector(sel)
186
+ /** A card's status popover, open (jam-ui.tsx TagStatus): its run's controls on the page. */
187
+ const statusOpen = (card: string) => `.cm-tstat.on[data-jam-card="${CSS.escape(card)}"]`
188
+
189
+ /** Another board (A4.6 #30). A request's switch commits only while its `alive` holds, read just before the board commits
190
+ * (store.ts switchBoard): words typed while the board loads, a hidden tab, the deadline or a later click leave the board,
191
+ * its draft and its open thread as they were - a hash set and left to the router would land whatever came after. A
192
+ * click (no request) follows the board's link, as before. True once the board is shown. */
193
+ export async function toBoard(board: string, alive?: Alive): Promise<boolean> {
194
+ if (!alive) {
195
+ location.hash = `#/b/${encodeURIComponent(board)}`
196
+ return waitFor(() => useStore.getState().board === board, always, waitMs({}, true))
197
+ }
198
+ if (!alive()) return false
199
+ // a stale overlay never survives into another board (App.tsx's router does the same)
200
+ if (useStore.getState().play) useStore.getState().setPlay(null)
201
+ // the wait is the request's too, however long the board's save or read takes (code review r2 P2) - and the switch,
202
+ // should it finish later, cannot commit: its predicate is alive, which never holds again once it failed (open-item.ts)
203
+ return (await whileAlive(switchFor(board, navigated(), alive), alive)) && alive()
204
+ }
205
+
206
+ /** `p`, or false as soon as `alive` fails, read every 30 ms: a request never waits past its own life - its deadline, or
207
+ * its end - whatever it waits on (a board's save or read, a hidden view's frames). The look stops once either settles. */
208
+ async function whileAlive<T>(p: Promise<T>, alive: Alive): Promise<T | false> {
209
+ // a click has no request to outlive: it waits on `p` alone, leaving no look behind in a hidden view (code review r4 P3)
210
+ if (alive === always) return p
211
+ let done = false
212
+ const ended = new Promise<false>((r) => { const look = () => { if (done) return; if (!alive()) { r(false); return } setTimeout(look, 30) }; look() })
213
+ try { return await Promise.race([p, ended]) } finally { done = true }
214
+ }
215
+
216
+ /** 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
217
+ * its menu - is never drawn under the Play overlay, and the lane is folded there. Left with no way back to its frame
218
+ * (playCtl.leave, not Esc's exit): Esc's return - a fit, or a switch to the board a frame of another board lives on -
219
+ * would run outside the request, and land on another board over a reply typed after the thread opened (code review r2
220
+ * P1). False when `alive` failed, or when Play could not be left - a board locked to its mode has no way out (Play.tsx
221
+ * `noDoor`); the caller tells them apart by `alive()` and opens over Play instead. */
222
+ async function leavePlay(alive: Alive): Promise<boolean> {
223
+ if (!useStore.getState().play) return true
224
+ const { playCtl } = await import('./Play.tsx')
225
+ if (!alive()) return false
226
+ if (!playCtl.leave() || useStore.getState().play) return false
227
+ // two frames for the layout, under the request: a hidden view can hold its frames for good (code review r3 P2), and
228
+ // the frame asked for is cancelled once the request has ended
229
+ let raf = 0
230
+ const laid = await whileAlive(new Promise<true>((r) => { raf = requestAnimationFrame(() => { raf = requestAnimationFrame(() => r(true)) }) }), alive)
231
+ if (!laid) cancelAnimationFrame(raf)
232
+ return laid && alive()
233
+ }
234
+
167
235
  /** 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) {
236
+ * its thread, any other capture its detail - the read-back for a draft. True once its surface is drawn. */
237
+ export async function openTile(id: string, o: { alive?: Alive } = {}): Promise<boolean> {
238
+ const alive = o.alive ?? always
170
239
  const c = cardById(id)
240
+ if (!c || !alive()) return false
171
241
  const ui = useJamUi.getState()
172
- if (!c) return
173
242
  if (c.state === 'asks' && c.thread) {
174
243
  ui.select(id)
175
- openThread(c)
176
- return
244
+ return openThreadAt(c.board, c.thread, { card: c, alive })
177
245
  }
246
+ // a request's card on another board: that board first, under the request (a click's reveal follows the link)
247
+ if (o.alive && c.board !== useStore.getState().board && !(await toBoard(c.board, o.alive))) return false
178
248
  ui.open({ kind: c.state === 'review' ? 'review' : c.kind === 'wrapup' ? 'wrapup' : 'capture', id })
179
- reveal(c)
249
+ reveal(c, o.alive)
250
+ return waitFor(() => useJamUi.getState().panel?.id === id && !!document.querySelector('[data-jam-focus]'), alive, waitMs(o))
180
251
  }
181
252
 
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
253
+ /**
254
+ * 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
255
+ * that opens a thread. On another board, that board opens first (toBoard) - the legacy all-scenes log is no board a link
256
+ * lands on (App.tsx sends it elsewhere), so its threads open on the board shown. An open thread whose frame a node of
257
+ * the board hosts shows in its thread card: Play left first, comments hidden by Shift+C turned on (a hidden layer draws
258
+ * nothing), then revealed; Play that cannot be left (a board locked to its mode) keeps the canvas under it, so the
259
+ * thread opens over Play as an unhosted one does. A capture's thread with no host opens the capture's own panel - with
260
+ * its question and a field when it asks - as in 0.28. Every other thread - frameless, its frame gone, resolved - opens
261
+ * 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
262
+ * card or the thread panel: the run's controls in view. True only once a surface for the thread is drawn - its card
263
+ * mounted, or a panel open on it, and with `status` that popover open; false when `alive` failed first.
264
+ */
265
+ export async function openThreadAt(board: string, thread: string, o: { card?: JamCard; status?: string; alive?: Alive } = {}): Promise<boolean> {
266
+ const alive = o.alive ?? always
267
+ const away = board !== ALL_SCENES && board !== useStore.getState().board
268
+ const ms = waitMs(o, away)
269
+ if (away && !(await toBoard(board, o.alive))) return false
270
+ const [{ revealThread }, { useComments }, { threadHostKey }] = await Promise.all([import('./Comments.tsx'), import('./comments-store.ts'), import('./keys.ts')])
271
+ const find = () => useComments.getState().threads.find((t) => t.id === thread && (!t.board || t.board === board))
272
+ // the board's comments may still be loading: known, or the time is up
273
+ await waitFor(() => !!find(), alive, ms)
274
+ if (!alive()) return false
275
+ const t = find()
276
+ const ok = (sel: string) => waitFor(() => drawn(sel)() && (!o.status || drawn(statusOpen(o.status))()), alive, ms)
277
+ // only an open thread has a card (the layer keeps open threads); Play kept, a card would draw under it
278
+ let host = t && !t.resolved ? threadHostKey(t, useStore.getState().nodes) : null
279
+ if (host && !(await leavePlay(alive))) {
280
+ if (!alive()) return false
281
+ host = null
282
+ }
283
+ if (host) {
284
+ if (!useComments.getState().show) { if (!alive()) return false; useComments.getState().setShow(true) }
285
+ if (!alive()) return false
286
+ if (o.status) useJamUi.getState().askStatus(o.status)
287
+ if (!revealThread(thread, alive)) return false
288
+ return ok(`.cm-card[data-thread="${CSS.escape(thread)}"]`)
289
+ }
290
+ const c = o.card
291
+ if (c?.kind === 'capture' && !t?.resolved) {
292
+ if (!alive()) return false
209
293
  useJamUi.getState().select(c.id)
210
294
  useJamUi.getState().open({ kind: 'capture', id: c.id })
211
- reveal(c)
212
- })
295
+ reveal(c, o.alive)
296
+ return ok('[data-jam-readback]')
297
+ }
298
+ if (!t || !alive()) return false
299
+ if (o.status) useJamUi.getState().askStatus(o.status)
300
+ useJamUi.getState().open({ kind: 'thread', id: thread, board })
301
+ return ok(`[data-jam-thread-panel="${CSS.escape(thread)}"]`)
302
+ }
303
+
304
+ /** 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 })
307
+ }
308
+
309
+ /**
310
+ * 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
311
+ * card has no tile: its thread opens with its status popover open on Retry or the three choices - in its thread card,
312
+ * or the thread panel. A capture or a record (the cards with a tile): failed, its panel with Retry and Drop in its
313
+ * footer; stalled, its tile selected and the tile's menu opened at it (Play left first: Play folds the lane - Play that
314
+ * cannot be left opens its lane over the stage, as Q does there).
315
+ */
316
+ export async function openRunControls(c: JamCard, o: { alive?: Alive } = {}): Promise<boolean> {
317
+ const alive = o.alive ?? always
318
+ if (c.kind === 'comment') return c.thread ? openThreadAt(c.board, c.thread, { card: c, status: c.id, alive }) : false
319
+ if (c.state === 'failed') return (await openTile(c.id, o)) && waitFor(drawn('[data-jam-focus] [data-jam-run-act="retry"]'), alive, waitMs(o))
320
+ if (!(await leavePlay(alive))) {
321
+ if (!alive()) return false
322
+ useJamUi.getState().setLaneKeys(true)
323
+ }
324
+ if (!(await waitFor(drawn(`.jm-lane [data-tile="${CSS.escape(c.id)}"]`), alive, waitMs(o)))) return false
325
+ if (!alive()) return false
326
+ useJamUi.getState().select(c.id)
327
+ if (!jamSurface.tileMenu(c.id)) return false
328
+ return waitFor(drawn(`.sh-ctxmenu[data-menu="tile:${CSS.escape(c.id)}"]`), alive, waitMs(o))
213
329
  }
214
330
 
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) {
331
+ /** Bring a card's frames into view beside the panel - on its own board (a frame link lands there). A request's `alive`
332
+ * (A4.6 #30) is read again when the camera moves: one that ended meanwhile - a later click, a hidden tab, the deadline,
333
+ * words typed - moves nothing, and its board is switched under it (toBoard), never by a link. */
334
+ export function reveal(c: JamCard, alive?: Alive) {
217
335
  const s = useStore.getState()
218
336
  if (!c.frames.length) return
219
- if (c.board !== s.board) { location.hash = `#/b/${encodeURIComponent(c.board)}?f=${c.frames.map(encodeURIComponent).join(',')}`; return }
337
+ if (c.board !== s.board) {
338
+ if (!alive) location.hash = `#/b/${encodeURIComponent(c.board)}?f=${c.frames.map(encodeURIComponent).join(',')}`
339
+ else void toBoard(c.board, alive).then((ok) => { if (ok) reveal(c, alive) })
340
+ return
341
+ }
220
342
  const keys = s.nodes.filter((n) => c.frames.includes(n.frame)).map((n) => n.key)
221
343
  // 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))))
344
+ if (keys.length) void import('./canvas/ctl.ts').then(({ canvasCtl }) => requestAnimationFrame(() => requestAnimationFrame(() => { if (!alive || alive()) canvasCtl.fitNodes(keys) })))
223
345
  }
224
346
 
225
347
  /** The next capture to review after `from` (or the oldest), walking the lane left to right. */
@@ -324,6 +446,10 @@ const rows = (): Row[] => {
324
446
  Escape: () => { if (ui.moreOpen) { clearMoreDraft(panelCard!.id); ui.setMoreOpen(false) } else ui.close() }, // Esc leaves the composer: its words go
325
447
  },
326
448
  },
449
+ { // the thread panel open (a notice's thread no card can show): Esc closes it
450
+ on: () => ui.panel?.kind === 'thread',
451
+ keys: { Escape: () => { if (laserOff()) return; ui.close() } },
452
+ },
327
453
  { // the lane has the keyboard
328
454
  on: () => ui.laneKeys,
329
455
  keys: (() => {
@@ -154,13 +154,22 @@ export function timelineLines(r: CaptureRecord, edited?: string): TimelineLine[]
154
154
  case 'interact': out.push({ t, kind: 'interact', text: s.on ? 'on' : 'off' }); break
155
155
  case 'picture':
156
156
  pictures++
157
- out.push({ t, kind: 'picture', text: `${frameName(s.frame).toLowerCase()}${s.why === 'end' ? ' at E' : s.why === 'pick' ? ' at a pick' : ''}`, point: pictures }); break
157
+ out.push({ t, kind: 'picture', text: `${frameName(s.frame).toLowerCase()}${s.why === 'end' ? ' at E' : s.why === 'pick' ? ' at a pick' : ''}${s.source === 'live' ? ` · ${AS_SEEN}` : ''}`, point: pictures }); break
158
158
  case 'missing': out.push({ t, kind: 'missing', text: s.what }); break
159
159
  }
160
160
  }
161
161
  return out
162
162
  }
163
163
 
164
+ /** A live picture's words (A4.6 #38): the Mac app's picture of the stage, as the owner saw it - not a render. */
165
+ const AS_SEEN = 'as you saw it'
166
+ /** A capture's picture as the read-back and the review's Capture tab caption it: "picture N", and "picture N · as you saw
167
+ * it" for a live one (its picture step says `source: 'live'`). */
168
+ export function pictureCaption(r: CaptureRecord, id: string, n: number): string {
169
+ const live = r.timeline.some((s) => s.event === 'picture' && s.id === id && s.source === 'live')
170
+ return `picture ${n}${live ? ` · ${AS_SEEN}` : ''}`
171
+ }
172
+
164
173
  /** A line as plain text, the spec's format: `[0:05] (pick 1) <span> "Save 20%" · file.tsx:48`,
165
174
  * `[0:04] "this badge"`, `[0:13] (interact on)`. */
166
175
  export function lineText(l: TimelineLine): string {
@@ -294,7 +294,7 @@ export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, picture
294
294
  <div className="actions">
295
295
  {readOnly ? (
296
296
  <><span className="sp" />{onOpenThread && <button className="jm-btn" onClick={onOpenThread}>Open thread</button>}
297
- {onRetry && <><button className="jm-btn ghost" onClick={onDrop}>Drop</button><button className="jm-btn primary" onClick={onRetry}>Retry</button></>}</>
297
+ {onRetry && <><button className="jm-btn ghost" data-jam-run-act="drop" onClick={onDrop}>Drop</button><button className="jm-btn primary" data-jam-run-act="retry" onClick={onRetry}>Retry</button></>}</>
298
298
  ) : (
299
299
  <>
300
300
  <span className="dim">{agent ? <>For <b style={{ color: 'var(--glass-ink-2)', fontWeight: 600 }}>{agent}</b></> : 'No agent yet - it waits in the queue'}</span>
@@ -311,8 +311,10 @@ export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, picture
311
311
  }
312
312
 
313
313
  /** What a capture's run asked you, and your answer - for a thread this board cannot show (its frame is on no node
314
- * here). Sent with @marver in its thread: the answer goes back to the agent, as a tagged reply does. */
315
- function AsksAnswer({ question, onAnswer }: { question: string; onAnswer(text: string): Promise<boolean> }) {
314
+ * here). Sent with @marver in its thread: the answer goes back to the agent, as a tagged reply does. The thread panel
315
+ * (spec 28 A4.6 #30) draws its own messages (no `question`) and says `tag` only when a Jam card is on the thread - a
316
+ * tag anywhere else would start a run nobody asked for, so the answer goes as typed. */
317
+ export function AsksAnswer({ question, onAnswer, tag = true }: { question?: string; onAnswer(text: string): Promise<boolean>; tag?: boolean }) {
316
318
  const [text, setText] = useState('')
317
319
  const [sending, setSending] = useState(false)
318
320
  const send = () => {
@@ -322,12 +324,12 @@ function AsksAnswer({ question, onAnswer }: { question: string; onAnswer(text: s
322
324
  }
323
325
  return (
324
326
  <div className="jm-asks" data-jam-asks="" style={{ display: 'flex', flexDirection: 'column', gap: 7 }}>
325
- <div className="jm-reply">
327
+ {question !== undefined && <div className="jm-reply">
326
328
  <Marver size={20} />
327
329
  <p>{question || 'It asks you something - see its thread.'}</p>
328
- </div>
330
+ </div>}
329
331
  <div className="jm-more">
330
- <span className="at">@marver</span>
332
+ {tag && <span className="at">@marver</span>}
331
333
  <textarea className="txt" rows={1} value={text} placeholder="Your answer" disabled={sending}
332
334
  onChange={(e) => setText(e.target.value)}
333
335
  onKeyDown={(e) => {
@@ -27,8 +27,13 @@ export interface JamCard {
27
27
  file?: string
28
28
  /** who runs it now (spec 29b): your session, a copy of it, or a fresh agent - and where it stands */
29
29
  runner?: JamRunner
30
+ /** the occurrence counters a notice's click compares (spec 28 A4.6 #9, #30): how many times it entered review or
31
+ * failed, and its batch's failures. Absent reads 0 */
32
+ att?: number
33
+ fails?: number
30
34
  }
31
- export interface JamRunner { kind: 'session' | 'fork' | 'fresh'; agent: string; state?: 'offered' | 'claimed' | 'stalled' | 'stopping' | 'waiting'; why?: string; batch: string; gen?: number }
35
+ /** `stalls`: how many times its claim went quiet (A4.6 #9; absent reads 0) */
36
+ export interface JamRunner { kind: 'session' | 'fork' | 'fresh'; agent: string; state?: 'offered' | 'claimed' | 'stalled' | 'stopping' | 'waiting'; why?: string; batch: string; gen?: number; stalls?: number }
32
37
  /** A coding-agent session connected to this repo (spec 29b): the selected one takes the work while a Jam session runs. */
33
38
  export interface JamSession { id: string; agent: 'claude' | 'codex' | 'cursor'; busy: boolean; selected: boolean; since: number; mode?: string }
34
39
  /** What Jam does on this machine: the config with the start sheet's switches over it. */
@@ -397,8 +397,8 @@ export function RecordDetail({ card, agent, more, onMore, onMoreOpen, onGood, on
397
397
  {failed && <div className="rule" />}
398
398
  {failed && (
399
399
  <div className="actions">
400
- <button className="jm-btn primary" onClick={onRetry}>Retry</button>
401
- <button className="jm-btn ghost" onClick={onDrop}>Drop</button>
400
+ <button className="jm-btn primary" data-jam-run-act="retry" onClick={onRetry}>Retry</button>
401
+ <button className="jm-btn ghost" data-jam-run-act="drop" onClick={onDrop}>Drop</button>
402
402
  </div>
403
403
  )}
404
404
  {review && <div className="rule" />}
@@ -1,10 +1,12 @@
1
1
  /**
2
2
  * Where Jam's surfaces stand in the shell (spec 27): the one focus panel (a capture's detail, a
3
- * review, a wrap-up), the lane's selection and its keyboard (`Q`), the review's picture view.
3
+ * review, a wrap-up, a thread), the lane's selection and its keyboard (`Q`), the review's picture view.
4
4
  */
5
5
  import { create } from 'zustand'
6
6
 
7
- export type Panel = { kind: 'capture' | 'review' | 'wrapup'; id: string } | null
7
+ /** The focus panel. `thread` (spec 28 A4.6 #30, r1 #3): a thread no frame on its board can show - frameless, its
8
+ * frame gone, resolved - opened where it can be read and answered; `id` is the thread's, on `board`. */
9
+ export type Panel = { kind: 'capture' | 'review' | 'wrapup'; id: string } | { kind: 'thread'; id: string; board: string } | null
8
10
 
9
11
  interface JamUi {
10
12
  panel: Panel
@@ -36,13 +38,22 @@ interface JamUi {
36
38
  setTab(i: number): void
37
39
  setMoreOpen(on: boolean): void
38
40
  follow(): void
41
+ /** a card's status icon asked to open its popover once (A4.6 #30): the first `TagStatus` drawing that card takes it */
42
+ statusFor: { card: string; n: number } | null
43
+ askStatus(card: string | null): void
44
+ /** the status icon of the request `n` opened: it is taken */
45
+ tookStatus(n: number): void
39
46
  }
40
47
 
48
+ let asked = 0
41
49
  export const useJamUi = create<JamUi>((set, get) => ({
42
- panel: null, selected: null, laneKeys: false, view: 'both', tab: 0, moreOpen: false, followEnd: 0, sheet: null, doneOpen: false,
50
+ panel: null, selected: null, laneKeys: false, view: 'both', tab: 0, moreOpen: false, followEnd: 0, sheet: null, doneOpen: false, statusFor: null,
51
+ askStatus(card) { set({ statusFor: card ? { card, n: ++asked } : null }) },
52
+ tookStatus(n) { if (get().statusFor?.n === n) set({ statusFor: null }) },
43
53
  setSheet(s) { set({ sheet: s }) },
44
54
  // the next card opens on Both, its first frame
45
- open(panel) { set({ panel, selected: panel?.id ?? get().selected, view: 'both', tab: 0, moreOpen: false }) },
55
+ // a thread panel names a thread, never a tile: the lane's selection stays
56
+ open(panel) { set({ panel, selected: panel && panel.kind !== 'thread' ? panel.id : get().selected, view: 'both', tab: 0, moreOpen: false }) },
46
57
  close() { set({ panel: null, moreOpen: false }) },
47
58
  setLaneKeys(on) { set({ laneKeys: on }) },
48
59
  // folding: a done tile that was selected hands its selection to the group
@@ -76,6 +87,10 @@ export function letGoOfTile() {
76
87
  useJamUi.setState({ panel: null, moreOpen: false, selected: null, laneKeys: false })
77
88
  }
78
89
 
90
+ /** What JamSurface lends the helpers that open things (jam-keys.ts): a tile's menu opened at the tile, as a right-click
91
+ * opens it (spec 28 A4.6 #30) - false when the tile is not drawn. */
92
+ export const jamSurface = { tileMenu: (_id: string): boolean => false }
93
+
79
94
  if (typeof window !== 'undefined' && (import.meta as any).env?.DEV) (window as any).__mvJamUi = useJamUi
80
95
 
81
96
  // ---- the Done fold (0.26.1): two or more done tiles fold into one, at the lane's left end ------------------
@@ -11,6 +11,7 @@ import { useEffect, useId, useLayoutEffect, useRef, useState, type ReactNode } f
11
11
  import { Tip } from './Tip.tsx'
12
12
  import { cardForEvent, useJamQueue, type JamCardState } from './jam-queue.ts'
13
13
  import { statusLines } from './jam-lines.ts'
14
+ import { useJamUi } from './jam-state.ts'
14
15
 
15
16
  const GRAY = 'var(--glass-ink-3)'
16
17
  const RED = '#e5484d' // board-icons.tsx RED - errors and failures only
@@ -71,6 +72,9 @@ export function TagStatus({ board, eventId, harness }: { board?: string; eventId
71
72
  return () => window.removeEventListener('pointerdown', away, true)
72
73
  }, [open])
73
74
  useEffect(() => { if (!card) setOpen(false) }, [card])
75
+ // asked to open once (a notice's click, A4.6 #30): this card's icon, wherever it is drawn first - its run's controls on the page
76
+ const asked = useJamUi((s) => (card && s.statusFor?.card === card.id ? s.statusFor.n : 0))
77
+ useEffect(() => { if (asked) { setOpen(true); useJamUi.getState().tookStatus(asked) } }, [asked])
74
78
  // the open detail stays on screen: it sits under the icon and slides left at the viewport's edge
75
79
  const popRef = useRef<HTMLSpanElement>(null)
76
80
  useLayoutEffect(() => {
@@ -0,0 +1,134 @@
1
+ /**
2
+ * Live pictures (spec 28 A4.6 #31-#38): in the Mac app, a capture's picture of the play stage is the owner's screen as
3
+ * they see it - an open menu, typed text, the pins on it - in place of the server's render. One logical picture per shot
4
+ * (#33): the live one when the shot is eligible and it lands, else the render, as without the app (jam-capture.ts
5
+ * `shoot`). Everywhere else - Chrome, a published canvas, an app without `capture` - nothing here runs.
6
+ *
7
+ * Eligible (#34), decided synchronously at the trigger, never cropped to fit: the app offers `capture`; the shot's frame
8
+ * is the one playing; the stage document has shown it for `STAGE_SETTLE_MS` (its `__mvStage` record, past a slide's
9
+ * tempo); the stage's whole rect is on screen below the scroll edge (`onScreen`, unchanged), at least `RING` px inside
10
+ * the view (the Jam ring), a 3 x 3 grid of `elementFromPoint` over it finds only the stage - its frame and its own
11
+ * pins and cards - and no floating layer of the shell's touches it by its box (the live caption and tips take no
12
+ * pointer, so hit-testing alone never sees them): never a lane tile, a panel, the notes card, the caption, a toast or
13
+ * a menu. So fill and doc presets, edge to edge, take the render; a device preset or a slide fitted to the window
14
+ * takes a live one.
15
+ *
16
+ * The ask binds what it was decided for - the frame, the theme, the rect, the view's size, the stage's `boot` and
17
+ * `seq` - and the answer is checked against all of it again (#35): a reload, A -> B -> A, a resize or an overlay
18
+ * opened meanwhile drops the bytes. Then the upload (`POST jam/picture/live`, the raw PNG), all under the caller's one
19
+ * deadline.
20
+ */
21
+ import { APP } from './marver-app.ts'
22
+ import { onScreen } from './inset.ts'
23
+ import { useStore } from './store.ts'
24
+ import { api } from './api.ts'
25
+ import type { StageRecord } from '../stage/main.tsx'
26
+
27
+ /** The stage has shown the frame this long: past the slide tempo (350 ms), so a transition is never pictured. */
28
+ export const STAGE_SETTLE_MS = 1000
29
+ /** The capture call and the upload together, at most; then the render (#36). */
30
+ export const LIVE_PICTURE_MS = 5000
31
+ /** The Jam ring's width at the view's edge (styles.css `.jm-edge`): the stage lies inside it. */
32
+ const RING = 6
33
+
34
+ const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
35
+
36
+ /** What a live picture was decided for: the answer must find all of it as it was. */
37
+ export interface LiveAsk {
38
+ frame: string
39
+ theme: string
40
+ /** the stage in view CSS px */
41
+ rect: { x: number; y: number; width: number; height: number }
42
+ view: { w: number; h: number }
43
+ boot: string
44
+ seq: number
45
+ }
46
+
47
+ const stageRecord = (stage: Element): StageRecord | null => {
48
+ try {
49
+ const r = (stage.querySelector('iframe')?.contentWindow as { __mvStage?: StageRecord } | null)?.__mvStage
50
+ return r && typeof r.boot === 'string' && typeof r.seq === 'number' ? r : null
51
+ } catch { return null }
52
+ }
53
+
54
+ /** Only the stage under a 3 x 3 grid over it: its frame, its own pins and cards. */
55
+ function clear(stage: Element, r: DOMRect): boolean {
56
+ for (const fy of [1 / 6, 1 / 2, 5 / 6]) for (const fx of [1 / 6, 1 / 2, 5 / 6]) {
57
+ const el = document.elementFromPoint(r.left + r.width * fx, r.top + r.height * fy)
58
+ if (!el || !stage.contains(el)) return false
59
+ }
60
+ return true
61
+ }
62
+
63
+ /** The shell's floating layers, by their visible boxes: the caption, the notes card and the mic question, the lane's
64
+ * tiles (never its full-width row), toasts, tips, menus, the focus panel, Jam's sheets. */
65
+ const LAYERS = '.jm-caption, .jm-over, .jm-lane-in > *, .sh-toasts > *, .sh-tip, .sh-menu, .jm-focus > *, .jm-sheet-at > *'
66
+
67
+ /** Does any of them, outside the stage, touch its rect? By box, not by hit-testing: the caption and a tip take no
68
+ * pointer, so the grid looks through them, and a band along an edge falls between its points - yet the readback
69
+ * holds whatever is drawn there. */
70
+ function covered(stage: Element, r: DOMRect): boolean {
71
+ for (const el of document.querySelectorAll(LAYERS)) {
72
+ if (stage.contains(el)) continue
73
+ const b = el.getBoundingClientRect()
74
+ if (b.width > 0 && b.height > 0 && b.left < r.right && r.left < b.right && b.top < r.bottom && r.top < b.bottom) return true
75
+ }
76
+ return false
77
+ }
78
+
79
+ const near = (a: number, b: number) => Math.abs(a - b) < 0.01
80
+
81
+ /** The ask for a live picture of `frame` now, or null: the shot takes the server's render (#34). */
82
+ export function liveAsk(frame: string): LiveAsk | null {
83
+ if (typeof APP?.capture !== 'function') return null
84
+ const play = useStore.getState().play
85
+ if (!play || play.at !== frame) return null
86
+ const stage = document.querySelector('.sh-play-stage')
87
+ const dev = stage?.querySelector('.dev')
88
+ if (!stage || !dev) return null
89
+ const rec = stageRecord(stage)
90
+ if (!rec || rec.at !== frame || Date.now() - rec.t < STAGE_SETTLE_MS) return null
91
+ const r = dev.getBoundingClientRect()
92
+ // its whole rect on screen, below the strip and its scroll edge: none of it cut
93
+ const on = onScreen(r)
94
+ if (!on || !near(on.left, r.left) || !near(on.top, r.top) || !near(on.right, r.right) || !near(on.bottom, r.bottom)) return null
95
+ if (r.left < RING || r.top < RING || r.right > innerWidth - RING || r.bottom > innerHeight - RING) return null
96
+ if (!clear(stage, r) || covered(stage, r)) return null
97
+ return { frame, theme: play.theme, rect: { x: r.left, y: r.top, width: r.width, height: r.height }, view: { w: innerWidth, h: innerHeight }, boot: rec.boot, seq: rec.seq }
98
+ }
99
+
100
+ /** Is everything the ask was decided for still so? The same frame, theme, rect and view, the same stage document and
101
+ * showing, and the grid clear again (#35). */
102
+ export function stillHolds(a: LiveAsk): boolean {
103
+ const b = liveAsk(a.frame)
104
+ return !!b && b.theme === a.theme && b.boot === a.boot && b.seq === a.seq && b.view.w === a.view.w && b.view.h === a.view.h
105
+ && near(b.rect.x, a.rect.x) && near(b.rect.y, a.rect.y) && near(b.rect.width, a.rect.width) && near(b.rect.height, a.rect.height)
106
+ }
107
+
108
+ /** `p`, or null once `signal` aborts (a capture call cannot be cancelled: its late answer is dropped). */
109
+ const until = <T>(p: Promise<T>, signal: AbortSignal): Promise<T | null> => new Promise((done) => {
110
+ if (signal.aborted) return done(null)
111
+ signal.addEventListener('abort', () => done(null), { once: true })
112
+ p.then(done, () => done(null))
113
+ })
114
+
115
+ /**
116
+ * The live picture for a shot of `capture`: the app's readback of the stage, checked again against the ask, then
117
+ * uploaded - its picture id, or null and the shot takes the render. `open()`: the capture is still unsealed. Every step
118
+ * stops at `signal` (the caller's one deadline over the call and the upload).
119
+ */
120
+ export async function takeLive(a: LiveAsk, capture: string, open: () => boolean, signal: AbortSignal): Promise<string | null> {
121
+ try {
122
+ const app = APP
123
+ if (!app?.capture) return null
124
+ const answer = await until(app.capture({ rect: a.rect }), signal)
125
+ if (!answer || !answer.ok || !(answer.png instanceof Uint8Array) || !answer.png.length) return null
126
+ if (signal.aborted || !open() || !stillHolds(a)) return null
127
+ const r = await api(`jam/picture/live?capture=${encodeURIComponent(capture)}&frame=${encodeURIComponent(a.frame)}`, {
128
+ method: 'POST', signal, headers: { 'content-type': 'image/png', 'x-mv-c': csrf() }, body: answer.png as Uint8Array<ArrayBuffer>,
129
+ })
130
+ if (!r.ok || signal.aborted) return null
131
+ const id = ((await r.json()) as { id?: unknown })?.id
132
+ return typeof id === 'string' && /^p-[0-9a-f]{16}$/.test(id) && !signal.aborted ? id : null
133
+ } catch { return null }
134
+ }