@marver-design/marver 0.12.0 → 0.14.0

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>}

package/src/client/content/slide.tsx

@@ -0,0 +1,238 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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`).
+ */
+import { createContext, useContext, useEffect, useRef, useSyncExternalStore, type CSSProperties, type ReactNode } from 'react'
+import { FONT_STACK } from './palette.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
+
+/** 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.
+ */
+const subscribePlay = (cb: () => void) => {
+  if (typeof document === 'undefined') return () => {}
+  const mo = new MutationObserver(cb)
+  mo.observe(document.documentElement, { attributes: true, attributeFilter: ['data-sl-play', 'data-sl-entered'] })
+  return () => mo.disconnect()
+}
+const readPlay = () => typeof document !== 'undefined' && document.documentElement.hasAttribute('data-sl-play')
+export const useSlidePlay = (): boolean => useSyncExternalStore(subscribePlay, readPlay, () => false)
+
+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 }
+}
+`
+
+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
+  const el = document.createElement('style')
+  el.setAttribute('data-mv-slide', '')
+  el.textContent = SLIDE_CSS
+  document.head.appendChild(el)
+}
+
+export function Slide({ children, style }: { children?: ReactNode; 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>
+    </SlideCtx.Provider>
+  )
+}

package/src/client/content/video.tsx

