@marver-design/marver 0.26.1 → 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 (109) hide show
  1. package/CHANGELOG.md +198 -0
  2. package/README.md +12 -4
  3. package/dist/{anchor-check-l-ny3UzH.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-DYG22tOe.mjs → boards-BqUqKNW8.mjs} +4 -4
  7. package/dist/{build-BDRiO_mP.mjs → build-VgNg4rr8.mjs} +8 -23
  8. package/dist/cli.mjs +45 -19
  9. package/dist/{collab-Dxg2trOK.mjs → collab-BEAcXrBb.mjs} +1 -1
  10. package/dist/{comments-BqXua-XL.mjs → comments-YEU1Zhv9.mjs} +4 -4
  11. package/dist/{context-HQ4Giw58.mjs → context-Ccjrhr1J.mjs} +3 -3
  12. package/dist/{daemon-DL6Fwq6D.mjs → daemon-Dc9AH0M3.mjs} +9 -7
  13. package/dist/detect-C0wpaePX.mjs +125 -0
  14. package/dist/dev-lock-C_FC70Mu.mjs +65 -0
  15. package/dist/dev-ri6nAlRp.mjs +1273 -0
  16. package/dist/exclusive-B1RtpeeP.mjs +150 -0
  17. package/dist/{init-D8DtrK_F.mjs → init-W0nxR1OY.mjs} +8 -6
  18. package/dist/{link-BNzLvdhI.mjs → link-CdTgn94Y.mjs} +23 -11
  19. package/dist/ls-BZ5TAtd5.mjs +38 -0
  20. package/dist/{manifest-Nl3KSVOk.mjs → manifest-aFyDmL8C.mjs} +2 -2
  21. package/dist/{marks-DyWMv_Z1.mjs → marks-BF9pNEgH.mjs} +3 -3
  22. package/dist/{marks-CKgzucHZ.mjs → marks-CnCCfAbD.mjs} +3 -3
  23. package/dist/{marver-id-gate-BjF6v4bT.mjs → marver-id-gate-D-R0hSt_.mjs} +1 -1
  24. package/dist/perf-DkAUFT6W.mjs +1319 -0
  25. package/dist/perf-jam-BaH3Lg0m.mjs +635 -0
  26. package/dist/plugin-B8UghYuF.mjs +5242 -0
  27. package/dist/{poster-BdtSKMDm.mjs → poster-BNgafWMK.mjs} +1 -1
  28. package/dist/{profile-WU9qcbIo.mjs → profile-jIS6BcAs.mjs} +1 -1
  29. package/dist/{publish-bakes-9RzRToXV.mjs → publish-bakes-38Nja78p.mjs} +3 -3
  30. package/dist/{queue-29ok5_eZ.mjs → queue-CAM_vNmX.mjs} +1 -1
  31. package/dist/recover-B8AiI29B.mjs +66 -0
  32. package/dist/{serve-C8rVheYk.mjs → serve-Dp3nHstu.mjs} +3 -3
  33. package/dist/{share--oFJ1bCI.mjs → share-Ce4tP7ji.mjs} +1 -1
  34. package/dist/{shot-XQV7HC9A.mjs → shot-CMQgMVZm.mjs} +1 -1
  35. package/dist/{shot-DQeR_Pfn.mjs → shot-Ch24tiMO.mjs} +36 -5
  36. package/dist/slots-CFNnegCc.mjs +478 -0
  37. package/dist/{sync-DKk-yT1V.mjs → sync-CQdGARJ9.mjs} +4 -3
  38. package/dist/{work-VvX_JIgl.mjs → work-Bxz-ObF3.mjs} +4 -2
  39. package/dist/{work-F5u-twpJ.mjs → work-CNhFF9pU.mjs} +5 -3
  40. package/docs/boards-and-folders.md +3 -1
  41. package/docs/jam-session.md +57 -2
  42. package/docs/performance.md +424 -0
  43. package/package.json +2 -2
  44. package/src/client/content/index.tsx +3 -0
  45. package/src/client/content/video.tsx +16 -4
  46. package/src/client/frame-host/bridge.js +22 -6
  47. package/src/client/frame-host/main.tsx +17 -5
  48. package/src/client/shell/App.tsx +188 -26
  49. package/src/client/shell/BoardList.tsx +5 -5
  50. package/src/client/shell/Comments.tsx +8 -5
  51. package/src/client/shell/ContextMenu.tsx +5 -3
  52. package/src/client/shell/JamSurface.tsx +4 -2
  53. package/src/client/shell/LockedApp.tsx +8 -5
  54. package/src/client/shell/Play.tsx +20 -10
  55. package/src/client/shell/Tip.tsx +3 -1
  56. package/src/client/shell/Toolbar.tsx +12 -1
  57. package/src/client/shell/api.ts +233 -0
  58. package/src/client/shell/app-bridge.ts +254 -0
  59. package/src/client/shell/app-perf.ts +92 -0
  60. package/src/client/shell/canvas/Canvas.tsx +141 -21
  61. package/src/client/shell/canvas/FrameNode.tsx +22 -9
  62. package/src/client/shell/canvas/admission.ts +31 -9
  63. package/src/client/shell/canvas/camera-broadcast.ts +15 -5
  64. package/src/client/shell/canvas/ctl.ts +8 -0
  65. package/src/client/shell/canvas/frame-registry.ts +28 -2
  66. package/src/client/shell/canvas/sleep.ts +60 -17
  67. package/src/client/shell/canvas/updates.ts +2 -1
  68. package/src/client/shell/comments-store.ts +12 -4
  69. package/src/client/shell/goto.ts +22 -10
  70. package/src/client/shell/inset.ts +44 -0
  71. package/src/client/shell/jam-capture.ts +41 -22
  72. package/src/client/shell/jam-keys.ts +12 -3
  73. package/src/client/shell/jam-panel.tsx +9 -3
  74. package/src/client/shell/jam-queue.ts +3 -3
  75. package/src/client/shell/jam-session.tsx +14 -8
  76. package/src/client/shell/jam-voice.ts +55 -15
  77. package/src/client/shell/legacy-links.ts +2 -2
  78. package/src/client/shell/main.tsx +18 -1
  79. package/src/client/shell/marks-ui.tsx +5 -3
  80. package/src/client/shell/marver-app.ts +21 -0
  81. package/src/client/shell/notes.ts +8 -1
  82. package/src/client/shell/perf-run-probe.ts +34 -0
  83. package/src/client/shell/perf-run.ts +70 -0
  84. package/src/client/shell/perf.ts +80 -58
  85. package/src/client/shell/recorder-core.ts +183 -0
  86. package/src/client/shell/recorder.ts +607 -0
  87. package/src/client/shell/store.ts +294 -110
  88. package/src/client/shell/styles.css +72 -15
  89. package/src/client/shell/unsaved.ts +81 -0
  90. package/src/client/shell/whiteout-probes.ts +141 -0
  91. package/src/shared/app-api.ts +205 -0
  92. package/src/shared/app-perf.ts +308 -0
  93. package/src/shared/logo-sniff.ts +86 -0
  94. package/src/shared/machine.ts +132 -0
  95. package/src/shared/perf-run.ts +177 -0
  96. package/templates/AGENTS-embedded.md +25 -4
  97. package/templates/AGENTS-studio.md +25 -4
  98. package/templates/demo/dark.tsx +1 -1
  99. package/templates/demo/welcome.tsx +1 -1
  100. package/templates/instructions/boards.md +3 -1
  101. package/templates/instructions/welcome.md +6 -3
  102. package/dist/bake-C-awKgLA.mjs +0 -786
  103. package/dist/config-Cf7EjAMf.mjs +0 -292
  104. package/dist/dev-Bw_qYWWq.mjs +0 -755
  105. package/dist/dev-lock-DWSpa6nj.mjs +0 -179
  106. package/dist/perf-C75MZ73h.mjs +0 -167
  107. package/dist/perf-DPbLGhhO.mjs +0 -49
  108. package/dist/perf-jam-BU3TVrZu.mjs +0 -239
  109. package/dist/plugin-DkGmZs_r.mjs +0 -2423
