@marver-design/marver 0.30.1 → 0.31.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 (107) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/README.md +11 -7
  3. package/dist/{anchor-check-Bv4o-R2T.mjs → anchor-check-B92s9tVv.mjs} +1 -1
  4. package/dist/{board-tree-BXR8dw4b.mjs → board-tree-DGj0HhEE.mjs} +6 -2
  5. package/dist/{boards-EH2onUXM.mjs → boards-Cim1GTKc.mjs} +32 -2
  6. package/dist/{boards-BeWtjGUM.mjs → boards-OlAhZ87x.mjs} +7 -7
  7. package/dist/{build-zWGXSzly.mjs → build-BNssmbqd.mjs} +14 -17
  8. package/dist/{capture-DEtM4qm5.mjs → capture-HaS-1or8.mjs} +1 -1
  9. package/dist/cli.mjs +38 -20
  10. package/dist/{collab-BEAcXrBb.mjs → collab-D2NcrOB8.mjs} +53 -14
  11. package/dist/comment-actions-Bxf9Ld4g.mjs +351 -0
  12. package/dist/{comments-XNhMmSSu.mjs → comments-BakJQwaf.mjs} +85 -10
  13. package/dist/config-B0YcFtqS.mjs +510 -0
  14. package/dist/{context-BUnFiyA3.mjs → context-Cj2TcC0H.mjs} +3 -3
  15. package/dist/{daemon-CChgWJNq.mjs → daemon-MxoEQajX.mjs} +222 -23
  16. package/dist/deep-link-DYtuT740.mjs +163 -0
  17. package/dist/{dev-DOgIITpT.mjs → dev-BBZe_brH.mjs} +23 -16
  18. package/dist/devices-uJZ2inMq.mjs +155 -0
  19. package/dist/{events-CLH4ijKP.mjs → events-Dieo1482.mjs} +49 -4
  20. package/dist/{init-CYlFaRzG.mjs → init-BgusplYn.mjs} +40 -10
  21. package/dist/{jam-Cj5gBvwD.mjs → jam-CkuLL8A8.mjs} +1 -1
  22. package/dist/{link-BFFRgrMt.mjs → link-Cmt9Xy4X.mjs} +54 -7
  23. package/dist/{logo-CXY-1yrn.mjs → logo-C9s7-Cy9.mjs} +89 -66
  24. package/dist/{ls-NqmePKOf.mjs → ls-DGVIW-Io.mjs} +1 -1
  25. package/dist/{manifest-DPZ3WNg_.mjs → manifest-CK8Qh4Nq.mjs} +255 -13
  26. package/dist/{marks-BnNANic9.mjs → marks-C8oX8kbE.mjs} +3 -3
  27. package/dist/{marks-DBp3h1Mc.mjs → marks-Dt-5JXCp.mjs} +18 -5
  28. package/dist/{marver-id-gate-vBLb_Icb.mjs → marver-id-gate-BAeuMeaU.mjs} +11 -7
  29. package/dist/md-B9_13Q0R.mjs +105 -0
  30. package/dist/notes-CRAX4wgk.mjs +148 -0
  31. package/dist/own-C8Mq0Hnf.mjs +128 -0
  32. package/dist/pdf-0m721FFn.mjs +117 -0
  33. package/dist/pdf-CZENT6t3.mjs +2299 -0
  34. package/dist/{perf-BCxAo0IS.mjs → perf-BB0XNt1M.mjs} +1 -1
  35. package/dist/{perf-6MOTHxay.mjs → perf-CIMijND6.mjs} +5 -5
  36. package/dist/{plugin-CFWBcAba.mjs → plugin-CL8_wL7a.mjs} +460 -83
  37. package/dist/{poster-DPPpQiva.mjs → poster-B7uSjlEP.mjs} +1 -1
  38. package/dist/{profile-B1FKOM1e.mjs → profile-cdmSer1k.mjs} +1 -1
  39. package/dist/{publish-bakes-_Zx8crP3.mjs → publish-bakes-BjgDNeyS.mjs} +3 -3
  40. package/dist/{queue-DeSQm24g.mjs → queue-BLLfdlDw.mjs} +156 -11
  41. package/dist/{recover-mDUVsnPd.mjs → recover-ByuFQOF9.mjs} +2 -2
  42. package/dist/{serve-DQv3Ti6X.mjs → serve-kcF6-H8V.mjs} +4 -4
  43. package/dist/{session-VDJfXEEm.mjs → session-DBF-nQvq.mjs} +29 -3
  44. package/dist/{share-Bu_kuOKL.mjs → share-CS2mg27O.mjs} +1 -1
  45. package/dist/{shot-d4h_hJi9.mjs → shot-BqwkdtKn.mjs} +4 -4
  46. package/dist/{shot-DBWN8hPP.mjs → shot-D2TQGo2V.mjs} +1 -1
  47. package/dist/show-B1u3DiJw.mjs +101 -0
  48. package/dist/{sizes-wjXDev3b.mjs → sizes-BckcL4Zz.mjs} +1 -1
  49. package/dist/{slots-Dn4Onb0V.mjs → slots-BOcfIqxy.mjs} +15 -3
  50. package/dist/{summary-Y8MY1Wuc.mjs → summary-cPmRDGpX.mjs} +1 -1
  51. package/dist/{sync-CMozOwZ0.mjs → sync-BNWwh8OF.mjs} +205 -7
  52. package/dist/{work-BYWD_1Zf.mjs → work-DRdzXPvg.mjs} +3 -3
  53. package/dist/{work-DJxH7cCX.mjs → work-Nv-n2_Un.mjs} +1 -1
  54. package/docs/app.md +49 -0
  55. package/docs/boards-and-folders.md +37 -6
  56. package/docs/jam-session.md +5 -0
  57. package/docs/live-jam.md +9 -0
  58. package/docs/pdf.md +108 -0
  59. package/docs/publish.md +9 -9
  60. package/docs/sharing.md +11 -0
  61. package/docs/slides.md +9 -0
  62. package/package.json +3 -1
  63. package/src/client/content/index.tsx +4 -2
  64. package/src/client/frame-host/main.tsx +3 -0
  65. package/src/client/shell/App.tsx +71 -24
  66. package/src/client/shell/BoardList.tsx +16 -7
  67. package/src/client/shell/Comments.tsx +77 -16
  68. package/src/client/shell/Play.tsx +24 -22
  69. package/src/client/shell/Toolbar.tsx +4 -3
  70. package/src/client/shell/app-bridge.ts +32 -5
  71. package/src/client/shell/canvas/Canvas.tsx +30 -8
  72. package/src/client/shell/canvas/FrameNode.tsx +3 -1
  73. package/src/client/shell/canvas/ctl.ts +16 -0
  74. package/src/client/shell/commands.ts +20 -0
  75. package/src/client/shell/comments-store.ts +81 -2
  76. package/src/client/shell/devices.tsx +42 -0
  77. package/src/client/shell/goto.ts +56 -9
  78. package/src/client/shell/icons.tsx +11 -4
  79. package/src/client/shell/jam-lines.ts +5 -3
  80. package/src/client/shell/jam-panel.tsx +17 -5
  81. package/src/client/shell/marks-ui.tsx +54 -0
  82. package/src/client/shell/notes.ts +21 -0
  83. package/src/client/shell/pdf-export.tsx +154 -0
  84. package/src/client/shell/pdf-notes.ts +20 -0
  85. package/src/client/shell/show.ts +250 -0
  86. package/src/client/shell/store.ts +23 -38
  87. package/src/client/shell/styles.css +43 -0
  88. package/src/shared/app-api.ts +49 -4
  89. package/src/shared/auto-place.ts +32 -0
  90. package/src/shared/board-tree.ts +3 -0
  91. package/src/shared/board-types.ts +6 -2
  92. package/src/shared/deep-link.ts +212 -0
  93. package/src/shared/devices.ts +89 -0
  94. package/src/shared/events.ts +48 -5
  95. package/src/shared/export-plan.ts +98 -0
  96. package/templates/AGENTS-embedded.md +76 -12
  97. package/templates/AGENTS-studio.md +76 -12
  98. package/templates/instructions/boards.md +6 -5
  99. package/templates/instructions/configure.md +32 -2
  100. package/templates/instructions/iterate.md +8 -0
  101. package/templates/instructions/jam.md +9 -0
  102. package/templates/instructions/publish.md +14 -4
  103. package/templates/instructions/review.md +4 -0
  104. package/templates/instructions/slides.md +67 -1
  105. package/templates/instructions/welcome.md +9 -5
  106. package/templates/playbooks/publish-canvas/PLAYBOOK.md +1 -1
  107. package/dist/config-BezZTiov.mjs +0 -182
