@marver-design/marver 0.29.0 → 0.30.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +2 -1
  3. package/dist/{anchor-check-DhlpKl2K.mjs → anchor-check-Bv4o-R2T.mjs} +1 -1
  4. package/dist/{build-CWbrb2bl.mjs → build-zWGXSzly.mjs} +5 -4
  5. package/dist/cli.mjs +5 -5
  6. package/dist/{daemon-Sc_z8gT6.mjs → daemon-CChgWJNq.mjs} +2 -2
  7. package/dist/{dev-DWBKQhxf.mjs → dev-DOgIITpT.mjs} +8 -8
  8. package/dist/{perf-Denssrko.mjs → perf-6MOTHxay.mjs} +710 -99
  9. package/dist/perf-BCxAo0IS.mjs +1743 -0
  10. package/dist/{plugin-DqoZB-D6.mjs → plugin-CFWBcAba.mjs} +928 -539
  11. package/dist/{poster-CrsjqhY4.mjs → poster-DPPpQiva.mjs} +1 -1
  12. package/dist/{publish-bakes-DW-NDgU2.mjs → publish-bakes-_Zx8crP3.mjs} +2 -2
  13. package/dist/{recover-GtJ9UDAB.mjs → recover-mDUVsnPd.mjs} +1 -1
  14. package/dist/{shot-T04Ixrvq.mjs → shot-d4h_hJi9.mjs} +3 -3
  15. package/docs/app.md +194 -0
  16. package/docs/performance.md +100 -19
  17. package/package.json +1 -1
  18. package/src/client/frame-host/bridge.js +17 -8
  19. package/src/client/frame-host/inplace.ts +124 -0
  20. package/src/client/frame-host/inspect.d.ts +1 -0
  21. package/src/client/frame-host/inspect.js +13 -4
  22. package/src/client/frame-host/main.tsx +12 -3
  23. package/src/client/frame-host/messages.ts +85 -0
  24. package/src/client/frame-host/signals.d.ts +15 -0
  25. package/src/client/frame-host/signals.js +219 -0
  26. package/src/client/recorder-level.ts +41 -0
  27. package/src/client/shell/App.tsx +158 -88
  28. package/src/client/shell/BoardList.tsx +103 -48
  29. package/src/client/shell/Comments.tsx +66 -42
  30. package/src/client/shell/ContextMenu.tsx +3 -2
  31. package/src/client/shell/JamSurface.tsx +116 -71
  32. package/src/client/shell/LockedApp.tsx +19 -3
  33. package/src/client/shell/Play.tsx +94 -58
  34. package/src/client/shell/StatusPicker.tsx +19 -9
  35. package/src/client/shell/Toolbar.tsx +15 -7
  36. package/src/client/shell/api.ts +18 -4
  37. package/src/client/shell/app-bridge.ts +12 -6
  38. package/src/client/shell/app-perf.ts +31 -1
  39. package/src/client/shell/canvas/Canvas.tsx +17 -6
  40. package/src/client/shell/canvas/FrameNode.tsx +25 -12
  41. package/src/client/shell/canvas/Sticky.tsx +4 -2
  42. package/src/client/shell/canvas/ctl.ts +2 -0
  43. package/src/client/shell/canvas/ready-watch.ts +4 -0
  44. package/src/client/shell/canvas/sleep.ts +2 -0
  45. package/src/client/shell/canvas/updates.ts +13 -6
  46. package/src/client/shell/commands.ts +765 -0
  47. package/src/client/shell/comments-store.ts +42 -27
  48. package/src/client/shell/goto.ts +11 -6
  49. package/src/client/shell/jam-keys.ts +141 -75
  50. package/src/client/shell/jam-lane.tsx +19 -12
  51. package/src/client/shell/jam-panel.tsx +61 -48
  52. package/src/client/shell/jam-session.tsx +41 -37
  53. package/src/client/shell/jam-state.ts +9 -1
  54. package/src/client/shell/jam-surface-parts.tsx +8 -6
  55. package/src/client/shell/jam-ui.tsx +9 -6
  56. package/src/client/shell/jam-voice.ts +4 -2
  57. package/src/client/shell/main.tsx +7 -1
  58. package/src/client/shell/marks-ui.tsx +11 -0
  59. package/src/client/shell/perf.ts +51 -5
  60. package/src/client/shell/recorder-core.ts +4 -1
  61. package/src/client/shell/recorder-hmr.ts +36 -0
  62. package/src/client/shell/recorder-reloads.ts +264 -0
  63. package/src/client/shell/recorder-seams.ts +116 -0
  64. package/src/client/shell/recorder-self.ts +73 -0
  65. package/src/client/shell/recorder-signals-core.ts +139 -0
  66. package/src/client/shell/recorder-signals.ts +485 -0
  67. package/src/client/shell/recorder.ts +118 -43
  68. package/src/client/shell/store.ts +112 -32
  69. package/src/client/shell/whiteout-probes.ts +3 -1
  70. package/src/client/stage/main.tsx +10 -5
  71. package/src/shared/app-api.ts +28 -6
  72. package/src/shared/app-perf.ts +99 -6
  73. package/src/shared/app-report.ts +586 -0
  74. package/src/shared/perf-records.ts +445 -0
  75. package/src/shared/perf-run.ts +6 -2
  76. package/dist/perf-jam-CLkERSHo.mjs +0 -642
@@ -6,6 +6,8 @@ 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
8
  import { unsavedWhen, workChanged } from './unsaved.ts'
9
+ import { nextSeq, PAGE_ID } from './recorder-seams.ts'
10
+ import type { BoardWriter, HeldBy, LoadTrigger } from '../../shared/perf-records.ts'
9
11
  // @ts-expect-error virtual module provided by the plugin
10
12
  import shConfig from 'virtual:sh-config'
11
13
  // @ts-expect-error virtual module: null in dev; a published build inlines manifest+boards
@@ -176,6 +178,7 @@ import { UNPLACED } from './hash.ts'
176
178
  import type { BoardType, StatusWord } from '../../shared/board-types.ts'
