@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
@@ -0,0 +1,86 @@
1
+ /**
2
+ * What a canvas's logo is, by its bytes (spec 28 A2.4, A2.9, A2.14 #24): the one sniff both sides run - the server's
3
+ * `findLogo` before it serves or publishes a file, and the Mac app on every logo it fetches - so a file's name never
4
+ * decides its type, and nothing that is not one of three image types is ever shown or served as a logo.
5
+ *
6
+ * - PNG: its 8-byte signature;
7
+ * - ICO: the header `00 00 01 00`;
8
+ * - SVG: UTF-8 text whose root element is `<svg`, after an optional byte-order mark, an optional XML declaration,
9
+ * comments, and at most one `<!DOCTYPE svg ...>` without an internal subset (Illustrator and Inkscape write one;
10
+ * a `[` - an internal subset, where entities live - fails it).
11
+ *
12
+ * Pure and dependency-free: the app's main bundle takes it as it is.
13
+ */
14
+
15
+ export type LogoType = 'png' | 'ico' | 'svg'
16
+
17
+ /** The most a logo may weigh, on either side: a file past it is never read whole, a fetch past it is aborted. */
18
+ export const LOGO_MAX = 256 * 1024
19
+
20
+ /** The type each sniffed logo is served with. */
21
+ export const LOGO_MIME: Record<LogoType, string> = { png: 'image/png', ico: 'image/x-icon', svg: 'image/svg+xml' }
22
+
23
+ const PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
24
+
25
+ /** The logo type these bytes are, or null when they are none of the three. */
26
+ export function sniffLogo(b: Uint8Array): LogoType | null {
27
+ if (b.length >= PNG.length && PNG.every((x, i) => b[i] === x)) return 'png'
28
+ if (b.length >= 4 && b[0] === 0 && b[1] === 0 && b[2] === 1 && b[3] === 0) return 'ico'
29
+ return svgRoot(b) ? 'svg' : null
30
+ }
31
+
32
+ /** Is this UTF-8 text an SVG document: its root element `<svg`, with only the prolog A2.14 #24 allows before it? */
33
+ function svgRoot(b: Uint8Array): boolean {
34
+ let s: string
35
+ try { s = new TextDecoder('utf-8', { fatal: true }).decode(b) } catch { return false }
36
+ let i = s.charCodeAt(0) === 0xfeff ? 1 : 0
37
+ const space = () => { while (i < s.length && /\s/.test(s[i])) i++ }
38
+ space()
39
+ if (s.startsWith('<?xml', i) && /[\s?]/.test(s[i + 5] ?? '')) {
40
+ const end = s.indexOf('?>', i)
41
+ if (end < 0) return false
42
+ i = end + 2
43
+ }
44
+ let doctype = false
45
+ for (;;) {
46
+ space()
47
+ if (s.startsWith('<!--', i)) {
48
+ const end = s.indexOf('-->', i + 4)
49
+ if (end < 0) return false
50
+ i = end + 3
51
+ continue
52
+ }
53
+ if (s.startsWith('<!DOCTYPE', i)) {
54
+ if (doctype) return false
55
+ doctype = true
56
+ const end = doctypeEnd(s, i + 9)
57
+ if (end < 0) return false
58
+ i = end
59
+ continue
60
+ }
61
+ break
62
+ }
63
+ return s.startsWith('<svg', i) && /[\s>/]/.test(s[i + 4] ?? '')
64
+ }
65
+
66
+ /** Just past the `>` that closes a `<!DOCTYPE svg ...>` whose body starts at `i`, or -1: another root name, an
67
+ * internal subset (`[` outside quotes) or no end. Quoted public and system ids may hold anything but their quote. */
68
+ function doctypeEnd(s: string, i: number): number {
69
+ if (!/\s/.test(s[i] ?? '')) return -1
70
+ while (i < s.length && /\s/.test(s[i])) i++
71
+ if (!s.startsWith('svg', i) || !/[\s>]/.test(s[i + 3] ?? '')) return -1
72
+ i += 3
73
+ while (i < s.length) {
74
+ const c = s[i]
75
+ if (c === '>') return i + 1
76
+ if (c === '[') return -1
77
+ if (c === '"' || c === "'") {
78
+ const close = s.indexOf(c, i + 1)
79
+ if (close < 0) return -1
80
+ i = close + 1
81
+ continue
82
+ }
83
+ i++
84
+ }
85
+ return -1
86
+ }
@@ -0,0 +1,132 @@
1
+ /**
2
+ * The machine profiles (spec 28 A3.2, A3.8 #11): what this Mac is, written once per distinct profile to
3
+ * `~/.marver/perf/machine/<hash>.json`, so old records keep pointing at the profile they were taken on. Two kinds
4
+ * share one host part and its hash: the app's (`app/src/main/machine.ts`, the recorder stream) and a headless
5
+ * run's (`src/server/machine-host.ts`, the headless stream), so runs and app records of one Mac meet by `hostHash`.
6
+ *
7
+ * FROZEN before the A3 streams split (A3.8 #53). Types, the canonical form and the host's read (`withHostSpawns`,
8
+ * `readHost`, added by the recorder stream: each side passes its own spawn) only - no imports: each writer hashes
9
+ * with its own `node:crypto` as `sha256(canonical(profile)).slice(0, 16)` (16 hex). Profiles are immutable,
10
+ * content-addressed (a temp file written with `wx`, then renamed; an existing one only touched). Thermal state and
11
+ * the speed limit are not in a profile (they go in samples); `lowPowerMode` is 'unknown' until spike S2.2.
12
+ */
13
+
14
+ export type Unknown = 'unknown'
15
+
16
+ /** The host: what a headless run can know too. */
17
+ export interface HostProfile {
18
+ /** os.cpus()[0].model, e.g. "Apple M3 Max" */
19
+ chip: string | Unknown
20
+ cores: { total: number; p: number | Unknown; e: number | Unknown }
21
+ /** e.g. "Mac15,9" */
22
+ model: string | Unknown
23
+ /** os.totalmem() in GiB, rounded */
24
+ memGB: number
25
+ /** sw_vers -productVersion, e.g. "26.6.2" */
26
+ os: string | Unknown
27
+ arch: string
28
+ }
29
+
30
+ export interface DisplayProfile {
31
+ internal: boolean
32
+ sizeDip: [number, number]
33
+ scaleFactor: number
34
+ pixels: [number, number]
35
+ hz: number
36
+ colorSpace: string
37
+ }
38
+
39
+ /** The app's profile (A3.2): the host, plus Electron's view of the GPU and the displays. */
40
+ export interface AppProfile {
41
+ v: 1
42
+ kind: 'app'
43
+ host: HostProfile
44
+ hostHash: string
45
+ electron: string
46
+ chrome: string
47
+ gpu: {
48
+ renderer: string | Unknown
49
+ backend: string | Unknown
50
+ vendorId: number | Unknown
51
+ gpuCores: number | Unknown
52
+ /** getGPUFeatureStatus(), as reported */
53
+ featureStatus: Record<string, string> | Unknown
54
+ }
55
+ /** sorted by display id */
56
+ displays: DisplayProfile[]
57
+ /** research b §1's formula, for the window's display */
58
+ tileBudgetMB: number | Unknown
59
+ power: { source: 'ac' | 'battery'; lowPowerMode: Unknown }
60
+ }
61
+
62
+ /** A headless run's host profile (machine-host.ts): its own file, sharing `hostHash` with the app's. */
63
+ export interface HeadlessProfile {
64
+ v: 1
65
+ kind: 'headless'
66
+ host: HostProfile
67
+ hostHash: string
68
+ power: 'ac' | 'battery' | Unknown
69
+ }
70
+
71
+ export type MachineProfile = AppProfile | HeadlessProfile
72
+
73
+ /** The hash's length in hex. */
74
+ export const PROFILE_HASH_HEX = 16
75
+
76
+ /** The host's one sysctl read: `sysctl -n` of these, in this order (P cores, E cores, the model). */
77
+ export const HOST_SYSCTL = ['hw.perflevel0.physicalcpu', 'hw.perflevel1.physicalcpu', 'hw.model'] as const
78
+
79
+ /** The host's two spawns, by absolute path (A3.2: every spawn `execFile` with an absolute path). */
80
+ export const HOST_SPAWNS = {
81
+ sysctl: { file: '/usr/sbin/sysctl', args: ['-n', ...HOST_SYSCTL] },
82
+ swVers: { file: '/usr/bin/sw_vers', args: ['-productVersion'] },
83
+ } as const
84
+
85
+ /**
86
+ * The host with its two spawns read (added by the recorder stream, so the app and a headless run parse them alike and
87
+ * their `hostHash` meets): `sysctl`'s stdout for HOST_SYSCTL - null when it exited non-zero - and `sw_vers
88
+ * -productVersion`'s, null when it failed. `sysctl` gives all three of P cores, E cores and the model, or none: an
89
+ * unknown oid shifts the lines (an Intel Mac has no perflevels), so anything but three lines that each parse leaves all
90
+ * three as `base` has them ('unknown'). The rules are machine-host.ts's own (`parseHostSysctl`, `parseOs`), so a host
91
+ * hashes alike whichever side parsed it.
92
+ */
93
+ export function withHostSpawns(base: HostProfile, sysctl: string | null, swVers: string | null): HostProfile {
94
+ const out: HostProfile = { ...base, cores: { ...base.cores } }
95
+ const l = typeof sysctl === 'string' ? sysctl.trim().split('\n').map((x) => x.trim()) : []
96
+ const n = (x: string | undefined) => (x !== undefined && /^\d{1,4}$/.test(x) ? Number(x) : null)
97
+ const p = n(l[0]), e = n(l[1]), model = l.length === 3 && /^[\w,. -]{1,64}$/.test(l[2]!) ? l[2]! : null
98
+ if (p !== null && e !== null && model !== null) { out.cores.p = p; out.cores.e = e; out.model = model }
99
+ const v = typeof swVers === 'string' ? swVers.trim() : ''
100
+ if (/^\d+(\.\d+){0,3}$/.test(v)) out.os = v
101
+ return out
102
+ }
103
+
104
+ /** One spawn's stdout, or null: it could not start, exited non-zero or ran past its timeout (the caller's execFile). */
105
+ export type HostSpawn = (file: string, args: readonly string[]) => Promise<string | null>
106
+
107
+ /**
108
+ * The host read the one way the app (machine.ts) and a headless run (machine-host.ts `hostProfile`) both read it:
109
+ * `base` (machine-host.ts `basicHost()`), then the two spawns through the caller's own `run`, each tried once more
110
+ * when it fails - one busy moment at a launch would otherwise give that launch a `hostHash` of its own - then
111
+ * `withHostSpawns`.
112
+ */
113
+ export async function readHost(base: HostProfile, run: HostSpawn): Promise<HostProfile> {
114
+ const twice = async (s: { file: string; args: readonly string[] }) => (await run(s.file, s.args)) ?? (await run(s.file, s.args))
115
+ const [sys, sw] = await Promise.all([twice(HOST_SPAWNS.sysctl), twice(HOST_SPAWNS.swVers)])
116
+ return withHostSpawns(base, sys, sw)
117
+ }
118
+
119
+ /**
120
+ * Canonical JSON: object keys sorted at every depth, arrays in order, no whitespace; `undefined` members dropped as
121
+ * JSON.stringify drops them. Two equal profiles give the same text whatever order their fields were built in.
122
+ */
123
+ export function canonical(v: unknown): string {
124
+ if (v === null || typeof v !== 'object') {
125
+ const s = JSON.stringify(v)
126
+ return s === undefined ? 'null' : s
127
+ }
128
+ if (Array.isArray(v)) return `[${v.map((x) => (x === undefined || typeof x === 'function' ? 'null' : canonical(x))).join(',')}]`
129
+ const o = v as Record<string, unknown>
130
+ const keys = Object.keys(o).filter((k) => o[k] !== undefined && typeof o[k] !== 'function').sort()
131
+ return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`).join(',')}}`
132
+ }
@@ -0,0 +1,177 @@
1
+ /**
2
+ * The perf-run contract between the shell and the server (spec 28 A3.4, A3.8 #17-#22): how a headless run names
3
+ * itself, what its page may send, what the page tells the driver, and the one line a run writes to
4
+ * `design/.local/perf/runs.jsonl`. `src/client/shell/perf-run.ts` and `src/server/perf-run.ts` re-export it, so the
5
+ * two halves read one list.
6
+ *
7
+ * FROZEN before the A3 streams split (A3.8 #53); the headless stream fills both halves. Read-only is enforced
8
+ * twice, before anything is sent: in the page (`mvFetch`'s barrier, a synthetic 403, counted as `refused`) and in
9
+ * the server (`perfRunBarrier()` right after the workspace guard, refused and counted per run id as `forbidden`).
10
+ * Stricter than A3.4's `/api/perf/*`: `perf/reload` and `perf/jam` would put headless documents into those logs.
11
+ */
12
+ import type { HostProfile } from './machine.ts'
13
+
14
+ /** The script's version: a run line compares only with lines of the same script (A3.4). */
15
+ export const RUN_SCRIPT = 1 as const
16
+
17
+ /** A run's own generated id: the same in the URL, the request headers and the output line (A3.4). */
18
+ export const RUN_ID = /^[0-9a-f]{16}$/
19
+ /** The header every request of a run's page carries. */
20
+ export const RUN_HEADER = 'x-mv-perfrun'
21
+ /** The query parameter: on the shell's URL (`?mvperfrun=<id>`), and added by `withWs()` to frame URLs, the play stage and Jam pictures. */
22
+ export const RUN_PARAM = 'mvperfrun'
23
+ /** `&warm=1`: the unrecorded warm-up load - the recorder runs and posts nothing. */
24
+ export const WARM_PARAM = 'warm'
25
+
26
+ /**
27
+ * The only mutating requests a run may make, under `${ROUTE}/api/` (A3.8 #17): its own page records, and the
28
+ * sleep bakes - `POST /api/bakes` only fills a derived cache, so it is allowed and never counted (A3.4). GET and
29
+ * HEAD always pass. `POST /api/poster` is refused for any run id, registered or not.
30
+ */
31
+ export const RUN_ALLOWED: readonly { method: 'POST'; path: string }[] = [
32
+ { method: 'POST', path: 'perf/page' },
33
+ { method: 'POST', path: 'bakes' },
34
+ ]
35
+
36
+ /** May a run send this? `apiPath` is the path under `${ROUTE}/api/` (no leading slash, no query), or null for any other path. */
37
+ export function allowedInRun(method: string, apiPath: string | null): boolean {
38
+ const m = method.toUpperCase()
39
+ if (m === 'GET' || m === 'HEAD') return true
40
+ if (apiPath === null) return false
41
+ return RUN_ALLOWED.some((a) => a.method === m && a.path === apiPath)
42
+ }
43
+
44
+ /**
45
+ * The page's own bake work (A3.8 #18): four counts of their own - `sleep.pending` says nothing about idleness. The
46
+ * run is bake-idle only when these four and the server's `jobsOf(run)` (queued, running) are all zero.
47
+ */
48
+ export interface BakeWork {
49
+ /** FrameNode's 250 ms timer and both retry timers, through one `scheduleSleep()` */
50
+ scheduled: number
51
+ /** a sleep from its entry to its `finally`: fonts, the ask, decode, texture install */
52
+ running: number
53
+ /** asks batched and not yet sent */
54
+ queued: number
55
+ /** the bake POST in flight */
56
+ inflight: number
57
+ }
58
+
59
+ /** `window.__mvPerfRun.status()`, polled by the driver through CDP (A3.8 #17). */
60
+ export interface PerfRunStatus {
61
+ run: string
62
+ warm: boolean
63
+ /** the load the recorder owns now */
64
+ load: { id: string; state: 'requested' | 'committed' | 'settled' | 'cut'; reason?: string; sinceNav?: number } | null
65
+ /** the page's four counts at zero (not the run's bake-idle: the server's jobs are the driver's to add) */
66
+ bakeIdle: boolean
67
+ bake: BakeWork
68
+ /** the camera in flight */
69
+ moving: boolean
70
+ /** gestures ended so far (perf.ts) */
71
+ gestures: number
72
+ /** same-origin frames whose root says data-mv-poster-skipped */
73
+ postersSkipped: number
74
+ /** requests the page refused before sending */
75
+ refused: number
76
+ }
77
+
78
+ /** `window.__mvPerfRun`, in perf mode only. */
79
+ export interface PerfRunProbe {
80
+ status(): PerfRunStatus
81
+ /** canvasCtl.fitAll(), then the camera idle (3 s at most) */
82
+ fit(): Promise<boolean>
83
+ /** the canvas element's client rect centre */
84
+ centre(): { x: number; y: number }
85
+ /** the recorder's outbox sent until empty: whether every batch landed */
86
+ flush(): Promise<boolean>
87
+ }
88
+
89
+ /** Why a run is invalid: the first that holds, in this order (A3.8 #22). */
90
+ export const INVALID_REASONS = ['cancelled', 'crash', 'inputs', 'writes', 'cut', 'frames', 'errors', 'bakes', 'gesture', 'records'] as const
91
+ export type InvalidReason = (typeof INVALID_REASONS)[number]
92
+
93
+ /** One line of `design/.local/perf/runs.jsonl` (A3.4, A3.8 #22). */
94
+ export interface RunLine {
95
+ v: 1
96
+ script: typeof RUN_SCRIPT
97
+ run: string
98
+ /** 'app' is the later real-window run (A3.4's last bullet) */
99
+ where: 'headless' | 'app'
100
+ ts: number
101
+ board: string
102
+ /** the fingerprint at the start (A3.8 #21) - once the warm-up has loaded the board: every watched file under the
103
+ * root, the board files and `_sizes.json`, and the watched files outside the root that the run's own warm-up page
104
+ * loaded, with their direct imports (the review of a3-runs' fixes: never another page's), so it depends on the board
105
+ * and the files alone. A later `where: 'app'` producer must fingerprint the same set. Null when the watcher was not
106
+ * ready - the run is invalid 'inputs' */
107
+ inputs: { hash: string; files: number } | null
108
+ /** the same files' fingerprint after the end and the 300 ms wait */
109
+ inputsEnd: string | null
110
+ frames: number | null
111
+ marver: string
112
+ chrome: string
113
+ flags: string[]
114
+ /** SystemInfo.getInfo's feature status and device */
115
+ renderer: { gpuCompositing?: string; rasterization?: string; vendor?: string; device?: string } | null
116
+ /** the headless profile's hash */
117
+ machine: string
118
+ host: HostProfile
119
+ power: 'ac' | 'battery' | 'unknown'
120
+ slow: boolean
121
+ /** the warm-up reached settled and bake-idle within 60 s */
122
+ bakes: 'warm' | 'cold'
123
+ postersMissing: number
124
+ /** heights known at start */
125
+ saved: { measuring: number; savedHeights: number } | null
126
+ /** from navigation start: `load.sinceNav + settled.ms`, on the page's monotonic clock (A3.8 #20) */
127
+ loadToSettledMs: number | null
128
+ /** from A1's load request */
129
+ settledMs: number | null
130
+ moves: number
131
+ lateMoves: number
132
+ /** the driver's own gestures (of three) whose end the shell reported - never the page's count since its load, which
133
+ * a fit's own motion raises (the review of a3-runs' fixes) */
134
+ gestures: number
135
+ p50: number | null
136
+ p95: number | null
137
+ /** null when no frame was timed (the review of a3-runs: widened from `number` - "not measured" is not "no slow
138
+ * frames"); a valid run always has it */
139
+ over33ms: number | null
140
+ /** Runtime.getHeapUsage at 1 Hz */
141
+ heapPeakMB: number | null
142
+ errors: number
143
+ /** mutating requests the server refused for this run id */
144
+ forbidden: number
145
+ refusedInPage: number
146
+ /** another run was registered at any moment of this one, or an earlier run's compile was still running when this one
147
+ * started (that run's `bakesPending`): never compared */
148
+ overlapped: boolean
149
+ valid: boolean
150
+ invalidReason?: InvalidReason
151
+ /** the cut's reason, when the load was cut - the recorder's (`timeout`, `hidden`, ...), or the driver's: `unresponsive`
152
+ * (a call to the page went unanswered for 15 s: its main thread stopped, a frame's script that never returns),
153
+ * `overrun` (the run drove past its 7 minutes) and `driver: <why>` (the driver failed for another reason than a
154
+ * crash - a page script that threw between two reads; added by the review of a3-runs' fixes) */
155
+ cut?: string
156
+ /** the dev server restarted in place during the run (an .env or config edit): its inputs changed, and its stream
157
+ * ended - invalid `inputs`, never `cancelled` (A3.8 #22; added by the review of a3-runs) */
158
+ restarted?: true
159
+ /** the run's own compiles were still running 50 s after its end (added by the review of a3-runs' fixes): the next run
160
+ * started beside them, so it is `overlapped` */
161
+ bakesPending?: true
162
+ }
163
+
164
+ /**
165
+ * `POST /api/perf/run` (work-token gated, A3.8 #22) answers NDJSON: headers at once, then these lines - a phase as
166
+ * each starts, a heartbeat every 10 s (Node's fetch cuts a body silent for 300 s), one `line` per run, then `done`.
167
+ * The body is read whole before a run registers; the response closing early cancels the run.
168
+ */
169
+ export type RunStreamLine =
170
+ | { phase: 'warm' | 'measured' | 'closing'; run: string }
171
+ | { heartbeat: number }
172
+ | { line: RunLine }
173
+ | { done: true }
174
+ | { error: string }
175
+
176
+ /** The request's body. `repeat` 1-5, 1 by default. */
177
+ export interface RunRequest { board: string; slow?: boolean; repeat?: number }
@@ -241,6 +241,9 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
241
241
  settled, how many moves and why, the slowest frames, errors. To make a board faster, name
