@marver-design/marver 0.13.0 → 0.15.0

package/src/client/shell/store.ts

@@ -1,5 +1,5 @@
 import { create } from 'zustand'
-import { ROUTE } from '../const.ts'
+import { ROUTE, slideSize } from '../const.ts'
 import { tidy, parseLayout, type BoardLayout } from './tidy.ts'
 import { stableNodeKey } from './keys.ts'
 // @ts-expect-error virtual module provided by the plugin
@@ -30,9 +30,18 @@ export const PUBLISHED = DATA !== null
 export const SOURCE_REVEALED = DATA ? DATA.policy?.reveal?.source === true : true
 
 /** The published per-board artifact metadata (type, open, lock). Empty in dev. */
-export const BOARD_POLICY: Record<string, { type?: string; open?: string; lock?: boolean }> = DATA?.policy?.boards ?? {}
+export const BOARD_POLICY: Record<string, { type?: string; open?: string; lock?: boolean; transition?: string; chrome?: string }> = DATA?.policy?.boards ?? {}
 
-export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string; variantGroup?: string; variant?: string; intent?: string; contentWidth?: number }
+export { SLIDE_INTRINSIC } from '../const.ts'
+
+/** Dev-only hydration: the shell loads the repo's publish.json boards so an
+ *  author previews slides mode exactly as viewers will get it. Published
+ *  builds carry the policy inline and never call this. */
+export function hydrateBoardPolicy(boards: Record<string, { type?: string; open?: string; lock?: boolean; transition?: string; chrome?: string }>) {
+  for (const [k, v] of Object.entries(boards)) if (!BOARD_POLICY[k]) BOARD_POLICY[k] = v
+}
+
+export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string; variantGroup?: string; variant?: string; intent?: string; contentWidth?: number; slide?: boolean }
 export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number }[] }
 export interface Node {
   key: string; frame: string; x: number; y: number; w: number; h: number
@@ -83,17 +92,24 @@ export function landingMode(board: string): 'canvas' | 'board' | 'present' | 'fo
   const p = BOARD_POLICY[board]
   if (!p) return 'canvas'
   if (p.open && ['canvas', 'board', 'present', 'focus', 'slides'].includes(p.open)) {
-    // slides is v1.5 - until the mode exists it lands in present, its nearest kin
-    return p.open === 'slides' ? 'present' : p.open as any
+    return p.open as any
   }
   switch (p.type) {
     case 'doc': return 'focus'
-    case 'slides': return 'present'          // slides mode is v1.5; present until then
+    case 'slides': return 'slides'
     case 'design': case 'sketch': case 'refs': return 'board'
     default: return 'canvas'
   }
 }
 
+/** Does this board PLAY as a deck? A `type: slides` board is a deck whatever
+ *  its landing (`open: canvas` only says where viewers arrive) - the P key and
+ *  the play button route here, never through landingMode. */
+export function playsAsSlides(board: string): boolean {
+  const p = BOARD_POLICY[board]
+  return p?.type === 'slides' || p?.open === 'slides'
+}
+
 /** Is this board frozen to its landing mode? The lock caps disclosure - no way
  *  out into other modes, and (published) no sidebar ever renders for it. */
 export const boardLocked = (board: string): boolean => BOARD_POLICY[board]?.lock === true
@@ -101,7 +117,7 @@ export const boardLocked = (board: string): boolean => BOARD_POLICY[board]?.lock
 /** May this board enter `mode`? A lock freezes what open pinned - a board
  *  locked to canvas must refuse present just as one locked to present refuses
  *  canvas. Unlocked boards enter anything. */
-export const modeAllowed = (board: string, mode: 'present' | 'focus'): boolean =>
+export const modeAllowed = (board: string, mode: 'present' | 'focus' | 'slides'): boolean =>
   !boardLocked(board) || landingMode(board) === mode
 
 export { cap, humanize } from './labels.ts'