@@ -0,0 +1,212 @@
1
+ /**
2
+ * Spec 31 Part D: the one contract for showing the human a place on a canvas - pure, no DOM, no Node, so the CLI,
3
+ * the dev server, the shell and the Mac app read it with one rule.
4
+ *
5
+ * - **A show target** (`ShowTarget`) is the hash's own targets on one board: `n` node keys, `f` frame ids, `s` scenes,
6
+ * `c` one comment thread. Node keys stay node keys (selecting one copy of a frame never selects every copy), and
7
+ * every value is checked against the hash grammar's characters - never a raw hash, never a URL, never script.
8
+ * - **The link hash** a target travels as: `#/b/<board>` and only the `f`, `s`, `n`, `c` query keys, each once, each
9
+ * value of the allowed characters (`targetFromHash` refuses anything else whole; `hashOfTarget` writes it back).
10
+ * - **A deep link** into the Mac app: `marver://open?ws=<folder>&to=<hash>[&port=<p>]`, both values written with
11
+ * `URLSearchParams` (so the hash's own `#`, `?` and `&` are percent-encoded inside `to`), 2 KB at most. `ws` is the
12
+ * canvas's folder (the app realpaths it and binds it to a running canvas); `port` is a hint the app uses only when
13
+ * that port's canvas has the same folder; a `to` that is not the grammar is dropped (the canvas opens on its default
14
+ * board), never the link.
15
+ */
16
+
17
+ export const DEEP_LINK_SCHEME = 'marver'
18
+ /** The longest deep link either side takes. */
19
+ export const DEEP_LINK_MAX = 2048
20
+ /** The most values one key carries. */
21
+ export const TARGET_LIST_MAX = 64
22
+
23
+ export interface ShowTarget {
24
+ board: string
25
+ /** node keys: exactly those nodes */
26
+ n?: string[]
27
+ /** frame ids: every node showing them */
28
+ f?: string[]
29
+ /** scenes: every frame of them */
30
+ s?: string[]
31
+ /** one comment thread, opened */
32
+ c?: string
33
+ }
34
+
35
+ /** The board-name grammar (shared/board-tree.ts BOARD_NAME, bounded) and the Not on a board view. */
36
+ const BOARD = /^[a-z0-9][a-z0-9-]{0,63}$/
37
+ export const UNPLACED_BOARD = '~unplaced'
38
+ const FRAME = /^[\w./-]{1,200}$/
39
+ const SCENE = /^[\w.-]{1,120}$/
40
+ /** a node key is the shell's: `<frame id>@<width>`, or a board file's own (`n-one`) */
41
+ const NODE = /^[\w./@:-]{1,200}$/
42
+ const THREAD = /^[\w-]{1,128}$/
43
+
44
+ const okBoard = (b: unknown): b is string => typeof b === 'string' && (BOARD.test(b) || b === UNPLACED_BOARD)
45
+ const okIn = (re: RegExp) => (v: unknown): v is string => typeof v === 'string' && re.test(v) && !v.includes('..')
46
+ const okFrame = okIn(FRAME), okScene = okIn(SCENE), okNode = okIn(NODE), okThread = okIn(THREAD)
47
+ const KEYS = { n: okNode, f: okFrame, s: okScene } as const
48
+
49
+ /**
50
+ * A show target off the wire (pure): `board` a board name, `n`/`f`/`s` arrays of their grammar's values (at most
51
+ * `TARGET_LIST_MAX`, de-duplicated, empty ones left out), `c` a thread id. Unknown fields are stripped; a known one of
52
+ * the wrong type or any value off its grammar refuses the whole (null).
53
+ */
54
+ export function checkShowTarget(v: unknown): ShowTarget | null {
55
+ if (!v || typeof v !== 'object' || Array.isArray(v)) return null
56
+ const r = v as Record<string, unknown>
57
+ if (!okBoard(r.board)) return null
58
+ const out: ShowTarget = { board: r.board }
59
+ for (const k of ['n', 'f', 's'] as const) {
60
+ if (r[k] === undefined) continue
61
+ const list = r[k]
62
+ if (!Array.isArray(list) || list.length > TARGET_LIST_MAX || !list.every(KEYS[k])) return null
63
+ const uniq = [...new Set(list as string[])]
64
+ if (uniq.length) out[k] = uniq
65
+ }
66
+ if (r.c !== undefined) {
67
+ if (!okThread(r.c)) return null
68
+ out.c = r.c
69
+ }
70
+ return out
71
+ }
72
+
73
+ /**
74
+ * The link hash's target (pure): `#/b/<board>` with only `f`, `s`, `n`, `c`, each at most once, every value of its
75
+ * grammar; anything else - another route, another key, a repeated key, a bad value, more than 2 KB - is null.
76
+ */
77
+ export function targetFromHash(hash: unknown): ShowTarget | null {
78
+ if (typeof hash !== 'string' || hash.length > DEEP_LINK_MAX) return null
79
+ const m = /^#\/b\/([^?#/]+)(?:\?([^#]*))?$/.exec(hash)
80
+ if (!m) return null
81
+ let board: string
82
+ try { board = decodeURIComponent(m[1]!) } catch { return null }
83
+ if (!okBoard(board)) return null
84
+ const raw: Record<string, unknown> = { board }
85
+ if (m[2] !== undefined && m[2] !== '') {
86
+ let params: URLSearchParams
87
+ try { params = new URLSearchParams(m[2]) } catch { return null }
88
+ const seen = new Set<string>()
89
+ for (const [k, v] of params) {
90
+ if (seen.has(k) || !['n', 'f', 's', 'c'].includes(k)) return null
91
+ seen.add(k)
92
+ if (k === 'c') raw.c = v
93
+ else raw[k] = v.split(',').map((x) => x.trim()).filter(Boolean)
94
+ }
95
+ }
96
+ return checkShowTarget(raw)
97
+ }
98
+
99
+ /** The target as the link hash (pure): the board, then `n`, `f`, `s`, `c` - every value already of URL-safe characters. */
100
+ export function hashOfTarget(t: ShowTarget): string {
101
+ const q = [
102
+ t.n?.length ? `n=${t.n.join(',')}` : '',
103
+ t.f?.length ? `f=${t.f.join(',')}` : '',
104
+ t.s?.length ? `s=${t.s.join(',')}` : '',
105
+ t.c ? `c=${t.c}` : '',
106
+ ].filter(Boolean).join('&')
107
+ return `#/b/${t.board}${q ? `?${q}` : ''}`
108
+ }
109
+
110
+ export interface DeepLink {
111
+ /** the canvas's folder, as the link wrote it (absolute; the app realpaths it) */
112
+ ws: string
113
+ /** the place, checked; null when the link named none or one off the grammar (the canvas's default board) */
114
+ to: ShowTarget | null
115
+ /** a hint: used only when that port's canvas has the same folder */
116
+ port?: number
117
+ }
118
+
119
+ const CONTROL = /[\u0000-\u001f\u007f]/
120
+
121
+ /** `marver://open?ws=<folder>&to=<hash>[&port=<p>]`, written with URLSearchParams; null past 2 KB or with a bad folder. */
122
+ export function buildDeepLink(o: { ws: string; to?: string; port?: number }): string | null {
123
+ if (!o.ws.startsWith('/') || CONTROL.test(o.ws)) return null
124
+ const p = new URLSearchParams({ ws: o.ws })
125
+ if (o.to) p.set('to', o.to)
126
+ if (o.port !== undefined && Number.isInteger(o.port) && o.port > 0 && o.port < 65536) p.set('port', String(o.port))
127
+ const link = `${DEEP_LINK_SCHEME}://open?${p}`
128
+ return link.length <= DEEP_LINK_MAX ? link : null
129
+ }
130
+
131
+ /**
132
+ * A deep link as the app hears it (pure): `marver://open` and nothing else on its path, at most 2 KB, only `ws`, `to`
133
+ * and `port` (each once), `ws` an absolute path with no control character (1 KB at most). A `to` off the grammar is
134
+ * dropped to null; a `port` that is not a port is ignored. Anything else is null: nothing opens.
135
+ */
136
+ export function parseDeepLink(raw: unknown): DeepLink | null {
137
+ if (typeof raw !== 'string' || raw.length > DEEP_LINK_MAX) return null
138
+ let u: URL
139
+ try { u = new URL(raw) } catch { return null }
140
+ if (u.protocol !== `${DEEP_LINK_SCHEME}:` || u.host !== 'open' || (u.pathname !== '' && u.pathname !== '/') || u.username || u.password || u.hash) return null
141
+ const seen = new Set<string>()
142
+ for (const k of u.searchParams.keys()) {
143
+ if (seen.has(k) || !['ws', 'to', 'port'].includes(k)) return null
144
+ seen.add(k)
145
+ }
146
+ const ws = u.searchParams.get('ws')
147
+ if (!ws || !ws.startsWith('/') || ws.length > 1024 || CONTROL.test(ws)) return null
148
+ const to = u.searchParams.has('to') ? targetFromHash(u.searchParams.get('to')) : null
149
+ const ps = u.searchParams.get('port')
150
+ const port = ps !== null && /^\d{1,5}$/.test(ps) && Number(ps) > 0 && Number(ps) < 65536 ? Number(ps) : undefined
151
+ return { ws, to, ...(port !== undefined ? { port } : {}) }
152
+ }
153
+
154
+ /** The first `marver://` argument of a command line (a second instance's argv), or null. */
155
+ export function deepLinkArg(argv: readonly unknown[]): string | null {
156
+ for (const a of argv) if (typeof a === 'string' && a.toLowerCase().startsWith(`${DEEP_LINK_SCHEME}://`)) return a
157
+ return null
158
+ }
159
+
160
+ /** Strictly newer x.y.z (pure): anything not three numbers compares false. */
161
+ export function newerVersion(a: unknown, b: unknown): boolean {
162
+ if (typeof a !== 'string' || typeof b !== 'string') return false
163
+ const pa = /^(\d+)\.(\d+)\.(\d+)$/.exec(a), pb = /^(\d+)\.(\d+)\.(\d+)$/.exec(b)
164
+ if (!pa || !pb) return false
165
+ for (let i = 1; i <= 3; i++) {
166
+ const x = Number(pa[i]), y = Number(pb[i])
167
+ if (x !== y) return x > y
168
+ }
169
+ return false
170
+ }
171
+
172
+ // ---- app-live.json: knowing when the app is in use (Part D2) ---------------------------------------------------
173
+
174
+ /** `<MARVER_HOME>/state/app-live.json`: the Mac app's word that it runs, rewritten every `APP_LIVE_EVERY_MS`. */
175
+ export const APP_LIVE_FILE = 'app-live.json'
176
+ export const APP_LIVE_EVERY_MS = 30_000
177
+ /** Older than this, the file is stale: the app is not in use (it quit without removing it, it hangs). */
178
+ export const APP_LIVE_FRESH_MS = 90_000
179
+
180
+ export interface AppLiveFile {
181
+ v: 1
182
+ pid: number
183
+ version: string
184
+ /** 1 when this app takes `marver://` links (an app that registered the scheme); absent otherwise */
185
+ scheme?: 1
186
+ /** when it was written, ms */
187
+ at: number
188
+ /** the real folders of the canvases open in its tabs */
189
+ workspaces: string[]
190
+ }
191
+
192
+ /** The file's shape (pure), or null. */
193
+ export function checkAppLive(v: unknown): AppLiveFile | null {
194
+ const r = v as Partial<AppLiveFile> | null
195
+ if (!r || typeof r !== 'object' || r.v !== 1) return null
196
+ if (!Number.isInteger(r.pid) || (r.pid as number) < 1 || typeof r.version !== 'string' || r.version.length > 32) return null
197
+ if (typeof r.at !== 'number' || !Number.isFinite(r.at)) return null
198
+ if (!Array.isArray(r.workspaces) || r.workspaces.length > 256 || !r.workspaces.every((w) => typeof w === 'string' && w.startsWith('/') && w.length <= 4096)) return null
199
+ return { v: 1, pid: r.pid as number, version: r.version, at: r.at, workspaces: [...r.workspaces], ...(r.scheme === 1 ? { scheme: 1 as const } : {}) }
200
+ }
201
+
202
+ /**
203
+ * Whether `marver link` gives the app's link for the canvas in `root` (pure): the file names a pid that runs, was
204
+ * written under 90 s ago (a stamp from the future is stale too), takes the scheme, and has this canvas's folder open.
205
+ * Anything else - no file, an older app, a stale file, the canvas not open in a tab - is the localhost link.
206
+ */
207
+ export function appTakesLink(file: AppLiveFile | null, root: string, now: number, alive: (pid: number) => boolean): boolean {
208
+ if (!file || file.scheme !== 1) return false
209
+ if (file.at > now + 5_000 || now - file.at > APP_LIVE_FRESH_MS) return false
210
+ if (!file.workspaces.includes(root)) return false
211
+ return alive(file.pid)
212
+ }
@@ -0,0 +1,89 @@
1
+ /**
2
+ * Your own breakpoints (spec 31 Part F): what a device shows as - its glyph and its label. Pure, shared by the
3
+ * server (which resolves design/config.ts's `viewports.<name>.icon` and `.label` once, at load) and the shell (which
4
+ * falls back to the same rules for a device name it has no resolved look for, e.g. a Jam step recorded earlier).
5
+ */
6
+
7
+ /** The built-in device glyphs, as `viewports.<name>.icon` may name them (a `-landscape` suffix rotates one). */
8
+ export const DEVICE_GLYPHS = ['mobile', 'tablet', 'laptop', 'monitor', 'tv', 'watch', 'desktop', 'ereader'] as const
9
+ export type DeviceGlyph = typeof DEVICE_GLYPHS[number]
10
+
11
+ /** How a device shows: its label, and a built-in glyph (null: the generic devices glyph) turned a quarter for a
12
+ * landscape device - or `mask`, a sanitized SVG as a `data:image/svg+xml;base64,` URI drawn as a CSS mask in the
13
+ * ink (never inline DOM). */
14
+ export interface DeviceLook { label: string; glyph: DeviceGlyph | null; rotate: boolean; mask?: string }
15
+
16
+ /** The longest label a device carries. */
17
+ export const DEVICE_LABEL_MAX = 40
18
+
19
+ const words = (name: string): string[] => name.split(/[^A-Za-z0-9]+/).filter(Boolean)
20
+ const tokens = (name: string): string[] => words(name).map((w) => w.toLowerCase())
21
+
22
+ /** A `-landscape` device: the name says so (a word of its own). */
23
+ export const isLandscape = (name: string): boolean => tokens(name).includes('landscape')
24
+
25
+ /** The glyph a device's NAME suggests, or null (the generic devices glyph). Class words first (`pixel-tablet` is a
26
+ * tablet), then the brands. */
27
+ export function glyphFromName(name: string): DeviceGlyph | null {
28
+ const t = tokens(name)
29
+ const has = (...w: string[]) => t.some((x) => w.includes(x))
30
+ const starts = (p: string) => t.some((x) => x.startsWith(p))
31
+ // the class words: what a device IS beats whose it is
32
+ if (has('tablet')) return 'tablet'
33
+ if (has('laptop')) return 'laptop'
34
+ if (has('phone', 'mobile', 'smartphone')) return 'mobile'
35
+ if (has('monitor', 'desktop')) return 'monitor'
36
+ if (has('tv')) return 'tv'
37
+ if (has('watch')) return 'watch'
38
+ if (has('ereader')) return 'ereader'
39
+ // the brands and the models
40
+ if (starts('iphone') || has('android', 'pixel')) return 'mobile'
41
+ if (starts('ipad') || has('boox', 'kindle')) return 'tablet'
42
+ if (starts('macbook')) return 'laptop'
43
+ if (has('imac', 'studio')) return 'monitor'
44
+ return null
45
+ }
46
+
47
+ /** Brand casing, by word: "ipad" -> "iPad", "tv" -> "TV". */
48
+ const BRAND: Record<string, string> = {
49
+ iphone: 'iPhone', ipad: 'iPad', imac: 'iMac', ipod: 'iPod', macbook: 'MacBook', mac: 'Mac', ios: 'iOS', ipados: 'iPadOS',
50
+ macos: 'macOS', watchos: 'watchOS', tvos: 'tvOS', visionos: 'visionOS', tv: 'TV', appletv: 'Apple TV', android: 'Android', pixel: 'Pixel',
51
+ galaxy: 'Galaxy', samsung: 'Samsung', kindle: 'Kindle', boox: 'Boox', kobo: 'Kobo', remarkable: 'reMarkable', surface: 'Surface',
52
+ chromebook: 'Chromebook', apple: 'Apple', google: 'Google', oneplus: 'OnePlus', xl: 'XL', hd: 'HD', uhd: 'UHD', fhd: 'FHD',
53
+ qhd: 'QHD', '4k': '4K', '5k': '5K', '6k': '6K', '8k': '8K', xdr: 'XDR', oled: 'OLED', se: 'SE', xr: 'XR', xs: 'XS', ui: 'UI',
54
+ }
55
+ /** A model's suffix words, capitalised after a brand: "iphone-15-pro-max" -> "iPhone 15 Pro Max". */
56
+ const MODEL = new Set(['pro', 'max', 'plus', 'mini', 'air', 'ultra', 'fold', 'flip', 'lite', 'studio', 'display', 'note'])
57
+ /** Brands that start a model name, so the words after them are its model words. */
58
+ const BRANDED = new Set(['iphone', 'ipad', 'imac', 'ipod', 'macbook', 'mac', 'pixel', 'galaxy', 'kindle', 'boox', 'kobo', 'remarkable', 'surface', 'chromebook', 'apple', 'google', 'samsung', 'oneplus', 'studio'])
59
+
60
+ /** A device's label from its NAME: the words humanized, brand casing kept ("ipad-landscape" -> "iPad landscape",
61
+ * "boox-full" -> "Boox full", "iphone-15-pro" -> "iPhone 15 Pro"). The first word starts capitalised, the rest stay
62
+ * as written; a word already carrying capitals keeps them ("myDevice" stays "myDevice"). */
63
+ export function labelFromName(name: string): string {
64
+ const ws = words(name)
65
+ if (!ws.length) return name
66
+ let branded = false
67
+ return ws.map((w, i) => {
68
+ const low = w.toLowerCase()
69
+ // a brand word with a model number glued on: "iphone15" -> "iPhone15", "ipad13" -> "iPad13"
70
+ const glued = /^([a-z]+)(\d+)$/.exec(low)
71
+ const brand = BRAND[low] ?? (glued && BRANDED.has(glued[1]) && BRAND[glued[1]] ? BRAND[glued[1]] + glued[2] : undefined)
72
+ const isBrand = BRANDED.has(low) || (!!glued && BRANDED.has(glued[1]))
73
+ const out = brand ?? (/[A-Z]/.test(w) ? w
74
+ : branded && MODEL.has(low) ? low[0].toUpperCase() + low.slice(1)
75
+ : i === 0 ? low[0].toUpperCase() + low.slice(1)
76
+ : low)
77
+ if (isBrand) branded = true
78
+ return out
79
+ }).join(' ')
80
+ }
81
+
82
+ /** A built-in glyph as `viewports.<name>.icon` names it, with its rotation - or null when the value is no glyph. */
83
+ export function parseGlyph(v: string): { glyph: DeviceGlyph; rotate: boolean } | null {
84
+ const m = /^([a-z]+)(-landscape)?$/.exec(v)
85
+ return m && (DEVICE_GLYPHS as readonly string[]).includes(m[1]) ? { glyph: m[1] as DeviceGlyph, rotate: !!m[2] } : null
86
+ }
87
+
88
+ /** A device's look from its name alone - the shell's fallback, and the server's for a device with no `icon`/`label`. */
89
+ export const lookFromName = (name: string): DeviceLook => ({ label: labelFromName(name), glyph: glyphFromName(name), rotate: isLandscape(name) })
@@ -5,7 +5,8 @@
5
5
  */
