@marver-design/marver 0.17.0 → 0.19.0

package/dist/publish-bakes-Dp-ZFk3d.mjs

@@ -0,0 +1,216 @@
+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";
+import { createServer } from "node:http";
+//#region src/server/publish-bakes.ts
+/**
+* Textures at publish time (spec 16, published canvases).
+*
+* A published canvas is a static site with no compiler, so its glass stayed live and a shared hi-fi
+* board flashed on pan and zoom as before 0.18.0. Everything the compiler needs is known when the
+* site is built: the published boards, every node's frame and size on them, and the themes a
+* visitor can flip to. So the build serves design/.dist to itself on a loopback port, compiles every
+* (frame, theme, size) against the PUBLISHED document - the one visitors get, not the dev one - with
+* the same certification as the dev server (bake.ts), ships the certified textures under
+* design/.dist/__mv/bakes/<build>/ and writes one static index the shell reads instead of asking a
+* server. Anything the compiler refuses is simply absent from the index: that frame sleeps with the
+* pause alone, glass live, as today. No Chrome on the build machine: the note is printed and the
+* site ships without textures.
+*/
+/** The shell's plain key for an ask (sleep.ts keyOf): frame|theme|w|h. */
+const indexKey = (a) => `${a.frame}|${a.theme}|${Math.round(a.w)}|${Math.round(a.h)}`;
+/** Every (frame, theme, size) a visitor can rest on: each published board's nodes, sized the way
+*  the shell sizes them (the node's own size, else the frame's default), each theme; the published
+*  `all-scenes` board shows every frame at its default size. Sizes are rounded first, then held to
+*  the compiler's limits: an oversize node is skipped, never clamped to a document of another size. */
+function publishedAsks(boards, themes, frames, viewports, allScenes = false) {
+	const byId = new Map(frames.map((f) => [f.id, f]));
+	const seen = /* @__PURE__ */ new Map();
+	const add = (frame, w, h) => {
+		w = Math.round(w);
+		h = Math.round(h);
+		if (!(w >= 120) || !(h >= 80) || w > ASK_MAX.side || h > ASK_MAX.side || w * h > ASK_MAX.area) return;
+		for (const theme of themes.length ? themes : ["light"]) {
+			const ask = {
+				frame,
+				theme,
+				w,
+				h
+			};
+			seen.set(indexKey(ask), ask);
+		}
+	};
+	const size = (f, n) => {
+		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;
+		return {
+			w: nw ?? p.width,
+			h: nh ?? p.initialHeight
+		};
+	};
+	for (const b of Object.values(boards)) for (const n of b?.nodes ?? []) {
+		const f = typeof n?.frame === "string" ? byId.get(n.frame) : void 0;
+		const s = f && size(f, n);
+		if (s) add(f.id, s.w, s.h);
+	}
+	if (allScenes) for (const f of frames) {
+		const s = size(f);
+		if (s) add(f.id, s.w, s.h);
+	}
+	return [...seen.values()];
+}
+/** The index: only answers that certified at least one texture, and only their certified targets
+*  (a refused target's selector ships nothing); everything else is absent. */
+function publishedIndex(gen, answers) {
+	const out = {
+		gen,
+		answers: {}
+	};
+	for (const a of answers) {
+		if (!a.ok) continue;
+		const targets = a.targets.filter((t) => t.verified && t.texture);
+		if (targets.length) out.answers[indexKey(a)] = {
+			ok: true,
+			targets
+		};
+	}
+	return out;
+}
+/** Serve `dir` on a loopback port the way `marver serve` does (extensionless = index.html). */
+function serveDir(dir) {
+	const real = realpathSync(dir);
+	const server = createServer((req, res) => {
+		let path = "";
+		try {
+			path = decodeURIComponent(new URL(req.url ?? "/", "http://x").pathname);
+		} catch {
+			res.statusCode = 400;
+			return res.end();
+		}
+		if (path.endsWith("/")) path += "index.html";
+		let file = resolve(dir, path.slice(1));
+		try {
+			const r = realpathSync(file);
+			if (relative(real, r).startsWith("..") || isAbsolute(relative(real, r))) throw 0;
+			file = r;
+		} catch {
+			file = join(dir, "index.html");
+		}
+		if (!extname(file)) file = join(dir, "index.html");
+		try {
+			const c = readFileSync(file);
+			res.setHeader("content-type", MIME[extname(file)] ?? "application/octet-stream");
+			res.end(c);
+		} catch {
+			res.statusCode = 404;
+			res.end();
+		}
+	});
+	return new Promise((ok) => server.listen(0, "127.0.0.1", () => {
+		ok({
+			origin: `http://127.0.0.1:${server.address().port}`,
+			close: () => server.close()
+		});
+	}));
+}
+/** Compile the published boards' frames against the built site and ship the textures with it.
+*  Returns null when there is no Chrome to compile with. */
+async function bakePublished(opts) {
+	const { root, outDir, gen, boards, themes, frames, viewports, allScenes, urlFor, log } = opts;
+	if (!findChrome()) return null;
+	const t0 = Date.now();
+	const asks = publishedAsks(boards, themes, frames, viewports, allScenes).filter((a) => urlFor(a.frame, a.theme));
+	const stats = {
+		asked: asks.length,
+		asleep: 0,
+		live: 0,
+		plain: 0,
+		bytes: 0,
+		ms: 0
+	};
+	if (!asks.length) return stats;
+	const cache = join(root, "design", ".local", "bakes", String(gen));
+	const site = await serveDir(outDir);
+	let answers;
+	try {
+		answers = await bakeBatch({
+			root,
+			gen,
+			asks,
+			urlBase: "/__mv/bakes",
+			urlFor: (a) => site.origin + urlFor(a.frame, a.theme)
+		});
+		const index = publishedIndex(gen, answers);
+		const to = join(outDir, "__mv", "bakes");
+		rmSync(to, {
+			recursive: true,
+			force: true
+		});
+		const grammar = new RegExp(`^/__mv/bakes/${gen}/[0-9a-f]{16}/\\d+\\.png$`);
+		const realCache = (() => {
+			try {
+				return realpathSync(cache);
+			} catch {
+				return null;
+			}
+		})();
+		for (const [key, a] of Object.entries(index.answers)) {
+			const files = [];
+			if (!(realCache !== null && a.targets.every((t) => {
+				if (!grammar.test(t.texture)) return false;
+				const from = join(root, "design", ".local", "bakes", t.texture.replace(/^\/__mv\/bakes\//, ""));
+				try {
+					if (!lstatSync(from).isFile()) return false;
+					if (!realpathSync(from).startsWith(realCache + "/")) return false;
+				} catch {
+					return false;
+				}
+				files.push([from, join(outDir, t.texture.slice(1))]);
+				return true;
+			}))) {
+				delete index.answers[key];
+				continue;
+			}
+			for (const [from, dest] of files) {
+				mkdirSync(join(dest, ".."), { recursive: true });
+				copyFileSync(from, dest);
+				stats.bytes += statSync(dest).size;
+			}
+		}
+		mkdirSync(join(to, String(gen)), { recursive: true });
+		writeFileSync(join(to, String(gen), "index.json"), JSON.stringify(index));
+		for (const a of answers) {
+			if (!a.ok) {
+				stats.live++;
+				log?.(`  bake: ${a.frame} ${a.theme} ${a.w}x${a.h} - stays live: ${a.error}`);
+				continue;
+			}
+			if (!(a.effects ?? a.targets.length)) {
+				stats.plain++;
+				continue;
+			}
+			if (!a.targets.length) {
+				stats.live++;
+				log?.(`  bake: ${a.frame} ${a.theme} ${a.w}x${a.h} - ${a.effects} effects, all nested, stay live`);
+				continue;
+			}
+			const shipped = index.answers[indexKey(a)]?.targets.length ?? 0;
+			if (shipped) stats.asleep++;
+			else stats.live++;
+			log?.(`  bake: ${a.frame} ${a.theme} ${a.w}x${a.h} - ${a.targets.length} effects, ${a.targets.length - shipped} stay live, ${a.ms} ms`);
+		}
+	} finally {
+		site.close();
+		rmSync(cache, {
+			recursive: true,
+			force: true
+		});
+	}
+	stats.ms = Date.now() - t0;
+	return stats;
+}
+//#endregion
+export { bakePublished };

package/dist/{serve-Bcwfpvhl.mjs → serve-z5qtj_wJ.mjs}

@@ -1,4 +1,4 @@
-import { n as NAME } from "./cli.mjs";
+import { r as NAME } from "./cli.mjs";
 import { t as secureSuffix } from "./secure-cookie-_K1Hsx8H.mjs";
 import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { extname, isAbsolute, join, relative, resolve } from "node:path";
@@ -147,7 +147,7 @@ async function serve(root, portFlag) {
 			console.error(`[${NAME}] MARVER_ID_ISSUER is set but MARVER_PUBLIC_ORIGIN is not.\n  Every assertion is bound to this canvas's exact origin, and it cannot be\n  inferred from request headers - a proxy can make any request look local.\n  Set it to the origin people actually reach this canvas on:\n    MARVER_PUBLIC_ORIGIN=https://canvas.example.com\n    MARVER_PUBLIC_ORIGIN=http://localhost:${portFlag ?? (Number(process.env.PORT) || 4199)} (development)`);
 			process.exit(1);
 		}
-		const { marverIdHandler } = await import("./marver-id-gate-D6By7XHj.mjs");
+		const { marverIdHandler } = await import("./marver-id-gate-B_idGdHm.mjs");
 		const { dataDir } = await import("./comments-DZyobpxG.mjs").then((n) => n.n);
 		const canvasName = humanName(meta.name);
 		const { ceilingsFromRights } = await import("./auth-DdUKeVKt.mjs").then((n) => n.R);
@@ -659,4 +659,4 @@ ${collabOn ? `
 }
 const esc = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
 //#endregion
-export { serve, poweredByUrl as t };
+export { MIME, serve, poweredByUrl as t };

package/dist/{share-Gqo_Ygqw.mjs → share--bdSc4G5.mjs}

@@ -1,4 +1,4 @@
-import { n as NAME } from "./cli.mjs";
+import { r as NAME } from "./cli.mjs";
 import { M as resolveAccess } from "./auth-DdUKeVKt.mjs";
 import { i as loadCollab } from "./sync-BZaCWqK-.mjs";
 //#region src/cli/share.ts

package/dist/{shot-BzQ0PXKH.mjs → shot-BFEuYbaz.mjs}

@@ -1,4 +1,4 @@
-import { n as NAME } from "./cli.mjs";
+import { r as NAME } from "./cli.mjs";
 import { readDevInfo } from "./work-CLrmY-vQ.mjs";
 //#region src/cli/shot.ts
 /**

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

@@ -1,4 +1,4 @@
-import { a as slideSize, i as ROUTE } from "./cli.mjs";
+import { a as ROUTE, o as slideSize } from "./cli.mjs";
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { randomBytes } from "node:crypto";
@@ -36,12 +36,19 @@ function findChrome() {
 }
 /** Profile directories marver has ever created (the sweep in shot.ts looks for both). */
 const PROFILE_PREFIXES = ["mv-shot-", "mv-browser-"];
+/** What a Linux container needs and a desktop must not get: Chrome refuses to run as root with its
+*  sandbox on (a build image runs as root), and a container's /dev/shm is too small for its tiles. */
+function containerFlags(platform, uid) {
+	return platform === "linux" && uid === 0 ? ["--no-sandbox", "--disable-dev-shm-usage"] : [];
+}
 const FLAGS = [
-	"--headless=new",
+	...process.env.MV_CHROME_HEADED ? [] : ["--headless=new"],
 	"--hide-scrollbars",
 	"--no-first-run",
 	"--no-default-browser-check",
-	"--disable-extensions"
+	"--disable-extensions",
+	...containerFlags(process.platform, process.getuid?.()),
+	...process.env.MV_CHROME_FLAGS?.split(" ").filter(Boolean) ?? []
 ];
 const HANDSHAKE_MS = 15e3;
 const MAX_MESSAGE = 1 << 30;
@@ -50,9 +57,9 @@ const MAX_MESSAGE = 1 << 30;
 *  and concatenated ONCE per delimiter (a screenshot answer is many chunks; re-concatenating
 *  the remainder per chunk would be quadratic). The size guard runs BEFORE a segment is held. */
 var Frames = class {
-	max;
 	chunks = [];
 	held = 0;
+	max;
 	constructor(max = MAX_MESSAGE) {
 		this.max = max;
 	}
@@ -330,8 +337,8 @@ async function shootFrame(opts) {
 	};
 	const plan = planShot(frame, viewports, size);
 	if (frame.kind !== "html") try {
-		const { scanAssetRefs } = await import("./build-D_g53Bp2.mjs");
-		const { ensurePoster } = await import("./poster-BEjUcQP3.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 {}
@@ -923,4 +930,4 @@ async function captureIn({ url, width, height, out, fullHeight = false, timeoutM
 	}
 }
 //#endregion
-export { capture, resolveFrames, shootBatch, shootFrame, sweepGhosts, findChrome as t };
+export { AREA, SURFACE, capture, planShot, pool, resolveFrames, shootBatch, shootFrame, shotConcurrency, sweepGhosts, findChrome as t, withBrowser };

package/dist/{work-lzC-lPY0.mjs → work-0YopuMt9.mjs}

@@ -1,4 +1,4 @@
-import { n as NAME } from "./cli.mjs";
+import { r as NAME } from "./cli.mjs";
 import { WORK_TTL_DEFAULT, WORK_TTL_MAX, readDevInfo } from "./work-CLrmY-vQ.mjs";
 //#region src/cli/work.ts
 /**

package/docs/publish.md

@@ -36,6 +36,20 @@ only around published boards (a folder with nothing published never reaches the
 and `title`s and `description`s ship only for published things - the project's, the
 published boards', their folders', scenes' and frames'.
 
+**Glass at rest.** `marver build` compiles the textures a hi-fi frame rests under (the same
+certified compile as the dev canvas, spec 16) against the site it just built - every published
+node, at its size on its board, in every theme - and ships them with it under `__mv/bakes/`. A
+visitor's browser reads one static index; the shell is the same. Whatever the compiler cannot
+certify (glass inside glass, blend modes, a frame whose paint is not a function of its URL) rests
+with its glass live, as before. The compile needs Chrome on the machine that builds: without one
+the build says so and ships without textures; `--no-textures` (or `MARVER_NO_TEXTURES=1` in CI)
+skips it on purpose. A visitor who resizes a frame to a device preset sees it live at that size
+(no texture was compiled for it). The textures are certified as the build machine renders the
+frame, so bundle the fonts your frames use (`@fontsource-*`, or files under `public/`): a font
+that exists only on a designer's laptop renders differently in a build container, and the
+visitor's browser then refuses those textures and rests the frame live. A republish mints new
+textures; a tab already open keeps the old shell and rests its glass live until it reloads.
+
 ## Who can open your canvas
 
 Three choices, and the canvas is public until you make one.
@@ -246,10 +260,13 @@ containerised canvas reports as one campaign.
 
 ## Railway (the one-pager)
 
-1. Push your repo to GitHub and create a Railway service from it.
-2. Build command: `npm ci && npx marver build`
-3. Start command: `npx marver serve`  (Railway's `$PORT` is picked up automatically)
-4. Variables: `MARVER_PASSWORD=<your password>`
+1. Push your repo to GitHub with the Dockerfile below at its root, and create a Railway
+   service from it (Railway detects the Dockerfile; a Nixpacks build has no browser and ships
+   the hi-fi frames with live glass).
+2. Start command: `npx marver serve`  (Railway's `$PORT` is picked up automatically)
+3. Variables: `MARVER_PASSWORD=<your password>`, or the identity gate from the table above.
+4. Read the build log: `textures: N frame views asleep under certified glass ...` is the line
+   that says the glass compiled; `textures: none - no Chrome` means the image has no browser.
 
 Deploy. The repo itself is the deployable - nothing to export, nothing to sync.
 
@@ -257,14 +274,19 @@ Deploy. The repo itself is the deployable - nothing to export, nothing to sync.
 
 ```dockerfile
 FROM node:22-slim
+RUN apt-get update && apt-get install -y --no-install-recommends chromium fonts-liberation \
+  && rm -rf /var/lib/apt/lists/*          # the browser `marver build` compiles the glass textures with
 WORKDIR /app                      # set share.name in design/config.ts - the fallback name is this directory
 COPY . .
-RUN npm ci && npx marver build
+RUN npm ci && npx marver build    # as root in a container: marver adds Chrome's --no-sandbox itself
 ENV PORT=8080
 EXPOSE 8080
 CMD ["npx", "marver", "serve"]
 ```
 
+Without a browser in the image the build still succeeds, says so, and ships every feature but the
+textures; `npx marver build --no-textures` skips the compile on purpose.
+
 ## Cloudflare Pages + Access (email/domain allowlists)
 
 For teams that want per-email policies instead of one password: build in CI

package/docs/sticky-notes.md

@@ -0,0 +1,43 @@
+# 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.
+
+## 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.17.0",
+  "version": "0.19.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,
@@ -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
+}

package/src/client/frame-host/bridge.js

@@ -12,20 +12,15 @@ const isHtmlFrame = new URL(import.meta.url).searchParams.get('html') === '1'
 const post = (msg) => { if (window.parent !== window) window.parent.postMessage(msg, location.origin) }
 const id = new URLSearchParams(location.search).get('id') ?? location.pathname
 
-// The shell serialises this frame's DOM (same origin) for the lean facade. Open shadow roots
-// are walkable, but a CLOSED root is invisible after the fact - flag it at creation so the serialiser
-// degrades the frame (keeps it live) instead of shipping a lean copy missing its shadow content.
-const _attachShadow = Element.prototype.attachShadow
-if (_attachShadow) Element.prototype.attachShadow = function (init) {
-  if (init && init.mode === 'closed') window.__mvClosedShadow = true
-  return _attachShadow.call(this, init)
-}
-
 // theme lands as BOTH signals: [data-theme] plus the `dark` class Tailwind/shadcn key on
 const setTheme = (theme) => {
   document.documentElement.dataset.theme = theme
   document.documentElement.classList.toggle('dark', theme === 'dark')
+  // the shell sleeps a frame only under the theme it has actually painted: report it, two frames later
+  requestAnimationFrame(() => requestAnimationFrame(() => post({ type: 'sh:theme-applied', id, theme })))
 }
+// the theme this document booted with (the URL's) counts as applied
+requestAnimationFrame(() => requestAnimationFrame(() => post({ type: 'sh:theme-applied', id, theme: new URLSearchParams(location.search).get('theme') ?? 'light' })))
 
 if (isHtmlFrame) {
   const theme = new URLSearchParams(location.search).get('theme')

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

@@ -3,7 +3,7 @@
  * Boot failures (theme, providers, layouts, the frame itself) render a plain-DOM error card
  * and post sh:error; an ErrorBoundary catches render-time throws the same way.
  */
-import { Component, createElement, type ReactNode } from 'react'
+import { Component, createElement, useLayoutEffect, type ReactNode } from 'react'
 import { createRoot } from 'react-dom/client'
 
 import './bridge.js'
@@ -53,9 +53,18 @@ class Boundary extends Component<{ children: ReactNode }, { err: Error | null }>
   }
 }
 
+/** Posts sh:ready once the scene has COMMITTED (render() only schedules; a layout effect on the
+ *  outermost element runs after every child's, before the first paint of the tree). */
+function Committed({ onCommit, children }: { onCommit: () => void; children?: ReactNode }) {
+  useLayoutEffect(onCommit, [])
+  return children
+}
+
 async function boot() {
+  const phases: Record<string, number> = { boot: Math.round(performance.now()) }   // ms since navigation: where a boot spends its time (research/hifi/bootscale.ts)
   try {
     await import('virtual:sh-theme' as string)
+    phases.theme = Math.round(performance.now())
 
     const fileKey = frameFile(id)
     // Honest copy: the id usually IS valid on disk - this document's frame registry is
@@ -63,6 +72,7 @@ async function boot() {
     if (!fileKey) return fail(`frame "${id}" is not in this canvas's registry yet - the file was likely just added or renamed. The canvas should recover on its own; if this card persists, reload it.`)
 
     const frameMod: any = await frames[fileKey]()
+    phases.scene = Math.round(performance.now())
     const Frame = frameMod.default
     // No typeof gate: memo()/forwardRef() components are objects, not functions.
     // React + the ErrorBoundary validate the element type better than we can.
@@ -73,17 +83,21 @@ async function boot() {
     if (providerKey) wrappers.push((await providers[providerKey]() as any).default)
     for (const lk of layoutChain(fileKey)) wrappers.push((await layouts[lk]() as any).default)
 
+    phases.wrappers = Math.round(performance.now())
     let tree: ReactNode = createElement(Frame)
     for (const W of wrappers.reverse()) if (W != null) tree = createElement(W, null, tree)
 
-    createRoot(document.getElementById('root')!).render(createElement(Boundary, null, tree))
-    // stamp the URL revision so the shell can drop a ready queued by a superseded document (one it
-    // auto-renavigated past) - a WindowProxy survives navigation, so a stale ready could otherwise
-    // mark a reloading frame ready. Mirrors the sh:measure generation guard.
-    post({ type: 'sh:ready', id, gen: params.get('r') ?? '', meta: frameMod.meta && typeof frameMod.meta === 'object' ? frameMod.meta : undefined })
+    // sh:ready on the first COMMIT, stamped with the URL revision so the shell can drop a ready queued
+    // by a superseded document (one it auto-renavigated past) - a WindowProxy survives navigation, so
+    // a stale ready could otherwise mark a reloading frame ready. Mirrors the sh:measure generation guard.
+    const ready = () => { phases.commit = Math.round(performance.now()); post({ type: 'sh:ready', id, gen: params.get('r') ?? '', meta: frameMod.meta && typeof frameMod.meta === 'object' ? frameMod.meta : undefined, phases }) }
+    createRoot(document.getElementById('root')!).render(createElement(Boundary, null, createElement(Committed, { onCommit: ready }, tree)))
   } catch (err) {
     fail((err as Error).message)
   }
 }
 
 boot()
+// Fast Refresh keeps this document alive across edits: tell the shell its source changed, so a
+// sleeping frame wakes and compiles again (a texture describes a source revision).
+if (import.meta.hot) import.meta.hot.on('vite:afterUpdate', () => post({ type: 'sh:hmr', id }))