@marver-design/marver 0.25.0 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/CHANGELOG.md +75 -0
  2. package/README.md +3 -1
  3. package/dist/{anchor-DVV732zR.mjs → anchor-5H1vnoLu.mjs} +6 -1
  4. package/dist/{anchor-check-BE5VVN6Q.mjs → anchor-check-Dg5xpNnU.mjs} +1 -1
  5. package/dist/audio-CmSRYFEs.mjs +429 -0
  6. package/dist/{auth-DdUKeVKt.mjs → auth-Dix8wrXV.mjs} +1 -1
  7. package/dist/{bake-D8byeRzB.mjs → bake-DtVlm0_F.mjs} +45 -6
  8. package/dist/{boards-Csxj2WJn.mjs → boards-DYG22tOe.mjs} +2 -2
  9. package/dist/{build-BHoWLvSj.mjs → build-C_gUgcdC.mjs} +16 -9
  10. package/dist/capture-CrqvU_jh.mjs +729 -0
  11. package/dist/cli.mjs +23 -17
  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-DZo6o3rU.mjs +2445 -0
  18. package/dist/{dev-DJdgow47.mjs → dev-_Nlsc6v9.mjs} +189 -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-NQi0wZJ4.mjs} +23 -5
  28. package/dist/{marver-id-gate-DGANtVyC.mjs → marver-id-gate-BjF6v4bT.mjs} +4 -4
  29. package/dist/{perf-QJIWtTw1.mjs → perf-D6VmmJ2q.mjs} +1 -1
  30. package/dist/{perf-CCisg-ny.mjs → perf-DPbLGhhO.mjs} +1 -1
  31. package/dist/{plugin-CTyhjwoJ.mjs → plugin-CTD0rydA.mjs} +279 -38
  32. package/dist/{poster-D0cbV7hi.mjs → poster-ChjXGTS5.mjs} +1 -1
  33. package/dist/{profile-Do0nGkXO.mjs → profile-WU9qcbIo.mjs} +1 -1
  34. package/dist/{publish-bakes--l8ot2eQ.mjs → publish-bakes-CEP_2NRc.mjs} +3 -3
  35. package/dist/queue-BuiCKSX1.mjs +1319 -0
  36. package/dist/reserve-BURNQ2Y3.mjs +53 -0
  37. package/dist/{rolldown-runtime-D7D4PA-g.mjs → rolldown-runtime-8H4AJuhK.mjs} +1 -0
  38. package/dist/{serve-wv2QWdxB.mjs → serve-C8rVheYk.mjs} +12 -12
  39. package/dist/session-qZWKt_VA.mjs +191 -0
  40. package/dist/{share-ScamJcks.mjs → share--oFJ1bCI.mjs} +2 -2
  41. package/dist/{shot-jdO_B6Qw.mjs → shot-CNbHoZ6H.mjs} +1 -1
  42. package/dist/{shot-CckrGW-J.mjs → shot-DqcxJibP.mjs} +4 -3
  43. package/dist/speech-models-DomiLQcY.mjs +299 -0
  44. package/dist/speech-worker.mjs +319 -0
  45. package/dist/{summary-CrW88e3q.mjs → summary-Y8MY1Wuc.mjs} +2 -2
  46. package/dist/{sync-C3035OnJ.mjs → sync-DKk-yT1V.mjs} +9 -8
  47. package/dist/{work-GE88wb_3.mjs → work-F5u-twpJ.mjs} +28 -5
  48. package/dist/{work-CpJn1gwY.mjs → work-VvX_JIgl.mjs} +2 -2
  49. package/docs/jam-session.md +177 -0
  50. package/docs/live-jam.md +21 -3
  51. package/package.json +7 -1
  52. package/src/client/frame-host/bridge.js +20 -2
  53. package/src/client/frame-host/inspect.d.ts +4 -0
  54. package/src/client/frame-host/inspect.js +88 -3
  55. package/src/client/frame-host/keys.d.ts +6 -0
  56. package/src/client/frame-host/keys.js +55 -0
  57. package/src/client/frame-host/trail.d.ts +7 -0
  58. package/src/client/frame-host/trail.js +204 -0
  59. package/src/client/shell/App.tsx +45 -5
  60. package/src/client/shell/Comments.tsx +20 -6
  61. package/src/client/shell/JamSurface.tsx +340 -0
  62. package/src/client/shell/Play.tsx +22 -3
  63. package/src/client/shell/Tip.tsx +8 -3
  64. package/src/client/shell/canvas/Canvas.tsx +12 -2
  65. package/src/client/shell/canvas/FrameNode.tsx +11 -2
  66. package/src/client/shell/canvas/sleep.ts +19 -1
  67. package/src/client/shell/comments-store.ts +23 -16
  68. package/src/client/shell/icons.tsx +15 -0
  69. package/src/client/shell/jam-capture.ts +939 -0
  70. package/src/client/shell/jam-keys.ts +329 -0
  71. package/src/client/shell/jam-lane.tsx +208 -0
  72. package/src/client/shell/jam-lines.ts +115 -0
  73. package/src/client/shell/jam-panel.tsx +506 -0
  74. package/src/client/shell/jam-queue.ts +126 -0
  75. package/src/client/shell/jam-session.tsx +389 -0
  76. package/src/client/shell/jam-state.ts +61 -0
  77. package/src/client/shell/jam-surface-parts.tsx +102 -0
  78. package/src/client/shell/jam-ui.tsx +104 -0
  79. package/src/client/shell/jam-voice.ts +479 -0
  80. package/src/client/shell/sound.ts +22 -0
  81. package/src/client/shell/stage-size.ts +11 -0
  82. package/src/client/shell/store.ts +34 -13
  83. package/src/client/shell/styles.css +544 -2
  84. package/src/client/stage/main.tsx +16 -2
  85. package/src/shared/capture-frames.ts +41 -0
  86. package/src/shared/events.ts +19 -4
  87. package/src/shared/speech.ts +16 -0
  88. package/templates/AGENTS-embedded.md +10 -2
  89. package/templates/AGENTS-studio.md +10 -2
  90. package/templates/instructions/iterate.md +8 -6
  91. package/templates/instructions/jam.md +129 -59
  92. package/dist/daemon-Cl8KXGW4.mjs +0 -1523
