@marver-design/marver 0.28.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 (105) hide show
  1. package/CHANGELOG.md +103 -0
  2. package/README.md +4 -3
  3. package/dist/{anchor-check-PHUOFj1N.mjs → anchor-check-c52IDkiQ.mjs} +1 -1
  4. package/dist/{build-BsAyLMT1.mjs → build-C3mUtjEn.mjs} +7 -4
  5. package/dist/{capture-DdZ6xgoz.mjs → capture-DEtM4qm5.mjs} +168 -5
  6. package/dist/cli.mjs +11 -11
  7. package/dist/{comments-CrBHPEQl.mjs → comments-XNhMmSSu.mjs} +2 -2
  8. package/dist/{connectors-MR9d-EBP.mjs → connectors-DekQvKt9.mjs} +3 -1
  9. package/dist/{daemon-C5dg2R-V.mjs → daemon-B0Wi1OQ3.mjs} +30 -29
  10. package/dist/{dev-D7YS7iT2.mjs → dev-5dlxoW28.mjs} +19 -14
  11. package/dist/{init-WE5lQkQL.mjs → init-CYlFaRzG.mjs} +1 -1
  12. package/dist/logo-CXY-1yrn.mjs +305 -0
  13. package/dist/{ls-BZ5TAtd5.mjs → ls-NqmePKOf.mjs} +1 -1
  14. package/dist/{marks-Kmdab_5w.mjs → marks-BnNANic9.mjs} +20 -1
  15. package/dist/{marks-Dyn6tmjp.mjs → marks-DBp3h1Mc.mjs} +2 -5
  16. package/dist/{marver-id-gate-D-R0hSt_.mjs → marver-id-gate-vBLb_Icb.mjs} +1 -1
  17. package/dist/{perf-Cn5LiRaY.mjs → perf-6MOTHxay.mjs} +751 -122
  18. package/dist/perf-BCxAo0IS.mjs +1743 -0
  19. package/dist/{plugin-C_0yb-Fq.mjs → plugin-CXRoMA8g.mjs} +1382 -810
  20. package/dist/{poster-DHi6I1fO.mjs → poster-CYmCa00B.mjs} +1 -1
  21. package/dist/{profile-jIS6BcAs.mjs → profile-B1FKOM1e.mjs} +1 -1
  22. package/dist/{publish-bakes-r4PEZuPl.mjs → publish-bakes-C_2ZtHou.mjs} +3 -3
  23. package/dist/{queue-c-6aTHEz.mjs → queue-DeSQm24g.mjs} +29 -14
  24. package/dist/{recover-nrLEVLyJ.mjs → recover-XD8iXJOj.mjs} +2 -2
  25. package/dist/{serve-Dp3nHstu.mjs → serve-DQv3Ti6X.mjs} +8 -4
  26. package/dist/{session-DyVE7cCk.mjs → session-VDJfXEEm.mjs} +1 -1
  27. package/dist/{share-Ce4tP7ji.mjs → share-Bu_kuOKL.mjs} +1 -1
  28. package/dist/{shot-BrRtqaiS.mjs → shot-CRRGgxru.mjs} +3 -3
  29. package/dist/{slots-CFNnegCc.mjs → slots-Dn4Onb0V.mjs} +101 -3
  30. package/dist/{sync-CQdGARJ9.mjs → sync-CMozOwZ0.mjs} +1 -1
  31. package/docs/app.md +194 -0
  32. package/docs/boards-and-folders.md +11 -0
  33. package/docs/jam-session.md +12 -3
  34. package/docs/live-jam.md +3 -0
  35. package/docs/performance.md +99 -19
  36. package/docs/publish.md +7 -0
  37. package/package.json +1 -1
  38. package/src/client/frame-host/bridge.js +17 -8
  39. package/src/client/frame-host/inplace.ts +124 -0
  40. package/src/client/frame-host/inspect.d.ts +1 -0
  41. package/src/client/frame-host/inspect.js +13 -4
  42. package/src/client/frame-host/main.tsx +12 -3
  43. package/src/client/frame-host/messages.ts +85 -0
  44. package/src/client/frame-host/signals.d.ts +15 -0
  45. package/src/client/frame-host/signals.js +219 -0
  46. package/src/client/recorder-level.ts +41 -0
  47. package/src/client/shell/App.tsx +158 -88
  48. package/src/client/shell/BoardList.tsx +103 -48
  49. package/src/client/shell/Comments.tsx +71 -46
  50. package/src/client/shell/ContextMenu.tsx +8 -6
  51. package/src/client/shell/JamSurface.tsx +187 -71
  52. package/src/client/shell/LockedApp.tsx +19 -3
  53. package/src/client/shell/Play.tsx +110 -62
  54. package/src/client/shell/StatusPicker.tsx +19 -9
  55. package/src/client/shell/Toolbar.tsx +15 -7
  56. package/src/client/shell/api.ts +25 -7
  57. package/src/client/shell/app-bridge.ts +23 -9
  58. package/src/client/shell/app-perf.ts +31 -1
  59. package/src/client/shell/canvas/Canvas.tsx +17 -6
  60. package/src/client/shell/canvas/FrameNode.tsx +25 -12
  61. package/src/client/shell/canvas/Sticky.tsx +4 -2
  62. package/src/client/shell/canvas/ctl.ts +2 -0
  63. package/src/client/shell/canvas/ready-watch.ts +4 -0
  64. package/src/client/shell/canvas/sleep.ts +2 -0
  65. package/src/client/shell/canvas/updates.ts +13 -6
  66. package/src/client/shell/commands.ts +765 -0
  67. package/src/client/shell/comments-store.ts +56 -27
  68. package/src/client/shell/goto.ts +15 -9
  69. package/src/client/shell/jam-capture.ts +39 -15
  70. package/src/client/shell/jam-keys.ts +303 -111
  71. package/src/client/shell/jam-lane.tsx +19 -12
  72. package/src/client/shell/jam-lines.ts +10 -1
  73. package/src/client/shell/jam-panel.tsx +68 -53
  74. package/src/client/shell/jam-queue.ts +6 -1
  75. package/src/client/shell/jam-session.tsx +41 -37
  76. package/src/client/shell/jam-state.ts +28 -5
  77. package/src/client/shell/jam-surface-parts.tsx +8 -6
  78. package/src/client/shell/jam-ui.tsx +12 -5
  79. package/src/client/shell/jam-voice.ts +4 -2
  80. package/src/client/shell/live-picture.ts +134 -0
  81. package/src/client/shell/main.tsx +7 -1
  82. package/src/client/shell/marks-ui.tsx +11 -0
  83. package/src/client/shell/open-item.ts +83 -0
  84. package/src/client/shell/open-resolve.ts +50 -0
  85. package/src/client/shell/perf.ts +51 -5
  86. package/src/client/shell/recorder-core.ts +4 -1
  87. package/src/client/shell/recorder-hmr.ts +36 -0
  88. package/src/client/shell/recorder-reloads.ts +264 -0
  89. package/src/client/shell/recorder-seams.ts +116 -0
  90. package/src/client/shell/recorder-self.ts +73 -0
  91. package/src/client/shell/recorder-signals-core.ts +139 -0
  92. package/src/client/shell/recorder-signals.ts +485 -0
  93. package/src/client/shell/recorder.ts +115 -41
  94. package/src/client/shell/store.ts +62 -24
  95. package/src/client/shell/styles.css +2 -0
  96. package/src/client/shell/whiteout-probes.ts +3 -1
  97. package/src/client/stage/main.tsx +39 -12
  98. package/src/shared/app-api.ts +201 -9
  99. package/src/shared/app-perf.ts +103 -8
  100. package/src/shared/app-report.ts +586 -0
  101. package/src/shared/perf-records.ts +445 -0
  102. package/src/shared/perf-run.ts +6 -2
  103. package/templates/instructions/jam.md +4 -0
  104. package/dist/live-Cgzsicwi.mjs +0 -4
  105. package/dist/perf-jam-QxD_UnzN.mjs +0 -635
