@marver-design/marver 0.26.1 → 0.27.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 (82) hide show
  1. package/CHANGELOG.md +104 -0
  2. package/README.md +8 -3
  3. package/dist/{anchor-check-l-ny3UzH.mjs → anchor-check-ChdDqL5z.mjs} +1 -1
  4. package/dist/{bake-C-awKgLA.mjs → bake-DM_uWgAA.mjs} +1 -1
  5. package/dist/{boards-DYG22tOe.mjs → boards-DlTcpF47.mjs} +1 -1
  6. package/dist/{build-BDRiO_mP.mjs → build-DZnFysGU.mjs} +4 -4
  7. package/dist/cli.mjs +28 -16
  8. package/dist/{comments-BqXua-XL.mjs → comments-DxOkCSNE.mjs} +4 -4
  9. package/dist/{daemon-DL6Fwq6D.mjs → daemon-BSA0lV8d.mjs} +8 -6
  10. package/dist/detect-C0wpaePX.mjs +125 -0
  11. package/dist/dev-eQJhWsqg.mjs +1273 -0
  12. package/dist/dev-lock-C_FC70Mu.mjs +65 -0
  13. package/dist/exclusive-B1RtpeeP.mjs +150 -0
  14. package/dist/{init-D8DtrK_F.mjs → init-COD0x48i.mjs} +5 -3
  15. package/dist/{link-BNzLvdhI.mjs → link-DDXZVGtv.mjs} +20 -8
  16. package/dist/ls-D7O1G505.mjs +38 -0
  17. package/dist/{marks-DyWMv_Z1.mjs → marks-CWM3WJjc.mjs} +1 -1
  18. package/dist/perf-BWzQwZqj.mjs +369 -0
  19. package/dist/perf-BoDSkbEb.mjs +429 -0
  20. package/dist/{perf-jam-BU3TVrZu.mjs → perf-jam-D55U3FZK.mjs} +5 -2
  21. package/dist/{plugin-DkGmZs_r.mjs → plugin-C-E7omsh.mjs} +394 -55
  22. package/dist/{poster-BdtSKMDm.mjs → poster-Bx83ZYVK.mjs} +1 -1
  23. package/dist/{profile-WU9qcbIo.mjs → profile-Bh5Y5zpW.mjs} +1 -1
  24. package/dist/{publish-bakes-9RzRToXV.mjs → publish-bakes-aljgm45S.mjs} +2 -2
  25. package/dist/{queue-29ok5_eZ.mjs → queue-CAM_vNmX.mjs} +1 -1
  26. package/dist/recover-t9Pno3u9.mjs +66 -0
  27. package/dist/{share--oFJ1bCI.mjs → share-W5H3BNvP.mjs} +1 -1
  28. package/dist/{shot-XQV7HC9A.mjs → shot-DoHLl6ig.mjs} +1 -1
  29. package/dist/{shot-DQeR_Pfn.mjs → shot-LFhC-WYD.mjs} +9 -3
  30. package/dist/slots-DCDo3N0x.mjs +471 -0
  31. package/dist/{sync-DKk-yT1V.mjs → sync-BQVlHZpx.mjs} +4 -3
  32. package/dist/{work-F5u-twpJ.mjs → work-Bp1p39kq.mjs} +4 -2
  33. package/dist/{work-VvX_JIgl.mjs → work-BroFwnup.mjs} +4 -2
  34. package/docs/boards-and-folders.md +3 -1
  35. package/docs/jam-session.md +55 -1
  36. package/docs/performance.md +262 -0
  37. package/package.json +2 -2
  38. package/src/client/content/index.tsx +3 -0
  39. package/src/client/content/video.tsx +6 -2
  40. package/src/client/frame-host/bridge.js +22 -6
  41. package/src/client/frame-host/main.tsx +17 -5
  42. package/src/client/shell/App.tsx +180 -25
  43. package/src/client/shell/BoardList.tsx +5 -5
  44. package/src/client/shell/Comments.tsx +3 -2
  45. package/src/client/shell/JamSurface.tsx +4 -2
  46. package/src/client/shell/LockedApp.tsx +5 -5
  47. package/src/client/shell/Play.tsx +16 -8
  48. package/src/client/shell/Toolbar.tsx +12 -1
  49. package/src/client/shell/api.ts +206 -0
  50. package/src/client/shell/canvas/Canvas.tsx +30 -3
  51. package/src/client/shell/canvas/FrameNode.tsx +12 -3
  52. package/src/client/shell/canvas/admission.ts +8 -1
  53. package/src/client/shell/canvas/camera-broadcast.ts +15 -5
  54. package/src/client/shell/canvas/ctl.ts +2 -0
  55. package/src/client/shell/canvas/frame-registry.ts +28 -2
  56. package/src/client/shell/canvas/sleep.ts +4 -1
  57. package/src/client/shell/comments-store.ts +12 -4
  58. package/src/client/shell/goto.ts +22 -10
  59. package/src/client/shell/jam-capture.ts +22 -8
  60. package/src/client/shell/jam-keys.ts +4 -0
  61. package/src/client/shell/jam-panel.tsx +3 -0
  62. package/src/client/shell/jam-queue.ts +3 -3
  63. package/src/client/shell/jam-session.tsx +14 -8
  64. package/src/client/shell/jam-voice.ts +7 -5
  65. package/src/client/shell/legacy-links.ts +2 -2
  66. package/src/client/shell/main.tsx +4 -0
  67. package/src/client/shell/notes.ts +8 -1
  68. package/src/client/shell/perf.ts +69 -58
  69. package/src/client/shell/recorder-core.ts +183 -0
  70. package/src/client/shell/recorder.ts +565 -0
  71. package/src/client/shell/store.ts +254 -98
  72. package/src/client/shell/styles.css +26 -1
  73. package/templates/AGENTS-embedded.md +22 -4
  74. package/templates/AGENTS-studio.md +22 -4
  75. package/templates/demo/dark.tsx +1 -1
  76. package/templates/demo/welcome.tsx +1 -1
  77. package/templates/instructions/welcome.md +6 -3
  78. package/dist/config-Cf7EjAMf.mjs +0 -292
  79. package/dist/dev-Bw_qYWWq.mjs +0 -755
  80. package/dist/dev-lock-DWSpa6nj.mjs +0 -179
  81. package/dist/perf-C75MZ73h.mjs +0 -167
  82. package/dist/perf-DPbLGhhO.mjs +0 -49
