@marver-design/marver 0.26.1 → 0.27.2

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 (109) hide show
  1. package/CHANGELOG.md +198 -0
  2. package/README.md +12 -4
  3. package/dist/{anchor-check-l-ny3UzH.mjs → anchor-check-gkxkPAIv.mjs} +1 -1
  4. package/dist/{board-tree-DRioF94d.mjs → board-tree-BXR8dw4b.mjs} +3 -1
  5. package/dist/{boards-CGg6piKF.mjs → boards-BHKP5yhI.mjs} +1 -1
  6. package/dist/{boards-DYG22tOe.mjs → boards-BqUqKNW8.mjs} +4 -4
  7. package/dist/{build-BDRiO_mP.mjs → build-VgNg4rr8.mjs} +8 -23
  8. package/dist/cli.mjs +45 -19
  9. package/dist/{collab-Dxg2trOK.mjs → collab-BEAcXrBb.mjs} +1 -1
  10. package/dist/{comments-BqXua-XL.mjs → comments-YEU1Zhv9.mjs} +4 -4
  11. package/dist/{context-HQ4Giw58.mjs → context-Ccjrhr1J.mjs} +3 -3
  12. package/dist/{daemon-DL6Fwq6D.mjs → daemon-Dc9AH0M3.mjs} +9 -7
  13. package/dist/detect-C0wpaePX.mjs +125 -0
  14. package/dist/dev-lock-C_FC70Mu.mjs +65 -0
  15. package/dist/dev-ri6nAlRp.mjs +1273 -0
  16. package/dist/exclusive-B1RtpeeP.mjs +150 -0
  17. package/dist/{init-D8DtrK_F.mjs → init-W0nxR1OY.mjs} +8 -6
  18. package/dist/{link-BNzLvdhI.mjs → link-CdTgn94Y.mjs} +23 -11
  19. package/dist/ls-BZ5TAtd5.mjs +38 -0
  20. package/dist/{manifest-Nl3KSVOk.mjs → manifest-aFyDmL8C.mjs} +2 -2
  21. package/dist/{marks-DyWMv_Z1.mjs → marks-BF9pNEgH.mjs} +3 -3
  22. package/dist/{marks-CKgzucHZ.mjs → marks-CnCCfAbD.mjs} +3 -3
  23. package/dist/{marver-id-gate-BjF6v4bT.mjs → marver-id-gate-D-R0hSt_.mjs} +1 -1
  24. package/dist/perf-DkAUFT6W.mjs +1319 -0
  25. package/dist/perf-jam-BaH3Lg0m.mjs +635 -0
  26. package/dist/plugin-B8UghYuF.mjs +5242 -0
  27. package/dist/{poster-BdtSKMDm.mjs → poster-BNgafWMK.mjs} +1 -1
  28. package/dist/{profile-WU9qcbIo.mjs → profile-jIS6BcAs.mjs} +1 -1
  29. package/dist/{publish-bakes-9RzRToXV.mjs → publish-bakes-38Nja78p.mjs} +3 -3
  30. package/dist/{queue-29ok5_eZ.mjs → queue-CAM_vNmX.mjs} +1 -1
  31. package/dist/recover-B8AiI29B.mjs +66 -0
  32. package/dist/{serve-C8rVheYk.mjs → serve-Dp3nHstu.mjs} +3 -3
  33. package/dist/{share--oFJ1bCI.mjs → share-Ce4tP7ji.mjs} +1 -1
  34. package/dist/{shot-XQV7HC9A.mjs → shot-CMQgMVZm.mjs} +1 -1
  35. package/dist/{shot-DQeR_Pfn.mjs → shot-Ch24tiMO.mjs} +36 -5
  36. package/dist/slots-CFNnegCc.mjs +478 -0
  37. package/dist/{sync-DKk-yT1V.mjs → sync-CQdGARJ9.mjs} +4 -3
  38. package/dist/{work-VvX_JIgl.mjs → work-Bxz-ObF3.mjs} +4 -2
  39. package/dist/{work-F5u-twpJ.mjs → work-CNhFF9pU.mjs} +5 -3
  40. package/docs/boards-and-folders.md +3 -1
  41. package/docs/jam-session.md +57 -2
  42. package/docs/performance.md +424 -0
  43. package/package.json +2 -2
  44. package/src/client/content/index.tsx +3 -0
  45. package/src/client/content/video.tsx +16 -4
  46. package/src/client/frame-host/bridge.js +22 -6
  47. package/src/client/frame-host/main.tsx +17 -5
  48. package/src/client/shell/App.tsx +188 -26
  49. package/src/client/shell/BoardList.tsx +5 -5
  50. package/src/client/shell/Comments.tsx +8 -5
  51. package/src/client/shell/ContextMenu.tsx +5 -3
  52. package/src/client/shell/JamSurface.tsx +4 -2
  53. package/src/client/shell/LockedApp.tsx +8 -5
  54. package/src/client/shell/Play.tsx +20 -10
  55. package/src/client/shell/Tip.tsx +3 -1
  56. package/src/client/shell/Toolbar.tsx +12 -1
  57. package/src/client/shell/api.ts +233 -0
  58. package/src/client/shell/app-bridge.ts +254 -0
  59. package/src/client/shell/app-perf.ts +92 -0
  60. package/src/client/shell/canvas/Canvas.tsx +141 -21
  61. package/src/client/shell/canvas/FrameNode.tsx +22 -9
  62. package/src/client/shell/canvas/admission.ts +31 -9
  63. package/src/client/shell/canvas/camera-broadcast.ts +15 -5
  64. package/src/client/shell/canvas/ctl.ts +8 -0
  65. package/src/client/shell/canvas/frame-registry.ts +28 -2
  66. package/src/client/shell/canvas/sleep.ts +60 -17
  67. package/src/client/shell/canvas/updates.ts +2 -1
  68. package/src/client/shell/comments-store.ts +12 -4
  69. package/src/client/shell/goto.ts +22 -10
  70. package/src/client/shell/inset.ts +44 -0
  71. package/src/client/shell/jam-capture.ts +41 -22
  72. package/src/client/shell/jam-keys.ts +12 -3
  73. package/src/client/shell/jam-panel.tsx +9 -3
  74. package/src/client/shell/jam-queue.ts +3 -3
  75. package/src/client/shell/jam-session.tsx +14 -8
  76. package/src/client/shell/jam-voice.ts +55 -15
  77. package/src/client/shell/legacy-links.ts +2 -2
  78. package/src/client/shell/main.tsx +18 -1
  79. package/src/client/shell/marks-ui.tsx +5 -3
  80. package/src/client/shell/marver-app.ts +21 -0
  81. package/src/client/shell/notes.ts +8 -1
  82. package/src/client/shell/perf-run-probe.ts +34 -0
  83. package/src/client/shell/perf-run.ts +70 -0
  84. package/src/client/shell/perf.ts +80 -58
  85. package/src/client/shell/recorder-core.ts +183 -0
  86. package/src/client/shell/recorder.ts +607 -0
  87. package/src/client/shell/store.ts +294 -110
  88. package/src/client/shell/styles.css +72 -15
  89. package/src/client/shell/unsaved.ts +81 -0
  90. package/src/client/shell/whiteout-probes.ts +141 -0
  91. package/src/shared/app-api.ts +205 -0
  92. package/src/shared/app-perf.ts +308 -0
  93. package/src/shared/logo-sniff.ts +86 -0
  94. package/src/shared/machine.ts +132 -0
  95. package/src/shared/perf-run.ts +177 -0
  96. package/templates/AGENTS-embedded.md +25 -4
  97. package/templates/AGENTS-studio.md +25 -4
  98. package/templates/demo/dark.tsx +1 -1
  99. package/templates/demo/welcome.tsx +1 -1
  100. package/templates/instructions/boards.md +3 -1
  101. package/templates/instructions/welcome.md +6 -3
  102. package/dist/bake-C-awKgLA.mjs +0 -786
  103. package/dist/config-Cf7EjAMf.mjs +0 -292
  104. package/dist/dev-Bw_qYWWq.mjs +0 -755
  105. package/dist/dev-lock-DWSpa6nj.mjs +0 -179
  106. package/dist/perf-C75MZ73h.mjs +0 -167
  107. package/dist/perf-DPbLGhhO.mjs +0 -49
  108. package/dist/perf-jam-BU3TVrZu.mjs +0 -239
  109. package/dist/plugin-DkGmZs_r.mjs +0 -2423
