kitfly 0.2.0 → 0.2.3

package/src/__tests__/brief.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Tests for the Brief template definition
+ *
+ * Covers: src/templates/brief.ts
+ * Strategy: import the template directly, verify structure and generated content
+ */
+
+import { describe, expect, it } from "vitest";
+import { brief } from "../templates/brief.ts";
+import type { BrandingConfig, TemplateContext, TemplateFile } from "../templates/schema.ts";
+
+function makeCtx(overrides?: Partial<TemplateContext>): TemplateContext {
+	const branding: BrandingConfig = {
+		siteName: "Test Brief",
+		brandName: "Acme Corp",
+		brandUrl: "https://acme.example.com",
+		primaryColor: "#2563eb",
+		footerText: "Footer text",
+	};
+	return {
+		name: "test-brief",
+		branding,
+		template: brief,
+		year: 2026,
+		...overrides,
+	};
+}
+
+function resolveContent(file: TemplateFile, ctx: TemplateContext): string {
+	return typeof file.content === "function" ? file.content(ctx) : file.content;
+}
+
+function findFile(path: string): TemplateFile {
+	const f = brief.files.find((entry) => entry.path === path);
+	if (!f) throw new Error(`Template file not found: ${path}`);
+	return f;
+}
+
+describe("brief template definition", () => {
+	it("has correct identity metadata", () => {
+		expect(brief.id).toBe("brief");
+		expect(brief.name).toBe("Brief");
+		expect(brief.version).toBe(1);
+		expect(brief.extends).toBe("minimal");
+	});
+
+	it("defines exactly four sections", () => {
+		expect(brief.sections).toHaveLength(4);
+		expect(brief.sections.map((s) => s.name)).toEqual([
+			"Product",
+			"Use Cases",
+			"Getting Started",
+			"Reference",
+		]);
+		expect(brief.sections.map((s) => s.path)).toEqual([
+			"content/product",
+			"content/use-cases",
+			"content/getting-started",
+			"content/reference",
+		]);
+	});
+
+	it("defines unique file paths", () => {
+		const paths = brief.files.map((f) => f.path);
+		expect(new Set(paths).size).toBe(paths.length);
+	});
+});
+
+describe("brief site.yaml", () => {
+	const ctx = makeCtx();
+	const file = findFile("site.yaml");
+
+	it("includes branding and all four section paths", () => {
+		const content = resolveContent(file, ctx);
+		expect(content).toContain('title: "Test Brief"');
+		expect(content).toContain('name: "Acme Corp"');
+		expect(content).toContain('url: "https://acme.example.com"');
+		expect(content).toContain('"content/product"');
+		expect(content).toContain('"content/use-cases"');
+		expect(content).toContain('"content/getting-started"');
+		expect(content).toContain('"content/reference"');
+		expect(content).toContain('home: "index.md"');
+	});
+});
+
+describe("brief starter files", () => {
+	const ctx = makeCtx();
+	const starterFiles = [
+		"index.md",
+		"content/product/overview.md",
+		"content/product/capabilities.md",
+		"content/use-cases/overview.md",
+		"content/use-cases/example-use-case.md",
+		"content/getting-started/overview.md",
+		"content/getting-started/requirements.md",
+		"content/reference/architecture.md",
+		"content/reference/faq.md",
+		"content/reference/contacts.md",
+	];
+
+	it("ships all 10 starter files", () => {
+		expect(starterFiles).toHaveLength(10);
+		for (const path of starterFiles) {
+			expect(brief.files.some((f) => f.path === path)).toBe(true);
+		}
+	});
+
+	it("includes frontmatter in markdown starter files", () => {
+		for (const path of starterFiles) {
+			const content = resolveContent(findFile(path), ctx);
+			expect(content).toMatch(/^---\n/);
+		}
+	});
+
+	it("includes customize markers in starter files", () => {
+		for (const path of starterFiles) {
+			const content = resolveContent(findFile(path), ctx);
+			expect(content).toContain("<!-- ← CUSTOMIZE");
+		}
+	});
+
+	it("uses professional framing in index and use cases", () => {
+		const index = resolveContent(findFile("index.md"), ctx);
+		expect(index).toContain("At a Glance");
+		expect(index).toContain("[Use Cases](/content/use-cases/overview)");
+
+		const useCases = resolveContent(findFile("content/use-cases/example-use-case.md"), ctx);
+		expect(useCases).toContain("## Scenario");
+		expect(useCases).toContain("## Outcome");
+		expect(useCases).toContain("| Metric | Before | After |");
+	});
+});
+
+describe("brief CUSTOMIZING.md", () => {
+	const ctx = makeCtx();
+	const file = findFile("CUSTOMIZING.md");
+
+	it("documents template identity and external-audience tone", () => {
+		const content = resolveContent(file, ctx);
+		expect(content).toContain("template: brief");
+		expect(content).toContain("clients, prospects, and partners");
+		expect(content).toContain("Informational and professional");
+		expect(content).toContain("Not sales copy");
+	});
+
+	it("guides use-case duplication workflow", () => {
+		const content = resolveContent(file, ctx);
+		expect(content).toContain("Duplicate `content/use-cases/example-use-case.md`");
+		expect(content).toContain("problem -> solution -> outcome");
+	});
+});