@@ -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
@@ -87,6 +88,14 @@ const startId = params.get('at') ?? ''
87
88
  // data-goto ever navigates the stage cross-origin
88
89
  const post = (msg: Record<string, unknown>) => { if (window.parent !== window) window.parent.postMessage(msg, location.origin) }
89
90
 
91
+ /** What a live picture binds (spec 28 A4.6 #34, r1 #5), read by the shell straight from this same-origin document - no
92
+ * message ordering involved (src/client/shell/live-picture.ts). `boot` is this document's; `seq` rises as every swap
93
+ * starts and as it commits; `at` is cleared as a swap starts and set, with `t`, in the tick the committed frame says
94
+ * `sh:stage-shown`. A reloaded stage is a new document: a new `boot`, and no `at` until its first frame commits. */
95
+ export interface StageRecord { boot: string; seq: number; at: string | null; t: number }
96
+ const stageRecord: StageRecord = { boot: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`, seq: 0, at: null, t: 0 }
97
+ ;(window as unknown as { __mvStage: StageRecord }).__mvStage = stageRecord
98
+
90
99
  window.addEventListener('error', (e) => post({ type: 'sh:stage-error', message: String(e.message || e.error) }))
91
100
  window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:stage-error', message: `unhandled rejection: ${e.reason}` }))
92
101
  // pinch inside the stage must not zoom the parent page (same rule as the frame bridge)
@@ -95,7 +104,9 @@ document.addEventListener('gesturestart', (e) => e.preventDefault())
95
104
  // B0.2: a nested scroll container hitting its boundary must not chain into the shell page
96
105
  document.documentElement.style.overscrollBehavior = 'contain'
97
106
 
98
- interface Mounted { id: string; Frame: ComponentType; wrappers: ComponentType[]; slide: boolean }
107
+ interface Mounted { id: string; Frame: ComponentType; wrappers: ComponentType[]; slide: boolean
108
+ /** the swap that committed it: the same frame committed again (a restart on it) is a new showing */
109
+ commit?: number }
99
110
 
100
111
  /** Resolve a frame id to its component + wrapper chain. Modules are import()-cached by
101
112
  * Vite, so re-resolving a chain yields the SAME component references - React keeps
@@ -118,7 +129,11 @@ class Boundary extends Component<{ resetKey: string; children?: ReactNode }, { e
118
129
  componentDidUpdate(prev: { resetKey: string }) {
119
130
  if (prev.resetKey !== this.props.resetKey && this.state.err) this.setState({ err: null })
120
131
  }
121
- componentDidCatch(err: Error) { post({ type: 'sh:stage-error', message: err.message }) }
132
+ componentDidCatch(err: Error) {
133
+ // its card holds the stage now: nothing on it is the frame
134
+ stageRecord.at = null; stageRecord.seq++
135
+ post({ type: 'sh:stage-error', message: err.message })
136
+ }
122
137
  render() {
123
138
  if (!this.state.err) return this.props.children
124
139
  return createElement(ErrorCard, { title: 'frame crashed', message: this.state.err.message, detail: this.props.resetKey })
@@ -128,13 +143,18 @@ class Boundary extends Component<{ resetKey: string; children?: ReactNode }, { e
128
143
  /** spec 26: a frame that committed - inside the error boundary, so a crash never counts - says which
129
144
  * frame the stage shows, at which revision (the stamp this document was served with: a frame imported
130
145
  * later never claims more than the wrappers it renders with), for which document generation. */
131
- function Shown({ id }: { id: string }) {
146
+ function Shown({ id, commit }: { id: string; commit?: number }) {
147
+ const said = useRef(false)
132
148
  // a tick later, and only if it is still mounted: a frame that throws from its own effects is replaced by
133
- // the boundary's card first, which unmounts this and cancels the report
149
+ // the boundary's card first, which unmounts this and cancels the report. Said once per frame shown; the record
150
+ // follows every commit (A4.6 #34), so the same frame committed again is shown again from then
134
151
  useEffect(() => {
135
- const t = setTimeout(() => post({ type: 'sh:stage-shown', at: id, nav: params.get('r') ?? '', epoch: stamps?.epoch ?? '', doc: stamps?.doc[id] ?? 0 }), 0)
152
+ const t = setTimeout(() => {
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 }) }
154
+ stageRecord.at = id; stageRecord.t = Date.now()
155
+ }, 0)
136
156
  return () => clearTimeout(t)
137
- }, [id])
157
+ }, [id, commit])
138
158
  return null
139
159
  }
140
160
 
@@ -158,6 +178,8 @@ function Stage() {
158
178
  const goto = async (id: string, announce: boolean) => {
159
179
  if (id === current.current && mounted && !err) return
160
180
  const seq = ++swapSeq.current
181
+ // a live picture asked before this swap is of another showing (A4.6 #34)
182
+ stageRecord.seq++; stageRecord.at = null
161
183
  try {
162
184
  const next = await resolve(id)
163
185
  if (seq !== swapSeq.current) return // a newer swap superseded this one
@@ -187,7 +209,8 @@ function Stage() {
187
209
  if (seq !== swapSeq.current) return
188
210
  // the slide mark first: content primitives read it while they render
189
211
  document.documentElement.toggleAttribute('data-mv-slide', next.slide)
190
- flushSync(() => { setErr(null); setMounted(next) })
212
+ stageRecord.seq++
213
+ flushSync(() => { setErr(null); setMounted({ ...next, commit: seq }) })
191
214
  current.current = id
192
215
  disarm()
193
216
  }
@@ -239,7 +262,7 @@ function Stage() {
239
262
  recorder.current = createRecorder({ post, getFrame: () => current.current, mode: 'play', trusted })
240
263
  // the keys the shell owns right now: consumed here, ahead of the frame, and forwarded as sh:key
241
264
  const keys = createKeys({ post, trusted })
242
- 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 })
243
266
 
244
267
  // data-goto is handled HERE, in place - never posted up as sh:go (capture phase
245
268
  // beats any frame handler; preventDefault stops real <a href> navigations). A
@@ -250,7 +273,7 @@ function Stage() {
250
273
  // on anything interactive, and data-goto (below) always wins
251
274
  if (slidesMode && e.target instanceof Element
252
275
  && !e.target.closest('a, button, input, textarea, select, video, .mv-video, [contenteditable], [data-goto]')) {
253
- 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
254
277
  }
255
278
  const el = e.target instanceof Element ? e.target.closest('[data-goto]') : null
256
279
  if (!el) return
@@ -288,6 +311,8 @@ function Stage() {
288
311
  if (data?.type === 'sh:set-theme') {
289
312
  document.documentElement.dataset.theme = data.theme
290
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 })))
291
316
  }
292
317
  else if (data?.type === 'sh:stage-set' && typeof data.at === 'string') goto(data.at, false)
293
318
  }
@@ -310,13 +335,15 @@ function Stage() {
310
335
  // that differs at depth k legitimately remounts everything below
311
336
  let tree: ReactNode = createElement(mounted.Frame)
312
337
  for (const W of [...mounted.wrappers].reverse()) tree = createElement(W, null, tree)
313
- return createElement(Boundary, { resetKey: mounted.id }, createElement(Shown, { key: mounted.id, id: mounted.id }), tree)
338
+ return createElement(Boundary, { resetKey: mounted.id }, createElement(Shown, { key: mounted.id, id: mounted.id, commit: mounted.commit }), tree)
314
339
  }
315
340
 
316
341
  async function boot() {
317
342
  try {
318
343
  await import('virtual:sh-theme' as string)
319
- 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))
320
347
  } catch (err) {
321
348
  post({ type: 'sh:stage-error', message: (err as Error).message })
322
349
  document.getElementById('root')!.innerHTML =
@@ -13,6 +13,17 @@
13
13
  * presentation epochs of the one ground; `mv:perf` / `mv:perf-ask`, the recorder's traffic. Every new method of
14
14
  * `MarverAppV1` is optional: a 0.27.2 shell inside app 0.1 still sees `marverApp` (marver-app.ts requires only the
15
15
  * six 0.1 methods), and a shell trusts the inset only with the whole presentation contract (inset.ts).
16
+ *
17
+ * A4 (app 0.3, marver 0.29.0) adds, frozen before its streams split (A4.6 #56) and `v` still 1: the features a slot
18
+ * file may list (`FEATURE`, A4.6 #2); the live stream's event and wire (`LiveEvent`, `LIVE_BOUNDS`, `LIVE_WIRE`,
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
+ * click handed to the shell (`OpenItem`, `OpenResult`, A4.6 #29, #30); `mv:capture`, a live picture of the
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`).
16
27
  */