@@ -1,6 +1,7 @@
1
1
  import { memo, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
2
2
  import { cap, frameUrl, shownRev, useStore, CONFIG, type Node } from '../store.ts'
3
3
  import { admit, release } from './admission.ts'
4
+ import { canvasCtl } from './ctl.ts'
4
5
  import { CopyIcon, IntentGlyph, ParallelogramFillIcon, ReloadIcon, SlideFrameIcon, XIcon } from '../icons.tsx'
5
6
  import { CommentLayer } from '../Comments.tsx'
6
7
  import { useComments } from '../comments-store.ts'
@@ -8,12 +9,14 @@ import { threadHostKey } from '../keys.ts'
8
9
  import { registerFrame, unregisterFrame } from './frame-registry.ts'
9
10
  import { canvasClick, canvasPointer, frameGone, frameLoaded, pressNow, useJamCapture } from '../jam-capture.ts'
10
11
  import { primeCameraFor } from './camera-broadcast.ts'
11
- import { sleep, wake } from './sleep.ts'
12
+ import { scheduleSleep, sleep, wake } from './sleep.ts'
12
13
  import { canAutoReload, shouldArmReadyWatch } from './ready-watch.ts'
13
14
  import { Stickies, type NoteSpec } from './Sticky.tsx'
15
+ import { recorder } from '../recorder.ts'
14
16
  import { noteId, sceneNoteHost } from '../notes.ts'
15
17
  import { slideSize, stageFit } from '../../const.ts'
16
18
  import { FrameSlot, toneOf, useFrameMark } from '../marks-ui.tsx'
19
+ import { stranded } from '../api.ts'
17
20
 
18
21
  export const HEADER = 28
19
22
  const SNAP = 12
@@ -94,6 +97,8 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
94
97
  // survives a theme flip; file changes and reloads navigate imperatively below, only once
95
98
  // admitted - a queued frame takes the fresh revision when its turn comes.
96
99
  const [src, setSrc] = useState<string>()
100
+ // the document is another project's "another canvas" page (spec 28 A1.11): a quiet placeholder over it instead
101
+ const [away, setAway] = useState(false)
97
102
  const admitted = src !== undefined
98
103
  const admittedRef = useRef(false)
99
104
  const fileRef = useRef(frame ? `${frame.kind}:${frame.file}` : null)
@@ -104,9 +109,12 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
104
109
  useEffect(() => {
105
110
  if (!frame || node.missing) { admittedRef.current = false; setSrc(undefined); return } // gone: the card replaces the iframe; a return is a new document, admitted anew
106
111
  if (admittedRef.current) return // the document exists (the frame's id changed under it): no slot
107
- const rank = () => { // visible first, then by distance to the centre of the canvas (the panel offsets the window's)
108
- const r = iframeRef.current?.getBoundingClientRect(), c = document.querySelector('.sh-canvas')?.getBoundingClientRect()
109
- if (!r || !c) return Infinity
112
+ // visible first, then by distance to the centre of the canvas (the panel offsets the window's) - where the frame
113
+ // will be once the camera lands from a fit or zoom on its way (a board's first pick comes as the fit sets off)
114
+ const rank = () => {
115
+ const now = iframeRef.current?.getBoundingClientRect(), c = document.querySelector('.sh-canvas')?.getBoundingClientRect()
116
+ if (!now || !c) return Infinity
117
+ const r = canvasCtl.landing(now)
110
118
  const visible = r.right > c.left && r.left < c.right && r.bottom > c.top && r.top < c.bottom
111
119
  return (visible ? 0 : 1e7) + Math.hypot(r.x + r.width / 2 - c.x - c.width / 2, r.y + r.height / 2 - c.y - c.height / 2)
112
120
  }
@@ -116,6 +124,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
116
124
  if (n.status !== 'loading') setStatus(node.key, 'loading') // a returning frame boots under the watchdog like any other
117
125
  admittedRef.current = true
118
126
  setSrc(frameUrl(f, n.theme))
127
+ recorder.admitted(node.key)
119
128
  }
120
129
  admit({ key: node.key, rank, start })
121
130
  return () => release(node.key)
@@ -210,8 +219,8 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
210
219
  // one being installed
211
220
  if (interact || dirty.current || resizing.current || node.status !== 'ready' || node.stale || behind) return
212
221
  if (node.themeOn !== undefined && node.themeOn !== node.theme) return // the frame has not painted the new theme yet
213
- const t = setTimeout(() => { void sleep(node.key, iframe, { frame: frame.id, theme: node.theme, w, h, doc: node.shown }) }, 250)
214
- return () => clearTimeout(t)
222
+ // counted while it waits (sleep.ts bakeWork): a headless perf run measures only once no sleep is still to come
223
+ return scheduleSleep(() => { void sleep(node.key, iframe, { frame: frame.id, theme: node.theme, w, h, doc: node.shown }) }, 250)
215
224
  }, [interact, node.status, node.theme, node.themeOn, node.rev, node.nav, node.stale, behind, w, h, node.missing, frame?.id, node.key, resizeTick])
216
225
  useEffect(() => () => wake(node.key, iframeRef.current), [node.key])
217
226
 
@@ -271,7 +280,9 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
271
280
  // boot slot - its boot is still running - and gives it back after a second silence.
272
281
  useEffect(() => {
273
282
  if (!admitted || node.status !== 'loading' || !frame || node.missing) return
274
- const t = setTimeout(() => { if (shouldArmReadyWatch(node, true)) reloadRef.current(true); else release(node.key) }, 10_000)
283
+ // the second silence gives the slot back, and is the recorder's never-ready (spec 28 A1.7) - the frame stays
284
+ // loading, never a red card
285
+ const t = setTimeout(() => { if (shouldArmReadyWatch(node, true)) reloadRef.current(true); else { release(node.key); recorder.neverReady(node.key) } }, 10_000)
275
286
  return () => clearTimeout(t)
276
287
  // depend on the frame's stable SIGNATURE, not the manifest object - that object is replaced on
277
288
  // every manifest reconcile, so depending on it would reset the budget on unrelated frames during
@@ -433,7 +444,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
433
444
  ) : null}
434
445
  {/* a frame still silent after its one auto-retry: a slow dev server, never a failure. A quiet
435
446
  non-covering pill (not the red card) keeps it honest and offers a manual reload. */}
436
- {node.status === 'loading' && node.readyRetried ? (
447
+ {node.status === 'loading' && node.readyRetried && !away ? (
437
448
  <div className="sh-loading sh-no-pan">
438
449
  <span>still loading</span>
439
450
  <button className="sh-no-pan" onClick={() => reload(false)}>
@@ -446,9 +457,11 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
446
457
  className="sh-live"
447
458
  src={src}
448
459
  title={frame.id}
449
- onLoad={() => { registerWin(); frameLoaded(node.key, iframeRef.current) }}
460
+ onLoad={() => { setAway(stranded(iframeRef.current)); registerWin(); frameLoaded(node.key, iframeRef.current); recorder.loaded(node.key) }}
450
461
  style={{ ...iframeBox(stage, node), display: node.missing || node.status === 'error' ? 'none' : 'block' }}
451
462
  />
463
+ {/* its canvas is away from this address: one calm line, the banner says the rest */}
464
+ {away && <div className="sh-stranded"><span>Waiting for this canvas</span></div>}
452
465
  {/* the overlay eats mouse events for drag-by-body; laser and comment mode both
453
466
  need the mouse INSIDE the frame for hover highlights, so it steps aside
454
467
  (drag still works via the header) */}
@@ -10,9 +10,11 @@
10
10
  *
11
11
  * A new batch admits ONE frame first (the quickest first content: one boot alone is ~550 ms, four
12
12
  * together ~1.8 s), then up to SLOTS at a time. Pure, apart from its timing: a board that mounts
13
- * registers every node, the shell fits the camera (App.tsx, a few tens of ms later), then the first
14
- * pump ranks them (visible first, nearest the centre of the canvas first); a freed slot pumps on
15
- * the next microtask, ranking again by the view of that moment.
13
+ * registers every node, the shell aims the camera (its fit: a frame after mount at boot, 60 ms after
14
+ * on a switch; Canvas.tsx says so through aimed()), then the first pump ranks them (visible first,
15
+ * nearest the centre of the canvas first) on where each frame will be once the camera lands
16
+ * (canvasCtl.landing) - it need not wait out the fit's ~320 ms flight. With no aim it waits SETTLE, as
17
+ * long as that flight. A freed slot pumps on the next microtask, ranking again by the view of that moment.
16
18
  */
17
19
  export const SLOTS = 4
18
20
  /** A new batch's head start: one frame alone until it is done, or until this long - one stalled
@@ -21,6 +23,7 @@ export const HEAD_MS = 2000
21
23
  let primed = false // the batch may use every slot
22
24
  let gen = 0 // the batch: a pump scheduled for an earlier one is void
23
25
  let timer: ReturnType<typeof setTimeout> | undefined
26
+ let settling: ReturnType<typeof setTimeout> | undefined // a pump waiting for the view to settle (SETTLE): aimed() runs it now
24
27
 
25
28
  export interface Admission { key: string; rank: () => number; start: () => void }
26
29
 
@@ -28,30 +31,49 @@ const waiting = new Map<string, Admission>()
28
31
  const active = new Set<string>()
29
32
  let scheduled = false
30
33
 
31
- /** Ask for a slot. Starts once the view has settled (SETTLE ms) when one is free; else queued by rank. */
34
+ /** Ask for a slot. Starts once the view has settled - the camera aimed where it will rest (aimed()), else SETTLE ms -
35
+ * when one is free; else queued by rank. */
32
36
  export function admit(a: Admission): void {
33
37
  if (active.has(a.key)) return
34
38
  if (!waiting.size && !active.size) { // a new batch
35
- primed = false; gen++; scheduled = false; clearTimeout(timer)
39
+ primed = false; gen++; scheduled = false; clearTimeout(timer); clearTimeout(settling); settling = undefined
36
40
  timer = setTimeout(() => { primed = true; schedule(0) }, HEAD_MS)
37
41
  }
38
42
  waiting.set(a.key, a)
39
43
  schedule(SETTLE)
40
44
  }
41
- const SETTLE = 350 // the board fit animates ~250 ms from 60 ms after mount: rank the first pick on the settled view
45
+ /** The board fit animates ~320 ms from 60 ms after mount: with no aim said, the first pick waits for it to land and
46
+ * ranks on the settled view. */
47
+ const SETTLE = 350
48
+
49
+ /** The camera was just sent where it will rest - a fit (a board's first, ⇧1, a link's selection), a zoom, a camera
50
+ * restored (Canvas.tsx). A pump waiting for the view to settle runs now: its ranks read where each frame will be once
51
+ * the camera lands (canvasCtl.landing), so the first pick is the one SETTLE would have made, a flight earlier. */
52
+ export function aimed(): void {
53
+ if (settling === undefined) return
54
+ clearTimeout(settling); settling = undefined; scheduled = false
55
+ schedule(0)
56
+ }
42
57
 
43
58
  /** The frame is done booting (ready, error, gone, or its watchdog took over): free the slot, or
44
59
  * leave the queue if it never started. */
45
60
  export function release(key: string): void {
46
- waiting.delete(key)
61
+ const was = waiting.delete(key) || active.has(key)
47
62
  if (active.delete(key)) { primed = true; schedule(0) }
63
+ if (was && admissionIdle()) for (const fn of idle) { try { fn() } catch { /* a listener never stops the queue */ } }
48
64
  }
49
65
 
66
+ const idle = new Set<() => void>()
67
+ /** Nothing queued, nothing booting: a board load settles only then (spec 28 A1.7). */
68
+ export const admissionIdle = (): boolean => !waiting.size && !active.size
69
+ /** Called each time the last frame lets go of its slot or leaves the queue; returns the unsubscribe. */
70
+ export function onAdmissionIdle(fn: () => void): () => void { idle.add(fn); return () => { idle.delete(fn) } }
71
+
50
72
  function schedule(ms: number): void {
51
73
  if (scheduled) return
52
74
  scheduled = true
53
75
  const g = gen, run = () => { if (g === gen) pump() }
54
- if (ms) setTimeout(run, ms); else queueMicrotask(run)
76
+ if (ms) settling = setTimeout(() => { settling = undefined; run() }, ms); else queueMicrotask(run)
55
77
  }
56
78
 
57
79
  function pump(): void {
@@ -67,4 +89,4 @@ function pump(): void {
67
89
  }
68
90
 
69
91
  /** For tests: nothing queued, nothing active. */
70
- export function resetAdmission(): void { waiting.clear(); active.clear(); primed = false; scheduled = false; gen++; clearTimeout(timer) }
92
+ export function resetAdmission(): void { waiting.clear(); active.clear(); primed = false; scheduled = false; gen++; clearTimeout(timer); clearTimeout(settling); settling = undefined }
@@ -22,17 +22,27 @@ function broadcast(moving: boolean): void {
22
22
  for (const w of frameWindows()) { try { w.postMessage(msg, location.origin) } catch { /* cross-doc timing */ } }
23
23
  }
24
24
 
25
+ /** What is moving on the canvas: the camera (a pan or zoom, `sh-camera`) and the layout (a preset or tidy animation,
26
+ * `sh-preset`). The same one observer tells the shell's own listeners - the gesture sampler (perf.ts) and the
27
+ * recorder's camera idle (spec 28 A1.7) - on every change of either, so nothing polls. */
28
+ export interface Motion { camera: boolean; preset: boolean }
29
+ let motion: Motion = { camera: false, preset: false }
30
+ const motionListeners = new Set<(m: Motion) => void>()
31
+ /** Called with the new motion at each change; returns the unsubscribe. */
32
+ export function onMotion(fn: (m: Motion) => void): () => void { motionListeners.add(fn); return () => { motionListeners.delete(fn) } }
33
+
25
34
  let started = false
26
35
  export function startCameraBroadcast(): void {
27
36
  if (started) return
28
37
  const world = document.getElementById('sh-world'); if (!world) return
29
38
  started = true
30
- let moving = false
31
39
  new MutationObserver(() => {
32
- const now = world.classList.contains('sh-camera')
33
- if (now === moving) return
34
- moving = now
35
- broadcast(now) // +sh-camera -> freeze; -sh-camera -> sharpen to the settled scale
40
+ const now = { camera: world.classList.contains('sh-camera'), preset: world.classList.contains('sh-preset') }
41
+ if (now.camera === motion.camera && now.preset === motion.preset) return
42
+ const cameraChanged = now.camera !== motion.camera
43
+ motion = now
44
+ if (cameraChanged) broadcast(now.camera) // +sh-camera -> freeze; -sh-camera -> sharpen to the settled scale
45
+ for (const fn of motionListeners) { try { fn(now) } catch { /* a listener never stops the broadcast */ } }
36
46
  }).observe(world, { attributes: true, attributeFilter: ['class'] })
37
47
  }
38
48
 
@@ -29,4 +29,12 @@ export const canvasCtl = {
29
29
  /** Is the camera mid-flight (a fit, a zoom)? A content-driven reflow waits for it to land: a fit
30
30
  * aimed at the frames a link names must not land on where they were before the rows moved. */
31
31
  cameraBusy(): boolean { return false },
32
+ /** What the camera shows now, in world px (null with no canvas) - a load's visible cohort when no fit landed. */
33
+ view(): { x: number; y: number; w: number; h: number } | null { return null },
34
+ /** Where a rect on screen now will be once the camera lands from the flight it is on (a fit, a zoom) - itself while
35
+ * the camera rests: the boot queue ranks a board's first frame on the view the person will see (admission.ts). */
36
+ landing(r: DOMRect): DOMRect { return r },
37
+ /** The camera now, `{ x, y, s }` as the world is drawn (null with no canvas): the white-out probes' bracket (spec 28
38
+ * A3.8 #16) and a hide mid-flight (A3.8 #43). Assigned by Canvas.tsx from its camera. */
39
+ transform(): { x: number; y: number; s: number } | null { return null },
32
40
  }
@@ -11,8 +11,34 @@
11
11
  export interface FrameReg { key: string; iframe: HTMLIFrameElement }
12
12
 
13
13
  const byWindow = new WeakMap<WindowProxy, FrameReg>()
14
+ const byKey = new Map<string, HTMLIFrameElement>()
14
15
 
15
- export const registerFrame = (win: WindowProxy, reg: FrameReg): void => { byWindow.set(win, reg) }
16
- export const unregisterFrame = (win: WindowProxy): void => { byWindow.delete(win) }
16
+ export const registerFrame = (win: WindowProxy, reg: FrameReg): void => { byWindow.set(win, reg); byKey.set(reg.key, reg.iframe) }
17
+ export const unregisterFrame = (win: WindowProxy): void => {
18
+ const reg = byWindow.get(win)
19
+ byWindow.delete(win)
20
+ if (reg && byKey.get(reg.key) === reg.iframe) byKey.delete(reg.key)
21
+ }
22
+ /** The iframe a node shows now - the recorder reads its live document's id off it (spec 28 A1.7). */
23
+ export const iframeOf = (key: string): HTMLIFrameElement | undefined => byKey.get(key)
17
24
  export const frameByWindow = (win: unknown): FrameReg | undefined =>
18
25
  win ? byWindow.get(win as WindowProxy) : undefined
26
+
27
+ /** The id of the document an iframe shows now, as its frame bridge set it (`__mvBoot`, spec 28 A1.7) - absent while a
28
+ * new document has not run its bridge yet, or when the frame was navigated off this origin (the read throws). */
29
+ export function bootOf(iframe: HTMLIFrameElement | undefined): string | undefined {
30
+ try {
31
+ const b = (iframe?.contentWindow as { __mvBoot?: unknown } | null | undefined)?.__mvBoot
32
+ return typeof b === 'string' ? b : undefined
33
+ } catch { return undefined }
34
+ }
35
+
36
+ /** A frame's message comes from the document its iframe shows now: the URL revision the shell gave that document
37
+ * (`gen`, against the iframe's src) and the document's own id (`boot`, against the live one). A WindowProxy survives
38
+ * navigation, and a same-URL reload keeps `gen`, so only both tell the document there now from one since replaced
39
+ * whose message was still on its way. Asked before a message changes anything. */
40
+ export function fromLiveDocument(iframe: HTMLIFrameElement, data: { gen?: unknown; boot?: unknown }): boolean {
41
+ const gen = iframe.src.match(/[?&]r=(\d+)/)?.[1] ?? ''
42
+ if (String(data.gen ?? '') !== gen) return false
43
+ return typeof data.boot === 'string' && data.boot !== '' && data.boot === bootOf(iframe)
44
+ }
@@ -27,7 +27,10 @@
27
27
  */
28
28
  import { ROUTE } from '../../const.ts'
29
29
  import { BAKES, PUBLISHED } from '../store.ts'
30
+ import { api } from '../api.ts'
31
+ import { PERF_RUN } from '../perf-run.ts'
30
32
  import { readOwn, sleepRule } from '../../../shared/sleep-rule.ts'
33
+ import type { BakeWork } from '../../../shared/perf-run.ts'
31
34
 
32
35
  /** `doc`: the revision the document shows (spec 26) - the compiler refuses a document behind its frame */
33
36
  export interface SleepKey { frame: string; theme: string; w: number; h: number; doc?: string }
@@ -48,10 +51,34 @@ const keyOf = (k: SleepKey) => `${k.frame}|${k.theme}|${Math.round(k.w)}|${Math.
48
51
 
49
52
  /** What a node's DOCUMENT is asleep under, published only once its override is INSTALLED. */
50
53
  const asleep = new Map<string, { key: string; doc: Document }>()
54
+ /** How many frames are asleep now (the recorder's weight of a settled load, spec 28 A1.7). */
55
+ export const sleepingCount = (): number => asleep.size
56
+ /**
57
+ * The page's own bake work (spec 28 A3.8 #18): four counts of their own - `pending` below is the current request
58
+ * per node and survives a successful sleep, so it says nothing about idleness. `scheduled`: FrameNode's 250 ms
59
+ * timer and both retry timers, every one through `scheduleSleep()`; `running`: a sleep from its entry to its
60
+ * `finally` (fonts, the ask, the decode, the texture installed); `queued`: asks batched and not sent yet;
61
+ * `inflight`: the bake POST on its way. A headless perf run measures only once all four are zero and the server's
62
+ * own jobs for the run are too (bake.ts `jobsOf`).
63
+ */
64
+ let scheduled = 0, running = 0, inflight = 0
65
+ export const bakeWork = (): BakeWork => ({ scheduled, running, queued: queue.length, inflight })
66
+ /** All four at zero. Not the run's bake-idle: the driver adds the server's `jobsOf(run)`. */
67
+ export const bakeIdle = (): boolean => { const w = bakeWork(); return !w.scheduled && !w.running && !w.queued && !w.inflight }
68
+ /** A sleep to try in `ms` (FrameNode's settle, a compile still running, one retry of a failed compile), counted while
69
+ * it waits; the cancel stops it and its count. */
70
+ export function scheduleSleep(fn: () => void, ms: number): () => void {
71
+ scheduled++
72
+ let done = false
73
+ const t = setTimeout(() => { if (done) return; done = true; scheduled--; fn() }, ms)
74
+ return () => { if (done) return; done = true; scheduled--; clearTimeout(t) }
75
+ }
51
76
  /** The node's current request, so a stale answer (a newer sleep, a wake in between) is dropped. */
52
77
  const pending = new Map<string, number>()
53
78
  let seq = 0
54
- /** Nodes with one retry of a failed compile in flight. */
79
+ /** Nodes with a retry of a failed compile in flight - or, in a headless perf run, spent: a run's frame retries once
80
+ * until it wakes, so the run can reach bake-idle; every other canvas retries every 4 s for as long as the frame
81
+ * rests, as before 0.27.2, so a frame recovers when the server does. */
55
82
  const retried = new Set<string>()
56
83
  const RETRY_MS = 4000
57
84
  /** The server's answer for a compile still running (src/server/bake.ts COMPILING), and how many times a
@@ -92,27 +119,39 @@ function ask(key: SleepKey): Promise<Answer> {
92
119
  for (const q of batch) { const kk = keyOf(q.key); const e = byKey.get(kk); if (e) e.waiters.push(q.resolve); else byKey.set(kk, { key: q.key, waiters: [q.resolve] }) }
93
120
  const asks = [...byKey.values()].map((e) => ({ frame: e.key.frame, theme: e.key.theme, w: Math.round(e.key.w), h: Math.round(e.key.h), ...(e.key.doc ? { doc: e.key.doc } : {}) }))
94
121
  let data: { answers?: (Answer & SleepKey)[] } | null = null
95
- const index = PUBLISHED ? await staticAnswers() : null
96
- if (!index) {
97
- try {
98
- const r = await fetch(`${ROUTE}/api/bakes`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() }, body: JSON.stringify({ asks }) })
99
- data = r.ok ? await r.json() : null
100
- } catch { data = null }
101
- }
102
- for (const e of byKey.values()) {
103
- const a = index ? index[keyOf(e.key)] : data?.answers?.find((x) => keyOf(x) === keyOf(e.key))
104
- const answer: Answer = a ? (a.ok ? { ok: true, targets: a.targets } : { ok: false, error: a.error }) : { ok: false, error: 'no answer' }
105
- for (const w of e.waiters) w(answer)
106
- }
122
+ inflight++
123
+ try {
124
+ const index = PUBLISHED ? await staticAnswers() : null
125
+ if (!index) {
126
+ try {
127
+ const r = await api('bakes', { method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() }, body: JSON.stringify({ asks }) })
128
+ data = r.ok ? await r.json() : null
129
+ } catch { data = null }
130
+ }
131
+ answerAll(byKey, index, data)
132
+ } finally { inflight-- }
107
133
  }, 40)
108
134
  })
109
135
  }
136
+ /** Every waiter of a batch, its key's answer - before the POST stops counting, so the page is never idle between. */
137
+ function answerAll(byKey: Map<string, { key: SleepKey; waiters: ((a: Answer) => void)[] }>, index: Record<string, Answer> | null, data: { answers?: (Answer & SleepKey)[] } | null): void {
138
+ for (const e of byKey.values()) {
139
+ const a = index ? index[keyOf(e.key)] : data?.answers?.find((x) => keyOf(x) === keyOf(e.key))
140
+ const answer: Answer = a ? (a.ok ? { ok: true, targets: a.targets } : { ok: false, error: a.error }) : { ok: false, error: 'no answer' }
141
+ for (const w of e.waiters) w(answer)
142
+ }
143
+ }
110
144
 
111
145
  /** Put a node's live document to sleep under `key`. Resolves once the override is installed (or
112
146
  * the document was found to have no effects, or the compile failed and the frame stays live).
113
147
  * A wake or a newer sleep in the meantime supersedes it. */
114
148
  export async function sleep(nodeKey: string, iframe: HTMLIFrameElement, key: SleepKey): Promise<'asleep' | 'live'> {
115
149
  if (AWAKE) return 'live'
150
+ running++
151
+ try { return await sleepNow(nodeKey, iframe, key) } finally { running-- }
152
+ }
153
+
154
+ async function sleepNow(nodeKey: string, iframe: HTMLIFrameElement, key: SleepKey): Promise<'asleep' | 'live'> {
116
155
  const k = keyOf(key)
117
156
  const doc = iframe.contentDocument
118
157
  if (!doc?.body) return 'live'
@@ -139,7 +178,7 @@ export async function sleep(nodeKey: string, iframe: HTMLIFrameElement, key: Sle
139
178
  const was = compiling.get(nodeKey)
140
179
  const n = (was && was.key === k ? was.n : 0) + 1
141
180
  compiling.set(nodeKey, { key: k, n })
142
- if (n <= COMPILING_TRIES) { setTimeout(() => { if (current()) void sleep(nodeKey, iframe, key) }, RETRY_MS); return 'live' }
181
+ if (n <= COMPILING_TRIES) { scheduleSleep(() => { if (current()) void sleep(nodeKey, iframe, key) }, RETRY_MS); return 'live' }
143
182
  }
144
183
  // no compiler (a published canvas, a compile that failed): the pause alone, the glass live -
145
184
  // never an effect layer without its texture
@@ -153,10 +192,13 @@ export async function sleep(nodeKey: string, iframe: HTMLIFrameElement, key: Sle
153
192
  if (PUBLISHED && targets.length && doc.querySelector('meta[name="mv-bakes"]')?.getAttribute('content') !== String(BAKES)) targets = []
154
193
  if (!install(doc, targets)) return 'live'
155
194
  // a certified sleep is remembered; the pause-only fallback is not, so the next lifecycle event
156
- // asks again (a compile the source outran, a server hiccup), and one retry is scheduled now
157
- if (targets.length) { asleep.set(nodeKey, { key: k, doc }); compiling.delete(nodeKey) }
195
+ // asks again (a compile the source outran, a server hiccup), and a retry is scheduled now. A canvas retries
196
+ // every 4 s while the frame rests: the retry clears its own mark, so a failure after a failure asks again and
197
+ // the glass sleeps once the server recovers. A headless perf run's retry keeps its mark until the node wakes -
198
+ // one retry, then nothing more, or a frame the compiler refuses would keep the run from ever being bake-idle
199
+ if (targets.length) { asleep.set(nodeKey, { key: k, doc }); compiling.delete(nodeKey); retried.delete(nodeKey) }
158
200
  else if (answer.ok === false && answer.error === COMPILING) { /* out of looks: the pause alone, final */ }
159
- else if (!PUBLISHED && !retried.has(nodeKey)) { retried.add(nodeKey); setTimeout(() => { retried.delete(nodeKey); if (current()) void sleep(nodeKey, iframe, key) }, RETRY_MS) } // a static miss is final
201
+ else if (!PUBLISHED && !retried.has(nodeKey)) { retried.add(nodeKey); scheduleSleep(() => { if (!PERF_RUN) retried.delete(nodeKey); if (current()) void sleep(nodeKey, iframe, key) }, RETRY_MS) } // a static miss is final
160
202
  return 'asleep'
161
203
  }
162
204
 
@@ -165,6 +207,7 @@ export function wake(nodeKey: string, iframe: HTMLIFrameElement | null): void {
165
207
  pending.delete(nodeKey)
166
208
  asleep.delete(nodeKey)
167
209
  compiling.delete(nodeKey)
210
+ retried.delete(nodeKey)
168
211
  const doc = iframe?.contentDocument
169
212
  const st = doc?.getElementById(STYLE_ID)
170
213
  if (!doc || !st) return
@@ -7,6 +7,7 @@
7
7
  * when its turn comes.
8
8
  */
9
9
  import { admit, release } from './admission.ts'
10
+ import { canvasCtl } from './ctl.ts'
10
11
  import { frameIsLeased, useStore, type Node } from '../store.ts'
11
12
 
12
13
  const rect = (key: string) => document.querySelector(`[data-node="${CSS.escape(key)}"]`)?.getBoundingClientRect()
@@ -21,7 +22,7 @@ function onScreen(key: string): boolean {
21
22
  return r.right > c.left - mx && r.left < c.right + mx && r.bottom > c.top - my && r.top < c.bottom + my
22
23
  }
23
24
  const rank = (key: string) => () => {
24
- const r = rect(key), c = view()
25
+ const now = rect(key), c = view(), r = now && canvasCtl.landing(now) // where it will be once a camera flight lands
25
26
  return r && c ? Math.hypot(r.x + r.width / 2 - c.x - c.width / 2, r.y + r.height / 2 - c.y - c.height / 2) : Infinity
26
27
  }
27
28
 
@@ -11,6 +11,7 @@ import { playPing } from './sound.ts'
11
11
  import { ROUTE } from '../const.ts'
12
12
  import { ALL_SCENES } from '../../shared/board-tree.ts'
13
13
  import { UNPLACED } from './hash.ts'
14
+ import { api as request, canvasStopped, scoped, stoppedLink, useLink } from './api.ts'
14
15
 
15
16
  /** What the Not on a board view says when asked for a comment: a note needs a board to live on. */
16
17
  export const NO_COMMENTS_HERE = 'pin it on a board to comment'
@@ -81,11 +82,11 @@ interface CommentsState {
81
82
 
82
83
  const uuid = () => crypto.randomUUID()
83
84
  const loadMentionSeen = (): Record<string, number> => {
84
- try { return JSON.parse(localStorage.getItem('mv-mention-seen') ?? '{}') } catch { return {} }
85
+ try { return JSON.parse(localStorage.getItem(scoped('mv-mention-seen')) ?? '{}') } catch { return {} }
85
86
  }
86
87
  const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
87
88
  const api = async (path: string, body?: unknown) => {
88
- const res = await fetch(`${ROUTE}/api/${path}`, body === undefined ? undefined : {
89
+ const res = await request(path, body === undefined ? undefined : {
89
90
  method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() },
90
91
  body: JSON.stringify(body),
91
92
  })
@@ -360,14 +361,15 @@ export const useComments = create<CommentsState>((set, get) => {
360
361
  },
361
362
 
362
363
  // the Not on a board view shows threads but takes no new ones (spec 26): a note needs a board
363
- setMode(on) { if (on && get().board === UNPLACED) return; set({ commentMode: on, ...(on ? { show: true } : { draft: null }) }) },
364
+ // never on while the canvas is stopped (spec 28 A1.11): a comment picked could not be sent
365
+ setMode(on) { if (on && (get().board === UNPLACED || canvasStopped())) return; set({ commentMode: on, ...(on ? { show: true } : { draft: null }) }) },
364
366
  setShow(show) { set({ show }) },
365
367
  setShowAnchor(showAnchor) { set({ showAnchor }) },
366
368
  setActive(active) {
367
369
  // opening a thread is SEEING it - the mention pulse for it stops here
368
370
  if (active) {
369
371
  const mentionSeen = { ...get().mentionSeen, [active]: Date.now() }
370
- try { localStorage.setItem('mv-mention-seen', JSON.stringify(mentionSeen)) } catch { /* private mode */ }
372
+ try { localStorage.setItem(scoped('mv-mention-seen'), JSON.stringify(mentionSeen)) } catch { /* private mode */ }
371
373
  set({ active, mentionSeen })
372
374
  } else set({ active })
373
375
  },
@@ -403,6 +405,12 @@ export const useComments = create<CommentsState>((set, get) => {
403
405
  }
404
406
  })
405
407
 
408
+ // the canvas stopped (spec 28 A1.11): comment mode goes off - a pick could open only a comment that cannot be
409
+ // sent. A comment being written stays, words and all.
410
+ useLink.subscribe((l, p) => {
411
+ if (stoppedLink(l.link) && !stoppedLink(p.link) && useComments.getState().commentMode && !useComments.getState().draft) useComments.getState().setMode(false)
412
+ })
413
+
406
414
  // dev-only debug handle - the canvas store exposes the same
407
415
  if (typeof window !== 'undefined' && (import.meta as any).env?.DEV) (window as any).__mvComments = useComments
408
416
 
@@ -13,10 +13,10 @@ export function goTo(target: string, carry = false): void {
13
13
  const s = useStore.getState()
14
14
  const existing = s.nodes.find((n) => n.frame === target && !n.missing)
15
15
  if (existing) {
16
- navigated() // a local goto supersedes any cross-board one in flight
16
+ const seq = navigated() // a local goto supersedes any cross-board one in flight
17
17
  s.select(existing.key)
18
18
  if (carry) s.setInteract(existing.key)
19
- setTimeout(() => canvasCtl.fitNode(existing.key), 50)
19
+ fitLater(existing.key, seq)
20
20
  } else void gotoAcrossBoards(target, carry)
21
21
  }
22
22
 
@@ -50,7 +50,7 @@ async function gotoAcrossBoards(target: string, carry: boolean) {
50
50
  if (!node) return st.toast(`unknown goto target "${target}"`)
51
51
  st.select(node.key)
52
52
  if (carry) st.setInteract(node.key)
53
- setTimeout(() => canvasCtl.fitNode(node.key), 50)
53
+ fitLater(node.key, seq)
54
54
  return
55
55
  }
56
56
  await landOn(home, target, carry, seq, from)
@@ -59,7 +59,8 @@ async function gotoAcrossBoards(target: string, carry: boolean) {
59
59
  /** Navigation supersedes any goto or reveal still on its way - its board lookup (gotoSeq) AND a board
60
60
  * switch it already started (a switch to the board on screen cancels any pending one: store.ts) - so
61
61
  * a slow lookup can never yank the view away from where the human has gone since. Every entry point
62
- * calls it: a pasted link, back/forward, a goto, a reveal, a board picked in the sidebar. */
62
+ * calls it, the published shell's too: a pasted link, back/forward, a goto, a reveal, a board picked in
63
+ * the sidebar or the play pill, a notification's View - and switches boards only through switchFor. */
63
64
  export function navigated(): number {
64
65
  const s = useStore.getState()
65
66
  if (s.board) void s.switchBoard(s.board)
@@ -67,12 +68,23 @@ export function navigated(): number {
67
68
  }
68
69
  /** Is this still the latest navigation - nothing newer since `navigated()` handed it out? */
69
70
  export const isLatest = (seq: number): boolean => seq === gotoSeq
71
+ /** The one way a navigation changes boards - a link, a goto, a reveal, a board picked in the sidebar or the play pill, a
72
+ * notification's View: the switch is navigation `nav`'s (a new one, unless the caller took it at its own start, before
73
+ * a lookup), and true only once it landed with nothing newer since. What the caller does on the board - select, set a
74
+ * mode, enter play, move the camera - waits for true: a switch a newer navigation cancelled comes back too, and may
75
+ * find the board it asked for, the newer one's by then. */
76
+ export async function switchFor(board: string, nav: number = navigated()): Promise<boolean> {
77
+ await useStore.getState().switchBoard(board)
78
+ return isLatest(nav) && useStore.getState().board === board
79
+ }
80
+ /** The camera to a node once it is drawn - unless a newer navigation has it by then. */
81
+ const fitLater = (key: string, seq: number) => setTimeout(() => { if (isLatest(seq)) canvasCtl.fitNode(key) }, 50)
70
82
 
71
83
  /** Switch to `home` and select + fit `target` there once the board commits - unless the human has
72
84
  * moved on: newer navigation, or a board they switched to themselves while the lookup ran. */
73
85
  async function landOn(home: string, target: string, carry: boolean, seq: number, from: string) {
74
86
  if (seq !== gotoSeq || useStore.getState().board !== from) return
75
- await useStore.getState().switchBoard(home)
87
+ if (!await switchFor(home, seq)) return
76
88
  for (let i = 0; i < 12; i++) { // the board commits async - retry like viewNote
77
89
  if (seq !== gotoSeq) return
78
90
  const st = useStore.getState()
@@ -81,7 +93,7 @@ async function landOn(home: string, target: string, carry: boolean, seq: number,
81
93
  if (node) {
82
94
  st.select(node.key)
83
95
  if (carry) st.setInteract(node.key)
84
- setTimeout(() => canvasCtl.fitNode(node.key), 50)
96
+ fitLater(node.key, seq)
85
97
  return
86
98
  }
87
99
  }
@@ -93,17 +105,17 @@ async function landOn(home: string, target: string, carry: boolean, seq: number,
93
105
  * not show, the way back from a focus link): this board, else the first board that shows it
94
106
  * (archive boards last), else - a frame on no board - the Not on a board view. Unlike a goto it
95
107
  * never spawns - opening a link must not edit a board. */
96
- export async function revealFrame(target: string): Promise<void> {
108
+ export async function revealFrame(target: string, nav?: number): Promise<void> { // `nav`: a caller's navigation, else its own
97
109
  const s = useStore.getState()
98
110
  const here = s.nodes.find((n) => n.frame === target && !n.missing)
99
111
  if (here) {
100
- navigated()
112
+ const seq = nav ?? navigated()
101
113
  s.select(here.key)
102
- setTimeout(() => canvasCtl.fitNode(here.key), 50)
114
+ fitLater(here.key, seq)
103
115
  return
104
116
  }
105
117
  if (!s.manifest?.frames.some((f) => f.id === target)) return s.toast(`no frame "${target}" on this canvas`)
106
- const seq = navigated()
118
+ const seq = nav ?? navigated()
107
119
  const from = s.board
108
120
  let home: string | null = null
109
121
  try {
@@ -0,0 +1,44 @@
1
+ /**
2
+ * The one usable-rectangle helper (spec 28 A2.9 v1.8 #6, A3.8 #31): where the shell may place what a person must
3
+ * see, under the Mac app's transparent strip. Owner: the one-ground stream (marver 0.27.2).
4
+ *
5
+ * `TOP` is 44 only when the app says this document must apply it (`topInset`, from `mv:doc`'s answer) **and** the
6
+ * presentation contract is whole (`onPresent` and `presented`): a shell never trusts half a contract, so in Chrome,
7
+ * on a published canvas, under `marver shot` and inside app 0.1 it is 0 and nothing moves. `--mv-top` goes on
8
+ * `:root` (some portals mount outside `.sh-app`), and every rule reads `var(--mv-top, 0px)`.
9
+ *
10
+ * FROZEN before the A3 streams split (A3.8 #53): `TOP`, `VISIBLE_TOP`, `usable()`, `onScreen()` and `applyInset()`.
11
+ * Consumers: the top-anchored layers, the selection bar, tips and menus (`TOP + 8`), insets(), focus, play sizes
12
+ * and Jam's fill use `usable()`; seen marks, visibleNodes(), A3.3's probes and A4.3's full-view test use `onScreen()`.
13
+ */
14
+ import { EDGE_FADE, TOP_INSET, type Inset } from '../../shared/app-api.ts'
15
+ import { APP } from './marver-app.ts'
16
+
17
+ /** 44 in app 0.2+ for a document main placed full height, with the presentation channel to match; else 0. */
18
+ export const TOP: Inset = APP?.topInset === TOP_INSET && typeof APP.onPresent === 'function' && typeof APP.presented === 'function' ? TOP_INSET : 0
19
+ /** Below the scroll edge: what counts as seen. 0 with no inset (Chrome is unchanged). */
20
+ export const VISIBLE_TOP = TOP ? TOP + EDGE_FADE : 0
21
+
22
+ /** main.tsx, before the first render: the variable every placement reads, on :root. Nothing without the inset. */
23
+ export function applyInset(): void {
24
+ if (!TOP) return
25
+ document.documentElement.style.setProperty('--mv-top', `${TOP}px`)
26
+ document.documentElement.classList.add('mv-inset')
27
+ }
28
+
29
+ /** The view below the strip, in client px. */
30
+ export function usable(): { top: number; left: number; width: number; height: number } {
31
+ return { top: TOP, left: 0, width: innerWidth, height: Math.max(0, innerHeight - TOP) }
32
+ }
33
+
34
+ /** The part of a client rect on screen below the scroll edge, or null when none is. */
35
+ export function onScreen(r: DOMRectReadOnly): DOMRect | null {
36
+ const top = Math.max(r.top, VISIBLE_TOP)
37
+ const bottom = Math.min(r.bottom, innerHeight)
38
+ const left = Math.max(r.left, 0)
39
+ const right = Math.min(r.right, innerWidth)
40
+ return bottom > top && right > left ? new DOMRect(left, top, right - left, bottom - top) : null
41
+ }
42
+
43
+ // dev-only inspection hook for tests (never installed in published builds)
44
+ if (typeof window !== 'undefined' && (import.meta as { env?: { DEV?: boolean } }).env?.DEV) (window as unknown as { __mvInset: unknown }).__mvInset = { TOP, VISIBLE_TOP, usable, onScreen }