kitfly 0.2.1 → 0.2.4

package/src/__tests__/shared.test.ts

@@ -2,7 +2,7 @@
  * Basic tests for shared utilities
  */
 
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -15,25 +15,34 @@ import {
 	buildNavStatic,
 	buildPageMeta,
 	buildSlideNav,
+	buildSlideNavHierarchical,
 	buildToc,
 	type ContentFile,
 	collectFiles,
+	collectPlanningVisualsContainmentWarnings,
 	collectSlides,
 	envBool,
 	envInt,
 	envString,
 	escapeHtml,
 	exists,
+	filterByProfile,
+	filterUnknownPlanningVisualsTypeDiagnostics,
 	filterUnknownSlidesVisualsTypeDiagnostics,
 	formatDate,
 	generateProvenance,
 	getGitInfo,
 	KITFLY_BRAND,
+	loadDataBindings,
 	loadSiteConfig,
+	mergeFrontmatterWithBody,
+	normalizeProfileTags,
 	type Provenance,
+	pagePathForData,
 	parseFrontmatter,
 	parseValue,
 	parseYaml,
+	resolveBindings,
 	resolveSiteVersion,
 	rewriteRelativeAssetUrls,
 	type SiteConfig,
@@ -43,6 +52,7 @@ import {
 	stripQuotes,
 	toUrlPath,
 	validatePath,
+	validatePlanningVisualsFences,
 	validateSlidesVisualsFences,
 } from "../shared.ts";
 
@@ -104,6 +114,271 @@ description: A test page
 	});
 });
 
