@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.
- package/CHANGELOG.md +198 -0
- package/README.md +12 -4
- package/dist/{anchor-check-l-ny3UzH.mjs → anchor-check-gkxkPAIv.mjs} +1 -1
- package/dist/{board-tree-DRioF94d.mjs → board-tree-BXR8dw4b.mjs} +3 -1
- package/dist/{boards-CGg6piKF.mjs → boards-BHKP5yhI.mjs} +1 -1
- package/dist/{boards-DYG22tOe.mjs → boards-BqUqKNW8.mjs} +4 -4
- package/dist/{build-BDRiO_mP.mjs → build-VgNg4rr8.mjs} +8 -23
- package/dist/cli.mjs +45 -19
- package/dist/{collab-Dxg2trOK.mjs → collab-BEAcXrBb.mjs} +1 -1
- package/dist/{comments-BqXua-XL.mjs → comments-YEU1Zhv9.mjs} +4 -4
- package/dist/{context-HQ4Giw58.mjs → context-Ccjrhr1J.mjs} +3 -3
- package/dist/{daemon-DL6Fwq6D.mjs → daemon-Dc9AH0M3.mjs} +9 -7
- package/dist/detect-C0wpaePX.mjs +125 -0
- package/dist/dev-lock-C_FC70Mu.mjs +65 -0
- package/dist/dev-ri6nAlRp.mjs +1273 -0
- package/dist/exclusive-B1RtpeeP.mjs +150 -0
- package/dist/{init-D8DtrK_F.mjs → init-W0nxR1OY.mjs} +8 -6
- package/dist/{link-BNzLvdhI.mjs → link-CdTgn94Y.mjs} +23 -11
- package/dist/ls-BZ5TAtd5.mjs +38 -0
- package/dist/{manifest-Nl3KSVOk.mjs → manifest-aFyDmL8C.mjs} +2 -2
- package/dist/{marks-DyWMv_Z1.mjs → marks-BF9pNEgH.mjs} +3 -3
- package/dist/{marks-CKgzucHZ.mjs → marks-CnCCfAbD.mjs} +3 -3
- package/dist/{marver-id-gate-BjF6v4bT.mjs → marver-id-gate-D-R0hSt_.mjs} +1 -1
- package/dist/perf-DkAUFT6W.mjs +1319 -0
- package/dist/perf-jam-BaH3Lg0m.mjs +635 -0
- package/dist/plugin-B8UghYuF.mjs +5242 -0
- package/dist/{poster-BdtSKMDm.mjs → poster-BNgafWMK.mjs} +1 -1
- package/dist/{profile-WU9qcbIo.mjs → profile-jIS6BcAs.mjs} +1 -1
- package/dist/{publish-bakes-9RzRToXV.mjs → publish-bakes-38Nja78p.mjs} +3 -3
- package/dist/{queue-29ok5_eZ.mjs → queue-CAM_vNmX.mjs} +1 -1
- package/dist/recover-B8AiI29B.mjs +66 -0
- package/dist/{serve-C8rVheYk.mjs → serve-Dp3nHstu.mjs} +3 -3
- package/dist/{share--oFJ1bCI.mjs → share-Ce4tP7ji.mjs} +1 -1
- package/dist/{shot-XQV7HC9A.mjs → shot-CMQgMVZm.mjs} +1 -1
- package/dist/{shot-DQeR_Pfn.mjs → shot-Ch24tiMO.mjs} +36 -5
- package/dist/slots-CFNnegCc.mjs +478 -0
- package/dist/{sync-DKk-yT1V.mjs → sync-CQdGARJ9.mjs} +4 -3
- package/dist/{work-VvX_JIgl.mjs → work-Bxz-ObF3.mjs} +4 -2
- package/dist/{work-F5u-twpJ.mjs → work-CNhFF9pU.mjs} +5 -3
- package/docs/boards-and-folders.md +3 -1
- package/docs/jam-session.md +57 -2
- package/docs/performance.md +424 -0
- package/package.json +2 -2
- package/src/client/content/index.tsx +3 -0
- package/src/client/content/video.tsx +16 -4
- package/src/client/frame-host/bridge.js +22 -6
- package/src/client/frame-host/main.tsx +17 -5
- package/src/client/shell/App.tsx +188 -26
- package/src/client/shell/BoardList.tsx +5 -5
- package/src/client/shell/Comments.tsx +8 -5
- package/src/client/shell/ContextMenu.tsx +5 -3
- package/src/client/shell/JamSurface.tsx +4 -2
- package/src/client/shell/LockedApp.tsx +8 -5
- package/src/client/shell/Play.tsx +20 -10
- package/src/client/shell/Tip.tsx +3 -1
- package/src/client/shell/Toolbar.tsx +12 -1
- package/src/client/shell/api.ts +233 -0
- package/src/client/shell/app-bridge.ts +254 -0
- package/src/client/shell/app-perf.ts +92 -0
- package/src/client/shell/canvas/Canvas.tsx +141 -21
- package/src/client/shell/canvas/FrameNode.tsx +22 -9
- package/src/client/shell/canvas/admission.ts +31 -9
- package/src/client/shell/canvas/camera-broadcast.ts +15 -5
- package/src/client/shell/canvas/ctl.ts +8 -0
- package/src/client/shell/canvas/frame-registry.ts +28 -2
- package/src/client/shell/canvas/sleep.ts +60 -17
- package/src/client/shell/canvas/updates.ts +2 -1
- package/src/client/shell/comments-store.ts +12 -4
- package/src/client/shell/goto.ts +22 -10
- package/src/client/shell/inset.ts +44 -0
- package/src/client/shell/jam-capture.ts +41 -22
- package/src/client/shell/jam-keys.ts +12 -3
- package/src/client/shell/jam-panel.tsx +9 -3
- package/src/client/shell/jam-queue.ts +3 -3
- package/src/client/shell/jam-session.tsx +14 -8
- package/src/client/shell/jam-voice.ts +55 -15
- package/src/client/shell/legacy-links.ts +2 -2
- package/src/client/shell/main.tsx +18 -1
- package/src/client/shell/marks-ui.tsx +5 -3
- package/src/client/shell/marver-app.ts +21 -0
- package/src/client/shell/notes.ts +8 -1
- package/src/client/shell/perf-run-probe.ts +34 -0
- package/src/client/shell/perf-run.ts +70 -0
- package/src/client/shell/perf.ts +80 -58
- package/src/client/shell/recorder-core.ts +183 -0
- package/src/client/shell/recorder.ts +607 -0
- package/src/client/shell/store.ts +294 -110
- package/src/client/shell/styles.css +72 -15
- package/src/client/shell/unsaved.ts +81 -0
- package/src/client/shell/whiteout-probes.ts +141 -0
- package/src/shared/app-api.ts +205 -0
- package/src/shared/app-perf.ts +308 -0
- package/src/shared/logo-sniff.ts +86 -0
- package/src/shared/machine.ts +132 -0
- package/src/shared/perf-run.ts +177 -0
- package/templates/AGENTS-embedded.md +25 -4
- package/templates/AGENTS-studio.md +25 -4
- package/templates/demo/dark.tsx +1 -1
- package/templates/demo/welcome.tsx +1 -1
- package/templates/instructions/boards.md +3 -1
- package/templates/instructions/welcome.md +6 -3
- package/dist/bake-C-awKgLA.mjs +0 -786
- package/dist/config-Cf7EjAMf.mjs +0 -292
- package/dist/dev-Bw_qYWWq.mjs +0 -755
- package/dist/dev-lock-DWSpa6nj.mjs +0 -179
- package/dist/perf-C75MZ73h.mjs +0 -167
- package/dist/perf-DPbLGhhO.mjs +0 -49
- package/dist/perf-jam-BU3TVrZu.mjs +0 -239
- package/dist/plugin-DkGmZs_r.mjs +0 -2423
|
@@ -0,0 +1,424 @@
|
|
|
1
|
+
# Performance
|
|
2
|
+
|
|
3
|
+
The canvas measures itself while you work, on your Mac: what each edit reloaded, what each board load
|
|
4
|
+
did, how long each step of Jam took. `npx marver perf` reads it back - for you, and with `--json` for your
|
|
5
|
+
agent. A published canvas records nothing.
|
|
6
|
+
|
|
7
|
+
## What is recorded
|
|
8
|
+
|
|
9
|
+
| Log | What | Read with |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| `design/.local/perf/reloads.jsonl` | each edit and the frames it reached; page-wide reloads, sent or dropped; each frame document that booted, and how long it took | `npx marver perf` |
|
|
12
|
+
| `design/.local/perf/page.jsonl` | each board load, as the page saw it: every frame's outcome, every move and why, when the board settled; gestures; errors | `npx marver perf --loads` |
|
|
13
|
+
| `design/.local/perf/jam.jsonl` | Jam's timings: numbers and fixed codes only, never your words | `npx marver perf --jam` |
|
|
14
|
+
| `design/.local/perf/runs.jsonl` | each headless run of a board (`npx marver perf run <board>`): one line, its numbers and whether it is valid | `npx marver perf --runs` |
|
|
15
|
+
|
|
16
|
+
`design/.local/` is gitignored, and `marver dev` never serves it. The perf folder is yours alone: mode 700,
|
|
17
|
+
each file 600 from the moment it is made - and files an earlier version made are tightened when `marver dev`
|
|
18
|
+
starts. At start, each log loses its lines older than 14 days, and past its cap its oldest half; a log that
|
|
19
|
+
passes its cap while the canvas runs loses its oldest half too. The cap is 2 MB, and 8 MB for `page.jsonl`:
|
|
20
|
+
one load of a 120-frame board writes about 140 KB there, most of it moves, so 2 MB held about fourteen such
|
|
21
|
+
loads - hours of work, not days. 8 MB holds four times as many.
|
|
22
|
+
|
|
23
|
+
`page.jsonl` holds frame names, node keys and numbers. Error messages and stack lines can hold file paths,
|
|
24
|
+
so, like the rest, they stay on this Mac.
|
|
25
|
+
|
|
26
|
+
## A board load
|
|
27
|
+
|
|
28
|
+
Each time a board opens - the page's first (`boot`), another board you chose (`switch`), or the open board
|
|
29
|
+
read again because its file changed on disk (`disk-reload`) - the page follows it until it settles:
|
|
30
|
+
|
|
31
|
+
1. **Requested.** The board, and why it loads. Until it mounts, every move belongs to the board still up.
|
|
32
|
+
2. **Committed.** It mounts: its frames by kind (hi-fi, content, HTML), how many are content frames that
|
|
33
|
+
measure their own height, and how many of those open at a height already known.
|
|
34
|
+
3. **Visible.** The frames the first camera fit shows - the ones you see first.
|
|
35
|
+
4. **Each frame's outcome** - [below](#frames).
|
|
36
|
+
5. **Quiet.** The first second after it mounts with nothing moving, written as that second ends: it says
|
|
37
|
+
when the move before it came (the mount itself, when nothing had moved yet). It is not when the board
|
|
38
|
+
stopped moving - a frame that reports its height later moves it again. That is the **last move**, on
|
|
39
|
+
the record that ends the load, settled or cut. `perf --loads` prints only the last move (`still from`);
|
|
40
|
+
`quiet` is in `--json`.
|
|
41
|
+
6. **Settled.** Every frame at its outcome, no re-flow pending or held, no frame booting or waiting its
|
|
42
|
+
turn to, the camera still, and the board still for one second after its last change - its last move, or
|
|
43
|
+
the mount when nothing moved - so a load never settles in under a second. It says how many moves and why,
|
|
44
|
+
when the last one came, when the visible frames and all the frames were ready, and how heavy the board
|
|
45
|
+
is: elements, frames awake and asleep, the heap (in Chrome).
|
|
46
|
+
|
|
47
|
+
Or **cut**: another board (`switch`), the same board loaded again (`reload`), the page hidden (`hidden`),
|
|
48
|
+
or 120 s without settling (`timeout`). A request that never mounted is cut too: a newer load
|
|
49
|
+
(`superseded`), a board that could not be read (`error`), your edits while it was read from disk
|
|
50
|
+
(`edited`), or a switch away from a board that could not be saved (`unsaved`). A request cut at 120 s or
|
|
51
|
+
while the page was hidden may still mount when its board arrives: its commit then says it came after the
|
|
52
|
+
cut (`late`), the cut stays, and what the board does from then is late.
|
|
53
|
+
|
|
54
|
+
## Reading `perf --loads`
|
|
55
|
+
|
|
56
|
+
A board of three content frames, `checkout`, titled "Checkout flow", opened twice. The first time no height
|
|
57
|
+
was known; the second time the heights the first load settled at were in `design/boards/_sizes.json`:
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
$ npx marver perf --loads
|
|
61
|
+
board loads, last 60 min - design/.local/perf/page.jsonl
|
|
62
|
+
|
|
63
|
+
3:41:36 PM Checkout flow (boot) settled 1.8 s
|
|
64
|
+
committed 0.0 s · 3 frames (3 content) · 3 measure, 0 opened at a known height
|
|
65
|
+
first frame started 0.05 s · visible ready 0.2 s (3 frames) · all ready 0.2 s · still from 0.8 s · settled 1.8 s
|
|
66
|
+
5 moves, 1650 px: measure-height 3, reflow:measured 2
|
|
67
|
+
slowest to settle: checkout/risks 0.4 s (waited 0.11 s, then 0.28 s), checkout/flows 0.3 s (waited 0.11 s, then 0.18 s), checkout/brief 0.3 s (waited 0.05 s, then 0.24 s)
|
|
68
|
+
|
|
69
|
+
3:42:03 PM Checkout flow (boot) settled 1.0 s
|
|
70
|
+
committed 0.0 s · 3 frames (3 content) · 3 measure, 3 opened at a known height
|
|
71
|
+
first frame started 0.05 s · visible ready 0.2 s (3 frames) · all ready 0.2 s · still from 0.0 s · settled 1.0 s
|
|
72
|
+
0 moves
|
|
73
|
+
slowest to settle: checkout/risks 0.3 s (waited 0.11 s, then 0.18 s), checkout/flows 0.3 s (waited 0.11 s, then 0.18 s), checkout/brief 0.2 s (waited 0.05 s, then 0.14 s)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Each load names its board as the sidebar does - its title, else its name - and `--json` by its name
|
|
77
|
+
(`board`). The first load opened each frame at a guess: each reported its height (`measure-height`) and
|
|
78
|
+
the frames below moved with the re-flow (`reflow:measured`) - five moves, the last at 0.8 s: still from
|
|
79
|
+
0.8 s, settled at 1.8 s. The second opened at the known heights: nothing moved, so it was still from the
|
|
80
|
+
mount, and it settled at 1.0 s, the one-second floor.
|
|
81
|
+
|
|
82
|
+
**Ready and settled are two clocks.** A frame is *ready* at its first render: `visible ready` and `all
|
|
83
|
+
ready` say when the last of the frames in view, and of all the frames, was. A content frame that measures
|
|
84
|
+
its own height has *settled* at its last height, later; `slowest to settle` lists the frames that took
|
|
85
|
+
longest to reach that (ready, for a frame that does not measure), so its times can come after `all ready`.
|
|
86
|
+
The board has *settled* once every frame has, and it has been still for one second after its last change:
|
|
87
|
+
`still from` says when that stillness began - its last move, or the mount when nothing moved - and
|
|
88
|
+
`settled` comes a second after it at the soonest, later when a frame was still on its way.
|
|
89
|
+
|
|
90
|
+
Each frame in `slowest to settle` says how long it waited for its turn to start, then how long it took once
|
|
91
|
+
started. The canvas starts a board's frames a few at a time: the first alone, as the board's first camera fit
|
|
92
|
+
sets off - a frame after the board mounts, 0.06 s later on a switch: `first frame started` - chosen as the
|
|
93
|
+
one nearest the centre of where the fit will land, then up to four at once, those in view first. Here every
|
|
94
|
+
frame took a quarter of a second or less of its own, and none waited much more than a tenth of one.
|
|
95
|
+
|
|
96
|
+
`--json` also has `quietMs`: when the first still second after the mount began. On a heavy board they part:
|
|
97
|
+
one that held still for a second after a move at 1.8 s, then moved again as late frames reported their
|
|
98
|
+
heights, has `quietMs` 1800 and says `still from 15.0 s`. The printed report leaves `quiet` out: the settle
|
|
99
|
+
waits on the last move, not the first still second.
|
|
100
|
+
|
|
101
|
+
A load that was cut has no ready times to give; it says how many of its frames were ready by the cut
|
|
102
|
+
instead - `69 of 121 ready`, of the frames on the board then (those placed while it loaded included, those
|
|
103
|
+
removed not) - when it last moved (`last move`: it never settled, so nothing was still from then), and,
|
|
104
|
+
after its slowest, how many never finished (`52 never finished`): `slowest to settle` lists only frames
|
|
105
|
+
that finished. A load can also say `never ready: ...`, `missing: ...`, its
|
|
106
|
+
errors (`late error` for one after it ended, settled or cut), how many errors past the first 50 went
|
|
107
|
+
unrecorded, and its gestures (how many, the worst p95, the frames over 33 ms). The last line says how many
|
|
108
|
+
records never reached the log, when any did.
|
|
109
|
+
|
|
110
|
+
## Making a board faster
|
|
111
|
+
|
|
112
|
+
Read the load, name the lever, change it, compare the next load - you, or your agent with
|
|
113
|
+
`npx marver perf --loads --json`.
|
|
114
|
+
|
|
115
|
+
- **Moves named `measure-height`, then `reflow:...`** - the board opened before it knew its heights.
|
|
116
|
+
`marver dev` writes each content frame's settled height to `design/boards/_sizes.json`
|
|
117
|
+
([Sizes](boards-and-folders.md#sizes)), and the next load opens at those heights (`savedHeights`
|
|
118
|
+
counts them) and the moves go, as above. Commit it with the rest of `design/`, and every clone and the
|
|
119
|
+
published canvas open at them too.
|
|
120
|
+
- **`slowest to settle`** names the frames that held the load longest, of those that finished. Look at those first:
|
|
121
|
+
what they load, how much they render - the time after `then` is the frame's own. A load cut before its frames
|
|
122
|
+
finished counts the rest apart; cut at 120 s (`timeout`), the board is too heavy to finish - split it, or
|
|
123
|
+
lighten what its frames load.
|
|
124
|
+
- **A frame that waits long to start: the queue, not the frame.** `waited` (and `first frame started`) is the
|
|
125
|
+
time before its turn came; nothing in the frame shortens it. On a board of many frames the last wait for those
|
|
126
|
+
before them: fewer frames on the board, or lighter ones that hand their turn on sooner. The first frame's wait
|
|
127
|
+
is the canvas's own and about the same on every board - 0.03-0.08 s on a page's first load, 0.08-0.11 s on a
|
|
128
|
+
switch, the time until the camera's first fit sets off - and a one-frame board that settles at 1.0 s has no
|
|
129
|
+
lever left in the project.
|
|
130
|
+
- **The canvas's own lever, taken in 0.27.2.** Until 0.27.0 the first frame waited 0.35 s after the board
|
|
131
|
+
mounted, for the first camera fit to land (`SETTLE` in `canvas/admission.ts`): that wait exists so the first
|
|
132
|
+
frame - booting alone, the quickest first content - is the one nearest the centre of the view you will see,
|
|
133
|
+
not of a camera still on its way. It now starts as the fit sets off, ranked on where the fit will land
|
|
134
|
+
(`canvasCtl.landing`); with no fit said (a frame added, a calm update), it waits as before. Measured on a
|
|
135
|
+
real project's boards - four of them, each opened three times in a fresh tab (`boot`) and three times picked
|
|
136
|
+
from another board (`switch`), headless Chrome at 1440x900, `perf --loads --json`, medians in ms (every frame
|
|
137
|
+
was in view, so visible ready and all ready are the same):
|
|
138
|
+
|
|
139
|
+
| board, frames | load | first frame started | ready | settled | moves |
|
|
140
|
+
|---|---|---|---|---|---|
|
|
141
|
+
| v1 build, 4 content | boot | 392 → 39 | 672 → 251 | 1051 → 1025 | 0 → 0 |
|
|
142
|
+
| v1 lo-fi, 30 | boot | 425 → 83 | 1306 → 1039 | 1370 → 1087 | 0 → 0 |
|
|
143
|
+
| Meeting, 14 | boot | 409 → 64 | 769 → 504 | 1029 → 1027 | 0 → 0 |
|
|
144
|
+
| Capture, 13 | boot | 404 → 52 | 721 → 457 | 1028 → 1019 | 0 → 0 |
|
|
145
|
+
| v1 build | switch | 369 → 82 | 613 → 500 | 1005 → 1005 | 0 → 0 |
|
|
146
|
+
| v1 lo-fi | switch | 395 → 112 | 1187 → 912 | 1194 → 1007 | 0 → 0 |
|
|
147
|
+
| Meeting | switch | 388 → 103 | 752 → 472 | 1005 → 1005 | 0 → 0 |
|
|
148
|
+
| Capture | switch | 380 → 93 | 636 → 377 | 1005 → 1005 | 0 → 0 |
|
|
149
|
+
|
|
150
|
+
Every board's first frame was the same one before and after. What it costs: that frame boots during the
|
|
151
|
+
fit's 0.32 s zoom over blank cards, which draws a frame or two fewer - over the twelve switches, 221 frames
|
|
152
|
+
drawn instead of 241, 18 intervals over 17 ms instead of 3 (4 over 33 ms instead of 3, none over 50 ms).
|
|
153
|
+
The boards that settle at 1.0 s were already at the one-second floor; a board whose frames finish later
|
|
154
|
+
settles sooner.
|
|
155
|
+
- **Never ready, missing, errors** are broken frames, not slow ones: fix them first. A missing frame's
|
|
156
|
+
file was deleted or renamed.
|
|
157
|
+
- **The weight** (`settled.weight`) says how heavy the settled board is: elements in the page and its
|
|
158
|
+
frames, frames awake and asleep, the heap.
|
|
159
|
+
- **Late moves** came after the load ended - settled, or cut. After a cut at 120 s, or while the page was
|
|
160
|
+
hidden, they are the board still loading. After it settled - and any **`unknown`** move, with no cause
|
|
161
|
+
named - they say something moved the board after it looked done: worth a look, or an
|
|
162
|
+
[issue](https://github.com/TNEP4/marver/issues).
|
|
163
|
+
|
|
164
|
+
## Frames
|
|
165
|
+
|
|
166
|
+
Each frame of a load ends at one outcome:
|
|
167
|
+
|
|
168
|
+
- **settled** - a content frame that renders a `Doc` measures its own height, and is done at its first
|
|
169
|
+
settled measurement taken at its current width (a width change waits for the next one);
|
|
170
|
+
- **ready** - every other frame (hi-fi, HTML, a content frame shown at a device size, content without a
|
|
171
|
+
`Doc`) is done when it is ready;
|
|
172
|
+
- **missing** - the frame is not in the manifest;
|
|
173
|
+
- **error** - it threw;
|
|
174
|
+
- **never-ready** - the ready watchdog gave up on it;
|
|
175
|
+
- **cut** - it was still on its way when the load ended.
|
|
176
|
+
|
|
177
|
+
An outcome counts only from the document the frame shows now: a message from a document since replaced, or
|
|
178
|
+
from one a reload is replacing, never counts. When the same board is read again its frames keep their
|
|
179
|
+
documents, and a frame whose document is older than the load is marked `kept`. A load with missing or
|
|
180
|
+
never-ready frames settles anyway, and says so.
|
|
181
|
+
|
|
182
|
+
## Moves and why
|
|
183
|
+
|
|
184
|
+
Every change to a frame's place or size is a `move`, with its cause:
|
|
185
|
+
|
|
186
|
+
| Cause | What moved it |
|
|
187
|
+
|---|---|
|
|
188
|
+
| `measure-height` | a content frame reported its height |
|
|
189
|
+
| `measure-width` | a content frame took its `Doc`'s own width |
|
|
190
|
+
| `reflow:<reasons>` | the board re-flowed its rows - `measured` (a height came in), `cramped` (a sticky note needed room), `stale` (heights changed since the board was laid out), `gesture-end` (a re-flow that waited for a drag); several join with `+` |
|
|
191
|
+
| `manifest` | the frames on disk changed: a frame that arrived had its guessed size corrected |
|
|
192
|
+
| `drag` | you moved it (a drag's steps add up in one record while it waits to be sent) |
|
|
193
|
+
| `resize` | you resized it, or the board re-tidied after a resize |
|
|
194
|
+
| `device` | a device view (`0`-`5`), or a device size for the selection |
|
|
195
|
+
| `tidy` | a tidy (`t`) |
|
|
196
|
+
| `unplaced` | the **Not on a board** list changed |
|
|
197
|
+
| `spawn` | a frame added to the board on the canvas |
|
|
198
|
+
| `unknown` | a change with no cause named |
|
|
199
|
+
|
|
200
|
+
A move after the load ended - it settled, or it was cut (a board cut at 120 s, or while the page was hidden,
|
|
201
|
+
stays open and goes on loading) - is `late`. A load owns its board for as long as the board stays open, so
|
|
202
|
+
its late moves are its own; `perf --loads` counts them apart: `late, after it settled` or `late, after it
|
|
203
|
+
was cut`.
|
|
204
|
+
|
|
205
|
+
## Gestures
|
|
206
|
+
|
|
207
|
+
Each pan, zoom or layout animation ends in a `gesture` record: how long it ran, how many frames it drew, and
|
|
208
|
+
the frame intervals as they are - `p50`, `p95`, `max`, and two plain counts, the intervals over 17 ms
|
|
209
|
+
(`over17ms`) and over 33 ms (`over33ms`) - plus `longFrames`, the long animation frames that started inside
|
|
210
|
+
it (long tasks, where the browser has no long-animation-frame). There is no "missed frames" count measured
|
|
211
|
+
against the median: it would call a steady half-rate gesture smooth. The sampler runs only from a gesture's
|
|
212
|
+
start to its end; at rest it asks for no frames.
|
|
213
|
+
|
|
214
|
+
## Errors
|
|
215
|
+
|
|
216
|
+
The page records the errors it sees - its own (an uncaught error or rejection, a crash the shell caught,
|
|
217
|
+
with the component), a frame's, and the play stage's - with the message and up to three stack lines, 200
|
|
218
|
+
characters each. At most 50 per load, the same one at most once a second; those past 50 are counted, not
|
|
219
|
+
recorded. An error after its load settled or was cut is `late`: a load owns its board for as long as the
|
|
220
|
+
board stays open. Errors from before the first board mounted are kept apart (`unowned` in the JSON).
|
|
221
|
+
|
|
222
|
+
## The records
|
|
223
|
+
|
|
224
|
+
Every line of `page.jsonl` carries `v`, `ws` (the project's key), `page` (one id per page load), `load`
|
|
225
|
+
(for `load`, `commit` and a request's `cut`, the request's own id; for every other record, the load that
|
|
226
|
+
owns the board then; `-` before the first), `seq` (its place in the page's order), `ts` and `kind`:
|
|
227
|
+
|
|
228
|
+
| `kind` | When | Fields |
|
|
229
|
+
|---|---|---|
|
|
230
|
+
| `load` | a board load starts, before the board is read | `board`, `cause` (`boot` / `switch` / `disk-reload`), `request`; on a page's first load `sinceNav`, the ms since the page started loading |
|
|
231
|
+
| `commit` | the board mounts | `request`, `ms`, `frames`, `byKind` (`hifi`, `content`, `html`), `measuring`, `savedHeights`; `late` when its request was cut first (120 s, the page hidden) and its board arrived after all |
|
|
232
|
+
| `visible` | the first camera fit after it | `nodes`, `ms`; `assumed` when no fit came before the load ended (the frames the camera showed then) |
|
|
233
|
+
| `frame` | a frame reaches its outcome, or the load ends | `node`, `frame`, `gen` (the URL revision), `boot` (the document's id), `admitted` (its turn to boot), `ready`, `firstMeasure`, `settled`, `outcome`, `kept` |
|
|
234
|
+
| `move` | a frame's place or size changes | `node`, `dx`, `dy`, `dw`, `dh` (px), `cause`, `late` (after the load ended, settled or cut) |
|
|
235
|
+
| `quiet` | the first second after the commit with no move | `ms`: when the move before that second came (the commit, when none had) |
|
|
236
|
+
| `settled` | the load settled | `ms`, `moves`, `distance` (px), `causes`, `lastMove` (when the last move came; absent when nothing moved), `visibleReadyMs`, `allReadyMs`, `missing`, `neverReady`, `errors`, `weight` (`domNodes`, `iframes`, `awake`, `asleep`, `heapMB`) |
|
|
237
|
+
| `cut` | a load, or a request, ended early | `reason`, `ms`, `lastMove` (as `settled`'s); on a load that mounted, `frames` (on its board then) and `ready` (how many of those were settled or ready); `request` for a request cut before it mounted |
|
|
238
|
+
| `gesture` | a pan, zoom or layout animation ends | `type` (`pan` / `zoom` / `layout`), `ms`, `frames`, `p50`, `p95`, `max`, `over17ms`, `over33ms`, `longFrames` |
|
|
239
|
+
| `error` | an error the page sees | `source` (`shell` / `frame` / `stage`), `frame`, `component`, `message`, `stack`, `late` |
|
|
240
|
+
| `dropped` | records were lost | `n`; `reason: "errors"` for errors past a load's 50 - with no reason, a full queue or a failed send |
|
|
241
|
+
|
|
242
|
+
Times are ms from the load's request. Frame records stop once the load has settled or been cut. `settled.moves`
|
|
243
|
+
counts every change to the board; `perf --loads` counts move records, where a drag's steps are one.
|
|
244
|
+
|
|
245
|
+
## `--json`
|
|
246
|
+
|
|
247
|
+
`npx marver perf --loads --json` prints `{ minutes, loads, unowned, dropped }`. Each load has `board` (the
|
|
248
|
+
board's name; the printed report shows its title), `cause` and `state` - `settled`, `cut`, or `open` (still going, or its end past the window) - and, as it
|
|
249
|
+
got there:
|
|
250
|
+
|
|
251
|
+
- `cut`: `reason`, `ms`, and `request: true` when the cut came before it mounted;
|
|
252
|
+
- the commit: `commitMs`, `frames`, `byKind`, `measuring`, `savedHeights` - and `mountedAfterCut: true` for a
|
|
253
|
+
request cut first whose board arrived after all (`perf --loads` says `cut (hidden) at 0.4 s before it
|
|
254
|
+
mounted · mounted 3.2 s`, and counts its moves as late);
|
|
255
|
+
- `visible` (with `visibleAssumed`), `visibleReadyMs`, `allReadyMs` (each frame's first render), `quietMs` (when
|
|
256
|
+
the first still second began), `lastMoveMs` (settled or cut; `still from` in the printed report, which says the
|
|
257
|
+
mount when it is absent), `settledMs`;
|
|
258
|
+
- `moves`: `count`, `distance`, the top five `causes` as `[cause, count]` pairs, and `late` (count and
|
|
259
|
+
causes of the moves after the load ended, settled or cut);
|
|
260
|
+
- `slowest`: the five slowest frames that finished (`node`, `frame`, `ms` - when it settled, or was ready -
|
|
261
|
+
`outcome`, `admittedMs` - when it started: its turn to boot - and `readyMs`; `ms - admittedMs` is its own time);
|
|
262
|
+
- `firstStartedMs`: when the load's first frame started;
|
|
263
|
+
- `errors` (each once, every one, `late` marked), `errorsNotRecorded`, `neverReady`, `missing`,
|
|
264
|
+
`unfinished` (frames still on their way when it was cut: they never finished);
|
|
265
|
+
- on a load cut after it mounted, `framesAtCut` - the frames on its board when it was cut, those placed while it
|
|
266
|
+
loaded included, those removed not - and `readyByCut`, how many of them were ready (settled, or ready) by
|
|
267
|
+
then (both absent on one cut before it mounted);
|
|
268
|
+
- `gestures` (`n`, `worstP95`, `over33ms`) and `weight`.
|
|
269
|
+
|
|
270
|
+
`unowned` holds what a page recorded before its first board mounted (its errors, how many gestures);
|
|
271
|
+
`dropped`, how many records never reached the log. A send the page tried again is counted once.
|
|
272
|
+
|
|
273
|
+
## What it costs
|
|
274
|
+
|
|
275
|
+
Nothing at rest. While no load is in flight and nothing waits to be sent, the recorder has no timer and no
|
|
276
|
+
frame callback of its own; it hears each change to the canvas's state with one check. Records wait 2 s for
|
|
277
|
+
company, then go in one request, one at a time. A send that fails on the network or the server is tried
|
|
278
|
+
twice more, 2 s apart; a refusal, or a canvas that stopped, is not tried again (a 403 goes once more,
|
|
279
|
+
after the page has asked for its request cookie). What never lands is counted in a `dropped` record. The
|
|
280
|
+
queue holds 2,000 records or 256 KB, and past that the oldest go, counted the same way. When the page
|
|
281
|
+
closes, Jam captures go first: while a capture is open or waiting to be sent, the recorder sends nothing;
|
|
282
|
+
otherwise its last records go with `keepalive`, 16 KB at most.
|
|
283
|
+
|
|
284
|
+
The dev server takes them only from the canvas's own page, rebuilds each from the fields its kind allows -
|
|
285
|
+
strings cut to 200 characters, 512 KB a request - and appends them to `page.jsonl`.
|
|
286
|
+
|
|
287
|
+
## Headless runs
|
|
288
|
+
|
|
289
|
+
`npx marver perf run <board>` measures a board the same way every time, in the canvas's own headless Chrome
|
|
290
|
+
(`marver dev` must be running; no app, no window): your agent's way to tell whether a change made a board
|
|
291
|
+
faster or slower. One line per run goes to `design/.local/perf/runs.jsonl`.
|
|
292
|
+
|
|
293
|
+
```
|
|
294
|
+
$ npx marver perf run main
|
|
295
|
+
run 3f1c9a20b7d4e815: warming up
|
|
296
|
+
measuring
|
|
297
|
+
closing
|
|
298
|
+
run 3f1c9a20b7d4e815 · Main · Chrome 156 · bakes warm
|
|
299
|
+
load to settled 1.57 s · 4 moves · p50 16.7 ms p95 16.8 ms · 0 frames over 33 ms · heap peak 26.1 MB
|
|
300
|
+
valid · inputs 68cff66a… (24 files)
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
**The script** (version 1). One warm-up load, not measured: Vite's transforms and the dependency cache warm up,
|
|
304
|
+
and the frames' sleep bakes compile. It waits until the board's load has ended - settled, or cut: a cut warm-up
|
|
305
|
+
still counts as warm - and nothing is still compiling, 60 s at most; past that the run goes on and its line says
|
|
306
|
+
`bakes: 'cold'`. Then a fresh browser context, the cache off, 1440 x 900 at scale 2: the board loads, settles
|
|
307
|
+
(120 s at most), waits again until nothing is compiling (30 s),
|
|
308
|
+
fits, and runs three gestures with the pointer at the canvas's centre - 40 ctrl-wheel steps in, 40 out, then a
|
|
309
|
+
pan of 60 steps right and 60 back - each ended by the canvas itself. `--slow` throttles the CPU 4x before the
|
|
310
|
+
load: a stand-in for a slower Mac's CPU, not for its GPU or its memory. `--repeat <n>` runs it up to 5 times,
|
|
311
|
+
one after another. Ctrl-C cancels: the line says `cancelled`. Every call to the page has 15 s to answer: a
|
|
312
|
+
frame whose script never returns stops the canvas's page with it, and the run ends `cut` (`unresponsive`) instead
|
|
313
|
+
of waiting for ever. If the dev server restarts in place during a run (an `.env` or config edit), the run's line
|
|
314
|
+
says `inputs` - never `cancelled` - and `perf run` says the dev server restarted.
|
|
315
|
+
|
|
316
|
+
**Read-only.** The run's page refuses every write before it is sent - board saves, heights, the seen marks,
|
|
317
|
+
comments, captures, Jam, work - and the dev server refuses and counts any that gets through, from the page or
|
|
318
|
+
from a frame. Only two kinds go out: the page's own load records (stamped with the run by the server, so
|
|
319
|
+
`perf --loads` leaves them out and says how many) and the sleep bakes, which only fill a cache. A video whose
|
|
320
|
+
generated poster is missing runs without it, and the line counts it (`postersMissing`); its frame's bake is the
|
|
321
|
+
run's alone, never the shared cache. A frame's own code can still write: runs are for boards whose frames do
|
|
322
|
+
not.
|
|
323
|
+
|
|
324
|
+
**Valid or not.** A run is valid when none of these held, and its line names the first that did:
|
|
325
|
+
`cancelled`, `crash` (the page or the browser crashed), `inputs` (a watched file changed during the run, even if it
|
|
326
|
+
was put back, or the dev server restarted), `writes` (the dev server refused a write: one that got past the page,
|
|
327
|
+
or a frame's own - a write the page refuses before sending is only counted, as `refusedInPage`), `cut` (the load
|
|
328
|
+
never settled - its `cut` says why: `unresponsive` when the page stopped answering, `driver: ...` when the run
|
|
329
|
+
failed for another reason, such as a page script that threw), `frames` (a frame missing or never ready), `errors`, `bakes` (still
|
|
330
|
+
compiling 30 s after the load), `gesture` (the camera never came to rest after the fit, a gesture the canvas never
|
|
331
|
+
ended within 5 s, or one in which no frame was timed - then `over33ms` is `null`, never 0), `records` (the page's
|
|
332
|
+
records did not all land, or some were lost to a bound on the way). `gestures` counts the run's own three that the
|
|
333
|
+
canvas ended. A compile of the run still running 50 s after it ends is said in its line (`bakesPending`), and the
|
|
334
|
+
next run, measured beside it, is `overlapped`. Headless numbers are intervals in headless Chrome - not what a display
|
|
335
|
+
shows.
|
|
336
|
+
|
|
337
|
+
**The inputs.** `inputs` fingerprints every file in the project the dev server watches (git status plays no part,
|
|
338
|
+
so an ignored file a frame imports counts) plus the board files and `_sizes.json`. Outside the project - a sibling
|
|
339
|
+
package's source in a monorepo - it counts the files the board itself loads: the run takes its fingerprint after its
|
|
340
|
+
warm-up has loaded the board, from the files that page requested, what they import directly (a stylesheet's
|
|
341
|
+
`@import`s) and the `tsconfig` above them, and hashes the same files again at its end. Another board's sibling
|
|
342
|
+
files, which the dev server watches once any page loaded them, are never in it, so two runs of a board with nothing
|
|
343
|
+
changed have the same inputs. `GET /__mv/api/perf/inputs?run=<id>` reads a run's own files again now (for the last
|
|
344
|
+
32 runs, while the dev server runs); without `?run=` it reads every file the dev server watches. A frame importing
|
|
345
|
+
from a folder the dev server ignores (a sibling package's `dist/`) is not in it.
|
|
346
|
+
|
|
347
|
+
**Comparing.** `npx marver perf --runs` compares runs only inside a cohort - the same script, board, Chrome,
|
|
348
|
+
flags, Mac (`machine`, a profile of its own in `~/.marver/perf/machine/`), power source, `--slow` and warm or
|
|
349
|
+
cold bakes - and inside it by inputs: the latest run against the one before with the same inputs ("within
|
|
350
|
+
10 %" of its load to settled and p95, or not), and against the last one with other inputs (the deltas).
|
|
351
|
+
`--against <run>` compares the latest run of its cohort made after it with that one, whatever their inputs, when you
|
|
352
|
+
changed something on purpose. Runs that overlapped another are listed, never compared; invalid runs are listed with
|
|
353
|
+
their reason. `--days <n>` (14 by default) and `--json` as elsewhere.
|
|
354
|
+
|
|
355
|
+
## Options
|
|
356
|
+
|
|
357
|
+
| Option | |
|
|
358
|
+
|---|---|
|
|
359
|
+
| `--loads` | each board load in full |
|
|
360
|
+
| `--jam` | Jam's timings |
|
|
361
|
+
| `run <board>` | a headless run of the board ([Headless runs](#headless-runs)); with `--slow` and `--repeat <n>` (1-5) |
|
|
362
|
+
| `--runs` | the headless runs, compared inside their cohorts; with `--against <run>` and `--days <n>` (14) |
|
|
363
|
+
| `--crashes` | the Mac app's crashes and hangs of this repo's canvases (below) |
|
|
364
|
+
| `--flashes` | the flashes marked in the Mac app, and the white-out candidates (below) |
|
|
365
|
+
| `--machine` | the machine profiles (below) |
|
|
366
|
+
| `--all` | with `--flashes`: also the marks on other canvases or on Home |
|
|
367
|
+
| `--days <n>` | how far back `--runs`, `--crashes`, `--flashes` and `--machine` read: 14 by default |
|
|
368
|
+
| `--json` | machine-readable |
|
|
369
|
+
| `--minutes <n>` | how far back to read: 60 by default (24 h with `--jam`) |
|
|
370
|
+
| `--root <dir>` | the project (default: here) |
|
|
371
|
+
|
|
372
|
+
Plain `npx marver perf` reads the reload log and ends with one line per board load. It and `--loads` leave out a
|
|
373
|
+
headless run's loads (`marver perf run`): they say how many.
|
|
374
|
+
|
|
375
|
+
## The Mac app's half
|
|
376
|
+
|
|
377
|
+
The Mac app (0.2 and later) records what only the app can see, in `~/.marver/perf/`: `app.jsonl` (Marver Dev writes
|
|
378
|
+
`app-dev.jsonl`; one writer per file), one line per event with `{ v, ts, kind, app, seq, flavour, machine }` - `app`
|
|
379
|
+
names the launch, `seq` counts its lines, `machine` the profile the line was written on. Every 5 s the app samples its
|
|
380
|
+
processes (`getAppMetrics()`: CPU from cumulative time, memory as each process's working set, a canvas renderer's own
|
|
381
|
+
footprint from its page, the memory pressure level), keeps the last minute in memory and writes one `sample` line a
|
|
382
|
+
minute; and it records renderer and GPU process ends, hangs, GPU changes, power and thermal events, each tab's state
|
|
383
|
+
and document, and the time a tab switch takes to its second frame (`shown`: until the app hears back from that
|
|
384
|
+
frame, so the reply's own way back is in it). A minute's canvas memory per tab (`canvases.byTab`) counts a renderer
|
|
385
|
+
two tabs share in each of them and says `shared`; add up `canvases.memMB`, never `byTab`. A line about a tab carries
|
|
386
|
+
its `tab`, `ws`, `commit` and `page` - the page id the shell's hello sent, which is the `page` of its records in
|
|
387
|
+
`page.jsonl`. With Settings' recorder off, nothing of this is written (a flash you mark still is, and so is an
|
|
388
|
+
error main did not catch: a `main-error` line, in `app-dev.jsonl` for Marver Dev, written the moment it happens).
|
|
389
|
+
`machine/<hash>.json` holds one profile per distinct machine state (the chip, the displays and their rates, the
|
|
390
|
+
GPU's renderer, power): a display change, the window moved to another display, or a GPU fallback makes a new one, and
|
|
391
|
+
old lines keep theirs. The app keeps 14 days of it (`keepPerfDays`, pruned a few seconds after launch and then
|
|
392
|
+
daily), at most 5 MB a file, 50 flash pictures and 10 crash reports; a profile a headless run wrote stays at least 14
|
|
393
|
+
days, as long as a repo's `runs.jsonl` may name it.
|
|
394
|
+
|
|
395
|
+
`marver perf` joins the two halves by `page`, so each app event lands on the board load it happened in:
|
|
396
|
+
|
|
397
|
+
- `--crashes`: each canvas crash of this repo (not one the app ended itself: an unload, Reload Page) with its board,
|
|
398
|
+
whether its load had settled, the last gesture before it, and the minute before it - or, for a document that
|
|
399
|
+
ended before its first batch of records reached `page.jsonl`, that its page recorded nothing; hangs, and when the
|
|
400
|
+
page answered again; then, **by time (machine-wide)**, the GPU process's and utility processes' ends and a GPU process
|
|
401
|
+
replaced silently (`gpu-restart`); and how many crash reports `crashpad/completed` holds.
|
|
402
|
+
- `--flashes`: each flash you marked with `⌃⌥F` on this repo's canvases, with its board, the gesture you marked it
|
|
403
|
+
during (when it started and when it ended) or else the one that ended within 2 s of it, before or after; the GPU
|
|
404
|
+
process's own events within a second (its end, its replacement, a feature change - not a renderer's or a utility
|
|
405
|
+
process's), the pressure at the mark (unknown when the last reading was over 10 s old: with the recorder off and
|
|
406
|
+
nothing to unload the app reads none), thermal state, the GPU figures (machine-wide) and the picture's path, or
|
|
407
|
+
that it was pruned since. A mark is dated by the moment you pressed it (the state the app took then), not by its
|
|
408
|
+
line, which is written a second or two later, once the picture and the GPU figures are in. The picture is the app's views as the app stacks them, not the screen: it holds no traffic
|
|
409
|
+
lights and may miss a flash that happens in the compositor. Marks on Home or other canvases are counted (`--all`
|
|
410
|
+
shows them). White-out candidates, found automatically during gestures, are listed apart: automatic, not verified.
|
|
411
|
+
- `--machine`: the profiles, grouped by host (the app and a headless run of one Mac share its `hostHash`), which is
|
|
412
|
+
current, and how many records and runs name each.
|
|
413
|
+
|
|
414
|
+
A record that carries a page joins that page and no other: when the page recorded nothing, the output says so
|
|
415
|
+
rather than lending it the tab's earlier document. A record that carries no page (a 0.27.0 canvas, or a document that
|
|
416
|
+
has not said hello) is joined by workspace and time, and the output says so. The repo's workspaces are its own and every workspace in its `page.jsonl`, so a
|
|
417
|
+
`--recover` run's records join too.
|
|
418
|
+
|
|
419
|
+
## In the page
|
|
420
|
+
|
|
421
|
+
In a dev canvas's console, `__mvPerf.report()` sums up the gestures so far - `gestureFrames`, `frameP50`,
|
|
422
|
+
`frameP95`, `frameMax`, `over17ms`, `over33ms`, `longFrames`, `longFrameP95`, `longFrameMax` and
|
|
423
|
+
`counters` - and `__mvPerf.reset()` starts over. On a published canvas, `?mvperf` in the URL (or
|
|
424
|
+
`localStorage.mvPerf = '1'`) turns it on; the recorder itself never runs there.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@marver-design/marver",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.27.2",
|
|
4
4
|
"description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"private": false,
|
|
@@ -55,7 +55,7 @@
|
|
|
55
55
|
"mermaid": "^11.6.0",
|
|
56
56
|
"react-zoom-pan-pinch": "^3.6.1",
|
|
57
57
|
"roughjs": "^4.6.6",
|
|
58
|
-
"vite": "
|
|
58
|
+
"vite": "~8.2.1",
|
|
59
59
|
"ws": "^8.22.0",
|
|
60
60
|
"zustand": "^5.0.0"
|
|
61
61
|
},
|
|
@@ -77,6 +77,9 @@ export function Doc({ layout = 'document', children }: { layout?: 'document' | '
|
|
|
77
77
|
// drops echoes that don't match the iframe's current src)
|
|
78
78
|
frame: params.get('id') ?? '',
|
|
79
79
|
gen: params.get('r') ?? '',
|
|
80
|
+
// and THIS document's id (the frame bridge sets it; absent where no bridge ran - the stage, a headless shot):
|
|
81
|
+
// the shell's recorder counts a settled report only from the document there now (spec 28 A1.7)
|
|
82
|
+
boot: (window as { __mvBoot?: string }).__mvBoot,
|
|
80
83
|
ownWidth: CONTENT_WIDTH[layout] ?? CONTENT_WIDTH.document,
|
|
81
84
|
measuredWidth: window.innerWidth, // the width this height is TRUE at (r3 #1)
|
|
82
85
|
height: height(),
|
|
@@ -27,6 +27,7 @@ import { useEffect, useRef, useState, useSyncExternalStore, type CSSProperties }
|
|
|
27
27
|
import { ROUTE } from '../const.ts'
|
|
28
28
|
import { assetUrl } from './md.ts'
|
|
29
29
|
import { useSlidePlay } from './slide.tsx'
|
|
30
|
+
import { RUN_ID, RUN_PARAM } from '../../shared/perf-run.ts'
|
|
30
31
|
|
|
31
32
|
const isRemote = (s: string) => /^https:\/\//.test(s)
|
|
32
33
|
const resolve = (s: string): string | null => (isRemote(s) ? s : assetUrl(s))
|
|
@@ -38,6 +39,15 @@ const posterNameFor = (src: string) => `${src}.poster.png`
|
|
|
38
39
|
// has no such API (build already generated the file); a failed request just keeps the card.
|
|
39
40
|
const requested = new Map<string, Promise<boolean>>()
|
|
40
41
|
const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
|
|
42
|
+
// the canvas names its workspace in the frame's URL (spec 28 A1.11); a request from this frame names
|
|
43
|
+
// it too, so a frame left open after its canvas stopped never asks another project for anything
|
|
44
|
+
const WS = typeof location !== 'undefined' ? new URLSearchParams(location.search).get('ws') : null
|
|
45
|
+
const named = (h: Record<string, string> = {}) => (WS ? { ...h, 'x-mv-ws': WS } : h)
|
|
46
|
+
// a headless perf run (spec 28 A3.8 #17, #19): the canvas names the run in the frame's URL, and the bake that renders
|
|
47
|
+
// this frame for the run too. A run is read-only: a missing poster is never generated - the clip rests without one,
|
|
48
|
+
// in the same box, and the document says so (`data-mv-poster-skipped`), so no compile of it fills the shared cache
|
|
49
|
+
const RUN = (() => { try { const id = new URLSearchParams(location.search).get(RUN_PARAM); return id && RUN_ID.test(id) ? id : null } catch { return null } })()
|
|
50
|
+
const POSTER_SKIPPED = 'data-mv-poster-skipped'
|
|
41
51
|
// in-flight probes + generations, for the shot renderer's settle (like __mvLodBusy): a
|
|
42
52
|
// screenshot taken while a poster is still being rendered would show the empty box
|
|
43
53
|
let busy = 0
|
|
@@ -48,8 +58,8 @@ const requestPoster = (src: string): Promise<boolean> => {
|
|
|
48
58
|
p = (async () => {
|
|
49
59
|
// the owner gate wants the double-submit cookie echoed; a frame host opened cold has not
|
|
50
60
|
// made an API GET yet, so prime it with the cheapest one first
|
|
51
|
-
if (!csrf()) await fetch(`${ROUTE}/api/policy
|
|
52
|
-
const r = await fetch(`${ROUTE}/api/poster
|
|
61
|
+
if (!csrf()) await fetch(`${ROUTE}/api/policy`, { headers: named() }).catch(() => null)
|
|
62
|
+
const r = await fetch(`${ROUTE}/api/poster`, { method: 'POST', headers: named({ 'content-type': 'application/json', 'x-mv-c': csrf() }), body: JSON.stringify({ src }) }).catch(() => null)
|
|
53
63
|
return !!r?.ok
|
|
54
64
|
})()
|
|
55
65
|
requested.set(src, p)
|
|
@@ -127,7 +137,7 @@ export function Video({ src, poster, ratio, autoplay = false }: { src: string; p
|
|
|
127
137
|
// or failed (the card). The <img> mounts only once ready: no broken-image glyph while the
|
|
128
138
|
// dev server renders the poster, and a shot taken meanwhile waits on __mvPosterBusy.
|
|
129
139
|
const generated = !poster && !isRemote(src) ? posterNameFor(src) : null
|
|
130
|
-
const [gen, setGen] = useState<'probing' | 'ready' | 'failed'>(generated ? 'probing' : 'ready')
|
|
140
|
+
const [gen, setGen] = useState<'probing' | 'ready' | 'failed' | 'skipped'>(generated ? 'probing' : 'ready')
|
|
131
141
|
const [bust, setBust] = useState(0)
|
|
132
142
|
const posterUrl = poster ? resolve(poster) : generated ? resolve(generated) : null
|
|
133
143
|
const posterSrc = posterUrl && bust ? `${posterUrl}?v=${bust}` : posterUrl
|
|
@@ -140,9 +150,11 @@ export function Video({ src, poster, ratio, autoplay = false }: { src: string; p
|
|
|
140
150
|
busy++
|
|
141
151
|
const done = () => { if (pending) { pending = false; busy-- } }
|
|
142
152
|
const probe = new Image()
|
|
143
|
-
const settle = (state: 'ready' | 'failed', rebust = false) => { done(); if (!alive) return; if (rebust) setBust(Date.now()); setGen(state) }
|
|
153
|
+
const settle = (state: 'ready' | 'failed' | 'skipped', rebust = false) => { done(); if (!alive) return; if (rebust) setBust(Date.now()); setGen(state) }
|
|
144
154
|
probe.onload = () => settle('ready')
|
|
145
155
|
probe.onerror = () => {
|
|
156
|
+
// a perf run asks for nothing: the box rests without its poster
|
|
157
|
+
if (RUN) { document.documentElement.setAttribute(POSTER_SKIPPED, ''); return settle('skipped') }
|
|
146
158
|
// not there yet: ask the dev server to render it (once per clip per document)
|
|
147
159
|
void requestPoster(src).then((ok) => settle(ok ? 'ready' : 'failed', ok))
|
|
148
160
|
}
|
|
@@ -15,6 +15,23 @@ const isHtmlFrame = new URL(import.meta.url).searchParams.get('html') === '1'
|
|
|
15
15
|
const post = (msg) => { if (window.parent !== window) window.parent.postMessage(msg, location.origin) }
|
|
16
16
|
const id = new URLSearchParams(location.search).get('id') ?? location.pathname
|
|
17
17
|
|
|
18
|
+
// One id per document (spec 28 A1.7), set before this document posts anything: its ready, measure and error carry
|
|
19
|
+
// it, and the shell reads the live one off this window - a message from a document since replaced never counts. The
|
|
20
|
+
// shell hears of a new document at once (sh:boot), so a reload of the same URL sends its node back to pending.
|
|
21
|
+
const BOOT = Array.from(crypto.getRandomValues(new Uint8Array(6)), (b) => b.toString(16).padStart(2, '0')).join('')
|
|
22
|
+
window.__mvBoot = BOOT
|
|
23
|
+
// the URL revision the shell gave this document (its generation guard)
|
|
24
|
+
const GEN = new URLSearchParams(location.search).get('r') ?? ''
|
|
25
|
+
post({ type: 'sh:boot', id, gen: GEN, boot: BOOT })
|
|
26
|
+
/** An error's first three stack lines (Chrome's "at …", else "fn@url:line:col"), when it has them. */
|
|
27
|
+
const stackOf = (err) => {
|
|
28
|
+
if (typeof err?.stack !== 'string') return undefined
|
|
29
|
+
const lines = err.stack.split('\n')
|
|
30
|
+
const chrome = lines.filter((l) => /^\s*at /.test(l))
|
|
31
|
+
const out = (chrome.length ? chrome : lines.filter((l) => /@.*:\d+(:\d+)?$/.test(l.trim()))).slice(0, 3).map((l) => l.trim().slice(0, 200))
|
|
32
|
+
return out.length ? out : undefined
|
|
33
|
+
}
|
|
34
|
+
|
|
18
35
|
// theme lands as BOTH signals: [data-theme] plus the `dark` class Tailwind/shadcn key on
|
|
19
36
|
const setTheme = (theme) => {
|
|
20
37
|
document.documentElement.dataset.theme = theme
|
|
@@ -70,8 +87,8 @@ document.addEventListener('click', (e) => {
|
|
|
70
87
|
// consumed and forwarded it already, so this never sees it
|
|
71
88
|
document.addEventListener('keydown', (e) => { if (e.key === 'Escape') post({ type: 'sh:exit-interact' }) })
|
|
72
89
|
|
|
73
|
-
window.addEventListener('error', (e) => post({ type: 'sh:error', id, message: String(e.message || e.error) }))
|
|
74
|
-
window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:error', id, message: `unhandled rejection: ${e.reason}
|
|
90
|
+
window.addEventListener('error', (e) => post({ type: 'sh:error', id, gen: GEN, boot: BOOT, message: String(e.message || e.error), stack: stackOf(e.error) }))
|
|
91
|
+
window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:error', id, gen: GEN, boot: BOOT, message: `unhandled rejection: ${e.reason}`, stack: stackOf(e.reason) }))
|
|
75
92
|
|
|
76
93
|
window.addEventListener('message', (e) => {
|
|
77
94
|
// commands come from the SHELL (parent) only - embedded app content must not flip the theme
|
|
@@ -91,10 +108,9 @@ window.addEventListener('message', (e) => {
|
|
|
91
108
|
})
|
|
92
109
|
|
|
93
110
|
if (isHtmlFrame) {
|
|
94
|
-
// stamp the URL revision (see main.tsx) so the shell can drop a ready from a superseded document
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
const ready = () => post({ type: 'sh:ready', id, gen, doc: document.querySelector('meta[name="mv-doc"]')?.getAttribute('content') ?? '' })
|
|
111
|
+
// stamp the URL revision (see main.tsx) so the shell can drop a ready from a superseded document, this document's
|
|
112
|
+
// id, and echo the revision the server stamped this document with (spec 26): what it shows
|
|
113
|
+
const ready = () => post({ type: 'sh:ready', id, gen: GEN, boot: BOOT, doc: document.querySelector('meta[name="mv-doc"]')?.getAttribute('content') ?? '' })
|
|
98
114
|
document.readyState === 'loading' ? addEventListener('DOMContentLoaded', ready) : ready()
|
|
99
115
|
}
|
|
100
116
|
|
|
@@ -20,6 +20,18 @@ document.documentElement.dataset.theme = theme
|
|
|
20
20
|
document.documentElement.classList.toggle('dark', theme === 'dark')
|
|
21
21
|
|
|
22
22
|
const post = (msg: Record<string, unknown>) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
|
|
23
|
+
// this document's id, set by the bridge (imported first, above) before anything is posted - and the URL revision the
|
|
24
|
+
// shell gave it: every ready and error carries both (spec 28 A1.7)
|
|
25
|
+
const docId = () => (window as { __mvBoot?: string }).__mvBoot
|
|
26
|
+
const gen = params.get('r') ?? ''
|
|
27
|
+
/** An error's first three stack lines (Chrome's "at …", else "fn@url:line:col"), when it has them - as the bridge's. */
|
|
28
|
+
const stackOf = (err: unknown) => {
|
|
29
|
+
const st = (err as Error | undefined)?.stack
|
|
30
|
+
if (typeof st !== 'string') return undefined
|
|
31
|
+
const lines = st.split('\n'), chrome = lines.filter((l) => /^\s*at /.test(l))
|
|
32
|
+
const out = (chrome.length ? chrome : lines.filter((l) => /@.*:\d+(:\d+)?$/.test(l.trim()))).slice(0, 3).map((l) => l.trim().slice(0, 200))
|
|
33
|
+
return out.length ? out : undefined
|
|
34
|
+
}
|
|
23
35
|
|
|
24
36
|
// A render failure posts sh:error to the shell, but a HEADLESS screenshot has no shell to
|
|
25
37
|
// hear it - so also stamp the error on the document, where the shot capture can read it.
|
|
@@ -27,9 +39,9 @@ const post = (msg: Record<string, unknown>) => { if (window.parent !== window) w
|
|
|
27
39
|
// agent that cannot see the PNG (only the JSON), instead of a clean-looking ok:true.
|
|
28
40
|
const markError = (message: string) => { (window as any).__mvFrameError = message }
|
|
29
41
|
|
|
30
|
-
function fail(message: string) {
|
|
42
|
+
function fail(message: string, err?: unknown) {
|
|
31
43
|
markError(message)
|
|
32
|
-
post({ type: 'sh:error', id, message })
|
|
44
|
+
post({ type: 'sh:error', id, gen, boot: docId(), message, stack: stackOf(err) })
|
|
33
45
|
document.getElementById('root')!.innerHTML =
|
|
34
46
|
`<div style="font-family:ui-monospace,monospace;font-size:12px;padding:16px;color:#b42318">
|
|
35
47
|
<div style="font-weight:700;margin-bottom:8px">frame failed</div>
|
|
@@ -43,7 +55,7 @@ const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt
|
|
|
43
55
|
class Boundary extends Component<{ children: ReactNode }, { err: Error | null }> {
|
|
44
56
|
state = { err: null as Error | null }
|
|
45
57
|
static getDerivedStateFromError(err: Error) { return { err } }
|
|
46
|
-
componentDidCatch(err: Error) { markError(err.message); post({ type: 'sh:error', id, message: err.message }) }
|
|
58
|
+
componentDidCatch(err: Error) { markError(err.message); post({ type: 'sh:error', id, gen, boot: docId(), message: err.message, stack: stackOf(err) }) }
|
|
47
59
|
render() {
|
|
48
60
|
if (!this.state.err) return this.props.children
|
|
49
61
|
return createElement('div', { style: { fontFamily: 'ui-monospace,monospace', fontSize: 12, padding: 16, color: '#b42318' } },
|
|
@@ -100,10 +112,10 @@ async function boot() {
|
|
|
100
112
|
// sh:ready on the first COMMIT, stamped with the URL revision so the shell can drop a ready queued
|
|
101
113
|
// by a superseded document (one it auto-renavigated past) - a WindowProxy survives navigation, so
|
|
102
114
|
// a stale ready could otherwise mark a reloading frame ready. Mirrors the sh:measure generation guard.
|
|
103
|
-
const ready = () => { phases.commit = Math.round(performance.now()); post({ type: 'sh:ready', id, gen:
|
|
115
|
+
const ready = () => { phases.commit = Math.round(performance.now()); post({ type: 'sh:ready', id, gen, boot: docId(), doc: document.querySelector('meta[name="mv-doc"]')?.getAttribute('content') ?? '', meta: frameMod.meta && typeof frameMod.meta === 'object' ? frameMod.meta : undefined, phases }) }
|
|
104
116
|
createRoot(document.getElementById('root')!).render(createElement(Boundary, null, createElement(Committed, { onCommit: ready }, tree)))
|
|
105
117
|
} catch (err) {
|
|
106
|
-
fail((err as Error).message)
|
|
118
|
+
fail((err as Error).message, err)
|
|
107
119
|
}
|
|
108
120
|
}
|
|
109
121
|
|