177
179
  import type { Phase, Status } from '../../shared/status.ts'
178
180
  import { isNew, type Marks } from '../../shared/marks.ts'
181
+ import { cmd, keepCmds, type CmdOpts } from './commands.ts'
179
182
 
180
183
  /** The CAS tokens a tree write echoes: the sha256 of every board file as last seen, and of
181
184
  * the folder registry (null = there was no file). */
@@ -272,11 +275,26 @@ const TAB = Math.random().toString(36).slice(2, 8)
272
275
  * means a first load, or a document that reloaded itself (the reload log tells them apart). */
273
276
  const reloadCause = new Map<string, 'job' | 'manual' | 'retry'>()
274
277
  export const takeReloadCause = (key: string) => { const c = reloadCause.get(key); reloadCause.delete(key); return c }
278
+ /** A reload line with its envelope (spec 30 #16): the tab, and the page and seq the `(page, seq)` dedupe reads. */
279
+ export const reloadLine = (entry: Record<string, unknown>): Record<string, unknown> => ({ tab: TAB, page: PAGE_ID, seq: nextSeq(), ts: Date.now(), ...entry })
280
+ /** The edit's way to the frames, as the recorder sees it: recorder-reloads.ts installs these at the full level (spec 30
281
+ * R1). Until then, and under `core`, a line goes as 0.29's did - one unconfirmed request - and the rest do nothing. */
282
+ export const reloadHooks = {
283
+ line: (l: Record<string, unknown>): void => {
284
+ const body = { records: [l] }
285
+ // a page's very first request may go before its request cookie exists: a GET primes it, then once more
286
+ void postOwner('perf/reload', body).then((r) => (r.status === 403 ? api('work').then(() => postOwner('perf/reload', body)) : r)).catch(() => {})
287
+ },
288
+ /** an edit reached these frames: before their nodes go stale */
289
+ invalidated: (_frames: ReadonlySet<string>, _revision: string): void => {},
290
+ /** a reload job started this navigation of a node */
291
+ started: (_key: string, _nav: number): void => {},
292
+ /** a stale node's turn was refused, and why (canvas/updates.ts) */
293
+ held: (_key: string, _why: HeldBy): void => {},
294
+ }
275
295
  export const logReload = (entry: Record<string, unknown>) => {
276
296
  if (PUBLISHED) return
277
- const body = { tab: TAB, ...entry }
278
- // a page's very first request may go before its request cookie exists: a GET primes it, then once more
279
- void postOwner('perf/reload', body).then((r) => (r.status === 403 ? api('work').then(() => postOwner('perf/reload', body)) : r)).catch(() => {})
297
+ reloadHooks.line(reloadLine(entry))
280
298
  }
281
299
  const postOwner = (path: string, body: unknown) =>
282
300
  api(path, { method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() }, body: JSON.stringify(body) })
@@ -285,11 +303,13 @@ const postOwner = (path: string, body: unknown) =>
285
303
  * `marver boards pin` does. The answer is said; the file change re-reads the sidebar and the view. */
286
304
  export async function addToBoard(board: string, frames: string[]): Promise<void> {
287
305
  const { toast } = useStore.getState()
306
+ const h = cmd('add-to-board', { via: 'click', in: 'shell', board, frames: frames.length })
288
307
  try {
289
308
  const r = await postOwner('boards/pin', { board, frames })
290
309
  const body = await r.json().catch(() => ({})) as { added?: string[]; error?: string }
310
+ if (r.ok) h.done(); else h.fail('api')
291
311
  toast(r.ok ? `${body.added?.length ? 'pinned' : 'already'} on ${boardLabel(board)}` : body.error ?? `could not pin (${r.status})`)
292
- } catch { toast('could not reach the dev server') }
312
+ } catch { h.fail('api'); toast('could not reach the dev server') }
293
313
  }
294
314
 
295
315
  const HEADER = 28
@@ -318,6 +338,36 @@ const nodeKey = () => 'n_' + Math.random().toString(36).slice(2, 8)
318
338
  let manifestRev = 0
319
339
  export const bumpManifestRev = () => { manifestRev++ }
320
340
 
341
+ /** The board read again over itself: a frame still on it keeps its live document, so the node keeps what is known of
342
+ * that document. Read fresh it would wait for a ready that document sent long ago - the watchdog then reloads every
343
+ * frame - and its `nav`, back to none, would read as a request to navigate. Only a healthy document is kept: one that
344
+ * failed, one silent past its retry, and one whose sizing changed - its mode, or a content frame's human width (a
345
+ * measure it will never send again) - are asked anew.
346
+ * A kept content frame keeps the size it measured: the file holds none (auto) or the width alone is the human's
347
+ * (manual), and a document that stays never measures again unless its width changes. `kept`: the nodes whose
348
+ * document stands; `carried`: the nodes whose kept size differs from the file's. */
349
+ function keepDocuments(mounted: Node[], nodes: Node[]): { nodes: Node[]; kept: Set<string>; carried: Set<string> } {
350
+ const was = new Map(mounted.map((n) => [n.key, n]))
351
+ const kept = new Set<string>(), carried = new Set<string>()
352
+ const next = nodes.map((n) => {
353
+ const o = was.get(n.key)
354
+ if (!o || o.frame !== n.frame || o.missing || n.missing) return n
355
+ const { status, error, nav, rev, themeOn, readyRetried, stale, shown, want } = o
356
+ // only a frame that measures (renders a Doc) has a size of its own to keep; a bare Md or Img is the size its board says
357
+ const fits = measures(n.frame)
358
+ // a human width the file changed is sizing too: the document fits its height at a width only once it loads there
359
+ const resized = fits && n.sizeMode === 'manual' && Math.round(o.w) !== Math.round(n.w)
360
+ if (status === 'error' || (status === 'loading' && readyRetried) || o.sizeMode !== n.sizeMode || resized) return { ...n, nav: (nav ?? 0) + 1, stale, want }
361
+ kept.add(n.key)
362
+ // auto: the whole size is measured; manual: the height, at the width it has
363
+ const w = fits && o.sizeMode === 'auto' ? o.w : n.w
364
+ const h = fits && (o.sizeMode === 'auto' || o.sizeMode === 'manual') ? o.h : n.h
365
+ if (Math.round(w) !== Math.round(n.w) || Math.round(h) !== Math.round(n.h)) carried.add(n.key)
366
+ return { ...n, w, h, status, error, nav, rev, themeOn, readyRetried, stale, shown, want }
367
+ })
368
+ return { nodes: next, kept, carried }
369
+ }
370
+
321
371
  /** ws= binds the document to this canvas (spec 28 A1.11): another project on this port later answers a
322
372
  * frame's own reload with the "another canvas" page (server/guard.ts), never with its frame. */
