@marver-design/marver 0.14.0 → 0.15.0

package/src/client/content/video.tsx

@@ -1,31 +1,85 @@
 /**
- * Video (v1.5) - poster-first, glass-controlled.
+ * 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 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.
+ * 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 (poster REQUIRED - it is the canvas
- * rendering) or a public https direct-file URL (mp4/webm; HLS where the
- * browser supports it natively).
+ * 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 } from 'react'
+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: 16 / 9 }
+.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: 4px }
+.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 }
@@ -46,42 +100,88 @@ const ensureCss = () => {
 
 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>
+// 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 }: { src: string; poster?: string }) {
+export function Video({ src, poster, ratio, autoplay = false }: { src: string; poster?: string; ratio?: string; autoplay?: boolean }) {
   ensureCss()
   const play = useSlidePlay()
-  const posterUrl = poster ? resolve(poster) : null
+  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 bad = !srcUrl || (!isRemote(src) && !posterUrl)
+  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' : 'a local video needs a poster - it IS the slide at rest'}</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.
-  if (!play) {
+  // 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">
-        {posterUrl ? <img src={posterUrl} alt="" loading="lazy" /> : null}
+      <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={posterUrl ?? undefined} />
+  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 }: { src: string; poster?: string }) {
+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)
@@ -95,9 +195,11 @@ function Player({ src, poster }: { src: string; poster?: string }) {
     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" onPointerMove={poke} onClick={(e) => { if (e.target === ref.current) toggle() }}>
+    <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)}
@@ -110,15 +212,10 @@ function Player({ src, poster }: { src: string; poster?: string }) {
           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>
+          <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?.()}>
-          <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>
+          <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

@@ -7,7 +7,7 @@ import { animateLayout, Canvas, canvasCtl } from './canvas/Canvas.tsx'
 import { frameByWindow } from './canvas/frame-registry.ts'
 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, SlideFrameIcon, 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>
   )
 }
@@ -835,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 }
@@ -878,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 })

package/src/client/shell/icons.tsx

@@ -38,6 +38,7 @@ export const DeviceTabletIcon = icon(<path d="M192,24H64A24,24,0,0,0,40,48V208a2
 export const LaptopIcon = icon(<path d="M232,168h-8V72a24,24,0,0,0-24-24H56A24,24,0,0,0,32,72v96H24a8,8,0,0,0-8,8v16a24,24,0,0,0,24,24H216a24,24,0,0,0,24-24V176A8,8,0,0,0,232,168ZM48,72a8,8,0,0,1,8-8H200a8,8,0,0,1,8,8v96H48ZM224,192a8,8,0,0,1-8,8H40a8,8,0,0,1-8-8v-8H224ZM152,88a8,8,0,0,1-8,8H112a8,8,0,0,1,0-16h32A8,8,0,0,1,152,88Z" />)
 export const MonitorIcon = icon(<path d="M208,40H48A24,24,0,0,0,24,64V176a24,24,0,0,0,24,24H208a24,24,0,0,0,24-24V64A24,24,0,0,0,208,40Zm8,136a8,8,0,0,1-8,8H48a8,8,0,0,1-8-8V64a8,8,0,0,1,8-8H208a8,8,0,0,1,8,8Zm-48,48a8,8,0,0,1-8,8H96a8,8,0,0,1,0-16h64A8,8,0,0,1,168,224Z" />)
 export const TvIcon = icon(<path d="M216,64H147.31l34.35-34.34a8,8,0,1,0-11.32-11.32L128,60.69,85.66,18.34A8,8,0,0,0,74.34,29.66L108.69,64H40A16,16,0,0,0,24,80V200a16,16,0,0,0,16,16H216a16,16,0,0,0,16-16V80A16,16,0,0,0,216,64Zm0,136H40V80H216V200Z" />)
+export const ImagesSquareIcon = icon(<path d="M208,32H80A16,16,0,0,0,64,48V64H48A16,16,0,0,0,32,80V208a16,16,0,0,0,16,16H176a16,16,0,0,0,16-16V192h16a16,16,0,0,0,16-16V48A16,16,0,0,0,208,32ZM80,48H208v69.38l-16.7-16.7a16,16,0,0,0-22.62,0L93.37,176H80Zm96,160H48V80H64v96a16,16,0,0,0,16,16h96Zm32-32H116l64-64,28,28v36Zm-88-64A24,24,0,1,0,96,88,24,24,0,0,0,120,112Zm0-32a8,8,0,1,1-8,8A8,8,0,0,1,120,80Z" />)
 export const SignpostIcon = icon(<path d="M246,106.65,212.33,69.3A16,16,0,0,0,200.44,64H136V32a8,8,0,0,0-16,0V64H40A16,16,0,0,0,24,80v64a16,16,0,0,0,16,16h80v64a8,8,0,0,0,16,0V160h64.44a16,16,0,0,0,11.89-5.3L246,117.35A8,8,0,0,0,246,106.65ZM200.44,144H40V80H200.44l28.8,32Z" />)
 export const ParallelogramDuoIcon = icon(<><path d="M239.29,59.28l-64.8,144a8,8,0,0,1-7.3,4.72H24a8,8,0,0,1-7.3-11.28l64.8-144A8,8,0,0,1,88.81,48H232A8,8,0,0,1,239.29,59.28Z" opacity=".1" /><path d="M245.43,47.31A15.94,15.94,0,0,0,232,40H88.81a16,16,0,0,0-14.59,9.43l-64.8,144A16,16,0,0,0,24,216H167.19a16,16,0,0,0,14.59-9.43l64.8-144A16,16,0,0,0,245.43,47.31ZM167.19,200H24L88.81,56H232Z" /></>)
 /** The marver mark, SOLID fill (for the Marver avatar - a filled white parallelogram on accent). */

