@marver-design/marver 0.29.0 → 0.30.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +2 -1
  3. package/dist/{anchor-check-DhlpKl2K.mjs → anchor-check-Bv4o-R2T.mjs} +1 -1
  4. package/dist/{build-CWbrb2bl.mjs → build-zWGXSzly.mjs} +5 -4
  5. package/dist/cli.mjs +5 -5
  6. package/dist/{daemon-Sc_z8gT6.mjs → daemon-CChgWJNq.mjs} +2 -2
  7. package/dist/{dev-DWBKQhxf.mjs → dev-DOgIITpT.mjs} +8 -8
  8. package/dist/{perf-Denssrko.mjs → perf-6MOTHxay.mjs} +710 -99
  9. package/dist/perf-BCxAo0IS.mjs +1743 -0
  10. package/dist/{plugin-DqoZB-D6.mjs → plugin-CFWBcAba.mjs} +928 -539
  11. package/dist/{poster-CrsjqhY4.mjs → poster-DPPpQiva.mjs} +1 -1
  12. package/dist/{publish-bakes-DW-NDgU2.mjs → publish-bakes-_Zx8crP3.mjs} +2 -2
  13. package/dist/{recover-GtJ9UDAB.mjs → recover-mDUVsnPd.mjs} +1 -1
  14. package/dist/{shot-T04Ixrvq.mjs → shot-d4h_hJi9.mjs} +3 -3
  15. package/docs/app.md +194 -0
  16. package/docs/performance.md +100 -19
  17. package/package.json +1 -1
  18. package/src/client/frame-host/bridge.js +17 -8
  19. package/src/client/frame-host/inplace.ts +124 -0
  20. package/src/client/frame-host/inspect.d.ts +1 -0
  21. package/src/client/frame-host/inspect.js +13 -4
  22. package/src/client/frame-host/main.tsx +12 -3
  23. package/src/client/frame-host/messages.ts +85 -0
  24. package/src/client/frame-host/signals.d.ts +15 -0
  25. package/src/client/frame-host/signals.js +219 -0
  26. package/src/client/recorder-level.ts +41 -0
  27. package/src/client/shell/App.tsx +158 -88
  28. package/src/client/shell/BoardList.tsx +103 -48
  29. package/src/client/shell/Comments.tsx +66 -42
  30. package/src/client/shell/ContextMenu.tsx +3 -2
  31. package/src/client/shell/JamSurface.tsx +116 -71
  32. package/src/client/shell/LockedApp.tsx +19 -3
  33. package/src/client/shell/Play.tsx +94 -58
  34. package/src/client/shell/StatusPicker.tsx +19 -9
  35. package/src/client/shell/Toolbar.tsx +15 -7
  36. package/src/client/shell/api.ts +18 -4
  37. package/src/client/shell/app-bridge.ts +12 -6
  38. package/src/client/shell/app-perf.ts +31 -1
  39. package/src/client/shell/canvas/Canvas.tsx +17 -6
  40. package/src/client/shell/canvas/FrameNode.tsx +25 -12
  41. package/src/client/shell/canvas/Sticky.tsx +4 -2
  42. package/src/client/shell/canvas/ctl.ts +2 -0
  43. package/src/client/shell/canvas/ready-watch.ts +4 -0
  44. package/src/client/shell/canvas/sleep.ts +2 -0
  45. package/src/client/shell/canvas/updates.ts +13 -6
  46. package/src/client/shell/commands.ts +765 -0
  47. package/src/client/shell/comments-store.ts +42 -27
  48. package/src/client/shell/goto.ts +11 -6
  49. package/src/client/shell/jam-keys.ts +141 -75
  50. package/src/client/shell/jam-lane.tsx +19 -12
  51. package/src/client/shell/jam-panel.tsx +61 -48
  52. package/src/client/shell/jam-session.tsx +41 -37
  53. package/src/client/shell/jam-state.ts +9 -1
  54. package/src/client/shell/jam-surface-parts.tsx +8 -6
  55. package/src/client/shell/jam-ui.tsx +9 -6
  56. package/src/client/shell/jam-voice.ts +4 -2
  57. package/src/client/shell/main.tsx +7 -1
  58. package/src/client/shell/marks-ui.tsx +11 -0
  59. package/src/client/shell/perf.ts +51 -5
  60. package/src/client/shell/recorder-core.ts +4 -1
  61. package/src/client/shell/recorder-hmr.ts +36 -0
  62. package/src/client/shell/recorder-reloads.ts +264 -0
  63. package/src/client/shell/recorder-seams.ts +116 -0
  64. package/src/client/shell/recorder-self.ts +73 -0
  65. package/src/client/shell/recorder-signals-core.ts +139 -0
  66. package/src/client/shell/recorder-signals.ts +485 -0
  67. package/src/client/shell/recorder.ts +118 -43
  68. package/src/client/shell/store.ts +112 -32
  69. package/src/client/shell/whiteout-probes.ts +3 -1
  70. package/src/client/stage/main.tsx +10 -5
  71. package/src/shared/app-api.ts +28 -6
  72. package/src/shared/app-perf.ts +99 -6
  73. package/src/shared/app-report.ts +586 -0
  74. package/src/shared/perf-records.ts +445 -0
  75. package/src/shared/perf-run.ts +6 -2
  76. package/dist/perf-jam-CLkERSHo.mjs +0 -642