6
6
 
7
7
  // 'reanchor' (Live Jam): re-pin a thread to a new element after the agent moved it.
8
- export type EventType = 'create' | 'reply' | 'edit' | 'resolve' | 'reopen' | 'react' | 'profile' | 'reanchor'
8
+ // 'delete' (0.31, spec 31 C.4): a terminal tombstone on one message - its author's only.
9
+ export type EventType = 'create' | 'reply' | 'edit' | 'resolve' | 'reopen' | 'react' | 'profile' | 'reanchor' | 'delete'
9
10
 
10
11
  // Live Jam: provenance stamped by the daemon on agent-authored events (who orchestrated the change).
11
12
  export interface AgentMeta { devUser?: string; harness?: string; model?: string; effort?: string; /** who ran it (spec 29b): the owner's session, a copy of it, or a fresh agent */ runner?: 'session' | 'fork' | 'fresh' }
@@ -49,6 +50,8 @@ export interface CommentEvent {
49
50
  capture?: string
50
51
  facts?: string
51
52
  origin?: string // server-stamped 'local' on dev-owner writes; the daemon's owner-trigger key
53
+ /** resolve and reopen events (0.31, spec 31 B.3): the resolve-all operation that wrote it - what its Undo matches */
54
+ op?: string
52
55
  }
