@marver-design/marver 0.3.1 → 0.4.0

package/templates/instructions/configure.md

@@ -39,6 +39,34 @@ canvas, the tour - that flow lives in instructions/welcome.md, run it alongside.
   several half-brands - document the one the app actually ships in DESIGN.md and
   name the others as legacy.
 
+## Working with teammates (branches, merges, a second engineer)
+
+The whole `design/` folder is git-tracked - boards, scenes, comment logs, the
+publish policy, these instructions. Only `design/.local/` (this machine's
+connect credential) and `design/.dist/` (built on the host) are ignored. So a
+teammate gets the exact canvas by pulling the branch: `pnpm install` →
+`npx marver dev`. Nothing else to sync.
+
+How the three kinds of design state merge across branches:
+
+- **Comment logs (`design/comments/*.jsonl`) merge themselves.** They're
+  append-only and keyed by event id, and init writes a `merge=union` git
+  attribute for them - two branches that both collected feedback union
+  cleanly, no conflict. Even a hand-botched merge self-heals: replay dedupes
+  by id. This is the point of the event-log design - multiplayer comments
+  Just Work through plain git.
+- **Scenes (`design/scenes/**.tsx`) merge like any code** - they're React
+  components. Standard review, standard conflicts.
+- **Boards (`design/boards/*.json`) are the one friction** - they're node
+  positions, so two people rearranging the same board conflict on x/y. It's
+  cosmetic: take either side and re-run Tidy, or give features their own
+  boards so layouts don't overlap. Never let a boards conflict block a merge.
+
+If collaboration is deployed, each engineer runs `marver comments connect
+<url>` ONCE with their own account (the owner invites them) to get the live
+cloud sync on top of git. Git carries the committed comments; `connect` adds
+the real-time stream from published viewers.
+
 ## When it breaks mid-project
 
 Frames suddenly unstyled → the theme import path moved: fix `design/theme.css`.

package/templates/instructions/iterate.md

@@ -48,3 +48,41 @@ The human picks a direction; then, in one pass:
 Archived frames are history, not options: never link them from live flows,
 never count them as current design. They exist so "what did we try for the
 editor?" has a visual answer.
+
+## Comments are your work queue
+
+When collaboration is on, humans pin comments to specific elements inside
+frames. Those threads are addressed to YOU as much as to the designer - treat
+the open list as a queue:
+
+```bash
+npx marver comments list --open --json     # what needs you (anchors included)
+npx marver comments reply <thread> --body "…"
+npx marver comments resolve <thread> --addressed-in <scene/frame>
+```
+
+The discipline:
+
+1. **Read the anchor before the words.** Each thread carries the element it
+   points at - tag, quote, source hint, position. "Too cramped" pinned to a
+   button is a different task than "too cramped" on the whole frame.
+2. **Fork, don't overwrite.** Address feedback by creating a NEW variant of the
+   frame (the letter convention above) and iterating there. The commented
+   frame stays as the before; your variant is the after.
+3. **Resolve with the receipt.** `--addressed-in <the-new-variant>` records
+   WHICH frame answered the feedback - the thread becomes an auditable link
+   from complaint to fix. Reply first when the change deserves a sentence of
+   explanation; resolve silently only for trivial mechanical fixes.
+4. **Never resolve what you didn't address.** Disagree? Reply with your
+   reasoning and leave the thread open - the human closes debates, you close
+   completed work.
+5. **A frame with open comments is load-bearing - never delete, rename, or
+   gut it.** Its threads are anchored to elements INSIDE it; restructure the
+   frame and the anchors strand (a dead anchor parks the pin at the frame
+   edge; deleting the whole frame strands the thread off-canvas entirely -
+   never lost from the log, but invisible until the frame returns). So: fork
+   the variant and iterate THERE, leave the commented frame untouched as the
+   before, and only once you `resolve --addressed-in <variant>` its threads
+   may it move to `archive/`. Resolve first, restructure second - never the
+   reverse. Check `comments list --board <b>` (no `--open`) to see resolved
+   threads too; the full history lives in the append-only log and in git.

package/templates/instructions/publish.md

