@marver-design/marver 0.19.1 → 0.20.0

package/src/client/content/slide.tsx

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

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

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

package/src/client/shell/Comments.tsx

@@ -7,7 +7,7 @@
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
 import { avatarFallback, useComments } from './comments-store.ts'
-import { useStore, type Node } from './store.ts'
+import { CONFIG, useStore, type Node } from './store.ts'
 import { threadHostKey } from './keys.ts'
 import { isNoteAnchor, resolveNoteAnchor, useNotes } from './notes.ts'
 import { canvasCtl } from './canvas/ctl.ts'
@@ -15,7 +15,7 @@ import { bootHash, buildHash, parseHash, writeHash } from './hash.ts'
 import { ArrowUpIcon, CheckIcon, CheckSquareOffsetIcon, LinkIcon, ParallelogramFillIcon, PencilSimpleIcon, PlusIcon, XIcon } from './icons.tsx'
 import { Tip } from './Tip.tsx'
 import { mentionAlerts, mentionPeople, mentionQueryAt, parseBody, type MentionPerson } from './mentions.ts'
-import { ROUTE } from '../const.ts'
+import { ROUTE, slideSize, stageFit } from '../const.ts'
 import type { AgentMeta, Thread } from '../../shared/events.ts'
 
 /** Tint the pin / composer / thread card EDGES (border, outline, focus ring) in the anchored
@@ -132,6 +132,13 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
   const selected = useStore((s) => s.selection.includes(node.key))
   const { setActive } = useComments.getState()
   const [rects, setRects] = useState<Record<string, { x: number; y: number; w: number; h: number } | null>>({})
+  // a slide renders at its stage and the node scales it (FrameNode): rects the frame reports are
+  // in stage px, so they map through the same fit into the node's coordinates
+  const frameEntry = useStore((s) => s.frameFor(node))
+  const stage = frameEntry ? slideSize(frameEntry, CONFIG.viewports) : null
+  const fit = stage ? stageFit(stage, { w: node.w, h: node.h }) : null
+  const inNode = <R extends { x: number; y: number; w: number; h: number }>(r: R): R =>
+    fit ? { ...r, x: fit.ox + r.x * fit.k, y: fit.oy + r.y * fit.k, w: r.w * fit.k, h: r.h * fit.k } : r
 
   const open = threads.filter((t) => !t.resolved)
   const anchored = open.filter((t) => (t.anchor as any)?.el)
@@ -249,7 +256,8 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
 
   const pinPos = (t: Thread) => {
     const a = t.anchor as any
-    const r = isNoteAnchor(a) ? noteRects[t.id] : rects[t.id]
+    const fr = rects[t.id]
+    const r = isNoteAnchor(a) ? noteRects[t.id] : fr && inNode(fr)
     if (a?.el && r) return { x: r.x + (a.pos?.fx ?? 0.5) * r.w, y: r.y + (a.pos?.fy ?? 0.5) * r.h, orphan: false }
     if (a?.el && r === null) return { x: node.w - 16, y: 16, orphan: true }         // orphan parks top-right
     const p = a?.pos                                                                // frame-level: stored fraction of the frame
@@ -310,7 +318,7 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
       )}
       {draft?.nodeKey === node.key && (() => {
         const a = draft.anchor as any
-        const r = (draftOnNote && noteRects.draft) || a?.rect
+        const r = (draftOnNote && noteRects.draft) || (a?.rect && inNode(a.rect))
         return <DraftComposer at={{ x: (r?.x ?? 0) + (a?.pos?.fx ?? 0.5) * (r?.w ?? 0), y: (r?.y ?? 0) + (a?.pos?.fy ?? 0.5) * (r?.h ?? 0) }} bounds={{ w: node.w, h: node.h }} hue={anchorHue(draft.anchor)} />
       })()}
     </>

package/src/client/shell/Play.tsx

@@ -15,7 +15,7 @@ import { useStore, BOARD_POLICY, BRANDING, CONFIG, PUBLISHED, SOURCE_REVEALED, b
 import { deckOrder } from './play-order.ts'
 import { useComments } from './comments-store.ts'
 import { isNoteAnchor } from './notes.ts'
-import { ROUTE } from '../const.ts'
+import { ROUTE, slideSize } from '../const.ts'
 import { poweredByUrl } from '../../shared/utm.ts'
 import { canvasCtl } from './canvas/ctl.ts'
 import { Tip } from './Tip.tsx'
@@ -70,9 +70,9 @@ export function enterSlides(over?: { at?: string; device?: string; theme?: strin
   const at = over?.at && deck.includes(over.at) ? over.at : deck[0]
   const frame = s.manifest?.frames.find((f) => f.id === at)
   const theme = (over?.theme && CONFIG.themes.includes(over.theme) ? over.theme : undefined) ?? frame?.theme ?? s.viewTheme
-  // the deck's own stage is the default device; a restored link may carry a
-  // picked viewport or fill - the standard prototype picker works in slides
-  const device = over?.device && (CONFIG.viewports[over.device] || over.device === 'fill' || over.device === 'slide') ? over.device : 'slide'
+  // a slide is a fixed stage: the deck shows it fit to the window ('slide') or edge to edge
+  // ('fill'); a viewport a restored link carries is not a slide view, so it lands on the stage
+  const device = over?.device === 'fill' ? 'fill' : 'slide'
   s.setPlay({ at, device, theme, slides: true })
 }
 
@@ -358,7 +358,11 @@ function PlayInner() {
 
   const setDevice = (name: string) => {
     const p = useStore.getState().play
-    if (p && (CONFIG.viewports[name] || name === 'fill' || (name === 'slide' && p.slides))) useStore.getState().setPlay({ ...p, device: name })
+    if (!p) return
+    // slides: the stage fit to the window or edge to edge - a viewport preset has no meaning
+    // for a fixed stage, so it lands on the slide view
+    if (p.slides) { useStore.getState().setPlay({ ...p, device: name === 'fill' ? 'fill' : 'slide' }); return }
+    if (CONFIG.viewports[name] || name === 'fill') useStore.getState().setPlay({ ...p, device: name })
   }
   const setTheme = (t: string) => {
     const p = useStore.getState().play
@@ -556,26 +560,34 @@ function PlayInner() {
 
   // doc preset: reading width, natural document scrolling - the iframe takes the
   // window's height at min(width, 860) CSS pixels, unscaled, and scrolls itself
-  const slideDev = slides && play.device === 'slide'
-  const vp = docPreset ? { width: Math.min(win.w, 860), height: win.h }
+  const frameEntry = useStore.getState().manifest?.frames.find((f) => f.id === play.at)
+  // a slide - in slides mode, or a slide frame met in present or focus - is a fixed stage:
+  // the iframe is always its own stage (its declared viewport, else 1280×720), scaled to the
+  // window UP as well as down, so a projector shows it at full size and the frame never scales
+  // itself. 'fill' fits it edge to edge; otherwise it leaves room for the chrome. A slide never
+  // reflows - a device preset has nothing to change on a fixed stage.
+  const stage = (frameEntry && slideSize(frameEntry, CONFIG.viewports)) ?? (slides ? SLIDE_INTRINSIC : null)
+  const vp = stage ? { width: stage.width, height: stage.height }
+    : docPreset ? { width: Math.min(win.w, 860), height: win.h }
     : fill ? { width: win.w, height: win.h }
-    : slideDev ? { width: SLIDE_INTRINSIC.width, height: SLIDE_INTRINSIC.height }
-    : CONFIG.viewports[play.device] ?? (slides ? { width: SLIDE_INTRINSIC.width, height: SLIDE_INTRINSIC.height } : Object.values(CONFIG.viewports)[0])
-  const scale = fill || docPreset ? 1
-    : slideDev ? Math.min(1, (win.w - 48) / vp.width, (win.h - (deckChrome === 'none' ? 48 : 88)) / vp.height)
+    : CONFIG.viewports[play.device] ?? Object.values(CONFIG.viewports)[0]
+  const scale = stage ? Math.max(0.05, fill ? Math.min(win.w / vp.width, win.h / vp.height)
+      : slides ? Math.min((win.w - 48) / vp.width, (win.h - (deckChrome === 'none' ? 48 : 88)) / vp.height)
+      : Math.min((win.w - 96) / vp.width, (win.h - 128) / vp.height))
+    : docPreset || fill ? 1
     : Math.min(1, (win.w - 96) / vp.width, (win.h - 128) / vp.height)
   const names = Object.keys(CONFIG.viewports)
   const list = focus ? [play.at] : slides ? currentDeck() : playList()
   const pos = list.indexOf(play.at)
   const variants = variantList()
-  const frameEntry = useStore.getState().manifest?.frames.find((f) => f.id === play.at)
   const title = focus ? (frameEntry?.title ?? (play.at.split('/').pop() ?? play.at).replace(/-/g, ' ')) : boardLabel(board)
 
   // whole-pixel wrapper + per-axis scale so the iframe lands exactly on its edges -
   // fractional sizes left subpixel seams glowing at the corners on dark frames
   const dw = Math.round(vp.width * scale)
   const dh = Math.round(vp.height * scale)
-  const deviceHint = fill ? 'Fill window' : `${vp.width} × ${vp.height} · keys 1-${names.length + 1}`
+  const deviceHint = stage ? `${vp.width} × ${vp.height} stage · ${fill ? 'edge to edge' : 'fit to the window'}`
+    : fill ? 'Fill window' : `${vp.width} × ${vp.height} · keys 1-${names.length + 1}`
 
   return (
     <div className={`sh-play${fill || docPreset ? ' fill' : ''}${docPreset ? ` doc t-${play.theme}` : ''}`}>
@@ -650,7 +662,7 @@ function PlayInner() {
         {!trimmed && <>
           <LaserButton />
           <i className="sep" />
-          {!docPreset && <DevicePicker value={fill ? 'fill' : play.device} onSelect={(n) => n && setDevice(n)} includeFill includeSlide={slides} hint={deviceHint} dark />}
+          {!docPreset && <DevicePicker value={fill ? 'fill' : play.device} onSelect={(n) => n && setDevice(n)} includeFill includeSlide={slides} stageOnly={slides} hint={deviceHint} dark />}
           <ThemePicker value={play.theme} onSelect={setTheme} hint="D" dark />
         </>}
         {playUpdateRevision && <>

package/src/client/shell/Toolbar.tsx

@@ -153,18 +153,20 @@ export function HideUIButton() {
 /** Controlled device dropdown. `value` is the active device name ('fill' allowed when
  *  includeFill), null = default/mixed. The trigger + menu chrome is shared; the adapter
  *  owns what select does. */