@@ -0,0 +1,183 @@
1
+ /**
2
+ * The recorder's pure parts (spec 28 A1.7), kept apart from the browser-coupled store so they can be unit-tested
3
+ * (the ready-watch.ts precedent): the bounded outbox, sizes in UTF-8 bytes, what fits a page's last keepalive send, a
4
+ * gesture's numbers, and a node's outcome from what its live document said.
5
+ */
6
+
7
+ export const KINDS = ['load', 'commit', 'visible', 'frame', 'move', 'quiet', 'settled', 'cut', 'gesture', 'error', 'dropped'] as const
8
+ export type Kind = typeof KINDS[number]
9
+ /** Every record: the workspace, this page, the load that owns the geometry ('-' before the first commit), its place
10
+ * in this page's order, and when it happened. */
11
+ export interface Envelope { v: 1; ws: string; page: string; load: string; seq: number; ts: number; kind: Kind }
12
+ export type PerfRecord = Envelope & Record<string, unknown>
13
+
14
+ /** The queue's bounds: past either, the oldest go and are counted. */
15
+ export const QUEUE_MAX = 2_000, QUEUE_BYTES = 256 * 1024
16
+ /** A page that is going sends at most this much with keepalive: the rest of the 64 KB allowance is the captures'. */
17
+ export const KEEPALIVE_BYTES = 16 * 1024
18
+ /** Records wait this long for company before a send; a failed send waits this long before it tries again. */
19
+ export const SEND_MS = 2_000
20
+ /** A board is quiet after this long without a move. */
21
+ export const QUIET_MS = 1_000
22
+ /** A load not settled by then is cut. */
23
+ export const LOAD_MAX_MS = 120_000
24
+
25
+ const enc = new TextEncoder()
26
+ /** Size in UTF-8 bytes, as the request body will carry it - not `.length`, which counts UTF-16 units. */
27
+ export const bytesOf = (x: unknown): number => enc.encode(typeof x === 'string' ? x : JSON.stringify(x)).length
28
+
29
+ /** Records waiting to be sent, oldest first. Past `max` records or `maxBytes` the oldest go, counted in `dropped`
30
+ * (the recorder sends that count in a `dropped` record and zeroes it). */
31
+ export class Outbox {
32
+ private items: { rec: PerfRecord; bytes: number }[] = []
33
+ private waiting = new Set<PerfRecord>()
34
+ bytes = 0
35
+ dropped = 0
36
+ constructor(private max = QUEUE_MAX, private maxBytes = QUEUE_BYTES) {}
37
+ get size(): number { return this.items.length }
38
+ push(rec: PerfRecord): void {
39
+ const bytes = bytesOf(rec)
40
+ this.items.push({ rec, bytes })
41
+ this.waiting.add(rec)
42
+ this.bytes += bytes
43
+ this.trim()
44
+ }
45
+ /** A waiting record changed in place (a coalesced move): its size again. */
46
+ touch(rec: PerfRecord): void {
47
+ for (let i = this.items.length - 1; i >= 0; i--) {
48
+ const it = this.items[i]
49
+ if (it.rec !== rec) continue
50
+ const bytes = bytesOf(rec)
51
+ this.bytes += bytes - it.bytes
52
+ it.bytes = bytes
53
+ this.trim()
54
+ return
55
+ }
56
+ }
57
+ /** Still waiting (not sent, not dropped)? */
58
+ has(rec: PerfRecord): boolean { return this.waiting.has(rec) }
59
+ /** Everything waiting, oldest first; the outbox is empty after. */
60
+ takeAll(): PerfRecord[] {
61
+ const out = this.items.map((it) => it.rec)
62
+ this.items = []
63
+ this.waiting.clear()
64
+ this.bytes = 0
65
+ return out
66
+ }
67
+ private trim(): void {
68
+ while (this.items.length && (this.items.length > this.max || this.bytes > this.maxBytes)) {
69
+ const it = this.items.shift()!
70
+ this.waiting.delete(it.rec)
71
+ this.bytes -= it.bytes
72
+ // a `dropped` record that goes takes what it counted with it
73
+ this.dropped += it.rec.kind === 'dropped' && typeof it.rec.n === 'number' ? it.rec.n : 1
74
+ }
75
+ }
76
+ }
77
+
78
+ /** For a page that is going: as many of `first` (the cuts) as fit, in their order, then the oldest of `rest`, while
79
+ * the whole body `{"records":[…]}` stays within `maxBytes` with `reserve` left for a `dropped` record - the limit
80
+ * holds for the cuts too, however many a stalled send left waiting. The others, cuts included, are `lost`. */
81
+ export function fitWithin(first: readonly PerfRecord[], rest: readonly PerfRecord[], maxBytes = KEEPALIVE_BYTES, reserve = 160): { fit: PerfRecord[]; lost: number } {
82
+ const fit: PerfRecord[] = []
83
+ let size = bytesOf({ records: [] }) + reserve
84
+ const take = (r: PerfRecord) => {
85
+ const add = bytesOf(r) + (fit.length ? 1 : 0)
86
+ if (size + add > maxBytes) return false
87
+ size += add
88
+ fit.push(r)
89
+ return true
90
+ }
91
+ let lost = 0
92
+ for (const r of first) if (!take(r)) lost++
93
+ for (let i = 0; i < rest.length; i++) if (!take(rest[i])) { lost += rest.length - i; break }
94
+ return { fit, lost }
95
+ }
96
+
97
+ /** A gesture's frame intervals as they are: nearest-rank percentiles (cli/perf.ts `spread`'s rule), one decimal; the
98
+ * counts over 17 ms and over 33 ms; `longFrames` as given. */
99
+ export function gestureStats(dts: readonly number[], longFrames: number): { frames: number; p50: number; p95: number; max: number; over17ms: number; over33ms: number; longFrames: number } {
100
+ const v = [...dts].sort((a, b) => a - b)
101
+ const at = (q: number) => (v.length ? v[Math.min(v.length - 1, Math.ceil(q * v.length) - 1)] : 0)
102
+ const r = (x: number) => Math.round(x * 10) / 10
103
+ return {
104
+ frames: v.length, p50: r(at(0.5)), p95: r(at(0.95)), max: r(v[v.length - 1] ?? 0),
105
+ over17ms: v.filter((d) => d > 17).length, over33ms: v.filter((d) => d > 33).length, longFrames,
106
+ }
107
+ }
108
+
109
+ /** What a node of a load waits for: a settled measure at its width, its ready, or nothing (missing). */
110
+ export type Rule = 'measure' | 'ready' | 'missing'
111
+ export type Outcome = 'settled' | 'ready' | 'missing' | 'error' | 'never-ready'
112
+ /** One node's story, as its live document told it (page-level, by node key: a reload of the same board keeps the
113
+ * documents, and their facts carry over). Times are performance.now(). */
114
+ export interface Track {
115
+ frame: string
116
+ /** the document these facts belong to */
117
+ boot?: string
118
+ /** that document's URL revision (its own `r`), and the node's navigation when it was adopted */
119
+ gen?: string
120
+ nav?: number
121
+ /** when the node's mount was admitted - not per document (a reload keeps its slot) */
122
+ admittedAt?: number
123
+ readyAt?: number
124
+ firstMeasureAt?: number
125
+ /** a settled report the store took at this width */
126
+ settled?: { at: number; w: number }
127
+ errorAt?: number
128
+ /** the watchdog's second silence, for this navigation */
129
+ neverReady?: { at: number; nav: number }
130
+ }
131
+
132
+ /** A message from document `boot`: kept only when that document is the one there now. A new live document starts
133
+ * the node's story over - noting its own URL revision (`gen`, from the message) and the node's navigation (`nav`) -
134
+ * and a message from a live document supersedes the watchdog's verdict. */
135
+ export function adopt(t: Track, boot: unknown, live: string | undefined, doc?: { gen?: unknown; nav?: number }): boolean {
136
+ if (typeof boot !== 'string' || !boot || boot !== live) return false
137
+ if (t.boot !== boot) {
138
+ t.boot = boot
139
+ delete t.gen; delete t.nav; delete t.readyAt; delete t.firstMeasureAt; delete t.settled; delete t.errorAt
140
+ if (doc) t.nav = doc.nav ?? 0
141
+ }
142
+ if (typeof doc?.gen === 'string') t.gen = doc.gen
143
+ delete t.neverReady
144
+ return true
145
+ }
146
+
147
+ /** The node's outcome now, or null (pending). An outcome a document reported counts only while that document is the
148
+ * live one, on the navigation the shell asked for last - a document since replaced, one still booting (no live boot
149
+ * yet), or one a reload is replacing (the node's `nav` moved on, or its iframe was sent to another revision `gen`,
150
+ * while the old document is still there until the new one commits) sends it back to pending.
151
+ * `missing` and `never-ready` have no document and are exempt: missing while the frame is absent from the manifest,
152
+ * never-ready for the navigation the watchdog gave up on, until a new navigation or a live message replaces it. */
153
+ export function outcomeOf(rule: Rule, t: Track | undefined, live: string | undefined, node: { w: number; nav?: number; gen?: string }): Outcome | null {
154
+ if (rule === 'missing') return 'missing'
155
+ if (!t) return null
156
+ const current = !!live && t.boot === live
157
+ && (t.nav === undefined || t.nav === (node.nav ?? 0))
158
+ && (t.gen === undefined || node.gen === undefined || t.gen === node.gen)
159
+ if (current && t.errorAt !== undefined) return 'error'
160
+ if (current && rule === 'ready' && t.readyAt !== undefined) return 'ready'
161
+ if (current && rule === 'measure' && t.settled && t.settled.w === Math.round(node.w)) return 'settled'
162
+ if (t.neverReady && t.neverReady.nav === (node.nav ?? 0)) return 'never-ready'
163
+ return null
164
+ }
165
+
166
+ /** The first three stack lines of an error - Chrome's " at …", else Safari's and Firefox's "fn@url:line:col" -
167
+ * each 200 characters at most. */
168
+ export function stackLines(stack: unknown): string[] | undefined {
169
+ if (typeof stack !== 'string' || !stack) return undefined
170
+ const lines = stack.split('\n')
171
+ const chrome = lines.filter((l) => /^\s*at /.test(l))
172
+ const picked = chrome.length ? chrome : lines.filter((l) => /@.*:\d+(:\d+)?$/.test(l.trim()))
173
+ const out = picked.slice(0, 3).map((l) => l.trim().slice(0, 200)).filter(Boolean)
174
+ return out.length ? out : undefined
175
+ }
176
+
177
+ /** A string bounded to `n` characters, or undefined. */
178
+ export const bound = (v: unknown, n = 200): string | undefined => (typeof v === 'string' && v ? v.slice(0, n) : undefined)
179
+
180
+ /** 12 hex characters: a page, a load or a document id. */
181
+ export function newId(): string {
182
+ return Array.from(crypto.getRandomValues(new Uint8Array(6)), (b) => b.toString(16).padStart(2, '0')).join('')
183
+ }