+describe("normalizeProfileTags", () => {
+	it("parses scalar and array-like profile tags", () => {
+		expect(normalizeProfileTags("alpha")).toEqual(["alpha"]);
+		expect(normalizeProfileTags("[alpha, beta]")).toEqual(["alpha", "beta"]);
+		expect(normalizeProfileTags(["alpha", "beta"])).toEqual(["alpha", "beta"]);
+	});
+
+	it("normalizes whitespace, quotes, and case", () => {
+		expect(normalizeProfileTags("[\"Alpha\", 'beta']")).toEqual(["alpha", "beta"]);
+	});
+});
+
+describe("filterByProfile", () => {
+	it("keeps all files when profiles are not configured", async () => {
+		const root = await mkdtemp(join(tmpdir(), "kitfly-profile-"));
+		try {
+			const alwaysPath = join(root, "always.md");
+			const alphaPath = join(root, "alpha.md");
+			const bothPath = join(root, "both.md");
+			const betaPath = join(root, "beta.md");
+			await writeFile(alwaysPath, "# Always");
+			await writeFile(alphaPath, "---\nprofile: alpha\n---\n# Alpha");
+			await writeFile(bothPath, "---\nprofile: [alpha, beta]\n---\n# Both");
+			await writeFile(betaPath, "---\nprofile: beta\n---\n# Beta");
+
+			const files: ContentFile[] = [
+				{ path: alwaysPath, urlPath: "always", section: "Docs" },
+				{ path: alphaPath, urlPath: "alpha", section: "Docs" },
+				{ path: bothPath, urlPath: "both", section: "Docs" },
+				{ path: betaPath, urlPath: "beta", section: "Docs" },
+			];
+
+			const noProfile = await filterByProfile(files);
+			expect(noProfile.map((f) => f.urlPath)).toEqual(["always", "alpha", "both", "beta"]);
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
+
+	it("filters tagged files when profiles are configured", async () => {
+		const root = await mkdtemp(join(tmpdir(), "kitfly-profile-"));
+		try {
+			const alwaysPath = join(root, "always.md");
+			const alphaPath = join(root, "alpha.md");
+			const bothPath = join(root, "both.md");
+			const betaPath = join(root, "beta.md");
+			await writeFile(alwaysPath, "# Always");
+			await writeFile(alphaPath, "---\nprofile: alpha\n---\n# Alpha");
+			await writeFile(bothPath, "---\nprofile: [alpha, beta]\n---\n# Both");
+			await writeFile(betaPath, "---\nprofile: beta\n---\n# Beta");
+
+			const files: ContentFile[] = [
+				{ path: alwaysPath, urlPath: "always", section: "Docs" },
+				{ path: alphaPath, urlPath: "alpha", section: "Docs" },
+				{ path: bothPath, urlPath: "both", section: "Docs" },
+				{ path: betaPath, urlPath: "beta", section: "Docs" },
+			];
+			const profiles = {
+				alpha: { include: { tags: ["alpha"] } },
+				beta: { include: { tags: ["beta"] } },
+			};
+
+			const noProfile = await filterByProfile(files, undefined, profiles);
+			expect(noProfile.map((f) => f.urlPath)).toEqual(["always"]);
+
+			const alphaProfile = await filterByProfile(files, "alpha", profiles);
+			expect(alphaProfile.map((f) => f.urlPath)).toEqual(["always", "alpha", "both"]);
+
+			const betaProfile = await filterByProfile(files, "beta", profiles);
+			expect(betaProfile.map((f) => f.urlPath)).toEqual(["always", "both", "beta"]);
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
+});
+
+describe("data bindings", () => {
+	it("resolves values and snippets with formatter chains", () => {
+		const bound = resolveBindings(
+			[
+				"Rate: {{ baseline | dollar }}",
+				"Pct: {{ ratio | percent }}",
+				"Rounded: {{ pi | round(2) }}",
+				"Upper: {{ label | upper }}",
+				"Chain: {{ baseline | round(0) | dollar }}",
+				"{{ snippet:table }}",
+			].join("\n"),
+			{
+				globals: { baseline: "1500", ratio: "0.125", pi: "3.14159" },
+				inject: { label: "pricing" },
+				snippets: [{ slot: "table", content: "| A | B |\n|---|---|" }],
+			},
+			"product/pricing.md",
+		);
+		expect(bound).toContain("Rate: $1,500");
+		expect(bound).toContain("Pct: 12.5%");
+		expect(bound).toContain("Rounded: 3.14");
+		expect(bound).toContain("Upper: PRICING");
+		expect(bound).toContain("Chain: $1,500");
+		expect(bound).toContain("| A | B |");
+	});
+
+	it("throws on unresolved keys, unknown snippets, and unknown formatters", () => {
+		expect(() =>
+			resolveBindings("{{ missing }}", { globals: {}, inject: {}, snippets: [] }, "x.md"),
+		).toThrow(/unresolved binding/);
+		expect(() =>
+			resolveBindings("{{ snippet:nope }}", { globals: {}, inject: {}, snippets: [] }, "x.md"),
+		).toThrow(/unknown snippet/);
+		expect(() =>
+			resolveBindings(
+				"{{ n | custom }}",
+				{ globals: { n: "1" }, inject: {}, snippets: [] },
+				"x.md",
+			),
+		).toThrow(/unknown formatter/);
+	});
+});
+
+describe("loadDataBindings", () => {
+	it("loads page-level inject/snippets and validates optional schema", async () => {
+		const root = await mkdtemp(join(tmpdir(), "kitfly-data-"));
+		try {
+			await mkdir(join(root, "content", "product"), { recursive: true });
+			await mkdir(join(root, "data"), { recursive: true });
+			await writeFile(
+				join(root, "data", "pricing.yaml"),
+				[
+					"globals:",
+					'  baseline: "200"',
+					"pages:",
+					"  - path: product/pricing.md",
+					"    inject:",
+					'      hero: "Implementation costs"',
+					"    snippets:",
+					"      - slot: pricing-table",
+					"        content: |",
+					"          | Tier | Price |",
+				].join("\n"),
+			);
+			await writeFile(
+				join(root, "data", "pricing.schema.json"),
+				JSON.stringify(
+					{
+						type: "object",
+						required: ["globals", "pages"],
+						properties: {
+							globals: {
+								type: "object",
+								required: ["baseline"],
+								properties: {
+									baseline: { type: "string", pattern: "^[0-9]+$" },
+								},
+							},
+							pages: { type: "array" },
+						},
+					},
+					null,
+					2,
+				),
+			);
+
+			const pagePath = pagePathForData(
+				root,
+				"content",
+				join(root, "content", "product", "pricing.md"),
+			);
+			const bindings = await loadDataBindings(
+				"data/pricing.yaml",
+				pagePath,
+				root,
+				"content",
+				"data",
+			);
+			expect(bindings.globals.baseline).toBe("200");
+			expect(bindings.inject.hero).toBe("Implementation costs");
+			expect(bindings.snippets[0].slot).toBe("pricing-table");
+			expect(bindings.snippets[0].content).toContain("| Tier | Price |");
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
+
+	it("rejects data paths that escape dataroot", async () => {
+		const root = await mkdtemp(join(tmpdir(), "kitfly-data-"));
+		try {
+			await mkdir(join(root, "data"), { recursive: true });
+			await writeFile(join(root, "outside.yaml"), 'globals:\n  x: "1"\n');
+			await expect(loadDataBindings("../outside.yaml", "a.md", root, ".", "data")).rejects.toThrow(
+				/data path escapes/,
+			);
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
+
+	it("rejects symlinked dataroot that escapes site root", async () => {
+		const root = await mkdtemp(join(tmpdir(), "kitfly-data-"));
+		const outside = await mkdtemp(join(tmpdir(), "kitfly-outside-"));
+		try {
+			await mkdir(join(root, "content"), { recursive: true });
+			await writeFile(join(outside, "pricing.yaml"), 'globals:\n  x: "1"\n');
+			await symlink(outside, join(root, "data"));
+			await expect(
+				loadDataBindings("data/pricing.yaml", "pricing.md", root, "content", "data"),
+			).rejects.toThrow(/data path escapes kitsite/);
+		} finally {
+			await rm(root, { recursive: true, force: true });
+			await rm(outside, { recursive: true, force: true });
+		}
+	});
+
+	it("loads multiline YAML snippet blocks for binding resolution", async () => {
+		const root = await mkdtemp(join(tmpdir(), "kitfly-data-"));
+		try {
+			await mkdir(join(root, "content", "product"), { recursive: true });
+			await mkdir(join(root, "data"), { recursive: true });
+			await writeFile(
+				join(root, "data", "pricing.yaml"),
+				[
+					"pages:",
+					"  - path: product/pricing.md",
+					"    snippets:",
+					"      - slot: pricing-table",
+					"        content: |",
+					"          | Tier | Price |",
+					"          |------|-------|",
+					"          | Starter | $200 |",
+				].join("\n"),
+			);
+			const bindings = await loadDataBindings(
+				"data/pricing.yaml",
+				"product/pricing.md",
+				root,
+				"content",
+				"data",
+			);
+			const rendered = resolveBindings(
+				"Table:\n{{ snippet:pricing-table }}",
+				bindings,
+				"product/pricing.md",
+			);
+			expect(rendered).toContain("| Tier | Price |");
+			expect(rendered).toContain("| Starter | $200 |");
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
+});
+
+describe("mergeFrontmatterWithBody", () => {
+	it("preserves original frontmatter text while replacing body", () => {
+		const original = `---
+title: "A # B"
+tags: [a, b]
+---
+
+# Old`;
+		const merged = mergeFrontmatterWithBody(original, "# New");
+		expect(merged).toContain('title: "A # B"');
+		expect(merged).toContain("tags: [a, b]");
+		expect(merged.endsWith("# New")).toBe(true);
+	});
+});
+
 describe("splitSlides", () => {
 	it("splits markdown on explicit slide delimiter", () => {
 		const input = `# One
@@ -178,6 +453,124 @@ label: Missing value
 	});
 });
 
+describe("planning-visuals diagnostics filtering", () => {
+	it("drops unknown-type diagnostics while preserving schema violations", () => {
+		const markdown = `:::future-planning
+foo: bar
+:::
+
+:::gantt
+time-unit: week
+time-start: 2026-W10
+time-end: 2026-W12
+:::`;
+		const diagnostics = validatePlanningVisualsFences(markdown);
+		const filtered = filterUnknownPlanningVisualsTypeDiagnostics(diagnostics);
+		expect(
+			diagnostics.some((d) => d.message.startsWith("Unknown planning-visuals block type:")),
+		).toBe(true);
+		expect(filtered.some((d) => d.message.startsWith("Unknown planning-visuals block type:"))).toBe(
+			false,
+		);
+		expect(filtered.some((d) => d.message.includes("Missing required key: tracks"))).toBe(true);
+	});
+});
+
+describe("planning-visuals containment warnings", () => {
+	it("returns non-fatal containment warnings when rows exceed axis", () => {
+		const markdown = `:::gantt
+time-unit: month
+time-start: 2026-04
+time-end: 2026-06
+tracks:
+  - label: Wave 1
+    depth: 1
+    start: 2026-03
+    end: 2026-07
+milestones:
+  - label: Late marker
+    date: 2026-08
+:::`;
+		const warnings = collectPlanningVisualsContainmentWarnings(markdown);
+		expect(warnings.some((w) => w.message.includes("Track range is outside axis"))).toBe(true);
+		expect(warnings.some((w) => w.message.includes("Milestone date is outside axis"))).toBe(true);
+	});
+
+	it("warns when marker date is outside axis range", () => {
+		const markdown = `:::gantt
+time-unit: week
+time-start: 2026-W14
+time-end: 2026-W20
+markers:
+  - label: Late gate
+    date: 2026-W22
+tracks:
+  - label: Phase 1
+    depth: 1
+    start: 2026-W14
+    end: 2026-W18
+:::`;
+		const warnings = collectPlanningVisualsContainmentWarnings(markdown);
+		expect(warnings.some((w) => w.message.includes("Marker date is outside axis"))).toBe(true);
+	});
+});
+
+describe("planning-visuals marker validation", () => {
+	it("accepts valid markers", () => {
+		const markdown = `:::gantt
+time-unit: week
+time-start: 2026-W14
+time-end: 2026-W30
+markers:
+  - label: Go/No-Go
+    date: 2026-W20
+tracks:
+  - label: Phase 1
+    depth: 1
+    start: 2026-W14
+    end: 2026-W24
+:::`;
+		const diags = validatePlanningVisualsFences(markdown);
+		expect(diags).toHaveLength(0);
+	});
+
+	it("rejects marker with mismatched date format", () => {
+		const markdown = `:::gantt
+time-unit: month
+time-start: 2026-04
+time-end: 2026-10
+markers:
+  - label: Gate
+    date: 2026-W20
+tracks:
+  - label: Build
+    depth: 1
+    start: 2026-04
+    end: 2026-07
+:::`;
+		const diags = validatePlanningVisualsFences(markdown);
+		expect(diags.some((d) => d.message.includes("Marker date must match month format"))).toBe(true);
+	});
+
+	it("accepts month markers with day precision", () => {
+		const markdown = `:::gantt
+time-unit: month
+time-start: 2026-04
+time-end: 2026-10
+markers:
+  - label: Conference
+    date: 2026-05-26
+tracks:
+  - label: Build
+    depth: 1
+    start: 2026-04
+    end: 2026-07
+:::`;
+		const diags = validatePlanningVisualsFences(markdown);
+		expect(diags).toHaveLength(0);
+	});
+});
+
 describe("segmentSlides", () => {
 	it("uses frontmatter title and class when present", () => {
 		const input = `---
@@ -348,6 +741,140 @@ title: Intro
 		expect(nav).toContain('<a href="#slide-2" class="active">Slide B</a>');
 		expect(nav).toContain('<span class="nav-section">Slides</span>');
 	});
+
+	it("builds hierarchical slide nav for nested source paths", () => {
+		const nav = buildSlideNavHierarchical(
+			[
+				{
+					index: 0,
+					frontmatter: {},
+					body: "# Overview",
+					title: "Overview",
+					id: "slide-1",
+					section: "Data Integration",
+					sourcePath: "/tmp/di/slides.md",
+					sourceUrlPath: "data-integration/slides",
+					kind: "markdown",
+				},
+				{
+					index: 1,
+					frontmatter: {},
+					body: "# POS Data",
+					title: "POS Data",
+					id: "slide-2",
+					section: "Data Integration",
+					sourcePath: "/tmp/di/sources/slides.md",
+					sourceUrlPath: "data-integration/sources/slides",
+					kind: "markdown",
+				},
+				{
+					index: 2,
+					frontmatter: {},
+					body: "# ETL Pipeline",
+					title: "ETL Pipeline",
+					id: "slide-3",
+					section: "Data Integration",
+					sourcePath: "/tmp/di/transforms/slides.md",
+					sourceUrlPath: "data-integration/transforms/slides",
+					kind: "markdown",
+				},
+			],
+			{
+				docroot: ".",
+				title: "Deck",
+				brand: { name: "Test", url: "/" },
+				sections: [{ name: "Data Integration", path: "data-integration" }],
+			},
+			"slide-2",
+		);
+
+		expect(nav).toContain('<summary class="nav-group">Sources</summary>');
+		expect(nav).toContain('<summary class="nav-group">Transforms</summary>');
+		expect(nav).toContain('<a href="#slide-2" class="active">POS Data</a>');
+		expect(nav).toContain('<a href="#slide-3">ETL Pipeline</a>');
+		expect(nav).toContain("<details open>");
+	});
+
+	it("keeps flat nav output when slides are not nested", () => {
+		const nav = buildSlideNavHierarchical(
+			[
+				{
+					index: 0,
+					frontmatter: {},
+					body: "# Intro",
+					title: "Intro",
+					id: "slide-1",
+					section: "Slides",
+					sourcePath: "/tmp/slides/a.md",
+					sourceUrlPath: "slides/a",
+					kind: "markdown",
+				},
+				{
+					index: 1,
+					frontmatter: {},
+					body: "# Next",
+					title: "Next",
+					id: "slide-2",
+					section: "Slides",
+					sourcePath: "/tmp/slides/b.md",
+					sourceUrlPath: "slides/b",
+					kind: "markdown",
+				},
+			],
+			{
+				docroot: ".",
+				title: "Deck",
+				brand: { name: "Test", url: "/" },
+				sections: [{ name: "Slides", path: "slides" }],
+			},
+			"slide-1",
+		);
+
+		expect(nav).toContain('<a href="#slide-1" class="active">Intro</a>');
+		expect(nav).toContain('<a href="#slide-2">Next</a>');
+		expect(nav).not.toContain('class="nav-group"');
+	});
+
+	it("keeps flat nav output when section path has trailing slash", () => {
+		const nav = buildSlideNavHierarchical(
+			[
+				{
+					index: 0,
+					frontmatter: {},
+					body: "# Intro",
+					title: "Intro",
+					id: "slide-1",
+					section: "Slides",
+					sourcePath: "/tmp/slides/a.md",
+					sourceUrlPath: "slides/a",
+					kind: "markdown",
+				},
+				{
+					index: 1,
+					frontmatter: {},
+					body: "# Next",
+					title: "Next",
+					id: "slide-2",
+					section: "Slides",
+					sourcePath: "/tmp/slides/b.md",
+					sourceUrlPath: "slides/b",
+					kind: "markdown",
+				},
+			],
+			{
+				docroot: ".",
+				title: "Deck",
+				brand: { name: "Test", url: "/" },
+				sections: [{ name: "Slides", path: "slides/" }],
+			},
+			"slide-1",
+		);
+
+		expect(nav).toContain('<a href="#slide-1" class="active">Intro</a>');
+		expect(nav).toContain('<a href="#slide-2">Next</a>');
+		expect(nav).not.toContain('class="nav-group"');
+		expect(nav).not.toContain("<summary");
+	});
 });
 
 describe("rewriteRelativeAssetUrls", () => {
@@ -532,6 +1059,78 @@ description: 'A test site'`;
 		expect(result.tags).toEqual(["javascript", "typescript"]);
 	});
 
+	it("parses literal block scalars", () => {
+		const yaml = `snippets:
+  - slot: pricing-table
+    content: |
+      | Tier | Price |
+      |------|-------|
+      | Starter | $200 |`;
+		const result = parseYaml(yaml);
+		const snippets = result.snippets as Array<Record<string, unknown>>;
+		expect(snippets[0].content).toBe("| Tier | Price |\n|------|-------|\n| Starter | $200 |");
+	});
+
+	it("parses folded block scalars", () => {
+		const yaml = `globals:
+  summary: >
+    Line one
+    line two
+
+    Paragraph two`;
+		const result = parseYaml(yaml);
+		const globals = result.globals as Record<string, unknown>;
+		expect(globals.summary).toBe("Line one line two\nParagraph two");
+	});
+
+	it("supports block scalar chomping indicators", () => {
+		const yaml = `globals:
+  keep: |+
+    One
+    Two
+  strip: >-
+    A
+    B`;
+		const result = parseYaml(yaml);
+		const globals = result.globals as Record<string, unknown>;
+		expect(globals.keep).toBe("One\nTwo\n");
+		expect(globals.strip).toBe("A B");
+	});
+
+	it("parses direct array block scalar items", () => {
+		const yaml = `snippets:
+  - |
+    line 1
+    line 2
+  - >-
+    folded
+    line`;
+		const result = parseYaml(yaml);
+		expect(result.snippets).toEqual(["line 1\nline 2", "folded line"]);
+	});
+
+	it("accepts block scalar indentation indicators", () => {
+		const yaml = `globals:
+  note: |2-
+      indented
+      block`;
+		const result = parseYaml(yaml);
+		const globals = result.globals as Record<string, unknown>;
+		expect(globals.note).toBe("indented\nblock");
+	});
+
+	it("treats invalid block scalar headers as plain strings", () => {
+		const yaml = `globals:
+  bad: |abc
+snippets:
+  - >foo`;
+		const result = parseYaml(yaml);
+		const globals = result.globals as Record<string, unknown>;
+		const snippets = result.snippets as unknown[];
+		expect(globals.bad).toBe("|abc");
+		expect(snippets[0]).toBe(">foo");
+	});
+
 	it("returns empty object for empty input", () => {
 		const result = parseYaml("");
 		expect(result).toEqual({});
@@ -1122,12 +1721,18 @@ version: "1.2.0"
 brand:
   name: Test
   url: /
+  logoDark: assets/brand/logo-dark.png
 sections:
   - name: Guide
     path: guide
 footer:
   copyright: "© 2026 Test"
   attribution: false
+  logo: "assets/brand/footer-logo.png"
+  logoDark: "assets/brand/footer-logo-dark.png"
+  logoUrl: "https://example.com/footer"
+  logoAlt: "Footer Brand"
+  logoHeight: 24
   links:
     - text: Privacy
       url: /privacy
@@ -1137,14 +1742,45 @@ footer:
 
 			const config = await loadSiteConfig(dir);
 			expect(config.version).toBe("1.2.0");
+			expect(config.brand.logoDark).toBe("assets/brand/logo-dark.png");
 			expect(config.footer?.copyright).toBe("© 2026 Test");
 			expect(config.footer?.attribution).toBe(false);
+			expect(config.footer?.logo).toBe("assets/brand/footer-logo.png");
+			expect(config.footer?.logoDark).toBe("assets/brand/footer-logo-dark.png");
+			expect(config.footer?.logoUrl).toBe("https://example.com/footer");
+			expect(config.footer?.logoAlt).toBe("Footer Brand");
+			expect(config.footer?.logoHeight).toBe(24);
 			expect(config.footer?.links).toEqual([{ text: "Privacy", url: "/privacy" }]);
 		} finally {
 			await rm(dir, { recursive: true, force: true });
 		}
 	});
 
+	it("clamps footer.logoHeight to supported range", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "kitfly-footer-logo-height-"));
+		try {
+			await writeFile(
+				join(dir, "site.yaml"),
+				`title: Test
+brand:
+  name: Test
+  url: /
+sections:
+  - name: Guide
+    path: guide
+footer:
+  logoHeight: 100
+`,
+				"utf-8",
+			);
+
+			const config = await loadSiteConfig(dir);
+			expect(config.footer?.logoHeight).toBe(40);
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
 	it("truncates footer links to max 10", async () => {
 		const dir = await mkdtemp(join(tmpdir(), "kitfly-footer-links-"));
 		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
@@ -1685,6 +2321,70 @@ describe("buildFooter", () => {
 		expect(result).toContain('class="footer-link"');
 	});
 
+	it("renders footer logo before version with configurable metadata", () => {
+		const result = buildFooter(
+			baseProvenance,
+			{
+				...baseConfig,
+				footer: {
+					logo: "assets/brand/footer-logo.png",
+					logoUrl: "https://footer.example.com",
+					logoAlt: "Footer Brand",
+					logoHeight: 22,
+				},
+			},
+			"../",
+		);
+		expect(result).toContain('class="footer-logo-link"');
+		expect(result).toContain('class="footer-logo-img"');
+		expect(result).toContain('href="https://footer.example.com"');
+		expect(result).toContain('src="../assets/brand/footer-logo.png"');
+		expect(result).toContain('alt="Footer Brand"');
+		expect(result).toContain("max-height: 22px");
+		expect(result).toContain("onerror=\"this.onerror=null;this.style.display='none'\"");
+		expect(result.indexOf('class="footer-logo-img"')).toBeLessThan(
+			result.indexOf('class="footer-version"'),
+		);
+	});
+
+	it("renders footer light/dark logo variants when logoDark is set", () => {
+		const result = buildFooter(baseProvenance, {
+			...baseConfig,
+			footer: {
+				logo: "assets/brand/footer-logo.png",
+				logoDark: "assets/brand/footer-logo-dark.png",
+			},
+		});
+		expect(result).toContain("footer-logo-img logo-light");
+		expect(result).toContain("footer-logo-img logo-dark");
+		expect(result).toContain('src="assets/brand/footer-logo-dark.png"');
+	});
+
+	it("falls back footer logo alt text to copyright then brand name", () => {
+		const withCopyrightAlt = buildFooter(
+			baseProvenance,
+			{
+				...baseConfig,
+				footer: {
+					logo: "assets/brand/footer-logo.png",
+					copyright: "Copyright 2026 Acme",
+				},
+			},
+			"./",
+		);
+		expect(withCopyrightAlt).toContain('alt="Copyright 2026 Acme"');
+
+		const withBrandAlt = buildFooter(
+			baseProvenance,
+			{
+				...baseConfig,
+				footer: { logo: "assets/brand/footer-logo.png" },
+			},
+			"./",
+		);
+		expect(withBrandAlt).toContain('alt="Acme Corp"');
+	});
+
 	it("uses publish date year in default copyright", () => {
 		const result = buildFooter(baseProvenance, baseConfig);
 		expect(result).toContain("© 2024 Acme Corp");
@@ -1751,6 +2451,24 @@ describe("buildBundleFooter", () => {
 		expect(result).toContain("&lt;em&gt;");
 		expect(result).not.toContain("<em>");
 	});
+
+	it("renders footer logo in bundle mode with override source", () => {
+		const result = buildBundleFooter(
+			"0.1.1",
+			{
+				...baseConfig,
+				footer: {
+					logo: "assets/brand/footer-logo.png",
+					logoUrl: "https://footer.example.com",
+					logoHeight: 18,
+				},
+			},
+			"data:image/png;base64,AAAA",
+		);
+		expect(result).toContain('src="data:image/png;base64,AAAA"');
+		expect(result).toContain('href="https://footer.example.com"');
+		expect(result).toContain("max-height: 18px");
+	});
 });
 
 // ---------------------------------------------------------------------------