@marver-design/marver 0.30.1 → 0.31.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 (107) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/README.md +11 -7
  3. package/dist/{anchor-check-Bv4o-R2T.mjs → anchor-check-B92s9tVv.mjs} +1 -1
  4. package/dist/{board-tree-BXR8dw4b.mjs → board-tree-DGj0HhEE.mjs} +6 -2
  5. package/dist/{boards-EH2onUXM.mjs → boards-Cim1GTKc.mjs} +32 -2
  6. package/dist/{boards-BeWtjGUM.mjs → boards-OlAhZ87x.mjs} +7 -7
  7. package/dist/{build-zWGXSzly.mjs → build-BNssmbqd.mjs} +14 -17
  8. package/dist/{capture-DEtM4qm5.mjs → capture-HaS-1or8.mjs} +1 -1
  9. package/dist/cli.mjs +38 -20
  10. package/dist/{collab-BEAcXrBb.mjs → collab-D2NcrOB8.mjs} +53 -14
  11. package/dist/comment-actions-Bxf9Ld4g.mjs +351 -0
  12. package/dist/{comments-XNhMmSSu.mjs → comments-BakJQwaf.mjs} +85 -10
  13. package/dist/config-B0YcFtqS.mjs +510 -0
  14. package/dist/{context-BUnFiyA3.mjs → context-Cj2TcC0H.mjs} +3 -3
  15. package/dist/{daemon-CChgWJNq.mjs → daemon-MxoEQajX.mjs} +222 -23
  16. package/dist/deep-link-DYtuT740.mjs +163 -0
  17. package/dist/{dev-DOgIITpT.mjs → dev-BBZe_brH.mjs} +23 -16
  18. package/dist/devices-uJZ2inMq.mjs +155 -0
  19. package/dist/{events-CLH4ijKP.mjs → events-Dieo1482.mjs} +49 -4
  20. package/dist/{init-CYlFaRzG.mjs → init-BgusplYn.mjs} +40 -10
  21. package/dist/{jam-Cj5gBvwD.mjs → jam-CkuLL8A8.mjs} +1 -1
  22. package/dist/{link-BFFRgrMt.mjs → link-Cmt9Xy4X.mjs} +54 -7
  23. package/dist/{logo-CXY-1yrn.mjs → logo-C9s7-Cy9.mjs} +89 -66
  24. package/dist/{ls-NqmePKOf.mjs → ls-DGVIW-Io.mjs} +1 -1
  25. package/dist/{manifest-DPZ3WNg_.mjs → manifest-CK8Qh4Nq.mjs} +255 -13
  26. package/dist/{marks-BnNANic9.mjs → marks-C8oX8kbE.mjs} +3 -3
  27. package/dist/{marks-DBp3h1Mc.mjs → marks-Dt-5JXCp.mjs} +18 -5
  28. package/dist/{marver-id-gate-vBLb_Icb.mjs → marver-id-gate-BAeuMeaU.mjs} +11 -7
  29. package/dist/md-B9_13Q0R.mjs +105 -0
  30. package/dist/notes-CRAX4wgk.mjs +148 -0
  31. package/dist/own-C8Mq0Hnf.mjs +128 -0
  32. package/dist/pdf-0m721FFn.mjs +117 -0
  33. package/dist/pdf-CZENT6t3.mjs +2299 -0
  34. package/dist/{perf-BCxAo0IS.mjs → perf-BB0XNt1M.mjs} +1 -1
  35. package/dist/{perf-6MOTHxay.mjs → perf-CIMijND6.mjs} +5 -5
  36. package/dist/{plugin-CFWBcAba.mjs → plugin-CL8_wL7a.mjs} +460 -83
  37. package/dist/{poster-DPPpQiva.mjs → poster-B7uSjlEP.mjs} +1 -1
  38. package/dist/{profile-B1FKOM1e.mjs → profile-cdmSer1k.mjs} +1 -1
  39. package/dist/{publish-bakes-_Zx8crP3.mjs → publish-bakes-BjgDNeyS.mjs} +3 -3
  40. package/dist/{queue-DeSQm24g.mjs → queue-BLLfdlDw.mjs} +156 -11
  41. package/dist/{recover-mDUVsnPd.mjs → recover-ByuFQOF9.mjs} +2 -2
  42. package/dist/{serve-DQv3Ti6X.mjs → serve-kcF6-H8V.mjs} +4 -4
  43. package/dist/{session-VDJfXEEm.mjs → session-DBF-nQvq.mjs} +29 -3
  44. package/dist/{share-Bu_kuOKL.mjs → share-CS2mg27O.mjs} +1 -1
  45. package/dist/{shot-d4h_hJi9.mjs → shot-BqwkdtKn.mjs} +4 -4
  46. package/dist/{shot-DBWN8hPP.mjs → shot-D2TQGo2V.mjs} +1 -1
  47. package/dist/show-B1u3DiJw.mjs +101 -0
  48. package/dist/{sizes-wjXDev3b.mjs → sizes-BckcL4Zz.mjs} +1 -1
  49. package/dist/{slots-Dn4Onb0V.mjs → slots-BOcfIqxy.mjs} +15 -3
  50. package/dist/{summary-Y8MY1Wuc.mjs → summary-cPmRDGpX.mjs} +1 -1
  51. package/dist/{sync-CMozOwZ0.mjs → sync-BNWwh8OF.mjs} +205 -7
  52. package/dist/{work-BYWD_1Zf.mjs → work-DRdzXPvg.mjs} +3 -3
  53. package/dist/{work-DJxH7cCX.mjs → work-Nv-n2_Un.mjs} +1 -1
  54. package/docs/app.md +49 -0
  55. package/docs/boards-and-folders.md +37 -6
  56. package/docs/jam-session.md +5 -0
  57. package/docs/live-jam.md +9 -0
  58. package/docs/pdf.md +108 -0
  59. package/docs/publish.md +9 -9
  60. package/docs/sharing.md +11 -0
  61. package/docs/slides.md +9 -0
  62. package/package.json +3 -1
  63. package/src/client/content/index.tsx +4 -2
  64. package/src/client/frame-host/main.tsx +3 -0
  65. package/src/client/shell/App.tsx +71 -24
  66. package/src/client/shell/BoardList.tsx +16 -7
  67. package/src/client/shell/Comments.tsx +77 -16
  68. package/src/client/shell/Play.tsx +24 -22
  69. package/src/client/shell/Toolbar.tsx +4 -3
  70. package/src/client/shell/app-bridge.ts +32 -5
  71. package/src/client/shell/canvas/Canvas.tsx +30 -8
  72. package/src/client/shell/canvas/FrameNode.tsx +3 -1
  73. package/src/client/shell/canvas/ctl.ts +16 -0
  74. package/src/client/shell/commands.ts +20 -0
  75. package/src/client/shell/comments-store.ts +81 -2
  76. package/src/client/shell/devices.tsx +42 -0
  77. package/src/client/shell/goto.ts +56 -9
  78. package/src/client/shell/icons.tsx +11 -4
  79. package/src/client/shell/jam-lines.ts +5 -3
  80. package/src/client/shell/jam-panel.tsx +17 -5
  81. package/src/client/shell/marks-ui.tsx +54 -0
  82. package/src/client/shell/notes.ts +21 -0
  83. package/src/client/shell/pdf-export.tsx +154 -0
  84. package/src/client/shell/pdf-notes.ts +20 -0
  85. package/src/client/shell/show.ts +250 -0
  86. package/src/client/shell/store.ts +23 -38
  87. package/src/client/shell/styles.css +43 -0
  88. package/src/shared/app-api.ts +49 -4
  89. package/src/shared/auto-place.ts +32 -0
  90. package/src/shared/board-tree.ts +3 -0
  91. package/src/shared/board-types.ts +6 -2
  92. package/src/shared/deep-link.ts +212 -0
  93. package/src/shared/devices.ts +89 -0
  94. package/src/shared/events.ts +48 -5
  95. package/src/shared/export-plan.ts +98 -0
  96. package/templates/AGENTS-embedded.md +76 -12
  97. package/templates/AGENTS-studio.md +76 -12
  98. package/templates/instructions/boards.md +6 -5
  99. package/templates/instructions/configure.md +32 -2
  100. package/templates/instructions/iterate.md +8 -0
  101. package/templates/instructions/jam.md +9 -0
  102. package/templates/instructions/publish.md +14 -4
  103. package/templates/instructions/review.md +4 -0
  104. package/templates/instructions/slides.md +67 -1
  105. package/templates/instructions/welcome.md +9 -5
  106. package/templates/playbooks/publish-canvas/PLAYBOOK.md +1 -1
  107. package/dist/config-BezZTiov.mjs +0 -182
