@marver-design/marver 0.26.1 → 0.27.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/CHANGELOG.md +198 -0
  2. package/README.md +12 -4
  3. package/dist/{anchor-check-l-ny3UzH.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-DYG22tOe.mjs → boards-BqUqKNW8.mjs} +4 -4
  7. package/dist/{build-BDRiO_mP.mjs → build-VgNg4rr8.mjs} +8 -23
  8. package/dist/cli.mjs +45 -19
  9. package/dist/{collab-Dxg2trOK.mjs → collab-BEAcXrBb.mjs} +1 -1
  10. package/dist/{comments-BqXua-XL.mjs → comments-YEU1Zhv9.mjs} +4 -4
  11. package/dist/{context-HQ4Giw58.mjs → context-Ccjrhr1J.mjs} +3 -3
  12. package/dist/{daemon-DL6Fwq6D.mjs → daemon-Dc9AH0M3.mjs} +9 -7
  13. package/dist/detect-C0wpaePX.mjs +125 -0
  14. package/dist/dev-lock-C_FC70Mu.mjs +65 -0
  15. package/dist/dev-ri6nAlRp.mjs +1273 -0
  16. package/dist/exclusive-B1RtpeeP.mjs +150 -0
  17. package/dist/{init-D8DtrK_F.mjs → init-W0nxR1OY.mjs} +8 -6
  18. package/dist/{link-BNzLvdhI.mjs → link-CdTgn94Y.mjs} +23 -11
  19. package/dist/ls-BZ5TAtd5.mjs +38 -0
  20. package/dist/{manifest-Nl3KSVOk.mjs → manifest-aFyDmL8C.mjs} +2 -2
  21. package/dist/{marks-DyWMv_Z1.mjs → marks-BF9pNEgH.mjs} +3 -3
  22. package/dist/{marks-CKgzucHZ.mjs → marks-CnCCfAbD.mjs} +3 -3
  23. package/dist/{marver-id-gate-BjF6v4bT.mjs → marver-id-gate-D-R0hSt_.mjs} +1 -1
  24. package/dist/perf-DkAUFT6W.mjs +1319 -0
  25. package/dist/perf-jam-BaH3Lg0m.mjs +635 -0
  26. package/dist/plugin-B8UghYuF.mjs +5242 -0
  27. package/dist/{poster-BdtSKMDm.mjs → poster-BNgafWMK.mjs} +1 -1
  28. package/dist/{profile-WU9qcbIo.mjs → profile-jIS6BcAs.mjs} +1 -1
  29. package/dist/{publish-bakes-9RzRToXV.mjs → publish-bakes-38Nja78p.mjs} +3 -3
  30. package/dist/{queue-29ok5_eZ.mjs → queue-CAM_vNmX.mjs} +1 -1
  31. package/dist/recover-B8AiI29B.mjs +66 -0
  32. package/dist/{serve-C8rVheYk.mjs → serve-Dp3nHstu.mjs} +3 -3
  33. package/dist/{share--oFJ1bCI.mjs → share-Ce4tP7ji.mjs} +1 -1
  34. package/dist/{shot-XQV7HC9A.mjs → shot-CMQgMVZm.mjs} +1 -1
  35. package/dist/{shot-DQeR_Pfn.mjs → shot-Ch24tiMO.mjs} +36 -5
  36. package/dist/slots-CFNnegCc.mjs +478 -0
  37. package/dist/{sync-DKk-yT1V.mjs → sync-CQdGARJ9.mjs} +4 -3
  38. package/dist/{work-VvX_JIgl.mjs → work-Bxz-ObF3.mjs} +4 -2
  39. package/dist/{work-F5u-twpJ.mjs → work-CNhFF9pU.mjs} +5 -3
  40. package/docs/boards-and-folders.md +3 -1
  41. package/docs/jam-session.md +57 -2
  42. package/docs/performance.md +424 -0
  43. package/package.json +2 -2
  44. package/src/client/content/index.tsx +3 -0
  45. package/src/client/content/video.tsx +16 -4
  46. package/src/client/frame-host/bridge.js +22 -6
  47. package/src/client/frame-host/main.tsx +17 -5
  48. package/src/client/shell/App.tsx +188 -26
  49. package/src/client/shell/BoardList.tsx +5 -5
  50. package/src/client/shell/Comments.tsx +8 -5
  51. package/src/client/shell/ContextMenu.tsx +5 -3
  52. package/src/client/shell/JamSurface.tsx +4 -2
  53. package/src/client/shell/LockedApp.tsx +8 -5
  54. package/src/client/shell/Play.tsx +20 -10
  55. package/src/client/shell/Tip.tsx +3 -1
  56. package/src/client/shell/Toolbar.tsx +12 -1
  57. package/src/client/shell/api.ts +233 -0
  58. package/src/client/shell/app-bridge.ts +254 -0
  59. package/src/client/shell/app-perf.ts +92 -0
  60. package/src/client/shell/canvas/Canvas.tsx +141 -21
  61. package/src/client/shell/canvas/FrameNode.tsx +22 -9
  62. package/src/client/shell/canvas/admission.ts +31 -9
  63. package/src/client/shell/canvas/camera-broadcast.ts +15 -5
  64. package/src/client/shell/canvas/ctl.ts +8 -0
  65. package/src/client/shell/canvas/frame-registry.ts +28 -2
  66. package/src/client/shell/canvas/sleep.ts +60 -17
  67. package/src/client/shell/canvas/updates.ts +2 -1
  68. package/src/client/shell/comments-store.ts +12 -4
  69. package/src/client/shell/goto.ts +22 -10
  70. package/src/client/shell/inset.ts +44 -0
  71. package/src/client/shell/jam-capture.ts +41 -22
  72. package/src/client/shell/jam-keys.ts +12 -3
  73. package/src/client/shell/jam-panel.tsx +9 -3
  74. package/src/client/shell/jam-queue.ts +3 -3
  75. package/src/client/shell/jam-session.tsx +14 -8
  76. package/src/client/shell/jam-voice.ts +55 -15
  77. package/src/client/shell/legacy-links.ts +2 -2
  78. package/src/client/shell/main.tsx +18 -1
  79. package/src/client/shell/marks-ui.tsx +5 -3
  80. package/src/client/shell/marver-app.ts +21 -0
  81. package/src/client/shell/notes.ts +8 -1
  82. package/src/client/shell/perf-run-probe.ts +34 -0
  83. package/src/client/shell/perf-run.ts +70 -0
  84. package/src/client/shell/perf.ts +80 -58
  85. package/src/client/shell/recorder-core.ts +183 -0
  86. package/src/client/shell/recorder.ts +607 -0
  87. package/src/client/shell/store.ts +294 -110
  88. package/src/client/shell/styles.css +72 -15
  89. package/src/client/shell/unsaved.ts +81 -0
  90. package/src/client/shell/whiteout-probes.ts +141 -0
  91. package/src/shared/app-api.ts +205 -0
  92. package/src/shared/app-perf.ts +308 -0
  93. package/src/shared/logo-sniff.ts +86 -0
  94. package/src/shared/machine.ts +132 -0
  95. package/src/shared/perf-run.ts +177 -0
  96. package/templates/AGENTS-embedded.md +25 -4
  97. package/templates/AGENTS-studio.md +25 -4
  98. package/templates/demo/dark.tsx +1 -1
  99. package/templates/demo/welcome.tsx +1 -1
  100. package/templates/instructions/boards.md +3 -1
  101. package/templates/instructions/welcome.md +6 -3
  102. package/dist/bake-C-awKgLA.mjs +0 -786
  103. package/dist/config-Cf7EjAMf.mjs +0 -292
  104. package/dist/dev-Bw_qYWWq.mjs +0 -755
  105. package/dist/dev-lock-DWSpa6nj.mjs +0 -179
  106. package/dist/perf-C75MZ73h.mjs +0 -167
  107. package/dist/perf-DPbLGhhO.mjs +0 -49
  108. package/dist/perf-jam-BU3TVrZu.mjs +0 -239
  109. package/dist/plugin-DkGmZs_r.mjs +0 -2423
