@marver-design/marver 0.24.0 → 0.25.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 (80) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/README.md +1 -1
  3. package/dist/anchor-DVV732zR.mjs +33 -0
  4. package/dist/anchor-check-BE5VVN6Q.mjs +135 -0
  5. package/dist/{bake-ZhXq-X9f.mjs → bake-D8byeRzB.mjs} +1 -1
  6. package/dist/{boards-BRLnoTC3.mjs → board-tree-DRioF94d.mjs} +21 -277
  7. package/dist/boards-CGg6piKF.mjs +342 -0
  8. package/dist/{boards-Dv-Ipd8G.mjs → boards-Csxj2WJn.mjs} +23 -9
  9. package/dist/{build-ckcinlWH.mjs → build-BHoWLvSj.mjs} +63 -37
  10. package/dist/cli.mjs +31 -17
  11. package/dist/{collab-mAiNZlDj.mjs → collab-gqNdScUE.mjs} +39 -9
  12. package/dist/{comments-DZyobpxG.mjs → comments-Zoch254k.mjs} +19 -1
  13. package/dist/{comments-Dx1hCVOT.mjs → comments-pTLlhjh4.mjs} +150 -20
  14. package/dist/{config-BUKprFAp.mjs → config-cKgZBRj0.mjs} +1 -1
  15. package/dist/{context-BncTXjLB.mjs → context-D2ugHqwO.mjs} +17 -123
  16. package/dist/{daemon-CQv73-jM.mjs → daemon-Cl8KXGW4.mjs} +146 -64
  17. package/dist/{dev-gv4NS6Fk.mjs → dev-DJdgow47.mjs} +23 -11
  18. package/dist/{events-B3LBn74P.mjs → events-DnK_AnrW.mjs} +13 -15
  19. package/dist/imports-WBSnnHLb.mjs +143 -0
  20. package/dist/{init--3Moc4J7.mjs → init-DO4DhUt_.mjs} +28 -6
  21. package/dist/link-C-qUIuKU.mjs +160 -0
  22. package/dist/{board-status-BZSzc9Hp.mjs → manifest-DnAte_fB.mjs} +537 -13
  23. package/dist/marks-DFuintmJ.mjs +50 -0
  24. package/dist/marks-koRsbHfe.mjs +397 -0
  25. package/dist/{marver-id-gate-B_idGdHm.mjs → marver-id-gate-DGANtVyC.mjs} +2 -2
  26. package/dist/perf-CCisg-ny.mjs +49 -0
  27. package/dist/perf-QJIWtTw1.mjs +68 -0
  28. package/dist/{plugin-Sa08E7wO.mjs → plugin-CTyhjwoJ.mjs} +424 -207
  29. package/dist/{poster-B2QPvKOq.mjs → poster-D0cbV7hi.mjs} +1 -1
  30. package/dist/{profile-CrZohD6g.mjs → profile-Do0nGkXO.mjs} +1 -1
  31. package/dist/{publish-bakes-BJR3huhu.mjs → publish-bakes--l8ot2eQ.mjs} +9 -9
  32. package/dist/{serve-z5qtj_wJ.mjs → serve-wv2QWdxB.mjs} +6 -6
  33. package/dist/{share-BD-wcDQq.mjs → share-ScamJcks.mjs} +1 -1
  34. package/dist/{shot-Cw96h5Kk.mjs → shot-CckrGW-J.mjs} +19 -11
  35. package/dist/{shot-Dh6fV1Lm.mjs → shot-jdO_B6Qw.mjs} +1 -1
  36. package/dist/{summary-C7CAypbB.mjs → summary-CrW88e3q.mjs} +1 -1
  37. package/dist/{sync-DoA1vf4u.mjs → sync-C3035OnJ.mjs} +18 -8
  38. package/dist/{work-CBUfsOOT.mjs → work-CpJn1gwY.mjs} +8 -4
  39. package/dist/{work-ayuL_9Kk.mjs → work-GE88wb_3.mjs} +4 -4
  40. package/docs/boards-and-folders.md +62 -21
  41. package/docs/live-jam.md +10 -5
  42. package/package.json +1 -1
  43. package/src/client/frame-host/bridge.js +2 -1
  44. package/src/client/frame-host/inspect.js +195 -84
  45. package/src/client/frame-host/main.tsx +7 -2
  46. package/src/client/frame-host/registry.ts +5 -5
  47. package/src/client/shell/App.tsx +66 -22
  48. package/src/client/shell/BoardList.tsx +54 -11
  49. package/src/client/shell/Comments.tsx +79 -34
  50. package/src/client/shell/ContextMenu.tsx +5 -2
  51. package/src/client/shell/LockedApp.tsx +45 -12
  52. package/src/client/shell/Play.tsx +35 -34
  53. package/src/client/shell/Toolbar.tsx +3 -1
  54. package/src/client/shell/canvas/Canvas.tsx +1 -1
  55. package/src/client/shell/canvas/FrameNode.tsx +10 -5
  56. package/src/client/shell/canvas/sleep.ts +4 -3
  57. package/src/client/shell/canvas/updates.ts +55 -0
  58. package/src/client/shell/comments-store.ts +48 -19
  59. package/src/client/shell/goto.ts +11 -14
  60. package/src/client/shell/hash.ts +12 -5
  61. package/src/client/shell/icons.tsx +1 -2
  62. package/src/client/shell/legacy-links.ts +67 -0
  63. package/src/client/shell/marks-ui.tsx +17 -19
  64. package/src/client/shell/pin-layout.ts +37 -0
  65. package/src/client/shell/store.ts +312 -92
  66. package/src/client/shell/styles.css +10 -8
  67. package/src/client/stage/main.tsx +19 -2
  68. package/src/shared/anchor.ts +57 -0
  69. package/src/shared/board-tree.ts +27 -10
  70. package/src/shared/events.ts +19 -10
  71. package/src/shared/marks.ts +17 -12
  72. package/templates/AGENTS-embedded.md +34 -15
  73. package/templates/AGENTS-studio.md +34 -15
  74. package/templates/instructions/boards.md +9 -5
  75. package/templates/instructions/iterate.md +20 -10
  76. package/templates/instructions/jam.md +13 -4
  77. package/templates/instructions/publish.md +2 -1
  78. package/templates/instructions/reference/deck-story.md +2 -2
  79. package/dist/link-vXjxMHTG.mjs +0 -132
  80. package/dist/manifest-cyG3kbhk.mjs +0 -528