-export function DevicePicker({ value, onSelect, includeDefault, includeFill, includeSlide, hint, dark }: {
+export function DevicePicker({ value, onSelect, includeDefault, includeFill, includeSlide, stageOnly, hint, dark }: {
   value: string | null
   onSelect: (name: string | null) => void
   includeDefault?: boolean
   includeFill?: boolean
-  /** slides mode: the deck's own 1280×720 stage as a first-class device */
+  /** slides mode: the slide's own stage, fit to the window, as a first-class device */
   includeSlide?: boolean
+  /** slides mode: a slide is a fixed stage - only the stage views (slide, fill), no viewports */
+  stageOnly?: boolean
   hint?: ReactNode
   dark?: boolean
 }) {
   const pop = usePopover()
-  const entries = Object.entries(CONFIG.viewports)
+  const entries = stageOnly ? [] : Object.entries(CONFIG.viewports)
   const pick = (name: string | null) => { onSelect(name); pop.setOpen(false) }
   const triggerIcon = value === 'fill' ? <FrameCornersIcon size={16} /> : value === 'slide' ? <SlideFrameIcon size={16} /> : deviceIcon(value, 16)
   return (
@@ -177,7 +179,7 @@ export function DevicePicker({ value, onSelect, includeDefault, includeFill, inc
       </Tip>
       <Popover pop={pop} dark={dark}>
         {includeSlide && <>
-          <button onClick={() => pick('slide')} title="1280 × 720">
+          <button onClick={() => pick('slide')} title="the slide's own size, fit to the window">
             <SlideFrameIcon size={15} /><span>Slide</span>
             {value === 'slide' && <CheckIcon size={13} className="chk" />}
           </button>
@@ -197,7 +199,7 @@ export function DevicePicker({ value, onSelect, includeDefault, includeFill, inc
           </button>
         ))}
         {includeFill && <button onClick={() => pick('fill')}>
-          <FrameCornersIcon size={15} /><span>Fill window</span><kbd>{entries.length + 1}</kbd>
+          <FrameCornersIcon size={15} /><span>Fill window</span><kbd>{Object.keys(CONFIG.viewports).length + 1}</kbd>
           {value === 'fill' && <CheckIcon size={13} className="chk" />}
         </button>}
       </Popover>

package/src/client/shell/canvas/FrameNode.tsx

@@ -11,10 +11,21 @@ import { sleep, wake } from './sleep.ts'
 import { canAutoReload, shouldArmReadyWatch } from './ready-watch.ts'
 import { Stickies, type NoteSpec } from './Sticky.tsx'
 import { noteId, sceneNoteHost } from '../notes.ts'
+import { slideSize, stageFit } from '../../const.ts'
 
 export const HEADER = 28
 const SNAP = 12
 
+/** The iframe's box in its node: a frame fills the node; a slide renders at its stage and is
+ *  scaled uniformly into the node and centred - resizing a slide node never reflows it. The
+ *  identity case carries no transform (no layer, no containing block). */
+function iframeBox(stage: { width: number; height: number } | null, node: { w: number; h: number }) {
+  if (!stage) return { width: node.w, height: node.h }
+  const { k, ox, oy } = stageFit(stage, node)
+  const identity = Math.abs(k - 1) < 1e-6 && Math.abs(ox) < 0.5 && Math.abs(oy) < 0.5
+  return { width: stage.width, height: stage.height, ...(identity ? {} : { transform: `translate(${ox}px, ${oy}px) scale(${k})`, transformOrigin: '0 0' }) }
+}
+
 /** Live Jam working shimmer: a slim 2x6 strip of tiny marver marks on the frame's left
  *  flank, top-aligned - each mark twinkles on its own scattered beat, phased per frame by
  *  --mv-w0 (set on the node) so parallel frames never pulse in sync. */
@@ -172,7 +183,10 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   const resizing = useRef(false)
   const [resizeTick, setResizeTick] = useState(0)
   useEffect(() => { dirty.current = false }, [node.nav])   // a fresh document is pristine again
-  const w = Math.round(node.w), h = Math.round(node.h)
+  // a slide's document is its stage, whatever the node's size (the node only scales it): the
+  // sleep key - the size the compiler renders to certify textures - is the document's size
+  const stage = frame ? slideSize(frame, CONFIG.viewports) : null
+  const w = Math.round(stage?.width ?? node.w), h = Math.round(stage?.height ?? node.h)
   // a layout effect: the wake lands BEFORE the first paint of the new state (a stretched texture
   // must never be painted at a new size)
   useLayoutEffect(() => {
@@ -418,7 +432,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
           src={src}
           title={frame.id}
           onLoad={registerWin}
-          style={{ width: node.w, height: node.h, display: node.missing || node.status === 'error' ? 'none' : 'block' }}
+          style={{ ...iframeBox(stage, node), display: node.missing || node.status === 'error' ? 'none' : 'block' }}
         />
         {/* the overlay eats mouse events for drag-by-body; laser and comment mode both
             need the mouse INSIDE the frame for hover highlights, so it steps aside

package/src/client/shell/canvas/Sticky.tsx

@@ -19,6 +19,7 @@ import { cleanSource, guardDiagramSource, sanitizeSvg } from '../../content/diag
 import { useComments } from '../comments-store.ts'
 import { goTo } from '../goto.ts'
 import { NOTE_W, SCENE_NOTE_W, noteAnchor, noteVisible, useNotes, type NoteKind } from '../notes.ts'
+import { useStore } from '../store.ts'
 
 export interface NoteSpec { kind: NoteKind; id: string; text: string }
 
@@ -266,10 +267,24 @@ function StickyBody({ text, kind, nodeKey, frameId }: { text: string; kind: Note
 export const Stickies = memo(function Stickies({ nodeKey, frameId, notes, underBadge }: { nodeKey: string; frameId: string; notes: NoteSpec[]; underBadge: boolean }) {
   const ids = notes.map((n) => n.id)
   const on = useNotes((s) => noteVisible(s, ids))
+  const col = useRef<HTMLDivElement>(null)
+  // the column's extent is measured, never computed: markdown, fonts and diagrams decide it. The
+  // layout gets it (and its changes) so a note longer than its frame has room below; a folded
+  // column keeps its height (the fold is a transform), so folding never reflows. Unmounting
+  // (notes gone, board switched) clears it.
+  useEffect(() => {
+    const el = col.current
+    if (!el) return
+    const report = () => useStore.getState().noteMeasured(nodeKey, el.offsetTop + el.offsetHeight)
+    const ro = new ResizeObserver(report)
+    ro.observe(el)
+    report()
+    return () => { ro.disconnect(); useStore.getState().noteMeasured(nodeKey, 0) }
+  }, [nodeKey, underBadge, notes.length])
   if (!notes.length) return null
   const width = Math.max(...notes.map((n) => (n.kind === 'scene' ? SCENE_NOTE_W : NOTE_W)))
   return (
-    <div className={`sh-notes${on ? '' : ' off'}${underBadge ? ' below-vbadge' : ''}`} data-node-notes={nodeKey} style={{ width }}>
+    <div ref={col} className={`sh-notes${on ? '' : ' off'}${underBadge ? ' below-vbadge' : ''}`} data-node-notes={nodeKey} style={{ width }}>
       <button className="sh-notes-fold sh-no-pan" type="button" aria-label={on ? 'hide notes' : 'show notes'} title={on ? 'hide notes (N: all)' : 'show notes (N: all)'}
         onPointerDown={(e) => e.stopPropagation()}
         onClick={(e) => { e.stopPropagation(); useNotes.getState().toggle(ids) }} />

package/src/client/shell/notes.ts

@@ -44,14 +44,36 @@ export function sceneNoteHost(
  *  `h + NODE_HEADER` tall, and that is the height a note beside it has to clear. */
 export const NODE_HEADER = 28
 
-/** True when a note has no room: another node's card stands inside the reserve in front of a
- *  noted node (its own note, or the scene's note it hosts). Room is the layout's job, never the
- *  author's - a board the shell composes re-applies its layout when this is true, so a note file
- *  can land on a saved board and the frames make way. Missing nodes (a deleted frame's card, still
- *  drawn full size) block room but never host a note. */
+/** The measured extent of a node's note column: world px from the node's top to the bottom of
+ *  its last sticky (0 = no column, or not rendered yet). A note's height is its content's, known
+ *  only once it is drawn - so, like a content frame's height, it is measured, transient (never
+ *  serialized, a reload remeasures), and fed back to the layout when it lands. */
+const noteHeights = new Map<string, number>()
+export const noteHeight = (key: string): number => noteHeights.get(key) ?? 0
+/** Record a column's extent; true when it changed (the caller asks the layout for room then). */
+export function setNoteHeight(key: string, h: number): boolean {
+  const H = Number.isFinite(h) && h > 0 ? Math.round(h) : 0
+  if ((noteHeights.get(key) ?? 0) === H) return false
+  if (H) noteHeights.set(key, H)
+  else noteHeights.delete(key)
+  return true
+}
+/** A board load starts from no heights: node keys are per board file, and a key another board
+ *  also uses must not bring its column's height along (the old board unmounts after the load). */
+export const clearNoteHeights = (): void => { noteHeights.clear() }
+
+/** True when a note has no room: another node stands inside the space in front of a noted node
+ *  (its own note, or the scene's note it hosts) - beside its card, or below it where a note taller
+ *  than its frame runs on. Room is the layout's job, never the author's - a board the shell
+ *  composes re-applies its layout when this is true, so a note file can land on a saved board and
+ *  the frames make way. An obstacle is another node's card, or its own note column (two columns
+ *  running into each other cramp too) - the two rectangles, never their bounding box: the empty
+ *  canvas under a card beside a long column is free. Missing nodes (a deleted frame's card, still
+ *  drawn full size) block room but never host a note. `noteH` is the measured column extent. */
 export function notesCramped(
   nodes: readonly { key: string; frame: string; x: number; y: number; w: number; h: number; missing?: boolean }[],
   manifest: { frames: { id: string; scene: string; note?: string }[]; scenes: { name: string; note?: string }[] } | null,
+  noteH: (key: string) => number = noteHeight,
 ): boolean {
   if (!manifest) return false
   const entry = (id: string) => manifest.frames.find((f) => f.id === id)
@@ -62,11 +84,23 @@ export function notesCramped(
     const h = sceneNoteHost(live, (id) => entry(id)?.scene, s.name)
     if (h) hosts.add(h)
   }
+  type N = (typeof nodes)[number]
+  type R = { x0: number; x1: number; y0: number; y1: number }
+  const hit = (a: R, b: R) => a.x0 < b.x1 && a.x1 > b.x0 && a.y0 < b.y1 && a.y1 > b.y0
+  const card = (n: N): R => ({ x0: n.x, x1: n.x + n.w, y0: n.y, y1: n.y + n.h + NODE_HEADER })
+  // the room a note takes: the reserve beside the card, as tall as the card or the column, whichever runs further
+  const room = (n: N): R | null => {
+    const r = n.missing ? 0 : noteReserve(!!entry(n.frame)?.note, hosts.has(n.key))
+    return r ? { x0: n.x - r, x1: n.x, y0: n.y, y1: n.y + Math.max(n.h + NODE_HEADER, noteH(n.key)) } : null
+  }
   return live.some((n) => {
-    const r = noteReserve(!!entry(n.frame)?.note, hosts.has(n.key))
-    if (!r) return false
-    const x0 = n.x - r, y1 = n.y + n.h + NODE_HEADER
-    return nodes.some((o) => o !== n && o.x < n.x && o.x + o.w > x0 && o.y < y1 && o.y + o.h + NODE_HEADER > n.y)
+    const mine = room(n)
+    if (!mine) return false
+    return nodes.some((o) => {
+      if (o === n) return false
+      const theirs = room(o)
+      return hit(mine, card(o)) || (!!theirs && hit(mine, theirs))
+    })
   })
 }