@marver-design/marver 0.26.1 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/CHANGELOG.md +104 -0
  2. package/README.md +8 -3
  3. package/dist/{anchor-check-l-ny3UzH.mjs → anchor-check-ChdDqL5z.mjs} +1 -1
  4. package/dist/{bake-C-awKgLA.mjs → bake-DM_uWgAA.mjs} +1 -1
  5. package/dist/{boards-DYG22tOe.mjs → boards-DlTcpF47.mjs} +1 -1
  6. package/dist/{build-BDRiO_mP.mjs → build-DZnFysGU.mjs} +4 -4
  7. package/dist/cli.mjs +28 -16
  8. package/dist/{comments-BqXua-XL.mjs → comments-DxOkCSNE.mjs} +4 -4
  9. package/dist/{daemon-DL6Fwq6D.mjs → daemon-BSA0lV8d.mjs} +8 -6
  10. package/dist/detect-C0wpaePX.mjs +125 -0
  11. package/dist/dev-eQJhWsqg.mjs +1273 -0
  12. package/dist/dev-lock-C_FC70Mu.mjs +65 -0
  13. package/dist/exclusive-B1RtpeeP.mjs +150 -0
  14. package/dist/{init-D8DtrK_F.mjs → init-COD0x48i.mjs} +5 -3
  15. package/dist/{link-BNzLvdhI.mjs → link-DDXZVGtv.mjs} +20 -8
  16. package/dist/ls-D7O1G505.mjs +38 -0
  17. package/dist/{marks-DyWMv_Z1.mjs → marks-CWM3WJjc.mjs} +1 -1
  18. package/dist/perf-BWzQwZqj.mjs +369 -0
  19. package/dist/perf-BoDSkbEb.mjs +429 -0
  20. package/dist/{perf-jam-BU3TVrZu.mjs → perf-jam-D55U3FZK.mjs} +5 -2
  21. package/dist/{plugin-DkGmZs_r.mjs → plugin-C-E7omsh.mjs} +394 -55
  22. package/dist/{poster-BdtSKMDm.mjs → poster-Bx83ZYVK.mjs} +1 -1
  23. package/dist/{profile-WU9qcbIo.mjs → profile-Bh5Y5zpW.mjs} +1 -1
  24. package/dist/{publish-bakes-9RzRToXV.mjs → publish-bakes-aljgm45S.mjs} +2 -2
  25. package/dist/{queue-29ok5_eZ.mjs → queue-CAM_vNmX.mjs} +1 -1
  26. package/dist/recover-t9Pno3u9.mjs +66 -0
  27. package/dist/{share--oFJ1bCI.mjs → share-W5H3BNvP.mjs} +1 -1
  28. package/dist/{shot-XQV7HC9A.mjs → shot-DoHLl6ig.mjs} +1 -1
  29. package/dist/{shot-DQeR_Pfn.mjs → shot-LFhC-WYD.mjs} +9 -3
  30. package/dist/slots-DCDo3N0x.mjs +471 -0
  31. package/dist/{sync-DKk-yT1V.mjs → sync-BQVlHZpx.mjs} +4 -3
  32. package/dist/{work-F5u-twpJ.mjs → work-Bp1p39kq.mjs} +4 -2
  33. package/dist/{work-VvX_JIgl.mjs → work-BroFwnup.mjs} +4 -2
  34. package/docs/boards-and-folders.md +3 -1
  35. package/docs/jam-session.md +55 -1
  36. package/docs/performance.md +262 -0
  37. package/package.json +2 -2
  38. package/src/client/content/index.tsx +3 -0
  39. package/src/client/content/video.tsx +6 -2
  40. package/src/client/frame-host/bridge.js +22 -6
  41. package/src/client/frame-host/main.tsx +17 -5
  42. package/src/client/shell/App.tsx +180 -25
  43. package/src/client/shell/BoardList.tsx +5 -5
  44. package/src/client/shell/Comments.tsx +3 -2
  45. package/src/client/shell/JamSurface.tsx +4 -2
  46. package/src/client/shell/LockedApp.tsx +5 -5
  47. package/src/client/shell/Play.tsx +16 -8
  48. package/src/client/shell/Toolbar.tsx +12 -1
  49. package/src/client/shell/api.ts +206 -0
  50. package/src/client/shell/canvas/Canvas.tsx +30 -3
  51. package/src/client/shell/canvas/FrameNode.tsx +12 -3
  52. package/src/client/shell/canvas/admission.ts +8 -1
  53. package/src/client/shell/canvas/camera-broadcast.ts +15 -5
  54. package/src/client/shell/canvas/ctl.ts +2 -0
  55. package/src/client/shell/canvas/frame-registry.ts +28 -2
  56. package/src/client/shell/canvas/sleep.ts +4 -1
  57. package/src/client/shell/comments-store.ts +12 -4
  58. package/src/client/shell/goto.ts +22 -10
  59. package/src/client/shell/jam-capture.ts +22 -8
  60. package/src/client/shell/jam-keys.ts +4 -0
  61. package/src/client/shell/jam-panel.tsx +3 -0
  62. package/src/client/shell/jam-queue.ts +3 -3
  63. package/src/client/shell/jam-session.tsx +14 -8
  64. package/src/client/shell/jam-voice.ts +7 -5
  65. package/src/client/shell/legacy-links.ts +2 -2
  66. package/src/client/shell/main.tsx +4 -0
  67. package/src/client/shell/notes.ts +8 -1
  68. package/src/client/shell/perf.ts +69 -58
  69. package/src/client/shell/recorder-core.ts +183 -0
  70. package/src/client/shell/recorder.ts +565 -0
  71. package/src/client/shell/store.ts +254 -98
  72. package/src/client/shell/styles.css +26 -1
  73. package/templates/AGENTS-embedded.md +22 -4
  74. package/templates/AGENTS-studio.md +22 -4
  75. package/templates/demo/dark.tsx +1 -1
  76. package/templates/demo/welcome.tsx +1 -1
  77. package/templates/instructions/welcome.md +6 -3
  78. package/dist/config-Cf7EjAMf.mjs +0 -292
  79. package/dist/dev-Bw_qYWWq.mjs +0 -755
  80. package/dist/dev-lock-DWSpa6nj.mjs +0 -179
  81. package/dist/perf-C75MZ73h.mjs +0 -167
  82. package/dist/perf-DPbLGhhO.mjs +0 -49