package/src/__tests__/build.test.ts

@@ -35,7 +35,8 @@ async function writeSiteYaml(dir: string, extra: Record<string, unknown> = {}):
 	const mode = extra.mode ? `mode: ${extra.mode}\n` : "";
 	const aspect = extra.aspect ? `aspect: ${extra.aspect}\n` : "";
 	const home = extra.home ? `home: ${extra.home}\n` : "";
-	const yaml = `title: ${title}\n${version}${mode}${aspect}brand:\n${brand}\n${home}sections:\n${sections}\n`;
+	const footer = extra.footer ? `footer:\n${extra.footer}\n` : "";
+	const yaml = `title: ${title}\n${version}${mode}${aspect}brand:\n${brand}\n${home}${footer}sections:\n${sections}\n`;
 	await writeFile(join(dir, "site.yaml"), yaml);
 }
 
@@ -216,6 +217,45 @@ describe("build", () => {
 		expect(html).toContain("unversioned");
 	});
 
+	it("renders footer logo with static path prefix in built output", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, {
+			footer: '  logo: "assets/brand/footer-logo.png"\n  logoAlt: "Footer Brand"\n  logoHeight: 24',
+		});
+		await writeMd(siteDir, "docs/page.md", "# Page");
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain('class="footer-logo-img"');
+		expect(html).toContain('src="./assets/brand/footer-logo.png"');
+		expect(html).toContain('alt="Footer Brand"');
+		expect(html).toContain("max-height: 24px");
+	});
+
+	it("renders light/dark variants for header and footer logos when configured", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, {
+			brand:
+				'  name: Test\n  url: /\n  logo: "assets/brand/logo.png"\n  logoDark: "assets/brand/logo-dark.png"',
+			footer:
+				'  logo: "assets/brand/footer-logo.png"\n  logoDark: "assets/brand/footer-logo-dark.png"',
+		});
+		await writeMd(siteDir, "docs/page.md", "# Page");
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain("logo-img logo-light");
+		expect(html).toContain("logo-img logo-dark");
+		expect(html).toContain("./assets/brand/logo-dark.png");
+		expect(html).toContain("footer-logo-img logo-light");
+		expect(html).toContain("footer-logo-img logo-dark");
+		expect(html).toContain("./assets/brand/footer-logo-dark.png");
+	});
+
 	it("builds a single-page hash-routed deck when mode is slides", async () => {
 		const siteDir = await makeTempDir();
 		const outDir = "out";
@@ -332,6 +372,87 @@ plugins:
 		expect(html).toContain(js);
 	});
 