@@ -0,0 +1,308 @@
1
+ /**
2
+ * The app half of the recorder, on disk and in memory (spec 28 A3.1, A3.8 #4-#9, #13, #16, #45, #48, #49): the
3
+ * one schema the Mac app writes into `~/.marver/perf/app.jsonl` (Marver Dev: `app-dev.jsonl`) and the CLI reads
4
+ * (`marver perf --crashes`, `--flashes`, `--machine`), and the sampler's shapes `memory.ts` and the budgets read.
5
+ * Types, constants and one pure reader only - no imports - so the app's main bundle, the CLI and the test harness
6
+ * all take it as it is.
7
+ *
8
+ * FROZEN before the A3 streams split (A3.8 #53). Owners: the recorder stream writes the envelope and most kinds;
9
+ * the unloading stream writes `pressure`, `unload`, `unload-skip`, `unload-effect` and `reopen` through
10
+ * `recorder.event`; the one-ground stream writes `cover`; the flash stream writes `flash` and
11
+ * `whiteout-candidate`. A kind's body grows only by optional fields; a field's meaning never changes.
12
+ *
13
+ * Units, said once: every `...MB` is MiB (KB / 1024 once per process, A3.8 #4); `cpu` is cores (Δ
14
+ * `cumulativeCPUUsage` / Δ monotonic seconds, never `percentCPUUsage`); times are epoch ms (`ts`, `at`) or
15
+ * monotonic ms (`mono`); a process is `(pid, born)`, `born` its `creationTime` - a reused pid is a new process.
16
+ * `gpuProcessRssMB` is the GPU process's working set, never "GPU memory" (Codex r1 #19); the app never reads a
17
+ * footprint about itself (A3.8 #2) - the budgets read footprint from outside.
18
+ */
19
+
20
+ // ---- the line --------------------------------------------------------------------------------------------------
21
+
22
+ /** Which build wrote a line: the release (`app.jsonl`) or Marver Dev (`app-dev.jsonl`). One writer per file (A3.8 #12). */
23
+ export type Flavour = 'release' | 'dev'
24
+ /** The file each flavour writes, under `<MARVER_HOME>/perf/`. */
25
+ export const APP_LOG: Record<Flavour, string> = { release: 'app.jsonl', dev: 'app-dev.jsonl' }
26
+
27
+ /**
28
+ * The record kinds (A3.8 #8). `main-error` is app 0.1's (errors.ts), kept so a 0.1 line still parses once the
29
+ * recorder stamps it with the envelope.
30
+ */
31
+ export const APP_KINDS = [
32
+ 'start', 'sample', 'agx', 'gone', 'child-gone', 'gpu-restart', 'unresponsive', 'responsive', 'gpu', 'power',
33
+ 'tab', 'shown', 'pressure', 'unload', 'unload-skip', 'unload-effect', 'reopen', 'cover', 'flash',
34
+ 'whiteout-candidate', 'dropped', 'main-error',
35
+ ] as const
36
+ export type AppKind = (typeof APP_KINDS)[number]
37
+
38
+ /** Every line (A3.8 #8). `app`: a random id per launch (12 hex); `seq`: counted per launch from 0, contiguous; `machine`: the profile hash in force, null only when none could be made in 3 s. */
39
+ export interface AppEnvelope {
40
+ v: 1
41
+ ts: number
42
+ kind: AppKind
43
+ app: string
44
+ seq: number
45
+ flavour: Flavour
46
+ machine: string | null
47
+ }
48
+
49
+ /**
50
+ * A record about a tab carries its identity, captured in the event's turn before any await (A3.8 #8). `page` is the
51
+ * one the admitted document's accepted `mv:hello` sent; a document that has not said hello has none, and never gets
52
+ * the next document's. `commit` is the tab's commit count (tabs.ts `doc.commits`).
53
+ */
54
+ export interface TabIdent { tab: string; ws?: string; commit?: number; page?: string }
55
+
56
+ /** A process, as the budgets and `--crashes` name it. */
57
+ export interface ProcId { pid: number; born: number }
58
+
59
+ // ---- the sampler (A3.8 #4-#6): what memory.ts, a flash and the budgets read -----------------------------------
60
+
61
+ export type ProcType = 'browser' | 'gpu' | 'utility' | 'renderer' | 'other'
62
+ /** A renderer's role: the page kind it hosts ('mixed': two app-page kinds; 'cover': S15's variant 3); every other process 'none'. */
63
+ export type Role = 'canvas' | 'strip' | 'home' | 'settings' | 'tabpage' | 'cover' | 'mixed' | 'none' | 'unknown'
64
+ /** Electron's `powerMonitor.getCurrentThermalState()`. */
65
+ export type ThermalState = 'unknown' | 'nominal' | 'fair' | 'serious' | 'critical'
66
+
67
+ /** `kern.memorystatus_vm_pressure_level`: 1 normal, 2 warn, 4 critical. */
68
+ export type PressureLevel = 1 | 2 | 4
69
+ /** One pressure read (A3.8 #6): `level` null is unknown (a failed, timed-out or other answer) - never normal, never acted on. */
70
+ export interface PressureReading {
71
+ level: PressureLevel | null
72
+ /** `kern.memorystatus_level`, 0-100: recorded, not acted on */
73
+ availablePct: number | null
74
+ /** epoch ms of the read */
75
+ at: number
76
+ }
77
+
78
+ export interface ProcSample {
79
+ pid: number
80
+ /** creationTime; with pid, the key */
81
+ born: number
82
+ type: ProcType
83
+ /** Electron's `name` (utility processes) */
84
+ name?: string
85
+ role: Role
86
+ /** the tabs with any frame in it (a canvas renderer shared by two tabs lists both; its out-of-process iframes count for their tab) */
87
+ tabs: string[]
88
+ /** cores; null on a process's first sample and the first after a resume */
89
+ cpu: number | null
90
+ rssMB: number
91
+ /** canvas renderers: the preload's footprint (`private`), at most 10 s old (A3.8 #5); else null - RSS stands in */
92
+ footprintMB: number | null
93
+ }
94
+
95
+ export interface Sample {
96
+ /** epoch ms */
97
+ ts: number
98
+ /** monotonic ms (performance.now()) */
99
+ mono: number
100
+ /** monotonic s since the previous sample; null for the first and after a resume */
101
+ dt: number | null
102
+ /** every unique process; a process is counted once in any sum */
103
+ procs: ProcSample[]
104
+ gpu: { pid: number; born: number; cpu: number | null; gpuProcessRssMB: number } | null
105
+ /** read only while recording or while a hidden tab could be unloaded (A3.8 #6); null when not read */
106
+ pressure: PressureReading | null
107
+ thermal: ThermalState
108
+ /** process.getSystemMemoryInfo(), KB to MB */
109
+ sys: { freeMB: number; purgeableMB: number } | null
110
+ /** the visible tab's last `mem` answer, at most 10 s old */
111
+ visible: (TabIdent & { privateMB: number; heapMB: number; at: number }) | null
112
+ }
113
+
114
+ /**
115
+ * The one sampler, two consumers (A3.8 #4): `recorder.ts` owns the only `getAppMetrics()` loop, every 5 s, while
116
+ * recording or while `wantPressure()` says an unload is possible; with the recorder off it runs only for
117
+ * `memory.ts` and writes nothing.
118
+ */
119
+ export interface Sampler {
120
+ /** every sample, as it is published (after its pressure read ended) */
121
+ onSample(fn: (s: Sample) => void): () => void
122
+ /** memory.ts: asked at every tick - true while some hidden tab could be unloaded (A3.8 #6); it also keeps the tick alive with the recorder off */
123
+ wantPressure(fn: () => boolean): void
124
+ /** one extra sample now, on the same baselines (an unload's "after", A3.8 #45) */
125
+ requestSample(): Promise<Sample>
126
+ /** the last sample published, or null */
127
+ last(): Sample | null
128
+ }
129
+
130
+ /** The GPU process's identity: `getAppMetrics()`'s `GPU` entry (A3.8 #27, r3 #1). A change, or none, is a loss. */
131
+ export type GpuIdentity = ProcId
132
+
133
+ // ---- bodies -----------------------------------------------------------------------------------------------------
134
+
135
+ /** mean, max and last over a window; null when nothing was read */
136
+ export interface Agg { mean: number | null; max: number | null; last: number | null }
137
+
138
+ /** One minute of 5 s samples (A3.8 #7): CPU exact over the minute (Δ cumulative / Δ monotonic), memory as mean, max and last. */
139
+ export interface SampleBody {
140
+ /** ms covered, and the samples folded in */
141
+ span: number
142
+ n: number
143
+ pressure: { last: PressureLevel | null; max: PressureLevel | null }
144
+ thermal: ThermalState
145
+ /** every unique process seen in the minute (the CPU budget joins by pid and a start time within 1 s of `born`, A3.8 #49) */
146
+ procs: {
147
+ pid: number; born: number; type: ProcType; role: Role; name?: string; tabs: string[]; cpu: Agg; rssMB: Agg; footprintMB: Agg
148
+ /** the core-seconds the process used in the minute (Δ cumulative) and the monotonic ms they cover: `cpu.mean` is s / (ms / 1000); absent with no CPU interval (added by the recorder stream, optional) */
149
+ cpuTime?: { s: number; ms: number }
150
+ }[]
151
+ gpu: { pid: number; born: number; cpu: Agg; gpuProcessRssMB: Agg } | null
152
+ /**
153
+ * canvas memory (A3.8 #41): Σ over unique canvas processes of footprintMB, else rssMB. `byTab` is each tab's own
154
+ * processes; `shared` (added by the recorder stream, optional) marks a tab whose renderer another tab shared in the
155
+ * minute - that renderer is whole in both tabs' entries, so byTab is never added up (`memMB` counts it once)
156
+ */
157
+ canvases: { memMB: Agg; byTab: Record<string, { memMB: Agg; cpu: Agg; shared?: true }> }
158
+ visible: Sample['visible']
159
+ sys: Sample['sys']
160
+ /** wall ms of this minute's sysctl / ioreg spawns: the recorder's own cost */
161
+ spawnMs: number
162
+ }
163
+
164
+ /** `ioreg -rc AGXAccelerator -d1`, machine-wide (A3.1, A3.8 #9): a missing key is 'unknown'. */
165
+ export interface AgxReading {
166
+ gpuSystemMemoryMB: number | 'unknown'
167
+ allocMB: number | 'unknown'
168
+ utilPct: number | 'unknown'
169
+ rendererPct: number | 'unknown'
170
+ tilerPct: number | 'unknown'
171
+ recoveryCount: number | 'unknown'
172
+ machineWide: true
173
+ }
174
+
175
+ export type UnloadReason = 'warn' | 'critical' | 'half-ram'
176
+ /** An unload's before and after figures (A3.8 #45). */
177
+ export interface UnloadFigures {
178
+ level: PressureLevel | null
179
+ availablePct: number | null
180
+ /** Σ canvas memory (A3.8 #41) */
181
+ canvasMB: number | null
182
+ /** the tab's own processes, unique */
183
+ tab: { pids: number[]; memMB: number | null }
184
+ gpuProcessRssMB: number | null
185
+ }
186
+
187
+ /** Why a flash's picture is missing (A3.8 #13). */
188
+ export type PictureWhy = 'window hidden' | 'timeout' | 'empty' | 'write failed' | 'quit' | 'no window'
189
+
190
+ /** A record held in the ring, as a flash quotes it: its kind, its time and its body. */
191
+ export type RingEvent = { kind: AppKind; ts: number } & Record<string, unknown>
192
+
193
+ export interface AppBodies {
194
+ start: { version: string; electron: string; chrome: string; recorder: boolean; pid: number }
195
+ sample: SampleBody
196
+ agx: AgxReading
197
+ /** a renderer ended (A3.8 #9): `ours` when main was ending it (an unload, Reload Page); an unload writes its own at `destroyed`, `source: 'unload'` */
198
+ gone: Partial<TabIdent> & { role: Role; pid: number; born: number; reason: string; exitCode: number; ours: boolean; source?: 'unload' | 'reload-page'; pressure: PressureLevel | null }
199
+ /** the GPU or a utility process ended; never ours */
200
+ 'child-gone': { type: string; name?: string; reason: string; exitCode: number; ours: false; machineWide: false }
201
+ /** a new GPU process with no child-gone within 2 s (A3.8 #9) */
202
+ 'gpu-restart': { pid: number; born: number; was: ProcId | null }
203
+ unresponsive: Partial<TabIdent> & { role: Role; pid: number; born: number }
204
+ responsive: Partial<TabIdent> & { role: Role; pid: number; born: number }
205
+ /** gpu-info-update whose getGPUFeatureStatus() changed */
206
+ gpu: { featureStatus: Record<string, string> }
207
+ power: { event: 'on-ac' | 'on-battery' | 'suspend' | 'resume' | 'thermal-state-change' | 'speed-limit-change'; thermal?: ThermalState; limit?: number }
208
+ /**
209
+ * a change of the tab's display state, active flag, view state, document commit count or main frame (A3.8 #9,
210
+ * r4 #1), diffed after each compose. `state` is tabs.ts's DisplayState, `view` its TabViewState.
211
+ */
212
+ tab: TabIdent & { state: string; active: boolean; view: string; main: ProcId | null }
213
+ /**
214
+ * main's show to main's receipt of the preload's answer from its second animation-frame callback, on tab switches
215
+ * only (A3.8 #9): the answer's IPC back to main is in it
216
+ */
217
+ shown: TabIdent & { ms: number }
218
+ /** memory.ts: a change of level (A3.8 #45) */
219
+ pressure: { level: PressureLevel | null; availablePct: number | null; was: PressureLevel | null }
220
+ /** `forced`: Force Quit Tab on a quit's stuck sheet (app 0.2 code review r2 #1) - the view taken out by hand, never a completed unload */
221
+ unload: TabIdent & { phase: 'start' | 'unsure' | 'done' | 'forced' | 'refused'; reason: UnloadReason; why?: string; before?: UnloadFigures }
222
+ /** once per tab and reason in each pressure episode (A3.8 #45); `why` an UnloadRefusal */
223
+ 'unload-skip': TabIdent & { reason: UnloadReason; why: string }
224
+ /** 5 s after an unload (A3.8 #45) */
225
+ 'unload-effect': TabIdent & { reason: UnloadReason; before: UnloadFigures; after: UnloadFigures; pidGone: boolean }
226
+ /** written at the reopened document's accepted hello, or its next document or 30 s after its lift with no page (A3.8 #45) */
227
+ reopen: TabIdent & { activateToLiftMs: number; unloadedForMs: number }
228
+ /** a presentation epoch's outcome (A3.8 #27; the one-ground stream's tuning record) */
229
+ cover: TabIdent & {
230
+ epoch: number
231
+ cause: 'doc' | 'size' | 'show' | 'fullscreen' | 'hello' | 'resize' | 'gpu'
232
+ outcome: 'uncovered' | 'mismatch' | 'superseded' | 'never'
233
+ /** ms from the epoch's start: sent, answered, uncovered */
234
+ sentMs?: number
235
+ answeredMs?: number
236
+ uncoveredMs?: number
237
+ /**
238
+ * ms from the epoch's start to when it ended because its view stopped showing - another tab or an app page, a tab
239
+ * page over it, its document no longer presentable, the window hidden, the app quitting; absent when a newer key
240
+ * superseded it while shown. A hidden view draws no frames: its silence after this is not the page's
241
+ */
242
+ hiddenMs?: number
243
+ frames: number
244
+ uncoverDelayMs: number
245
+ }
246
+ /** Mark a Flash (A3.3, A3.8 #13, #14): written once the picture settled, the AGX read ended and the +1 s GPU window closed */
247
+ flash: Partial<TabIdent> & {
248
+ id: string
249
+ via: 'key' | 'menu'
250
+ recorder: boolean
251
+ /** the ring, only with the recorder on: the last 12 samples and 60 s of events */
252
+ ring: { samples: Sample[]; events: RingEvent[] } | null
253
+ /** the state at the mark: one getAppMetrics(), in the mark's turn - its `ts` is the mark's time, which the CLI dates the mark by (the line's own `ts` is when it was written, about mark + 2 s) */
254
+ now: Sample
255
+ /** GPU process events from 1 s before the mark to 1 s after it */
256
+ gpuEvents: RingEvent[]
257
+ thermal: ThermalState
258
+ pressure: PressureReading | null
259
+ featureStatus: Record<string, string>
260
+ agx: AgxReading
261
+ /** `flashes/<id>.png` under perf/, or null with `pictureWhy` */
262
+ picture: string | null
263
+ pictureWhy?: PictureWhy
264
+ }
265
+ /** two completed white samples at consecutive ticks (A3.8 #16): white at `observedAt` only, nothing between them */
266
+ 'whiteout-candidate': TabIdent & {
267
+ gesture: number
268
+ observedAt: number[]
269
+ rateHz: 4 | 2
270
+ samples: number
271
+ skipped: number
272
+ inconclusive: number
273
+ gpuEvents: RingEvent[]
274
+ agx: AgxReading
275
+ }
276
+ /** the writer's queue overflowed (2,000 lines): how many went */
277
+ dropped: { n: number }
278
+ /** app 0.1's error policy (errors.ts) */
279
+ 'main-error': { what: 'exception' | 'rejection'; name: string; message: string; stack: string[] }
280
+ }
281
+
282
+ /** A kind's body alone (what `recorder.event` and the writer take; the writer adds the envelope). */
283
+ export type AppBody<K extends AppKind> = AppBodies[K]
284
+ /** One line of app.jsonl. */
285
+ export type AppRecord = { [K in AppKind]: AppEnvelope & { kind: K } & AppBodies[K] }[AppKind]
286
+
287
+ // ---- the reader -------------------------------------------------------------------------------------------------
288
+
289
+ const KINDS = new Set<string>(APP_KINDS)
290
+ const isInt = (v: unknown): v is number => typeof v === 'number' && Number.isInteger(v) && v >= 0
291
+
292
+ /**
293
+ * One line of app.jsonl, or null (A3.5): the envelope checked - `v: 1`, a finite `ts`, a known `kind`, an `app` id,
294
+ * a whole `seq`, a `flavour`, a `machine` hash or null. The body is the writer's and is passed on as it is: a
295
+ * reader takes the fields it knows. A line without the envelope (app 0.1's main-error lines) is null.
296
+ */
297
+ export function parseAppLine(line: string): AppRecord | null {
298
+ let r: unknown
299
+ try { r = JSON.parse(line) } catch { return null }
300
+ if (!r || typeof r !== 'object' || Array.isArray(r)) return null
301
+ const o = r as Record<string, unknown>
302
+ if (o.v !== 1 || typeof o.ts !== 'number' || !Number.isFinite(o.ts)) return null
303
+ if (typeof o.kind !== 'string' || !KINDS.has(o.kind)) return null
304
+ if (typeof o.app !== 'string' || !/^[0-9a-f]{12}$/.test(o.app) || !isInt(o.seq)) return null
305
+ if (o.flavour !== 'release' && o.flavour !== 'dev') return null
306
+ if (o.machine !== null && (typeof o.machine !== 'string' || !/^[0-9a-f]{16}$/.test(o.machine))) return null
307
+ return o as unknown as AppRecord
308
+ }
@@ -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
+ }