@@ -34,7 +34,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
34
34
  | Phase | When | Read |
35
35
  |---|---|---|
36
36
  | Welcome | the human's FIRST session, or "what is this?" | instructions/welcome.md |
37
- | Configure | first session in a repo, or frames render unstyled | instructions/configure.md |
37
+ | Configure | first session in a repo, frames render unstyled, or the canvas does not wear the product's name and logo: `marver dev`'s boot line says "this canvas still shows ...", `name` in design/config.ts is missing or still init's guess from package.json ("My repo" for `my-repo`), or the logo is the Marver mark - do step 6, identity | instructions/configure.md |
38
38
  | Discover | any new surface, feature, or flow | instructions/discover.md |
39
39
  | Shape | thinking a feature through on canvas (specs, diagrams, mood boards) - never the first session | instructions/shape.md |
40
40
  | Wireframe | new work: nail structure + copy in throwaway lo-fi | instructions/wireframe.md |
@@ -44,7 +44,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
44
44
  | Review | before presenting anything | instructions/review.md |
45
45
  | Boards | creating a board, choosing what ships | instructions/boards.md |
46
46
  | Context | any question about what the product does or what is live; a behaviour change; a deploy; no `context/` yet | instructions/context.md |
47
- | Slides | a deck is asked for, or `slide: true` frames exist | instructions/slides.md + design/slides.md |
47
+ | Slides | a deck is asked for; a PDF of a deck or of any board, a flow too (`npx marver pdf <board>`, then give back the path it prints); or `slide: true` frames exist | instructions/slides.md + design/slides.md |
48
48
  | Publish | deploying the canvas: gate, volume, accounts, invites | instructions/publish.md |
49
49
  | Live Jam | responding to an `@marver` comment (a spawned job), or a "Live Jam: ... new request" message (below) - run `npx marver jam next`; on by default - confirm it names YOUR tool | instructions/jam.md |
50
50
 
@@ -160,13 +160,35 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
160
160
 
161
161
  - **Every reply in which you created or changed frames ends with their canvas link**, on its
