@marver-design/marver 0.24.0 → 0.25.1

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 +56 -0
  2. package/README.md +1 -1
  3. package/dist/anchor-DVV732zR.mjs +33 -0
  4. package/dist/anchor-check-DGZnYviN.mjs +135 -0
  5. package/dist/{bake-ZhXq-X9f.mjs → bake-BpxMZfij.mjs} +45 -6
  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-DKaGhoVN.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-Diqx1Rt8.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-dTF5reck.mjs} +425 -207
  29. package/dist/{poster-B2QPvKOq.mjs → poster-D-zjYpgk.mjs} +1 -1
  30. package/dist/{profile-CrZohD6g.mjs → profile-Do0nGkXO.mjs} +1 -1
  31. package/dist/{publish-bakes-BJR3huhu.mjs → publish-bakes-C_9VZ-Mq.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-CUlmkqFX.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 +23 -4
  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
@@ -59,8 +59,8 @@ to step 4.
59
59
  in default order). Create the board the first time (`"order"` high, so it
60
60
  sits last among the curated boards; `"auto": false`). Set the copied frames'
61
61
  `meta.title` to `"<title> · v<N>"` so the sidebar reads as history. The
62
- version also shows on `all-scenes` (it holds everything) - fine; it must NOT
63
- be added to any feature board or to `publish.json`.
62
+ archive is the version's one board: it must NOT be added to any feature board
63
+ or to `publish.json`.
64
64
 
65
65
  ```json
66
66
  { "version": 1, "name": "archive", "order": 90, "auto": false,
@@ -85,8 +85,8 @@ to step 4.
85
85
  (instructions/jam.md). A change that removes an anchored element: a
86
86
  collaborator's thread is replied to and resolved FIRST, then the change
87
87
  (resolve first, restructure second); the owner's stays open - say in the
88
- reply what replaced the element (its pin parks at the frame's corner, still
89
- in view).
88
+ reply what replaced the element (its pin joins the column at the frame's
89
+ top-right corner, still in view) - or re-pin it with `comments move`.
90
90
 
91
91
  Never wait for the human to ask for this. They should be able to say "make the
92
92
  cards denser", "drop the sidebar", "try a warmer palette" three times in a row
@@ -143,11 +143,22 @@ the open list as a queue:
143
143
 
144
144
  ```bash
145
145
  npx marver comments list --open --json # what needs you (anchors included)
146
- npx marver comments reply <thread> --body "…"
146
+ npx marver comments reply <thread> --body "…" [--ask]
147
147
  npx marver comments resolve <thread> --addressed-in <scene/frame>
