@marver-design/marver 0.27.0 → 0.27.2

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 (82) hide show
  1. package/CHANGELOG.md +94 -0
  2. package/README.md +5 -2
  3. package/dist/{anchor-check-ChdDqL5z.mjs → anchor-check-gkxkPAIv.mjs} +1 -1
  4. package/dist/{board-tree-DRioF94d.mjs → board-tree-BXR8dw4b.mjs} +3 -1
  5. package/dist/{boards-CGg6piKF.mjs → boards-BHKP5yhI.mjs} +1 -1
  6. package/dist/{boards-DlTcpF47.mjs → boards-BqUqKNW8.mjs} +4 -4
  7. package/dist/{build-DZnFysGU.mjs → build-VgNg4rr8.mjs} +7 -22
  8. package/dist/cli.mjs +32 -18
  9. package/dist/{collab-Dxg2trOK.mjs → collab-BEAcXrBb.mjs} +1 -1
  10. package/dist/{comments-DxOkCSNE.mjs → comments-YEU1Zhv9.mjs} +4 -4
  11. package/dist/{context-HQ4Giw58.mjs → context-Ccjrhr1J.mjs} +3 -3
  12. package/dist/{daemon-BSA0lV8d.mjs → daemon-Dc9AH0M3.mjs} +4 -4
  13. package/dist/{dev-eQJhWsqg.mjs → dev-ri6nAlRp.mjs} +11 -11
  14. package/dist/{init-COD0x48i.mjs → init-W0nxR1OY.mjs} +3 -3
  15. package/dist/{link-DDXZVGtv.mjs → link-CdTgn94Y.mjs} +4 -4
  16. package/dist/{ls-D7O1G505.mjs → ls-BZ5TAtd5.mjs} +1 -1
  17. package/dist/{manifest-Nl3KSVOk.mjs → manifest-aFyDmL8C.mjs} +2 -2
  18. package/dist/{marks-CWM3WJjc.mjs → marks-BF9pNEgH.mjs} +2 -2
  19. package/dist/{marks-CKgzucHZ.mjs → marks-CnCCfAbD.mjs} +3 -3
  20. package/dist/{marver-id-gate-BjF6v4bT.mjs → marver-id-gate-D-R0hSt_.mjs} +1 -1
  21. package/dist/perf-DkAUFT6W.mjs +1319 -0
  22. package/dist/perf-jam-BaH3Lg0m.mjs +635 -0
  23. package/dist/{plugin-C-E7omsh.mjs → plugin-B8UghYuF.mjs} +2592 -112
  24. package/dist/{poster-Bx83ZYVK.mjs → poster-BNgafWMK.mjs} +1 -1
  25. package/dist/{profile-Bh5Y5zpW.mjs → profile-jIS6BcAs.mjs} +1 -1
  26. package/dist/{publish-bakes-aljgm45S.mjs → publish-bakes-38Nja78p.mjs} +3 -3
  27. package/dist/{recover-t9Pno3u9.mjs → recover-B8AiI29B.mjs} +2 -2
  28. package/dist/{serve-C8rVheYk.mjs → serve-Dp3nHstu.mjs} +3 -3
  29. package/dist/{share-W5H3BNvP.mjs → share-Ce4tP7ji.mjs} +1 -1
  30. package/dist/{shot-DoHLl6ig.mjs → shot-CMQgMVZm.mjs} +1 -1
  31. package/dist/{shot-LFhC-WYD.mjs → shot-Ch24tiMO.mjs} +30 -5
  32. package/dist/{slots-DCDo3N0x.mjs → slots-CFNnegCc.mjs} +8 -1
  33. package/dist/{sync-BQVlHZpx.mjs → sync-CQdGARJ9.mjs} +1 -1
  34. package/dist/{work-BroFwnup.mjs → work-Bxz-ObF3.mjs} +3 -3
  35. package/dist/{work-Bp1p39kq.mjs → work-CNhFF9pU.mjs} +1 -1
  36. package/docs/jam-session.md +2 -1
  37. package/docs/performance.md +197 -35
  38. package/package.json +1 -1
  39. package/src/client/content/video.tsx +10 -2
  40. package/src/client/shell/App.tsx +10 -3
  41. package/src/client/shell/Comments.tsx +5 -3
  42. package/src/client/shell/ContextMenu.tsx +5 -3
  43. package/src/client/shell/LockedApp.tsx +3 -0
  44. package/src/client/shell/Play.tsx +4 -2
  45. package/src/client/shell/Tip.tsx +3 -1
  46. package/src/client/shell/api.ts +47 -20
  47. package/src/client/shell/app-bridge.ts +254 -0
  48. package/src/client/shell/app-perf.ts +92 -0
  49. package/src/client/shell/canvas/Canvas.tsx +115 -22
  50. package/src/client/shell/canvas/FrameNode.tsx +10 -6
  51. package/src/client/shell/canvas/admission.ts +23 -8
  52. package/src/client/shell/canvas/ctl.ts +6 -0
  53. package/src/client/shell/canvas/sleep.ts +57 -17
  54. package/src/client/shell/canvas/updates.ts +2 -1
  55. package/src/client/shell/inset.ts +44 -0
  56. package/src/client/shell/jam-capture.ts +19 -14
  57. package/src/client/shell/jam-keys.ts +8 -3
  58. package/src/client/shell/jam-panel.tsx +6 -3
  59. package/src/client/shell/jam-voice.ts +48 -10
  60. package/src/client/shell/main.tsx +14 -1
  61. package/src/client/shell/marks-ui.tsx +5 -3
  62. package/src/client/shell/marver-app.ts +21 -0
  63. package/src/client/shell/perf-run-probe.ts +34 -0
  64. package/src/client/shell/perf-run.ts +70 -0
  65. package/src/client/shell/perf.ts +11 -0
  66. package/src/client/shell/recorder.ts +45 -3
  67. package/src/client/shell/store.ts +52 -24
  68. package/src/client/shell/styles.css +47 -15
  69. package/src/client/shell/unsaved.ts +81 -0
  70. package/src/client/shell/whiteout-probes.ts +141 -0
  71. package/src/shared/app-api.ts +205 -0
  72. package/src/shared/app-perf.ts +308 -0
  73. package/src/shared/logo-sniff.ts +86 -0
  74. package/src/shared/machine.ts +132 -0
  75. package/src/shared/perf-run.ts +177 -0
  76. package/templates/AGENTS-embedded.md +3 -0
  77. package/templates/AGENTS-studio.md +3 -0
  78. package/templates/instructions/boards.md +3 -1
  79. package/dist/bake-DM_uWgAA.mjs +0 -786
  80. package/dist/perf-BWzQwZqj.mjs +0 -369
  81. package/dist/perf-BoDSkbEb.mjs +0 -429
  82. package/dist/perf-jam-D55U3FZK.mjs +0 -242
