@marver-design/marver 0.25.1 → 0.26.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 (95) hide show
  1. package/CHANGELOG.md +116 -0
  2. package/README.md +5 -3
  3. package/dist/{anchor-DVV732zR.mjs → anchor-5H1vnoLu.mjs} +6 -1
  4. package/dist/{anchor-check-DGZnYviN.mjs → anchor-check-l-ny3UzH.mjs} +1 -1
  5. package/dist/audio-Dw1lfMdb.mjs +443 -0
  6. package/dist/{auth-DdUKeVKt.mjs → auth-Dix8wrXV.mjs} +1 -1
  7. package/dist/{bake-BpxMZfij.mjs → bake-C-awKgLA.mjs} +1 -1
  8. package/dist/{boards-Csxj2WJn.mjs → boards-DYG22tOe.mjs} +2 -2
  9. package/dist/{build-DKaGhoVN.mjs → build-BDRiO_mP.mjs} +16 -9
  10. package/dist/capture-vadKjuCo.mjs +730 -0
  11. package/dist/cli.mjs +24 -18
  12. package/dist/{collab-gqNdScUE.mjs → collab-Dxg2trOK.mjs} +4 -3
  13. package/dist/{comments-Zoch254k.mjs → comments-0BSbb04K.mjs} +14 -3
  14. package/dist/{comments-pTLlhjh4.mjs → comments-BqXua-XL.mjs} +7 -7
  15. package/dist/{config-cKgZBRj0.mjs → config-Cf7EjAMf.mjs} +12 -1
  16. package/dist/{context-D2ugHqwO.mjs → context-HQ4Giw58.mjs} +1 -1
  17. package/dist/daemon-DL6Fwq6D.mjs +2569 -0
  18. package/dist/{dev-Diqx1Rt8.mjs → dev-Bw_qYWWq.mjs} +202 -18
  19. package/dist/dev-lock-DWSpa6nj.mjs +179 -0
  20. package/dist/{events-DnK_AnrW.mjs → events-CLH4ijKP.mjs} +14 -4
  21. package/dist/{init-DO4DhUt_.mjs → init-D8DtrK_F.mjs} +2 -2
  22. package/dist/{ledger-BNXW14Xw.mjs → ledger-D54iROST.mjs} +17 -1
  23. package/dist/{link-C-qUIuKU.mjs → link-BNzLvdhI.mjs} +2 -2
  24. package/dist/live-Cgzsicwi.mjs +4 -0
  25. package/dist/{manifest-DnAte_fB.mjs → manifest-Nl3KSVOk.mjs} +1 -1
  26. package/dist/{marks-koRsbHfe.mjs → marks-CKgzucHZ.mjs} +2 -2
  27. package/dist/{marks-DFuintmJ.mjs → marks-DyWMv_Z1.mjs} +23 -5
  28. package/dist/{marver-id-gate-DGANtVyC.mjs → marver-id-gate-BjF6v4bT.mjs} +4 -4
  29. package/dist/perf-C75MZ73h.mjs +167 -0
  30. package/dist/{perf-CCisg-ny.mjs → perf-DPbLGhhO.mjs} +1 -1
  31. package/dist/perf-jam-BU3TVrZu.mjs +239 -0
  32. package/dist/{plugin-dTF5reck.mjs → plugin-DkGmZs_r.mjs} +298 -38
  33. package/dist/{poster-D-zjYpgk.mjs → poster-BdtSKMDm.mjs} +2 -1
  34. package/dist/{profile-Do0nGkXO.mjs → profile-WU9qcbIo.mjs} +1 -1
  35. package/dist/{publish-bakes-C_9VZ-Mq.mjs → publish-bakes-9RzRToXV.mjs} +3 -3
  36. package/dist/queue-29ok5_eZ.mjs +1319 -0
  37. package/dist/reserve-BURNQ2Y3.mjs +53 -0
  38. package/dist/{rolldown-runtime-D7D4PA-g.mjs → rolldown-runtime-8H4AJuhK.mjs} +1 -0
  39. package/dist/{serve-wv2QWdxB.mjs → serve-C8rVheYk.mjs} +12 -12
  40. package/dist/session-BAaJsK5c.mjs +191 -0
  41. package/dist/{share-ScamJcks.mjs → share--oFJ1bCI.mjs} +2 -2
  42. package/dist/{shot-CUlmkqFX.mjs → shot-DQeR_Pfn.mjs} +339 -20
  43. package/dist/shot-XQV7HC9A.mjs +139 -0
  44. package/dist/speech-models-DomiLQcY.mjs +299 -0
  45. package/dist/speech-worker.mjs +354 -0
  46. package/dist/{summary-CrW88e3q.mjs → summary-Y8MY1Wuc.mjs} +2 -2
  47. package/dist/{sync-C3035OnJ.mjs → sync-DKk-yT1V.mjs} +9 -8
  48. package/dist/{work-GE88wb_3.mjs → work-F5u-twpJ.mjs} +28 -5
  49. package/dist/{work-CpJn1gwY.mjs → work-VvX_JIgl.mjs} +2 -2
  50. package/docs/jam-session.md +194 -0
  51. package/docs/live-jam.md +29 -3
  52. package/package.json +7 -1
  53. package/src/client/frame-host/bridge.js +20 -2
  54. package/src/client/frame-host/inspect.d.ts +4 -0
  55. package/src/client/frame-host/inspect.js +96 -6
  56. package/src/client/frame-host/keys.d.ts +6 -0
  57. package/src/client/frame-host/keys.js +59 -0
  58. package/src/client/frame-host/trail.d.ts +7 -0
  59. package/src/client/frame-host/trail.js +204 -0
  60. package/src/client/shell/App.tsx +52 -8
  61. package/src/client/shell/Comments.tsx +20 -6
  62. package/src/client/shell/JamSurface.tsx +346 -0
  63. package/src/client/shell/Play.tsx +32 -9
  64. package/src/client/shell/Tip.tsx +8 -3
  65. package/src/client/shell/Toolbar.tsx +5 -4
  66. package/src/client/shell/canvas/Canvas.tsx +12 -2
  67. package/src/client/shell/canvas/FrameNode.tsx +14 -4
  68. package/src/client/shell/comments-store.ts +23 -16
  69. package/src/client/shell/icons.tsx +17 -0
  70. package/src/client/shell/jam-capture.ts +1005 -0
  71. package/src/client/shell/jam-keys.ts +358 -0
  72. package/src/client/shell/jam-lane.tsx +249 -0
  73. package/src/client/shell/jam-lines.ts +115 -0
  74. package/src/client/shell/jam-panel.tsx +556 -0
  75. package/src/client/shell/jam-queue.ts +126 -0
  76. package/src/client/shell/jam-session.tsx +389 -0
  77. package/src/client/shell/jam-state.ts +103 -0
  78. package/src/client/shell/jam-surface-parts.tsx +106 -0
  79. package/src/client/shell/jam-ui.tsx +104 -0
  80. package/src/client/shell/jam-voice.ts +479 -0
  81. package/src/client/shell/sound.ts +22 -0
  82. package/src/client/shell/stage-size.ts +11 -0
  83. package/src/client/shell/store.ts +47 -17
  84. package/src/client/shell/styles.css +564 -2
  85. package/src/client/stage/main.tsx +18 -2
  86. package/src/shared/capture-frames.ts +41 -0
  87. package/src/shared/events.ts +19 -4
  88. package/src/shared/speech.ts +16 -0
  89. package/templates/AGENTS-embedded.md +10 -2
  90. package/templates/AGENTS-studio.md +10 -2
  91. package/templates/instructions/iterate.md +8 -6
  92. package/templates/instructions/jam.md +131 -59
  93. package/dist/daemon-Cl8KXGW4.mjs +0 -1523
  94. package/dist/perf-QJIWtTw1.mjs +0 -68
  95. package/dist/shot-jdO_B6Qw.mjs +0 -86
