@marver-design/marver 0.26.1 → 0.27.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +198 -0
- package/README.md +12 -4
- package/dist/{anchor-check-l-ny3UzH.mjs → anchor-check-gkxkPAIv.mjs} +1 -1
- package/dist/{board-tree-DRioF94d.mjs → board-tree-BXR8dw4b.mjs} +3 -1
- package/dist/{boards-CGg6piKF.mjs → boards-BHKP5yhI.mjs} +1 -1
- package/dist/{boards-DYG22tOe.mjs → boards-BqUqKNW8.mjs} +4 -4
- package/dist/{build-BDRiO_mP.mjs → build-VgNg4rr8.mjs} +8 -23
- package/dist/cli.mjs +45 -19
- package/dist/{collab-Dxg2trOK.mjs → collab-BEAcXrBb.mjs} +1 -1
- package/dist/{comments-BqXua-XL.mjs → comments-YEU1Zhv9.mjs} +4 -4
- package/dist/{context-HQ4Giw58.mjs → context-Ccjrhr1J.mjs} +3 -3
- package/dist/{daemon-DL6Fwq6D.mjs → daemon-Dc9AH0M3.mjs} +9 -7
- package/dist/detect-C0wpaePX.mjs +125 -0
- package/dist/dev-lock-C_FC70Mu.mjs +65 -0
- package/dist/dev-ri6nAlRp.mjs +1273 -0
- package/dist/exclusive-B1RtpeeP.mjs +150 -0
- package/dist/{init-D8DtrK_F.mjs → init-W0nxR1OY.mjs} +8 -6
- package/dist/{link-BNzLvdhI.mjs → link-CdTgn94Y.mjs} +23 -11
- package/dist/ls-BZ5TAtd5.mjs +38 -0
- package/dist/{manifest-Nl3KSVOk.mjs → manifest-aFyDmL8C.mjs} +2 -2
- package/dist/{marks-DyWMv_Z1.mjs → marks-BF9pNEgH.mjs} +3 -3
- package/dist/{marks-CKgzucHZ.mjs → marks-CnCCfAbD.mjs} +3 -3
- package/dist/{marver-id-gate-BjF6v4bT.mjs → marver-id-gate-D-R0hSt_.mjs} +1 -1
- package/dist/perf-DkAUFT6W.mjs +1319 -0
- package/dist/perf-jam-BaH3Lg0m.mjs +635 -0
- package/dist/plugin-B8UghYuF.mjs +5242 -0
- package/dist/{poster-BdtSKMDm.mjs → poster-BNgafWMK.mjs} +1 -1
- package/dist/{profile-WU9qcbIo.mjs → profile-jIS6BcAs.mjs} +1 -1
- package/dist/{publish-bakes-9RzRToXV.mjs → publish-bakes-38Nja78p.mjs} +3 -3
- package/dist/{queue-29ok5_eZ.mjs → queue-CAM_vNmX.mjs} +1 -1
- package/dist/recover-B8AiI29B.mjs +66 -0
- package/dist/{serve-C8rVheYk.mjs → serve-Dp3nHstu.mjs} +3 -3
- package/dist/{share--oFJ1bCI.mjs → share-Ce4tP7ji.mjs} +1 -1
- package/dist/{shot-XQV7HC9A.mjs → shot-CMQgMVZm.mjs} +1 -1
- package/dist/{shot-DQeR_Pfn.mjs → shot-Ch24tiMO.mjs} +36 -5
- package/dist/slots-CFNnegCc.mjs +478 -0
- package/dist/{sync-DKk-yT1V.mjs → sync-CQdGARJ9.mjs} +4 -3
- package/dist/{work-VvX_JIgl.mjs → work-Bxz-ObF3.mjs} +4 -2
- package/dist/{work-F5u-twpJ.mjs → work-CNhFF9pU.mjs} +5 -3
- package/docs/boards-and-folders.md +3 -1
- package/docs/jam-session.md +57 -2
- package/docs/performance.md +424 -0
- package/package.json +2 -2
- package/src/client/content/index.tsx +3 -0
- package/src/client/content/video.tsx +16 -4
- package/src/client/frame-host/bridge.js +22 -6
- package/src/client/frame-host/main.tsx +17 -5
- package/src/client/shell/App.tsx +188 -26
- package/src/client/shell/BoardList.tsx +5 -5
- package/src/client/shell/Comments.tsx +8 -5
- package/src/client/shell/ContextMenu.tsx +5 -3
- package/src/client/shell/JamSurface.tsx +4 -2
- package/src/client/shell/LockedApp.tsx +8 -5
- package/src/client/shell/Play.tsx +20 -10
- package/src/client/shell/Tip.tsx +3 -1
- package/src/client/shell/Toolbar.tsx +12 -1
- package/src/client/shell/api.ts +233 -0
- package/src/client/shell/app-bridge.ts +254 -0
- package/src/client/shell/app-perf.ts +92 -0
- package/src/client/shell/canvas/Canvas.tsx +141 -21
- package/src/client/shell/canvas/FrameNode.tsx +22 -9
- package/src/client/shell/canvas/admission.ts +31 -9
- package/src/client/shell/canvas/camera-broadcast.ts +15 -5
- package/src/client/shell/canvas/ctl.ts +8 -0
- package/src/client/shell/canvas/frame-registry.ts +28 -2
- package/src/client/shell/canvas/sleep.ts +60 -17
- package/src/client/shell/canvas/updates.ts +2 -1
- package/src/client/shell/comments-store.ts +12 -4
- package/src/client/shell/goto.ts +22 -10
- package/src/client/shell/inset.ts +44 -0
- package/src/client/shell/jam-capture.ts +41 -22
- package/src/client/shell/jam-keys.ts +12 -3
- package/src/client/shell/jam-panel.tsx +9 -3
- package/src/client/shell/jam-queue.ts +3 -3
- package/src/client/shell/jam-session.tsx +14 -8
- package/src/client/shell/jam-voice.ts +55 -15
- package/src/client/shell/legacy-links.ts +2 -2
- package/src/client/shell/main.tsx +18 -1
- package/src/client/shell/marks-ui.tsx +5 -3
- package/src/client/shell/marver-app.ts +21 -0
- package/src/client/shell/notes.ts +8 -1
- package/src/client/shell/perf-run-probe.ts +34 -0
- package/src/client/shell/perf-run.ts +70 -0
- package/src/client/shell/perf.ts +80 -58
- package/src/client/shell/recorder-core.ts +183 -0
- package/src/client/shell/recorder.ts +607 -0
- package/src/client/shell/store.ts +294 -110
- package/src/client/shell/styles.css +72 -15
- package/src/client/shell/unsaved.ts +81 -0
- package/src/client/shell/whiteout-probes.ts +141 -0
- package/src/shared/app-api.ts +205 -0
- package/src/shared/app-perf.ts +308 -0
- package/src/shared/logo-sniff.ts +86 -0
- package/src/shared/machine.ts +132 -0
- package/src/shared/perf-run.ts +177 -0
- package/templates/AGENTS-embedded.md +25 -4
- package/templates/AGENTS-studio.md +25 -4
- package/templates/demo/dark.tsx +1 -1
- package/templates/demo/welcome.tsx +1 -1
- package/templates/instructions/boards.md +3 -1
- package/templates/instructions/welcome.md +6 -3
- package/dist/bake-C-awKgLA.mjs +0 -786
- package/dist/config-Cf7EjAMf.mjs +0 -292
- package/dist/dev-Bw_qYWWq.mjs +0 -755
- package/dist/dev-lock-DWSpa6nj.mjs +0 -179
- package/dist/perf-C75MZ73h.mjs +0 -167
- package/dist/perf-DPbLGhhO.mjs +0 -49
- package/dist/perf-jam-BU3TVrZu.mjs +0 -239
- package/dist/plugin-DkGmZs_r.mjs +0 -2423
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The perf-run contract between the shell and the server (spec 28 A3.4, A3.8 #17-#22): how a headless run names
|
|
3
|
+
* itself, what its page may send, what the page tells the driver, and the one line a run writes to
|
|
4
|
+
* `design/.local/perf/runs.jsonl`. `src/client/shell/perf-run.ts` and `src/server/perf-run.ts` re-export it, so the
|
|
5
|
+
* two halves read one list.
|
|
6
|
+
*
|
|
7
|
+
* FROZEN before the A3 streams split (A3.8 #53); the headless stream fills both halves. Read-only is enforced
|
|
8
|
+
* twice, before anything is sent: in the page (`mvFetch`'s barrier, a synthetic 403, counted as `refused`) and in
|
|
9
|
+
* the server (`perfRunBarrier()` right after the workspace guard, refused and counted per run id as `forbidden`).
|
|
10
|
+
* Stricter than A3.4's `/api/perf/*`: `perf/reload` and `perf/jam` would put headless documents into those logs.
|
|
11
|
+
*/
|
|
12
|
+
import type { HostProfile } from './machine.ts'
|
|
13
|
+
|
|
14
|
+
/** The script's version: a run line compares only with lines of the same script (A3.4). */
|
|
15
|
+
export const RUN_SCRIPT = 1 as const
|
|
16
|
+
|
|
17
|
+
/** A run's own generated id: the same in the URL, the request headers and the output line (A3.4). */
|
|
18
|
+
export const RUN_ID = /^[0-9a-f]{16}$/
|
|
19
|
+
/** The header every request of a run's page carries. */
|
|
20
|
+
export const RUN_HEADER = 'x-mv-perfrun'
|
|
21
|
+
/** The query parameter: on the shell's URL (`?mvperfrun=<id>`), and added by `withWs()` to frame URLs, the play stage and Jam pictures. */
|
|
22
|
+
export const RUN_PARAM = 'mvperfrun'
|
|
23
|
+
/** `&warm=1`: the unrecorded warm-up load - the recorder runs and posts nothing. */
|
|
24
|
+
export const WARM_PARAM = 'warm'
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* The only mutating requests a run may make, under `${ROUTE}/api/` (A3.8 #17): its own page records, and the
|
|
28
|
+
* sleep bakes - `POST /api/bakes` only fills a derived cache, so it is allowed and never counted (A3.4). GET and
|
|
29
|
+
* HEAD always pass. `POST /api/poster` is refused for any run id, registered or not.
|
|
30
|
+
*/
|
|
31
|
+
export const RUN_ALLOWED: readonly { method: 'POST'; path: string }[] = [
|
|
32
|
+
{ method: 'POST', path: 'perf/page' },
|
|
33
|
+
{ method: 'POST', path: 'bakes' },
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
/** May a run send this? `apiPath` is the path under `${ROUTE}/api/` (no leading slash, no query), or null for any other path. */
|
|
37
|
+
export function allowedInRun(method: string, apiPath: string | null): boolean {
|
|
38
|
+
const m = method.toUpperCase()
|
|
39
|
+
if (m === 'GET' || m === 'HEAD') return true
|
|
40
|
+
if (apiPath === null) return false
|
|
41
|
+
return RUN_ALLOWED.some((a) => a.method === m && a.path === apiPath)
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* The page's own bake work (A3.8 #18): four counts of their own - `sleep.pending` says nothing about idleness. The
|
|
46
|
+
* run is bake-idle only when these four and the server's `jobsOf(run)` (queued, running) are all zero.
|
|
47
|
+
*/
|
|
48
|
+
export interface BakeWork {
|
|
49
|
+
/** FrameNode's 250 ms timer and both retry timers, through one `scheduleSleep()` */
|
|
50
|
+
scheduled: number
|
|
51
|
+
/** a sleep from its entry to its `finally`: fonts, the ask, decode, texture install */
|
|
52
|
+
running: number
|
|
53
|
+
/** asks batched and not yet sent */
|
|
54
|
+
queued: number
|
|
55
|
+
/** the bake POST in flight */
|
|
56
|
+
inflight: number
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** `window.__mvPerfRun.status()`, polled by the driver through CDP (A3.8 #17). */
|
|
60
|
+
export interface PerfRunStatus {
|
|
61
|
+
run: string
|
|
62
|
+
warm: boolean
|
|
63
|
+
/** the load the recorder owns now */
|
|
64
|
+
load: { id: string; state: 'requested' | 'committed' | 'settled' | 'cut'; reason?: string; sinceNav?: number } | null
|
|
65
|
+
/** the page's four counts at zero (not the run's bake-idle: the server's jobs are the driver's to add) */
|
|
66
|
+
bakeIdle: boolean
|
|
67
|
+
bake: BakeWork
|
|
68
|
+
/** the camera in flight */
|
|
69
|
+
moving: boolean
|
|
70
|
+
/** gestures ended so far (perf.ts) */
|
|
71
|
+
gestures: number
|
|
72
|
+
/** same-origin frames whose root says data-mv-poster-skipped */
|
|
73
|
+
postersSkipped: number
|
|
74
|
+
/** requests the page refused before sending */
|
|
75
|
+
refused: number
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** `window.__mvPerfRun`, in perf mode only. */
|
|
79
|
+
export interface PerfRunProbe {
|
|
80
|
+
status(): PerfRunStatus
|
|
81
|
+
/** canvasCtl.fitAll(), then the camera idle (3 s at most) */
|
|
82
|
+
fit(): Promise<boolean>
|
|
83
|
+
/** the canvas element's client rect centre */
|
|
84
|
+
centre(): { x: number; y: number }
|
|
85
|
+
/** the recorder's outbox sent until empty: whether every batch landed */
|
|
86
|
+
flush(): Promise<boolean>
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** Why a run is invalid: the first that holds, in this order (A3.8 #22). */
|
|
90
|
+
export const INVALID_REASONS = ['cancelled', 'crash', 'inputs', 'writes', 'cut', 'frames', 'errors', 'bakes', 'gesture', 'records'] as const
|
|
91
|
+
export type InvalidReason = (typeof INVALID_REASONS)[number]
|
|
92
|
+
|
|
93
|
+
/** One line of `design/.local/perf/runs.jsonl` (A3.4, A3.8 #22). */
|
|
94
|
+
export interface RunLine {
|
|
95
|
+
v: 1
|
|
96
|
+
script: typeof RUN_SCRIPT
|
|
97
|
+
run: string
|
|
98
|
+
/** 'app' is the later real-window run (A3.4's last bullet) */
|
|
99
|
+
where: 'headless' | 'app'
|
|
100
|
+
ts: number
|
|
101
|
+
board: string
|
|
102
|
+
/** the fingerprint at the start (A3.8 #21) - once the warm-up has loaded the board: every watched file under the
|
|
103
|
+
* root, the board files and `_sizes.json`, and the watched files outside the root that the run's own warm-up page
|
|
104
|
+
* loaded, with their direct imports (the review of a3-runs' fixes: never another page's), so it depends on the board
|
|
105
|
+
* and the files alone. A later `where: 'app'` producer must fingerprint the same set. Null when the watcher was not
|
|
106
|
+
* ready - the run is invalid 'inputs' */
|
|
107
|
+
inputs: { hash: string; files: number } | null
|
|
108
|
+
/** the same files' fingerprint after the end and the 300 ms wait */
|
|
109
|
+
inputsEnd: string | null
|
|
110
|
+
frames: number | null
|
|
111
|
+
marver: string
|
|
112
|
+
chrome: string
|
|
113
|
+
flags: string[]
|
|
114
|
+
/** SystemInfo.getInfo's feature status and device */
|
|
115
|
+
renderer: { gpuCompositing?: string; rasterization?: string; vendor?: string; device?: string } | null
|
|
116
|
+
/** the headless profile's hash */
|
|
117
|
+
machine: string
|
|
118
|
+
host: HostProfile
|
|
119
|
+
power: 'ac' | 'battery' | 'unknown'
|
|
120
|
+
slow: boolean
|
|
121
|
+
/** the warm-up reached settled and bake-idle within 60 s */
|
|
122
|
+
bakes: 'warm' | 'cold'
|
|
123
|
+
postersMissing: number
|
|
124
|
+
/** heights known at start */
|
|
125
|
+
saved: { measuring: number; savedHeights: number } | null
|
|
126
|
+
/** from navigation start: `load.sinceNav + settled.ms`, on the page's monotonic clock (A3.8 #20) */
|
|
127
|
+
loadToSettledMs: number | null
|
|
128
|
+
/** from A1's load request */
|
|
129
|
+
settledMs: number | null
|
|
130
|
+
moves: number
|
|
131
|
+
lateMoves: number
|
|
132
|
+
/** the driver's own gestures (of three) whose end the shell reported - never the page's count since its load, which
|
|
133
|
+
* a fit's own motion raises (the review of a3-runs' fixes) */
|
|
134
|
+
gestures: number
|
|
135
|
+
p50: number | null
|
|
136
|
+
p95: number | null
|
|
137
|
+
/** null when no frame was timed (the review of a3-runs: widened from `number` - "not measured" is not "no slow
|
|
138
|
+
* frames"); a valid run always has it */
|
|
139
|
+
over33ms: number | null
|
|
140
|
+
/** Runtime.getHeapUsage at 1 Hz */
|
|
141
|
+
heapPeakMB: number | null
|
|
142
|
+
errors: number
|
|
143
|
+
/** mutating requests the server refused for this run id */
|
|
144
|
+
forbidden: number
|
|
145
|
+
refusedInPage: number
|
|
146
|
+
/** another run was registered at any moment of this one, or an earlier run's compile was still running when this one
|
|
147
|
+
* started (that run's `bakesPending`): never compared */
|
|
148
|
+
overlapped: boolean
|
|
149
|
+
valid: boolean
|
|
150
|
+
invalidReason?: InvalidReason
|
|
151
|
+
/** the cut's reason, when the load was cut - the recorder's (`timeout`, `hidden`, ...), or the driver's: `unresponsive`
|
|
152
|
+
* (a call to the page went unanswered for 15 s: its main thread stopped, a frame's script that never returns),
|
|
153
|
+
* `overrun` (the run drove past its 7 minutes) and `driver: <why>` (the driver failed for another reason than a
|
|
154
|
+
* crash - a page script that threw between two reads; added by the review of a3-runs' fixes) */
|
|
155
|
+
cut?: string
|
|
156
|
+
/** the dev server restarted in place during the run (an .env or config edit): its inputs changed, and its stream
|
|
157
|
+
* ended - invalid `inputs`, never `cancelled` (A3.8 #22; added by the review of a3-runs) */
|
|
158
|
+
restarted?: true
|
|
159
|
+
/** the run's own compiles were still running 50 s after its end (added by the review of a3-runs' fixes): the next run
|
|
160
|
+
* started beside them, so it is `overlapped` */
|
|
161
|
+
bakesPending?: true
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* `POST /api/perf/run` (work-token gated, A3.8 #22) answers NDJSON: headers at once, then these lines - a phase as
|
|
166
|
+
* each starts, a heartbeat every 10 s (Node's fetch cuts a body silent for 300 s), one `line` per run, then `done`.
|
|
167
|
+
* The body is read whole before a run registers; the response closing early cancels the run.
|
|
168
|
+
*/
|
|
169
|
+
export type RunStreamLine =
|
|
170
|
+
| { phase: 'warm' | 'measured' | 'closing'; run: string }
|
|
171
|
+
| { heartbeat: number }
|
|
172
|
+
| { line: RunLine }
|
|
173
|
+
| { done: true }
|
|
174
|
+
| { error: string }
|
|
175
|
+
|
|
176
|
+
/** The request's body. `repeat` 1-5, 1 by default. */
|
|
177
|
+
export interface RunRequest { board: string; slow?: boolean; repeat?: number }
|
|
@@ -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
|
-
|
|
6
|
-
|
|
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.
|
|
130
|
-
|
|
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,13 @@ 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).
|
|
244
|
+
To compare before and after a change, `npx marver perf run <board> --json` measures the board
|
|
245
|
+
the same way each time, read-only, in the canvas's own headless Chrome; `npx marver perf --runs
|
|
246
|
+
--json` compares the runs with the same inputs, and those after a change.
|
|
228
247
|
- **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
|
|
229
248
|
IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
|
|
230
249
|
that never move on a rename. `title` is what humans see - free text (casing,
|
|
@@ -247,6 +266,8 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
|
|
|
247
266
|
always yours (Show the work, step 1).
|
|
248
267
|
- Do not import from "design/" inside src/ or app/. The arrow points one way.
|
|
249
268
|
- Do not add network calls, app stores, or auth to frames or the presentational screens.
|
|
269
|
+
- Frames cannot register a service worker on the local canvas (it refuses the script): a PWA
|
|
270
|
+
prototype shows its screens, not its offline behaviour.
|
|
250
271
|
- A scene may not be named "components" or "screens".
|
|
251
272
|
|
|
252
273
|
## 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
|
-
|
|
6
|
-
|
|
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.
|
|
130
|
-
|
|
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,13 @@ 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).
|
|
243
|
+
To compare before and after a change, `npx marver perf run <board> --json` measures the board
|
|
244
|
+
the same way each time, read-only, in the canvas's own headless Chrome; `npx marver perf --runs
|
|
245
|
+
--json` compares the runs with the same inputs, and those after a change.
|
|
227
246
|
- **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
|
|
228
247
|
IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
|
|
229
248
|
that never move on a rename. `title` is what humans see - free text (casing,
|
|
@@ -247,6 +266,8 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
|
|
|
247
266
|
- Do not import from "design/" inside src/ or app/. The arrow points one way.
|
|
248
267
|
- Do not add network calls, app stores, or auth to frames. Mocked data only.
|
|
249
268
|
- Keep each frame self-sufficient: it must render from its file + fixtures + ui imports alone.
|
|
269
|
+
- Frames cannot register a service worker on the local canvas (it refuses the script): a PWA
|
|
270
|
+
prototype shows its screens, not its offline behaviour.
|
|
250
271
|
- A scene may not be named "components" or "screens".
|
|
251
272
|
|
|
252
273
|
## Promotion (when a design is approved)
|
package/templates/demo/dark.tsx
CHANGED
|
@@ -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' },
|
|
@@ -298,7 +298,9 @@ brief counts unless it says otherwise), never Blocked, never a reason.
|
|
|
298
298
|
|
|
299
299
|
The published gate page shows the app's identity: `design/logo.svg` + the host
|
|
300
300
|
package name (overridable via config `share`). If the app has no logo asset yet,
|
|
301
|
-
create a simple `design/logo.svg`.
|
|
301
|
+
create a simple `design/logo.svg`. The same logo wears the canvas's tab in the Mac
|
|
302
|
+
app. It counts only as a real file in the repo (never a symlink), at most 256 KB,
|
|
303
|
+
whose bytes are an SVG, a PNG or an ICO. Leave `share.branding` ON unless the human
|
|
302
304
|
explicitly asks to remove it: marver is free, the gate is already personalized to
|
|
303
305
|
the app, and the small "Powered by" line is how the tool spreads. Do not remove it
|
|
304
306
|
as part of "branding polish".
|
|
@@ -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.
|
|
111
|
-
|
|
112
|
-
|
|
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
|