@@ -0,0 +1,319 @@
1
+ import { createRequire } from "node:module";
2
+ import { parentPort, workerData } from "node:worker_threads";
3
+ //#region src/server/jam/speech-cut.ts
4
+ /**
5
+ * One capture's audio, cut into phrases and transcribed in order (spec 27, Part 4) - the logic, free of
6
+ * the model, so it is tested with a fake VAD and a fake recognizer. Samples are 16 kHz mono, numbered
7
+ * from the capture's start (sample 0 is the mark at `S`): pre-roll can never reach before it.
8
+ *
9
+ * - Silero VAD cuts phrases (0.4 s of silence ends one). Marver also cuts at 15 s: it counts the samples
10
+ * since a phrase began and, at 15 s, calls `vad.flush()` - the next phrase starts at the next sample.
11
+ * - Each phrase keeps 250 ms of the audio before it (the VAD clipped first words), never from before the
12
+ * capture, and never across a forced cut (that audio is already in the phrase before).
13
+ * - At most 30 s of audio waits for transcription; past that the oldest waiting phrase is dropped and
14
+ * the transcript says "[words lost]" where it was.
15
+ * - `end(lastSample)` pads the last partial VAD window with silence (the VAD only takes whole windows),
16
+ * flushes, transcribes what is left, drops any word timed after `lastSample`, and resolves.
17
+ * Raw audio lives only in memory, and only as long as it is needed.
18
+ */
19
+ const RATE = 16e3;
20
+ const PREROLL = Math.round(.25 * RATE);
21
+ /** How much recent audio is kept for pre-roll - a little over the longest phrase plus its pre-roll. */
22
+ const HISTORY = 272e3;
23
+ /** Tokens to words: a token that starts with a space or `▁` starts a word; the word's time is its first
24
+ * token's. */
25
+ function tokensToWords(r, phraseStart) {
26
+ const out = [];
27
+ r.tokens.forEach((t, i) => {
28
+ const at = phraseStart + Math.round((r.timestamps[i] ?? 0) * RATE);
29
+ const starts = /^[\s▁]/.test(t) || !out.length;
30
+ const text = t.replace(/^[\s▁]+/, "");
31
+ if (starts) {
32
+ if (text) out.push({
33
+ w: text,
34
+ at
35
+ });
36
+ } else if (out.length) out[out.length - 1].w += text;
37
+ });
38
+ return out;
39
+ }
40
+ var Segmenter = class {
41
+ pending = /* @__PURE__ */ new Float32Array(0);
42
+ fed = 0;
43
+ history = new Float32Array(HISTORY);
44
+ speech = 0;
45
+ forcedAt = -1;
46
+ skipped = 0;
47
+ gapEnd = 0;
48
+ cancelled = false;
49
+ waiting = [];
50
+ busy = false;
51
+ idle = [];
52
+ last = Infinity;
53
+ ended = false;
54
+ vad;
55
+ recognize;
56
+ onWords;
57
+ constructor(vad, recognize, onWords) {
58
+ this.vad = vad;
59
+ this.recognize = recognize;
60
+ this.onWords = onWords;
61
+ }
62
+ /** The samples from `offset` on (the page numbers them; an overlap is skipped). A short gap is silence
63
+ * given to the VAD; a long one (over a second - a microphone that opened late, a resumed capture) ends
64
+ * the phrase being said and is stepped over whole: every sample keeps its exact number. */
65
+ push(offset, pcm) {
66
+ if (this.ended) return;
67
+ let have = this.fed + this.pending.length;
68
+ if (offset > have && offset - have <= 16e3) {
69
+ this.take(new Float32Array(offset - have));
70
+ have = offset;
71
+ } else if (offset > have) {
72
+ if (this.pending.length) {
73
+ const w = /* @__PURE__ */ new Float32Array(512);
74
+ w.set(this.pending);
75
+ this.pending = /* @__PURE__ */ new Float32Array(0);
76
+ this.window(w);
77
+ }
78
+ this.vad.flush();
79
+ this.drain();
80
+ this.speech = 0;
81
+ if (offset > this.fed) {
82
+ this.skipped += offset - this.fed;
83
+ this.fed = offset;
84
+ }
85
+ this.gapEnd = this.fed;
86
+ have = this.fed;
87
+ }
88
+ const skip = Math.max(0, have - offset);
89
+ if (skip >= pcm.length) return;
90
+ this.take(pcm.subarray(skip));
91
+ }
92
+ take(pcm) {
93
+ let buf = this.pending.length ? concat(this.pending, pcm) : pcm;
94
+ let i = 0;
95
+ for (; i + 512 <= buf.length; i += 512) this.window(buf.subarray(i, i + 512));
96
+ this.pending = buf.slice(i);
97
+ }
98
+ window(w) {
99
+ for (let k = 0; k < w.length; k++) this.history[(this.fed + k) % HISTORY] = w[k];
100
+ this.vad.acceptWaveform(w);
101
+ this.fed += w.length;
102
+ if (this.vad.isDetected()) {
103
+ this.speech += w.length;
104
+ if (this.speech >= 24e4) {
105
+ this.vad.flush();
106
+ this.drain();
107
+ this.forcedAt = this.fed;
108
+ this.speech = 0;
109
+ }
110
+ } else this.speech = 0;
111
+ this.drain();
112
+ }
113
+ /** Phrases the VAD has finished, each with its pre-roll, into the waiting list. */
114
+ drain() {
115
+ while (!this.vad.isEmpty()) {
116
+ const raw = this.vad.front();
117
+ this.vad.pop();
118
+ const seg = {
119
+ start: raw.start + this.skipped,
120
+ samples: raw.samples
121
+ };
122
+ const floor = Math.max(0, this.forcedAt >= 0 && this.forcedAt <= seg.start ? this.forcedAt : 0, this.gapEnd <= seg.start ? this.gapEnd : 0, this.fed - HISTORY);
123
+ const from = Math.max(floor, seg.start - PREROLL);
124
+ const pre = new Float32Array(Math.max(0, seg.start - from));
125
+ for (let k = 0; k < pre.length; k++) pre[k] = this.history[(from + k) % HISTORY];
126
+ this.enqueue({
127
+ start: from,
128
+ samples: pre.length ? concat(pre, seg.samples) : seg.samples
129
+ });
130
+ }
131
+ }
132
+ enqueue(p) {
133
+ this.waiting.push(p);
134
+ while (this.waiting.length > 1 && this.waiting.reduce((n, x) => n + x.samples.length, 0) > 48e4) {
135
+ const gone = this.waiting.shift();
136
+ if (!this.cancelled) this.onWords([{
137
+ w: "[words lost]",
138
+ at: gone.start,
139
+ lost: true
140
+ }]);
141
+ }
142
+ this.run();
143
+ }
144
+ async run() {
145
+ if (this.busy) return;
146
+ this.busy = true;
147
+ try {
148
+ while (this.waiting.length) {
149
+ const p = this.waiting.shift();
150
+ let words = [];
151
+ try {
152
+ words = tokensToWords(await this.recognize(p.samples), p.start);
153
+ } catch {
154
+ words = [{
155
+ w: "[words lost]",
156
+ at: p.start,
157
+ lost: true
158
+ }];
159
+ }
160
+ const kept = words.filter((x) => x.at <= this.last);
161
+ if (kept.length && !this.cancelled) this.onWords(kept);
162
+ }
163
+ } finally {
164
+ this.busy = false;
165
+ if (!this.waiting.length) for (const f of this.idle.splice(0)) f();
166
+ else this.run();
167
+ }
168
+ }
169
+ /** The capture was dropped: everything it holds goes - nothing waiting is transcribed, no word is given. */
170
+ cancel() {
171
+ this.cancelled = true;
172
+ this.ended = true;
173
+ this.last = -Infinity;
174
+ this.waiting = [];
175
+ this.pending = /* @__PURE__ */ new Float32Array(0);
176
+ if (!this.busy) for (const f of this.idle.splice(0)) f();
177
+ }
178
+ /** Audio given and not yet turned into words: phrases waiting, in samples (the worker's backlog). */
179
+ get waitingSamples() {
180
+ return this.waiting.reduce((n, x) => n + x.samples.length, 0);
181
+ }
182
+ /** The capture ended at `lastSample`: the partial window padded with silence, the VAD flushed, the
183
+ * rest transcribed; resolves when every word up to `lastSample` has been given. */
184
+ end(lastSample) {
185
+ if (!this.ended) {
186
+ this.last = lastSample;
187
+ const keep = Math.max(0, Math.min(this.pending.length, lastSample - this.fed));
188
+ if (keep > 0) {
189
+ const w = /* @__PURE__ */ new Float32Array(512);
190
+ w.set(this.pending.subarray(0, Math.min(keep, 512)));
191
+ this.pending = /* @__PURE__ */ new Float32Array(0);
192
+ this.window(w);
193
+ }
194
+ this.pending = /* @__PURE__ */ new Float32Array(0);
195
+ this.ended = true;
196
+ this.vad.flush();
197
+ this.drain();
198
+ }
199
+ return this.busy || this.waiting.length ? new Promise((r) => {
200
+ this.idle.push(r);
201
+ this.run();
202
+ }) : Promise.resolve();
203
+ }
204
+ };
205
+ function concat(a, b) {
206
+ const out = new Float32Array(a.length + b.length);
207
+ out.set(a, 0);
208
+ out.set(b, a.length);
209
+ return out;
210
+ }
211
+ //#endregion
212
+ //#region src/server/jam/speech-worker.ts
213
+ /**
214
+ * The speech worker (spec 27, Part 4): a worker thread, so decoding never blocks the dev server. It
215
+ * loads `sherpa-onnx-node` (an optional dependency) and the checked model once, then runs one Segmenter
216
+ * per capture - Silero VAD for phrases, Parakeet v3 for words.
217
+ *
218
+ * in : { type: 'begin', capture } · { type: 'audio', capture, offset, pcm: Int16Array }
219
+ * { type: 'end', capture, lastSample } · { type: 'drop', capture }
220
+ * out : { type: 'ready' } · { type: 'unavailable', reason } · { type: 'words', capture, words }
221
+ * { type: 'final', capture }
222
+ */
223
+ const port = parentPort;
224
+ const paths = workerData.paths;
225
+ let sherpa;
226
+ let recognizer;
227
+ try {
228
+ sherpa = createRequire(import.meta.url)("sherpa-onnx-node");
229
+ recognizer = new sherpa.OfflineRecognizer({
230
+ featConfig: {
231
+ sampleRate: RATE,
232
+ featureDim: 80
233
+ },
234
+ modelConfig: {
235
+ transducer: {
236
+ encoder: paths.encoder,
237
+ decoder: paths.decoder,
238
+ joiner: paths.joiner
239
+ },
240
+ tokens: paths.tokens,
241
+ numThreads: 2,
242
+ provider: "cpu",
243
+ modelType: "nemo_transducer"
244
+ }
245
+ });
246
+ port.postMessage({ type: "ready" });
247
+ } catch (err) {
248
+ port.postMessage({
249
+ type: "unavailable",
250
+ reason: err.message
251
+ });
252
+ }
253
+ const vadFor = () => new sherpa.Vad({
254
+ sileroVad: {
255
+ model: paths.vad,
256
+ threshold: .5,
257
+ minSpeechDuration: .25,
258
+ minSilenceDuration: .4,
259
+ windowSize: 512
260
+ },
261
+ sampleRate: RATE,
262
+ debug: false,
263
+ numThreads: 1
264
+ }, 30);
265
+ const turn = () => new Promise((r) => setImmediate(r));
266
+ const recognize = async (samples) => {
267
+ await turn();
268
+ const s = recognizer.createStream();
269
+ s.acceptWaveform({
270
+ sampleRate: RATE,
271
+ samples
272
+ });
273
+ recognizer.decode(s);
274
+ const r = recognizer.getResult(s);
275
+ return {
276
+ tokens: r.tokens ?? [],
277
+ timestamps: r.timestamps ?? []
278
+ };
279
+ };
280
+ const captures = /* @__PURE__ */ new Map();
281
+ port.on("message", (m) => {
282
+ if (!recognizer || !m || typeof m.capture !== "string") return;
283
+ const id = m.capture;
284
+ if (m.type === "begin") {
285
+ if (!captures.has(id)) captures.set(id, new Segmenter(vadFor(), recognize, (words) => port.postMessage({
286
+ type: "words",
287
+ capture: id,
288
+ words
289
+ })));
290
+ } else if (m.type === "audio") {
291
+ const seg = captures.get(id);
292
+ if (!seg || !(m.pcm instanceof Int16Array)) return;
293
+ const f = new Float32Array(m.pcm.length);
294
+ for (let i = 0; i < f.length; i++) f[i] = m.pcm[i] / 32768;
295
+ seg.push(m.offset, f);
296
+ } else if (m.type === "end") {
297
+ const seg = captures.get(id);
298
+ if (!seg) {
299
+ port.postMessage({
300
+ type: "final",
301
+ capture: id,
302
+ incomplete: true
303
+ });
304
+ return;
305
+ }
306
+ seg.end(Number(m.lastSample) || 0).then(() => {
307
+ captures.delete(id);
308
+ port.postMessage({
309
+ type: "final",
310
+ capture: id
311
+ });
312
+ });
313
+ } else if (m.type === "drop") {
314
+ captures.get(id)?.cancel();
315
+ captures.delete(id);
316
+ }
317
+ });
318
+ //#endregion
319
+ export {};
@@ -1,5 +1,5 @@
1
- import { r as replay } from "./events-DnK_AnrW.mjs";
2
- import { x as withLock } from "./auth-DdUKeVKt.mjs";
1
+ import { r as replay } from "./events-CLH4ijKP.mjs";
2
+ import { x as withLock } from "./auth-Dix8wrXV.mjs";
3
3
  import { closeSync, fsyncSync, openSync, readFileSync, renameSync, writeSync } from "node:fs";