162
162
  own line: the `on the canvas:` line `work done` printed, or `npx marver link <scene/frame |
163
- scene ...>` for any set. Each opens a board they sit on (one link per board when they sit
164
- on several) with them selected and in view -
165
- the human finds the work at once on a board of fifty frames. Never a full-screen focus link
166
- (`#/f/...`) unless they ask for full screen. `npx marver ls` lists the canvases running on
167
- this Mac and their links; none for this folder? End by asking the person to run
168
- `npx marver dev` in their own terminal (or start it detached: "Keeping the canvas up") - the
169
- link carries its port.
163
+ scene ...>` for any set (`checkout/cart`, or `checkout` for a whole scene). Each opens a board
164
+ they sit on (one link per board when they sit on several; `--board <b>` picks one) with them
165
+ selected and in view - the human finds the work at once on a board of fifty frames. **Give
166
+ exactly what those commands print** - a `marver://...` link (the Mac app has this canvas
167
+ open) or a localhost one - never a link you wrote yourself or rewrote. `link` reads a bare
168
+ name as a scene (`checkout`), never as a board: for a whole board, link the scenes it shows
169
+ with `--board <board>` (each node's `frame` in design/boards/<board>.json starts with its
170
+ scene; an `auto: true` board shows every scene), or its frames when it shows only some of a
171
+ scene's. Never a full-screen focus link unless they ask for full screen - then
172
+ `#/f/<scene/frame>` after the localhost link `npx marver ls` prints, the one link you write
173
+ yourself. **`link` and `show` need `marver dev` running for this folder** - the link carries
174
+ its port. `npx marver ls` lists the canvases running on this Mac and their links; none for
175
+ this folder? End by asking the person to run `npx marver dev` in their own terminal (or start
176
+ it detached: "Keeping the canvas up").
177
+ - **Show, only when they ask.** "Show me", "take me there", "open it for me": run `npx marver
178
+ show <target>` - `checkout/cart` (a frame), `checkout/cart checkout/pay` (several),
179
+ `checkout` (a scene), `launch-plan` (a board, fitted whole). A bare name is a frame or a
180
+ scene first, and a board only when no frame or scene has that name: a board whose name a
181
+ scene also has cannot be shown whole - show the scenes it shows with `--board <board>`, as
182
+ for `link`. `--thread <id>` opens that comment thread there too, with its frame or board
183
+ still named (`show checkout/cart --thread <id>`). Every open tab of this canvas goes
184
+ there, selected and fitted, and the Mac app comes forward. It waits 3 seconds, prints one
185
+ line, then the link:
186
+ - `shown in 2 tabs` - say it is on their screen, and end with the link;
187
+ - `1 tab holds words not yet sent - ...` - they were typing, so that tab did not move: it
188
+ shows "Your agent wants to show you ... · Go". Say so, and give the link;
189
+ - `not shown - no open tab took it ...` or `not shown: ...` - nothing moved: give the link.
190
+ Frames on two boards are refused: show one board at a time (`--board <board>`). Never show on
191
+ your own to hand work back - that is the link, above.
170
192
  - **Answer each comment thread you addressed, in the thread**: `npx marver comments reply
171
193
  <thread> --body "<what changed>"` - one line, no longer than their comment. On a thread
172
194
  the human started it posts as Marver and pings them on the frame. A reply that asks them
@@ -183,7 +205,7 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
183
205
  new --thread <id>` on your own note), never a second note on the same subject. A note in the
184
206
  wrong place: `npx marver comments move <thread> --on "..."`, never a second copy. The chat keeps
185
207
  the summary and can say "question on the form". Never resolve your own notes: the human
186
- resolves them as they review.
208
+ resolves them as they review (one at a time, or all at once - below).
187
209
  - **A plain reply in a Marver thread starts no job - only an `@marver` tag does.** The human
188
210
  answers your notes and questions on the canvas, then tags the threads they want acted on, or
189
211
  says "go through my replies": then run `npx marver marks` - its **answered by you** list is
@@ -201,6 +223,17 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
201
223
  // tv available commented-out). Pick the one the screen is designed for - the human can
202
224
  // flip the whole board to any device (Devices menu; digit keys - 0 restores each
203
225
  // frame's own size, 1..n per configured device) to check responsiveness.
226
+ // Add the product's own devices there too: `"boox-full": { width: 1240, height: 1860 }`.
227
+ // Each shows as its name reads ("ipad-landscape" -> "iPad landscape", the tablet glyph
228
+ // turned) unless it sets `label` (40 chars) and `icon`: a glyph (mobile, tablet, laptop,
229
+ // monitor, tv, watch, desktop, ereader; "-landscape" turns it) or a repo .svg - paths and
230
+ // shapes only (no style, script, href, text), 32 KB at most, drawn in the toolbar's ink:
231
+ // it is a mask, so colours do not matter, only what is painted - `fill`/`stroke` attributes
232
+ // are fine (any colour, or none); a line icon needs fill="none" or its shapes fill solid.
233
+ // An `icon` replaces the name's turn: a landscape device names `tablet-landscape`,
234
+ // not `tablet`. An .svg is never turned - draw it the way the device stands. A bad
235
+ // label or icon falls back to the name's, with one line in `marver dev`'s terminal;
236
+ // both are read when `marver dev` starts (instructions/configure.md, step 6).
204
237
  - States are sibling frames: empty.tsx, filled.tsx, error.tsx, success.tsx.
205
238
  - VERSIONS are sibling frames with letter prefixes, and the canvas understands them:
206
239
  design/scenes/landing/a-terminal.tsx + b-editorial.tsx form a VARIANT GROUP - kept
@@ -260,9 +293,40 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
260
293
  Read it before exploring; `marver dev` keeps it fresh. `npx marver boards` prints the
261
294
  boards part as a tree.
262
295
  - **What the human has not reviewed.** At the start of a session, `npx marver marks`: the frames
263
- waiting on them (your notes and replies they have not resolved - the ones that ask first) and
264
- the frames new since they last looked. When it bears on the work, say so in your first message
296
+ waiting on them (your notes and replies they have not resolved - the ones that ask first), the
297
+ frames new since they last looked, and the open conversations per board. When it bears on the work, say so in your first message
265
298
  ("you have not looked at the checkout frames since I changed them").
299
+ - **The sidebar's marks, as the human names them.** Orange is Marver waiting on them: an
300
+ orange bubble on a frame, scene, board or closed folder counts your open notes and replies
301
+ there (a hollow one on a frame: they answered, and it waits on you - `marks`' answered by
302
+ you list). Blue is new: frames new or changed since they last looked - a blue dot, a blue
303
+ title. A board's status glyph takes the same slot when no question does (Building is blue),
304
+ and a board icon that shimmers blue is an agent at work on it. The human's own threads wear
305
+ no mark. Orange goes as the threads are resolved (resolve-all, below, only on their yes);
306
+ blue goes as they look at the frames, or with "Mark all as seen" in a board, folder or scene
307
+ menu - theirs to click, never yours.
308
+ - **Many open conversations: offer, never decide.** When `npx marver marks` shows more than 10
309
+ open (its `open` line; `--json` has `open.total` and `open.boards`), or the human says the
310
+ badges are noisy, ask - with the count per board it prints ("38 open: launch-plan 22,
311
+ checkout-compare 16 - resolve them?"). A frame on two boards counts on both. Only on a yes, and only for what
312
+ they said yes to: one board is `npx marver comments resolve --all --board <b>`, a folder
313
+ `--folder <f>`, a scene `--scene <s>`, everything `--canvas` (the only scope that also takes
314
+ threads with no frame or on a frame that is gone; `--scene` takes its frames whether or not a board shows them). `--dry-run` counts first. Give them the `--undo` line it
315
+ prints. It never touches what Jam is working on, and the human has the same in every board,
316
+ folder and scene menu ("Resolve all comments") and on the Mac app's tab. Never on your own.
317
+ - **Undo a resolve-all later.** The canvas's Undo notice lasts 10 seconds. After that, each run
318
+ is kept as `design/.local/comment-ops/<op>.json` (its `scope` and `at` say which; skip the
319
+ `.undo.json` files): `npx marver comments resolve --undo <op>` reopens each thread nothing
320
+ happened in since.
321
+ - **Edit and delete are the author's, on the canvas.** People edit and delete their own
322
+ messages there. Marver's notes and replies have no Edit or Delete, for anyone, and the CLI
323
+ edits and deletes nothing. A note of yours that is wrong: correct it in its thread (`comments
324
+ new --thread <id>` on your own note); a misplaced one: `comments move`. Say so in the chat;
325
+ the human resolves it. A person's message only they can change: never post it again reworded.
326
+ - **A deleted comment is gone.** A deleted reply
327
+ disappears; a deleted first comment whose replies stay is listed as "(comment deleted)"
328
+ (`"deleted": true` in `--json`, no body or author). Its words never reach you, in
329
+ `comments list` or in Jam. Never quote one back, and never write one again.
266
330
  - **Performance.** `npx marver perf --loads --json` says what each board load did - time to
267
331
  settled, how many moves and why, the slowest frames, errors. To make a board faster, name
268
332
  the lever, change it, compare the next load. A slow frame's `admittedMs` is when its turn to
@@ -302,11 +302,12 @@ A board's status, reason and capability never ship - unless the row says `"showS
302
302
  then only a status drawn from publishable evidence (`audience: publishable` under `context/`; a scene
303
303
  brief counts unless it says otherwise), never Blocked, never a reason.