@@ -1,4 +1,4 @@
1
- import { i as capture, p as findChrome } from "./shot-T04Ixrvq.mjs";
1
+ import { i as capture, p as findChrome } from "./shot-d4h_hJi9.mjs";
2
2
  import { constants, copyFileSync, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
3
3
  import { basename, dirname, join, sep } from "node:path";
4
4
  import { pathToFileURL } from "node:url";
@@ -1,6 +1,6 @@
1
1
  import { o as slideSize } from "./cli.mjs";
2
- import { c as ASK_MAX, l as bakeBatch } from "./plugin-DqoZB-D6.mjs";
3
- import { p as findChrome, s as planShot } from "./shot-T04Ixrvq.mjs";
2
+ import { c as ASK_MAX, l as bakeBatch } from "./plugin-CFWBcAba.mjs";
3
+ import { p as findChrome, s as planShot } from "./shot-d4h_hJi9.mjs";
4
4
  import { MIME } from "./serve-DQv3Ti6X.mjs";
5
5
  import { copyFileSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
6
6
  import { extname, isAbsolute, join, relative, resolve } from "node:path";
@@ -1,6 +1,6 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
2
  import { d as recoverTarget, r as legacyEntry, u as recoverEntries, v as workspaceId } from "./slots-Dn4Onb0V.mjs";
3
- import { DevStartError, dev } from "./dev-DWBKQhxf.mjs";
3
+ import { DevStartError, dev } from "./dev-DOgIITpT.mjs";
4
4
  //#region src/cli/recover.ts
5
5
  /**
6
6
  * `marver dev --recover` (spec 28 A1.6). A Jam capture the page could not send waits in that browser's
@@ -1,6 +1,6 @@
1
1
  import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
2
2
  import { a as ROUTE, o as slideSize } from "./cli.mjs";
3
- import { t as logJam } from "./perf-jam-CLkERSHo.mjs";
3
+ import { d as logJam } from "./perf-BCxAo0IS.mjs";
4
4
  import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
5
5
  import { join } from "node:path";
6
6
  import { randomBytes } from "node:crypto";
@@ -524,8 +524,8 @@ async function shootFrame(opts) {
524
524
  };
525
525
  const plan = planShot(frame, viewports, size);
526
526
  if (frame.kind !== "html") try {
527
- const { scanAssetRefs } = await import("./build-CWbrb2bl.mjs");
528
- const { ensurePoster } = await import("./poster-CrsjqhY4.mjs");
527
+ const { scanAssetRefs } = await import("./build-zWGXSzly.mjs");
528
+ const { ensurePoster } = await import("./poster-DPPpQiva.mjs");
529
529
  const refs = scanAssetRefs(readFileSync(join(root, frame.file), "utf8"), frame.file);
530
530
  for (const r of refs) if (r.endsWith(".poster.png")) await ensurePoster(join(root, "design", "assets"), r.slice(0, -11));
531
531
  } catch {}
package/docs/app.md ADDED
@@ -0,0 +1,194 @@
1
+ # Marver for Mac
2
+
3
+ Marver for Mac shows every canvas you run on this Mac in one window, a tab each, and tells you when one needs you.
4
+ It shows the canvases you run and starts none: a canvas still runs from its repo with `npx marver dev`, and stops
5
+ there. A shared canvas's https link opens in a tab of its own too.
6
+
7
+ **[Download Marver for Mac](https://github.com/TNEP4/marver-app/releases/latest/download/Marver-arm64.dmg)** ·
8
+ Apple silicon · macOS 13 or later
9
+
10
+ Help > Marver Help opens this page. The app's source is [`app/`](../app) in this repository; its releases, each with
11
+ what changed, are in [TNEP4/marver-app](https://github.com/TNEP4/marver-app/releases).
12
+
13
+ ## What it needs
14
+
15
+ - **A Mac with Apple silicon and macOS 13 (Ventura) or later.** On an Intel Mac, or on macOS 12 or older, it does not
16
+ open at all ([below](#on-an-intel-mac-or-an-older-macos)).
17
+ - **Canvases on Marver 0.27 or later.** They show in the app, a tab each, and closing, reloading or quitting asks
18
+ before losing their unsaved work. Marks, notices and live pictures need **0.29 or later**, the version to use with
19
+ the app. A canvas on 0.26 or older does not appear: update it with `npm i -D @marver-design/marver@latest`.
20
+
21
+ ## Install
22
+
23
+ 1. Download [Marver-arm64.dmg](https://github.com/TNEP4/marver-app/releases/latest/download/Marver-arm64.dmg)
24
+ (Apple silicon · macOS 13 or later). Every release has this name, so the link always fetches the latest; the disk
25
+ image it opens is named for its version, "Marver 1.0.0". Safari may first ask whether to allow downloads from
26
+ GitHub's download site: allow it.
27
+ 2. Open it and drag Marver onto Applications.
28
+ 3. Eject the disk image.
29
+ 4. Open Marver from Applications. macOS asks once, because the app was downloaded: whether to open an app
30
+ "downloaded from the Internet", adding that "Apple checked it for malicious software and none was detected".
31
+ Marver is signed with a Developer ID and notarised by Apple. Choose Open; that is the only question.
32
+
33
+ **Opening it straight from the disk image works too.** macOS asks there first (Open, Show Disk Image, Cancel). Marver
34
+ then moves itself into Applications without asking, quits and opens from there, so macOS asks its question a second
35
+ time, at the copy in Applications. Dragging it in first saves that second question. Once moved, the tab strip says
36
+ once: "**Marver moved itself to Applications.** You can eject the disk image." Opened from another folder, such as
37
+ Downloads, Marver moves itself the same way and says "You can delete the copy in Downloads." It never deletes the copy
38
+ it came from.
39
+
40
+ **When something is already in Applications**, Marver moves nothing. It says what it found, and what to do:
41
+
42
+ | In Applications | Marver says | Then |
43
+ |---|---|---|
44
+ | a Marver of this version or newer | "Marver 1.0.1 is already in Applications" | "Open it, and this copy quits. You can delete this copy afterwards." Open It or Cancel |
45
+ | an older Marver | "An older Marver (0.3.0) is in Applications" | "To replace it, drag this Marver into Applications and choose Replace." Show Both or Cancel |
46
+ | another app named Marver | "Another app named Marver is in Applications" | "Marver doesn't replace it. Move it out of Applications, then drag this Marver in." Show Both or Cancel |
47
+ | an empty folder named Marver.app | "An empty folder named Marver.app is in Applications" | "Move that empty folder to the Trash, then open the download again." Show Both or Cancel |
48
+ | anything else of that name | "Something named Marver.app is in Applications" | "Marver doesn't replace what it doesn't know. Move it out of Applications, then drag this Marver in." Show Both or Cancel |
49
+ | nothing, but this account can't add apps there | "Marver can't add itself to Applications" | "This account can't add apps to Applications. Drag Marver into Applications in Finder: it asks for an administrator's name and password." Show Both or Cancel |
50
+
51
+ Show Both shows this copy and what is in Applications in Finder, for the drag. Marver never replaces, renames or
52
+ deletes what is in Applications, and never asks for an administrator's password itself: when one is needed (an older
53
+ Marver this account can't change, say), Finder asks. Cancel opens Marver where it is, and it asks again the next time.
54
+ A Marver that runs outside Applications works, but does not update itself. The Applications folder in your home folder
55
+ (`~/Applications`) counts too: a Marver there is not moved, and updates itself.
56
+
57
+ ## An earlier Marver
58
+
59
+ A Marver before 1.0 (any 0.x, `~/Applications/Marver.app` included) has no updater, so it is replaced once, by hand:
60
+
61
+ 1. Quit it. While one Marver runs, opening another only brings the running one forward.
62
+ 2. Install 1.0 as above. An older Marver in Applications is the "An older Marver" case: drag 1.0 over it and choose
63
+ Replace.
64
+ 3. Drag any other old copy to the Trash, so you never open it by mistake.
65
+
66
+ Your settings and tabs stay: every version keeps them in the same folders ([Uninstalling](#uninstalling)).
67
+
68
+ ## First launch
69
+
70
+ Marver opens on Home. With no canvas running, Home says how to start one: `npx marver dev` in a repo with Marver ("It
71
+ appears here, with its own tab, a second after it starts."), and for a repo without Marver yet, `npm i -D
72
+ @marver-design/marver && npx marver init` first. Each command has a button that copies it. Every canvas running on
73
+ this Mac gets its own tab; `⌘L`, or Home's field, opens a link - a local canvas's, or a shared canvas's.
74
+
75
+ ## What it asks, and when
76
+
77
+ - **Notices.** Nothing touches macOS's notices or the Dock before you choose. The first time a canvas needs you while
78
+ Marver's window is in front, the strip offers "Get a notice when a canvas needs you": Turn On, and macOS asks then;
79
+ Not now, and it never offers again. Settings' Notices row turns them on or off later.
80
+ - **The microphone.** macOS asks the first time a canvas listens, at your first Jam session or capture with the
81
+ microphone on, giving Marver's reason: "Marver uses the microphone only during a Jam session you start."
82
+
83
+ ## Updates
84
+
85
+ Marver keeps itself up to date from the Applications folder. It checks 30 seconds after it opens, every 4 hours and
86
+ when the Mac wakes, and downloads an update quietly; a check that finds nothing says nothing. **Marver > Check for
87
+ Updates…** checks now and answers in the strip: "Marver 1.0.0 is up to date", "Couldn't check for updates · You're
88
+ offline" or "Couldn't check for updates · Try again later". While it works, the item reads Checking for Updates… or
89
+ Downloading Update….
90
+
91
+ **When an update is ready**, the strip says "1.0.1 is ready" with **Restart to Update** (its tooltip is the first line
92
+ of what changed), and the Marver menu reads Restart to Install Update. Two ways to install it:
93
+
94
+ - **Restart to Update** closes your canvases as a quit does, installs the update and opens the new Marver. A canvas
95
+ with unsaved work - an unsent capture, an edit not yet saved - holds it: its tab comes forward saying "**Unsaved
96
+ work here** the update waits", and from any other tab the strip says "1.0.1 waits for Checkout" (that canvas's
97
+ name) with Try Again. Once that work is saved, or its tab closed, the strip is back to "1.0.1 is ready": press
98
+ Restart to Update again. A canvas the app can't read, such as a shared one, asks first, as it does at a quit
99
+ ("Restart to update anyway?"). Marver never restarts by itself.
100
+ - **Quit Marver.** A plain quit installs the downloaded update: the next time you open Marver, it is the new version.
101
+
102
+ **After an update, Marver opens as it does after a quit.** With Settings' "Reopen tabs at launch" on (the default),
103
+ each running canvas gets its tab back on the board it showed, and Settings if it was open; with it off, Marver starts
104
+ on Home and every running canvas still gets its tab. Shared canvases do not come back in tabs (Home's Shared canvases
105
+ reopens them), and a canvas that is not running gets no tab. What a page held only in memory, such as an open panel or
106
+ a scroll position, does not come back. The first launch after says "Updated to 1.0.1", once.
107
+
108
+ **Where it updates.** Only from an Applications folder, and only where this account can change Marver and its
109
+ folder: Marver never asks for an administrator's password to update. Otherwise the Marver menu says why, in place of
110
+ Check for Updates…:
111
+
112
+ | The menu | Its alert |
113
+ |---|---|
114
+ | Updates Need the Applications Folder… | "Marver updates itself only from the Applications folder" - "This Marver runs from ~/Downloads. Quit it, move it to Applications, and open it from there: it then checks for updates on its own." OK or Show in Finder |
115
+ | Updates Unavailable… | "Marver can't update itself here" - "Updating replaces Marver where it is, and this account can't change /Applications. Download the latest Marver and install it again to update." OK or Download |
116
+ | Updates Unavailable… | "Marver can't check for updates" - "Its updater couldn't start on this Mac. Download the latest Marver to update by hand." OK or Download |
117
+
118
+ **If an update goes wrong:**
119
+
120
+ - The restart can fail before Marver ends: "Marver couldn't restart to install 1.0.1" - "Your canvases were closed
121
+ safely. Open Marver again: it may already be 1.0.1, and if not, it tells you how to get it." Quit, then open Marver.
122
+ - When the update did not install, Marver opens as the version it was and the strip says "1.0.1 couldn't be
123
+ installed", with Download, which fetches the latest disk image in your browser. Open it, drag Marver into
124
+ Applications and choose Replace.
125
+ - **If Marver won't open after an update**, download
126
+ [the disk image](https://github.com/TNEP4/marver-app/releases/latest/download/Marver-arm64.dmg) again, open it,
127
+ drag Marver into Applications and choose Replace. Your settings and tabs stay.
128
+
129
+ ## The performance report
130
+
131
+ When Marver is slow, crashes or flashes, a report helps find out why. **Help > Export Performance Report…** (also on a
132
+ canvas's page that keeps crashing, beside Copy Details) opens a save panel on
133
+ `~/Downloads/Marver-report-YYYY-MM-DD.json`, writes the file and shows it in Finder. Nothing is uploaded, and the file
134
+ is JSON you can read before you send it. If it cannot be saved, an alert says why ("The performance report wasn't
135
+ saved") and no half-written file is left.
136
+
137
+ **What it holds:** the last 7 days of the app's own records in `~/.marver/perf/` (fewer when Settings' "Keep
138
+ performance files" keeps fewer):
139
+
140
+ - when it was made, and the app's, Electron's and macOS's versions;
141
+ - your Mac: its chip, cores, memory, model and macOS version, and each display's scale and refresh rate;
142
+ - one row per hour: the app's own CPU and memory, the canvases' memory, the GPU process's memory, the highest memory
143
+ pressure and the worst thermal state;
144
+ - events, newest first, at most 2,000: a page or a helper process that crashed or stopped answering, the GPU
145
+ restarting or changing, power and heat, memory pressure, tabs unloaded and reopened, the flashes you marked (whether
146
+ a picture was kept, never the picture), the updater's and the move's steps, and an error in the app by its type
147
+ alone (such as `TypeError`);
148
+ - how long tab switches took, per day, and how many crash reports the app kept;
149
+ - for each part, whether it was read whole.
150
+
151
+ A tab appears only as an opaque id, such as `t3`.
152
+
153
+ **What it never holds:** board, canvas or file names; paths, hosts or links; error messages or stack traces; process
154
+ names or ids; pictures; traces or crash dumps. Board loads and headless runs are not in it either: they stay in each
155
+ repo, where `npx marver perf` shows them ([Performance](performance.md)).
156
+
157
+ **Where to send it:** [open an issue on TNEP4/marver](https://github.com/TNEP4/marver/issues/new), say what happened
158
+ and roughly when, and attach the file.
159
+
160
+ ## `~/.marver/` and its README
161
+
162
+ Marver keeps its settings and its state in `~/.marver/`, beside the files `marver dev` keeps there. At every launch
163
+ the app writes a `README.md` in it, for you and your coding agent: every file, every setting, and the rules for
164
+ changing them (edits to the README itself are lost). Settings (Marver > Settings…) writes `config.json` and
165
+ `theme.json`. Home's Show the Files opens the folder; Help > Show Performance Files opens the app's performance records.
166
+
167
+ ## Uninstalling
168
+
169
+ Quit Marver and drag it from Applications to the Trash. Its files stay until you delete them:
170
+
171
+ - `~/Library/Application Support/Marver`: the app's web data, shared canvases' sign-ins among it;
172
+ - in `~/.marver/`, the app's own: `config.json`, `theme.json`, `schemas/`, `state/`, `perf/` and `README.md`.
173
+
174
+ The rest of `~/.marver/` (`running/`, `prefer/`, `canvases/`, `models/`) is what `npx marver` keeps for your repos'
175
+ canvases: delete the whole folder only when you no longer use Marver at all.
176
+
177
+ ## On an Intel Mac, or an older macOS
178
+
179
+ The app needs Apple silicon and macOS 13 or later. On any other Mac nothing of it runs: macOS refuses to open it with
180
+ its own message, and Marver has no chance to explain. That is why the requirement sits beside every download link.
181
+ Marver runs the same in your browser: `npx marver dev`.
182
+
183
+ ## Troubleshooting
184
+
185
+ - **A canvas does not appear.** `npx marver ls` lists every canvas running on this Mac, with its version. Not listed:
186
+ it is not running, so start it with `npx marver dev` in its repo. Listed at 0.26 or older: update it
187
+ (`npm i -D @marver-design/marver@latest`) and start it again.
188
+ - **A tab says "Not a Marver canvas".** "Something else answers on this port: a canvas that stopped without cleaning
189
+ up, or another program, or the canvas failed to render - its terminal says why. The app shows nothing it serves."
190
+ Start the canvas again and press Try Again, or Close Tab.
191
+ - **Marver does not update.** The Marver menu says why ([Where it updates](#updates)).
192
+ - **Marver won't open after an update.** Download the disk image again and drag Marver over the old one (Replace).
193
+ - **Anything else:** [an issue on TNEP4/marver](https://github.com/TNEP4/marver/issues), with the performance report
194
+ attached when it is about speed, a crash or a flash.
@@ -8,20 +8,26 @@ agent. A published canvas records nothing.
8
8
 
9
9
  | Log | What | Read with |
10
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` |
11
+ | `design/.local/perf/reloads.jsonl` | each file change and what it came to: the frames it reached, each one's wait and redraw, in-place updates; page-wide reloads, sent or dropped, and the file behind them; 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: what triggered it, every frame's outcome, every move and why, when the board settled; gestures and what held them up; theme switches, modes, every command you gave, re-renders; errors | `npx marver perf --loads` |
13
13
  | `design/.local/perf/jam.jsonl` | Jam's timings: numbers and fixed codes only, never your words | `npx marver perf --jam` |
14
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
15
 
16
16
  `design/.local/` is gitignored, and `marver dev` never serves it. The perf folder is yours alone: mode 700,
17
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.
18
+ starts.
22
19
 
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.
20
+ Each log keeps 14 days, whole. It is a live file plus closed segments, `page.<opened>-<newest>.jsonl`: the live file is
21
+ closed - a rename - 24 hours after it was opened or once it passes its size (8 MB for `page.jsonl` and `reloads.jsonl`,
22
+ 2 MB for `jam.jsonl` and `runs.jsonl`). `<newest>` is a safe upper bound on the newest record in it, and a segment is
23
+ deleted once that is 14 days old, at start and hourly: never read, never rewritten. A log whose rate is far past any
24
+ measured day meets its safety cap (128 MB for `page.jsonl`, 48 MB for `reloads.jsonl`, 8 MB each for the others): its
25
+ oldest segments go, and a `dropped` record with `reason: "retention-cap"` says how many records. A file an earlier
26
+ version left is closed as a segment as it stands once it is due. `npx marver perf` reads every segment and the live file as one log.
27
+
28
+ `page.jsonl` holds frame names, node keys, command names, key combinations and numbers. It never holds what you type, a
29
+ comment's words, a setting's value, your clipboard or a request's body. Error and console-error messages are kept as the code
30
+ produced them, 200 characters, and can hold file paths or, in rare cases, text you typed, so, like the rest, they stay on this Mac.
25
31
 
26
32
  ## A board load
27
33
 
@@ -176,7 +182,8 @@ Each frame of a load ends at one outcome:
176
182
 
177
183
  An outcome counts only from the document the frame shows now: a message from a document since replaced, or
178
184
  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
185
+ documents, and a frame whose document is older than the load is marked `kept` - all but a frame that had failed, one
186
+ silent past its retry, and one whose sizing the file changed: those load again, and are not `kept`. A load with missing or
180
187
  never-ready frames settles anyway, and says so.
181
188
 
182
189
  ## Moves and why
@@ -211,11 +218,42 @@ it (long tasks, where the browser has no long-animation-frame). There is no "mis
211
218
  against the median: it would call a steady half-rate gesture smooth. The sampler runs only from a gesture's
212
219
  start to its end; at rest it asks for no frames.
213
220
 
221
+ From 0.30 it also says what the gesture went through and what held it up: `scale` (`from`, `to`, `min`, `max`), `visible` and
222
+ `awake` (frames on screen, and how many were live documents), `by` (the command behind it, if any), and `loaf`, the three
223
+ longest long animation frames, each with its blocking time and the script behind it (its path, or the frame it belongs to).
224
+
225
+ ## One edit, followed
226
+
227
+ Each file change the dev server's watcher sees gets an id, `change`, and `reloads.jsonl` carries it through. `change`: the
228
+ file, when it was seen, what it came to (`reloadN`, `inPlaceN`, `fullReload`). `invalidate`: the send to the page, as a
229
+ `revision`. `invalidated`: what each page found for that revision - how many of the board's nodes were awake, asleep, or held,
230
+ and why (`offscreen`, `leased`, `play`, `loading`, `missing`). Each redraw's `ready`: `queuedMs` (its wait), `bootMs` (its
231
+ redraw), `heldBy` (what kept it waiting). `inplace`: a document that fetched an update in place, with `applied` `false` when Vite
232
+ said it failed and `unknown` otherwise - a fetch does not prove an update applied, and the record does not claim it.
233
+
234
+ A `full-reload` names its file and how it knows (`fileBy`): the one run open, `ambiguous` with `candidates` when several
235
+ overlap, `unknown` when none is. Attribution the code cannot establish is said to be unknown, never guessed; that is a correct
236
+ answer, not a gap.
237
+
238
+ ## Commands
239
+
240
+ Every command you give writes a `cmd` record, however you give it: `cmd` (its name), `via` (`key`, `click`, `menu`, `context`,
241
+ `drag`, `dblclick`, `relay`), `keys` (the combination), `in` (where it arrived), `board`, `frame`, `frames`. A command decided at
242
+ once writes one record, `phase: once`; the others a `start` at the input and an `end` with the same `id`: `outcome` (`done`,
243
+ `failed`, `noop`, `cancelled`, `unobserved`), `why` (a fixed code), `ms`, `steps` (milestones). `done` is bound to the effect:
244
+ C ends when comments mode has reached every visible frame, copy image when the clipboard holds it, opening a board when
245
+ it settled. `unobserved` says only that no signal came by the command's deadline; a later completion is written with `late`.
246
+ A `start` with no `end` reads as `interrupted` when something shows its page or the app ended, otherwise `unmatched`. What a
247
+ command caused (`mode`, `theme`, `load`, `gesture`) names it in `by`. Names and key combinations only: never a value.
248
+
214
249
  ## Errors
215
250
 
216
251
  The page records the errors it sees - its own (an uncaught error or rejection, a crash the shell caught,
217
252
  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
253
+ characters each. From 0.30 also console errors (`console`; warnings are counted, in `warnings`, with no text), build errors
254
+ (`vite`, with its file and plugin), failed requests (`api`: `route`, `method`, `status`, `ms`, never a query) and elements that
255
+ would not load (`resource`: `tag`, `url` without its query). Each error says the `modes` that were on. A frame limits its noisy
256
+ sources itself, before formatting anything, and counts what it refused. At most 50 per load, the same one at most once a second; those past 50 are counted, not
219
257
  recorded. An error after its load settled or was cut is `late`: a load owns its board for as long as the
220
258
  board stays open. Errors from before the first board mounted are kept apart (`unowned` in the JSON).
221
259
 
@@ -237,6 +275,13 @@ owns the board then; `-` before the first), `seq` (its place in the page's order
237
275
  | `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
276
  | `gesture` | a pan, zoom or layout animation ends | `type` (`pan` / `zoom` / `layout`), `ms`, `frames`, `p50`, `p95`, `max`, `over17ms`, `over33ms`, `longFrames` |
239
277
  | `error` | an error the page sees | `source` (`shell` / `frame` / `stage`), `frame`, `component`, `message`, `stack`, `late` |
278
+ | `theme` | a theme switch ended | `scope` (`view` / `selection` / `play`), `to`, `frames`, `applied`, `p50Ms`, `maxMs`, `late`, `outcome`, `by` |
279
+ | `mode` | a mode was entered or left | `mode`, `phase`, `shownMs` or `firstFrameMs`, `frames`, `outcome`; on exit `heldMs`, `errors`; `by` |
280
+ | `cmd` | a command ([Commands](#commands)) | `phase`, `id`, `cmd`, `via`, `keys`, `in`, `board`, `frame`, `frames`, `arg`; `outcome`, `why`, `ms`, `steps`, `late` |
281
+ | `renders` | a minute's React commits | `minute`, `rows`: `who` (shell, stage, a frame), `commits`, `ms`, `maxMs`, `inGesture` |
282
+ | `warnings` | console warnings counted | `n`, `top` (by node) |
283
+ | `hmr` | the dev server's socket | `phase` (`lost` / `back`), `downMs` |
284
+ | `self` | every 5 minutes it recorded anything | `cpuMs`, `hookMs`, `records`, `bytes`, `dropped`: the recorder's own cost |
240
285
  | `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
286
 
242
287
  Times are ms from the load's request. Frame records stop once the load has settled or been cut. `settled.moves`
@@ -284,6 +329,12 @@ otherwise its last records go with `keepalive`, 16 KB at most.
284
329
  The dev server takes them only from the canvas's own page, rebuilds each from the fields its kind allows -
285
330
  strings cut to 200 characters, 512 KB a request - and appends them to `page.jsonl`.
286
331
 
332
+ The recorder measures itself. Every 5 minutes in which it recorded anything, the page writes a `self` record: `cpuMs`,
333
+ `hookMs` by hook (`console`, `theme`, `mode`, `cmd`, `renders`, `send`), `records`, `bytes` and `dropped`. A page's clock
334
+ is coarse (100 µs), so these are sums of coarse readings: right on average, never to the microsecond. To measure the
335
+ cost itself, `npx marver perf run <board> --recorder core` turns off everything but the load tracking a run reads
336
+ ([Headless runs](#headless-runs)); `core` and `full` runs never compare as one, since the level is one of a run's inputs.
337
+
287
338
  ## Headless runs
288
339
 
289
340
  `npx marver perf run <board>` measures a board the same way every time, in the canvas's own headless Chrome
@@ -358,25 +409,45 @@ their reason. `--days <n>` (14 by default) and `--json` as elsewhere.
358
409
  |---|---|
359
410
  | `--loads` | each board load in full |
360
411
  | `--jam` | Jam's timings; with the Mac app, its live pictures kept, failed and rendered instead |
361
- | `run <board>` | a headless run of the board ([Headless runs](#headless-runs)); with `--slow` and `--repeat <n>` (1-5) |
412
+ | `run <board>` | a headless run of the board ([Headless runs](#headless-runs)); with `--slow`, `--repeat <n>` (1-5) and `--recorder core\|full` (`full`) |
362
413
  | `--runs` | the headless runs, compared inside their cohorts; with `--against <run>` and `--days <n>` (14) |
363
414
  | `--crashes` | the Mac app's crashes and hangs of this repo's canvases (below) |
364
415
  | `--flashes` | the flashes marked in the Mac app, and the white-out candidates (below) |
365
416
  | `--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 |
417
+ | `--all` | every canvas this Mac knows, one summary ([below](#every-canvas)); with `--live`, their live files; with `--flashes`, also the marks on other canvases or on Home |
418
+ | `--live` | a tail in the terminal ([below](#a-tail)); with `--kinds a,b` only those kinds, with `--json` the raw lines |
419
+ | `--days <n>` | how far back `--all`, `--runs`, `--crashes`, `--flashes` and `--machine` read: 14 by default |
368
420
  | `--json` | machine-readable |
369
421
  | `--minutes <n>` | how far back to read: 60 by default (24 h with `--jam`) |
370
422
  | `--root <dir>` | the project (default: here) |
371
423
 
372
424
  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.
425
+ headless run's loads (`marver perf run`): they say how many. From 0.30 an edit is its change id, so several lines of one
426
+ change are one edit; older lines, which have none, count as they always did. A record written twice - a retry can do that
427
+ past the server's own check - is read once, by its `page` and `seq`, in every view.
428
+
429
+ ### Every canvas
430
+
431
+ `npx marver perf --all` needs no repo. It lists every canvas this Mac knows - those running, and those the Mac app
432
+ remembers, one per real path - and for each, over `--days`: board loads, how many came after an edit, how many settled,
433
+ all-ready p50 / p90 / max, the most frames, the largest heap, the worst gesture p95 (p50 / max), edit to last redraw,
434
+ page-wide reloads whose file is ambiguous or unknown, re-renders (React's render work only, not layout or paint), the
435
+ longest theme switch, comments mode's shown p50, errors by source, and commands failed, unobserved or interrupted. A canvas
436
+ with no records says so. Then the app's: launches and the time to the first canvas, crashes, hangs, flashes, white-out
437
+ candidates by what they happened during, and the window time the detector could not cover, and why. `--json` emits the same.
438
+
439
+ ### A tail
440
+
441
+ `npx marver perf --live` follows this repo's live files (`--all`: every known canvas's) and the app's `app.jsonl` from now,
442
+ one line per record, until Ctrl-C. It is about 3 s behind: the page's 2 s batch and the app's 2 s flush. A file that closes
443
+ as a segment is read to its end before the new one is opened, so nothing is skipped or read twice.
374
444
 
375
445
  ## The Mac app's half
376
446
 
377
447
  The Mac app (0.2 and later) records what only the app can see, in `~/.marver/perf/`: `app.jsonl` (Marver Dev writes
378
448
  `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
449
+ names the launch, `seq` counts its lines, `machine` the profile the line was written on. From app 1.0.1 the `sample` and
450
+ `agx` lines are in `samples.jsonl` (`samples-dev.jsonl`), their rows unchanged, and one `seq` runs across both files. Every 5 s the app samples its
380
451
  processes (`getAppMetrics()`: CPU from cumulative time, memory as each process's working set, a canvas renderer's own
381
452
  footprint from its page, the memory pressure level), keeps the last minute in memory and writes one `sample` line a
382
453
  minute; and it records renderer and GPU process ends, hangs, GPU changes, power and thermal events, each tab's state
@@ -388,9 +459,19 @@ its `tab`, `ws`, `commit` and `page` - the page id the shell's hello sent, which
388
459
  error main did not catch: a `main-error` line, in `app-dev.jsonl` for Marver Dev, written the moment it happens).
389
460
  `machine/<hash>.json` holds one profile per distinct machine state (the chip, the displays and their rates, the
390
461
  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.
462
+ old lines keep theirs. The app keeps 14 days of it (`keepPerfDays`), each file a live file plus closed segments as above
463
+ (4 MB or 24 h for `app.jsonl`, cap 16 MB; 8 MB or 24 h for `samples.jsonl`, cap 128 MB), checked a few seconds after
464
+ launch and then hourly; 50 flash pictures and 10 crash reports; a profile a headless run wrote stays at least 14 days, as
465
+ long as a repo's `runs.jsonl` may name it.
466
+
467
+ Each launch writes one `launch` line, whatever the recorder setting: ms from process start to ready, to the window shown,
468
+ and to the first local canvas uncovered, with that canvas's `page`, which joins its boot `load`; what was restored; and with
469
+ no canvas after 30 s, why (`home`, `none-restored`, `timeout`).
470
+
471
+ The white-out detector watches more than gestures: a tab being shown, and with a 0.30 canvas a board load, a theme switch
472
+ and an on-screen frame's reload. Outside gestures it takes at most 3 s of capture per rolling minute, each capture charged at
473
+ its true length, and a window ends at 10 s. A minute's `sample` carries `whiteout`: its windows, captures, capture time, and
474
+ the time it could not cover, by why (`stage`, a play stage covering the canvas; `budget`; `hidden`). A candidate says `why`.
394
475
 
395
476
  `marver perf` joins the two halves by `page`, so each app event lands on the board load it happened in:
396
477
 
@@ -407,7 +488,7 @@ days, as long as a repo's `runs.jsonl` may name it.
407
488
  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
489
  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
490
  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.
491
+ shows them). White-out candidates, found automatically, are listed apart with what they happened during: automatic, not verified.
411
492
  - `--machine`: the profiles, grouped by host (the app and a headless run of one Mac share its `hostHash`), which is
412
493
  current, and how many records and runs name each.
413
494
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marver-design/marver",
3
- "version": "0.29.0",
3
+ "version": "0.30.1",
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,
@@ -8,6 +8,7 @@
8
8
  import { createInspect } from './inspect.js'
9
9
  import { createKeys } from './keys.js'
10
10
  import { createRecorder } from './trail.js'
11
+ import { startDocumentSignals } from './signals.js'
11
12
 
12
13
  const isHtmlFrame = new URL(import.meta.url).searchParams.get('html') === '1'
13
14
  // same-origin parent (the shell): a fixed target origin keeps posts (incl. picked anchor
@@ -23,6 +24,9 @@ window.__mvBoot = BOOT
23
24
  // the URL revision the shell gave this document (its generation guard)
24
25
  const GEN = new URLSearchParams(location.search).get('r') ?? ''
25
26
  post({ type: 'sh:boot', id, gen: GEN, boot: BOOT })
27
+ // the recorder's hooks in this document (spec 30 #28, #32, #33: console, element errors, their budget), before anything
28
+ // the frame's own code runs; null where nothing records (a published canvas, a `core` run)
29
+ const signals = startDocumentSignals({ post, id, gen: GEN, boot: BOOT })
26
30
  /** An error's first three stack lines (Chrome's "at …", else "fn@url:line:col"), when it has them. */
27
31
  const stackOf = (err) => {
28
32
  if (typeof err?.stack !== 'string') return undefined
@@ -33,14 +37,15 @@ const stackOf = (err) => {
33
37
  }
34
38
 
35
39
  // theme lands as BOTH signals: [data-theme] plus the `dark` class Tailwind/shadcn key on
36
- const setTheme = (theme) => {
40
+ const setTheme = (theme, t) => {
37
41
  document.documentElement.dataset.theme = theme
38
42
  document.documentElement.classList.toggle('dark', theme === 'dark')
39
- // the shell sleeps a frame only under the theme it has actually painted: report it, two frames later
40
- requestAnimationFrame(() => requestAnimationFrame(() => post({ type: 'sh:theme-applied', id, theme })))
43
+ // the shell sleeps a frame only under the theme it has actually painted: report it, two frames later - with the
44
+ // switch's transition and this document's id (spec 30 #21)
45
+ requestAnimationFrame(() => requestAnimationFrame(() => post({ type: 'sh:theme-applied', id, theme, boot: BOOT, ...(typeof t === 'string' ? { t } : {}) })))
41
46
  }
42
47
  // the theme this document booted with (the URL's) counts as applied
43
- requestAnimationFrame(() => requestAnimationFrame(() => post({ type: 'sh:theme-applied', id, theme: new URLSearchParams(location.search).get('theme') ?? 'light' })))
48
+ requestAnimationFrame(() => requestAnimationFrame(() => post({ type: 'sh:theme-applied', id, theme: new URLSearchParams(location.search).get('theme') ?? 'light', boot: BOOT })))
44
49
 
45
50
  if (isHtmlFrame) {
46
51
  const theme = new URLSearchParams(location.search).get('theme')
@@ -66,7 +71,7 @@ const keys = createKeys({ post, trusted })
66
71
  // laser / pick / anchor / highlight - one shared controller (see inspect.js). The id is
67
72
  // static here (one iframe per frame); onModeChange re-reports the lease when a mode flips.
68
73
  // Inside a capture a laser click is the capture's pick, not a path copy.
69
- const inspect = createInspect({ post, getId: () => id, onModeChange: () => reportInteraction(), onLaserPick: (el, e) => recorder.pick(el, e) })
74
+ const inspect = createInspect({ post, getId: () => id, getBoot: () => BOOT, onModeChange: () => reportInteraction(), onLaserPick: (el, e) => recorder.pick(el, e) })
70
75
 
71
76
  document.addEventListener('mouseover', () => { if (!pointerInside) { pointerInside = true; reportInteraction() } })
72
77
  document.addEventListener('mouseout', (e) => { if (!e.relatedTarget) { pointerInside = false; reportInteraction() } })
@@ -87,14 +92,18 @@ document.addEventListener('click', (e) => {
87
92
  // consumed and forwarded it already, so this never sees it
88
93
  document.addEventListener('keydown', (e) => { if (e.key === 'Escape') post({ type: 'sh:exit-interact' }) })
89
94
 
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) }))
95
+ // A window error or an unhandled rejection always reaches the shell: `sh:error` is what marks the frame failed
96
+ // (App.tsx), and the recorder never stands in the way of that (spec 30 #5). It spends the document's budget (#33), which
97
+ // limits only the telemetry beside it - console and resource errors; the shell's 50 a load and its duplicate rule bound
98
+ // the `error` records.
99
+ window.addEventListener('error', (e) => { signals?.take('frame', true); post({ type: 'sh:error', id, gen: GEN, boot: BOOT, message: String(e.message || e.error), stack: stackOf(e.error) }) })
100
+ window.addEventListener('unhandledrejection', (e) => { signals?.take('frame', true); post({ type: 'sh:error', id, gen: GEN, boot: BOOT, message: `unhandled rejection: ${e.reason}`, stack: stackOf(e.reason) }) })
92
101
 
93
102
  window.addEventListener('message', (e) => {
94
103
  // commands come from the SHELL (parent) only - embedded app content must not flip the theme
95
104
  if (e.source !== window.parent || window.parent === window) return
96
105
  if (e.origin && e.origin !== location.origin) return // a navigated frame must not spoof commands
97
- if (e?.data?.type === 'sh:set-theme') setTheme(e.data.theme)
106
+ if (e?.data?.type === 'sh:set-theme') setTheme(e.data.theme, e.data.t)
98
107
  // B0.2: interact/play target owns its own wheel; passive frames forward it to the canvas
99
108
  if (e?.data?.type === 'sh:interactive') {
100
109
  interactiveOn = !!e.data.on