kitfly 0.2.1 → 0.2.4

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()
@@ -513,17 +1008,16 @@ const SLIDES_VISUALS_TYPES = new Set([
 	"staircase",
 ]);
 
-const SLIDES_VISUALS_RULES: Record<
-	string,
-	{
-		required: string[];
-		scalars: string[];
-		lists: Record<
-			string,
-			{ kind: "strings" } | { kind: "objects"; fields: string[]; optional?: string[] }
-		>;
-	}
-> = {
+type VisualListRule =
+	| { kind: "strings" }
+	| { kind: "objects"; fields: string[]; optional?: string[] };
+type VisualRules = {
+	required: string[];
+	scalars: string[];
+	lists: Record<string, VisualListRule>;
+};
+
+const SLIDES_VISUALS_RULES: Record<string, VisualRules> = {
 	kpi: {
 		required: ["label", "value"],
 		scalars: ["label", "value", "trend"],
@@ -596,11 +1090,44 @@ const SLIDES_VISUALS_RULES: Record<
 	},
 };
 
-/**
- * Validate slides-visuals `:::` blocks in a single markdown slide body.
- * This contract is intentionally strict so writers/devs don’t guess at edge cases.
- */
-export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenceDiagnostic[] {
+const PLANNING_VISUALS_TYPES = new Set(["gantt"]);
+
+const PLANNING_VISUALS_RULES: Record<string, VisualRules> = {
+	gantt: {
+		required: ["time-unit", "time-start", "time-end", "tracks"],
+		scalars: ["label", "time-unit", "time-start", "time-end", "max-depth", "max-tracks", "today"],
+		lists: {
+			tracks: {
+				kind: "objects",
+				fields: ["label", "depth", "start", "end"],
+				optional: ["status"],
+			},
+			milestones: {
+				kind: "objects",
+				fields: ["label", "date"],
+				optional: ["depth"],
+			},
+			markers: {
+				kind: "objects",
+				fields: ["label", "date"],
+				optional: ["color"],
+			},
+		},
+	},
+};
+
+function parseQuotedScalar(raw: string): string {
+	const trimmed = raw.trim();
+	const match = trimmed.match(/^"(.*)"$/) || trimmed.match(/^'(.*)'$/);
+	return match ? match[1] : trimmed;
+}
+
+function validateVisualFences(
+	markdown: string,
+	visualTypes: Set<string>,
+	visualRules: Record<string, VisualRules>,
+	unknownTypePrefix: string,
+): SlidesVisualsFenceDiagnostic[] {
 	const diagnostics: SlidesVisualsFenceDiagnostic[] = [];
 	const lines = markdown.replaceAll("\r\n", "\n").split("\n");
 
@@ -618,7 +1145,7 @@ export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenc
 	}
 
 	function finishFence(closeLine: number) {
-		const rules = SLIDES_VISUALS_RULES[visualType];
+		const rules = visualRules[visualType];
 		if (!rules) return;
 
 		for (const key of rules.required) {
@@ -664,10 +1191,10 @@ export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenc
 			const m = raw.match(/^:::\s*([a-z0-9-]+)\s*$/i);
 			if (!m) continue;
 			const type = m[1].toLowerCase();
-			if (!SLIDES_VISUALS_TYPES.has(type)) {
+			if (!visualTypes.has(type)) {
 				diagnostics.push({
 					line: i + 1,
-					message: `Unknown slides-visuals block type: ${type}`,
+					message: `${unknownTypePrefix}${type}`,
 					type,
 				});
 				continue;
@@ -682,7 +1209,6 @@ export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenc
 			continue;
 		}
 
-		// inside visual fence
 		if (trimmed === ":::" && !raw.startsWith(":::")) {
 			err(i + 1, "Closing ::: fence must start at column 0");
 			continue;
@@ -702,13 +1228,12 @@ export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenc
 		}
 
 		if (/^\s/.test(raw)) {
-			// list item or list continuation
 			if (!currentListKey) {
 				err(i + 1, "Indented content is only allowed inside a list");
 				continue;
 			}
 
-			const listRule = SLIDES_VISUALS_RULES[visualType]?.lists[currentListKey];
+			const listRule = visualRules[visualType]?.lists[currentListKey];
 			const item = raw.match(/^ {2}-\s+(.+)$/);
 			if (item) {
 				listItems += 1;
@@ -739,7 +1264,7 @@ export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenc
 			continue;
 		}
 
-		const rules = SLIDES_VISUALS_RULES[visualType];
+		const rules = visualRules[visualType];
 		if (!rules) continue;
 
 		const kv = raw.match(/^([a-z][a-z0-9-]*)\s*:\s*(.*)$/i);
@@ -752,7 +1277,6 @@ export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenc
 		const value = kv[2];
 
 		if (value === "") {
-			// list key
 			const listRule = rules.lists[key];
 			if (!listRule) {
 				err(i + 1, `Key '${key}' is not a supported list for ${visualType}`);
@@ -764,7 +1288,6 @@ export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenc
 			continue;
 		}
 
-		// scalar key
 		if (!rules.scalars.includes(key)) {
 			err(i + 1, `Key '${key}' is not a supported scalar for ${visualType}`);
 			continue;
@@ -784,12 +1307,408 @@ export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenc
 	return diagnostics;
 }
 
+/**
+ * Validate slides-visuals `:::` blocks in a single markdown slide body.
+ * This contract is intentionally strict so writers/devs don’t guess at edge cases.
+ */
+export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenceDiagnostic[] {
+	return validateVisualFences(
+		markdown,
+		SLIDES_VISUALS_TYPES,
+		SLIDES_VISUALS_RULES,
+		"Unknown slides-visuals block type: ",
+	);
+}
+
+type ParsedPlanningBlock = {
+	startLine: number;
+	data: Record<string, unknown>;
+	scalarLines: Record<string, number>;
+	listLines: Record<string, number>;
+};
+
+function parsePlanningGanttBlocks(markdown: string): ParsedPlanningBlock[] {
+	const blocks: ParsedPlanningBlock[] = [];
+	const lines = markdown.replaceAll("\r\n", "\n").split("\n");
+	let mdFence: FenceState | null = null;
+	let current: ParsedPlanningBlock | null = null;
+	let currentList: string | null = null;
+	let currentObject: Record<string, unknown> | null = null;
+
+	for (let i = 0; i < lines.length; i++) {
+		const raw = lines[i];
+		const trimmed = raw.trim();
+		const lineNo = i + 1;
+
+		mdFence = updateFenceState(trimmed, mdFence);
+		if (mdFence) continue;
+
+		if (!current) {
+			const open = raw.match(/^:::\s*([a-z0-9-]+)\s*$/i);
+			if (!open || open[1].toLowerCase() !== "gantt") continue;
+			current = {
+				startLine: lineNo,
+				data: {},
+				scalarLines: {},
+				listLines: {},
+			};
+			currentList = null;
+			currentObject = null;
+			continue;
+		}
+
+		if (raw.match(/^:::\s*$/)) {
+			blocks.push(current);
+			current = null;
+			currentList = null;
+			currentObject = null;
+			continue;
+		}
+
+		const kv = raw.match(/^([a-z][a-z0-9-]*)\s*:\s*(.*)$/i);
+		if (kv) {
+			const key = kv[1].toLowerCase();
+			const value = kv[2];
+			if (value === "") {
+				currentList = key;
+				currentObject = null;
+				current.listLines[key] = lineNo;
+				if (!Array.isArray(current.data[key])) current.data[key] = [];
+			} else {
+				current.data[key] = parseQuotedScalar(value);
+				current.scalarLines[key] = lineNo;
+				currentList = null;
+				currentObject = null;
+			}
+			continue;
+		}
+
+		const item = raw.match(/^ {2}-\s+(.+)$/);
+		if (item && currentList) {
+			const list: unknown[] = Array.isArray(current.data[currentList])
+				? (current.data[currentList] as unknown[])
+				: [];
+			current.data[currentList] = list;
+			const objKV = item[1].match(/^([a-z][a-z0-9-]*)\s*:\s*(.+)$/i);
+			if (objKV) {
+				currentObject = { [objKV[1].toLowerCase()]: parseQuotedScalar(objKV[2]) };
+				list.push(currentObject);
+			} else {
+				currentObject = null;
+				list.push(parseQuotedScalar(item[1]));
+			}
+			continue;
+		}
+
+		const cont = raw.match(/^ {4}([a-z][a-z0-9-]*)\s*:\s*(.+)$/i);
+		if (cont && currentObject) {
+			currentObject[cont[1].toLowerCase()] = parseQuotedScalar(cont[2]);
+		}
+	}
+
+	return blocks;
+}
+
+function isoWeeksInYear(year: number): number {
+	const dec28 = new Date(Date.UTC(year, 11, 28));
+	return getIsoWeekInfo(Math.floor(dec28.getTime() / (24 * 60 * 60 * 1000))).week;
+}
+
+function isoWeekMondayUtcMs(year: number, week: number): number {
+	const jan4 = new Date(Date.UTC(year, 0, 4));
+	const jan4Weekday = (jan4.getUTCDay() + 6) % 7; // Monday=0
+	const weekOneMondayMs = jan4.getTime() - jan4Weekday * 24 * 60 * 60 * 1000;
+	return weekOneMondayMs + (week - 1) * 7 * 24 * 60 * 60 * 1000;
+}
+
+function parseWeekOrdinal(value: string): number | null {
+	const isoWeekAnchorDay = -3; // 1969-12-29 (Monday of 1970-W01)
+	const match = value.match(/^(\d{4})-W(\d{2})$/i);
+	if (!match) return null;
+	const year = Number.parseInt(match[1], 10);
+	const week = Number.parseInt(match[2], 10);
+	if (week < 1 || week > isoWeeksInYear(year)) return null;
+	const dayMs = 24 * 60 * 60 * 1000;
+	const mondayDayOrdinal = Math.floor(isoWeekMondayUtcMs(year, week) / dayMs);
+	return Math.floor((mondayDayOrdinal - isoWeekAnchorDay) / 7);
+}
+
+function parseMonthOrdinal(value: string): number | null {
+	const match = value.match(/^(\d{4})-(\d{2})$/);
+	if (!match) return null;
+	const year = Number.parseInt(match[1], 10);
+	const month = Number.parseInt(match[2], 10);
+	if (month < 1 || month > 12) return null;
+	return year * 12 + (month - 1);
+}
+
+function daysInMonthUtc(year: number, month: number): number {
+	return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+function parsePlanningMonthMarkerPosition(value: string): number | null {
+	const monthOrdinal = parseMonthOrdinal(value);
+	if (monthOrdinal != null) return monthOrdinal + 0.5;
+
+	const match = value.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+	if (!match) return null;
+	const year = Number.parseInt(match[1], 10);
+	const month = Number.parseInt(match[2], 10);
+	const day = Number.parseInt(match[3], 10);
+	if (month < 1 || month > 12) return null;
+	const dim = daysInMonthUtc(year, month);
+	if (day < 1 || day > dim) return null;
+	const ordinal = year * 12 + (month - 1);
+	return ordinal + (day - 0.5) / dim;
+}
+
+function parsePlanningUnitOrdinal(value: unknown, unit: string): number | null {
+	if (typeof value !== "string" || !value.trim()) return null;
+	if (unit === "week") return parseWeekOrdinal(value.trim());
+	if (unit === "month") return parseMonthOrdinal(value.trim());
+	return null;
+}
+
+function parsePlanningMarkerPosition(value: unknown, unit: string): number | null {
+	if (typeof value !== "string" || !value.trim()) return null;
+	const raw = value.trim();
+	if (unit === "week") {
+		const ordinal = parseWeekOrdinal(raw);
+		return ordinal == null ? null : ordinal + 0.5;
+	}
+	if (unit === "month") {
+		return parsePlanningMonthMarkerPosition(raw);
+	}
+	return null;
+}
+
+function getIsoWeekInfo(dayOrdinal: number): { year: number; week: number } {
+	const dayMs = 24 * 60 * 60 * 1000;
+	const date = new Date(dayOrdinal * dayMs);
+	const day = (date.getUTCDay() + 6) % 7; // Monday=0
+	const thursday = new Date(date.getTime() + (3 - day) * dayMs);
+	const year = thursday.getUTCFullYear();
+	const firstThursday = new Date(Date.UTC(year, 0, 4));
+	const firstThursdayDay = (firstThursday.getUTCDay() + 6) % 7;
+	const firstThursdayOrdinal = Math.floor(firstThursday.getTime() / dayMs) + (3 - firstThursdayDay);
+	const week = Math.floor((Math.floor(thursday.getTime() / dayMs) - firstThursdayOrdinal) / 7) + 1;
+	return { year, week };
+}
+
+export function validatePlanningVisualsFences(markdown: string): SlidesVisualsFenceDiagnostic[] {
+	const diagnostics = validateVisualFences(
+		markdown,
+		PLANNING_VISUALS_TYPES,
+		PLANNING_VISUALS_RULES,
+		"Unknown planning-visuals block type: ",
+	);
+	const ganttBlocks = parsePlanningGanttBlocks(markdown);
+
+	for (const block of ganttBlocks) {
+		const unitRaw = block.data["time-unit"];
+		const unit = typeof unitRaw === "string" ? unitRaw.trim().toLowerCase() : "";
+		const unitLine = block.scalarLines["time-unit"] ?? block.startLine;
+		const startLine = block.scalarLines["time-start"] ?? block.startLine;
+		const endLine = block.scalarLines["time-end"] ?? block.startLine;
+		const tracksLine = block.listLines.tracks ?? block.startLine;
+		const milestonesLine = block.listLines.milestones ?? block.startLine;
+
+		if (unit !== "week" && unit !== "month") {
+			diagnostics.push({
+				line: unitLine,
+				message: "Invalid time-unit (expected 'week' or 'month')",
+				type: "gantt",
+			});
+			continue;
+		}
+
+		const axisStart = parsePlanningUnitOrdinal(block.data["time-start"], unit);
+		const axisEnd = parsePlanningUnitOrdinal(block.data["time-end"], unit);
+		if (axisStart == null) {
+			diagnostics.push({
+				line: startLine,
+				message: `Invalid time-start format for ${unit}`,
+				type: "gantt",
+			});
+		}
+		if (axisEnd == null) {
+			diagnostics.push({
+				line: endLine,
+				message: `Invalid time-end format for ${unit}`,
+				type: "gantt",
+			});
+		}
+		if (axisStart != null && axisEnd != null && axisStart >= axisEnd) {
+			diagnostics.push({
+				line: endLine,
+				message: "time-start must be before time-end",
+				type: "gantt",
+			});
+		}
+
+		const todayRaw = block.data.today;
+		if (todayRaw != null && parsePlanningUnitOrdinal(todayRaw, unit) == null) {
+			diagnostics.push({
+				line: block.scalarLines.today ?? block.startLine,
+				message: `Invalid today format for ${unit}`,
+				type: "gantt",
+			});
+		}
+
+		const tracks = Array.isArray(block.data.tracks) ? block.data.tracks : [];
+		for (const track of tracks) {
+			if (!track || typeof track !== "object") {
+				diagnostics.push({
+					line: tracksLine,
+					message: "Track items must be objects",
+					type: "gantt",
+				});
+				continue;
+			}
+			const start = parsePlanningUnitOrdinal((track as Record<string, unknown>).start, unit);
+			const end = parsePlanningUnitOrdinal((track as Record<string, unknown>).end, unit);
+			if (start == null || end == null) {
+				diagnostics.push({
+					line: tracksLine,
+					message: `Track start/end must match ${unit} format`,
+					type: "gantt",
+				});
+				continue;
+			}
+			if (start > end) {
+				diagnostics.push({
+					line: tracksLine,
+					message: "Track start must be before or equal to end",
+					type: "gantt",
+				});
+			}
+		}
+
+		const milestones = Array.isArray(block.data.milestones) ? block.data.milestones : [];
+		for (const milestone of milestones) {
+			if (!milestone || typeof milestone !== "object") {
+				diagnostics.push({
+					line: milestonesLine,
+					message: "Milestone items must be objects",
+					type: "gantt",
+				});
+				continue;
+			}
+			const date = parsePlanningUnitOrdinal((milestone as Record<string, unknown>).date, unit);
+			if (date == null) {
+				diagnostics.push({
+					line: milestonesLine,
+					message: `Milestone date must match ${unit} format`,
+					type: "gantt",
+				});
+			}
+		}
+
+		const markersLine = block.listLines.markers ?? block.startLine;
+		const markers = Array.isArray(block.data.markers) ? block.data.markers : [];
+		for (const marker of markers) {
+			if (!marker || typeof marker !== "object") {
+				diagnostics.push({
+					line: markersLine,
+					message: "Marker items must be objects",
+					type: "gantt",
+				});
+				continue;
+			}
+			const date = parsePlanningMarkerPosition((marker as Record<string, unknown>).date, unit);
+			if (date == null) {
+				const expected =
+					unit === "month" ? "month format (YYYY-MM or YYYY-MM-DD)" : "week format (YYYY-Www)";
+				diagnostics.push({
+					line: markersLine,
+					message: `Marker date must match ${expected}`,
+					type: "gantt",
+				});
+			}
+		}
+	}
+
+	return diagnostics;
+}
+
+export function collectPlanningVisualsContainmentWarnings(
+	markdown: string,
+): SlidesVisualsFenceDiagnostic[] {
+	const warnings: SlidesVisualsFenceDiagnostic[] = [];
+	const ganttBlocks = parsePlanningGanttBlocks(markdown);
+
+	for (const block of ganttBlocks) {
+		const unitRaw = block.data["time-unit"];
+		const unit = typeof unitRaw === "string" ? unitRaw.trim().toLowerCase() : "";
+		if (unit !== "week" && unit !== "month") continue;
+
+		const axisStart = parsePlanningUnitOrdinal(block.data["time-start"], unit);
+		const axisEnd = parsePlanningUnitOrdinal(block.data["time-end"], unit);
+		if (axisStart == null || axisEnd == null || axisStart >= axisEnd) continue;
+
+		const tracksLine = block.listLines.tracks ?? block.startLine;
+		const milestonesLine = block.listLines.milestones ?? block.startLine;
+
+		const tracks = Array.isArray(block.data.tracks) ? block.data.tracks : [];
+		for (const track of tracks) {
+			if (!track || typeof track !== "object") continue;
+			const start = parsePlanningUnitOrdinal((track as Record<string, unknown>).start, unit);
+			const end = parsePlanningUnitOrdinal((track as Record<string, unknown>).end, unit);
+			if (start == null || end == null) continue;
+			if (start < axisStart || end > axisEnd) {
+				warnings.push({
+					line: tracksLine,
+					message: "Track range is outside axis and will be clipped",
+					type: "gantt",
+				});
+			}
+		}
+
+		const milestones = Array.isArray(block.data.milestones) ? block.data.milestones : [];
+		for (const milestone of milestones) {
+			if (!milestone || typeof milestone !== "object") continue;
+			const date = parsePlanningUnitOrdinal((milestone as Record<string, unknown>).date, unit);
+			if (date == null) continue;
+			if (date < axisStart || date > axisEnd) {
+				warnings.push({
+					line: milestonesLine,
+					message: "Milestone date is outside axis and will not be rendered",
+					type: "gantt",
+				});
+			}
+		}
+
+		const markersLine = block.listLines.markers ?? block.startLine;
+		const markers = Array.isArray(block.data.markers) ? block.data.markers : [];
+		for (const marker of markers) {
+			if (!marker || typeof marker !== "object") continue;
+			const position = parsePlanningMarkerPosition((marker as Record<string, unknown>).date, unit);
+			if (position == null) continue;
+			if (position < axisStart || position > axisEnd + 1) {
+				warnings.push({
+					line: markersLine,
+					message: "Marker date is outside axis and will not be rendered",
+					type: "gantt",
+				});
+			}
+		}
+	}
+
+	return warnings;
+}
+
 export function filterUnknownSlidesVisualsTypeDiagnostics(
 	diagnostics: SlidesVisualsFenceDiagnostic[],
 ): SlidesVisualsFenceDiagnostic[] {
 	return diagnostics.filter((d) => !d.message.startsWith("Unknown slides-visuals block type:"));
 }
 
+export function filterUnknownPlanningVisualsTypeDiagnostics(
+	diagnostics: SlidesVisualsFenceDiagnostic[],
+): SlidesVisualsFenceDiagnostic[] {
+	return diagnostics.filter((d) => !d.message.startsWith("Unknown planning-visuals block type:"));
+}
+
 /**
  * Split markdown content into slide chunks using explicit delimiter.
  * Delimiter lines inside fenced code blocks are ignored.
@@ -884,7 +1803,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;
 
@@ -893,7 +1815,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({
@@ -926,7 +1849,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,
@@ -941,17 +1939,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("/")) {
@@ -1478,10 +2484,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()
@@ -1510,11 +2574,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>
@@ -1536,7 +2602,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)
@@ -1561,11 +2632,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>
@@ -1763,6 +2836,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
@@ -1779,15 +2853,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
@@ -1811,6 +2936,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",
@@ -1825,12 +2951,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") {
@@ -1859,6 +2988,7 @@ export async function loadSiteConfig(
 		if (sections.length > 0) {
 			return {
 				docroot: "content",
+				dataroot: "data",
 				title: "Documentation",
 				mode: "docs",
 				aspect: "16/9",
@@ -1873,6 +3003,7 @@ export async function loadSiteConfig(
 	// Final fallback
 	return {
 		docroot: ".",
+		dataroot: "data",
 		title: defaultTitle,
 		mode: "docs",
 		aspect: "16/9",