@marver-design/marver 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,95 @@
 
 Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## 0.15.0 - 2026-09-02
+
+### Added
+
+- **Copy frame as image.** The floating toolbar gains an images-square button
+  (right of Copy path): one click puts the selected frame on the clipboard as
+  a **2x PNG**, rendered by the dev server's headless Chrome - the same picture
+  `marver shot` gives an agent. `i` is the shortcut; `⇧i` (or shift-click)
+  renders at **4x** (a slide is 5120×2880). The icon breathes while the render
+  runs and flashes a check on success, like Copy path. Sized to the node: a
+  frame resized to Laptop copies as Laptop; content frames capture in full;
+  slides are always the 1280×720 artwork. Dev canvases only - a published
+  container has no browser - and one frame at a time.
+- **`marver shot --scale <1-4>`** and `scale=`/`w=`/`h=`/`format=png` on
+  `/api/shot`. A frame too tall for the asked scale steps down (4 → 2 → 1)
+  inside a 16384px-per-side / 64M-pixel capture budget and reports it in
+  `note`; the file name carries the scale actually used (`…@4x.png`), so a
+  4x file always holds 4x pixels.
+- **Render settle.** Every shot (not only content frames) now waits - bounded
+  to 3 s, and again in the final viewport of a full-height capture - for fonts,
+  in-viewport images, LOD decodes, echarts instances and mermaid diagrams before
+  capturing, so a slide with a chart or a photo is never shot half-drawn. Shot
+  file names: a default request keeps its unsuffixed name whatever scale the
+  capture settled on; an explicit scale gets `@4x`, or `@4x-as-2x` when it had
+  to step down, so nothing an agent reads moves and `@4x` never lies.
+
+### Changed
+
+- **Three standing rules for the agent, from dogfooding** (`AGENTS.md`,
+  `boards.md`, `iterate.md`, `jam.md` - refreshed by `marver init`):
+  - **One horizontal band by default.** Every curated board carries a `layout`
+    recipe with the scenes side by side; a second band only when the agent can
+    say why the eye should move down, with a gap that reads as "below". (Without
+    a recipe the shell stacks every scene as its own row.)
+  - **Look sideways.** A pin or a pasted pointer marks where the human noticed
+    a problem, not the only place it lives: the agent checks the board's live
+    sibling frames, fixes the same defect in the same pass and names the frames,
+    or asks in-thread whether to roll it out - never one frame fixed and its
+    siblings left wrong. History (`archive/`, versions) is never a sibling.
+  - **Version the scene before a round.** A round of feedback on a reviewed
+    scene starts with a snapshot, `design/scenes/<scene>-v<N>/`, pinned as its
+    own band on the `archive` board (oldest at the top), with `data-goto`,
+    `goto:` links and `meta.of` re-pointed so the version plays on its own; then
+    the live frames are edited in place and threads answered. One snapshot per
+    round, git commits per version on offer, staging only the round's paths.
+    Rollback is a copy back; the archive is the proof of work.
+
+### Fixed
+
+- **Charts everywhere, not only on slides.** `Chart` now takes its ink and
+  typeface from the frame it sits in (a UI screen's Tailwind colour and font, a
+  Doc's tokens, a Slide's), sizes its type to the context (12px labels in a
+  screen or document, 18px on a slide), paints series labels in that ink with
+  no halo, follows the layout on resize (a chart no longer pins its flex/grid
+  column at mount width), and keys on the option's content so a parent
+  re-render never re-initialises it (a viewer's dataZoom or legend selection
+  survives, and a formatter edit reaches the live chart). Before this a chart
+  in a dark screen or dark spec drew dark-on-dark axis text at slide scale.
+- **Video plays everywhere, not only on slides.** The player used to mount
+  only under the slides-mode contract, so a `Video` in a screen, a spec or a
+  published prototype was a poster forever. Now the poster is the play button
+  wherever the frame is live (interact, play, focus, published); slides keep
+  the auto-mounted player, and leaving interact mode on the canvas disarms a
+  playing clip so the frame goes still again. New: `ratio="9 / 16"` for
+  vertical clips, and `autoplay` for a muted ambient loop (an explicit choice -
+  that frame stays live on the canvas). The player's glyphs are Phosphor
+  (play, pause, speaker, corners). `shape.md` and `craft.md` teach it.
+- **Posters render themselves.** A local clip without `poster` no longer fails
+  the build: marver renders `<clip>.poster.png` beside it from the clip's own
+  first moments (at 0.5 s, past the usual black opening) in the same headless
+  Chrome the shot renderer uses - the dev server on first sight (the frame
+  asks when its conventional poster is missing), `marver build` before assets
+  are copied, and `shot` before a frame's first capture. Posters render on
+  their own capture lane, so a frame's poster never waits behind the shot that
+  needs it. An authored poster always wins; without Chrome the build says
+  exactly which file to add.
+- **A screen with a chart is still a screen.** Importing anything from
+  `@marver-design/marver/content` used to turn the frame into a content
+  document (spec badge, measured height, no device). Content frames are now
+  those that render `Doc`, `Md`, `Diagram` or `Img`; `Chart`, `Video`, `Row`,
+  `Col` and `Space` are shared blocks a screen or a slide uses freely. The
+  block card (padding, hairline, surface) is a document treatment: inside a
+  slide or a screen a block is bare, so charts no longer carry 32px of
+  invisible padding there. `shape.md` and `craft.md` now teach `Chart`.
+- **Dev server behind a symlinked path.** `marver dev` on a repo reached
+  through a symlink (`/tmp` → `/private/tmp`, a linked Dropbox folder) refused
+  to serve its own frames ("outside of Vite serving allow list"); the allow
+  list now carries the realpath too.
+
 ## 0.14.0 - 2026-09-02
 
 ### Added