@@ -0,0 +1,129 @@
+# Publish - put the canvas on a URL, collaboration included
+
+Publishing is three decisions, then one build and one process. A coding agent can
+run the whole thing; nothing here needs a human at a dashboard except pasting env
+vars if the host has no CLI.
+
+## The three decisions
+
+1. **Which boards ship, with which rights** - `design/publish.json`:
+
+   ```json
+   { "boards": { "release-review": "comment", "roadmap": "read" } }
+   ```
+
+   `read` = visible to anyone past the gate. `comment` = signed-in accounts can
+   also pin threads. Boards not listed do not ship at all - their frames are not
+   even in the bundle. `marver build` FAILS without this file (default-closed);
+   `--boards a,b` overrides ad hoc (grants comment), `--all-boards` ships
+   everything loudly.
+
+2. **The canvas password** - `MARVER_PASSWORD` at serve time. This is the READ
+   boundary: one shared password for GUESTS. Members never need it - their own
+   account signs them in at the gate, and invite links skip it entirely (the
+   token is the authorization). Rotating it therefore only affects guests.
+   No env var = an open canvas.
+
+3. **Collaboration on or off** - `MARVER_DATA_DIR` at serve time. Set it to a
+   path on a PERSISTENT disk and the serve grows accounts + live comments.
+   Leave it unset for a static, comment-free canvas. Setting it to ephemeral
+   container disk is the one real deploy mistake - comments would vanish on
+   redeploy; marver fails loudly if the dir cannot be created.
+
+## The serve contract (env vars, complete list)
+
+| Var | Meaning |
+|---|---|
+| `PORT` | listen port (hosts inject this) |
+| `MARVER_PASSWORD` | canvas password (guests' read credential); unset = open |
+| `MARVER_DATA_DIR` | persistent dir for `comments/` + `auth.json`; unset = no collaboration |
+| `MARVER_OWNER_EMAIL` | prints a single-use OWNER claim link in the deploy logs on first boot |
+| `MARVER_TRUSTED_PROXY` | set to `1` behind a reverse proxy (Railway, Fly) so rate limits see real IPs |
+
+## The host contract (works on any volume-capable host)
+
+The host does two things, and the deploy config names both. **`design/.dist` is
+gitignored - it is built ON THE HOST at deploy time, never committed.**
+
+- **build command**: `<install> && npx marver build` (respects `publish.json`,
+  seeds comment logs into the bundle)
+- **start command**: `npx marver serve` (reads `PORT` + the env vars above)
+- a **persistent volume** mounted at some path, named by `MARVER_DATA_DIR`
+
+The `@marver-design/marver` dependency must resolve from the registry (a local
+`link:`/`file:` dep cannot ride to a remote host) - a normal `^0.4.0` in
+`package.json` is all it takes.
+
+## Railway quickstart
+
+Commit a `railway.json` so `railway up` knows how to build and serve:
+
+```json
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": { "builder": "NIXPACKS", "buildCommand": "pnpm install && npx marver build" },
+  "deploy": { "startCommand": "npx marver serve" }
+}
+```
+
+Then, once per service:
+
+```bash
+railway init                      # or `railway link` an existing service
+railway volume add --mount-path /data
+railway variables --set MARVER_PASSWORD=<pw> --set MARVER_DATA_DIR=/data \
+  --set MARVER_OWNER_EMAIL=<owner@email> --set MARVER_TRUSTED_PROXY=1
+railway up                        # uploads the repo; Railway runs build then start
+railway logs                      # ← the owner claim LINK prints here, once (see below)
+```
+
+Republishing is just `railway up` again: the server unions the seeded logs on
+boot, so collected feedback is NEVER clobbered by a new build. Run ONE instance -
+the event log is single-writer by design.
+
+## What the deployed gate offers (so you know what you're wiring)
+
+On a collaboration canvas the gate has three doors, one credential each:
+- **Guest** - the canvas password → read-only across published boards.
+- **Member** - "Sign in instead" → their own email + password → read + comment.
+  A member session IS gate passage; they never touch the shared password again.
+- **Invited** - opening an invite link → set a display name + password (+ optional
+  avatar) → account created, read + comment. The link skips the canvas password.
+
+## Wiring people up (after first deploy)
+
+`MARVER_OWNER_EMAIL` makes the first boot print an owner bootstrap in the logs:
+a browser link (`<url>/#/i/<token>`) AND the exact repo command. The token is
+single-use. Claim it from the repo so this machine can mint invites:
+
+```bash
+# 1. claim the owner account - copy the command the deploy logs printed:
+marver comments connect https://canvas.example.com --invite <token-from-logs>
+
+# 2. invite each colleague - one command, one link, no email infrastructure
+marver comments invite colleague@company.com
+#    → prints a single invite LINK (<url>/#/i/<token>). Send it over Slack/DM
+#    with the canvas password. It opens straight into the claim (name +
+#    password + optional avatar). Single-use; 7-day expiry.
+
+# 3. the loop is now closed
+marver dev                        # two-way syncs comments every 30s
+marver comments list --open       # the agent's work queue
+marver comments reply <thread> --body "..."          # answer in the loop
+marver comments resolve <thread> --addressed-in <frame>   # close with a receipt
+marver comments revoke <email>    # kills the account + its sessions, mid-flight
+```
+
+Share the canvas as `<url>/#/b/<board>` (with the canvas password), or copy-link
+on any thread for a deep link straight to it - the gate carries deep links
+through sign-in.
+
+## What lands where (so you can reason about persistence)
+
+- `design/publish.json` - the policy, git-tracked, part of the repo.
+- `<MARVER_DATA_DIR>/comments/<board>.jsonl` - the live event log, on the volume.
+- `<MARVER_DATA_DIR>/auth.json` - accounts (scrypt), sessions, invites, on the volume.
+- `design/comments/<board>.jsonl` - the dev-side mirror, git-tracked: feedback
+  has history, and the volume has an off-site replica for free.
+- `design/.local/collab.json` - THIS machine's device credential. Gitignored;
+  never commit it.

package/dist/serve-OtA9Nlow.mjs

@@ -1,207 +0,0 @@
-import { n as NAME } from "./cli.mjs";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
-import { extname, isAbsolute, join, relative, resolve } from "node:path";
-import { createHmac, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
-import { createServer } from "node:http";
-//#region src/server/serve.ts
-/**
-* `marver serve` - a zero-dependency static server for design/.dist with an optional
-* password gate (SPEC-M2 §4b). No MARVER_PASSWORD → plain static serving. With it, the
-* bundle is never sent pre-auth: every unauthenticated request gets the gate page, auth
-* is a POST compare + an HMAC-signed 30-day cookie keyed off the password itself (all
-* instances agree, nothing stored server-side).
-*/
-const MIME = {
-	".html": "text/html; charset=utf-8",
-	".js": "text/javascript",
-	".mjs": "text/javascript",
-	".css": "text/css",
-	".json": "application/json",
-	".svg": "image/svg+xml",
-	".png": "image/png",
-	".ico": "image/x-icon",
-	".webmanifest": "application/manifest+json",
-	".woff": "font/woff",
-	".woff2": "font/woff2",
-	".map": "application/json",
-	".txt": "text/plain"
-};
-const COOKIE = "mv_a";
-const MONTH = 2592e3;
-function serve(root, portFlag) {
-	const dist = join(root, "design", ".dist");
-	if (!existsSync(join(dist, "index.html"))) {
-		console.error(`[${NAME}] design/.dist not found - run \`npx ${NAME} build\` first.`);
-		process.exit(1);
-	}
-	const realDist = realpathSync(dist);
-	let meta = {
-		name: "Marver",
-		branding: true
-	};
-	try {
-		meta = {
-			...meta,
-			...JSON.parse(readFileSync(join(dist, "meta.json"), "utf8"))
-		};
-	} catch {}
-	const password = process.env.MARVER_PASSWORD ?? "";
-	const verifier = password ? scryptSync(password, "marver-gate", 32) : null;
-	const cookieKey = randomBytes(32);
-	const sign = (exp) => createHmac("sha256", cookieKey).update(`v1.${exp}`).digest("hex");
-	const authed = (req) => {
-		const m = /(?:^|;\s*)mv_a=(\d+)\.([0-9a-f]+)/.exec(String(req.headers.cookie ?? ""));
-		if (!m) return false;
-		const exp = Number(m[1]);
-		if (!Number.isFinite(exp) || exp * 1e3 < Date.now()) return false;
-		const want = Buffer.from(sign(exp)), got = Buffer.from(m[2]);
-		return want.length === got.length && timingSafeEqual(want, got);
-	};
-	const server = createServer((req, res) => {
-		const url = new URL(req.url ?? "/", "http://x");
-		if (verifier) {
-			if (req.method === "POST" && url.pathname === "/__mv/auth") {
-				let body = "";
-				req.on("data", (c) => {
-					body += c;
-					if (body.length > 1e4) req.destroy();
-				});
-				req.on("end", () => {
-					const form = new URLSearchParams(body);
-					const given = form.get("password") ?? "";
-					if (timingSafeEqual(scryptSync(given, "marver-gate", 32), verifier)) {
-						const exp = Math.floor(Date.now() / 1e3) + MONTH;
-						const secure = req.headers["x-forwarded-proto"] === "https" ? "; Secure" : "";
-						res.setHeader("set-cookie", `${COOKIE}=${exp}.${sign(exp)}; Path=/; Max-Age=${MONTH}; HttpOnly; SameSite=Lax${secure}`);
-						const next = form.get("next") ?? "";
-						res.statusCode = 303;
-						res.setHeader("location", /^#\/[\w\/?&=%.,~-]*$/.test(next) ? `/${next}` : "/");
-						return res.end();
-					}
-					return gate(res, meta, "Wrong password - try again");
-				});
-				return;
-			}
-			const cosmetic = url.pathname.startsWith("/__mv/favicon/") || /^\/__mv\/logo\.(svg|png)$/.test(url.pathname);
-			if (!authed(req) && !cosmetic) return gate(res, meta);
-		}
-		let path;
-		try {
-			path = decodeURIComponent(url.pathname);
-		} catch {
-			res.statusCode = 400;
-			return res.end("bad request");
-		}
-		if (path.endsWith("/")) path += "index.html";
-		let file = resolve(dist, path.slice(1));
-		try {
-			const real = realpathSync(file);
-			const rel = relative(realDist, real);
-			if (rel.startsWith("..") || isAbsolute(rel)) throw new Error("outside dist");
-			file = real;
-		} catch {
-			file = join(dist, "index.html");
-		}
-		if (!extname(file)) file = join(dist, "index.html");
-		try {
-			const content = readFileSync(file);
-			res.setHeader("content-type", MIME[extname(file)] ?? "application/octet-stream");
-			const cache = verifier ? "private, no-store" : file.startsWith(join(dist, "assets")) ? "public, max-age=31536000, immutable" : "no-store";
-			res.setHeader("cache-control", cache);
-			res.end(content);
-		} catch {
-			res.statusCode = 404;
-			res.end("not found");
-		}
-	});
-	const port = portFlag ?? (Number(process.env.PORT) || 4199);
-	server.on("error", (err) => {
-		if (err.code === "EADDRINUSE") {
-			console.error(`[${NAME}] port ${port} is already in use - another \`${NAME} serve\` still running? Stop it, or pass --port <n>.`);
-			process.exit(1);
-		}
-		throw err;
-	});
-	server.listen(port, () => {
-		console.log(`\n  ${NAME} serving design/.dist → http://localhost:${port}/`);
-		console.log(verifier ? "  gate: ON (MARVER_PASSWORD set)\n" : "  gate: off - set MARVER_PASSWORD to require a password\n");
-	});
-	return server;
-}
-/** The Marver logo mark (ParallelogramDuo, same as the shell's sidebar). */
-const MARK_AT = (size) => `<svg viewBox="0 0 256 256" width="${size}" height="${size}" fill="currentColor" aria-hidden><path d="M239.29,59.28l-64.8,144a8,8,0,0,1-7.3,4.72H24a8,8,0,0,1-7.3-11.28l64.8-144A8,8,0,0,1,88.81,48H232A8,8,0,0,1,239.29,59.28Z" opacity=".1"/><path d="M245.43,47.31A15.94,15.94,0,0,0,232,40H88.81a16,16,0,0,0-14.59,9.43l-64.8,144A16,16,0,0,0,24,216H167.19a16,16,0,0,0,14.59-9.43l64.8-144A16,16,0,0,0,245.43,47.31ZM167.19,200H24L88.81,56H232Z"/></svg>`;
-const MARK = MARK_AT(17);
-const MARK_LG = MARK_AT(24);
-/** The gate: the canvas's own antechamber - light ground, dot grid, glass card in the
-*  shell's exact token language. The visitor is one password away from stepping in. */
-function gate(res, meta, error) {
-	const name = meta.name ? meta.name[0].toUpperCase() + meta.name.slice(1) : "Marver";
-	const appMark = meta.logo ? `<img src="${esc(meta.logo)}" alt="" width="24" height="24" />` : MARK_LG;
-	const title = meta.branding ? `${name} | Marver - Visualize your software` : name;
-	const desc = meta.branding ? `${name}, shared as a live Marver canvas - real screens and prototypes, built from the codebase. Marver is the agent-native design canvas.` : `${name} - a private design canvas.`;
-	res.statusCode = 200;
-	res.setHeader("content-type", "text/html; charset=utf-8");
-	res.setHeader("cache-control", "no-store");
-	res.end(`<!doctype html>
-<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${esc(title)}</title>
-<meta name="description" content="${esc(desc)}" />
-<meta name="robots" content="noindex" />
-<meta name="theme-color" content="#e7e9ef" />
-<meta property="og:title" content="${esc(title)}" />
-<meta property="og:description" content="${esc(desc)}" />
-${meta.branding ? "<meta property=\"og:site_name\" content=\"Marver\" />" : ""}
-<meta property="og:type" content="website" />
-<meta name="twitter:card" content="summary" />
-<link rel="icon" href="/__mv/favicon/favicon.ico" sizes="48x48" />
-<link rel="icon" type="image/png" sizes="32x32" href="/__mv/favicon/favicon-32x32.png" />
-<link rel="icon" type="image/png" sizes="16x16" href="/__mv/favicon/favicon-16x16.png" />
-<link rel="apple-touch-icon" href="/__mv/favicon/apple-touch-icon.png" />
-<style>
-  * { box-sizing: border-box; margin: 0 }
-  body { min-height: 100vh; display: flex; align-items: center; justify-content: center;
-    background-color: #e7e9ef;
-    background-image: radial-gradient(#c9cbd5 1px, transparent 1px); background-size: 20px 20px;
-    font: 500 14px -apple-system, system-ui, sans-serif; color: #18181b;
-    -webkit-font-smoothing: antialiased }
-  main { display: flex; flex-direction: column; align-items: center; gap: 22px; padding: 16px }
-  form { width: 340px; padding: 24px; border-radius: 24px; display: flex; flex-direction: column; gap: 14px;
-    background: rgba(255, 255, 255, .64); backdrop-filter: blur(20px); -webkit-backdrop-filter: blur(20px);
-    border: 1px solid rgba(24, 24, 27, .1);
-    box-shadow: inset 0 1px 0 rgba(255, 255, 255, .65), 0 1px 2px rgba(24, 24, 27, .05), 0 4px 12px -6px rgba(24, 24, 27, .12) }
-  header { display: flex; align-items: center; gap: 10px; padding: 4px 2px 4px 4px }
-  header svg, header img { color: #0088ff; flex: none; border-radius: 6px }
-  h1 { font-size: 17px; font-weight: 600; letter-spacing: -.01em }
-  p { font-size: 12.5px; line-height: 1.5; color: rgba(24, 24, 27, .66); padding: 0 4px }
-  input { height: 40px; padding: 0 16px; border-radius: 999px; border: 1px solid rgba(24, 24, 27, .14);
-    background: #fff; color: #18181b; font: inherit; outline: none; transition: border-color .15s, box-shadow .15s }
-  input::placeholder { color: rgba(24, 24, 27, .35) }
-  input:focus { border-color: #0088ff; box-shadow: 0 0 0 3px rgba(0, 136, 255, .18) }
-  button { height: 40px; border: 0; border-radius: 999px; background: #18181b; color: #fafafa;
-    font: 600 13px -apple-system, system-ui, sans-serif; cursor: pointer; transition: background .15s }
-  button:hover { background: #000 }
-  .err { font-size: 12px; color: #b42318; padding: 0 4px }
-  footer a { display: inline-flex; align-items: center; gap: 7px; font: 600 12.5px -apple-system, system-ui, sans-serif;
-    color: rgba(24, 24, 27, .55); text-decoration: none }
-  footer a > svg:first-of-type { width: 20px; height: 20px; color: #0088ff }
-  footer .md, footer .up { transition: color .15s, opacity .15s }
-  footer a:hover .md { color: #0088ff; text-decoration: underline; text-underline-offset: 3px }
-  footer .up { opacity: .45; margin-left: -3px }
-  footer a:hover .up { opacity: 1; color: #0088ff }
-</style></head>
-<body><main>
-  <form method="post" action="/__mv/auth">
-    <header>${appMark}<h1>${esc(name)}</h1></header>
-    <p>You're one step from the canvas. This space is private - enter the password to step inside.</p>
-    ${error ? `<div class="err">${esc(error)}</div>` : ""}
-    <input type="password" name="password" placeholder="Password" autofocus autocomplete="current-password" />
-    <input type="hidden" name="next" />
-    <button type="submit">Open the canvas</button>
-  </form>
-  <script>document.querySelector('[name=next]').value = location.hash<\/script>
-  ${meta.branding ? `<footer><a href="https://marver.design" target="_blank" rel="noopener">${MARK} <span>Powered by <span class="md">Marver.design</span></span> <svg class="up" viewBox="0 0 256 256" width="11" height="11" fill="currentColor" aria-hidden><path d="M200,64V168a8,8,0,0,1-16,0V83.31L69.66,197.66a8,8,0,0,1-11.32-11.32L172.69,72H88a8,8,0,0,1,0-16H192A8,8,0,0,1,200,64Z"/></svg></a></footer>` : ""}
-</main></body></html>`);
-}
-const esc = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
-//#endregion
-export { serve };