@marver-design/marver 0.29.0 → 0.30.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +2 -1
  3. package/dist/{anchor-check-DhlpKl2K.mjs → anchor-check-Bv4o-R2T.mjs} +1 -1
  4. package/dist/{build-CWbrb2bl.mjs → build-zWGXSzly.mjs} +5 -4
  5. package/dist/cli.mjs +5 -5
  6. package/dist/{daemon-Sc_z8gT6.mjs → daemon-CChgWJNq.mjs} +2 -2
  7. package/dist/{dev-DWBKQhxf.mjs → dev-DOgIITpT.mjs} +8 -8
  8. package/dist/{perf-Denssrko.mjs → perf-6MOTHxay.mjs} +710 -99
  9. package/dist/perf-BCxAo0IS.mjs +1743 -0
  10. package/dist/{plugin-DqoZB-D6.mjs → plugin-CFWBcAba.mjs} +928 -539
  11. package/dist/{poster-CrsjqhY4.mjs → poster-DPPpQiva.mjs} +1 -1
  12. package/dist/{publish-bakes-DW-NDgU2.mjs → publish-bakes-_Zx8crP3.mjs} +2 -2
  13. package/dist/{recover-GtJ9UDAB.mjs → recover-mDUVsnPd.mjs} +1 -1
  14. package/dist/{shot-T04Ixrvq.mjs → shot-d4h_hJi9.mjs} +3 -3
  15. package/docs/app.md +194 -0
  16. package/docs/performance.md +100 -19
  17. package/package.json +1 -1
  18. package/src/client/frame-host/bridge.js +17 -8
  19. package/src/client/frame-host/inplace.ts +124 -0
  20. package/src/client/frame-host/inspect.d.ts +1 -0
  21. package/src/client/frame-host/inspect.js +13 -4
  22. package/src/client/frame-host/main.tsx +12 -3
  23. package/src/client/frame-host/messages.ts +85 -0
  24. package/src/client/frame-host/signals.d.ts +15 -0
  25. package/src/client/frame-host/signals.js +219 -0
  26. package/src/client/recorder-level.ts +41 -0
  27. package/src/client/shell/App.tsx +158 -88
  28. package/src/client/shell/BoardList.tsx +103 -48
  29. package/src/client/shell/Comments.tsx +66 -42
  30. package/src/client/shell/ContextMenu.tsx +3 -2
  31. package/src/client/shell/JamSurface.tsx +116 -71
  32. package/src/client/shell/LockedApp.tsx +19 -3
  33. package/src/client/shell/Play.tsx +94 -58
  34. package/src/client/shell/StatusPicker.tsx +19 -9
  35. package/src/client/shell/Toolbar.tsx +15 -7
  36. package/src/client/shell/api.ts +18 -4
  37. package/src/client/shell/app-bridge.ts +12 -6
  38. package/src/client/shell/app-perf.ts +31 -1
  39. package/src/client/shell/canvas/Canvas.tsx +17 -6
  40. package/src/client/shell/canvas/FrameNode.tsx +25 -12
  41. package/src/client/shell/canvas/Sticky.tsx +4 -2
  42. package/src/client/shell/canvas/ctl.ts +2 -0
  43. package/src/client/shell/canvas/ready-watch.ts +4 -0
  44. package/src/client/shell/canvas/sleep.ts +2 -0
  45. package/src/client/shell/canvas/updates.ts +13 -6
  46. package/src/client/shell/commands.ts +765 -0
  47. package/src/client/shell/comments-store.ts +42 -27
  48. package/src/client/shell/goto.ts +11 -6
  49. package/src/client/shell/jam-keys.ts +141 -75
  50. package/src/client/shell/jam-lane.tsx +19 -12
  51. package/src/client/shell/jam-panel.tsx +61 -48
  52. package/src/client/shell/jam-session.tsx +41 -37
  53. package/src/client/shell/jam-state.ts +9 -1
  54. package/src/client/shell/jam-surface-parts.tsx +8 -6
  55. package/src/client/shell/jam-ui.tsx +9 -6
  56. package/src/client/shell/jam-voice.ts +4 -2
  57. package/src/client/shell/main.tsx +7 -1
  58. package/src/client/shell/marks-ui.tsx +11 -0
  59. package/src/client/shell/perf.ts +51 -5
  60. package/src/client/shell/recorder-core.ts +4 -1
  61. package/src/client/shell/recorder-hmr.ts +36 -0
  62. package/src/client/shell/recorder-reloads.ts +264 -0
  63. package/src/client/shell/recorder-seams.ts +116 -0
  64. package/src/client/shell/recorder-self.ts +73 -0
  65. package/src/client/shell/recorder-signals-core.ts +139 -0
  66. package/src/client/shell/recorder-signals.ts +485 -0
  67. package/src/client/shell/recorder.ts +118 -43
  68. package/src/client/shell/store.ts +112 -32
  69. package/src/client/shell/whiteout-probes.ts +3 -1
  70. package/src/client/stage/main.tsx +10 -5
  71. package/src/shared/app-api.ts +28 -6
  72. package/src/shared/app-perf.ts +99 -6
  73. package/src/shared/app-report.ts +586 -0
  74. package/src/shared/perf-records.ts +445 -0
  75. package/src/shared/perf-run.ts +6 -2
  76. package/dist/perf-jam-CLkERSHo.mjs +0 -642
