@marver-design/marver 0.27.0 → 0.27.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/CHANGELOG.md +94 -0
  2. package/README.md +5 -2
  3. package/dist/{anchor-check-ChdDqL5z.mjs → anchor-check-gkxkPAIv.mjs} +1 -1
  4. package/dist/{board-tree-DRioF94d.mjs → board-tree-BXR8dw4b.mjs} +3 -1
  5. package/dist/{boards-CGg6piKF.mjs → boards-BHKP5yhI.mjs} +1 -1
  6. package/dist/{boards-DlTcpF47.mjs → boards-BqUqKNW8.mjs} +4 -4
  7. package/dist/{build-DZnFysGU.mjs → build-VgNg4rr8.mjs} +7 -22
  8. package/dist/cli.mjs +32 -18
  9. package/dist/{collab-Dxg2trOK.mjs → collab-BEAcXrBb.mjs} +1 -1
  10. package/dist/{comments-DxOkCSNE.mjs → comments-YEU1Zhv9.mjs} +4 -4
  11. package/dist/{context-HQ4Giw58.mjs → context-Ccjrhr1J.mjs} +3 -3
  12. package/dist/{daemon-BSA0lV8d.mjs → daemon-Dc9AH0M3.mjs} +4 -4
  13. package/dist/{dev-eQJhWsqg.mjs → dev-ri6nAlRp.mjs} +11 -11
  14. package/dist/{init-COD0x48i.mjs → init-W0nxR1OY.mjs} +3 -3
  15. package/dist/{link-DDXZVGtv.mjs → link-CdTgn94Y.mjs} +4 -4
  16. package/dist/{ls-D7O1G505.mjs → ls-BZ5TAtd5.mjs} +1 -1
  17. package/dist/{manifest-Nl3KSVOk.mjs → manifest-aFyDmL8C.mjs} +2 -2
  18. package/dist/{marks-CWM3WJjc.mjs → marks-BF9pNEgH.mjs} +2 -2
  19. package/dist/{marks-CKgzucHZ.mjs → marks-CnCCfAbD.mjs} +3 -3
  20. package/dist/{marver-id-gate-BjF6v4bT.mjs → marver-id-gate-D-R0hSt_.mjs} +1 -1
  21. package/dist/perf-DkAUFT6W.mjs +1319 -0
  22. package/dist/perf-jam-BaH3Lg0m.mjs +635 -0
  23. package/dist/{plugin-C-E7omsh.mjs → plugin-B8UghYuF.mjs} +2592 -112
  24. package/dist/{poster-Bx83ZYVK.mjs → poster-BNgafWMK.mjs} +1 -1
  25. package/dist/{profile-Bh5Y5zpW.mjs → profile-jIS6BcAs.mjs} +1 -1
  26. package/dist/{publish-bakes-aljgm45S.mjs → publish-bakes-38Nja78p.mjs} +3 -3
  27. package/dist/{recover-t9Pno3u9.mjs → recover-B8AiI29B.mjs} +2 -2
  28. package/dist/{serve-C8rVheYk.mjs → serve-Dp3nHstu.mjs} +3 -3
  29. package/dist/{share-W5H3BNvP.mjs → share-Ce4tP7ji.mjs} +1 -1
  30. package/dist/{shot-DoHLl6ig.mjs → shot-CMQgMVZm.mjs} +1 -1
  31. package/dist/{shot-LFhC-WYD.mjs → shot-Ch24tiMO.mjs} +30 -5
  32. package/dist/{slots-DCDo3N0x.mjs → slots-CFNnegCc.mjs} +8 -1
  33. package/dist/{sync-BQVlHZpx.mjs → sync-CQdGARJ9.mjs} +1 -1
  34. package/dist/{work-BroFwnup.mjs → work-Bxz-ObF3.mjs} +3 -3
  35. package/dist/{work-Bp1p39kq.mjs → work-CNhFF9pU.mjs} +1 -1
  36. package/docs/jam-session.md +2 -1
  37. package/docs/performance.md +197 -35
  38. package/package.json +1 -1
  39. package/src/client/content/video.tsx +10 -2
  40. package/src/client/shell/App.tsx +10 -3
  41. package/src/client/shell/Comments.tsx +5 -3
  42. package/src/client/shell/ContextMenu.tsx +5 -3
  43. package/src/client/shell/LockedApp.tsx +3 -0
  44. package/src/client/shell/Play.tsx +4 -2
  45. package/src/client/shell/Tip.tsx +3 -1
  46. package/src/client/shell/api.ts +47 -20
  47. package/src/client/shell/app-bridge.ts +254 -0
  48. package/src/client/shell/app-perf.ts +92 -0
  49. package/src/client/shell/canvas/Canvas.tsx +115 -22
  50. package/src/client/shell/canvas/FrameNode.tsx +10 -6
  51. package/src/client/shell/canvas/admission.ts +23 -8
  52. package/src/client/shell/canvas/ctl.ts +6 -0
  53. package/src/client/shell/canvas/sleep.ts +57 -17
  54. package/src/client/shell/canvas/updates.ts +2 -1
  55. package/src/client/shell/inset.ts +44 -0
  56. package/src/client/shell/jam-capture.ts +19 -14
  57. package/src/client/shell/jam-keys.ts +8 -3
  58. package/src/client/shell/jam-panel.tsx +6 -3
  59. package/src/client/shell/jam-voice.ts +48 -10
  60. package/src/client/shell/main.tsx +14 -1
  61. package/src/client/shell/marks-ui.tsx +5 -3
  62. package/src/client/shell/marver-app.ts +21 -0
  63. package/src/client/shell/perf-run-probe.ts +34 -0
  64. package/src/client/shell/perf-run.ts +70 -0
  65. package/src/client/shell/perf.ts +11 -0
  66. package/src/client/shell/recorder.ts +45 -3
  67. package/src/client/shell/store.ts +52 -24
  68. package/src/client/shell/styles.css +47 -15
  69. package/src/client/shell/unsaved.ts +81 -0
  70. package/src/client/shell/whiteout-probes.ts +141 -0
  71. package/src/shared/app-api.ts +205 -0
  72. package/src/shared/app-perf.ts +308 -0
  73. package/src/shared/logo-sniff.ts +86 -0
  74. package/src/shared/machine.ts +132 -0
  75. package/src/shared/perf-run.ts +177 -0
  76. package/templates/AGENTS-embedded.md +3 -0
  77. package/templates/AGENTS-studio.md +3 -0
  78. package/templates/instructions/boards.md +3 -1
  79. package/dist/bake-DM_uWgAA.mjs +0 -786
  80. package/dist/perf-BWzQwZqj.mjs +0 -369
  81. package/dist/perf-BoDSkbEb.mjs +0 -429
  82. package/dist/perf-jam-D55U3FZK.mjs +0 -242