@@ -0,0 +1,478 @@
1
+ import { r as NAME } from "./cli.mjs";
2
+ import { a as readJson, i as portInUse, o as takeExclusive, r as pidRuns, t as asHolder } from "./exclusive-B1RtpeeP.mjs";
3
+ import { chmodSync, existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
4
+ import { join } from "node:path";
5
+ import { createHash, randomBytes } from "node:crypto";
6
+ import { homedir } from "node:os";
7
+ //#region src/server/workspace.ts
8
+ /**
9
+ * A project's one identity on this Mac (spec 28 A1.6): the first 16 hex of sha256 over its REAL path,
10
+ * so a root reached through a symlink is the same project. CONFIG.workspace, the capture upload's
11
+ * check, the slot file, the preference file and the app's partition all read it.
12
+ *
13
+ * A run holds two values (A1.13 #6): the canonical identity, which picks the project's preference
14
+ * file, and the effective workspace - this run's documents, API, captures and registry record. They
15
+ * differ only in a `--recover` run, which serves under the workspace key an earlier address used.
16
+ *
17
+ * The CLI already hands `dev()` the root's real path (cli/index.ts), so for every canvas started with
18
+ * `npx marver dev` this equals 0.26's key: unsent captures keep their key, and only the origin moves.
19
+ */
20
+ const key = (s) => createHash("sha256").update(s).digest("hex").slice(0, 16);
21
+ /** realpath, or the path itself when it cannot be resolved (never throws at boot). */
22
+ const realRoot = (root) => {
23
+ try {
24
+ return realpathSync(root);
25
+ } catch {
26
+ return root;
27
+ }
28
+ };
29
+ /** The project's canonical identity. */
30
+ const workspaceId = (root) => key(realRoot(root));
31
+ /** 0.26's key, for `--recover` alone: sha256 of the root exactly as it was given (0.26 hashed the
32
+ * given root in plugin.ts and api.ts alike). Equals `workspaceId` for every CLI start. */
33
+ const legacyWorkspace = (root) => key(root);
34
+ const runIdentity = (root, recoverWs) => {
35
+ const real = realRoot(root);
36
+ const id = key(real);
37
+ return {
38
+ root: real,
39
+ id,
40
+ ws: recoverWs ?? id
41
+ };
42
+ };
43
+ const marverHome = () => process.env.MARVER_HOME || join(homedir(), ".marver");
44
+ /** The port before slot 1 - slot n listens on base + n (localhost:4805-4824). MARVER_SLOT_BASE moves
45
+ * the range for the test suite alone: the port check sees every program on this Mac, so a suite on
46
+ * 4805+ would take the slot of a canvas someone is using. */
47
+ function slotBase() {
48
+ const b = Number(process.env.MARVER_SLOT_BASE);
49
+ return process.env.MARVER_SLOT_BASE && Number.isInteger(b) && b >= 1024 && b <= 65515 ? b : 4804;
50
+ }
51
+ const slotPort = (n) => slotBase() + n;
52
+ const slotOfPort = (port) => {
53
+ const n = port - slotBase();
54
+ return n >= 1 && n <= 20 ? n : null;
55
+ };
56
+ /** `~/x` for a path under the home directory - how paths are shown. */
57
+ const tilde = (p) => {
58
+ const h = homedir();
59
+ return p === h ? "~" : p.startsWith(h + "/") ? `~${p.slice(h.length)}` : p;
60
+ };
61
+ const runningDir = () => join(marverHome(), "running");
62
+ const preferDir = () => join(marverHome(), "prefer");
63
+ /** A registry folder, made for writing: mode 700. The home itself is made 700 only when missing (it holds
64
+ * canvases/ and models/ too, and an existing one is never changed). */
65
+ function made(d) {
66
+ mkdirSync(marverHome(), {
67
+ recursive: true,
68
+ mode: 448
69
+ });
70
+ mkdirSync(d, {
71
+ recursive: true,
72
+ mode: 448
73
+ });
74
+ try {
75
+ chmodSync(d, 448);
76
+ } catch {}
77
+ return d;
78
+ }
79
+ const slotFileOf = (n) => join(runningDir(), `slot-${n}.json`);
80
+ const portFileOf = (port) => join(runningDir(), `port-${port}.json`);
81
+ /** Write `file` whole: a private temp file renamed over it. */
82
+ function writeWhole(file, body) {
83
+ const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
84
+ writeFileSync(tmp, body, { mode: 384 });
85
+ try {
86
+ renameSync(tmp, file);
87
+ } catch (err) {
88
+ try {
89
+ unlinkSync(tmp);
90
+ } catch {}
91
+ throw err;
92
+ }
93
+ }
94
+ /** A record read back, or null when the file names no canvas. Lenient on what a later version adds. */
95
+ function asRecord(v) {
96
+ const h = asHolder(v);
97
+ const r = v;
98
+ if (!h || !r || typeof r.port !== "number" || typeof r.url !== "string") return null;
99
+ return {
100
+ v: 1,
101
+ state: r.state === "ready" || r.state === "closing" ? r.state : "starting",
102
+ pid: h.pid,
103
+ instance: h.instance,
104
+ slot: typeof r.slot === "number" ? r.slot : null,
105
+ port: r.port,
106
+ origin: typeof r.origin === "string" ? r.origin : null,
107
+ url: r.url,
108
+ root: typeof r.root === "string" ? r.root : "",
109
+ name: typeof r.name === "string" ? r.name : "",
110
+ version: typeof r.version === "string" ? r.version : "",
111
+ features: Array.isArray(r.features) ? r.features.filter((f) => typeof f === "string") : [],
112
+ ws: typeof r.ws === "string" ? r.ws : "",
113
+ startedAt: typeof r.startedAt === "number" ? r.startedAt : h.at,
114
+ key: typeof r.key === "string" ? r.key : ""
115
+ };
116
+ }
117
+ /** What this version's shell offers the Mac app, written from the `starting` write on (spec 28 A2.14 #15): `bridge` -
118
+ * its shell sends A2.9's hello, theme, menu and `mv:busy` with `unsaved`, so the app's guard can trust what the page
119
+ * reports. A canvas without it (0.27.0) gets the app's degraded guard, which asks first. `inset` (0.27.2, A3.8 #31):
120
+ * its shell takes the top inset under the app's transparent strip, keeps what it means to be read or clicked below
121
+ * it and its scroll edge, and answers the app's presentation requests - so app 0.2 may run it at the window's full
122
+ * height. A canvas without it stays below the strip. */
123
+ const FEATURES = ["bridge", "inset"];
124
+ /** Take one candidate: the file, then - holding it - the port check. */
125
+ async function take(i, slot, port) {
126
+ const file = slot ? slotFileOf(slot) : portFileOf(port);
127
+ made(runningDir());
128
+ const key = randomBytes(32);
129
+ const rec = {
130
+ v: 1,
131
+ state: "starting",
132
+ pid: process.pid,
133
+ instance: i.instance,
134
+ slot,
135
+ port,
136
+ origin: null,
137
+ url: `http://localhost:${port}/`,
138
+ root: i.root,
139
+ name: i.name,
140
+ version: i.version,
141
+ features: [...FEATURES],
142
+ ws: i.ws,
143
+ startedAt: Date.now(),
144
+ key: key.toString("base64url")
145
+ };
146
+ const r = await takeExclusive(file, {
147
+ pid: rec.pid,
148
+ instance: rec.instance,
149
+ at: rec.startedAt
150
+ }, JSON.stringify(rec, null, 2) + "\n", { reclaimWaitMs: i.reclaimWaitMs });
151
+ if (!r.ok) return r.why === "held" ? {
152
+ ok: false,
153
+ why: "held",
154
+ holder: asRecord(readJson(file)),
155
+ file
156
+ } : {
157
+ ok: false,
158
+ why: r.why,
159
+ file
160
+ };
161
+ i.onHold?.(r.release);
162
+ if (await (i.inUse ?? portInUse)(port)) {
163
+ r.release();
164
+ return {
165
+ ok: false,
166
+ why: "busy",
167
+ file
168
+ };
169
+ }
170
+ let now = rec;
171
+ const rewrite = (next) => {
172
+ if (asHolder(readJson(file))?.instance !== rec.instance) return;
173
+ writeWhole(file, JSON.stringify(next, null, 2) + "\n");
174
+ now = next;
175
+ };
176
+ return {
177
+ ok: true,
178
+ claim: {
179
+ slot,
180
+ port,
181
+ file,
182
+ instance: rec.instance,
183
+ key,
184
+ url: rec.url,
185
+ release: r.release,
186
+ ready(origin) {
187
+ if (now.state !== "closing") rewrite({
188
+ ...now,
189
+ state: "ready",
190
+ origin
191
+ });
192
+ },
193
+ closing() {
194
+ if (now.state !== "closing") rewrite({
195
+ ...now,
196
+ state: "closing"
197
+ });
198
+ }
199
+ }
200
+ };
201
+ }
202
+ const canvasOf = (rec) => rec ? `"${rec.name || "?"}" (${tilde(rec.root) || "?"})` : "another canvas";
203
+ const stuckLine = (n) => `slot ${n} is stuck: delete ${tilde(slotFileOf(n))}.reclaim if no canvas is starting`;
204
+ const unreadableLine = (file, n) => `${tilde(file)} is unreadable - ${n ? `slot ${n}` : "that port"} skipped (delete it if no canvas runs there)`;
205
+ /** A slot, any slot: the project's preferred one first, then 1..20. */
206
+ async function anySlot(i, notes) {
207
+ const preferred = readPrefer(i.id)?.slot ?? null;
208
+ const order = [...preferred ? [preferred] : [], ...Array.from({ length: 20 }, (_, k) => k + 1).filter((n) => n !== preferred)];
209
+ for (const n of order) {
210
+ const t = await take(i, n, slotPort(n));
211
+ if (t.ok) return {
212
+ ok: true,
213
+ claim: t.claim,
214
+ notes
215
+ };
216
+ if (t.why === "busy") notes.push(`port ${slotPort(n)} is used by another program - slot ${n} skipped`);
217
+ else if (t.why === "stuck") notes.push(stuckLine(n));
218
+ else if (t.why === "unreadable") notes.push(unreadableLine(t.file, n));
219
+ }
220
+ return {
221
+ ok: false,
222
+ message: [
223
+ `all 20 slots are taken:`,
224
+ ...formatRunning(readRunning()).map((l) => ` ${l}`),
225
+ ...notes,
226
+ "stop one (Ctrl-C in its terminal), or start this one with --port <n>"
227
+ ].join("\n ")
228
+ };
229
+ }
230
+ /** Where this canvas listens: a slot, a port of its own, or --recover's exact one - held as a file before
231
+ * anything binds. */
232
+ async function place(i) {
233
+ if (i.recover) {
234
+ const port = i.recover.port;
235
+ const n = slotOfPort(port);
236
+ const t = await take(i, n, port);
237
+ if (t.ok) return {
238
+ ok: true,
239
+ claim: t.claim,
240
+ notes: []
241
+ };
242
+ const never = "--recover never takes another address";
243
+ return {
244
+ ok: false,
245
+ message: t.why === "held" && t.holder?.state === "closing" ? `port ${port} is held by ${canvasOf(t.holder)}, which is closing - ${never}; run it again once it has stopped` : t.why === "held" ? `port ${port} is held by ${canvasOf(t.holder)} - ${never}; stop it (Ctrl-C in its terminal) and run it again` : t.why === "busy" ? `port ${port} is in use - ${never}; stop what holds it and run it again` : t.why === "stuck" && n ? `${stuckLine(n)} - ${never}` : `${unreadableLine(t.file, n)} - ${never}`
246
+ };
247
+ }
248
+ if (i.explicit) {
249
+ const { port, from } = i.explicit;
250
+ const n = slotOfPort(port);
251
+ if (n) {
252
+ const t = await take(i, n, port);
253
+ if (t.ok) return {
254
+ ok: true,
255
+ claim: t.claim,
256
+ notes: []
257
+ };
258
+ const instead = from === "config" ? "or remove `port` from design/config.ts" : "or start without --port";
259
+ return {
260
+ ok: false,
261
+ message: t.why === "held" && t.holder?.state === "closing" ? `port ${port} is slot ${n}, and ${canvasOf(t.holder)} holds it while it closes - start again once it has stopped, ${instead}` : t.why === "held" ? `port ${port} is slot ${n}, and ${canvasOf(t.holder)} holds it - stop it first (Ctrl-C in its terminal), ${instead}` : t.why === "busy" ? `port ${port} (slot ${n}) is in use by another program - stop it, ${instead}` : t.why === "stuck" ? stuckLine(n) : unreadableLine(t.file, n)
262
+ };
263
+ }
264
+ const t = await take(i, null, port);
265
+ if (t.ok) return {
266
+ ok: true,
267
+ claim: t.claim,
268
+ notes: []
269
+ };
270
+ const placed = await anySlot(i, t.why === "stuck" ? [`${tilde(t.file)}.reclaim is left from a start that crashed: delete it if no canvas is starting`] : t.why === "unreadable" ? [unreadableLine(t.file, null)] : []);
271
+ return placed.ok ? {
272
+ ...placed,
273
+ fellBackFrom: port
274
+ } : placed;
275
+ }
276
+ return anySlot(i, []);
277
+ }
278
+ /** The address a listening server actually bound - `[::1]` or `127.0.0.1`, wildcards mapped to
279
+ * loopback - or null before it listens. */
280
+ const originOf = (a) => {
281
+ if (!a || typeof a === "string") return null;
282
+ return `http://${a.family === "IPv6" ? a.address === "::" ? "[::1]" : `[${a.address}]` : a.address === "0.0.0.0" ? "127.0.0.1" : a.address}:${a.port}`;
283
+ };
284
+ /** 0.26's per-project port in [5200,5399], verbatim - kept only so --recover can offer the address a
285
+ * canvas had before 0.27. Hashes the root exactly as given, as 0.26 did. */
286
+ const legacyPort = (root) => {
287
+ let h = 0;
288
+ for (let i = 0; i < root.length; i++) h = Math.imul(h, 31) + root.charCodeAt(i) | 0;
289
+ return 5200 + Math.abs(h) % 200;
290
+ };
291
+ /** What every `marver dev` since 0.24 writes in design/.local as it starts and keeps once it stops: the sidebar
292
+ * marks (changes.json, seen.json - the dev server their only writer, at every start), the Jam queue, the reload
293
+ * log. No other command writes them, and dev.lock and dev.json go when a canvas stops. Not the daily update check
294
+ * (update-check.json): a start sets it off and does not wait for it, so it lands when it lands - after a failed
295
+ * start has taken back its traces, or while another start reads them - and says nothing of a canvas that ran. */
296
+ const DEV_TRACES = [
297
+ "changes.json",
298
+ "seen.json",
299
+ "jam-jobs.json",
300
+ join("perf", "reloads.jsonl")
301
+ ];
302
+ /** Did a `marver dev` run in this folder before? Read once a start holds the folder's lock, before it writes any of
303
+ * them: with none, a project with no preference file is new, not one 0.26 served - and its first start has nothing
304
+ * to say about 0.26. */
305
+ const ranDevBefore = (root) => DEV_TRACES.some((f) => existsSync(join(root, "design", ".local", f)));
306
+ /** A start that found none of them and never served (a sandbox, a port just taken) takes back those it wrote - the
307
+ * marks (with their deps.json) and the rest - so the folder still reads as one no canvas ran in. */
308
+ const forgetDevTraces = (root) => {
309
+ for (const f of [...DEV_TRACES, "deps.json"]) try {
310
+ rmSync(join(root, "design", ".local", f), { force: true });
311
+ } catch {}
312
+ };
313
+ const HISTORY = 5;
314
+ const preferFileOf = (id) => /^[0-9a-f]{16}$/.test(id) ? join(preferDir(), `${id}.json`) : null;
315
+ const sameAddress = (a, b) => a.url === b.url && a.bind === b.bind && a.ws === b.ws;
316
+ /** The project's preference: undefined when it has none (its first 0.27 run), null when the file is there
317
+ * but unreadable (not a first run; the next write replaces it). */
318
+ function readPrefer(id) {
319
+ const file = preferFileOf(id);
320
+ if (!file) return null;
321
+ const raw = readJson(file);
322
+ if (raw === void 0) return void 0;
323
+ if (!raw || raw.v !== 1 || !(raw.slot === null || Number.isInteger(raw.slot) && raw.slot >= 1 && raw.slot <= 20) || !Array.isArray(raw.history)) return null;
324
+ const history = raw.history.filter((a) => !!a && typeof a.url === "string" && typeof a.bind === "string" && typeof a.ws === "string").map((a) => ({
325
+ url: a.url,
326
+ bind: a.bind,
327
+ ws: a.ws,
328
+ from: Number(a.from) || 0,
329
+ until: Number(a.until) || 0
330
+ }));
331
+ return {
332
+ v: 1,
333
+ slot: raw.slot ?? null,
334
+ history
335
+ };
336
+ }
337
+ /** Record this run's address, after ready: a new entry only when url, bind or ws differ from the newest
338
+ * (so recovery never loses the one it needs); an address it ran on before moves to the front, keeping its
339
+ * first start - five distinct addresses at most. Says whether this is the project's first 0.27 run, and
340
+ * the address it ran on last. */
341
+ function notePrefer(id, run, now = Date.now()) {
342
+ const file = preferFileOf(id);
343
+ if (!file) throw new Error(`not a workspace id: ${id}`);
344
+ const cur = readPrefer(id);
345
+ const previous = cur?.history[0] ? { ...cur.history[0] } : null;
346
+ const before = cur?.history.find((a) => sameAddress(a, run));
347
+ const history = [{
348
+ url: run.url,
349
+ bind: run.bind,
350
+ ws: run.ws,
351
+ from: before?.from ?? now,
352
+ until: now
353
+ }, ...(cur?.history ?? []).filter((a) => !sameAddress(a, run))];
354
+ made(preferDir());
355
+ writeWhole(file, JSON.stringify({
356
+ v: 1,
357
+ slot: run.slot ?? cur?.slot ?? null,
358
+ history: history.slice(0, HISTORY)
359
+ }, null, 2) + "\n");
360
+ return {
361
+ first: cur === void 0,
362
+ previous
363
+ };
364
+ }
365
+ /** This run stopped: its entry's `until` (best effort, synchronous - it runs on exit and on signals). */
366
+ function stopPrefer(id, run, now = Date.now()) {
367
+ try {
368
+ const file = preferFileOf(id);
369
+ const cur = readPrefer(id);
370
+ if (!file || !cur || !cur.history[0] || !sameAddress(cur.history[0], run)) return;
371
+ cur.history[0].until = now;
372
+ writeWhole(file, JSON.stringify(cur, null, 2) + "\n");
373
+ } catch {}
374
+ }
375
+ /** The address 0.26 gave this folder: its hash port, `localhost`, and its key. */
376
+ const legacyEntry = (root, port = legacyPort(root)) => ({
377
+ url: `http://localhost:${port}/`,
378
+ bind: `http://localhost:${port}`,
379
+ ws: legacyWorkspace(root),
380
+ legacy: true
381
+ });
382
+ /** The addresses this project ran on, newest first, then the one 0.26 gave it - always last, because the
383
+ * first 0.27 run has written history by the time anyone acts on its hint (A1.13 #6). */
384
+ function recoverEntries(root) {
385
+ const history = readPrefer(workspaceId(root))?.history ?? [];
386
+ const legacy = legacyEntry(root);
387
+ return history.some((h) => h.url === legacy.url && h.ws === legacy.ws) ? history : [...history, legacy];
388
+ }
389
+ /** What a start says about where this canvas ran before (A1.6) - nothing, when nothing a person could have open
390
+ * there has moved:
391
+ * - its first 0.27 start on a slot, only when a `marver dev` ran in this folder before: a new project has no 0.26
392
+ * address to name;
393
+ * - another link than last time (its slot taken, a port of its own given up): where it was, who runs there now
394
+ * when a canvas does, and how to run there again. A tab still open there keeps its unsaved edits until this
395
+ * canvas answers there, and a Jam capture left unsent waits there too. The link alone counts: the address a run
396
+ * bound (`[::1]` or `127.0.0.1`) is what the Mac app loads, and a browser at the link reaches either. */
397
+ function startedWhere(b) {
398
+ if (b.first) {
399
+ if (!b.ranBefore || !b.run.slot) return [];
400
+ const old = legacyPort(b.root);
401
+ return [`ports are now fixed slots: this canvas is at ${b.run.url}`, ...old !== b.port ? [`0.26 served this canvas at http://localhost:${old}/ - if a Jam capture was left unsent there, \`npx ${NAME} dev --recover\` gets it back`] : []];
402
+ }
403
+ const p = b.previous;
404
+ if (!p || p.url === b.run.url) return [];
405
+ const holder = readRunning().find((r) => r.url === p.url && r.pid !== process.pid && r.state !== "closing");
406
+ const who = holder ? `"${holder.name || "?"}"` : null;
407
+ const n = recoverEntries(b.root).findIndex((e) => e.url === p.url && e.bind === p.bind && e.ws === p.ws) + 1;
408
+ return [
409
+ `last run was at ${p.url}${who ? ` - ${who} runs there now` : ""}`,
410
+ "a tab still open there keeps its unsaved edits until this canvas runs there again (a Jam capture left unsent there waits too):",
411
+ `stop ${who ? `${who} and ` : ""}this canvas, then \`npx ${NAME} dev --recover${n ? ` ${n}` : ""}\``
412
+ ];
413
+ }
414
+ function recoverTarget(e) {
415
+ const b = new URL(e.bind);
416
+ const port = Number(b.port);
417
+ const host = b.hostname === "localhost" ? void 0 : b.hostname.replace(/^\[(.*)\]$/, "$1");
418
+ return {
419
+ port,
420
+ ...host ? { host } : {},
421
+ ws: e.ws,
422
+ url: e.url,
423
+ bind: e.bind
424
+ };
425
+ }
426
+ /** The canvases running on this Mac: every slot and port file whose pid runs, slots by number, then
427
+ * ports. Reads only - a Mac with no registry has none. */
428
+ function readRunning() {
429
+ let names;
430
+ try {
431
+ names = readdirSync(runningDir());
432
+ } catch {
433
+ return [];
434
+ }
435
+ const out = [];
436
+ for (const name of names) {
437
+ if (!/^(slot-\d+|port-\d+)\.json$/.test(name)) continue;
438
+ const file = join(runningDir(), name);
439
+ const rec = asRecord(readJson(file));
440
+ if (!rec || !pidRuns(rec.pid)) continue;
441
+ const { key: _key, instance: _instance, ...pub } = rec;
442
+ out.push({
443
+ ...pub,
444
+ file
445
+ });
446
+ }
447
+ return out.sort((a, b) => (a.slot === null ? 1 : 0) - (b.slot === null ? 1 : 0) || (a.slot ?? a.port) - (b.slot ?? b.port));
448
+ }
449
+ const uptime = (ms) => {
450
+ const s = Math.max(0, Math.floor(ms / 1e3)), m = Math.floor(s / 60), h = Math.floor(m / 60), d = Math.floor(h / 24);
451
+ return d ? `${d}d ${h % 24}h` : h ? `${h}h ${m % 60}m` : m ? `${m}m` : `${s}s`;
452
+ };
453
+ /** The list as `marver ls` prints it: slot, link, name, version, state, uptime, then the folder - last, its length
454
+ * its own, so the columns before it stay on the line. A canvas that is closing is listed, `closing`: it still holds
455
+ * its slot and its folder, so a start there is refused until it has gone, and the list says why. */
456
+ function formatRunning(list, now = Date.now()) {
457
+ const rows = [[
458
+ "slot",
459
+ "link",
460
+ "name",
461
+ "version",
462
+ "state",
463
+ "up",
464
+ "folder"
465
+ ], ...list.map((r) => [
466
+ r.slot === null ? "-" : String(r.slot),
467
+ r.url,
468
+ r.name,
469
+ r.version,
470
+ r.state,
471
+ uptime(now - r.startedAt),
472
+ tilde(r.root)
473
+ ])];
474
+ const widths = rows[0].map((_, c) => Math.max(...rows.map((r) => r[c].length)));
475
+ return rows.map((r) => r.map((cell, c) => c === 0 ? cell.padStart(widths[c]) : cell.padEnd(widths[c])).join(" ").trimEnd());
476
+ }
477
+ //#endregion
478
+ export { notePrefer as a, ranDevBefore as c, recoverTarget as d, startedWhere as f, workspaceId as h, marverHome as i, readRunning as l, runIdentity as m, formatRunning as n, originOf as o, stopPrefer as p, legacyEntry as r, place as s, forgetDevTraces as t, recoverEntries as u };
@@ -2,10 +2,10 @@ import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
2
2
  import { n as diffEvents } from "./events-CLH4ijKP.mjs";
3
3
  import { a as readLog, i as listBoards, t as appendEvents } from "./comments-0BSbb04K.mjs";
4
4
  import { t as CLI_TOKEN_CHARS } from "./auth-Dix8wrXV.mjs";
5
+ import { i as marverHome } from "./slots-CFNnegCc.mjs";
5
6
  import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeSync } from "node:fs";