53
56
 
54
57
  export interface Thread {
@@ -66,7 +69,11 @@ export interface Thread {
66
69
  asks?: boolean
67
70
  capture?: string // a capture's comment (0.26)
68
71
  facts?: string
69
- replies: { id: string; author?: CommentEvent['author']; body?: string; ts: number; agent?: boolean; agentMeta?: AgentMeta; mentions?: Mention[]; asks?: boolean; alsoChanged?: string[] }[]
72
+ /** the first comment was deleted (0.31): its replies stay under a "Comment deleted" placeholder - no body, author or mentions */
73
+ deleted?: true
74
+ /** when its words were last edited (0.31: "edited" is shown) - an edit that changes only a flag does not count */
75
+ edited?: number
76
+ replies: { id: string; author?: CommentEvent['author']; body?: string; ts: number; agent?: boolean; agentMeta?: AgentMeta; mentions?: Mention[]; asks?: boolean; alsoChanged?: string[]; edited?: number }[]
70
77
  reactions: Record<string, string[]> // emoji -> author emails (toggle semantics)
71
78
  }
72
79
 
@@ -82,10 +89,31 @@ export function diffEvents(mine: CommentEvent[], theirIds: Iterable<string>): Co
82
89
  return mine.filter((e) => !have.has(e.id))
83
90
  }
