@docubook/plugin-og-image 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,1008 @@
+import { mkdir, readFile, rename, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { presetRegistry, resolveTheme } from "@docubook/themes-colors";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import matter from "@11ty/gray-matter";
+// src/options.ts
+/**
+* Plugin options from `docu.json` and their validation. Pure: no file system
+* and no flame imports, so a typo stops `flame build` and `flame dev` before
+* anything else runs.
+*/
+var LOG_PREFIX = "[plugin:og-image]";
+var LAYOUTS = ["card", "minimal"];
+var KNOWN_KEYS = /* @__PURE__ */ new Set([
+	"layout",
+	"logo",
+	"siteName",
+	"pages",
+	"fonts"
+]);
+var PAGE_KEYS = /* @__PURE__ */ new Set([
+	"docs",
+	"index",
+	"home"
+]);
+var EXAMPLE = `Example:
+  "plugins": [["@docubook/plugin-og-image", { "layout": "card" }]]`;
+function fail(message) {
+	throw new Error(`${LOG_PREFIX} ${message}\n${EXAMPLE}`);
+}
+/**
+* A value that names something on another host or inline data rather than a
+* local file: `https://…`, `//cdn…`, `data:…`. Single-letter schemes are left
+* alone so a Windows drive path (`C:\…`) is not mistaken for a URL.
+*/
+function isRemoteReference(value) {
+	return /^[a-z][a-z\d+.-]+:/i.test(value) || value.startsWith("//");
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveOptions(input) {
+	if (input === void 0 || input === null) input = {};
+	if (!isPlainObject(input)) fail("options must be an object.");
+	for (const key of Object.keys(input)) if (!KNOWN_KEYS.has(key)) fail(`unknown option "${key}". Valid options: ${[...KNOWN_KEYS].join(", ")}.`);
+	const layout = input.layout ?? "card";
+	if (typeof layout !== "string" || !LAYOUTS.includes(layout)) fail(`"layout" must be one of ${LAYOUTS.map((l) => `"${l}"`).join(", ")}.`);
+	const logo = input.logo;
+	if (logo !== void 0 && logo !== false) {
+		if (typeof logo !== "string" || logo.trim() === "") fail(`"logo" must be a file path or false.`);
+		if (isRemoteReference(logo)) fail(`"logo" must be a local file, not "${logo}". The build never downloads files.`);
+	}
+	const siteName = input.siteName;
+	if (siteName !== void 0 && (typeof siteName !== "string" || siteName.trim() === "")) fail(`"siteName" must be a non-empty string.`);
+	const pages = {
+		docs: true,
+		index: true,
+		home: true
+	};
+	if (input.pages !== void 0) {
+		if (!isPlainObject(input.pages)) fail(`"pages" must be an object such as { "home": false }.`);
+		for (const [key, value] of Object.entries(input.pages)) {
+			if (!PAGE_KEYS.has(key)) fail(`unknown key "pages.${key}". Valid keys: docs, index, home.`);
+			if (typeof value !== "boolean") fail(`"pages.${key}" must be true or false.`);
+			pages[key] = value;
+		}
+	}
+	const fonts = [];
+	if (input.fonts !== void 0) {
+		if (!Array.isArray(input.fonts)) fail(`"fonts" must be an array of { "path": "…" }.`);
+		input.fonts.forEach((font, i) => {
+			if (!isPlainObject(font) || typeof font.path !== "string" || font.path.trim() === "") fail(`"fonts[${i}].path" must be a file path.`);
+			if (isRemoteReference(font.path)) fail(`"fonts[${i}].path" must be a local file, not "${font.path}".`);
+			if (font.weight !== void 0 && (typeof font.weight !== "number" || font.weight < 1 || font.weight > 1e3)) fail(`"fonts[${i}].weight" must be a number from 1 to 1000.`);
+			if (font.style !== void 0 && font.style !== "normal" && font.style !== "italic") fail(`"fonts[${i}].style" must be "normal" or "italic".`);
+			fonts.push({
+				path: font.path,
+				...font.weight !== void 0 && { weight: font.weight },
+				...font.style !== void 0 && { style: font.style }
+			});
+		});
+	}
+	return {
+		layout,
+		logo,
+		siteName,
+		pages,
+		fonts
+	};
+}
+// src/site.ts
+/**
+* What the plugin needs to know about the site, derived from `docu.json` the
+* same way flame derives it. `@docubook/flame` has no runtime exports, so the
+* base-path rules are mirrored here; `__tests__/site.test.ts` pins them to
+* flame's own cases.
+*/
+var DEFAULT_BASE_PATH = "/docs";
+/** Output directory of the cards, below the docs output directory. */
+var CARD_DIR = "assets/og";
+/**
+* Strip slashes from the end (and the start, unless `endOnly`) in one linear
+* pass. A `/\/+$/` regex backtracks polynomially on long runs of `/`.
+*/
+function trimSlashes(value, endOnly = false) {
+	let start = 0;
+	let end = value.length;
+	if (!endOnly) while (start < end && value[start] === "/") start++;
+	while (end > start && value[end - 1] === "/") end--;
+	return value.slice(start, end);
+}
+/** Walk up from `start` to the directory holding `docu.json`, as flame does. */
+function findProjectRoot(start = process.cwd()) {
+	let dir = start;
+	for (let i = 0; i < 6; i++) {
+		if (existsSync(join(dir, "docu.json"))) return dir;
+		const parent = resolve(dir, "..");
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return start;
+}
+/** Mirror of flame's `normalizeBasePath`. */
+function normalizeBasePath(value) {
+	if (typeof value !== "string") return DEFAULT_BASE_PATH;
+	let path = value.trim();
+	if (path.length === 0 || path === "/") return "";
+	try {
+		if (/^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(path)) path = new URL(path).pathname;
+	} catch {}
+	path = `/${trimSlashes(path)}`;
+	return path === "/" ? "" : path;
+}
+/** Mirror of flame's `canonicalBasePath`. */
+function canonicalBasePath(value) {
+	const structural = normalizeBasePath(value);
+	if (structural === "") return "";
+	const cleaned = structural.replace(/\s+/g, "-").replace(/[^A-Za-z0-9\-._~/]+/g, "").split("/").filter((segment) => segment.length > 0 && segment !== "." && segment !== "..").join("/").replace(/-{2,}/g, "-").toLowerCase();
+	return cleaned.length > 0 ? `/${cleaned}` : "";
+}
+/** Mirror of flame's `resolveBasePath`. */
+function resolveBasePath(config) {
+	const basePath = config.meta?.basePath;
+	if (typeof basePath !== "string") return DEFAULT_BASE_PATH;
+	if (normalizeBasePath(basePath) === "") return "";
+	return canonicalBasePath(basePath) || "/docs";
+}
+/** Mirror of flame's `resolveDeployPath`: the path part of `meta.baseURL`. */
+function resolveDeployPath(config) {
+	const raw = config.meta?.baseURL;
+	if (typeof raw !== "string") return "";
+	try {
+		return normalizeBasePath(new URL(raw).pathname);
+	} catch {
+		return raw.startsWith("/") ? normalizeBasePath(raw) : "";
+	}
+}
+function domainOf(baseURL) {
+	try {
+		const url = new URL(baseURL);
+		return `${url.host}${trimSlashes(url.pathname, true)}`;
+	} catch {
+		return;
+	}
+}
+function resolveSite(config, options, root) {
+	const prefix = resolveBasePath(config);
+	const ownPages = config.experimental?.pages === true;
+	const baseURL = trimSlashes((config.meta?.baseURL ?? "").trim(), true);
+	const navbarName = config.navbar?.logoText?.trim();
+	return {
+		root,
+		docsDir: join(root, "docs"),
+		prefix,
+		baseURL,
+		domain: baseURL ? domainOf(baseURL) : void 0,
+		siteName: options.siteName ?? (navbarName || config.meta?.title?.trim() || "Docs"),
+		hasLanding: !ownPages,
+		hasDocsIndex: prefix !== "" || ownPages,
+		routes: Array.isArray(config.routes) ? config.routes : []
+	};
+}
+/**
+* Title of the top-level sidebar group a docs page sits in, e.g. "Getting
+* Started" for `getting-started/configuration`. Top-level pages have none.
+*/
+function sectionFor(routes, slug) {
+	const segments = slug.split("/");
+	if (segments.length < 2) return void 0;
+	return routes.find((r) => typeof r.href === "string" && trimSlashes(r.href) === segments[0])?.title?.trim() || void 0;
+}
+/** Absolute directory flame writes the docs pages to. */
+function docsOutputDir(outDir, prefix) {
+	return prefix === "" ? outDir : join(outDir, prefix.slice(1));
+}
+/**
+* Absolute URL of a card, as flame's SEO resolver builds it for a relative
+* `frontmatter.image`. Root-relative when `meta.baseURL` is unset.
+*/
+function cardUrl(site, file) {
+	return `${site.baseURL}${site.prefix}/${CARD_DIR}/${file}`;
+}
+/** True when `file` is inside `root` (or is `root`). */
+function isInside(root, file) {
+	const rel = relative(root, file);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+var LOGO_TYPES = {
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp"
+};
+/**
+* Map a logo reference to a file in the project.
+*
+* `navbar.logo.src` is a site path (`/docs/assets/images/logo.svg`), while the
+* `logo` option may also be a project path (`brand/logo.svg`). Site paths
+* under the docs prefix, or under the default `/docs` spelling flame re-bases,
+* map to `docs/`; anything else is tried relative to the project root, then
+* to `docs/`.
+*/
+function findLogoFile(value, site, deployPath) {
+	if (isRemoteReference(value)) return {
+		reason: "remote",
+		value
+	};
+	let path = value.split(/[?#]/)[0];
+	const candidates = [];
+	if (path.startsWith("/")) {
+		if (deployPath && path.startsWith(`${deployPath}/`)) path = path.slice(deployPath.length);
+		for (const prefix of [site.prefix, DEFAULT_BASE_PATH]) if (prefix && path.startsWith(`${prefix}/`)) candidates.push(join(site.docsDir, path.slice(prefix.length + 1)));
+		if (site.prefix === "") candidates.push(join(site.docsDir, path.slice(1)));
+		candidates.push(join(site.root, path.slice(1)));
+	} else candidates.push(resolve(site.root, path), resolve(site.docsDir, path));
+	let outside = false;
+	for (const candidate of candidates) {
+		if (!isInside(site.root, candidate)) {
+			outside = true;
+			continue;
+		}
+		try {
+			if (statSync(candidate).isFile()) {
+				if (!(extname(candidate).toLowerCase() in LOGO_TYPES)) return {
+					reason: "type",
+					value
+				};
+				return { file: candidate };
+			}
+		} catch {}
+	}
+	return {
+		reason: outside ? "outside" : "missing",
+		value
+	};
+}
+// src/cards.ts
+/**
+* Turning a page into a card: what text it shows, whether it is skipped, and
+* the file name it is published under. Pure functions over frontmatter.
+*/
+/** Frontmatter value as flame's schema coerces it: primitives become strings. */
+function text(value) {
+	if (typeof value === "string") return value.trim();
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return "";
+}
+function overrides(frontmatter) {
+	const og = frontmatter.og;
+	return typeof og === "object" && og !== null && !Array.isArray(og) ? og : {};
+}
+/**
+* Why a page gets no card, or `undefined` when it gets one. An image the
+* author set always wins; `og: false` opts the page out.
+*/
+function skipReason(kind, frontmatter, options) {
+	if (!options.pages[kind]) return "disabled";
+	if (frontmatter.og === false) return "opt-out";
+	if (text(frontmatter.image)) return "author-image";
+}
+/** Card text for a docs page or the docs index. Mirrors flame's title fallback. */
+function docsCard(kind, slug, frontmatter, site) {
+	const og = overrides(frontmatter);
+	return {
+		kind,
+		slug,
+		title: text(og.title) || text(frontmatter.title) || slug || "Docs",
+		description: text(og.description) || text(frontmatter.description),
+		section: kind === "docs" ? sectionFor(site.routes, slug) : void 0
+	};
+}
+/** Card text for the landing page: the hero headline and the site description. */
+function homeCard(config) {
+	const hero = config.home?.hero;
+	return {
+		kind: "home",
+		slug: "",
+		title: text(hero?.headline) || text(config.meta?.title) || "Docs",
+		description: text(config.meta?.description),
+		section: void 0
+	};
+}
+function sha256(...parts) {
+	const hash = createHash("sha256");
+	for (const part of parts) hash.update(part);
+	return hash.digest("hex");
+}
+/**
+* Plan a card's file. The name hash covers only inputs that also invalidate
+* flame's page cache (plugin version, `docu.json`, the page's source), so a
+* page served from that cache always points at a file this build writes.
+*/
+function planCard(card, site, options, version) {
+	const nameHash = sha256(JSON.stringify([
+		version,
+		options.layout,
+		options.logo ?? null,
+		options.fonts,
+		site.siteName,
+		site.domain ?? null,
+		card.kind,
+		card.title,
+		card.description,
+		card.section ?? null
+	]));
+	return {
+		card,
+		file: `${card.kind === "docs" ? card.slug : card.kind}.${nameHash.slice(0, 8)}.png`,
+		nameHash
+	};
+}
+/** The value set as `frontmatter.image`; flame resolves it against the docs prefix. */
+function imageRef(file) {
+	return `./${CARD_DIR}/${file}`;
+}
+/** Source file candidates for a slug, in the order flame's scanner would find them. */
+function sourceCandidates(docsDir, slug) {
+	if (slug === "") return [join(docsDir, "index.mdx"), join(docsDir, "index.md")];
+	return [
+		join(docsDir, `${slug}.mdx`),
+		join(docsDir, `${slug}.md`),
+		join(docsDir, slug, "index.mdx"),
+		join(docsDir, slug, "index.md")
+	];
+}
+/** Frontmatter of a source file. Parsed with the same library `@docubook/core` uses. */
+function parseFrontmatter(raw) {
+	return matter(raw, {}).data;
+}
+/**
+* Frontmatter of a docs page as written in its source file, or `undefined`
+* when no source exists. Every card is planned from this, never from the
+* frontmatter other plugins hand on, so the page phase and `onEnd` always
+* agree on the file name.
+*/
+async function readFrontmatter(docsDir, slug) {
+	for (const file of sourceCandidates(docsDir, slug)) {
+		let raw;
+		try {
+			raw = await readFile(file, "utf8");
+		} catch {
+			continue;
+		}
+		return parseFrontmatter(raw);
+	}
+}
+/** {@link readFrontmatter} for hooks that must return synchronously. */
+function readFrontmatterSync(docsDir, slug) {
+	for (const file of sourceCandidates(docsDir, slug)) {
+		let raw;
+		try {
+			raw = readFileSync(file, "utf8");
+		} catch {
+			continue;
+		}
+		return parseFrontmatter(raw);
+	}
+}
+// src/layouts.ts
+var WIDTH = 1200;
+var hsl = (triplet, alpha) => alpha === void 0 ? `hsl(${triplet})` : `hsl(${triplet} / ${alpha})`;
+var box = (style, children = []) => ({
+	type: "container",
+	style,
+	children
+});
+var label = (value, style) => ({
+	type: "text",
+	text: value,
+	style
+});
+/** Two lines at most, then an ellipsis. */
+var clamp = {
+	lineClamp: 2,
+	textOverflow: "ellipsis",
+	overflow: "hidden"
+};
+function logoImage(brand, size, radius = 0) {
+	if (!brand.logo) return [];
+	return [{
+		type: "image",
+		src: brand.logo,
+		width: size,
+		height: size,
+		style: {
+			width: size,
+			height: size,
+			borderRadius: radius,
+			objectFit: "contain"
+		}
+	}];
+}
+function identityRow(card, brand, fontSize) {
+	const { palette } = brand;
+	return box({
+		display: "flex",
+		alignItems: "center",
+		gap: 18,
+		fontSize,
+		color: hsl(palette.muted)
+	}, [
+		...logoImage(brand, 56, 14),
+		label(brand.siteName, {
+			fontWeight: 600,
+			color: hsl(palette.foreground)
+		}),
+		...card.section ? [label("›", { opacity: .6 }), label(card.section, {})] : []
+	]);
+}
+function textBlock(card, brand, maxWidth) {
+	return box({
+		display: "flex",
+		flexDirection: "column",
+		gap: 22,
+		maxWidth
+	}, [label(card.title, {
+		fontSize: 64,
+		fontWeight: 700,
+		lineHeight: 1.1,
+		letterSpacing: -1.5,
+		color: hsl(brand.palette.foreground),
+		...clamp
+	}), ...card.description ? [label(card.description, {
+		fontSize: 30,
+		lineHeight: 1.35,
+		color: hsl(brand.palette.muted),
+		...clamp
+	})] : []]);
+}
+/**
+* Default layout: identity row, title, description, a page-kind chip with the
+* domain, the logo in a tinted tile on the right, and a brand bar along the
+* bottom edge over a faint grid.
+*/
+function cardLayout(card, brand) {
+	const { palette } = brand;
+	const kind = card.kind === "home" ? "Home" : "Docs";
+	return box({
+		display: "flex",
+		flexDirection: "column",
+		position: "relative",
+		overflow: "hidden",
+		width: WIDTH,
+		height: 630,
+		backgroundColor: hsl(palette.background),
+		color: hsl(palette.foreground),
+		fontFamily: brand.fontFamily
+	}, [
+		box({
+			position: "absolute",
+			top: 0,
+			left: 0,
+			right: 0,
+			bottom: 0,
+			backgroundImage: `linear-gradient(${hsl(palette.border)} 1px, transparent 1px), linear-gradient(90deg, ${hsl(palette.border)} 1px, transparent 1px)`,
+			backgroundSize: "40px 40px",
+			opacity: .45
+		}),
+		box({
+			position: "absolute",
+			top: -220,
+			right: -160,
+			width: 720,
+			height: 720,
+			borderRadius: 9999,
+			backgroundImage: `radial-gradient(circle, ${hsl(palette.primary, .2)} 0%, ${hsl(palette.primary, 0)} 65%)`
+		}),
+		box({
+			display: "flex",
+			flexDirection: "column",
+			justifyContent: "space-between",
+			flexGrow: 1,
+			position: "relative",
+			padding: "72px 80px 60px 80px"
+		}, [
+			identityRow(card, brand, 28),
+			textBlock(card, brand, brand.logo ? 760 : 1040),
+			box({
+				display: "flex",
+				alignItems: "center",
+				gap: 20,
+				fontSize: 24,
+				color: hsl(palette.muted)
+			}, [box({
+				display: "flex",
+				alignItems: "center",
+				gap: 10,
+				padding: "8px 18px",
+				borderRadius: 9999,
+				backgroundColor: hsl(palette.primary, .1),
+				color: hsl(palette.primary),
+				fontWeight: 600
+			}, [box({
+				width: 10,
+				height: 10,
+				borderRadius: 9999,
+				backgroundColor: hsl(palette.primary)
+			}), label(kind, {})]), ...brand.domain ? [label(brand.domain, {})] : []])
+		]),
+		...brand.logo ? [box({
+			position: "absolute",
+			right: 80,
+			top: 200,
+			width: 220,
+			height: 220,
+			borderRadius: 48,
+			backgroundColor: hsl(palette.primary, .08),
+			display: "flex",
+			alignItems: "center",
+			justifyContent: "center"
+		}, logoImage(brand, 140))] : [],
+		box({
+			height: 12,
+			flexShrink: 0,
+			backgroundColor: hsl(palette.primary)
+		})
+	]);
+}
+/** Plain layout: identity row, title, description, domain. Safe for square crops. */
+function minimalLayout(card, brand) {
+	const { palette } = brand;
+	return box({
+		display: "flex",
+		flexDirection: "column",
+		justifyContent: "space-between",
+		width: WIDTH,
+		height: 630,
+		padding: 80,
+		backgroundColor: hsl(palette.background),
+		color: hsl(palette.foreground),
+		fontFamily: brand.fontFamily
+	}, [
+		box({
+			display: "flex",
+			alignItems: "center",
+			gap: 18,
+			fontSize: 28
+		}, [...logoImage(brand, 56, 14), label(brand.siteName, { fontWeight: 600 })]),
+		textBlock(card, brand, 980),
+		label(brand.domain ?? "", {
+			fontSize: 24,
+			color: hsl(palette.muted)
+		})
+	]);
+}
+function buildTree(layout, card, brand) {
+	return layout === "minimal" ? minimalLayout(card, brand) : cardLayout(card, brand);
+}
+// src/renderer.ts
+/** Family name Takumi gives its built-in font. */
+var BUILTIN_FAMILY = "Geist";
+async function loadTakumi() {
+	try {
+		return await import("@takumi-rs/core");
+	} catch (err) {
+		throw new Error(`${LOG_PREFIX} could not load the Takumi renderer (@takumi-rs/core). Its native binary is installed per platform: run the install again on the machine that builds the site.\nCause: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+	}
+}
+/** Width and height from a PNG's IHDR chunk, or `undefined` for anything else. */
+function pngSize(bytes) {
+	if (bytes.length < 24 || [
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	].some((b, i) => bytes[i] !== b)) return void 0;
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	return {
+		width: view.getUint32(16),
+		height: view.getUint32(20)
+	};
+}
+/** A code point no font maps, so Takumi draws its "missing glyph" box. */
+var NOTDEF_PROBE = "􏿽";
+async function createEngine(fonts) {
+	const { Renderer } = await loadTakumi();
+	const renderer = new Renderer();
+	const families = [];
+	for (const font of fonts) {
+		const registered = await renderer.registerFont({
+			data: font.data,
+			...font.weight !== void 0 && { weight: font.weight },
+			...font.style !== void 0 && { style: font.style }
+		});
+		for (const family of registered) if (!families.includes(family.name)) families.push(family.name);
+	}
+	const fontFamily = [...families, BUILTIN_FAMILY].map((name) => JSON.stringify(name)).join(", ");
+	const glyphCache = /* @__PURE__ */ new Map();
+	let notdef;
+	const drawGlyph = (char) => renderer.render({
+		type: "container",
+		style: {
+			display: "flex",
+			width: 48,
+			height: 48,
+			backgroundColor: "#fff",
+			fontFamily
+		},
+		children: [{
+			type: "text",
+			text: char,
+			style: {
+				fontSize: 32,
+				color: "#000"
+			}
+		}]
+	}, {
+		width: 48,
+		height: 48,
+		format: "raw"
+	});
+	return {
+		fontFamily,
+		async render(tree) {
+			const png = await renderer.render(tree, {
+				width: WIDTH,
+				height: 630,
+				format: "png"
+			});
+			return new Uint8Array(png.buffer, png.byteOffset, png.byteLength);
+		},
+		async missingGlyphs(chars) {
+			const missing = [];
+			for (const char of chars) {
+				if (char.codePointAt(0) < 127 || /\s/u.test(char)) continue;
+				let isMissing = glyphCache.get(char);
+				if (isMissing === void 0) {
+					notdef ??= await drawGlyph(NOTDEF_PROBE);
+					isMissing = notdef.equals(await drawGlyph(char));
+					glyphCache.set(char, isMissing);
+				}
+				if (isMissing) missing.push(char);
+			}
+			return missing;
+		}
+	};
+}
+async function readManifest(path) {
+	try {
+		const parsed = JSON.parse(await readFile(path, "utf8"));
+		if (parsed?.version === 1 && typeof parsed.files === "object" && parsed.files) return parsed;
+	} catch {}
+	return {
+		version: 1,
+		files: {}
+	};
+}
+/** Write through a temp file so an interrupted build never leaves half a file. */
+async function writeAtomic(path, data) {
+	await mkdir(dirname(path), { recursive: true });
+	const temp = `${path}.${process.pid}.tmp`;
+	try {
+		await writeFile(temp, data);
+		await rename(temp, path);
+	} catch (err) {
+		await unlink(temp).catch(() => {});
+		throw err;
+	}
+}
+async function exists(path) {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
+}
+async function mapLimit(items, limit, fn) {
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) await fn(items[next++]);
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+/** Remove now-empty parent directories of a removed card, up to `stop`. */
+async function removeEmptyParents(file, stop) {
+	for (let dir = dirname(file); dir.startsWith(stop) && dir !== stop; dir = dirname(dir)) try {
+		await rmdir(dir);
+	} catch {
+		return;
+	}
+}
+/**
+* Bring `cardDir` in line with `jobs`: render cards that are missing or out
+* of date, delete files an earlier build wrote and this one no longer needs,
+* and save the manifest. Only files listed in the previous manifest are ever
+* deleted, so anything else in the directory is left alone.
+*/
+async function publishCards(jobs, cardDir, manifestPath, render) {
+	const previous = await readManifest(manifestPath);
+	const next = {
+		version: 1,
+		files: {}
+	};
+	const result = {
+		rendered: [],
+		unchanged: [],
+		removed: [],
+		oversized: []
+	};
+	const pending = [];
+	for (const job of jobs) {
+		next.files[job.file] = job.renderHash;
+		if (previous.files[job.file] === job.renderHash && await exists(join(cardDir, job.file))) result.unchanged.push(job.file);
+		else pending.push(job);
+	}
+	await mapLimit(pending, 2, async (job) => {
+		const png = await render(job);
+		const size = pngSize(png);
+		if (!size || size.width !== 1200 || size.height !== 630) throw new Error(`card for "${job.file}" is ${size ? `${size.width}×${size.height}` : "not a PNG"}, expected ${WIDTH}×630`);
+		if (png.byteLength > 307200) result.oversized.push({
+			file: job.file,
+			bytes: png.byteLength
+		});
+		await writeAtomic(join(cardDir, job.file), png);
+		result.rendered.push(job.file);
+	});
+	for (const file of Object.keys(previous.files)) {
+		if (file in next.files) continue;
+		const path = join(cardDir, file);
+		if (!isInside(cardDir, path) || path === cardDir) continue;
+		try {
+			await unlink(path);
+			result.removed.push(file);
+			await removeEmptyParents(path, cardDir);
+		} catch (err) {
+			if (err.code !== "ENOENT") throw err;
+		}
+	}
+	await writeAtomic(manifestPath, `${JSON.stringify(next, null, 2)}\n`);
+	return result;
+}
+// src/index.ts
+/**
+* @docubook/plugin-og-image
+*
+* Gives every page a 1200×630 social preview card, rendered at build time
+* from the page's frontmatter with Takumi. Authors write nothing extra:
+*
+* - `transformFrontmatter` points `frontmatter.image` at the page's card, and
+*   flame's own SEO code turns it into an absolute `og:image`;
+* - `injectHead` adds the card's size, type and alt text, and an `og:image`
+*   on the landing page when `meta.ogImage` does not set one;
+* - `onEnd` renders the cards into `<docs>/assets/og/`, skipping the ones
+*   whose inputs did not change;
+* - `handleRequest` renders a card on demand during `flame dev`.
+*
+* An `image` in frontmatter always wins, and `og: false` opts a page out.
+*/
+/** Logos above this size are skipped: a card shows them at 140 px. */
+var MAX_LOGO_BYTES = 1048576;
+/** Cards kept in memory by the dev server. */
+var DEV_CACHE_SIZE = 50;
+var consoleLogger = {
+	info: (message) => console.log(`${LOG_PREFIX} ${message}`),
+	warn: (message) => console.warn(`${LOG_PREFIX} ${message}`)
+};
+function escapeAttr(value) {
+	return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function sizeTags(card) {
+	return [
+		`<meta property="og:image:width" content="1200">`,
+		`<meta property="og:image:height" content="630">`,
+		`<meta property="og:image:type" content="image/png">`,
+		`<meta property="og:image:alt" content="${escapeAttr(card.title)}">`
+	];
+}
+/** Light-mode colours of the active theme, as flame resolves it. */
+function resolvePalette(config) {
+	const themeConfig = process.env.FLAME_THEME || config.themes?.colors;
+	const vars = resolveTheme(themeConfig, presetRegistry).variables.root;
+	return {
+		background: vars.background ?? "0 0% 100%",
+		foreground: vars.foreground ?? "220 30% 15%",
+		primary: vars.primary ?? "210 81% 56%",
+		muted: vars["muted-foreground"] ?? "220 15% 38%",
+		border: vars["border-color"] ?? "210 20% 88%"
+	};
+}
+async function loadLogo(config, site, options, log) {
+	if (options.logo === false) return void 0;
+	const value = options.logo ?? config.navbar?.logo?.src;
+	if (!value) return void 0;
+	const source = options.logo ? `"logo" option` : `navbar.logo.src`;
+	const found = findLogoFile(value, site, resolveDeployPath(config));
+	if ("reason" in found) {
+		const why = {
+			remote: "is a URL, and the build never downloads files",
+			outside: "points outside the project",
+			missing: "was not found in the project",
+			type: "is not an SVG, PNG, JPEG or WebP file"
+		}[found.reason];
+		log.warn(`${source} "${value}" ${why}. Cards are rendered without a logo; set the "logo" option to a local file.`);
+		return;
+	}
+	const { size } = await stat(found.file);
+	if (size > 1048576) {
+		log.warn(`${source} "${value}" is ${Math.round(size / 1024)} KB, above the 1 MB limit. Cards are rendered without a logo.`);
+		return;
+	}
+	return new Uint8Array(await readFile(found.file));
+}
+async function loadRuntime(config, site, options, log, makeEngine) {
+	const fonts = [];
+	for (const font of options.fonts) {
+		const path = resolve(site.root, font.path);
+		let data;
+		try {
+			data = new Uint8Array(await readFile(path));
+		} catch (err) {
+			throw new Error(`${LOG_PREFIX} font "${font.path}" could not be read: ${err.message}`, { cause: err });
+		}
+		fonts.push({
+			...font,
+			data
+		});
+	}
+	const logo = await loadLogo(config, site, options, log);
+	const engine = await makeEngine(fonts);
+	const palette = resolvePalette(config);
+	return {
+		engine,
+		brand: {
+			siteName: site.siteName,
+			domain: site.domain,
+			logo,
+			palette,
+			fontFamily: engine.fontFamily
+		},
+		fingerprint: sha256(JSON.stringify(palette), logo ? sha256(logo) : "no-logo", ...fonts.map((font) => sha256(font.data)))
+	};
+}
+function describe(list, limit = 5) {
+	const shown = list.slice(0, limit).join(", ");
+	return list.length > limit ? `${shown} (+${list.length - limit} more)` : shown;
+}
+function pluginOgImage(options, internals = {}) {
+	const resolved = resolveOptions(options);
+	const version = internals.version ?? "0.1.0";
+	const log = internals.log ?? consoleLogger;
+	return {
+		name: "og-image",
+		setup(build) {
+			const config = build.config;
+			const root = internals.root ?? findProjectRoot();
+			for (const [label, path] of [...typeof resolved.logo === "string" && !resolved.logo.startsWith("/") ? [["logo", resolved.logo]] : [], ...resolved.fonts.map((font, i) => [`fonts[${i}].path`, font.path])]) if (!isInside(root, resolve(root, path))) throw new Error(`${LOG_PREFIX} "${label}" must point inside the project, not "${path}".`);
+			const site = resolveSite(config, resolved, root);
+			const plan = (card) => planCard(card, site, resolved, version);
+			const wantsHome = () => site.hasLanding && resolved.pages.home && !config.meta?.ogImage;
+			let runtime;
+			const ready = () => runtime ??= loadRuntime(config, site, resolved, log, internals.createEngine ?? createEngine);
+			build.onStart(async () => {
+				if (!site.baseURL) log.warn(`meta.baseURL is not set, so og:image stays a relative URL that social sites ignore.`);
+				await ready();
+			});
+			const linked = /* @__PURE__ */ new Map();
+			build.transformFrontmatter((frontmatter, ctx) => {
+				linked.delete(ctx.slug);
+				const kind = ctx.slug === "" ? "index" : "docs";
+				if (kind === "index" && !site.hasDocsIndex) return;
+				if (skipReason(kind, frontmatter, resolved)) return;
+				let source;
+				try {
+					source = readFrontmatterSync(site.docsDir, ctx.slug);
+				} catch {
+					return;
+				}
+				if (!source || skipReason(kind, source, resolved)) return;
+				const planned = plan(docsCard(kind, ctx.slug, source, site));
+				linked.set(ctx.slug, planned);
+				return {
+					...frontmatter,
+					image: imageRef(planned.file)
+				};
+			});
+			build.injectHead((ctx) => {
+				if (ctx.pageType === "docs") {
+					const planned = linked.get(ctx.slug);
+					return planned && ctx.frontmatter.image === imageRef(planned.file) ? sizeTags(planned.card) : [];
+				}
+				if (ctx.pageType === "home" && wantsHome()) {
+					const planned = plan(homeCard(config));
+					return [`<meta property="og:image" content="${escapeAttr(cardUrl(site, planned.file))}">`, ...sizeTags(planned.card)];
+				}
+				return [];
+			});
+			build.onEnd(async (_config, pages, { outDir }) => {
+				const started = performance.now();
+				const rt = await ready();
+				const cards = [];
+				let skipped = 0;
+				const addDocs = async (kind, slug) => {
+					let frontmatter;
+					try {
+						frontmatter = await readFrontmatter(site.docsDir, slug);
+					} catch (err) {
+						log.warn(`skipped "${slug || "index"}": its frontmatter could not be read (${err.message}).`);
+						return;
+					}
+					if (!frontmatter) return;
+					if (skipReason(kind, frontmatter, resolved)) {
+						skipped++;
+						return;
+					}
+					cards.push(plan(docsCard(kind, slug, frontmatter, site)));
+				};
+				if (resolved.pages.docs) for (const page of pages) await addDocs("docs", page.slug);
+				if (site.hasDocsIndex && resolved.pages.index) await addDocs("index", "");
+				if (wantsHome()) cards.push(plan(homeCard(config)));
+				const missing = await rt.engine.missingGlyphs(new Set(cards.flatMap(({ card }) => [...`${card.title}${card.description}${card.section ?? ""}`]).concat([...site.siteName])));
+				if (missing.length > 0) {
+					const affected = cards.filter(({ card }) => missing.some((char) => `${card.title}${card.description}${card.section ?? ""}`.includes(char))).map(({ card }) => card.kind === "docs" ? card.slug : card.kind);
+					log.warn(`no loaded font can draw ${describe(missing.map((char) => `"${char}"`), 10)}, so cards show boxes in their place. Add a font that covers them with the "fonts" option.` + (affected.length > 0 ? ` Pages: ${describe(affected)}.` : ""));
+				}
+				const jobs = cards.map((planned) => ({
+					...planned,
+					renderHash: sha256(planned.nameHash, rt.fingerprint)
+				}));
+				const cardDir = join(docsOutputDir(outDir, site.prefix), CARD_DIR);
+				let result;
+				try {
+					result = await publishCards(jobs, cardDir, join(dirname(outDir), "og-image.json"), (job) => rt.engine.render(buildTree(resolved.layout, job.card, rt.brand)));
+				} catch (err) {
+					throw new Error(`${LOG_PREFIX} ${err.message}`, { cause: err });
+				}
+				for (const { file, bytes } of result.oversized) log.warn(`${file} is ${Math.round(bytes / 1024)} KB; some apps (WhatsApp) skip previews above 300 KB.`);
+				const parts = [`${result.rendered.length} rendered`, `${result.unchanged.length} unchanged`];
+				if (result.removed.length > 0) parts.push(`${result.removed.length} removed`);
+				if (skipped > 0) parts.push(`${skipped} pages use their own image`);
+				log.info(`${jobs.length} cards: ${parts.join(", ")} (${Math.round(performance.now() - started)}ms)`);
+			});
+			const devCache = /* @__PURE__ */ new Map();
+			const base = `${site.prefix}/${CARD_DIR}/`;
+			build.handleRequest(async (req) => {
+				const { pathname } = new URL(req.url);
+				if (!pathname.startsWith(base)) return;
+				const notFound = () => new Response("Not found", { status: 404 });
+				let relative;
+				try {
+					relative = decodeURIComponent(pathname.slice(base.length));
+				} catch {
+					return notFound();
+				}
+				const match = /^(.+)\.([0-9a-f]{8})\.png$/.exec(relative);
+				if (!match) return notFound();
+				const [, stem, hash] = match;
+				if (stem.split("/").some((s) => !/^[\w@-][\w.@-]*$/.test(s) || s.includes(".."))) return notFound();
+				try {
+					const candidates = [];
+					if (stem === "home" && wantsHome()) candidates.push(plan(homeCard(config)));
+					if (stem === "index" && site.hasDocsIndex && resolved.pages.index) {
+						const frontmatter = await readFrontmatter(site.docsDir, "");
+						if (frontmatter) candidates.push(plan(docsCard("index", "", frontmatter, site)));
+					}
+					if (resolved.pages.docs) {
+						const frontmatter = await readFrontmatter(site.docsDir, stem);
+						if (frontmatter) candidates.push(plan(docsCard("docs", stem, frontmatter, site)));
+					}
+					const chosen = candidates.find((c) => c.nameHash.startsWith(hash)) ?? candidates[0];
+					if (!chosen) return notFound();
+					const rt = await ready();
+					const key = sha256(chosen.nameHash, rt.fingerprint);
+					let png = devCache.get(key);
+					if (!png) {
+						png = await rt.engine.render(buildTree(resolved.layout, chosen.card, rt.brand));
+						devCache.set(key, png);
+						if (devCache.size > DEV_CACHE_SIZE) devCache.delete(devCache.keys().next().value);
+					}
+					return new Response(png, { headers: {
+						"Content-Type": "image/png",
+						"Cache-Control": "no-cache"
+					} });
+				} catch (err) {
+					return new Response(`${LOG_PREFIX} ${err.message}`, { status: 500 });
+				}
+			});
+		}
+	};
+}
+export { MAX_LOGO_BYTES, pluginOgImage as default, resolvePalette };
+
+//# sourceMappingURL=index.js.map