@marver-design/marver 0.18.0 → 0.19.1

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## 0.19.1 - 2026-09-08
+
+### Fixed
+
+- **A note landing on a composed board makes its own room.** 0.19.0 reserved a note's width only
+  when tidy ran; a note file added to a board that already had saved positions stood on its left
+  neighbour until someone pressed `t`. A board with a recipe (or the auto board) now re-applies
+  its layout when a note has no room - as the file lands while the board is open, and at load
+  when it landed while the board was closed - and saves the result. Boards dragged by hand keep
+  their positions, as before. A deleted frame's card counts as an obstacle; a drag inside the
+  reflow's debounce is never overwritten. The agent instructions say it plainly: placement is
+  the canvas's job, write the file.
+
+## 0.19.0 - 2026-09-08
+
+### Added
+
+- **Sticky notes.** A markdown file beside a frame (`cart.note.md` next to `cart.tsx`, `.jsx` or
+  `.html`) or a scene (`_note.md` in the scene directory) renders as a yellow note left of the
+  frame on the canvas - the scene's on the scene's first frame of the board, above the frame's
+  own. Markdown with the Md block's rules (`goto:` links jump to a frame, images from
+  `design/assets/`, raw HTML inert) and ` ```mermaid ` fences drawn hand-drawn. Comments pin on a
+  note's elements as on a frame's; a folded note parks its pins on its tab. Tidy keeps room for
+  notes. Every viewer folds a note at its corner and hides all with `N`; the choice stays in the
+  browser, never in the board file. Published and shared canvases carry the notes, their images
+  copied like any Md image. An edit to a note file updates the sticky in place; the frame is never
+  reloaded. Every diagram family wears the note's look - flowchart, sequence, state, class, ER,
+  pie, mindmap, timeline, gantt, journey, quadrant, git graph, block: hand-sketched boxes, one
+  yellow palette, handwriting labels (the Diagram block in content frames keeps its own theme).
+
+### Changed
+
+- The manifest carries `note` on frames and scenes; the dev watcher regenerates it when a note
+  file changes.
+- The agent contract (`design/AGENTS.md`, refreshed by `npx marver init`) and
+  `instructions/shape.md` teach sticky notes: what one is, when to write one, what it supports
+  (markdown, tables, `goto:` links, images, hand-drawn mermaid) and how it works.
+- Markdown in content frames: text inside a raw `<script>`/`<style>` block is now escaped like
+  every other text, and the rendered HTML passes a tag and attribute allowlist before insertion.
+  Diagram source is judged after decoding escapes; image shapes and directives are refused.
+
 ## 0.18.0 - 2026-09-07
 
 ### Changed

package/README.md

@@ -8,7 +8,7 @@
 
 Screens, prototypes, specs, and now slide decks - all real code, all on one canvas, all shareable with people who sign in as themselves.
 
-[marver.design](https://marver.design) · [Slides](docs/slides.md) · [Live Jam](docs/live-jam.md) · [Deploying a canvas](docs/publish.md) · [Sharing](docs/sharing.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Issues](https://github.com/TNEP4/marver/issues)
+[marver.design](https://marver.design) · [Slides](docs/slides.md) · [Sticky notes](docs/sticky-notes.md) · [Live Jam](docs/live-jam.md) · [Deploying a canvas](docs/publish.md) · [Sharing](docs/sharing.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Issues](https://github.com/TNEP4/marver/issues)
 
 ## Quickstart
 
@@ -45,6 +45,7 @@ Frames appear on the canvas the moment the files land. That's the loop.
 - **Prototype links.** `data-goto="scene/frame"` on any element links frames into a walkable prototype - across boards, too.
 - **Five ways to view a board.** The canvas (frames on a plane), the board (the same, tidy), **present** (`p`: a full-screen clickable walkthrough - `data-goto` navigates, arrows step, `[` / `]` cycle variants, laser, comments, theme and device pickers in the toolbar), **focus** (one frame as a document - the reading preset for specs), and **slides** (a deck). A published board names its landing view; a frame deep link opens straight into it.
 - **Content frames.** Specs, Mermaid diagrams, mood boards, and slides live on the same canvas as the screens - import `Doc`, `Md`, `Diagram`, `Img`, `Slide`, `Chart`, `Video` from `@marver-design/marver/content` and think a feature through before any pixels exist. Works in a repo with no app at all: idea first, design second.
+- **Sticky notes.** A markdown file beside a frame (`cart.note.md`) or a scene (`_note.md`) becomes a yellow note left of the frame on the canvas - what it is for, how two variations differ, an open question. Markdown, `goto:` links to frames, hand-drawn Mermaid; readers comment on a note's text like on a frame's, fold it to its corner, hide them all with `n`. The layout makes room for it; published canvases carry them.
 - **Hi-fi at rest.** A frame at rest is its own live document, asleep: animations paused and every `backdrop-filter` element painted with a certified texture of its filtered backdrop (compiled by the dev server's headless Chrome), so a board of 30 glass screens pans like 30 statics and wakes pixel-identical on interact. Glass inside glass, blend modes and frames whose paint depends on random data or the clock stay live; `?awake=1` keeps every frame live for comparison.
 - **Charts and video in any frame.** `Chart` (Apache ECharts, SVG, still at rest) inherits the ink, typeface and accent of whatever frame it sits in - a Tailwind dashboard, a dark spec, a slide - sizes its type to the context and follows the layout on resize. `Video` is poster-first everywhere: click to play wherever the frame is live, `autoplay` for an ambient loop, `ratio` for vertical clips; omit the poster and marver renders one from the clip. A screen with a chart or a clip is still a screen.
 - **Copy as image.** Select a frame, press `i` - a 2x PNG of it lands on the clipboard, rendered by the same headless Chrome that serves `marver shot`; `⇧i` for 4x (a slide is 5120×2880). Paste into Slack, a doc, or a chat with your agent.

package/dist/{bake-jr38C_pX.mjs → bake-kaf5kGZ7.mjs}

@@ -1,4 +1,4 @@
-import { AREA, SURFACE, pool, shotConcurrency, withBrowser } from "./shot-iicees2e.mjs";
+import { AREA, SURFACE, pool, shotConcurrency, withBrowser } from "./shot-DMDvDbeP.mjs";
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
 import { join, sep } from "node:path";
 import { createHash } from "node:crypto";

package/dist/{build-ER_7T6Cw.mjs → build-7ed5H2vT.mjs}

@@ -1,13 +1,14 @@
 import { a as ROUTE, r as NAME } from "./cli.mjs";
 import { a as listBoardFiles, d as flatten, f as isBoardName, n as checkBoardsDir, s as readRegistry, t as boardFields, u as buildTree } from "./boards-BmxcT3Lc.mjs";
-import { l as detectHost, n as scanFrames, s as loadConfig } from "./manifest-DAnEL8_a.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-Cai5C1WV.mjs";
+import { c as loadConfig, r as scanFrames, u as detectHost } from "./manifest-B01PSyDc.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DI-7NAnx.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createHash, randomBytes } from "node:crypto";
 import { build } from "vite";
 import react from "@vitejs/plugin-react";
+import { Marked } from "marked";
 //#region src/server/css-fix.ts
 /** Every `-webkit-backdrop-filter` declaration (the property itself, never a custom property that
 *  happens to end in it) is mirrored by the standard one right after it, in order, importance and
@@ -193,7 +194,37 @@ function scanAssetRefs(src, moduleId) {
 		}
 		if (posterM) out.push(posterM[1]);
 	}
-	for (const tpl of templates) for (const m of tpl.matchAll(/!\[[^\]]*\]\(([^)\s"']+)\)/g)) out.push(m[1]);
+	for (const tpl of templates) out.push(...markdownImageRefs(tpl.slice(1, -1)));
+	return out;
+}
+/** Markdown images in prose, through the parser: inline and reference-style, titles and
+*  parentheses in paths handled, code never counted. Decoded the way the client's assetUrl
+*  decodes (one pass; a path still carrying `%` is refused there and skipped here). Md content
+*  inside frames and sticky notes alike. */
+function markdownImageRefs(md) {
+	const out = [];
+	const walk = (tokens) => {
+		for (const t of tokens) {
+			if (t.type === "image" && typeof t.href === "string") {
+				let p = t.href.trim();
+				try {
+					p = decodeURIComponent(p);
+				} catch {
+					continue;
+				}
+				if (!p.includes("%")) out.push(p);
+			}
+			if (t.type !== "code" && t.type !== "codespan") {
+				if (Array.isArray(t.tokens)) walk(t.tokens);
+				if (Array.isArray(t.items)) walk(t.items);
+				if (Array.isArray(t.rows)) for (const row of t.rows) walk(row.map((c) => ({ tokens: c.tokens })));
+				if (Array.isArray(t.header)) walk(t.header.map((c) => ({ tokens: c.tokens })));
+			}
+		}
+	};
+	try {
+		walk(new Marked({ gfm: true }).lexer(md));
+	} catch {}
 	return out;
 }
 /** Same shape the client's assetUrl accepts: relative, inside design/assets/, no tricks. */
@@ -335,12 +366,13 @@ function publishedManifest(manifest, pubFrames, publishedNames, strip) {
 		...manifest.project ? { project: manifest.project } : {},
 		...pubFolders.length ? { folders: pubFolders } : {},
 		...pubBoards.length ? { boards: pubBoards } : {},
-		scenes: manifest.scenes.filter((s) => pubScenes.has(s.name)).map(({ name, title, description, brief }) => ({
+		scenes: manifest.scenes.filter((s) => pubScenes.has(s.name)).map(({ name, title, description, brief, note }) => ({
 			name,
 			frames: pubFrames.filter((f) => f.scene === name).length,
 			...title ? { title } : {},
 			...description ? { description } : {},
-			...brief && !strip ? { brief } : {}
+			...brief && !strip ? { brief } : {},
+			...note ? { note } : {}
 		})),
 		frames: pubFrames
 	};
@@ -646,11 +678,12 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds, textures =
 		const rel = file.startsWith(rootP + "/") ? file.slice(rootP.length + 1) : file;
 		for (const r of scanAssetRefs(src, rel)) refs.add(r);
 	}
+	for (const note of [...pubManifest.frames.map((f) => f.note), ...pubManifest.scenes.map((s) => s.note)]) if (note) for (const r of markdownImageRefs(note)) refs.add(r);
 	let copiedAssets = 0;
 	const realAssets = existsSync(assetsDir) ? realpathSync(assetsDir) : null;
 	for (const r of refs) {
 		if (!isLocalAssetRef(r) || !r.endsWith(".poster.png") || existsSync(join(assetsDir, r))) continue;
-		const { ensurePoster } = await import("./poster-CIuz_PwH.mjs");
+		const { ensurePoster } = await import("./poster-DNh6N27C.mjs");
 		const g = await ensurePoster(assetsDir, r.slice(0, -11));
 		if (!g.ok) throw new Error(`design/assets/${r}: ${g.error}`);
 		console.log(`  poster: rendered design/assets/${r} (${g.width}×${g.height})`);
@@ -717,7 +750,7 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds, textures =
 	}));
 	let textureLine = "  textures: skipped (--no-textures)";
 	if (textures && bakeGen) {
-		const { bakePublished } = await import("./publish-bakes-D0LhbQQ3.mjs");
+		const { bakePublished } = await import("./publish-bakes-Dp-ZFk3d.mjs");
 		const pubFrameFile = new Map(pubFrames.map((f) => [f.id, f]));
 		const r = await bakePublished({
 			root,

package/dist/cli.mjs

@@ -72,14 +72,14 @@ const resolve$1 = (dir) => {
 };
 const cli = cac(NAME);
 cli.command("init", "Scaffold design/ in this repo").option("--mode <mode>", "studio | embedded", { default: "studio" }).option("--no-demo", "Skip the demo scene (the demo ships unless this flag is passed)").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { init } = await import("./init-BWbHqVng.mjs");
+	const { init } = await import("./init-BQYCS3EU.mjs");
 	init(resolve$1(opts.root), {
 		mode: opts.mode === "embedded" ? "embedded" : "studio",
 		demo: opts.demo !== false
 	});
 });
 for (const [name, desc] of [["dev", "Start the local canvas (everything on: hot reload, comments, Live Jam)"], ["canvas", "Start the local canvas - same as dev"]]) cli.command(name, desc).option("--root <dir>", "Host repo root", { default: "." }).option("--port <port>", "Port (default 5199)").action(async (opts) => {
-	const { dev } = await import("./dev-BvLbY98O.mjs");
+	const { dev } = await import("./dev-D3mP2x27.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -89,7 +89,7 @@ for (const [name, desc] of [["dev", "Start the local canvas (everything on: hot
 	await dev(resolve$1(opts.root), port);
 });
 cli.command("build", "Static export → design/.dist (what ships comes from design/publish.json - publishing is default-closed)").option("--boards <names>", "Publish only these boards (comma-separated); overrides the publish policy").option("--all-boards", "Publish every board - the loud override for the default-closed policy").option("--embed-seeds", "Copy comment history INTO the web root (identifying - every event carries its author's email)").option("--no-textures", "Skip compiling the glass textures the published frames rest under (needs Chrome; a CI without one skips on its own)").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { buildSite } = await import("./build-ER_7T6Cw.mjs");
+	const { buildSite } = await import("./build-7ed5H2vT.mjs");
 	try {
 		const boards = opts.boards === void 0 ? void 0 : typeof opts.boards === "string" ? opts.boards : "";
 		await buildSite(resolve$1(opts.root), boards, opts.allBoards === true, opts.embedSeeds === true, opts.textures !== false && !process.env.MARVER_NO_TEXTURES);

package/dist/{daemon-CKhg0zuT.mjs → daemon-DbHvLQUL.mjs}

@@ -1,7 +1,7 @@
 import { n as replay } from "./events-B3LBn74P.mjs";
 import { i as readLog, r as listBoards, t as appendEvents } from "./comments-DZyobpxG.mjs";
 import { n as localProfile } from "./profile-BjAPAJSb.mjs";
-import { i as toFrameId } from "./manifest-DAnEL8_a.mjs";
+import { a as toFrameId } from "./manifest-B01PSyDc.mjs";
 import { workActivity } from "./work-CLrmY-vQ.mjs";
 import { r as deviceId, t as has } from "./ledger-Bu0BjqIe.mjs";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, watch, writeFileSync, writeSync } from "node:fs";

package/dist/{dev-BvLbY98O.mjs → dev-D3mP2x27.mjs}

@@ -1,6 +1,6 @@
 import { i as PKG, r as NAME } from "./cli.mjs";
-import { l as detectHost, s as loadConfig } from "./manifest-DAnEL8_a.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-Cai5C1WV.mjs";
+import { c as loadConfig, u as detectHost } from "./manifest-B01PSyDc.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DI-7NAnx.mjs";
 import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -437,6 +437,7 @@ async function dev(root, portFlag) {
 				"react/jsx-dev-runtime",
 				`${PKG} > marked`,
 				`${PKG} > mermaid`,
+				`${PKG} > roughjs`,
 				`${PKG} > html-to-image`,
 				...iconModules(root)
 			],
@@ -451,12 +452,12 @@ async function dev(root, portFlag) {
 	console.log(`\n  ${NAME} · ${projectName} → http://localhost:${port}/\n`);
 	setTimeout(async () => {
 		try {
-			await (await import("./shot-iicees2e.mjs")).sweepGhosts((m) => console.log(`  ${m}`));
+			await (await import("./shot-DMDvDbeP.mjs")).sweepGhosts((m) => console.log(`  ${m}`));
 		} catch {}
 	}, 0);
 	try {
 		const { staleManagedInstructions } = await import("./managed-HwHVNI3h.mjs");
-		const { installedVersion } = await import("./plugin-Cai5C1WV.mjs").then((n) => n.i);
+		const { installedVersion } = await import("./plugin-DI-7NAnx.mjs").then((n) => n.i);
 		const stale = staleManagedInstructions(root);
 		if (stale.length) {
 			const shown = stale.slice(0, 4).join(", ") + (stale.length > 4 ? `, +${stale.length - 4} more` : "");
@@ -494,7 +495,7 @@ async function dev(root, portFlag) {
 		});
 	}
 	if (config.jam) {
-		const { startJam } = await import("./daemon-CKhg0zuT.mjs");
+		const { startJam } = await import("./daemon-DbHvLQUL.mjs");
 		const jam = startJam(root, config.jam, (m) => console.log(m), (board) => server.ws.send("sh:jam-comment", { board }));
 		if (jam) {
 			const close = server.close.bind(server);

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

@@ -1,5 +1,5 @@
 import { r as NAME } from "./cli.mjs";
-import { a as writeManifest, c as detectAgent, l as detectHost, n as scanFrames, o as DEFAULTS, u as readJson } from "./manifest-DAnEL8_a.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 { 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";

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

@@ -375,6 +375,23 @@ function validViewports(v) {
 //#region src/server/manifest.ts
 const FRAME_EXT = /\.(tsx|jsx|html)$/;
 const RESERVED_SCENES = /* @__PURE__ */ new Set(["components", "screens"]);
+/** Sticky notes (spec 18): the longest note the manifest carries - a note is an aside, not a spec. */
+const NOTE_MAX = 2e4;
+/** The note file beside a frame file: `cart.tsx` -> `cart.note.md`; a scene's is `_note.md`. */
+const noteFileFor = (frameFile) => frameFile.replace(FRAME_EXT, ".note.md");
+/** Is this path a note file - the dev watcher's "regenerate on change" predicate. */
+const isNoteFile = (file) => /(^|[\\/])(_note|[^\\/]+\.note)\.md$/.test(file);
+/** A note's text: BOM stripped, trimmed, capped at NOTE_MAX. Undefined when the file is missing,
+*  empty, or not a regular file (a symlink is never followed - the `_brief.md` rule). */
+function readNote(abs) {
+	try {
+		if (!lstatSync(abs).isFile()) return void 0;
+		const text = readFileSync(abs, "utf8").replace(/^/, "").trim();
+		return text ? text.slice(0, NOTE_MAX) : void 0;
+	} catch {
+		return;
+	}
+}
 /** Extract `export const meta = {...}` with literal string values only. Anything else is silently omitted. */
 function extractMeta(src) {
 	const m = /export\s+const\s+meta\s*=\s*\{([\s\S]*?)\}/.exec(src);
@@ -526,6 +543,10 @@ function sceneBrief(root, scene) {
 		...description ? { description } : {}
 	};
 }
+/** A scene's sticky note: `design/scenes/<scene>/_note.md` (spec 18). */
+function sceneNote(root, scene) {
+	return scene ? readNote(join(root, "design", "scenes", scene, "_note.md")) : void 0;
+}
 /** Write a scene's title into its brief's front matter - only that line changes; the body,
 *  every other field and the file's own line endings are kept. No brief yet = a front-matter-only
 *  brief. An empty title removes the line, and the file when nothing else is in it. The write
@@ -649,6 +670,8 @@ function scanFrames(root, project) {
 			kind,
 			scene
 		};
+		const note = readNote(noteFileFor(abs));
+		if (note) entry.note = note;
 		if (kind === "tsx") {
 			const src = readFileSync(abs, "utf8");
 			const meta = extractMeta(src);
@@ -684,11 +707,15 @@ function scanFrames(root, project) {
 	inferVariantGroups(frames);
 	const sceneCounts = /* @__PURE__ */ new Map();
 	for (const f of frames) sceneCounts.set(f.scene, (sceneCounts.get(f.scene) ?? 0) + 1);
-	const scenes = [...sceneCounts.entries()].map(([name, n]) => ({
-		name,
-		frames: n,
-		...sceneBrief(root, name)
-	})).sort((a, b) => a.name.localeCompare(b.name));
+	const scenes = [...sceneCounts.entries()].map(([name, n]) => {
+		const note = sceneNote(root, name);
+		return {
+			name,
+			frames: n,
+			...sceneBrief(root, name),
+			...note ? { note } : {}
+		};
+	}).sort((a, b) => a.name.localeCompare(b.name));
 	return {
 		...project && (project.name || project.description) ? { project: {
 			...project.name ? { name: project.name } : {},
@@ -779,4 +806,4 @@ function writeManifest(root, manifest) {
 	return true;
 }
 //#endregion
-export { writeManifest as a, detectAgent as c, toFrameId as i, detectHost as l, scanFrames as n, DEFAULTS as o, setSceneTitle as r, loadConfig as s, affectedFrameIds as t, readJson as u };
+export { toFrameId as a, loadConfig as c, readJson as d, setSceneTitle as i, detectAgent as l, isNoteFile as n, writeManifest as o, scanFrames as r, DEFAULTS as s, affectedFrameIds as t, detectHost as u };

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

@@ -2,7 +2,7 @@ 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 { n as localProfile, t as isConnected } from "./profile-BjAPAJSb.mjs";
-import { a as writeManifest, n as scanFrames, r as setSceneTitle, s as loadConfig, t as affectedFrameIds } from "./manifest-DAnEL8_a.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 { 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";
@@ -422,7 +422,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-iicees2e.mjs");
+				const { shootFrame } = await import("./shot-DMDvDbeP.mjs");
 				const r = await shootFrame({
 					root,
 					viewports: opts.viewports ?? {},
@@ -472,7 +472,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-iicees2e.mjs");
+				const { resolveFrames, shootBatch } = await import("./shot-DMDvDbeP.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 +500,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-jr38C_pX.mjs");
+				const { bakeBatch, ASK_MAX } = await import("./bake-kaf5kGZ7.mjs");
 				let manifest = {};
 				try {
 					manifest = JSON.parse(readFileSync(join(root, "design", "manifest.json"), "utf8"));
@@ -544,8 +544,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-CIuz_PwH.mjs");
-				const { isLocalAssetRef } = await import("./build-ER_7T6Cw.mjs");
+				const { ensurePoster, isLocalClip } = await import("./poster-DNh6N27C.mjs");
+				const { isLocalAssetRef } = await import("./build-7ed5H2vT.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 +1027,7 @@ function marverPlugin(ctx) {
 			};
 			const prune = () => setTimeout(async () => {
 				try {
-					(await import("./bake-jr38C_pX.mjs")).pruneBakes(root, bakeGen);
+					(await import("./bake-kaf5kGZ7.mjs")).pruneBakes(root, bakeGen);
 				} catch {}
 			}, 500);
 			prune();
@@ -1046,7 +1046,7 @@ function marverPlugin(ctx) {
 					rescanTheme();
 				}
 			});
-			server.watcher.on("change", (f) => inScope(f) && (/\.(tsx|jsx)$/.test(f) || f.endsWith("_brief.md")) && regen());
+			server.watcher.on("change", (f) => inScope(f) && (/\.(tsx|jsx)$/.test(f) || f.endsWith("_brief.md") || isNoteFile(f)) && regen());
 			const configFile = join(root, "design", "config.ts");
 			server.watcher.on("change", (f) => {
 				if (f !== configFile) return;
@@ -1166,7 +1166,7 @@ function marverPlugin(ctx) {
 								});
 								return;
 							}
-							const { shootFrame, shootBatch, resolveFrames } = await import("./shot-iicees2e.mjs");
+							const { shootFrame, shootBatch, resolveFrames } = await import("./shot-DMDvDbeP.mjs");
 							if (ways[0] === "frame") {
 								if (typeof spec.frame !== "string") {
 									write({

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

@@ -1,4 +1,4 @@
-import { capture, t as findChrome } from "./shot-iicees2e.mjs";
+import { capture, t as findChrome } from "./shot-DMDvDbeP.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-D0LhbQQ3.mjs → publish-bakes-Dp-ZFk3d.mjs}

@@ -1,5 +1,5 @@
-import { planShot, t as findChrome } from "./shot-iicees2e.mjs";
-import { ASK_MAX, bakeBatch } from "./bake-jr38C_pX.mjs";
+import { planShot, t as findChrome } from "./shot-DMDvDbeP.mjs";
+import { ASK_MAX, bakeBatch } from "./bake-kaf5kGZ7.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";

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

@@ -337,8 +337,8 @@ async function shootFrame(opts) {
 	};
 	const plan = planShot(frame, viewports, size);
 	if (frame.kind !== "html") try {
-		const { scanAssetRefs } = await import("./build-ER_7T6Cw.mjs");
-		const { ensurePoster } = await import("./poster-CIuz_PwH.mjs");
+		const { scanAssetRefs } = await import("./build-7ed5H2vT.mjs");
+		const { ensurePoster } = await import("./poster-DNh6N27C.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/sticky-notes.md

@@ -0,0 +1,49 @@
+# Sticky notes
+
+A sticky note is the aside beside a frame: a yellow note left of it on the canvas, in dev and on
+every published or shared canvas, that says what the screen cannot - what the frame is for, how
+two variations differ, how a mechanism works, an open question. Reviewers read it, click its links,
+and comment on its text exactly as they comment on a frame.
+
+## Writing one
+
+One markdown file, nothing to declare:
+
+| For | File |
+|---|---|
+| a frame `checkout/cart` (`cart.tsx`, `.jsx` or `.html`) | `design/scenes/checkout/cart.note.md` |
+| a scene `checkout` | `design/scenes/checkout/_note.md` (beside the scene's first frame on the board) |
+| a component frame | `design/components/<name>.note.md` |
+
+Markdown with the Md block's rules: headings, lists, tables, emphasis, code; `[text](goto:scene/frame)`
+links jump to a frame; `http(s)` links open a new tab; images come from `design/assets/`; raw HTML is
+inert. A scene note is 380 wide, a frame note 260; when a frame has both, they stack in one column,
+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.
+
+## Diagrams
+
+A ```mermaid fence renders hand-sketched on the paper: rough boxes, hatched fills, handwriting
+labels, one ink. Write plain mermaid - no `%%{init}%%`, theme, colours or `style` lines, no URLs or
+images in the source. Every family works; flowchart, sequence, state, class, ER, pie and mindmap
+read best at note width, while gantt, journey, timeline, quadrant and git graphs are wide by nature
+and want few items. This look is the note's alone: the `Diagram` block in content frames keeps its
+own theme.
+
+## Reading one
+
+- Fold: the dog-ear at the note's corner folds the column to a tab; the tab brings it back.
+- `N` hides every note on the canvas and shows them again.
+- Both are per viewer, in the browser - never saved to the board, never shared.
+- 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.
+
+## What it is not
+
+A note is an aside, a screen's worth of reading at most. Specs, flows and mood boards stay content
+frames on the board.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "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,
@@ -53,6 +53,7 @@
     "marked": "^16.0.0",
     "mermaid": "^11.6.0",
     "react-zoom-pan-pinch": "^3.6.1",
+    "roughjs": "^4.6.6",
     "vite": "^8.0.0",
     "zustand": "^5.0.0"
   },

package/src/client/content/diagram.tsx

@@ -67,6 +67,32 @@ export function withFamilies(src: string): string {
   return `${src}\n${defs}`
 }
 
+/** The zero-external-request boundary, BEFORE render: mermaid's image shapes fetch their URL
+ *  during render(), so post-render SVG sanitizing alone is too late. Rejected: any URL shape
+ *  (scheme + // or scheme + \\, protocol-relative //), and the `img:` shape data of the
+ *  flowchart node syntax `A@{ img: ... }` - the one construct that loads a resource at all. */
+export function guardDiagramSource(src: string): void {
+  // judge the DECODED text: mermaid resolves \uXXXX, \xXX and HTML entities in shape data and
+  // labels before it acts on them, so an escaped `//` or a quoted, escaped `"img"` key is the
+  // same request in the end. Directives and front matter are gone by now (cleanSource) - a
+  // themeCSS with url() never reaches the renderer either way, url( is refused here too.
+  const text = decodeEscapes(src)
+  if (/(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(text) || /[a-z][a-z0-9+.-]*:\\/i.test(text)) throw new Error('URLs are not allowed in diagram source - use local design/assets/ images in an Img block instead')
+  if (/url\s*\(/i.test(text) || /@import\b/i.test(text)) throw new Error('external resources are not allowed in diagram source')
+  if (/@\s*\{/.test(text) && /["'`]?\s*img\s*["'`]?\s*:/i.test(text)) throw new Error('image shapes are not allowed in diagram source')
+  if (/%%\s*\{/.test(text) || /^\s*---/.test(text)) throw new Error('directives are not allowed in diagram source')
+}
+/** \uXXXX, \u{...}, \xXX and numeric/named HTML entities -> the characters they stand for. */
+export function decodeEscapes(src: string): string {
+  return src
+    .replace(/\\u\{([0-9a-f]{1,6})\}/gi, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+    .replace(/\\u([0-9a-f]{4})/gi, (_, h) => String.fromCharCode(parseInt(h, 16)))
+    .replace(/\\x([0-9a-f]{2})/gi, (_, h) => String.fromCharCode(parseInt(h, 16)))
+    .replace(/&#x([0-9a-f]{1,6});/gi, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+    .replace(/&#(\d{1,7});/g, (_, d) => String.fromCodePoint(Number(d)))
+    .replace(///gi, '/').replace(/\/gi, '\\').replace(/:/gi, ':').replace(/"/gi, '"').replace(/'/gi, "'")
+}
+
 /** Remove external URL references from rendered SVG (images, links, href attrs). */
 export function sanitizeSvg(svg: string): string {
   const doc = new DOMParser().parseFromString(svg, 'image/svg+xml')
@@ -100,7 +126,7 @@ export function Diagram({ title, children }: { title?: string; children?: ReactN
         // shapes fetch their URL during render(), so post-render SVG sanitizing alone
         // would be too late. Reject ANY URL shape - absolute (scheme://) and
         // protocol-relative (//host) alike; neither has a place in diagram source.
-        if (/(?:\w+:)?\/\//.test(src)) throw new Error('URLs are not allowed in diagram source - use local design/assets/ images in an Img block instead')
+        guardDiagramSource(src)
         const mermaid = (await import('mermaid')).default
         if (!live || mySeq !== seq) return
         mermaid.initialize({

package/src/client/content/index.tsx

@@ -10,7 +10,7 @@
 import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
 import { useInSlide } from './slide.tsx'
 import { CONTENT_WIDTH } from '../const.ts'
-import { assetUrl, renderMarkdown, FAMILIES } from './md.ts'
+import { assetUrl, renderMarkdown, sanitizeMarkdownHtml, FAMILIES } from './md.ts'
 import { lodSupported, registerLodImage } from './img-lod.ts'
 
 // D3: family color classes for inline Md (`:blue[...]`), theme-aware (frames carry .dark + [data-theme])
@@ -87,7 +87,7 @@ export function Space({ n = 1 }: { n?: number }) {
 export function Md({ children }: { children?: ReactNode }) {
   ensureStyles()
   const src = typeof children === 'string' ? children : Array.isArray(children) ? children.join('') : String(children ?? '')
-  const html = useMemo(() => renderMarkdown(src), [src])
+  const html = useMemo(() => sanitizeMarkdownHtml(renderMarkdown(src)), [src])
   return <div className="mv-md" dangerouslySetInnerHTML={{ __html: html }} />
 }
 

package/src/client/content/md.ts

@@ -7,6 +7,9 @@
 import { Marked } from 'marked'
 
 const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)
+/** Prose text: markup escaped, but an entity the author wrote (`&copy;`, `&#x41;`) keeps its
+ *  meaning - marked's own rule; a raw `<` is still never a tag. */
+const escapeText = (s: string) => s.replace(/&(?!#?\w+;)|[<>"']/g, (c) => `&#${c.charCodeAt(0)};`)
 
 /** D3: named color families for inline Md - the SAME families the diagrams use, so prose and
  *  the diagram beside it speak one color language. Theme pairs (light/dark). Bound to classes,
@@ -38,6 +41,12 @@ const marked = new Marked({
   renderer: {
     // raw HTML (block or inline) renders as its literal text - inert by construction
     html(token: any) { return escapeHtml(String(token.text ?? '')) },
+    // marked leaves the text INSIDE a raw block (<script>, <style>, <pre>, <textarea>) unescaped
+    // (`token.escaped`); here every text token is escaped - there is no raw block to serve
+    text(token: any) {
+      if (token.tokens) return this.parser.parseInline(token.tokens)
+      return escapeText(String(token.text ?? ''))
+    },
     link(token: any) {
       const href = String(token.href ?? '')
       const inner = this.parser.parseInline(token.tokens ?? [])
@@ -77,3 +86,42 @@ marked.use({
 export function renderMarkdown(src: string): string {
   return marked.parse(src, { async: false }) as string
 }
+
+// ---- the second gate: an allowlist over the rendered DOM ----------------------------------
+// renderMarkdown is built to emit only these; this pass makes that a property of the OUTPUT,
+// not of every renderer branch - the shell realm (sticky notes) is more privileged than a
+// frame, so the HTML it inserts is checked element by element, attribute by attribute.
+const TAGS = new Set(['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'ul', 'ol', 'li', 'blockquote', 'pre', 'code', 'strong', 'em', 'del', 's', 'a', 'img', 'hr', 'br', 'table', 'thead', 'tbody', 'tr', 'th', 'td', 'span', 'input', 'div', 'sup', 'sub'])
+export const ATTR_POLICY: Record<string, (v: string) => boolean> = {
+  href: (v) => v === '#' || /^https?:\/\//i.test(v) || /^mailto:/i.test(v),
+  // a frame id: any path text without markup, quotes, spaces or a scheme (ids are unicode-free
+  // by convention but not by law - `checkout/café` is a real id)
+  'data-goto': (v) => v.length > 0 && v.length <= 300 && !/[\s<>"'`:\\]/.test(v) && !v.split('/').some((seg) => seg === '..' || seg === ''),
+  target: (v) => v === '_blank',
+  rel: (v) => v === 'noopener noreferrer',
+  // exactly what assetUrl emits: inside design/assets, no traversal SEGMENT (`flow..png` is a name)
+  src: (v) => v.startsWith('/design/assets/') && !v.slice('/design/assets/'.length).split('/').some((seg) => seg === '..' || seg === '.' || seg === ''),
+  alt: () => true, title: () => true, loading: (v) => v === 'lazy',
+  class: (v) => v.split(' ').every((c) => /^(mv-|language-)[^\s"'<>]+$/.test(c)),
+  align: (v) => /^(left|center|right)$/.test(v),
+  type: (v) => v === 'checkbox', checked: () => true, disabled: () => true,
+  start: (v) => /^\d+$/.test(v), colspan: (v) => /^\d+$/.test(v), rowspan: (v) => /^\d+$/.test(v),
+}
+/** Rendered markdown -> the same HTML with every element and attribute outside the allowlist
+ *  removed (an element goes with its subtree; an attribute alone). Browser only (DOMParser). */
+export function sanitizeMarkdownHtml(html: string): string {
+  const doc = new DOMParser().parseFromString(`<body>${html}</body>`, 'text/html')
+  const walk = (el: Element) => {
+    for (const child of [...el.children]) {
+      if (!TAGS.has(child.tagName.toLowerCase())) { child.remove(); continue }
+      for (const a of [...child.attributes]) {
+        const ok = ATTR_POLICY[a.name]
+        if (!ok || !ok(a.value)) child.removeAttribute(a.name)
+      }
+      if (child.tagName === 'INPUT') child.setAttribute('disabled', '')
+      walk(child)
+    }
+  }
+  walk(doc.body)
+  return doc.body.innerHTML
+}