304
304
 
305
- The published gate page shows the app's identity: `design/logo.svg` + the host
306
- package name (overridable via config `share`). If the app has no logo asset yet,
307
- create a simple `design/logo.svg`. The same logo wears the canvas's tab in the Mac
308
- app. It counts only as a real file in the repo (never a symlink), at most 256 KB,
309
- whose bytes are an SVG, a PNG or an ICO. Leave `share.branding` ON unless the human
305
+ The published gate page shows the app's identity - the same as the canvas wears in the
306
+ Mac app (instructions/configure.md, step 6): config `name`, else `share.name`, else the
307
+ host package name; config `logo`, else `share.logo`, else `design/logo.svg` (then
308
+ `public/`). If the app has no logo asset yet, create a simple `design/logo.svg`. It
309
+ counts only as a real file in the repo (never a symlink), at most 256 KB, whose bytes
310
+ are an SVG, a PNG or an ICO. Leave `share.branding` ON unless the human
310
311
  explicitly asks to remove it: marver is free, the gate is already personalized to
311
312
  the app, and the small "Powered by" line is how the tool spreads. Do not remove it
312
313
  as part of "branding polish".
@@ -20,8 +20,38 @@ frames render suspiciously unstyled - then never think about it again.
20
20
  guessed from env markers and PATH - on a machine with both CLIs installed that guess
21
21
  can be wrong, and then every `@marver` comment is answered by the other tool. Fix the
22
22
  line and tell the human. Details, including the off switch: instructions/jam.md.
23
-
24
- All five true → idle state. Go design.
23
+ 6. **The canvas looks like the product** (identity): in the Mac app's tab, on its Home
24
+ card and in the sidebar, a canvas wears its name and its logo - left alone it is the
25
+ folder's name and the Marver mark, like every other canvas there (`marver dev`'s boot
26
+ line says so). So:
27
+ - `name` in `design/config.ts` is the product's human name - "TMS Broker", not
28
+ "tms-broker". A config a current `marver init` wrote has a first guess from
29
+ package.json, else the folder (`my-repo` -> "My repo"): make it real - the boot line does not ask
30
+ about a guess. An older config has no `name` line, and re-running init never adds
31
+ one - add it yourself. 80 characters at most.
32
+ - `design/logo.svg` is the product's REAL mark - find it in the app (`public/`,
33
+ `src/assets/`, the favicon) and copy it in; draw a simple one only when the app
34
+ truly has none, and tell the human. A regular file in the repo (never a symlink),
35
+ an SVG, PNG or ICO of at most 256 KB; `logo: "path"` in the config names another.
36
+ With no `logo` in the config, the canvas takes the first of design/logo.svg|png,
37
+ public/logo.svg|png and public/favicon.svg|png|ico, else the Marver mark: check that
38
+ what it found is the product's mark.
39
+ - Boards, folders and frames carry titles written for people ("iPad landscape",
40
+ "Checkout - empty cart"), never a slug ("Ipad-landscape").
41
+ - Custom breakpoints read well: `viewports.<name>` takes a `label` and an `icon` (a
42
+ built-in glyph or a repo .svg) - see the Frames section of AGENTS.md. A name like
43
+ `ipad-landscape` needs neither: it already shows as "iPad landscape" with the tablet
44
+ glyph turned.
45
+ - `name`, `logo` and a viewport's `label` and `icon` are read when `marver dev` starts:
46
+ the running canvas keeps its old name and icons until it starts again (a new
47
+ `design/logo.svg` shows at once). Tell the human to stop and start `marver dev`
48
+ when it suits them. Never restart it yourself while they are on the canvas. Its
49
+ terminal then names anything ignored (`[marver] design/config.ts: ...` for a name, label or icon;
50
+ `marver: logo <path> is ignored: ...` for a logo, when the canvas or the app first asks for it), and its
51
+ boot line stops asking for a name and a logo once both are set.
52
+ `share.name` / `share.logo` still work (`name` / `logo` win); nothing needs rewriting.
53
+
54
+ All six true → idle state. Go design.
25
55
 