+	it("preserves dollar-sign replacement patterns in injected plugin JS", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir);
+		await writeMd(siteDir, "docs/page.md", "# Test");
+
+		const js = "const expr='x'; const sample = `$${expr}$`; const marker = '$`';";
+		await mkdir(join(siteDir, "plugins-dist"), { recursive: true });
+		await writeFile(join(siteDir, "plugins-dist", "literal.js"), js, "utf-8");
+
+		await mkdir(join(siteDir, "registry"), { recursive: true });
+		await writeFile(
+			join(siteDir, "registry", "plugins.yaml"),
+			`version: 1
+updated: "2026-02-16"
+baseUrl: ""
+plugins:
+  literal:
+    name: "Literal"
+    description: "Replacement pattern regression"
+    version: "1.0.0"
+    contract: "1"
+    kitfly: ">=0.2.0 <1.0.0"
+    license: MIT
+    verified: true
+    assets:
+      js: "plugins-dist/literal.js"
+      assetSha256:
+        js: "sha256:${sha256Hex(js)}"
+`,
+			"utf-8",
+		);
+
+		await writeFile(join(siteDir, "kitfly.plugins.yaml"), "plugins:\n  - literal@1.0.0\n", "utf-8");
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain("const sample = `$${expr}$`;");
+		expect(html).toContain("const marker = '$`';");
+		expect(html).not.toContain("<!DOCTYPE html><html");
+	});
+
+	it("preserves dollar-sign replacement patterns in markdown content", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir);
+		await writeMd(
+			siteDir,
+			"docs/dollars.md",
+			"# Dollars\n\nLiteral dollars: $$ and $` and $' and $&\n\nMath style: $$x^2$$",
+		);
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain("Literal dollars: $$ and $` and $&#39; and $&amp;");
+		expect(html).toContain("Math style: $$x^2$$");
+		expect(html.match(/<!DOCTYPE html>/g)?.length ?? 0).toBe(1);
+	});
+
+	it("injects latex plugin in docs mode", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir);
+		await writeMd(
+			siteDir,
+			"docs/math.md",
+			"# Math\n\nInline: $x^2$.\n\n$$\n\\\\int_0^1 x^2 dx\n$$\n\n```math\n\\\\sum_{i=1}^{n} i\n```",
+		);
+		await writeFile(join(siteDir, "kitfly.plugins.yaml"), "plugins:\n  - latex@0.2.2\n", "utf-8");
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain('data-kitfly-plugin="latex@0.2.2"');
+		expect(html).toContain("const KATEX_JS_URL =");
+		expect(html).toContain("cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js");
+		expect(html).toContain("cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css");
+	});
+
 	it("injects slides-only plugins when mode=slides", async () => {
 		const siteDir = await makeTempDir();
 		const outDir = "out";
@@ -365,7 +486,7 @@ plugins:
   slides-visuals:
     name: "Slides Visuals"
     description: "Test visuals"
-    version: "0.2.0"
+    version: "0.2.1"
     contract: "1"
     kitfly: ">=0.2.0 <1.0.0"
     license: MIT
@@ -383,15 +504,124 @@ plugins:
 
 		await writeFile(
 			join(siteDir, "kitfly.plugins.yaml"),
-			"plugins:\n  - slides-visuals@0.2.0\n",
+			"plugins:\n  - slides-visuals@0.2.1\n",
 			"utf-8",
 		);
 
 		await build({ folder: siteDir, out: outDir });
 
 		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
-		expect(html).toContain('data-kitfly-plugin="slides-visuals@0.2.0"');
+		expect(html).toContain('data-kitfly-plugin="slides-visuals@0.2.1"');
 		expect(html).toContain(css);
 		expect(html).toContain(js);
 	});