package/src/client/shell/store.ts

@@ -251,6 +251,8 @@ interface State {
   playUpdateRevision: string | null                        // a revision arrived while play is open
   playNav: number                                          // bumps to reload the play stage on demand
   pathPulse: number                                        // bumps on each successful path copy - flashes the toolbar icon into a check
+  imagePulse: number                                       // bumps on each successful image copy - same flash, the images-square icon
+  imageBusy: boolean                                       // a copy-as-image render is in flight (one at a time)
 
   boot(): Promise<boolean>
   applyManifest(m: Manifest): void
@@ -280,6 +282,7 @@ interface State {
   renameBoard(from: string, to: string): Promise<{ ok: boolean; error?: string }>
   reorderBoards(order: string[]): Promise<boolean>
   pulsePath(): void
+  copyFrameImage(scale: 2 | 4): void
   setScale(s: number): void
   togglePanel(): void
   setTheme(theme: string): void
@@ -564,7 +567,7 @@ export const useStore = create<State>((set, get) => {
     manifest: null, nodes: [], selection: [], interact: null, viewTheme: initialViewTheme(), play: null, gesture: false, laser: false,
     board: DATA?.default ?? 'all-scenes', boardAuto: (DATA?.default ?? 'all-scenes') === 'all-scenes', deviceView: null, sceneRows: null, layout: null, layoutRaw: undefined, baseLayout: null,
     panelOpen: true, scale: 1, toasts: [], working: [], workingSince: {}, boardHash: null, dirty: false,
-    pendingFrameRevisions: {}, externalLeases: {}, playUpdateRevision: null, playNav: 0, pathPulse: 0,
+    pendingFrameRevisions: {}, externalLeases: {}, playUpdateRevision: null, playNav: 0, pathPulse: 0, imagePulse: 0, imageBusy: false,
 
     async boot() {
       const seq = ++loadSeq
@@ -1017,6 +1020,53 @@ export const useStore = create<State>((set, get) => {
     },
     setScale(scale) { set({ scale }) },
     pulsePath() { set((s) => ({ pathPulse: s.pathPulse + 1 })) },
+    // Copy the ONE selected frame to the clipboard as a PNG - the dev server's headless
+    // renderer (/api/shot, the same picture `marver shot` gives an agent) sized to what the
+    // node shows, at 2x (or 4x). The ClipboardItem takes a PROMISE: clipboard.write runs
+    // inside the click/keydown gesture and the browser waits for the bytes - a plain
+    // await-then-write would have lost the transient activation during the 1-4s render.
+    copyFrameImage(scale) {
+      const s = get()
+      if (PUBLISHED || s.imageBusy || s.selection.length !== 1) return
+      const node = s.nodes.find((n) => n.key === s.selection[0])
+      if (!node || node.missing) return
+      const frame = s.frameFor(node)
+      if (!frame) { s.toast('frame is still indexing - try again in a second'); return }
+      const CI = (globalThis as { ClipboardItem?: typeof ClipboardItem }).ClipboardItem
+      if (!CI || !navigator.clipboard?.write || (CI.supports && !CI.supports('image/png'))) { s.toast("this browser can't put images on the clipboard - use Chrome, Edge or Safari"); return }
+      set({ imageBusy: true })
+      const done = () => set({ imageBusy: false })
+      const qs = new URLSearchParams({ frame: frame.id, theme: node.theme, scale: String(scale), w: String(Math.round(node.w)), h: String(Math.round(node.h)), format: 'png' })
+      // the render is serialized server-side behind any CLI/jam shots; a minute is the ceiling
+      // before the UI gives up on this copy (the server's own watchdog is 45s per shot)
+      const ctl = new AbortController()
+      const timer = setTimeout(() => ctl.abort(), 60_000)
+      let meta: { scale?: number; note?: string } = {}
+      const png = fetch(`${ROUTE}/api/shot?${qs}`, { headers: { 'x-mv-c': csrf() }, signal: ctl.signal }).then(async (r) => {
+        if (!r.ok) throw new Error((await r.json().catch(() => ({}))).error ?? `shot failed (${r.status})`)
+        try { meta = JSON.parse(atob((r.headers.get('x-mv-shot') ?? '').replace(/-/g, '+').replace(/_/g, '/'))) } catch { /* summary is advisory */ }
+        return r.blob()
+      }).finally(() => clearTimeout(timer))
+      let renderErr = ''
+      png.catch((e: Error) => { renderErr = e.name === 'AbortError' ? 'timed out - the renderer is busy' : e.message })
+      const fail = (err: unknown) => {
+        done()
+        // a prompt clipboard refusal (no gesture, focus lost) must not wait a minute on the
+        // render: abandon the fetch, toast now. A render failure surfaces its own cause.
+        if (!renderErr) ctl.abort()
+        s.toast(renderErr ? `render failed - ${renderErr}` : (err as Error)?.name === 'NotAllowedError' ? 'copy blocked - click the canvas first' : `copy failed - ${(err as Error)?.message ?? err}`)
+      }
+      try {
+        navigator.clipboard.write([new CI({ 'image/png': png })]).then(
+          () => {
+            done()
+            const used = meta.scale ?? scale
+            s.toast(used < scale ? `image copied at ${used}x - frame too tall for ${scale}x` : scale === 4 ? 'image copied (4x)' : 'image copied')
+            set((st) => ({ imagePulse: st.imagePulse + 1 }))
+          },
+          fail)
+      } catch (err) { fail(err) }   // a synchronous constructor/type error must not wedge busy
+    },
     togglePanel() { set((s) => ({ panelOpen: !s.panelOpen })) },
     // global theme = the VIEW preference: persists across boards + reloads, clears
     // per-frame pins. Frames declaring meta.theme keep their mode (they only work there).

package/src/client/shell/styles.css

@@ -413,6 +413,12 @@ body.sh-commenting .sh-lean { opacity: 0 }
   justify-content: center; padding: 0 6px; margin: 0 2px 0 3px }
 .sh-ctx button.on { background: var(--glass-accent-bg); color: var(--glass-accent) }
 .sh-ctx button:hover:not(.on) { background: var(--glass-hover); color: var(--glass-ink) }
+/* multi-select / no-op states read as quiet, not broken */
+.sh-ctx button:disabled { cursor: default; opacity: .45 }
+.sh-ctx button:disabled:hover { background: none; color: var(--glass-ink-2) }
+/* copy-as-image while the headless render runs (1-4s): a slow breathe on the icon */
+.sh-ctx button.busy { opacity: 1; color: var(--glass-accent); animation: sh-ctx-breathe 1.1s ease-in-out infinite }
+@keyframes sh-ctx-breathe { 0%, 100% { opacity: .35 } 50% { opacity: 1 } }
 .sh-ctx .sep { width: 1px; height: 14px; background: var(--glass-brd); margin: 0 3px }
 
 /* error / missing cards (inside the frame body) */

package/templates/AGENTS-embedded.md

@@ -19,7 +19,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
 | Wireframe | new work: nail structure + copy in throwaway lo-fi | instructions/wireframe.md |
 | Brand | before the first hi-fi work: extract or create the world | instructions/brand.md |
 | Build | hi-fi frames from real components | instructions/craft.md + components.md |
-| Iterate | changing a frame the human has seen, or retiring explorations | instructions/iterate.md |
+| Iterate | changing a frame the human has seen, a round of feedback on a scene, or retiring explorations | instructions/iterate.md |
 | Review | before presenting anything | instructions/review.md |
 | Boards | creating a board, choosing what ships | instructions/boards.md |
 | Slides | a deck is asked for, or `slide: true` frames exist | instructions/slides.md + design/slides.md |
@@ -58,6 +58,13 @@ Two channels carry element-precise feedback - honor both:
   thread carries the anchored element (tag, quoted text, css path, frame). Work that queue
   per instructions/iterate.md; the comment names the div, so read the anchor before the words.
 
+Either way, **a pointer names where the human noticed it, not the only place it is.** Before
+you answer, look sideways: every other LIVE frame on that board that shares the component,
+the pattern, the copy or the state (never `archive/` or a `<scene>-v<N>` version - history is
+not a sibling). Same defect there? Fix it in the same pass and say which frames you touched.
+A judgment call? Do the pinned one, then ask in the thread or the reply whether to roll it
+across the others - never silently fix one and leave its siblings wrong.
+
 ## Show the work (working state)
 
 The canvas can wear your effort live. When a request will create or change frames, making
@@ -148,9 +155,17 @@ A board is a saved canvas: `design/boards/<name>.json` - you create and manage t
 by writing files; `all-scenes` is auto-managed, never write it. Compose a board
 deliberately with `"layout"`: rows/columns lanes of scenes plus `{ "space": n }`
 whitespace tokens, and the same grammar per scene for frames (columns align left
-edges; a variant-group name is one indivisible atom). BEFORE creating a board or
-publishing anything, read instructions/boards.md (the layout grammar, file format,
-publishing rules).
+edges; a variant-group name is one indivisible atom). **The default composition is
+ONE horizontal band**: scenes side by side, frames flowing left to right; a second
+band only when you can say why the eye should move down, and then with generous
+vertical space. Without a recipe the shell stacks every scene as its own row - so
+every curated board carries one. BEFORE creating a board or publishing anything,
+read instructions/boards.md (the layout grammar, file format, publishing rules).
+
+A round of feedback on a scene the human has already reviewed starts with a
+**version snapshot** (`design/scenes/<scene>-v<N>/` on the `archive` board) BEFORE
+the first edit - the human iterates fast knowing every version is one board away.
+instructions/iterate.md has the mechanics.
 
 ## Upstream feedback (when marver itself misbehaves)
 

package/templates/AGENTS-studio.md

@@ -19,7 +19,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
 | Wireframe | new work: nail structure + copy in throwaway lo-fi | instructions/wireframe.md |
 | Brand | before the first hi-fi work: extract or create the world | instructions/brand.md |
 | Build | hi-fi frames from real components | instructions/craft.md + components.md |
-| Iterate | changing a frame the human has seen, or retiring explorations | instructions/iterate.md |
+| Iterate | changing a frame the human has seen, a round of feedback on a scene, or retiring explorations | instructions/iterate.md |
 | Review | before presenting anything | instructions/review.md |
 | Boards | creating a board, choosing what ships | instructions/boards.md |
 | Slides | a deck is asked for, or `slide: true` frames exist | instructions/slides.md + design/slides.md |
@@ -58,6 +58,13 @@ Two channels carry element-precise feedback - honor both:
   thread carries the anchored element (tag, quoted text, css path, frame). Work that queue
   per instructions/iterate.md; the comment names the div, so read the anchor before the words.
 
+Either way, **a pointer names where the human noticed it, not the only place it is.** Before
+you answer, look sideways: every other LIVE frame on that board that shares the component,
+the pattern, the copy or the state (never `archive/` or a `<scene>-v<N>` version - history is
+not a sibling). Same defect there? Fix it in the same pass and say which frames you touched.
+A judgment call? Do the pinned one, then ask in the thread or the reply whether to roll it
+across the others - never silently fix one and leave its siblings wrong.
+
 ## Show the work (working state)
 
 The canvas can wear your effort live. When a request will create or change frames, making
@@ -148,9 +155,17 @@ A board is a saved canvas: `design/boards/<name>.json` - you create and manage t
 by writing files; `all-scenes` is auto-managed, never write it. Compose a board
 deliberately with `"layout"`: rows/columns lanes of scenes plus `{ "space": n }`
 whitespace tokens, and the same grammar per scene for frames (columns align left
-edges; a variant-group name is one indivisible atom). BEFORE creating a board or
-publishing anything, read instructions/boards.md (the layout grammar, file format,
-publishing rules).
+edges; a variant-group name is one indivisible atom). **The default composition is
+ONE horizontal band**: scenes side by side, frames flowing left to right; a second
+band only when you can say why the eye should move down, and then with generous
+vertical space. Without a recipe the shell stacks every scene as its own row - so
+every curated board carries one. BEFORE creating a board or publishing anything,
+read instructions/boards.md (the layout grammar, file format, publishing rules).
+
+A round of feedback on a scene the human has already reviewed starts with a
+**version snapshot** (`design/scenes/<scene>-v<N>/` on the `archive` board) BEFORE
+the first edit - the human iterates fast knowing every version is one board away.
+instructions/iterate.md has the mechanics.
 
 ## Upstream feedback (when marver itself misbehaves)
 

package/templates/instructions/boards.md

@@ -29,16 +29,58 @@ viewport and lays it out:
   EVERY frame, so it is the heavy one) and always sinks to the BOTTOM of the switcher -
   never the landing board, and never write its file.
 - Do not edit board files while the canvas is open unless asked; the shell owns
-  their layout fields.
+  their layout fields (`x`/`y`/`w`/`h`, node keys). What is always yours, canvas
+  open or not: creating a board, appending nodes, and writing the `layout` recipe
+  of a board you curate (the `archive` board above all).
 - Use boards for comparisons: version A vs B vs C of a flow, side by side. Variant
   groups (letter-prefixed siblings) stay contiguous through every relayout
   automatically.
 - Content frames (specs, diagrams, mood boards - instructions/shape.md) are ordinary
   atoms in every layout scope: a feature-story board mixes them freely with UI frames.
-- The `archive` board (instructions/iterate.md) is the one board of retired
-  explorations: curated over design/scenes/archive/, tidied with a recipe,
-  every frame relabeled with what it was and why it retired. Winners live on
-  the feature boards; the archive answers "what did we try?".
+- The `archive` board (instructions/iterate.md) is the one board of history:
+  retired explorations (design/scenes/archive/, every frame relabeled with what
+  it was and why it retired) and **scene versions** (`<scene>-v1`, `<scene>-v2`
+  … - the whole flow as it stood before each round of feedback), one band per
+  version, oldest at the top. Winners live on the feature boards; the archive
+  answers "what did we try?" and "what did it look like before?".
+
+## The default composition: one horizontal band
+
+A board reads like a page: left to right first, down only for a reason. The
+default for every curated board is **one `rows` lane holding the scenes side by
+side, in reading order, each scene's frames flowing left to right** - the whole
+story on one horizontal band the human pans along. Without a recipe the shell
+stacks every scene as its own row (a vertical pile of unrelated bands), so a board
+without a `layout` is a board you have not composed yet.
+
+```json
+"layout": { "rows": [["onboarding", "checkout", "account"]] }
+```
+
+A **second band** is a decision, not a reflex. Open one when you can say in a
+sentence why the eye should move down - a different chapter of the story (the
+specs that argue for the flow above), a different audience (admin vs customer),
+an archive or a version history, a scene so wide that beside the others it would
+not be read. Then make the break unmistakable: the gap between bands must read as
+"below", never as "next". Units are adaptive (proportional to the touching
+frames), so judge the RENDERED gap: between rows of phone or laptop frames that
+is `{ "space": 4 }`; after a band of tall spec frames `{ "space": 2 }`-`3` already
+reads as a chapter break. Inside a band, `{ "space": 2 }`-`{ "space": 3 }`
+separates clusters (a variant run, a scene that ends one thought and starts
+another); plain adjacency joins.
+
+Two boards are multi-band BY DESIGN and set their own gaps: the feature-story
+board (instructions/shape.md - thinking, structure, answer, three bands) and the
+`archive` board (instructions/iterate.md - one band per version). Everything else
+starts as one band.
+
+```json
+"layout": { "rows": [["onboarding", "checkout", "account"], { "space": 4 }, ["checkout-specs"]] }
+```
+
+`columns` are for the rarer case where things must share a left edge (versions of
+one flow stacked as a timeline, a parked archive under a hero) - never as a way to
+fit more on screen.
 
 ## Composing the canvas: `layout`
 

package/templates/instructions/craft.md

@@ -96,6 +96,23 @@ thing - changes everything. This section is binding, not aspiration:
 - **Imagery is real imagery.** When the design calls for photos or screenshots,
   fetch and commit them locally with names that say what they are - never
   hotlink (published canvases make zero external requests, and remote URLs rot).
+- **Charts are real charts.** A dashboard, a report, an analytics screen gets
+  `Chart` from `@marver-design/marver/content` - Apache ECharts behind a house
+  theme that inherits the SCREEN's ink, typeface and accent (light and dark),
+  renders SVG, sits still at rest and follows the layout on resize. Importing it
+  does not make the screen a content frame: it keeps its device, its height and
+  its place in the flow. Write the ECharts `option` with fixture data; never
+  set colors, fonts or animation in it. Never a static chart image, never
+  hand-drawn bars from divs when the real thing is one import away.
+- **Video is a real video.** A hero loop, an onboarding clip, a story in a
+  phone screen: `Video` from `@marver-design/marver/content` - poster-first
+  (still on the canvas, no media fetched at rest), click-to-play wherever the
+  frame is live, `ratio="9 / 16"` for vertical, `autoplay` for a muted ambient
+  loop (an explicit choice: that frame stays live on the canvas). The poster
+  is rendered from the clip when you omit it (`<clip>.poster.png` beside it in
+  `design/assets/`); author one when the opening frame is not the picture.
+  Never a gray "video" box, never
+  a static screenshot standing in for motion the design depends on.
 - **Licensing sanity, briefly:** brand marks from official sources shown to
   identify the brand are fine; photos come from sources that permit the use.
   Unsure about one? Use it, and flag it to the human in the same message.