17
28
 
18
29
  export const APP_API_VERSION = 1
@@ -41,7 +52,8 @@ export interface Busy { busy: boolean; unsaved: boolean; why: Why[] }
41
52
  export interface Theme { dark: boolean }
42
53
  /** `mv:menu` - at most 40, no separators in 0.1 (A2.7). */
43
54
  export interface MenuItem { id: string; group: 'view' | 'jam'; label: string; hint?: string; checked?: boolean }
44
- /** `mv:app-state` (main to canvas). `untrusted`: stop every microphone track (A2.14 #13). `open-next` is A4's. */
55
+ /** `mv:app-state` (main to canvas). `untrusted`: stop every microphone track (A2.14 #13). A4 adds `mv:open` and
56
+ * `mv:capture`; this stays these three (A4.6 #29). */
45
57
  export type AppState = 'shown' | 'hidden' | 'untrusted'
46
58
  /**
47
59
  * `mv:doc` - the preload's one synchronous call at document start, answered at once on every path while untrusted,
@@ -52,8 +64,11 @@ export type AppState = 'shown' | 'hidden' | 'untrusted'
52
64
  export interface DocAnswer { reopen: boolean; inset?: Inset }
53
65
  /** `mv:admit` (main to canvas) - the document admitted at its trusted commit (v1.12 r1 #1). */