+
+	it("injects slides-charts-lite plugin in slides mode", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, { mode: "slides" });
+		await writeMd(
+			siteDir,
+			"docs/deck.md",
+			`# Chart
+
+\`\`\`chart
+kind: bar
+title: Revenue
+labels: ["Q1", "Q2"]
+data: [10, 12]
+\`\`\`
+`,
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - slides-charts-lite@0.2.2\n",
+			"utf-8",
+		);
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain('data-kitfly-plugin="slides-charts-lite@0.2.2"');
+		expect(html).toContain("kitfly-chart-wrapper");
+	});
+
+	it("does not inject slides-charts-lite in docs mode", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, { mode: "docs" });
+		await writeMd(siteDir, "docs/page.md", "# Page");
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - slides-charts-lite@0.2.2\n",
+			"utf-8",
+		);
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).not.toContain('data-kitfly-plugin="slides-charts-lite@0.2.2"');
+	});
+
+	it("ignores unknown slides-visuals block types while enforcing known contracts", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, { mode: "slides" });
+		await writeMd(
+			siteDir,
+			"docs/deck.md",
+			`# Title
+
+:::future-thing
+note: this should pass through
+:::
+
+:::kpi
+label: Uptime
+value: 99.95%
+:::
+`,
+		);
+
+		const js = "console.log('slides visuals');";
+		const css = ".kitfly-visual{border:1px solid red;}";
+		await mkdir(join(siteDir, "plugins-dist"), { recursive: true });
+		await writeFile(join(siteDir, "plugins-dist", "slides-visuals.js"), js, "utf-8");
+		await writeFile(join(siteDir, "plugins-dist", "slides-visuals.css"), css, "utf-8");
+		await mkdir(join(siteDir, "registry"), { recursive: true });
+		await writeFile(
+			join(siteDir, "registry", "plugins.yaml"),
+			`version: 1
+updated: "2026-02-15"
+baseUrl: ""
+plugins:
+  slides-visuals:
+    name: "Slides Visuals"
+    description: "Test visuals"
+    version: "0.2.1"
+    contract: "1"
+    kitfly: ">=0.2.0 <1.0.0"
+    license: MIT
+    verified: true
+    modes: ["slides"]
+    assets:
+      js: "plugins-dist/slides-visuals.js"
+      css: "plugins-dist/slides-visuals.css"
+      assetSha256:
+        js: "sha256:${sha256Hex(js)}"
+        css: "sha256:${sha256Hex(css)}"
+`,
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - slides-visuals@0.2.1\n",
+			"utf-8",
+		);
+
+		await expect(build({ folder: siteDir, out: outDir })).resolves.toBeUndefined();
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain('data-kitfly-plugin="slides-visuals@0.2.1"');
+		expect(html).toContain("future-thing");
+	});
 });

package/src/__tests__/bundle.test.ts

@@ -5,6 +5,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import {
 	buildBundleNav,
 	buildBundleSidebarHeader,
+	bundleSite,
 	fileToDataUri,
 	imageMime,
 	inlineLocalImages,
@@ -815,3 +816,136 @@ describe("buildBundleSidebarHeader", () => {
 		expect(html).toContain(`src="${logo}"`);
 	});
 });