4
4
  import { join } from "node:path";
5
5
  import { createHash, createPrivateKey, createPublicKey, createVerify, generateKeyPairSync, randomBytes, sign } from "node:crypto";
@@ -1,7 +1,7 @@
1
- import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
2
- import { n as diffEvents } from "./events-DnK_AnrW.mjs";
3
- import { a as readLog, i as listBoards, t as appendEvents } from "./comments-Zoch254k.mjs";
4
- import { t as CLI_TOKEN_CHARS } from "./auth-DdUKeVKt.mjs";
1
+ import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
2
+ import { n as diffEvents } from "./events-CLH4ijKP.mjs";
3
+ import { a as readLog, i as listBoards, t as appendEvents } from "./comments-0BSbb04K.mjs";
4
+ import { t as CLI_TOKEN_CHARS } from "./auth-Dix8wrXV.mjs";
5
5
  import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeSync } from "node:fs";
6
6
  import { join } from "node:path";
7
7
  import { createHash, randomBytes } from "node:crypto";
@@ -305,11 +305,12 @@ async function connectToken(root, url, token) {
305
305
  }
306
306
  /** The thread an event belongs to: a reply names its root; everything else names its comment. */
307
307
  const threadOf = (e) => e.parentId ?? e.commentId ?? "";
308
- /** Threads that live on this machine only: started by Marver (an agent's `comments new`). Every id
309
- * that resolves to one - the thread, and each reply in it (an edit or reaction names the reply) - is
310
- * in the set, so `threadOf` of any event in such a thread hits it. */
308
+ /** Threads that live on this machine only: started by Marver (an agent's `comments new`) or by a Jam
309
+ * capture (its words, spoken or typed - 0.26). Every id that resolves to one - the thread, and each reply
310
+ * in it (an edit or reaction names the reply) - is in the set, so `threadOf` of any event in such a
311
+ * thread hits it. */
311
312
  function localOnlyThreads(events) {
312
- return threadIds(events, (e) => !!e.agent);
313
+ return threadIds(events, (e) => !!e.agent || !!e.capture);
313
314
  }