84
91
 
92
+ /** The messages (create or reply comment ids) a log's tombstones name (spec 31 C.4): terminal, whatever came
93
+ * before or after them. Every reader that turns a request into agent input filters by it, per message. */
94
+ export function deletedMessages(events: readonly CommentEvent[]): Set<string> {
95
+ const out = new Set<string>()
96
+ for (const e of events) if (e.type === 'delete' && typeof e.commentId === 'string' && e.commentId) out.add(e.commentId)
97
+ return out
98
+ }
99
+
100
+ /** An event as a browser may see it (spec 31 C.4): a create, reply or edit of a deleted message carries no words or
101
+ * mentions - the log keeps them (sync is by id), no transport to a page does. `gone`: deletedMessages of the log. */
102
+ export const withoutDeletedWords = (e: CommentEvent, gone: ReadonlySet<string>): CommentEvent =>
103
+ gone.size && (e.type === 'create' || e.type === 'reply' || e.type === 'edit') && !!e.commentId && gone.has(e.commentId) ? { ...e, body: '', mentions: undefined } : e
104
+
105
+ /** The copy a published page keeps of what it just sent (spec 31 C.2): its author wears the viewer's own opaque id, as
106
+ * the server's projection of it will - the echo is a duplicate by id and dropped, so without it a message just written
107
+ * would not be "mine" (no Edit, no Delete) until a reload. Never sent: the server assigns ids. */
108
+ export const asSentBy = (events: CommentEvent[], myId: string | undefined): CommentEvent[] =>
109
+ !myId ? events : events.map((e) => (e.author && !e.author.id ? { ...e, author: { ...e.author, id: myId } } : e))
110
+
85
111
  /** Replay a board's events into current thread state. Deterministic: replay order is
86
112
  * (ts, id) so two stores holding the same event SET always derive the same state.
87
113
  * TWO passes - creates first, then everything else - so a reply whose author's clock
88
- * ran ahead of the creator's still lands instead of being dropped forever. */
114
+ * ran ahead of the creator's still lands instead of being dropped forever. Deletes (0.31)
115
+ * apply after both, whatever their time: a deleted reply is gone; a deleted first comment
116
+ * keeps its surviving replies under a placeholder, and with none the thread is gone. */
89
117
  export function replay(events: CommentEvent[]): Thread[] {
90
118
  const ordered = [...events].sort((a, b) => a.ts - b.ts || (a.id < b.id ? -1 : 1))
91
119
  const threads = new Map<string, Thread>()
@@ -112,7 +140,7 @@ export function replay(events: CommentEvent[]): Thread[] {
112
140
  if (!ev.commentId || (ev.body === undefined && ev.asks === undefined && ev.alsoChanged === undefined)) break
113
141
  const m = threads.get(ev.commentId) ?? [...threads.values()].flatMap((th) => th.replies).find((r) => r.id === ev.commentId)
114
142
  if (!m) break
115
- if (ev.body !== undefined) m.body = ev.body
143
+ if (ev.body !== undefined) { if (ev.body !== m.body) m.edited = ev.ts; m.body = ev.body }
116
144
  if (ev.asks !== undefined) m.asks = ev.asks
117
145
  if (ev.alsoChanged !== undefined && !('replies' in m)) (m as { alsoChanged?: string[] }).alsoChanged = ev.alsoChanged // a reply's
118
146
  break
@@ -152,7 +180,22 @@ export function replay(events: CommentEvent[]): Thread[] {
152
180
  break
153
181
  }
154
182
  // 'profile' events update author snapshots at write time on the client - replay ignores them
183
+ // 'delete' events are applied below, after everything else
184
+ }
185
+ }
186
+ const gone = deletedMessages(ordered)
187
+ if (!gone.size) return [...threads.values()]
188
+ const out: Thread[] = []
189
+ for (const t of threads.values()) {
190
+ t.replies = t.replies.filter((r) => !gone.has(r.id))
191
+ if (gone.has(t.id)) {
192
+ if (!t.replies.length) continue
193
+ // the placeholder carries nothing of what was said, nor who said it
194
+ t.deleted = true
195
+ t.body = undefined; t.author = undefined; t.mentions = undefined; t.asks = undefined; t.edited = undefined
196
+ delete t.capture; delete t.facts
155
197
  }
198
+ out.push(t)
156
199
  }