@@ -1,5 +1,6 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
- import { i as readDevInfo, n as WORK_TTL_MAX, t as WORK_TTL_DEFAULT } from "./work-F5u-twpJ.mjs";
2
+ import { i as readDevInfo, n as WORK_TTL_MAX, t as WORK_TTL_DEFAULT } from "./work-Bp1p39kq.mjs";
3
+ import { unreachable } from "./link-DDXZVGtv.mjs";
3
4
  //#region src/cli/work.ts
4
5
  /**
5
6
  * `marver work` - the coding agent's hand on the canvas working state.
@@ -30,6 +31,7 @@ async function workCommand(root, action, frames, opts) {
30
31
  ...body === void 0 ? {} : { body: JSON.stringify(body) }
31
32
  });
32
33
  } catch {
34
+ if (info.pid !== void 0) throw new Error(`${unreachable(info.pid)} The working glow needs it; the canvas itself is fine - \`npx ${NAME} link <scene/frame>\` still prints its link`);
33
35
  throw new Error(`could not reach \`${NAME} dev\` on port ${info.port} - is it still running?`);
34
36
  }
35
37
  const data = await res.json().catch(() => ({}));
@@ -66,7 +68,7 @@ async function workCommand(root, action, frames, opts) {
66
68
  });
67
69
  console.log(active.length ? `still working: ${active.join(", ")}` : "nothing working - all clear");
68
70
  const done = before.filter((f) => !active.includes(f));
69
- const { links, hints } = done.length ? await (await import("./link-BNzLvdhI.mjs")).handBack(root, done) : {
71
+ const { links, hints } = done.length ? await (await import("./link-DDXZVGtv.mjs")).handBack(root, done) : {
70
72
  links: [],
71
73
  hints: []
72
74
  };
@@ -106,7 +106,9 @@ screen first; a frame off screen waits until you scroll to it, and one you are u
106
106
  drawing a laser, commenting) waits until you are done. A content frame keeps its height while it
107
107
  reloads, so the rows below stay still; if heights did change, the board moves once. The canvas page
108
108
  itself never reloads for a design edit. `npx marver perf` shows what each edit reloaded and how long
109
- it took (from `design/.local/perf/reloads.jsonl`).
109
+ it took (from `design/.local/perf/reloads.jsonl`), and `npx marver perf --loads` what each board load
110
+ did: how long until it settled, how many moves it took on the way, and why
111
+ ([Performance](performance.md)).
110
112
 
111
113
  ## In the files
112
114
 
@@ -32,6 +32,9 @@ is kept as it stood - its words and notes so far, and a line saying the page clo
32
32
  back as a draft to read, resume or drop; it never goes to your agent on its own. (Best effort: a crash gives the page
33
33
  no chance to keep it.)
34
34
 
35
+ A capture the page could not send waits in this browser, for this address, and sends itself the next time the canvas
36
+ opens there - see [A capture left on an old address](#a-capture-left-on-an-old-address).
37
+
35
38
  A capture is about the frames you **touched** - selected, clicked, typed in, scrolled,
36
39
  resized, pictured, or zoomed to alone - not every frame that happened to be on screen. Those
37
40
  are the frames its run may edit, and the frames pictured before and after it.
@@ -178,7 +181,7 @@ The keys work inside frames too, in interactive mode and in play.
178
181
 
179
182
  How long each step takes on your machine - a capture sealing, its pictures, your words, naming, the queue, your agent,
180
183
  the pictures before and after - is in `npx marver perf --jam` (median, slowest, and what went wrong lately), read from
181
- `design/.local/perf/jam.jsonl`: numbers and fixed codes only, never your words.
184
+ `design/.local/perf/jam.jsonl`: numbers and fixed codes only, never your words ([Performance](performance.md)).
182
185
 
183
186
  The capture itself sits in `design/.local/` (gitignored, never published): its full record
184
187
  and pictures under `design/.local/jam/`, the session transcript under
@@ -192,3 +195,54 @@ comment would. They never reach a published canvas: `marver build` and `marver c
192
195
  leave capture threads (and Marver's notes and replies) on your machine. The session
193
196
  **record** your agent writes goes to `context/sessions/`, also meant to be committed.
194
197
  Published canvases carry none of Jam: no captures, no queue, no microphone.
198
+
199
+ ## A capture left on an old address
200
+
201
+ A capture the page could not send - the canvas was away, or the page closed before its send landed - waits in that
202
+ browser's storage, under that page's address (`http://localhost:<port>`), and goes out the next time the canvas opens
203
+ **at that address** with Live Jam on. When the canvas moves, the capture stays behind: 0.27 moved canvases to slots,
204
+ and a later start lands on another slot when its own is taken. So does a tab still open there with edits it could not
205
+ save: it keeps them until its own canvas answers at that address again. `marver dev` says so as it starts - where it
206
+ was, which canvas runs there now (when one does), and the `--recover` number of that address:
207
+
208
+ ```
209
+ last run was at http://localhost:4806/ - "atlas" runs there now
210
+ a tab still open there keeps its unsaved edits until this canvas runs there again (a Jam capture left unsent there waits too):
211
+ stop "atlas" and this canvas, then `npx marver dev --recover 2`
212
+ ```
213
+
214
+ `--recover` starts the canvas there again. Stop the canvas first if it runs (`Ctrl-C`): one canvas runs per folder, so
215
+ a recovery started beside it stops with "a canvas already runs here". The list works either way:
216
+
217
+ The list holds the last five distinct addresses the canvas ran on (an older one drops off as a sixth arrives), then
218
+ the address 0.26 gave the folder:
219
+
220
+ ```bash
221
+ npx marver dev --recover # the addresses this canvas ran on, newest first
222
+ npx marver dev --recover 2 # start on exactly that one
223
+ ```
224
+
225
+ ```
226
+ addresses this canvas ran on, newest first:
227
+ 1 http://localhost:4807/ bound http://[::1]:4807 22 Oct 15:40 - 22 Oct 17:02
228
+ 2 http://localhost:4806/ bound http://[::1]:4806 21 Oct 09:12 - 21 Oct 18:30
229
+ 3 http://localhost:5329/ the address 0.26 gave it
230
+ start on one: npx marver dev --recover <n> - then open its link in the browser that made the capture
231
+ ```
232
+
233
+ A recovery runs on exactly that entry's port, the address it bound, and the project key that run used - never another.
234
+ Open the link it prints in the browser that made the capture; the captures waiting there send themselves. Then stop it
235
+ (`Ctrl-C`) and start the canvas as usual. If the port or the address cannot be had - another canvas or another program
236
+ holds it - it stops and says why; it never moves elsewhere. A recovery leaves the canvas's list of addresses as it was.
237
+
238
+ **The list always holds the address 0.26 gave this folder** (or would have given it), last unless this canvas has run
239
+ there since. It only matters coming from 0.26. The first 0.27 start of a canvas that ran before names it too ("0.26
240
+ served this canvas at http://localhost:5329/ - if a Jam capture was left unsent there, ..."); a new project's first
241
+ start says nothing of it. If 0.26 had moved to another port when you made the capture
242
+ (it said "port ... is in use - serving ... instead" as it started), name that port:
243
+ `npx marver dev --recover --port <that port>`.
244
+
245
+ **When it cannot come back** - an address that can no longer be had, or a browser profile that is gone - Marver cannot
246
+ send the capture. It is still readable by hand: in the browser's developer tools, under Local storage for that address,
247
+ the key `mv-jam-sealed:<project key>` holds it as JSON; copy what you said into a new capture's notes. A capture only
248
+ waits like this when it could not reach its canvas before the page closed.
@@ -0,0 +1,262 @@
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
+
15
+ `design/.local/` is gitignored, and `marver dev` never serves it. The perf folder is yours alone: mode 700,
16
+ each file 600 from the moment it is made - and files an earlier version made are tightened when `marver dev`
17
+ starts. At start, each log loses its lines older than 14 days, and past its cap its oldest half; a log that
18
+ passes its cap while the canvas runs loses its oldest half too. The cap is 2 MB, and 8 MB for `page.jsonl`:
19
+ one load of a 120-frame board writes about 140 KB there, most of it moves, so 2 MB held about fourteen such
20
+ loads - hours of work, not days. 8 MB holds four times as many.
21
+
22
+ `page.jsonl` holds frame names, node keys and numbers. Error messages and stack lines can hold file paths,
23
+ so, like the rest, they stay on this Mac.
24
+
25
+ ## A board load
26
+
27
+ Each time a board opens - the page's first (`boot`), another board you chose (`switch`), or the open board
28
+ read again because its file changed on disk (`disk-reload`) - the page follows it until it settles:
29
+
30
+ 1. **Requested.** The board, and why it loads. Until it mounts, every move belongs to the board still up.
31
+ 2. **Committed.** It mounts: its frames by kind (hi-fi, content, HTML), how many are content frames that
32
+ measure their own height, and how many of those open at a height already known.
33
+ 3. **Visible.** The frames the first camera fit shows - the ones you see first.
34
+ 4. **Each frame's outcome** - [below](#frames).
35
+ 5. **Quiet.** The first second after it mounts with nothing moving, written as that second ends: it says
36
+ when the move before it came (the mount itself, when nothing had moved yet). It is not when the board
37
+ stopped moving - a frame that reports its height later moves it again. That is the **last move**, on
38
+ the record that ends the load, settled or cut.
39
+ 6. **Settled.** Every frame at its outcome, no re-flow pending or held, no frame booting or waiting its
40
+ turn to, the camera still, and a second with no move - so a load never settles in under a second. It says
41
+ how many moves and why, when the last one came, when the visible frames and all the frames were ready,
42
+ and how heavy the board is: elements, frames awake and asleep, the heap (in Chrome).
43
+
44
+ Or **cut**: another board (`switch`), the same board loaded again (`reload`), the page hidden (`hidden`),
45
+ or 120 s without settling (`timeout`). A request that never mounted is cut too: a newer load
46
+ (`superseded`), a board that could not be read (`error`), your edits while it was read from disk
47
+ (`edited`), or a switch away from a board that could not be saved (`unsaved`). A request cut at 120 s or
48
+ while the page was hidden may still mount when its board arrives: its commit then says it came after the
49
+ cut (`late`), the cut stays, and what the board does from then is late.
50
+
51
+ ## Reading `perf --loads`
52
+
53
+ A board of three content frames, opened twice. The first time no height was known; the second time the
54
+ heights the first load settled at were in `design/boards/_sizes.json`:
55
+
56
+ ```
57
+ $ npx marver perf --loads
58
+ board loads, last 60 min - design/.local/perf/page.jsonl
59
+
60
+ 3:41:36 PM Checkout (boot) settled 2.1 s
61
+ committed 0.0 s · 3 frames (3 content) · 3 measure, 0 opened at a known height
62
+ first frame started 0.36 s · visible ready 0.5 s (3 frames) · all ready 0.5 s · quiet 1.1 s · last move 1.1 s · settled 2.1 s
63
+ 5 moves, 1650 px: measure-height 3, reflow:measured 2
64
+ slowest: checkout/risks 0.7 s (waited 0.42 s, then 0.28 s), checkout/flows 0.6 s (waited 0.42 s, then 0.18 s), checkout/brief 0.6 s (waited 0.36 s, then 0.24 s)
65
+
66
+ 3:42:03 PM Checkout (boot) settled 1.0 s
67
+ committed 0.0 s · 3 frames (3 content) · 3 measure, 3 opened at a known height
68
+ first frame started 0.36 s · visible ready 0.5 s (3 frames) · all ready 0.5 s · quiet 0.0 s · settled 1.0 s
69
+ 0 moves
70
+ slowest: checkout/risks 0.6 s (waited 0.42 s, then 0.18 s), checkout/flows 0.6 s (waited 0.42 s, then 0.18 s), checkout/brief 0.5 s (waited 0.36 s, then 0.14 s)
71
+ ```
72
+
73
+ The first load opened each frame at a guess: each reported its height (`measure-height`) and the frames
74
+ below moved with the re-flow (`reflow:measured`) - five moves, the last at 1.1 s, settled at 2.1 s. The
75
+ second opened at the known heights: nothing moved (so no last move), and it settled at 1.0 s, the
76
+ one-second floor.
77
+
78
+ Each slowest frame says how long it waited for its turn to start, then how long it took once started. The canvas
79
+ starts a board's frames a few at a time: the first alone, once the first camera fit has settled - about 0.35 s after
80
+ the board mounts, `first frame started` - then up to four at once, those in view first. Here every frame took a
81
+ quarter of a second or less of its own; most of the time before them was the wait.
82
+
83
+ `quiet` and `last move` agree here. On a heavy board they part: one that held still for its first second
84
+ and then moved again as late frames reported their heights says `quiet 1.8 s · last move 15.0 s`. `quiet`
85
+ is the first still second; `last move` is when it stopped moving.
86
+
87
+ A load that was cut has no ready times to give; it says how many of its frames were ready by the cut
88
+ instead - `69 of 121 ready`, of the frames on the board then (those placed while it loaded included, those
89
+ removed not) - and, after its slowest, how many never finished (`52 never finished`):
90
+ `slowest` lists only frames that finished. A load can also say `never ready: ...`, `missing: ...`, its
91
+ errors (`late error` for one after it ended, settled or cut), how many errors past the first 50 went
92
+ unrecorded, and its gestures (how many, the worst p95, the frames over 33 ms). The last line says how many
93
+ records never reached the log, when any did.
94
+
95
+ ## Making a board faster
96
+
97
+ Read the load, name the lever, change it, compare the next load - you, or your agent with
98
+ `npx marver perf --loads --json`.
99
+
100
+ - **Moves named `measure-height`, then `reflow:...`** - the board opened before it knew its heights.
101
+ `marver dev` writes each content frame's settled height to `design/boards/_sizes.json`
102
+ ([Sizes](boards-and-folders.md#sizes)), and the next load opens at those heights (`savedHeights`
103
+ counts them) and the moves go, as above. Commit it with the rest of `design/`, and every clone and the
104
+ published canvas open at them too.
105
+ - **`slowest`** names the frames that held the load longest, of those that finished. Look at those first:
106
+ what they load, how much they render - the time after `then` is the frame's own. A load cut before its frames
107
+ finished counts the rest apart; cut at 120 s (`timeout`), the board is too heavy to finish - split it, or
108
+ lighten what its frames load.
109
+ - **A frame that waits long to start: the queue, not the frame.** `waited` (and `first frame started`) is the
110
+ time before its turn came; nothing in the frame shortens it. On a board of many frames the last wait for those
111
+ before them: fewer frames on the board, or lighter ones that hand their turn on sooner. The first frame's wait,
112
+ about 0.35 s, is the canvas's own and the same on every board - a one-frame board that settles at 1.0 s has no
113
+ lever left in the project.
114
+ - **Never ready, missing, errors** are broken frames, not slow ones: fix them first. A missing frame's
115
+ file was deleted or renamed.
116
+ - **The weight** (`settled.weight`) says how heavy the settled board is: elements in the page and its
117
+ frames, frames awake and asleep, the heap.
118
+ - **Late moves** came after the load ended - settled, or cut. After a cut at 120 s, or while the page was
119
+ hidden, they are the board still loading. After it settled - and any **`unknown`** move, with no cause
120
+ named - they say something moved the board after it looked done: worth a look, or an
121
+ [issue](https://github.com/TNEP4/marver/issues).
122
+
123
+ ## Frames
124
+
125
+ Each frame of a load ends at one outcome:
126
+
127
+ - **settled** - a content frame that renders a `Doc` measures its own height, and is done at its first
128
+ settled measurement taken at its current width (a width change waits for the next one);
129
+ - **ready** - every other frame (hi-fi, HTML, a content frame shown at a device size, content without a
130
+ `Doc`) is done when it is ready;
131
+ - **missing** - the frame is not in the manifest;
132
+ - **error** - it threw;
133
+ - **never-ready** - the ready watchdog gave up on it;
134
+ - **cut** - it was still on its way when the load ended.
135
+
136
+ An outcome counts only from the document the frame shows now: a message from a document since replaced, or
137
+ from one a reload is replacing, never counts. When the same board is read again its frames keep their
138
+ documents, and a frame whose document is older than the load is marked `kept`. A load with missing or
139
+ never-ready frames settles anyway, and says so.
140
+
141
+ ## Moves and why
142
+
143
+ Every change to a frame's place or size is a `move`, with its cause:
144
+
145
+ | Cause | What moved it |
146
+ |---|---|
147
+ | `measure-height` | a content frame reported its height |
148
+ | `measure-width` | a content frame took its `Doc`'s own width |
149
+ | `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 `+` |
150
+ | `manifest` | the frames on disk changed: a frame that arrived had its guessed size corrected |
151
+ | `drag` | you moved it (a drag's steps add up in one record while it waits to be sent) |
152
+ | `resize` | you resized it, or the board re-tidied after a resize |
153
+ | `device` | a device view (`0`-`5`), or a device size for the selection |
154
+ | `tidy` | a tidy (`t`) |
155
+ | `unplaced` | the **Not on a board** list changed |
156
+ | `spawn` | a frame added to the board on the canvas |
157
+ | `unknown` | a change with no cause named |
158
+
159
+ A move after the load ended - it settled, or it was cut (a board cut at 120 s, or while the page was hidden,
160
+ stays open and goes on loading) - is `late`. A load owns its board for as long as the board stays open, so
161
+ its late moves are its own; `perf --loads` counts them apart: `late, after it settled` or `late, after it
162
+ was cut`.
163
+
164
+ ## Gestures
165
+
166
+ Each pan, zoom or layout animation ends in a `gesture` record: how long it ran, how many frames it drew, and
167
+ the frame intervals as they are - `p50`, `p95`, `max`, and two plain counts, the intervals over 17 ms
168
+ (`over17ms`) and over 33 ms (`over33ms`) - plus `longFrames`, the long animation frames that started inside
169
+ it (long tasks, where the browser has no long-animation-frame). There is no "missed frames" count measured
170
+ against the median: it would call a steady half-rate gesture smooth. The sampler runs only from a gesture's
171
+ start to its end; at rest it asks for no frames.
172
+
173
+ ## Errors
174
+
175
+ The page records the errors it sees - its own (an uncaught error or rejection, a crash the shell caught,
176
+ with the component), a frame's, and the play stage's - with the message and up to three stack lines, 200
177
+ characters each. At most 50 per load, the same one at most once a second; those past 50 are counted, not
178
+ recorded. An error after its load settled or was cut is `late`: a load owns its board for as long as the
179
+ board stays open. Errors from before the first board mounted are kept apart (`unowned` in the JSON).
180
+
181
+ ## The records
182
+
183
+ Every line of `page.jsonl` carries `v`, `ws` (the project's key), `page` (one id per page load), `load`
184
+ (for `load`, `commit` and a request's `cut`, the request's own id; for every other record, the load that
185
+ owns the board then; `-` before the first), `seq` (its place in the page's order), `ts` and `kind`:
186
+
187
+ | `kind` | When | Fields |
188
+ |---|---|---|
189
+ | `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 |
190
+ | `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 |
191
+ | `visible` | the first camera fit after it | `nodes`, `ms`; `assumed` when no fit came before the load ended (the frames the camera showed then) |
192
+ | `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` |
193
+ | `move` | a frame's place or size changes | `node`, `dx`, `dy`, `dw`, `dh` (px), `cause`, `late` (after the load ended, settled or cut) |
194
+ | `quiet` | the first second after the commit with no move | `ms`: when the move before that second came (the commit, when none had) |
195
+ | `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`) |
196
+ | `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 |
197
+ | `gesture` | a pan, zoom or layout animation ends | `type` (`pan` / `zoom` / `layout`), `ms`, `frames`, `p50`, `p95`, `max`, `over17ms`, `over33ms`, `longFrames` |
198
+ | `error` | an error the page sees | `source` (`shell` / `frame` / `stage`), `frame`, `component`, `message`, `stack`, `late` |
199
+ | `dropped` | records were lost | `n`; `reason: "errors"` for errors past a load's 50 - with no reason, a full queue or a failed send |
200
+
201
+ Times are ms from the load's request. Frame records stop once the load has settled or been cut. `settled.moves`
202
+ counts every change to the board; `perf --loads` counts move records, where a drag's steps are one.
203
+
204
+ ## `--json`
205
+
206
+ `npx marver perf --loads --json` prints `{ minutes, loads, unowned, dropped }`. Each load has `board`,
207
+ `cause` and `state` - `settled`, `cut`, or `open` (still going, or its end past the window) - and, as it
208
+ got there:
209
+
210
+ - `cut`: `reason`, `ms`, and `request: true` when the cut came before it mounted;
211
+ - the commit: `commitMs`, `frames`, `byKind`, `measuring`, `savedHeights` - and `mountedAfterCut: true` for a
212
+ request cut first whose board arrived after all (`perf --loads` says `cut (hidden) at 0.4 s before it
213
+ mounted · mounted 3.2 s`, and counts its moves as late);
214
+ - `visible` (with `visibleAssumed`), `visibleReadyMs`, `allReadyMs`, `quietMs`, `lastMoveMs` (settled or cut),
215
+ `settledMs`;
216
+ - `moves`: `count`, `distance`, the top five `causes` as `[cause, count]` pairs, and `late` (count and
217
+ causes of the moves after the load ended, settled or cut);
218
+ - `slowest`: the five slowest frames that finished (`node`, `frame`, `ms` - when it settled, or was ready -
219
+ `outcome`, `admittedMs` - when it started: its turn to boot - and `readyMs`; `ms - admittedMs` is its own time);
220
+ - `firstStartedMs`: when the load's first frame started;
221
+ - `errors` (each once, every one, `late` marked), `errorsNotRecorded`, `neverReady`, `missing`,
222
+ `unfinished` (frames still on their way when it was cut: they never finished);
223
+ - on a load cut after it mounted, `framesAtCut` - the frames on its board when it was cut, those placed while it
224
+ loaded included, those removed not - and `readyByCut`, how many of them were ready (settled, or ready) by
225
+ then (both absent on one cut before it mounted);
226
+ - `gestures` (`n`, `worstP95`, `over33ms`) and `weight`.
227
+
228
+ `unowned` holds what a page recorded before its first board mounted (its errors, how many gestures);
229
+ `dropped`, how many records never reached the log. A send the page tried again is counted once.
230
+
231
+ ## What it costs
232
+
233
+ Nothing at rest. While no load is in flight and nothing waits to be sent, the recorder has no timer and no
234
+ frame callback of its own; it hears each change to the canvas's state with one check. Records wait 2 s for
235
+ company, then go in one request, one at a time. A send that fails on the network or the server is tried
236
+ twice more, 2 s apart; a refusal, or a canvas that stopped, is not tried again (a 403 goes once more,
237
+ after the page has asked for its request cookie). What never lands is counted in a `dropped` record. The
238
+ queue holds 2,000 records or 256 KB, and past that the oldest go, counted the same way. When the page
239
+ closes, Jam captures go first: while a capture is open or waiting to be sent, the recorder sends nothing;
240
+ otherwise its last records go with `keepalive`, 16 KB at most.
241
+
242
+ The dev server takes them only from the canvas's own page, rebuilds each from the fields its kind allows -
243
+ strings cut to 200 characters, 512 KB a request - and appends them to `page.jsonl`.
244
+
245
+ ## Options
246
+
247
+ | Option | |
248
+ |---|---|
249
+ | `--loads` | each board load in full |
250
+ | `--jam` | Jam's timings |
251
+ | `--json` | machine-readable |
252
+ | `--minutes <n>` | how far back to read: 60 by default (24 h with `--jam`) |
253
+ | `--root <dir>` | the project (default: here) |
254
+
255
+ Plain `npx marver perf` reads the reload log and ends with one line per board load.
256
+
257
+ ## In the page
258
+
259
+ In a dev canvas's console, `__mvPerf.report()` sums up the gestures so far - `gestureFrames`, `frameP50`,
260
+ `frameP95`, `frameMax`, `over17ms`, `over33ms`, `longFrames`, `longFrameP95`, `longFrameMax` and
261
+ `counters` - and `__mvPerf.reset()` starts over. On a published canvas, `?mvperf` in the URL (or
262
+ `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.26.1",
3
+ "version": "0.27.0",
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": "^8.0.0",
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(),
@@ -38,6 +38,10 @@ const posterNameFor = (src: string) => `${src}.poster.png`
38
38
  // has no such API (build already generated the file); a failed request just keeps the card.
39
39
  const requested = new Map<string, Promise<boolean>>()
40
40
  const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
41
+ // the canvas names its workspace in the frame's URL (spec 28 A1.11); a request from this frame names
42
+ // it too, so a frame left open after its canvas stopped never asks another project for anything
43
+ const WS = typeof location !== 'undefined' ? new URLSearchParams(location.search).get('ws') : null
44
+ const named = (h: Record<string, string> = {}) => (WS ? { ...h, 'x-mv-ws': WS } : h)
41
45
  // in-flight probes + generations, for the shot renderer's settle (like __mvLodBusy): a
42
46
  // screenshot taken while a poster is still being rendered would show the empty box
43
47
  let busy = 0
@@ -48,8 +52,8 @@ const requestPoster = (src: string): Promise<boolean> => {
48
52
  p = (async () => {
49
53
  // the owner gate wants the double-submit cookie echoed; a frame host opened cold has not
50
54
  // made an API GET yet, so prime it with the cheapest one first
51
- if (!csrf()) await fetch(`${ROUTE}/api/policy`).catch(() => null)
52
- const r = await fetch(`${ROUTE}/api/poster?src=${encodeURIComponent(src)}`, { headers: { 'x-mv-c': csrf() } }).catch(() => null)
55
+ if (!csrf()) await fetch(`${ROUTE}/api/policy`, { headers: named() }).catch(() => null)
56
+ 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
57
  return !!r?.ok
54
58
  })()
55
59
  requested.set(src, p)
@@ -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
- const gen = new URLSearchParams(location.search).get('r') ?? ''
96
- // and echo the revision the server stamped this document with (spec 26): what it shows
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: params.get('r') ?? '', doc: document.querySelector('meta[name="mv-doc"]')?.getAttribute('content') ?? '', meta: frameMod.meta && typeof frameMod.meta === 'object' ? frameMod.meta : undefined, phases }) }
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