@marver-design/marver 0.19.2 → 0.21.0

package/src/client/const.ts

@@ -9,15 +9,33 @@ export const ROUTE = '/__mv'
  *  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. */
+/** The default slide stage: 16:9 at 1280×720, deliberately NOT a config viewport - no
+ *  migration for existing projects, no deck device in sweeps. Dependency-neutral so
+ *  server (shot) and shell (store, play) 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
+/** The one sizing rule for slide frames, shared by canvas, shot and slides mode: a
+ *  `slide: true` frame's stage is its declared viewport when the project defines one
+ *  (a 16:10 deck authored at `laptop` stays 1280×800), else the 1280×720 default. A
+ *  slide is an ordinary frame at that size - slides mode scales the whole stage to the
+ *  screen, so the frame never has to. */
+export function slideSize(
+  frame: { slide?: boolean; viewport?: string },
+  viewports: Record<string, { width: number; height: number }> = {},
+): { width: number; height: number } | null {
+  if (!frame.slide) return null
+  const vp = frame.viewport ? viewports[frame.viewport] : undefined
+  return vp ? { width: vp.width, height: vp.height } : SLIDE_INTRINSIC
+}
+
+/** The baseline every slide document shares, in the frame host and the stage alike: the
+ *  document IS the stage, so the browser's body margin never frames it - whatever the theme
+ *  or the content primitives a previous slide injected. */
+export const SLIDE_DOC_CSS = 'html[data-mv-slide] body { margin: 0 }'
+
+/** How a slide's stage sits in a box of any other size: scaled uniformly to fit and centred.
+ *  A slide never reflows - the canvas node, the player and a shot all show the same stage. */
+export function stageFit(stage: { width: number; height: number }, box: { w: number; h: number }): { k: number; ox: number; oy: number } {
+  const k = Math.max(0.01, Math.min(box.w / stage.width, box.h / stage.height))
+  return { k, ox: (box.w - stage.width * k) / 2, oy: (box.h - stage.height * k) / 2 }
 }

package/src/client/content/chart.tsx

@@ -1,11 +1,9 @@
 /**
  * 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).
+ * marver injects the house theme and keeps the chart still at rest.
  *
- * SVG renderer ONLY - a canvas-rendered chart would pin its frame live on
- * the board (the lean-DOM serializer keeps <canvas> frames degraded). At
+ * SVG renderer ONLY - crisp at any canvas zoom and any stage scale. At
  * rest the chart renders its final state (animation force-disabled); in
  * slides mode (useSlidePlay) it plays its entrance once on mount.
  *
@@ -66,19 +64,21 @@ export function chartTheme(t: { ink: string; font: string; accent: string; groun
 
 /** 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. */
+ *  Tailwind text colour and typeface, a Doc's tokens, or a slide's own type, with no
+ *  per-context wiring. Accent and ground come from slide tokens, then Doc tokens, then the
+ *  mode palette. A slide frame (meta `slide: true`, stamped on <html> as data-mv-slide) or a
+ *  <Slide> wrapper takes the stage label scale. */
 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'),
+    accent: v('--sl-accent', '--marver-slide-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'),
+    inSlide: !!el.closest('.sl-root') || document.documentElement.hasAttribute('data-mv-slide'),
   })
 }
 

package/src/client/content/index.tsx