157
- return [...threads.values()]
200
+ return out
158
201
  }
@@ -0,0 +1,98 @@
1
+ /**
2
+ * The export plan (spec 31 Part A #2): which frames a board prints, in which order, at which size and theme. One
3
+ * definition, read by the PDF (src/server/pdf.ts) and by Play (src/client/shell/Play.tsx), so a deck's pages and the
4
+ * stage never disagree.
5
+ *
6
+ * - a *slides* board (it plays as slides: its publish policy says `type: slides` or `open: slides`) prints its deck:
7
+ * slide frames in reading order (y, then x), deduped - `deckOrder`, the order slides mode plays;
8
+ * - any other board prints its nodes in the board's own order (Play's order), deduped, html frames included (Play
9
+ * cannot mount them on its stage; the PDF prints them from their own document);
10
+ * - a page is the size the stage shows: a `slide: true` frame's stage (`slideSize`) on any board, else the device Play
11
+ * picks for the node - the viewport whose width is the node's, else the frame's declared viewport, else the first -
12
+ * at that viewport's height;
13
+ * - its theme: the export's own when one is asked, else the node's, else the frame's, else light;
14
+ * - a node whose frame the manifest does not list is skipped, and named.
15
+ *
16
+ * Pure and dependency-free (beyond the two shared rules it composes), so the server, the shell and the tests import it.
17
+ */
18
+ import { deckOrder, type OrderFrame, type OrderNode } from '../client/shell/play-order.ts'
19
+ import { slideSize } from '../client/const.ts'
20
+
21
+ export type Viewports = Record<string, { width: number; height: number }>
22
+ export interface PlanFrame extends OrderFrame { viewport?: string; theme?: string; title?: string; file?: string }
23
+ export interface PlanNode extends OrderNode {
24
+ /** the node's width on the board, when it has one - names the device Play shows it at */
25
+ w?: number
26
+ /** the node's own theme, as the person pinned it (`themeUser`), when there is one */
27
+ theme?: string
28
+ }
29
+ export interface PlanPage {
30
+ frame: string
31
+ kind: 'tsx' | 'html'
32
+ width: number
33
+ height: number
34
+ theme: string
35
+ /** the frame's title, else its id's last part made readable - a bookmark's name */
36
+ title: string
37
+ /** the viewport the page is printed at, for a non-slide frame */
38
+ device?: string
39
+ }
40
+ export interface Plan { pages: PlanPage[]; skipped: { frame: string; why: 'missing' | 'not a slide' }[] }
41
+
42
+ /** The device Play shows a node at (spec 31 #2): the viewport whose width is the node's, else the frame's declared
43
+ * viewport, else the first. Undefined only when the project has no viewport at all. */
44
+ export function presentDevice(node: { w?: number } | undefined, frame: { viewport?: string } | undefined, viewports: Viewports): string | undefined {
45
+ const names = Object.keys(viewports)
46
+ return (node?.w !== undefined ? names.find((v) => viewports[v].width === node.w) : undefined)
47
+ ?? (frame?.viewport && viewports[frame.viewport] ? frame.viewport : names[0])
48
+ }
49
+
50
+ /** A board's frames in its own order, deduped, its missing ones skipped - Play's list (`html: false`, what its stage can
51
+ * mount) and the PDF's (`html: true`). */
52
+ export function boardOrder<N extends { frame: string; missing?: boolean }>(nodes: N[], frameOf: (n: N) => OrderFrame | undefined, o: { html: boolean }): N[] {
53
+ const seen = new Set<string>()
54
+ const out: N[] = []
55
+ for (const n of nodes) {
56
+ if (n.missing || seen.has(n.frame)) continue
57
+ const f = frameOf(n)
58
+ if (!f || (!o.html && f.kind !== 'tsx')) continue
59
+ seen.add(n.frame)
60
+ out.push(n)
61
+ }
62
+ return out
63
+ }
64
+
65
+ /** A frame's title, else its id's last part with spaces for dashes (as Play's pill names a frame). */
66
+ export const titleOf = (f: { id: string; title?: string }): string => f.title?.trim() || (f.id.split('/').pop() ?? f.id).replace(/-/g, ' ')
67
+
68
+ /** The plan for one board (spec 31 #2). `theme` is the export's own (`--theme`), when one was asked. */
69
+ export function exportPlan(o: { slides: boolean; nodes: PlanNode[]; frames: PlanFrame[]; viewports: Viewports; theme?: string }): Plan {
70
+ const byId = new Map(o.frames.map((f) => [f.id, f]))
71
+ const skipped: Plan['skipped'] = []
72
+ const seenMissing = new Set<string>()
73
+ for (const n of o.nodes) if (!byId.has(n.frame) && !seenMissing.has(n.frame)) { seenMissing.add(n.frame); skipped.push({ frame: n.frame, why: 'missing' }) }
74
+ const page = (f: PlanFrame, node: PlanNode | undefined): PlanPage | null => {
75
+ const theme = o.theme ?? node?.theme ?? f.theme ?? 'light'
76
+ const sl = slideSize(f, o.viewports)
77
+ if (sl) return { frame: f.id, kind: f.kind, width: sl.width, height: sl.height, theme, title: titleOf(f) }
78
+ const device = presentDevice(node, f, o.viewports)
79
+ const vp = device ? o.viewports[device] : undefined
80
+ if (!vp) return null
81
+ return { frame: f.id, kind: f.kind, width: vp.width, height: vp.height, theme, title: titleOf(f), device }
82
+ }
83
+ const pages: PlanPage[] = []
84
+ if (o.slides) {
85
+ const { deck, excluded } = deckOrder(o.nodes.map((n) => ({ ...n, missing: n.missing || !byId.has(n.frame) })), byId)
86
+ for (const id of excluded) skipped.push({ frame: id, why: 'not a slide' })
87
+ for (const id of deck) {
88
+ const p = page(byId.get(id)!, o.nodes.find((n) => n.frame === id))
89
+ if (p) pages.push(p)
90
+ }
91
+ } else {
92
+ for (const n of boardOrder(o.nodes, (x) => byId.get(x.frame), { html: true })) {
93
+ const p = page(byId.get(n.frame)!, n)
94
+ if (p) pages.push(p)
95
+ }
96
+ }
97
+ return { pages, skipped }
98
+ }
@@ -34,7 +34,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
34
34
  | Phase | When | Read |
