@marver-design/marver 0.26.0 → 0.27.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 (96) hide show
  1. package/CHANGELOG.md +158 -0
  2. package/README.md +10 -5
  3. package/dist/{anchor-check-Dg5xpNnU.mjs → anchor-check-ChdDqL5z.mjs} +1 -1
  4. package/dist/{audio-CmSRYFEs.mjs → audio-Dw1lfMdb.mjs} +14 -0
  5. package/dist/{bake-DtVlm0_F.mjs → bake-DM_uWgAA.mjs} +1 -1
  6. package/dist/{boards-DYG22tOe.mjs → boards-DlTcpF47.mjs} +1 -1
  7. package/dist/{build-C_gUgcdC.mjs → build-DZnFysGU.mjs} +4 -4
  8. package/dist/{capture-CrqvU_jh.mjs → capture-vadKjuCo.mjs} +2 -1
  9. package/dist/cli.mjs +28 -16
  10. package/dist/{comments-BqXua-XL.mjs → comments-DxOkCSNE.mjs} +4 -4
  11. package/dist/{daemon-DZo6o3rU.mjs → daemon-BSA0lV8d.mjs} +400 -274
  12. package/dist/detect-C0wpaePX.mjs +125 -0
  13. package/dist/dev-eQJhWsqg.mjs +1273 -0
  14. package/dist/dev-lock-C_FC70Mu.mjs +65 -0
  15. package/dist/exclusive-B1RtpeeP.mjs +150 -0
  16. package/dist/{init-D8DtrK_F.mjs → init-COD0x48i.mjs} +5 -3
  17. package/dist/{link-BNzLvdhI.mjs → link-DDXZVGtv.mjs} +20 -8
  18. package/dist/ls-D7O1G505.mjs +38 -0
  19. package/dist/{marks-NQi0wZJ4.mjs → marks-CWM3WJjc.mjs} +1 -1
  20. package/dist/perf-BWzQwZqj.mjs +369 -0
  21. package/dist/perf-BoDSkbEb.mjs +429 -0
  22. package/dist/perf-jam-D55U3FZK.mjs +242 -0
  23. package/dist/{plugin-CTD0rydA.mjs → plugin-C-E7omsh.mjs} +425 -66
  24. package/dist/{poster-ChjXGTS5.mjs → poster-Bx83ZYVK.mjs} +2 -1
  25. package/dist/{profile-WU9qcbIo.mjs → profile-Bh5Y5zpW.mjs} +1 -1
  26. package/dist/{publish-bakes-CEP_2NRc.mjs → publish-bakes-aljgm45S.mjs} +2 -2
  27. package/dist/{queue-BuiCKSX1.mjs → queue-CAM_vNmX.mjs} +3 -3
  28. package/dist/recover-t9Pno3u9.mjs +66 -0
  29. package/dist/{session-qZWKt_VA.mjs → session-BAaJsK5c.mjs} +1 -1
  30. package/dist/{share--oFJ1bCI.mjs → share-W5H3BNvP.mjs} +1 -1
  31. package/dist/shot-DoHLl6ig.mjs +139 -0
  32. package/dist/{shot-DqcxJibP.mjs → shot-LFhC-WYD.mjs} +343 -19
  33. package/dist/slots-DCDo3N0x.mjs +471 -0
  34. package/dist/speech-worker.mjs +40 -5
  35. package/dist/{sync-DKk-yT1V.mjs → sync-BQVlHZpx.mjs} +4 -3
  36. package/dist/{work-F5u-twpJ.mjs → work-Bp1p39kq.mjs} +4 -2
  37. package/dist/{work-VvX_JIgl.mjs → work-BroFwnup.mjs} +4 -2
  38. package/docs/boards-and-folders.md +3 -1
  39. package/docs/jam-session.md +78 -7
  40. package/docs/live-jam.md +8 -0
  41. package/docs/performance.md +262 -0
  42. package/package.json +2 -2
  43. package/src/client/content/index.tsx +3 -0
  44. package/src/client/content/video.tsx +6 -2
  45. package/src/client/frame-host/bridge.js +22 -6
  46. package/src/client/frame-host/inspect.js +8 -3
  47. package/src/client/frame-host/keys.js +6 -2
  48. package/src/client/frame-host/main.tsx +17 -5
  49. package/src/client/shell/App.tsx +188 -29
  50. package/src/client/shell/BoardList.tsx +5 -5
  51. package/src/client/shell/Comments.tsx +3 -2
  52. package/src/client/shell/JamSurface.tsx +13 -5
  53. package/src/client/shell/LockedApp.tsx +5 -5
  54. package/src/client/shell/Play.tsx +27 -15
  55. package/src/client/shell/Toolbar.tsx +17 -5
  56. package/src/client/shell/api.ts +206 -0
  57. package/src/client/shell/canvas/Canvas.tsx +30 -3
  58. package/src/client/shell/canvas/FrameNode.tsx +15 -5
  59. package/src/client/shell/canvas/admission.ts +8 -1
  60. package/src/client/shell/canvas/camera-broadcast.ts +15 -5
  61. package/src/client/shell/canvas/ctl.ts +2 -0
  62. package/src/client/shell/canvas/frame-registry.ts +28 -2
  63. package/src/client/shell/canvas/sleep.ts +4 -1
  64. package/src/client/shell/comments-store.ts +12 -4
  65. package/src/client/shell/goto.ts +22 -10
  66. package/src/client/shell/icons.tsx +2 -0
  67. package/src/client/shell/jam-capture.ts +96 -16
  68. package/src/client/shell/jam-keys.ts +51 -18
  69. package/src/client/shell/jam-lane.tsx +46 -5
  70. package/src/client/shell/jam-panel.tsx +66 -13
  71. package/src/client/shell/jam-queue.ts +3 -3
  72. package/src/client/shell/jam-session.tsx +14 -8
  73. package/src/client/shell/jam-state.ts +48 -6
  74. package/src/client/shell/jam-surface-parts.tsx +10 -6
  75. package/src/client/shell/jam-voice.ts +7 -5
  76. package/src/client/shell/legacy-links.ts +2 -2
  77. package/src/client/shell/main.tsx +4 -0
  78. package/src/client/shell/notes.ts +8 -1
  79. package/src/client/shell/perf.ts +69 -58
  80. package/src/client/shell/recorder-core.ts +183 -0
  81. package/src/client/shell/recorder.ts +565 -0
  82. package/src/client/shell/store.ts +268 -103
  83. package/src/client/shell/styles.css +54 -9
  84. package/src/client/stage/main.tsx +2 -0
  85. package/templates/AGENTS-embedded.md +22 -4
  86. package/templates/AGENTS-studio.md +22 -4
  87. package/templates/demo/dark.tsx +1 -1
  88. package/templates/demo/welcome.tsx +1 -1
  89. package/templates/instructions/jam.md +5 -3
  90. package/templates/instructions/welcome.md +6 -3
  91. package/dist/config-Cf7EjAMf.mjs +0 -292
  92. package/dist/dev-_Nlsc6v9.mjs +0 -742
  93. package/dist/dev-lock-DWSpa6nj.mjs +0 -179
  94. package/dist/perf-D6VmmJ2q.mjs +0 -68
  95. package/dist/perf-DPbLGhhO.mjs +0 -49
  96. package/dist/shot-CNbHoZ6H.mjs +0 -86