26
56
  ## By repo maturity
27
57
 
@@ -89,6 +89,9 @@ comment took it minutes ago), the snapshot exists - skip to step 4.
89
89
  (resolve first, restructure second); the owner's stays open - say in the
90
90
  reply what replaced the element (its pin joins the column at the frame's
91
91
  top-right corner, still in view) - or re-pin it with `comments move`.
92
+ End the round's chat reply with what `npx marver link <scene>` prints (the
93
+ after) and `npx marver link <scene>-v<N> --board archive` (the before), each
94
+ on its own line, as printed.
92
95
 
93
96
  Never wait for the human to ask for this. They should be able to say "make the
94
97
  cards denser", "drop the sidebar", "try a warmer palette" three times in a row
@@ -193,6 +196,11 @@ The discipline:
193
196
  5. **Never resolve what you didn't address.** Disagree? Reply with your
194
197
  reasoning and leave the thread open - the human closes debates, you close
195
198
  completed work.
199
+ Many open at once is the human's to clear, never yours: past ten open
200
+ (`npx marver marks` counts them per board), ask - and only on a yes run
201
+ `npx marver comments resolve --all --board <b>` (`--folder`, `--scene`,
202
+ `--canvas`; `--dry-run` counts first; it prints its `--undo`). It skips
203
+ every thread Jam is working on.
196
204
  6. **A frame with open comments is load-bearing - never delete, rename, or
197
205
  gut it.** Its threads are anchored to elements INSIDE it; restructure the