242
242
  the lever, change it, compare the next load. A slow frame's `admittedMs` is when its turn to
243
243
  start came: a long wait is the queue, not the frame (`ms - admittedMs` is the frame's own).
244
+ To compare before and after a change, `npx marver perf run <board> --json` measures the board
245
+ the same way each time, read-only, in the canvas's own headless Chrome; `npx marver perf --runs
246
+ --json` compares the runs with the same inputs, and those after a change.
244
247
  - **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
245
248
  IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
246
249
  that never move on a rename. `title` is what humans see - free text (casing,
@@ -240,6 +240,9 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
240
240
  settled, how many moves and why, the slowest frames, errors. To make a board faster, name
241
241
  the lever, change it, compare the next load. A slow frame's `admittedMs` is when its turn to
242
242
  start came: a long wait is the queue, not the frame (`ms - admittedMs` is the frame's own).
243
+ To compare before and after a change, `npx marver perf run <board> --json` measures the board
244
+ the same way each time, read-only, in the canvas's own headless Chrome; `npx marver perf --runs
245
+ --json` compares the runs with the same inputs, and those after a change.
243
246
  - **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
244
247
  IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
245
248
  that never move on a rename. `title` is what humans see - free text (casing,
@@ -298,7 +298,9 @@ brief counts unless it says otherwise), never Blocked, never a reason.
298
298
 
299
299
  The published gate page shows the app's identity: `design/logo.svg` + the host
300
300
  package name (overridable via config `share`). If the app has no logo asset yet,
301
- create a simple `design/logo.svg`. Leave `share.branding` ON unless the human
301
+ create a simple `design/logo.svg`. The same logo wears the canvas's tab in the Mac
302
+ app. It counts only as a real file in the repo (never a symlink), at most 256 KB,
303
+ whose bytes are an SVG, a PNG or an ICO. Leave `share.branding` ON unless the human
302
304
  explicitly asks to remove it: marver is free, the gate is already personalized to
303
305
  the app, and the small "Powered by" line is how the tool spreads. Do not remove it
304
306
  as part of "branding polish".