+
+describe("bundleSite plugin integration", () => {
+	it("inlines latex plugin script when enabled", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "docs"), { recursive: true });
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Test"\nbrand:\n  name: "Test"\n  url: "/"\nsections:\n  - name: Docs\n    path: docs\n',
+			"utf-8",
+		);
+		await writeFile(join(siteDir, "docs", "index.md"), "# Bundle Math\n\n$E=mc^2$", "utf-8");
+		await writeFile(join(siteDir, "kitfly.plugins.yaml"), "plugins:\n  - latex@0.2.2\n", "utf-8");
+
+		await bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" });
+
+		const html = await readFile(join(siteDir, "bundles", "bundle.html"), "utf-8");
+		expect(html).toContain('data-kitfly-plugin="latex@0.2.2"');
+		expect(html).toContain("const KATEX_JS_URL =");
+		expect(html).toContain("cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js");
+		expect(html).toContain("cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css");
+	});
+
+	it("inlines slides-charts-lite plugin in slides mode", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "slides"), { recursive: true });
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Charts Test"\nmode: "slides"\nbrand:\n  name: "Test"\n  url: "/"\nsections:\n  - name: Slides\n    path: slides\n',
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "slides", "deck.md"),
+			'# Deck\n\n```chart\nkind: line\nlabels: ["W1", "W2"]\ndata: [2, 3]\n```',
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - slides-charts-lite@0.2.2\n",
+			"utf-8",
+		);
+
+		await bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" });
+
+		const html = await readFile(join(siteDir, "bundles", "bundle.html"), "utf-8");
+		expect(html).toContain('data-kitfly-plugin="slides-charts-lite@0.2.2"');
+		expect(html).toContain("kitfly-chart-wrapper");
+	});
+
+	it("inlines footer logo image when configured", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "docs"), { recursive: true });
+		await mkdir(join(siteDir, "assets", "brand"), { recursive: true });
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Footer Test"\nbrand:\n  name: "Test"\n  url: "/"\nfooter:\n  logo: "assets/brand/footer-logo.png"\n  logoAlt: "Footer Brand"\n  logoHeight: 24\nsections:\n  - name: Docs\n    path: docs\n',
+			"utf-8",
+		);
+		await writeFile(join(siteDir, "docs", "index.md"), "# Footer Logo");
+		await writeFile(
+			join(siteDir, "assets", "brand", "footer-logo.png"),
+			Buffer.from(
+				"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Wl9x9kAAAAASUVORK5CYII=",
+				"base64",
+			),
+		);
+
+		await bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" });
+
+		const html = await readFile(join(siteDir, "bundles", "bundle.html"), "utf-8");
+		expect(html).toContain('class="footer-logo-img"');
+		expect(html).toContain('src="data:image/png;base64,');
+		expect(html).not.toContain('src="assets/brand/footer-logo.png"');
+		expect(html).toContain('alt="Footer Brand"');
+		expect(html).toContain("max-height: 24px");
+	});
+
+	it("inlines footer logo from site-root-relative path outside assets", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "docs"), { recursive: true });
+		await mkdir(join(siteDir, "logos"), { recursive: true });
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Footer Root Path Test"\nbrand:\n  name: "Test"\n  url: "/"\nfooter:\n  logo: "logos/footer.png"\n  logoAlt: "Footer Root Logo"\nsections:\n  - name: Docs\n    path: docs\n',
+			"utf-8",
+		);
+		await writeFile(join(siteDir, "docs", "index.md"), "# Footer Root Path");
+		await writeFile(
+			join(siteDir, "logos", "footer.png"),
+			Buffer.from(
+				"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Wl9x9kAAAAASUVORK5CYII=",
+				"base64",
+			),
+		);
+
+		await bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" });
+
+		const html = await readFile(join(siteDir, "bundles", "bundle.html"), "utf-8");
+		expect(html).toContain('class="footer-logo-img"');
+		expect(html).toContain('src="data:image/png;base64,');
+		expect(html).not.toContain('src="logos/footer.png"');
+		expect(html).toContain('alt="Footer Root Logo"');
+	});
+
+	it("inlines light/dark variants for header and footer logos", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "docs"), { recursive: true });
+		await mkdir(join(siteDir, "assets", "brand"), { recursive: true });
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Dark Logos Test"\nbrand:\n  name: "Test"\n  url: "/"\n  logo: "assets/brand/logo.png"\n  logoDark: "assets/brand/logo-dark.png"\nfooter:\n  logo: "assets/brand/footer-logo.png"\n  logoDark: "assets/brand/footer-logo-dark.png"\nsections:\n  - name: Docs\n    path: docs\n',
+			"utf-8",
+		);
+		await writeFile(join(siteDir, "docs", "index.md"), "# Dark Logos");
+		const pixelPng = Buffer.from(
+			"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Wl9x9kAAAAASUVORK5CYII=",
+			"base64",
+		);
+		await writeFile(join(siteDir, "assets", "brand", "logo.png"), pixelPng);
+		await writeFile(join(siteDir, "assets", "brand", "logo-dark.png"), pixelPng);
+		await writeFile(join(siteDir, "assets", "brand", "footer-logo.png"), pixelPng);
+		await writeFile(join(siteDir, "assets", "brand", "footer-logo-dark.png"), pixelPng);
+
+		await bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" });
+
+		const html = await readFile(join(siteDir, "bundles", "bundle.html"), "utf-8");
+		expect(html).toContain('class="logo-img logo-light"');
+		expect(html).toContain('class="logo-img logo-dark"');
+		expect(html).toContain('class="footer-logo-img logo-light"');
+		expect(html).toContain('class="footer-logo-img logo-dark"');
+		expect(html).not.toContain('src="assets/brand/logo-dark.png"');
+		expect(html).not.toContain('src="assets/brand/footer-logo-dark.png"');
+	});
+});