148
- npx marver comments new <scene/frame> --body "…" [--on "<words on screen>"] # a note where you need them
148
+ npx marver comments new <scene/frame> --body "…" --on "<words on screen>" # a note on its element
149
+ npx marver comments new <scene/frame> --body "…" --at "<testid or selector>" # ...one without words
150
+ npx marver comments new --thread <thread> --body "…" # a follow-up on your own note
151
+ npx marver comments move <thread> --on "<words on screen>" # a note in the wrong place
149
152
  ```
150
153
 
154
+ Your own notes: pin each point on the element it is about - `--on` with words that element
155
+ shows, or `--at` for an element without words (`--nth`, `--viewport`, `--theme` when the check
156
+ asks for them). One thread per topic, each on its element; never a changelog - a list of
157
+ decisions is one note per decision, each on its own line. A follow-up is a reply (`comments
158
+ reply`, or `comments new --thread`), never a second note on the same subject; a note in the
159
+ wrong place is moved (`comments move`), never copied. A note asks (`--fyi` when it does not);
160
+ a reply asks only with `--ask`.
161
+
151
162
  The discipline:
152
163
 
153
164
  1. **Read the anchor before the words.** Each thread carries the element it
@@ -155,8 +166,7 @@ The discipline:
155
166
  button is a different task than "too cramped" on the whole frame.
156
167
  2. **Look sideways before you touch anything.** A pin marks where the human
157
168
  NOTICED the problem, not the only place it lives. Siblings are the LIVE
158
- frames on the board the comment names (on `all-scenes`, the frames of the
159
- pinned frame's own scene and its feature board) that share the component,
169
+ frames on the board the comment names that share the component,
160
170
  the pattern, the copy or the state: the other steps of the flow, the sibling
161
171
  states, the variants. Never `archive/` and never a `<scene>-v<N>` version -
162
172
  history is not a sibling. Same defect there (the same element or pattern
@@ -183,8 +193,8 @@ The discipline:
183
193
  completed work.
184
194
  6. **A frame with open comments is load-bearing - never delete, rename, or
185
195
  gut it.** Its threads are anchored to elements INSIDE it; restructure the
186
- frame and the anchors strand (a dead anchor parks the pin at the frame
187
- edge; deleting the whole frame strands the thread off-canvas entirely -
196
+ frame and the anchors strand (a dead anchor parks the pin in the column at
197
+ the frame's corner; deleting the whole frame strands the thread off-canvas entirely -
188
198
  never lost from the log, but invisible until the frame returns). So: with a
189
199
  version snapshot taken, edit the live frame and close out each thread right
190
200
  after its change - a collaborator's resolved, the owner's replied to and left
@@ -131,13 +131,18 @@ did not.
131
131
 
132
132
  ## Re-pin if you moved the target
133
133
  If your edit renamed or moved the commented element so its old anchor no longer matches, re-pin
134
- the thread so it does not dangle. End your reply with a fenced block (nothing after it):
134
+ the thread so it does not dangle. End your reply with a fenced block (nothing after it) naming
135
+ the element the way `comments move` does: `"on"` = words it shows, or `"at"` = its data-testid
136
+ or a CSS selector (an element without words); `"nth"` picks one of several matches, and
137
+ `"viewport"` / `"theme"` name where to look when only another viewport or theme shows it:
135
138
  ```
136
139
  ```marver-reanchor
137
- [{"thread":"<threadId from the packet>","anchor":{"selector":"...","quote":"visible text","semantics":{"tag":"button","testId":"..."}}}]
140
+ [{"thread":"<threadId from the packet>","on":"Get started"}]
138
141
  ```
139
142
  ```
140
- Omit it when the element's identity is unchanged. The daemon writes the reanchor for you.
143
+ Omit it when the element's identity is unchanged. The daemon finds the element in the rendered
144
+ frame and writes the reanchor for you, in the same anchor format as a click; a target the frame
145
+ does not show (or shows several times, with no `nth`) is skipped.
141
146
 
142
147
  ## Reply
143
148
  Your FIRST message is ONE short line to the owner, posted the moment you write it - the owner
@@ -148,7 +153,8 @@ own run, never the thread. Just the ack, then go quiet and work.
148
153
  - Unclear? LOOK AROUND FIRST, like a human would: the packet's `thread` and `nearby`, then Read
149
154
  `design/comments/<board>.jsonl` (every thread on the board - recent pins on this frame often
150
155
  explain a terse ask). If that unlocks it, ack and proceed.
151
- - STILL unclear after looking around -> ONE clarifying question, then stop without editing.
156
+ - STILL unclear after looking around -> ONE clarifying question, then stop without editing
157
+ (the same question goes in a `marver-reply ask` block, below).
152
158
 
153
159
  Your completion reply goes in a fenced block at the end of your run - the daemon posts ONLY what
154
160
  is inside it and discards everything else you say (narration never reaches the thread):
@@ -157,6 +163,9 @@ is inside it and discards everything else you say (narration never reaches the t
157
163
  <your reply>
158
164
  ```
159
165
  ```
166
+ A reply that ASKS the owner something they must answer - a question, a decision - opens its
167
+ block with ```` ```marver-reply ask ```` instead: it comes first for them, with a notice of its own.
168
+ A done reply stays plain, even with an optional follow-up line.
160
169
  Rules (first line and the marver-reply block):
161
170
  - **Plain text only.** The thread renders RAW text, so markdown shows as literal characters. No
162
171
  `**bold**`, no `` `backticks` ``, no headings, no bullet lists. Line breaks are your only formatting.
@@ -16,7 +16,8 @@ vars if the host has no CLI.
16
16
  also pin threads. Boards not listed do not ship at all - their frames are not