54
66
  export interface Admit { doc: string }
55
- /** `mv:menu-click` (main to canvas). */
56
- 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 }
57
72
  /**
58
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
59
74
  * channels table: "Mark all as seen sends `mv:menu-click mark-all-seen` to the canvas"). A shell that does not know
@@ -86,15 +101,26 @@ export interface PerfSize { w: number; h: number }
86
101
  * says which of them are still valid (moved by less than their clearance between the two answers);
87
102
  * - `mem`: `process.getProcessMemoryInfo().private` and `getHeapStatistics()`, all in KB (A3.8 #5);
88
103
  * - `shown`: the second animation-frame callback after a `shown` ask (A3.8 #9: a frame produced, not presented);
89
- * - `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.
90
109
  */
91
110
  export type PerfMsg =
92
111
  | { kind: 'gesture'; on: boolean; seq: number; type?: 'pan' | 'zoom' | 'layout' }
93
- | { 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 }
94
113
  | { kind: 'probes'; tick: number; at: 'after'; valid: boolean[]; cam: PerfCam | null; view: PerfSize }
95
114
  | { kind: 'mem'; tick: number; privateKB: number; heapUsedKB: number; heapTotalKB: number }
96
115
  | { kind: 'shown'; tick: number }
97
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
98
124
 
