@marver-design/marver 0.22.1 → 0.23.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 (65) hide show
  1. package/CHANGELOG.md +117 -0
  2. package/README.md +14 -10
  3. package/dist/agent-BsieQGTD.mjs +99 -0
  4. package/dist/{bake-CvY8QR3L.mjs → bake-DQtnDB8-.mjs} +1 -1
  5. package/dist/{board-status-CWGHIdo_.mjs → board-status-BZSzc9Hp.mjs} +69 -610
  6. package/dist/boards-BRLnoTC3.mjs +620 -0
  7. package/dist/{boards-BwKI0qWd.mjs → boards-Dv-Ipd8G.mjs} +13 -5
  8. package/dist/{build-B1kavcpc.mjs → build-_ndp_dXn.mjs} +18 -10
  9. package/dist/cli.mjs +20 -11
  10. package/dist/{comments-ClVgfQib.mjs → comments-BlqyZh3D.mjs} +71 -9
  11. package/dist/{config-DJxMRVD8.mjs → config-BUKprFAp.mjs} +5 -97
  12. package/dist/{context-D4t59wDi.mjs → context-CdkNiKdJ.mjs} +3 -2
  13. package/dist/{daemon-PmNqoOAk.mjs → daemon-BvMPdQ3k.mjs} +78 -19
  14. package/dist/{dev-Cf4wLGe2.mjs → dev-Cf-4eqaC.mjs} +50 -10
  15. package/dist/{init-C_K-cjBQ.mjs → init-hfZV7TwY.mjs} +10 -4
  16. package/dist/{ledger-Bu0BjqIe.mjs → ledger-BNXW14Xw.mjs} +1 -6
  17. package/dist/link-BodAbIQz.mjs +132 -0
  18. package/dist/{manifest-CcdWx7ud.mjs → manifest-TpfDWldB.mjs} +56 -6
  19. package/dist/{plugin-C5u07Yhv.mjs → plugin-DoXql0ZZ.mjs} +400 -48
  20. package/dist/{poster-BduzQBYz.mjs → poster-XBmUvQiL.mjs} +1 -1
  21. package/dist/{profile-BjAPAJSb.mjs → profile-CrZohD6g.mjs} +1 -1
  22. package/dist/{publish-bakes-b0jUwvM_.mjs → publish-bakes-KKTHWqq3.mjs} +2 -2
  23. package/dist/{share--bdSc4G5.mjs → share-BD-wcDQq.mjs} +1 -1
  24. package/dist/{shot-BAR8hmU9.mjs → shot-DOD8v6fJ.mjs} +2 -2
  25. package/dist/{shot-BFEuYbaz.mjs → shot-Dh6fV1Lm.mjs} +1 -1
  26. package/dist/{sync-BZaCWqK-.mjs → sync-DoA1vf4u.mjs} +15 -1
  27. package/dist/{work-0YopuMt9.mjs → work-ClFFq0Qh.mjs} +9 -3
  28. package/dist/{work-CLrmY-vQ.mjs → work-ayuL_9Kk.mjs} +72 -1
  29. package/docs/boards-and-folders.md +60 -7
  30. package/docs/context.md +10 -2
  31. package/docs/live-jam.md +11 -0
  32. package/docs/sticky-notes.md +1 -1
  33. package/package.json +1 -1
  34. package/src/client/content/diagram.tsx +7 -1
  35. package/src/client/content/img-lod.ts +12 -2
  36. package/src/client/content/index.tsx +73 -6
  37. package/src/client/content/md.ts +3 -2
  38. package/src/client/frame-host/inspect.js +23 -0
  39. package/src/client/shell/App.tsx +21 -10
  40. package/src/client/shell/BoardList.tsx +26 -6
  41. package/src/client/shell/LockedApp.tsx +2 -2
  42. package/src/client/shell/Play.tsx +5 -1
  43. package/src/client/shell/StatusPicker.tsx +12 -5
  44. package/src/client/shell/Tip.tsx +25 -5
  45. package/src/client/shell/board-icons.tsx +15 -1
  46. package/src/client/shell/canvas/Canvas.tsx +42 -6
  47. package/src/client/shell/canvas/anchor.ts +41 -0
  48. package/src/client/shell/canvas/ctl.ts +6 -0
  49. package/src/client/shell/comments-store.ts +8 -5
  50. package/src/client/shell/goto.ts +52 -3
  51. package/src/client/shell/hash.ts +24 -3
  52. package/src/client/shell/store.ts +261 -36
  53. package/src/client/shell/styles.css +20 -2
  54. package/src/client/shell/tidy.ts +34 -3
  55. package/src/shared/board-types.ts +10 -6
  56. package/src/shared/frames.ts +3 -0
  57. package/src/shared/status.ts +17 -8
  58. package/templates/AGENTS-embedded.md +43 -8
  59. package/templates/AGENTS-studio.md +43 -8
  60. package/templates/instructions/boards.md +13 -3
  61. package/templates/instructions/context.md +6 -2
  62. package/templates/instructions/iterate.md +29 -16
  63. package/templates/instructions/jam.md +9 -2
  64. package/templates/instructions/reference/deck-layouts.md +2 -1
  65. package/templates/instructions/reference/deck-story.md +2 -1
@@ -1,6 +1,6 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
2
  import { M as resolveAccess } from "./auth-DdUKeVKt.mjs";
3
- import { i as loadCollab } from "./sync-BZaCWqK-.mjs";
3
+ import { i as loadCollab } from "./sync-DoA1vf4u.mjs";
4
4
  //#region src/cli/share.ts