@@ -173,6 +189,11 @@ const manifestKey = (m: Manifest) => JSON.stringify(m.frames)   // any change co
 const measuredHeights = new Map<string, number>()
 
 function defaultSize(frame: FrameEntry) {
+  // the precedence chain (spec 09 slice 1): slide intrinsic → authored
+  // viewport → content sizing → default (one helper, shared with shot) -
+  // the Slide root renders fixed 1280×720, so nothing may size it smaller
+  const sl = slideSize(frame)
+  if (sl) return { w: sl.width, h: sl.height }
   // content frames: own width from Doc layout; height from the latest
   // measurement at that width, or a placeholder until sh:measure lands.
   // meta.viewport, when declared, wins - the existing precedence.
@@ -206,7 +227,7 @@ interface State {
    *  fourth mode): no walking, doc reading preset when the board type is doc.
    *  `deep` = entered by a frame deep link - the chrome then carries no board
    *  name and no canvas door (presentation default of the link, 04 §2.35). */
-  play: { at: string; device: string; theme: string; focus?: boolean; deep?: boolean } | null
+  play: { at: string; device: string; theme: string; focus?: boolean; deep?: boolean; slides?: boolean } | null
   gesture: boolean                    // a frame drag/resize is in progress - canvas panning is disabled
   laser: boolean                      // laser/inspect mode: frames outline their structure
   board: string                       // active board name; 'all-scenes' is the auto board
@@ -230,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
@@ -259,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
@@ -543,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
@@ -996,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) */
@@ -736,22 +742,6 @@ body.sh-commenting .sh-lean { opacity: 0 }
 .sh-play-chip:hover { color: #f5f5f7 }
 .sh-play-chip.idle { opacity: 0; pointer-events: none; transform: scale(.6) }
 
-/* the H coach bubble: hairline, translucent, teaches the way back from immersive mode.
-   Same pill geometry and separators as the bar it stands in for. */
-.sh-play-hint { position: absolute; top: 14px; right: 16px; display: flex; align-items: center; gap: 3px;
-  padding: 4px 4px 4px 14px; border-radius: 999px;
-  background: rgba(18, 18, 24, .6); border: 1px solid rgba(255, 255, 255, .14);
-  backdrop-filter: blur(16px); -webkit-backdrop-filter: blur(16px);
-  font: 500 12px -apple-system, system-ui, sans-serif; color: rgba(245, 245, 247, .85);
-  animation: sh-play-in .3s ease-out }
-.sh-play-hint .sep { width: 1px; height: 16px; background: rgba(255, 255, 255, .14); margin: 0 8px }
-.sh-play-hint kbd { font: 600 11px -apple-system, system-ui, sans-serif; padding: 1px 6px; border-radius: 5px;
-  background: rgba(255, 255, 255, .12); border: 1px solid rgba(255, 255, 255, .16) }
-.sh-play-hint button { height: 30px; padding: 0 12px; border: 0; border-radius: 999px; cursor: pointer;
-  font: 600 11px -apple-system, system-ui, sans-serif; background: rgba(255, 255, 255, .14); color: #f5f5f7 }
-.sh-play-hint button:hover { background: rgba(255, 255, 255, .22) }
-.sh-play-hint button.dim { background: transparent; color: rgba(245, 245, 247, .5); font-weight: 500 }
-.sh-play-hint button.dim:hover { color: rgba(245, 245, 247, .8); background: rgba(255, 255, 255, .08) }
 
 /* ---- Focus: silent for pointer + shortcut use; ONE branded inset ring, and only while
    the user is actually Tab-navigating (body.sh-kbd, armed by Tab, disarmed by pointer).
@@ -861,22 +851,19 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
 
 /* ---- present/focus chrome (sharing v1): brand pill top-left, counter in the
    toolbar, doc reading preset. Same glass skin as the play pill. */
-.sh-play-brand.sh-pill { left: var(--edge); right: auto; transform-origin: 22px 22px; padding: 5px 14px 5px 10px }
-.sh-play-mark { display: inline-flex; align-items: center; gap: 7px; padding: 0 2px 0 6px; color: rgba(245, 245, 247, .88) }
+/* the brand pill matches the toolbar pill to the pixel: the SAME .sh-pill
+   padding (5px) and the SAME 34px inner height as .sh-pill-btn - its two
+   children are sized like buttons, so text metrics never set the height */
+.sh-play-brand.sh-pill { left: var(--edge); right: auto; transform-origin: 22px 22px; padding: 5px 9px 5px 5px }
+.sh-play-mark { display: inline-flex; align-items: center; gap: 7px; height: 34px; padding: 0 8px 0 10px; border-radius: 999px;
+  color: rgba(245, 245, 247, .88); text-decoration: none; cursor: pointer }
+.sh-play-mark:hover { background: rgba(255, 255, 255, .1); color: #f5f5f7 }
 .sh-play-mark svg { color: #6db3ff }
 .sh-play-mark .wd { font: 600 13px -apple-system, system-ui, sans-serif; letter-spacing: -.01em }
-.sh-play-title { font: 500 13px -apple-system, system-ui, sans-serif; color: rgba(245, 245, 247, .82);
+.sh-play-title { display: inline-block; height: 34px; line-height: 34px; font: 500 13px/34px -apple-system, system-ui, sans-serif; color: rgba(245, 245, 247, .82);
   max-width: 143px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; padding: 0 6px }
 .sh-play-pos { font: 500 12.5px -apple-system, system-ui, sans-serif; color: rgba(245, 245, 247, .64);
   font-variant-numeric: tabular-nums; padding: 0 8px; white-space: nowrap }
-/* the hint pill: bottom center, the design's quiet keyboard cue */
-.sh-play-hint { position: absolute; bottom: 12px; left: 50%; transform: translateX(-50%); z-index: 31;
-  border-radius: 999px; padding: 7px 16px; white-space: nowrap;
-  background: rgba(18, 18, 24, .8); border: 1px solid rgba(255, 255, 255, .1);
-  backdrop-filter: blur(16px); -webkit-backdrop-filter: blur(16px);
-  font: 500 12px -apple-system, system-ui, sans-serif; color: rgba(245, 245, 247, .64) }
-.sh-play-hint kbd { font: 500 11.5px ui-monospace, monospace }
-body.sh-hide-ui .sh-play-hint { display: none !important }
 /* doc preset: the page IS the surface - reading column on a calm ground, no
    device shell, natural document scrolling inside the frame */
 .sh-play.doc { background: #f4f4f6 }
@@ -1249,3 +1236,12 @@ body.sh-hide-ui .sh-play-hint { display: none !important }
   color: rgba(255,255,255,.92); font: 700 13px/1 -apple-system, system-ui, sans-serif; letter-spacing: .02em }
 /* the title row is flex, which swallows the JSX whitespace - the verb carries its own gap */
 .sh-jam-frame .v { color: var(--glass-ink-2); font-weight: 500; margin-left: 4px; flex: none }
+
+/* v1.5 slides mode: the slim progress strip + the zero-chrome escape hatch */
+.sh-slides-strip { position: fixed; left: 50%; bottom: 14px; transform: translateX(-50%); z-index: 30;
+  display: flex; align-items: center; gap: 10px; padding: 8px 14px; border-radius: 999px;
+  background: var(--glass); border: 1px solid var(--glass-brd); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur) }
+.sh-slides-strip .n { font: 600 12px/1 -apple-system, system-ui, sans-serif; color: var(--glass-ink-2); white-space: nowrap }
+.sh-slides-strip .bar { width: 140px; height: 3px; border-radius: 999px; background: var(--glass-hover); overflow: hidden }
+.sh-slides-strip .bar i { display: block; height: 100%; border-radius: inherit; background: var(--accent); transition: width .25s ease }
+@media (max-width: 480px) { .sh-slides-strip .bar { width: 80px } }

package/src/client/stage/main.tsx

@@ -21,6 +21,14 @@ const params = new URLSearchParams(location.search)
 // token systems, .dark for class-keyed ones (Tailwind/shadcn). Missing the class made
 // play render class-keyed apps light while the canvas showed them dark.
 const bootTheme = params.get('theme') ?? 'light'
+// slides mode (v1.5): the shell says so in the URL; the stage stamps the ONE
+// attribute the content primitives observe (data-sl-play lifts the rest-state
+// motion reset; data-sl-entered arms the entrance presets after each swap
+// settles). `tr=none` and prefers-reduced-motion both skip view transitions.
+const slidesMode = params.get('slides') === '1'
+const deckTransition = params.get('tr') ?? 'fade'
+if (slidesMode) document.documentElement.setAttribute('data-sl-play', '')
+const reducedMotion = typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches
 document.documentElement.dataset.theme = bootTheme
 document.documentElement.classList.toggle('dark', bootTheme === 'dark')
 const startId = params.get('at') ?? ''
@@ -95,9 +103,41 @@ function Stage() {
       // inspect.getId() never reports the new frame while the old DOM is still live -
       // a pick / anchor-resolve landing mid-swap then carries the old id and the shell
       // guards drop it instead of stamping it onto the wrong frame.
-      const apply = () => { if (seq === swapSeq.current) { flushSync(() => { setErr(null); setMounted(next) }); current.current = id } }
-      if (document.startViewTransition) document.startViewTransition(apply)
-      else { apply(); document.getElementById('root')?.animate([{ opacity: 0.35 }, { opacity: 1 }], { duration: 180, easing: 'ease-out' }) }
+      // slides: the entrance presets re-arm per swap. The disarm (drop `entered`,
+      // strip data-animate from morph-owned elements) runs INSIDE the transition's
+      // update callback - after the new DOM commits, before the NEW-state capture.
+      // Disarming before startViewTransition would capture the OUTGOING slide with
+      // its [data-animate] elements at opacity 0 (they'd vanish from the old
+      // snapshot), and a morphed element still carrying data-animate would be
+      // captured transparent and pop in after the morph.
+      const disarm = () => {
+        if (!slidesMode) return
+        document.documentElement.removeAttribute('data-sl-entered')
+        // one transform owner: an element that morphs must not also run an
+        // entrance preset - CSS cannot see a computed view-transition-name,
+        // so the stage strips data-animate from morph-owned elements here
+        for (const el of document.querySelectorAll('[data-animate]'))
+          if (getComputedStyle(el).viewTransitionName !== 'none') el.removeAttribute('data-animate')
+      }
+      const apply = () => { if (seq === swapSeq.current) { flushSync(() => { setErr(null); setMounted(next) }); current.current = id; disarm() } }
+      const entered = () => {
+        if (!slidesMode || seq !== swapSeq.current) return
+        document.documentElement.setAttribute('data-sl-entered', '')
+      }
+      const skipVt = reducedMotion || (slidesMode && deckTransition === 'none')
+      if (document.startViewTransition && !skipVt) {
+        const vt = document.startViewTransition(apply)
+        vt.finished.then(entered, entered)
+      } else if (skipVt) { apply(); entered() }
+      else {
+        // no view transitions here: a plain crossfade at the deck's tempo, so
+        // the one-tempo contract holds even where morphs cannot
+        apply(); entered()
+        const raw = getComputedStyle(document.documentElement).getPropertyValue('--marver-slide-tempo').trim()
+        const m = /^(\d*\.?\d+)\s*(ms|s)?$/i.exec(raw)
+        const tempo = m ? parseFloat(m[1]) * (m[2]?.toLowerCase() === 's' ? 1000 : 1) : 350   // a CSS <time>: 350ms or .35s; 0 is honoured
+        if (tempo > 0) document.getElementById('root')?.animate([{ opacity: 0.35 }, { opacity: 1 }], { duration: tempo, easing: 'ease-out' })
+      }
       if (announce) post({ type: 'sh:stage-at', at: id })
     } catch (e) {
       if (seq !== swapSeq.current) return
@@ -129,6 +169,12 @@ function Stage() {
     // laser/comment click owns the press instead - it must not navigate.
     const onClick = (e: MouseEvent) => {
       if (inspect.modeActive()) return
+      // slides: a background click advances (posted as the Space key) - never
+      // on anything interactive, and data-goto (below) always wins
+      if (slidesMode && e.target instanceof Element
+        && !e.target.closest('a, button, input, textarea, select, video, .mv-video, [contenteditable], [data-goto]')) {
+        post({ type: 'sh:stage-key', key: ' ', code: 'Space' })
+      }
       const el = e.target instanceof Element ? e.target.closest('[data-goto]') : null
       if (!el) return
       e.preventDefault()
@@ -149,6 +195,11 @@ function Stage() {
       // l/c toggle laser/comment, C (shift+c) hides pins; the shell acts and broadcasts back.
       if (/^Digit[0-9]$/.test(e.code) || ['d', 'h', 'r', 'l', 'c', 'C', '[', ']', 'ArrowRight', 'ArrowLeft'].includes(e.key))
         post({ type: 'sh:stage-key', key: e.key, code: e.code })
+      // slides: Space advances - but never stolen from anything interactive
+      if (slidesMode && e.key === ' ' && !(e.target instanceof Element && e.target.closest('button, input, textarea, select, video, .mv-video, a, [contenteditable]'))) {
+        e.preventDefault()
+        post({ type: 'sh:stage-key', key: ' ', code: e.code })
+      }
     }
     window.addEventListener('keydown', onKey)
 

package/src/shared/utm.ts

@@ -4,12 +4,13 @@
  *    utm_source   = the surface class ('published-canvas' | 'dev-canvas')
  *    utm_medium   = the link unit ('powered-by')
  *    utm_campaign = THIS canvas's name, slugged ("Marver tour" -> "marver-tour")
- *    utm_content  = the placement ('gate' badge | 'shell' wordmark | 'sign-in' finish page)
+ *    utm_content  = the placement ('gate' badge | 'shell' wordmark | 'sign-in' finish page |
+ *                   'play-brand' the present/slides brand pill)
  */
 export function poweredByUrl(
   canvasName: string | undefined,
   source: 'published-canvas' | 'dev-canvas',
-  content: 'gate' | 'shell' | 'sign-in',
+  content: 'gate' | 'shell' | 'sign-in' | 'play-brand',
 ): string {
   const slug = (canvasName ?? '').toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
   const q = new URLSearchParams({

package/templates/AGENTS-embedded.md

@@ -19,9 +19,10 @@ 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 |
 | Publish | deploying the canvas: gate, volume, accounts, invites | instructions/publish.md |
 | Live Jam | responding to an `@marver` comment (a spawned job); on by default - confirm it names YOUR tool | instructions/jam.md |
 
@@ -57,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
@@ -147,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,9 +19,10 @@ 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 |
 | Publish | deploying the canvas: gate, volume, accounts, invites | instructions/publish.md |
 | Live Jam | responding to an `@marver` comment (a spawned job); on by default - confirm it names YOUR tool | instructions/jam.md |
 
@@ -57,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
@@ -147,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.