@marver-design/marver 0.28.0 → 0.30.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 (105) hide show
  1. package/CHANGELOG.md +103 -0
  2. package/README.md +4 -3
  3. package/dist/{anchor-check-PHUOFj1N.mjs → anchor-check-c52IDkiQ.mjs} +1 -1
  4. package/dist/{build-BsAyLMT1.mjs → build-C3mUtjEn.mjs} +7 -4
  5. package/dist/{capture-DdZ6xgoz.mjs → capture-DEtM4qm5.mjs} +168 -5
  6. package/dist/cli.mjs +11 -11
  7. package/dist/{comments-CrBHPEQl.mjs → comments-XNhMmSSu.mjs} +2 -2
  8. package/dist/{connectors-MR9d-EBP.mjs → connectors-DekQvKt9.mjs} +3 -1
  9. package/dist/{daemon-C5dg2R-V.mjs → daemon-B0Wi1OQ3.mjs} +30 -29
  10. package/dist/{dev-D7YS7iT2.mjs → dev-5dlxoW28.mjs} +19 -14
  11. package/dist/{init-WE5lQkQL.mjs → init-CYlFaRzG.mjs} +1 -1
  12. package/dist/logo-CXY-1yrn.mjs +305 -0
  13. package/dist/{ls-BZ5TAtd5.mjs → ls-NqmePKOf.mjs} +1 -1
  14. package/dist/{marks-Kmdab_5w.mjs → marks-BnNANic9.mjs} +20 -1
  15. package/dist/{marks-Dyn6tmjp.mjs → marks-DBp3h1Mc.mjs} +2 -5
  16. package/dist/{marver-id-gate-D-R0hSt_.mjs → marver-id-gate-vBLb_Icb.mjs} +1 -1
  17. package/dist/{perf-Cn5LiRaY.mjs → perf-6MOTHxay.mjs} +751 -122
  18. package/dist/perf-BCxAo0IS.mjs +1743 -0
  19. package/dist/{plugin-C_0yb-Fq.mjs → plugin-CXRoMA8g.mjs} +1382 -810
  20. package/dist/{poster-DHi6I1fO.mjs → poster-CYmCa00B.mjs} +1 -1
  21. package/dist/{profile-jIS6BcAs.mjs → profile-B1FKOM1e.mjs} +1 -1
  22. package/dist/{publish-bakes-r4PEZuPl.mjs → publish-bakes-C_2ZtHou.mjs} +3 -3
  23. package/dist/{queue-c-6aTHEz.mjs → queue-DeSQm24g.mjs} +29 -14
  24. package/dist/{recover-nrLEVLyJ.mjs → recover-XD8iXJOj.mjs} +2 -2
  25. package/dist/{serve-Dp3nHstu.mjs → serve-DQv3Ti6X.mjs} +8 -4
  26. package/dist/{session-DyVE7cCk.mjs → session-VDJfXEEm.mjs} +1 -1
  27. package/dist/{share-Ce4tP7ji.mjs → share-Bu_kuOKL.mjs} +1 -1
  28. package/dist/{shot-BrRtqaiS.mjs → shot-CRRGgxru.mjs} +3 -3
  29. package/dist/{slots-CFNnegCc.mjs → slots-Dn4Onb0V.mjs} +101 -3
  30. package/dist/{sync-CQdGARJ9.mjs → sync-CMozOwZ0.mjs} +1 -1
  31. package/docs/app.md +194 -0
  32. package/docs/boards-and-folders.md +11 -0
  33. package/docs/jam-session.md +12 -3
  34. package/docs/live-jam.md +3 -0
  35. package/docs/performance.md +99 -19
  36. package/docs/publish.md +7 -0
  37. package/package.json +1 -1
  38. package/src/client/frame-host/bridge.js +17 -8
  39. package/src/client/frame-host/inplace.ts +124 -0
  40. package/src/client/frame-host/inspect.d.ts +1 -0
  41. package/src/client/frame-host/inspect.js +13 -4
  42. package/src/client/frame-host/main.tsx +12 -3
  43. package/src/client/frame-host/messages.ts +85 -0
  44. package/src/client/frame-host/signals.d.ts +15 -0
  45. package/src/client/frame-host/signals.js +219 -0
  46. package/src/client/recorder-level.ts +41 -0
  47. package/src/client/shell/App.tsx +158 -88
  48. package/src/client/shell/BoardList.tsx +103 -48
  49. package/src/client/shell/Comments.tsx +71 -46
  50. package/src/client/shell/ContextMenu.tsx +8 -6
  51. package/src/client/shell/JamSurface.tsx +187 -71
  52. package/src/client/shell/LockedApp.tsx +19 -3
  53. package/src/client/shell/Play.tsx +110 -62
  54. package/src/client/shell/StatusPicker.tsx +19 -9
  55. package/src/client/shell/Toolbar.tsx +15 -7
  56. package/src/client/shell/api.ts +25 -7
  57. package/src/client/shell/app-bridge.ts +23 -9
  58. package/src/client/shell/app-perf.ts +31 -1
  59. package/src/client/shell/canvas/Canvas.tsx +17 -6
  60. package/src/client/shell/canvas/FrameNode.tsx +25 -12
  61. package/src/client/shell/canvas/Sticky.tsx +4 -2
  62. package/src/client/shell/canvas/ctl.ts +2 -0
  63. package/src/client/shell/canvas/ready-watch.ts +4 -0
  64. package/src/client/shell/canvas/sleep.ts +2 -0
  65. package/src/client/shell/canvas/updates.ts +13 -6
  66. package/src/client/shell/commands.ts +765 -0
  67. package/src/client/shell/comments-store.ts +56 -27
  68. package/src/client/shell/goto.ts +15 -9
  69. package/src/client/shell/jam-capture.ts +39 -15
  70. package/src/client/shell/jam-keys.ts +303 -111
  71. package/src/client/shell/jam-lane.tsx +19 -12
  72. package/src/client/shell/jam-lines.ts +10 -1
  73. package/src/client/shell/jam-panel.tsx +68 -53
  74. package/src/client/shell/jam-queue.ts +6 -1
  75. package/src/client/shell/jam-session.tsx +41 -37
  76. package/src/client/shell/jam-state.ts +28 -5
  77. package/src/client/shell/jam-surface-parts.tsx +8 -6
  78. package/src/client/shell/jam-ui.tsx +12 -5
  79. package/src/client/shell/jam-voice.ts +4 -2
  80. package/src/client/shell/live-picture.ts +134 -0
  81. package/src/client/shell/main.tsx +7 -1
  82. package/src/client/shell/marks-ui.tsx +11 -0
  83. package/src/client/shell/open-item.ts +83 -0
  84. package/src/client/shell/open-resolve.ts +50 -0
  85. package/src/client/shell/perf.ts +51 -5
  86. package/src/client/shell/recorder-core.ts +4 -1
  87. package/src/client/shell/recorder-hmr.ts +36 -0
  88. package/src/client/shell/recorder-reloads.ts +264 -0
  89. package/src/client/shell/recorder-seams.ts +116 -0
  90. package/src/client/shell/recorder-self.ts +73 -0
  91. package/src/client/shell/recorder-signals-core.ts +139 -0
  92. package/src/client/shell/recorder-signals.ts +485 -0
  93. package/src/client/shell/recorder.ts +115 -41
  94. package/src/client/shell/store.ts +62 -24
  95. package/src/client/shell/styles.css +2 -0
  96. package/src/client/shell/whiteout-probes.ts +3 -1
  97. package/src/client/stage/main.tsx +39 -12
  98. package/src/shared/app-api.ts +201 -9
  99. package/src/shared/app-perf.ts +103 -8
  100. package/src/shared/app-report.ts +586 -0
  101. package/src/shared/perf-records.ts +445 -0
  102. package/src/shared/perf-run.ts +6 -2
  103. package/templates/instructions/jam.md +4 -0
  104. package/dist/live-Cgzsicwi.mjs +0 -4
  105. package/dist/perf-jam-QxD_UnzN.mjs +0 -635
