kitfly 0.2.0 → 0.2.3

package/src/shared.ts

@@ -5,7 +5,7 @@
  * to reduce duplication and ensure consistency.
  */
 
-import { readdir, readFile, stat } from "node:fs/promises";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import { basename, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { ENGINE_SITE_DIR, siteOverridePath } from "./engine.ts";
 
@@ -26,6 +26,7 @@ export interface SiteBrand {
 	url: string;
 	external?: boolean;
 	logo?: string; // Path to logo image (default: assets/brand/logo.png)
+	logoDark?: string; // Optional dark-mode logo image
 	favicon?: string; // Path to favicon (default: assets/brand/favicon.png)
 	logoType?: "icon" | "wordmark"; // icon = square, wordmark = wide
 }
@@ -54,6 +55,11 @@ export interface SiteFooter {
 	copyrightUrl?: string;
 	links?: FooterLink[];
 	attribution?: boolean;
+	logo?: string;
+	logoDark?: string;
+	logoUrl?: string;
+	logoAlt?: string;
+	logoHeight?: number;
 	// social?: SocialLinks; // Reserved for future
 }
 
@@ -62,11 +68,24 @@ export interface SiteServer {
 	host?: string; // Default dev server host
 }
 
+export interface ProfileConfig {
+	description?: string;
+	include?: {
+		tags?: string[];
+	};
+}
+
+export interface PrebuildHook {
+	command: string;
+	watch?: string[];
+}
+
 export type SiteMode = "docs" | "slides";
 export type SlideAspect = "16/9" | "4/3" | "3/2" | "16/10";
 
 export interface SiteConfig {
 	docroot: string;
+	dataroot?: string;
 	title: string;
 	version?: string;
 	mode?: SiteMode;
@@ -76,6 +95,8 @@ export interface SiteConfig {
 	sections: SiteSection[];
 	footer?: SiteFooter;
 	server?: SiteServer;
+	profiles?: Record<string, ProfileConfig>;
+	prebuild?: PrebuildHook[];
 }
 
 export interface Provenance {
@@ -109,6 +130,21 @@ export interface SlideContent extends SlideSegment {
 	kind: "markdown" | "yaml" | "json";
 }
 
+export interface CollectSlidesOptions {
+	markdownTransform?: (raw: string, file: ContentFile) => Promise<string> | string;
+}
+
+export interface DataSnippet {
+	slot: string;
+	content: string;
+}
+
+export interface DataBindings {
+	globals: Record<string, string>;
+	inject: Record<string, string>;
+	snippets: DataSnippet[];
+}
+
 // ---------------------------------------------------------------------------
 // Environment and CLI helpers
 // ---------------------------------------------------------------------------
@@ -227,6 +263,75 @@ export function parseYaml(content: string): Record<string, unknown> {
 	// Stack tracks current object context with its base indentation
 	const stack: { obj: Record<string, unknown>; indent: number }[] = [{ obj: result, indent: -2 }];
 
+	function foldBlockScalarLines(blockLines: string[]): string {
+		let output = "";
+		for (let idx = 0; idx < blockLines.length; idx++) {
+			const line = blockLines[idx];
+			if (idx === 0) {
+				output = line;
+				continue;
+			}
+			const prev = blockLines[idx - 1];
+			if (line === "") {
+				output += "\n";
+				continue;
+			}
+			output += prev === "" ? line : ` ${line}`;
+		}
+		return output;
+	}
+
+	function parseBlockHeader(
+		token: string,
+	): { style: "|" | ">"; chomp: "clip" | "strip" | "keep" } | null {
+		if (!token) return null;
+		const style = token[0];
+		if (style !== "|" && style !== ">") return null;
+		const tail = token.slice(1);
+		if (tail && !/^([1-9][+-]?|[+-][1-9]?|[+-])$/.test(tail)) {
+			return null;
+		}
+		const chomp = tail.includes("+") ? "keep" : tail.includes("-") ? "strip" : "clip";
+		return { style, chomp };
+	}
+
+	function parseBlockScalar(
+		startLine: number,
+		baseIndent: number,
+		style: "|" | ">",
+		chomp: "clip" | "strip" | "keep",
+	): { value: string; endLine: number } {
+		const rawBlock: string[] = [];
+		let cursor = startLine;
+
+		while (cursor < lines.length) {
+			const candidate = lines[cursor];
+			if (candidate.trim() === "") {
+				rawBlock.push("");
+				cursor += 1;
+				continue;
+			}
+			const candidateIndent = candidate.search(/\S/);
+			if (candidateIndent <= baseIndent) break;
+			rawBlock.push(candidate);
+			cursor += 1;
+		}
+
+		const indentLevels = rawBlock
+			.filter((line) => line.trim() !== "")
+			.map((line) => line.search(/\S/));
+		const blockIndent = indentLevels.length > 0 ? Math.min(...indentLevels) : 0;
+		const blockLines = rawBlock.map((line) => {
+			if (line === "") return "";
+			return line.slice(blockIndent);
+		});
+
+		let value = style === "|" ? blockLines.join("\n") : foldBlockScalarLines(blockLines);
+		if (chomp === "strip") value = value.replace(/\n+$/g, "");
+		if (chomp === "keep" && value !== "" && !value.endsWith("\n")) value += "\n";
+		return { value, endLine: cursor - 1 };
+	}
+
 	for (let i = 0; i < lines.length; i++) {
 		const line = lines[i];
 		// Skip comments and empty lines
@@ -257,11 +362,18 @@ export function parseYaml(content: string): Record<string, unknown> {
 				if (val.startsWith("[") && val.endsWith("]")) {
 					const arrContent = val.slice(1, -1);
 					obj[key] = arrContent.split(",").map((s) => stripQuotes(s.trim()));
-				} else if (val === "") {
-					// Nested structure will follow
-					obj[key] = null; // Placeholder
 				} else {
-					obj[key] = parseValue(val);
+					const header = parseBlockHeader(val);
+					if (header) {
+						const block = parseBlockScalar(i + 1, indent, header.style, header.chomp);
+						obj[key] = block.value;
+						i = block.endLine;
+					} else if (val === "") {
+						// Nested structure will follow
+						obj[key] = null; // Placeholder
+					} else {
+						obj[key] = parseValue(val);
+					}
 				}
 
 				// Find the array in parent
@@ -280,7 +392,15 @@ export function parseYaml(content: string): Record<string, unknown> {
 				const arrays = Object.entries(parent).filter(([, v]) => Array.isArray(v));
 				if (arrays.length > 0) {
 					const [, arr] = arrays[arrays.length - 1];
-					(arr as unknown[]).push(stripQuotes(stripInlineComment(afterDash.trim())));
+					const itemValue = stripInlineComment(afterDash.trim());
+					const header = parseBlockHeader(itemValue);
+					if (header) {
+						const block = parseBlockScalar(i + 1, indent, header.style, header.chomp);
+						(arr as unknown[]).push(block.value);
+						i = block.endLine;
+					} else {
+						(arr as unknown[]).push(stripQuotes(itemValue));
+					}
 				}
 			}
 			continue;
@@ -312,7 +432,14 @@ export function parseYaml(content: string): Record<string, unknown> {
 				const arrContent = value.slice(1, -1);
 				parent[key] = arrContent.split(",").map((s) => stripQuotes(s.trim()));
 			} else {
-				parent[key] = parseValue(value);
+				const header = parseBlockHeader(value);
+				if (header) {
+					const block = parseBlockScalar(i + 1, indent, header.style, header.chomp);
+					parent[key] = block.value;
+					i = block.endLine;
+				} else {
+					parent[key] = parseValue(value);
+				}
 			}
 		}
 	}
@@ -447,6 +574,374 @@ export function parseFrontmatter(content: string): {
 	return { frontmatter, body };
 }
 
+export function mergeFrontmatterWithBody(originalContent: string, body: string): string {
+	const normalized = originalContent.replace(/^\uFEFF/, "").replaceAll("\r\n", "\n");
+	const lines = normalized.split("\n");
+
+	let i = 0;
+	while (i < lines.length && lines[i].trim() === "") i += 1;
+	if (i >= lines.length || lines[i].trim() !== "---") {
+		return body;
+	}
+
+	i += 1;
+	while (i < lines.length && lines[i].trim() !== "---") {
+		i += 1;
+	}
+	if (i >= lines.length) return body;
+	i += 1; // consume closing ---
+
+	const prefix = lines.slice(0, i).join("\n");
+	return `${prefix}\n${body}`;
+}
+
+export function normalizeProfileTags(value: unknown): string[] {
+	if (Array.isArray(value)) {
+		return value
+			.filter((entry): entry is string => typeof entry === "string")
+			.map((entry) => entry.trim().toLowerCase())
+			.filter((entry) => entry.length > 0);
+	}
+
+	if (typeof value !== "string") return [];
+	const raw = value.trim();
+	if (!raw) return [];
+
+	if (raw.startsWith("[") && raw.endsWith("]")) {
+		const inner = raw.slice(1, -1).trim();
+		if (!inner) return [];
+		return inner
+			.split(",")
+			.map((entry) => stripQuotes(entry.trim()).toLowerCase())
+			.filter((entry) => entry.length > 0);
+	}
+
+	return [stripQuotes(raw).toLowerCase()].filter((entry) => entry.length > 0);
+}
+
+function normalizePathForMatch(pathValue: string): string {
+	return pathValue
+		.replaceAll("\\", "/")
+		.replace(/^\.\/+/, "")
+		.replace(/^\/+/, "");
+}
+
+export function pagePathForData(siteRoot: string, docroot: string, filePath: string): string {
+	const relFromDocroot = normalizePathForMatch(relative(resolve(siteRoot, docroot), filePath));
+	if (relFromDocroot && !relFromDocroot.startsWith("../")) return relFromDocroot;
+	return normalizePathForMatch(relative(siteRoot, filePath));
+}
+
+function toStringRecord(raw: unknown): Record<string, string> {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+	const result: Record<string, string> = {};
+	for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+		if (typeof value === "string") result[key] = value;
+		else if (typeof value === "number" || typeof value === "boolean") result[key] = String(value);
+	}
+	return result;
+}
+
+function toSnippetArray(raw: unknown): DataSnippet[] {
+	if (!Array.isArray(raw)) return [];
+	return raw
+		.map((item) => {
+			if (!item || typeof item !== "object") return null;
+			const entry = item as Record<string, unknown>;
+			if (typeof entry.slot !== "string" || typeof entry.content !== "string") return null;
+			return { slot: entry.slot, content: entry.content };
+		})
+		.filter((item): item is DataSnippet => !!item);
+}
+
+function validateSchemaNode(
+	value: unknown,
+	schema: unknown,
+	pathLabel: string,
+	dataPath: string,
+): void {
+	if (!schema || typeof schema !== "object") return;
+	const schemaObj = schema as Record<string, unknown>;
+	const type = typeof schemaObj.type === "string" ? schemaObj.type : undefined;
+
+	if (type) {
+		const valid =
+			(type === "object" && value !== null && typeof value === "object" && !Array.isArray(value)) ||
+			(type === "array" && Array.isArray(value)) ||
+			(type === "string" && typeof value === "string") ||
+			(type === "number" && typeof value === "number") ||
+			(type === "boolean" && typeof value === "boolean");
+		if (!valid) {
+			throw new Error(`schema validation failed at ${pathLabel} in ${dataPath}: expected ${type}`);
+		}
+	}
+
+	if (type === "string" && typeof value === "string" && typeof schemaObj.pattern === "string") {
+		const re = new RegExp(schemaObj.pattern);
+		if (!re.test(value)) {
+			throw new Error(
+				`schema validation failed at ${pathLabel} in ${dataPath}: value does not match pattern`,
+			);
+		}
+	}
+
+	if (type === "object" && value && typeof value === "object" && !Array.isArray(value)) {
+		const obj = value as Record<string, unknown>;
+		const required = Array.isArray(schemaObj.required)
+			? schemaObj.required.filter((key): key is string => typeof key === "string")
+			: [];
+		for (const key of required) {
+			if (!(key in obj)) {
+				throw new Error(`schema validation failed at ${pathLabel}.${key} in ${dataPath}: required`);
+			}
+		}
+		if (schemaObj.properties && typeof schemaObj.properties === "object") {
+			for (const [key, subSchema] of Object.entries(
+				schemaObj.properties as Record<string, unknown>,
+			)) {
+				if (key in obj) {
+					validateSchemaNode(obj[key], subSchema, `${pathLabel}.${key}`, dataPath);
+				}
+			}
+		}
+	}
+
+	if (type === "array" && Array.isArray(value) && schemaObj.items) {
+		for (const [idx, item] of value.entries()) {
+			validateSchemaNode(item, schemaObj.items, `${pathLabel}[${idx}]`, dataPath);
+		}
+	}
+}
+
+async function maybeValidateDataSchema(resolvedDataPath: string, parsed: unknown): Promise<void> {
+	const schemaPath = resolvedDataPath.replace(/\.(ya?ml|json)$/i, ".schema.json");
+	if (!(await exists(schemaPath))) return;
+
+	let schema: unknown;
+	try {
+		schema = JSON.parse(await readFile(schemaPath, "utf-8"));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`schema validation failed: invalid schema JSON ${schemaPath} (${message})`);
+	}
+
+	validateSchemaNode(parsed, schema, "$", normalizePathForMatch(schemaPath));
+}
+
+function parseNumeric(value: string, formatter: string, key: string, filePath: string): number {
+	const n = Number(value);
+	if (Number.isNaN(n)) {
+		throw new Error(
+			`${formatter} formatter: "${value}" is not a number (key "${key}" in ${filePath})`,
+		);
+	}
+	return n;
+}
+
+function applyFormatter(formatter: string, value: string, key: string, filePath: string): string {
+	const round = formatter.match(/^round\((\d+)\)$/);
+	if (round) {
+		const n = parseNumeric(value, formatter, key, filePath);
+		return n.toFixed(parseInt(round[1], 10));
+	}
+
+	switch (formatter) {
+		case "dollar": {
+			const n = parseNumeric(value, formatter, key, filePath);
+			return Number.isInteger(n)
+				? `$${n.toLocaleString("en-US")}`
+				: `$${n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+		}
+		case "number":
+			return parseNumeric(value, formatter, key, filePath).toLocaleString("en-US");
+		case "percent":
+			return `${parseNumeric(value, formatter, key, filePath) * 100}%`;
+		case "upper":
+			return value.toUpperCase();
+		case "lower":
+			return value.toLowerCase();
+		default:
+			throw new Error(`unknown formatter "${formatter}" in ${filePath}`);
+	}
+}
+
+export async function loadDataBindings(
+	dataPath: string,
+	pagePath: string,
+	siteRoot: string,
+	docroot = ".",
+	dataroot = "data",
+): Promise<DataBindings> {
+	const siteRootReal = await realpath(siteRoot);
+	const normalizedDataPath = normalizePathForMatch(dataPath);
+	const dataDir = validatePath(siteRoot, ".", dataroot);
+	const resolved = validatePath(siteRoot, ".", normalizedDataPath);
+	if (!dataDir || !resolved) throw new Error(`data path escapes kitsite: ${dataPath}`);
+	if (!resolved.startsWith(`${dataDir}${sep}`) && resolved !== dataDir) {
+		throw new Error(`data path escapes dataroot: ${dataPath}`);
+	}
+	if (!(await exists(resolved))) {
+		throw new Error(`data file not found: ${dataPath}`);
+	}
+	const dataDirReal = await realpath(dataDir);
+	const resolvedReal = await realpath(resolved);
+	if (!dataDirReal.startsWith(`${siteRootReal}${sep}`) && dataDirReal !== siteRootReal) {
+		throw new Error(`data path escapes kitsite: ${dataPath}`);
+	}
+	if (!resolvedReal.startsWith(`${siteRootReal}${sep}`) && resolvedReal !== siteRootReal) {
+		throw new Error(`data path escapes kitsite: ${dataPath}`);
+	}
+	if (!resolvedReal.startsWith(`${dataDirReal}${sep}`) && resolvedReal !== dataDirReal) {
+		throw new Error(`data path escapes dataroot: ${dataPath}`);
+	}
+
+	const raw = await readFile(resolved, "utf-8");
+	const parsed = normalizedDataPath.endsWith(".json")
+		? JSON.parse(raw)
+		: (parseYaml(raw) as Record<string, unknown>);
+	await maybeValidateDataSchema(resolved, parsed);
+
+	const doc = parsed as Record<string, unknown>;
+	const globals = toStringRecord(doc.globals);
+	const normalizedPagePath = normalizePathForMatch(pagePath);
+	const rootRelativePagePath = normalizePathForMatch(
+		relative(siteRoot, resolve(siteRoot, docroot, normalizedPagePath)),
+	);
+	const pages = Array.isArray(doc.pages) ? doc.pages : [];
+	const pageEntry = pages.find((entry) => {
+		if (!entry || typeof entry !== "object") return false;
+		const pathValue = normalizePathForMatch((entry as Record<string, unknown>).path as string);
+		return pathValue === normalizedPagePath || pathValue === rootRelativePagePath;
+	}) as Record<string, unknown> | undefined;
+
+	return {
+		globals,
+		inject: pageEntry ? toStringRecord(pageEntry.inject) : {},
+		snippets: pageEntry ? toSnippetArray(pageEntry.snippets) : [],
+	};
+}
+
+export function resolveBindings(content: string, bindings: DataBindings, filePath: string): string {
+	const values = { ...bindings.globals, ...bindings.inject };
+
+	const resolvedSnippets = content.replace(
+		/\{\{\s*snippet:([A-Za-z0-9][\w-]*)\s*\}\}/g,
+		(_match, slot: string) => {
+			const snippet = bindings.snippets.find((entry) => entry.slot === slot);
+			if (!snippet) throw new Error(`unknown snippet "${slot}" in ${filePath}`);
+			return snippet.content;
+		},
+	);
+
+	return resolvedSnippets.replace(
+		/\{\{\s*([A-Za-z0-9][\w-]*)(\s*(?:\|[^}]+)?)\s*\}\}/g,
+		(_match, key: string, rawPipeline: string) => {
+			const value = values[key];
+			if (value === undefined) throw new Error(`unresolved binding "${key}" in ${filePath}`);
+			const steps = rawPipeline
+				.split("|")
+				.map((part) => part.trim())
+				.filter(Boolean);
+			return steps.reduce((acc, step) => applyFormatter(step, acc, key, filePath), value);
+		},
+	);
+}
+
+function commandForPlatform(command: string): string[] {
+	if (process.platform === "win32") return ["cmd", "/d", "/s", "/c", command];
+	return ["sh", "-lc", command];
+}
+
+export async function runPrebuildHooks(
+	hooks: PrebuildHook[],
+	siteRoot: string,
+	buildMode: "dev" | "build" | "bundle",
+	profile?: string,
+	dataroot = "data",
+	changedPath?: string,
+): Promise<number> {
+	if (!hooks.length) return 0;
+	const normalizedChangedPath = changedPath ? normalizePathForMatch(changedPath) : undefined;
+	const filteredHooks = normalizedChangedPath
+		? hooks.filter((hook) =>
+				Array.isArray(hook.watch)
+					? hook.watch.some((pattern) => globMatch(pattern, normalizedChangedPath))
+					: false,
+			)
+		: hooks;
+	if (!filteredHooks.length) return 0;
+
+	const normalizedDataDir = `${normalizePathForMatch(dataroot).replace(/\/+$/, "") || "data"}/`;
+	const env = {
+		...process.env,
+		KITFLY_SITE_ROOT: siteRoot,
+		KITFLY_DATA_DIR: normalizedDataDir,
+		KITFLY_BUILD_MODE: buildMode,
+		...(profile ? { KITFLY_PROFILE: profile } : {}),
+	};
+
+	for (const hook of filteredHooks) {
+		if (!hook.command) continue;
+		const result = Bun.spawnSync(commandForPlatform(hook.command), {
+			cwd: siteRoot,
+			env,
+			stdout: "inherit",
+			stderr: "pipe",
+		});
+		if (result.exitCode !== 0) {
+			const stderr = new TextDecoder().decode(result.stderr).trim();
+			const detail = stderr ? `\n${stderr}` : "";
+			throw new Error(`prebuild hook failed (exit ${result.exitCode}): ${hook.command}${detail}`);
+		}
+	}
+
+	return filteredHooks.length;
+}
+
+export async function filterByProfile(
+	files: ContentFile[],
+	activeProfile?: string,
+	profileConfig?: Record<string, ProfileConfig>,
+): Promise<ContentFile[]> {
+	const normalizedProfile = activeProfile?.trim().toLowerCase();
+	const hasProfilesConfig = !!profileConfig && Object.keys(profileConfig).length > 0;
+	if (!normalizedProfile && !hasProfilesConfig) {
+		// Backward compatibility: no profiles configured means no filtering at all.
+		return files;
+	}
+
+	let allowedTags = normalizedProfile ? [normalizedProfile] : [];
+	if (normalizedProfile && profileConfig?.[normalizedProfile]?.include?.tags) {
+		allowedTags = normalizeProfileTags(profileConfig[normalizedProfile].include?.tags ?? []);
+	}
+
+	const filtered: ContentFile[] = [];
+	for (const file of files) {
+		let content = "";
+		try {
+			content = await readFile(file.path, "utf-8");
+		} catch {
+			// If a file disappears during watch/build, skip it.
+			continue;
+		}
+		const { frontmatter } = parseFrontmatter(content);
+		const tags = normalizeProfileTags(frontmatter.profile);
+
+		// Untagged content is always included.
+		if (tags.length === 0) {
+			filtered.push(file);
+			continue;
+		}
+
+		// Tagged content is opt-in via active profile match.
+		if (normalizedProfile && tags.some((tag) => allowedTags.includes(tag))) {
+			filtered.push(file);
+		}
+	}
+
+	return filtered;
+}
+
 export function slugify(text: string): string {
 	return text
 		.toLowerCase()
@@ -506,6 +1001,11 @@ const SLIDES_VISUALS_TYPES = new Set([
 	"layer-cake",
 	"pyramid",
 	"funnel",
+	"timeline-horizontal",
+	"timeline-vertical",
+	"flow-branching",
+	"flow-converging",
+	"staircase",
 ]);
 
 const SLIDES_VISUALS_RULES: Record<
@@ -564,6 +1064,31 @@ const SLIDES_VISUALS_RULES: Record<
 		scalars: [],
 		lists: { stages: { kind: "strings" } },
 	},
+	"timeline-horizontal": {
+		required: ["events"],
+		scalars: [],
+		lists: { events: { kind: "objects", fields: ["label"], optional: ["date"] } },
+	},
+	"timeline-vertical": {
+		required: ["events"],
+		scalars: [],
+		lists: { events: { kind: "objects", fields: ["label"], optional: ["date"] } },
+	},
+	"flow-branching": {
+		required: ["source", "branches"],
+		scalars: ["source", "split"],
+		lists: { branches: { kind: "strings" } },
+	},
+	"flow-converging": {
+		required: ["sources", "target"],
+		scalars: ["target", "merge"],
+		lists: { sources: { kind: "strings" } },
+	},
+	staircase: {
+		required: ["steps"],
+		scalars: ["direction"],
+		lists: { steps: { kind: "strings" } },
+	},
 };
 
 /**
@@ -754,6 +1279,12 @@ export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenc
 	return diagnostics;
 }
 
+export function filterUnknownSlidesVisualsTypeDiagnostics(
+	diagnostics: SlidesVisualsFenceDiagnostic[],
+): SlidesVisualsFenceDiagnostic[] {
+	return diagnostics.filter((d) => !d.message.startsWith("Unknown slides-visuals block type:"));
+}
+
 /**
  * Split markdown content into slide chunks using explicit delimiter.
  * Delimiter lines inside fenced code blocks are ignored.
@@ -848,7 +1379,10 @@ export function segmentSlides(content: string, fallbackTitle: string): SlideSegm
  * Collect slide content objects from discovered content files.
  * Markdown files can produce multiple slides via explicit delimiters.
  */
-export async function collectSlides(files: ContentFile[]): Promise<SlideContent[]> {
+export async function collectSlides(
+	files: ContentFile[],
+	options: CollectSlidesOptions = {},
+): Promise<SlideContent[]> {
 	const slides: SlideContent[] = [];
 	let index = 0;
 
@@ -857,7 +1391,8 @@ export async function collectSlides(files: ContentFile[]): Promise<SlideContent[
 		const stem = basename(file.path, extname(file.path));
 
 		if (file.path.endsWith(".md")) {
-			const segments = segmentSlides(raw, stem);
+			const markdown = options.markdownTransform ? await options.markdownTransform(raw, file) : raw;
+			const segments = segmentSlides(markdown, stem);
 			for (const segment of segments) {
 				index += 1;
 				slides.push({
@@ -890,7 +1425,82 @@ export async function collectSlides(files: ContentFile[]): Promise<SlideContent[
 	return slides;
 }
 
-export function buildSlideNav(
+interface SlideNavGroup {
+	name: string;
+	groups: Map<string, SlideNavGroup>;
+	slides: SlideContent[];
+}
+
+function sectionRelativePath(sourceUrlPath: string, sectionBase: string): string {
+	if (!sectionBase) return sourceUrlPath;
+	if (sourceUrlPath === sectionBase) return "";
+	if (sourceUrlPath.startsWith(`${sectionBase}/`))
+		return sourceUrlPath.slice(sectionBase.length + 1);
+	return sourceUrlPath;
+}
+
+function toTitleCaseSlug(segment: string): string {
+	return segment
+		.split(/[-_]/)
+		.filter(Boolean)
+		.map((token) => token.charAt(0).toUpperCase() + token.slice(1))
+		.join(" ");
+}
+
+function createSlideNavGroup(name: string): SlideNavGroup {
+	return { name, groups: new Map(), slides: [] };
+}
+
+function buildSlideSectionTree(items: SlideContent[], sectionBase: string): SlideNavGroup {
+	const root = createSlideNavGroup("");
+	for (const slide of items) {
+		const rel = sectionRelativePath(slide.sourceUrlPath, sectionBase);
+		const segments = rel.split("/").filter(Boolean);
+		segments.pop(); // Drop file stem so nav groups only reflect subfolders.
+
+		let node = root;
+		for (const segment of segments) {
+			let next = node.groups.get(segment);
+			if (!next) {
+				next = createSlideNavGroup(toTitleCaseSlug(segment));
+				node.groups.set(segment, next);
+			}
+			node = next;
+		}
+		node.slides.push(slide);
+	}
+	return root;
+}
+
+function slideGroupContains(group: SlideNavGroup, currentSlideId: string | undefined): boolean {
+	if (!currentSlideId) return false;
+	if (group.slides.some((slide) => slide.id === currentSlideId)) return true;
+	for (const child of group.groups.values()) {
+		if (slideGroupContains(child, currentSlideId)) return true;
+	}
+	return false;
+}
+
+function renderSlideGroup(group: SlideNavGroup, currentSlideId?: string): string {
+	let html = "<ul>";
+
+	for (const slide of group.slides) {
+		const active = currentSlideId === slide.id ? ' class="active"' : "";
+		html += `<li><a href="#${slide.id}"${active}>${escapeHtml(slide.title)}</a></li>`;
+	}
+
+	for (const child of group.groups.values()) {
+		const open = slideGroupContains(child, currentSlideId) ? " open" : "";
+		html += `<li><details${open}><summary class="nav-group">${escapeHtml(child.name)}</summary>`;
+		html += renderSlideGroup(child, currentSlideId);
+		html += "</details></li>";
+	}
+
+	html += "</ul>";
+	return html;
+}
+
+export function buildSlideNavHierarchical(
 	slides: SlideContent[],
 	config: SiteConfig,
 	currentSlideId?: string,
@@ -905,17 +1515,25 @@ export function buildSlideNav(
 	for (const section of config.sections) {
 		const items = grouped.get(section.name);
 		if (!items || items.length === 0) continue;
-		html += `<li><span class="nav-section">${escapeHtml(section.name)}</span><ul>`;
-		for (const slide of items) {
-			const active = currentSlideId === slide.id ? ' class="active"' : "";
-			html += `<li><a href="#${slide.id}"${active}>${escapeHtml(slide.title)}</a></li>`;
-		}
-		html += "</ul></li>";
+		const sectionBase = section.path.replace(/^\/+|\/+$/g, "");
+		const tree = buildSlideSectionTree(items, sectionBase);
+		html += `<li><span class="nav-section">${escapeHtml(section.name)}</span>`;
+		html += renderSlideGroup(tree, currentSlideId);
+		html += "</li>";
 	}
 	html += "</ul>";
 	return html;
 }
 
+// Backwards-compatible alias.
+export function buildSlideNav(
+	slides: SlideContent[],
+	config: SiteConfig,
+	currentSlideId?: string,
+): string {
+	return buildSlideNavHierarchical(slides, config, currentSlideId);
+}
+
 function resolveRelativeContentPath(pathOrRef: string, currentUrlPath?: string): string {
 	let cleaned = pathOrRef;
 	if (currentUrlPath && !cleaned.startsWith("/")) {
@@ -1442,10 +2060,68 @@ export function buildPageMeta(frontmatter: Record<string, unknown>): string {
 	return `<div class="page-meta">Last updated: ${formatted}</div>`;
 }
 
+interface LogoImgHtmlOptions {
+	logo: string;
+	logoDark?: string;
+	alt: string;
+	className?: string;
+	pathPrefix?: string;
+	onerrorFallback?: boolean;
+	style?: string;
+}
+
+export function buildLogoImgHtml(options: LogoImgHtmlOptions): string {
+	const className = options.className || "logo-img";
+	const pathPrefix = options.pathPrefix || "";
+	const onerror = options.onerrorFallback
+		? `onerror="this.onerror=null;this.style.display='none';this.parentElement.classList.add('logo-fallback')"`
+		: `onerror="this.onerror=null;this.style.display='none'"`;
+	const style = options.style ? `style="${escapeHtml(options.style)}"` : "";
+	const lightSrc = `${pathPrefix}${options.logo}`;
+	const alt = escapeHtml(options.alt);
+
+	if (!options.logoDark) {
+		return `<img src="${escapeHtml(lightSrc)}" alt="${alt}" class="${className}" ${style} ${onerror}>`;
+	}
+
+	const darkSrc = `${pathPrefix}${options.logoDark}`;
+	return `<img src="${escapeHtml(lightSrc)}" alt="${alt}" class="${className} logo-light" ${style} ${onerror}>
+<img src="${escapeHtml(darkSrc)}" alt="${alt}" class="${className} logo-dark" ${style} onerror="this.onerror=null;this.style.display='none'">`;
+}
+
 /**
  * Build footer HTML from provenance
  */
-export function buildFooter(provenance: Provenance, config: SiteConfig): string {
+function renderFooterLogo(
+	footer: SiteFooter,
+	config: SiteConfig,
+	pathPrefix: string,
+	logoOverride?: string,
+	logoDarkOverride?: string,
+): string {
+	const footerLogo = logoOverride || footer.logo;
+	if (!footerLogo) return "";
+
+	const altText = footer.logoAlt || footer.copyright || config.brand.name;
+	const logoHeight = footer.logoHeight ?? 20;
+	const logoDark = logoDarkOverride || footer.logoDark;
+	const image = buildLogoImgHtml({
+		logo: footerLogo,
+		logoDark,
+		alt: altText,
+		className: "footer-logo-img",
+		pathPrefix: logoOverride ? "" : pathPrefix,
+		onerrorFallback: false,
+		style: `max-height: ${logoHeight}px`,
+	});
+	const wrapped = footer.logoUrl
+		? `<a href="${escapeHtml(footer.logoUrl)}" class="footer-logo-link">${image}</a>`
+		: `<span class="footer-logo-link">${image}</span>`;
+
+	return `${wrapped}<span class="footer-separator">·</span>`;
+}
+
+export function buildFooter(provenance: Provenance, config: SiteConfig, pathPrefix = ""): string {
 	const commitDate = formatDate(provenance.gitCommitDate);
 	const publishYear = Number.isNaN(new Date(provenance.gitCommitDate).getTime())
 		? new Date().getFullYear().toString()
@@ -1474,11 +2150,13 @@ export function buildFooter(provenance: Provenance, config: SiteConfig): string
 		? `<span class="footer-version">v${escapeHtml(provenance.version)}</span>
           <span class="footer-separator">·</span>`
 		: "";
+	const footerLogoHtml = renderFooterLogo(footer, config, pathPrefix);
 
 	return `
     <footer class="site-footer">
       <div class="footer-content">
         <div class="footer-left">
+          ${footerLogoHtml}
           ${versionHtml}
           <span class="footer-commit" title="Commit: ${escapeHtml(provenance.gitCommit)}">Published ${commitDate}</span>
         </div>
@@ -1500,7 +2178,12 @@ export function buildFooter(provenance: Provenance, config: SiteConfig): string
 /**
  * Build bundle footer HTML.
  */
-export function buildBundleFooter(version: string | undefined, config: SiteConfig): string {
+export function buildBundleFooter(
+	version: string | undefined,
+	config: SiteConfig,
+	logoOverride?: string,
+	logoDarkOverride?: string,
+): string {
 	const footer = config.footer || {};
 	const copyrightText = footer.copyright
 		? escapeHtml(footer.copyright)
@@ -1525,11 +2208,13 @@ export function buildBundleFooter(version: string | undefined, config: SiteConfi
 		? `<span class="footer-version">v${escapeHtml(version)}</span>
         <span class="footer-separator">·</span>`
 		: "";
+	const footerLogoHtml = renderFooterLogo(footer, config, "", logoOverride, logoDarkOverride);
 
 	return `
   <footer class="site-footer">
     <div class="footer-content">
       <div class="footer-left">
+        ${footerLogoHtml}
         ${versionHtml}
         <span class="footer-commit">Published (offline bundle)</span>
       </div>
@@ -1727,6 +2412,7 @@ function normalizeFooter(footer: unknown): SiteFooter | undefined {
 	if (!footer || typeof footer !== "object") return undefined;
 	const raw = footer as Record<string, unknown>;
 	let links: FooterLink[] | undefined;
+	let logoHeight: number | undefined;
 
 	if (Array.isArray(raw.links)) {
 		links = raw.links
@@ -1743,15 +2429,66 @@ function normalizeFooter(footer: unknown): SiteFooter | undefined {
 			console.warn("⚠ site.yaml footer.links supports at most 10 links; truncating extras.");
 		}
 	}
+	const parsedLogoHeight =
+		typeof raw.logoHeight === "number"
+			? raw.logoHeight
+			: typeof raw.logoHeight === "string"
+				? Number.parseInt(raw.logoHeight, 10)
+				: NaN;
+	if (Number.isInteger(parsedLogoHeight)) {
+		logoHeight = Math.max(10, Math.min(40, parsedLogoHeight));
+	}
 
 	return {
 		copyright: typeof raw.copyright === "string" ? raw.copyright : undefined,
 		copyrightUrl: typeof raw.copyrightUrl === "string" ? raw.copyrightUrl : undefined,
 		links,
 		attribution: typeof raw.attribution === "boolean" ? raw.attribution : undefined,
+		logo: typeof raw.logo === "string" ? raw.logo : undefined,
+		logoDark: typeof raw.logoDark === "string" ? raw.logoDark : undefined,
+		logoUrl: typeof raw.logoUrl === "string" ? raw.logoUrl : undefined,
+		logoAlt: typeof raw.logoAlt === "string" ? raw.logoAlt : undefined,
+		logoHeight,
 	};
 }
 
+function normalizeProfiles(raw: unknown): Record<string, ProfileConfig> | undefined {
+	if (!raw || typeof raw !== "object") return undefined;
+	const entries = Object.entries(raw as Record<string, unknown>);
+	if (entries.length === 0) return undefined;
+
+	const profiles: Record<string, ProfileConfig> = {};
+	for (const [name, value] of entries) {
+		if (!value || typeof value !== "object") continue;
+		const profileRaw = value as Record<string, unknown>;
+		const tags = normalizeProfileTags(
+			(profileRaw.include as Record<string, unknown> | undefined)?.tags,
+		);
+		profiles[name.trim().toLowerCase()] = {
+			description: typeof profileRaw.description === "string" ? profileRaw.description : undefined,
+			include: tags.length > 0 ? { tags } : undefined,
+		};
+	}
+
+	return Object.keys(profiles).length > 0 ? profiles : undefined;
+}
+
+function normalizePrebuild(raw: unknown): PrebuildHook[] | undefined {
+	if (!Array.isArray(raw)) return undefined;
+	const hooks = raw
+		.map((entry) => {
+			if (!entry || typeof entry !== "object") return null;
+			const record = entry as Record<string, unknown>;
+			if (typeof record.command !== "string" || !record.command.trim()) return null;
+			const watch = Array.isArray(record.watch)
+				? record.watch.filter((item): item is string => typeof item === "string" && !!item.trim())
+				: undefined;
+			return { command: record.command.trim(), watch } as PrebuildHook;
+		})
+		.filter((hook): hook is PrebuildHook => !!hook);
+	return hooks.length > 0 ? hooks : undefined;
+}
+
 /**
  * Load site configuration with fallback chain
  * @param root - The root directory
@@ -1775,6 +2512,7 @@ export async function loadSiteConfig(
 
 		return {
 			docroot: parsed.docroot || ".",
+			dataroot: typeof parsedRecord.dataroot === "string" ? parsedRecord.dataroot : "data",
 			title: parsed.title,
 			version: typeof parsedRecord.version === "string" ? parsedRecord.version : undefined,
 			mode: parsedRecord.mode === "slides" ? "slides" : "docs",
@@ -1789,12 +2527,15 @@ export async function loadSiteConfig(
 			brand: {
 				...parsed.brand,
 				logo: parsed.brand.logo || "assets/brand/logo.png",
+				logoDark: typeof parsed.brand.logoDark === "string" ? parsed.brand.logoDark : undefined,
 				favicon: parsed.brand.favicon || "assets/brand/favicon.png",
 				logoType: parsed.brand.logoType || "icon",
 			},
 			sections: parsed.sections,
 			footer: normalizeFooter(parsedRecord.footer),
 			server: parsed.server,
+			profiles: normalizeProfiles(parsedRecord.profiles),
+			prebuild: normalizePrebuild(parsedRecord.prebuild),
 		};
 	} catch (e) {
 		if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
@@ -1823,6 +2564,7 @@ export async function loadSiteConfig(
 		if (sections.length > 0) {
 			return {
 				docroot: "content",
+				dataroot: "data",
 				title: "Documentation",
 				mode: "docs",
 				aspect: "16/9",
@@ -1837,6 +2579,7 @@ export async function loadSiteConfig(
 	// Final fallback
 	return {
 		docroot: ".",
+		dataroot: "data",
 		title: defaultTitle,
 		mode: "docs",
 		aspect: "16/9",