kitfly 0.2.0 → 0.2.3

package/scripts/dev.ts

@@ -6,6 +6,7 @@
  * Options:
  *   -p, --port <number>   Port to serve on [env: KITFLY_DEV_PORT] [default: 3333]
  *   -H, --host <string>   Host to bind to [env: KITFLY_DEV_HOST] [default: localhost]
+ *   --profile <name>      Active content profile [env: KITFLY_PROFILE]
  *   -o, --open            Open browser on start [env: KITFLY_DEV_OPEN] [default: true]
  *   --no-open             Don't open browser
  *   --help                Show help message
@@ -18,14 +19,23 @@ import { readdir, readFile, stat } from "node:fs/promises";
 import { basename, extname, join, resolve } from "node:path";
 import { marked, Renderer } from "marked";
 import { ENGINE_ASSETS_DIR, ENGINE_SITE_DIR } from "../src/engine.ts";
-import { loadPluginInjections } from "../src/plugin-loader.ts";
+import {
+	loadPluginInjections,
+	PluginConfigError,
+	PluginIntegrityError,
+	PluginNetworkError,
+	PluginPolicyError,
+} from "../src/plugin-loader.ts";
 import {
 	buildBreadcrumbsSimple,
 	buildFooter,
+	buildLogoImgHtml,
 	buildNavSimple,
 	buildPageMeta,
-	buildSlideNav,
+	buildSlideNavHierarchical,
 	buildToc,
+	// Types
+	type ContentFile,
 	// Network utilities
 	checkPortOrExit,
 	// Navigation/template building
@@ -37,21 +47,26 @@ import {
 	envString,
 	// Formatting
 	escapeHtml,
+	filterByProfile,
+	filterUnknownSlidesVisualsTypeDiagnostics,
 	// Provenance
 	generateProvenance,
+	loadDataBindings,
 	// YAML/Config parsing
 	loadSiteConfig,
+	mergeFrontmatterWithBody,
 	type Provenance,
+	pagePathForData,
 	// Markdown utilities
 	parseFrontmatter,
 	parseYaml,
+	resolveBindings,
 	resolveStylesPath,
 	resolveTemplatePath,
 	rewriteRelativeAssetUrls,
-	// Types
+	runPrebuildHooks,
 	type SiteConfig,
 	slugify,
-	toUrlPath,
 	validatePath,
 	validateSlidesVisualsFences,
 } from "../src/shared.ts";
@@ -66,6 +81,7 @@ let HOST = DEFAULT_HOST;
 let ROOT = process.cwd();
 let OPEN_BROWSER = true;
 let LOG_FORMAT = ""; // "structured" when invoked by CLI daemon
+let ACTIVE_PROFILE: string | undefined;
 
 // Structured logger for daemon mode — set during main() init.
 // When null, all output goes through console.log (standalone mode).
@@ -75,6 +91,86 @@ let daemonLog: {
 	error: (msg: string) => void;
 } | null = null;
 
+async function applyDataBindingsToMarkdown(
+	rawMarkdown: string,
+	filePath: string,
+	config: SiteConfig,
+): Promise<{ frontmatter: Record<string, unknown>; body: string }> {
+	const parsed = parseFrontmatter(rawMarkdown);
+	const dataRef = typeof parsed.frontmatter.data === "string" ? parsed.frontmatter.data.trim() : "";
+	if (!dataRef) return parsed;
+
+	const pagePath = pagePathForData(ROOT, config.docroot, filePath);
+	const bindings = await loadDataBindings(dataRef, pagePath, ROOT, config.docroot, config.dataroot);
+	return {
+		frontmatter: parsed.frontmatter,
+		body: resolveBindings(parsed.body, bindings, pagePath),
+	};
+}
+
+async function applyDataBindingsForSlides(
+	rawMarkdown: string,
+	filePath: string,
+	config: SiteConfig,
+): Promise<string> {
+	const resolved = await applyDataBindingsToMarkdown(rawMarkdown, filePath, config);
+	return mergeFrontmatterWithBody(rawMarkdown, resolved.body);
+}
+
+function isPluginLoaderError(error: unknown): error is Error {
+	return (
+		error instanceof PluginConfigError ||
+		error instanceof PluginIntegrityError ||
+		error instanceof PluginPolicyError ||
+		error instanceof PluginNetworkError
+	);
+}
+
+function pluginVersionMismatchHint(message: string): string {
+	const m = message.match(/^Plugin ([a-z0-9-]+) version mismatch: ([^ ]+) != ([^ ]+)$/i);
+	if (!m) return "";
+	const pluginId = m[1];
+	const expected = m[3];
+	return `Update <code>kitfly.plugins.yaml</code> to <code>${pluginId}@${expected}</code>, then refresh.`;
+}
+
+export function buildDevPluginErrorHtml(message: string): string {
+	const hint = pluginVersionMismatchHint(message);
+	const safeMessage = escapeHtml(message);
+	const hintBlock = hint
+		? `<p>${hint}</p>`
+		: "<p>Check <code>kitfly.plugins.yaml</code> and <code>registry/plugins.yaml</code>, then refresh.</p>";
+	return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Plugin Configuration Error</title>
+  <style>
+    body { font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif; margin: 0; background: #0b1020; color: #e8ecf3; }
+    main { max-width: 820px; margin: 8vh auto; padding: 1.25rem; }
+    .card { background: #131a2e; border: 1px solid #2a3557; border-radius: 12px; padding: 1rem 1.1rem; }
+    h1 { margin: 0 0 0.75rem; font-size: 1.25rem; }
+    p, li { line-height: 1.5; }
+    code { background: #0e1528; padding: 0.08rem 0.3rem; border-radius: 6px; border: 1px solid #2a3557; }
+    pre { margin: 0.8rem 0 0; padding: 0.75rem; background: #0e1528; border: 1px solid #2a3557; border-radius: 8px; overflow: auto; }
+    .muted { color: #b5bfd2; font-size: 0.92rem; }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="card">
+      <h1>Plugin setup error</h1>
+      <p>Kitfly could not load one or more plugins for dev preview.</p>
+      ${hintBlock}
+      <pre><code>${safeMessage}</code></pre>
+      <p class="muted">After updating config, refresh this page. No dev server restart required.</p>
+    </div>
+  </main>
+</body>
+</html>`;
+}
+
 /** Log info — uses structured logger in daemon mode, console.log otherwise */
 function logInfo(msg: string): void {
 	if (daemonLog) daemonLog.info(msg);
@@ -97,6 +193,7 @@ interface ParsedArgs {
 	open?: boolean;
 	folder?: string;
 	logFormat?: string;
+	profile?: string;
 }
 
 function parseArgs(argv: string[]): ParsedArgs {
@@ -114,6 +211,9 @@ function parseArgs(argv: string[]): ParsedArgs {
 		} else if (arg === "--log-format") {
 			result.logFormat = next;
 			i++;
+		} else if (arg === "--profile" && next && !next.startsWith("-")) {
+			result.profile = next;
+			i++;
 		} else if (arg === "--open" || arg === "-o") {
 			result.open = true;
 		} else if (arg === "--no-open") {
@@ -131,6 +231,7 @@ function getConfig(): {
 	open: boolean;
 	folder?: string;
 	logFormat?: string;
+	profile?: string;
 } {
 	const args = parseArgs(process.argv.slice(2));
 	return {
@@ -139,9 +240,15 @@ function getConfig(): {
 		open: args.open ?? envBool("KITFLY_DEV_OPEN", true),
 		folder: args.folder,
 		logFormat: args.logFormat,
+		profile: args.profile ?? process.env.KITFLY_PROFILE,
 	};
 }
 
+async function getFilteredFiles(config: SiteConfig): Promise<ContentFile[]> {
+	const files = await collectFiles(ROOT, config);
+	return filterByProfile(files, ACTIVE_PROFILE, config.profiles);
+}
+
 function getContentType(filePath: string): string {
 	const ext = extname(filePath).toLowerCase();
 	switch (ext) {
@@ -288,7 +395,7 @@ async function renderPage(
 		}
 		htmlContent = `<h1>${title}</h1>\n<pre><code class="language-json">${escapeHtml(prettyJson)}</code></pre>`;
 	} else {
-		const { frontmatter, body } = parseFrontmatter(content);
+		const { frontmatter, body } = await applyDataBindingsToMarkdown(content, filePath, config);
 		if (frontmatter.title) {
 			title = frontmatter.title as string;
 		}
@@ -296,16 +403,16 @@ async function renderPage(
 		htmlContent = marked.parse(body) as string;
 	}
 
-	const files = await collectFiles(ROOT, config);
+	const files = await getFilteredFiles(config);
 	const currentUrlPath = urlPath.slice(1).replace(/\.html$/, "");
+	const pathPrefix = "/";
 	const nav = buildNavSimple(files, config, currentUrlPath);
-	const footer = buildFooter(provenance, config);
+	const footer = buildFooter(provenance, config, pathPrefix);
 	const breadcrumbs = buildBreadcrumbsSimple(urlPath, files, config);
 	const toc = buildToc(htmlContent);
 	const brandTarget = config.brand.external ? ' target="_blank" rel="noopener"' : "";
 	const themeCSS = generateThemeCSS(theme);
 	const prismUrls = getPrismUrls(theme);
-	const pathPrefix = "/";
 	const plugins = await getPluginInjectionsCached(config.mode === "slides" ? "slides" : "docs");
 
 	const hotReloadScript = `
@@ -317,33 +424,51 @@ async function renderPage(
 
 	const logoClass = config.brand.logoType === "wordmark" ? "logo-wordmark" : "logo-icon";
 	const brandInitial = escapeHtml(config.brand.name.trim().charAt(0).toUpperCase() || "K");
+	const mobileLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: `logo-img ${logoClass}`,
+		pathPrefix,
+		onerrorFallback: true,
+	});
+	const sidebarLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: "logo-img",
+		pathPrefix,
+		onerrorFallback: true,
+	});
 
 	return template
 		.replace("{{BODY_CLASS}}", "mode-docs")
-		.replace(/\{\{PATH_PREFIX\}\}/g, pathPrefix)
-		.replace(/\{\{BRAND_URL\}\}/g, config.brand.url)
-		.replace(/\{\{BRAND_TARGET\}\}/g, brandTarget)
-		.replace(/\{\{BRAND_NAME\}\}/g, config.brand.name)
-		.replace(/\{\{BRAND_INITIAL\}\}/g, brandInitial)
-		.replace(/\{\{BRAND_LOGO\}\}/g, config.brand.logo || "assets/brand/logo.png")
-		.replace(/\{\{BRAND_FAVICON\}\}/g, config.brand.favicon || "assets/brand/favicon.png")
-		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, logoClass)
-		.replace(/\{\{SITE_TITLE\}\}/g, config.title)
-		.replace("{{TITLE}}", title)
-		.replace("{{VERSION}}", uiVersion)
-		.replace("{{BRANCH}}", provenance.gitBranch)
-		.replace("{{BREADCRUMBS}}", breadcrumbs)
-		.replace("{{PAGE_META}}", pageMeta)
-		.replace("{{NAV}}", nav)
-		.replace("{{CONTENT}}", htmlContent)
-		.replace("{{TOC}}", toc)
-		.replace("{{FOOTER}}", footer)
-		.replace("{{THEME_CSS}}", themeCSS)
-		.replace("{{PLUGIN_HEAD}}", plugins.head)
-		.replace("{{PLUGIN_BODY_END}}", plugins.bodyEnd)
-		.replace("{{PRISM_LIGHT_URL}}", prismUrls.light)
-		.replace("{{PRISM_DARK_URL}}", prismUrls.dark)
-		.replace("{{HOT_RELOAD_SCRIPT}}", hotReloadScript);
+		.replace(/\{\{PATH_PREFIX\}\}/g, () => pathPrefix)
+		.replace(/\{\{BRAND_URL\}\}/g, () => config.brand.url)
+		.replace(/\{\{BRAND_TARGET\}\}/g, () => brandTarget)
+		.replace(/\{\{BRAND_NAME\}\}/g, () => config.brand.name)
+		.replace(/\{\{BRAND_INITIAL\}\}/g, () => brandInitial)
+		.replace("{{MOBILE_BRAND_LOGO_IMG}}", () => mobileLogoHtml)
+		.replace("{{SIDEBAR_BRAND_LOGO_IMG}}", () => sidebarLogoHtml)
+		.replace(/\{\{BRAND_LOGO\}\}/g, () => config.brand.logo || "assets/brand/logo.png")
+		.replace(/\{\{BRAND_FAVICON\}\}/g, () => config.brand.favicon || "assets/brand/favicon.png")
+		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, () => logoClass)
+		.replace(/\{\{SITE_TITLE\}\}/g, () => config.title)
+		.replace("{{TITLE}}", () => title)
+		.replace("{{VERSION}}", () => uiVersion)
+		.replace("{{BRANCH}}", () => provenance.gitBranch)
+		.replace("{{BREADCRUMBS}}", () => breadcrumbs)
+		.replace("{{PAGE_META}}", () => pageMeta)
+		.replace("{{NAV}}", () => nav)
+		.replace("{{CONTENT}}", () => htmlContent)
+		.replace("{{TOC}}", () => toc)
+		.replace("{{FOOTER}}", () => footer)
+		.replace("{{THEME_CSS}}", () => themeCSS)
+		.replace("{{PLUGIN_HEAD}}", () => plugins.head)
+		.replace("{{PLUGIN_BODY_END}}", () => plugins.bodyEnd)
+		.replace("{{PRISM_LIGHT_URL}}", () => prismUrls.light)
+		.replace("{{PRISM_DARK_URL}}", () => prismUrls.dark)
+		.replace("{{HOT_RELOAD_SCRIPT}}", () => hotReloadScript);
 }
 
 async function renderSlidesPage(
@@ -353,8 +478,10 @@ async function renderSlidesPage(
 ): Promise<string> {
 	const uiVersion = provenance.version ? `v${provenance.version}` : "unversioned";
 	const template = await readFile(await resolveTemplatePath(ROOT), "utf-8");
-	const files = await collectFiles(ROOT, config);
-	const slides = await collectSlides(files);
+	const files = await getFilteredFiles(config);
+	const slides = await collectSlides(files, {
+		markdownTransform: (raw, file) => applyDataBindingsForSlides(raw, file.path, config),
+	});
 
 	if (slides.length === 0) {
 		return renderGettingStarted(provenance, config, theme);
@@ -367,7 +494,9 @@ async function renderSlidesPage(
 			let inner = "";
 			if (slide.kind === "markdown") {
 				if (validateFences) {
-					const diagnostics = validateSlidesVisualsFences(slide.body);
+					const diagnostics = filterUnknownSlidesVisualsTypeDiagnostics(
+						validateSlidesVisualsFences(slide.body),
+					);
 					if (diagnostics.length) {
 						const msg = diagnostics
 							.slice(0, 12)
@@ -413,8 +542,8 @@ async function renderSlidesPage(
           </div>
         </div>`;
 
-	const nav = buildSlideNav(slides, config, "slide-1");
-	const footer = buildFooter(provenance, config);
+	const nav = buildSlideNavHierarchical(slides, config, "slide-1");
+	const footer = buildFooter(provenance, config, pathPrefix);
 	const brandTarget = config.brand.external ? ' target="_blank" rel="noopener"' : "";
 	const themeCSS = generateThemeCSS(theme);
 	const prismUrls = getPrismUrls(theme);
@@ -427,33 +556,51 @@ async function renderSlidesPage(
 	const plugins = await getPluginInjectionsCached("slides");
 	const logoClass = config.brand.logoType === "wordmark" ? "logo-wordmark" : "logo-icon";
 	const brandInitial = escapeHtml(config.brand.name.trim().charAt(0).toUpperCase() || "K");
+	const mobileLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: `logo-img ${logoClass}`,
+		pathPrefix,
+		onerrorFallback: true,
+	});
+	const sidebarLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: "logo-img",
+		pathPrefix,
+		onerrorFallback: true,
+	});
 
 	return template
 		.replace("{{BODY_CLASS}}", "mode-slides")
-		.replace(/\{\{PATH_PREFIX\}\}/g, pathPrefix)
-		.replace(/\{\{BRAND_URL\}\}/g, config.brand.url)
-		.replace(/\{\{BRAND_TARGET\}\}/g, brandTarget)
-		.replace(/\{\{BRAND_NAME\}\}/g, config.brand.name)
-		.replace(/\{\{BRAND_INITIAL\}\}/g, brandInitial)
-		.replace(/\{\{BRAND_LOGO\}\}/g, config.brand.logo || "assets/brand/logo.png")
-		.replace(/\{\{BRAND_FAVICON\}\}/g, config.brand.favicon || "assets/brand/favicon.png")
-		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, logoClass)
-		.replace(/\{\{SITE_TITLE\}\}/g, config.title)
-		.replace("{{TITLE}}", config.title)
-		.replace("{{VERSION}}", uiVersion)
-		.replace("{{BRANCH}}", provenance.gitBranch)
+		.replace(/\{\{PATH_PREFIX\}\}/g, () => pathPrefix)
+		.replace(/\{\{BRAND_URL\}\}/g, () => config.brand.url)
+		.replace(/\{\{BRAND_TARGET\}\}/g, () => brandTarget)
+		.replace(/\{\{BRAND_NAME\}\}/g, () => config.brand.name)
+		.replace(/\{\{BRAND_INITIAL\}\}/g, () => brandInitial)
+		.replace("{{MOBILE_BRAND_LOGO_IMG}}", () => mobileLogoHtml)
+		.replace("{{SIDEBAR_BRAND_LOGO_IMG}}", () => sidebarLogoHtml)
+		.replace(/\{\{BRAND_LOGO\}\}/g, () => config.brand.logo || "assets/brand/logo.png")
+		.replace(/\{\{BRAND_FAVICON\}\}/g, () => config.brand.favicon || "assets/brand/favicon.png")
+		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, () => logoClass)
+		.replace(/\{\{SITE_TITLE\}\}/g, () => config.title)
+		.replace("{{TITLE}}", () => config.title)
+		.replace("{{VERSION}}", () => uiVersion)
+		.replace("{{BRANCH}}", () => provenance.gitBranch)
 		.replace("{{BREADCRUMBS}}", "")
 		.replace("{{PAGE_META}}", "")
-		.replace("{{NAV}}", nav)
-		.replace("{{CONTENT}}", htmlContent)
+		.replace("{{NAV}}", () => nav)
+		.replace("{{CONTENT}}", () => htmlContent)
 		.replace("{{TOC}}", "")
-		.replace("{{FOOTER}}", footer)
-		.replace("{{THEME_CSS}}", themeCSS)
-		.replace("{{PLUGIN_HEAD}}", plugins.head)
-		.replace("{{PLUGIN_BODY_END}}", plugins.bodyEnd)
-		.replace("{{PRISM_LIGHT_URL}}", prismUrls.light)
-		.replace("{{PRISM_DARK_URL}}", prismUrls.dark)
-		.replace("{{HOT_RELOAD_SCRIPT}}", hotReloadScript);
+		.replace("{{FOOTER}}", () => footer)
+		.replace("{{THEME_CSS}}", () => themeCSS)
+		.replace("{{PLUGIN_HEAD}}", () => plugins.head)
+		.replace("{{PLUGIN_BODY_END}}", () => plugins.bodyEnd)
+		.replace("{{PRISM_LIGHT_URL}}", () => prismUrls.light)
+		.replace("{{PRISM_DARK_URL}}", () => prismUrls.dark)
+		.replace("{{HOT_RELOAD_SCRIPT}}", () => hotReloadScript);
 }
 
 // Render Getting Started page when no config
@@ -502,33 +649,51 @@ sections:
 
 	const logoClass = config.brand.logoType === "wordmark" ? "logo-wordmark" : "logo-icon";
 	const brandInitial = escapeHtml(config.brand.name.trim().charAt(0).toUpperCase() || "K");
+	const mobileLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: `logo-img ${logoClass}`,
+		pathPrefix,
+		onerrorFallback: true,
+	});
+	const sidebarLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: "logo-img",
+		pathPrefix,
+		onerrorFallback: true,
+	});
 
 	return template
 		.replace("{{BODY_CLASS}}", "mode-docs")
-		.replace(/\{\{PATH_PREFIX\}\}/g, pathPrefix)
-		.replace(/\{\{BRAND_URL\}\}/g, config.brand.url)
-		.replace(/\{\{BRAND_TARGET\}\}/g, brandTarget)
-		.replace(/\{\{BRAND_NAME\}\}/g, config.brand.name)
-		.replace(/\{\{BRAND_INITIAL\}\}/g, brandInitial)
-		.replace(/\{\{BRAND_LOGO\}\}/g, config.brand.logo || "assets/brand/logo.png")
-		.replace(/\{\{BRAND_FAVICON\}\}/g, config.brand.favicon || "assets/brand/favicon.png")
-		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, logoClass)
-		.replace(/\{\{SITE_TITLE\}\}/g, config.title)
+		.replace(/\{\{PATH_PREFIX\}\}/g, () => pathPrefix)
+		.replace(/\{\{BRAND_URL\}\}/g, () => config.brand.url)
+		.replace(/\{\{BRAND_TARGET\}\}/g, () => brandTarget)
+		.replace(/\{\{BRAND_NAME\}\}/g, () => config.brand.name)
+		.replace(/\{\{BRAND_INITIAL\}\}/g, () => brandInitial)
+		.replace("{{MOBILE_BRAND_LOGO_IMG}}", () => mobileLogoHtml)
+		.replace("{{SIDEBAR_BRAND_LOGO_IMG}}", () => sidebarLogoHtml)
+		.replace(/\{\{BRAND_LOGO\}\}/g, () => config.brand.logo || "assets/brand/logo.png")
+		.replace(/\{\{BRAND_FAVICON\}\}/g, () => config.brand.favicon || "assets/brand/favicon.png")
+		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, () => logoClass)
+		.replace(/\{\{SITE_TITLE\}\}/g, () => config.title)
 		.replace("{{TITLE}}", "Getting Started")
-		.replace("{{VERSION}}", uiVersion)
-		.replace("{{BRANCH}}", provenance.gitBranch)
+		.replace("{{VERSION}}", () => uiVersion)
+		.replace("{{BRANCH}}", () => provenance.gitBranch)
 		.replace("{{BREADCRUMBS}}", "")
 		.replace("{{PAGE_META}}", "")
 		.replace("{{NAV}}", "<ul></ul>")
-		.replace("{{CONTENT}}", htmlContent)
+		.replace("{{CONTENT}}", () => htmlContent)
 		.replace("{{TOC}}", "")
-		.replace("{{FOOTER}}", buildFooter(provenance, config))
-		.replace("{{THEME_CSS}}", themeCSS)
-		.replace("{{PLUGIN_HEAD}}", plugins.head)
-		.replace("{{PLUGIN_BODY_END}}", plugins.bodyEnd)
-		.replace("{{PRISM_LIGHT_URL}}", prismUrls.light)
-		.replace("{{PRISM_DARK_URL}}", prismUrls.dark)
-		.replace("{{HOT_RELOAD_SCRIPT}}", hotReloadScript);
+		.replace("{{FOOTER}}", () => buildFooter(provenance, config, pathPrefix))
+		.replace("{{THEME_CSS}}", () => themeCSS)
+		.replace("{{PLUGIN_HEAD}}", () => plugins.head)
+		.replace("{{PLUGIN_BODY_END}}", () => plugins.bodyEnd)
+		.replace("{{PRISM_LIGHT_URL}}", () => prismUrls.light)
+		.replace("{{PRISM_DARK_URL}}", () => prismUrls.dark)
+		.replace("{{HOT_RELOAD_SCRIPT}}", () => hotReloadScript);
 }
 
 async function tryServeFile(filePath: string): Promise<Response | null> {
@@ -563,9 +728,11 @@ async function tryServeContentAsset(
 }
 
 // Find file for a URL path
-async function findFile(urlPath: string, config: SiteConfig): Promise<string | null> {
-	const { stat } = await import("node:fs/promises");
-
+async function findFile(
+	urlPath: string,
+	config: SiteConfig,
+	files: ContentFile[],
+): Promise<string | null> {
 	// Remove leading slash and .html extension (for compatibility with built links)
 	const path = urlPath.slice(1).replace(/\.html$/, "") || "";
 
@@ -573,84 +740,20 @@ async function findFile(urlPath: string, config: SiteConfig): Promise<string | n
 	if (!path) {
 		if (config.home) {
 			const homePath = validatePath(ROOT, config.docroot, config.home, true);
-			if (homePath) {
-				try {
-					await stat(homePath);
-					return homePath;
-				} catch {
-					// Home file not found, fall through
-				}
-			}
+			const homeFile = homePath ? files.find((file) => file.path === homePath) : undefined;
+			if (homeFile) return homeFile.path;
 		}
 		// Fallback to first file
-		const files = await collectFiles(ROOT, config);
 		return files.length > 0 ? files[0].path : null;
 	}
 
-	// Check configured sections
-	for (const section of config.sections) {
-		const sectionPath = validatePath(ROOT, config.docroot, section.path, true);
-		if (!sectionPath) continue;
-
-		if (section.files) {
-			// Check explicit files
-			for (const file of section.files) {
-				const name = file.replace(/\.(md|yaml|json)$/, "").toLowerCase();
-				if (name === path) {
-					const filePath = join(sectionPath, file);
-					try {
-						await stat(filePath);
-						return filePath;
-					} catch {
-						// Continue
-					}
-				}
-			}
-		} else {
-			// Check directory for matching file (supports nested paths)
-			const urlBase = toUrlPath(ROOT, sectionPath);
-			if (path.startsWith(`${urlBase}/`) || path === urlBase) {
-				const relPath = path === urlBase ? "" : path.slice(urlBase.length + 1);
-				// Guard against path traversal
-				if (relPath.includes("..")) continue;
-				const extensions = [".md", ".yaml", ".json"];
-
-				if (relPath === "") {
-					// Section root URL — try index file
-					for (const ext of extensions) {
-						const filePath = join(sectionPath, `index${ext}`);
-						try {
-							await stat(filePath);
-							return filePath;
-						} catch {
-							// Continue
-						}
-					}
-				} else {
-					// Try direct file match at nested path
-					for (const ext of extensions) {
-						const filePath = join(sectionPath, relPath + ext);
-						try {
-							await stat(filePath);
-							return filePath;
-						} catch {
-							// Continue
-						}
-					}
-					// Try as directory with index file
-					for (const ext of extensions) {
-						const filePath = join(sectionPath, relPath, `index${ext}`);
-						try {
-							await stat(filePath);
-							return filePath;
-						} catch {
-							// Continue
-						}
-					}
-				}
-			}
-		}
-	}
+	const directMatch = files.find((file) => file.urlPath === path);
+	if (directMatch) return directMatch.path;
+
+	const sectionIndex = files.find(
+		(file) => file.urlPath === `${path}/index` || file.urlPath === path,
+	);
+	if (sectionIndex) return sectionIndex.path;
 
 	return null;
 }
@@ -687,17 +790,35 @@ function startWatcher(config: SiteConfig) {
 	for (const dir of watchDirs) {
 		try {
 			watch(dir, { recursive: true }, (_event, filename) => {
-				if (
-					filename &&
-					(filename.endsWith(".md") ||
-						filename.endsWith(".yaml") ||
-						filename.endsWith(".json") ||
-						filename.endsWith(".html") ||
-						filename.endsWith(".css"))
-				) {
-					logInfo(`File changed: ${filename}`);
-					notifyReload();
-				}
+				if (!filename) return;
+				void (async () => {
+					try {
+						let hooksRan = 0;
+						if (config.prebuild?.length) {
+							hooksRan = await runPrebuildHooks(
+								config.prebuild,
+								ROOT,
+								"dev",
+								ACTIVE_PROFILE,
+								config.dataroot || "data",
+								filename,
+							);
+						}
+						const shouldReload =
+							hooksRan > 0 ||
+							filename.endsWith(".md") ||
+							filename.endsWith(".yaml") ||
+							filename.endsWith(".json") ||
+							filename.endsWith(".html") ||
+							filename.endsWith(".css");
+						if (shouldReload) {
+							logInfo(`File changed: ${filename}`);
+							notifyReload();
+						}
+					} catch (error) {
+						logWarn(error instanceof Error ? error.message : String(error));
+					}
+				})();
 			});
 		} catch {
 			// Directory doesn't exist, skip
@@ -721,6 +842,10 @@ async function main() {
 	// Load configuration
 	const config = await loadSiteConfig(ROOT);
 	logInfo(`Loaded config: "${config.title}" (${config.sections.length} sections)`);
+	if (config.prebuild?.length) {
+		await runPrebuildHooks(config.prebuild, ROOT, "dev", ACTIVE_PROFILE, config.dataroot || "data");
+		logInfo(`Ran prebuild hooks (${config.prebuild.length})`);
+	}
 
 	// Apply server config from site.yaml if CLI didn't override
 	if (config.server?.port && PORT === DEFAULT_PORT) {
@@ -795,7 +920,7 @@ async function main() {
 		if (assetResponse) return assetResponse;
 
 		// Check for content
-		const files = await collectFiles(ROOT, config);
+		const files = await getFilteredFiles(config);
 		if (files.length === 0) {
 			// No content - render Getting Started page
 			const html = await renderGettingStarted(provenance, config, theme);
@@ -813,7 +938,7 @@ async function main() {
 		}
 
 		// Find and render markdown/yaml file
-		const filePath = await findFile(url.pathname, config);
+		const filePath = await findFile(url.pathname, config, files);
 		if (filePath) {
 			// If this is an index/readme file and the URL lacks a trailing slash,
 			// redirect so relative links resolve correctly (BUG-003)
@@ -854,19 +979,44 @@ async function main() {
 		return new Response("Not found", { status: 404 });
 	}
 
-	// Wrap with request logging middleware when in structured log mode
-	const fetch = daemonLog
-		? async (req: Request) => {
-				const start = performance.now();
-				const response = await handleRequest(req);
+	// Wrap with request logging + friendly plugin errors.
+	const fetch = async (req: Request) => {
+		const start = performance.now();
+		const url = new URL(req.url);
+		try {
+			const response = await handleRequest(req);
+			if (daemonLog && url.pathname !== "/__reload") {
 				const duration = (performance.now() - start).toFixed(0);
-				const url = new URL(req.url);
-				if (url.pathname !== "/__reload") {
-					daemonLog?.info(`${req.method} ${url.pathname} ${response.status} ${duration}ms`);
+				daemonLog.info(`${req.method} ${url.pathname} ${response.status} ${duration}ms`);
+			}
+			return response;
+		} catch (error) {
+			const duration = (performance.now() - start).toFixed(0);
+			const message = error instanceof Error ? error.message : String(error);
+			if (isPluginLoaderError(error)) {
+				if (daemonLog && url.pathname !== "/__reload") {
+					daemonLog.warn(
+						`${req.method} ${url.pathname} 500 ${duration}ms plugin error: ${message}`,
+					);
+				} else if (!daemonLog) {
+					logWarn(`Plugin error: ${message}`);
 				}
-				return response;
+				return new Response(buildDevPluginErrorHtml(message), {
+					status: 500,
+					headers: { "Content-Type": "text/html; charset=utf-8" },
+				});
+			}
+			if (daemonLog && url.pathname !== "/__reload") {
+				daemonLog.error(`${req.method} ${url.pathname} 500 ${duration}ms ${message}`);
+			} else if (!daemonLog) {
+				console.error(error);
 			}
-		: handleRequest;
+			return new Response("Internal server error", {
+				status: 500,
+				headers: { "Content-Type": "text/plain; charset=utf-8" },
+			});
+		}
+	};
 
 	// Create server
 	Bun.serve({
@@ -910,9 +1060,22 @@ async function main() {
 		}
 	}
 
-	// Open browser (macOS)
+	// Open browser (cross-platform)
 	if (OPEN_BROWSER) {
-		Bun.spawn(["open", serverUrl]);
+		try {
+			if (process.platform === "win32") {
+				// cmd.exe built-in: start
+				// Empty title argument avoids treating URL as window title.
+				Bun.spawn(["cmd", "/c", "start", "", serverUrl]);
+			} else if (process.platform === "darwin") {
+				Bun.spawn(["open", serverUrl]);
+			} else {
+				// Most Linux distros
+				Bun.spawn(["xdg-open", serverUrl]);
+			}
+		} catch {
+			// Non-fatal: server is already running; user can open manually.
+		}
 	}
 }
 
@@ -923,6 +1086,7 @@ export interface DevOptions {
 	host?: string;
 	open?: boolean;
 	logFormat?: string;
+	profile?: string;
 }
 
 export async function dev(options: DevOptions = {}) {
@@ -941,6 +1105,7 @@ export async function dev(options: DevOptions = {}) {
 	if (options.logFormat) {
 		LOG_FORMAT = options.logFormat;
 	}
+	ACTIVE_PROFILE = options.profile;
 	await main();
 }
 
@@ -954,6 +1119,7 @@ Usage: bun run dev [folder] [options]
 Options:
   -p, --port <number>   Port to serve on [env: KITFLY_DEV_PORT] [default: ${DEFAULT_PORT}]
   -H, --host <string>   Host to bind to [env: KITFLY_DEV_HOST] [default: ${DEFAULT_HOST}]
+  --profile <name>      Active content profile [env: KITFLY_PROFILE]
   -o, --open            Open browser on start [env: KITFLY_DEV_OPEN] [default: true]
   --no-open             Don't open browser
   --help                Show this help message
@@ -975,5 +1141,6 @@ Examples:
 		host: cfg.host,
 		open: cfg.open,
 		logFormat: cfg.logFormat,
+		profile: cfg.profile,
 	}).catch(console.error);
 }