package/README.md

@@ -45,6 +45,8 @@ Frames appear on the canvas the moment the files land. That's the loop.
 - **Prototype links.** `data-goto="scene/frame"` on any element links frames into a walkable prototype - across boards, too.
 - **Five ways to view a board.** The canvas (frames on a plane), the board (the same, tidy), **present** (`p`: a full-screen clickable walkthrough - `data-goto` navigates, arrows step, `[` / `]` cycle variants, laser, comments, theme and device pickers in the toolbar), **focus** (one frame as a document - the reading preset for specs), and **slides** (a deck). A published board names its landing view; a frame deep link opens straight into it.
 - **Content frames.** Specs, Mermaid diagrams, mood boards, and slides live on the same canvas as the screens - import `Doc`, `Md`, `Diagram`, `Img`, `Slide`, `Chart`, `Video` from `@marver-design/marver/content` and think a feature through before any pixels exist. Works in a repo with no app at all: idea first, design second.
+- **Charts and video in any frame.** `Chart` (Apache ECharts, SVG, still at rest) inherits the ink, typeface and accent of whatever frame it sits in - a Tailwind dashboard, a dark spec, a slide - sizes its type to the context and follows the layout on resize. `Video` is poster-first everywhere: click to play wherever the frame is live, `autoplay` for an ambient loop, `ratio` for vertical clips; omit the poster and marver renders one from the clip. A screen with a chart or a clip is still a screen.
+- **Copy as image.** Select a frame, press `i` - a 2x PNG of it lands on the clipboard, rendered by the same headless Chrome that serves `marver shot`; `⇧i` for 4x (a slide is 5120×2880). Paste into Slack, a doc, or a chat with your agent.
 
 ## Slides
 
@@ -82,7 +84,7 @@ The trust boundary is hard: only comments written on the owner's machine trigger
 
 ## Working state
 
-The same glow, driven from the terminal. When your agent takes a request, it creates the frame files first, pins them on a board, and runs `npx marver work start <scene/frame ...>` - you see the work land on the canvas in seconds, watch it shimmer while subagents build in parallel, and see it settle on `work done`. Marks self-expire, so a crashed agent never leaves a frame glowing. And `npx marver shot <scene/frame>` renders one frame headless to a PNG, so the agent can look at what it built before it says it is done.
+The same glow, driven from the terminal. When your agent takes a request, it creates the frame files first, pins them on a board, and runs `npx marver work start <scene/frame ...>` - you see the work land on the canvas in seconds, watch it shimmer while subagents build in parallel, and see it settle on `work done`. Marks self-expire, so a crashed agent never leaves a frame glowing. And `npx marver shot <scene/frame> [--scale 4]` renders one frame headless to a PNG, so the agent can look at what it built before it says it is done - the same picture you get from the canvas's copy-as-image.
 
 ## Commands
 
