@marver-design/marver 0.19.2 → 0.21.0

package/dist/{init-BQYCS3EU.mjs → init-C34BY3R4.mjs}

@@ -1,5 +1,5 @@
 import { r as NAME } from "./cli.mjs";
-import { d as readJson, l as detectAgent, o as writeManifest, r as scanFrames, s as DEFAULTS, u as detectHost } from "./manifest-B01PSyDc.mjs";
+import { d as readJson, l as detectAgent, o as writeManifest, r as scanFrames, s as DEFAULTS, u as detectHost } from "./manifest-mMfUhPtL.mjs";
 import { MANAGED_PREFIX, enumerateInstructionTemplates, hashBody, managedFile, pkgDir } from "./managed-HwHVNI3h.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
@@ -153,11 +153,11 @@ function init(root, opts) {
 		}
 	}
 	write("slides.md", [
-		"# This project's slide layouts and house rules",
+		"# This project's deck look and house habits",
 		"",
-		"The agent reads BOTH the shipped doctrine (instructions/slides.md) and this",
-		"file - and this file WINS where they disagree. Add your own layouts, house",
-		"rules, and banned moves here; it is yours and marver never touches it.",
+		"The agent reads BOTH the shipped guide (instructions/slides.md) and this",
+		"file - and this file WINS where they disagree. Add your own deck look,",
+		"compositions and habits here; it is yours and marver never touches it.",
 		"",
 		"To grow it from examples: drop decks (PPTX, PDF, screenshots) into",
 		"design/slides-inspiration/ and ask the agent to \"study my inspiration\" -",
@@ -166,44 +166,45 @@ function init(root, opts) {
 		"## The deck look",
 		"",
 		"How a deck wears this brand. The agent drafts it from DESIGN.md and",
-		"theme.css on the first deck (a reviewed edit, building on provisionally",
-		"with the theme's tokens); anything it cannot settle stays `TBD` for you.",
-		"Each line shows the shape with an example - replace the example, keep the",
-		"shape.",
+		"theme.css on the first deck (a reviewed edit); anything it cannot settle",
+		"stays `TBD` for you. Each line shows the shape with an example - replace",
+		"the example, keep the shape.",
 		"",
-		"- **Tokens** (`--marver-slide-*` in theme.css, read by the Slide root):",
-		"  ground / ink / muted, each with a `-dark` twin; accent, one value for",
-		"  both themes. e.g. ground = the page background, ink = the heading",
-		"  colour, accent = the primary button.",
-		"- **Type** (`--marver-slide-font`): one family, the theme's; the type",
-		"  roles carry their weights. e.g. Inter.",
-		"- **The mark**: which asset, where, how big. e.g. wordmark SVG, bottom-left",
-		"  of the cover and the closing only, 120px wide - never on content slides.",
-		"- **Colour meaning** (charts, cards, badges): hue = category, fixed across",
-		"  the deck. e.g. accent = us, slate = competitors, muted = the baseline;",
-		"  green / amber / red reserved for status.",
-		"- **Backgrounds allowed**: e.g. the flat ground; a theme gradient on covers",
-		"  and sections only; no photos behind text without a scrim.",
-		"- **Imagery**: e.g. product screenshots on a device-less frame, real people,",
-		"  no stock; illustrations in the product's line style only. Evidentiary",
-		"  images (a report fragment, a log line, a reasoning trace, a real",
-		"  screen) are evidence objects, not decoration - hero material when the",
-		"  message warrants it.",
-		"- **Tempo** (`--marver-slide-tempo`): e.g. 350ms - one value, every deck.",
+		"- **Stage**: e.g. 1280×720 (the default); or `viewport: 'laptop'` on every",
+		"  slide for a 16:10 deck.",
+		"- **The master**: what every content slide wears. e.g. the mark top left,",
+		"  \"Prepared for <client> · Confidential · <month year>\" top right in the",
+		"  muted colour; the cover and the closing step outside it.",
+		"- **Tones**: whole-slide colour sets. e.g. paper (#F1F0EA on #151616) for",
+		"  working slides, ink for statements and turns, the brand blue once, for",
+		"  the proof.",
+		"- **Type**: family, weights, tracking, the few sizes. e.g. the brand sans at",
+		"  400 for headlines and text, tight tracking on headlines; a display, a",
+		"  heading, a body and a small label size - hierarchy by size and colour.",
+		"- **The mark**: which asset, where, how big. e.g. the lockup in the master,",
+		"  paired with the client's mark on the cover.",
+		"- **Imagery**: e.g. the client's own photography, full- or half-bleed under",
+		"  a uniform scrim; product screenshots on a device-less frame; no stock.",
+		"- **Drawings**: e.g. native SVG line drawings on a shared dotted grid, ink",
+		"  with one accent per slide, light and dark versions.",
+		"- **Colour meaning**: e.g. accent = the point of the slide; dark red = the",
+		"  problem loop; green = the outcome; never decoration.",
+		"- **Motion** (`--marver-slide-tempo` in theme.css): e.g. 350ms morphs;",
+		"  drawings trace in when a slide arrives; nothing loops.",
 		"- **Numbers**: e.g. $ and k / M (lowercase k), fiscal years as FY26,",
 		"  negatives in brackets, one decimal on percentages.",
 		"- **Voice**: three words the deck sounds like, and the words it never",
 		"  uses. e.g. direct, warm, specific; never \"leverage\", \"seamless\", \"journey\".",
 		"- **Terminology**: user-facing word → never-shown internal word.",
 		"  e.g. \"Comments\" → \"Enrichment\".",
-		"- **End card**: yes / no. e.g. yes - the mark on the ground, no text; the",
-		"  ask lives on the slide before it.",
+		"- **End card**: e.g. a full-bleed photograph, the mark and a contact; the",
+		"  ask lives on the slide before.",
 		"",
-		"## Layouts",
+		"## Compositions",
 		"",
-		"(none yet - the shipped recipe list and atlas apply)",
+		"(none yet - the shipped idea bank in instructions/reference/deck-layouts.md applies)",
 		"",
-		"## House rules",
+		"## House habits",
 		"",
 		"(none yet)",
 		""

package/dist/{manifest-B01PSyDc.mjs → manifest-mMfUhPtL.mjs}

@@ -1,5 +1,5 @@
 import { i as PKG, n as CONTENT_WIDTH } from "./cli.mjs";
-import { a as listBoardFiles, d as flatten, f as isBoardName, g as hash, m as readTitle, n as checkBoardsDir, p as readDescription, r as checkRealDirs, s as readRegistry, t as boardFields, u as buildTree } from "./boards-BmxcT3Lc.mjs";
+import { a as listBoardFiles, d as flatten, f as folderEntries, h as readTitle, m as readDescription, n as checkBoardsDir, p as isBoardName, r as checkRealDirs, s as readRegistry, t as boardFields, u as buildTree, v as hash } from "./boards-BwiDAmPf.mjs";
 import { accessSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { delimiter, isAbsolute, join, relative, sep } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -615,8 +615,9 @@ function setSceneTitle(root, scene, title) {
 	}
 	return null;
 }
-/** The sidebar as files say it is, for the manifest: folders in root order, boards in
-*  reading order with their folder and description. A boards dir we may not read (symlink)
+/** The sidebar as files say it is, for the manifest: folders in reading order (a sub-folder
+*  after its parent, with `parent`), boards in reading order with the folder they sit in
+*  directly and their description. A boards dir we may not read (symlink)
 *  or a malformed registry yields nothing here - the API and the build say why; the
 *  orientation file must never fail to write. */
 function scanBoards(root) {
@@ -629,10 +630,12 @@ function scanBoards(root) {
 		...boardFields(b.json, isBoardName)
 	}));
 	const tree = buildTree(rows, reg.folders);
+	const entries = folderEntries(tree);
 	const folderOf = /* @__PURE__ */ new Map();
-	for (const it of tree) if (it.kind === "folder") for (const b of it.boards) folderOf.set(b, it.name);
-	const folders = tree.filter((it) => it.kind === "folder").map((it) => ({
+	for (const { folder } of entries) for (const k of folder.items) if (k.kind === "board") folderOf.set(k.name, folder.name);
+	const folders = entries.map(({ folder: it, parent }) => ({
 		name: it.name,
+		...parent ? { parent } : {},
 		...it.title ? { title: it.title } : {},
 		...it.description ? { description: it.description } : {}
 	}));

package/dist/{plugin-DI-7NAnx.mjs → plugin-omHLCn91.mjs}

@@ -1,8 +1,8 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import { a as ROUTE, i as PKG, r as NAME } from "./cli.mjs";
-import { a as listBoardFiles, c as BOARD_NAME, g as hash, h as validateWire, i as isRegularFile, l as FOLDERS_FILE, m as readTitle, n as checkBoardsDir, o as nodeExists, p as readDescription, s as readRegistry, t as boardFields } from "./boards-BmxcT3Lc.mjs";
+import { _ as wireKids, a as listBoardFiles, c as BOARD_NAME, g as validateWire, h as readTitle, i as isRegularFile, l as FOLDERS_FILE, m as readDescription, n as checkBoardsDir, o as nodeExists, s as readRegistry, t as boardFields, v as hash } from "./boards-BwiDAmPf.mjs";
 import { n as localProfile, t as isConnected } from "./profile-BjAPAJSb.mjs";
-import { c as loadConfig, i as setSceneTitle, n as isNoteFile, o as writeManifest, r as scanFrames, t as affectedFrameIds } from "./manifest-B01PSyDc.mjs";
+import { c as loadConfig, i as setSceneTitle, n as isNoteFile, o as writeManifest, r as scanFrames, t as affectedFrameIds } from "./manifest-mMfUhPtL.mjs";
 import { copyFileSync, existsSync, linkSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -261,6 +261,7 @@ function apiMiddleware(root, opts = {}) {
 				}
 				const reg = readRegistry(boardsDir);
 				if (reg.state === "malformed") return json(res, 422, { error: reg.error });
+				if (reg.state === "ok" && reg.folders.some((f) => f.parent) && parsed.protocol !== 2) return json(res, 422, { error: "this tab predates folders in folders - reload the canvas, then try again" });
 				if (reg.sha256 !== b.folders) return json(res, 409, {
 					error: "folders changed on disk",
 					stale: [FOLDERS_FILE]
@@ -300,23 +301,29 @@ function apiMiddleware(root, opts = {}) {
 					return null;
 				};
 				const folders = [];
-				for (const [i, it] of tree.entries()) {
-					if (typeof it === "string") {
-						const e = consider(it, i, null);
-						if (e) return json(res, 422, { error: e });
-						continue;
-					}
-					const title = readTitle(it.title), description = readDescription(it.description);
-					folders.push({
-						name: it.folder,
-						order: i,
-						...title ? { title } : {},
-						...description ? { description } : {}
-					});
-					for (const [j, kid] of it.boards.entries()) {
-						const e = consider(kid, j, it.folder);
-						if (e) return json(res, 422, { error: e });
+				const walk = (list, parent) => {
+					for (const [i, it] of list.entries()) {
+						if (typeof it === "string") {
+							const e = consider(it, i, parent);
+							if (e) return e;
+							continue;
+						}
+						const title = readTitle(it.title), description = readDescription(it.description);
+						folders.push({
+							name: it.folder,
+							order: i,
+							...parent ? { parent } : {},
+							...title ? { title } : {},
+							...description ? { description } : {}
+						});
+						const e = walk(wireKids(it), it.folder);
+						if (e) return e;
 					}
+					return null;
+				};
+				{
+					const e = walk(tree, null);
+					if (e) return json(res, 422, { error: e });
 				}
 				if (stale.length) return json(res, 409, {
 					error: "boards changed on disk",
@@ -335,8 +342,9 @@ function apiMiddleware(root, opts = {}) {
 				mkdirSync(boardsDir, { recursive: true });
 				let foldersSha = null;
 				if (folders.length) {
+					const version = folders.some((f) => f.parent) ? 2 : 1;
 					const next = JSON.stringify({
-						version: 1,
+						version,
 						folders
 					}, null, 2) + "\n";
 					atomicWrite(foldersPath, next);
@@ -422,7 +430,7 @@ function apiMiddleware(root, opts = {}) {
 				};
 				const asPng = url.searchParams.get("format") === "png";
 				const origin = opts.origin?.() ?? `http://${req.headers.host ?? "localhost"}`;
-				const { shootFrame } = await import("./shot-DMDvDbeP.mjs");
+				const { shootFrame } = await import("./shot-DswS4iRK.mjs");
 				const r = await shootFrame({
 					root,
 					viewports: opts.viewports ?? {},
@@ -472,7 +480,7 @@ function apiMiddleware(root, opts = {}) {
 				if (typeof theme !== "string" || !/^[a-z0-9-]+$/i.test(theme)) return json(res, 400, { error: "invalid theme" });
 				const scale = body.scale === void 0 ? void 0 : body.scale;
 				if (scale !== void 0 && !(Number.isInteger(scale) && scale >= 1 && scale <= 4)) return json(res, 400, { error: "invalid scale" });
-				const { resolveFrames, shootBatch } = await import("./shot-DMDvDbeP.mjs");
+				const { resolveFrames, shootBatch } = await import("./shot-DswS4iRK.mjs");
 				const sel = resolveFrames(root, body);
 				if (!sel.ok) return json(res, sel.status, { error: sel.error });
 				const origin = opts.origin?.() ?? `http://${req.headers.host ?? "localhost"}`;
@@ -500,7 +508,7 @@ function apiMiddleware(root, opts = {}) {
 					return json(res, 400, { error: "malformed JSON" });
 				}
 				if (!body || typeof body !== "object" || !Array.isArray(body.asks) || !body.asks.length || body.asks.length > 200) return json(res, 400, { error: "asks must list 1-200 frames" });
-				const { bakeBatch, ASK_MAX } = await import("./bake-kaf5kGZ7.mjs");
+				const { bakeBatch, ASK_MAX } = await import("./bake-BID6mo-N.mjs");
 				let manifest = {};
 				try {
 					manifest = JSON.parse(readFileSync(join(root, "design", "manifest.json"), "utf8"));
@@ -544,8 +552,8 @@ function apiMiddleware(root, opts = {}) {
 			if (path === "poster" && req.method === "GET") {
 				if (!ownerGated(req)) return json(res, 403, { error: "forbidden" });
 				const src = url.searchParams.get("src") ?? "";
-				const { ensurePoster, isLocalClip } = await import("./poster-DNh6N27C.mjs");
-				const { isLocalAssetRef } = await import("./build-7ed5H2vT.mjs");
+				const { ensurePoster, isLocalClip } = await import("./poster-BvxiAzy1.mjs");
+				const { isLocalAssetRef } = await import("./build-C7MqQ7hq.mjs");
 				if (!isLocalAssetRef(src) || !isLocalClip(src)) return json(res, 400, { error: "src must be a clip under design/assets/" });
 				const r = await ensurePoster(join(root, "design", "assets"), src);
 				if (!r.ok) return json(res, r.error.includes("does not exist") ? 404 : 503, { error: r.error });
@@ -1027,7 +1035,7 @@ function marverPlugin(ctx) {
 			};
 			const prune = () => setTimeout(async () => {
 				try {
-					(await import("./bake-kaf5kGZ7.mjs")).pruneBakes(root, bakeGen);
+					(await import("./bake-BID6mo-N.mjs")).pruneBakes(root, bakeGen);
 				} catch {}
 			}, 500);
 			prune();
@@ -1166,7 +1174,7 @@ function marverPlugin(ctx) {
 								});
 								return;
 							}
-							const { shootFrame, shootBatch, resolveFrames } = await import("./shot-DMDvDbeP.mjs");
+							const { shootFrame, shootBatch, resolveFrames } = await import("./shot-DswS4iRK.mjs");
 							if (ways[0] === "frame") {
 								if (typeof spec.frame !== "string") {
 									write({

package/dist/{poster-DNh6N27C.mjs → poster-BvxiAzy1.mjs}

@@ -1,4 +1,4 @@
-import { capture, t as findChrome } from "./shot-DMDvDbeP.mjs";
+import { capture, t as findChrome } from "./shot-DswS4iRK.mjs";
 import { constants, copyFileSync, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { pathToFileURL } from "node:url";

package/dist/{publish-bakes-Dp-ZFk3d.mjs → publish-bakes-BqzAAa3w.mjs}

@@ -1,5 +1,6 @@
-import { planShot, t as findChrome } from "./shot-DMDvDbeP.mjs";
-import { ASK_MAX, bakeBatch } from "./bake-kaf5kGZ7.mjs";
+import { o as slideSize } from "./cli.mjs";
+import { planShot, t as findChrome } from "./shot-DswS4iRK.mjs";
+import { ASK_MAX, bakeBatch } from "./bake-BID6mo-N.mjs";
 import { MIME } from "./serve-z5qtj_wJ.mjs";
 import { copyFileSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { extname, isAbsolute, join, relative, resolve } from "node:path";
@@ -43,6 +44,11 @@ function publishedAsks(boards, themes, frames, viewports, allScenes = false) {
 		}
 	};
 	const size = (f, n) => {
+		const sl = slideSize(f, viewports);
+		if (sl) return {
+			w: sl.width,
+			h: sl.height
+		};
 		const nw = n && typeof n.w === "number" && n.w > 0 ? n.w : void 0, nh = n && typeof n.h === "number" && n.h > 0 ? n.h : void 0;
 		const p = planShot(f, viewports, {});
 		if (p.fullHeight && !nh) return null;

package/dist/{shot-DMDvDbeP.mjs → shot-DswS4iRK.mjs}

@@ -283,16 +283,16 @@ function planShot(frame, viewports, override = {}) {
 	const cw = num(frame.contentWidth);
 	const vpObj = frame.viewport ? viewports[frame.viewport] : void 0;
 	const ow = num(override.w), oh = num(override.h);
-	const sl = slideSize(frame);
+	const fallback = viewports.mobile ?? {
+		width: 390,
+		height: 844
+	};
+	const sl = slideSize(frame, viewports);
 	if (sl) return {
 		width: sl.width,
 		initialHeight: sl.height,
 		fullHeight: false
 	};
-	const fallback = viewports.mobile ?? {
-		width: 390,
-		height: 844
-	};
 	if (cw) {
 		const width = clamp(ow ?? vpObj?.width ?? cw, 320, 1600);
 		return {
@@ -337,8 +337,8 @@ async function shootFrame(opts) {
 	};
 	const plan = planShot(frame, viewports, size);
 	if (frame.kind !== "html") try {
-		const { scanAssetRefs } = await import("./build-7ed5H2vT.mjs");
-		const { ensurePoster } = await import("./poster-DNh6N27C.mjs");
+		const { scanAssetRefs } = await import("./build-C7MqQ7hq.mjs");
+		const { ensurePoster } = await import("./poster-BvxiAzy1.mjs");
 		const refs = scanAssetRefs(readFileSync(join(root, frame.file), "utf8"), frame.file);
 		for (const r of refs) if (r.endsWith(".poster.png")) await ensurePoster(join(root, "design", "assets"), r.slice(0, -11));
 	} catch {}

package/docs/live-jam.md

@@ -105,7 +105,7 @@ obvious one:
   scale}` for humans and shell-ful agents - the same renderer, one line. A batch is ONE
   operation: one headless browser, `MARVER_SHOT_CONCURRENCY` frames at a time inside it
   (default up to 6, sized to the machine), so a scene costs about what a frame does. Default
-  2x; `--scale 4` for a print-quality still (a slide comes back 5120×2880). A frame too tall
+  2x; `--scale 4` for a print-quality still (a 1280×720 slide comes back 5120×2880). A frame too tall
   for the asked scale steps down and says so in `note`; the file name carries the scale
   actually used (`…@4x.png`). A frame that ran out of settle budget still ships, marked
   `unsettled` with a note.

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

@@ -44,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.2",
+  "version": "0.21.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,