@@ -1,4 +1,4 @@
1
- import { capture, t as findChrome } from "./shot-LFhC-WYD.mjs";
1
+ import { i as capture, p as findChrome } from "./shot-Ch24tiMO.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,4 +1,4 @@
1
- import { i as loadCollab } from "./sync-BQVlHZpx.mjs";
1
+ import { i as loadCollab } from "./sync-CQdGARJ9.mjs";
2
2
  import { readFileSync } from "node:fs";
3
3
  import { join } from "node:path";
4
4
  //#region src/server/profile.ts
@@ -1,7 +1,7 @@
1
1
  import { o as slideSize } from "./cli.mjs";
2
- import { planShot, t as findChrome } from "./shot-LFhC-WYD.mjs";
3
- import { ASK_MAX, bakeBatch } from "./bake-DM_uWgAA.mjs";
4
- import { MIME } from "./serve-C8rVheYk.mjs";
2
+ import { o as ASK_MAX, s as bakeBatch } from "./plugin-B8UghYuF.mjs";
3
+ import { p as findChrome, s as planShot } from "./shot-Ch24tiMO.mjs";
4
+ import { MIME } from "./serve-Dp3nHstu.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";
7
7
  import { createServer } from "node:http";
@@ -1,6 +1,6 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
- import { d as recoverTarget, h as workspaceId, r as legacyEntry, u as recoverEntries } from "./slots-DCDo3N0x.mjs";
3
- import { DevStartError, dev } from "./dev-eQJhWsqg.mjs";
2
+ import { d as recoverTarget, h as workspaceId, r as legacyEntry, u as recoverEntries } from "./slots-CFNnegCc.mjs";
3
+ import { DevStartError, dev } from "./dev-ri6nAlRp.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
@@ -75,7 +75,7 @@ async function serve(root, portFlag) {
75
75
  * accounts get in. Null when there is no roster to consult. */
76
76
  let guestDoorOpen = null;
77
77
  if (process.env.MARVER_DATA_DIR) {
78
- const { collabHandler } = await import("./collab-Dxg2trOK.mjs");
78
+ const { collabHandler } = await import("./collab-BEAcXrBb.mjs");
79
79
  const { appendEvents, readLog } = await import("./comments-0BSbb04K.mjs").then((n) => n.n);
80
80
  const { dataDir } = await import("./comments-0BSbb04K.mjs").then((n) => n.n);
81
81
  const dir = dataDir();
@@ -147,7 +147,7 @@ async function serve(root, portFlag) {
147
147
  console.error(`[${NAME}] MARVER_ID_ISSUER is set but MARVER_PUBLIC_ORIGIN is not.\n Every assertion is bound to this canvas's exact origin, and it cannot be\n inferred from request headers - a proxy can make any request look local.\n Set it to the origin people actually reach this canvas on:\n MARVER_PUBLIC_ORIGIN=https://canvas.example.com\n MARVER_PUBLIC_ORIGIN=http://localhost:${portFlag ?? (Number(process.env.PORT) || 4199)} (development)`);
148
148
  process.exit(1);
149
149
  }
150
- const { marverIdHandler } = await import("./marver-id-gate-BjF6v4bT.mjs");
150
+ const { marverIdHandler } = await import("./marver-id-gate-D-R0hSt_.mjs");
151
151
  const { dataDir } = await import("./comments-0BSbb04K.mjs").then((n) => n.n);
152
152
  const canvasName = humanName(meta.name);
153
153
  const { ceilingsFromRights } = await import("./auth-Dix8wrXV.mjs").then((n) => n.R);
@@ -316,7 +316,7 @@ function isCosmetic(pathname) {
316
316
  try {
317
317
  decoded = decodeURIComponent(pathname);
318
318
  } catch {}
319
- return /^\/__mv\/favicon\/[\w-]+(?:\.[\w-]+)+$/.test(decoded) || /^\/__mv\/logo\.(?:svg|png)$/.test(decoded);
319
+ return /^\/__mv\/favicon\/[\w-]+(?:\.[\w-]+)+$/.test(decoded) || /^\/__mv\/logo\.(?:svg|png|ico)$/.test(decoded);
320
320
  }
321
321
  /** The Marver logo mark (ParallelogramDuo, same as the shell's sidebar). */
322
322
  const MARK_AT = (size) => `<svg viewBox="0 0 256 256" width="${size}" height="${size}" fill="currentColor" aria-hidden><path d="M239.29,59.28l-64.8,144a8,8,0,0,1-7.3,4.72H24a8,8,0,0,1-7.3-11.28l64.8-144A8,8,0,0,1,88.81,48H232A8,8,0,0,1,239.29,59.28Z" opacity=".1"/><path d="M245.43,47.31A15.94,15.94,0,0,0,232,40H88.81a16,16,0,0,0-14.59,9.43l-64.8,144A16,16,0,0,0,24,216H167.19a16,16,0,0,0,14.59-9.43l64.8-144A16,16,0,0,0,245.43,47.31ZM167.19,200H24L88.81,56H232Z"/></svg>`;
@@ -1,6 +1,6 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
2
  import { M as resolveAccess } from "./auth-Dix8wrXV.mjs";
3
- import { i as loadCollab } from "./sync-BQVlHZpx.mjs";
3
+ import { i as loadCollab } from "./sync-CQdGARJ9.mjs";
4
4
  //#region src/cli/share.ts
5
5
  /**
6
6
  * `marver share <action>` - the roster from the terminal (01-sharing §9).
@@ -1,5 +1,5 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
- import { i as readDevInfo } from "./work-Bp1p39kq.mjs";
2
+ import { i as readDevInfo } from "./work-CNhFF9pU.mjs";
3
3
  import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
4
4
  import { join } from "node:path";
5
5
  import { randomBytes } from "node:crypto";
@@ -1,5 +1,6 @@
1
+ import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
1
2
  import { a as ROUTE, o as slideSize } from "./cli.mjs";
2
- import { t as logJam } from "./perf-jam-D55U3FZK.mjs";
3
+ import { t as logJam } from "./perf-jam-BaH3Lg0m.mjs";
3
4
  import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
4
5
  import { join } from "node:path";
5
6
  import { randomBytes } from "node:crypto";
@@ -58,6 +59,9 @@ const FLAGS = [
58
59
  ...containerFlags(process.platform, process.getuid?.()),
59
60
  ...process.env.MV_CHROME_FLAGS?.split(" ").filter(Boolean) ?? []
60
61
  ];
62
+ /** The flags every browser here launches with (a headless perf run's line says them: runs compare only with runs
63
+ * that launched alike, spec 28 A3.8 #22). */
64
+ const launchFlags = () => [...FLAGS];
61
65
  const HANDSHAKE_MS = 15e3;
62
66
  const MAX_MESSAGE = 1 << 30;
63
67
  /** The pipe's framing: NUL-terminated messages, arriving in chunks split anywhere - inside a
@@ -432,6 +436,26 @@ function unfilterRow(raw, up, out, bpp) {
432
436
  * and the browser closed in the operation's finally - never idle, never shared, never
433
437
  * outliving the server.
434
438
  */
439
+ var shot_exports = /* @__PURE__ */ __exportAll({
440
+ AREA: () => AREA,
441
+ BATCH_MAX: () => 200,
442
+ MOUNTED: () => MOUNTED,
443
+ SURFACE: () => SURFACE,
444
+ capture: () => capture,
445
+ captureIn: () => captureIn,
446
+ frameUrl: () => frameUrl,
447
+ manifestFrame: () => manifestFrame,
448
+ planShot: () => planShot,
449
+ pool: () => pool,
450
+ resolveFrames: () => resolveFrames,
451
+ shootBatch: () => shootBatch,
452
+ shootFrame: () => shootFrame,
453
+ shotConcurrency: () => shotConcurrency,
454
+ shotEvent: () => shotEvent,
455
+ shotSeams: () => shotSeams,
456
+ sweepGhosts: () => sweepGhosts,
457
+ withBrowser: () => withBrowser
458
+ });
435
459
  const slug = (frameId) => frameId.replace(/\//g, "--");
436
460
  const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
437
461
  const num = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? v : void 0;
@@ -500,8 +524,8 @@ async function shootFrame(opts) {
500
524
  };
501
525
  const plan = planShot(frame, viewports, size);
502
526
  if (frame.kind !== "html") try {
503
- const { scanAssetRefs } = await import("./build-DZnFysGU.mjs");
504
- const { ensurePoster } = await import("./poster-Bx83ZYVK.mjs");
527
+ const { scanAssetRefs } = await import("./build-VgNg4rr8.mjs");
528
+ const { ensurePoster } = await import("./poster-BNgafWMK.mjs");
505
529
  const refs = scanAssetRefs(readFileSync(join(root, frame.file), "utf8"), frame.file);
506
530
  for (const r of refs) if (r.endsWith(".poster.png")) await ensurePoster(join(root, "design", "assets"), r.slice(0, -11));
507
531
  } catch {}
@@ -792,8 +816,9 @@ function sweepTemps(dir) {
792
816
  * very shot that is waiting for it - and so do anchor checks, which have a deadline of their
793
817
  * own and must not wait out a batch of shots. */
794
818
  const chains = /* @__PURE__ */ new Map();
795
- function withBrowser(lane, fn) {
819
+ function withBrowser(lane, fn, o = {}) {
796
820
  const run = async () => {
821
+ if (o.skip?.()) return o.skipped;
797
822
  const b = await Browser.launch();
798
823
  try {
799
824
  return await fn(b);
@@ -1263,4 +1288,4 @@ async function captureOnce({ url, width, height, out, fullHeight = false, timeou
1263
1288
  }
1264
1289
  }
1265
1290
  //#endregion
1266
- export { AREA, MOUNTED, SURFACE, capture, frameUrl, manifestFrame, planShot, pool, resolveFrames, shootBatch, shootFrame, shotConcurrency, sweepGhosts, findChrome as t, withBrowser };
1291
+ export { frameUrl as a, pool as c, withBrowser as d, Browser as f, capture as i, shotConcurrency as l, launchFlags as m, MOUNTED as n, manifestFrame as o, findChrome as p, SURFACE as r, planShot as s, AREA as t, shot_exports as u };
@@ -114,6 +114,13 @@ function asRecord(v) {
114
114
  key: typeof r.key === "string" ? r.key : ""
115
115
  };
116
116
  }
117
+ /** What this version's shell offers the Mac app, written from the `starting` write on (spec 28 A2.14 #15): `bridge` -
118
+ * its shell sends A2.9's hello, theme, menu and `mv:busy` with `unsaved`, so the app's guard can trust what the page
119
+ * reports. A canvas without it (0.27.0) gets the app's degraded guard, which asks first. `inset` (0.27.2, A3.8 #31):
120
+ * its shell takes the top inset under the app's transparent strip, keeps what it means to be read or clicked below
121
+ * it and its scroll edge, and answers the app's presentation requests - so app 0.2 may run it at the window's full
122
+ * height. A canvas without it stays below the strip. */
123
+ const FEATURES = ["bridge", "inset"];
117
124
  /** Take one candidate: the file, then - holding it - the port check. */
118
125
  async function take(i, slot, port) {
119
126
  const file = slot ? slotFileOf(slot) : portFileOf(port);
@@ -131,7 +138,7 @@ async function take(i, slot, port) {
131
138
  root: i.root,
132
139
  name: i.name,
133
140
  version: i.version,
134
- features: [],
141
+ features: [...FEATURES],
135
142
  ws: i.ws,
136
143
  startedAt: Date.now(),
137
144
  key: key.toString("base64url")
@@ -2,7 +2,7 @@ import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
2
2
  import { n as diffEvents } from "./events-CLH4ijKP.mjs";
3
3
  import { a as readLog, i as listBoards, t as appendEvents } from "./comments-0BSbb04K.mjs";
4
4
  import { t as CLI_TOKEN_CHARS } from "./auth-Dix8wrXV.mjs";
5
- import { i as marverHome } from "./slots-DCDo3N0x.mjs";
5
+ import { i as marverHome } from "./slots-CFNnegCc.mjs";
6
6
  import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeSync } from "node:fs";
7
7
  import { join } from "node:path";
8
8
  import { createHash, randomBytes } from "node:crypto";
@@ -1,6 +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-Bp1p39kq.mjs";
3
- import { unreachable } from "./link-DDXZVGtv.mjs";
2
+ import { i as readDevInfo, n as WORK_TTL_MAX, t as WORK_TTL_DEFAULT } from "./work-CNhFF9pU.mjs";
3
+ import { unreachable } from "./link-CdTgn94Y.mjs";
4
4
  //#region src/cli/work.ts
5
5
  /**
6
6
  * `marver work` - the coding agent's hand on the canvas working state.
@@ -68,7 +68,7 @@ async function workCommand(root, action, frames, opts) {
68
68
  });
69
69
  console.log(active.length ? `still working: ${active.join(", ")}` : "nothing working - all clear");
70
70
  const done = before.filter((f) => !active.includes(f));
71
- const { links, hints } = done.length ? await (await import("./link-DDXZVGtv.mjs")).handBack(root, done) : {
71
+ const { links, hints } = done.length ? await (await import("./link-CdTgn94Y.mjs")).handBack(root, done) : {
72
72
  links: [],
73
73
  hints: []
74
74
  };
@@ -1,5 +1,5 @@
1
1
  import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
2
- import { s as listBoardFiles } from "./boards-CGg6piKF.mjs";
2
+ import { s as listBoardFiles } from "./boards-BHKP5yhI.mjs";
3
3
  import { r as pidRuns } from "./exclusive-B1RtpeeP.mjs";
4
4
  import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
5
5
  import { join } from "node:path";
@@ -27,7 +27,8 @@ dot. While it records, everything you do is part of it:
27
27
 
28
28
  `E` ends it. `Esc` throws it away. One capture records at a time.
29
29
 
30
- Closing or reloading the tab asks first while a capture is recording or finishing. If you leave anyway, the capture
30
+ Closing or reloading the tab asks first while a capture is recording, finishing or not yet taken by the canvas (as it
31
+ does for any unsaved work). If you leave anyway, the capture
31
32
  is kept as it stood - its words and notes so far, and a line saying the page closed before it finished - and comes
32
33
  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
34
  no chance to keep it.)
@@ -11,6 +11,7 @@ agent. A published canvas records nothing.
11
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
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
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` |
14
15
 
15
16
  `design/.local/` is gitignored, and `marver dev` never serves it. The perf folder is yours alone: mode 700,
16
17
  each file 600 from the moment it is made - and files an earlier version made are tightened when `marver dev`
@@ -35,11 +36,13 @@ read again because its file changed on disk (`disk-reload`) - the page follows i
35
36
  5. **Quiet.** The first second after it mounts with nothing moving, written as that second ends: it says
36
37
  when the move before it came (the mount itself, when nothing had moved yet). It is not when the board
37
38
  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
+ the record that ends the load, settled or cut. `perf --loads` prints only the last move (`still from`);
40
+ `quiet` is in `--json`.
39
41
  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).
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).
43
46
 
44
47
  Or **cut**: another board (`switch`), the same board loaded again (`reload`), the page hidden (`hidden`),
45
48
  or 120 s without settling (`timeout`). A request that never mounted is cut too: a newer load
@@ -50,44 +53,56 @@ cut (`late`), the cut stays, and what the board does from then is late.
50
53
 
51
54
  ## Reading `perf --loads`
52
55
 
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`:
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`:
55
58
 
56
59
  ```
57
60
  $ npx marver perf --loads
58
61
  board loads, last 60 min - design/.local/perf/page.jsonl
59
62
 
60
- 3:41:36 PM Checkout (boot) settled 2.1 s
63
+ 3:41:36 PM Checkout flow (boot) settled 1.8 s
61
64
  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
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
63
66
  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)
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)
65
68
 
66
- 3:42:03 PM Checkout (boot) settled 1.0 s
69
+ 3:42:03 PM Checkout flow (boot) settled 1.0 s
67
70
  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
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
69
72
  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)
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)
71
74
  ```
72
75
 
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.
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.
86
100
 
87
101
  A load that was cut has no ready times to give; it says how many of its frames were ready by the cut
88
102
  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
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
91
106
  errors (`late error` for one after it ended, settled or cut), how many errors past the first 50 went
92
107
  unrecorded, and its gestures (how many, the worst p95, the frames over 33 ms). The last line says how many
93
108
  records never reached the log, when any did.
@@ -102,15 +117,41 @@ Read the load, name the lever, change it, compare the next load - you, or your a
102
117
  ([Sizes](boards-and-folders.md#sizes)), and the next load opens at those heights (`savedHeights`
103
118
  counts them) and the moves go, as above. Commit it with the rest of `design/`, and every clone and the
104
119
  published canvas open at them too.
105
- - **`slowest`** names the frames that held the load longest, of those that finished. Look at those first:
120
+ - **`slowest to settle`** names the frames that held the load longest, of those that finished. Look at those first:
106
121
  what they load, how much they render - the time after `then` is the frame's own. A load cut before its frames
107
122
  finished counts the rest apart; cut at 120 s (`timeout`), the board is too heavy to finish - split it, or
108
123
  lighten what its frames load.
109
124
  - **A frame that waits long to start: the queue, not the frame.** `waited` (and `first frame started`) is the
110
125
  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
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
113
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.
114
155
  - **Never ready, missing, errors** are broken frames, not slow ones: fix them first. A missing frame's
115
156
  file was deleted or renamed.
116
157
  - **The weight** (`settled.weight`) says how heavy the settled board is: elements in the page and its
@@ -203,16 +244,17 @@ counts every change to the board; `perf --loads` counts move records, where a dr
203
244
 
204
245
  ## `--json`
205
246
 
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
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
208
249
  got there:
209
250
 
210
251
  - `cut`: `reason`, `ms`, and `request: true` when the cut came before it mounted;
211
252
  - the commit: `commitMs`, `frames`, `byKind`, `measuring`, `savedHeights` - and `mountedAfterCut: true` for a
212
253
  request cut first whose board arrived after all (`perf --loads` says `cut (hidden) at 0.4 s before it
213
254
  mounted · mounted 3.2 s`, and counts its moves as late);
214
- - `visible` (with `visibleAssumed`), `visibleReadyMs`, `allReadyMs`, `quietMs`, `lastMoveMs` (settled or cut),
215
- `settledMs`;
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`;
216
258
  - `moves`: `count`, `distance`, the top five `causes` as `[cause, count]` pairs, and `late` (count and
217
259
  causes of the moves after the load ended, settled or cut);
218
260
  - `slowest`: the five slowest frames that finished (`node`, `frame`, `ms` - when it settled, or was ready -
@@ -242,17 +284,137 @@ otherwise its last records go with `keepalive`, 16 KB at most.
242
284
  The dev server takes them only from the canvas's own page, rebuilds each from the fields its kind allows -
243
285
  strings cut to 200 characters, 512 KB a request - and appends them to `page.jsonl`.
244
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
+
245
355
  ## Options
246
356
 
247
357
  | Option | |
248
358
  |---|---|
249
359
  | `--loads` | each board load in full |
250
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 |
251
368
  | `--json` | machine-readable |
252
369
  | `--minutes <n>` | how far back to read: 60 by default (24 h with `--jam`) |
253
370
  | `--root <dir>` | the project (default: here) |
254
371
 
255
- Plain `npx marver perf` reads the reload log and ends with one line per board load.
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.
256
418
 
257
419
  ## In the page
258
420
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marver-design/marver",
3
- "version": "0.27.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,
@@ -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))
@@ -42,6 +43,11 @@ const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
42
43
  // it too, so a frame left open after its canvas stopped never asks another project for anything
43
44
  const WS = typeof location !== 'undefined' ? new URLSearchParams(location.search).get('ws') : null
44
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'
45
51
  // in-flight probes + generations, for the shot renderer's settle (like __mvLodBusy): a
46
52
  // screenshot taken while a poster is still being rendered would show the empty box
47
53
  let busy = 0
@@ -131,7 +137,7 @@ export function Video({ src, poster, ratio, autoplay = false }: { src: string; p
131
137
  // or failed (the card). The <img> mounts only once ready: no broken-image glyph while the
132
138
  // dev server renders the poster, and a shot taken meanwhile waits on __mvPosterBusy.
133
139
  const generated = !poster && !isRemote(src) ? posterNameFor(src) : null
134
- const [gen, setGen] = useState<'probing' | 'ready' | 'failed'>(generated ? 'probing' : 'ready')
140
+ const [gen, setGen] = useState<'probing' | 'ready' | 'failed' | 'skipped'>(generated ? 'probing' : 'ready')
135
141
  const [bust, setBust] = useState(0)
136
142
  const posterUrl = poster ? resolve(poster) : generated ? resolve(generated) : null
137
143
  const posterSrc = posterUrl && bust ? `${posterUrl}?v=${bust}` : posterUrl
@@ -144,9 +150,11 @@ export function Video({ src, poster, ratio, autoplay = false }: { src: string; p
144
150
  busy++
145
151
  const done = () => { if (pending) { pending = false; busy-- } }
146
152
  const probe = new Image()
147
- 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) }
148
154
  probe.onload = () => settle('ready')
149
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') }
150
158
  // not there yet: ask the dev server to render it (once per clip per document)
151
159
  void requestPoster(src).then((ok) => settle(ok ? 'ready' : 'failed', ok))
152
160
  }