35
35
  |---|---|---|
36
36
  | Welcome | the human's FIRST session, or "what is this?" | instructions/welcome.md |
37
- | Configure | first session in a repo, or frames render unstyled | instructions/configure.md |
37
+ | Configure | first session in a repo, frames render unstyled, or the canvas does not wear the product's name and logo: `marver dev`'s boot line says "this canvas still shows ...", `name` in design/config.ts is missing or still init's guess from package.json ("My repo" for `my-repo`), or the logo is the Marver mark - do step 6, identity | instructions/configure.md |
38
38
  | Discover | any new surface, feature, or flow | instructions/discover.md |
39
39
  | Shape | thinking a feature through on canvas (specs, diagrams, mood boards) - never the first session | instructions/shape.md |
40
40
  | Wireframe | new work: nail structure + copy in throwaway lo-fi | instructions/wireframe.md |
@@ -44,7 +44,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
44
44
  | Review | before presenting anything | instructions/review.md |
45
45
  | Boards | creating a board, choosing what ships | instructions/boards.md |
46
46
  | Context | any question about what the product does or what is live; a behaviour change; a deploy; no `context/` yet | instructions/context.md |
47
- | Slides | a deck is asked for, or `slide: true` frames exist | instructions/slides.md + design/slides.md |
47
+ | Slides | a deck is asked for; a PDF of a deck or of any board, a flow too (`npx marver pdf <board>`, then give back the path it prints); or `slide: true` frames exist | instructions/slides.md + design/slides.md |
48
48
  | Publish | deploying the canvas: gate, volume, accounts, invites | instructions/publish.md |
49
49
  | Live Jam | responding to an `@marver` comment (a spawned job), or a "Live Jam: ... new request" message (below) - run `npx marver jam next`; on by default - confirm it names YOUR tool | instructions/jam.md |
50
50
 
@@ -160,13 +160,35 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
160
160
 
161
161
  - **Every reply in which you created or changed frames ends with their canvas link**, on its
162
162
  own line: the `on the canvas:` line `work done` printed, or `npx marver link <scene/frame |
163
- scene ...>` for any set. Each opens a board they sit on (one link per board when they sit
164
- on several) with them selected and in view -
165
- the human finds the work at once on a board of fifty frames. Never a full-screen focus link
166
- (`#/f/...`) unless they ask for full screen. `npx marver ls` lists the canvases running on
167
- this Mac and their links; none for this folder? End by asking the person to run
168
- `npx marver dev` in their own terminal (or start it detached: "Keeping the canvas up") - the
169
- link carries its port.
163
+ scene ...>` for any set (`checkout/cart`, or `checkout` for a whole scene). Each opens a board
164
+ they sit on (one link per board when they sit on several; `--board <b>` picks one) with them
165
+ selected and in view - the human finds the work at once on a board of fifty frames. **Give
166
+ exactly what those commands print** - a `marver://...` link (the Mac app has this canvas
167
+ open) or a localhost one - never a link you wrote yourself or rewrote. `link` reads a bare
168
+ name as a scene (`checkout`), never as a board: for a whole board, link the scenes it shows
169
+ with `--board <board>` (each node's `frame` in design/boards/<board>.json starts with its
170
+ scene; an `auto: true` board shows every scene), or its frames when it shows only some of a
171
+ scene's. Never a full-screen focus link unless they ask for full screen - then
172
+ `#/f/<scene/frame>` after the localhost link `npx marver ls` prints, the one link you write
173
+ yourself. **`link` and `show` need `marver dev` running for this folder** - the link carries
174
+ its port. `npx marver ls` lists the canvases running on this Mac and their links; none for
175
+ this folder? End by asking the person to run `npx marver dev` in their own terminal (or start
176
+ it detached: "Keeping the canvas up").
177
+ - **Show, only when they ask.** "Show me", "take me there", "open it for me": run `npx marver
178
+ show <target>` - `checkout/cart` (a frame), `checkout/cart checkout/pay` (several),
179
+ `checkout` (a scene), `launch-plan` (a board, fitted whole). A bare name is a frame or a
180
+ scene first, and a board only when no frame or scene has that name: a board whose name a
181
+ scene also has cannot be shown whole - show the scenes it shows with `--board <board>`, as
182
+ for `link`. `--thread <id>` opens that comment thread there too, with its frame or board
183
+ still named (`show checkout/cart --thread <id>`). Every open tab of this canvas goes
184
+ there, selected and fitted, and the Mac app comes forward. It waits 3 seconds, prints one
185
+ line, then the link:
186
+ - `shown in 2 tabs` - say it is on their screen, and end with the link;
187
+ - `1 tab holds words not yet sent - ...` - they were typing, so that tab did not move: it
188
+ shows "Your agent wants to show you ... · Go". Say so, and give the link;
189
+ - `not shown - no open tab took it ...` or `not shown: ...` - nothing moved: give the link.
190
+ Frames on two boards are refused: show one board at a time (`--board <board>`). Never show on
191
+ your own to hand work back - that is the link, above.
170
192
  - **Answer each comment thread you addressed, in the thread**: `npx marver comments reply
171
193
  <thread> --body "<what changed>"` - one line, no longer than their comment. On a thread
