@marver-design/marver 0.13.0 → 0.15.0

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,223 @@
+/**
+ * Video - poster-first, glass-controlled, in EVERY kind of frame.
+ *
+ * At rest there is NO <video> element and no media fetch: the poster <img>
+ * plus a play glyph IS the frame (lean-DOM safe - a <video> element would
+ * pin the frame live). The real element mounts with the glass control strip
+ * (play/pause, seekable progress, mute, fullscreen, auto-hiding) in two ways:
+ *   - anywhere a frame is live (interact mode, play/present, focus, a
+ *     published prototype): the poster is the play button - one click mounts
+ *     the player and starts it, inside that gesture, so sound is allowed;
+ *   - in slides mode (useSlidePlay): the player mounts on its own, the deck's
+ *     entrance contract.
+ * `autoplay` is the third shape - an ambient loop (muted, no strip) for a hero
+ * or a product mockup; it mounts the element as soon as the frame is live,
+ * which keeps that frame live on the canvas (the serializer marks <video>
+ * degraded) - an explicit, per-video choice.
+ * Leaving (play flips off / unmount) pauses everything.
+ *
+ * Sources: a design-asset path or a public https direct-file URL (mp4/webm;
+ * HLS where the browser supports it natively). The poster is the frame at
+ * rest: authored, or - omitted on a local clip - the generated
+ * `<clip>.poster.png` beside it (server/poster.ts renders it; the primitive
+ * asks the dev server once when the file is missing). `ratio` is the CSS aspect-ratio of the box
+ * (default 16 / 9; "9 / 16" for a vertical clip inside a phone screen).
+ */
+import { useEffect, useRef, useState, useSyncExternalStore, type CSSProperties } from 'react'
+import { ROUTE } from '../const.ts'
+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))
+/** The generated poster's conventional name (server/poster.ts owns the rule). */
+const posterNameFor = (src: string) => `${src}.poster.png`
+
+// One generation request per clip per document: the dev server renders the poster from
+// the clip's own first moments (server/poster.ts) and the <img> reloads. A published canvas
+// has no such API (build already generated the file); a failed request just keeps the card.
+const requested = new Map<string, Promise<boolean>>()
+const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
+// in-flight probes + generations, for the shot renderer's settle (like __mvLodBusy): a
+// screenshot taken while a poster is still being rendered would show the empty box
+let busy = 0
+if (typeof window !== 'undefined') (window as { __mvPosterBusy?: () => number }).__mvPosterBusy = () => busy
+const requestPoster = (src: string): Promise<boolean> => {
+  let p = requested.get(src)
+  if (!p) {
+    p = (async () => {
+      // the owner gate wants the double-submit cookie echoed; a frame host opened cold has not
+      // made an API GET yet, so prime it with the cheapest one first
+      if (!csrf()) await fetch(`${ROUTE}/api/policy`).catch(() => null)
+      const r = await fetch(`${ROUTE}/api/poster?src=${encodeURIComponent(src)}`, { headers: { 'x-mv-c': csrf() } }).catch(() => null)
+      return !!r?.ok
+    })()
+    requested.set(src, p)
+    // a failure is not forever: the next mount (a fix, Chrome installed) may ask again
+    void p.then((ok) => { if (!ok) requested.delete(src) })
+  }
+  return p
+}
+
+/** Is the human in the canvas's interact mode on this frame? The bridge mirrors sh:interactive
+ *  on the document. Absent everywhere else (play, focus, published) - only the true->false
+ *  transition matters: it disarms a playing clip when the mode is left. */
+const subscribeInteractive = (cb: () => void) => {
+  if (typeof document === 'undefined') return () => {}
+  const mo = new MutationObserver(cb)
+  mo.observe(document.documentElement, { attributes: true, attributeFilter: ['data-sh-interactive'] })
+  return () => mo.disconnect()
+}
+const readInteractive = () => typeof document !== 'undefined' && document.documentElement.hasAttribute('data-sh-interactive')
+const useInteractive = (): boolean => useSyncExternalStore(subscribeInteractive, readInteractive, () => false)
+
+const VIDEO_CSS = `
+.mv-video { position: relative; width: 100%; border-radius: 14px; overflow: hidden; background: #000; aspect-ratio: var(--mv-video-ratio, 16 / 9) }
+.mv-video.armed { cursor: pointer }
+.mv-video.armed:hover .glyph span { background: rgba(16, 16, 20, .75) }
+.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: 2px }
+.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')}`
+
+// Phosphor icons (play/pause in the fill weight, speaker and corners regular), path data
+// inlined from @phosphor-icons/core - MIT (c) Phosphor Icons - the same way the shell's
+// icons.tsx does it: no icon dependency reaches the host.
+const P = ({ d, size }: { d: string; size: number }) => (
+  <svg width={size} height={size} viewBox="0 0 256 256" fill="#fff" aria-hidden><path d={d} /></svg>
+)
+const PLAY = 'M240,128a15.74,15.74,0,0,1-7.6,13.51L88.32,229.65a16,16,0,0,1-16.2.3A15.86,15.86,0,0,1,64,216.13V39.87a15.86,15.86,0,0,1,8.12-13.82,16,16,0,0,1,16.2.3L232.4,114.49A15.74,15.74,0,0,1,240,128Z'
+const PAUSE = 'M216,48V208a16,16,0,0,1-16,16H160a16,16,0,0,1-16-16V48a16,16,0,0,1,16-16h40A16,16,0,0,1,216,48ZM96,32H56A16,16,0,0,0,40,48V208a16,16,0,0,0,16,16H96a16,16,0,0,0,16-16V48A16,16,0,0,0,96,32Z'
+const SPEAKER = 'M155.51,24.81a8,8,0,0,0-8.42.88L77.25,80H32A16,16,0,0,0,16,96v64a16,16,0,0,0,16,16H77.25l69.84,54.31A8,8,0,0,0,160,224V32A8,8,0,0,0,155.51,24.81ZM32,96H72v64H32ZM144,207.64,88,164.09V91.91l56-43.55Zm54-106.08a40,40,0,0,1,0,52.88,8,8,0,0,1-12-10.58,24,24,0,0,0,0-31.72,8,8,0,0,1,12-10.58ZM248,128a79.9,79.9,0,0,1-20.37,53.34,8,8,0,0,1-11.92-10.67,64,64,0,0,0,0-85.33,8,8,0,1,1,11.92-10.67A79.83,79.83,0,0,1,248,128Z'
+const SPEAKER_SLASH = 'M53.92,34.62A8,8,0,1,0,42.08,45.38L73.55,80H32A16,16,0,0,0,16,96v64a16,16,0,0,0,16,16H77.25l69.84,54.31A8,8,0,0,0,160,224V175.09l42.08,46.29a8,8,0,1,0,11.84-10.76ZM32,96H72v64H32ZM144,207.64,88,164.09V95.89l56,61.6Zm42-63.77a24,24,0,0,0,0-31.72,8,8,0,1,1,12-10.57,40,40,0,0,1,0,52.88,8,8,0,0,1-12-10.59Zm-80.16-76a8,8,0,0,1,1.4-11.23l39.85-31A8,8,0,0,1,160,32v74.83a8,8,0,0,1-16,0V48.36l-26.94,21A8,8,0,0,1,105.84,67.91ZM248,128a79.9,79.9,0,0,1-20.37,53.34,8,8,0,0,1-11.92-10.67,64,64,0,0,0,0-85.33,8,8,0,1,1,11.92-10.67A79.83,79.83,0,0,1,248,128Z'
+const CORNERS = 'M216,48V88a8,8,0,0,1-16,0V56H168a8,8,0,0,1,0-16h40A8,8,0,0,1,216,48ZM88,200H56V168a8,8,0,0,0-16,0v40a8,8,0,0,0,8,8H88a8,8,0,0,0,0-16Zm120-40a8,8,0,0,0-8,8v32H168a8,8,0,0,0,0,16h40a8,8,0,0,0,8-8V168A8,8,0,0,0,208,160ZM88,40H48a8,8,0,0,0-8,8V88a8,8,0,0,0,16,0V56H88a8,8,0,0,0,0-16Z'
+const PlayGlyph = ({ size = 30 }: { size?: number }) => <P d={PLAY} size={size} />
+const PauseGlyph = ({ size = 18 }: { size?: number }) => <P d={PAUSE} size={size} />
+
+export function Video({ src, poster, ratio, autoplay = false }: { src: string; poster?: string; ratio?: string; autoplay?: boolean }) {
+  ensureCss()
+  const play = useSlidePlay()
+  const interactive = useInteractive()
+  const [armed, setArmed] = useState(false)      // the poster was clicked in a live frame
+  // leaving interact mode disarms: the clip pauses (Player unmounts) and the frame returns to
+  // its poster, so the canvas can serialize it lean again
+  useEffect(() => { if (!interactive) setArmed(false) }, [interactive])
+  // poster omitted on a local clip: the generated one, by convention. `gen` walks
+  // probing -> ready (the file exists, or was just rendered - reloaded with a cache-buster)
+  // or failed (the card). The <img> mounts only once ready: no broken-image glyph while the
+  // dev server renders the poster, and a shot taken meanwhile waits on __mvPosterBusy.
+  const generated = !poster && !isRemote(src) ? posterNameFor(src) : null
+  const [gen, setGen] = useState<'probing' | 'ready' | 'failed'>(generated ? 'probing' : 'ready')
+  const [bust, setBust] = useState(0)
+  const posterUrl = poster ? resolve(poster) : generated ? resolve(generated) : null
+  const posterSrc = posterUrl && bust ? `${posterUrl}?v=${bust}` : posterUrl
+  const srcUrl = resolve(src)
+  const style = ratio ? ({ '--mv-video-ratio': ratio } as CSSProperties) : undefined
+  useEffect(() => {
+    if (!generated || !posterUrl) { setGen('ready'); return }
+    let alive = true, pending = true
+    setGen('probing'); setBust(0)
+    busy++
+    const done = () => { if (pending) { pending = false; busy-- } }
+    const probe = new Image()
+    const settle = (state: 'ready' | 'failed', rebust = false) => { done(); if (!alive) return; if (rebust) setBust(Date.now()); setGen(state) }
+    probe.onload = () => settle('ready')
+    probe.onerror = () => {
+      // not there yet: ask the dev server to render it (once per clip per document)
+      void requestPoster(src).then((ok) => settle(ok ? 'ready' : 'failed', ok))
+    }
+    probe.src = posterUrl
+    return () => { alive = false; probe.onload = probe.onerror = null; done() }
+  }, [generated, posterUrl, src])
+  const bad = !srcUrl || (!isRemote(src) && !posterUrl) || gen === 'failed'
+  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' : `no poster - add poster="…", or put ${generated} beside the clip (the dev server renders it when Chrome is installed)`}</span>
+      </div>
+    )
+  }
+  // Ambient: a muted loop, no chrome - the author accepted that this frame stays live.
+  if (autoplay) {
+    return (
+      <div className="mv-block mv-video" style={style}>
+        <video src={srcUrl!} poster={gen === 'ready' ? posterSrc ?? undefined : undefined} autoPlay muted loop playsInline preload="auto" />
+      </div>
+    )
+  }
+  // AT REST: the poster and nothing else - no <video>, no fetch, still. In a lean cover the
+  // click never fires (no script); in a live frame it arms the player inside the gesture.
+  if (!play && !armed) {
+    return (
+      <div className="mv-block mv-video armed" style={style} role="button" aria-label="Play video" onClick={() => setArmed(true)}>
+        {posterSrc && gen === 'ready' ? <img src={posterSrc} alt="" loading="lazy" /> : null}
+        <div className="glyph"><span><PlayGlyph /></span></div>
+      </div>
+    )
+  }
+  return <Player src={srcUrl!} poster={gen === 'ready' ? posterSrc ?? undefined : undefined} style={style} autoStart={armed} />
+}
+
+/** The glass strip - deliberately four controls and a clock, nothing more. */
+function Player({ src, poster, style, autoStart = false }: { src: string; poster?: string; style?: CSSProperties; autoStart?: boolean }) {
+  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() }, [])
+  // armed by a click on the poster: start now - still inside that gesture's activation
+  useEffect(() => { if (autoStart) { void ref.current?.play().catch(() => {}); poke() } }, [autoStart])
+  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" style={style} 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)}>
+          <P d={muted ? SPEAKER_SLASH : SPEAKER} size={18} />
+        </button>
+        <button aria-label="Fullscreen" onClick={(e) => void (e.currentTarget.closest('.mv-video') as HTMLElement | null)?.requestFullscreen?.()}>
+          <P d={CORNERS} size={18} />
+        </button>
+      </div>
+    </div>
+  )
+}