314
315
  /** Every id that resolves to a thread whose root passes `root` - the thread, and each reply in it. */
315
316
  function threadIds(events, root) {
@@ -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,177 @@
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;
20
+ - **what you do in the prototype**: interactive mode on and off, every click and field, the
21
+ screens you went to in play, the device and theme you switched to, what you copied;
22
+ - **notes** you type (`N` opens the notes card) - a note often names what your words point at;
23
+ - **pictures**: `I` takes one of the frame under the pointer, and the frames you touched are
24
+ pictured as the capture ends - three at most - at the size you were looking at them (a
25
+ device, a width you dragged, the play stage). A capture holds twelve pictures in all.
26
+
27
+ `E` ends it. `Esc` throws it away. One capture records at a time.
28
+
29
+ A capture is about the frames you **touched** - selected, clicked, typed in, scrolled,
30
+ resized, pictured, or zoomed to alone - not every frame that happened to be on screen. Those
31
+ are the frames its run may edit, and the frames pictured before and after it.
32
+
33
+ ## The read-back
34
+
35
+ When a capture ends, its **read-back** opens: the timeline of what you said and did, with its
36
+ pictures, under a short name a small model gave it (see [Names](#names)). Read it, fix a
37
+ mistranscribed word in place, and decide:
38
+
39
+ | Key | |
40
+ |---|---|
41
+ | `⏎` **Add to queue** | it goes to your agent |
42
+ | `K` **Keep** | not work now - kept for the session's record |
43
+ | `R` **Resume** | it ended too soon: carry on recording into the same capture |
44
+ | `Esc` **Drop** | throw it away |
45
+
46
+ A draft's read-back also takes notes after the fact: type in **Add a note** and they are
47
+ logged under "Added after", in the timeline's style, and go to the agent with the rest.
48
+
49
+ `jam: { capture: "at-once" }` skips the read-back: a capture queues as soon as it ends.
50
+
51
+ ## The lane
52
+
53
+ Captures line up along the bottom of the canvas in the order you made them, newest on the
54
+ right - drafts, queued, working, ready to review, done. Each tile says where it is. `Q` gives
55
+ the lane the keyboard: `←` `→` move, `⏎` opens, `⌘⏎` runs a queued one next, `K` keeps,
56
+ `⌫` drops, `Esc` hands the keys back. Right-click a tile to rename it.
57
+
58
+ Your agent works on up to `jam.concurrency` captures at once (6 by default), each in its own
59
+ run, but never two on the same frame: a capture about a frame another run holds waits for it
60
+ ("Queued · next").
61
+
62
+ ## Review
63
+
64
+ When a run finishes, its tile turns to **Ready to review**, with a soft chime (`jam: { chime:
65
+ false }` silences it). `V` opens the next one to review:
66
+
67
+ - **Review** shows the agent's reply beside a picture of each frame it changed - `B` flips
68
+ between before and after; `⌥←` `⌥→` move between frames. A frame the run made is marked
69
+ **New**, with no before.
70
+ - **Capture** (the tab at the top) shows the capture as you made it: its pictures and timeline.
71
+
72
+ `⏎` **Looks good** closes it; `⇧⏎` **More work** sends it back with what is still wrong;
73
+ `→` leaves it for later, `←` goes back. A capture started while a review is open follows that
74
+ run - "and this too".
75
+
76
+ When a capture asked for something new beside a frame - "a laptop version of this, next to
77
+ it" - the frame it pointed at was only where the new one goes. If the run made a new frame
78
+ and left the one you pointed at unchanged, the capture's thread moves onto the new frame
79
+ (when that capture ran alone, so the new frame is surely its own).
80
+
81
+ ## A session: `J`
82
+
83
+ `J` (or the Jam button in the toolbar) opens the start sheet: what Marver listens to, the
84
+ agent the session hands work to, and the keyboard shortcuts. **Start** (`⏎`) begins the
85
+ session and its first capture at once.
86
+
87
+ While a session runs, the canvas keeps its glowing edge and the Jam button its dot and
88
+ clock - seconds the first minute, then minutes - and the lane shows **Jam on**, listening
89
+ between captures. `S` starts the next capture.
90
+
91
+ `J` again wraps up. The wrap-up sheet lists every capture of the session with its state, and
92
+ a box for your instructions on how to take the session in - "prioritise the checkout fixes",
93
+ "file the small ideas as backlog". **Write the record** queues one more job: your agent
94
+ writes a page to `context/sessions/` (or `design/sessions/` without a `context/` folder) -
95
+ what was asked, what was done, what is left, the decisions heard, the ideas worth keeping.
96
+ It reads the confirmed and kept captures, your edits and notes, their replies and your
97
+ verdicts, and, unless you turn it off on the sheet, what you said between captures. **End
98
+ without a record** writes nothing.
99
+
100
+ Sessions are optional: captures, the lane and review all work without one.
101
+
102
+ ## Words, on this Mac
103
+
104
+ The first `S` or `J` asks once whether to use the microphone. Speech becomes words on your
105
+ machine with NVIDIA's Parakeet v3, a small speech-to-text model that runs locally: the first
106
+ time, Marver asks before downloading it (488 MB, once, into `~/.marver/models/`, every file
107
+ checked against its published hash) and keeps it for every canvas. Captures keep recording
108
+ while it downloads; your words start with the next one.
109
+
110
+ - **The audio never leaves this Mac and is never written to disk** - only the words are kept.
111
+ - English, French and the other major European languages are recognised.
112
+ - The speech engine (`sherpa-onnx-node`) is an optional dependency. Where it cannot install
113
+ or load, captures keep typed notes and the canvas says why.
114
+ - **Not now** keeps captures to typed notes; click the crossed-out microphone on a capture's
115
+ tile to be asked again.
116
+
117
+ ## Names
118
+
119
+ With Claude Code as the jam agent, each capture is named as soon as its words are in - a few
120
+ words like "Lamp tablet product page" on its tile, in the lane and on its thread. The name
121
+ comes from Claude Haiku, run through your own Claude Code login with no tools: **a draft's
122
+ words go to Anthropic for this**, as they do when the capture runs. A name you give it
123
+ (Rename) always wins. `jam: { names: false }` turns naming off; tiles then show their first
124
+ words. Other agents do not name captures.
125
+
126
+ ## What your agent receives
127
+
128
+ Each capture reaches your agent as one job: its words with their times, your notes, every UI
129
+ step, the pictures, and the element under each point with its source location
130
+ (`data-mv-loc`, the file and line it was written at, so the agent goes straight there). It
131
+ reads each distinct ask, acts on the reserved frames only, and replies per ask; the reply
132
+ shows in the review, beside the before and after pictures. The managed instructions
133
+ (`design/instructions/jam.md`, refreshed by `npx marver init`) spell this out for the agent.
134
+
135
+ ## Configuration
136
+
137
+ ```ts
138
+ // design/config.ts
139
+ jam: { agent: "claude", concurrency: 6, capture: "confirm", chime: true, names: true, loc: true },
140
+ ```
141
+
142
+ | Key | Default | What it does |
143
+ |---|---|---|
144
+ | `capture` | `"confirm"` | `"confirm"`: a capture waits for its read-back. `"at-once"`: it queues at `E` |
145
+ | `chime` | `true` | A soft chime when a capture is ready to review |
146
+ | `names` | `true` | Name each capture with Claude Haiku (Claude Code only) |
147
+ | `loc` | `true` | Stamp each element of your design files with `data-mv-loc` (dev only, never published) |
148
+
149
+ The rest - `agent`, `concurrency`, `subagents` - is in the [Live Jam guide](live-jam.md#the-config-block).
150
+ A bad value says so at boot and takes the default; nothing here turns Jam off.
151
+
152
+ ## Keys
153
+
154
+ | Where | Keys |
155
+ |---|---|
156
+ | Anywhere on the canvas | `S` capture · `J` session · `Q` the lane · `V` next to review |
157
+ | A capture recording | `E` end · `N` note · `I` picture · `L` laser · `Esc` drop |
158
+ | A read-back | `⏎` add to queue · `K` keep · `R` resume · `Esc` drop |
159
+ | A review | `⏎` looks good · `⇧⏎` more work · `→` later · `←` back · `B` before/after · `⌥←` `⌥→` frames · `Esc` leave |
160
+ | The lane (`Q`) | `←` `→` move · `⏎` open · `⌘⏎` do next · `K` keep · `⌫` drop · `Esc` leave |
161
+
162
+ The keys work inside frames too, in interactive mode and in play.
163
+
164
+ ## Where things are kept
165
+
166
+ The capture itself sits in `design/.local/` (gitignored, never published): its full record
167
+ and pictures under `design/.local/jam/`, the session transcript under
168
+ `design/.local/jam/sessions/`, the queue in `design/.local/jam-jobs.json`.
169
+
170
+ A capture you add to the queue or keep also becomes a **thread** on its board, like a
171
+ comment: a short excerpt of its words (600 characters at most), then your agent's replies.
172
+ Threads live in `design/comments/<board>.jsonl`, which is committed with the rest of
173
+ `design/` - so what you said in a capture reaches your repository when you commit, as a
174
+ comment would. They never reach a published canvas: `marver build` and `marver comments sync`
175
+ leave capture threads (and Marver's notes and replies) on your machine. The session
176
+ **record** your agent writes goes to `context/sessions/`, also meant to be committed.
177
+ 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**.
@@ -166,9 +179,10 @@ at once, and raise the bottom-right pill with a ping - Marver's replies on one b
166
179
  single notice ("2 replies", View walks through them), a message that asks (a note, unless the
167
180
  agent wrote `--fyi`; a reply with `--ask`; a jam reply opened with ```` ```marver-reply ask ````)
168
181
  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
182
+ bubble in the sidebar until the thread is resolved. A plain reply in a note starts nothing - only
183
+ a tag does: tag `@marver` in your reply and it is a jam job, with the note in its brief; while
184
+ the chat agent still has that frame lit (`marver work start`), the job waits for it. Your plain
185
+ 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
186
  collaborator's thread keeps your voice, the one that reaches them on the published canvas.
173
187
 
174
188
  ## Parallelism
@@ -191,6 +205,10 @@ configuration speaking, and marver does not override it.
191
205
 
192
206
  - **It has to be your machine, your repo, with `marver dev` running.** That is the trust
193
207
  boundary above, working as intended.
208
+ - **It has to tag `@marver`.** Since 0.26 a plain reply starts nothing, even in a thread
209
+ Marver started - tag it in the reply.
210
+ - **One canvas per folder.** A second `marver dev` in the same folder stops with "a canvas
211
+ already runs here" and its link, so two servers never run the same jobs twice.
194
212
  - **The first boot after upgrading to 0.9.0 rebaselines the job journal**, because an
195
213
  existing journal predates the device stamp. Any `@marver` left unprocessed while the
196
214
  server was down is marked seen instead of run. Re-comment to pick it up.