@marver-design/marver 0.19.1 → 0.20.0

package/docs/slides.md

@@ -3,67 +3,63 @@
 A slide is an ordinary frame with `slide: true`:
 
 ```tsx
-import { Slide } from '@marver-design/marver/content'
-export const meta = { title: 'Cover', slide: true }
+export const meta = { title: 'Onboarding time halved', slide: true }
 export default () => (
-  <Slide>
-    <h1 className="sl-assertion">Churn halved after onboarding v2</h1>
-  </Slide>
+  <main className="deck deck-ink">
+    <h1>Onboarding time halved in one quarter.</h1>
+  </main>
 )
 ```
 
-It renders 1280×720 on the canvas, wears the slide badge, and everything
-you know - comments, lasers, variants, promotion, Live Jam - keeps working.
-**The stage fits every screen**: you author at exactly 1280×720, and the
-slide scales and centers itself to whatever viewport plays it - fill window,
-a laptop, a viewer's phone - author px, Tailwind classes, and charts all
-scale together, so the composition you approved is the composition everyone
-sees. One scene = one deck; numbered files
-(`01-cover.tsx`) are the authoring order; **the board's reading order is the
-played order** - drag slides around the canvas to reorder the deck.
-
-## Why it stays light for the agent
-
-There is no slide component library to learn. `Slide` is the ONE primitive:
-it owns the 1280×720 stage, the asymmetric margins, six fixed type roles
-(`sl-display` 160 · `sl-stat` 88 · `sl-assertion` 56 · `sl-support` 30 ·
-`sl-body` 24 · `sl-caption` 18), your theme's tokens, and the motion
-contract. Everything inside it is your project's own markup, classes, and
-components - the same ones the app ships - so a slide is built the way a
-screen is built, and an approved slide can be promoted like one.
-
-Looking good at every size costs the agent nothing extra: the fit is pure
-CSS on the root (a resized canvas node, a phone, a projector all get the
-same composition, scaled), so the doctrine forbids `vw`/`vh` and media
-queries inside a slide and asks for flex/grid in the stage's own
-proportions. A dev-only overflow marker outlines a slide whose content escapes the
-stage, or whose flex/grid child outgrows its parent - the agent sees the
-defect on the canvas, and the rule is always "cut or split, never shrink the type".
-
-The craft lives in prose, not code. `marver init` ships
-`design/instructions/slides.md` - the doctrine: assertion-first argument,
-the type roles, **the space IS the design** (three bands, the 85% rule, one
-px spacing scale), **seven silhouettes chosen before any recipe** (statement
-/ hero / split / grid / stream / field / bookend) with a storyboard step
-and pacing rules so a deck never reads as one repeated shape, 19 core
-recipes with budgets and morph anchors, the choreography rules, and a
-review gate that squints the contact sheet. Two depth references sit
-beside it: `instructions/reference/deck-story.md` (intake, answer-first
-structure, the evidence check, audience calibration, the words) and
-`instructions/reference/deck-layouts.md` (the full layout atlas by job, the
-grid, content budgets, rebuilding an existing deck, chart craft). Your own
-**deck look** (tokens, type, the mark, colour meaning, numbers, voice - a
-fill-in template the agent drafts on the first deck), layouts, and house
-rules live in `design/slides.md`, which overrides the doctrine and which
-marver never overwrites.
+That is the whole contract. Everything inside is your code - your
+project's components and classes, any layout, any typeface, any image,
+any SVG drawing, any CSS or JS animation. marver adds what a deck needs
+around it: a stage, a player, and a place on the board.
+
+- **The stage.** A slide renders at its stage size: 1280×720 by default,
+  or the `viewport` it declares (`viewport: 'laptop'` gives a 16:10 deck at
+  1280×800). On the canvas it is a frame like any other - comments, laser,
+  variants, Live Jam - with a slide badge.
+- **The deck.** One scene is one deck; numbered files (`01-cover.tsx`) are
+  the authoring order, and **the board's reading order is the played
+  order** - drag slides around the canvas to reorder the deck.
+- **The host scales, not the slide.** A slide never reflows. Slides mode
+  renders each slide at its stage and scales the whole stage to the screen -
+  up on a projector, down on a laptop or a phone - and a canvas node resized
+  smaller shows the same stage, scaled, like a thumbnail. The composition you
+  approved is the one everyone sees, without breakpoints.
+- **Notes.** `<slide>.note.md` beside the frame is its
+  [sticky note](sticky-notes.md): the aim, the talk track, the visual
+  intent, the sources. Notes ship with a published canvas, so keep anything
+  the audience must not read out of them.
+
+## The guidance the agent reads
+
+`marver init` ships `design/instructions/slides.md` - not a rulebook, a
+guide: how a slide plays and animates, the **deck kit** a strong deck is
+built on (a master shell, whole-slide tones, the brand's type, hairlines
+and labels, a drawing helper), the craft that makes a deck look made
+rather than typed (the brand's own voice, one idea per slide, structure
+with space instead of boxes, real images used big, a drawing system of its
+own, pacing, honest numbers), the method (the answer first, a slide list
+that tells the argument, a `_brief.md`, notes per slide), and a review that
+squints at the contact sheet. Two references sit beside it:
+`instructions/reference/deck-story.md` (intake, answer-first structure, the
+evidence check, the words) and `instructions/reference/deck-layouts.md` (an
+idea bank of compositions, rebuilding an existing deck, chart craft).
+
+Your own **deck look** - master, tones, type, mark, imagery, drawing style,
+colour meaning, voice - lives in `design/slides.md`, which the agent drafts
+from your brand on the first deck, which overrides the shipped guide, and
+which marver never overwrites.
 
 ## Playing and publishing a deck
 
 Press `p` on a board whose publish row says slides and you get slides mode:
-the 16:9 stage with the standard prototype toolbars (with `chrome: full`,
-the default) - arrows / Space / click to advance, `d` cycles the theme,
-devices including a 1280×720 Slide preset and fill window.
-Publish it with:
+the stage scaled to the window, the standard prototype toolbars (with
+`chrome: full`, the default), arrows / Space / click to advance, `d` cycles
+the theme, and two views of the stage: Slide (fit to the window, room for
+the chrome) and Fill window (edge to edge). Publish it with:
 
 ```json
 { "boards": { "pitch": { "max": "comment", "type": "slides",
@@ -72,8 +68,8 @@ Publish it with:
 
 - `transition`: `fade` (default) or `none`.
 - `chrome`: `full` (default - the standard prototype chrome: the top-right
-  toolbar with comment, laser, theme, and devices including fill, plus the
-  bottom-left walker; a locked deck-only share also carries the brand pill),
+  toolbar with comment, laser, theme, and devices, plus the bottom-left
+  walker; a locked deck-only share also carries the brand pill),
   `minimal` (a slim progress strip, comments, the canvas door when the
   board is not locked, and a pending-update control), or `none` (bare
   stage).
@@ -83,35 +79,44 @@ Publish it with:
 
 Viewers land straight in the deck; the URL survives refresh and back.
 
-## Motion - the diff is the animation
+## Motion
 
-A resting slide is STILL - that is a contract, not a hope: charts render
-final-state SVG, videos are posters (no `<video>` element exists), and the
-`Slide` root suspends every CSS animation and transition under it at rest.
-(Your own `<canvas>`, `<video>`, or JS-driven motion is outside the contract
-and stays live, as in any frame.) Motion happens in slides
-mode, one-shot:
+Motion is yours to write. While a deck plays, the stage puts
+`data-sl-play` on `<html>` for the whole show, and `data-sl-entered` once
+each slide has arrived (removed at each swap, set again when the new slide
+settles); `useSlidePlay()` from `/content` is the playing flag in React. Key
+your animations off them, so the canvas, `marver shot` and thumbnails show
+the finished slide:
+
+```css
+:root[data-sl-entered] .route { animation: draw 900ms ease-out both }
+@keyframes draw { from { stroke-dashoffset: 600 } to { stroke-dashoffset: 0 } }
+```
+
+On the canvas, a resting frame's animations are paused anyway (see sleep in
+the README). marver adds three things on top:
 
 - **Morphs**: give the same `view-transition-name` to an element on two
-  adjacent slides and it travels/grows between them. This is the house move.
-- **Build steps**: progressive disclosure is sibling frames (`03a-`, `03b-`)
-  sharing morph names - every step visible and commentable on the board.
-- **Entrances**: `data-animate="fade-up | fade | scale-in"` +
-  `data-animate-delay="0-3"`, run once after the transition settles. Never
-  on an element that carries a morph name.
+  adjacent slides and it travels or resizes between them.
+- **Build steps**: progressive disclosure is sibling frames (`03a-`,
+  `03b-`) sharing morph names - every step visible and commentable on the
+  board.
+- **Entrance shortcuts**: `data-animate="fade-up | fade | scale-in"` +
+  `data-animate-delay="1-3"`, run once after a slide arrives. Never on an
+  element that carries a morph name.
 
-`prefers-reduced-motion` flattens marver's own motion - the morphs between
-slides and the entrance presets.
+`--marver-slide-tempo` in your theme (default 350ms) times the morphs and
+the shortcuts. `prefers-reduced-motion` flattens both.
 
 ## Charts and video
 
 - `<Chart option={...} h={420} />` - an Apache ECharts option, on a
   fixed supported surface: series bar, line, pie, scatter, radar, gauge, heatmap, funnel, treemap, sunburst, sankey, boxplot; components grid, polar, radar, tooltip, legend, title, dataset (+ transform), markLine, markPoint, markArea, visualMap, dataZoom. Anything outside
   it is dropped by ECharts without an error, so stay inside. marver
-  supplies the house theme (colours, type, tooltip) from your
-  `design/theme.css` tokens, strips animation at rest, and lets any
-  styling you pass override the theme - so pass data and structure only.
-  SVG-rendered, in a lazy chunk chart-free canvases never download.
+  supplies the house theme from the slide's own ink and typeface (and
+  `--marver-slide-accent`), sizes labels for a stage, keeps the chart
+  still at rest and plays its entrance in slides mode. SVG-rendered, in a
+  lazy chunk chart-free canvases never download.
 - `<Video src="intro.mp4" poster="intro.jpg" />` - the poster is the frame
   at rest. Omit it on a local clip and marver renders one from the clip's own
   first moments (`intro.mp4.poster.png` beside it - the dev server on first
@@ -122,19 +127,14 @@ slides and the entrance presets.
   `ratio="9 / 16"` for a vertical clip; `autoplay` for a muted ambient loop
   (that frame then stays live on the canvas). Remote https direct files work
   too.
+- Images: `Img` for a framed asset, or a plain `<img>` when the slide needs
+  full control. Slides play scaled up, so use files at least 2x the size
+  they show.
+
+## Decks built before 0.20
 
-## Theme tokens
-
-The `Slide` root reads `--marver-slide-ground / -ink / -muted` (each with a
-`-dark` variant), `--marver-slide-accent` (one value, both themes),
-`--marver-slide-font`, and `--marver-slide-tempo` (one duration that times
-both the entrances and the morphs between slides) from your theme and falls
-back to the house palette. The stage is 1280×720 (`SLIDE_W` / `SLIDE_H`, exported from `/content`)
-with asymmetric margins - 88px sides, 44px top and bottom, overridable in
-px via `--marver-slide-pad-x` / `--marver-slide-pad-y` - leaving a 1104×632
-content box. Morphs between slides are progressive enhancement: where
-`document.startViewTransition` is missing, slides crossfade at the tempo.
-Type roles, fixed: `sl-display` (160px, the one
-oversize - a hero number, a section numeral), `sl-stat` (88px, a row of
-figures), `sl-assertion` (56px),
-`sl-support` (30px), `sl-body` (24px), `sl-caption` (18px).
+Earlier decks wrap each slide in `<Slide>` and use its `sl-*` type classes.
+`<Slide>` still exists, as an optional wrapper that fills the frame - but it
+no longer pads the stage, centres content, sizes type or freezes animation,
+and the `sl-*` classes carry no styles. Such a deck still plays; give it its
+own styles (a deck kit, as the guide describes) to restore the look.

package/docs/sticky-notes.md

@@ -21,10 +21,11 @@ inert. A scene note is 380 wide, a frame note 260; when a frame has both, they s
 scene first. An edit lands on the canvas as you save, without reloading the frame.
 
 The room is the layout's job. Every layout the shell composes (a board's `layout` recipe, the auto
-board, tidy, device views) reserves the note's width in front of its frame, and a note landing on a
-board already composed re-applies the recipe so the frames make way - whether the board is open at
-the time or not. Nobody moves frames for a note. A board dragged by hand keeps its positions; `t`
-makes the room there.
+board, tidy, device views) reserves the note's width in front of its frame and its height below it:
+a note longer than its frame runs on under the card, and the row beneath starts under the note, the
+gutter unchanged. A note landing on a board already composed re-applies the recipe so the frames
+make way - whether the board is open at the time or not - and so does a note that grows. Nobody
+moves frames for a note. A board dragged by hand keeps its positions; `t` makes the room there.
 
 ## Diagrams
 
@@ -43,6 +44,15 @@ own theme.
 - Comments: in comment mode (`C`) click any element of a note; the pin sits on the note, follows a
   fold onto the tab, and the thread card opens beside the column.
 
+## On a slide
+
+Beside a slide (`slide: true`), the note is the presenter's script and the next agent's memory,
+and the [slides guide](slides.md) teaches agents to write it in four short parts - **Aim** (what the
+slide must do in the argument), **Say** (the talk track), **Visual** (what the image or drawing
+carries) and **Source context** (where the facts come from, and their limits) - so the slide itself
+can stay sparse. A note ships with a published canvas like any other: keep anything the audience
+must not read out of it.
+
 ## What it is not
 
 A note is an aside, a screen's worth of reading at most. Specs, flows and mood boards stay content

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
   "type": "module",
   "private": false,

package/src/client/const.ts

@@ -9,15 +9,33 @@ export const ROUTE = '/__mv'
  *  manifest scan (defaultSize for content frames) - one source, no drift. */
 export const CONTENT_WIDTH: Record<string, number> = { document: 760, wide: 1280 }
 
-/** The slide stage (v1.5): a runtime-reserved intrinsic, deliberately NOT a
- *  config viewport - no migration for existing projects, no deck device in
- *  sweeps. Dependency-neutral so server (shot) and shell (store) share it. */
+/** The default slide stage: 16:9 at 1280×720, deliberately NOT a config viewport - no
+ *  migration for existing projects, no deck device in sweeps. Dependency-neutral so
+ *  server (shot) and shell (store, play) share it. */
 export const SLIDE_INTRINSIC = { width: 1280, height: 720 }
 
-/** The one DEFAULT sizing rule for slide frames, shared by canvas and shot:
- *  `slide: true` sets the intrinsic 1280×720 stage, over any authored viewport.
- *  Board nodes stay resizable (the Slide root scales into whatever box it is
- *  given); this governs defaults, shots, and stage coordinates. */
-export function slideSize(frame: { slide?: boolean }): { width: number; height: number } | null {
-  return frame.slide ? SLIDE_INTRINSIC : null
+/** The one sizing rule for slide frames, shared by canvas, shot and slides mode: a
+ *  `slide: true` frame's stage is its declared viewport when the project defines one
+ *  (a 16:10 deck authored at `laptop` stays 1280×800), else the 1280×720 default. A
+ *  slide is an ordinary frame at that size - slides mode scales the whole stage to the
+ *  screen, so the frame never has to. */
+export function slideSize(
+  frame: { slide?: boolean; viewport?: string },
+  viewports: Record<string, { width: number; height: number }> = {},
+): { width: number; height: number } | null {
+  if (!frame.slide) return null
+  const vp = frame.viewport ? viewports[frame.viewport] : undefined
+  return vp ? { width: vp.width, height: vp.height } : SLIDE_INTRINSIC
+}
+
+/** The baseline every slide document shares, in the frame host and the stage alike: the
+ *  document IS the stage, so the browser's body margin never frames it - whatever the theme
+ *  or the content primitives a previous slide injected. */
+export const SLIDE_DOC_CSS = 'html[data-mv-slide] body { margin: 0 }'
+
+/** How a slide's stage sits in a box of any other size: scaled uniformly to fit and centred.
+ *  A slide never reflows - the canvas node, the player and a shot all show the same stage. */
+export function stageFit(stage: { width: number; height: number }, box: { w: number; h: number }): { k: number; ox: number; oy: number } {
+  const k = Math.max(0.01, Math.min(box.w / stage.width, box.h / stage.height))
+  return { k, ox: (box.w - stage.width * k) / 2, oy: (box.h - stage.height * k) / 2 }
 }

package/src/client/content/chart.tsx

@@ -1,11 +1,9 @@
 /**
  * Chart (v1.5) - Apache ECharts, the Diagram way: the author picks the FORM
  * (the ECharts option surface, pointed at from instructions/slides.md);
- * marver injects the house theme and strips author styling drift where it
- * breaks the deck (animation at rest, above all).
+ * marver injects the house theme and keeps the chart still at rest.
  *
- * SVG renderer ONLY - a canvas-rendered chart would pin its frame live on
- * the board (the lean-DOM serializer keeps <canvas> frames degraded). At
+ * SVG renderer ONLY - crisp at any canvas zoom and any stage scale. At
  * rest the chart renders its final state (animation force-disabled); in
  * slides mode (useSlidePlay) it plays its entrance once on mount.
  *
@@ -66,19 +64,21 @@ export function chartTheme(t: { ink: string; font: string; accent: string; groun
 
 /** The house theme, read from the frame the chart sits in, at render time. Ink and font are
  *  the element's own COMPUTED color and font-family - so a chart inherits a UI screen's
- *  Tailwind text colour and typeface, a Doc's tokens, or a Slide's, with no per-context
- *  wiring. Accent and ground come from slide tokens, then Doc tokens, then the mode palette. */
+ *  Tailwind text colour and typeface, a Doc's tokens, or a slide's own type, with no
+ *  per-context wiring. Accent and ground come from slide tokens, then Doc tokens, then the
+ *  mode palette. A slide frame (meta `slide: true`, stamped on <html> as data-mv-slide) or a
+ *  <Slide> wrapper takes the stage label scale. */
 function houseTheme(el: HTMLElement, dark: boolean) {
   const css = getComputedStyle(el)
   const v = (...names: string[]) => { for (const n of names) { const x = css.getPropertyValue(n).trim(); if (x) return x } return '' }
   return chartTheme({
     ink: css.color || (dark ? '#F2F2F7' : '#1C1C1E'),
     font: v('--sl-font') || css.fontFamily || FONT_STACK,
-    accent: v('--sl-accent', '--mv-accent') || (dark ? '#0091FF' : '#0088FF'),
+    accent: v('--sl-accent', '--marver-slide-accent', '--mv-accent') || (dark ? '#0091FF' : '#0088FF'),
     ground: v('--sl-ground', '--mv-surface', '--mv-bg') || (dark ? '#1C1C1E' : '#FFFFFF'),
     grid: v('--sl-grid') || (dark ? 'rgba(242,242,247,.12)' : 'rgba(28,28,30,.1)'),
     dark,
-    inSlide: !!el.closest('.sl-root'),
+    inSlide: !!el.closest('.sl-root') || document.documentElement.hasAttribute('data-mv-slide'),
   })
 }
 

package/src/client/content/index.tsx

@@ -22,7 +22,7 @@ export function Diagram(props: Parameters<typeof DiagramRoot>[0]) { ensureStyles
 import { Slide as SlideRoot } from './slide.tsx'
 import { Chart as ChartRoot } from './chart.tsx'
 import { Video as VideoRoot } from './video.tsx'
-export { SLIDE_W, SLIDE_H } from './slide.tsx'
+export { SLIDE_W, SLIDE_H, useSlidePlay } from './slide.tsx'
 // the shared stylesheet used to ride in with Doc alone; a slide composes Img,
 // Chart, and Video straight inside <Slide> with no Doc, so every public
 // primitive installs it - once per document, idempotent
@@ -98,9 +98,10 @@ export function Img({ src, caption, alt, h }: { src: string; caption?: string; a
   const url = assetUrl(src)
   const [err, setErr] = useState(false)
   const canvasRef = useRef<HTMLCanvasElement>(null)
-  // inside a <Slide>, the LOD canvas is OFF: a resting slide must serialize to
-  // the lean-DOM path, and a <canvas> element pins its frame live (v1.5 §7)
-  const inSlide = useInSlide()
+  // on a slide the LOD canvas is OFF: slides mode scales the whole stage up to the screen,
+  // and a bitmap decoded for the frame's own box would blur there - the plain <img> keeps
+  // its full resolution. A slide frame is marked on <html> (data-mv-slide) before it renders.
+  const inSlide = useInSlide() || (typeof document !== 'undefined' && document.documentElement.hasAttribute('data-mv-slide'))
   // LOD: paint the image on a <canvas> decoded to its on-screen size (never the full 17MB bitmap), and
   // re-pick resolution only when the canvas settles after a zoom. See img-lod.ts. Falls back to a plain
   // <img> where createImageBitmap/bitmaprenderer isn't available (correctness over the optimization).