@marver-design/marver 0.29.0 → 0.30.0

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 +44 -0
  2. package/README.md +2 -1
  3. package/dist/{anchor-check-DhlpKl2K.mjs → anchor-check-c52IDkiQ.mjs} +1 -1
  4. package/dist/{build-CWbrb2bl.mjs → build-C3mUtjEn.mjs} +5 -4
  5. package/dist/cli.mjs +5 -5
  6. package/dist/{daemon-Sc_z8gT6.mjs → daemon-B0Wi1OQ3.mjs} +5 -3
  7. package/dist/{dev-DWBKQhxf.mjs → dev-5dlxoW28.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-CXRoMA8g.mjs} +898 -539
  11. package/dist/{poster-CrsjqhY4.mjs → poster-CYmCa00B.mjs} +1 -1
  12. package/dist/{publish-bakes-DW-NDgU2.mjs → publish-bakes-C_2ZtHou.mjs} +2 -2
  13. package/dist/{recover-GtJ9UDAB.mjs → recover-XD8iXJOj.mjs} +1 -1
  14. package/dist/{shot-T04Ixrvq.mjs → shot-CRRGgxru.mjs} +3 -3
  15. package/docs/app.md +194 -0
  16. package/docs/performance.md +98 -18
  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 +115 -41
  68. package/src/client/shell/store.ts +56 -22
  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
@@ -12,7 +12,7 @@
12
12
  * Jam captures (spec 27) speak the same messages here as in a canvas frame: the keys the shell owns
13
13
  * (`sh:keys` -> `sh:key`, frame-host/keys.js) and the recorder (frame-host/trail.js, mode 'play').
14
14
  */
15
- import { Component, createElement, useEffect, useRef, useState, type ComponentType, type ReactNode } from 'react'
15
+ import { Component, createElement, Profiler, useEffect, useRef, useState, type ComponentType, type ReactNode } from 'react'
16
16
  import { flushSync } from 'react-dom'
17
17
  import { createRoot } from 'react-dom/client'
18
18
  import { frameFile, frames, layoutChain, layouts, providers } from '../frame-host/registry.ts'
@@ -20,6 +20,7 @@ import { SLIDE_DOC_CSS } from '../const.ts'
20
20
  import { createInspect } from '../frame-host/inspect.js'
21
21
  import { createKeys, keyAllowed } from '../frame-host/keys.js'
22
22
  import { createRecorder } from '../frame-host/trail.js'
23
+ import { frameRenders } from '../frame-host/signals.js'
23
24
 
24
25
  const params = new URLSearchParams(location.search)
25
26
  // Both signals, always - same pair as the frame host: [data-theme] for attribute-keyed