@@ -2,20 +2,27 @@
2
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
3
  * one schema the Mac app writes into `~/.marver/perf/app.jsonl` (Marver Dev: `app-dev.jsonl`) and the CLI reads
4
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.
5
+ * Types, constants and one pure reader only - no imports but a type (perf-records.ts's `cmd`, erased) - so the app's
6
+ * main bundle, the CLI and the test harness all take it as it is.
7
7
  *
8
8
  * FROZEN before the A3 streams split (A3.8 #53). Owners: the recorder stream writes the envelope and most kinds;
9
9
  * the unloading stream writes `pressure`, `unload`, `unload-skip`, `unload-effect` and `reopen` through
10
10
  * `recorder.event`; the one-ground stream writes `cover`; the flash stream writes `flash` and
11
11
  * `whiteout-candidate`. A kind's body grows only by optional fields; a field's meaning never changes.
12
12
  *
13
+ * Spec 30 (app 1.0.1) adds, frozen before its streams split and `v` still 1: `launch` (R7 #37), `cmd` (R12, the record
14
+ * the canvas shares, perf-records.ts), `window` (#53); `by` on `shown` and `reopen`; `why` on `whiteout-candidate`
15
+ * and the minute's `whiteout` on `sample` (R8 #41); `dropped`'s `reason`; and `samples.jsonl`, where `sample` and
16
+ * `agx` lines move unchanged (R9 #44). Owners: app-store writes `launch`, the white-out fields and the files;
17
+ * commands writes `cmd`, `window` (R12 #53) and `by`. The report counts `launch`, `cmd` and `window`, never exports them (#56).
18
+ *
13
19
  * Units, said once: every `...MB` is MiB (KB / 1024 once per process, A3.8 #4); `cpu` is cores (Δ
14
20
  * `cumulativeCPUUsage` / Δ monotonic seconds, never `percentCPUUsage`); times are epoch ms (`ts`, `at`) or
15
21
  * monotonic ms (`mono`); a process is `(pid, born)`, `born` its `creationTime` - a reused pid is a new process.
16
22
  * `gpuProcessRssMB` is the GPU process's working set, never "GPU memory" (Codex r1 #19); the app never reads a
17
23
  * footprint about itself (A3.8 #2) - the budgets read footprint from outside.
18
24
  */
25
+ import type { CmdRecord } from './perf-records.ts'
19
26
 
20
27
  // ---- the line --------------------------------------------------------------------------------------------------
21
28
 
@@ -23,6 +30,11 @@
23
30
  export type Flavour = 'release' | 'dev'
24
31
  /** The file each flavour writes, under `<MARVER_HOME>/perf/`. */
25
32
  export const APP_LOG: Record<Flavour, string> = { release: 'app.jsonl', dev: 'app-dev.jsonl' }
33
+ /** Spec 30 R9 #44: where each flavour's `sample` and `agx` lines go from app 1.0.1, rows unchanged. One `seq` per
34
+ * launch runs across both files; readers merge by `app` and `seq`. */
35
+ export const APP_SAMPLES_LOG: Record<Flavour, string> = { release: 'samples.jsonl', dev: 'samples-dev.jsonl' }
36
+ /** The kinds that go to the samples file (#44). */
37
+ export const SAMPLE_KINDS = ['sample', 'agx'] as const
26
38
 
27
39
  /**
28
40
  * 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
@@ -32,6 +44,10 @@ export const APP_KINDS = [
32
44
  'start', 'sample', 'agx', 'gone', 'child-gone', 'gpu-restart', 'unresponsive', 'responsive', 'gpu', 'power',
33
45
  'tab', 'shown', 'pressure', 'unload', 'unload-skip', 'unload-effect', 'reopen', 'cover', 'flash',
34
46
  'whiteout-candidate', 'dropped', 'main-error',
47
+ // A5 (app 1.0): the updater, the restart and the move (A5.1 #25)
48
+ 'update',
49
+ // spec 30 (app 1.0.1): the launch (R7 #37), commands (R12 #48), observable window events (#53)
50
+ 'launch', 'cmd', 'window',
35
51
  ] as const
36
52
  export type AppKind = (typeof APP_KINDS)[number]
37
53
 
@@ -161,6 +177,16 @@ export interface SampleBody {
161
177
  sys: Sample['sys']
162
178
  /** wall ms of this minute's sysctl / ioreg spawns: the recorder's own cost */
163
179
  spawnMs: number
180
+ /**
181
+ * the app's own processes, folded at each sample with that sample's roles (A5.1 #27; `inOwnSet`: 'cpu' for CPU,
182
+ * 'memory-no-canvas' for memory). `rssMB`: their RSS summed at each sample, folded over the minute. `cpu`: an
183
+ * interval in which every own process has a figure adds Σ cpu × dt (core-seconds) to `s` and its length to `ms`; one
184
+ * in which any has none adds its length to `unmeasuredMs` only; a sample with no interval adds nothing. Absent on
185
+ * lines from before A5 (the report counts those minutes as missing)
186
+ */
187
+ own?: { rssMB: Agg; cpu: { s: number; ms: number; unmeasuredMs: number } }
188
+ /** spec 30 R8 #41: the white-out detector's minute; absent before app 1.0.1 */
189
+ whiteout?: WhiteoutMinute
164
190
  }
165
191
 
166
192
  /** `ioreg -rc AGXAccelerator -d1`, machine-wide (A3.1, A3.8 #9): a missing key is 'unknown'. */
@@ -192,6 +218,64 @@ export type PictureWhy = 'window hidden' | 'timeout' | 'empty' | 'write failed'
192
218
  /** A record held in the ring, as a flash quotes it: its kind, its time and its body. */
193
219
  export type RingEvent = { kind: AppKind; ts: number } & Record<string, unknown>
194
220
 
221
+ /**
222
+ * The `update` record (A5.1 #25): written whatever `recorder` says, as `flash` and `main-error` are. Each attempt
223
+ * writes `check` at its start and one end. `message` is the updater's error text, kept in app.jsonl only: the report
224
+ * never takes it (#27). A `move` record's `why` is one of UPDATE_MOVE_WHY.
225
+ */
226
+ export interface UpdateBody {
227
+ phase: 'blocked' | 'check' | 'current' | 'downloading' | 'downloaded' | 'error' | 'late' | 'slow' | 'restart'
228
+ | 'restart-failed' | 'installed' | 'install-failed' | 'move'
229
+ attempt?: number
230
+ version?: string
231
+ from?: string
232
+ to?: string
233
+ why?: string
234
+ manual?: boolean
235
+ message?: string
236
+ }
237
+ export const UPDATE_MOVE_WHY = ['offered', 'moved', 'opened-existing', 'declined', 'finder', 'cancelled', 'taken', 'failed', 'cleaned'] as const
238
+
239
+ /** Spec 30 R8 #38: a white-out window's reason - main's own (`gesture`, `shown`) and the three a 0.30 shell asks for
240
+ * with `mv:perf watch` (app-api.ts `WATCH_WHY`). */
241
+ export const WHITEOUT_WHY = ['gesture', 'shown', 'load', 'theme', 'reload'] as const
242
+ export type WhiteoutWhy = (typeof WHITEOUT_WHY)[number]
243
+ /** #39: why a window's time went uncaptured. */
244
+ export const UNCOVERED_WHY = ['stage', 'budget', 'hidden'] as const
245
+ export type UncoveredWhy = (typeof UNCOVERED_WHY)[number]
246
+ /** #41: the detector's minute, on `sample`. `captureMs` charges each capture's true length when its promise settled;
247
+ * `overrunMs` is the part past the 500 ms abandon; `skipped`: ticks refused admission (#40). */
248
+ export interface WhiteoutMinute {
249
+ windows: number
250
+ captures: number
251
+ captureMs: number
252
+ overrunMs: number
253
+ skipped: number
254
+ uncoveredMs: Record<UncoveredWhy, number>
255
+ byWhy: Partial<Record<WhiteoutWhy, number>>
256
+ }
257
+
258
+ /**
259
+ * Spec 30 R7 #37: one per launch, at the first local canvas uncovered or 30 s after ready. Times are ms from process
260
+ * start (`Date.now() - process.uptime() * 1000` at main's first line). `firstCanvas.page` joins the page's boot `load`.
261
+ */
262
+ export interface LaunchBody {
263
+ readyMs: number
264
+ /** the first `showWindow` (window.ts:871) */
265
+ windowShownMs?: number
266
+ /** the first uncovered `cover` of a local tab (window.ts:703); `page` null before its hello (a 0.27.1 shell or older) */
267
+ firstCanvas?: { tab: string; ws?: string; page: string | null; commit?: number; uncoveredMs: number; cause: AppBodies['cover']['cause'] }
268
+ tabs: { restored: number; local: number; remote: number; active: 'local' | 'remote' | 'home' | 'settings' | null }
269
+ /** ms main spent restoring the saved tabs */
270
+ restoreTabs?: number
271
+ /** no canvas uncovered: Home was up, nothing was restored, or 30 s passed */
272
+ why?: 'home' | 'none-restored' | 'timeout'
273
+ }
274
+ /** #53: what macOS lets main observe of the native roles; `cause: 'app'` when one of the app's own commands did it in
275
+ * the same turn, else `unknown` (a role item, the green button, the Dock). */
276
+ export const WINDOW_EVENTS = ['enter-full-screen', 'leave-full-screen', 'minimize', 'restore', 'maximize', 'unmaximize'] as const
277
+ export type WindowEvent = (typeof WINDOW_EVENTS)[number]
278
+
195
279
  export interface AppBodies {
196
280
  start: { version: string; electron: string; chrome: string; recorder: boolean; pid: number }
197
281
  sample: SampleBody
@@ -216,7 +300,7 @@ export interface AppBodies {
216
300
  * main's show to main's receipt of the preload's answer from its second animation-frame callback, on tab switches
217
301
  * only (A3.8 #9): the answer's IPC back to main is in it
218
302
  */
219
- shown: TabIdent & { ms: number }
303
+ shown: TabIdent & { ms: number; /** spec 30: the command that caused it (#52) */ by?: string }
220
304
  /** memory.ts: a change of level (A3.8 #45) */
221
305
  pressure: { level: PressureLevel | null; availablePct: number | null; was: PressureLevel | null }
222
306
  /** `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 */
@@ -226,7 +310,7 @@ export interface AppBodies {
226
310
  /** 5 s after an unload (A3.8 #45) */
227
311
  'unload-effect': TabIdent & { reason: UnloadReason; before: UnloadFigures; after: UnloadFigures; pidGone: boolean }
228
312
  /** written at the reopened document's accepted hello, or its next document or 30 s after its lift with no page (A3.8 #45) */
229
- reopen: TabIdent & { activateToLiftMs: number; unloadedForMs: number }
313
+ reopen: TabIdent & { activateToLiftMs: number; unloadedForMs: number; /** spec 30: the command that caused it */ by?: string }
230
314
  /** a presentation epoch's outcome (A3.8 #27; the one-ground stream's tuning record) */
231
315
  cover: TabIdent & {
232
316
  epoch: number
@@ -274,11 +358,20 @@ export interface AppBodies {
274
358
  inconclusive: number
275
359
  gpuEvents: RingEvent[]
276
360
  agx: AgxReading
361
+ /** spec 30 #41: the reasons of the window it was taken in (a window extended by a new reason has several) */
362
+ why?: WhiteoutWhy[]
277
363
  }
278
- /** the writer's queue overflowed (2,000 lines): how many went */
279
- dropped: { n: number }
364
+ /** the writer's queue overflowed (2,000 lines): how many went; spec 30: `retention-cap` (#43), `cmd` (#48) */
365
+ dropped: { n: number; reason?: 'retention-cap' | 'cmd' }
280
366
  /** app 0.1's error policy (errors.ts) */
281
367
  'main-error': { what: 'exception' | 'rejection'; name: string; message: string; stack: string[] }
368
+ update: UpdateBody
369
+ /** spec 30 R7 #37 */
370
+ launch: LaunchBody
371
+ /** spec 30 R12: the tab's identity when the command acts on one (`tab`, `page`); never a relay's (#51) */
372
+ cmd: Partial<TabIdent> & CmdRecord
373
+ /** spec 30 #53 */
374
+ window: { event: WindowEvent; cause: 'app' | 'unknown' }
282
375
  }
283
376
 
284
377
  /** A kind's body alone (what `recorder.event` and the writer take; the writer adds the envelope). */