@@ -22,7 +22,7 @@ export function Diagram(props: Parameters<typeof DiagramRoot>[0]) { ensureStyles
 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'
+export { SLIDE_W, SLIDE_H, useSlidePlay } 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
@@ -98,9 +98,10 @@ export function Img({ src, caption, alt, h }: { src: string; caption?: string; a
   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()
+  // on a slide the LOD canvas is OFF: slides mode scales the whole stage up to the screen,
+  // and a bitmap decoded for the frame's own box would blur there - the plain <img> keeps
+  // its full resolution. A slide frame is marked on <html> (data-mv-slide) before it renders.
+  const inSlide = useInSlide() || (typeof document !== 'undefined' && document.documentElement.hasAttribute('data-mv-slide'))
   // 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).

package/src/client/content/slide.tsx

@@ -1,39 +1,32 @@
 /**
- * The Slide root (v1.5) - the ONE slide primitive. Owns the 1280×720 stage,
- * the tokens, the type roles, and the rest-state motion reset. Recipes are
- * prose in instructions/slides.md; markup composes INSIDE <Slide> with the
- * project's own classes - nothing else is an API.
+ * Slide - an OPTIONAL wrapper, nothing more. A slide is any frame with `slide: true` in its
+ * meta: it renders at its stage size (its declared viewport, else 1280×720) and slides mode
+ * scales the whole stage to the screen, so the frame never scales itself. Everything inside
+ * is the author's own code - layout, type, colour, imagery, motion.
  *
- * Tokens read documented host variables (--marver-slide-*) from the frame's
- * theme when the host defines them, and fall back to the palette - an
- * unthemed repo still gets a coherent deck.
+ * The wrapper fills the frame and tells the content primitives they sit on a stage (Img,
+ * Chart); decks written against the earlier Slide root import it, so it stays.
  *
- * Motion law: at rest (canvas), everything inside a slide is STILL - CSS
- * animations and transitions are suspended. Slides mode lifts the reset by
- * setting `data-sl-play` on <html> (the stage owns that flag), which also
- * arms the entrance presets (`data-animate`, run once after the swap
- * settles - the stage adds `data-sl-entered`).
+ * The playback contract lives with the player (src/client/stage/main.tsx): while a deck
+ * plays, <html> carries `data-sl-play`, plus `data-sl-entered` once each slide has arrived -
+ * authors key their own CSS and JS motion off them. useSlidePlay() is the same flag for React.
  */
-import { createContext, useContext, useEffect, useRef, useSyncExternalStore, type CSSProperties, type ReactNode } from 'react'
-import { FONT_STACK } from './palette.ts'
+import { createContext, useContext, useSyncExternalStore, type CSSProperties, type ReactNode } from 'react'
+import { SLIDE_INTRINSIC } from '../const.ts'
 
-export const SLIDE_W = 1280
-export const SLIDE_H = 720
-/** Stage margins: wide at the sides, tight top and bottom (content 1104x632). */
-const PAD_X = 88
-const PAD_Y = 44
+/** The default stage. A deck may declare another size through its frames' viewport. */
+export const SLIDE_W = SLIDE_INTRINSIC.width
+export const SLIDE_H = SLIDE_INTRINSIC.height
 
-/** Img (and anything else that cares) asks: am I inside a slide? */
+/** Img (and anything else that cares) asks: am I inside a <Slide>? */
 export const SlideCtx = createContext(false)
 export const useInSlide = () => useContext(SlideCtx)
 
 /**
- * Is slides mode live? The STAGE owns the answer: it stamps `data-sl-play`
- * on <html> (boot: the `slides` URL param; thereafter its own messages).
- * CSS reacts to the attribute natively; React components (Chart's entrance,
- * Video's player mount) subscribe here - a MutationObserver over the
- * documentElement attribute, so the contract is one attribute, one owner,
- * observable by anyone.
+ * Is a deck playing? The STAGE owns the answer: it stamps `data-sl-play` on <html> (boot:
+ * the `slides` URL param). CSS reacts to the attribute natively; React components (Chart's
+ * entrance, Video's player mount) subscribe here - a MutationObserver over the
+ * documentElement attribute, so the contract is one attribute, one owner, observable by anyone.
  */
 const subscribePlay = (cb: () => void) => {
   if (typeof document === 'undefined') return () => {}
@@ -44,195 +37,27 @@ const subscribePlay = (cb: () => void) => {
 const readPlay = () => typeof document !== 'undefined' && document.documentElement.hasAttribute('data-sl-play')
 export const useSlidePlay = (): boolean => useSyncExternalStore(subscribePlay, readPlay, () => false)
 
+/* the frame document must not pad the stage: a stage-wide root in a margined body overflows */
 const SLIDE_CSS = `
-/* the frame document must not pad the stage: a 1280px root in a margined
-   body overflows the intrinsic by 16px - reset where a slide lives. The body
-   also paints the slide ground, so the letterbox around a scaled stage is
-   seamless instead of a default-white halo. */
-body:has(.sl-root) { margin: 0; background: var(--marver-slide-ground, #ffffff) }
-.dark body:has(.sl-root), [data-theme="dark"] body:has(.sl-root) { background: var(--marver-slide-ground-dark, #101014) }
-.sl-root, .sl-root * { box-sizing: border-box }
-.sl-root {
-  --sl-ink: var(--marver-slide-ink, #18181b);
-  --sl-ground: var(--marver-slide-ground, #ffffff);
-  --sl-accent: var(--marver-slide-accent, #0088ff);
-  --sl-muted: var(--marver-slide-muted, rgba(24, 24, 27, .55));
-  --sl-tempo: var(--marver-slide-tempo, 350ms);
-  --sl-font: var(--marver-slide-font, ${FONT_STACK});
-  /* THE STAGE MARGINS, in px and ASYMMETRIC - the shape every well-made deck
-     uses. Generous at the sides, tighter top and bottom, so the title sits
-     high, the footnote sits low, and the middle band is the tallest thing on
-     the slide. Percentages are wrong here twice over: they would resolve
-     against this absolutely positioned box's containing block (the viewport,
-     not the stage), and one value for all four sides squeezes the middle. */
-  --sl-pad-x: var(--marver-slide-pad-x, ${PAD_X}px);
-  --sl-pad-y: var(--marver-slide-pad-y, ${PAD_Y}px);
-  --sl-margin: var(--sl-pad-x);          /* the side margin, for author math */
-  /* THE FIT: authored at exactly ${SLIDE_W}x${SLIDE_H}, then scaled and
-     centered to the largest box the viewport gives it - fill window, any
-     device, a canvas node resized to a phone, any published viewer's screen.
-     One coordinate system, so the author's px, Tailwind classes, and charts
-     all scale together. Pure CSS (tan(atan2(a, b)) is the unitless ratio
-     a / b), so a lean cover - which runs no JS - reflows to the right scale
-     the moment its node is resized. 1 wherever the viewport IS the stage.
-     Declared under @supports below: an engine without CSS trig would keep
-     the invalid tokens, defeat the var() fallback, and invalidate the whole
-     transform - unscaled AND uncentered. */
-  --sl-fit: 1;
-  /* translate-center, not inset+margin:auto - an overconstrained absolute
-     box (1280px stage in a 390px viewport) resolves margins to 0 and the
-     scaled slide drifts off-center; translate(-50%,-50%) centers at ANY size */
-  position: absolute; left: 50%; top: 50%;
-  width: ${SLIDE_W}px; height: ${SLIDE_H}px; overflow: hidden;
-  transform: translate(-50%, -50%) scale(var(--sl-fit, 1)); transform-origin: center center;
-  background: var(--sl-ground); color: var(--sl-ink);
-  font-family: var(--sl-font);
-  padding: var(--sl-pad-y) var(--sl-pad-x); box-sizing: border-box;
-  display: flex; flex-direction: column; justify-content: center; gap: 28px;
-}
-@supports (width: calc(1px * tan(atan2(1px, 1px)))) {
-  .sl-root { --sl-fit: min(tan(atan2(100vw, ${SLIDE_W}px)), tan(atan2(100vh, ${SLIDE_H}px))) }
-}
-.dark .sl-root, [data-theme="dark"] .sl-root {
-  --sl-ink: var(--marver-slide-ink-dark, #f5f5f7);
-  --sl-ground: var(--marver-slide-ground-dark, #101014);
-  --sl-muted: var(--marver-slide-muted-dark, rgba(245, 245, 247, .55));
-}
-/* type roles - fixed values, one coordinate system with the 1280x720 stage.
-   sl-display is the ONE sanctioned oversize: the big-number stat, a section
-   numeral, the manifesto line - never running text. */
-.sl-display { font-size: 160px; line-height: 1; font-weight: 800; letter-spacing: -.03em; margin: 0; font-variant-numeric: tabular-nums }
-/* sl-stat is the ROW size: three or four figures side by side, where one
-   sl-display would not fit and sl-assertion would not read as a number. */
-.sl-stat { font-size: 88px; line-height: 1.02; font-weight: 700; letter-spacing: -.03em; margin: 0; font-variant-numeric: tabular-nums }
-.sl-assertion { font-size: 56px; line-height: 1.08; font-weight: 750; letter-spacing: -.02em; margin: 0 }
-.sl-support { font-size: 30px; line-height: 1.25; font-weight: 500; margin: 0 }
-.sl-body { font-size: 24px; line-height: 1.45; margin: 0 }
-.sl-caption { font-size: 18px; line-height: 1.4; color: var(--sl-muted); margin: 0 }
-
-/* THE MOTION RESET - at rest, a slide is still: animation NONE (not paused -
-   none is deterministic; paused can freeze mid-keyframe) and no transitions.
-   Slides mode (the stage sets data-sl-play on <html>) lifts it. This governs
-   EVERY descendant - spinners and loaders included - and that is the Slide
-   contract, documented in instructions/slides.md. */
-:root:not([data-sl-play]) .sl-root, :root:not([data-sl-play]) .sl-root *,
-:root:not([data-sl-play]) .sl-root *::before, :root:not([data-sl-play]) .sl-root *::after {
-  animation: none !important;
-  transition: none !important;
-}
-
-/* Entrance presets: inert until the stage marks the swap settled. An element
-   carrying a morph name must not carry data-animate (one transform owner) -
-   the doctrine says so; the selector below cannot check it, the review gate does. */
-[data-sl-play] .sl-root [data-animate] { opacity: 0 }
-/* ONE tempo per deck: the token times the entrances AND the view-transition
-   morphs between slides (the stage document is this document). */
-::view-transition-group(*), ::view-transition-old(root), ::view-transition-new(root) {
-  animation-duration: var(--marver-slide-tempo, 350ms);
-}
-[data-sl-play][data-sl-entered] .sl-root [data-animate] {
-  opacity: 1; animation-duration: var(--sl-tempo); animation-timing-function: cubic-bezier(.2, .7, .2, 1);
-  animation-fill-mode: both;
-}
-[data-sl-play][data-sl-entered] .sl-root [data-animate="fade-up"] { animation-name: sl-fade-up }
-[data-sl-play][data-sl-entered] .sl-root [data-animate="fade"] { animation-name: sl-fade }
-[data-sl-play][data-sl-entered] .sl-root [data-animate="scale-in"] { animation-name: sl-scale-in }
-[data-sl-play][data-sl-entered] .sl-root [data-animate-delay="1"] { animation-delay: 80ms }
-[data-sl-play][data-sl-entered] .sl-root [data-animate-delay="2"] { animation-delay: 160ms }
-[data-sl-play][data-sl-entered] .sl-root [data-animate-delay="3"] { animation-delay: 240ms }
-@keyframes sl-fade-up { from { opacity: 0; transform: translateY(18px) } to { opacity: 1; transform: none } }
-@keyframes sl-fade { from { opacity: 0 } to { opacity: 1 } }
-@keyframes sl-scale-in { from { opacity: 0; transform: scale(.94) } to { opacity: 1; transform: none } }
-@media (prefers-reduced-motion: reduce) {
-  [data-sl-play] .sl-root [data-animate] { opacity: 1; animation: none !important }
-}
+body:has(.sl-root) { margin: 0 }
+.sl-root { position: relative; box-sizing: border-box; width: 100%; min-height: 100vh }
 `
 
 function ensureSlideStyles() {
   // keyed by the DOCUMENT, not a module boolean - HMR reloads and multiple
   // roots must not double- or under-inject
-  if (typeof document === 'undefined' || document.querySelector('style[data-mv-slide]')) return
+  if (typeof document === 'undefined' || document.querySelector('style[data-mv-slide-css]')) return
   const el = document.createElement('style')
-  el.setAttribute('data-mv-slide', '')
+  el.setAttribute('data-mv-slide-css', '')
   el.textContent = SLIDE_CSS
   document.head.appendChild(el)
 }
 
-export function Slide({ children, style }: { children?: ReactNode; style?: CSSProperties }) {
+export function Slide({ children, className, style }: { children?: ReactNode; className?: string; style?: CSSProperties }) {
   ensureSlideStyles()
-  const ref = useRef<HTMLDivElement>(null)
-  // DEV overflow marker: a slide that outgrows its stage is a VISIBLE defect
-  // (outline + console + data-sl-over), never a silent clip decision left to
-  // chance. Development only - a published deck paints no diagnostics.
-  // Two tests, both in the stage's LAYOUT space (rects are post-transform,
-  // the fit scales the stage, so rect offsets are divided by the scale):
-  //  1. escape - a box leaving the 1280x720 stage. Measured against the
-  //     STAGE, not the padded content box: full-bleed images and clipped
-  //     photos break the margins on purpose.
-  //  2. collision - a flex/grid child outgrowing its parent's content box.
-  //     Inside a flex column a body at flex:1 keeps its own box while ITS
-  //     children spill over the neighbouring bands, all still inside the
-  //     stage, which test 1 never sees.
-  useEffect(() => {
-    if (!import.meta.env.DEV) return
-    const el = ref.current
-    if (!el || typeof ResizeObserver === 'undefined') return
-    let last: boolean | null = null
-    let raf = 0
-    const check = () => {
-      raf = 0
-      const r = el.getBoundingClientRect()
-      const k = el.offsetWidth ? r.width / el.offsetWidth : 1
-      const pad = (v: string) => parseFloat(v) || 0
-      const W = el.offsetWidth, H = el.offsetHeight
-      let over = el.scrollHeight > el.clientHeight + 1 || el.scrollWidth > el.clientWidth + 1
-      let culprit: Element | null = null
-      const all = el.querySelectorAll('*')
-      const n = Math.min(all.length, 600)
-      for (let i = 0; !over && i < n; i++) {
-        const c = all[i]
-        const b = c.getBoundingClientRect()
-        if (!b.width && !b.height) continue
-        const y0 = (b.top - r.top) / k, y1 = (b.bottom - r.top) / k
-        const x0 = (b.left - r.left) / k, x1 = (b.right - r.left) / k
-        if (y1 > H + 1.5 || y0 < -1.5 || x1 > W + 1.5 || x0 < -1.5) { over = true; culprit = c; break }
-        const par = c.parentElement
-        if (!par || !par.clientHeight) continue
-        const ps = getComputedStyle(par)
-        if (!/flex|grid/.test(ps.display) || ps.overflowY !== 'visible' || ps.overflowX !== 'visible') continue
-        if (/absolute|fixed/.test(getComputedStyle(c).position)) continue
-        const pr = par.getBoundingClientRect()
-        const lo = (pr.top - b.top) / k + pad(ps.paddingTop)
-        const hi = (b.bottom - pr.bottom) / k + pad(ps.paddingBottom)
-        if (lo > 2 || hi > 2) { over = true; culprit = c; break }
-      }
-      if (over === last) return                       // idempotent: never write the same state twice
-      last = over
-      el.style.outline = over ? '3px solid #ff4d4f' : ''
-      el.dataset.slOver = over ? '1' : ''
-      if (over) console.warn('[marver slide] content overflows the 1280×720 stage - split the slide, never shrink the type', culprit ?? el)
-    }
-    const schedule = () => { if (!raf) raf = requestAnimationFrame(check) }
-    // observe every descendant (bounded): a flex child keeps its box while its
-    // content grows, and a root-only observer never hears about that. Nodes
-    // added later are picked up by the childList observer - childList ONLY,
-    // so our own outline/data writes (attribute mutations) cannot re-trigger.
-    const ro = new ResizeObserver(schedule)
-    const seen = new WeakSet<Element>()
-    const observeAll = () => {
-      const all = el.querySelectorAll('*')
-      for (let i = 0; i < all.length && i < 600; i++) { if (!seen.has(all[i])) { seen.add(all[i]); ro.observe(all[i]) } }
-    }
-    ro.observe(el)
-    observeAll()
-    const mo = new MutationObserver(() => { observeAll(); schedule() })
-    mo.observe(el, { childList: true, subtree: true })
-    schedule()
-    return () => { cancelAnimationFrame(raf); ro.disconnect(); mo.disconnect() }
-  }, [])
   return (
     <SlideCtx.Provider value={true}>
-      <div ref={ref} className="sl-root" style={style}>{children}</div>
+      <div className={className ? `sl-root ${className}` : 'sl-root'} style={style}>{children}</div>
     </SlideCtx.Provider>
   )
 }

package/src/client/frame-host/main.tsx

@@ -8,6 +8,7 @@ import { createRoot } from 'react-dom/client'
 
 import './bridge.js'
 import { frameFile, frames, layoutChain, layouts, providers } from './registry.ts'
+import { SLIDE_DOC_CSS } from '../const.ts'
 
 const params = new URLSearchParams(location.search)
 const id = params.get('id') ?? ''
@@ -77,6 +78,15 @@ async function boot() {
     // No typeof gate: memo()/forwardRef() components are objects, not functions.
     // React + the ErrorBoundary validate the element type better than we can.
     if (Frame == null) return fail(`${fileKey} has no default export`)
+    // a slide frame says so on its document - content primitives size for a stage by it, and
+    // the slide baseline (SLIDE_DOC_CSS) applies, the same one the stage installs
+    if (frameMod.meta?.slide === true) {
+      document.documentElement.setAttribute('data-mv-slide', '')
+      const base = document.createElement('style')
+      base.setAttribute('data-mv-slide-doc', '')
+      base.textContent = SLIDE_DOC_CSS
+      document.head.appendChild(base)
+    }
 
     const wrappers: any[] = []
     const providerKey = Object.keys(providers)[0]