@marver-design/marver 0.13.0 → 0.15.0

package/docs/slides.md

@@ -0,0 +1,140 @@
+# Slides - decks on the canvas
+
+A slide is an ordinary frame with `slide: true`:
+
+```tsx
+import { Slide } from '@marver-design/marver/content'
+export const meta = { title: 'Cover', slide: true }
+export default () => (
+  <Slide>
+    <h1 className="sl-assertion">Churn halved after onboarding v2</h1>
+  </Slide>
+)
+```
+
+It renders 1280×720 on the canvas, wears the slide badge, and everything
+you know - comments, lasers, variants, promotion, Live Jam - keeps working.
+**The stage fits every screen**: you author at exactly 1280×720, and the
+slide scales and centers itself to whatever viewport plays it - fill window,
+a laptop, a viewer's phone - author px, Tailwind classes, and charts all
+scale together, so the composition you approved is the composition everyone
+sees. One scene = one deck; numbered files
+(`01-cover.tsx`) are the authoring order; **the board's reading order is the
+played order** - drag slides around the canvas to reorder the deck.
+
+## Why it stays light for the agent
+
+There is no slide component library to learn. `Slide` is the ONE primitive:
+it owns the 1280×720 stage, the asymmetric margins, six fixed type roles
+(`sl-display` 160 · `sl-stat` 88 · `sl-assertion` 56 · `sl-support` 30 ·
+`sl-body` 24 · `sl-caption` 18), your theme's tokens, and the motion
+contract. Everything inside it is your project's own markup, classes, and
+components - the same ones the app ships - so a slide is built the way a
+screen is built, and an approved slide can be promoted like one.
+
+Looking good at every size costs the agent nothing extra: the fit is pure
+CSS on the root (a resized canvas node, a phone, a projector all get the
+same composition, scaled), so the doctrine forbids `vw`/`vh` and media
+queries inside a slide and asks for flex/grid in the stage's own
+proportions. A dev-only overflow marker outlines a slide whose content escapes the
+stage, or whose flex/grid child outgrows its parent - the agent sees the
+defect on the canvas, and the rule is always "cut or split, never shrink the type".
+
+The craft lives in prose, not code. `marver init` ships
+`design/instructions/slides.md` - the doctrine: assertion-first argument,
+the type roles, **the space IS the design** (three bands, the 85% rule, one
+px spacing scale), **seven silhouettes chosen before any recipe** (statement
+/ hero / split / grid / stream / field / bookend) with a storyboard step
+and pacing rules so a deck never reads as one repeated shape, 19 core
+recipes with budgets and morph anchors, the choreography rules, and a
+review gate that squints the contact sheet. Two depth references sit
+beside it: `instructions/reference/deck-story.md` (intake, answer-first
+structure, the evidence check, audience calibration, the words) and
+`instructions/reference/deck-layouts.md` (the full layout atlas by job, the
+grid, content budgets, rebuilding an existing deck, chart craft). Your own
+**deck look** (tokens, type, the mark, colour meaning, numbers, voice - a
+fill-in template the agent drafts on the first deck), layouts, and house
+rules live in `design/slides.md`, which overrides the doctrine and which
+marver never overwrites.
+
+## Playing and publishing a deck
+
+Press `p` on a board whose publish row says slides and you get slides mode:
+the 16:9 stage with the standard prototype toolbars (with `chrome: full`,
+the default) - arrows / Space / click to advance, `d` cycles the theme,
+devices including a 1280×720 Slide preset and fill window.
+Publish it with:
+
+```json
+{ "boards": { "pitch": { "max": "comment", "type": "slides",
+  "open": "slides", "transition": "fade" } } }
+```
+
+- `transition`: `fade` (default) or `none`.
+- `chrome`: `full` (default - the standard prototype chrome: the top-right
+  toolbar with comment, laser, theme, and devices including fill, plus the
+  bottom-left walker; a locked deck-only share also carries the brand pill),
+  `minimal` (a slim progress strip, comments, the canvas door when the
+  board is not locked, and a pending-update control), or `none` (bare
+  stage).
+- Add `"lock": true` to freeze visitors in the deck - no way out to the
+  canvas. When every published board is locked to present, focus, or
+  slides, the canvas shell is left out of the bundle entirely.
+
+Viewers land straight in the deck; the URL survives refresh and back.
+
+## Motion - the diff is the animation
+
+A resting slide is STILL - that is a contract, not a hope: charts render
+final-state SVG, videos are posters (no `<video>` element exists), and the
+`Slide` root suspends every CSS animation and transition under it at rest.
+(Your own `<canvas>`, `<video>`, or JS-driven motion is outside the contract
+and stays live, as in any frame.) Motion happens in slides
+mode, one-shot:
+
+- **Morphs**: give the same `view-transition-name` to an element on two
+  adjacent slides and it travels/grows between them. This is the house move.
+- **Build steps**: progressive disclosure is sibling frames (`03a-`, `03b-`)
+  sharing morph names - every step visible and commentable on the board.
+- **Entrances**: `data-animate="fade-up | fade | scale-in"` +
+  `data-animate-delay="0-3"`, run once after the transition settles. Never
+  on an element that carries a morph name.
+
+`prefers-reduced-motion` flattens marver's own motion - the morphs between
+slides and the entrance presets.
+
+## Charts and video
+
+- `<Chart option={...} h={420} />` - an Apache ECharts option, on a
+  fixed supported surface: series bar, line, pie, scatter, radar, gauge, heatmap, funnel, treemap, sunburst, sankey, boxplot; components grid, polar, radar, tooltip, legend, title, dataset (+ transform), markLine, markPoint, markArea, visualMap, dataZoom. Anything outside
+  it is dropped by ECharts without an error, so stay inside. marver
+  supplies the house theme (colours, type, tooltip) from your
+  `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 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
+
+The `Slide` root reads `--marver-slide-ground / -ink / -muted` (each with a
+`-dark` variant), `--marver-slide-accent` (one value, both themes),
+`--marver-slide-font`, and `--marver-slide-tempo` (one duration that times
+both the entrances and the morphs between slides) from your theme and falls
+back to the house palette. The stage is 1280×720 (`SLIDE_W` / `SLIDE_H`, exported from `/content`)
+with asymmetric margins - 88px sides, 44px top and bottom, overridable in
+px via `--marver-slide-pad-x` / `--marver-slide-pad-y` - leaving a 1104×632
+content box. Morphs between slides are progressive enhancement: where
+`document.startViewTransition` is missing, slides crossfade at the tempo.
+Type roles, fixed: `sl-display` (160px, the one
+oversize - a hero number, a section numeral), `sl-stat` (88px, a row of
+figures), `sl-assertion` (56px),
+`sl-support` (30px), `sl-body` (24px), `sl-caption` (18px).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.13.0",
+  "version": "0.15.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,
@@ -27,6 +27,7 @@
     "src/client",
     "src/shared",
     "templates",
+    "docs",
     "README.md",
     "LICENSE",
     "NOTICE",
@@ -47,6 +48,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^6.0.0",
     "cac": "^7.0.0",
+    "echarts": "^6.1.0",
     "html-to-image": "^1.11.13",
     "marked": "^16.0.0",
     "mermaid": "^11.6.0",

package/src/client/const.ts

@@ -8,3 +8,16 @@ export const ROUTE = '/__mv'
  *  Shared by the Doc primitive (measurement messages) and the server-side
  *  manifest scan (defaultSize for content frames) - one source, no drift. */
 export const CONTENT_WIDTH: Record<string, number> = { document: 760, wide: 1280 }
+
+/** The slide stage (v1.5): a runtime-reserved intrinsic, deliberately NOT a
+ *  config viewport - no migration for existing projects, no deck device in
+ *  sweeps. Dependency-neutral so server (shot) and shell (store) share it. */
+export const SLIDE_INTRINSIC = { width: 1280, height: 720 }
+
+/** The one DEFAULT sizing rule for slide frames, shared by canvas and shot:
+ *  `slide: true` sets the intrinsic 1280×720 stage, over any authored viewport.
+ *  Board nodes stay resizable (the Slide root scales into whatever box it is
+ *  given); this governs defaults, shots, and stage coordinates. */
+export function slideSize(frame: { slide?: boolean }): { width: number; height: number } | null {
+  return frame.slide ? SLIDE_INTRINSIC : null
+}

package/src/client/content/chart-engine.ts

@@ -0,0 +1,33 @@
+/** The lazily-loaded ECharts engine - STATIC named imports only, so the
+ *  bundler tree-shakes to exactly the blessed set (whole-namespace imports
+ *  drag the entire library into the chunk). chart.tsx dynamic-imports THIS
+ *  file, which is what splits echarts into its own async chunk. */
+import * as core from 'echarts/core'
+import { SVGRenderer } from 'echarts/renderers'
+import {
+  BarChart, LineChart, PieChart, ScatterChart, RadarChart, GaugeChart, HeatmapChart,
+  FunnelChart, TreemapChart, SunburstChart, SankeyChart, BoxplotChart,
+} from 'echarts/charts'
+import {
+  DatasetComponent, GridComponent, LegendComponent, MarkLineComponent, MarkPointComponent,
+  MarkAreaComponent, TitleComponent, TooltipComponent, PolarComponent, RadarComponent,
+  VisualMapComponent, DataZoomComponent, TransformComponent,
+} from 'echarts/components'
+
+/** THE SUPPORTED SURFACE - docs/slides.md and the doctrine list exactly this.
+ *  Series: bar, line, pie, scatter, radar, gauge, heatmap, funnel, treemap,
+ *  sunburst, sankey, boxplot. Components: grid, polar, radar, tooltip, legend,
+ *  title, dataset (+ transform), markLine, markPoint, markArea, visualMap,
+ *  dataZoom. Anything else in an option is silently dropped by ECharts - add
+ *  it HERE and to the docs together, never one without the other. */
+core.use([
+  SVGRenderer,
+  BarChart, LineChart, ScatterChart, PieChart, RadarChart, GaugeChart, HeatmapChart,
+  FunnelChart, TreemapChart, SunburstChart, SankeyChart, BoxplotChart,
+  GridComponent, PolarComponent, RadarComponent, TooltipComponent, LegendComponent,
+  TitleComponent, DatasetComponent, TransformComponent, MarkLineComponent,
+  MarkPointComponent, MarkAreaComponent, VisualMapComponent, DataZoomComponent,
+])
+
+export const init = core.init
+export type EChartsInstance = ReturnType<typeof core.init>

package/src/client/content/chart.tsx

@@ -0,0 +1,138 @@
+/**
+ * Chart (v1.5) - Apache ECharts, the Diagram way: the author picks the FORM
+ * (the ECharts option surface, pointed at from instructions/slides.md);
+ * marver injects the house theme and strips author styling drift where it
+ * breaks the deck (animation at rest, above all).
+ *
+ * SVG renderer ONLY - a canvas-rendered chart would pin its frame live on
+ * the board (the lean-DOM serializer keeps <canvas> frames degraded). At
+ * rest the chart renders its final state (animation force-disabled); in
+ * slides mode (useSlidePlay) it plays its entrance once on mount.
+ *
+ * echarts is a real dependency loaded through a dynamic import, so it
+ * splits into its own lazy chunk: canvases without charts ship zero echarts
+ * bytes.
+ */
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import { FONT_STACK } from './palette.ts'
+import { useSlidePlay } from './slide.tsx'
+
+type Engine = typeof import('./chart-engine.ts')
+
+let enginePromise: Promise<Engine> | null = null
+const loadEngine = (): Promise<Engine> => (enginePromise ??= import('./chart-engine.ts'))
+
+/** Strip every way an option can keep moving at rest: top-level and
+ *  per-series animation flags, and graphic keyframe animations. Pure and
+ *  exported - the tests own it. */
+export function sanitizeOption(option: Record<string, unknown>, animate: boolean): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...option, animation: animate }
+  delete out.graphic                                    // free-floating animated graphics have no place on a slide
+  const scrub = (s: unknown): unknown =>
+    s && typeof s === 'object'
+      ? {
+          ...Object.fromEntries(Object.entries(s as Record<string, unknown>).filter(([k]) => !/^animation/.test(k))),
+          animation: animate,
+        }
+      : s
+  if (Array.isArray(out.series)) out.series = out.series.map(scrub)
+  else if (out.series) out.series = scrub(out.series)
+  return out
+}
+
+/** 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: [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: 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: 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. */
+const subscribeTheme = (cb: () => void) => {
+  if (typeof document === 'undefined') return () => {}
+  const mo = new MutationObserver(cb)
+  mo.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'data-theme'] })
+  return () => mo.disconnect()
+}
+const readTheme = () => (typeof document !== 'undefined' && (document.documentElement.classList.contains('dark') || document.documentElement.dataset.theme === 'dark') ? 'dark' : 'light')
+const useFrameTheme = (): string => useSyncExternalStore(subscribeTheme, readTheme, () => 'light')
+
+export function Chart({ option, h = 420 }: { option: Record<string, unknown>; h?: number }) {
+  const ref = useRef<HTMLDivElement>(null)
+  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 ro: ResizeObserver | null = null
+    void loadEngine().then((engine) => {
+      if (disposed || !ref.current) return
+      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; 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>
+  // 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

@@ -8,6 +8,7 @@
  * can give the frame a natural size (the shell alone owns node dimensions).
  */
 import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { useInSlide } from './slide.tsx'
 import { CONTENT_WIDTH } from '../const.ts'
 import { assetUrl, renderMarkdown, FAMILIES } from './md.ts'
 import { lodSupported, registerLodImage } from './img-lod.ts'
@@ -16,7 +17,18 @@ import { lodSupported, registerLodImage } from './img-lod.ts'
 const FAMILY_CSS = Object.entries(FAMILIES).map(([f, c]) =>
   `.mv-md .mv-c-${f}{color:${c.light}}.dark .mv-md .mv-c-${f},[data-theme="dark"] .mv-md .mv-c-${f}{color:${c.dark}}`).join('\n')
 
-export { Diagram } from './diagram.tsx'
+import { Diagram as DiagramRoot } from './diagram.tsx'
+export function Diagram(props: Parameters<typeof DiagramRoot>[0]) { ensureStyles(); return <DiagramRoot {...props} /> }
+import { Slide as SlideRoot } from './slide.tsx'
+import { Chart as ChartRoot } from './chart.tsx'
+import { Video as VideoRoot } from './video.tsx'
+export { SLIDE_W, SLIDE_H } from './slide.tsx'
+// the shared stylesheet used to ride in with Doc alone; a slide composes Img,
+// Chart, and Video straight inside <Slide> with no Doc, so every public
+// primitive installs it - once per document, idempotent
+export function Slide(props: Parameters<typeof SlideRoot>[0]) { ensureStyles(); return <SlideRoot {...props} /> }
+export function Chart(props: Parameters<typeof ChartRoot>[0]) { ensureStyles(); return <ChartRoot {...props} /> }
+export function Video(props: Parameters<typeof VideoRoot>[0]) { ensureStyles(); return <VideoRoot {...props} /> }
 
 const UNIT = 16   // one gap unit, px - plain adjacency on boards is one gutter; same feel here
 
@@ -56,20 +68,24 @@ export function Doc({ layout = 'document', children }: { layout?: 'document' | '
 /* ----------------------------- layout blocks ------------------------------ */
 
 export function Row({ space = 1, children }: { space?: number; children?: ReactNode }) {
+  ensureStyles()
   return <div className="mv-row" style={{ gap: space * UNIT }}>{children}</div>
 }
 
 export function Col({ space = 1, children }: { space?: number; children?: ReactNode }) {
+  ensureStyles()
   return <div className="mv-col" style={{ gap: space * UNIT }}>{children}</div>
 }
 
 export function Space({ n = 1 }: { n?: number }) {
+  ensureStyles()
   return <div aria-hidden className="mv-space" style={{ flex: `0 0 ${n * UNIT}px`, minWidth: n * UNIT, minHeight: n * UNIT }} />
 }
 
 /* ---------------------------------- Md ------------------------------------ */
 
 export function Md({ children }: { children?: ReactNode }) {
+  ensureStyles()
   const src = typeof children === 'string' ? children : Array.isArray(children) ? children.join('') : String(children ?? '')
   const html = useMemo(() => renderMarkdown(src), [src])
   return <div className="mv-md" dangerouslySetInnerHTML={{ __html: html }} />
@@ -78,16 +94,21 @@ export function Md({ children }: { children?: ReactNode }) {
 /* ---------------------------------- Img ----------------------------------- */
 
 export function Img({ src, caption, alt, h }: { src: string; caption?: string; alt?: string; h?: number }) {
+  ensureStyles()
   const url = assetUrl(src)
   const [err, setErr] = useState(false)
   const canvasRef = useRef<HTMLCanvasElement>(null)
+  // inside a <Slide>, the LOD canvas is OFF: a resting slide must serialize to
+  // the lean-DOM path, and a <canvas> element pins its frame live (v1.5 §7)
+  const inSlide = useInSlide()
   // LOD: paint the image on a <canvas> decoded to its on-screen size (never the full 17MB bitmap), and
   // re-pick resolution only when the canvas settles after a zoom. See img-lod.ts. Falls back to a plain
   // <img> where createImageBitmap/bitmaprenderer isn't available (correctness over the optimization).
+  const lodOn = lodSupported && !inSlide
   useEffect(() => {
-    if (!url || err || !lodSupported || !canvasRef.current) return
+    if (!url || err || !lodOn || !canvasRef.current) return
     return registerLodImage(canvasRef.current, url)
-  }, [url, err])
+  }, [url, err, lodOn])
   if (!url || err) {
     return (
       <div className="mv-block mv-imgerr">
@@ -106,7 +127,7 @@ export function Img({ src, caption, alt, h }: { src: string; caption?: string; a
   const style = undefined
   return (
     <figure className="mv-block mv-img">
-      {lodSupported
+      {lodOn
         ? <canvas ref={canvasRef} className="mv-img-el" role="img" aria-label={alt ?? caption ?? ''} style={style} />
         : <img className="mv-img-el" src={url} alt={alt ?? caption ?? ''} loading="lazy" style={style} onError={() => setErr(true)} />}
       {caption && <figcaption>{caption}</figcaption>}
@@ -155,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,