@@ -0,0 +1,126 @@
+/**
+ * Video (v1.5) - poster-first, glass-controlled.
+ *
+ * At rest there is NO <video> element and no media fetch: the poster <img>
+ * plus a play glyph IS the slide (lean-DOM safe - a <video> element would
+ * pin the frame live). In slides mode (useSlidePlay) the real element
+ * mounts with the glass control strip: play/pause, seekable progress, mute,
+ * fullscreen, auto-hiding. Leaving the slide (play flips off / unmount)
+ * pauses everything.
+ *
+ * Sources: a design-asset path (poster REQUIRED - it is the canvas
+ * rendering) or a public https direct-file URL (mp4/webm; HLS where the
+ * browser supports it natively).
+ */
+import { useEffect, useRef, useState } from 'react'
+import { assetUrl } from './md.ts'
+import { useSlidePlay } from './slide.tsx'
+
+const isRemote = (s: string) => /^https:\/\//.test(s)
+const resolve = (s: string): string | null => (isRemote(s) ? s : assetUrl(s))
+
+const VIDEO_CSS = `
+.mv-video { position: relative; width: 100%; border-radius: 14px; overflow: hidden; background: #000; aspect-ratio: 16 / 9 }
+.mv-video > img, .mv-video > video { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; display: block }
+.mv-video .glyph { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; pointer-events: none }
+.mv-video .glyph span { width: 72px; height: 72px; border-radius: 999px; display: flex; align-items: center; justify-content: center;
+  background: rgba(16, 16, 20, .55); backdrop-filter: blur(10px); border: 1px solid rgba(255, 255, 255, .28) }
+.mv-video .glyph svg { margin-left: 4px }
+.mv-video .strip { position: absolute; left: 10px; right: 10px; bottom: 10px; display: flex; align-items: center; gap: 10px;
+  padding: 8px 12px; border-radius: 999px; background: rgba(16, 16, 20, .55); backdrop-filter: blur(12px);
+  border: 1px solid rgba(255, 255, 255, .22); color: #fff; opacity: 1; transition: opacity .25s }
+.mv-video .strip.hidden { opacity: 0; pointer-events: none }
+.mv-video .strip button { border: 0; background: none; color: #fff; cursor: pointer; display: flex; padding: 2px }
+.mv-video .strip input[type=range] { flex: 1; accent-color: #fff; height: 3px; cursor: pointer }
+.mv-video .strip .t { font: 500 12px/1 -apple-system, system-ui, sans-serif; opacity: .85; min-width: 34px }
+`
+let injected = false
+const ensureCss = () => {
+  if (injected || typeof document === 'undefined') return
+  injected = true
+  const el = document.createElement('style')
+  el.setAttribute('data-mv-video', '')
+  el.textContent = VIDEO_CSS
+  document.head.appendChild(el)
+}
+
+const fmt = (s: number) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, '0')}`
+
+const PlayGlyph = ({ size = 26 }: { size?: number }) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill="#fff"><path d="M8 5.5 19 12 8 18.5 Z" /></svg>
+)
+const PauseGlyph = () => (
+  <svg width="18" height="18" viewBox="0 0 24 24" fill="#fff"><rect x="6" y="5" width="4" height="14" rx="1" /><rect x="14" y="5" width="4" height="14" rx="1" /></svg>
+)
+
+export function Video({ src, poster }: { src: string; poster?: string }) {
+  ensureCss()
+  const play = useSlidePlay()
+  const posterUrl = poster ? resolve(poster) : null
+  const srcUrl = resolve(src)
+  const bad = !srcUrl || (!isRemote(src) && !posterUrl)
+  if (bad) {
+    return (
+      <div className="mv-block mv-imgerr">
+        <b>video unavailable</b>
+        <span>{src}</span>
+        <span className="dim">{!srcUrl ? 'must be a design/assets/ path or an https file URL' : 'a local video needs a poster - it IS the slide at rest'}</span>
+      </div>
+    )
+  }
+  // AT REST: the poster and nothing else - no <video>, no fetch, still.
+  if (!play) {
+    return (
+      <div className="mv-block mv-video">
+        {posterUrl ? <img src={posterUrl} alt="" loading="lazy" /> : null}
+        <div className="glyph"><span><PlayGlyph /></span></div>
+      </div>
+    )
+  }
+  return <Player src={srcUrl!} poster={posterUrl ?? undefined} />
+}
+
+/** The glass strip - deliberately four controls and a clock, nothing more. */
+function Player({ src, poster }: { src: string; poster?: string }) {
+  const ref = useRef<HTMLVideoElement>(null)
+  const [playing, setPlaying] = useState(false)
+  const [muted, setMuted] = useState(false)
+  const [t, setT] = useState(0)
+  const [dur, setDur] = useState(0)
+  const [idle, setIdle] = useState(false)
+  const idleTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const poke = () => {
+    setIdle(false)
+    if (idleTimer.current) clearTimeout(idleTimer.current)
+    idleTimer.current = setTimeout(() => setIdle(true), 2200)
+  }
+  useEffect(() => () => { if (idleTimer.current) clearTimeout(idleTimer.current); ref.current?.pause() }, [])
+  const toggle = () => { const v = ref.current; if (!v) return; if (v.paused) { void v.play(); poke() } else v.pause() }
+  return (
+    <div className="mv-block mv-video" onPointerMove={poke} onClick={(e) => { if (e.target === ref.current) toggle() }}>
+      <video ref={ref} src={src} poster={poster} preload="metadata" muted={muted} playsInline
+        onPlay={() => { setPlaying(true); poke() }} onPause={() => { setPlaying(false); setIdle(false) }}
+        onTimeUpdate={(e) => setT(e.currentTarget.currentTime)}
+        onLoadedMetadata={(e) => setDur(e.currentTarget.duration || 0)} />
+      {!playing && <div className="glyph"><span><PlayGlyph /></span></div>}
+      <div className={`strip${playing && idle ? ' hidden' : ''}`}>
+        <button aria-label={playing ? 'Pause' : 'Play'} onClick={toggle}>{playing ? <PauseGlyph /> : <PlayGlyph size={18} />}</button>
+        <span className="t">{fmt(t)}</span>
+        <input type="range" min={0} max={dur || 0} step={0.1} value={t} aria-label="Seek"
+          onChange={(e) => { const v = ref.current; if (v) { v.currentTime = Number(e.target.value); setT(v.currentTime) } }} />
+        <span className="t">{fmt(dur)}</span>
+        <button aria-label={muted ? 'Unmute' : 'Mute'} onClick={() => setMuted((m) => !m)}>
+          <svg width="17" height="17" viewBox="0 0 24 24" fill="none" stroke="#fff" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <path d="M11 5 6 9 H3 v6 h3 l5 4 Z" fill="#fff" stroke="none" />
+            {muted ? <path d="m16 9 6 6 M22 9 l-6 6" /> : <path d="M15.5 8.5 a5 5 0 0 1 0 7 M18.5 6 a9 9 0 0 1 0 12" />}
+          </svg>
+        </button>
+        <button aria-label="Fullscreen" onClick={(e) => void (e.currentTarget.closest('.mv-video') as HTMLElement | null)?.requestFullscreen?.()}>
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#fff" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <path d="M8 3 H4 a1 1 0 0 0 -1 1 v4 M16 3 h4 a1 1 0 0 1 1 1 v4 M8 21 H4 a1 1 0 0 1 -1 -1 v-4 M16 21 h4 a1 1 0 0 0 1 -1 v-4" />
+          </svg>
+        </button>
+      </div>
+    </div>
+  )
+}

package/src/client/shell/App.tsx

@@ -1,16 +1,16 @@
 import { Component, useEffect, useRef, useState, type MouseEvent as ReactMouseEvent, type PointerEvent as ReactPointerEvent, type ReactNode } from 'react'
 import { createPortal } from 'react-dom'
-import { useStore, CONFIG, LOCKED_SHELL, PUBLISHED, SOURCE_REVEALED, boardLabel, boardFrames, cap, humanize, fetchBoardNames, landingMode, type FrameEntry } from './store.ts'
+import { useStore, CONFIG, LOCKED_SHELL, PUBLISHED, SOURCE_REVEALED, boardLabel, boardFrames, cap, humanize, fetchBoardNames, hydrateBoardPolicy, landingMode, playsAsSlides, type FrameEntry } from './store.ts'
 import { Tip } from './Tip.tsx'
 import { PKG, ROUTE } from '../const.ts'
 import { animateLayout, Canvas, canvasCtl } from './canvas/Canvas.tsx'
 import { frameByWindow } from './canvas/frame-registry.ts'
-import { enterFocus, enterPlay, playCtl, PlayOverlay } from './Play.tsx'
+import { enterFocus, enterPlay, enterSlides, playCtl, PlayOverlay } from './Play.tsx'
 import { bootHash, parseHash, writeHash } from './hash.ts'
-import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, ColumnsIcon, FrameRectIcon, IntentGlyph, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, ParallelogramFillIcon, PencilSimpleIcon, PlayIcon, SignpostIcon, SunIcon, VariantsIcon, XIcon, deviceIcon } from './icons.tsx'
+import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, ColumnsIcon, FrameRectIcon, IntentGlyph, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, ParallelogramFillIcon, PencilSimpleIcon, PlayIcon, SignpostIcon, SlideFrameIcon, SunIcon, VariantsIcon, XIcon, deviceIcon } from './icons.tsx'
 import { CommentsController, revealThread } from './Comments.tsx'
 import { poweredByUrl } from '../../shared/utm.ts'
-import { useComments } from './comments-store.ts'
+import { avatarFallback, useComments } from './comments-store.ts'
 import { CommentButton, DevicePicker, HideUIButton, LaserButton, Popover, ThemePicker, toggleHideUI, usePopover } from './Toolbar.tsx'
 
 const commentsStore = () => useComments.getState()
@@ -553,6 +553,14 @@ export function App() {
     if (booted) return
     booted = true
     const start = async () => {
+      if (!PUBLISHED) {
+        // dev: hydrate board policy (slides/type/open) from the repo so P and
+        // deep links preview exactly what viewers get
+        try {
+          const r = await fetch(`${ROUTE}/api/policy`)
+          if (r.ok) hydrateBoardPolicy(((await r.json()) as { boards?: Record<string, never> }).boards ?? {})
+        } catch { /* dev server without the route - fine */ }
+      }
       if (bootHash.board) {
         if (bootHash.board !== useStore.getState().board)   // a deep link wins
           useStore.setState({ board: bootHash.board, boardAuto: bootHash.board === 'all-scenes' })
@@ -569,7 +577,8 @@ export function App() {
         // (01-sharing §6.1 step 3) - the stage mounts any manifest frame, so no
         // board lookup is needed
         enterFocus(bootHash.focus.at, { ...bootHash.focus, deep: true })
-      } else if (ok && bootHash.play) enterPlay(bootHash.play)     // #/p/<board> alone = board start
+      } else if (ok && bootHash.play?.slides) enterSlides(bootHash.play)
+      else if (ok && bootHash.play) enterPlay(bootHash.play)     // #/p/<board> alone = board start
       else if (ok && PUBLISHED) {
         // published landing: explicit `open` beats the type default; canvas and
         // board land on the canvas surface (board-scoped already); a lock will
@@ -577,6 +586,7 @@ export function App() {
         const mode = landingMode(useStore.getState().board)
         if (mode === 'present') enterPlay()
         else if (mode === 'focus') enterFocus()
+        else if (mode === 'slides') enterSlides()
       }
     }
     void start()
@@ -619,7 +629,10 @@ export function App() {
       if (h.focus) {
         enterFocus(h.focus.at, { ...h.focus, deep: true })
       } else if (h.play) {
-        if (s.play) playCtl.sync(h.play)
+        // sync only holds WITHIN a mode: a slides hash over a present stage (or
+        // the reverse) re-enters, which remounts the stage with the right src
+        if (s.play && !!h.play.slides === !!s.play.slides) playCtl.sync(h.play)
+        else if (h.play.slides) enterSlides(h.play)
         else enterPlay(h.play)
       } else {
         if (s.play) s.setPlay(null)
@@ -835,7 +848,9 @@ export function App() {
         else if (s.laser) s.setLaser(false)          // Escape also exits laser mode (parity with comment)
         else s.interact ? setInteract(null) : select(null)
       }
-      if (e.key === 'p') enterPlay()
+      // a slides board PLAYS as slides even when its landing is the canvas -
+      // the deck is what the board IS; landing only says where viewers arrive
+      if (e.key === 'p') { if (playsAsSlides(useStore.getState().board)) enterSlides(); else enterPlay() }
       // H hides all chrome (shared binary Hide-UI); press again to reveal. Not persisted,
       // so a refresh always restores it (the safety net for a forgotten toggle).
       if (e.key === 'h') { toggleHideUI(); return }
@@ -1067,11 +1082,14 @@ export function App() {
                     const on = !!n && selection.includes(n.key)
                     rows.push(
                       <div key={f.id} className={`sub${on ? ' on' : ''}`} onClick={(e) => go(f.id, e.shiftKey)} onContextMenu={(e) => cm.open(e, frameMenu(f))} title={f.intent}>
-                        {/* every frame leads with an icon: intent glyph for content
-                            frames, the plain frame rectangle for UI frames */}
-                        {f.intent
-                          ? <IntentGlyph intent={f.intent} size={13} className="iicon" aria-label={f.intent} />
-                          : <FrameRectIcon size={13} className="iicon" />}
+                        {/* every frame leads with an icon: the slide badge first (a deck
+                            frame is a deck frame whatever it imports), intent glyph for
+                            content frames, the plain rectangle for UI frames */}
+                        {f.slide
+                          ? <SlideFrameIcon size={13} className="iicon" role="img" aria-hidden={false} aria-label="slide" />
+                          : f.intent
+                            ? <IntentGlyph intent={f.intent} size={13} className="iicon" aria-label={f.intent} />
+                            : <FrameRectIcon size={13} className="iicon" />}
                         {cap(f.id.split('/').slice(1).join('/') || f.id)}
                       </div>,
                     )
@@ -1104,7 +1122,7 @@ export function App() {
         <i className="sep" />
         {/* far right: view management - prototype, hide, collapse */}
         <Tip side="bottom" label={<><b>Prototype view</b><span>P</span></>}>
-          <button className="sh-pill-btn" onClick={() => enterPlay()}><PlayIcon size={15} /></button>
+          <button className="sh-pill-btn" onClick={() => (playsAsSlides(useStore.getState().board) ? enterSlides() : enterPlay())}><PlayIcon size={15} /></button>
         </Tip>
         <HideUIButton />
         <Tip side="bottom" label={<><b>Collapse toolbar</b><span>⌘/</span></>}>
@@ -1169,6 +1187,15 @@ function JamToasts({ toasts }: { toasts: import('./store.ts').Toast[] }) {
   )
 }
 
+/** The pill's face for a human notification - the author's picture, or the
+ *  house initials fallback (same ladder the thread avatars use). */
+function JamAvatar({ author }: { author: { name?: string; avatar?: string; id?: string; email?: string } }) {
+  const { initials, hue } = avatarFallback(author)
+  return author.avatar
+    ? <img className="sh-jam-ava" src={author.avatar} alt="" referrerPolicy="no-referrer" />
+    : <span className="sh-jam-ava init" style={{ background: `hsl(${hue} 55% 45%)` }}>{initials}</span>
+}
+
 /** A data-goto whose target frame is not on the current board follows the frame HOME:
  *  the first curated board (switcher rank) that pins it is switched to and the frame
  *  focused there - a link is navigation, and navigation never edits a board. Only a
@@ -1239,11 +1266,18 @@ async function viewNote(note: import('./store.ts').JamNote, dismiss: () => void)
  *  `badge` shows the +N deck count (replacing View); `inert` disables inner clicks (the deck handles it). */
 function JamToast({ id, note, badge, inert }: { id: number; note: import('./store.ts').JamNote; badge?: number; inert?: boolean }) {
   const dismiss = () => useStore.getState().dismissToast(id)
+  // human pills are person-first: their avatar, "name mentioned you"; the
+  // agent pill keeps its frame-first shape with the mark
+  const human = note.kind && note.author
   return (
     <div className="sh-toast jam">
-      <span className="sh-jam-mark"><ParallelogramFillIcon size={17} /></span>
+      {human
+        ? <JamAvatar author={note.author!} />
+        : <span className="sh-jam-mark"><ParallelogramFillIcon size={17} /></span>}
       <div className="sh-jam-txt">
-        <b className="sh-jam-frame"><span className="t">{note.frameTitle ?? note.board}</span></b>
+        {human
+          ? <b className="sh-jam-frame"><span className="t">{note.author!.name ?? 'Someone'}</span> <span className="v">{note.kind === 'mention' ? 'mentioned you' : 'replied'}</span></b>
+          : <b className="sh-jam-frame"><span className="t">{note.frameTitle ?? note.board}</span></b>}
         <span className="sh-jam-prev">{note.preview}</span>
       </div>
       {badge != null