5
5
  /**
6
6
  * `marver share <action>` - the roster from the terminal (01-sharing §9).
@@ -337,8 +337,8 @@ async function shootFrame(opts) {
337
337
  };
338
338
  const plan = planShot(frame, viewports, size);
339
339
  if (frame.kind !== "html") try {
340
- const { scanAssetRefs } = await import("./build-B1kavcpc.mjs");
341
- const { ensurePoster } = await import("./poster-BduzQBYz.mjs");
340
+ const { scanAssetRefs } = await import("./build-_ndp_dXn.mjs");
341
+ const { ensurePoster } = await import("./poster-XBmUvQiL.mjs");
342
342
  const refs = scanAssetRefs(readFileSync(join(root, frame.file), "utf8"), frame.file);
343
343
  for (const r of refs) if (r.endsWith(".poster.png")) await ensurePoster(join(root, "design", "assets"), r.slice(0, -11));
344
344
  } catch {}
@@ -1,5 +1,5 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
- import { readDevInfo } from "./work-CLrmY-vQ.mjs";
2
+ import { i as readDevInfo } from "./work-ayuL_9Kk.mjs";
3
3
  //#region src/cli/shot.ts
4
4
  /**
5
5
  * `marver shot <scene/frame> [...]`, `--scene <name>`, `--all` - render frames headless and
@@ -27,6 +27,7 @@ var sync_exports = /* @__PURE__ */ __exportAll({
27
27
  connectClaim: () => connectClaim,
28
28
  connectToken: () => connectToken,
29
29
  loadCollab: () => loadCollab,
30
+ localOnlyThreads: () => localOnlyThreads,
30
31
  saveCollab: () => saveCollab,
31
32
  syncOnce: () => syncOnce
32
33
  });