@@ -95,7 +97,7 @@ The same glow, driven from the terminal. When your agent takes a request, it cre
 | `npx marver share …` | The roster (owner): `add <who> [--role]` · `remove` · `block` / `unblock` · `general <mode>` · `list` · `requests` · `explain <who>` · `who` |
 | `npx marver comments …` | The agent's queue: `connect <url>` · `sync` · `list` · `reply` · `resolve` · `invite <email>` · `revoke <email>` |
 | `npx marver work …` | Working glow from the terminal: `start <scene/frame …>` · `done … \| --all` · `list` |
-| `npx marver shot <frame>` | Render one frame headless and print the PNG path (needs `dev` running) |
+| `npx marver shot <frame> [--scale 1-4]` | Render one frame headless and print the PNG path (needs `dev` running); 2x by default |
 
 ## Shortcuts
 
@@ -108,7 +110,7 @@ The same glow, driven from the terminal. When your agent takes a request, it cre
 
 **Board & chrome** - `t` tidy · `d` toggle light/dark for the board · `⌘\` (ctrl+\) collapse/open sidebar.
 
-**Selection** - click selects · shift+click (canvas or sidebar) builds a multi-selection · `⌘A` selects every frame on the board · `⇧P` copies the selected frames' paths (board, frame, and file) · double-click enters interact mode (`esc` or click outside leaves) · drag the title bar to move, edges to resize (widths snap to devices).
+**Selection** - click selects · shift+click (canvas or sidebar) builds a multi-selection · `⌘A` selects every frame on the board · `⇧P` copies the selected frames' paths (board, frame, and file) · `i` copies the selected frame to the clipboard as a 2x PNG (`⇧i` for 4x; also the images-square button in the floating toolbar - dev canvases only, the renderer is the dev server's headless Chrome) · double-click enters interact mode (`esc` or click outside leaves) · drag the title bar to move, edges to resize (widths snap to devices).
 
 **Modes** - `c` comment mode · `l` laser mode · `⇧C` hide/show comment pins · `⇧L` laser comment (spotlight a thread's element) · `p` play (present, or slides on a slides board) · `h` hide all chrome.
 

package/dist/{build-ByYafIhj.mjs → build-DfuTQZlY.mjs}

@@ -1,6 +1,6 @@
 import { i as ROUTE, n as NAME } from "./cli.mjs";
-import { l as detectHost, r as scanFrames, s as loadConfig } from "./manifest-DvOmglFp.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-BsmG5i2X.mjs";
+import { l as detectHost, r as scanFrames, s as loadConfig } from "./manifest-BzxSMoDB.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DJyjmQeh.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -44,8 +44,9 @@ function scanAssetRefs(src, moduleId) {
 		const srcM = /\bsrc\s*=\s*["']([^"']+)["']/.exec(tag);
 		const posterM = /\bposter\s*=\s*["']([^"']+)["']/.exec(tag);
 		if (srcM) {
-			if (!/^https:\/\//.test(srcM[1]) && !posterM) throw new Error(`${moduleId}: <Video src="${srcM[1]}"> is a local file without a poster - the poster is the slide at rest. Add poster="...".`);
+			const remote = /^https:\/\//.test(srcM[1]);
 			out.push(srcM[1]);
+			if (!remote && !posterM) out.push(`${srcM[1]}.poster.png`);
 		}
 		if (posterM) out.push(posterM[1]);
 	}
@@ -458,6 +459,13 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 	}
 	let copiedAssets = 0;
 	const realAssets = existsSync(assetsDir) ? realpathSync(assetsDir) : null;
+	for (const r of refs) {
+		if (!isLocalAssetRef(r) || !r.endsWith(".poster.png") || existsSync(join(assetsDir, r))) continue;
+		const { ensurePoster } = await import("./poster-CbpzSzJu.mjs");
+		const g = await ensurePoster(assetsDir, r.slice(0, -11));
+		if (!g.ok) throw new Error(`design/assets/${r}: ${g.error}`);
+		console.log(`  poster: rendered design/assets/${r} (${g.width}×${g.height})`);
+	}
 	for (const r of refs) {
 		if (!isLocalAssetRef(r)) continue;
 		const srcFile = join(assetsDir, r);
@@ -526,4 +534,4 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 	console.log(`\n  serve it:  npx ${NAME} serve   (set MARVER_PASSWORD to gate it)\n`);
 }
 //#endregion
-export { buildSite };
+export { buildSite, isLocalAssetRef, scanAssetRefs };

package/dist/cli.mjs

@@ -53,14 +53,14 @@ function version() {
 }
 const cli = cac(NAME);
 cli.command("init", "Scaffold design/ in this repo").option("--mode <mode>", "studio | embedded", { default: "studio" }).option("--no-demo", "Skip the demo scene (the demo ships unless this flag is passed)").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { init } = await import("./init-Dvaso7YO.mjs");
+	const { init } = await import("./init-QKNi9gvF.mjs");
 	init(resolve(opts.root), {
 		mode: opts.mode === "embedded" ? "embedded" : "studio",
 		demo: opts.demo !== false
 	});
 });
 for (const [name, desc] of [["dev", "Start the local canvas (everything on: hot reload, comments, Live Jam)"], ["canvas", "Start the local canvas - same as dev"]]) cli.command(name, desc).option("--root <dir>", "Host repo root", { default: "." }).option("--port <port>", "Port (default 5199)").action(async (opts) => {
-	const { dev } = await import("./dev-yZMyQeUj.mjs");
+	const { dev } = await import("./dev-BxCmeU_H.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -70,7 +70,7 @@ for (const [name, desc] of [["dev", "Start the local canvas (everything on: hot
 	await dev(resolve(opts.root), port);
 });
 cli.command("build", "Static export → design/.dist (what ships comes from design/publish.json - publishing is default-closed)").option("--boards <names>", "Publish only these boards (comma-separated); overrides the publish policy").option("--all-boards", "Publish every board - the loud override for the default-closed policy").option("--embed-seeds", "Copy comment history INTO the web root (identifying - every event carries its author's email)").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { buildSite } = await import("./build-ByYafIhj.mjs");
+	const { buildSite } = await import("./build-DfuTQZlY.mjs");
 	try {
 		const boards = opts.boards === void 0 ? void 0 : typeof opts.boards === "string" ? opts.boards : "";
 		await buildSite(resolve(opts.root), boards, opts.allBoards === true, opts.embedSeeds === true);
@@ -115,8 +115,8 @@ cli.command("work <action> [...frames]", "Working state on the canvas: start <sc
 		process.exit(1);
 	}
 });
-cli.command("shot <frame>", "Render one frame headless and print the PNG path (needs `dev` running)").option("--root <dir>", "Host repo root", { default: "." }).option("--theme <name>", "Theme to render (default: light)").action(async (frame, opts) => {
-	const { shotCommand } = await import("./shot-DkkwuCZ2.mjs");
+cli.command("shot <frame>", "Render one frame headless and print the PNG path (needs `dev` running)").option("--root <dir>", "Host repo root", { default: "." }).option("--theme <name>", "Theme to render (default: light)").option("--scale <n>", "Device pixels per CSS px, 1-4 (default: 2; 4 for print-quality stills)").action(async (frame, opts) => {
+	const { shotCommand } = await import("./shot-By1AItpD.mjs");
 	try {
 		await shotCommand(resolve(opts.root), frame, opts);
 	} catch (err) {

package/dist/{daemon-Bfucyf1o.mjs → daemon-DalgvoA9.mjs}

@@ -1,7 +1,7 @@
 import { n as replay } from "./events-B3LBn74P.mjs";
 import { i as readLog, r as listBoards, t as appendEvents } from "./comments-DZyobpxG.mjs";
 import { n as localProfile } from "./profile-BjAPAJSb.mjs";
-import { i as toFrameId } from "./manifest-DvOmglFp.mjs";
+import { i as toFrameId } from "./manifest-BzxSMoDB.mjs";
 import { workActivity } from "./work-CLrmY-vQ.mjs";
 import { r as deviceId, t as has } from "./ledger-Bu0BjqIe.mjs";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, watch, writeFileSync, writeSync } from "node:fs";

package/dist/{dev-yZMyQeUj.mjs → dev-BxCmeU_H.mjs}

@@ -1,6 +1,6 @@
 import { n as NAME, r as PKG } from "./cli.mjs";
-import { l as detectHost, s as loadConfig } from "./manifest-DvOmglFp.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-BsmG5i2X.mjs";
+import { l as detectHost, s as loadConfig } from "./manifest-BzxSMoDB.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DJyjmQeh.mjs";
 import { realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -18,6 +18,14 @@ const portFree = (p) => new Promise((res) => {
 	s.once("listening", () => s.close(() => res(true)));
 	s.listen(p, "127.0.0.1");
 });
+/** realpath, or the path itself when it cannot be resolved (never throws at boot). */
+const safeReal = (p) => {
+	try {
+		return realpathSync(p);
+	} catch {
+		return p;
+	}
+};
 /** C1: a deterministic per-project port in [5200,5399] derived from the root path. Two projects
 *  never collide, and the same project always lands on the same port across restarts. */
 const projectPort = (root) => {
@@ -189,7 +197,9 @@ async function dev(root, portFlag) {
 			fs: {
 				allow: [.../* @__PURE__ */ new Set([
 					root,
+					safeReal(root),
 					pkgDir,
+					safeReal(pkgDir),
 					searchForWorkspaceRoot(root)
 				])],
 				deny: FS_DENY
@@ -247,7 +257,7 @@ async function dev(root, portFlag) {
 	console.log(`\n  ${NAME} · ${projectName} → http://localhost:${port}/\n`);
 	try {
 		const { staleManagedInstructions } = await import("./managed-HwHVNI3h.mjs");
-		const { installedVersion } = await import("./plugin-BsmG5i2X.mjs").then((n) => n.i);
+		const { installedVersion } = await import("./plugin-DJyjmQeh.mjs").then((n) => n.i);
 		const stale = staleManagedInstructions(root);
 		if (stale.length) {
 			const shown = stale.slice(0, 4).join(", ") + (stale.length > 4 ? `, +${stale.length - 4} more` : "");
@@ -285,7 +295,7 @@ async function dev(root, portFlag) {
 		});
 	}
 	if (config.jam) {
-		const { startJam } = await import("./daemon-Bfucyf1o.mjs");
+		const { startJam } = await import("./daemon-DalgvoA9.mjs");
 		const jam = startJam(root, config.jam, (m) => console.log(m), (board) => server.ws.send("sh:jam-comment", { board }));
 		if (jam) {
 			const close = server.close.bind(server);

package/dist/{init-Dvaso7YO.mjs → init-QKNi9gvF.mjs}

@@ -1,5 +1,5 @@
 import { n as NAME } from "./cli.mjs";
-import { a as writeManifest, c as detectAgent, l as detectHost, o as DEFAULTS, r as scanFrames, u as readJson } from "./manifest-DvOmglFp.mjs";
+import { a as writeManifest, c as detectAgent, l as detectHost, o as DEFAULTS, r as scanFrames, u as readJson } from "./manifest-BzxSMoDB.mjs";
 import { MANAGED_PREFIX, enumerateInstructionTemplates, hashBody, managedFile, pkgDir } from "./managed-HwHVNI3h.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";

package/dist/{manifest-DvOmglFp.mjs → manifest-BzxSMoDB.mjs}

@@ -403,20 +403,31 @@ function extractMeta(src) {
 	if (slide !== void 0) out.slide = slide;
 	return out;
 }
-/** Content-frame detection: LEXICAL by convention - the frame file
-*  itself imports PKG/content (an import specifier scan, so "<Diagram" inside a
-*  string in a UI frame can never misbadge it; barrels/re-exports are not
-*  detected - meta.intent is the taught path and always works). Returns the
-*  inferred intent + natural width, or null for UI frames. */
+/** Content-frame detection: LEXICAL by convention - the frame file itself imports
+*  PKG/content (an import specifier scan, so "<Diagram" inside a string in a UI frame can
+*  never misbadge it; barrels/re-exports are not detected - meta.intent is the taught path
+*  and always works) AND renders a DOCUMENT primitive: Doc, Md, Diagram or Img (reference
+*  imagery - a moodboard is Rows of Img). The import alone is not enough - Chart, Video, Row,
+*  Col and Space are shared blocks a UI screen or a slide uses too, and a dashboard with one
+*  <Chart> is still a screen (device height, no document measuring), never a spec. Returns
+*  the inferred intent + natural width, or null for UI frames. */
 const CONTENT_IMPORT = new RegExp(`from\\s+['"]${PKG}/content['"]`);
 const WIDE_DOC = /<Doc\b[^>]*\blayout\s*=\s*["']wide["']/;
 const contentWidthOf = (src) => WIDE_DOC.test(src) ? CONTENT_WIDTH.wide : CONTENT_WIDTH.document;
+/** The source with comments, template literals and CODE-shaped strings blanked (a JSX
+*  expression string `{'<Diagram>'}`, an attribute value), so a tag name quoted in an example
+*  or a comment never counts as a rendered element. Prose is left alone: JSX text has
+*  apostrophes ("it's"), and a blanket quote match would swallow real tags between two of them. */
+const codeOnly = (src) => src.replace(/`(?:[^`\\]|\\[\s\S])*`/g, "``").replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1").replace(/\{\s*(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*')\s*\}/g, "{\"\"}").replace(/([=(,:[{?+|&!]|\breturn)\s*(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*')/g, "$1\"\"").replace(/([=(,:[{?+|&!]|\breturn)\s*\/(?:[^/\\\n[]|\\.|\[(?:[^\]\\\n]|\\.)*\])+\/[gimsuy]*/g, "$1/re/");
 function contentScan(src) {
 	if (!CONTENT_IMPORT.test(src)) return null;
-	const count = (re) => (src.match(re) ?? []).length;
+	const code = codeOnly(src);
+	const count = (re) => (code.match(re) ?? []).length;
+	const docs = count(/<Doc[\s>/]/g);
 	const diagrams = count(/<Diagram[\s>/]/g);
 	const imgs = count(/<Img[\s>/]/g);
 	const mds = count(/<Md[\s>/]/g);
+	if (docs + diagrams + mds + imgs === 0) return null;
 	return {
 		intent: diagrams > 0 ? "diagram" : imgs > mds ? "moodboard" : "spec",
 		width: contentWidthOf(src)

package/dist/{plugin-BsmG5i2X.mjs → plugin-DJyjmQeh.mjs}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import { i as ROUTE, n as NAME, r as PKG } from "./cli.mjs";
 import { n as localProfile, t as isConnected } from "./profile-BjAPAJSb.mjs";
-import { a as writeManifest, n as hash, r as scanFrames, t as affectedFrameIds } from "./manifest-DvOmglFp.mjs";
+import { a as writeManifest, n as hash, r as scanFrames, t as affectedFrameIds } from "./manifest-BzxSMoDB.mjs";
 import { copyFileSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -283,27 +283,59 @@ function apiMiddleware(root, opts = {}) {
 				if (!ownerGated(req) && !(token && req.headers["x-mv-work"] === token)) return json(res, 403, { error: "forbidden" });
 				const frameId = url.searchParams.get("frame") ?? "";
 				const theme = url.searchParams.get("theme") ?? "light";
+				const scale = url.searchParams.has("scale") ? Number(url.searchParams.get("scale")) : void 0;
+				const dim = (k) => {
+					const v = Math.round(Number(url.searchParams.get(k)));
+					return url.searchParams.has(k) && Number.isFinite(v) ? v : void 0;
+				};
+				const size = {
+					w: dim("w"),
+					h: dim("h")
+				};
+				const asPng = url.searchParams.get("format") === "png";
 				const origin = opts.origin?.() ?? `http://${req.headers.host ?? "localhost"}`;
-				const { shootFrame } = await import("./shot-kbR_xzJH.mjs");
+				const { shootFrame } = await import("./shot-BWhoz6cU.mjs");
 				const r = await shootFrame({
 					root,
 					viewports: opts.viewports ?? {},
 					frameId,
 					theme,
-					origin
+					origin,
+					scale,
+					size
 				});
-				if (!r.ok) return json(res, r.error.startsWith("unknown frame") ? 404 : r.error === "invalid theme" ? 400 : 503, { error: r.error });
-				return json(res, 200, {
+				if (!r.ok) return json(res, r.error.startsWith("unknown frame") ? 404 : r.error.startsWith("invalid ") ? 400 : 503, { error: r.error });
+				const summary = {
 					path: r.path,
 					frame: frameId,
 					theme,
 					width: r.width,
 					height: r.height,
 					scale: r.scale,
-					...r.truncated ? {
-						truncated: true,
-						note: r.note
-					} : {}
+					...r.truncated ? { truncated: true } : {},
+					...r.note ? { note: r.note } : {}
+				};
+				if (!asPng) return json(res, 200, summary);
+				const png = readFileSync(join(root, r.path));
+				res.writeHead(200, {
+					"content-type": "image/png",
+					"content-length": png.length,
+					"cache-control": "no-store",
+					"x-mv-shot": Buffer.from(JSON.stringify(summary)).toString("base64url")
+				});
+				return res.end(png);
+			}
+			if (path === "poster" && req.method === "GET") {
+				if (!ownerGated(req)) return json(res, 403, { error: "forbidden" });
+				const src = url.searchParams.get("src") ?? "";
+				const { ensurePoster, isLocalClip } = await import("./poster-CbpzSzJu.mjs");
+				const { isLocalAssetRef } = await import("./build-DfuTQZlY.mjs");
+				if (!isLocalAssetRef(src) || !isLocalClip(src)) return json(res, 400, { error: "src must be a clip under design/assets/" });
+				const r = await ensurePoster(join(root, "design", "assets"), src);
+				if (!r.ok) return json(res, r.error.includes("does not exist") ? 404 : 503, { error: r.error });
+				return json(res, 200, {
+					path: `design/assets/${src}.poster.png`,
+					generated: r.generated
 				});
 			}
 			if (path === "me" && req.method === "GET") return json(res, 200, {
@@ -817,7 +849,7 @@ function marverPlugin(ctx) {
 								});
 								return;
 							}
-							const { shootFrame } = await import("./shot-kbR_xzJH.mjs");
+							const { shootFrame } = await import("./shot-BWhoz6cU.mjs");
 							write(await shootFrame({
 								root,
 								viewports: config.viewports,

package/dist/poster-CbpzSzJu.mjs

@@ -0,0 +1,143 @@
+import { capture, findChrome } from "./shot-BWhoz6cU.mjs";
+import { constants, copyFileSync, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { randomBytes } from "node:crypto";
+import { tmpdir } from "node:os";
+//#region src/server/poster.ts
+/**
+* Video posters, generated: a local clip without an authored poster gets one rendered
+* from its own first moments - the same headless Chrome the shot renderer drives, no
+* ffmpeg. The convention is `<clip>.poster.png` beside the clip in design/assets/, and
+* the Video primitive reaches for that name whenever `poster` is omitted, so the dev
+* server (on demand, when the frame first asks) and `marver build` (before assets are
+* copied - a published canvas never ships a poster-less video) produce one file both
+* agree on. An authored poster always wins: this only runs when the file is missing.
+*
+* The frame is taken at min(0.5s, half the duration) - the first frame of most clips is
+* black or a fade. The page is a file:// document holding the clip as a file:// <video>,
+* so nothing has to be served; readiness is the video element appearing in #root once
+* the seek lands, which is the shot renderer's own readiness rule.
+*/
+/** The conventional poster path for a local clip reference (relative to design/assets/). */
+const posterNameFor = (src) => `${src}.poster.png`;
+/** Is this a video reference the generator handles (a local design-asset clip)? The same
+*  grammar the client's assetUrl accepts: relative, forward slashes only, no dot segments. */
+const isLocalClip = (src) => !/^https?:\/\//.test(src) && /\.(mp4|webm|mov|m4v|ogv)$/i.test(src) && !src.includes("\\") && !src.includes(":") && !src.startsWith("/") && !src.split("/").some((seg) => seg === ".." || seg === "." || seg === "");
+/** realpath(p) is base or inside it. */
+const inside = (p, base) => {
+	try {
+		const r = realpathSync(p);
+		return r === base || r.startsWith(base + sep);
+	} catch {
+		return false;
+	}
+};
+const PAGE = (video) => `<!doctype html><html><head><meta charset="utf-8"><style>
+html,body{margin:0;background:#000}#root video{display:block}
+</style></head><body><div id="root"></div><script>
+(function(){
+  var v = document.createElement('video');
+  v.muted = true; v.playsInline = true; v.preload = 'auto'; v.src = ${JSON.stringify(video)};
+  var done = false;
+  function show(){ if (done) return; done = true;
+    var w = Math.min(1920, v.videoWidth || 1280), h = Math.round(w * ((v.videoHeight || 720) / (v.videoWidth || 1280)));
+    v.width = w; v.height = h; v.style.width = w + 'px'; v.style.height = h + 'px';
+    document.getElementById('root').appendChild(v) }
+  v.addEventListener('loadedmetadata', function(){
+    var t = Math.min(0.5, (isFinite(v.duration) ? v.duration : 1) / 2);
+    v.addEventListener('seeked', show, { once: true });
+    v.currentTime = t; });
+  v.addEventListener('error', function(){ window.__mvFrameError = 'the clip could not be decoded by this browser (' + (v.error && v.error.code) + ')' ; document.getElementById('root').appendChild(document.createElement('i')) });
+  setTimeout(function(){ if (!done && v.readyState >= 2) show() }, 4000);
+})();
+<\/script></body></html>`;
+/** Render `<clip>.poster.png` for a clip under design/assets/. Idempotent: an existing
+*  poster (authored or generated) is left alone. */
+async function ensurePoster(assetsDir, src) {
+	if (!isLocalClip(src)) return {
+		ok: false,
+		error: `not a local clip: ${src}`
+	};
+	const clip = join(assetsDir, src);
+	const out = join(assetsDir, posterNameFor(src));
+	if (existsSync(out)) return {
+		ok: true,
+		path: out,
+		width: 0,
+		height: 0,
+		generated: false
+	};
+	if (!existsSync(clip)) return {
+		ok: false,
+		error: `design/assets/${src} does not exist`
+	};
+	let realAssets;
+	try {
+		realAssets = realpathSync(assetsDir);
+	} catch {
+		return {
+			ok: false,
+			error: "design/assets/ does not exist"
+		};
+	}
+	if (!inside(clip, realAssets)) return {
+		ok: false,
+		error: `design/assets/${src} resolves outside design/assets/ - not rendered`
+	};
+	if (!inside(dirname(out), realAssets)) return {
+		ok: false,
+		error: `design/assets/${dirname(src)} resolves outside design/assets/ - not rendered`
+	};
+	if (!findChrome()) return {
+		ok: false,
+		error: `no Chrome/Chromium found to render a poster for ${src} - add poster="..." on the <Video>, or install Chrome`
+	};
+	const dir = mkdtempSync(join(tmpdir(), "mv-poster-"));
+	const page = join(dir, "poster.html");
+	writeFileSync(page, PAGE(pathToFileURL(realpathSync(clip)).href));
+	const tmp = join(dirname(out), `.${basename(out)}.${randomBytes(6).toString("hex")}.tmp`);
+	try {
+		const r = await capture({
+			url: pathToFileURL(page).href,
+			width: 1920,
+			height: 1080,
+			scale: 1,
+			out: tmp,
+			fullHeight: false,
+			clip: "#root video",
+			timeoutMs: 2e4
+		}, "poster");
+		if (!r.ok) return {
+			ok: false,
+			error: `could not render a poster for ${basename(src)} - ${r.error}`
+		};
+		try {
+			copyFileSync(tmp, out, constants.COPYFILE_EXCL);
+		} catch (err) {
+			if (err.code === "EEXIST") return {
+				ok: true,
+				path: out,
+				width: r.width,
+				height: r.height,
+				generated: false
+			};
+			throw err;
+		}
+		return {
+			ok: true,
+			path: out,
+			width: r.width,
+			height: r.height,
+			generated: true
+		};
+	} finally {
+		rmSync(tmp, { force: true });
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+export { ensurePoster, isLocalClip };