323
373
  export function frameUrl(frame: FrameEntry, theme: string): string {
@@ -517,11 +567,12 @@ export type RequestCut = 'superseded' | 'error' | 'edited' | 'unsaved'
517
567
  * on a published one. A request owns the geometry from its commit, and `commit` runs right BEFORE the set that
518
568
  * mounts the load: mounting it is never a move. */
519
569
  export const recorderHooks = {
520
- request: (_board: string, _cause: LoadCause): string => '',
570
+ /** `trigger`, `writer`: why it read the board again, and who may have written it (spec 30 #17, #18) */
571
+ request: (_board: string, _cause: LoadCause, _trigger?: LoadTrigger, _writer?: BoardWriter): string => '',
521
572
  /** a request is about to commit: the load that was up ends - before the incoming sizes are installed, so it ends by
522
573
  * the sizes it read (which frames measure), its board's nodes still in the store */
523
574
  handover: (_request: string): void => {},
524
- commit: (_request: string, _nodes: readonly Node[], _manifest: Manifest): void => {},
575
+ commit: (_request: string, _nodes: readonly Node[], _manifest: Manifest, _kept?: ReadonlySet<string>): void => {},
525
576
  cut: (_request: string, _reason: RequestCut): void => {},
526
577
  /** nothing of the reflow story is left: no reflow pending, no height held, none owed */
527
578
  reflowIdle: (): void => {},
@@ -633,8 +684,9 @@ interface State {
633
684
  imageBusy: boolean // a copy-as-image render is in flight (one at a time)
634
685
 
635
686
  /** (re)load the open board from disk. `mayCommit`, when given, is asked again at the moment the
636
- * reload would land - a caller's own conditions (a status write's: nothing moved since its flush) */
637
- boot(mayCommit?: () => boolean): Promise<boolean>
687
+ * reload would land - a caller's own conditions (a status write's: nothing moved since its flush).
688
+ * `trigger`, `writer`: why it reads the board again, and who may have written it - the recorder's (spec 30 #17, #18) */
689
+ boot(mayCommit?: () => boolean, trigger?: LoadTrigger, writer?: BoardWriter): Promise<boolean>
638
690
  applyManifest(m: Manifest): void
639
691
  frameFor(node: Node): FrameEntry | undefined
640
692
  moveNode(key: string, x: number, y: number): void
@@ -688,7 +740,7 @@ interface State {
688
740
  setScenes(scenes: Manifest['scenes']): void
689
741
  arrangeBoards(tree: TreeItem[], base: TreeBase): Promise<{ ok: true } | { ok: false; stale: boolean; error?: string }>
690
742
  pulsePath(): void
691
- copyFrameImage(scale: 2 | 4): void
743
+ copyFrameImage(scale: 2 | 4, how: CmdOpts): void
692
744
  setScale(s: number): void
693
745
  togglePanel(): void
694
746
  setTheme(theme: string): void
@@ -843,7 +895,12 @@ export const useStore = create<State>((set, get) => {
843
895
  if (!holds.size && reflowOwed) { reflowOwed = false; scheduleReflow(null) }
844
896
  else reflowSettled()
845
897
  }
846
- const dropHolds = () => { for (const h of holds.values()) clearTimeout(h.timer); holds.clear(); reflowOwed = false }
898
+ /** `keep`: nodes whose document a board read kept - a reload of theirs still on its way keeps its hold and the
899
+ * measure it held back (an image still loading lands when the hold lets go) */
900
+ const dropHolds = (keep?: ReadonlySet<string>) => {
901
+ for (const [k, h] of holds) if (!keep?.has(k)) { clearTimeout(h.timer); holds.delete(k) }
902
+ reflowOwed = reflowOwed && holds.size > 0 // a reflow owed to a hold that stays is still owed when it lets go
903
+ }
847
904
  /** A content measure moved the rows: once, after the last held node lets go. */
848
905
  const reflowAfterHolds = () => { reflowReasons.add('measured'); if (holds.size) reflowOwed = true; else scheduleReflow('measured') }
849
906
  /** The recorder hears when nothing of the reflow story is left (spec 28 A1.7): no timer, no held height, none owed. */
@@ -893,10 +950,11 @@ export const useStore = create<State>((set, get) => {
893
950
  * it: it already equals the committed one. So once the board is up, the recipe re-runs if the
894
951
  * known heights differ from the ones its positions were laid out around (`laidOut`). A frame the
895
952
  * human dragged, at heights that did not change, stays where they put it. */
896
- const layoutStale = () => {
953
+ const layoutStale = (kept?: ReadonlySet<string>) => {
897
954
  const { nodes, laidOut } = get()
898
955
  const record = laidOut ?? {}
899
- const known = (n: Node) => n.sizeMode === 'auto' && hasKnownHeight(n.frame, Math.round(n.w))
956
+ // `kept`: nodes whose size a board read kept from their live document - known as surely as a measured one
957
+ const known = (n: Node) => (n.sizeMode === 'auto' && hasKnownHeight(n.frame, Math.round(n.w))) || !!kept?.has(n.key)
900
958
  const has = (n: Node) => Object.prototype.hasOwnProperty.call(record, n.key)
901
959
  // a node the layout recorded, at another size now
902
960
  if (nodes.some((n) => known(n) && has(n) && sizeOf(n) !== record[n.key])) return true
@@ -959,7 +1017,9 @@ export const useStore = create<State>((set, get) => {
959
1017
  * mounted board reads: those it read come back with it, for the commit to install (installSizes).
960
1018
  * null = failure (transport, malformed manifest, non-404 board error) - the caller
961
1019
  * keeps whatever board is currently mounted. */
962
- const loadBoardState = async (boardName: string): Promise<{ state: Partial<State>; sizes: SizeRead | null } | null> => {
1020
+ /** `tidied`: this load laid the rows out itself (no positions, a cramped note) - every position is the recipe's, made
1021
+ * around the sizes it read */
1022
+ const loadBoardState = async (boardName: string): Promise<{ state: Partial<State>; sizes: SizeRead | null; tidied: boolean } | null> => {
963
1023
  clearNoteHeights() // heights are per column drawn; a key shared by two board files carries none across
964
1024
  loadErrors.delete(boardName)
965
1025
  try {
@@ -1145,7 +1205,8 @@ export const useStore = create<State>((set, get) => {
1145
1205
  // a note that landed while this board was closed has no room in the saved positions:
1146
1206
  // a board with a recipe re-applies it (spec 18 - room is the layout's job)
1147
1207
  const cramped = !!boardHash && !needTidy && !!(layout || sceneRows?.length || boardAuto) && notesCramped(nodes, manifest)
1148
- if ((!boardHash || needTidy || cramped) && nodes.length) {
1208
+ const tidied = (!boardHash || needTidy || cramped) && nodes.length > 0
1209
+ if (tidied) {
1149
1210
  const placedAll = tidy(tidyInput(nodes, manifest), effectiveLayout(layout, sceneRows), layoutWarn, knownScenes(manifest))
1150
1211
  for (const pl of placedAll) { const n = nodes.find((x) => x.key === pl.key)!; n.x = pl.x; n.y = pl.y }
1151
1212
  laidOut = sizeRecord(nodes)
@@ -1158,7 +1219,7 @@ export const useStore = create<State>((set, get) => {
1158
1219
  if (layout && boardHash && !needTidy && !cramped && nodes.length) {
1159
1220
  tidy(tidyInput(nodes, manifest), layout, layoutWarn, knownScenes(manifest))
1160
1221
  }
1161
- return { state: { manifest, nodes, boardHash, boardAuto, deviceView, sceneRows, layout, layoutRaw, baseLayout, laidOut, baseLaidOut, selection: [], dirty: prunedAtLoad || cramped }, sizes }
1222
+ return { state: { manifest, nodes, boardHash, boardAuto, deviceView, sceneRows, layout, layoutRaw, baseLayout, laidOut, baseLaidOut, selection: [], dirty: prunedAtLoad || cramped }, sizes, tidied }
1162
1223
  } catch { return null } finally { preparing = null }
1163
1224
  }
1164
1225
 
@@ -1168,12 +1229,12 @@ export const useStore = create<State>((set, get) => {
1168
1229
  panelOpen: true, scale: 1, toasts: [], working: [], workingSince: {}, workingBoards: [], workingSeq: -1, boardHash: null, dirty: false, boardTitles: DATA?.titles ?? {}, boardMeta: DATA?.meta ?? {},
1169
1230
  externalLeases: {}, playUpdateRevision: null, stageShown: null, playNav: 0, pathPulse: 0, imagePulse: 0, imageBusy: false,
1170
1231
 
1171
- async boot(mayCommit) {
1232
+ async boot(mayCommit, trigger, writer) {
1172
1233
  const seq = ++loadSeq
1173
1234
  recorderHooks.cut(bootRequest, 'superseded')
1174
1235
  const boardName = get().board
1175
1236
  // the recorder's request (spec 28 A1.7): the page's first load, else the open board read from disk again
1176
- const request = bootRequest = recorderHooks.request(boardName, firstLoad ? 'boot' : 'disk-reload')
1237
+ const request = bootRequest = recorderHooks.request(boardName, firstLoad ? 'boot' : 'disk-reload', firstLoad ? 'first' : trigger, writer)
1177
1238
  firstLoad = false
1178
1239
  const revAtStart = editRev, scenesAtStart = scenesRev
1179
1240
  const loaded = await loadBoardState(boardName)
@@ -1181,13 +1242,20 @@ export const useStore = create<State>((set, get) => {
1181
1242
  if (!loaded) { recorderHooks.cut(request, 'error'); get().toast(`board "${boardName}" failed to load${whyNot(boardName)}`); return false }
1182
1243
  // the user kept editing while we fetched - their newer state wins over the reload
1183
1244
  if (get().board !== boardName || editRev !== revAtStart || (mayCommit && !mayCommit())) { recorderHooks.cut(request, 'edited'); return false }
1184
- const next = loaded.state
1185
1245
  const live = get().manifest // a WS manifest update may have landed mid-fetch
1186
1246
  recorderHooks.handover(request) // the load that was up ends by its own sizes
1187
1247
  installSizes(loaded.sizes) // the sizes this load read are the page's from its commit
1188
- recorderHooks.commit(request, next.nodes as Node[], next.manifest as Manifest) // before the set: mounting is not a move
1248
+ // after the install: which frames measure is this load's word
1249
+ const { nodes, kept, carried } = keepDocuments(get().nodes, loaded.state.nodes as Node[])
1250
+ const next = { ...loaded.state, nodes }
1251
+ recorderHooks.commit(request, next.nodes, next.manifest as Manifest, kept) // before the set: mounting is not a move
1189
1252
  set(next)
1190
- cancelReflow(); dropHolds(); reloadCause.clear()
1253
+ cancelReflow(); dropHolds(kept)
1254
+ // a kept size the file did not hold: rows this load laid out around the file's sizes are laid out again around the
1255
+ // kept ones; positions read from the file move only if the layout was not made around it - judged as a known
1256
+ // height is (a human's placement at the sizes it recorded stays)
1257
+ if (carried.size && composed(get())) scheduleReflow('stale', loaded.tidied ? undefined : () => layoutStale(carried))
1258
+ for (const k of [...reloadCause.keys()]) if (!kept.has(k)) reloadCause.delete(k) // a document still loading keeps its cause
1191
1259
  if (next.dirty) scheduleSave() // load-time prune must reach the disk
1192
1260
  if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
1193
1261
  else if (scenesRev !== scenesAtStart && liveScenes) set({ manifest: { ...get().manifest!, scenes: liveScenes } }) // an sh:scenes that landed mid-fetch outranks the file we read
@@ -1245,6 +1313,7 @@ export const useStore = create<State>((set, get) => {
1245
1313
  },
1246
1314
 
1247
1315
  renameBoard(name, title, baseHash) {
1316
+ const sending = keepCmds() // spec 30 #18: this write names its command however long it waits for its turn and the flush
1248
1317
  return structural(async () => {
1249
1318
  const from = name
1250
1319
  const active = from === get().board
@@ -1263,12 +1332,12 @@ export const useStore = create<State>((set, get) => {
1263
1332
  try {
1264
1333
  // the active board's hash is freshest in the store (an autosave may have landed since
1265
1334
  // the sidebar looked); every other board's is the sidebar's
1266
- const send = (base: string | null | undefined) => postOwner('boards/rename', { from, title, ...(base ? { baseHash: base } : {}) })
1335
+ const send = (base: string | null | undefined) => sending(() => postOwner('boards/rename', { from, title, ...(base ? { baseHash: base } : {}) }))
1267
1336
  let res: Response
1268
1337
  try {
1269
1338
  res = await send(active && get().boardHash ? get().boardHash : baseHash)
1270
1339
  // the open board changed on disk: reload it, then once more (setBoardStatus's reasoning)
1271
- if (res.status === 409 && mayReload() && await get().boot(mayReload)) res = await send(get().boardHash)
1340
+ if (res.status === 409 && mayReload() && await get().boot(mayReload, 'save-conflict')) res = await send(get().boardHash)
1272
1341
  }
1273
1342
  catch { return { ok: false, error: 'could not reach the dev server' } }
1274
1343
  const body = await res.json().catch(() => ({} as { error?: string; sha256?: string }))
@@ -1285,6 +1354,7 @@ export const useStore = create<State>((set, get) => {
1285
1354
  },
1286
1355
 
1287
1356
  setBoardStatus(name, status, reason, baseHash) {
1357
+ const sending = keepCmds() // renameBoard's
1288
1358
  return structural(async () => {
1289
1359
  const active = name === get().board
1290
1360
  // the active board's file is rewritten under the autosave: flush first, hold across (renameBoard's pattern)
@@ -1299,14 +1369,14 @@ export const useStore = create<State>((set, get) => {
1299
1369
  const rev = editRev
1300
1370
  const mayReload = () => active && get().board === name && editRev === rev && !get().gesture
1301
1371
  try {
1302
- const send = (base: string | null | undefined) => postOwner('boards/status', { name, status, ...(reason ? { reason } : {}), ...(base ? { baseHash: base } : {}) })
1372
+ const send = (base: string | null | undefined) => sending(() => postOwner('boards/status', { name, status, ...(reason ? { reason } : {}), ...(base ? { baseHash: base } : {}) }))
1303
1373
  let res: Response
1304
1374
  try {
1305
1375
  res = await send(active && get().boardHash ? get().boardHash : baseHash)
1306
1376
  // the open board changed on disk (an agent wrote it): its hash in the store is behind, and a
1307
1377
  // retry with it would 409 again - reload the board (layout and hash together) when nothing
1308
1378
  // has changed here since the flush, then try once more against what is on disk now
1309
- if (res.status === 409 && mayReload() && await get().boot(mayReload)) res = await send(get().boardHash)
1379
+ if (res.status === 409 && mayReload() && await get().boot(mayReload, 'save-conflict')) res = await send(get().boardHash)
1310
1380
  }
1311
1381
  catch { return { ok: false, error: 'could not reach the dev server' } }
1312
1382
  const body = await res.json().catch(() => ({} as { error?: string; sha256?: string }))
@@ -1354,6 +1424,7 @@ export const useStore = create<State>((set, get) => {
1354
1424
  // true and the watcher's echo is filtered as our own. `base` carries the hashes the
1355
1425
  // sidebar last saw; a 409 (`stale`) means someone else wrote first - refetch and replay.
1356
1426
  arrangeBoards(tree, base) {
1427
+ const sending = keepCmds() // renameBoard's
1357
1428
  return structural(async () => {
1358
1429
  let ok = true
1359
1430
  for (let i = 0; i < 5 && get().dirty && ok; i++) { clearTimeout(saveTimer); ok = await get().save() }
@@ -1365,7 +1436,7 @@ export const useStore = create<State>((set, get) => {
1365
1436
  const active = get().board
1366
1437
  const boards = { ...base.boards, ...(get().boardHash && base.boards[active] !== undefined ? { [active]: get().boardHash } : {}) }
1367
1438
  let res: Response
1368
- try { res = await postOwner('boards/reorder', { tree: toWire(tree), base: { boards, folders: base.folders }, protocol: TREE_PROTOCOL }) }
1439
+ try { res = await sending(() => postOwner('boards/reorder', { tree: toWire(tree), base: { boards, folders: base.folders }, protocol: TREE_PROTOCOL })) }
1369
1440
  catch { return { ok: false as const, stale: false, error: 'could not reach the dev server' } }
1370
1441
  const body = await res.json().catch(() => ({} as { error?: string; sha256?: { boards?: Record<string, string> } }))
1371
1442
  if (!res.ok) return { ok: false as const, stale: res.status === 409, error: body?.error }
@@ -1762,6 +1833,7 @@ export const useStore = create<State>((set, get) => {
1762
1833
  // every document of these frames is behind - one loading too (one running, one waiting): a document
1763
1834
  // that shows the revision the edit made clears it when it is ready (setShown)
1764
1835
  const want = (f: string) => (docs?.epoch && typeof docs.docs?.[f] === 'number' ? `${docs.epoch}:${docs.docs[f]}` : undefined)
1836
+ reloadHooks.invalidated(ids, revision)
1765
1837
  const nodes = s.nodes.map((n) => (ids.has(n.frame) && !n.missing ? { ...n, stale: true, want: later(n.want, want(n.frame)) } : n))
1766
1838
  set({ nodes, ...(s.play ? { playUpdateRevision: revision } : {}) })
1767
1839
  pumpUpdates()
@@ -1776,6 +1848,7 @@ export const useStore = create<State>((set, get) => {
1776
1848
  set((s) => ({ nodes: s.nodes.map((x) => (x.key === key
1777
1849
  ? { ...x, stale: false, status: 'loading' as const, error: undefined, nav: (x.nav ?? 0) + 1, readyRetried: false }
1778
1850
  : x)) }))
1851
+ reloadHooks.started(key, (n.nav ?? 0) + 1)
1779
1852
  },
1780
1853
  setShown(key, shown) {
1781
1854
  set((s) => ({ nodes: s.nodes.map((x) => {
@@ -1816,15 +1889,19 @@ export const useStore = create<State>((set, get) => {
1816
1889
  // node shows, at 2x (or 4x). The ClipboardItem takes a PROMISE: clipboard.write runs
1817
1890
  // inside the click/keydown gesture and the browser waits for the bytes - a plain
1818
1891
  // await-then-write would have lost the transient activation during the 1-4s render.
1819
- copyFrameImage(scale) {
1892
+ copyFrameImage(scale, how) {
1820
1893
  const s = get()
1821
- if (PUBLISHED || s.imageBusy || s.selection.length !== 1) return
1894
+ if (PUBLISHED) return
1895
+ // spec 30: done when the clipboard holds it (60 s, the ceiling below); each refusal its code
1896
+ const h = cmd('copy-image', { ...how, frames: s.selection.length, arg: `${scale}x` })
1897
+ if (s.imageBusy) { h.noop('busy'); return }
1898
+ if (s.selection.length !== 1) { h.noop('multi'); return }
1822
1899
  const node = s.nodes.find((n) => n.key === s.selection[0])
1823
- if (!node || node.missing) return
1900
+ if (!node || node.missing) { h.noop('indexing'); return }
1824
1901
  const frame = s.frameFor(node)
1825
- if (!frame) { s.toast('frame is still indexing - try again in a second'); return }
1902
+ if (!frame) { h.noop('indexing'); s.toast('frame is still indexing - try again in a second'); return }
1826
1903
  const CI = (globalThis as { ClipboardItem?: typeof ClipboardItem }).ClipboardItem
1827
- if (!CI || !navigator.clipboard?.write || (CI.supports && !CI.supports('image/png'))) { s.toast("this browser can't put images on the clipboard - use Chrome, Edge or Safari"); return }
1904
+ if (!CI || !navigator.clipboard?.write || (CI.supports && !CI.supports('image/png'))) { h.fail('browser'); s.toast("this browser can't put images on the clipboard - use Chrome, Edge or Safari"); return }
1828
1905
  set({ imageBusy: true })
1829
1906
  void import('./jam-capture.ts').then(({ recordCopy }) => recordCopy('image', frame.id)) // a capture notes that it happened
1830
1907
  const done = () => set({ imageBusy: false })
@@ -1840,11 +1917,13 @@ export const useStore = create<State>((set, get) => {
1840
1917
  return r.blob()
1841
1918
  }).finally(() => clearTimeout(timer))
1842
1919
  let renderErr = ''
1843
- png.catch((e: Error) => { renderErr = e.name === 'AbortError' ? 'timed out - the renderer is busy' : e.message })
1920
+ let renderTimedOut = false
1921
+ png.catch((e: Error) => { renderTimedOut = e.name === 'AbortError'; renderErr = renderTimedOut ? 'timed out - the renderer is busy' : e.message })
1844
1922
  const fail = (err: unknown) => {
1845
1923
  done()
1846
1924
  // a prompt clipboard refusal (no gesture, focus lost) must not wait a minute on the
1847
1925
  // render: abandon the fetch, toast now. A render failure surfaces its own cause.
1926
+ h.fail(renderErr ? (renderTimedOut ? 'render-timeout' : 'render-failed') : (err as Error)?.name === 'NotAllowedError' ? 'clipboard-blocked' : 'render-failed')
1848
1927
  if (!renderErr) ctl.abort()
1849
1928
  s.toast(renderErr ? `render failed - ${renderErr}` : (err as Error)?.name === 'NotAllowedError' ? 'copy blocked - click the canvas first' : `copy failed - ${(err as Error)?.message ?? err}`)
1850
1929
  }
@@ -1852,6 +1931,7 @@ export const useStore = create<State>((set, get) => {
1852
1931
  navigator.clipboard.write([new CI({ 'image/png': png })]).then(
1853
1932
  () => {
1854
1933
  done()
1934
+ h.done()
1855
1935
  const used = meta.scale ?? scale
1856
1936
  s.toast(used < scale ? `image copied at ${used}x - frame too tall for ${scale}x` : scale === 4 ? 'image copied (4x)' : 'image copied')
1857
1937
  set((st) => ({ imagePulse: st.imagePulse + 1 }))
@@ -2150,7 +2230,7 @@ export const useStore = create<State>((set, get) => {
2150
2230
  lostInResume('gone') // a save while a resume is owed: the page after its reload says this, not "saved"
2151
2231
  return true
2152
2232
  }
2153
- const reloaded = await get().boot() // hash advances only when the authoritative reload commits
2233
+ const reloaded = await get().boot(undefined, 'save-conflict') // hash advances only when the authoritative reload commits
2154
2234
  if (reloaded) { get().toast(DISK_WON); lostInResume('disk') }
2155
2235
  return reloaded // false keeps dirty set; the next debounce retries once edits settle
2156
2236
  }
@@ -91,8 +91,10 @@ function cameraPath(): { path: PerfCam[]; stop(): void } {
91
91
  return { path, stop: () => { on = false } }
92
92
  }
93
93
 
94
- /** The `before` answer for `tick`: the points chosen now, the camera and the viewport. */
94
+ /** The `before` answer for `tick`: the points chosen now, the camera and the viewport. A covering play stage leaves no
95
+ * ground to probe, and says so (spec 30 #39): main takes no capture and records the time as uncovered. */
95
96
  export function pick(tick: number): Extract<PerfMsg, { kind: 'probes'; at: 'before' }> {
97
+ if (document.querySelector('.sh-play')) return { kind: 'probes', tick, at: 'before', points: [], cam: canvasCtl.transform(), view: view(), stage: true }
96
98
  const top = VISIBLE_TOP
97
99
  const w = innerWidth, h = Math.max(0, innerHeight - top)
98
100
  const rects = nodeRects()
@@ -12,7 +12,7 @@
12
12
  * Jam captures (spec 27) speak the same messages here as in a canvas frame: the keys the shell owns
13
13
  * (`sh:keys` -> `sh:key`, frame-host/keys.js) and the recorder (frame-host/trail.js, mode 'play').
14
14
  */
15
- import { Component, createElement, useEffect, useRef, useState, type ComponentType, type ReactNode } from 'react'
15
+ import { Component, createElement, Profiler, useEffect, useRef, useState, type ComponentType, type ReactNode } from 'react'
16
16
  import { flushSync } from 'react-dom'
17
17
  import { createRoot } from 'react-dom/client'
18
18
  import { frameFile, frames, layoutChain, layouts, providers } from '../frame-host/registry.ts'
@@ -20,6 +20,7 @@ import { SLIDE_DOC_CSS } from '../const.ts'
20
20
  import { createInspect } from '../frame-host/inspect.js'
21
21
  import { createKeys, keyAllowed } from '../frame-host/keys.js'
22
22
  import { createRecorder } from '../frame-host/trail.js'
23
+ import { frameRenders } from '../frame-host/signals.js'
23
24
 
24
25
  const params = new URLSearchParams(location.search)
25
26
  // Both signals, always - same pair as the frame host: [data-theme] for attribute-keyed
@@ -149,7 +150,7 @@ function Shown({ id, commit }: { id: string; commit?: number }) {
149
150
  // follows every commit (A4.6 #34), so the same frame committed again is shown again from then
150
151
  useEffect(() => {
151
152
  const t = setTimeout(() => {
152
- if (!said.current) { said.current = true; post({ type: 'sh:stage-shown', at: id, nav: params.get('r') ?? '', epoch: stamps?.epoch ?? '', doc: stamps?.doc[id] ?? 0 }) }
153
+ if (!said.current) { said.current = true; post({ type: 'sh:stage-shown', at: id, nav: params.get('r') ?? '', epoch: stamps?.epoch ?? '', doc: stamps?.doc[id] ?? 0, boot: stageRecord.boot }) }
153
154
  stageRecord.at = id; stageRecord.t = Date.now()
154
155
  }, 0)
155
156
  return () => clearTimeout(t)
@@ -261,7 +262,7 @@ function Stage() {
261
262
  recorder.current = createRecorder({ post, getFrame: () => current.current, mode: 'play', trusted })
262
263
  // the keys the shell owns right now: consumed here, ahead of the frame, and forwarded as sh:key
263
264
  const keys = createKeys({ post, trusted })
264
- const inspect = createInspect({ post, getId: () => current.current, onLaserPick: (el, e) => recorder.current?.pick(el, e) ?? false })
265
+ const inspect = createInspect({ post, getId: () => current.current, getBoot: () => stageRecord.boot, onLaserPick: (el, e) => recorder.current?.pick(el, e) ?? false })
265
266
 
266
267
  // data-goto is handled HERE, in place - never posted up as sh:go (capture phase
267
268
  // beats any frame handler; preventDefault stops real <a href> navigations). A
@@ -272,7 +273,7 @@ function Stage() {
272
273
  // on anything interactive, and data-goto (below) always wins
273
274
  if (slidesMode && e.target instanceof Element
274
275
  && !e.target.closest('a, button, input, textarea, select, video, .mv-video, [contenteditable], [data-goto]')) {
275
- post({ type: 'sh:stage-key', key: ' ', code: 'Space' })
276
+ post({ type: 'sh:stage-key', key: ' ', code: 'Space', origin: 'click' }) // spec 30 #50: a click, told apart from Space
276
277
  }
277
278
  const el = e.target instanceof Element ? e.target.closest('[data-goto]') : null
278
279
  if (!el) return
@@ -310,6 +311,8 @@ function Stage() {
310
311
  if (data?.type === 'sh:set-theme') {
311
312
  document.documentElement.dataset.theme = data.theme
312
313
  document.documentElement.classList.toggle('dark', data.theme === 'dark')
314
+ // spec 30 #21: a switch that names its transition is acknowledged two animation frames after, as a frame's is
315
+ if (typeof data.t === 'string') requestAnimationFrame(() => requestAnimationFrame(() => post({ type: 'sh:theme-applied', id: 'stage', theme: data.theme, t: data.t, boot: stageRecord.boot })))
313
316
  }
314
317
  else if (data?.type === 'sh:stage-set' && typeof data.at === 'string') goto(data.at, false)
315
318
  }
@@ -338,7 +341,9 @@ function Stage() {
338
341
  async function boot() {
339
342
  try {
340
343
  await import('virtual:sh-theme' as string)
341
- createRoot(document.getElementById('root')!).render(createElement(Stage))
344
+ // the recorder's minute of this root's commits (spec 30 #36): none where nothing records
345
+ const onRender = frameRenders(post, 'stage', () => stageRecord.boot)
346
+ createRoot(document.getElementById('root')!).render(onRender ? createElement(Profiler, { id: 'stage', onRender }, createElement(Stage)) : createElement(Stage))
342
347
  } catch (err) {
343
348
  post({ type: 'sh:stage-error', message: (err as Error).message })
344
349
  document.getElementById('root')!.innerHTML =
@@ -19,6 +19,11 @@
19
19
  * A4.6 #11, #14), which the server writes and main reads - no page ever opens it; `mv:open` / `mv:opened`, a notice's
20
20
  * click handed to the shell (`OpenItem`, `OpenResult`, A4.6 #29, #30); `mv:capture`, a live picture of the
21
21
  * document's own view (`CaptureAsk`, `CaptureAnswer`, A4.6 #35). The new methods are optional, as A3's are.
22
+ *
23
+ * Spec 30 (app 1.0.1, marver 0.30.0) adds, frozen before its streams split and `v` still 1: `mv:perf`'s `watch`, the
24
+ * three white-out windows a shell asks for (R8 #38), sent only when `perfInfo().watch` is true - app 1.0.0 would refuse
25
+ * it and spend the tab's bucket; and `mv:menu-click`'s `in`, the menu a relayed item came from (#51), absent from 1.0.0
26
+ * (the shell then records `in: 'app'`). Owners: app-store (`watch`, `perfInfo().watch`), commands (`in`).
22
27
  */
23
28
 
24
29
  export const APP_API_VERSION = 1
@@ -59,8 +64,11 @@ export type AppState = 'shown' | 'hidden' | 'untrusted'
59
64
  export interface DocAnswer { reopen: boolean; inset?: Inset }
60
65
  /** `mv:admit` (main to canvas) - the document admitted at its trusted commit (v1.12 r1 #1). */
61
66
  export interface Admit { doc: string }
62
- /** `mv:menu-click` (main to canvas). */
63
- export interface MenuClick { id: string }
67
+ /** Spec 30 #51: the menu a relayed item came from - a View or Jam item, or the tab's right-click menu. */
68
+ export const MENU_IN = ['menu', 'tab-menu'] as const
69
+ export type MenuIn = (typeof MENU_IN)[number]
70
+ /** `mv:menu-click` (main to canvas). `in` (app 1.0.1): where the person chose it; absent from app 1.0.0. */
71
+ export interface MenuClick { id: string; in?: MenuIn }
64
72
  /**
65
73
  * The ids main sends of its own, never in the page's `mv:menu`: the tab's right-click Mark All as Seen (A2.4's
66
74
  * channels table: "Mark all as seen sends `mv:menu-click mark-all-seen` to the canvas"). A shell that does not know
@@ -93,15 +101,26 @@ export interface PerfSize { w: number; h: number }
93
101
  * says which of them are still valid (moved by less than their clearance between the two answers);
94
102
  * - `mem`: `process.getProcessMemoryInfo().private` and `getHeapStatistics()`, all in KB (A3.8 #5);
95
103
  * - `shown`: the second animation-frame callback after a `shown` ask (A3.8 #9: a frame produced, not presented);
96
- * - `board`: the board's frame count and how many sleep, at each commit (Copy Details, A3.8 #9).
104
+ * - `board`: the board's frame count and how many sleep, at each commit (Copy Details, A3.8 #9);
105
+ * - `watch` (spec 30 R8 #38, app 1.0.1): a white-out window the shell opens (`on`) and closes, numbered (`seq`) like a
106
+ * gesture's - `load` from the request to settled or cut, `theme` from a switch to its outcome, `reload` from an
107
+ * on-screen job's `startReload` to its ready. Main keeps one window per tab: a new reason extends it, and a window
108
+ * ends at 10 s whatever the shell says.
97
109
  */
98
110
  export type PerfMsg =
99
111
  | { kind: 'gesture'; on: boolean; seq: number; type?: 'pan' | 'zoom' | 'layout' }
100
- | { kind: 'probes'; tick: number; at: 'before'; points: [number, number][]; cam: PerfCam | null; view: PerfSize }
112
+ | { kind: 'probes'; tick: number; at: 'before'; points: [number, number][]; cam: PerfCam | null; view: PerfSize; /** spec 30 #39: a play stage covers the canvas - no ground to probe, no capture taken */ stage?: true }
101
113
  | { kind: 'probes'; tick: number; at: 'after'; valid: boolean[]; cam: PerfCam | null; view: PerfSize }
102
114
  | { kind: 'mem'; tick: number; privateKB: number; heapUsedKB: number; heapTotalKB: number }
103
115
  | { kind: 'shown'; tick: number }
104
116
  | { kind: 'board'; frames: number; asleep: number }
117
+ | { kind: 'watch'; on: boolean; seq: number; why: WatchWhy }
118
+
119
+ /** Spec 30 R8 #38: the windows a shell asks for; main's own are `gesture` and `shown` (app-perf.ts `WHITEOUT_WHY`). */
120
+ export const WATCH_WHY = ['load', 'theme', 'reload'] as const
121
+ export type WatchWhy = (typeof WATCH_WHY)[number]
122
+ /** #40: a non-gesture window's end, whatever the shell says. */
123
+ export const WATCH_MAX_MS = 10_000
105
124
 
106
125
  /**
107
126
  * `mv:perf-ask` (main to canvas; on the wire `{ doc, ...PerfAsk }`). The preload answers `mem` and `shown` itself,
@@ -347,8 +366,11 @@ export interface MarverAppV1 {
347
366
  perf?(p: PerfMsg): void
348
367
  /** A3 (app 0.2): main's probe asks (the white-out detector, A3.8 #16) */
349
368
  onPerfAsk?(fn: (a: PerfProbeAsk) => void): () => void
350
- /** A3 (app 0.2): the display's refresh rate from main's `display` ask, null until one came; the shell puts it on its gesture records */
351
- perfInfo?(): { hz: number | null }
369
+ /**
370
+ * A3 (app 0.2): the display's refresh rate from main's `display` ask, null until one came; the shell puts it on its
371
+ * gesture records. `watch` (app 1.0.1, spec 30 #38): true when main takes `mv:perf` `watch` - a shell sends it only then
372
+ */
373
+ perfInfo?(): { hz: number | null; watch?: boolean }
352
374
  /**
353
375
  * A4 (app 0.3): main's `mv:open` for a clicked notice, delivered once to this document after its hello when its
354
376
  * instance lists `open` (A4.6 #29). The shell resolves the occurrence against a fresh read and answers (#30); the