mr-md 1.0.0

package/src/renderer/blocks.ts

@@ -0,0 +1,452 @@
+import katex from "katex";
+import type { Block, BuildOptions, QuizFile, QuizQuestion } from "../types.js";
+import {
+	blockChrome,
+	escapeScriptJson,
+	mdInline,
+	mdToHtml,
+	renderSimulationControls,
+} from "./markdown.js";
+import hljs from "highlight.js";
+import { type NavItem, resolveAssetSrc, resolveContent } from "./utils.js";
+
+// HTML escaping utility needed by blocks
+export function escHtml(str: string): string {
+	return str
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#39;");
+}
+export function escAttr(str: string): string {
+	return escHtml(str);
+}
+
+// ─── Block renderers ──────────────────────────────────────────────────────────
+
+function renderBlock(
+	block: Block,
+	idx: number,
+	options: BuildOptions,
+): { html: string; navItem?: NavItem } {
+	try {
+		const result = renderBlockInner(block, idx, options);
+		if (
+			result.html &&
+			"src" in block &&
+			typeof block.src === "string" &&
+			block.src.includes(".")
+		) {
+			result.html = result.html.replace(
+				/^<([a-zA-Z0-9-]+)([^>]*)>/,
+				`<$1 data-bk-src="${escAttr(block.src)}"$2>`,
+			);
+		}
+		return result;
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		console.warn(
+			`  ⚠ Error rendering block ${idx + 1} (${block.type}): ${msg}`,
+		);
+		const errorHtml = `<div class="bk-callout bk-callout--warning"><div class="bk-callout-icon"></div><div class="bk-callout-content"><div class="bk-callout-label">Block Error (${escHtml(block.type)})</div><div class="bk-callout-body"><p>${escHtml(msg)}</p></div></div></div>`;
+		return { html: errorHtml };
+	}
+}
+
+function renderBlockInner(
+	block: Block,
+	idx: number,
+	options: BuildOptions,
+): { html: string; navItem?: NavItem } {
+	switch (block.type) {
+		case "heading": {
+			const md = resolveContent(block.src, options, "md");
+			const { html, title } = mdToHtml(md);
+			const label = block.title || title || (typeof block.src === "string" && !block.src.includes(".md") ? block.src : "Heading");
+			const id = `heading-${idx}`;
+			return {
+				html: `<section id="${id}" class="bk-section bk-heading">${html}</section>`,
+				navItem: { id, label, kind: "heading" },
+			};
+		}
+
+		case "markdown": {
+			const md = resolveContent(block.src, options, "md");
+			const { html } = mdToHtml(md);
+			return { html: `<div class="bk-markdown">${html}</div>` };
+		}
+
+		case "section": {
+			const md = resolveContent(block.src, options, "md");
+			const { html, title } = mdToHtml(md);
+			const label = block.label || title || (typeof block.src === "string" && !block.src.includes(".md") ? block.src : "Section");
+			const id = `section-${idx}`;
+			return {
+				html: `<section id="${id}" class="bk-section bk-subsection">${html}</section>`,
+				navItem: { id, label, kind: "section" },
+			};
+		}
+
+		case "important":
+		case "warning":
+		case "tip":
+		case "note": {
+			const variantMap = {
+				important: "Important",
+				warning: "Warning",
+				tip: "Tip",
+				note: "Note",
+			};
+			const label = variantMap[block.type];
+			const md = resolveContent(block.src, options, "md");
+			const { html } = mdToHtml(md);
+			return {
+				html: `<div class="bk-callout bk-callout--${block.type}">
+          <div class="bk-callout-icon"></div>
+          <div class="bk-callout-content">
+            <div class="bk-callout-label">${label}</div>
+            <div class="bk-callout-body">${html}</div>
+          </div>
+        </div>`,
+			};
+		}
+
+		case "code": {
+			const raw = resolveContent(block.src, options, "text"); // Could be file or inline
+			const lang =
+				block.lang ??
+				(typeof block.src === "string" && block.src.includes(".")
+					? (block.src.split(".").pop() ?? "")
+					: "");
+            let highlighted = escHtml(raw);
+            if (lang && hljs.getLanguage(lang)) {
+                highlighted = hljs.highlight(raw, { language: lang }).value;
+            } else {
+                highlighted = hljs.highlightAuto(raw).value;
+            }
+			return {
+				html: `<div class="bk-code-block">
+          ${block.label ? `<div class="bk-code-header"><span class="bk-code-label">${escHtml(block.label)}</span><span class="bk-code-lang">${lang}</span></div>` : ""}
+          <div class="bk-code-scroll">
+            <pre><code class="language-${lang} hljs">${highlighted}</code></pre>
+          </div>
+        </div>`,
+			};
+		}
+
+		case "simulation": {
+			const propsJson = JSON.stringify(block.props ?? {});
+			const simSrc = resolveContent(block.src, options, "js");
+			const simConfig = { js: simSrc, loop: false, dependencies: block.dependencies };
+			return {
+				html: blockChrome(
+					block.controls === "observe" ? "Simulation" : "Interactive Lab",
+					block.label,
+					block.caption,
+					`${renderSimulationControls(block as Extract<Block, { type: "simulation" }>)}
+          <div class="bk-embed-frame bk-embed-interactive">
+            <div class="bk-embed-overlay" tabindex="0" role="button" aria-label="Activate interactive simulation">
+              <span class="bk-embed-overlay-text">Click to interact</span>
+            </div>
+            <iframe srcdoc="${iframeDoc(simSrc, propsJson, false, block.dependencies)}"
+              sandbox="allow-scripts"
+              style="width:100%;height:100%;border:none;display:block;">
+            </iframe>
+          </div>
+          <script type="application/json" class="bk-sim-config">${escapeScriptJson(simConfig)}</script>`,
+					block.accent ?? "blue",
+				),
+			};
+		}
+
+		case "animation": {
+			const animSrc = resolveContent(block.src, options, "js");
+			return {
+				html: blockChrome(
+					"Animation",
+					block.label,
+					block.caption,
+					`<div class="bk-embed-frame bk-embed-interactive">
+            <div class="bk-embed-overlay" tabindex="0" role="button" aria-label="Activate interactive animation">
+              <span class="bk-embed-overlay-text">Click to interact</span>
+            </div>
+            <iframe srcdoc="${iframeDoc(animSrc, "{}", block.loop)}"
+              sandbox="allow-scripts"
+              style="width:100%;height:100%;border:none;display:block;">
+            </iframe>
+          </div>`,
+					block.accent ?? "neutral",
+				),
+			};
+		}
+
+		case "media": {
+			const src = resolveAssetSrc(block.src, options);
+			const media =
+				block.kind === "image"
+					? `<img src="${escAttr(src)}" alt="${escAttr(block.alt ?? "")}" loading="lazy">`
+					: block.kind === "video"
+						? `<video src="${escAttr(src)}" ${block.poster ? `poster="${escAttr(resolveAssetSrc(block.poster, options))}"` : ""} ${block.controls !== false ? "controls" : ""} playsinline></video>`
+						: `<audio src="${escAttr(src)}" ${block.controls !== false ? "controls" : ""}></audio>`;
+
+			return {
+				html: blockChrome(
+					block.kind,
+					block.label,
+					[block.caption, block.credit ? `Credit: ${block.credit}` : ""]
+						.filter(Boolean)
+						.join(" "),
+					`<div class="bk-media bk-media--${block.kind}">${media}</div>`,
+					"neutral",
+				),
+			};
+		}
+
+		case "youtube": {
+			const params = new URLSearchParams();
+			params.set("rel", "0");
+			if (block.start) params.set("start", String(block.start));
+			return {
+				html: blockChrome(
+					"YouTube",
+					block.label,
+					block.caption,
+					`<div class="bk-embed-frame">
+            <iframe src="https://www.youtube-nocookie.com/embed/${escAttr(block.id)}?${params.toString()}"
+              title="${escAttr(block.label ?? "YouTube video")}"
+              allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+              allowfullscreen
+              referrerpolicy="strict-origin-when-cross-origin"
+              loading="lazy"
+              style="width:100%;height:100%;border:none;display:block;">
+            </iframe>
+          </div>`,
+					"neutral",
+				),
+			};
+		}
+
+		case "latex": {
+			const rendered = katex.renderToString(block.tex, {
+				throwOnError: false,
+				displayMode: block.display ?? true,
+			});
+			return {
+				html: blockChrome(
+					"LaTeX",
+					block.label,
+					block.caption,
+					`<div class="${block.display === false ? "bk-latex-inline" : "bk-latex-block"}">${rendered}</div>`,
+					"violet",
+					false
+				),
+			};
+		}
+
+		case "columns": {
+			return {
+				html: blockChrome(
+					"Columns",
+					block.label,
+					block.caption,
+					`<div class="bk-columns" style="grid-template-columns:${block.columns
+						.map((column) => column.width ?? "minmax(0, 1fr)")
+						.join(" ")}">
+            ${block.columns
+							.map((column) => {
+								const content =
+									column.latex != null
+										? `<div class="bk-latex-block">${katex.renderToString(column.latex, { throwOnError: false, displayMode: true })}</div>`
+										: mdToHtml(
+												column.markdown ??
+													(column.src
+														? resolveContent(column.src, options, "md")
+														: ""),
+											).html;
+								return `<div class="bk-column">${content}</div>`;
+							})
+							.join("")}
+          </div>`,
+					"neutral",
+					false
+				),
+			};
+		}
+
+		case "quiz": {
+			let quiz: QuizFile = { questions: [] };
+			const rawJson = resolveContent(block.src, options, "json");
+			try {
+				quiz = JSON.parse(rawJson);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				if (options.strict !== false) {
+					throw new Error(`Invalid Quiz JSON for block ${idx + 1}: ${msg}`);
+				}
+				console.warn(`  ⚠ Invalid Quiz JSON for block ${idx + 1}:`, e);
+				return {
+					html: `<div class="bk-callout bk-callout--warning"><div class="bk-callout-icon"></div><div class="bk-callout-content"><div class="bk-callout-label">Quiz JSON Error</div><div class="bk-callout-body"><p>${escHtml(msg)}</p></div></div></div>`,
+				};
+			}
+
+			return {
+				html: `<div class="bk-quiz" id="quiz-${idx}">
+          <div class="bk-quiz-head">
+            <span>${escHtml(block.label ?? "Check your understanding")}</span>
+            ${block.caption ? `<small>${mdInline(block.caption)}</small>` : ""}
+          </div>
+          <div class="bk-quiz-body">
+            ${quiz.questions.map((q, qi) => renderQuestion(q, `quiz-${idx}`, qi)).join("\n")}
+          </div>
+        </div>`,
+				navItem: {
+					id: `quiz-${idx}`,
+					label: block.label ?? "Questions",
+					kind: "quiz",
+				},
+			};
+		}
+
+		case "divider":
+			return { html: '<hr class="bk-divider">' };
+
+		default:
+			return { html: "" };
+	}
+}
+
+function renderQuestion(q: QuizQuestion, quizId: string, qi: number): string {
+	const qid = `${quizId}-q${qi}`;
+	const options = q.options
+		.map(
+			(opt, oi) => `
+    <button class="bk-opt" data-correct="${oi === q.answer}" onclick="bkAnswer(this,'${qid}')">
+      <span class="bk-opt-dot"></span><span class="bk-opt-text">${mdInline(opt)}</span>
+    </button>`,
+		)
+		.join("");
+
+	const expHtml = q.explanation
+		? `<div class="bk-explanation" id="${qid}-exp" hidden>${mdToHtml(q.explanation).html}</div>`
+		: "";
+
+	return `
+    <div class="bk-question" id="${qid}">
+      <div class="bk-q-text">${mdToHtml(q.q).html}</div>
+      <div class="bk-opts">${options}</div>
+      ${expHtml}
+    </div>`;
+}
+
+// Wraps a JS string in a minimal iframe document
+function iframeDoc(js: string, props: string, loop?: boolean, dependencies?: string[]): string {
+	const scriptTags = (dependencies ?? []).map((url) => `<script src="${escAttr(url)}"></script>`).join("\\n");
+	const doc = `<!DOCTYPE html><html><head>
+${scriptTags}
+<style>
+  html, body { height: 100%; width: 100%; margin: 0; padding: 0; overflow: hidden; background: transparent; display: flex; align-items: center; justify-content: center; }
+  canvas { display: block; touch-action: none; transform-origin: center center; flex-shrink: 0; }
+  body { font-family: sans-serif; }
+</style>
+</head><body>
+<canvas id="c" width="800" height="500"></canvas>
+<script>
+window.__simProps=${props};
+window.__loop=${loop ?? false};
+window.bkSetupCalled = false;
+window.bkCanvasPoint = function(event, canvas) {
+  const c = canvas || event.currentTarget || event.target;
+  const rect = c.getBoundingClientRect();
+  const logicalW = c.__bkLogicalW || 800;
+  const logicalH = c.__bkLogicalH || 500;
+  return {
+    x: (event.clientX - rect.left) * logicalW / rect.width,
+    y: (event.clientY - rect.top) * logicalH / rect.height
+  };
+};
+window.bkFitCanvas = function(c, requestedW, requestedH, options) {
+  if (!c) return { scale: 1, width: requestedW, height: requestedH, cssScale: 1 };
+  const dpr = window.devicePixelRatio || 1;
+  const w = requestedW;
+  const h = requestedH;
+  
+  c.__bkLogicalW = w;
+  c.__bkLogicalH = h;
+  
+  c.style.width = w + "px";
+  c.style.height = h + "px";
+  
+  c.style.position = "relative";
+  c.style.left = "auto";
+  c.style.top = "auto";
+  c.style.transformOrigin = "center center";
+  
+  const scaleX = window.innerWidth / w;
+  const scaleY = window.innerHeight / h;
+  const cssScale = Math.max(scaleX, scaleY);
+  
+  c.style.transform = "scale(" + cssScale + ")";
+  
+  const physW = Math.max(1, Math.round(w * dpr));
+  const physH = Math.max(1, Math.round(h * dpr));
+
+  if (!options || options.bitmap !== false) {
+    if (c.width !== physW || c.height !== physH) {
+      c.width = physW;
+      c.height = physH;
+    }
+  }
+  return { scale: dpr, width: w, height: h, cssScale };
+};
+window.bkSetup = function(requestedW, requestedH, loopFn) {
+  window.bkSetupCalled = true;
+  const canvas = document.getElementById("c");
+  if (!canvas) return;
+  const ctx = canvas.getContext("2d");
+  
+  function loop() {
+    const fit = window.bkFitCanvas(canvas, requestedW, requestedH);
+    if (window.innerWidth >= 32 && window.innerHeight >= 32) {
+      ctx.save();
+      ctx.scale(fit.scale, fit.scale);
+      
+      loopFn(ctx, fit.width, fit.height);
+      
+      ctx.restore();
+    }
+    requestAnimationFrame(loop);
+  }
+  loop();
+};
+
+window.addEventListener("message", (event) => {
+  if (!event.data || event.data.type !== "bk:set-props") return;
+  window.__simProps = { ...window.__simProps, ...event.data.props };
+  window.dispatchEvent(new CustomEvent("bk:props", { detail: window.__simProps }));
+});
+try {
+  ${js}
+} catch (e) {
+  console.error("Simulation Error:", e);
+  document.body.innerHTML = '<div style="padding:20px;color:red;font-family:monospace">Error: ' + e.message + '</div>';
+}
+if (!window.bkSetupCalled) {
+  function fallbackScale() {
+    window.bkFitCanvas(document.getElementById("c"), 800, 500, { bitmap: false });
+    requestAnimationFrame(fallbackScale);
+  }
+  fallbackScale();
+}
+</script>
+</body></html>`;
+	// We use double quotes for the srcdoc attribute, so we must escape them.
+	return doc
+		.replace(/&/g, "&amp;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#39;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
+export { blockChrome, renderBlock, renderBlockInner };

package/src/renderer/html.ts

@@ -0,0 +1,163 @@
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+import type { BuildOptions, Lesson } from "../types.js";
+import { escHtml } from "./blocks.js";
+import type { NavItem } from "./utils.js";
+
+// ─── Page shell ───────────────────────────────────────────────────────────────
+
+function renderNavItem(item: NavItem): string {
+	const kindClass =
+		item.kind === "heading"
+			? "bk-nav-heading"
+			: item.kind === "quiz"
+				? "bk-nav-quiz"
+				: "bk-nav-sub";
+	return `<a href="#${item.id}" class="bk-nav-item ${kindClass}" data-id="${item.id}">${escHtml(item.label)}</a>`;
+}
+
+function renderEndNav(lesson: Lesson): string {
+	const { prevSlug, prevTitle, nextSlug, nextTitle } = lesson.meta;
+	if (!prevSlug && !nextSlug) return "";
+
+	return `<nav class="bk-end-nav" aria-label="Lesson navigation" style="grid-template-columns: repeat(2, minmax(0, 1fr));">
+    ${prevSlug ? `
+    <a class="bk-end-link bk-end-link--prev" href="${prevSlug}.html">
+      <span>Previous Lesson</span>
+      <strong>${escHtml(prevTitle || "Previous")}</strong>
+    </a>
+    ` : `<div class="bk-end-link" style="visibility:hidden"></div>`}
+    ${nextSlug ? `
+    <a class="bk-end-link bk-end-link--next" href="${nextSlug}.html">
+      <span>Next Lesson</span>
+      <strong>${escHtml(nextTitle || "Next")}</strong>
+    </a>
+    ` : `<div class="bk-end-link" style="visibility:hidden"></div>`}
+  </nav>`;
+}
+
+function renderPage(
+	lesson: Lesson,
+	navItems: NavItem[],
+	bodyHtml: string,
+	opts: BuildOptions,
+): string {
+	const theme = opts.theme ?? "auto";
+	const schemeAttr = theme === "auto" ? "" : `data-theme="${theme}"`;
+	const preset = opts.preset ?? {};
+	const layout = preset.layout ?? "lesson";
+	const density = preset.density ?? "comfortable";
+	const tone = preset.tone ?? "scholarly";
+	const palette = opts.palette ?? "ink";
+	const navHtml = navItems.map(renderNavItem).join("\n");
+	const endNavHtml = renderEndNav(lesson);
+
+	return `<!DOCTYPE html>
+<html lang="en" data-palette="${palette}" ${schemeAttr}>
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escHtml(lesson.meta.title)}</title>
+${lesson.meta.description ? `<meta name="description" content="${escHtml(lesson.meta.description)}">` : ""}
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.47/dist/katex.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/highlight.js@11.11.1/styles/github-dark.min.css">
+${opts.head ?? ""}
+<style>
+${opts.font ? `:root { --font-sans: ${opts.font}, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }` : ""}
+${pageCSS()}
+</style>
+</head>
+<body class="bk-layout-${layout} bk-density-${density} bk-tone-${tone}">
+<div class="bk-shell">
+  <aside class="bk-sidebar">
+    <div class="bk-sidebar-inner">
+      <div class="bk-sidebar-header">
+        ${lesson.meta.parentSlug ? `<div style="margin-top: 8px;"><a href="${lesson.meta.parentSlug}.html" class="bk-back-link" aria-label="Back to Chapter" style="margin-bottom: 12px;"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 12H5"/><path d="M12 19l-7-7 7-7"/></svg>Back to Chapter</a></div>` : `<div style="margin-top: 8px;"></div>`}
+        <div class="bk-sidebar-title">${escHtml(lesson.meta.title)}</div>
+        ${lesson.meta.author ? `<div class="bk-sidebar-author">By ${escHtml(lesson.meta.author)}</div>` : ""}
+        ${lesson.meta.tags?.length ? `<div class="bk-tag-row">${lesson.meta.tags.map((tag) => `<span>${escHtml(tag)}</span>`).join("")}</div>` : ""}
+      </div>
+      <nav class="bk-nav">${navHtml}</nav>
+      <div class="bk-sidebar-footer">
+        <button class="bk-icon-btn bk-settings-button" id="bk-settings-button" type="button" aria-expanded="false" aria-controls="bk-theme-panel" title="Display settings">
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="3"></circle><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z"></path></svg>
+          <span class="bk-sr-only">Display settings</span>
+        </button>
+        <div class="bk-theme-panel" id="bk-theme-panel" aria-label="Display settings" hidden>
+          <div class="bk-theme-row">
+            <span>Theme</span>
+            <div class="bk-segmented-control" id="bk-theme-icons">
+               <button type="button" class="bk-segment-btn ${theme === "light" ? "active" : ""}" data-theme="light" title="Light" aria-label="Light theme">
+                 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"></circle><line x1="12" y1="1" x2="12" y2="3"></line><line x1="12" y1="21" x2="12" y2="23"></line><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line><line x1="1" y1="12" x2="3" y2="12"></line><line x1="21" y1="12" x2="23" y2="12"></line><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line></svg>
+               </button>
+               <button type="button" class="bk-segment-btn ${theme === "dark" ? "active" : ""}" data-theme="dark" title="Dark" aria-label="Dark theme">
+                 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"></path></svg>
+               </button>
+               <button type="button" class="bk-segment-btn ${theme === "auto" ? "active" : ""}" data-theme="auto" title="System" aria-label="System theme">
+                 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="14" rx="2" ry="2"></rect><line x1="8" y1="21" x2="16" y2="21"></line><line x1="12" y1="17" x2="12" y2="21"></line></svg>
+               </button>
+            </div>
+          </div>
+          <div class="bk-theme-row">
+            <span>Palette</span>
+            <div class="bk-segmented-control" id="bk-palette-icons">
+               <button type="button" class="bk-segment-btn ${palette === "ink" ? "active" : ""}" data-palette="ink" title="Ink" aria-label="Ink palette">
+                 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 2.69l5.66 5.66a8 8 0 1 1-11.31 0z"></path></svg>
+               </button>
+               <button type="button" class="bk-segment-btn ${palette === "field" ? "active" : ""}" data-palette="field" title="Field" aria-label="Field palette">
+                 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M11 20A7 7 0 0 1 9.8 6.1C15.5 5 17 4.48 19 2c1 2 2 4.18 2 8 0 5.5-4.78 10-10 10Z"></path><path d="M2 21c0-3 1.85-5.36 5.08-6C9.5 14.52 12 13 13 12"></path></svg>
+               </button>
+               <button type="button" class="bk-segment-btn ${palette === "ember" ? "active" : ""}" data-palette="ember" title="Ember" aria-label="Ember palette">
+                 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8.5 14.5A2.5 2.5 0 0011 12c0-1.38-.5-2-1-3-1.072-2.143-.224-4.054 2-6 .5 2.5 2 4.9 4 6.5 2 1.6 3 3.5 3 5.5a7 7 0 11-14 0c0-1.153.433-2.294 1-3a2.5 2.5 0 002.5 2.5z"></path></svg>
+               </button>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </aside>
+  <button class="bk-sidebar-collapse-floating" id="bk-sidebar-collapse" aria-label="Collapse sidebar">
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 18l-6-6 6-6"/></svg>
+  </button>
+  <main class="bk-main">
+    <button class="bk-sidebar-expand" id="bk-sidebar-expand" type="button" aria-label="Expand sidebar">
+      <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 18l6-6-6-6"/></svg>
+    </button>
+    <article class="bk-content">
+      <header class="bk-hero">
+        <p class="bk-eyebrow">Interactive Lesson</p>
+        <h1 style="view-transition-name: title-${lesson.meta.slug}">${escHtml(lesson.meta.title)}</h1>
+        ${lesson.meta.description ? `<p class="bk-deck">${escHtml(lesson.meta.description)}</p>` : ""}
+      </header>
+      ${bodyHtml}
+      ${endNavHtml}
+    </article>
+  </main>
+</div>
+<script>
+${clientScript()}
+</script>
+</body>
+</html>`;
+}
+
+// ─── CSS ──────────────────────────────────────────────────────────────────────
+
+function pageCSS(): string {
+	return fs.readFileSync(
+		path.join(__dirname, "../styles/theme.css"),
+		"utf-8",
+	);
+}
+
+// ─── Client-side script ───────────────────────────────────────────────────────
+
+function clientScript(): string {
+	return fs.readFileSync(path.join(__dirname, "../client/app.js"), "utf-8");
+}
+
+export { clientScript, pageCSS, renderNavItem, renderPage };