@@ -149,7 +150,7 @@ function Shown({ id, commit }: { id: string; commit?: number }) {
149
150
  // follows every commit (A4.6 #34), so the same frame committed again is shown again from then
150
151
  useEffect(() => {
151
152
  const t = setTimeout(() => {
152
- if (!said.current) { said.current = true; post({ type: 'sh:stage-shown', at: id, nav: params.get('r') ?? '', epoch: stamps?.epoch ?? '', doc: stamps?.doc[id] ?? 0 }) }
153
+ if (!said.current) { said.current = true; post({ type: 'sh:stage-shown', at: id, nav: params.get('r') ?? '', epoch: stamps?.epoch ?? '', doc: stamps?.doc[id] ?? 0, boot: stageRecord.boot }) }
153
154
  stageRecord.at = id; stageRecord.t = Date.now()
154
155
  }, 0)
155
156
  return () => clearTimeout(t)
@@ -261,7 +262,7 @@ function Stage() {
261
262
  recorder.current = createRecorder({ post, getFrame: () => current.current, mode: 'play', trusted })
262
263
  // the keys the shell owns right now: consumed here, ahead of the frame, and forwarded as sh:key
263
264
  const keys = createKeys({ post, trusted })
264
- const inspect = createInspect({ post, getId: () => current.current, onLaserPick: (el, e) => recorder.current?.pick(el, e) ?? false })
265
+ const inspect = createInspect({ post, getId: () => current.current, getBoot: () => stageRecord.boot, onLaserPick: (el, e) => recorder.current?.pick(el, e) ?? false })
265
266
 
266
267
  // data-goto is handled HERE, in place - never posted up as sh:go (capture phase
267
268
  // beats any frame handler; preventDefault stops real <a href> navigations). A
@@ -272,7 +273,7 @@ function Stage() {
272
273
  // on anything interactive, and data-goto (below) always wins
273
274
  if (slidesMode && e.target instanceof Element
274
275
  && !e.target.closest('a, button, input, textarea, select, video, .mv-video, [contenteditable], [data-goto]')) {
275
- post({ type: 'sh:stage-key', key: ' ', code: 'Space' })
276
+ post({ type: 'sh:stage-key', key: ' ', code: 'Space', origin: 'click' }) // spec 30 #50: a click, told apart from Space
276
277
  }
277
278
  const el = e.target instanceof Element ? e.target.closest('[data-goto]') : null
278
279
  if (!el) return
@@ -310,6 +311,8 @@ function Stage() {
310
311
  if (data?.type === 'sh:set-theme') {
311
312
  document.documentElement.dataset.theme = data.theme
312
313
  document.documentElement.classList.toggle('dark', data.theme === 'dark')
314
+ // spec 30 #21: a switch that names its transition is acknowledged two animation frames after, as a frame's is
315
+ if (typeof data.t === 'string') requestAnimationFrame(() => requestAnimationFrame(() => post({ type: 'sh:theme-applied', id: 'stage', theme: data.theme, t: data.t, boot: stageRecord.boot })))
313
316
  }
314
317
  else if (data?.type === 'sh:stage-set' && typeof data.at === 'string') goto(data.at, false)
315
318
  }
@@ -338,7 +341,9 @@ function Stage() {
338
341
  async function boot() {
339
342
  try {
340
343
  await import('virtual:sh-theme' as string)
341
- createRoot(document.getElementById('root')!).render(createElement(Stage))
344
+ // the recorder's minute of this root's commits (spec 30 #36): none where nothing records
345
+ const onRender = frameRenders(post, 'stage', () => stageRecord.boot)
346
+ createRoot(document.getElementById('root')!).render(onRender ? createElement(Profiler, { id: 'stage', onRender }, createElement(Stage)) : createElement(Stage))
342
347
  } catch (err) {
343
348
  post({ type: 'sh:stage-error', message: (err as Error).message })
344
349
  document.getElementById('root')!.innerHTML =
@@ -19,6 +19,11 @@
19
19
  * A4.6 #11, #14), which the server writes and main reads - no page ever opens it; `mv:open` / `mv:opened`, a notice's
20
20
  * click handed to the shell (`OpenItem`, `OpenResult`, A4.6 #29, #30); `mv:capture`, a live picture of the
21
21
  * document's own view (`CaptureAsk`, `CaptureAnswer`, A4.6 #35). The new methods are optional, as A3's are.
22
+ *
23
+ * Spec 30 (app 1.0.1, marver 0.30.0) adds, frozen before its streams split and `v` still 1: `mv:perf`'s `watch`, the
24
+ * three white-out windows a shell asks for (R8 #38), sent only when `perfInfo().watch` is true - app 1.0.0 would refuse
25
+ * it and spend the tab's bucket; and `mv:menu-click`'s `in`, the menu a relayed item came from (#51), absent from 1.0.0
26
+ * (the shell then records `in: 'app'`). Owners: app-store (`watch`, `perfInfo().watch`), commands (`in`).
22
27
  */
23
28
 
24
29
  export const APP_API_VERSION = 1
@@ -59,8 +64,11 @@ export type AppState = 'shown' | 'hidden' | 'untrusted'
59
64
  export interface DocAnswer { reopen: boolean; inset?: Inset }
60
65
  /** `mv:admit` (main to canvas) - the document admitted at its trusted commit (v1.12 r1 #1). */
61
66
  export interface Admit { doc: string }
62
- /** `mv:menu-click` (main to canvas). */
63
- export interface MenuClick { id: string }
67
+ /** Spec 30 #51: the menu a relayed item came from - a View or Jam item, or the tab's right-click menu. */
68
+ export const MENU_IN = ['menu', 'tab-menu'] as const
69
+ export type MenuIn = (typeof MENU_IN)[number]
70
+ /** `mv:menu-click` (main to canvas). `in` (app 1.0.1): where the person chose it; absent from app 1.0.0. */
71
+ export interface MenuClick { id: string; in?: MenuIn }
64
72
  /**
65
73
  * The ids main sends of its own, never in the page's `mv:menu`: the tab's right-click Mark All as Seen (A2.4's
66
74
  * channels table: "Mark all as seen sends `mv:menu-click mark-all-seen` to the canvas"). A shell that does not know
@@ -93,15 +101,26 @@ export interface PerfSize { w: number; h: number }
93
101
  * says which of them are still valid (moved by less than their clearance between the two answers);
94
102
  * - `mem`: `process.getProcessMemoryInfo().private` and `getHeapStatistics()`, all in KB (A3.8 #5);
95
103
  * - `shown`: the second animation-frame callback after a `shown` ask (A3.8 #9: a frame produced, not presented);
96
- * - `board`: the board's frame count and how many sleep, at each commit (Copy Details, A3.8 #9).
104
+ * - `board`: the board's frame count and how many sleep, at each commit (Copy Details, A3.8 #9);
105
+ * - `watch` (spec 30 R8 #38, app 1.0.1): a white-out window the shell opens (`on`) and closes, numbered (`seq`) like a
106
+ * gesture's - `load` from the request to settled or cut, `theme` from a switch to its outcome, `reload` from an
107
+ * on-screen job's `startReload` to its ready. Main keeps one window per tab: a new reason extends it, and a window
108
+ * ends at 10 s whatever the shell says.
97
109
  */
98
110
  export type PerfMsg =
99
111
  | { kind: 'gesture'; on: boolean; seq: number; type?: 'pan' | 'zoom' | 'layout' }
100
- | { kind: 'probes'; tick: number; at: 'before'; points: [number, number][]; cam: PerfCam | null; view: PerfSize }
112
+ | { kind: 'probes'; tick: number; at: 'before'; points: [number, number][]; cam: PerfCam | null; view: PerfSize; /** spec 30 #39: a play stage covers the canvas - no ground to probe, no capture taken */ stage?: true }
101
113
  | { kind: 'probes'; tick: number; at: 'after'; valid: boolean[]; cam: PerfCam | null; view: PerfSize }
102
114
  | { kind: 'mem'; tick: number; privateKB: number; heapUsedKB: number; heapTotalKB: number }
103
115
  | { kind: 'shown'; tick: number }
104
116
  | { kind: 'board'; frames: number; asleep: number }
117
+ | { kind: 'watch'; on: boolean; seq: number; why: WatchWhy }
118
+
119
+ /** Spec 30 R8 #38: the windows a shell asks for; main's own are `gesture` and `shown` (app-perf.ts `WHITEOUT_WHY`). */
120
+ export const WATCH_WHY = ['load', 'theme', 'reload'] as const
121
+ export type WatchWhy = (typeof WATCH_WHY)[number]
122
+ /** #40: a non-gesture window's end, whatever the shell says. */
123
+ export const WATCH_MAX_MS = 10_000
105
124
 
106
125
  /**
107
126
  * `mv:perf-ask` (main to canvas; on the wire `{ doc, ...PerfAsk }`). The preload answers `mem` and `shown` itself,
@@ -347,8 +366,11 @@ export interface MarverAppV1 {
347
366
  perf?(p: PerfMsg): void
348
367
  /** A3 (app 0.2): main's probe asks (the white-out detector, A3.8 #16) */
349
368
  onPerfAsk?(fn: (a: PerfProbeAsk) => void): () => void
350
- /** A3 (app 0.2): the display's refresh rate from main's `display` ask, null until one came; the shell puts it on its gesture records */
351
- perfInfo?(): { hz: number | null }
369
+ /**
370
+ * A3 (app 0.2): the display's refresh rate from main's `display` ask, null until one came; the shell puts it on its
371
+ * gesture records. `watch` (app 1.0.1, spec 30 #38): true when main takes `mv:perf` `watch` - a shell sends it only then
372
+ */
373
+ perfInfo?(): { hz: number | null; watch?: boolean }
352
374
  /**
353
375
  * A4 (app 0.3): main's `mv:open` for a clicked notice, delivered once to this document after its hello when its
354
376
  * instance lists `open` (A4.6 #29). The shell resolves the occurrence against a fresh read and answers (#30); the
@@ -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). */