package/src/__tests__/dev-plugin-errors.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { buildDevPluginErrorHtml } from "../../scripts/dev.ts";
+
+describe("dev plugin error page", () => {
+	it("shows actionable update hint for plugin version mismatch", () => {
+		const html = buildDevPluginErrorHtml("Plugin slides-visuals version mismatch: 0.2.0 != 0.2.1");
+		expect(html).toContain("Plugin setup error");
+		expect(html).toContain("kitfly.plugins.yaml");
+		expect(html).toContain("slides-visuals@0.2.1");
+	});
+
+	it("escapes error text and falls back to generic guidance", () => {
+		const html = buildDevPluginErrorHtml('Invalid plugin ref: bad"@1.0.0 <x>');
+		expect(html).toContain(
+			"Check <code>kitfly.plugins.yaml</code> and <code>registry/plugins.yaml</code>",
+		);
+		expect(html).toContain("bad&quot;@1.0.0 &lt;x&gt;");
+		expect(html).not.toContain('bad"@1.0.0 <x>');
+	});
+});

package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-branching-no-source.md

@@ -0,0 +1,5 @@
+:::flow-branching
+branches:
+  - "API Handler"
+  - "Static Files"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-converging-no-target.md

@@ -0,0 +1,6 @@
+:::flow-converging
+sources:
+  - "Frontend Logs"
+  - "API Logs"
+merge: "Aggregator"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/invalid/staircase-empty-steps.md

@@ -0,0 +1,3 @@
+:::staircase
+steps:
+:::

package/src/__tests__/fixtures/fences/slides-visuals/invalid/timeline-horizontal-no-events.md

@@ -0,0 +1,2 @@
+:::timeline-horizontal
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching-no-split.md

@@ -0,0 +1,7 @@
+:::flow-branching
+source: "Incoming Request"
+branches:
+  - "API Handler"
+  - "Static Files"
+  - "WebSocket"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching.md

@@ -0,0 +1,8 @@
+:::flow-branching
+source: "Incoming Request"
+split: "Route"
+branches:
+  - "API Handler"
+  - "Static Files"
+  - "WebSocket"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging-no-merge.md

@@ -0,0 +1,7 @@
+:::flow-converging
+sources:
+  - "Frontend Logs"
+  - "API Logs"
+  - "DB Logs"
+target: "Dashboard"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging.md

@@ -0,0 +1,8 @@
+:::flow-converging
+sources:
+  - "Frontend Logs"
+  - "API Logs"
+  - "DB Logs"
+merge: "Aggregator"
+target: "Dashboard"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase-down.md

@@ -0,0 +1,7 @@
+:::staircase
+direction: down
+steps:
+  - "Optimized"
+  - "Managed"
+  - "Defined"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase.md

@@ -0,0 +1,8 @@
+:::staircase
+steps:
+  - "Ad Hoc"
+  - "Repeatable"
+  - "Defined"
+  - "Managed"
+  - "Optimized"
+:::