172
194
  the human started it posts as Marver and pings them on the frame. A reply that asks them
@@ -183,7 +205,7 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
183
205
  new --thread <id>` on your own note), never a second note on the same subject. A note in the
184
206
  wrong place: `npx marver comments move <thread> --on "..."`, never a second copy. The chat keeps
185
207
  the summary and can say "question on the form". Never resolve your own notes: the human
186
- resolves them as they review.
208
+ resolves them as they review (one at a time, or all at once - below).
187
209
  - **A plain reply in a Marver thread starts no job - only an `@marver` tag does.** The human
188
210
  answers your notes and questions on the canvas, then tags the threads they want acted on, or
189
211
  says "go through my replies": then run `npx marver marks` - its **answered by you** list is
@@ -201,6 +223,17 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
201
223
  // tv available commented-out). Pick the one the screen is designed for - the human can
202
224
  // flip the whole board to any device (Devices menu; digit keys - 0 restores each
203
225
  // frame's own size, 1..n per configured device) to check responsiveness.
226
+ // Add the product's own devices there too: `"boox-full": { width: 1240, height: 1860 }`.
227
+ // Each shows as its name reads ("ipad-landscape" -> "iPad landscape", the tablet glyph
228
+ // turned) unless it sets `label` (40 chars) and `icon`: a glyph (mobile, tablet, laptop,
229
+ // monitor, tv, watch, desktop, ereader; "-landscape" turns it) or a repo .svg - paths and
230
+ // shapes only (no style, script, href, text), 32 KB at most, drawn in the toolbar's ink:
231
+ // it is a mask, so colours do not matter, only what is painted - `fill`/`stroke` attributes
232
+ // are fine (any colour, or none); a line icon needs fill="none" or its shapes fill solid.
233
+ // An `icon` replaces the name's turn: a landscape device names `tablet-landscape`,
234
+ // not `tablet`. An .svg is never turned - draw it the way the device stands. A bad
235
+ // label or icon falls back to the name's, with one line in `marver dev`'s terminal;
236
+ // both are read when `marver dev` starts (instructions/configure.md, step 6).
204
237
  - States are sibling frames: empty.tsx, filled.tsx, error.tsx, success.tsx.
205
238
  - VERSIONS are sibling frames with letter prefixes, and the canvas understands them:
206
239
  design/scenes/landing/a-terminal.tsx + b-editorial.tsx form a VARIANT GROUP - kept
@@ -261,9 +294,40 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
261
294
  Read it before exploring; `marver dev` keeps it fresh. `npx marver boards` prints the
262
295
  boards part as a tree.
263
296
  - **What the human has not reviewed.** At the start of a session, `npx marver marks`: the frames
264
- waiting on them (your notes and replies they have not resolved - the ones that ask first) and
265
- the frames new since they last looked. When it bears on the work, say so in your first message
297
+ waiting on them (your notes and replies they have not resolved - the ones that ask first), the
298
+ frames new since they last looked, and the open conversations per board. When it bears on the work, say so in your first message
266
299
  ("you have not looked at the checkout frames since I changed them").
300
+ - **The sidebar's marks, as the human names them.** Orange is Marver waiting on them: an
301
+ orange bubble on a frame, scene, board or closed folder counts your open notes and replies
302
+ there (a hollow one on a frame: they answered, and it waits on you - `marks`' answered by
303
+ you list). Blue is new: frames new or changed since they last looked - a blue dot, a blue
304
+ title. A board's status glyph takes the same slot when no question does (Building is blue),
305
+ and a board icon that shimmers blue is an agent at work on it. The human's own threads wear
306
+ no mark. Orange goes as the threads are resolved (resolve-all, below, only on their yes);
307
+ blue goes as they look at the frames, or with "Mark all as seen" in a board, folder or scene
308
+ menu - theirs to click, never yours.
309
+ - **Many open conversations: offer, never decide.** When `npx marver marks` shows more than 10
310
+ open (its `open` line; `--json` has `open.total` and `open.boards`), or the human says the
311
+ badges are noisy, ask - with the count per board it prints ("38 open: launch-plan 22,
312
+ checkout-compare 16 - resolve them?"). A frame on two boards counts on both. Only on a yes, and only for what
313
+ they said yes to: one board is `npx marver comments resolve --all --board <b>`, a folder
314
+ `--folder <f>`, a scene `--scene <s>`, everything `--canvas` (the only scope that also takes
315
+ threads with no frame or on a frame that is gone; `--scene` takes its frames whether or not a board shows them). `--dry-run` counts first. Give them the `--undo` line it
316
+ prints. It never touches what Jam is working on, and the human has the same in every board,
317
+ folder and scene menu ("Resolve all comments") and on the Mac app's tab. Never on your own.
318
+ - **Undo a resolve-all later.** The canvas's Undo notice lasts 10 seconds. After that, each run
319
+ is kept as `design/.local/comment-ops/<op>.json` (its `scope` and `at` say which; skip the
320
+ `.undo.json` files): `npx marver comments resolve --undo <op>` reopens each thread nothing
321
+ happened in since.
322
+ - **Edit and delete are the author's, on the canvas.** People edit and delete their own
323
+ messages there. Marver's notes and replies have no Edit or Delete, for anyone, and the CLI
324
+ edits and deletes nothing. A note of yours that is wrong: correct it in its thread (`comments
325
+ new --thread <id>` on your own note); a misplaced one: `comments move`. Say so in the chat;
326
+ the human resolves it. A person's message only they can change: never post it again reworded.
327
+ - **A deleted comment is gone.** A deleted reply
328
+ disappears; a deleted first comment whose replies stay is listed as "(comment deleted)"
329
+ (`"deleted": true` in `--json`, no body or author). Its words never reach you, in
330
+ `comments list` or in Jam. Never quote one back, and never write one again.
267
331
  - **Performance.** `npx marver perf --loads --json` says what each board load did - time to
268
332
  settled, how many moves and why, the slowest frames, errors. To make a board faster, name
269
333
  the lever, change it, compare the next load. A slow frame's `admittedMs` is when its turn to