@marver-design/marver 0.14.0 → 0.16.0

package/dist/{shot-kbR_xzJH.mjs → shot-CwmHO5T4.mjs}

@@ -1,6 +1,7 @@
 import { a as slideSize, i as ROUTE } from "./cli.mjs";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
 import { spawn } from "node:child_process";
 //#region src/server/shot.ts
@@ -35,9 +36,11 @@ function findChrome() {
 }
 const slug = (frameId) => frameId.replace(/\//g, "--");
 const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
-function planShot(frame, viewports) {
-	const cw = typeof frame.contentWidth === "number" && Number.isFinite(frame.contentWidth) && frame.contentWidth > 0 ? frame.contentWidth : void 0;
+const num = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? v : void 0;
+function planShot(frame, viewports, override = {}) {
+	const cw = num(frame.contentWidth);
 	const vpObj = frame.viewport ? viewports[frame.viewport] : void 0;
+	const ow = num(override.w), oh = num(override.h);
 	const sl = slideSize(frame);
 	if (sl) return {
 		width: sl.width,
@@ -49,7 +52,7 @@ function planShot(frame, viewports) {
 		height: 844
 	};
 	if (cw) {
-		const width = clamp(vpObj?.width ?? cw, 320, 1600);
+		const width = clamp(ow ?? vpObj?.width ?? cw, 320, 1600);
 		return {
 			width,
 			initialHeight: Math.round(width * .75),
@@ -57,6 +60,11 @@ function planShot(frame, viewports) {
 		};
 	}
 	const vp = vpObj ?? fallback;
+	if (ow || oh) return {
+		width: clamp(ow ?? vp.width, 120, 3840),
+		initialHeight: clamp(oh ?? vp.height, 80, 2160),
+		fullHeight: false
+	};
 	return {
 		width: vp.width,
 		initialHeight: vp.height,
@@ -67,11 +75,15 @@ function planShot(frame, viewports) {
 *  transports (the HTTP /api/shot endpoint and the file-drop inbox), so they validate and
 *  name output identically. `origin` is the dev server's own base URL. */
 async function shootFrame(opts) {
-	const { root, viewports, frameId, theme, origin } = opts;
+	const { root, viewports, frameId, theme, origin, scale = 2, size } = opts;
 	if (!/^[a-z0-9-]+$/i.test(theme)) return {
 		ok: false,
 		error: "invalid theme"
 	};
+	if (!Number.isInteger(scale) || scale < 1 || scale > 4) return {
+		ok: false,
+		error: "invalid scale"
+	};
 	let manifest = {};
 	try {
 		manifest = JSON.parse(readFileSync(join(root, "design", "manifest.json"), "utf8"));
@@ -81,38 +93,99 @@ async function shootFrame(opts) {
 		ok: false,
 		error: `unknown frame "${frameId}" - ids are in design/manifest.json`
 	};
-	const plan = planShot(frame, viewports);
+	const plan = planShot(frame, viewports, size);
+	if (frame.kind !== "html") try {
+		const { scanAssetRefs } = await import("./build-Ct0iMoSi.mjs");
+		const { ensurePoster } = await import("./poster-DOY7pax8.mjs");
+		const refs = scanAssetRefs(readFileSync(join(root, frame.file), "utf8"), frame.file);
+		for (const r of refs) if (r.endsWith(".poster.png")) await ensurePoster(join(root, "design", "assets"), r.slice(0, -11));
+	} catch {}
 	const shotsDir = join(root, "design", ".local", "shots");
 	mkdirSync(shotsDir, { recursive: true });
-	const rel = `design/.local/shots/${slug(frameId)}--${theme}.png`;
+	sweepTemps(shotsDir);
+	const explicit = opts.scale !== void 0;
+	const relFor = (used) => {
+		const tag = !explicit || scale === 2 && used === 2 ? "" : used === scale ? `@${scale}x` : `@${scale}x-as-${used}x`;
+		return `design/.local/shots/${slug(frameId)}--${theme}${tag}.png`;
+	};
+	const tmp = join(shotsDir, `.${slug(frameId)}--${theme}.${randomBytes(6).toString("hex")}.tmp.png`);
 	const result = await capture({
 		url: frame.kind === "html" ? `${origin}/${frame.file}?theme=${encodeURIComponent(theme)}` : `${origin}${ROUTE}/frame/?id=${encodeURIComponent(frameId)}&theme=${encodeURIComponent(theme)}`,
 		width: plan.width,
 		height: plan.initialHeight,
-		out: join(root, rel),
-		fullHeight: plan.fullHeight
+		out: tmp,
+		fullHeight: plan.fullHeight,
+		scale
 	});
-	return result.ok ? {
+	if (!result.ok) {
+		rmSync(tmp, { force: true });
+		return result;
+	}
+	const rel = relFor(result.scale);
+	try {
+		try {
+			renameSync(tmp, join(root, rel));
+		} catch (err) {
+			const code = err.code;
+			if (code !== "EEXIST" && code !== "EPERM") throw err;
+			copyFileSync(tmp, join(root, rel));
+		}
+	} catch (err) {
+		return {
+			ok: false,
+			error: `could not write the shot - ${err.message}`
+		};
+	} finally {
+		rmSync(tmp, { force: true });
+	}
+	return {
 		ok: true,
 		path: rel,
 		width: result.width,
 		height: result.height,
 		scale: result.scale,
-		...result.truncated ? {
-			truncated: true,
-			note: result.note
-		} : {}
-	} : result;
+		...result.truncated ? { truncated: true } : {},
+		...result.note ? { note: result.note } : {}
+	};
+}
+/** A crashed process can leave a `.tmp.png` behind; sweep them (older than a minute, so an in-
+*  flight capture in this process is never touched) at the next shot. */
+const sweptAt = /* @__PURE__ */ new Map();
+function sweepTemps(dir) {
+	if (Date.now() - (sweptAt.get(dir) ?? 0) < 6e4) return;
+	sweptAt.set(dir, Date.now());
+	try {
+		for (const f of readdirSync(dir)) {
+			if (!f.endsWith(".tmp.png")) continue;
+			const p = join(dir, f);
+			try {
+				if (Date.now() - statSync(p).mtimeMs > 6e4) rmSync(p, { force: true });
+			} catch {}
+		}
+	} catch {}
 }
-/** One capture at a time: shots are seconds apart at most, and a Chrome per concurrent
-*  request would stampede the machine mid-jam. */
-let chain = Promise.resolve();
-function capture(req) {
-	const run = chain.then(() => captureNow(req), () => captureNow(req));
-	chain = run;
+/** One capture at a time PER LANE: shots are seconds apart at most, and a Chrome per
+*  concurrent request would stampede the machine mid-jam. Posters have their own lane - a
+*  frame being shot may ask for its poster mid-render, and on the shot's lane that request
+*  would wait for the very shot that is waiting for it. */
+const chains = /* @__PURE__ */ new Map();
+function capture(req, lane = "shot") {
+	const run = (chains.get(lane) ?? Promise.resolve()).then(() => captureNow(req), () => captureNow(req));
+	chains.set(lane, run);
 	return run;
 }
-async function captureNow({ url, width, height, out, fullHeight = false, timeoutMs = 3e4 }) {
+/** The capture budget. Chrome's surface tops out near 16384 device px per SIDE, and a bitmap is
+*  also bounded by its AREA: 64M device px (~256 MiB RGBA) is comfortably rendered, encoded and
+*  pasted, where a 3840×2160@4 (133M px) can stall the renderer or the paste target. Both limits
+*  are exported so the tests hold the same numbers. */
+const SURFACE = 16384;
+const AREA = 64e6;
+const fits = (w, h, dsf) => w * dsf <= 16384 && h * dsf <= 16384 && w * h * dsf * dsf <= 64e6;
+/** The tallest CSS height a full-height capture of `width` can hold at `dsf`. */
+const capFor = (width, dsf) => Math.max(1, Math.min(Math.floor(SURFACE / dsf), Math.floor(AREA / (width * dsf * dsf))));
+async function captureNow({ url, width, height, out, fullHeight = false, timeoutMs = 3e4, scale: wantScale = 2, clip }) {
+	let scale = Math.min(4, Math.max(1, Math.round(wantScale)));
+	while (scale > 1 && !fits(width, height, scale)) scale--;
 	const bin = findChrome();
 	if (!bin) return {
 		ok: false,
@@ -205,11 +278,14 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 			}
 		});
 		const sendD = (method, params, ms = 1500) => Promise.race([send(method, params, sessionId), new Promise((_, rej) => setTimeout(() => rej(/* @__PURE__ */ new Error(`${method} timed out`)), ms))]);
+		const hardBy = Date.now() + timeoutMs + 15e3;
 		watchdog = setTimeout(() => {
 			try {
 				chrome.kill("SIGKILL");
 			} catch {}
 		}, timeoutMs + 15e3);
+		const RESERVE = 21e3;
+		const discretionary = () => hardBy - RESERVE - Date.now();
 		const { targetId } = await send("Target.createTarget", { url: "about:blank" });
 		const { sessionId } = await send("Target.attachToTarget", {
 			targetId,
@@ -218,7 +294,7 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 		await send("Emulation.setDeviceMetricsOverride", {
 			width,
 			height,
-			deviceScaleFactor: 2,
+			deviceScaleFactor: scale,
 			mobile: false
 		}, sessionId);
 		await send("Page.enable", {}, sessionId);
@@ -244,12 +320,55 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 			ok: false,
 			error: `the frame never rendered${lastException ? ` - the page threw: ${lastException}` : " (no exception surfaced - is the dev server reachable from this machine?)"}`
 		};
-		await send("Runtime.evaluate", {
-			expression: "document.fonts.ready.then(() => true)",
-			awaitPromise: true,
-			returnByValue: true
-		}, sessionId).catch(() => null);
-		await new Promise((r2) => setTimeout(r2, 250));
+		const SETTLED = `(() => {
+      if (typeof window.__mvLodBusy === 'function' && window.__mvLodBusy() > 0) return false
+      if (typeof window.__mvPosterBusy === 'function' && window.__mvPosterBusy() > 0) return false
+      const H = window.innerHeight, W = window.innerWidth
+      for (const im of document.images) {
+        if (im.complete) continue
+        const r = im.getBoundingClientRect()
+        if (r.bottom < 0 || r.top > H || r.right < 0 || r.left > W) continue
+        return false
+      }
+      for (const c of document.querySelectorAll('.mv-chart')) if (!c.querySelector('svg, canvas')) return false
+      for (const d of document.querySelectorAll('.mv-diagram')) if (!d.querySelector('.mv-diagram-svg svg, .mv-diagram-err')) return false
+      return true
+    })()`;
+		const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+		const settle = async (budgetMs) => {
+			const total = Math.min(budgetMs, discretionary());
+			if (total <= 0) return false;
+			const by = Date.now() + total;
+			const left = () => Math.max(1, by - Date.now());
+			await sendD("Runtime.evaluate", {
+				expression: `window.postMessage({type:'sh:camera',moving:false,scale:1}, location.origin)`,
+				returnByValue: true
+			}, left()).catch(() => null);
+			await sendD("Runtime.evaluate", {
+				expression: "document.fonts.ready.then(() => true)",
+				awaitPromise: true,
+				returnByValue: true
+			}, left()).catch(() => null);
+			let ok = false;
+			while (Date.now() < by) {
+				if ((await sendD("Runtime.evaluate", {
+					expression: SETTLED,
+					returnByValue: true
+				}, left()).catch(() => null))?.result?.value === true) {
+					ok = true;
+					break;
+				}
+				await wait(Math.min(100, left()));
+			}
+			if (Date.now() < by) await sendD("Runtime.evaluate", {
+				expression: "new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(() => r(true))))",
+				awaitPromise: true,
+				returnByValue: true
+			}, Math.min(1e3, left())).catch(() => null);
+			if (Date.now() < by) await wait(Math.min(ok ? 150 : 250, left()));
+			return ok;
+		};
+		await settle(3e3);
 		const errEval = await send("Runtime.evaluate", {
 			expression: "window.__mvFrameError || \"\"",
 			returnByValue: true
@@ -259,9 +378,8 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 			ok: false,
 			error: `the frame rendered an error - ${frameError}`
 		};
-		let capW = width, capH = height, scale = 2, truncated = false, note = "";
+		let capW = width, capH = height, truncated = false, note = "";
 		if (fullHeight) {
-			const wait = (ms) => new Promise((r) => setTimeout(r, ms));
 			const measureH = async () => {
 				const v = (await sendD("Runtime.evaluate", {
 					expression: `Math.ceil((document.querySelector('.mv-doc')||document.getElementById('root')||document.body).getBoundingClientRect().height)`,
@@ -306,46 +424,71 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 					h = Math.max(m, capped);
 				}
 			};
-			const CAP2 = 8192, CAP1 = 16384;
-			const settleDeadline = Date.now() + 6e3;
-			await growFit(2, CAP2, settleDeadline);
-			if (measured > CAP2) {
+			const settleDeadline = Date.now() + Math.max(0, Math.min(6e3, discretionary()));
+			const asked = scale;
+			await growFit(scale, capFor(width, scale), settleDeadline);
+			if (measured > capFor(width, scale) && scale > 2) {
+				scale = 2;
+				await growFit(2, capFor(width, 2), settleDeadline);
+			}
+			if (measured > capFor(width, scale) && scale > 1) {
 				scale = 1;
-				await growFit(1, CAP1, settleDeadline);
+				await growFit(1, capFor(width, 1), settleDeadline);
 			}
-			const cap = scale === 2 ? CAP2 : CAP1;
+			const cap = capFor(width, scale);
 			capW = width;
 			if (measured > cap) {
 				capH = cap;
 				truncated = true;
 				note = `frame is ${measured}px tall; captured the top ${cap}px - split it or reduce its height`;
 			} else capH = clamp(measured || height, 80, cap);
+			if (scale < asked && !truncated) note = `frame is ${measured}px tall - too tall for ${asked}x, captured at ${scale}x`;
 			await sendD("Emulation.setDeviceMetricsOverride", {
 				width: capW,
 				height: capH,
 				deviceScaleFactor: scale,
 				mobile: false
 			}, 5e3);
-			if (Date.now() < settleDeadline) {
-				await sendD("Runtime.evaluate", {
-					expression: `window.postMessage({type:'sh:camera',moving:false,scale:1}, location.origin)`,
-					returnByValue: true
-				}).catch(() => null);
-				await wait(300);
-				for (let j = 0; j < 20 && Date.now() < settleDeadline && !await lodIdle(); j++) await wait(100);
-				await sendD("Runtime.evaluate", {
-					expression: "document.fonts.ready.then(()=>true)",
-					awaitPromise: true,
-					returnByValue: true
-				}).catch(() => null);
+			await wait(Math.min(300, Math.max(0, discretionary())));
+			await settle(Math.max(1200, settleDeadline - Date.now()));
+			const m2 = await measureH();
+			if (m2 > capH) {
+				if (m2 <= cap) capH = m2;
+				else {
+					capH = cap;
+					truncated = true;
+					note = `frame is ${m2}px tall; captured the top ${cap}px - split it or reduce its height`;
+				}
+				await sendD("Emulation.setDeviceMetricsOverride", {
+					width: capW,
+					height: capH,
+					deviceScaleFactor: scale,
+					mobile: false
+				}, 5e3);
+				await settle(600);
 			}
 		}
+		let capX = 0, capY = 0;
+		if (clip) {
+			const box = (await sendD("Runtime.evaluate", {
+				expression: `(() => { const el = document.querySelector(${JSON.stringify(clip)}); if (!el) return null; const b = el.getBoundingClientRect(); return { x: b.x, y: b.y, w: b.width, h: b.height } })()`,
+				returnByValue: true
+			}, 2e3).catch(() => null))?.result?.value;
+			if (!box || box.w < 1 || box.h < 1) return {
+				ok: false,
+				error: `nothing to capture at "${clip}"`
+			};
+			capX = Math.max(0, Math.floor(box.x));
+			capY = Math.max(0, Math.floor(box.y));
+			capW = Math.max(1, Math.round(box.w));
+			capH = Math.max(1, Math.round(box.h));
+		}
 		const shot = await sendD("Page.captureScreenshot", {
 			format: "png",
 			captureBeyondViewport: true,
 			clip: {
-				x: 0,
-				y: 0,
+				x: capX,
+				y: capY,
 				width: capW,
 				height: capH,
 				scale: 1
@@ -357,10 +500,8 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 			width: capW,
 			height: capH,
 			scale,
-			...truncated ? {
-				truncated: true,
-				note
-			} : {}
+			...truncated ? { truncated: true } : {},
+			...note ? { note } : {}
 		};
 	} catch (err) {
 		return {
@@ -384,4 +525,4 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 	}
 }
 //#endregion
-export { shootFrame };
+export { capture, findChrome, shootFrame };

package/docs/live-jam.md

@@ -98,8 +98,12 @@ obvious one:
   `design/.local/shots/<slug>.request.json` with `{"frame":"<id>","theme":"<t>"}`; the dev
   server renders and writes `<slug>.result.json` with the PNG path or an error, which the
   agent Reads.
-- **`npx marver shot <frame>`** / `GET /api/shot?frame=<id>&theme=<t>` for humans and
-  shell-ful agents - the same renderer, one line.
+- **`npx marver shot <frame> [--scale 1-4]`** / `GET /api/shot?frame=<id>&theme=<t>&scale=<n>`
+  for humans and shell-ful agents - the same renderer, one line. Default 2x; `--scale 4` for a
+  print-quality still (a slide comes back 5120×2880). A frame too tall for the asked scale steps
+  down and says so in `note`; the file name carries the scale actually used (`…@4x.png`).
+  The canvas's **copy as image** (`i` / `⇧i`, the images-square toolbar button) is this same
+  renderer with `format=png`, so what a designer pastes and what an agent shoots is one picture.
 
 The generated jam instructions tell every agent to shoot and LOOK before replying "done".
 A frame that never mounts, or a dev server that isn't reachable, comes back as an honest

package/docs/publish.md

@@ -31,7 +31,10 @@ opens the same view on the published site, as long as its board and frame shippe
 
 **What ships**: the boards you list, the frames they reference, and the host `public/`
 directory in full (the `--boards` filter covers frames, not public assets). A flow you
-publish must have all its `data-goto` targets on a published board.
+publish must have all its `data-goto` targets on a published board. Sidebar folders ship
+only around published boards (a folder with nothing published never reaches the bundle),
+and `description`s ship only for published things - the project's, the published boards',
+their folders', scenes' and frames'.
 
 ## Who can open your canvas
 

package/docs/slides.md

@@ -112,9 +112,15 @@ slides and the entrance presets.
   `design/theme.css` tokens, strips animation at rest, and lets any
   styling you pass override the theme - so pass data and structure only.
   SVG-rendered, in a lazy chunk chart-free canvases never download.
-- `<Video src="intro.mp4" poster="intro.jpg" />` - the poster is the slide
-  at rest (required for local files); in slides mode the glass strip plays
-  it (play/pause, seek, mute, fullscreen). Remote https direct files work
+- `<Video src="intro.mp4" poster="intro.jpg" />` - the poster is the frame
+  at rest. Omit it on a local clip and marver renders one from the clip's own
+  first moments (`intro.mp4.poster.png` beside it - the dev server on first
+  sight, `marver build` before publishing; needs Chrome, like `shot`). An
+  authored poster always wins. In slides mode the glass strip mounts
+  on its own (play/pause, seek, mute, fullscreen); in any other live frame -
+  interact mode, play, a published prototype - the poster is the play button.
+  `ratio="9 / 16"` for a vertical clip; `autoplay` for a muted ambient loop
+  (that frame then stays live on the canvas). Remote https direct files work
   too.
 
 ## Theme tokens

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
   "type": "module",
   "private": false,

package/src/client/content/chart.tsx

@@ -40,30 +40,48 @@ export function sanitizeOption(option: Record<string, unknown>, animate: boolean
   return out
 }
 
-/** The house theme, from the slide tokens at render time (computed style so
- *  host overrides and dark scheme are both honored). */
-function houseTheme(el: HTMLElement) {
-  const css = getComputedStyle(el)
-  const v = (name: string, fb: string) => css.getPropertyValue(name).trim() || fb
-  const ink = v('--sl-ink', '#18181b')
-  const muted = v('--sl-muted', 'rgba(24,24,27,.55)')
-  const accent = v('--sl-accent', '#0088ff')
-  const font = v('--sl-font', FONT_STACK)        // the deck's family, so chart text matches the slide
+/** The chart's palette, pure so the tests own it. `inSlide` picks the slide type scale
+ *  (18px labels on a 1280-wide stage) over the document/UI scale (12px). */
+export function chartTheme(t: { ink: string; font: string; accent: string; ground: string; grid: string; dark: boolean; inSlide: boolean }) {
+  const fs = t.inSlide ? 18 : 12
+  const muted = t.dark ? 'rgba(242,242,247,.5)' : 'rgba(28,28,30,.5)'
   return {
-    color: [accent, '#7c5cff', '#00b8a9', '#f0883e', '#d6608c', '#5b8def'],
-    textStyle: { fontFamily: font, color: ink },
+    color: [t.accent, '#7c5cff', '#00b8a9', '#f0883e', '#d6608c', '#5b8def'],
+    textStyle: { fontFamily: t.font, color: t.ink },
     axisPointer: { lineStyle: { color: muted } },
-    categoryAxis: { axisLine: { lineStyle: { color: muted } }, axisLabel: { color: ink, fontSize: 18 }, splitLine: { show: false } },
-    valueAxis: { axisLabel: { color: ink, fontSize: 18 }, splitLine: { lineStyle: { color: v('--sl-grid', 'rgba(127,127,127,.15)') } } },
-    legend: { textStyle: { color: ink, fontSize: 18 } },
+    categoryAxis: { axisLine: { lineStyle: { color: muted } }, axisLabel: { color: t.ink, fontSize: fs }, splitLine: { show: false } },
+    valueAxis: { axisLabel: { color: t.ink, fontSize: fs }, splitLine: { lineStyle: { color: t.grid } } },
+    legend: { textStyle: { color: t.ink, fontSize: fs } },
+    title: { textStyle: { color: t.ink, fontFamily: t.font }, subtextStyle: { color: muted, fontFamily: t.font } },
+    // series labels (pie/funnel/bar values): the frame's ink, no halo - echarts' default paints
+    // #333 with a white 2px text border, which reads as outlined glyphs on a dark ground
+    label: { color: t.ink, fontSize: fs, textBorderWidth: 0 },
     tooltip: {
-      backgroundColor: v('--sl-ground', '#fff'), borderColor: 'rgba(127,127,127,.25)',
-      textStyle: { color: ink, fontFamily: font },
+      backgroundColor: t.ground, borderColor: 'rgba(127,127,127,.25)',
+      textStyle: { color: t.ink, fontFamily: t.font, fontSize: fs === 18 ? 16 : 12 },
       extraCssText: 'border-radius:12px;box-shadow:0 8px 24px rgba(0,0,0,.14);backdrop-filter:blur(8px)',
     },
   }
 }
 
+/** The house theme, read from the frame the chart sits in, at render time. Ink and font are
+ *  the element's own COMPUTED color and font-family - so a chart inherits a UI screen's
+ *  Tailwind text colour and typeface, a Doc's tokens, or a Slide's, with no per-context
+ *  wiring. Accent and ground come from slide tokens, then Doc tokens, then the mode palette. */
+function houseTheme(el: HTMLElement, dark: boolean) {
+  const css = getComputedStyle(el)
+  const v = (...names: string[]) => { for (const n of names) { const x = css.getPropertyValue(n).trim(); if (x) return x } return '' }
+  return chartTheme({
+    ink: css.color || (dark ? '#F2F2F7' : '#1C1C1E'),
+    font: v('--sl-font') || css.fontFamily || FONT_STACK,
+    accent: v('--sl-accent', '--mv-accent') || (dark ? '#0091FF' : '#0088FF'),
+    ground: v('--sl-ground', '--mv-surface', '--mv-bg') || (dark ? '#1C1C1E' : '#FFFFFF'),
+    grid: v('--sl-grid') || (dark ? 'rgba(242,242,247,.12)' : 'rgba(28,28,30,.1)'),
+    dark,
+    inSlide: !!el.closest('.sl-root'),
+  })
+}
+
 /** The frame's visual theme (light/dark), observed the same way the play
  *  flag is - the stage flips documentElement class/data-theme on sh:set-theme
  *  and a themed chart must follow, not stay stale. */
@@ -81,20 +99,40 @@ export function Chart({ option, h = 420 }: { option: Record<string, unknown>; h?
   const play = useSlidePlay()
   const theme = useFrameTheme()
   const [failed, setFailed] = useState(false)
+  // The instance lives in a ref: init/dispose follows the THEME and the play flip (a theme
+  // object per init, the entrance on play); the option rides a separate effect that calls
+  // setOption on the live instance - so a parent re-render, or an HMR edit to a formatter
+  // function, never disposes and re-inits the chart.
+  const chartRef = useRef<import('./chart-engine.ts').EChartsInstance | null>(null)
+  const optionRef = useRef(option)
+  optionRef.current = option
+  const playRef = useRef(play)
+  playRef.current = play
   useEffect(() => {
     const el = ref.current
     if (!el) return
     let disposed = false
-    let chart: import('./chart-engine.ts').EChartsInstance | null = null
+    let ro: ResizeObserver | null = null
     void loadEngine().then((engine) => {
       if (disposed || !ref.current) return
-      // a theme OBJECT per init - never a stale global registration
-      chart = engine.init(ref.current, houseTheme(ref.current), { renderer: 'svg' })
-      chart.setOption(sanitizeOption(option, play))
+      const chart = engine.init(ref.current, houseTheme(ref.current, theme === 'dark'), { renderer: 'svg' })
+      chartRef.current = chart
+      chart.setOption(sanitizeOption(optionRef.current, playRef.current))
+      // a slide is a fixed stage, but a UI screen or a Doc reflows (device pills, responsive
+      // layouts): follow the box, or the SVG keeps its mount-time size
+      if (typeof ResizeObserver !== 'undefined') {
+        ro = new ResizeObserver(() => { if (!disposed) chart.resize() })
+        ro.observe(ref.current)
+      }
     }).catch(() => setFailed(true))
-    return () => { disposed = true; chart?.dispose() }
-    // re-init on play flip (the entrance) and on theme flip (fresh tokens)
-  }, [option, play, theme])
+    return () => { disposed = true; ro?.disconnect(); chartRef.current?.dispose(); chartRef.current = null }
+  }, [play, theme])
+  // option changes (content OR a function inside it) reach the live instance: a normal merge
+  // that REPLACES the series list (a removed series disappears) while a viewer's dataZoom,
+  // legend selection and the like survive - notMerge would reset them on every parent render
+  useEffect(() => { chartRef.current?.setOption(sanitizeOption(option, play), { replaceMerge: ['series'] }) }, [option, play])
   if (failed) return <div className="mv-block mv-imgerr"><b>chart unavailable</b><span>echarts failed to load</span></div>
-  return <div ref={ref} className="mv-block mv-chart" style={{ width: '100%', height: h }} />
+  // contain: inline-size - echarts sizes its inner box in px, which would otherwise pin the
+  // author's flex/grid column at that width (min-content) and defeat the ResizeObserver above
+  return <div ref={ref} className="mv-block mv-chart" style={{ width: '100%', height: h, minWidth: 0, contain: 'inline-size' }} />
 }

package/src/client/content/index.tsx

@@ -176,8 +176,11 @@ body { margin: 0; }
 .mv-col { display: flex; flex-direction: column; min-width: 0; }
 
 /* the rubber: diagram + image blocks own their breathing room. The surface is
-   a whisper, not a card - the content pops, the block only frames it */
-.mv-block { margin: 0; padding: ${UNIT}px; border: 1px solid var(--mv-block-line);
+   a whisper, not a card - the content pops, the block only frames it. The card is a
+   DOCUMENT treatment: inside a Slide or a UI screen a block is bare (the author's own
+   card or the slide's grid frames it), so it takes no invisible ${UNIT}px of padding there. */
+.mv-block { margin: 0; }
+.mv-doc .mv-block { padding: ${UNIT}px; border: 1px solid var(--mv-block-line);
   border-radius: 10px; background: var(--mv-block-bg); }
 /* an image block is NOT a card: the screenshot IS the content. Drop the surface + border so we don't
    frame a frame; give the image itself a hairline edge and a whisper of shadow so it reads as a clean,