@@ -16,6 +16,8 @@ import { admissionIdle, onAdmissionIdle } from './canvas/admission.ts'
16
16
  import { canvasCtl } from './canvas/ctl.ts'
17
17
  import { bootOf, iframeOf } from './canvas/frame-registry.ts'
18
18
  import { adopt, bound, fitWithin, KEEPALIVE_BYTES, LOAD_MAX_MS, newId, Outbox, outcomeOf, QUIET_MS, SEND_MS, stackLines, type Kind, type Outcome, type PerfRecord, type Track } from './recorder-core.ts'
19
+ import { PERF_RUN, type PerfRunStatus } from './perf-run.ts'
20
+ import { displayHz } from './app-perf.ts'
19
21
 
20
22
  /** This document, in every record (and, in the app, in its hello: the app's records about this tab carry it). */
21
23
  export const PAGE_ID = newId()
@@ -40,6 +42,8 @@ interface Load {
40
42
  /** node key -> `${outcome}:${boot}` its last frame record said */
41
43
  reported: Map<string, string>
42
44
  done?: 'settled' | 'cut'
45
+ /** why it was cut, request or load (a headless perf run's status says it) */
46
+ cutReason?: string
43
47
  quietTimer?: ReturnType<typeof setTimeout>; timeout?: ReturnType<typeof setTimeout>; retry?: ReturnType<typeof setTimeout>
44
48
  }
45
49
 
@@ -66,6 +70,14 @@ const open = new Map<string, PerfRecord>()
66
70
  let inFlight: PerfRecord[] = []
67
71
  let sendTimer: ReturnType<typeof setTimeout> | undefined
68
72
  let sending = false
73
+ /** sends whose records never landed, since the page loaded (a headless perf run's `flush()` answers with it) */
74
+ let failedSends = 0
75
+ /** records lost on this page's side since it loaded - the queue's bound, a send that never landed - however many
76
+ * `dropped` records said so: the count each one carries starts over, this one never does (`flush()`) */
77
+ let lostEver = 0
78
+ /** The warm-up load of a headless perf run (spec 28 A3.8 #17): the recorder runs - the driver reads `settled` from
79
+ * it - and posts nothing. */
80
+ const WARM = PERF_RUN?.warm === true
69
81
  /** what only the canvas knows (Canvas.tsx attaches it): is a pan, zoom or layout animation running; frames asleep */
70
82
  let motion = { camera: false, preset: false }
71
83
  let sleeping = (): number => 0
@@ -166,6 +178,7 @@ function cutRequest(id: string, reason: RequestCut | 'timeout' | 'hidden'): void
166
178
  clearTimeout(L.timeout)
167
179
  L.timeout = undefined
168
180
  L.done = 'cut'
181
+ L.cutReason = reason
169
182
  rec('cut', id, { reason, request: id, ms: Math.round(performance.now() - L.t0) })
170
183
  // its fetch may still answer and mount it
171
184
  if (reason === 'timeout' || reason === 'hidden') {
@@ -363,6 +376,7 @@ function cut(L: Load, reason: 'switch' | 'reload' | 'hidden' | 'timeout'): void
363
376
  else if (L.reported.get(n.key) !== said(n, o)) frameRecord(L, n, o)
364
377
  }
365
378
  rec('cut', L.id, { reason, ms: Math.round(performance.now() - L.t0), lastMove: rel(L, L.movedAt), frames: s.nodes.length, ready })
379
+ L.cutReason = reason
366
380
  finish(L, 'cut')
367
381
  }
368
382
 
@@ -439,6 +453,7 @@ const wait = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
439
453
  const droppedNow = (more = 0): PerfRecord[] => {
440
454
  const n = outbox.dropped + more
441
455
  outbox.dropped = 0
456
+ lostEver += n
442
457
  return n ? [env('dropped', ownerId(), { n })] : []
443
458
  }
444
459
 
@@ -449,6 +464,8 @@ async function send(): Promise<void> {
449
464
  clearTimeout(sendTimer)
450
465
  sendTimer = undefined
451
466
  if (!on || sending || !outbox.size) return
467
+ // a perf run's warm-up: what it recorded is the driver's to read, never the log's
468
+ if (WARM) { outbox.takeAll(); outbox.dropped = 0; open.clear(); return }
452
469
  sending = true
453
470
  let batch: PerfRecord[] = []
454
471
  let ok = false
@@ -466,7 +483,7 @@ async function send(): Promise<void> {
466
483
  } catch { /* the network: again */ }
467
484
  }
468
485
  } catch { /* never in the way: what it held is counted below */ }
469
- if (!ok) outbox.dropped += batch.filter((r) => r.kind !== 'dropped').length + batch.filter((r) => r.kind === 'dropped').reduce((n, r) => n + (r.n as number), 0)
486
+ if (!ok) { failedSends++; outbox.dropped += batch.filter((r) => r.kind !== 'dropped').length + batch.filter((r) => r.kind === 'dropped').reduce((n, r) => n + (r.n as number), 0) }
470
487
  inFlight = []
471
488
  sending = false
472
489
  armSend()
