kitfly 0.2.1 → 0.2.4

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
@@ -28,14 +29,18 @@ import {
 import {
 	buildBreadcrumbsSimple,
 	buildFooter,
+	buildLogoImgHtml,
 	buildNavSimple,
 	buildPageMeta,
-	buildSlideNav,
+	buildSlideNavHierarchical,
 	buildToc,
+	// Types
+	type ContentFile,
 	// Network utilities
 	checkPortOrExit,
 	// Navigation/template building
 	collectFiles,
+	collectPlanningVisualsContainmentWarnings,
 	collectSlides,
 	envBool,
 	envInt,
@@ -43,23 +48,29 @@ import {
 	envString,
 	// Formatting
 	escapeHtml,
+	filterByProfile,
+	filterUnknownPlanningVisualsTypeDiagnostics,
 	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,
+	validatePlanningVisualsFences,
 	validateSlidesVisualsFences,
 } from "../src/shared.ts";
 import { generateThemeCSS, getPrismUrls, loadTheme, type Theme } from "../src/theme.ts";
@@ -73,6 +84,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).
@@ -82,6 +94,32 @@ 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 ||
@@ -158,6 +196,7 @@ interface ParsedArgs {
 	open?: boolean;
 	folder?: string;
 	logFormat?: string;
+	profile?: string;
 }
 
 function parseArgs(argv: string[]): ParsedArgs {
@@ -175,6 +214,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") {
@@ -192,6 +234,7 @@ function getConfig(): {
 	open: boolean;
 	folder?: string;
 	logFormat?: string;
+	profile?: string;
 } {
 	const args = parseArgs(process.argv.slice(2));
 	return {
@@ -200,9 +243,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) {
@@ -256,15 +305,23 @@ const clients: Set<ReadableStreamDefaultController> = new Set();
 
 let pluginCache: { key: string; head: string; bodyEnd: string } | null = null;
 
-async function isSlidesVisualsEnabled(): Promise<boolean> {
+async function getFenceValidationFlags(): Promise<{
+	slidesVisuals: boolean;
+	planningVisuals: boolean;
+}> {
 	const configPath = join(ROOT, "kitfly.plugins.yaml");
 	try {
 		const raw = await readFile(configPath, "utf-8");
 		const parsed = parseYaml(raw) as unknown as Record<string, unknown>;
 		const plugins = Array.isArray(parsed?.plugins) ? (parsed.plugins as unknown[]) : [];
-		return plugins.some((p) => typeof p === "string" && p.startsWith("slides-visuals@"));
+		return {
+			slidesVisuals: plugins.some((p) => typeof p === "string" && p.startsWith("slides-visuals@")),
+			planningVisuals: plugins.some(
+				(p) => typeof p === "string" && p.startsWith("planning-visuals@"),
+			),
+		};
 	} catch {
-		return false;
+		return { slidesVisuals: false, planningVisuals: false };
 	}
 }
 
@@ -349,24 +406,41 @@ 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;
 		}
 		pageMeta = buildPageMeta(frontmatter);
+		const fenceValidation = await getFenceValidationFlags();
+		if (fenceValidation.planningVisuals) {
+			const diagnostics = filterUnknownPlanningVisualsTypeDiagnostics(
+				validatePlanningVisualsFences(body),
+			);
+			if (diagnostics.length) {
+				const msg = diagnostics
+					.slice(0, 12)
+					.map((d) => `  - ${filePath}:${d.line} ${d.message}`)
+					.join("\n");
+				throw new Error(`planning-visuals fence contract violations:\n${msg}`);
+			}
+			const warnings = collectPlanningVisualsContainmentWarnings(body);
+			for (const warning of warnings.slice(0, 12)) {
+				logWarn(`${filePath}:${warning.line} ${warning.message}`);
+			}
+		}
 		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 = `
@@ -378,33 +452,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(
@@ -414,20 +506,22 @@ 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);
 	}
 	const pathPrefix = "/";
-	const validateFences = await isSlidesVisualsEnabled();
+	const fenceValidation = await getFenceValidationFlags();
 
 	const sections = await Promise.all(
 		slides.map(async (slide, i) => {
 			let inner = "";
 			if (slide.kind === "markdown") {
-				if (validateFences) {
+				if (fenceValidation.slidesVisuals) {
 					const diagnostics = filterUnknownSlidesVisualsTypeDiagnostics(
 						validateSlidesVisualsFences(slide.body),
 					);
@@ -439,6 +533,22 @@ async function renderSlidesPage(
 						throw new Error(`slides-visuals fence contract violations:\n${msg}`);
 					}
 				}
+				if (fenceValidation.planningVisuals) {
+					const diagnostics = filterUnknownPlanningVisualsTypeDiagnostics(
+						validatePlanningVisualsFences(slide.body),
+					);
+					if (diagnostics.length) {
+						const msg = diagnostics
+							.slice(0, 12)
+							.map((d) => `  - ${slide.sourcePath}:${d.line} ${d.message}`)
+							.join("\n");
+						throw new Error(`planning-visuals fence contract violations:\n${msg}`);
+					}
+					const warnings = collectPlanningVisualsContainmentWarnings(slide.body);
+					for (const warning of warnings.slice(0, 12)) {
+						logWarn(`${slide.sourcePath}:${warning.line} ${warning.message}`);
+					}
+				}
 				inner = marked.parse(slide.body) as string;
 			} else if (slide.kind === "yaml") {
 				inner = `<pre><code class="language-yaml">${escapeHtml(slide.body)}</code></pre>`;
@@ -476,8 +586,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);
@@ -490,33 +600,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
@@ -565,33 +693,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> {
@@ -626,9 +772,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$/, "") || "";
 
@@ -636,84 +784,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;
 }
@@ -750,17 +834,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
@@ -784,6 +886,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) {
@@ -858,7 +964,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);
@@ -876,7 +982,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)
@@ -998,9 +1104,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.
+		}
 	}
 }
 
@@ -1011,6 +1130,7 @@ export interface DevOptions {
 	host?: string;
 	open?: boolean;
 	logFormat?: string;
+	profile?: string;
 }
 
 export async function dev(options: DevOptions = {}) {
@@ -1029,6 +1149,7 @@ export async function dev(options: DevOptions = {}) {
 	if (options.logFormat) {
 		LOG_FORMAT = options.logFormat;
 	}
+	ACTIVE_PROFILE = options.profile;
 	await main();
 }
 
@@ -1042,6 +1163,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
@@ -1063,5 +1185,6 @@ Examples:
 		host: cfg.host,
 		open: cfg.open,
 		logFormat: cfg.logFormat,
+		profile: cfg.profile,
 	}).catch(console.error);
 }