@@ -905,7 +905,7 @@ body.sh-hide-ui .sh-fab,
905
905
  body.sh-hide-ui .sh-ctx,
906
906
  body.sh-hide-ui .sh-update,
907
907
  body.sh-hide-ui .sh-toasts,
908
- body.sh-hide-ui .sh-banner,
908
+ body.sh-hide-ui .sh-banner:not(.sh-stopped), /* a stopped canvas stays said: the page holds what only it has */
909
909
  body.sh-hide-ui .sh-play-nav { display: none !important }
910
910
 
911
911
  /* the prototype pill reuses the shared pill LAYOUT but wears the discreet DARK skin of the
@@ -1496,16 +1496,16 @@ body.sh-commenting .sh-sticky-body { cursor: crosshair }
1496
1496
  much more transparent than the shell's glass, a strong backdrop blur so text reads over any frame, a
1497
1497
  glaze (top highlight + a thin light rim) and a teeny shadow. Colour lives in the state glyph only. ---- */
1498
1498
  .sh-app {
1499
- --jm-tile: rgba(255, 255, 255, .36);
1500
- --jm-tile-hover: rgba(255, 255, 255, .58);
1499
+ --jm-tile: rgba(255, 255, 255, .6);
1500
+ --jm-tile-hover: rgba(255, 255, 255, .78);
1501
1501
  --jm-tile-glaze: linear-gradient(180deg, rgba(255, 255, 255, .55), rgba(255, 255, 255, .08) 55%, rgba(255, 255, 255, 0));
1502
1502
  --jm-tile-blur: blur(18px) saturate(180%);
1503
1503
  --jm-tile-shadow: inset 0 0 0 .5px rgba(255, 255, 255, .75), inset 0 1px 0 rgba(255, 255, 255, .9),
1504
1504
  0 0 0 .5px rgba(24, 24, 27, .09), 0 1px 1.5px rgba(24, 24, 27, .06), 0 3px 8px -4px rgba(24, 24, 27, .14);
1505
1505
  --jm-r: 11px }
1506
1506
  .sh-app.dark, .jm-stage {
1507
- --jm-tile: rgba(34, 34, 42, .42);
1508
- --jm-tile-hover: rgba(52, 52, 62, .6);
1507
+ --jm-tile: rgba(34, 34, 42, .62);
1508
+ --jm-tile-hover: rgba(52, 52, 62, .76);
1509
1509
  --jm-tile-glaze: linear-gradient(180deg, rgba(255, 255, 255, .09), rgba(255, 255, 255, .015) 55%, rgba(255, 255, 255, 0));
1510
1510
  --jm-tile-shadow: inset 0 0 0 .5px rgba(255, 255, 255, .1), inset 0 1px 0 rgba(255, 255, 255, .1),
1511
1511
  0 0 0 .5px rgba(0, 0, 0, .4), 0 1px 1.5px rgba(0, 0, 0, .25), 0 3px 8px -4px rgba(0, 0, 0, .45) }
@@ -1522,9 +1522,15 @@ body.sh-commenting .sh-sticky-body { cursor: crosshair }
1522
1522
  .jm-lane-in { display: flex; align-items: center; gap: 10px; min-width: 0; max-width: 100%; overflow-x: auto; overflow-y: hidden; pointer-events: auto;
1523
1523
  padding: 6px 4px; margin: -6px -4px; scrollbar-width: none; overscroll-behavior-x: contain } /* room for the tiles' shadow inside the scroller */
1524
1524
  .jm-lane-in::-webkit-scrollbar { display: none }