package/src/client/frame-host/bridge.js

@@ -69,7 +69,12 @@ window.addEventListener('message', (e) => {
   if (e.origin && e.origin !== location.origin) return   // a navigated frame must not spoof commands
   if (e?.data?.type === 'sh:set-theme') setTheme(e.data.theme)
   // B0.2: interact/play target owns its own wheel; passive frames forward it to the canvas
-  if (e?.data?.type === 'sh:interactive') { interactiveOn = !!e.data.on }
+  if (e?.data?.type === 'sh:interactive') {
+    interactiveOn = !!e.data.on
+    // mirrored on the document so content primitives can observe it (Video disarms its
+    // player when the human leaves interact mode - a playing clip must not outlive the mode)
+    document.documentElement.toggleAttribute('data-sh-interactive', interactiveOn)
+  }
 })
 
 if (isHtmlFrame) {

package/src/client/shell/App.tsx

@@ -1,13 +1,13 @@
 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, ImagesSquareIcon, 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 { avatarFallback, useComments } from './comments-store.ts'
@@ -323,6 +323,17 @@ function SelectionBar() {
     const t = setTimeout(() => setCopied(false), 1400)
     return () => clearTimeout(t)
   }, [pathPulse])
+  // copy-as-image: same flash contract (imagePulse bumps only on a real clipboard write),
+  // plus a busy state for the 1-4s headless render - the icon dims and the button locks
+  const imagePulse = useStore((s) => s.imagePulse)
+  const imageBusy = useStore((s) => s.imageBusy)
+  const [copiedImage, setCopiedImage] = useState(false)
+  useEffect(() => {
+    if (!imagePulse) return
+    setCopiedImage(true)
+    const t = setTimeout(() => setCopiedImage(false), 1400)
+    return () => clearTimeout(t)
+  }, [imagePulse])
   if (!node || !frame || node.missing) return null
   // anchor: centered over the bounding box of ALL selected frames, above the topmost
   const selNodes = nodes.filter((n) => selection.includes(n.key))