@@ -962,7 +962,8 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
962
962
  /* the canvas writes --sh-inv (1/zoom) for screen-constant pins; the prototype has no
963
963
  zoom, so neutralise it or the leaked value scales every comment pin by ~12x at overview */
964
964
  .sh-play { --sh-inv: 1 }
965
- .sh-play-comments { position: absolute; inset: 0; z-index: 31; overflow: visible; pointer-events: none }
965
+ .sh-play-comments { position: absolute; inset: 0; z-index: 31; overflow: visible; pointer-events: none;
966
+ --sh-inv: 1 } /* the stage does not zoom: its markers are placed in screen px */
966
967
  .sh-play-comments > * { pointer-events: auto }
967
968
 
968
969
  /* the current variant's name trails the chips at natural width - the chips anchor,
@@ -1016,9 +1017,12 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
1016
1017
  .cm-pin .cm-avatar + .cm-avatar, .cm-stack .cm-avatar + .cm-avatar { margin-left: -8px }
1017
1018
  .cm-pin b, .cm-stack b { padding: 0 8px 0 6px }
1018
1019
 
1019
- /* pin: the teardrop. Bottom-left tail points at the anchored element. */
1020
+ /* pin: the teardrop. Bottom-left tail points at the anchored element. Its face draws inside ONE
1021
+ fixed box (pin-layout.ts MARKER: 80 x 34 screen px), the box markers are placed by - so a reply
1022
+ or a new participant never moves a marker, and two never overlap. */
1020
1023
  .cm-pin { position: absolute; z-index: 30; transform: translate(-2px, -100%) scale(var(--sh-inv, 1));
1021
1024
  transform-origin: bottom left; border-radius: 18px 18px 18px 4px;
1025
+ height: 34px; max-width: 80px; overflow: hidden; white-space: nowrap;
1022
1026
  box-shadow: 0 1px 2px rgba(24,24,27,.18), 0 6px 16px -6px rgba(24,24,27,.35);
1023
1027
  transition: box-shadow .15s, transform .15s }
1024
1028
  .cm-pin:hover { box-shadow: 0 1px 3px rgba(24,24,27,.22), 0 10px 24px -6px rgba(24,24,27,.45) }
@@ -1030,12 +1034,10 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
1030
1034
  outline: 2px solid var(--cm-line, var(--comment)); outline-offset: -1px;
1031
1035
  box-shadow: 0 0 0 4px var(--cm-line-ring, var(--comment-ring)), 0 1px 2px rgba(24,24,27,.18), 0 6px 16px -6px rgba(24,24,27,.35) }
1032
1036
  .cm-pin.orphan { border-style: dashed; opacity: .75 }
1033
- /* the open pin's tail leans TOWARD its card. Default (sharp bottom-left) already reads "left";
1034
- card on the RIGHT mirrors the pin around its anchor - sharp corner bottom-right, box extending
1035
- left+up, so the tail points right at the conversation. */
1036
- .cm-pin.tail-r { border-radius: 18px 18px 4px 18px;
1037
- transform: translate(calc(-100% + 2px), -100%) scale(var(--sh-inv, 1));
1038
- transform-origin: bottom right }
1037
+ /* a marker moved off its point (another sat there first) keeps a thin line up to it - under the
1038
+ markers, never in the way of a click */
1039
+ .cm-lead { position: absolute; z-index: 29; pointer-events: none !important; width: calc(1.5px * var(--sh-inv, 1));
1040
+ transform: translateX(-50%); background: rgba(24,24,27,.45); border-radius: 1px }
1039
1041
 
1040
1042
  /* stack: the frame-corner cluster - everyone across the frame's threads */
1041
1043
  .cm-stack { position: absolute; top: 10px; right: 10px; z-index: 30;
@@ -6,7 +6,7 @@
6
6
  * agents opt into shared-element morphs with plain view-transition-name CSS.
7
7
  *
8
8
  * The shell owns chrome, device sizing, walk order, and the URL; the stage owns data-goto:
9
- * stage -> shell: sh:stage-ready · sh:stage-at {at} · sh:stage-exit · sh:stage-error
9
+ * stage -> shell: sh:stage-ready · sh:stage-shown {at, epoch, doc} · sh:stage-at {at} · sh:stage-exit · sh:stage-error
10
10
  * sh:stage-key {key, code} (forwarded shortcuts)
11
11
  * shell -> stage: sh:stage-set {at} (history / walk / restart) · sh:set-theme
12
12
  */
@@ -22,6 +22,10 @@ const params = new URLSearchParams(location.search)
22
22
  // token systems, .dark for class-keyed ones (Tailwind/shadcn). Missing the class made
23
23
  // play render class-keyed apps light while the canvas showed them dark.
24
24
  const bootTheme = params.get('theme') ?? 'light'
25
+ /** The revisions this stage document was served with (spec 26): { epoch, doc: { frame: rev } }. */
26
+ const stamps: { epoch: string; doc: Record<string, number> } | null = (() => {
27
+ try { return JSON.parse(document.querySelector('meta[name="mv-doc"]')?.getAttribute('content') ?? 'null') } catch { return null }
28
+ })()
25
29
  // slides mode: the shell says so in the URL; the stage stamps the attributes every slide
26
30
  // can key its own motion off - data-sl-play (the deck is playing) on <html> for the whole
27
31
  // show, data-sl-entered once each swap settles, data-mv-slide while the mounted frame is a
@@ -117,6 +121,19 @@ class Boundary extends Component<{ resetKey: string; children?: ReactNode }, { e
117
121
  }
118
122
  }