1525
- .jm-lane-in.fade-r { -webkit-mask: linear-gradient(90deg, #000 calc(100% - 56px), transparent); mask: linear-gradient(90deg, #000 calc(100% - 56px), transparent) }
1526
- .jm-lane-in.fade-l { -webkit-mask: linear-gradient(90deg, transparent, #000 56px); mask: linear-gradient(90deg, transparent, #000 56px) }
1527
- .jm-lane-in.fade-l.fade-r { -webkit-mask: linear-gradient(90deg, transparent, #000 56px calc(100% - 56px), transparent); mask: linear-gradient(90deg, transparent, #000 56px calc(100% - 56px), transparent) }
1525
+ /* the edge fades: two strips BESIDE the scroller, never a mask on it - a masked ancestor is a backdrop root,
1526
+ and every tile inside it would lose its blur (0.26.2: the lane was unreadable exactly when it was full).
1527
+ Each strip blurs what is under it and tints it toward the ground, under its own mask (its own mask leaves
1528
+ its own backdrop filter alone). */
1529
+ .jm-lane-edge { position: absolute; top: -6px; bottom: -6px; width: 56px; pointer-events: none; z-index: 1;
1530
+ background: linear-gradient(90deg, var(--ground), transparent); backdrop-filter: blur(6px); -webkit-backdrop-filter: blur(6px);
1531
+ -webkit-mask: linear-gradient(90deg, #000, transparent); mask: linear-gradient(90deg, #000, transparent) }
1532
+ .jm-lane-edge.l { left: -4px }
1533
+ .jm-lane-edge.r { right: -4px; transform: scaleX(-1) }
1528
1534
  .jm-lane .jm-chip { flex: none } /* the recording tile: last, whole */
1529
1535
 
1530
1536
  /* ---- the toolbar's Jam button (between Laser and Tidy). No blue while a session runs: blue is hover and
@@ -1558,6 +1564,12 @@ body.sh-commenting .sh-sticky-body { cursor: crosshair }
1558
1564
  overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-variant-numeric: tabular-nums }
1559
1565
  .jm-card .x { flex: none; display: inline-flex; color: var(--glass-ink-3); margin-left: auto }
1560
1566
  .jm-card.review .m { color: var(--glass-ink-2) }
1567
+ /* the Done fold (0.26.1): the group tile, the narrow collapse tile that leads the opened done tiles, and their slide */
1568
+ .jm-card.close { width: auto; gap: 6px; padding: 0 12px; color: var(--glass-ink-2) }
1569
+ .jm-card.close .t { font: 600 12px -apple-system, system-ui, sans-serif }
1570
+ .jm-card.unfold { animation: jm-unfold .16s cubic-bezier(.2, .7, .3, 1) both }
1571
+ @keyframes jm-unfold { from { transform: translateX(-14px); opacity: 0 } }
1572
+ @media (prefers-reduced-motion: reduce) { .jm-card.unfold { animation: none } }
1561
1573
  .jm-card.queued .t, .jm-card.confirming .t { color: var(--glass-ink-2) }
1562
1574
  .jm-card.done .t, .jm-card.kept .t { color: var(--glass-ink-3) }
1563
1575
  .jm-card.held { color: var(--glass-ink-3) }
@@ -1801,7 +1813,7 @@ body.sh-commenting .sh-sticky-body { cursor: crosshair }
1801
1813
  .jm-focus { position: absolute; top: var(--edge); bottom: calc(var(--edge) + var(--jm-lane) + 2px); z-index: 31; display: flex }
1802
1814
  .jm-focus > .jm-panel { width: 100%; height: 100%; min-height: 0 }
1803
1815
  /* one big picture at a time: the frame tabs and a Before | After switch above it (B flips) */
1804
- .jm-fbar { display: flex; align-items: center; gap: 8px }
1816
+ .jm-fbar { display: flex; align-items: center; gap: 8px; flex-wrap: wrap } /* a narrow window wraps the switch under the tabs */
1805
1817
  .jm-fbar .sp { flex: 1 }
1806
1818
  .jm-fbar kbd { font: 500 10.5px -apple-system, system-ui, sans-serif; color: var(--glass-ink-3); background: none; border: 0; padding: 0 4px 0 2px; align-self: center }
1807
1819
  .jm-big { flex: 1; min-height: 0; display: flex }
@@ -1843,6 +1855,14 @@ body.sh-commenting .sh-sticky-body { cursor: crosshair }
1843
1855
  .jm-big .jm-shot .pic img { width: auto; height: auto; max-width: 100%; max-height: 100%; object-fit: contain; border-radius: 8px;
1844
1856
  box-shadow: 0 0 0 1px var(--glass-brd), 0 2px 10px -4px rgba(24, 24, 27, .18) }
1845
1857
  .jm-big .jm-shot .pic.none { border: 1px dashed var(--glass-ink-3); border-radius: 8px }
1858
+ /* before and after at once (0.26.1): side by side for a tall frame, stacked for a wide one - each a caption over its
1859
+ picture, both at the frame's own proportions */
1860
+ .jm-big.pair { gap: 10px; align-items: stretch }
1861
+ .jm-big.pair.side { flex-direction: row }
1862
+ .jm-big.pair.stack { flex-direction: column }
1863
+ .jm-big.pair .jm-shot { flex: 1; min-width: 0; min-height: 0; height: auto; display: flex; flex-direction: column-reverse; gap: 4px }
1864
+ .jm-big.pair .jm-shot .pic { flex: 1; min-height: 0; height: auto }
1865
+ .jm-big.pair .jm-shot .cap { flex: none; height: 14px; font: 600 11px/14px -apple-system, system-ui, sans-serif; color: var(--glass-ink-2); text-align: center }
1846
1866
  /* the editable words: a quiet hover says "click to edit" */
1847
1867
  .jm-editable { margin: -6px -8px; padding: 6px 8px; border-radius: 10px; cursor: text }
1848
1868
  .jm-editable:hover { background: var(--glass-hover) }
@@ -1868,6 +1888,31 @@ button.jm-link { padding: 0; border: 0; background: none; text-align: left; widt
1868
1888
  .sh-app.jm-lane-on .sh-update { bottom: calc(var(--edge) + 56px) }
1869
1889
  .sh-app.jm-lane-on .sh-toasts { bottom: calc(var(--edge) + 56px) }
1870
1890
  .sh-app.jm-lane-on .sh-banner { bottom: calc(var(--edge) + 56px) }
1891
+ /* the canvas stopped (spec 28 A1.11): on the toolbar's centre line in the gap between the sidebar and the
1892
+ toolbar, or just below the toolbar row - placed by the shell (App.tsx placeBanner), which measures both; above
1893
+ play and focus. The fallback before it measures: top centre, on the line (34px tall, the row 46px) */
1894
+ .sh-app .sh-banner.sh-stopped { top: calc(var(--edge) + 6px); bottom: auto; left: 50%; right: auto; transform: translateX(-50%);
1895
+ z-index: 40; width: max-content; max-width: none; white-space: nowrap; text-align: center; text-wrap: balance; pointer-events: auto }
1896
+ .sh-banner.sh-stopped code { font: 500 11.5px/14px ui-monospace, SFMono-Regular, Menlo, monospace; padding: 1px 5px; border-radius: 5px;
1897
+ background: color-mix(in srgb, currentColor 11%, transparent); white-space: nowrap }
1898
+ .sh-banner.sh-stopped .kept { color: var(--glass-ink-2) }
1899
+ .sh-banner.sh-stopped:is([data-at="stack"], [data-at="below"]) .dot { display: none }
1900
+ .sh-banner.sh-stopped:is([data-at="stack"], [data-at="below"]) .kept { display: block }
1901
+ /* over play and focus: the play chrome's dark skin (its pills, the navigator), warm light text - 13:1 */
1902
+ .sh-banner.sh-stopped.dark { background: rgba(18, 18, 24, .86); border-color: rgba(255, 255, 255, .1); color: #ffd9a0;
1903
+ backdrop-filter: blur(16px); -webkit-backdrop-filter: blur(16px); box-shadow: 0 2px 10px rgba(0, 0, 0, .35) } /* tight: never a smudge on the stage under it */
1904
+ .sh-banner.sh-stopped.dark::after { display: none }
1905
+ .sh-banner.sh-stopped.dark .kept { color: rgba(245, 245, 247, .78) }
1906
+ /* a frame (or the stage) whose canvas is away shows another project's "another canvas" page: one calm line over
1907
+ it, in the frame's own theme - the banner says what happened, once. Screen-size text, never wider than its frame */
1908
+ .sh-stranded { position: absolute; inset: 0; z-index: 2; display: grid; place-items: center; padding: 8%; container-type: size;
1909
+ background: var(--node-bg, var(--pdev-bg, #fff)); color: color-mix(in srgb, var(--head-ink, #18181b) 64%, var(--node-bg, #fff));
1910
+ pointer-events: none; text-align: center }
1911
+ .sh-stranded span { font-family: -apple-system, system-ui, sans-serif; font-weight: 500; font-size: min(calc(12px * var(--sh-inv, 1)), 7cqi); line-height: 1.35 }
1912
+ .sh-play .dev .sh-stranded { --node-bg: #fff; --head-ink: #18181b }
1913
+ .sh-play .dev[data-theme="dark"] .sh-stranded { --node-bg: #0f1015; --head-ink: #ececf1 }
1914
+ /* the tools that need the server, while the canvas is stopped: quiet, their tooltip says why */
1915
+ .sh-pill-btn[data-stopped], .sh-pill-btn[data-stopped]:hover { opacity: .38; background: none; cursor: default }
1871
1916
 
1872
1917
 
1873
1918
  /* ---- words on this Mac (spec 27 Part 4): the live caption over the capture tile, the one question ---- */
@@ -268,6 +268,8 @@ function Stage() {
268
268
  // comment/laser first, else exit) - the stage can't see review mode
269
269
  if (e.key === 'Escape') { post({ type: 'sh:stage-key', key: 'Escape', code: e.code }); return }
270
270
  if (!keyAllowed(e)) return // the one guard: never from a field, an editable, an IME composition
271
+ // ⌥L (inspect): Option types a symbol on a Mac - named by the key pressed
272
+ if (e.altKey && e.code === 'KeyL') { post({ type: 'sh:stage-key', key: 'l', code: e.code, alt: true }); return }
271
273
  // every play shortcut belongs to the shell (it owns walk order + chrome) - forward.
272
274
  // l/c toggle laser/comment, C (shift+c) hides pins; the shell acts and broadcasts back.
273
275
  if (/^Digit[0-9]$/.test(e.code) || ['d', 'h', 'r', 'l', 'c', 'C', '[', ']', 'ArrowRight', 'ArrowLeft'].includes(e.key))
@@ -2,8 +2,18 @@
2
2
 
3
3
  You design by writing files. The canvas at the printed localhost URL reflects them live.
4
4
  Never drive or automate the canvas UI; read and write files only. (Starting
5
- `npx marver dev` so the human has a live canvas - first session, or on request -
6
- is the one allowed touch.)
5
+ the canvas so the human has a live one - first session, or on request - is the one
6
+ allowed touch: `npx marver dev`, never with a port. It takes a free slot,
7
+ localhost:4805-4824, usually the same one next time, and prints its link.)
8
+
9
+ **Keeping the canvas up.** A canvas you start dies with the job that started it: Claude Code
10
+ stops a background job after 10 minutes, and a headless session never exits while one runs.
11
+ So `npx marver ls` first - one may already run for this folder. None: ask the person to run
12
+ `npx marver dev` in their own terminal. If you start it yourself, start it detached so it
13
+ outlives you - `mkdir -p design/.local && nohup npx marver dev > design/.local/dev.log 2>&1 &` -
14
+ then read its link from `npx marver ls`. In a sandbox where it cannot start ("cannot watch
15
+ this folder") or cannot be reached ("cannot be reached from here"), ask the person to run it:
16
+ `npx marver shot`, `marks`, `ls` and `perf --loads` still work there.
7
17
 
8
18
  ## Before the method: a project with no `context/`
9
19
 
@@ -126,8 +136,10 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
126
136
  scene ...>` for any set. Each opens a board they sit on (one link per board when they sit
127
137
  on several) with them selected and in view -
128
138
  the human finds the work at once on a board of fifty frames. Never a full-screen focus link
129
- (`#/f/...`) unless they ask for full screen. No `marver dev` running? End with
130
- `npx marver dev` instead - the link carries its port.
139
+ (`#/f/...`) unless they ask for full screen. `npx marver ls` lists the canvases running on
140
+ this Mac and their links; none for this folder? End by asking the person to run
141
+ `npx marver dev` in their own terminal (or start it detached: "Keeping the canvas up") - the
142
+ link carries its port.
131
143
  - **Answer each comment thread you addressed, in the thread**: `npx marver comments reply
132
144
  <thread> --body "<what changed>"` - one line, no longer than their comment. On a thread
133
145
  the human started it posts as Marver and pings them on the frame. A reply that asks them
@@ -225,6 +237,10 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
225
237
  waiting on them (your notes and replies they have not resolved - the ones that ask first) and
226
238
  the frames new since they last looked. When it bears on the work, say so in your first message
227
239
  ("you have not looked at the checkout frames since I changed them").
240
+ - **Performance.** `npx marver perf --loads --json` says what each board load did - time to
241
+ settled, how many moves and why, the slowest frames, errors. To make a board faster, name
242
+ the lever, change it, compare the next load. A slow frame's `admittedMs` is when its turn to
243
+ start came: a long wait is the queue, not the frame (`ms - admittedMs` is the frame's own).
228
244
  - **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
229
245
  IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
230
246
  that never move on a rename. `title` is what humans see - free text (casing,
@@ -247,6 +263,8 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
247
263
  always yours (Show the work, step 1).
248
264
  - Do not import from "design/" inside src/ or app/. The arrow points one way.
249
265
  - Do not add network calls, app stores, or auth to frames or the presentational screens.
266
+ - Frames cannot register a service worker on the local canvas (it refuses the script): a PWA
267
+ prototype shows its screens, not its offline behaviour.
250
268
  - A scene may not be named "components" or "screens".
251
269
 
252
270
  ## Handoff (when a design is approved)
@@ -2,8 +2,18 @@
2
2
 
3
3
  You design by writing files. The canvas at the printed localhost URL reflects them live.
4
4
  Never drive or automate the canvas UI; read and write files only. (Starting
5
- `npx marver dev` so the human has a live canvas - first session, or on request -
6
- is the one allowed touch.)
5
+ the canvas so the human has a live one - first session, or on request - is the one
6
+ allowed touch: `npx marver dev`, never with a port. It takes a free slot,
7
+ localhost:4805-4824, usually the same one next time, and prints its link.)
8
+
9
+ **Keeping the canvas up.** A canvas you start dies with the job that started it: Claude Code
10
+ stops a background job after 10 minutes, and a headless session never exits while one runs.
11
+ So `npx marver ls` first - one may already run for this folder. None: ask the person to run
12
+ `npx marver dev` in their own terminal. If you start it yourself, start it detached so it
13
+ outlives you - `mkdir -p design/.local && nohup npx marver dev > design/.local/dev.log 2>&1 &` -
14
+ then read its link from `npx marver ls`. In a sandbox where it cannot start ("cannot watch
15
+ this folder") or cannot be reached ("cannot be reached from here"), ask the person to run it:
16
+ `npx marver shot`, `marks`, `ls` and `perf --loads` still work there.
7
17
 
8
18
  ## Before the method: a project with no `context/`
9
19
 
@@ -126,8 +136,10 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
126
136
  scene ...>` for any set. Each opens a board they sit on (one link per board when they sit
127
137
  on several) with them selected and in view -
128
138
  the human finds the work at once on a board of fifty frames. Never a full-screen focus link
129
- (`#/f/...`) unless they ask for full screen. No `marver dev` running? End with
130
- `npx marver dev` instead - the link carries its port.
139
+ (`#/f/...`) unless they ask for full screen. `npx marver ls` lists the canvases running on
140
+ this Mac and their links; none for this folder? End by asking the person to run
141
+ `npx marver dev` in their own terminal (or start it detached: "Keeping the canvas up") - the
142
+ link carries its port.
131
143
  - **Answer each comment thread you addressed, in the thread**: `npx marver comments reply
132
144
  <thread> --body "<what changed>"` - one line, no longer than their comment. On a thread
133
145
  the human started it posts as Marver and pings them on the frame. A reply that asks them
@@ -224,6 +236,10 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
224
236
  waiting on them (your notes and replies they have not resolved - the ones that ask first) and
225
237
  the frames new since they last looked. When it bears on the work, say so in your first message
226
238
  ("you have not looked at the checkout frames since I changed them").
239
+ - **Performance.** `npx marver perf --loads --json` says what each board load did - time to
240
+ settled, how many moves and why, the slowest frames, errors. To make a board faster, name
241
+ the lever, change it, compare the next load. A slow frame's `admittedMs` is when its turn to
242
+ start came: a long wait is the queue, not the frame (`ms - admittedMs` is the frame's own).
227
243
  - **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
228
244
  IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
229
245
  that never move on a rename. `title` is what humans see - free text (casing,
@@ -247,6 +263,8 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
247
263
  - Do not import from "design/" inside src/ or app/. The arrow points one way.
248
264
  - Do not add network calls, app stores, or auth to frames. Mocked data only.
249
265
  - Keep each frame self-sufficient: it must render from its file + fixtures + ui imports alone.
266
+ - Frames cannot register a service worker on the local canvas (it refuses the script): a PWA
267
+ prototype shows its screens, not its offline behaviour.
250
268
  - A scene may not be named "components" or "screens".
251
269
 
252
270
  ## Promotion (when a design is approved)
@@ -3,7 +3,7 @@ export const meta = { title: 'Demo - error state', viewport: 'mobile' }
3
3
 
4
4
  export default function DarkError() {
5
5
  return (
6
- <div style={{ fontFamily: 'system-ui', minHeight: '100vh', background: '#12151f', color: '#e7eaf2', padding: 24, display: 'flex', flexDirection: 'column', gap: 12 }}>
6
+ <div style={{ fontFamily: 'system-ui', minHeight: '100vh', boxSizing: 'border-box', background: '#12151f', color: '#e7eaf2', padding: 24, display: 'flex', flexDirection: 'column', gap: 12 }}>
7
7
  <b style={{ fontSize: 16 }}>‹ Checkout</b>
8
8
  <div style={{ background: '#2a1215', border: '1px solid #5c2320', borderRadius: 8, padding: '12px 14px', color: '#f0776b', fontSize: 14, lineHeight: 1.5 }}>
9
9
  <b style={{ display: 'block', color: '#f9a8a0' }}>Card declined</b>
@@ -4,7 +4,7 @@ import { fx } from './_fixtures.ts'
4
4
  export const meta = { title: 'Demo - welcome', viewport: 'mobile' }
5
5
 
6
6
  const s = {
7
- wrap: { fontFamily: 'system-ui', minHeight: '100vh', display: 'flex', flexDirection: 'column', padding: 24, gap: 12, background: 'var(--background, #fff)', color: 'var(--foreground, #111)' },
7
+ wrap: { fontFamily: 'system-ui', minHeight: '100vh', boxSizing: 'border-box', display: 'flex', flexDirection: 'column', padding: 24, gap: 12, background: 'var(--background, #fff)', color: 'var(--foreground, #111)' },
8
8
  h: { fontSize: 28, fontWeight: 700, letterSpacing: '-0.02em', margin: 0 },
9
9
  p: { color: '#667085', margin: 0, lineHeight: 1.5 },
10
10
  btn: { marginTop: 'auto', padding: '12px 16px', borderRadius: 8, border: 0, background: '#111', color: '#fff', fontWeight: 600, fontSize: 15, cursor: 'pointer' },
@@ -168,9 +168,11 @@ full, not cropped. A frame tall enough to hit the capture cap comes back with
168
168
  printing one PNG path per line; a failed frame goes to stderr and the exit code is 1. After
169
169
  writing a scene, shoot the scene, not the frames. `--scale 4` is for a print-quality still -
170
170
  the human's "copy as image" on the canvas uses this same renderer, so you both see one
171
- picture. If it says the dev server cannot be reached - a sandbox that blocks the network
172
- blocks localhost too - drop a request file as above instead: it works in every sandbox. Never
173
- reply that you could not look.)
171
+ picture. In a sandbox that blocks the network (localhost too) the command takes the picture
172
+ through the file inbox by itself; if it still says the dev server cannot be reached, drop a
173
+ request file as above. Never reply that you could not look. A picture that came back tiled
174
+ from Chrome is taken again for you; a shot that fails with "stale surface" is worth one more
175
+ try.)
174
176
 
175
177
  Verification is best-effort, not a gate. If your model cannot read images, or the result
176
178
  reports no Chrome on the machine, still act on `ok`/`error` - and say plainly in your reply
@@ -107,9 +107,12 @@ without narrating into the void; your next message is the reveal.
107
107
  ## The reveal
108
108
 
109
109
  Deliver conversationally when the first draft is ready - a short guided
110
- message, not a manual. Start `npx marver dev` if it is not already running
111
- (allowed for this purpose) and ALWAYS hand a deep link to the board you
112
- prepared, using the port the dev server PRINTED:
110
+ message, not a manual. The canvas must be running: `npx marver ls` lists it.
111
+ Not yet? Ask the person to run `npx marver dev` in their own terminal - a
112
+ canvas you start dies with your job - or start it detached, as design/AGENTS.md
113
+ says ("Keeping the canvas up"); never with a port. ALWAYS hand a deep link to
114
+ the board you prepared, using the port the dev server printed (`npx marver ls`
115
+ lists it):
113
116
  `http://localhost:<port>/#/b/<board>` - never the bare root URL. The link goes
114
117
  at the BOTTOM of the message, on its own line: the human reads through, then
115
118
  clicks. The human has already played with the hosted tour by now, so keep it
@@ -1,292 +0,0 @@
1
- import { m as readDescription } from "./board-tree-DRioF94d.mjs";
2
- import { i as onPath, n as AGENT_NAMES, r as detectAgent, t as AGENT_BIN } from "./agent-BsieQGTD.mjs";
3
- import { existsSync, readFileSync } from "node:fs";
4
- import { join } from "node:path";
5
- import { pathToFileURL } from "node:url";
6
- //#region src/server/detect.ts
7
- function readJson(file) {
8
- try {
9
- return JSON.parse(stripJsonComments(readFileSync(file, "utf8")));
10
- } catch {
11
- return null;
12
- }
13
- }
14
- function stripJsonComments(s) {
15
- let out = "", inStr = false, inLine = false, inBlock = false;
16
- for (let i = 0; i < s.length; i++) {
17
- const c = s[i], n = s[i + 1];
18
- if (inLine) {
19
- if (c === "\n") {
20
- inLine = false;
21
- out += c;
22
- }
23
- continue;
24
- }
25
- if (inBlock) {
26
- if (c === "*" && n === "/") {
27
- inBlock = false;
28
- i++;
29
- }
30
- continue;
31
- }
32
- if (inStr) {
33
- out += c;
34
- if (c === "\\") {
35
- out += n ?? "";
36
- i++;
37
- } else if (c === "\"") inStr = false;
38
- continue;
39
- }
40
- if (c === "\"") {
41
- inStr = true;
42
- out += c;
43
- continue;
44
- }
45
- if (c === "/" && n === "/") {
46
- inLine = true;
47
- i++;
48
- continue;
49
- }
50
- if (c === "/" && n === "*") {
51
- inBlock = true;
52
- i++;
53
- continue;
54
- }
55
- out += c;
56
- }
57
- let res = "", inS = false;
58
- for (let i = 0; i < out.length; i++) {
59
- const c = out[i];
60
- if (inS) {
61
- res += c;
62
- if (c === "\\") {
63
- res += out[i + 1] ?? "";
64
- i++;
65
- } else if (c === "\"") inS = false;
66
- continue;
67
- }
68
- if (c === "\"") {
69
- inS = true;
70
- res += c;
71
- continue;
72
- }
73
- if (c === ",") {
74
- let j = i + 1;
75
- while (j < out.length && /\s/.test(out[j])) j++;
76
- if (out[j] === "}" || out[j] === "]") continue;
77
- }
78
- res += c;
79
- }
80
- return res;
81
- }
82
- function detectHost(root) {
83
- const pkg = readJson(join(root, "package.json")) ?? {};
84
- const deps = {
85
- ...pkg.dependencies,
86
- ...pkg.devDependencies
87
- };
88
- const twRange = deps["tailwindcss"];
89
- const tailwind = !twRange ? null : /(^|[^\d])4\./.test(twRange) || twRange.startsWith("^4") || twRange.startsWith("~4") ? 4 : 3;
90
- const router = deps["next"] ? "next" : deps["react-router"] || deps["react-router-dom"] ? "react-router" : null;
91
- const routerPkg = deps["react-router-dom"] ? "react-router-dom" : "react-router";
92
- const toaster = deps["sonner"] ? "sonner" : deps["react-hot-toast"] ? "react-hot-toast" : null;
93
- let shadcn = null;
94
- const comp = readJson(join(root, "components.json"));
95
- if (comp?.tailwind?.css) shadcn = {
96
- themeCss: comp.tailwind.css,
97
- uiAlias: comp.aliases?.ui ?? "@/components/ui"
98
- };
99
- const themeCss = shadcn?.themeCss && existsSync(join(root, shadcn.themeCss)) ? shadcn.themeCss : firstExisting(root, [
100
- "src/index.css",
101
- "src/styles/theme.css",
102
- "src/styles/globals.css",
103
- "src/app/globals.css",
104
- "app/globals.css",
105
- "src/globals.css",
106
- "src/style.css",
107
- "styles/globals.css"
108
- ]);
109
- const ts = readJson(join(root, "tsconfig.json"));
110
- const include = ts?.include;
111
- const exclude = ts?.exclude ?? [];
112
- const sweeps = ts != null && !exclude.some((e) => e === "design" || e.startsWith("design/")) && (!include || include.some((i) => i === "." || i.startsWith("**") || i.startsWith("design")));
113
- return {
114
- tailwind,
115
- router,
116
- routerPkg,
117
- toaster,
118
- shadcn,
119
- themeCss,
120
- tsconfigSweepsDesign: !!sweeps
121
- };
122
- }
123
- function firstExisting(root, candidates) {
124
- for (const c of candidates) if (existsSync(join(root, c))) return c;
125
- return null;
126
- }
127
- //#endregion
128
- //#region src/server/config.ts
129
- const DEFAULTS = {
130
- mode: "studio",
131
- theme: null,
132
- viewports: {
133
- mobile: {
134
- width: 390,
135
- height: 844
136
- },
137
- tablet: {
138
- width: 768,
139
- height: 1024
140
- },
141
- laptop: {
142
- width: 1280,
143
- height: 800
144
- },
145
- monitor: {
146
- width: 1920,
147
- height: 1080
148
- }
149
- },
150
- themes: ["light", "dark"],
151
- port: 5199,
152
- zoomSpeed: 1,
153
- share: { branding: true }
154
- };
155
- /** Load design/config.ts via native TS import (Node >= 22.18). Missing or broken fields fall back to defaults. */
156
- async function loadConfig(root) {
157
- const file = join(root, "design", "config.ts");
158
- if (!existsSync(file)) return {
159
- ...DEFAULTS,
160
- ...jamFields(void 0)
161
- };
162
- try {
163
- const user = (await import(`${pathToFileURL(file).href}?t=${Date.now()}`)).default ?? {};
164
- return {
165
- ...DEFAULTS,
166
- ...user,
167
- viewports: validViewports(user.viewports) ?? DEFAULTS.viewports,
168
- themes: Array.isArray(user.themes) && user.themes.length ? user.themes.map(String) : DEFAULTS.themes,
169
- port: validPort(user.port) ?? DEFAULTS.port,
170
- zoomSpeed: validZoom(user.zoomSpeed) ?? DEFAULTS.zoomSpeed,
171
- description: readDescription(user.description),
172
- share: {
173
- branding: user.share?.branding !== false,
174
- name: typeof user.share?.name === "string" ? user.share.name : void 0,
175
- logo: typeof user.share?.logo === "string" ? user.share.logo : void 0,
176
- frontDoor: user.share?.frontDoor !== false && user.share?.front_door !== false,
177
- notify: user.share?.notify !== false
178
- },
179
- ...jamFields(user.jam)
180
- };
181
- } catch (err) {
182
- console.error(`[marver] design/config.ts failed to load, using defaults and leaving Live Jam OFF:\n ${err.message}`);
183
- return {
184
- ...DEFAULTS,
185
- jamOff: "unreadable"
186
- };
187
- }
188
- }
189
- const validDim = (n) => typeof n === "number" && Number.isFinite(n) && n >= 1 && n <= 2e4;
190
- function validPort(n) {
191
- return typeof n === "number" && Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
192
- }
193
- function validZoom(n) {
194
- return typeof n === "number" && Number.isFinite(n) && n >= .1 && n <= 10 ? n : null;
195
- }
196
- /** Six frames at once is what a jam actually feels like - at 3, half of a multi-frame
197
- * ask sat waiting on the other half while the human watched. */
198
- const DEFAULT_CONCURRENCY = 6;
199
- /** A config value, printable in a warning. Never throws - a formatter that can crash inside an
200
- * error path (JSON.stringify does, on a BigInt) turns a clear message into a mystery. */
201
- const show = (v) => {
202
- try {
203
- return JSON.stringify(v) ?? String(v);
204
- } catch {
205
- return String(v);
206
- }
207
- };
208
- /** A `{...}` written by hand, not a Date/Map/class instance that merely types as "object". */
209
- const plainObject = (v) => {
210
- if (!v || typeof v !== "object") return false;
211
- const proto = Object.getPrototypeOf(v);
212
- return proto === Object.prototype || proto === null;
213
- };
214
- /** The agent to arm with - or, when the human NAMED one we cannot use, why not (said once,
215
- * here, because a bad `jam.agent` is a config-file error like any other).
216
- *
217
- * A named agent is never quietly swapped for another: running a different tool than the one
218
- * asked for is worse than not running. Nor is one armed that cannot be spawned - that would
219
- * claim every @marver mention, fail it, and never retry. */
220
- function resolveAgent(named) {
221
- if (named === void 0) return detectAgent() ?? "no-agent";
222
- if (typeof named !== "string" || !Object.hasOwn(AGENT_BIN, named)) {
223
- console.warn(`[marver] design/config.ts: jam.agent ${show(named)} is not an agent marver can spawn - Live Jam is off. Use ${AGENT_NAMES}.`);
224
- return "bad-agent";
225
- }
226
- const agent = named;
227
- if (!onPath(AGENT_BIN[agent])) {
228
- console.warn(`[marver] design/config.ts names jam.agent "${agent}", but \`${AGENT_BIN[agent]}\` is not on PATH - Live Jam is off until it is installed.`);
229
- return "bad-agent";
230
- }
231
- return agent;
232
- }
233
- /** Resolve the jam block. Live Jam is ON by default: an absent or partial `jam` resolves
234
- * to whatever agent CLI this machine has, so a fresh workspace jams with nothing
235
- * configured and an old one needs no re-init. `jam: false` is the off switch. */
236
- function resolveJam(v) {
237
- if (v === false) return "opted-out";
238
- const shape = v === void 0 || v === true ? {} : typeof v === "string" ? { agent: v } : plainObject(v) ? v : null;
239
- if (!shape) {
240
- console.warn(`[marver] design/config.ts: jam must be false, an agent name, or an options object - got ${show(v)}. Live Jam is off.`);
241
- return "bad-agent";
242
- }
243
- const j = shape;
244
- const agent = resolveAgent(j.agent);
245
- if (agent === "no-agent" || agent === "bad-agent") return agent;
246
- const c = j.concurrency;
247
- const pick = (key, v, ok, fallback, want) => {
248
- if (v === void 0) return fallback;
249
- if (ok(v)) return v;
250
- console.warn(`[marver] design/config.ts: jam.${key} must be ${want} - got ${show(v)}. Using ${JSON.stringify(fallback)}.`);
251
- return fallback;
252
- };
253
- const bool = (v) => typeof v === "boolean";
254
- return {
255
- agent,
256
- concurrency: typeof c === "number" && Number.isInteger(c) && c >= 1 && c <= 16 ? c : DEFAULT_CONCURRENCY,
257
- subagents: j.subagents !== false,
258
- proactive: j.proactive === true,
259
- chime: pick("chime", j.chime, bool, true, "true or false"),
260
- capture: pick("capture", j.capture, (v) => v === "confirm" || v === "at-once", "confirm", `'confirm' or 'at-once'`),
261
- loc: pick("loc", j.loc, bool, true, "true or false"),
262
- names: pick("names", j.names, bool, true, "true or false")
263
- };
264
- }
265
- /** Exactly one of `jam` (armed) or `jamOff` (why not) - so the dev server can speak up about
266
- * the one off-state nothing has reported yet, and stay quiet about the rest. BOTH keys are
267
- * always written: these spread over the user's own `jam`, and a raw `jam: false` reaching the
268
- * server as config would arm the daemon against a truthy object check. */
269
- function jamFields(v) {
270
- const r = resolveJam(v);
271
- return typeof r === "string" ? {
272
- jam: void 0,
273
- jamOff: r
274
- } : {
275
- jam: r,
276
- jamOff: void 0
277
- };
278
- }
279
- function validViewports(v) {
280
- if (!v || typeof v !== "object") return null;
281
- const out = {};
282
- for (const [k, val] of Object.entries(v)) {
283
- const vp = val;
284
- if (validDim(vp?.width) && validDim(vp?.height)) out[k] = {
285
- width: Math.round(vp.width),
286
- height: Math.round(vp.height)
287
- };
288
- }
289
- return Object.keys(out).length ? out : null;
290
- }
291
- //#endregion
292
- export { readJson as i, loadConfig as n, detectHost as r, DEFAULTS as t };