@@ -149,7 +150,9 @@ async function syncOnce(root, collab) {
149
150
  const pulled = appendEvents(dir, board, remote).length;
150
151
  let pushed = 0;
151
152
  if (rights[board] === "comment") {
152
- const missing = diffEvents(readLog(dir, board), remote.map((e) => e.id)).filter((e) => !e.agent);
153
+ const local = readLog(dir, board);
154
+ const marverThreads = localOnlyThreads(local);
155
+ const missing = diffEvents(local, remote.map((e) => e.id)).filter((e) => !e.agent && !marverThreads.has(threadOf(e)));
153
156
  for (let i = 0; i < missing.length; i += 100) {
154
157
  const r = await fetch(`${base}/__mv/api/comments/${board}`, {
155
158
  method: "POST",
@@ -294,5 +297,16 @@ async function connectToken(root, url, token) {
294
297
  avatar: body.user.avatar
295
298
  });
296
299
  }
300
+ /** The thread an event belongs to: a reply names its root; everything else names its comment. */
301
+ const threadOf = (e) => e.parentId ?? e.commentId ?? "";
302
+ /** Threads that live on this machine only: started by Marver (an agent's `comments new`). Every id
303
+ * that resolves to one - the thread, and each reply in it (an edit or reaction names the reply) - is
304
+ * in the set, so `threadOf` of any event in such a thread hits it. */
305
+ function localOnlyThreads(events) {
306
+ const roots = new Set(events.filter((e) => e.agent && e.type === "create" && e.commentId).map((e) => e.commentId));
307
+ const out = new Set(roots);
308
+ for (const e of events) if (e.type === "reply" && e.parentId && roots.has(e.parentId) && e.commentId) out.add(e.commentId);
309
+ return out;
310
+ }
297
311
  //#endregion
298
312
  export { syncOnce as a, loadCollab as i, connectClaim as n, sync_exports as o, connectToken as r, connect as t };
@@ -1,11 +1,11 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
- import { WORK_TTL_DEFAULT, WORK_TTL_MAX, readDevInfo } from "./work-CLrmY-vQ.mjs";
2
+ import { i as readDevInfo, n as WORK_TTL_MAX, t as WORK_TTL_DEFAULT } from "./work-ayuL_9Kk.mjs";
3
3
  //#region src/cli/work.ts
4
4
  /**
5
5
  * `marver work` - the coding agent's hand on the canvas working state.
6
6
  *
7
7
  * work start <scene/frame ...> [--ttl <minutes>] mark frames actively working
8
- * work done <scene/frame ...> | --all clear the glow
8
+ * work done <scene/frame ...> | --all clear the glow; print the canvas link to them
9
9
  * work list what is glowing right now
10
10
  *
11
11
  * The intended choreography (taught in design/AGENTS.md): on accepting a request,
@@ -43,17 +43,20 @@ async function workCommand(root, action, frames, opts) {
43
43
  if (!frames.length) throw new Error("name the frames: work start <scene/frame ...>");
44
44
  const min = Number(opts.ttl);
45
45
  const ttlMs = Number.isFinite(min) && min > 0 ? Math.min(Math.max(min * 6e4, 1e4), WORK_TTL_MAX) : WORK_TTL_DEFAULT;
46
- const { frames: active } = await call("POST", {
46
+ const { frames: active, behind = [], context } = await call("POST", {
47
47
  frames,
48
48
  on: true,
49
49
  ttlMs
50
50
  });
51
51
  const pretty = ttlMs >= 6e4 ? `${Math.round(ttlMs / 6e4)} min` : `${Math.round(ttlMs / 1e3)} s`;
52
52
  console.log(`working: ${active.join(", ")} (auto-expires in ${pretty} - re-run to extend, \`work done\` to clear)`);
53
+ const label = (st) => st === "todo" ? "To do" : "Backlog";
54
+ for (const b of behind) console.log(context ? `note: board "${b.board}" still reads ${label(b.status)} - you are working on it, so make it In progress: a plan in context/plans/ that opens with front matter naming it - "---" / "state: proposed" / "capability: ${b.capability}" / "---" - then what you are building and why, a few lines (follow the form of the plans already there). Once its code starts, add "stage: build" to that front matter (Building). design/AGENTS.md, "Show the work".` : `note: board "${b.board}" reads ${label(b.status)} - with no context/ its status is set by hand: once the human has answered the context line (design/AGENTS.md), "status": "in-progress" on the board says it is being worked on ("building" once its code starts).`);
53
55
  return;
54
56
  }
55
57
  case "done": {
56
58
  if (!frames.length && !opts.all) throw new Error("name the frames (or --all): work done <scene/frame ...>");
59
+ const before = opts.all ? (await call("GET")).frames : frames;
57
60
  const { frames: active } = await call("POST", opts.all ? {
58
61
  on: false,
59
62
  all: true
@@ -62,6 +65,9 @@ async function workCommand(root, action, frames, opts) {
62
65
  on: false
63
66
  });
64
67
  console.log(active.length ? `still working: ${active.join(", ")}` : "nothing working - all clear");
68
+ const done = before.filter((f) => !active.includes(f));
69
+ const link = done.length ? await (await import("./link-BodAbIQz.mjs")).linkLine(root, done) : null;
70
+ if (link) console.log(`on the canvas: ${link}`);
65
71
  return;
66
72
  }
67
73
  case "list": {
@@ -1,3 +1,5 @@
1
+ import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
2
+ import { s as listBoardFiles } from "./boards-BRLnoTC3.mjs";
1
3
  import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
2
4
  import { join } from "node:path";
3
5
  import { randomBytes } from "node:crypto";
@@ -28,6 +30,10 @@ function createActivity(ttlMs = 9e4) {
28
30
  if (changed) emit();
29
31
  },
30
32
  active: frames,
33
+ has(frame, src) {
34
+ const until = m.get(`${src}|${frame}`);
35
+ return until !== void 0 && until > Date.now();
36
+ },
31
37
  sweep() {
32
38
  const now = Date.now();
33
39
  let changed = false;
@@ -60,8 +66,26 @@ function createActivity(ttlMs = 9e4) {
60
66
  * process that can read the repo - the owner's own tools - is trusted by definition.
61
67
  * Presence itself NEVER touches disk (activity.ts).
62
68
  */
69
+ var work_exports = /* @__PURE__ */ __exportAll({
70
+ WORK_TTL_DEFAULT: () => WORK_TTL_DEFAULT,
71
+ WORK_TTL_MAX: () => WORK_TTL_MAX,
72
+ activityClock: () => activityClock,
73
+ boardsChanged: () => boardsChanged,
74
+ boardsShowing: () => boardsShowing,
75
+ nextActivitySeq: () => nextActivitySeq,
76
+ onBoardsChanged: () => onBoardsChanged,
77
+ readDevInfo: () => readDevInfo,
78
+ removeDevInfo: () => removeDevInfo,
79
+ workActivity: () => workActivity,
80
+ writeDevInfo: () => writeDevInfo
81
+ });
63
82
  /** One per process - the dev server, the jam daemon, and the API all share it. */
64
83
  const workActivity = createActivity();
84
+ /** The order of what the shell is told about activity: each broadcast takes the next number, and the
85
+ * snapshot a page asks for carries the latest - so a slow snapshot never undoes a newer broadcast.
86
+ * Time-based, so a restarted server never counts backwards past a page that outlived it. */
87
+ const activityClock = { seq: 0 };
88
+ const nextActivitySeq = () => activityClock.seq = Math.max(activityClock.seq + 1, Date.now());
65
89
  /** The longest a CLI mark may glow unrefreshed - a forgotten `done` self-heals. */
66
90
  const WORK_TTL_MAX = 18e5;
67
91
  const WORK_TTL_DEFAULT = 6e5;
@@ -93,5 +117,52 @@ function readDevInfo(root) {
93
117
  return null;
94
118
  }
95
119
  }
120
+ const indexes = /* @__PURE__ */ new Map();
121
+ const boardListeners = /* @__PURE__ */ new Set();
122
+ function indexOf(root) {
123
+ let ix = indexes.get(root);
124
+ if (ix) return ix;
125
+ ix = {
126
+ byFrame: /* @__PURE__ */ new Map(),
127
+ auto: []
128
+ };
129
+ try {
130
+ for (const b of listBoardFiles(join(root, "design", "boards")).boards) {
131
+ const j = b.json;
132
+ if (j?.auto === true) ix.auto.push(b.name);
133
+ if (!Array.isArray(j?.nodes)) continue;
134
+ for (const n of j.nodes) {
135
+ const f = n && typeof n === "object" ? n.frame : void 0;
136
+ if (typeof f !== "string") continue;
137
+ let set = ix.byFrame.get(f);
138
+ if (!set) ix.byFrame.set(f, set = /* @__PURE__ */ new Set());
139
+ set.add(b.name);
140
+ }
141
+ }
142
+ } catch {}
143
+ indexes.set(root, ix);
144
+ return ix;
145
+ }
146
+ /** A board file changed (the dev server's boards watcher): forget the index, tell who is listening. */
147
+ function boardsChanged(root) {
148
+ indexes.delete(root);
149
+ for (const l of boardListeners) l(root);
150
+ }
151
+ function onBoardsChanged(fn) {
152
+ boardListeners.add(fn);
153
+ return () => {
154
+ boardListeners.delete(fn);
155
+ };
156
+ }
157
+ /** The boards that show any of these frames - what the sidebar lights while an agent works (the
158
+ * board's type icon shimmers): every board pinning one, every auto board, and all-scenes, which
159
+ * holds every frame. Sorted, so an unchanged answer compares equal. */
160
+ function boardsShowing(root, frames) {
161
+ if (!frames.length) return [];
162
+ const ix = indexOf(root);
163
+ const out = /* @__PURE__ */ new Set(["all-scenes", ...ix.auto]);
164
+ for (const f of frames) for (const b of ix.byFrame.get(f) ?? []) out.add(b);
165
+ return [...out].sort();
166
+ }
96
167
  //#endregion
97
- export { WORK_TTL_DEFAULT, WORK_TTL_MAX, readDevInfo, removeDevInfo, workActivity, writeDevInfo };
168
+ export { workActivity as a, readDevInfo as i, WORK_TTL_MAX as n, work_exports as o, boardsChanged as r, WORK_TTL_DEFAULT as t };
@@ -78,6 +78,37 @@ nests a sub-folder with `parent`:
78
78
  with its rank, the landing board - and `--json` gives the same tree. The landing board is the first
79
79
  board in that reading order, down through folders.
80
80
 
81
+ A board file that is not valid JSON says why, with the line and column: a red mark on its row in the
82
+ sidebar (hover it), the toast when you open it, the dev server's log, and an `(invalid JSON: …)` note
83
+ on its line in `npx marver boards` (`invalid` in `--json`).
84
+
85
+ ### Sizes
86
+
87
+ A content frame - a `Doc` of markdown, diagrams and images - is as tall as its content, which only a
88
+ render can tell. **`design/boards/_sizes.json` remembers it**: the height each one measured at its
89
+ own width, one line per frame.
90
+
91
+ ```json
92
+ { "about": "Written by marver dev: ...",
93
+ "heights": {
94
+ "spec/checkout@760": 1834,
95
+ "spec/pricing@1280": 1210 } }
96
+ ```
97
+
98
+ So a board opens with every frame at its real size - the content fills in, nothing moves - in
99
+ `marver dev` and on a published canvas alike (`marver build` ships the heights of the published
100
+ frames). `marver dev` writes it when a frame settles at a new height; commit it with the rest of
101
+ `design/`, and never edit it. A stale height is only a first guess: the frame measures, and the file
102
+ follows. A merge conflict in it is safe to resolve either way.
103
+
104
+ A board with a layout recipe also notes, as `laidOut`, which heights its rows were laid out around.
105
+ When a doc on it changed while the board was closed, the board re-runs its recipe as it opens; a
106
+ frame you dragged, at heights that did not change, stays where you put it.
107
+
108
+ When content does change the layout - an agent makes a doc taller, and the rows below move down -
109
+ the canvas holds the frame you are looking at in place: the selected one when it is on screen, else
110
+ the one in the middle of the view.
111
+
81
112
  ## Descriptions
82
113
 
83
114
  Every folder, board, scene and frame takes one `description`: a sentence for agents - what it is
@@ -109,19 +140,28 @@ but `marver build` suggests a publish type from it - `slides` for a deck, `refs`
109
140
  ## Status
110
141
 
111
142
  Feature and project boards also wear a status, read from the project's `context/` - Backlog, To do,
112
- In progress (filling by phase), Done, Done reported, Unknown - or decided on the board itself:
143
+ In progress (filling by phase), Building (the design agreed, the code underway: `stage: build` in the
144
+ open plan), Done, Done reported, Unknown - or decided on the board itself:
113
145
  `"status": "archived"`, `"paused"`, or `"blocked"` with a `"reason"`. **Done is never set by hand.**
114
146
  The tooltip says what decided it. [Context](context.md) has the rules.
115
147
 
116
148
  **Set it from the sidebar:** right-click a feature or project board, **Change status…**. The picker
117
149
  shows what the evidence says and offers only what a person decides - Blocked (it asks why), Paused,
118
- Archived, and **Back to the evidence** to undo a decision; without `context/`, Backlog, To do and In
119
- progress as well. Type to filter, or press a number. It writes `status` and `reason` into the board
120
- file and nothing else.
150
+ Archived, and **Back to the evidence** to undo a decision; where an open plan names the capability,
151
+ In progress and Building too, which write that plan's `stage` (no plan: "Building needs an open
152
+ plan"); without `context/`, Backlog, To do, In progress and Building as well. Type to filter, or press
153
+ a number. It writes `status` and `reason` into the board file, or the `stage` into the plan, and
154
+ nothing else.
121
155
 
122
156
  One rule draws them: a status still open is an outline in its colour - grey, yellow filling by phase,
123
- red for blocked - and a settled one is filled: Done a green disc, Archived a solid brown box. Done,
124
- reported is the green outline - a written claim, not yet confirmed.
157
+ the code in accent blue for Building, red for blocked - and a settled one is filled: Done a green
158
+ disc, Archived a solid brown box. Done, reported is the green outline - a written claim, not yet
159
+ confirmed.
160
+
161
+ **An agent at work.** While an agent works on a board's frames (`marver work start`, or a Live Jam
162
+ job), that board's icon in the sidebar turns accent blue with a highlight sweeping across it - the
163
+ frames' working shimmer, in miniature - and so does a closed folder holding it. It lasts exactly as
164
+ long as the work, so nobody sets it.
125
165
 
126
166
  ## Starting points
127
167
 
@@ -135,7 +175,8 @@ reported is the green outline - a written claim, not yet confirmed.
135
175
  - `npx marver boards new <name> --folder features` - a board in its type's starting layout: a
136
176
  feature's three phase scenes as three bands (spec, lo-fi, hi-fi), a start board rendering
137
177
  `context/INDEX.md` and `context/shipped.md`, a deck on its title slide. `--type` overrides the
138
- folder's; `--title`, `--description`, `--capability` fill the rest.
178
+ folder's; `--title`, `--description`, `--capability` fill the rest. A phase scene with its brief
179
+ and no frame yet waits quietly: its band takes no room until its first frame lands.
139
180
 
140
181
  ## Agents
141
182
 
@@ -146,6 +187,18 @@ teaches each one - creating a sub-folder, moving a folder in or out, renaming a
146
187
  refuses a write that would overwrite an edit it has not seen, so an agent's file write and a
147
188
  person's drag never silently erase each other.
148
189
 
190
+ ## Links to frames
191
+
192
+ `npx marver link <scene/frame | scene ...>` prints the canvas link that lands on those frames: the
193
+ board they sit on, in canvas mode, with them selected and the camera fitted to them - not the
194
+ full-screen focus view. The board is the first in sidebar order that shows them all, else
195
+ `all-scenes`; `--board` picks one. The link reads `#/b/<board>?f=<scene/frame>,...` (or
196
+ `?s=<scene>` for a whole scene), and a link naming a frame its board does not show follows the
197
+ frame to where it lives. `npx marver work done` prints the same link for the frames it clears, so an
198
+ agent's reply ends with it. A focus link (`#/f/<frame>`) opened on your dev canvas now has its way
199
+ back to the canvas (the grid button, or Esc); on a published canvas a focus link stays a page of
200
+ its own.
201
+
149
202
  ## Publishing
150
203
 
151
204
  A published canvas shows the folders of the published boards only - a sub-folder's parent included,
package/docs/context.md CHANGED
@@ -21,6 +21,14 @@ project this was run on, a blind eval answered the same 16 questions correctly b
21
21
 
22
22
  ## Start
23
23
 
24
+ On a canvas, the shortest way in is one sentence to your agent: *"Set up our context."* The context
25
+ instruction is the whole recipe - it asks you a few questions, runs `context init` with the right
26
+ kind, drafts from evidence, files your feature boards so they wear a status, and puts the check in ci.
27
+ Until a project has `context/`, an agent that makes or changes a feature board ends its reply with one
28
+ line offering exactly that; say no and it stops asking for the session.
29
+
30
+ By hand:
31
+
24
32
  ```bash
25
33
  npx marver context init
26
34
  ```
@@ -32,7 +40,7 @@ stages a new version beside any you have. `--kind knowledge` keeps a delivered r
32
40
  Project and Delivered columns - and a repository without a canvas gets the conventions themselves as
33
41
  `context/README.md`.
34
42
 
35
- Then ask your agent: *"Read design/instructions/context.md and set up our context."* It interviews
43
+ Then tell your agent: *"Set up our context."* It interviews
36
44
  you first - who is involved, where each relationship happens, what is private - then drafts from
37
45
  evidence: the shipped record from deploy runs and the changelog, the map from the code, contracts
38
46
  for the capabilities that matter now. Where nothing proves a claim, it writes `unknown`.
@@ -96,7 +104,7 @@ Feature and project boards wear a status, read from these files - the first that
96
104
  |---|---|---|
97
105
  | 1-3 | the board says `"status": "archived"`, `"paused"`, or `"blocked"` with a `"reason"` - by hand, or from the sidebar's **Change status…** | Archived · Paused · Blocked |
98
106
  | 4 | the evidence cannot be read | Unknown |
99
- | 5 | an open plan in `context/plans/` names the capability | In progress, filling by phase |
107
+ | 5 | an open plan in `context/plans/` names the capability | Building when the plan says `stage: build`, else In progress, filling by phase |
100
108
  | 6 | `shipped.md` shows it available, `confirmed` - in a clause (one per `;`) with no negation or pending word ("nowhere", "not yet", "rolled back", "planned") and, for a product, no pre-production place (staging, preview, dev, local, testing) unless it also names production | Done |
101
109
  | 7 | ... `reported` only | Done, reported |
102
110
  | 8 | its contract is `state: current` | To do |
package/docs/live-jam.md CHANGED
@@ -152,6 +152,17 @@ model when the agent names one. Claude Code, Cursor, droid, grok, and pi report
152
152
  in the stream; `codex exec` and `opencode run` report none, so their replies carry the
153
153
  harness without a model rather than a guessed one.
154
154
 
155
+ ## Notes from your chat agent
156
+
157
+ Live Jam answers comments; the same voice works the other way. An agent you are chatting with leaves
158
+ a note where it needs you - `npx marver comments new <scene/frame> --body "..." [--on "<words on
159
+ screen>"]` pins it on the frame, or on the element showing those words - and answers your threads
160
+ with `npx marver comments reply`. Both post as Marver, with the same provenance, land on your canvas
161
+ at once, and raise the bottom-right pill with a ping. Reply in a note and it is a jam job like any
162
+ reply to Marver - no tag needed; while the chat agent still has that frame lit (`marver work
163
+ start`), the job waits for it. Notes stay on your machine for now, like jam replies; a reply to a
164
+ collaborator's thread keeps your voice, the one that reaches them on the published canvas.
165
+
155
166
  ## Parallelism
156
167
 
157
168
  Two knobs stack, and they are not the same thing. `jam.concurrency` is how many jobs the
@@ -17,7 +17,7 @@ One markdown file, nothing to declare:
17
17
 
18
18
  Markdown with the Md block's rules: headings, lists, tables, emphasis, code; `[text](goto:scene/frame)`
19
19
  links jump to a frame; `http(s)` links open a new tab; images come from `design/assets/`; raw HTML is
20
- inert. A scene note is 380 wide, a frame note 260; when a frame has both, they stack in one column,
20
+ inert, shown as plain text, and HTML comments (`<!-- ... -->`) are not shown at all. A scene note is 380 wide, a frame note 260; when a frame has both, they stack in one column,
21
21
  scene first. An edit lands on the canvas as you save, without reloading the frame.
22
22
 
23
23
  The room is the layout's job. Every layout the shell composes (a board's `layout` recipe, the auto
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marver-design/marver",
3
- "version": "0.22.1",
3
+ "version": "0.23.1",
4
4
  "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -11,6 +11,11 @@ import { useEffect, useRef, useState, type ReactNode } from 'react'
11
11
  import { FONT_STACK, THEME_CSS, themeVars } from './palette.ts'
12
12
 
13
13
  let uidSeq = 0
14
+ /** Renders in flight - mermaid loads and lays out asynchronously, so a Doc is not done growing
15
+ * until this is 0 (the Doc's settled measurement reads it; the frame's own innerHTML is set
16
+ * before the count drops). */
17
+ let diagramsBusy = 0
18
+ export const diagramsPending = (): number => diagramsBusy
14
19
 
15
20
  const isDark = () =>
16
21
  document.documentElement.classList.contains('dark') || document.documentElement.dataset.theme === 'dark'
@@ -121,6 +126,7 @@ export function Diagram({ title, children }: { title?: string; children?: ReactN
121
126
  let renderSeq = 0
122
127
  const render = async () => {
123
128
  const mySeq = ++seq
129
+ diagramsBusy++
124
130
  try {
125
131
  // the zero-external-request boundary must hold BEFORE render: mermaid's image
126
132
  // shapes fetch their URL during render(), so post-render SVG sanitizing alone
@@ -145,7 +151,7 @@ export function Diagram({ title, children }: { title?: string; children?: ReactN
145
151
  setError(null)
146
152
  } catch (e) {
147
153
  if (live && mySeq === seq) setError(String((e as Error)?.message ?? e))
148
- }
154
+ } finally { diagramsBusy-- }
149
155
  }
150
156
  render()
151
157
  // the bridge mutates <html data-theme>/.dark with no React event - observe and re-render
@@ -51,6 +51,12 @@ function pick(devicePx: number): number {
51
51
  return 0 // native decode - only past the top bucket
52
52
  }
53
53
 
54
+ /** The event a canvas image fires when its FIRST decode is done, landed or failed. A canvas fed by
55
+ * fetch + createImageBitmap fires no DOM load/error of its own; the Doc listens for this one to
56
+ * know its height is final (content/index.tsx) - after its poll has stopped, too. */
57
+ export const LOD_SETTLED = 'mv-lod-settled'
58
+ const firstDone = (canvas: HTMLCanvasElement) => queueMicrotask(() => canvas.dispatchEvent(new Event(LOD_SETTLED, { bubbles: true })))
59
+
54
60
  async function decode(it: Item, bucket: number): Promise<void> {
55
61
  const token = ++it.token
56
62
  let bmp: ImageBitmap
@@ -59,7 +65,11 @@ async function decode(it: Item, bucket: number): Promise<void> {
59
65
  bmp = bucket
60
66
  ? await createImageBitmap(blob, { resizeWidth: bucket, resizeQuality: 'high' })
61
67
  : await createImageBitmap(blob)
62
- } catch { return } // network / decode failure: keep the last frame
68
+ } catch { // network / decode failure: keep the last frame
69
+ // a first decode that failed will not pin an aspect: the Doc must not wait on it to settle
70
+ if (!it.canvas.style.aspectRatio) { it.canvas.dataset.mvLod = 'failed'; firstDone(it.canvas) }
71
+ return
72
+ }
63
73
  if (it.token !== token || !it.canvas.isConnected) { bmp.close(); return } // superseded or unmounted
64
74
  const ctx = it.canvas.getContext('bitmaprenderer')
65
75
  if (!ctx) { bmp.close(); return }
@@ -68,7 +78,7 @@ async function decode(it: Item, bucket: number): Promise<void> {
68
78
  // the layout box would shift a hair on every resolution switch - the doc reflows, the content frame
69
79
  // auto-resizes, and the frame "jiggles" as you zoom (and the reflow storm helped starve frames to a
70
80
  // ready-timeout). A fixed aspect-ratio makes the box identical across buckets: only pixels sharpen.
71
- if (!it.canvas.style.aspectRatio) it.canvas.style.aspectRatio = `${bmp.width} / ${bmp.height}`
81
+ if (!it.canvas.style.aspectRatio) { it.canvas.style.aspectRatio = `${bmp.width} / ${bmp.height}`; firstDone(it.canvas) }
72
82
  it.canvas.width = bmp.width; it.canvas.height = bmp.height
73
83
  ctx.transferFromImageBitmap(bmp) // zero-copy; consumes + closes the bitmap
74
84
  it.bucket = bucket
@@ -11,13 +11,13 @@ import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
11
11
  import { useInSlide } from './slide.tsx'
12
12
  import { CONTENT_WIDTH } from '../const.ts'
13
13
  import { assetUrl, renderMarkdown, sanitizeMarkdownHtml, FAMILIES } from './md.ts'
14
- import { lodSupported, registerLodImage } from './img-lod.ts'
14
+ import { LOD_SETTLED, lodSupported, registerLodImage } from './img-lod.ts'
15
15
 
16
16
  // D3: family color classes for inline Md (`:blue[...]`), theme-aware (frames carry .dark + [data-theme])
17
17
  const FAMILY_CSS = Object.entries(FAMILIES).map(([f, c]) =>
18
18
  `.mv-md .mv-c-${f}{color:${c.light}}.dark .mv-md .mv-c-${f},[data-theme="dark"] .mv-md .mv-c-${f}{color:${c.dark}}`).join('\n')
19
19
 
20
- import { Diagram as DiagramRoot } from './diagram.tsx'
20
+ import { Diagram as DiagramRoot, diagramsPending } from './diagram.tsx'
21
21
  export function Diagram(props: Parameters<typeof DiagramRoot>[0]) { ensureStyles(); return <DiagramRoot {...props} /> }
22
22
  import { Slide as SlideRoot } from './slide.tsx'
23
23
  import { Chart as ChartRoot } from './chart.tsx'
@@ -34,6 +34,23 @@ const UNIT = 16 // one gap unit, px - plain adjacency on boards is one gutter;
34
34
 
35
35
  /* ---------------------------------- Doc ---------------------------------- */
36
36
 
37
+ /** How long the first measurement waits for the doc to finish growing before it reports anyway. */
38
+ const SETTLE_CAP = 2000
39
+ /** After the cap, a provisional doc keeps checking (slower) for this long, to report once it IS done. */
40
+ const SETTLE_TAIL = 60_000
41
+
42
+ /** Is anything that still changes this doc's height in flight? Fonts loading, a diagram rendering,
43
+ * an image not decoded yet (an LOD canvas pins its aspect on its first decode - img-lod.ts - and
44
+ * an <img> with no size yet is 0 tall until it loads; a lazy one off-screen may not load at all).
45
+ * A video poster sits in a fixed-ratio box: it never changes the height. */
46
+ export function heightPending(el: HTMLElement, doc: Document = document): boolean {
47
+ if (doc.fonts?.status === 'loading') return true
48
+ if (diagramsPending() > 0) return true
49
+ for (const c of el.querySelectorAll<HTMLCanvasElement>('canvas.mv-img-el')) if (!c.style.aspectRatio && c.dataset.mvLod !== 'failed') return true
50
+ for (const img of el.querySelectorAll('img')) if (!img.complete && !img.closest('.mv-video')) return true
51
+ return false
52
+ }
53
+
37
54
  export function Doc({ layout = 'document', children }: { layout?: 'document' | 'wide'; children?: ReactNode }) {
38
55
  const ref = useRef<HTMLDivElement>(null)
39
56
  useEffect(() => {
@@ -41,8 +58,18 @@ export function Doc({ layout = 'document', children }: { layout?: 'document' | '
41
58
  const el = ref.current
42
59
  if (!el || window.parent === window) return
43
60
  let t: ReturnType<typeof setTimeout> | undefined
61
+ let poll: ReturnType<typeof setTimeout> | undefined
62
+ let reported = false // the first measurement went out - the observer may report from here
63
+ let lastSettled = false
64
+ let tailFrom = 0
44
65
  const params = new URLSearchParams(location.search)
66
+ const height = () => Math.ceil(el.getBoundingClientRect().height)
45
67
  const post = () => {
68
+ reported = true
69
+ lastSettled = !heightPending(el)
70
+ // ANY provisional report - the first, or a later one (an edit that brought a loading image) -
71
+ // is followed by a settled one once the doc is done, even when finishing changes no geometry
72
+ if (!lastSettled && poll === undefined) { tailFrom = performance.now(); poll = setTimeout(check, 500) }
46
73
  window.parent.postMessage({
47
74
  type: 'sh:measure',
48
75
  // identity guards: board files may reuse node keys (frame id must match), and
@@ -52,15 +79,51 @@ export function Doc({ layout = 'document', children }: { layout?: 'document' | '
52
79
  gen: params.get('r') ?? '',
53
80
  ownWidth: CONTENT_WIDTH[layout] ?? CONTENT_WIDTH.document,
54
81
  measuredWidth: window.innerWidth, // the width this height is TRUE at (r3 #1)
55
- height: Math.ceil(el.getBoundingClientRect().height),
82
+ height: height(),
83
+ // settled = the doc is done growing: the shell commits it as THE height (and the dev shell
84
+ // keeps it for the next load - sizes.ts). Provisional = it may still grow (an image to come)
85
+ settled: lastSettled,
56
86
  }, '*')
57
87
  }
88
+ // The FIRST report waits until the doc is done: fonts, diagrams and images, and the height
89
+ // still the same two checks running - otherwise a board that already knows this frame's
90
+ // height (the committed cache) would see it shrink to the half-loaded doc and grow back.
91
+ // Capped: a slow or broken image never holds the frame hostage - it reports provisional,
92
+ // then once more, settled, when the image lands (or the observer sees it).
93
+ const start = performance.now()
94
+ let prevH = -1, quiet = 0
95
+ function check() {
96
+ poll = undefined
97
+ if (!reported) {
98
+ const h = height()
99
+ quiet = !heightPending(el!) && h === prevH ? quiet + 1 : 0
100
+ prevH = h
101
+ if (quiet >= 2 || performance.now() - start >= SETTLE_CAP) post()
102
+ else poll = setTimeout(check, 50)
103
+ return
104
+ }
105
+ if (lastSettled) return
106
+ if (!heightPending(el!)) { post(); return }
107
+ if (performance.now() - tailFrom < SETTLE_TAIL) poll = setTimeout(check, 500)
108
+ }
58
109
  // debounced ~300ms after the last content change; the shell guards staleness
59
110
  // on its side (event.source must map to a mounted iframe; reflow is board-scoped)
60
- const ro = new ResizeObserver(() => { clearTimeout(t); t = setTimeout(post, 300) })
111
+ const ro = new ResizeObserver(() => { if (!reported) return; clearTimeout(t); t = setTimeout(post, 300) })
61
112
  ro.observe(el)
62
- post()
63
- return () => { ro.disconnect(); clearTimeout(t) }
113
+ // an image landing or failing, a font finishing: check again now - the poll stops after its tail,
114
+ // and a size-given image that loads a minute later still owes the settled report
115
+ const onAsset = () => { if (reported && !lastSettled && poll === undefined) poll = setTimeout(check, 50) }
116
+ el.addEventListener('load', onAsset, true)
117
+ el.addEventListener('error', onAsset, true)
118
+ el.addEventListener(LOD_SETTLED, onAsset) // a canvas image's first decode, landed or failed (img-lod.ts)
119
+ document.fonts?.addEventListener?.('loadingdone', onAsset)
120
+ check()
121
+ return () => {
122
+ ro.disconnect(); clearTimeout(t); clearTimeout(poll)
123
+ el.removeEventListener('load', onAsset, true); el.removeEventListener('error', onAsset, true)
124
+ el.removeEventListener(LOD_SETTLED, onAsset)
125
+ document.fonts?.removeEventListener?.('loadingdone', onAsset)
126
+ }
64
127
  }, [layout])
65
128
  return <div ref={ref} className={`mv-doc mv-doc-${layout}`}>{children}</div>
66
129
  }
@@ -209,6 +272,10 @@ body { margin: 0; }
209
272
  breathe ABOVE far more than below, so structure reads at a glance. Every
210
273
  list-style is re-asserted: host Tailwind preflight strips markers. */
211
274
  .mv-md { max-width: 72ch; min-width: 0; font-size: 16px; line-height: 1.65; }
275
+ /* #12: prose keeps its measure, but a table straight in a wide Doc grows past it as far as its
276
+ cells need, up to the Doc's own width (cqi) - never into a Row's neighbour */
277
+ .mv-doc-wide { container-type: inline-size; }
278
+ .mv-doc-wide > .mv-md table { width: max-content; min-width: 100%; max-width: 100cqi; }
212
279
  .mv-md > :first-child { margin-top: 0; }
213
280
  .mv-md > :last-child { margin-bottom: 0; }
214
281
  .mv-md h1 { font-size: 30px; line-height: 1.16; letter-spacing: -0.021em; font-weight: 700; margin: 44px 0 14px; }
@@ -39,8 +39,9 @@ export function assetUrl(src: string): string | null {
39
39
  const marked = new Marked({
40
40
  gfm: true,
41
41
  renderer: {
42
- // raw HTML (block or inline) renders as its literal text - inert by construction
43
- html(token: any) { return escapeHtml(String(token.text ?? '')) },
42
+ // raw HTML (block or inline) renders as its literal text - inert by construction. Comments
43
+ // are the exception: markdown readers never show them, an unclosed one runs to the end (#15)
44
+ html(token: any) { return escapeHtml(String(token.text ?? '').replace(/<!--(?:-?>|[\s\S]*?(?:-->|$))/g, '')) },
44
45
  // marked leaves the text INSIDE a raw block (<script>, <style>, <pre>, <textarea>) unescaped
45
46
  // (`token.escaped`); here every text token is escaped - there is no raw block to serve
46
47
  text(token: any) {
@@ -290,10 +290,33 @@ body [data-mv-hover] { outline: 2px solid hsl(var(--mv-hue) 95% 45%); outline-of
290
290
  for (const el of document.querySelectorAll(want.tag))
291
291
  if (match(el)) return el
292
292
  }
293
+ // an anchor an agent wrote (`comments new --on "<text>"`) names the words alone: the
294
+ // innermost element showing them
295
+ if (want.quote && !want.tag && !anchor?.el?.cssPath) return byWords(want.quote)
293
296
  } catch { /* malformed semantics must not sink the whole batch */ }
294
297
  return null
295
298
  }
296
299
 
300
+ const norm = (t) => (t ?? '').replace(/\s+/g, ' ').trim()
301
+ const byWords = (quote) => {
302
+ const q = norm(quote).slice(0, 80).toLowerCase()
303
+ if (!q) return null
304
+ // one text node holding the words: its element (the common case, and cheap)
305
+ const walk = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT)
306
+ for (let n = walk.nextNode(); n; n = walk.nextNode()) {
307
+ const host = n.parentElement
308
+ if (!host || host.closest('script,style,noscript,template')) continue
309
+ if (norm(n.data).toLowerCase().includes(q)) return host
310
+ }
311
+ // words split across inline elements ("Pay <b>now</b>"): walk down from the body to the
312
+ // innermost element whose text still holds them (the first occurrence)
313
+ const holds = (el) => !el.matches('script,style,noscript,template') && norm(el.textContent).toLowerCase().includes(q)
314
+ let el = document.body
315
+ if (!holds(el)) return null
316
+ for (let next = [...el.children].find(holds); next; next = [...el.children].find(holds)) el = next
317
+ return el
318
+ }
319
+
297
320
  // re-resolve + re-apply the shell-driven highlight. Called on set and on every
298
321
  // resolve-anchors pass, so a stage frame swapped in AFTER the highlight arrived
299
322
  // (the DOM had not committed yet) still lights up on the next cycle - and, just as