17
17
  even in the bundle. `marver build` FAILS without this file (default-closed);
18
18
  `--boards a,b` overrides ad hoc (grants comment), `--all-boards` ships
19
- everything loudly.
19
+ every board loudly. A frame ships only on a board that shows it - every frame
20
+ goes on the board it belongs to.
20
21
 
21
22
  2. **Who gets in** - pick ONE of two gates at serve time. They are alternatives,
22
23
  not layers; setting both weakens the invite list to "an account OR whoever
@@ -82,8 +82,8 @@ one-sentence slides on the canvas) a missing fact is a visible `[PLACEHOLDER:
82
82
  what belongs here]`. In the build, a factual placeholder BLOCKS its slide -
83
83
  answered, or the slide is cut - never filled with plausible prose. Editorial
84
84
  gaps (a tagline, a caption, a transition line) you DO draft, labelled as
85
- proposed in a note on the frame (`npx marver comments new <scene/frame>`) - that
86
- is writing, not invention.
85
+ proposed in a note on what you drafted (`npx marver comments new <scene/frame> --on "<the
86
+ words you drafted>" --body "Proposed: ..."`) - that is writing, not invention.
87
87
 
88
88
  ## Writing that carries
89
89
 
@@ -1,132 +0,0 @@
1
- import { r as NAME } from "./cli.mjs";
2
- import { F as resolveType, _ as folderMap, h as flatten, i as checkBoardsDir, m as buildTree, r as boardFields, s as listBoardFiles, u as readRegistry, y as isBoardName } from "./boards-BRLnoTC3.mjs";
3
- import { s as scanFrames } from "./manifest-cyG3kbhk.mjs";
4
- import { i as readDevInfo } from "./work-ayuL_9Kk.mjs";
5
- import { join } from "node:path";
6
- //#region src/cli/link.ts
7
- /**
8
- * `marver link <scene/frame | scene ...>` - the canvas link that lands ON the work: the board the
9
- * frames sit on, opened in canvas mode with them selected and the camera fitted (never past 100%) -
10
- * not the full-screen focus view. An agent knows frame ids and scene names; it does not know the
11
- * shell's node keys or which port `marver dev` took, so it asks here and pastes what comes back.
12
- * `work done` prints the same link for the frames it clears; `comments new` prints its thread's.
13
- *
14
- * The board: `--board` when given; else the first board in sidebar order that shows EVERY frame
15
- * asked for (archive boards last - history is not where a change is reviewed); else `all-scenes`,
16
- * which holds every frame.
17
- */
18
- function resolveLink(root, targets, board) {
19
- if (!targets.length) throw new Error("name what to link: link <scene/frame | scene ...>");
20
- const known = scanFrames(root).frames.map((f) => f.id);
21
- const ids = new Set(known);
22
- const frames = [], scenes = [], all = [], exact = [];
23
- for (const raw of targets) {
24
- const t = raw.replace(/^design\/scenes\//, "").replace(/\.(tsx|jsx|html)$/, "").replace(/\/+$/, "");
25
- if (ids.has(t)) {
26
- if (!frames.includes(t)) frames.push(t);
27
- if (!all.includes(t)) all.push(t);
28
- if (!exact.includes(t)) exact.push(t);
29
- continue;
30
- }
31
- const members = known.filter((id) => id.startsWith(`${t}/`));
32
- if (members.length) {
33
- if (t.includes("/")) for (const m of members) {
34
- if (!frames.includes(m)) frames.push(m);
35
- if (!all.includes(m)) all.push(m);
36
- }
37
- else {
38
- if (!scenes.includes(t)) scenes.push(t);
39
- for (const m of members) if (!all.includes(m)) all.push(m);
40
- }
41
- continue;
42
- }
43
- throw new Error(`no frame or scene "${raw}" in design/scenes/ - a frame is <scene>/<name>, a scene is its folder`);
44
- }
45
- const dir = join(root, "design", "boards");
46
- const files = checkBoardsDir(root, dir) ? [] : listBoardFiles(dir).boards;
47
- const nodesOf = (name) => {
48
- const json = files.find((b) => b.name === name)?.json;
49
- return Array.isArray(json?.nodes) ? json.nodes.filter((n) => !!n && typeof n.frame === "string") : [];
50
- };
51
- const shows = (name) => {
52
- const pins = new Set(nodesOf(name).map((n) => n.frame));
53
- return all.every((f) => pins.has(f));
54
- };
55
- let pick = board;
56
- let fellBack = false;
57
- if (pick) {
58
- if (!isBoardName(pick)) throw new Error(`"${pick}" is not a board name`);
59
- if (pick !== "all-scenes" && !files.some((b) => b.name === pick)) throw new Error(`no board "${pick}" in design/boards/`);
60
- if (pick !== "all-scenes" && !shows(pick)) {
61
- const missing = all.filter((f) => !nodesOf(pick).some((n) => n.frame === f));
62
- throw new Error(`board "${pick}" does not show ${missing.join(", ")} - pin ${missing.length === 1 ? "it" : "them"} there first, or leave --board out`);
63
- }
64
- } else {
65
- const reg = readRegistry(dir);
66
- const folders = reg.state === "ok" ? reg.folders : [];
67
- const rows = files.filter((b) => b.name !== "all-scenes").map((b) => ({
68
- name: b.name,
69
- ...boardFields(b.json, isBoardName)
70
- }));
71
- const tree = buildTree(rows, folders);
72
- const order = flatten(tree);
73
- const fm = folderMap(tree);
74
- const byName = new Map(folders.map((f) => [f.name, f]));
75
- const typeOf = (n) => {
76
- const folder = byName.get(fm.get(n) ?? "");
77
- return resolveType(rows.find((r) => r.name === n)?.type, folder?.type, folder?.parent ? byName.get(folder.parent)?.type : void 0);
78
- };
79
- const isArchive = (n) => n === "archive" || typeOf(n) === "archive";
80
- pick = [...order.filter((n) => !isArchive(n)), ...order.filter(isArchive)].find(shows);
81
- if (!pick) {
82
- pick = "all-scenes";
83
- fellBack = true;
84
- }
85
- }
86
- const q = [frames.length ? `f=${frames.join(",")}` : "", scenes.length ? `s=${scenes.join(",")}` : ""].filter(Boolean).join("&");
87
- return {
88
- board: pick,
89
- frames,
90
- exact,
91
- scenes,
92
- all,
93
- hash: `#/b/${pick}?${q}`,
94
- ...fellBack ? { fellBack } : {},
95
- nodesOf
96
- };
97
- }
98
- /** The dev server's origin when it is running in this repo and answers like `marver dev` - else null. */
99
- async function devOrigin(root) {
100
- const info = readDevInfo(root);
101
- if (!info) return null;
102
- try {
103
- const res = await fetch(`http://localhost:${info.port}/__mv/api/work`, {
104
- headers: { "x-mv-work": info.token },
105
- signal: AbortSignal.timeout(1500)
106
- });
107
- const data = await res.json().catch(() => null);
108
- return res.ok && Array.isArray(data?.frames) ? `http://localhost:${info.port}/` : null;
109
- } catch {
110
- return null;
111
- }
112
- }
113
- const NOT_RUNNING = `\`${NAME} dev\` is not running in this repo - start it (\`npx ${NAME} dev\`), then run this again: the link carries its port`;
114
- async function linkCommand(root, targets, opts) {
115
- const r = resolveLink(root, targets, opts.board);
116
- const origin = await devOrigin(root);
117
- if (!origin) throw new Error(NOT_RUNNING);
118
- if (r.fellBack) console.error(` (no curated board shows ${r.all.length === 1 ? "it" : "all of them"} - the link opens on all-scenes; pin ${r.all.length === 1 ? "it" : "them"} on a board for a tighter view)`);
119
- console.log(`${origin}${r.hash}`);
120
- }
121
- /** The link line other commands print after their own output - never fails them. */
122
- async function linkLine(root, targets) {
123
- try {
124
- const r = resolveLink(root, targets);
125
- const origin = await devOrigin(root);
126
- return origin ? `${origin}${r.hash}` : null;
127
- } catch {
128
- return null;
129
- }
130
- }
131
- //#endregion
132
- export { devOrigin, linkCommand, linkLine, resolveLink };