@@ -401,6 +412,17 @@ function SelectionBar() {
               () => toast('copy blocked - click the canvas first'))
           }}>{copied ? <CheckIcon size={15} /> : <SignpostIcon size={15} />}</button>
       </Tip>
+      {/* copy as image: dev only (the renderer is the dev server's headless Chrome) and one
+          frame at a time (a clipboard holds one image). I = 2x, Shift+I = 4x. */}
+      {!PUBLISHED && (
+        <Tip label={multi ? 'Select one frame to copy as image' : <><b>Copy as image</b><span className="k">⇧i</span></>}>
+          <button className={`icon${imageBusy ? ' busy' : ''}`} disabled={multi || imageBusy} aria-label="Copy as image"
+            data-state={copiedImage ? 'copied' : imageBusy ? 'busy' : 'idle'}
+            onClick={(e) => useStore.getState().copyFrameImage(e.shiftKey ? 4 : 2)}>
+            {copiedImage ? <CheckIcon size={15} /> : <ImagesSquareIcon size={15} />}
+          </button>
+        </Tip>
+      )}
     </div>
   )
 }
@@ -553,6 +575,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 +599,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 +608,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 +651,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)
@@ -822,7 +857,11 @@ export function App() {
   // keyboard: t tidy · d theme · ⌘\ panel · Escape exit · shift+0/1/2 zoom
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
-      if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) return
+      // anything that edits text owns its keys: inputs, textareas, selects, contenteditable (the
+      // comment composer), and an IME mid-composition
+      if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement || e.target instanceof HTMLSelectElement) return
+      if (e.target instanceof HTMLElement && e.target.isContentEditable) return
+      if (e.isComposing) return
       const s = useStore.getState()
       if (s.play) return                       // play mode owns the keyboard (Play.tsx)
       if ((e.metaKey || e.ctrlKey) && e.key === '\\') { e.preventDefault(); togglePanel(); return }
@@ -835,7 +874,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 }
@@ -863,6 +904,8 @@ export function App() {
         c.setShowAnchor(!c.showAnchor)
         toast(c.showAnchor ? 'laser comment off' : 'laser comment on')
       }
+      // I = copy the selected frame as a 2x PNG · Shift+I = 4x (dev only; one frame at a time)
+      if ((e.key === 'i' || e.key === 'I') && !PUBLISHED && !e.altKey && !e.repeat) { s.copyFrameImage(e.shiftKey ? 4 : 2); return }
       if (e.key === 'P' && e.shiftKey && s.selection.length) {
         const paths = s.selection
           .map((k) => { const n = s.nodes.find((x) => x.key === k); const f = n && s.frameFor(n); return f ? framePath(s.board, f) : undefined })
@@ -1067,11 +1110,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 +1150,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></>}>