@@ -481,7 +498,7 @@ function leave(): void {
481
498
  clearTimeout(sendTimer)
482
499
  sendTimer = undefined
483
500
  sealCaptures()
484
- if (capturesPending()) return
501
+ if (capturesPending() || WARM) return
485
502
  // a send on its way may not outlive the page: its records again (the report drops a duplicate by its seq)
486
503
  const all = [...inFlight, ...outbox.takeAll()]
487
504
  if (!all.length) return
@@ -490,6 +507,31 @@ function leave(): void {
490
507
  try { void post([...fit, ...droppedNow(lost)], true).catch(() => {}) } catch { /* going anyway */ }
491
508
  }
492
509
 
510
+ // ---- a headless perf run (spec 28 A3.8 #17) ----------------------------------------------------------------------
511
+
512
+ /** The load the page has now - the newest request still waiting, else the one that owns the geometry - and where it
513
+ * is: requested, committed, settled or cut (with why). `sinceNav`, a boot load's request on the page's clock. */
514
+ export function currentLoad(): PerfRunStatus['load'] {
515
+ const L = [...pending.values()].at(-1) ?? owner
516
+ if (!L) return null
517
+ const state = L.done ?? (L.committedAt !== undefined ? 'committed' : 'requested')
518
+ return { id: L.id, state, ...(L.cutReason ? { reason: L.cutReason } : {}), ...(L.cause === 'boot' ? { sinceNav: Math.round(L.t0) } : {}) }
519
+ }
520
+
521
+ /** Everything recorded so far sent now, until nothing waits and nothing is on its way (15 s at most): whether every
522
+ * batch this page ever sent landed, and no record was ever lost to the queue's bound. The driver awaits it before it
523
+ * ends the page. A warm-up posts nothing: true. */
524
+ export async function flush(): Promise<boolean> {
525
+ if (!on) return false
526
+ if (WARM) return true
527
+ const by = performance.now() + 15_000
528
+ while ((sending || outbox.size) && performance.now() < by) {
529
+ if (!sending) await send()
530
+ else await wait(25)
531
+ }
532
+ return !sending && !outbox.size && !outbox.dropped && failedSends === 0 && lostEver === 0
533
+ }
534
+
493
535
  // ---- for tests --------------------------------------------------------------------------------------------------
494
536
 
495
537
  function state() {
@@ -556,7 +598,7 @@ export const recorder = {
556
598
  rec('visible', L.id, { nodes: L.cohort.size, ms: Math.round(performance.now() - L.t0) })
557
599
  }),
558
600
  /** A pan, zoom or layout animation ended (perf.ts). */
559
- gesture: guard((g: Gesture) => { rec('gesture', ownerId(), g); settleSoon() }),
601
+ gesture: guard((g: Gesture) => { rec('gesture', ownerId(), { ...g, hz: displayHz() ?? undefined }); settleSoon() }),
560
602
  /** An error the shell saw: its own (window, ShellBoundary) or the play stage's. A shell error goes out at once. */
561
603
  error: guard((e: { source: 'shell' | 'stage'; message: unknown; stack?: unknown; component?: string }) => {
562
604
  logError(e)
@@ -5,6 +5,7 @@ import { clearNoteHeights, noteHeight, noteReserve, notesCramped, scopeNotes, se
5
5
  import { stableNodeKey } from './keys.ts'
6
6
  import { canvasCtl } from './canvas/ctl.ts'
7
7
  import { api, beforeResume, canvasStopped, holdsReload, lostInResume, mvFetch, noteUnsaved, onLinkNotice, savedInResume, scoped, STOPPED_WAY, withWs } from './api.ts'
8
+ import { unsavedWhen, workChanged } from './unsaved.ts'
8
9
  // @ts-expect-error virtual module provided by the plugin
9
10
  import shConfig from 'virtual:sh-config'
10
11
  // @ts-expect-error virtual module: null in dev; a published build inlines manifest+boards
@@ -127,7 +128,7 @@ export interface JamNote {
127
128
  }
128
129
  export interface Toast { id: number; text: string; jam?: JamNote }
129
130
 
130
- export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean; setup?: boolean; projectName?: string; branding?: boolean; jam?: { chime: boolean; capture: 'confirm' | 'at-once'; names?: boolean } | null; workspace?: string } = shConfig
131
+ export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean; setup?: boolean; projectName?: string; branding?: boolean; jam?: { chime: boolean; capture: 'confirm' | 'at-once'; names?: boolean } | null; workspace?: string; version?: string } = shConfig
131
132
 
132
133
  /** Invariant: `branding: false` strips every Marver mention - new chrome included. */
133
134
  export const BRANDING = CONFIG.branding !== false
@@ -391,22 +392,31 @@ const measures = (frameId: string) => { const m = preparing ? preparing.measurin
391
392
 
392
393
  // settled heights that differ from the committed ones, written back in batches (dev only). One
393
394
  // write in flight at a time; a height that changes while its write is in flight queues behind it,
394
- // so the LAST settled height is the one the file ends with
395
+ // so the LAST settled height is the one the file ends with. A write the server did not take (no
396
+ // answer, or an error status) goes back in the queue - behind any newer height for the same key,
397
+ // which wins - so the heights stay unsaved until they reach the file, and is sent again after a
398
+ // wait that doubles with each failure in a row (1.5 s to 24 s)
395
399
  const pendingHeights = new Map<string, number>()
396
400
  const inflightHeights = new Map<string, number>()
397
401
  let heightsTimer: ReturnType<typeof setTimeout> | undefined
398
- let flushing = false
402
+ /** The write in flight, until it has answered and its heights are saved or queued again (the resume awaits it). */
403
+ let flushing: Promise<void> | null = null
404
+ let heightsFailed = 0
405
+ const HEIGHTS_MS = 1500
399
406
  const persistHeight = (key: string, h: number) => {
400
407
  if (DATA) return
401
- if (!inflightHeights.has(key) && savedHeights.get(key) === h) { pendingHeights.delete(key); return }
408
+ if (!inflightHeights.has(key) && savedHeights.get(key) === h) { if (pendingHeights.delete(key)) workChanged(); return }
409
+ if (!pendingHeights.size) workChanged() // heights not written yet: unsaved (unsaved.ts)
402
410
  pendingHeights.set(key, h)
403
- if (!flushing) heightsTimer ??= setTimeout(flushHeights, 1500) // a throttle, not a debounce: a board settling in waves still writes
411
+ if (!flushing) heightsTimer ??= setTimeout(flushHeights, HEIGHTS_MS) // a throttle, not a debounce: a board settling in waves still writes
404
412
  }
405
- async function flushHeights() {
413
+ async function flushHeights(): Promise<void> {
406
414
  heightsTimer = undefined
407
- if (flushing || !pendingHeights.size) return
415
+ if (flushing) return flushing
416
+ if (!pendingHeights.size) return
408
417
  if (canvasStopped()) return // held until the canvas answers again (A1.11): the resume flushes them
409
- flushing = true
418
+ let done = () => {}
419
+ flushing = new Promise<void>((r) => { done = r })
410
420
  const batch = Object.fromEntries([...pendingHeights].slice(0, 500))
411
421
  for (const [k, v] of Object.entries(batch)) { pendingHeights.delete(k); inflightHeights.set(k, v) }
412
422
  let answered = false
@@ -419,13 +429,26 @@ async function flushHeights() {
419
429
  }
420
430
  } catch { /* lost: below */ }
421
431
  // no answer = the write may or may not have landed: what the file holds is unknown, so nothing is
422
- // deduplicated against it - a correction queued meanwhile still goes, the next report still writes
423
- if (!answered) for (const k of Object.keys(batch)) savedHeights.delete(k)
432
+ // deduplicated against it - a correction queued meanwhile still goes, the next report still writes.
433
+ // Each of its heights is owed again, unless a newer one for that key is already queued
434
+ if (!answered) for (const [k, v] of Object.entries(batch)) { savedHeights.delete(k); if (!pendingHeights.has(k)) pendingHeights.set(k, v) }
424
435
  for (const k of Object.keys(batch)) inflightHeights.delete(k)
425
436
  // a height that settled while the write was in flight: still owed only if it differs from what landed
426
437
  for (const [k, v] of pendingHeights) if (savedHeights.get(k) === v) pendingHeights.delete(k)
427
- flushing = false
428
- if (pendingHeights.size) heightsTimer ??= setTimeout(flushHeights, 1500)
438
+ heightsFailed = answered ? 0 : Math.min(heightsFailed + 1, 5)
439
+ flushing = null
440
+ workChanged()
441
+ if (pendingHeights.size) heightsTimer ??= setTimeout(flushHeights, HEIGHTS_MS * 2 ** Math.max(0, heightsFailed - 1))
442
+ done()
443
+ }
444
+ /** Every height this page measured is in the file: none queued, none in flight. */
445
+ const heightsSaved = () => !pendingHeights.size && !inflightHeights.size
446
+ /** The resume's turn (A1.11): the write in flight answers first, then what is queued goes now - unless it is waiting
447
+ * out a failure's backoff, which its own timer sends. True once every height is in the file. */
448
+ async function settleHeights(): Promise<boolean> {
449
+ await flushing
450
+ if (pendingHeights.size && !(heightsFailed && heightsTimer)) { clearTimeout(heightsTimer); await flushHeights() }
451
+ return heightsSaved()
429
452
  }
430
453
 
431
454
  const hasKnownHeight = (frameId: string, w: number) => measures(frameId) && (measuredHeights.has(`${frameId}@${w}`) || savedNow().has(`${frameId}@${w}`))
@@ -2120,7 +2143,7 @@ export const useStore = create<State>((set, get) => {
2120
2143
  // renamed/deleted externally - drop the write, don't recreate it or loop
2121
2144
  set({ dirty: false })
2122
2145
  get().toast(BOARD_GONE)
2123
- lostInResume('gone') // a resume's save: the page after its reload says this, not "saved"
2146
+ lostInResume('gone') // a save while a resume is owed: the page after its reload says this, not "saved"
2124
2147
  return true
2125
2148
  }
2126
2149
  const reloaded = await get().boot() // hash advances only when the authoritative reload commits
@@ -2131,7 +2154,7 @@ export const useStore = create<State>((set, get) => {
2131
2154
  const { sha256 } = await res.json()
2132
2155
  // an edit that landed after this save started keeps dirty set for the next save
2133
2156
  set({ boardHash: sha256, ...(editRev === rev ? { dirty: false } : {}) })
2134
- savedInResume() // a resume's save: the page after its reload says the edits were saved
2157
+ savedInResume() // a save while a resume is owed (the resume's, or this autosave): the page after its reload says the edits were saved
2135
2158
  return true
2136
2159
  }
2137
2160
  return false
@@ -2157,11 +2180,14 @@ beforeResume(async () => {
2157
2180
  const s = () => useStore.getState()
2158
2181
  if (s().gesture) return false
2159
2182
  for (let i = 0; i < 5 && s().dirty; i++) if (!(await s().save())) break
2160
- await flushHeights()
2161
- return !s().dirty && !s().gesture
2183
+ // heights a write did not land (a 500, no answer) hold the reload too: queued again, they go on their timer while
2184
+ // the page works as live, and it reloads the second after they reach the file
2185
+ const heights = await settleHeights()
2186
+ return heights && !s().dirty && !s().gesture
2162
2187
  })
2163
- // and an edit made, or a drag begun, while that save was on its way holds the reload as well
2164
- holdsReload(() => { const s = useStore.getState(); return s.dirty || !!s.gesture })
2188
+ // and an edit made, a drag begun, or a height measured or sent back to the queue while that save was on its way holds
2189
+ // the reload as well
2190
+ holdsReload(() => { const s = useStore.getState(); return s.dirty || !!s.gesture || !heightsSaved() })
2165
2191
  // while stopped, the banner says "your unsaved edits are kept" from the edit that makes some
2166
2192
  useStore.subscribe((s, p) => { if ((s.dirty !== p.dirty || s.gesture !== p.gesture) && canvasStopped()) noteUnsaved() })
2167
2193
  onLinkNotice((text) => useStore.getState().toast(text))
@@ -2172,12 +2198,14 @@ export function stoppedFor(what: string): boolean {
2172
2198
  useStore.getState().toast(`${what} - ${STOPPED_WAY}`)
2173
2199
  return true
2174
2200
  }
2175
- // a stopped page holds edits only it has: leaving it (a reload by hand, a close) asks first
2176
- if (typeof window !== 'undefined') window.addEventListener('beforeunload', (e) => {
2177
- if (!canvasStopped() || !useStore.getState().dirty) return
2178
- e.preventDefault()
2179
- e.returnValue = ''
2180
- })
2201
+ // spec 28 A2.9: leaving a page that holds a board edit not on disk yet - dirty, a save in flight or one that failed -
2202
+ // or heights not written yet asks first (unsaved.ts's one beforeunload), live or stopped; the Mac app hears it too.
2203
+ // A drag is not work until it drops. A published canvas keeps its pins and sizes in the session: nothing to lose
2204
+ if (!PUBLISHED) {
2205
+ unsavedWhen('board-unsaved', () => useStore.getState().dirty)
2206
+ unsavedWhen('heights', () => !heightsSaved())
2207
+ useStore.subscribe((s, p) => { if (s.dirty !== p.dirty) workChanged() })
2208
+ }
2181
2209
 
2182
2210
  // dev-only inspection hook for tests/debugging (never installed in published builds)
2183
2211
  if (import.meta.env.DEV) (window as unknown as { __mvStore: unknown }).__mvStore = useStore
@@ -2,6 +2,9 @@
2
2
  Light board -> light glass chrome over a paper canvas; dark board -> dark glass
3
3
  chrome over a dark canvas. Frames are cards; chrome is glass. */
4
4
 
5
+ /* @tokens */
6
+ /* The token block (spec 28 A2.2, A2.9): the Mac app copies everything between these two markers into its own pages
7
+ at build time (app/scripts/tokens.mjs, rewritten onto :root), so its strip and pages wear exactly this glass. */
5
8
  .sh-app {
6
9
  --ground: #e7e9ef; --dot: #c9cbd5;
7
10
  --accent: #0088ff; --accent-ring: rgba(0, 136, 255, .2); --beam: rgba(0, 136, 255, .42); --beam-blur: 6px; --beam-bottom: -13px; --beam-h: 12px; --beam-inset: 12%; --edge-accent: rgba(0, 136, 255, .8); --inner-tint: rgba(0, 136, 255, .13); --tip-bg: #18181b; --tip-ink: #fafafa; --accent-wash: rgba(0, 136, 255, .07);
@@ -102,6 +105,17 @@
102
105
  @property --glass-accent { syntax: '<color>'; inherits: true; initial-value: #0077e6; }
103
106
  @property --glass-accent-bg { syntax: '<color>'; inherits: true; initial-value: rgba(0, 136, 255, .13); }
104
107
 
108
+ /* Reduce Transparency and Increase Contrast (spec 28 A2.9, A2.13): every glass surface opaque - its fill the solid
109
+ one, its border the node's, no blur - in both themes (the dark rule's own specificity, later in the file); and
110
+ with more contrast the dimmer inks take the full one. macOS's settings reach Chrome too. */
111
+ @media (prefers-reduced-transparency: reduce), (prefers-contrast: more) {
112
+ .sh-app, .sh-app.dark { --glass: var(--solid); --glass-brd: var(--node-brd); --blur: none; }
113
+ }
114
+ @media (prefers-contrast: more) {
115
+ .sh-app, .sh-app.dark { --glass-ink-2: var(--glass-ink); --glass-ink-3: var(--glass-ink); }
116
+ }
117
+ /* @end-tokens */
118
+
105
119
  /* interact mode: the whole shell shifts to the interactive purple - one token override,
106
120
  and every accent-derived surface (mark, sidebar actives, selection bar, beams, rings,
107
121
  handles, device chips) follows without knowing the mode exists */
@@ -150,6 +164,21 @@ button svg { pointer-events: none } /* event targets stay on the button - pan
150
164
  background-size: var(--grid-size, 20px 20px);
151
165
  background-position: var(--grid-pos, 0 0);
152
166
  opacity: var(--grid-alpha, 1) }
167
+ /* the scroll edge (0.27.2, spec 28 A2.9 v1.8 #8, A3.8 #31): under the Mac app's transparent strip only (App.tsx renders
168
+ it when inset.ts's TOP is 44). One band over the world and under the chrome (z 9; the panels are 10): opaque ground
169
+ through --mv-top, fading out over 16 px more, the dots drawn from the same three grid variables paintGrid writes on
170
+ .sh-app - so nothing of a frame shows under the tabs, and a frame panned up fades out below them while the dots run
171
+ on. The grid's alpha reaches the dots only. The world itself carries no mask (one would add a render surface to every
172
+ frame). */
173
+ .sh-edge { position: absolute; left: 0; right: 0; top: 0; height: calc(var(--mv-top, 0px) + 16px); z-index: 9; pointer-events: none;
174
+ background: var(--ground);
175
+ -webkit-mask-image: linear-gradient(#000 0 var(--mv-top, 0px), transparent calc(var(--mv-top, 0px) + 16px));
176
+ mask-image: linear-gradient(#000 0 var(--mv-top, 0px), transparent calc(var(--mv-top, 0px) + 16px)) }
177
+ .sh-edge::before { content: ''; position: absolute; inset: 0;
178
+ background-image: radial-gradient(var(--dot) 1px, transparent 1px);
179
+ background-size: var(--grid-size, 20px 20px);
180
+ background-position: var(--grid-pos, 0 0);
181
+ opacity: var(--grid-alpha, 1) }
153
182
  .sh-content { will-change: auto }
154
183
  #sh-world { position: relative; width: 1px; height: 1px }
155
184
  #sh-world.sh-gesturing .sh-live { pointer-events: none } /* law G-4 */
@@ -434,8 +463,8 @@ body.sh-space .sh-node { pointer-events: none } /* space-drag
434
463
  .sh-ibtn:hover { background: var(--glass-hover); color: var(--glass-ink) }
435
464
 
436
465
  /* floating glass panel; collapses into the fab with a scale-fade morph */
437
- .sh-panel { position: absolute; left: var(--edge); top: var(--edge); width: 236px;
438
- max-height: calc(100% - 2 * var(--edge)); z-index: 10;
466
+ .sh-panel { position: absolute; left: var(--edge); top: calc(var(--mv-top, 0px) + var(--edge)); width: 236px;
467
+ max-height: calc(100% - 2 * var(--edge) - var(--mv-top, 0px)); z-index: 10;
439
468
  border-radius: var(--r-panel); padding: 10px; display: flex; flex-direction: column;
440
469
  font-size: 13px; color: var(--glass-ink);
441
470
  transform-origin: 22px 22px; transition: transform var(--morph), opacity .2s ease }
@@ -559,7 +588,7 @@ body.sh-space .sh-node { pointer-events: none } /* space-drag
559
588
  .sh-panel .sub.dim:hover { background: none; color: var(--glass-ink-3) }
560
589
 
561
590
  /* collapsed panel: a round glass button; morphs against the panel */
562
- .sh-fab { position: absolute; left: var(--edge); top: var(--edge); z-index: 11; width: 44px; height: 44px;
591
+ .sh-fab { position: absolute; left: var(--edge); top: calc(var(--mv-top, 0px) + var(--edge)); z-index: 11; width: 44px; height: 44px;
563
592
  display: grid; place-items: center; border-radius: 999px;
564
593
  color: var(--glass-ink-2); cursor: pointer;
565
594
  transition: transform var(--morph), opacity .2s ease }
@@ -568,13 +597,13 @@ body.sh-space .sh-node { pointer-events: none } /* space-drag
568
597
 
569
598
  /* pill nav */
570
599
  /* uniform 5px inset on every side: 34px buttons + 2*5px = 44px, same as the fab */
571
- .sh-pill { position: absolute; right: var(--edge); top: var(--edge); z-index: 10; display: flex; align-items: center; gap: 1px;
600
+ .sh-pill { position: absolute; right: var(--edge); top: calc(var(--mv-top, 0px) + var(--edge)); z-index: 10; display: flex; align-items: center; gap: 1px;
572
601
  border-radius: 999px; padding: 5px;
573
602
  transform-origin: calc(100% - 22px) 22px; transition: transform var(--morph), opacity .2s ease }
574
603
  .sh-pill.closed { transform: scale(.16); opacity: 0; pointer-events: none }
575
604
  /* the pill's expand chip - the sidebar fab, mirrored top-right: same glass (shared
576
605
  surface rule above), same morph, the bar shrinking into the chip's spot */
577
- .sh-pill-fab { position: absolute; right: var(--edge); top: var(--edge); z-index: 11; width: 44px; height: 44px;
606
+ .sh-pill-fab { position: absolute; right: var(--edge); top: calc(var(--mv-top, 0px) + var(--edge)); z-index: 11; width: 44px; height: 44px;
578
607
  display: grid; place-items: center; border-radius: 999px;
579
608
  color: var(--glass-ink-2); cursor: pointer;
580
609
  transition: transform var(--morph), opacity .2s ease }
@@ -606,7 +635,7 @@ body.sh-space .sh-node { pointer-events: none } /* space-drag
606
635
  .sh-menu button span { flex: 1; text-transform: capitalize }
607
636
  /* the sidebar right-click menu keeps its labels verbatim (they match the toolbar exactly);
608
637
  it scrolls rather than overflowing the window when the folder list grows long */
609
- .sh-ctxmenu { max-height: calc(100vh - 16px); max-width: 240px; overflow-y: auto; scrollbar-width: thin }
638
+ .sh-ctxmenu { max-height: calc(100vh - 16px - var(--mv-top, 0px)); max-width: 240px; overflow-y: auto; scrollbar-width: thin }
610
639
  .sh-ctxmenu button { flex: none; max-width: 100% }
611
640
  .sh-ctxmenu button span { text-transform: none; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0 }
612
641
  .sh-menu .chk { color: var(--glass-accent) }
@@ -649,7 +678,7 @@ body.sh-space .sh-node { pointer-events: none } /* space-drag
649
678
  /* a lane tile's whole title: wraps past one line, never wider than a short paragraph */
650
679
  .sh-tip .jm-tip-title { display: block; max-width: 320px; white-space: normal; line-height: 16px }
651
680
  /* a status's tooltip: the status, then where it came from - each piece of evidence on its own line */
652
- .sh-tip .sh-tip-lines { display: flex; flex-direction: column; gap: 2px; max-width: 420px; max-height: calc(100vh - 32px); overflow: hidden; white-space: normal }
681
+ .sh-tip .sh-tip-lines { display: flex; flex-direction: column; gap: 2px; max-width: 420px; max-height: calc(100vh - 32px - var(--mv-top, 0px)); overflow: hidden; white-space: normal }
653
682
  /* read by a screen reader, never seen: what a glyph says to the eye */
654
683
  .sh-sr { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0 }
655
684
  .sh-tip .sh-tip-lines small { opacity: .62; font-size: 11px; line-height: 1.35; overflow-wrap: anywhere }
@@ -742,7 +771,7 @@ body.sh-space .sh-node { pointer-events: none } /* space-drag
742
771
 
743
772
  /* ---- Play mode: near-black stage, one centered device, auto-hiding bar.
744
773
  Fixed dark palette - the backdrop never follows the board theme, so no tokens here. */
745
- .sh-play { position: absolute; inset: 0; z-index: 30; background: #0a0a0b; display: flex;
774
+ .sh-play { position: absolute; inset: 0; z-index: 30; background: #0a0a0b; display: flex; padding-top: var(--mv-top, 0px);
746
775
  align-items: center; justify-content: center; animation: sh-play-in .28s ease-out; cursor: auto }
747
776
  @keyframes sh-play-in { from { opacity: 0 } }
748
777
  /* the device wears the frame-node card language: same theme border tokens, the same
@@ -773,7 +802,10 @@ body.sh-space .sh-node { pointer-events: none } /* space-drag
773
802
  .sh-play.fill .dev { border-radius: 0; box-shadow: none; transition: none }
774
803
  .sh-play.fill .dev::after { display: none }
775
804
 
776
- /* the two floating chrome pieces share one glass language and one idle behavior */
805
+ /* the two floating chrome pieces share one glass language and one idle behavior. Of them only .sh-play-nav is still
806
+ rendered: play's top chrome is the shared pill (Play.tsx: nav.sh-pill.sh-play-pill, .sh-pill-fab), which takes the
807
+ Mac app's inset through .sh-pill's own rule - .sh-play-bar, its menu and .sh-play-chip below are unused, left as
808
+ they were */
777
809
  .sh-play-bar, .sh-play-nav { position: absolute; display: flex; align-items: center; gap: 1px;
778
810
  padding: 4px; border-radius: 999px;
779
811
  background: rgba(18, 18, 24, .82); border: 1px solid rgba(255, 255, 255, .12);
@@ -1254,7 +1286,7 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
1254
1286
  .sh-tip .cm-meta-row b { font-weight: 600; opacity: 1; margin: 0; color: var(--tip-ink) } /* value: bold, full-bright */
1255
1287
  .sh-tip .cm-meta-row .k { margin: 0; opacity: .5; font-weight: 500; color: var(--tip-ink) } /* label: muted qualifier */
1256
1288
  /* identity modal - same glass family */
1257
- .cm-modal-wrap { position: fixed; inset: 0; z-index: 300; display: flex; align-items: center; justify-content: center;
1289
+ .cm-modal-wrap { position: fixed; inset: var(--mv-top, 0px) 0 0 0; z-index: 300; display: flex; align-items: center; justify-content: center;
1258
1290
  background: rgba(24,24,27,.45); backdrop-filter: blur(5px) }
1259
1291
  /* the auth modal is a focused surface, not a floating glass panel - near-solid so
1260
1292
  the canvas behind never bleeds through the fields */
@@ -1586,7 +1618,7 @@ body.sh-commenting .sh-sticky-body { cursor: crosshair }
1586
1618
  .jm-rename input:focus { border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-ring) }
1587
1619
 
1588
1620
  /* ---- the capture: an edge ring round the window, the chip, the caption, points ---- */
1589
- .jm-edge { position: absolute; inset: 0; pointer-events: none; z-index: 40;
1621
+ .jm-edge { position: absolute; inset: var(--mv-top, 0px) 0 0 0; pointer-events: none; z-index: 40;
1590
1622
  box-shadow: inset 0 0 0 2px var(--jm-rec), inset 0 0 0 6px var(--jm-rec-ring) }
1591
1623
  /* the capture recording NOW (round 3): the last tile of the lane, two lines like the others - a pulsing
1592
1624
  teal dot, "Capturing" and the timer over what it holds so far - then Stop. A little wider, never cut. */
@@ -1810,7 +1842,7 @@ body.sh-commenting .sh-sticky-body { cursor: crosshair }
1810
1842
  .jm-notefield .caret { display: inline-block; width: 1px; height: 15px; background: var(--accent); vertical-align: -3px; margin-left: 1px }
1811
1843
  .jm-notes .foot { display: flex; gap: 12px; justify-content: flex-end; font: 500 11px -apple-system, system-ui, sans-serif; color: var(--glass-ink-3) }
1812
1844
  /* the focus panel: top edge to just above the lane; the panel inside fills it and its middle scrolls */
1813
- .jm-focus { position: absolute; top: var(--edge); bottom: calc(var(--edge) + var(--jm-lane) + 2px); z-index: 31; display: flex }
1845
+ .jm-focus { position: absolute; top: calc(var(--mv-top, 0px) + var(--edge)); bottom: calc(var(--edge) + var(--jm-lane) + 2px); z-index: 31; display: flex }
1814
1846
  .jm-focus > .jm-panel { width: 100%; height: 100%; min-height: 0 }
1815
1847
  /* one big picture at a time: the frame tabs and a Before | After switch above it (B flips) */
1816
1848
  .jm-fbar { display: flex; align-items: center; gap: 8px; flex-wrap: wrap } /* a narrow window wraps the switch under the tabs */
@@ -1884,14 +1916,14 @@ button.jm-link { padding: 0; border: 0; background: none; text-align: left; widt
1884
1916
 
1885
1917
  /* Jam V2: while the lane shows, the sidebar stops above it and the bottom edge rises one lane - the
1886
1918
  Update pill, toasts and notices (LANE_H, jam-lane.tsx) */
1887
- .sh-app.jm-lane-on .sh-panel { max-height: calc(100% - 2 * var(--edge) - 56px); bottom: auto }
1919
+ .sh-app.jm-lane-on .sh-panel { max-height: calc(100% - 2 * var(--edge) - 56px - var(--mv-top, 0px)); bottom: auto }
1888
1920
  .sh-app.jm-lane-on .sh-update { bottom: calc(var(--edge) + 56px) }
1889
1921
  .sh-app.jm-lane-on .sh-toasts { bottom: calc(var(--edge) + 56px) }
1890
1922
  .sh-app.jm-lane-on .sh-banner { bottom: calc(var(--edge) + 56px) }
1891
1923
  /* the canvas stopped (spec 28 A1.11): on the toolbar's centre line in the gap between the sidebar and the
1892
1924
  toolbar, or just below the toolbar row - placed by the shell (App.tsx placeBanner), which measures both; above
1893
1925
  play and focus. The fallback before it measures: top centre, on the line (34px tall, the row 46px) */
1894
- .sh-app .sh-banner.sh-stopped { top: calc(var(--edge) + 6px); bottom: auto; left: 50%; right: auto; transform: translateX(-50%);
1926
+ .sh-app .sh-banner.sh-stopped { top: calc(var(--mv-top, 0px) + var(--edge) + 6px); bottom: auto; left: 50%; right: auto; transform: translateX(-50%);
1895
1927
  z-index: 40; width: max-content; max-width: none; white-space: nowrap; text-align: center; text-wrap: balance; pointer-events: auto }
1896
1928
  .sh-banner.sh-stopped code { font: 500 11.5px/14px ui-monospace, SFMono-Regular, Menlo, monospace; padding: 1px 5px; border-radius: 5px;
1897
1929
  background: color-mix(in srgb, currentColor 11%, transparent); white-space: nowrap }
@@ -2001,7 +2033,7 @@ button.jm-link { padding: 0; border: 0; background: none; text-align: left; widt
2001
2033
  .jm-panel button.row:hover { background: var(--glass-hover) }
2002
2034
  textarea.jm-field { width: 100%; resize: none; outline: none; overflow: hidden; display: block }
2003
2035
  textarea.jm-field:focus { border-color: transparent; box-shadow: 0 0 0 1px var(--accent), 0 0 0 4px var(--accent-ring) }
2004
- .jm-sheet-at { position: absolute; right: var(--edge); top: 64px; z-index: 42 }
2036
+ .jm-sheet-at { position: absolute; right: var(--edge); top: calc(var(--mv-top, 0px) + 64px); z-index: 42 }
2005
2037
  .jm-sheet .rows, .jm-wrapup .rows { margin: 0 -8px }
2006
2038
  .jm-sc-row { position: relative; cursor: default; outline: none }
2007
2039
  .jm-record-panel .jm-body { overflow: auto }
@@ -0,0 +1,81 @@
1
+ /**
2
+ * What this page holds that is not on the server yet, and what it is busy with (spec 28 A2.9, A2.14 #18): one
3
+ * registry of reasons, read by one `beforeunload` - so Chrome asks before a reload or a close loses any of them, not
4
+ * only a capture being recorded - and, in the Mac app, by the shell's `mv:busy` (app-bridge.ts), which the app's guard
5
+ * trusts before it closes, reloads or replaces the page.
6
+ *
7
+ * Beside A1's `holdsReload` (api.ts), which keeps meaning "this page may not reload itself now" and drives the
8
+ * stopped banner: the two ask much the same questions, and each keeps its own job.
9
+ *
10
+ * The reasons are the contract's (`src/shared/app-api.ts`): unsaved - `capture-recording`, `capture-unsent` (sealed,
11
+ * not taken by the server yet, memory-only ones included), `board-unsaved` (a dirty board: a save in flight or
12
+ * failed keeps it dirty), `heights`, `typing` (words typed and not sent); busy but not unsaved - `jam-session`,
13
+ * `microphone`, `agent`. A drag is not work: it becomes `board-unsaved` on drop.
14
+ *
15
+ * No imports but the contract's types: a unit test drives it without a page.
16
+ */
17
+ import { UNSAVED_WHY, WHY, type Why } from '../../shared/app-api.ts'
18
+
19
+ export type UnsavedWhy = (typeof UNSAVED_WHY)[number]
20
+ export type BusyWhy = Exclude<Why, UnsavedWhy>
21
+
22
+ const reasons = new Map<Why, Set<() => boolean>>()
23
+ /** A check that throws holds: what it guards is not known to be safe. */
24
+ const holds = (fn: () => boolean): boolean => { try { return !!fn() } catch { return true } }
25
+ const on = (why: Why): boolean => [...(reasons.get(why) ?? [])].some(holds)
26
+ export const isUnsaved = (why: Why): why is UnsavedWhy => (UNSAVED_WHY as readonly Why[]).includes(why)
27
+
28
+ function register(why: Why, fn: () => boolean): () => void {
29
+ let set = reasons.get(why)
30
+ if (!set) reasons.set(why, set = new Set())
31
+ set.add(fn)
32
+ workChanged()
33
+ return () => { set!.delete(fn); workChanged() }
34
+ }
35
+ /** Unsaved work of this kind while `fn` answers true. Returns the unregister. */
36
+ export const unsavedWhen = (why: UnsavedWhy, fn: () => boolean) => register(why, fn)
37
+ /** Busy (not unsaved) while `fn` answers true: a Jam session, the microphone, an agent at work. */
38
+ export const busyWhen = (why: BusyWhy, fn: () => boolean) => register(why, fn)
39
+
40
+ /** Every reason that holds now, in the contract's order. */
41
+ export const busyWhy = (): Why[] => WHY.filter(on)
42
+ /** The unsaved reasons that hold now. */
43
+ export const unsavedWhy = (): UnsavedWhy[] => UNSAVED_WHY.filter(on)
44
+ /** Does this page hold anything not on the server yet? */
45
+ export const hasUnsavedWork = (): boolean => UNSAVED_WHY.some(on)
46
+
47
+ const listeners = new Set<() => void>()
48
+ let queued = false
49
+ /** A reason may have changed: every listener hears it once, a microtask later (a burst of changes is one). */
50
+ export function workChanged(): void {
51
+ if (queued || !listeners.size) return
52
+ queued = true
53
+ queueMicrotask(() => { queued = false; for (const fn of [...listeners]) { try { fn() } catch { /* the rest still hear */ } } })
54
+ }
55
+ export const onWorkChange = (fn: () => void): (() => void) => { listeners.add(fn); return () => { listeners.delete(fn) } }
56
+
57
+ // ---- leaving --------------------------------------------------------------------------------------------
58
+
59
+ let leaving = false
60
+ let rearm: ReturnType<typeof setTimeout> | undefined
61
+ /** The page's own reload - A1's resume, once its canvas is back and what it held is saved - goes without asking
62
+ * itself. Should the reload not happen after all (a frame refused it), the guard is back a second later. */
63
+ export function leaveNow(go: () => void): void {
64
+ leaving = true
65
+ clearTimeout(rearm)
66
+ rearm = setTimeout(() => { leaving = false }, 1000)
67
+ go()
68
+ }
69
+
70
+ /** Would the guard ask before this page goes? */
71
+ export const asksBeforeLeaving = (): boolean => !leaving && hasUnsavedWork()
72
+
73
+ /** The one `beforeunload` (it replaces the store's stopped-and-dirty one and the capture's recording one). Chrome shows
74
+ * its question only on a page that had a gesture since it loaded; the Mac app does not rely on it (A2.14 #16). */
75
+ export function guardLeaving(target: EventTarget): void {
76
+ target.addEventListener('beforeunload', (e) => {
77
+ if (!asksBeforeLeaving()) return
78
+ e.preventDefault()
79
+ try { (e as BeforeUnloadEvent).returnValue = '' } catch { /* not every engine has it */ }
80
+ })
81
+ }