6
7
  import { join } from "node:path";
7
8
  import { createHash, randomBytes } from "node:crypto";
8
- import { homedir } from "node:os";
9
9
  //#region src/server/sync.ts
10
10
  /**
11
11
  * Dev ↔ published comment sync - one merge rule, run from the dev side.
@@ -43,13 +43,14 @@ var sync_exports = /* @__PURE__ */ __exportAll({
43
43
  *
44
44
  * So the file moved out of reach instead. Under the user's home, keyed by the
45
45
  * absolute path of the project it belongs to, one file per canvas per machine.
46
- * Nothing serves that directory, so there is no path to guard.
46
+ * Nothing serves that directory, so there is no path to guard. (MARVER_HOME moves
47
+ * it with the registry: the test suite's, so no test writes the owner's.)
47
48
  *
48
49
  * The old location is still read once, moved, and removed - a credential left
49
50
  * behind in a repo is exactly the thing being fixed.
50
51
  */
51
52
  const legacyCollabFile = (root) => join(root, "design", ".local", "collab.json");
52
- const collabDir = () => join(homedir(), ".marver", "canvases");
53
+ const collabDir = () => join(marverHome(), "canvases");
53
54
  const collabFile = (root) => {
54
55
  let canonical = root;
55
56
  try {
@@ -1,5 +1,6 @@
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-F5u-twpJ.mjs";
2
+ import { i as readDevInfo, n as WORK_TTL_MAX, t as WORK_TTL_DEFAULT } from "./work-CNhFF9pU.mjs";
3
+ import { unreachable } from "./link-CdTgn94Y.mjs";
3
4
  //#region src/cli/work.ts
4
5
  /**
5
6
  * `marver work` - the coding agent's hand on the canvas working state.
@@ -30,6 +31,7 @@ async function workCommand(root, action, frames, opts) {
30
31
  ...body === void 0 ? {} : { body: JSON.stringify(body) }
31
32
  });
32
33
  } catch {
34
+ if (info.pid !== void 0) throw new Error(`${unreachable(info.pid)} The working glow needs it; the canvas itself is fine - \`npx ${NAME} link <scene/frame>\` still prints its link`);
33
35
  throw new Error(`could not reach \`${NAME} dev\` on port ${info.port} - is it still running?`);
34
36
  }
35
37
  const data = await res.json().catch(() => ({}));
@@ -66,7 +68,7 @@ async function workCommand(root, action, frames, opts) {
66
68
  });
67
69
  console.log(active.length ? `still working: ${active.join(", ")}` : "nothing working - all clear");
68
70
  const done = before.filter((f) => !active.includes(f));
69
- const { links, hints } = done.length ? await (await import("./link-BNzLvdhI.mjs")).handBack(root, done) : {
71
+ const { links, hints } = done.length ? await (await import("./link-CdTgn94Y.mjs")).handBack(root, done) : {
70
72
  links: [],
71
73
  hints: []
72
74
  };
@@ -1,6 +1,6 @@
1
1
  import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
2
- import { s as listBoardFiles } from "./boards-CGg6piKF.mjs";
3
- import { r as pidRuns } from "./dev-lock-DWSpa6nj.mjs";
2
+ import { s as listBoardFiles } from "./boards-BHKP5yhI.mjs";
3
+ import { r as pidRuns } from "./exclusive-B1RtpeeP.mjs";
4
4
  import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
5
5
  import { join } from "node:path";
6
6
  import { randomBytes, randomUUID } from "node:crypto";
@@ -128,13 +128,15 @@ function removeDevInfo(root, instance = written.get(root)) {
128
128
  if (written.get(root) === instance) written.delete(root);
129
129
  } catch {}
130
130
  }
131
+ /** The running server's dev.json: its port and token, and its pid (a file from before 0.26 has none). */
131
132
  function readDevInfo(root) {
132
133
  try {
133
134
  const v = JSON.parse(readFileSync(infoPath(root), "utf8"));
134
135
  if (v?.pid !== void 0 && !pidRuns(v.pid)) return null;
135
136
  return typeof v?.port === "number" && typeof v?.token === "string" ? {
136
137
  port: v.port,
137
- token: v.token
138
+ token: v.token,
139
+ ...typeof v.pid === "number" ? { pid: v.pid } : {}
138
140
  } : null;
139
141
  } catch {
140
142
  return null;
@@ -106,7 +106,9 @@ screen first; a frame off screen waits until you scroll to it, and one you are u
106
106
  drawing a laser, commenting) waits until you are done. A content frame keeps its height while it
107
107
  reloads, so the rows below stay still; if heights did change, the board moves once. The canvas page
108
108
  itself never reloads for a design edit. `npx marver perf` shows what each edit reloaded and how long
109
- it took (from `design/.local/perf/reloads.jsonl`).
109
+ it took (from `design/.local/perf/reloads.jsonl`), and `npx marver perf --loads` what each board load
110
+ did: how long until it settled, how many moves it took on the way, and why
111
+ ([Performance](performance.md)).
110
112
 
111
113
  ## In the files
112
114
 
@@ -27,11 +27,15 @@ dot. While it records, everything you do is part of it:
27
27
 
28
28
  `E` ends it. `Esc` throws it away. One capture records at a time.
29
29
 
30
- Closing or reloading the tab asks first while a capture is recording or finishing. If you leave anyway, the capture
30
+ Closing or reloading the tab asks first while a capture is recording, finishing or not yet taken by the canvas (as it
31
+ does for any unsaved work). If you leave anyway, the capture
31
32
  is kept as it stood - its words and notes so far, and a line saying the page closed before it finished - and comes
32
33
  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
34
  no chance to keep it.)
34
35
 
36
+ A capture the page could not send waits in this browser, for this address, and sends itself the next time the canvas
37
+ opens there - see [A capture left on an old address](#a-capture-left-on-an-old-address).
38
+
35
39
  A capture is about the frames you **touched** - selected, clicked, typed in, scrolled,
36
40
  resized, pictured, or zoomed to alone - not every frame that happened to be on screen. Those
37
41
  are the frames its run may edit, and the frames pictured before and after it.
@@ -178,7 +182,7 @@ The keys work inside frames too, in interactive mode and in play.
178
182
 
179
183
  How long each step takes on your machine - a capture sealing, its pictures, your words, naming, the queue, your agent,
180
184
  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.
185
+ `design/.local/perf/jam.jsonl`: numbers and fixed codes only, never your words ([Performance](performance.md)).
182
186
 
183
187
  The capture itself sits in `design/.local/` (gitignored, never published): its full record
184
188
  and pictures under `design/.local/jam/`, the session transcript under
@@ -192,3 +196,54 @@ comment would. They never reach a published canvas: `marver build` and `marver c
192
196
  leave capture threads (and Marver's notes and replies) on your machine. The session
193
197
  **record** your agent writes goes to `context/sessions/`, also meant to be committed.
194
198
  Published canvases carry none of Jam: no captures, no queue, no microphone.
199
+
200
+ ## A capture left on an old address
201
+
202
+ A capture the page could not send - the canvas was away, or the page closed before its send landed - waits in that
203
+ browser's storage, under that page's address (`http://localhost:<port>`), and goes out the next time the canvas opens
204
+ **at that address** with Live Jam on. When the canvas moves, the capture stays behind: 0.27 moved canvases to slots,
205
+ and a later start lands on another slot when its own is taken. So does a tab still open there with edits it could not
206
+ save: it keeps them until its own canvas answers at that address again. `marver dev` says so as it starts - where it
207
+ was, which canvas runs there now (when one does), and the `--recover` number of that address:
208
+
209
+ ```
210
+ last run was at http://localhost:4806/ - "atlas" runs there now
211
+ a tab still open there keeps its unsaved edits until this canvas runs there again (a Jam capture left unsent there waits too):
212
+ stop "atlas" and this canvas, then `npx marver dev --recover 2`
213
+ ```
214
+
215
+ `--recover` starts the canvas there again. Stop the canvas first if it runs (`Ctrl-C`): one canvas runs per folder, so
216
+ a recovery started beside it stops with "a canvas already runs here". The list works either way:
217
+
218
+ The list holds the last five distinct addresses the canvas ran on (an older one drops off as a sixth arrives), then
219
+ the address 0.26 gave the folder:
220
+
221
+ ```bash
222
+ npx marver dev --recover # the addresses this canvas ran on, newest first
223
+ npx marver dev --recover 2 # start on exactly that one
224
+ ```
225
+
226
+ ```
227
+ addresses this canvas ran on, newest first:
228
+ 1 http://localhost:4807/ bound http://[::1]:4807 22 Oct 15:40 - 22 Oct 17:02
229
+ 2 http://localhost:4806/ bound http://[::1]:4806 21 Oct 09:12 - 21 Oct 18:30
230
+ 3 http://localhost:5329/ the address 0.26 gave it
231
+ start on one: npx marver dev --recover <n> - then open its link in the browser that made the capture
232
+ ```
233
+
234
+ A recovery runs on exactly that entry's port, the address it bound, and the project key that run used - never another.
235
+ Open the link it prints in the browser that made the capture; the captures waiting there send themselves. Then stop it
236
+ (`Ctrl-C`) and start the canvas as usual. If the port or the address cannot be had - another canvas or another program
237
+ holds it - it stops and says why; it never moves elsewhere. A recovery leaves the canvas's list of addresses as it was.
238
+
239
+ **The list always holds the address 0.26 gave this folder** (or would have given it), last unless this canvas has run
240
+ there since. It only matters coming from 0.26. The first 0.27 start of a canvas that ran before names it too ("0.26
241
+ served this canvas at http://localhost:5329/ - if a Jam capture was left unsent there, ..."); a new project's first
242
+ start says nothing of it. If 0.26 had moved to another port when you made the capture
243
+ (it said "port ... is in use - serving ... instead" as it started), name that port:
244
+ `npx marver dev --recover --port <that port>`.
245
+
246
+ **When it cannot come back** - an address that can no longer be had, or a browser profile that is gone - Marver cannot
247
+ send the capture. It is still readable by hand: in the browser's developer tools, under Local storage for that address,
248
+ the key `mv-jam-sealed:<project key>` holds it as JSON; copy what you said into a new capture's notes. A capture only
249
+ waits like this when it could not reach its canvas before the page closed.