@@ -1,8 +1,9 @@
1
- import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
1
+ import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
2
2
  import { s as listBoardFiles } from "./boards-CGg6piKF.mjs";
3
+ import { r as pidRuns } from "./dev-lock-DWSpa6nj.mjs";
3
4
  import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
4
5
  import { join } from "node:path";
5
- import { randomBytes } from "node:crypto";
6
+ import { randomBytes, randomUUID } from "node:crypto";
6
7
  //#region src/server/jam/activity.ts
7
8
  function createActivity(ttlMs = 9e4) {
8
9
  const m = /* @__PURE__ */ new Map();
@@ -43,6 +44,16 @@ function createActivity(ttlMs = 9e4) {
43
44
  }
44
45
  if (changed) emit();
45
46
  },
47
+ leases(src) {
48
+ const now = Date.now();
49
+ return [...m].filter(([k, until]) => k.startsWith(`${src}|`) && until > now).map(([k, until]) => [k.slice(src.length + 1), until]);
50
+ },
51
+ restore(frame, until, src) {
52
+ if (frame && until > Date.now()) {
53
+ m.set(`${src}|${frame}`, until);
54
+ emit();
55
+ }
56
+ },
46
57
  onChange(fn) {
47
58
  cbs.push(fn);
48
59
  return () => {
@@ -90,25 +101,37 @@ const nextActivitySeq = () => activityClock.seq = Math.max(activityClock.seq + 1
90
101
  const WORK_TTL_MAX = 18e5;
91
102
  const WORK_TTL_DEFAULT = 6e5;
92
103
  const infoPath = (root) => join(root, "design", ".local", "dev.json");
93
- /** Written once per boot (dev.ts), removed on close - the CLI's discovery + credential. */
94
- function writeDevInfo(root, port) {
104
+ /** The instance each root's dev.json was last written with by THIS process - what `removeDevInfo`
105
+ * compares by default, so a server that stops never deletes the file of the canvas that still runs. */
106
+ const written = /* @__PURE__ */ new Map();
107
+ /** Written once per boot (dev.ts), removed on close - the CLI's discovery + credential. It names its
108
+ * server (`pid`, `instance`): a file whose pid is gone is ignored, and only its own server removes it. */
109
+ function writeDevInfo(root, port, instance = randomUUID()) {
95
110
  const token = randomBytes(24).toString("base64url");
96
111
  mkdirSync(join(root, "design", ".local"), { recursive: true });
97
112
  writeFileSync(infoPath(root), JSON.stringify({
98
113
  port,
99
114
  token,
115
+ pid: process.pid,
116
+ instance,
100
117
  ts: Date.now()
101
118
  }, null, 2) + "\n");
119
+ written.set(root, instance);
102
120
  return token;
103
121
  }
104
- function removeDevInfo(root) {
122
+ /** Remove dev.json if it is still this server's (`instance`, by default the one this process wrote). */
123
+ function removeDevInfo(root, instance = written.get(root)) {
105
124
  try {
125
+ const v = JSON.parse(readFileSync(infoPath(root), "utf8"));
126
+ if (!instance || v?.instance !== instance) return;
106
127
  rmSync(infoPath(root), { force: true });
128
+ if (written.get(root) === instance) written.delete(root);
107
129
  } catch {}
108
130
  }
109
131
  function readDevInfo(root) {
110
132
  try {
111
133
  const v = JSON.parse(readFileSync(infoPath(root), "utf8"));
134
+ if (v?.pid !== void 0 && !pidRuns(v.pid)) return null;
112
135
  return typeof v?.port === "number" && typeof v?.token === "string" ? {
113
136
  port: v.port,
114
137
  token: v.token
@@ -1,5 +1,5 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
- import { i as readDevInfo, n as WORK_TTL_MAX, t as WORK_TTL_DEFAULT } from "./work-GE88wb_3.mjs";
2
+ import { i as readDevInfo, n as WORK_TTL_MAX, t as WORK_TTL_DEFAULT } from "./work-F5u-twpJ.mjs";
3
3
  //#region src/cli/work.ts
4
4
  /**
5
5
  * `marver work` - the coding agent's hand on the canvas working state.
@@ -66,7 +66,7 @@ async function workCommand(root, action, frames, opts) {
66
66
  });
67
67
  console.log(active.length ? `still working: ${active.join(", ")}` : "nothing working - all clear");
68
68
  const done = before.filter((f) => !active.includes(f));
69
- const { links, hints } = done.length ? await (await import("./link-C-qUIuKU.mjs")).handBack(root, done) : {
69
+ const { links, hints } = done.length ? await (await import("./link-BNzLvdhI.mjs")).handBack(root, done) : {
70
70
  links: [],
71
71
  hints: []
72
72
  };
@@ -0,0 +1,194 @@
1
+ # Jam sessions and captures
2
+
3
+ Talk through your canvas the way you would with a designer beside you. Press `S`, point at
4
+ things, click through the prototype and say what is wrong; press `E`. That is a **capture**:
5
+ your words, every click and pick, and pictures of the frames you touched, in one record your
6
+ own coding agent works from. Run a whole review as a **session** (`J`) and Marver keeps the
7
+ thread of it, then writes it up when you are done.
8
+
9
+ Everything here runs with `npx marver dev` and the agent [Live Jam](live-jam.md) already
10
+ uses. Nothing needs setting up; the microphone is optional.
11
+
12
+ ## A capture: `S` ... `E`
13
+
14
+ `S` starts a capture. A teal ring runs round the canvas and the Jam button shows a pulsing
15
+ dot. While it records, everything you do is part of it:
16
+
17
+ - **what you say**, transcribed on this Mac (see [Words](#words-on-this-mac));
18
+ - **what you point at**: a click on an element numbers it on the frame, and holding the
19
+ pointer still over one notes it too. `L` picks with the laser (`⌥L` for the inspect laser,
20
+ every element outlined);
21
+ - **what you do in the prototype**: interactive mode on and off, every click and field, the
22
+ screens you went to in play, the device and theme you switched to, what you copied;
23
+ - **notes** you type (`N` opens the notes card) - a note often names what your words point at;
24
+ - **pictures**: `I` takes one of the frame under the pointer, and the frames you touched are
25
+ pictured as the capture ends - three at most - at the size you were looking at them (a
26
+ device, a width you dragged, the play stage). A capture holds twelve pictures in all.
27
+
28
+ `E` ends it. `Esc` throws it away. One capture records at a time.
29
+
30
+ Closing or reloading the tab asks first while a capture is recording or finishing. If you leave anyway, the capture
31
+ is kept as it stood - its words and notes so far, and a line saying the page closed before it finished - and comes
32
+ back as a draft to read, resume or drop; it never goes to your agent on its own. (Best effort: a crash gives the page
33
+ no chance to keep it.)
34
+
35
+ A capture is about the frames you **touched** - selected, clicked, typed in, scrolled,
36
+ resized, pictured, or zoomed to alone - not every frame that happened to be on screen. Those
37
+ are the frames its run may edit, and the frames pictured before and after it.
38
+
39
+ ## The read-back
40
+
41
+ When a capture ends, its **read-back** opens: the timeline of what you said and did, with its
42
+ pictures, under a short name a small model gave it (see [Names](#names)). Read it, fix a
43
+ mistranscribed word in place, and decide:
44
+
45
+ | Key | |
46
+ |---|---|
47
+ | `⏎` **Add to queue** | it goes to your agent |
48
+ | `K` **Keep** | not work now - kept for the session's record |
49
+ | `R` **Resume** | it ended too soon: carry on recording into the same capture |
50
+ | `Esc` **Drop** | throw it away |
51
+
52
+ A draft's read-back also takes notes after the fact: type in **Add a note** and they are
53
+ logged under "Added after", in the timeline's style, and go to the agent with the rest.
54
+
55
+ `jam: { capture: "at-once" }` skips the read-back: a capture queues as soon as it ends.
56
+
57
+ ## The lane
58
+
59
+ Captures line up along the bottom of the canvas in the order you made them, newest on the
60
+ right - drafts, queued, working, ready to review, done. Each tile says where it is. `Q` gives
61
+ the lane the keyboard: `←` `→` move, `⏎` opens, `⌘⏎` runs a queued one next, `K` keeps,
62
+ `⌫` drops, `Esc` hands the keys back. Right-click a tile to rename it.
63
+
64
+ Once two or more captures are done, they fold into one **Done** tile at the left end - "4
65
+ captures · 6 frames changed" - so the lane keeps its room for what still needs you. Click it
66
+ (or `⏎` on it) to open them in place, behind a narrow collapse tile that folds them back.
67
+
68
+ Your agent works on up to `jam.concurrency` captures at once (6 by default), each in its own
69
+ run, but never two on the same frame: a capture about a frame another run holds waits for it
70
+ ("Queued · next").
71
+
72
+ ## Review
73
+
74
+ When a run finishes, its tile turns to **Ready to review**, with a soft chime (`jam: { chime:
75
+ false }` silences it). `V` opens the next one to review:
76
+
77
+ - **Review** shows the agent's reply beside each frame it changed, **before and after at
78
+ once**: side by side for a tall frame (a phone), one above the other for a wide one (a
79
+ laptop), the panel as wide as that takes. **Both · Before · After** shows one alone; `B`
80
+ steps through them. `⌥←` `⌥→` move between frames. A frame the run made is marked **New**,
81
+ with no before.
82
+ - **Capture** (the tab at the top) shows the capture as you made it: its pictures and timeline.
83
+
84
+ `⏎` **Looks good** closes it; `⇧⏎` **More work** sends it back with what is still wrong;
85
+ `→` leaves it for later, `←` goes back. A capture started while a review is open follows that
86
+ run - "and this too".
87
+
88
+ When a capture asked for something new beside a frame - "a laptop version of this, next to
89
+ it" - the frame it pointed at was only where the new one goes. If the run made a new frame
90
+ and left the one you pointed at unchanged, the capture's thread moves onto the new frame
91
+ (when that capture ran alone, so the new frame is surely its own).
92
+
93
+ ## A session: `J`
94
+
95
+ `J` (or the Jam button in the toolbar) opens the start sheet: what Marver listens to, the
96
+ agent the session hands work to, and the keyboard shortcuts. **Start** (`⏎`) begins the
97
+ session and its first capture at once.
98
+
99
+ While a session runs, the canvas keeps its glowing edge and the Jam button its dot and
100
+ clock - seconds the first minute, then minutes - and the lane shows **Jam on**, listening
101
+ between captures. `S` starts the next capture.
102
+
103
+ `J` again wraps up. The wrap-up sheet lists every capture of the session with its state, and
104
+ a box for your instructions on how to take the session in - "prioritise the checkout fixes",
105
+ "file the small ideas as backlog". **Write the record** queues one more job: your agent
106
+ writes a page to `context/sessions/` (or `design/sessions/` without a `context/` folder) -
107
+ what was asked, what was done, what is left, the decisions heard, the ideas worth keeping.
108
+ It reads the confirmed and kept captures, your edits and notes, their replies and your
109
+ verdicts, and, unless you turn it off on the sheet, what you said between captures. **End
110
+ without a record** writes nothing.
111
+
112
+ Sessions are optional: captures, the lane and review all work without one.
113
+
114
+ ## Words, on this Mac
115
+
116
+ The first `S` or `J` asks once whether to use the microphone. Speech becomes words on your
117
+ machine with NVIDIA's Parakeet v3, a small speech-to-text model that runs locally: the first
118
+ time, Marver asks before downloading it (488 MB, once, into `~/.marver/models/`, every file
119
+ checked against its published hash) and keeps it for every canvas. Captures keep recording
120
+ while it downloads; your words start with the next one.
121
+
122
+ - **The audio never leaves this Mac and is never written to disk** - only the words are kept.
123
+ - English, French and the other major European languages are recognised.
124
+ - The speech engine (`sherpa-onnx-node`) is an optional dependency. Where it cannot install
125
+ or load, captures keep typed notes and the canvas says why.
126
+ - **Not now** keeps captures to typed notes; click the crossed-out microphone on a capture's
127
+ tile to be asked again.
128
+
129
+ ## Names
130
+
131
+ With Claude Code as the jam agent, each capture is named as soon as its words are in - a few
132
+ words like "Lamp tablet product page" on its tile, in the lane and on its thread. The name
133
+ comes from Claude Haiku, run through your own Claude Code login with no tools: **a draft's
134
+ words go to Anthropic for this**, as they do when the capture runs. A name you give it
135
+ (Rename) always wins. `jam: { names: false }` turns naming off; tiles then show their first
136
+ words. Other agents do not name captures.
137
+
138
+ ## What your agent receives
139
+
140
+ Each capture reaches your agent as one job: its words with their times, your notes, every UI
141
+ step, the pictures, and the element under each point with its source location
142
+ (`data-mv-loc`, the file and line it was written at, so the agent goes straight there). It
143
+ reads each distinct ask, acts on the reserved frames only, and replies per ask; the reply
144
+ shows in the review, beside the before and after pictures. The managed instructions
145
+ (`design/instructions/jam.md`, refreshed by `npx marver init`) spell this out for the agent.
146
+
147
+ ## Configuration
148
+
149
+ ```ts
150
+ // design/config.ts
151
+ jam: { agent: "claude", concurrency: 6, capture: "confirm", chime: true, names: true, loc: true },
152
+ ```
153
+
154
+ | Key | Default | What it does |
155
+ |---|---|---|
156
+ | `capture` | `"confirm"` | `"confirm"`: a capture waits for its read-back. `"at-once"`: it queues at `E` |
157
+ | `chime` | `true` | A soft chime when a capture is ready to review |
158
+ | `names` | `true` | Name each capture with Claude Haiku (Claude Code only) |
159
+ | `loc` | `true` | Stamp each element of your design files with `data-mv-loc` (dev only, never published) |
160
+
161
+ The rest - `agent`, `concurrency`, `subagents` - is in the [Live Jam guide](live-jam.md#the-config-block).
162
+ A bad value says so at boot and takes the default; nothing here turns Jam off.
163
+
164
+ ## Keys
165
+
166
+ | Where | Keys |
167
+ |---|---|
168
+ | Anywhere on the canvas | `S` capture · `J` session · `Q` the lane · `V` next to review |
169
+ | A capture recording | `E` end · `N` note · `I` picture · `L` laser · `⌥L` inspect · `Esc` drop |
170
+ | A read-back | `⏎` add to queue · `K` keep · `R` resume · `Esc` drop |
171
+ | A review | `⏎` looks good · `⇧⏎` more work · `→` later · `←` back · `B` both/before/after · `⌥←` `⌥→` frames · `Esc` leave |
172
+ | The lane (`Q`) | `←` `→` move · `⏎` open (or open/fold the Done tile) · `⌘⏎` do next · `K` keep · `⌫` drop · `Esc` leave |
173
+ | A laser on | `L` pointer · `⌥L` inspect · `Esc` off (before it closes or drops anything) |
174
+
175
+ The keys work inside frames too, in interactive mode and in play.
176
+
177
+ ## Where things are kept
178
+
179
+ How long each step takes on your machine - a capture sealing, its pictures, your words, naming, the queue, your agent,
180
+ the pictures before and after - is in `npx marver perf --jam` (median, slowest, and what went wrong lately), read from
181
+ `design/.local/perf/jam.jsonl`: numbers and fixed codes only, never your words.
182
+
183
+ The capture itself sits in `design/.local/` (gitignored, never published): its full record
184
+ and pictures under `design/.local/jam/`, the session transcript under
185
+ `design/.local/jam/sessions/`, the queue in `design/.local/jam-jobs.json`.
186
+
187
+ A capture you add to the queue or keep also becomes a **thread** on its board, like a
188
+ comment: a short excerpt of its words (600 characters at most), then your agent's replies.
189
+ Threads live in `design/comments/<board>.jsonl`, which is committed with the rest of
190
+ `design/` - so what you said in a capture reaches your repository when you commit, as a
191
+ comment would. They never reach a published canvas: `marver build` and `marver comments sync`
192
+ leave capture threads (and Marver's notes and replies) on your machine. The session
193
+ **record** your agent writes goes to `context/sessions/`, also meant to be committed.
194
+ Published canvases carry none of Jam: no captures, no queue, no microphone.
package/docs/live-jam.md CHANGED
@@ -6,6 +6,15 @@ glow, the agent edits the real frame source, and its reply lands back in the sam
6
6
  No round trip to the terminal. Marver ships no AI: the agent that acts is the one you
7
7
  already run and pay for.
8
8
 
9
+ **Only a tag starts work** (since 0.26). A plain reply in a thread - even one answering Marver -
10
+ is conversation: it starts nothing, and `npx marver marks` lists it under "answered by you"
11
+ for your chat agent. Each tag is a card, answered in its own thread; your agent works on up to
12
+ `jam.concurrency` of them at once, never two on the same frame.
13
+
14
+ To talk through the canvas instead of typing - point, click through the prototype, say what
15
+ is wrong - use a capture (`S` ... `E`) or a whole session (`J`): see
16
+ [Jam sessions and captures](jam-session.md).
17
+
9
18
  ## It arms itself
10
19
 
11
20
  Live Jam is on by default (since 0.9.0). Marver speaks seven agent CLIs - `claude`,
@@ -45,6 +54,10 @@ jam: { agent: "claude", concurrency: 6 },
45
54
  | `agent` | detected | The CLI the daemon spawns: `"claude"`, `"codex"`, `"cursor"`, `"droid"`, `"opencode"`, `"grok"`, or `"pi"` |
46
55
  | `concurrency` | `6` | Frames worked on at once (1-16). The same frame never gets two agents |
47
56
  | `subagents` | `true` | Inside one job, fan out one subagent per frame |
57
+ | `capture` | `"confirm"` | A capture waits for its read-back, or `"at-once"` queues at `E` ([captures](jam-session.md#configuration)) |
58
+ | `chime` | `true` | A soft chime when a capture is ready to review |
59
+ | `names` | `true` | Name each capture with Claude Haiku through Claude Code - its words go to Anthropic (Claude Code only) |
60
+ | `loc` | `true` | Stamp design elements with `data-mv-loc` (file and line, dev only) so the agent goes straight to the source |
48
61
 
49
62
  Shorthands: `jam: "codex"` names the agent and takes the rest of the defaults, `jam: true`
50
63
  is the default block, and **`jam: false` is the off switch**.
@@ -117,6 +130,14 @@ obvious one:
117
130
  The canvas's **copy as image** (`i` / `⇧i`, the images-square toolbar button) is this same
118
131
  renderer with `format=png`, so what a designer pastes and what an agent shoots is one picture.
119
132
 
133
+ - **Pictures that are what the frame shows** (0.26.1). Headless Chrome could copy its view before resizing it for the
134
+ picture and tile the old copy across the image. Each picture now has a window of its own (a fixed frame's or a
135
+ slide's sized to the picture first), and every picture is checked for that tiling: one that shows it is taken again
136
+ (`recaptures` in `--json` says how many times), and one that never comes out right fails with "stale surface"
137
+ rather than shipping.
138
+ - **Inside a sandbox** (Codex blocks the network, localhost included), `marver shot` cannot reach the dev server: it
139
+ then drops the same request in the file inbox itself and waits for its answer - the same output, the same exit code.
140
+
120
141
  The generated jam instructions tell every agent to shoot and LOOK before replying "done".
121
142
  A frame that never mounts, or a dev server that isn't reachable, comes back as an honest
122
143
  `{"ok":false,"error":...}` carrying the real cause - never a blank that reads as success.
@@ -166,9 +187,10 @@ at once, and raise the bottom-right pill with a ping - Marver's replies on one b
166
187
  single notice ("2 replies", View walks through them), a message that asks (a note, unless the
167
188
  agent wrote `--fyi`; a reply with `--ask`; a jam reply opened with ```` ```marver-reply ask ````)
168
189
  stands on its own, and the frame wears the orange question
169
- bubble in the sidebar until the thread is resolved. Reply in a note and it is a jam job like any
170
- reply to Marver - no tag needed; while the chat agent still has that frame lit (`marver work
171
- start`), the job waits for it. Notes stay on your machine for now, like jam replies; a reply to a
190
+ bubble in the sidebar until the thread is resolved. A plain reply in a note starts nothing - only
191
+ a tag does: tag `@marver` in your reply and it is a jam job, with the note in its brief; while
192
+ the chat agent still has that frame lit (`marver work start`), the job waits for it. Your plain
193
+ answers are listed by `npx marver marks` ("answered by you") for your chat agent. Notes stay on your machine for now, like jam replies; a reply to a
172
194
  collaborator's thread keeps your voice, the one that reaches them on the published canvas.
173
195
 
174
196
  ## Parallelism
@@ -191,6 +213,10 @@ configuration speaking, and marver does not override it.
191
213
 
192
214
  - **It has to be your machine, your repo, with `marver dev` running.** That is the trust
193
215
  boundary above, working as intended.
216
+ - **It has to tag `@marver`.** Since 0.26 a plain reply starts nothing, even in a thread
217
+ Marver started - tag it in the reply.
218
+ - **One canvas per folder.** A second `marver dev` in the same folder stops with "a canvas
219
+ already runs here" and its link, so two servers never run the same jobs twice.
194
220
  - **The first boot after upgrading to 0.9.0 rebaselines the job journal**, because an
195
221
  existing journal predates the device stamp. Any `@marver` left unprocessed while the
196
222
  server was down is marked seen instead of run. Re-comment to pick it up.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marver-design/marver",
3
- "version": "0.25.1",
3
+ "version": "0.26.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,
@@ -50,11 +50,13 @@
50
50
  "cac": "^7.0.0",
51
51
  "echarts": "^6.1.0",
52
52
  "html-to-image": "^1.11.13",
53
+ "magic-string": "^0.30.21",
53
54
  "marked": "^16.0.0",
54
55
  "mermaid": "^11.6.0",
55
56
  "react-zoom-pan-pinch": "^3.6.1",
56
57
  "roughjs": "^4.6.6",
57
58
  "vite": "^8.0.0",
59
+ "ws": "^8.22.0",
58
60
  "zustand": "^5.0.0"
59
61
  },
60
62
  "peerDependencies": {
@@ -65,6 +67,7 @@
65
67
  "@types/node": "^22.0.0",
66
68
  "@types/react": "^19.0.0",
67
69
  "@types/react-dom": "^19.0.0",
70
+ "@types/ws": "^8.18.2",
68
71
  "tsdown": "^0.22.0",
69
72
  "typescript": "^5.7.0",
70
73
  "vitest": "^3.0.0"
@@ -80,5 +83,8 @@
80
83
  },
81
84
  "publishConfig": {
82
85
  "access": "public"
86
+ },
87
+ "optionalDependencies": {
88
+ "sherpa-onnx-node": "1.13.8"
83
89
  }
84
90
  }
@@ -3,8 +3,11 @@
3
3
  //
4
4
  // The laser / comment-pick / anchor / highlight machinery lives in ./inspect.js and is
5
5
  // shared with the prototype stage; this bridge owns the canvas-frame concerns around it:
6
- // theme, wheel ownership, the interaction lease, data-goto, and error reporting.
6
+ // theme, wheel ownership, the interaction lease, data-goto, and error reporting - and, for Jam
7
+ // captures, the keys the shell owns (keys.js) and the recorder (trail.js).
7
8
  import { createInspect } from './inspect.js'
9
+ import { createKeys } from './keys.js'
10
+ import { createRecorder } from './trail.js'
8
11
 
9
12
  const isHtmlFrame = new URL(import.meta.url).searchParams.get('html') === '1'
10
13
  // same-origin parent (the shell): a fixed target origin keeps posts (incl. picked anchor
@@ -34,9 +37,19 @@ let pointerInside = false
34
37
  let interactiveOn = false // B0.2: set by sh:interactive - the play/interact target owns its own wheel
35
38
  const reportInteraction = () => post({ type: 'sh:interaction', id, laser: pointerInside && inspect.isLaser(), comment: pointerInside && inspect.isPick() })
36
39
 
40
+ // commands come from the SHELL (parent) only - embedded app content must not drive them, and a
41
+ // navigated frame must not spoof them
42
+ const trusted = (e) => e.source === window.parent && window.parent !== window && (!e.origin || e.origin === location.origin)
43
+
44
+ // the capture recorder (trail.js): passive, and silent while no capture is open
45
+ const recorder = createRecorder({ post, getFrame: () => id, mode: 'interact', trusted })
46
+ // the keys the shell owns right now are consumed here and forwarded (keys.js) - ahead of the app
47
+ const keys = createKeys({ post, trusted })
48
+
37
49
  // laser / pick / anchor / highlight - one shared controller (see inspect.js). The id is
38
50
  // static here (one iframe per frame); onModeChange re-reports the lease when a mode flips.
39
- const inspect = createInspect({ post, getId: () => id, onModeChange: () => reportInteraction() })
51
+ // Inside a capture a laser click is the capture's pick, not a path copy.
52
+ const inspect = createInspect({ post, getId: () => id, onModeChange: () => reportInteraction(), onLaserPick: (el, e) => recorder.pick(el, e) })
40
53
 
41
54
  document.addEventListener('mouseover', () => { if (!pointerInside) { pointerInside = true; reportInteraction() } })
42
55
  document.addEventListener('mouseout', (e) => { if (!e.relatedTarget) { pointerInside = false; reportInteraction() } })
@@ -53,6 +66,8 @@ document.addEventListener('click', (e) => {
53
66
  if (target) post({ type: 'sh:go', target })
54
67
  }, true)
55
68
 
69
+ // Escape leaves interact mode - unless the shell owns it right now (a capture, a review): keys.js
70
+ // consumed and forwarded it already, so this never sees it
56
71
  document.addEventListener('keydown', (e) => { if (e.key === 'Escape') post({ type: 'sh:exit-interact' }) })
57
72
 
58
73
  window.addEventListener('error', (e) => post({ type: 'sh:error', id, message: String(e.message || e.error) }))
@@ -69,6 +84,9 @@ window.addEventListener('message', (e) => {
69
84
  // mirrored on the document so content primitives can observe it (Video disarms its
70
85
  // player when the human leaves interact mode - a playing clip must not outlive the mode)
71
86
  document.documentElement.toggleAttribute('data-sh-interactive', interactiveOn)
87
+ // leaving interact leaves the field you were typing in: the next key is a shortcut again, not a
88
+ // letter typed into a frame you are no longer using
89
+ if (!interactiveOn) { const a = document.activeElement; if (a && a !== document.body && typeof a.blur === 'function') a.blur() }
72
90
  }
73
91
  })
74
92
 
@@ -3,4 +3,8 @@ export function createInspect(opts: {
3
3
  post: (msg: Record<string, unknown>) => void
4
4
  getId: () => string
5
5
  onModeChange?: (laser: boolean, pick: boolean) => void
6
+ onLaserPick?: (el: Element, e: MouseEvent) => boolean
6
7
  }): { modeActive: () => boolean; isLaser: () => boolean; isPick: () => boolean; dispose: () => void }
8
+ export function safeBundle(el: Element, point?: { x: number; y: number }): Record<string, unknown>
9
+ export function fieldValue(f: Element): string
10
+ export function sensitiveField(f: Element): boolean
@@ -10,12 +10,14 @@
10
10
  // touches laser/pick/anchor/highlight. It self-installs the pointer + message
11
11
  // listeners and returns { modeActive } so the host can guard its own nav clicks.
12
12
  //
13
- // createInspect({ post, getId, onModeChange? })
13
+ // createInspect({ post, getId, onModeChange?, onLaserPick? })
14
14
  // post(msg) send a message up to the shell (parent)
15
15
  // getId() the frame id to stamp on posts (static on canvas, the
16
16
  // current stage frame in play - it swaps without reload)
17
17
  // onModeChange?() called after any laser/pick flip (the canvas bridge uses it
18
18
  // to report its interaction lease; the stage ignores it)
19
+ // onLaserPick?(el, e) a laser click; returning true means a capture took it as its pick
20
+ // (trail.js) - no sh:laser-copy then
19
21
  //
20
22
  // shell -> frame : sh:laser · sh:pick · sh:copy-ok · sh:resolve-anchors · sh:highlight-anchor
21
23
  // frame -> shell : sh:frame-down · sh:picked · sh:laser-copy · sh:anchor-rects
@@ -113,6 +115,84 @@ const elBundle = (el) => {
113
115
  }
114
116
  }
115
117
 
118
+ // ---- safeBundle: what a capture may carry out of a frame (spec 27, "Nothing secret leaves the frame")
119
+
120
+ const FIELD = 'input, textarea, select'
121
+ const EDITABLE = '[contenteditable]:not([contenteditable="false"])'
122
+ // matched on the words normalised: separators of every kind (spaces, underscores, dots, any Unicode dash)
123
+ // become one hyphen, so "One time code", "one_time", "One‑time code" (U+2011) and "onetime" all read alike
124
+ const SECRET = /pass|secret|token|card|cc-|cvv|cvc|one-?time|otp|security-?code|pin-?code/i
125
+ const secretWords = (s) => SECRET.test(String(s).toLowerCase().replace(/[\s_.\u2010-\u2015\u2212\uFE58\uFE63\uFF0D-]+/g, '-'))
126
+ const MASK = '•••'
127
+
128
+ /** The words a field is known by: its type, name, id, autocomplete, aria-label, labels. */
129
+ const fieldWords = (f) => {
130
+ const out = [f.getAttribute('type'), f.getAttribute('name'), f.id, f.getAttribute('autocomplete'), f.getAttribute('aria-label'), f.getAttribute('placeholder')]
131
+ for (const l of f.labels ?? []) out.push(l.textContent)
132
+ for (const ref of (f.getAttribute('aria-labelledby') ?? '').split(/\s+/)) if (ref) out.push(document.getElementById(ref)?.textContent)
133
+ return out.filter(Boolean).join(' ')
134
+ }
135
+ /** A field that holds a secret: a password, or one whose words say secret, token, card, cvv, one-time code. */
136
+ export const sensitiveField = (f) => f instanceof Element && f.matches(FIELD) && (f.getAttribute('type') === 'password' || secretWords(fieldWords(f)))
137
+
138
+ /** A sensitive context: the element is, contains, or sits inside a field or an editable region, or
139
+ * relates to a secret field (a label for it, an element naming it). Such a bundle keeps only its
140
+ * tag, its source and a css path without attribute values. */
141
+ const sensitive = (el) => {
142
+ if (el.isContentEditable || el.closest(`${FIELD}, ${EDITABLE}`) || el.querySelector(`${FIELD}, ${EDITABLE}`)) return true
143
+ const label = el.closest('label')
144
+ const control = label?.control ?? (el.id ? document.querySelector(`label[for="${CSS.escape(el.id)}"]`)?.control : null)
145
+ if (control && sensitiveField(control)) return true
146
+ for (const ref of [el.getAttribute('aria-controls'), el.getAttribute('aria-describedby')]) {
147
+ const f = ref && document.getElementById(ref)
148
+ if (f && sensitiveField(f)) return true
149
+ }
150
+ return false
151
+ }
152
+ /** The text a person reads in it - every field and editable subtree skipped, whatever it is called. */
153
+ const safeText = (el) => {
154
+ let t = ''
155
+ for (const n of el.childNodes) {
156
+ if (n.nodeType === 3) t += n.data
157
+ else if (n.nodeType === 1 && !n.matches(`${FIELD}, ${EDITABLE}, script, style, noscript, template`)) t += ' ' + safeText(n)
158
+ }
159
+ return t
160
+ }
161
+ /** A css path built from tags and positions only - no id, no attribute value. */
162
+ const plainPath = (el) => {
163
+ const seg = []
164
+ for (let cur = el; cur && cur !== document.body && cur.nodeType === 1; cur = cur.parentElement) {
165
+ const tag = cur.tagName.toLowerCase()
166
+ let n = 1
167
+ for (let sib = cur.previousElementSibling; sib; sib = sib.previousElementSibling) if (sib.tagName === cur.tagName) n++
168
+ seg.unshift(n > 1 ? `${tag}:nth-of-type(${n})` : tag)
169
+ }
170
+ return seg.join(' > ')
171
+ }
172
+
173
+ /** The element as a capture records it - a pick, a click, a hover, a probe answer, a field. Built
174
+ * on elBundle's shape; a sensitive context is masked. `point` (viewport px) adds where it was hit. */
175
+ export function safeBundle(el, point) {
176
+ const r = el.getBoundingClientRect()
177
+ const where = point ? { pos: { fx: r.width ? Math.min(1, Math.max(0, (point.x - r.left) / r.width)) : .5, fy: r.height ? Math.min(1, Math.max(0, (point.y - r.top) / r.height)) : .5 } } : {}
178
+ const rect = { rect: { x: r.left, y: r.top, w: r.width, h: r.height } }
179
+ if (sensitive(el)) {
180
+ return { el: { semantics: { tag: el.tagName.toLowerCase(), role: MASK, ariaLabel: MASK, testId: MASK, quote: MASK }, cssPath: plainPath(el), source: el.dataset?.mvLoc ?? undefined, sensitive: true }, ...where, ...rect }
181
+ }
182
+ const b = elBundle(el)
183
+ b.el.semantics.quote = norm(safeText(el)).slice(0, 200) || undefined
184
+ return { ...b, ...where, ...rect }
185
+ }
186
+
187
+ /** What a field change records: the value only for a text, search, number or select field that is
188
+ * not a secret one; anything else "changed (12 characters)". */
189
+ export function fieldValue(f) {
190
+ const v = typeof f.value === 'string' ? f.value : ''
191
+ const type = (f.getAttribute('type') ?? 'text').toLowerCase()
192
+ const plain = f.matches('select') || (f.matches('input') && ['text', 'search', 'number'].includes(type))
193
+ return plain && !sensitiveField(f) ? v : `changed (${v.length} characters)`
194
+ }
195
+
116
196
  const SKIP = 'script,style,noscript,template'
117
197
  /** The visible elements showing these words (case and spacing aside): the innermost element
118
198
  * whose SEEN text holds them - only text whose own element is shown, with a line break or a block
@@ -243,8 +323,11 @@ const checkTarget = ({ on, at, nth } = {}, others = []) => {
243
323
  }
244
324
  if (typeof window !== 'undefined') window.__mvAnchorCheck = checkTarget
245
325
 
246
- export function createInspect({ post, getId, onModeChange }) {
326
+ export function createInspect({ post, getId, onModeChange, onLaserPick }) {
247
327
  let laserOn = false, pickOn = false
328
+ // the laser as inspect (⌥L): every element outlined. Off, the laser is a pointer - the element under the cursor lit,
329
+ // as comment mode lights it
330
+ let inspectOn = false
248
331
  // quiet pick (⇧L laser comment off): clicks still anchor comments, but NO hover outline,
249
332
  // label, or lock lighting inside the artwork - the shell decides, the frame obeys
250
333
  let pickQuiet = false
@@ -263,14 +346,15 @@ export function createInspect({ post, getId, onModeChange }) {
263
346
  // Both colour by the element's depth hue (--mv-hue lives in the always-on base sheet).
264
347
  const laserCss = () => {
265
348
  let rules = DEPTH_HUE // depth hues live only while a mode is active
266
- if (laserOn)
349
+ if (laserOn && inspectOn)
267
350
  rules += 'body *:not(script):not(style):not(#mv-laser-label):not(#mv-laser-label *) { outline: 1px solid hsl(var(--mv-hue) 85% 55% / .75); outline-offset: -1px }\n'
268
351
  if (pickOn || laserOn)
269
352
  rules += `body, body * { cursor: ${pickOn ? PICK_CURSOR : LASER_CURSOR} !important }\n`
270
353
  // comment mode: the hovered element pops in its OWN hue (outline + fill + ring), so it
271
354
  // reads as "the thing you'll comment on" in the same colour it wears in laser. Laser
272
355
  // keeps its lighter single outline so the whole board stays legible.
273
- const hover = pickOn ? HUE_HL('[data-mv-hover]', '--mv-hue') : `
356
+ // the pointer laser lights the hovered element exactly as comment mode does; inspect keeps its lighter outline
357
+ const hover = pickOn || !inspectOn ? HUE_HL('[data-mv-hover]', '--mv-hue') : `
274
358
  body [data-mv-hover] { outline: 2px solid hsl(var(--mv-hue) 95% 45%); outline-offset: -2px;
275
359
  background-image: linear-gradient(hsl(var(--mv-hue) 95% 50% / .08), hsl(var(--mv-hue) 95% 50% / .08)) }`
276
360
  return rules + hover + `
@@ -299,6 +383,9 @@ body [data-mv-hover] { outline: 2px solid hsl(var(--mv-hue) 95% 45%); outline-of
299
383
  }
300
384
 
301
385
  const applyModes = () => {
386
+ // one mode flag for the whole frame: the capture recorder records no click while it is set,
387
+ // so a pick is recorded once (trail.js)
388
+ window.__mvPick = modeActive()
302
389
  const cur = document.getElementById(LASER_ID)
303
390
  if (!modeActive()) { if (cur) cur.remove(); clearHover(); return }
304
391
  const s = cur ?? document.createElement('style')
@@ -422,7 +509,8 @@ body [data-mv-hover] { outline: 2px solid hsl(var(--mv-hue) 95% 45%); outline-of
422
509
  if (!pickQuiet) applyLock(el, hueOf(el))
423
510
  clearHover()
424
511
  post({ type: 'sh:picked', id: getId(), anchor: anchorBundle(el, e) })
425
- } else {
512
+ } else if (!onLaserPick?.(el, e)) {
513
+ // outside a capture a laser click copies the element's path; inside one it is the capture's pick
426
514
  copyEl = el
427
515
  post({ type: 'sh:laser-copy', id: getId(), seq: ++copySeq, path: cssPath(el), source: el.dataset.mvLoc ?? null })
428
516
  }
@@ -443,7 +531,8 @@ body [data-mv-hover] { outline: 2px solid hsl(var(--mv-hue) 95% 45%); outline-of
443
531
  if (e.origin && e.origin !== location.origin) return // a navigated frame must not spoof shell commands
444
532
  const m = e?.data
445
533
  if (!m || typeof m !== 'object') return
446
- if (m.type === 'sh:laser') { laserOn = !!m.on; applyModes(); onModeChange?.(laserOn, pickOn) }
534
+ // (a shell from before 0.26.1 sends no `inspect`: its laser is the outlined one)
535
+ if (m.type === 'sh:laser') { laserOn = !!m.on; inspectOn = laserOn && (m.inspect === undefined ? true : !!m.inspect); applyModes(); onModeChange?.(laserOn, pickOn) }
447
536
  else if (m.type === 'sh:pick') {
448
537
  pickOn = !!m.on; pickQuiet = !!m.quiet; applyModes()
449
538
  if (pickQuiet) clearHover() // a hover lit before the toggle landed must not linger
@@ -488,6 +577,7 @@ body [data-mv-hover] { outline: 2px solid hsl(var(--mv-hue) 95% 45%); outline-of
488
577
  clearHover(); clearLock()
489
578
  document.getElementById(LASER_ID)?.remove()
490
579
  document.getElementById(BASE_ID)?.remove()
580
+ window.__mvPick = false
491
581
  },
492
582
  }
493
583
  }
@@ -0,0 +1,6 @@
1
+ // Types for keys.js (plain JS: it serves into frames like bridge.js).
2
+ export function inField(t: EventTarget | null): boolean
3
+ export function composing(e: KeyboardEvent): boolean
4
+ export function keyAllowed(e: KeyboardEvent): boolean
5
+ export function keyDescriptor(e: KeyboardEvent): string
6
+ export function createKeys(opts: { post: (msg: Record<string, unknown>) => void; trusted: (e: MessageEvent) => boolean }): { owns: (e: KeyboardEvent) => boolean; dispose: () => void }