198
206
  frame and the anchors strand (a dead anchor parks the pin in the column at
@@ -323,6 +323,12 @@ discards everything else you say (narration never reaches a thread):
323
323
  your reply where they asked, with no review step after it. Say what you changed and what is
324
324
  left; to go on, they tag again. **A capture member's** reply is also shown in its review,
325
325
  beside its before and after pictures.
326
+ - **A request to be shown** ("show me the cart", in a tag or a capture): with a shell (a run in
327
+ your own session), run `npx marver show <scene/frame | scene | board>` - their open tabs go there
328
+ (one where they are typing gets a notice instead) - and say in the reply block what you showed.
329
+ With no shell (a spawned job), or when it prints `not shown`, say in the reply block where it is
330
+ (board and frame). Never a link in a reply block: the thread is already on their canvas. Never a link in a reply block:
331
+ the thread is already on their canvas.
326
332
  Rules (first line and the marver-reply block):
327
333
  - **Plain text only.** The thread renders RAW text, so markdown shows as literal characters. No
328
334
  `**bold**`, no `` `backticks` ``, no headings, no bullet lists. Line breaks are your only formatting.
@@ -339,6 +345,9 @@ Rules (first line and the marver-reply block):
339
345
  - **Concise and clear, always.** Cut every filler word. Lead with what changed. Apply the copy
340
346
  principles in instructions/reference/copy.md (active voice, specific, no fluff).
341
347
  Do NOT resolve the thread; the human resolves after reviewing.
348
+ A message the owner deleted never reaches you: it is taken out of the packet before the hand-off (and a
349
+ request with nothing left is dropped). Once a packet is in your hands nothing can unread it - so never
350
+ quote a message back that the thread no longer shows.
342
351
 
343
352
  ## Working in parallel (when enabled)
344
353
  Two kinds of parallelism stack, and they are not the same knob: the daemon runs up to
@@ -53,11 +53,13 @@ vars if the host has no CLI.
53
53
  redeploy; marver fails loudly if the dir cannot be created.
54
54
 
55
55
  Then one line before you build: **name the canvas** -
56
- `share: { name: "Your App" }` in `design/config.ts`. The name is the gate's
56
+ `name: "Your App"` in `design/config.ts` (configure.md's identity step usually did;
57
+ `share.name` still works). The name is the gate's
57
58
  title, the brand pill's tooltip, and the `utm_campaign` on every powered-by
58
59
  link the canvas emits (the wordmark, the gate, the play brand pill). With no
59
- name it falls back to the ROOT DIRECTORY, which in a container is `app` -
60
- every containerised canvas you never named reports as the same campaign.
60
+ name, the gate falls back to package.json's `name` and the canvas shell to the
61
+ ROOT DIRECTORY, which in a container is `app` - every containerised canvas you
62
+ never named reports as the same campaign.
61
63
 
62
64
  ## The serve contract (env vars, complete list)
63
65
 
@@ -250,6 +252,12 @@ marver dev # two-way syncs comments every 30s
250
252
  marver comments list --open # the agent's work queue
251
253
  marver comments reply <thread> --body "..." # answer in the loop
252
254
  marver comments resolve <thread> --addressed-in <frame> # close with a receipt
255
+ # resolve-all (`marver comments resolve --all ...`, or "Resolve all comments" in a
256
+ # board's menu) runs on this machine only - the published canvas has no such button -
257
+ # and each thread it resolves (or its Undo reopens) reaches the published canvas as its
258
+ # own resolve on the next sync. Threads your agent started stay here, as always.
259
+ # A message deleted locally reaches a canvas older than 0.31 only once it is upgraded
260
+ # (until then it is held back)
253
261
  marver comments revoke <email> # kills the account + its sessions, mid-flight
254
262
  ```
255
263
 
@@ -265,7 +273,9 @@ through sign-in.
265
273
  - `design/comments/<board>.jsonl` - the dev-side mirror, git-tracked: feedback
266
274
  has history, and the volume has an off-site replica for free. **Each event
267
275
  carries its author's email address** - that is how the canvas decides who may
268
- edit or resolve their own thread. Harmless in a private repo; if yours is
276
+ edit or delete a message: its author, and only its author. Resolving is not
277
+ the author's alone: anyone who may comment on a board may resolve (and reopen)
278
+ any thread on it. Harmless in a private repo; if yours is
269
279
  public, or may become public, gitignore `design/comments/` and let the volume
270
280
  be the record. The canvas keeps its own copy either way, so nothing is lost.
271
281
  - `~/.marver/canvases/<project-hash>.json` - THIS machine's device credential, kept
@@ -53,3 +53,7 @@ Lead with what to look at: the board name, the frame to start on, the flow to wa
53
53
  and the one or two decisions you need from the human. Copy file paths for anything
54
54
  you reference (select frames + press c). Never present work whose review you skipped;
55
55
  say "unreviewed" if the human asked for speed.
56
+
57
+ End with the canvas link, on its own line: what `npx marver link <scene/frame | scene ...>`
58
+ (or `work done`) printed, as printed. Run `npx marver show <scene/frame | scene | board>`
59
+ only if they ask to be shown (design/AGENTS.md, "Hand it back on the canvas").
@@ -56,7 +56,7 @@ Code means the motion is yours: CSS keyframes and transitions, SVG
56
56
  animation, a JS library the project already uses. Three habits make it play
57
57
  well:
58
58
 
59
- - **At rest, the finished slide.** On the canvas, in `marver shot`, in a
59
+ - **At rest, the finished slide.** On the canvas, in `marver shot`, in a PDF, in a
60
60
  thumbnail, the slide shows its final composition. Animate while the deck
61
61
  plays: the stage puts `data-sl-play` on `<html>` for the whole show and adds
62
62
  `data-sl-entered` once each slide has arrived. Key motion off them:
@@ -269,6 +269,9 @@ are stuck.
269
269
  slide, a card around everything, a tiny uppercase kicker over every
270
270
  headline, filler numbers, the same composition three slides running with no
271
271
  reason. Delete before you add.
272
+ - **Hand it over** with what `npx marver link <deck>` prints (the deck's
273
+ scene), on its own line, as printed. `npx marver show <deck board>` only when
274
+ they ask to be shown.
272
275
 
273
276
  ## Publishing a deck
274
277
 
@@ -283,6 +286,69 @@ The board is the deck. Publish with:
283
286
  standard prototype toolbar and walker), `minimal` (a progress strip +
284
287
  comments) or `none`. Add `"lock": true` for a share that is ONLY the deck.
285
288
 
289
+ ## A deck as a PDF
290
+
291
+ When the human asks for a PDF of a deck or of any board ("make a PDF of the
292
+ deck", "send me the slides", to attach or print), run `npx marver pdf <board>`
293
+ and give them the path it prints. It needs `marver dev` running for this
294
+ folder: `npx marver ls` first; none running, see "Keeping the canvas up" in
295
+ design/AGENTS.md. It writes `design/exports/<board>.pdf` (kept out of git);
296
+ `--out <file>` writes it elsewhere ("on my Desktop": `--out
297
+ ~/Desktop/<board>.pdf`). `--json` prints the report as JSON, with the file's
298
+ absolute path in `file`.
299
+
300
+ - **What prints.** A board whose `design/publish.json` row says
301
+ `"type": "slides"` (or `"open": "slides"`) prints its deck: its `slide: true`
302
+ frames in reading order, one page each at the stage size. Any other board
303
+ prints every frame in the board file's order (Play's), each at the device
304
+ Play shows it at. So before you export a deck, give its board that publish
305
+ row (Publishing a deck, above). A board file's own `"type"` does not count:
306
+ without the row the pages follow the board file's order, non-slide frames
307
+ included.
308
+ - `--notes` makes a handout instead (`<board>-notes.pdf`) - what the human
309
+ calls "with speaker notes": each page's picture and title beside its whole
310
+ `.note.md` (all four parts, Say among them), "No notes" when it has none,
311
+ Letter landscape (`--paper a4` for A4). Its pages are the deck's, chosen the
312
+ same way: give the board its publish row first here too.
313
+ `--theme dark` prints every page in one theme; without it each slide prints
314
+ in its own.
315
+ - One PDF at a time per canvas: "a PDF of ... is being made" means wait for
316
+ it, then run again.
317
+ - The human can do the same on the canvas: Export PDF in the board's menu,
318
+ the export button in slides and present mode, or File > Export PDF in the
319
+ Mac app. A published canvas cannot export.
320
+
321
+ Read the report before you hand it over. Its first line is the file, pages,
322
+ size and time; each line under it names slides that need a look:
323
+
324
+ - **patched** slides are fine - glass, filters, blends, masks and big soft
325
+ shadows were fixed and checked against the screen;
326
+ - **raster** slides printed as pictures (no searchable text), with the reason:
327
+ say so. An effect on the page itself (`body` or `html`) or under a transform
328
+ is the usual cause - move it onto an inner element and export again;
329
+ - **unsettled**: an image or chart was still loading after 10 s - fix the
330
+ slide (a missing asset, a slow chart) and export again;
331
+ - **clipped**: the slide is taller or wider than its stage - fix the layout;
332
+ - **spilled**: the page ran onto a second printed page and only the first was
333
+ kept - check that nothing is missing;
334
+ - **changed while printing**: its files changed during the export (an edit
335
+ landed) - export again once edits stop;
336
+ - **printed differently from the screen (kept: --vector)**: only with
337
+ `--vector` - those pages print as Chrome prints them, unlike the screen. Look
338
+ at them in the PDF, or export again without `--vector`;
339
+ - **skipped**: a frame the board names but the manifest no longer lists, or a
340
+ non-slide frame on a slides board - name it to the human;
341
+ - **failed**: the frame threw or never rendered, and the export stops with no
342
+ file - `npx marver shot` it, fix it, export again. With `--keep-going` the
343
+ PDF is written with that page blank and the command exits 1: never hand it
344
+ over without saying which page is blank.
345
+ - The last line says `every page print-certified` or `screen-certified only`
346
+ (no rasteriser on this machine): both are fine to hand over. `not
347
+ print-certified` follows the "printed differently" line above.
348
+
349
+ The PDF is the finished slide, as at rest: another reason every slide must
350
+ show its final composition without `data-sl-play` (Motion, above).
351
+
286
352
  ## design/slides.md - this project's deck look
287
353
 
288
354
  The project's own file: the deck look (master, tones, type, mark, imagery,
@@ -64,7 +64,9 @@ without narrating into the void; your next message is the reveal.
64
64
  execution - assume, mark UNCONFIRMED, surface it first.) Once they confirm,
65
65
  write that understanding as one sentence into `description` in
66
66
  design/config.ts - the project's line in design/manifest.json, the first
67
- thing every later session reads.
67
+ thing every later session reads - and set `name` there to the product's
68
+ name as they say it (init's guess reads "Tms broker"; configure.md step 6
69
+ also gives the canvas its real logo).
68
70
  2. **Confirm the stack aloud - what detection ACTUALLY found.** Read AGENTS.md's
69
71
  UI line and design/theme.css and narrate the reality, for example: "Tailwind
70
72
  + shadcn/ui; brand tokens in <file>; design/theme.css imports them." No
@@ -110,10 +112,12 @@ Deliver conversationally when the first draft is ready - a short guided
110
112
  message, not a manual. The canvas must be running: `npx marver ls` lists it.
111
113
  Not yet? Ask the person to run `npx marver dev` in their own terminal - a
112
114
  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):
116
- `http://localhost:<port>/#/b/<board>` - never the bare root URL. The link goes
115
+ says ("Keeping the canvas up"); never with a port. ALWAYS end with what
116
+ `npx marver link <scene ...> --board <board>` prints for the board you prepared
117
+ (its scenes selected and in view), or the `on the canvas:` line `work done`
118
+ printed - a `marver://` link when the Mac app has this canvas open, else a
119
+ localhost one. Give it as printed: never a link you wrote, never the bare root
120
+ URL. The link goes
117
121
  at the BOTTOM of the message, on its own line: the human reads through, then
118
122
  clicks. The human has already played with the hosted tour by now, so keep it
119
123
  short - let their own product carry the moment. The highlights, all real
@@ -24,7 +24,7 @@ project's values (which account, which domain, which gate) and every run in the
24
24
  - The three decisions are made: **which boards ship** (`design/publish.json` - publishing is
25
25
  default-closed), **who gets in** (Marver Sign In by default; the canvas password when nothing
26
26
  external may be in the sign-in path), **collaboration** (a persistent volume for comments, or none).
27
- - The canvas has a name: `share: { name: "..." }` in `design/config.ts`.
27
+ - The canvas has a name: `name: "..."` in `design/config.ts` (or `share: { name }`).
28
28
 
29
29
  ## Steps
30
30
 
@@ -1,182 +0,0 @@
1
- import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
2
- import { h as readDescription } from "./board-tree-BXR8dw4b.mjs";
3
- import { i as onPath, n as AGENT_NAMES, r as detectAgent, t as AGENT_BIN } from "./agent-BsieQGTD.mjs";
4
- import { existsSync } from "node:fs";
5
- import { join } from "node:path";
6
- import { pathToFileURL } from "node:url";
7
- //#region src/server/config.ts
8
- var config_exports = /* @__PURE__ */ __exportAll({
9
- DEFAULTS: () => DEFAULTS,
10
- loadConfig: () => loadConfig
11
- });
12
- const DEFAULTS = {
13
- mode: "studio",
14
- theme: null,
15
- viewports: {
16
- mobile: {
17
- width: 390,
18
- height: 844
19
- },
20
- tablet: {
21
- width: 768,
22
- height: 1024
23
- },
24
- laptop: {
25
- width: 1280,
26
- height: 800
27
- },
28
- monitor: {
29
- width: 1920,
30
- height: 1080
31
- }
32
- },
33
- themes: ["light", "dark"],
34
- port: 5199,
35
- zoomSpeed: 1,
36
- share: { branding: true }
37
- };
38
- /** Load design/config.ts via native TS import (Node >= 22.18). Missing or broken fields fall back to defaults. */
39
- async function loadConfig(root) {
40
- const file = join(root, "design", "config.ts");
41
- if (!existsSync(file)) return {
42
- ...DEFAULTS,
43
- ...jamFields(void 0)
44
- };
45
- try {
46
- const user = (await import(`${pathToFileURL(file).href}?t=${Date.now()}`)).default ?? {};
47
- return {
48
- ...DEFAULTS,
49
- ...user,
50
- viewports: validViewports(user.viewports) ?? DEFAULTS.viewports,
51
- themes: Array.isArray(user.themes) && user.themes.length ? user.themes.map(String) : DEFAULTS.themes,
52
- port: validPort(user.port) ?? DEFAULTS.port,
53
- zoomSpeed: validZoom(user.zoomSpeed) ?? DEFAULTS.zoomSpeed,
54
- description: readDescription(user.description),
55
- share: {
56
- branding: user.share?.branding !== false,
57
- name: typeof user.share?.name === "string" ? user.share.name : void 0,
58
- logo: typeof user.share?.logo === "string" ? user.share.logo : void 0,
59
- frontDoor: user.share?.frontDoor !== false && user.share?.front_door !== false,
60
- notify: user.share?.notify !== false
61
- },
62
- ...jamFields(user.jam)
63
- };
64
- } catch (err) {
65
- console.error(`[marver] design/config.ts failed to load, using defaults and leaving Live Jam OFF:\n ${err.message}`);
66
- return {
67
- ...DEFAULTS,
68
- jamOff: "unreadable"
69
- };
70
- }
71
- }
72
- const validDim = (n) => typeof n === "number" && Number.isFinite(n) && n >= 1 && n <= 2e4;
73
- function validPort(n) {
74
- return typeof n === "number" && Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
75
- }
76
- function validZoom(n) {
77
- return typeof n === "number" && Number.isFinite(n) && n >= .1 && n <= 10 ? n : null;
78
- }
79
- /** Six frames at once is what a jam actually feels like - at 3, half of a multi-frame
80
- * ask sat waiting on the other half while the human watched. */
81
- const DEFAULT_CONCURRENCY = 6;
82
- /** A config value, printable in a warning. Never throws - a formatter that can crash inside an
83
- * error path (JSON.stringify does, on a BigInt) turns a clear message into a mystery. */
84
- const show = (v) => {
85
- try {
86
- return JSON.stringify(v) ?? String(v);
87
- } catch {
88
- return String(v);
89
- }
90
- };
91
- /** A `{...}` written by hand, not a Date/Map/class instance that merely types as "object". */
92
- const plainObject = (v) => {
93
- if (!v || typeof v !== "object") return false;
94
- const proto = Object.getPrototypeOf(v);
95
- return proto === Object.prototype || proto === null;
96
- };
97
- /** The agent to arm with - or, when the human NAMED one we cannot use, why not (said once,
98
- * here, because a bad `jam.agent` is a config-file error like any other).
99
- *
100
- * A named agent is never quietly swapped for another: running a different tool than the one
101
- * asked for is worse than not running. Nor is one armed that cannot be spawned - that would
102
- * claim every @marver mention, fail it, and never retry. */
103
- function resolveAgent(named) {
104
- if (named === void 0) return detectAgent() ?? "no-agent";
105
- if (typeof named !== "string" || !Object.hasOwn(AGENT_BIN, named)) {
106
- console.warn(`[marver] design/config.ts: jam.agent ${show(named)} is not an agent marver can spawn - Live Jam is off. Use ${AGENT_NAMES}.`);
107
- return "bad-agent";
108
- }
109
- const agent = named;
110
- if (!onPath(AGENT_BIN[agent])) {
111
- 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.`);
112
- return "bad-agent";
113
- }
114
- return agent;
115
- }
116
- /** Resolve the jam block. Live Jam is ON by default: an absent or partial `jam` resolves
117
- * to whatever agent CLI this machine has, so a fresh workspace jams with nothing
118
- * configured and an old one needs no re-init. `jam: false` is the off switch. */
119
- function resolveJam(v) {
120
- if (v === false) return "opted-out";
121
- const shape = v === void 0 || v === true ? {} : typeof v === "string" ? { agent: v } : plainObject(v) ? v : null;
122
- if (!shape) {
123
- console.warn(`[marver] design/config.ts: jam must be false, an agent name, or an options object - got ${show(v)}. Live Jam is off.`);
124
- return "bad-agent";
125
- }
126
- const j = shape;
127
- const agent = resolveAgent(j.agent);
128
- if (agent === "no-agent" || agent === "bad-agent") return agent;
129
- const c = j.concurrency;
130
- const pick = (key, v, ok, fallback, want) => {
131
- if (v === void 0) return fallback;
132
- if (ok(v)) return v;
133
- console.warn(`[marver] design/config.ts: jam.${key} must be ${want} - got ${show(v)}. Using ${JSON.stringify(fallback)}.`);
134
- return fallback;
135
- };
136
- const bool = (v) => typeof v === "boolean";
137
- return {
138
- agent,
139
- concurrency: typeof c === "number" && Number.isInteger(c) && c >= 1 && c <= 16 ? c : DEFAULT_CONCURRENCY,
140
- subagents: j.subagents !== false,
141
- proactive: j.proactive === true,
142
- chime: pick("chime", j.chime, bool, true, "true or false"),
143
- capture: pick("capture", j.capture, (v) => v === "confirm" || v === "at-once", "confirm", `'confirm' or 'at-once'`),
144
- loc: pick("loc", j.loc, bool, true, "true or false"),
145
- names: pick("names", j.names, bool, true, "true or false"),
146
- runner: pick("runner", j.runner, (v) => v === "auto" || v === "session" || v === "background", "auto", `'auto', 'session' or 'background'`),
147
- session: pick("session", j.session, bool, true, "true or false"),
148
- context: pick("context", j.context, (v) => v === "fork" || v === "fresh", "fork", `'fork' or 'fresh'`),
149
- mcp: pick("mcp", j.mcp, bool, true, "true or false"),
150
- skills: pick("skills", j.skills, bool, true, "true or false"),
151
- others: pick("others", j.others, bool, false, "true or false"),
152
- ...((sm) => sm === void 0 ? {} : { sessionMax: sm })(pick("sessionMax", j.sessionMax, (v) => typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= 8, void 0, "a whole number from 1 to 8"))
153
- };
154
- }
155
- /** Exactly one of `jam` (armed) or `jamOff` (why not) - so the dev server can speak up about
156
- * the one off-state nothing has reported yet, and stay quiet about the rest. BOTH keys are
157
- * always written: these spread over the user's own `jam`, and a raw `jam: false` reaching the
158
- * server as config would arm the daemon against a truthy object check. */
159
- function jamFields(v) {
160
- const r = resolveJam(v);
161
- return typeof r === "string" ? {
162
- jam: void 0,
163
- jamOff: r
164
- } : {
165
- jam: r,
166
- jamOff: void 0
167
- };
168
- }
169
- function validViewports(v) {
170
- if (!v || typeof v !== "object") return null;
171
- const out = {};
172
- for (const [k, val] of Object.entries(v)) {
173
- const vp = val;
174
- if (validDim(vp?.width) && validDim(vp?.height)) out[k] = {
175
- width: Math.round(vp.width),
176
- height: Math.round(vp.height)
177
- };
178
- }
179
- return Object.keys(out).length ? out : null;
180
- }
181
- //#endregion
182
- export { loadConfig as n, config_exports as t };