119
123
 
124
+ /** spec 26: a frame that committed - inside the error boundary, so a crash never counts - says which
125
+ * frame the stage shows, at which revision (the stamp this document was served with: a frame imported
126
+ * later never claims more than the wrappers it renders with), for which document generation. */
127
+ function Shown({ id }: { id: string }) {
128
+ // a tick later, and only if it is still mounted: a frame that throws from its own effects is replaced by
129
+ // the boundary's card first, which unmounts this and cancels the report
130
+ useEffect(() => {
131
+ const t = setTimeout(() => post({ type: 'sh:stage-shown', at: id, nav: params.get('r') ?? '', epoch: stamps?.epoch ?? '', doc: stamps?.doc[id] ?? 0 }), 0)
132
+ return () => clearTimeout(t)
133
+ }, [id])
134
+ return null
135
+ }
136
+
120
137
  function ErrorCard({ title, message, detail }: { title: string; message: string; detail: string }) {
121
138
  return createElement('div', { style: { fontFamily: 'ui-monospace,monospace', fontSize: 12, padding: 16, color: '#ff8a80' } },
122
139
  createElement('div', { style: { fontWeight: 700, marginBottom: 8 } }, title),
@@ -277,7 +294,7 @@ function Stage() {
277
294
  // that differs at depth k legitimately remounts everything below
278
295
  let tree: ReactNode = createElement(mounted.Frame)
279
296
  for (const W of [...mounted.wrappers].reverse()) tree = createElement(W, null, tree)
280
- return createElement(Boundary, { resetKey: mounted.id }, tree)
297
+ return createElement(Boundary, { resetKey: mounted.id }, createElement(Shown, { key: mounted.id, id: mounted.id }), tree)
281
298
  }
282
299
 
283
300
  async function boot() {
@@ -0,0 +1,57 @@
1
+ /**
2
+ * One anchor format (spec 26, Part 6). A person's click, `comments new`, `comments move` and a Live
3
+ * Jam re-pin all write the element bundle the frame builds (inspect.js `elBundle`): tag, role,
4
+ * label, test id, quote and CSS path, plus `pos` when a person clicked a point on it. What an agent
5
+ * names is a TARGET - words the element shows, or a selector / test id for one without words - and
6
+ * the dev server turns it into that bundle by finding the element in the rendered frame.
7
+ */
8
+
9
+ export interface AnchorTarget { on?: string; at?: string; nth?: number }
10
+ /** Where to look for a target only another viewport or theme shows (`--viewport`, `--theme`). */
11
+ export interface AnchorLook { viewport?: string; theme?: string }
12
+
13
+ export interface Anchor {
14
+ el: {
15
+ semantics: { tag?: string; role?: string; ariaLabel?: string; testId?: string; quote?: string }
16
+ cssPath?: string
17
+ source?: string
18
+ hue?: number
19
+ /** which of several look-alikes (1-based), when the path goes stale */
20
+ nth?: number
21
+ /** an unchecked `--at` target, resolved as the check resolves it: its test id, else selector */
22
+ at?: string
23
+ }
24
+ /** where a person clicked, as a fraction of the element - an agent's anchor has none */
25
+ pos?: { fx: number; fy: number }
26
+ }
27
+
28
+ /** What the dev server's check says (server/anchor-check.ts). Refused only on evidence - a frame
29
+ * that rendered with no match, or several; anything that stops the check is `unchecked`. */
30
+ export type AnchorCheck =
31
+ | { ok: true; anchor: Anchor; holders: string[]; viewport: string; theme: string }
32
+ | { ok: false; refused: 'none'; visible: string[]; viewport: string; theme: string }
33
+ | { ok: false; refused: 'several'; matches: string[]; viewport: string; theme: string }
34
+ | { ok: false; unchecked: string }
35
+
36
+ /** Read a target from untrusted input - CLI flags, a Live Jam block: exactly one of `on` / `at`, an
37
+ * optional whole `nth` from 1. A string is the reason it is not one. */
38
+ export function readTarget(raw: { on?: unknown; at?: unknown; nth?: unknown }): AnchorTarget | string {
39
+ const clean = (v: unknown) => (typeof v === 'string' || typeof v === 'number' ? String(v).replace(/\s+/g, ' ').trim() : '')
40
+ const on = clean(raw.on), at = clean(raw.at)
41
+ if (!on === !at) return 'name the element with --on "<words it shows>" or --at "<css selector or data-testid>" (one of them)'
42
+ // never cut short: a shortened target could match an element that shows only its beginning
43
+ if ((on || at).length > MAX_TARGET) return `--on / --at take at most ${MAX_TARGET} characters - name fewer words`
44
+ const nth = raw.nth === undefined ? undefined : Number(raw.nth)
45
+ if (nth !== undefined && !(Number.isInteger(nth) && nth >= 1)) return '--nth takes a whole number from 1'
46
+ return { ...(on ? { on } : { at }), ...(nth ? { nth } : {}) }
47
+ }
48
+ const MAX_TARGET = 200
49
+
50
+ /** The anchor written when the frame cannot be checked (dev off, no Chrome, a frame that throws):
51
+ * the target alone, which the canvas resolves exactly as the check would - by its words, or by
52
+ * `at` (its test id, else its selector). One that does not resolve shows as an orphan;
53
+ * `comments move` fixes it. */
54
+ export function uncheckedAnchor(t: AnchorTarget): Anchor {
55
+ const nth = t.nth ? { nth: t.nth } : {}
56
+ return t.on ? { el: { semantics: { quote: t.on }, ...nth } } : { el: { semantics: {}, at: t.at, ...nth } }
57
+ }
@@ -4,8 +4,7 @@
4
4
  * board file - one slug, the folder it sits in directly), ranked among its siblings by
5
5
  * `order`, and `design/boards/_folders.json` says which folders exist, where they rank, and
6
6
  * which folder holds which (`parent`). Two levels: a folder holds boards and folders, a
7
- * folder inside a folder (a sub-folder) holds boards only. `all-scenes` never enters the
8
- * tree - callers pin it last.
7
+ * folder inside a folder (a sub-folder) holds boards only.
9
8
  */
10
9
 
11
10
  import { readType } from './board-types.ts'
@@ -17,9 +16,28 @@ export const isBoardName = (n: unknown): n is string => typeof n === 'string' &&
17
16
 
18
17
  /** The folder registry beside the boards - underscore = infrastructure, never a board. */
19
18
  export const FOLDERS_FILE = '_folders.json'
20
- /** Is this basename in design/boards/ a board file? `_folders.json`, temp files and any
21
- * off-grammar name are not - every lister (dev API, build, watcher) shares this rule. */
22
- export const isBoardFile = (f: string): boolean => f.endsWith('.json') && isBoardName(f.slice(0, -5))
19
+ /** The built-in board every frame sat on until 0.25 (spec 26, Part 7). A reserved name: never
20
+ * created, renamed to or saved, and a leftover file is set aside - but its comment log keeps
21
+ * its name, and old links naming it still land. */
22
+ export const ALL_SCENES = 'all-scenes'
23
+ /** Is this basename in design/boards/ a board file? `_folders.json`, temp files, any
24
+ * off-grammar name and a leftover `all-scenes.json` are not - every lister (dev API, build,
25
+ * watcher) shares this rule. */
26
+ export const isBoardFile = (f: string): boolean => f.endsWith('.json') && f !== `${ALL_SCENES}.json` && isBoardName(f.slice(0, -5))
27
+
28
+ /** One meaning of "on a board": the live frames a board shows - those its nodes hold, or every
29
+ * live frame when it says `"auto": true`. Every check, hint, link, mark and the Not on a board
30
+ * list asks here. */
31
+ export function framesOn(board: unknown, live: readonly string[]): string[] {
32
+ const b = board as { auto?: unknown; nodes?: unknown } | null
33
+ if (b?.auto === true) return [...live]
34
+ const held = new Set(Array.isArray(b?.nodes) ? b.nodes.map((n) => (n as { frame?: unknown } | null)?.frame) : [])
35
+ return live.filter((f) => held.has(f))
36
+ }
37
+
38
+ /** Sidebar order with archive boards last - history is not where a change is reviewed. */
39
+ export const archiveLast = (order: readonly string[], isArchive: (n: string) => boolean): string[] =>
40
+ [...order.filter((n) => !isArchive(n)), ...order.filter(isArchive)]
23
41
 
24
42
  /** A folder and what it holds, in order: boards, and - in a top-level folder only - sub-folders. */
25
43
  export type Folder = { kind: 'folder'; name: string; items: TreeItem[]; title?: string; description?: string; type?: string }
@@ -126,7 +144,7 @@ export function buildTree(boards: BoardRow[], folders: FolderRow[]): TreeItem[]
126
144
  const implied: string[] = []
127
145
  const rootBoards: BoardRow[] = []
128
146
  for (const b of boards) {
129
- if (!isBoardName(b.name) || b.name === 'all-scenes') continue
147
+ if (!isBoardName(b.name) || b.name === ALL_SCENES) continue
130
148
  const folder = isBoardName(b.folder) ? b.folder : undefined
131
149
  if (!folder) { rootBoards.push(b); continue }
132
150
  if (!reg.has(folder) && !implied.includes(folder)) implied.push(folder) // implied by the board alone: always top-level
@@ -180,7 +198,7 @@ export function validateWire(wire: unknown): string | null {
180
198
  if (!Array.isArray(wire)) return 'invalid tree'
181
199
  const boards = new Set<string>(), folders = new Set<string>()
182
200
  const board = (n: unknown): string | null => {
183
- if (!isBoardName(n) || n === 'all-scenes') return 'invalid board name in tree'
201
+ if (!isBoardName(n) || n === ALL_SCENES) return 'invalid board name in tree'
184
202
  if (boards.has(n)) return `board "${n}" appears twice`
185
203
  boards.add(n)
186
204
  return null
@@ -286,8 +304,8 @@ export function takeBoard(t: TreeItem[], board: string): { list: string | null;
286
304
  export type Drag = { kind: TreeItem['kind']; name: string }
287
305
  export type Drop = { list: string | null; index: number } | { into: string }
288
306
 
289
- /** A row the sidebar rendered, measured - the list as the human sees it, top to bottom,
290
- * the pinned `all-scenes` row included (it is the root's end). `parent` is the folder the
307
+ /** A row the sidebar rendered, measured - the list as the human sees it, top to bottom.
308
+ * `parent` is the folder the
291
309
  * row sits in (null = the root) and `depth` that list's depth (0 root, 1 a top-level
292
310
  * folder's items, 2 a sub-folder's). `open` is a folder's disclosure; `left` is the row's
293
311
  * left edge, from which the indent of each level is measured. */
@@ -341,7 +359,6 @@ export function resolveDrop(t: TreeItem[], d: Drag, rows: Row[], x: number, y: n
341
359
  for (const r of rs) if (y >= mid(r)) g++
342
360
  const above = rs[g - 1], below = rs[g]
343
361
  if (!above) return { list: null, index: 0 }
344
- if (above.name === 'all-scenes') return { list: null, index: t.length }
345
362
  type Slot = { list: string | null; index: number; depth: number }
346
363
  // the deepest slot the gap can mean: inside an open folder, under its header - or right after the row above, in its own list
347
364
  let first: Slot
@@ -35,6 +35,9 @@ export interface CommentEvent {
35
35
  mentions?: Mention[] // create/reply only - people named in the body (v1.1)
36
36
  emoji?: string // react events
37
37
  addressedIn?: string // resolve events: the variant frame that answered
38
+ /** create/reply (and an edit of one): does this message ask the human something (spec 26)?
39
+ * Absent = written before 0.25, read by `asks()` with the old rule. */
40
+ asks?: boolean
38
41
  // --- Live Jam additions ---
39
42
  agent?: boolean // true = written by the Marver agent (never trusted for execution; render + guard only)
40
43
  agentMeta?: AgentMeta // provenance for the Marver avatar tooltip (agent events only)
@@ -53,10 +56,17 @@ export interface Thread {
53
56
  agent?: boolean // root authored by the agent
54
57
  agentMeta?: AgentMeta
55
58
  mentions?: Mention[]
56
- replies: { id: string; author?: CommentEvent['author']; body?: string; ts: number; agent?: boolean; agentMeta?: AgentMeta; mentions?: Mention[] }[]
59
+ asks?: boolean
60
+ replies: { id: string; author?: CommentEvent['author']; body?: string; ts: number; agent?: boolean; agentMeta?: AgentMeta; mentions?: Mention[]; asks?: boolean }[]
57
61
  reactions: Record<string, string[]> // emoji -> author emails (toggle semantics)
58
62
  }
59
63
 
64
+ /** Does this message ask the human something? The writer says so (`asks`); a message written
65
+ * before 0.25 says nothing, and the old rule reads it: a note asks, a reply asks when it ends
66
+ * in "?". `note` = the thread's root (a create event). */
67
+ export const asks = (m: { asks?: boolean; body?: string }, note: boolean): boolean =>
68
+ m.asks ?? (note || /\?\s*$/.test(m.body ?? ''))
69
+
60
70
  /** Events the other side lacks, by id - the sync payload in either direction. */
61
71
  export function diffEvents(mine: CommentEvent[], theirIds: Iterable<string>): CommentEvent[] {
62
72
  const have = new Set(theirIds)
@@ -76,7 +86,7 @@ export function replay(events: CommentEvent[]): Thread[] {
76
86
  threads.set(ev.commentId, {
77
87
  id: ev.commentId, board: ev.board, nodeKey: ev.nodeKey, frame: ev.frame,
78
88
  anchor: ev.anchor, author: ev.author, body: ev.body, ts: ev.ts,
79
- resolved: false, agent: ev.agent, agentMeta: ev.agentMeta, mentions: ev.mentions, replies: [], reactions: {},
89
+ resolved: false, agent: ev.agent, agentMeta: ev.agentMeta, mentions: ev.mentions, asks: ev.asks, replies: [], reactions: {},
80
90
  })
81
91
  }
82
92
  for (const ev of ordered) {
@@ -84,17 +94,16 @@ export function replay(events: CommentEvent[]): Thread[] {
84
94
  case 'reply': {
85
95
  const t = ev.parentId ? threads.get(ev.parentId) : undefined
86
96
  if (!t || !ev.commentId || t.replies.some((r) => r.id === ev.commentId)) break
87
- t.replies.push({ id: ev.commentId, author: ev.author, body: ev.body, ts: ev.ts, agent: ev.agent, agentMeta: ev.agentMeta, mentions: ev.mentions })
97
+ t.replies.push({ id: ev.commentId, author: ev.author, body: ev.body, ts: ev.ts, agent: ev.agent, agentMeta: ev.agentMeta, mentions: ev.mentions, asks: ev.asks })
88
98
  break
89
99
  }
90
100
  case 'edit': {
91
- if (!ev.commentId || ev.body === undefined) break
92
- const t = threads.get(ev.commentId)
93
- if (t) { t.body = ev.body; break }
94
- for (const th of threads.values()) {
95
- const r = th.replies.find((r) => r.id === ev.commentId)
96
- if (r) { r.body = ev.body; break }
97
- }
101
+ // an edit changes the words, the `asks` flag, or both - and keeps whichever it leaves out
102
+ if (!ev.commentId || (ev.body === undefined && ev.asks === undefined)) break
103
+ const m = threads.get(ev.commentId) ?? [...threads.values()].flatMap((th) => th.replies).find((r) => r.id === ev.commentId)
104
+ if (!m) break
105
+ if (ev.body !== undefined) m.body = ev.body
106
+ if (ev.asks !== undefined) m.asks = ev.asks
98
107
  break
99
108
  }
100
109
  case 'resolve': {
@@ -6,24 +6,27 @@
6
6
  * a frame (orange). A row keeps ONE slot at its right edge; what fills it, first match wins: a
7
7
  * question (the bubble with how many), then the row's own count or status, then a frame's dot.
8
8
  */
9
- import type { Thread } from './events.ts'
9
+ import { asks, type Thread } from './events.ts'
10
10
 
11
- /** What the dev server says: when each frame last changed, when you last looked, and the line
12
- * before which everything counts as seen (the day marks first ran). */
11
+ /** What the dev server says (spec 26): revisions, never clock times. `changed` = the last revision
12
+ * that touched a frame; `doc` = the last one that needs a new document to be seen; `seen` = the
13
+ * revision you acknowledged. `epoch` names the state: it changes only when the state starts over. */
13
14
  export interface Marks {
15
+ epoch: string
14
16
  changed: Record<string, number>
17
+ doc: Record<string, number>
15
18
  seen: Record<string, number>
16
- baseline: number
17
19
  /** each board's frames - a board you are not on rolls up over these */
18
20
  boards: Record<string, string[]>
19
21
  }
20
22
 
21
23
  export const isNew = (m: Marks | null, id: string): boolean =>
22
- !!m && (m.changed[id] ?? 0) > Math.max(m.seen[id] ?? 0, m.baseline)
24
+ !!m && (m.changed[id] ?? 0) > (m.seen[id] ?? 0)
23
25
 
24
26
  /** A question's state is read from its thread - nobody sets it. Open with Marver's word last:
25
- * needs you. Open with yours last, after Marver spoke: answered, waiting on the agent. */
26
- export type Ask = { ask: number; answered: number }
27
+ * waiting on you (`ask`), `asking` when that word asks something. Open with yours last, after
28
+ * Marver spoke: answered, waiting on the agent. */
29
+ export type Ask = { ask: number; asking: number; answered: number }
27
30
  export function questions(threads: readonly Thread[]): Map<string, Ask> {
28
31
  const out = new Map<string, Ask>()
29
32
  for (const t of threads) {
@@ -31,8 +34,8 @@ export function questions(threads: readonly Thread[]): Map<string, Ask> {
31
34
  const last = t.replies.length ? t.replies[t.replies.length - 1] : t
32
35
  const marver = !!t.agent || t.replies.some((r) => r.agent)
33
36
  if (!marver) continue
34
- const q = out.get(t.frame) ?? { ask: 0, answered: 0 }
35
- if (last.agent) q.ask++
37
+ const q = out.get(t.frame) ?? { ask: 0, asking: 0, answered: 0 }
38
+ if (last.agent) { q.ask++; if (asks(last, last === t)) q.asking++ } // the agent says when it asks (spec 26)
36
39
  else q.answered++
37
40
  out.set(t.frame, q)
38
41
  }
@@ -55,11 +58,13 @@ export function rollup(m: Marks | null, q: Map<string, Ask>, ids: Iterable<strin
55
58
  return { asks, fresh }
56
59
  }
57
60
 
58
- /** `U`: the next frame that needs you, else the next new one - after `from` in reading order,
59
- * wrapping. `order` is the board's frames top-to-bottom, left-to-right. */
61
+ /** `U`: the next frame that asks you something, then the next one waiting on you (work to review),
62
+ * then the next new one (spec 26) - after `from` in reading order, wrapping. `order` is the board's
63
+ * frames top-to-bottom, left-to-right. */
60
64
  export function nextToLook(m: Marks | null, q: Map<string, Ask>, order: readonly string[], from: string | null): string | null {
61
65
  const i = from ? order.indexOf(from) : -1
62
66
  const ring = [...order.slice(i + 1), ...order.slice(0, i + 1)]
63
67
  // an answered frame waits on the agent, not on you: U skips it even when it is also new
64
- return ring.find((id) => (q.get(id)?.ask ?? 0) > 0) ?? ring.find((id) => isNew(m, id) && !q.get(id)?.answered) ?? null
68
+ return ring.find((id) => (q.get(id)?.asking ?? 0) > 0) ?? ring.find((id) => (q.get(id)?.ask ?? 0) > 0)
69
+ ?? ring.find((id) => isNew(m, id) && !q.get(id)?.answered) ?? null
65
70
  }
@@ -85,9 +85,11 @@ planning. The human should see the request land on the canvas within the first m
85
85
 
86
86
  1. **Create the frame files immediately** - right name, right scene, `meta` (title,
87
87
  viewport), and a minimal skeleton (a heading and a few placeholder blocks - enough
88
- to give it shape) - and pin them on the target board (APPEND a node to the board
89
- JSON - adding is always yours, only rearranging belongs to the shell; auto boards pick
90
- new frames up on their own). Changing existing frames only? Skip this step.
88
+ to give it shape) - and pin them on the board they belong to: `npx marver boards pin
89
+ <board> <scene/frame ...>` (or APPEND a node to the board JSON - adding is always yours,
90
+ only rearranging belongs to the shell). **Every frame goes on the board it belongs to -
91
+ its feature, its spec, its flow - and a frame that belongs to two goes on both.** A frame
92
+ on no board is listed apart (Not on a board). Changing existing frames only? Skip this step.
91
93
  2. **Light them up**: `npx marver work start <scene/frame ...>` - each frame wears the
92
94
  live working shimmer, and its board's icon in the sidebar. Only now do research,
93
95
  discovery, and planning begin - under a lit frame, never before one.
@@ -108,8 +110,12 @@ planning. The human should see the request land on the canvas within the first m
108
110
  the PNGs. No shell? instructions/jam.md has the file-drop way (`{"scene":"..."}`).
109
111
  6. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
110
112
  self-expire (default 10 min; `--ttl <min>` up to 30) - re-run `start` on long jobs,
111
- and never lean on expiry instead of `done`. `done` prints the canvas link to the
112
- frames it cleared (`on the canvas: ...`).
113
+ and never lean on expiry instead of `done`. `done` prints the canvas links to the
114
+ frames it cleared (`on the canvas: ...`, one per board), and a warning for a frame on no
115
+ board, with where its scene's other frames live - pin it, then hand it back.
116
+ An edit to a file several frames read (a kit, a spec read with `?raw`) already marks each of
117
+ them as changed for the human; name a frame in `done` for a change no import shows - data
118
+ fetched at run time, the app behind an embedded frame.
113
119
 
114
120
  ## Hand it back on the canvas
115
121
 
@@ -117,20 +123,28 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
117
123
 
118
124
  - **Every reply in which you created or changed frames ends with their canvas link**, on its
119
125
  own line: the `on the canvas:` line `work done` printed, or `npx marver link <scene/frame |
120
- scene ...>` for any set. It opens the board they sit on with them selected and in view -
126
+ scene ...>` for any set. Each opens a board they sit on (one link per board when they sit
127
+ on several) with them selected and in view -
121
128
  the human finds the work at once on a board of fifty frames. Never a full-screen focus link
122
129
  (`#/f/...`) unless they ask for full screen. No `marver dev` running? End with
123
130
  `npx marver dev` instead - the link carries its port.
124
131
  - **Answer each comment thread you addressed, in the thread**: `npx marver comments reply
125
132
  <thread> --body "<what changed>"` - one line, no longer than their comment. On a thread
126
- the human started it posts as Marver and pings them on the frame.
127
- - **A question or a decision about a frame goes ON that frame**, not only in the chat:
128
- `npx marver comments new <scene/frame> --body "..." [--on "<words on screen>"]` pins it where
129
- it applies, so the human answers in place. Also for a judgment call you took that they should
130
- check, or a change they would not spot. Nothing else - never a changelog, at most one note per
131
- frame per turn; the chat keeps the summary and can say "question on the form". Never resolve
132
- your own notes: the human resolves them as they review, and a reply in one comes back to you
133
- (Live Jam).
133
+ the human started it posts as Marver and pings them on the frame. A reply that asks them
134
+ something says so with `--ask` - it comes first for them.
135
+ - **A question or a decision about a frame goes ON that frame**, not only in the chat, and on
136
+ the element it is about: `npx marver comments new <scene/frame> --body "..." --on "<words that
137
+ element shows>"`, or `--at "<data-testid or css selector>"` for an element without words (an
138
+ icon). With `marver dev` running the frame is checked: words it does not show are refused with
139
+ what it does show, several matches need `--nth <n>`, and a target only another viewport or
140
+ theme shows needs `--viewport` / `--theme`. Also for a judgment call you took that they should
141
+ check, or a change they would not spot. A note asks; one that asks nothing says `--fyi`.
142
+ - **One thread per topic, each on its element; never a changelog.** A list of decisions is one
143
+ note per decision, each on its own line. A follow-up is a reply (`comments reply`, or `comments
144
+ new --thread <id>` on your own note), never a second note on the same subject. A note in the
145
+ wrong place: `npx marver comments move <thread> --on "..."`, never a second copy. The chat keeps
146
+ the summary and can say "question on the form". Never resolve your own notes: the human
147
+ resolves them as they review, and a reply in one comes back to you (Live Jam).
134
148
  - A comment-born (`@marver`) job hands back through its reply block alone
135
149
  (instructions/jam.md): no link, no CLI reply to its own thread.
136
150
 
@@ -201,6 +215,10 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
201
215
  `description` when one was written, and its `title` when the human (or you) named it.
202
216
  Read it before exploring; `marver dev` keeps it fresh. `npx marver boards` prints the
203
217
  boards part as a tree.
218
+ - **What the human has not reviewed.** At the start of a session, `npx marver marks`: the frames
219
+ waiting on them (your notes and replies they have not resolved - the ones that ask first) and
220
+ the frames new since they last looked. When it bears on the work, say so in your first message
221
+ ("you have not looked at the checkout frames since I changed them").
204
222
  - **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
205
223
  IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
206
224
  that never move on a rename. `title` is what humans see - free text (casing,
@@ -237,7 +255,8 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
237
255
  ## Boards (curated canvases)
238
256
 
239
257
  A board is a saved canvas: `design/boards/<name>.json` - you create and manage them
240
- by writing files; `all-scenes` is auto-managed, never write it. Compose a board
258
+ by writing files (`npx marver boards pin` puts frames on one). Every frame goes on the
259
+ board it belongs to; a frame that belongs to two goes on both. Compose a board
241
260
  deliberately with `"layout"`: rows/columns lanes of scenes plus `{ "space": n }`
242
261
  whitespace tokens, and the same grammar per scene for frames (columns align left
243
262
  edges; a variant-group name is one indivisible atom). **The default composition is
@@ -85,9 +85,11 @@ planning. The human should see the request land on the canvas within the first m
85
85
 
86
86
  1. **Create the frame files immediately** - right name, right scene, `meta` (title,
87
87
  viewport), and a minimal skeleton (a heading and a few placeholder blocks - enough
88
- to give it shape) - and pin them on the target board (APPEND a node to the board
89
- JSON - adding is always yours, only rearranging belongs to the shell; auto boards pick
90
- new frames up on their own). Changing existing frames only? Skip this step.
88
+ to give it shape) - and pin them on the board they belong to: `npx marver boards pin
89
+ <board> <scene/frame ...>` (or APPEND a node to the board JSON - adding is always yours,
90
+ only rearranging belongs to the shell). **Every frame goes on the board it belongs to -
91
+ its feature, its spec, its flow - and a frame that belongs to two goes on both.** A frame
92
+ on no board is listed apart (Not on a board). Changing existing frames only? Skip this step.
91
93
  2. **Light them up**: `npx marver work start <scene/frame ...>` - each frame wears the
92
94
  live working shimmer, and its board's icon in the sidebar. Only now do research,
93
95
  discovery, and planning begin - under a lit frame, never before one.
@@ -108,8 +110,12 @@ planning. The human should see the request land on the canvas within the first m
108
110
  the PNGs. No shell? instructions/jam.md has the file-drop way (`{"scene":"..."}`).
109
111
  6. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
110
112
  self-expire (default 10 min; `--ttl <min>` up to 30) - re-run `start` on long jobs,
111
- and never lean on expiry instead of `done`. `done` prints the canvas link to the
112
- frames it cleared (`on the canvas: ...`).
113
+ and never lean on expiry instead of `done`. `done` prints the canvas links to the
114
+ frames it cleared (`on the canvas: ...`, one per board), and a warning for a frame on no
115
+ board, with where its scene's other frames live - pin it, then hand it back.
116
+ An edit to a file several frames read (a kit, a spec read with `?raw`) already marks each of
117
+ them as changed for the human; name a frame in `done` for a change no import shows - data
118
+ fetched at run time, the app behind an embedded frame.
113
119
 
114
120
  ## Hand it back on the canvas
115
121
 
@@ -117,20 +123,28 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
117
123
 
118
124
  - **Every reply in which you created or changed frames ends with their canvas link**, on its
119
125
  own line: the `on the canvas:` line `work done` printed, or `npx marver link <scene/frame |
120
- scene ...>` for any set. It opens the board they sit on with them selected and in view -
126
+ scene ...>` for any set. Each opens a board they sit on (one link per board when they sit
127
+ on several) with them selected and in view -
121
128
  the human finds the work at once on a board of fifty frames. Never a full-screen focus link
122
129
  (`#/f/...`) unless they ask for full screen. No `marver dev` running? End with
123
130
  `npx marver dev` instead - the link carries its port.
124
131
  - **Answer each comment thread you addressed, in the thread**: `npx marver comments reply
125
132
  <thread> --body "<what changed>"` - one line, no longer than their comment. On a thread
126
- the human started it posts as Marver and pings them on the frame.
127
- - **A question or a decision about a frame goes ON that frame**, not only in the chat:
128
- `npx marver comments new <scene/frame> --body "..." [--on "<words on screen>"]` pins it where
129
- it applies, so the human answers in place. Also for a judgment call you took that they should
130
- check, or a change they would not spot. Nothing else - never a changelog, at most one note per
131
- frame per turn; the chat keeps the summary and can say "question on the form". Never resolve
132
- your own notes: the human resolves them as they review, and a reply in one comes back to you
133
- (Live Jam).
133
+ the human started it posts as Marver and pings them on the frame. A reply that asks them
134
+ something says so with `--ask` - it comes first for them.
135
+ - **A question or a decision about a frame goes ON that frame**, not only in the chat, and on
136
+ the element it is about: `npx marver comments new <scene/frame> --body "..." --on "<words that
137
+ element shows>"`, or `--at "<data-testid or css selector>"` for an element without words (an
138
+ icon). With `marver dev` running the frame is checked: words it does not show are refused with
139
+ what it does show, several matches need `--nth <n>`, and a target only another viewport or
140
+ theme shows needs `--viewport` / `--theme`. Also for a judgment call you took that they should
141
+ check, or a change they would not spot. A note asks; one that asks nothing says `--fyi`.
142
+ - **One thread per topic, each on its element; never a changelog.** A list of decisions is one
143
+ note per decision, each on its own line. A follow-up is a reply (`comments reply`, or `comments
144
+ new --thread <id>` on your own note), never a second note on the same subject. A note in the
145
+ wrong place: `npx marver comments move <thread> --on "..."`, never a second copy. The chat keeps
146
+ the summary and can say "question on the form". Never resolve your own notes: the human
147
+ resolves them as they review, and a reply in one comes back to you (Live Jam).
134
148
  - A comment-born (`@marver`) job hands back through its reply block alone
135
149
  (instructions/jam.md): no link, no CLI reply to its own thread.
136
150
 
@@ -200,6 +214,10 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
200
214
  `description` when one was written, and its `title` when the human (or you) named it.
201
215
  Read it before exploring; `marver dev` keeps it fresh. `npx marver boards` prints the
202
216
  boards part as a tree.
217
+ - **What the human has not reviewed.** At the start of a session, `npx marver marks`: the frames
218
+ waiting on them (your notes and replies they have not resolved - the ones that ask first) and
219
+ the frames new since they last looked. When it bears on the work, say so in your first message
220
+ ("you have not looked at the checkout frames since I changed them").
203
221
  - **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
204
222
  IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
205
223
  that never move on a rename. `title` is what humans see - free text (casing,
@@ -237,7 +255,8 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
237
255
  ## Boards (curated canvases)
238
256
 
239
257
  A board is a saved canvas: `design/boards/<name>.json` - you create and manage them
240
- by writing files; `all-scenes` is auto-managed, never write it. Compose a board
258
+ by writing files (`npx marver boards pin` puts frames on one). Every frame goes on the
259
+ board it belongs to; a frame that belongs to two goes on both. Compose a board
241
260
  deliberately with `"layout"`: rows/columns lanes of scenes plus `{ "space": n }`
242
261
  whitespace tokens, and the same grammar per scene for frames (columns align left
243
262
  edges; a variant-group name is one indivisible atom). **The default composition is
@@ -47,9 +47,14 @@ is safe to resolve either way.
47
47
  in the sidebar (which rewrites `order`), retitle one from its right-click menu (which
48
48
  writes `title`), and file boards into folders (below) - so your ranking is a starting
49
49
  point they may adjust.
50
- - `auto: false` boards show exactly their list. `all-scenes` is auto-managed (it holds
51
- EVERY frame, so it is the heavy one) and always sinks to the BOTTOM of the switcher -
52
- never the landing board, and never write its file.
50
+ - **Every frame goes on the board it belongs to - its feature, its spec, its flow - and a
51
+ frame that belongs to two goes on both.** `npx marver boards pin <board> <scene/frame ...>`
52
+ appends them as nodes (or append a `{ "frame": ... }` node yourself). No board holds
53
+ everything: a frame on no board is listed apart - `npx marver boards`, the dev log, the
54
+ sidebar's Not on a board - and `work done` and `marver link` say where it belongs.
55
+ `all-scenes` is a reserved name, never a board.
56
+ - `auto: false` boards show exactly their list; `"auto": true` makes a board hold every frame
57
+ (a heavy board - keep it for a canvas of a few frames).
53
58
  - Do not edit board files while the canvas is open unless asked; the shell owns
54
59
  their layout fields (`x`/`y`/`w`/`h`, node keys). What is always yours, canvas
55
60
  open or not: creating a board, appending nodes, and writing the `layout` recipe
@@ -77,8 +82,7 @@ folder, or in a sub-folder. Files are the truth, and two files carry it:
77
82
  sub-folder names the sub-folder, never a path). `order` then ranks it among its
78
83
  siblings: at every level, the boards and folders there share one sequence (the root's
79
84
  boards and top-level folders; a folder's boards and sub-folders; a sub-folder's boards). Same grammar as board names
80
- (`^[a-z0-9][a-z0-9-]*$`); an invalid value means top level. `all-scenes` never
81
- lives in a folder.
85
+ (`^[a-z0-9][a-z0-9-]*$`); an invalid value means top level.
82
86
  - **Folders live in `design/boards/_folders.json`** - the underscore marks it as
83
87
  infrastructure, never a board:
84
88