@@ -1,4 +1,4 @@
1
- import { i as capture, p as findChrome } from "./shot-BrRtqaiS.mjs";
1
+ import { i as capture, p as findChrome } from "./shot-CRRGgxru.mjs";
2
2
  import { constants, copyFileSync, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
3
3
  import { basename, dirname, join, sep } from "node:path";
4
4
  import { pathToFileURL } from "node:url";
@@ -1,4 +1,4 @@
1
- import { i as loadCollab } from "./sync-CQdGARJ9.mjs";
1
+ import { i as loadCollab } from "./sync-CMozOwZ0.mjs";
2
2
  import { readFileSync } from "node:fs";
3
3
  import { join } from "node:path";
4
4
  //#region src/server/profile.ts
@@ -1,7 +1,7 @@
1
1
  import { o as slideSize } from "./cli.mjs";
2
- import { o as ASK_MAX, s as bakeBatch } from "./plugin-C_0yb-Fq.mjs";
3
- import { p as findChrome, s as planShot } from "./shot-BrRtqaiS.mjs";
4
- import { MIME } from "./serve-Dp3nHstu.mjs";
2
+ import { c as ASK_MAX, l as bakeBatch } from "./plugin-CXRoMA8g.mjs";
3
+ import { p as findChrome, s as planShot } from "./shot-CRRGgxru.mjs";
4
+ import { MIME } from "./serve-DQv3Ti6X.mjs";
5
5
  import { copyFileSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
6
6
  import { extname, isAbsolute, join, relative, resolve } from "node:path";
7
7
  import { createServer } from "node:http";
@@ -1,10 +1,10 @@
1
1
  import { n as createExclusive, r as pidRuns } from "./exclusive-B1RtpeeP.mjs";
2
2
  import { r as replay } from "./events-CLH4ijKP.mjs";
3
3
  import { a as readLog, i as listBoards } from "./comments-0BSbb04K.mjs";
4
- import { n as localProfile } from "./profile-jIS6BcAs.mjs";
4
+ import { n as localProfile } from "./profile-B1FKOM1e.mjs";
5
5
  import { a as deviceId, r as owned } from "./ledger-D54iROST.mjs";
6
- import { C as sanitize, T as threadId, _ as buildPacket, f as readCapture, h as wordsSince, l as hashOf, n as captureFrames, p as requestWords, s as factsOf, u as madeOf, y as packetPath } from "./capture-DdZ6xgoz.mjs";
7
- import { i as readWrapup, o as recordPathProblem } from "./session-DyVE7cCk.mjs";
6
+ import { E as threadId, b as packetPath, g as wordsSince, l as hashOf, m as requestWords, n as captureFrames, p as readCapture, s as factsOf, u as madeOf, v as buildPacket, w as sanitize } from "./capture-DEtM4qm5.mjs";
7
+ import { i as readWrapup, o as recordPathProblem } from "./session-VDJfXEEm.mjs";
8
8
  import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
9
9
  import { join } from "node:path";
10
10
  import { randomBytes, randomUUID } from "node:crypto";
@@ -186,12 +186,23 @@ const ctxFor = (root) => ({
186
186
  });
187
187
  const isOwned = (ctx, board, id) => ctx.owned.has(`${board}\t${id}`);
188
188
  const seenKey = (board, id) => `${board}|${id}`;
189
+ /** Every move of a card's state but a requeue's. Entering review or failed from another state begins an episode: one
190
+ * more `att` (spec 28 A4.6 #9), what a live item's id hashes - a heartbeat, a rename or a re-read never changes it. */
189
191
  const set = (c, state, now, note) => {
192
+ if ((state === "review" || state === "failed") && c.state !== state) c.att = (c.att ?? 0) + 1;
190
193
  c.state = state;
191
194
  c.rev += 1;
192
195
  c.at = now;
193
196
  if (note !== void 0) c.note = note;
194
197
  };
198
+ /** The one way a card turns failed (A4.6 #9, r1 #1): `set` it, and when the journal holds its batch, that batch's
199
+ * `failures` one more - so a redelivery that fails again is a new occurrence of the same run. Several cards failing
200
+ * in one write add several: an id is compared, never counted. daemon.ts calls it too, never writing `failed` itself. */
201
+ function failCard(j, c, note, now) {
202
+ set(c, "failed", now, note);
203
+ const b = c.batch ? j.batches.find((x) => x.batchId === c.batch) : void 0;
204
+ if (b) b.failures = (b.failures ?? 0) + 1;
205
+ }
195
206
  const onThread = (j, board, thread) => j.cards.filter((c) => c.board === board && c.thread === thread);
196
207
  /** The frame each thread sits on (a reply names only its thread). */
197
208
  const framesOf = (events) => {
@@ -662,24 +673,24 @@ function wrapupIntact(ctx, c) {
662
673
  /** The wrap-up content a card writes from (a More work card writes from the same, its note added). */
663
674
  const wrapupOf = (c) => c.id;
664
675
  function validate(ctx, c, events, now, j) {
665
- if (c.capture && j && !captureIntact(j, ctx, c.capture)) {
666
- set(c, "failed", now, "the capture changed after it was confirmed - capture it again");
676
+ if (c.capture && !captureIntact(j, ctx, c.capture)) {
677
+ failCard(j, c, "the capture changed after it was confirmed - capture it again", now);
667
678
  return false;
668
679
  }
669
680
  if (c.kind === "capture") {
670
681
  const ok = c.events.every((id) => isOwned(ctx, c.board, id) && events.some((e) => e.id === id));
671
- if (!ok) set(c, "failed", now, "an ask on this capture is no longer the owner's");
682
+ if (!ok) failCard(j, c, "an ask on this capture is no longer the owner's", now);
672
683
  return ok;
673
684
  }
674
685
  if (c.kind === "wrapup") {
675
686
  if (!wrapupIntact(ctx, c)) {
676
- set(c, "failed", now, "the session record changed after it was written - write it again");
687
+ failCard(j, c, "the session record changed after it was written - write it again", now);
677
688
  return false;
678
689
  }
679
690
  const w = readWrapup(ctx.root, c.id);
680
691
  const unsafe = w && recordPathProblem(ctx.root, w.wrapup.file);
681
692
  if (unsafe) {
682
- set(c, "failed", now, `the record's file is not safe to write: ${unsafe}`);
693
+ failCard(j, c, `the record's file is not safe to write: ${unsafe}`, now);
683
694
  return false;
684
695
  }
685
696
  return true;
@@ -956,13 +967,13 @@ function settleOne(j, b, m, p, now, out) {
956
967
  set(c, "done", now, "resolved");
957
968
  out.push({ card: c });
958
969
  } else if ("missing" in r) {
959
- set(c, "failed", now, "the agent did not answer this one");
970
+ failCard(j, c, "the agent did not answer this one", now);
960
971
  out.push({
961
972
  card: c,
962
973
  notice: "failed"
963
974
  });
964
975
  } else if (c.exclusive || (c.shared ?? 0) >= 1) {
965
- set(c, "failed", now, "needed more shared files than it was given");
976
+ failCard(j, c, "needed more shared files than it was given", now);
966
977
  out.push({
967
978
  card: c,
968
979
  notice: "failed"
@@ -981,7 +992,7 @@ function fail(j, b, note, now = Date.now()) {
981
992
  if (!c || c.state !== "working" || c.batch !== b.batchId) continue;
982
993
  if (c.resolved) set(c, "done", now, "resolved");
983
994
  else {
984
- set(c, "failed", now, note);
995
+ failCard(j, c, note, now);
985
996
  out.push({
986
997
  card: c,
987
998
  notice: "failed"
@@ -1003,7 +1014,7 @@ function undelivered(j, b, note, now = Date.now()) {
1003
1014
  const r = b.results?.[m.id];
1004
1015
  if (r && !("body" in r)) settleOne(j, b, m, {}, now, out);
1005
1016
  else {
1006
- set(c, "failed", now, note);
1017
+ failCard(j, c, note, now);
1007
1018
  out.push({
1008
1019
  card: c,
1009
1020
  notice: "failed"
@@ -1116,7 +1127,10 @@ function upgrade(v1, ctx, now = Date.now()) {
1116
1127
  if (b.state === "done") continue;
1117
1128
  if (b.state === "claimed" && b.pgid) fence.push(b.pgid);
1118
1129
  if (!tag) continue;
1119
- j.cards.push(card("failed", b.state === "failed" ? "the agent could not finish - Retry" : "interrupted by the upgrade - Retry"));
1130
+ j.cards.push({
1131
+ ...card("failed", b.state === "failed" ? "the agent could not finish - Retry" : "interrupted by the upgrade - Retry"),
1132
+ att: 1
1133
+ });
1120
1134
  j.batches.push({
1121
1135
  batchId: b.batchId,
1122
1136
  members: [{
@@ -1129,6 +1143,7 @@ function upgrade(v1, ctx, now = Date.now()) {
1129
1143
  leaseUntil: 0,
1130
1144
  attempts: b.attempts,
1131
1145
  ...b.pgid ? { pgid: b.pgid } : {},
1146
+ failures: 1,
1132
1147
  at: now
1133
1148
  });
1134
1149
  }
@@ -1455,4 +1470,4 @@ function createQueue(root, onUpgrade, alive = () => true) {
1455
1470
  };
1456
1471
  }
1457
1472
  //#endregion
1458
- export { ACTIONS, act, addCapture, addWrapup, answeredSince, answers, beginStep, captureComment, captureIntact, conflictStep, createQueue, ctxFor, endSession, endStep, fail, form, joinAlone, looksGood, moreWrapup, releaseLock as n, ownerOnly, payloadKey, pending, prune, redelivering, requeue, runsAlone, sameComment, settle, startSession, stillOwned, acquireLock as t, textOf, undelivered, wrapupIntact, wrapupOf };
1473
+ export { ACTIONS, act, addCapture, addWrapup, answeredSince, answers, beginStep, captureComment, captureIntact, conflictStep, createQueue, ctxFor, endSession, endStep, fail, failCard, form, joinAlone, looksGood, moreWrapup, releaseLock as n, ownerOnly, payloadKey, pending, prune, redelivering, requeue, runsAlone, sameComment, settle, startSession, stillOwned, acquireLock as t, textOf, undelivered, wrapupIntact, wrapupOf };
@@ -1,6 +1,6 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
- import { d as recoverTarget, h as workspaceId, r as legacyEntry, u as recoverEntries } from "./slots-CFNnegCc.mjs";
3
- import { DevStartError, dev } from "./dev-D7YS7iT2.mjs";
2
+ import { d as recoverTarget, r as legacyEntry, u as recoverEntries, v as workspaceId } from "./slots-Dn4Onb0V.mjs";
3
+ import { DevStartError, dev } from "./dev-5dlxoW28.mjs";
4
4
  //#region src/cli/recover.ts
5
5
  /**
6
6
  * `marver dev --recover` (spec 28 A1.6). A Jam capture the page could not send waits in that browser's
@@ -1,4 +1,5 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
+ import { t as logoIconLink } from "./logo-CXY-1yrn.mjs";
2
3
  import { t as secureSuffix } from "./secure-cookie-_K1Hsx8H.mjs";
3
4
  import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
4
5
  import { extname, isAbsolute, join, relative, resolve } from "node:path";
@@ -147,7 +148,7 @@ async function serve(root, portFlag) {
147
148
  console.error(`[${NAME}] MARVER_ID_ISSUER is set but MARVER_PUBLIC_ORIGIN is not.\n Every assertion is bound to this canvas's exact origin, and it cannot be\n inferred from request headers - a proxy can make any request look local.\n Set it to the origin people actually reach this canvas on:\n MARVER_PUBLIC_ORIGIN=https://canvas.example.com\n MARVER_PUBLIC_ORIGIN=http://localhost:${portFlag ?? (Number(process.env.PORT) || 4199)} (development)`);
148
149
  process.exit(1);
149
150
  }
150
- const { marverIdHandler } = await import("./marver-id-gate-D-R0hSt_.mjs");
151
+ const { marverIdHandler } = await import("./marver-id-gate-vBLb_Icb.mjs");
151
152
  const { dataDir } = await import("./comments-0BSbb04K.mjs").then((n) => n.n);
152
153
  const canvasName = humanName(meta.name);
153
154
  const { ceilingsFromRights } = await import("./auth-Dix8wrXV.mjs").then((n) => n.R);
@@ -322,6 +323,11 @@ function isCosmetic(pathname) {
322
323
  const MARK_AT = (size) => `<svg viewBox="0 0 256 256" width="${size}" height="${size}" fill="currentColor" aria-hidden><path d="M239.29,59.28l-64.8,144a8,8,0,0,1-7.3,4.72H24a8,8,0,0,1-7.3-11.28l64.8-144A8,8,0,0,1,88.81,48H232A8,8,0,0,1,239.29,59.28Z" opacity=".1"/><path d="M245.43,47.31A15.94,15.94,0,0,0,232,40H88.81a16,16,0,0,0-14.59,9.43l-64.8,144A16,16,0,0,0,24,216H167.19a16,16,0,0,0,14.59-9.43l64.8-144A16,16,0,0,0,245.43,47.31ZM167.19,200H24L88.81,56H232Z"/></svg>`;
323
324
  const MARK = MARK_AT(17);
324
325
  const MARK_LG = MARK_AT(24);
326
+ /** Marver's own tab icons: the gate's only when the build found no repo logo, whose icon is then the one there is
327
+ * (spec 28 A4.6 #46; release review P2 - beside it, a browser could still pick one of these). */
328
+ const MARVER_ICONS = `<link rel="icon" href="/__mv/favicon/favicon.ico" sizes="48x48" />
329
+ <link rel="icon" type="image/png" sizes="32x32" href="/__mv/favicon/favicon-32x32.png" />
330
+ <link rel="icon" type="image/png" sizes="16x16" href="/__mv/favicon/favicon-16x16.png" />`;
325
331
  /** The gate: the canvas's own antechamber - light ground, dot grid, glass card in the
326
332
  * shell's exact token language. Three doors, one credential each:
327
333
  * guests pay the canvas password, members sign in with their OWN password, and an
@@ -413,9 +419,7 @@ function gate(res, meta, collabOn, error, idOn = false) {
413
419
  ${meta.branding ? "<meta property=\"og:site_name\" content=\"Marver\" />" : ""}
414
420
  <meta property="og:type" content="website" />
415
421
  <meta name="twitter:card" content="summary" />
416
- <link rel="icon" href="/__mv/favicon/favicon.ico" sizes="48x48" />
417
- <link rel="icon" type="image/png" sizes="32x32" href="/__mv/favicon/favicon-32x32.png" />
418
- <link rel="icon" type="image/png" sizes="16x16" href="/__mv/favicon/favicon-16x16.png" />
422
+ ${logoIconLink(meta.logo) || MARVER_ICONS}
419
423
  <link rel="apple-touch-icon" href="/__mv/favicon/apple-touch-icon.png" />
420
424
  <style>
421
425
  * { box-sizing: border-box; margin: 0 }
@@ -1,5 +1,5 @@
1
1
  import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
2
- import { f as readCapture } from "./capture-DdZ6xgoz.mjs";
2
+ import { p as readCapture } from "./capture-DEtM4qm5.mjs";
3
3
  import { appendFileSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, writeSync } from "node:fs";
4
4
  import { dirname, join, relative, sep } from "node:path";
5
5
  import { createHash, randomBytes } from "node:crypto";
@@ -1,6 +1,6 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
2
  import { M as resolveAccess } from "./auth-Dix8wrXV.mjs";
3
- import { i as loadCollab } from "./sync-CQdGARJ9.mjs";
3
+ import { i as loadCollab } from "./sync-CMozOwZ0.mjs";
4
4
  //#region src/cli/share.ts
5
5
  /**
6
6
  * `marver share <action>` - the roster from the terminal (01-sharing §9).
@@ -1,6 +1,6 @@
1
1
  import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
2
2
  import { a as ROUTE, o as slideSize } from "./cli.mjs";
3
- import { t as logJam } from "./perf-jam-QxD_UnzN.mjs";
3
+ import { d as logJam } from "./perf-BCxAo0IS.mjs";
4
4
  import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
5
5
  import { join } from "node:path";
6
6
  import { randomBytes } from "node:crypto";
@@ -524,8 +524,8 @@ async function shootFrame(opts) {
524
524
  };
525
525
  const plan = planShot(frame, viewports, size);
526
526
  if (frame.kind !== "html") try {
527
- const { scanAssetRefs } = await import("./build-BsAyLMT1.mjs");
528
- const { ensurePoster } = await import("./poster-DHi6I1fO.mjs");
527
+ const { scanAssetRefs } = await import("./build-C3mUtjEn.mjs");
528
+ const { ensurePoster } = await import("./poster-CYmCa00B.mjs");
529
529
  const refs = scanAssetRefs(readFileSync(join(root, frame.file), "utf8"), frame.file);
530
530
  for (const r of refs) if (r.endsWith(".poster.png")) await ensurePoster(join(root, "design", "assets"), r.slice(0, -11));
531
531
  } catch {}
@@ -40,6 +40,92 @@ const runIdentity = (root, recoverWs) => {
40
40
  ws: recoverWs ?? id
41
41
  };
42
42
  };
43
+ //#endregion
44
+ //#region src/shared/app-api.ts
45
+ /** Reasons a page is busy (A2.14 #18). The first five are unsaved work; the last three are busy, not unsaved. */
46
+ const UNSAVED_WHY = [
47
+ "capture-recording",
48
+ "capture-unsent",
49
+ "board-unsaved",
50
+ "heights",
51
+ "typing"
52
+ ];
53
+ const BUSY_ONLY_WHY = [
54
+ "jam-session",
55
+ "microphone",
56
+ "agent"
57
+ ];
58
+ [...UNSAVED_WHY, ...BUSY_ONLY_WHY];
59
+ /** Bounds main checks again (A2.14 #19): unknown fields are stripped, a known one of the wrong type or past its bound refuses the message. */
60
+ const BOUNDS = {
61
+ version: 32,
62
+ versionChars: /^[0-9A-Za-z.+-]+$/,
63
+ board: 128,
64
+ page: /^[A-Za-z0-9_-]{8,64}$/,
65
+ doc: /^[A-Za-z0-9_-]{16,64}$/,
66
+ menuItems: 40,
67
+ menuId: /^[a-z][a-z0-9-]{0,31}$/,
68
+ label: 48,
69
+ hint: 8,
70
+ /** A3.8 #27: an epoch is an integer 0..epoch; a presentation viewport's sides are 0..viewport CSS px; `frames` 1..frames */
71
+ epoch: 2 ** 31 - 1,
72
+ viewport: 2e4,
73
+ frames: 8,
74
+ /** A4.6 #35, #37: a live picture's long side at most (main scales down to it; the server refuses past it), and
75
+ * main's deadline for one capture */
76
+ captureLong: 4096,
77
+ captureMs: 1500
78
+ };
79
+ /**
80
+ * What a slot file's `features` say a canvas offers the Mac app (src/server/slots.ts `FEATURES`; the app reads each
81
+ * registry entry's). A name is a version (A4.6 #2): a breaking change to its contract takes a new name (`live2`),
82
+ * never a new meaning for this one, and `bridge` and `inset` imply none of the others. An app ignores a name it does
83
+ * not know (A1.3), and asks nothing of a canvas that does not list one (A4.6 #3).
84
+ */
85
+ const FEATURE = {
86
+ /** 0.27.1 (A2.9, A2.14 #15): the shell says hello, theme, menu and `mv:busy` with `unsaved` */
87
+ bridge: "bridge",
88
+ /** 0.27.2 (A3.8 #31): the shell takes the top inset under the strip and answers presentation requests */
89
+ inset: "inset",
90
+ /** 0.29.0 (A4.6 #5, #6, #11): the server answers `GET /__mv/app/live` (`LIVE_WIRE`) with `LiveEvent` v1 */
91
+ live: "live",
92
+ /** 0.29.0 (A4.6 #29, #30): the shell handles `mv:open` and answers `mv:opened` */
93
+ open: "open",
94
+ /** 0.29.0 (A4.6 #33-#37): the shell asks `mv:capture` for live pictures and the server takes `POST /api/jam/picture/live` */
95
+ capture: "capture"
96
+ };
97
+ /**
98
+ * The bounds both sides keep (A4.6 #11, #16): the server's selector and encoder write within them, and main checks
99
+ * every field again, stripping unknown ones and dropping an item of an unknown kind (not the event). `eventBytes`:
100
+ * the event as written (`event: live`, its `data:` line, the blank line) in UTF-8 bytes - the encoder drops the
101
+ * oldest whole items until it fits, and main drops a connection whose event is longer.
102
+ */
103
+ const LIVE_BOUNDS = {
104
+ items: 100,
105
+ title: 140,
106
+ note: 140,
107
+ ref: 128,
108
+ cards: 8,
109
+ eventBytes: 65536,
110
+ id: /^(ask|review|failed|stalled):[0-9a-f]{20}$/
111
+ };
112
+ /**
113
+ * The live stream's wire (A4.6 #5, #6, #14). `GET <origin><path>` with `x-mv-ws`, a fresh `x-mv-nonce` and
114
+ * `x-mv-app` = `appProof(key, port)`; the 200 is `text/event-stream` carrying `x-mv-instance` and `x-mv-proof` =
115
+ * `liveProof(key, nonce, port)` (src/server/proof.ts). Each snapshot is `event: <event>`, one `data:` line of
116
+ * `LiveEvent` JSON, then a blank line; `<heartbeat>` is a comment line every `heartbeatMs`. No `Last-Event-ID`, no
117
+ * `retry:`. At most `clients` at once (one more ends the oldest); a client with more than `slowBytes` unsent is
118
+ * dropped and reconnects.
119
+ */
120
+ const LIVE_WIRE = {
121
+ path: "/__mv/app/live",
122
+ type: "text/event-stream",
123
+ event: "live",
124
+ heartbeat: ": hb",
125
+ heartbeatMs: 3e4,
126
+ clients: 4,
127
+ slowBytes: 65536
128
+ };
43
129
  const marverHome = () => process.env.MARVER_HOME || join(homedir(), ".marver");
44
130
  /** The port before slot 1 - slot n listens on base + n (localhost:4805-4824). MARVER_SLOT_BASE moves
45
131
  * the range for the test suite alone: the port check sees every program on this Mac, so a suite on
@@ -119,8 +205,20 @@ function asRecord(v) {
119
205
  * 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
206
  * its shell takes the top inset under the app's transparent strip, keeps what it means to be read or clicked below
121
207
  * 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"];
208
+ * height. A canvas without it stays below the strip. The names are app-api.ts's `FEATURE`, read by the app too.
209
+ *
210
+ * A4 (0.29.0, A4.6 #2) adds `live`, `open` and `capture` - each a frozen contract, described at `FEATURE`. A name here
211
+ * is a promise the app acts on (it opens a stream, sends `mv:open`, answers `mv:capture`), so each A4 stream adds its
212
+ * own name here once its half works, never before: `live` (app-live.ts), `open` (the shell's open-item.ts) and
213
+ * `capture` (the shell asks for live pictures in play and the server takes `POST /api/jam/picture/live`:
214
+ * live-picture.ts, api.ts). */
215
+ const FEATURES = [
216
+ FEATURE.bridge,
217
+ FEATURE.inset,
218
+ FEATURE.live,
219
+ FEATURE.open,
220
+ FEATURE.capture
221
+ ];
124
222
  /** Take one candidate: the file, then - holding it - the port check. */
125
223
  async function take(i, slot, port) {
126
224
  const file = slot ? slotFileOf(slot) : portFileOf(port);
@@ -475,4 +573,4 @@ function formatRunning(list, now = Date.now()) {
475
573
  return rows.map((r) => r.map((cell, c) => c === 0 ? cell.padStart(widths[c]) : cell.padEnd(widths[c])).join(" ").trimEnd());
476
574
  }
477
575
  //#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 };
576
+ export { runIdentity as _, notePrefer as a, ranDevBefore as c, recoverTarget as d, startedWhere as f, LIVE_WIRE as g, LIVE_BOUNDS as h, marverHome as i, readRunning as l, BOUNDS as m, formatRunning as n, originOf as o, stopPrefer as p, legacyEntry as r, place as s, forgetDevTraces as t, recoverEntries as u, workspaceId as v };
@@ -2,7 +2,7 @@ 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
+ import { i as marverHome } from "./slots-Dn4Onb0V.mjs";
6
6
  import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeSync } from "node:fs";
7
7
  import { join } from "node:path";
8
8
  import { createHash, randomBytes } from "node:crypto";
package/docs/app.md ADDED
@@ -0,0 +1,194 @@
1
+ # Marver for Mac
2
+
3
+ Marver for Mac shows every canvas you run on this Mac in one window, a tab each, and tells you when one needs you.
4
+ It shows the canvases you run and starts none: a canvas still runs from its repo with `npx marver dev`, and stops
5
+ there. A shared canvas's https link opens in a tab of its own too.
6
+
7
+ **[Download Marver for Mac](https://github.com/TNEP4/marver-app/releases/latest/download/Marver-arm64.dmg)** ·
8
+ Apple silicon · macOS 13 or later
9
+
10
+ Help > Marver Help opens this page. The app's source is [`app/`](../app) in this repository; its releases, each with
11
+ what changed, are in [TNEP4/marver-app](https://github.com/TNEP4/marver-app/releases).
12
+
13
+ ## What it needs
14
+
15
+ - **A Mac with Apple silicon and macOS 13 (Ventura) or later.** On an Intel Mac, or on macOS 12 or older, it does not
16
+ open at all ([below](#on-an-intel-mac-or-an-older-macos)).
17
+ - **Canvases on Marver 0.27 or later.** They show in the app, a tab each, and closing, reloading or quitting asks
18
+ before losing their unsaved work. Marks, notices and live pictures need **0.29 or later**, the version to use with
19
+ the app. A canvas on 0.26 or older does not appear: update it with `npm i -D @marver-design/marver@latest`.
20
+
21
+ ## Install
22
+
23
+ 1. Download [Marver-arm64.dmg](https://github.com/TNEP4/marver-app/releases/latest/download/Marver-arm64.dmg)
24
+ (Apple silicon · macOS 13 or later). Every release has this name, so the link always fetches the latest; the disk
25
+ image it opens is named for its version, "Marver 1.0.0". Safari may first ask whether to allow downloads from
26
+ GitHub's download site: allow it.
27
+ 2. Open it and drag Marver onto Applications.
28
+ 3. Eject the disk image.
29
+ 4. Open Marver from Applications. macOS asks once, because the app was downloaded: whether to open an app
30
+ "downloaded from the Internet", adding that "Apple checked it for malicious software and none was detected".
31
+ Marver is signed with a Developer ID and notarised by Apple. Choose Open; that is the only question.
32
+
33
+ **Opening it straight from the disk image works too.** macOS asks there first (Open, Show Disk Image, Cancel). Marver
34
+ then moves itself into Applications without asking, quits and opens from there, so macOS asks its question a second
35
+ time, at the copy in Applications. Dragging it in first saves that second question. Once moved, the tab strip says
36
+ once: "**Marver moved itself to Applications.** You can eject the disk image." Opened from another folder, such as
37
+ Downloads, Marver moves itself the same way and says "You can delete the copy in Downloads." It never deletes the copy
38
+ it came from.
39
+
40
+ **When something is already in Applications**, Marver moves nothing. It says what it found, and what to do:
41
+
42
+ | In Applications | Marver says | Then |
43
+ |---|---|---|
44
+ | a Marver of this version or newer | "Marver 1.0.1 is already in Applications" | "Open it, and this copy quits. You can delete this copy afterwards." Open It or Cancel |
45
+ | an older Marver | "An older Marver (0.3.0) is in Applications" | "To replace it, drag this Marver into Applications and choose Replace." Show Both or Cancel |
46
+ | another app named Marver | "Another app named Marver is in Applications" | "Marver doesn't replace it. Move it out of Applications, then drag this Marver in." Show Both or Cancel |
47
+ | an empty folder named Marver.app | "An empty folder named Marver.app is in Applications" | "Move that empty folder to the Trash, then open the download again." Show Both or Cancel |
48
+ | anything else of that name | "Something named Marver.app is in Applications" | "Marver doesn't replace what it doesn't know. Move it out of Applications, then drag this Marver in." Show Both or Cancel |
49
+ | nothing, but this account can't add apps there | "Marver can't add itself to Applications" | "This account can't add apps to Applications. Drag Marver into Applications in Finder: it asks for an administrator's name and password." Show Both or Cancel |
50
+
51
+ Show Both shows this copy and what is in Applications in Finder, for the drag. Marver never replaces, renames or
52
+ deletes what is in Applications, and never asks for an administrator's password itself: when one is needed (an older
53
+ Marver this account can't change, say), Finder asks. Cancel opens Marver where it is, and it asks again the next time.
54
+ A Marver that runs outside Applications works, but does not update itself. The Applications folder in your home folder
55
+ (`~/Applications`) counts too: a Marver there is not moved, and updates itself.
56
+
57
+ ## An earlier Marver
58
+
59
+ A Marver before 1.0 (any 0.x, `~/Applications/Marver.app` included) has no updater, so it is replaced once, by hand:
60
+
61
+ 1. Quit it. While one Marver runs, opening another only brings the running one forward.
62
+ 2. Install 1.0 as above. An older Marver in Applications is the "An older Marver" case: drag 1.0 over it and choose
63
+ Replace.
64
+ 3. Drag any other old copy to the Trash, so you never open it by mistake.
65
+
66
+ Your settings and tabs stay: every version keeps them in the same folders ([Uninstalling](#uninstalling)).
67
+
68
+ ## First launch
69
+
70
+ Marver opens on Home. With no canvas running, Home says how to start one: `npx marver dev` in a repo with Marver ("It
71
+ appears here, with its own tab, a second after it starts."), and for a repo without Marver yet, `npm i -D
72
+ @marver-design/marver && npx marver init` first. Each command has a button that copies it. Every canvas running on
73
+ this Mac gets its own tab; `⌘L`, or Home's field, opens a link - a local canvas's, or a shared canvas's.
74
+
75
+ ## What it asks, and when
76
+
77
+ - **Notices.** Nothing touches macOS's notices or the Dock before you choose. The first time a canvas needs you while
78
+ Marver's window is in front, the strip offers "Get a notice when a canvas needs you": Turn On, and macOS asks then;
79
+ Not now, and it never offers again. Settings' Notices row turns them on or off later.
80
+ - **The microphone.** macOS asks the first time a canvas listens, at your first Jam session or capture with the
81
+ microphone on, giving Marver's reason: "Marver uses the microphone only during a Jam session you start."
82
+
83
+ ## Updates
84
+
85
+ Marver keeps itself up to date from the Applications folder. It checks 30 seconds after it opens, every 4 hours and
86
+ when the Mac wakes, and downloads an update quietly; a check that finds nothing says nothing. **Marver > Check for
87
+ Updates…** checks now and answers in the strip: "Marver 1.0.0 is up to date", "Couldn't check for updates · You're
88
+ offline" or "Couldn't check for updates · Try again later". While it works, the item reads Checking for Updates… or
89
+ Downloading Update….
90
+
91
+ **When an update is ready**, the strip says "1.0.1 is ready" with **Restart to Update** (its tooltip is the first line
92
+ of what changed), and the Marver menu reads Restart to Install Update. Two ways to install it:
93
+
94
+ - **Restart to Update** closes your canvases as a quit does, installs the update and opens the new Marver. A canvas
95
+ with unsaved work - an unsent capture, an edit not yet saved - holds it: its tab comes forward saying "**Unsaved
96
+ work here** the update waits", and from any other tab the strip says "1.0.1 waits for Checkout" (that canvas's
97
+ name) with Try Again. Once that work is saved, or its tab closed, the strip is back to "1.0.1 is ready": press
98
+ Restart to Update again. A canvas the app can't read, such as a shared one, asks first, as it does at a quit
99
+ ("Restart to update anyway?"). Marver never restarts by itself.
100
+ - **Quit Marver.** A plain quit installs the downloaded update: the next time you open Marver, it is the new version.
101
+
102
+ **After an update, Marver opens as it does after a quit.** With Settings' "Reopen tabs at launch" on (the default),
103
+ each running canvas gets its tab back on the board it showed, and Settings if it was open; with it off, Marver starts
104
+ on Home and every running canvas still gets its tab. Shared canvases do not come back in tabs (Home's Shared canvases
105
+ reopens them), and a canvas that is not running gets no tab. What a page held only in memory, such as an open panel or
106
+ a scroll position, does not come back. The first launch after says "Updated to 1.0.1", once.
107
+
108
+ **Where it updates.** Only from an Applications folder, and only where this account can change Marver and its
109
+ folder: Marver never asks for an administrator's password to update. Otherwise the Marver menu says why, in place of
110
+ Check for Updates…:
111
+
112
+ | The menu | Its alert |
113
+ |---|---|
114
+ | Updates Need the Applications Folder… | "Marver updates itself only from the Applications folder" - "This Marver runs from ~/Downloads. Quit it, move it to Applications, and open it from there: it then checks for updates on its own." OK or Show in Finder |
115
+ | Updates Unavailable… | "Marver can't update itself here" - "Updating replaces Marver where it is, and this account can't change /Applications. Download the latest Marver and install it again to update." OK or Download |
116
+ | Updates Unavailable… | "Marver can't check for updates" - "Its updater couldn't start on this Mac. Download the latest Marver to update by hand." OK or Download |
117
+
118
+ **If an update goes wrong:**
119
+
120
+ - The restart can fail before Marver ends: "Marver couldn't restart to install 1.0.1" - "Your canvases were closed
121
+ safely. Open Marver again: it may already be 1.0.1, and if not, it tells you how to get it." Quit, then open Marver.
122
+ - When the update did not install, Marver opens as the version it was and the strip says "1.0.1 couldn't be
123
+ installed", with Download, which fetches the latest disk image in your browser. Open it, drag Marver into
124
+ Applications and choose Replace.
125
+ - **If Marver won't open after an update**, download
126
+ [the disk image](https://github.com/TNEP4/marver-app/releases/latest/download/Marver-arm64.dmg) again, open it,
127
+ drag Marver into Applications and choose Replace. Your settings and tabs stay.
128
+
129
+ ## The performance report
130
+
131
+ When Marver is slow, crashes or flashes, a report helps find out why. **Help > Export Performance Report…** (also on a
132
+ canvas's page that keeps crashing, beside Copy Details) opens a save panel on
133
+ `~/Downloads/Marver-report-YYYY-MM-DD.json`, writes the file and shows it in Finder. Nothing is uploaded, and the file
134
+ is JSON you can read before you send it. If it cannot be saved, an alert says why ("The performance report wasn't
135
+ saved") and no half-written file is left.
136
+
137
+ **What it holds:** the last 7 days of the app's own records in `~/.marver/perf/` (fewer when Settings' "Keep
138
+ performance files" keeps fewer):
139
+
140
+ - when it was made, and the app's, Electron's and macOS's versions;
141
+ - your Mac: its chip, cores, memory, model and macOS version, and each display's scale and refresh rate;
142
+ - one row per hour: the app's own CPU and memory, the canvases' memory, the GPU process's memory, the highest memory
143
+ pressure and the worst thermal state;
144
+ - events, newest first, at most 2,000: a page or a helper process that crashed or stopped answering, the GPU
145
+ restarting or changing, power and heat, memory pressure, tabs unloaded and reopened, the flashes you marked (whether
146
+ a picture was kept, never the picture), the updater's and the move's steps, and an error in the app by its type
147
+ alone (such as `TypeError`);
148
+ - how long tab switches took, per day, and how many crash reports the app kept;
149
+ - for each part, whether it was read whole.
150
+
151
+ A tab appears only as an opaque id, such as `t3`.
152
+
153
+ **What it never holds:** board, canvas or file names; paths, hosts or links; error messages or stack traces; process
154
+ names or ids; pictures; traces or crash dumps. Board loads and headless runs are not in it either: they stay in each
155
+ repo, where `npx marver perf` shows them ([Performance](performance.md)).
156
+
157
+ **Where to send it:** [open an issue on TNEP4/marver](https://github.com/TNEP4/marver/issues/new), say what happened
158
+ and roughly when, and attach the file.
159
+
160
+ ## `~/.marver/` and its README
161
+
162
+ Marver keeps its settings and its state in `~/.marver/`, beside the files `marver dev` keeps there. At every launch
163
+ the app writes a `README.md` in it, for you and your coding agent: every file, every setting, and the rules for
164
+ changing them (edits to the README itself are lost). Settings (Marver > Settings…) writes `config.json` and
165
+ `theme.json`. Home's Show the Files opens the folder; Help > Show Performance Files opens the app's performance records.
166
+
167
+ ## Uninstalling
168
+
169
+ Quit Marver and drag it from Applications to the Trash. Its files stay until you delete them:
170
+
171
+ - `~/Library/Application Support/Marver`: the app's web data, shared canvases' sign-ins among it;
172
+ - in `~/.marver/`, the app's own: `config.json`, `theme.json`, `schemas/`, `state/`, `perf/` and `README.md`.
173
+
174
+ The rest of `~/.marver/` (`running/`, `prefer/`, `canvases/`, `models/`) is what `npx marver` keeps for your repos'
175
+ canvases: delete the whole folder only when you no longer use Marver at all.
176
+
177
+ ## On an Intel Mac, or an older macOS
178
+
179
+ The app needs Apple silicon and macOS 13 or later. On any other Mac nothing of it runs: macOS refuses to open it with
180
+ its own message, and Marver has no chance to explain. That is why the requirement sits beside every download link.
181
+ Marver runs the same in your browser: `npx marver dev`.
182
+
183
+ ## Troubleshooting
184
+
185
+ - **A canvas does not appear.** `npx marver ls` lists every canvas running on this Mac, with its version. Not listed:
186
+ it is not running, so start it with `npx marver dev` in its repo. Listed at 0.26 or older: update it
187
+ (`npm i -D @marver-design/marver@latest`) and start it again.
188
+ - **A tab says "Not a Marver canvas".** "Something else answers on this port: a canvas that stopped without cleaning
189
+ up, or another program, or the canvas failed to render - its terminal says why. The app shows nothing it serves."
190
+ Start the canvas again and press Try Again, or Close Tab.
191
+ - **Marver does not update.** The Marver menu says why ([Where it updates](#updates)).
192
+ - **Marver won't open after an update.** Download the disk image again and drag Marver over the old one (Replace).
193
+ - **Anything else:** [an issue on TNEP4/marver](https://github.com/TNEP4/marver/issues), with the performance report
194
+ attached when it is about speed, a crash or a flash.
@@ -99,6 +99,17 @@ new when you do; everything already there the first time counts as seen. They li
99
99
  `design/.local/`, on this machine only, and a published canvas shows none. `npx marver marks` prints
100
100
  them - for you, or for your agent at the start of a session.
101
101
 
102
+ **In the Mac app** (0.3, with Marver 0.29), each canvas's tab sums this up, even while it is hidden: an
103
+ orange count of what needs you - Marver's questions, captures to review, runs that failed or stalled -
104
+ else a blue count of new frames, else a shimmer while an agent works, and a teal dot while a Jam session
105
+ runs. Turn notices on and a canvas you are not looking at sends one when something new needs you, and the
106
+ Dock counts them all. Clicking a notice opens what it names where you can see it, on its board: a question
107
+ in its thread on the frame (Play left and hidden pins shown for it), or in a panel with a field to answer
108
+ when no frame on the board holds it; a review in its review; a failed run with Retry in view, a stalled
109
+ one with its three choices (a stalled capture's or Jam session's on its tile in the lane, on the board you are on). On a
110
+ board locked to play, Play stays and the thread opens over it; a resolved thread opens read-only. It moves
111
+ nothing while you are capturing or have typed words not yet sent.
112
+
102
113
  ## Edits land calmly
103
114
 
104
115
  When a file changes, the canvas reloads only the frames that read it, a few at a time, the ones on
@@ -24,6 +24,12 @@ dot. While it records, everything you do is part of it:
24
24
  - **pictures**: `I` takes one of the frame under the pointer, and the frames you touched are
25
25
  pictured as the capture ends - three at most - at the size you were looking at them (a
26
26
  device, a width you dragged, the play stage). A capture holds twelve pictures in all.
27
+ In the Mac app (0.3, with Marver 0.29), a picture in play is **live**: the stage as you saw
28
+ it - a menu you opened, text you typed - captioned "as you saw it". It is taken when the
29
+ whole stage is in view with nothing over it and has shown its screen for a second (a device
30
+ preset, a slide fitted to the window); otherwise, in a browser, and whenever the app cannot
31
+ take it, the picture is a fresh render of the frame. A live picture is not filtered: it shows
32
+ whatever was on the stage, comment pins and anyone's words in them included.
27
33
 
28
34
  Two ways to end it (0.28): `E` **stops and queues it** - the agent starts on it, nothing to confirm - and `⇧E`
29
35
  **stops to review**: its read-back opens so you can check it and add to it first. Both are on the capture bar. `Esc`
@@ -89,7 +95,9 @@ your own session's run is working goes to that session at once, which decides ho
89
95
  ## Review
90
96
 
91
97
  When a run finishes, its tile turns to **Ready to review**, with a soft chime (`jam: { chime:
92
- false }` silences it). `V` opens the next one to review:
98
+ false }` silences it). In the Mac app, with notices on, a canvas you are not looking at sends a
99
+ notice too, and clicking it opens the review ([what needs you](boards-and-folders.md#what-is-new-what-needs-you)).
100
+ `V` opens the next one to review:
93
101
 
94
102
  - **Review** shows the agent's reply beside each frame it changed, **before and after at
95
103
  once**: side by side for a tall frame (a phone), one above the other for a wide one (a
@@ -167,8 +175,9 @@ words. Other agents do not name captures.
167
175
  ## What your agent receives
168
176
 
169
177
  Each capture reaches your agent as one job: its words with their times, your notes, every UI
170
- step, the pictures, and the element under each point with its source location
171
- (`data-mv-loc`, the file and line it was written at, so the agent goes straight there). It
178
+ step, the pictures (files it opens, since 0.29 - a live one marked), and the element under each
179
+ point with its source location (`data-mv-loc`, the file and line it was written at, so the agent
180
+ goes straight there). It
172
181
  reads each distinct ask, acts on the reserved frames only, and replies per ask; the reply
173
182
  shows in the review, beside the before and after pictures. The managed instructions
174
183
  (`design/instructions/jam.md`, refreshed by `npx marver init`) spell this out for the agent.