99
125
  /**
100
126
  * `mv:perf-ask` (main to canvas; on the wire `{ doc, ...PerfAsk }`). The preload answers `mem` and `shown` itself,
@@ -109,7 +135,8 @@ export type PerfAsk =
109
135
  /** What reaches the shell's `onPerfAsk`. */
110
136
  export type PerfProbeAsk = Extract<PerfAsk, { kind: 'probes' }>
111
137
 
112
- /** The canvas channels. `mv:inset` is gone (A3.8 #26: `mv:doc` answers it); needs-you and capture are A4's. */
138
+ /** The canvas channels. `mv:inset` is gone (A3.8 #26: `mv:doc` answers it). A4 adds `mv:open` and `mv:capture`;
139
+ * `mv:needs-you` is cut (A4.6 #15): main reads what needs you from the server's live stream. */
113
140
  export const CANVAS_CHANNELS = {
114
141
  doc: 'mv:doc',
115
142
  admit: 'mv:admit',
@@ -125,6 +152,11 @@ export const CANVAS_CHANNELS = {
125
152
  /** A3: the recorder (A3.8 #10) */
126
153
  perf: 'mv:perf',
127
154
  perfAsk: 'mv:perf-ask',
155
+ /** A4: a notice's click (main to canvas) and the shell's answer (A4.6 #29) */
156
+ open: 'mv:open',
157
+ opened: 'mv:opened',
158
+ /** A4: a live picture of the document's own view - an invoke (A4.6 #35) */
159
+ capture: 'mv:capture',
128
160
  } as const
129
161
 
130
162
  /** Bounds main checks again (A2.14 #19): unknown fields are stripped, a known one of the wrong type or past its bound refuses the message. */
@@ -142,6 +174,10 @@ export const BOUNDS = {
142
174
  epoch: 2 ** 31 - 1,
143
175
  viewport: 20_000,
144
176
  frames: 8,
177
+ /** A4.6 #35, #37: a live picture's long side at most (main scales down to it; the server refuses past it), and
178
+ * main's deadline for one capture */
179
+ captureLong: 4096,
180
+ captureMs: 1500,
145
181
  } as const
146
182
 
147
183
  /**
@@ -161,9 +197,151 @@ export const PERF_BOUNDS = {
161
197
  burst: 64,
162
198
  } as const
163
199
 
200
+ // ---- A4 (app 0.3, marver 0.29.0): frozen by A4.6 #56 ----------------------------------------------------------
201
+
202
+ /**
203
+ * What a slot file's `features` say a canvas offers the Mac app (src/server/slots.ts `FEATURES`; the app reads each
204
+ * registry entry's). A name is a version (A4.6 #2): a breaking change to its contract takes a new name (`live2`),
205
+ * never a new meaning for this one, and `bridge` and `inset` imply none of the others. An app ignores a name it does
206
+ * not know (A1.3), and asks nothing of a canvas that does not list one (A4.6 #3).
207
+ */
208
+ export const FEATURE = {
209
+ /** 0.27.1 (A2.9, A2.14 #15): the shell says hello, theme, menu and `mv:busy` with `unsaved` */
210
+ bridge: 'bridge',
211
+ /** 0.27.2 (A3.8 #31): the shell takes the top inset under the strip and answers presentation requests */
212
+ inset: 'inset',
213
+ /** 0.29.0 (A4.6 #5, #6, #11): the server answers `GET /__mv/app/live` (`LIVE_WIRE`) with `LiveEvent` v1 */
214
+ live: 'live',
215
+ /** 0.29.0 (A4.6 #29, #30): the shell handles `mv:open` and answers `mv:opened` */
216
+ open: 'open',
217
+ /** 0.29.0 (A4.6 #33-#37): the shell asks `mv:capture` for live pictures and the server takes `POST /api/jam/picture/live` */
218
+ capture: 'capture',
219
+ } as const
220
+ export type Feature = (typeof FEATURE)[keyof typeof FEATURE]
221
+
222
+ /** What waits on the owner, one item per need (A4.6 #8, #10). `stopped` is main's own item, never on the wire (#20). */
223
+ export const LIVE_KINDS = ['ask', 'review', 'failed', 'stalled'] as const
224
+ export type LiveKind = (typeof LIVE_KINDS)[number]
225
+
226
+ /**
227
+ * One need (A4.6 #8-#11). Its `id` is `<kind>:` and the first 20 hex of a sha256 over the occurrence's persisted
228
+ * parts (#9): the same need gives the same id across reconnects and restarts, a new occurrence a new id; the app
229
+ * compares ids and never parses one. Every ref (`board`, `frame`, `thread`, `msg`, a card or batch id) is at most
230
+ * `LIVE_BOUNDS.ref`; an item with a longer one is left out of `items` and still counted.
231
+ */
232
+ export interface LiveItem {
233
+ id: string
234
+ kind: LiveKind
235
+ board: string
236
+ /** one line: whitespace collapsed, control characters removed, at most 140 UTF-16 units, never cut inside a pair */
237
+ title: string
238
+ /** failed: why, at most 140 */
239
+ note?: string
240
+ /** when it began waiting: order only, never identity */
241
+ at: number
242
+ frame?: string
243
+ /** an ask's thread; a comment card's thread */
244
+ thread?: string
245
+ /** ask: the asking message's id - its occurrence */
246
+ msg?: string
247
+ /** the Jam cards it covers, at most 8 (MAX_MEMBERS) */
248
+ cards?: string[]
249
+ /** review, failed with a run, stalled */
250
+ batch?: string
251
+ /** stalled: the claim's generation */
252
+ gen?: number
253
+ /** the counter in its id (A4.6 #9, r1 #1): a review's `att`, a failed run's `failures` (a card that failed with no
254
+ * run: its `att`), a stalled run's `stalls`. A click compares it with the view as it is then (#30) */
255
+ occ?: number
256
+ }
257
+
258
+ /** One snapshot of the live stream, whole every time (A4.6 #11, #12): no deltas. */
259
+ export interface LiveEvent {
260
+ v: 1
261
+ /** the slot file's; equals the response's `x-mv-instance` */
262
+ instance: string
263
+ /** per server process: rises across Vite restarts of one instance */
264
+ seq: number
265
+ /** off: no Jam view here (Jam off, or the repo's Jam lock held elsewhere) - its review, failed and stalled are then
266
+ * 0 because nothing on this canvas can act on them, not because none wait (#12) */
267
+ jam: 'on' | 'off'
268
+ /** newest first by `at`, at most `LIVE_BOUNDS.items`, and only as many as fit `eventBytes` */
269
+ items: LiveItem[]
270
+ /** items the cap or the byte budget left out (the oldest); 0 when none. An item left out for a long ref is not here */
271
+ cut: number
272
+ /** exact, before the cap */
273
+ counts: { ask: number; review: number; failed: number; stalled: number }
274
+ /** frames new to the owner: a count only, never items, never a notice */
275
+ unseen: number
276
+ /** `marver work` holds a lease, or a Jam run is at work (not stalled, offered, waiting or stopping) (#8) */
277
+ working: boolean
278
+ /** a Jam session runs (`!!view.session`) */
279
+ session: boolean
280
+ }
281
+
282
+ /**
283
+ * The bounds both sides keep (A4.6 #11, #16): the server's selector and encoder write within them, and main checks
284
+ * every field again, stripping unknown ones and dropping an item of an unknown kind (not the event). `eventBytes`:
285
+ * the event as written (`event: live`, its `data:` line, the blank line) in UTF-8 bytes - the encoder drops the
286
+ * oldest whole items until it fits, and main drops a connection whose event is longer.
287
+ */
288
+ export const LIVE_BOUNDS = {
289
+ items: 100,
290
+ title: 140,
291
+ note: 140,
292
+ ref: 128,
293
+ cards: 8,
294
+ eventBytes: 65_536,
295
+ id: /^(ask|review|failed|stalled):[0-9a-f]{20}$/,
296
+ } as const
297
+
298
+ /**
299
+ * The live stream's wire (A4.6 #5, #6, #14). `GET <origin><path>` with `x-mv-ws`, a fresh `x-mv-nonce` and
300
+ * `x-mv-app` = `appProof(key, port)`; the 200 is `text/event-stream` carrying `x-mv-instance` and `x-mv-proof` =
301
+ * `liveProof(key, nonce, port)` (src/server/proof.ts). Each snapshot is `event: <event>`, one `data:` line of
302
+ * `LiveEvent` JSON, then a blank line; `<heartbeat>` is a comment line every `heartbeatMs`. No `Last-Event-ID`, no
303
+ * `retry:`. At most `clients` at once (one more ends the oldest); a client with more than `slowBytes` unsent is
304
+ * dropped and reconnects.
305
+ */
306
+ export const LIVE_WIRE = {
307
+ path: '/__mv/app/live',
308
+ type: 'text/event-stream',
309
+ event: 'live',
310
+ heartbeat: ': hb',
311
+ heartbeatMs: 30_000,
312
+ clients: 4,
313
+ slowBytes: 65_536,
314
+ } as const
315
+
316
+ /** What a notice's click hands the shell (A4.6 #29, r1 #1): the item as the stream gave it, its words left out. */
317
+ export type OpenItem = Pick<LiveItem, 'id' | 'kind' | 'board' | 'thread' | 'msg' | 'cards' | 'batch' | 'gen' | 'occ'>
318
+ /**
319
+ * The shell's answer (A4.6 #30): `handled` - the item is on screen; `stale` - its target stands in another state, or
320
+ * the same state with another counter, and opens as it stands; `missing` - the target is gone, its board opens;
321
+ * `busy` - a capture records or words wait unsent, nothing moved; `dropped` - a read failed, the deadline passed or
322
+ * a later request took its place, nothing moved.
323
+ */
324
+ export const OPEN_RESULTS = ['handled', 'stale', 'missing', 'busy', 'dropped'] as const
325
+ export type OpenResult = (typeof OPEN_RESULTS)[number]
326
+ /** `mv:open` (main to canvas; on the wire `{ doc, item }`, stamped by main like `mv:app-state`). */
327
+ export interface Open { item: OpenItem }
328
+ /** `mv:opened` (canvas to main; on the wire `{ doc, p }`, stamped by the preload and accepted like the reports). */
329
+ export interface Opened { id: string; result: OpenResult }
330
+
331
+ /** `mv:capture`'s rect, in view CSS px (A4.6 #35): finite, `x, y >= 0`, `width, height >= 1`, inside the view. */
332
+ export interface CaptureRect { x: number; y: number; width: number; height: number }
333
+ /** `mv:capture` (canvas to main, an invoke; on the wire `{ doc, p }`). */
334
+ export interface CaptureAsk { rect: CaptureRect }
335
+ /** Why there is no picture (A4.6 #35): the shell then takes the server's render, as without the app (#36). */
336
+ export const CAPTURE_WHY = ['hidden', 'busy', 'bounds', 'empty', 'timeout', 'stale', 'untrusted'] as const
337
+ export type CaptureWhy = (typeof CAPTURE_WHY)[number]
338
+ /** The PNG's bytes cross IPC as a `Uint8Array` (a sandboxed preload has no `Buffer` in Electron 45, A4.6 #1); its
339
+ * size in device pixels, its long side at most `BOUNDS.captureLong`. */
340
+ export type CaptureAnswer = { ok: true; png: Uint8Array; width: number; height: number } | { ok: false; why: CaptureWhy }
341
+
164
342
  /**
165
343
  * `window.marverApp`, exposed by the canvas preload to verified local canvases. Typed methods only: a page never
166
- * names a channel. The six methods of 0.1 are required (marver-app.ts checks them); every A3 one is optional.
344
+ * names a channel. The six methods of 0.1 are required (marver-app.ts checks them); every A3 and A4 one is optional.
167
345
  */
168
346
  export interface MarverAppV1 {
169
347
  readonly v: 1
@@ -188,8 +366,22 @@ export interface MarverAppV1 {
188
366
  perf?(p: PerfMsg): void
189
367
  /** A3 (app 0.2): main's probe asks (the white-out detector, A3.8 #16) */
190
368
  onPerfAsk?(fn: (a: PerfProbeAsk) => void): () => void
191
- /** 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 */
192
- 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 }
374
+ /**
375
+ * A4 (app 0.3): main's `mv:open` for a clicked notice, delivered once to this document after its hello when its
376
+ * instance lists `open` (A4.6 #29). The shell resolves the occurrence against a fresh read and answers (#30); the
377
+ * preload sends the answer as `mv:opened`
378
+ */
379
+ onOpen?(fn: (p: OpenItem) => OpenResult | Promise<OpenResult>): () => void
380
+ /**
381
+ * A4 (app 0.3): a picture of this document's own view, `rect` in view CSS px (A4.6 #35). Before an admit it
382
+ * answers `untrusted` with no IPC; main answers `hidden`, `busy`, `bounds`, `empty`, `timeout` or `stale` otherwise
383
+ */
384
+ capture?(a: CaptureAsk): Promise<CaptureAnswer>
193
385
  }
194
386
 
195
387
  /** Main's words for a reason (the hang sheet, the unsaved pill); `heights` is never named (A2.14 #18). */
@@ -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
 
@@ -49,9 +65,11 @@ export interface AppEnvelope {
49
65
  /**
50
66
  * A record about a tab carries its identity, captured in the event's turn before any await (A3.8 #8). `page` is the
51
67
  * 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`).
68
+ * the next document's. `commit` is the tab's commit count (tabs.ts `doc.commits`). A shared canvas's (A4.6 #48) has no
69
+ * `ws` - so `marver perf` in a repo never shows it - and `origin`, its scheme, host and port: never a path, query,
70
+ * hash or credential, so two shared canvases on one host stay apart and no sign-in token is ever written.
53
71
  */
54
- export interface TabIdent { tab: string; ws?: string; commit?: number; page?: string }
72
+ export interface TabIdent { tab: string; ws?: string; commit?: number; page?: string; origin?: string }
55
73
 
56
74
  /** A process, as the budgets and `--crashes` name it. */
57
75
  export interface ProcId { pid: number; born: number }
@@ -159,6 +177,16 @@ export interface SampleBody {
159
177
  sys: Sample['sys']
160
178
  /** wall ms of this minute's sysctl / ioreg spawns: the recorder's own cost */
161
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
162
190
  }
163
191
 
164
192
  /** `ioreg -rc AGXAccelerator -d1`, machine-wide (A3.1, A3.8 #9): a missing key is 'unknown'. */
@@ -190,6 +218,64 @@ export type PictureWhy = 'window hidden' | 'timeout' | 'empty' | 'write failed'
190
218
  /** A record held in the ring, as a flash quotes it: its kind, its time and its body. */
191
219
  export type RingEvent = { kind: AppKind; ts: number } & Record<string, unknown>
192
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
+
193
279
  export interface AppBodies {
194
280
  start: { version: string; electron: string; chrome: string; recorder: boolean; pid: number }
195
281
  sample: SampleBody
@@ -214,7 +300,7 @@ export interface AppBodies {
214
300
  * main's show to main's receipt of the preload's answer from its second animation-frame callback, on tab switches
215
301
  * only (A3.8 #9): the answer's IPC back to main is in it
216
302
  */
217
- shown: TabIdent & { ms: number }
303
+ shown: TabIdent & { ms: number; /** spec 30: the command that caused it (#52) */ by?: string }
218
304
  /** memory.ts: a change of level (A3.8 #45) */
219
305
  pressure: { level: PressureLevel | null; availablePct: number | null; was: PressureLevel | null }
220
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 */
@@ -224,7 +310,7 @@ export interface AppBodies {
224
310
  /** 5 s after an unload (A3.8 #45) */
225
311
  'unload-effect': TabIdent & { reason: UnloadReason; before: UnloadFigures; after: UnloadFigures; pidGone: boolean }
226
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) */
227
- reopen: TabIdent & { activateToLiftMs: number; unloadedForMs: number }
313
+ reopen: TabIdent & { activateToLiftMs: number; unloadedForMs: number; /** spec 30: the command that caused it */ by?: string }
228
314
  /** a presentation epoch's outcome (A3.8 #27; the one-ground stream's tuning record) */
229
315
  cover: TabIdent & {
230
316
  epoch: number
@@ -272,11 +358,20 @@ export interface AppBodies {
272
358
  inconclusive: number
273
359
  gpuEvents: RingEvent[]
274
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[]
275
363
  }
276
- /** the writer's queue overflowed (2,000 lines): how many went */
277
- 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' }
278
366
  /** app 0.1's error policy (errors.ts) */
279
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' }
280
375
  }
281
376
 
282
377
  /** A kind's body alone (what `recorder.event` and the writer take; the writer adds the envelope). */