@brandon_m_behring/book-scaffold-astro 5.1.0 → 5.2.0

package/dist/index.mjs

@@ -1277,8 +1277,8 @@ function corpusCollectionEntryId(corpus, entry, data, options = {}) {
 }
 function corpusBookIdFromPath(corpus, pathname, baseUrl = "/") {
   const normalizedBase2 = baseUrl === "/" ? "/" : `/${baseUrl.replace(/^\/+|\/+$/g, "")}/`;
-  const relative = pathname.startsWith(normalizedBase2) ? pathname.slice(normalizedBase2.length) : pathname.replace(/^\/+/, "");
-  const segments = relative.split("/").filter(Boolean);
+  const relative2 = pathname.startsWith(normalizedBase2) ? pathname.slice(normalizedBase2.length) : pathname.replace(/^\/+/, "");
+  const segments = relative2.split("/").filter(Boolean);
   const candidate = segments[0] === "chapters" ? segments[1] : segments[0];
   return candidate && corpus.books.some((book) => book.id === candidate) ? candidate : null;
 }
@@ -1781,6 +1781,877 @@ function bookScaffoldIntegration(opts) {
   return integration;
 }
 
+// src/lib/og-cards.ts
+import { createHash } from "crypto";
+import {
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  realpath,
+  stat,
+  unlink,
+  writeFile
+} from "fs/promises";
+import { extname, join as join2, relative, sep } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { parse } from "parse5";
+var CARD_WIDTH = 1200;
+var CARD_HEIGHT = 630;
+var TEMPLATE_VERSION = 1;
+var TITLE_LIMIT = 96;
+var DESCRIPTION_LIMIT = 180;
+var BOOK_TITLE_LIMIT = 72;
+var HOSTNAME_LIMIT = 80;
+var ALLOWED_CONFIG_KEYS = /* @__PURE__ */ new Set(["enabled", "exclude"]);
+var UNSUPPORTED_GLOB_TOKENS = /[?\[\]{}]/u;
+var PROFILE_THEMES = Object.freeze({
+  academic: Object.freeze({ background: "#1A1816", accent: "#7297BB" }),
+  tools: Object.freeze({ background: "#26231F", accent: "#AB80A5" }),
+  minimal: Object.freeze({ background: "#1A1816", accent: "#D2B575" }),
+  "course-notes": Object.freeze({ background: "#1A1816", accent: "#7DA275" }),
+  "research-portfolio": Object.freeze({ background: "#26231F", accent: "#D29287" })
+});
+function normalizeOgCardsConfig(value) {
+  if (value === void 0 || value === false) return null;
+  if (value === true) return Object.freeze({ enabled: true, exclude: Object.freeze([]) });
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      "seo.ogCards must be true, false, or an object with enabled and exclude fields."
+    );
+  }
+  const input = value;
+  const unknown = Object.keys(input).filter((key) => !ALLOWED_CONFIG_KEYS.has(key));
+  if (unknown.length > 0) {
+    throw new Error(`seo.ogCards contains unknown ${unknown.length === 1 ? "field" : "fields"}: ${unknown.join(", ")}.`);
+  }
+  if (input.enabled !== void 0 && typeof input.enabled !== "boolean") {
+    throw new Error("seo.ogCards.enabled must be a boolean.");
+  }
+  if (input.exclude !== void 0 && !Array.isArray(input.exclude)) {
+    throw new Error("seo.ogCards.exclude must be an array of route patterns.");
+  }
+  const exclude = input.exclude ?? [];
+  const normalized = Array.from(exclude, (pattern, index) => validateExcludePattern(pattern, index));
+  if (new Set(normalized).size !== normalized.length) {
+    throw new Error("seo.ogCards.exclude must not contain duplicate patterns.");
+  }
+  if (input.enabled === false) return null;
+  return Object.freeze({ enabled: true, exclude: Object.freeze(normalized) });
+}
+function validateExcludePattern(value, index) {
+  const label = `seo.ogCards.exclude[${index}]`;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+  if (!value.startsWith("/")) {
+    throw new Error(`${label} must be base-relative and start with "/".`);
+  }
+  if (value.startsWith("//") || value.includes("\\") || /[\u0000-\u001F\u007F]/u.test(value)) {
+    throw new Error(`${label} must be a local route pattern without a host, backslash, or control character.`);
+  }
+  if (value.includes("?") || value.includes("#")) {
+    throw new Error(`${label} must not contain a query string or fragment.`);
+  }
+  if (UNSUPPORTED_GLOB_TOKENS.test(value)) {
+    throw new Error(`${label} supports only literal segments plus whole "*" and "**" segments.`);
+  }
+  const segments = value.slice(1).split("/");
+  for (let segmentIndex = 0; segmentIndex < segments.length; segmentIndex += 1) {
+    const segment = segments[segmentIndex];
+    const trailingSlash = segmentIndex === segments.length - 1 && segment === "";
+    if (!trailingSlash && segment === "") {
+      throw new Error(`${label} must not contain an empty route segment.`);
+    }
+    if (segment === "." || segment === "..") {
+      throw new Error(`${label} must not contain "." or ".." route segments.`);
+    }
+    if (segment.includes("*") && segment !== "*" && segment !== "**") {
+      throw new Error(`${label}: "*" and "**" must occupy a complete route segment.`);
+    }
+  }
+  return value;
+}
+function escapeRegExp(value) {
+  return value.replace(/[|\\{}()[\]^$+?.-]/g, "\\$&");
+}
+function exclusionMatcher(pattern) {
+  const segments = pattern.split("/");
+  let source = "^";
+  for (let index = 1; index < segments.length; index += 1) {
+    const segment = segments[index];
+    const isLast = index === segments.length - 1;
+    if (segment === "" && isLast) {
+      source += "/";
+      continue;
+    }
+    if (segment === "**") {
+      source += isLast ? "(?:/.*)?" : "(?:/[^/]+)*";
+      continue;
+    }
+    if (segment === "*") {
+      source += "/[^/]+";
+      continue;
+    }
+    source += `/${escapeRegExp(segment)}`;
+  }
+  return new RegExp(`${source}$`, "u");
+}
+function normalizeBase(base) {
+  const trimmed = (base ?? "/").trim();
+  if (!trimmed || trimmed === "/") return "/";
+  return `/${trimmed.replace(/^\/+|\/+$/g, "")}/`;
+}
+function cardUrl(site, base, hash) {
+  const url = new URL(site.origin);
+  url.pathname = `${normalizeBase(base)}_og/${hash}.png`.replace(/\/{2,}/g, "/");
+  return url.toString();
+}
+function resolveStaticImageUrl(value, site, base) {
+  const trimmed = value.trim();
+  if (!trimmed) throw new Error("OG card static image must not be blank.");
+  if (/^https?:\/\//iu.test(trimmed)) {
+    return absoluteHttpUrl(trimmed, "static OG image", "(config)").toString();
+  }
+  if (trimmed.startsWith("//")) {
+    if (trimmed.startsWith("///")) {
+      throw new Error(`OG card static image has an invalid protocol-relative URL: ${JSON.stringify(value)}.`);
+    }
+    return absoluteHttpUrl(`${site.protocol}${trimmed}`, "static OG image", "(config)").toString();
+  }
+  if (/^[a-z][a-z\d+.-]*:/iu.test(trimmed)) {
+    throw new Error(
+      `OG card static image must be local, protocol-relative, or http(s) (got ${JSON.stringify(value)}).`
+    );
+  }
+  if (trimmed.includes("\\") || /[\u0000-\u001F\u007F]/u.test(trimmed)) {
+    throw new Error("OG card local static image must not contain a backslash or control character.");
+  }
+  const rawPath = trimmed.split(/[?#]/u, 1)[0];
+  if (!rawPath) throw new Error("OG card local static image must contain a path.");
+  for (const rawSegment of rawPath.split("/")) {
+    let decoded = rawSegment;
+    try {
+      for (let pass = 0; pass < 4; pass += 1) {
+        const next = decodeURIComponent(decoded);
+        if (next === decoded) break;
+        decoded = next;
+      }
+    } catch {
+      throw new Error(`OG card local static image contains invalid percent encoding: ${JSON.stringify(value)}.`);
+    }
+    if (decoded === "." || decoded === ".." || decoded.includes("/") || decoded.includes("\\") || /[\u0000-\u001F\u007F]/u.test(decoded)) {
+      throw new Error(`OG card local static image must not contain encoded path traversal: ${JSON.stringify(value)}.`);
+    }
+  }
+  const localPath = `/${rawPath.replace(/^\/+/, "")}`;
+  const suffix = trimmed.slice(rawPath.length);
+  const normalizedBase2 = normalizeBase(base);
+  const baseWithoutTrailingSlash = normalizedBase2.replace(/\/+$/u, "");
+  const alreadyPrefixed = normalizedBase2 === "/" || localPath === baseWithoutTrailingSlash || localPath.startsWith(normalizedBase2);
+  const resolvedPath = alreadyPrefixed ? localPath : `${normalizedBase2}${localPath.slice(1)}`;
+  let url;
+  try {
+    url = new URL(`${resolvedPath}${suffix}`, site.origin);
+  } catch {
+    throw new Error(`OG card static image ${JSON.stringify(value)} is not a valid URL.`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`OG card static image must resolve to an http(s) URL (got ${JSON.stringify(value)}).`);
+  }
+  return url.toString();
+}
+function walk(node, visit) {
+  visit(node);
+  for (const child of node.childNodes ?? []) walk(child, visit);
+}
+function attr(node, name) {
+  const found = node.attrs?.find((candidate) => candidate.name.toLowerCase() === name);
+  return found?.value ?? null;
+}
+function elements(document, tagName) {
+  const found = [];
+  walk(document, (node) => {
+    if (node.tagName?.toLowerCase() === tagName) found.push(node);
+  });
+  return found;
+}
+function textContent(node) {
+  if (node.nodeName === "#text") return node.value ?? "";
+  return (node.childNodes ?? []).map(textContent).join("");
+}
+function metas(document, attribute, value) {
+  const normalizedValue = value.toLowerCase();
+  return elements(document, "meta").filter(
+    (node) => attr(node, attribute)?.trim().toLowerCase() === normalizedValue
+  );
+}
+function contentOfUniqueMeta(document, attribute, value, file) {
+  const matches = metas(document, attribute, value);
+  if (matches.length > 1) {
+    throw new Error(`${file}: duplicate <meta ${attribute}=${JSON.stringify(value)}> tags are ambiguous.`);
+  }
+  if (matches.length === 0) return null;
+  const content = attr(matches[0], "content")?.trim() ?? "";
+  if (!content) {
+    throw new Error(`${file}: <meta ${attribute}=${JSON.stringify(value)}> requires non-empty content.`);
+  }
+  return content;
+}
+function absoluteHttpUrl(value, label, file) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${file}: ${label} must be an absolute http(s) URL.`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:" || !url.hostname) {
+    throw new Error(`${file}: ${label} must be an absolute http(s) URL.`);
+  }
+  return url;
+}
+function parsePage(source, file, route) {
+  const document = parse(source, { sourceCodeLocationInfo: true });
+  const html = elements(document, "html");
+  const heads = elements(document, "head");
+  if (html.length !== 1 || heads.length !== 1) {
+    throw new Error(`${file}: generated OG cards require exactly one <html> and one <head> element.`);
+  }
+  const head = heads[0];
+  return { document, head, route, file };
+}
+function isBuiltInErrorRoute(route) {
+  return /(?:^|\/)(?:404|500)(?:\/|\.html)$/u.test(route);
+}
+function isRedirect(document) {
+  return elements(document, "meta").some(
+    (node) => attr(node, "http-equiv")?.trim().toLowerCase() === "refresh"
+  );
+}
+function isNoIndex(document) {
+  return elements(document, "meta").some((node) => {
+    const name = attr(node, "name")?.trim().toLowerCase();
+    if (name !== "robots" && name !== "googlebot") return false;
+    const directives = (attr(node, "content") ?? "").toLowerCase().split(/[\s,]+/u);
+    return directives.includes("noindex") || directives.includes("none");
+  });
+}
+function existingAuthoredOgImage(document, file) {
+  const value = contentOfUniqueMeta(document, "property", "og:image", file);
+  if (value === null) return null;
+  absoluteHttpUrl(value, "og:image content", file);
+  return value;
+}
+function uniqueMarker(document, name, file) {
+  const values = [];
+  walk(document, (node) => {
+    const value = attr(node, name);
+    if (value !== null) values.push(value.trim());
+  });
+  if (values.length > 1) {
+    throw new Error(`${file}: duplicate ${name} identity markers are ambiguous.`);
+  }
+  if (values.length === 0) return null;
+  if (!values[0]) throw new Error(`${file}: ${name} identity marker must not be empty.`);
+  return values[0];
+}
+function pagefindIdentities(document) {
+  const books = /* @__PURE__ */ new Set();
+  let corpusSurface = false;
+  walk(document, (node) => {
+    const filter = attr(node, "data-pagefind-filter");
+    if (filter === null) return;
+    for (const token of filter.split(/[;,\s]+/u)) {
+      if (token.startsWith("book:") && token.length > 5) books.add(token.slice(5));
+      if (token === "surface:corpus") corpusSurface = true;
+    }
+  });
+  return { books: [...books].sort(), corpusSurface };
+}
+function resolvePageIdentity(document, file, corpus) {
+  const markerBook = uniqueMarker(document, "data-book-scaffold-book", file);
+  const markerSurface = uniqueMarker(document, "data-book-scaffold-surface", file);
+  const fallback = pagefindIdentities(document);
+  if (markerSurface !== null && markerSurface !== "corpus") {
+    throw new Error(`${file}: unknown data-book-scaffold-surface ${JSON.stringify(markerSurface)}.`);
+  }
+  if (fallback.books.length > 1) {
+    throw new Error(`${file}: multiple Pagefind book identities are ambiguous.`);
+  }
+  const fallbackBook = fallback.books[0] ?? null;
+  if (markerBook && fallbackBook && markerBook !== fallbackBook) {
+    throw new Error(`${file}: book identity marker ${JSON.stringify(markerBook)} disagrees with Pagefind ${JSON.stringify(fallbackBook)}.`);
+  }
+  const bookId = markerBook ?? fallbackBook;
+  const corpusSurface = markerSurface === "corpus" || fallback.corpusSurface;
+  if (bookId && corpusSurface) {
+    throw new Error(`${file}: a page cannot carry both book and corpus-surface identity.`);
+  }
+  if (!corpus) {
+    if (bookId || corpusSurface) {
+      throw new Error(`${file}: corpus identity markers were rendered without a configured corpus.`);
+    }
+    return { book: null, surface: null };
+  }
+  if (!bookId) return { book: null, surface: corpusSurface ? "corpus" : null };
+  const book = corpus.books.find((candidate) => candidate.id === bookId) ?? null;
+  if (!book) {
+    throw new Error(
+      `${file}: unknown rendered corpus book ${JSON.stringify(bookId)}; expected ${corpus.books.map(({ id }) => id).join(" | ")}.`
+    );
+  }
+  return { book, surface: null };
+}
+function uniqueTitle(document, file) {
+  const ogTitle = contentOfUniqueMeta(document, "property", "og:title", file);
+  if (ogTitle) return ogTitle;
+  const titles = elements(document, "title");
+  if (titles.length > 1) throw new Error(`${file}: duplicate <title> elements are ambiguous.`);
+  if (titles.length === 0) return null;
+  const title = textContent(titles[0]).trim();
+  if (!title) throw new Error(`${file}: <title> must not be empty.`);
+  return title;
+}
+function pageDescription(document, file) {
+  return contentOfUniqueMeta(document, "property", "og:description", file) ?? contentOfUniqueMeta(document, "name", "description", file);
+}
+function canonicalUrl(document, file) {
+  const canonicals = elements(document, "link").filter(
+    (node) => (attr(node, "rel") ?? "").toLowerCase().split(/\s+/u).includes("canonical")
+  );
+  if (canonicals.length !== 1) {
+    throw new Error(`${file}: generated OG cards require exactly one rendered canonical link.`);
+  }
+  const href = attr(canonicals[0], "href")?.trim() ?? "";
+  return absoluteHttpUrl(href, "canonical href", file);
+}
+function clampText(value, limit) {
+  const normalized = value.replace(/\s+/gu, " ").trim();
+  const points = Array.from(normalized);
+  if (points.length <= limit) return normalized;
+  const budget = limit - 1;
+  const prefix = points.slice(0, budget).join("");
+  const boundary = prefix.lastIndexOf(" ");
+  const wordSafe = boundary >= Math.floor(budget * 0.6) ? prefix.slice(0, boundary) : prefix;
+  return `${wordSafe.replace(/[\s,.;:!?\-–—]+$/u, "")}\u2026`;
+}
+function payloadForPage(page, options, identity) {
+  const rawTitle = uniqueTitle(page.document, page.file);
+  if (!rawTitle) throw new Error(`${page.file}: generated OG cards require og:title or <title>.`);
+  const canonical = canonicalUrl(page.document, page.file);
+  const rawBookTitle = identity.book?.title ?? options.title ?? "book-scaffold-astro";
+  const rawDescription = pageDescription(page.document, page.file) ?? identity.book?.description ?? options.description ?? "";
+  return {
+    templateVersion: TEMPLATE_VERSION,
+    width: CARD_WIDTH,
+    height: CARD_HEIGHT,
+    profile: options.profile,
+    bookId: identity.book?.id ?? null,
+    bookTitle: clampText(rawBookTitle, BOOK_TITLE_LIMIT),
+    title: clampText(rawTitle, TITLE_LIMIT),
+    description: clampText(rawDescription, DESCRIPTION_LIMIT),
+    hostname: clampText(canonical.hostname.toLowerCase(), HOSTNAME_LIMIT)
+  };
+}
+function stablePayloadJson(payload) {
+  return JSON.stringify(payload);
+}
+function shortHash(payloadJson) {
+  return createHash("sha256").update(payloadJson, "utf8").digest("hex").slice(0, 16);
+}
+function htmlEscape(value) {
+  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function insertIntoHead(page, source, tags) {
+  if (tags.length === 0) return source;
+  const insertionOffset = page.head.sourceCodeLocation?.endTag?.startOffset;
+  if (insertionOffset === void 0) {
+    throw new Error(`${page.file}: cannot locate </head> for OG metadata insertion.`);
+  }
+  const block = `${tags.map((tag) => `    ${tag}`).join("\n")}
+`;
+  return `${source.slice(0, insertionOffset)}${block}${source.slice(insertionOffset)}`;
+}
+function ensureNoDuplicateImageMetadata(document, file) {
+  for (const [attribute, value] of [
+    ["property", "og:image:width"],
+    ["property", "og:image:height"],
+    ["property", "og:image:type"],
+    ["name", "twitter:image"]
+  ]) {
+    const matches = metas(document, attribute, value);
+    if (matches.length > 1) {
+      throw new Error(`${file}: duplicate ${value} metadata is ambiguous.`);
+    }
+    if (matches.length === 1 && !(attr(matches[0], "content") ?? "").trim()) {
+      throw new Error(`${file}: ${value} metadata requires non-empty content.`);
+    }
+  }
+}
+function staticImageTags(page, imageUrl) {
+  ensureNoDuplicateImageMetadata(page.document, page.file);
+  const tags = [
+    `<meta property="og:image" content="${htmlEscape(imageUrl)}">`
+  ];
+  if (metas(page.document, "name", "twitter:image").length === 0) {
+    tags.push(`<meta name="twitter:image" content="${htmlEscape(imageUrl)}">`);
+  }
+  return tags;
+}
+function generatedImageTags(page, imageUrl) {
+  ensureNoDuplicateImageMetadata(page.document, page.file);
+  const expected = [
+    { attribute: "property", name: "og:image:width", content: String(CARD_WIDTH) },
+    { attribute: "property", name: "og:image:height", content: String(CARD_HEIGHT) },
+    { attribute: "property", name: "og:image:type", content: "image/png" },
+    { attribute: "name", name: "twitter:image", content: imageUrl }
+  ];
+  const tags = [`<meta property="og:image" content="${htmlEscape(imageUrl)}">`];
+  for (const item of expected) {
+    const matches = metas(page.document, item.attribute, item.name);
+    if (matches.length === 1) {
+      const actual = attr(matches[0], "content")?.trim() ?? "";
+      if (actual !== item.content) {
+        throw new Error(
+          `${page.file}: existing ${item.name}=${JSON.stringify(actual)} conflicts with generated value ${JSON.stringify(item.content)}.`
+        );
+      }
+      continue;
+    }
+    tags.push(
+      `<meta ${item.attribute}="${item.name}" content="${htmlEscape(item.content)}">`
+    );
+  }
+  return tags;
+}
+function routeForHtml(outputDir, file) {
+  const local = relative(outputDir, file).split(sep).join("/");
+  if (local === "index.html") return "/";
+  if (local.endsWith("/index.html")) return `/${local.slice(0, -"index.html".length)}`;
+  return `/${local}`;
+}
+async function htmlFiles(outputDir) {
+  const files = [];
+  async function visit(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name, "en"));
+    for (const entry of entries) {
+      const target = join2(directory, entry.name);
+      if (entry.isDirectory()) await visit(target);
+      else if (entry.isFile() && extname(entry.name).toLowerCase() === ".html") files.push(target);
+    }
+  }
+  await visit(outputDir);
+  return files.sort(
+    (left, right) => routeForHtml(outputDir, left).localeCompare(routeForHtml(outputDir, right), "en")
+  );
+}
+function cardTree(payload, theme) {
+  const bookLength = Array.from(payload.bookTitle).length;
+  const titleLength = Array.from(payload.title).length;
+  const descriptionLength = Array.from(payload.description).length;
+  const hostnameLength = Array.from(payload.hostname).length;
+  const children = [
+    {
+      type: "div",
+      key: "og-book",
+      props: {
+        style: {
+          display: "flex",
+          alignItems: "center",
+          width: "100%",
+          maxWidth: 1056,
+          flexShrink: 0,
+          fontSize: bookLength > 56 ? 22 : 25,
+          fontWeight: 700,
+          lineHeight: 1.15,
+          letterSpacing: "-0.01em",
+          wordBreak: "break-word",
+          color: "#F7F5F0"
+        },
+        children: payload.bookTitle
+      }
+    },
+    {
+      type: "div",
+      key: "og-title",
+      props: {
+        style: {
+          display: "flex",
+          width: "100%",
+          marginTop: 28,
+          maxWidth: 1040,
+          flexShrink: 0,
+          fontSize: titleLength > 80 ? 42 : titleLength > 60 ? 48 : titleLength > 40 ? 54 : 62,
+          fontWeight: 700,
+          lineHeight: 1.08,
+          letterSpacing: "-0.035em",
+          wordBreak: "break-word",
+          color: "#FDFCF9"
+        },
+        children: payload.title
+      }
+    }
+  ];
+  if (payload.description) {
+    children.push({
+      type: "div",
+      key: "og-description",
+      props: {
+        style: {
+          display: "flex",
+          width: "100%",
+          marginTop: 22,
+          maxWidth: 1010,
+          flexShrink: 0,
+          fontSize: descriptionLength > 140 ? 20 : descriptionLength > 90 ? 22 : 25,
+          lineHeight: 1.3,
+          wordBreak: "break-word",
+          color: "#E8E5DD"
+        },
+        children: payload.description
+      }
+    });
+  }
+  children.push({
+    type: "div",
+    key: "og-footer",
+    props: {
+      style: {
+        display: "flex",
+        width: "100%",
+        flexShrink: 0,
+        justifyContent: "space-between",
+        alignItems: "flex-end",
+        gap: 32,
+        marginTop: "auto",
+        lineHeight: 1.15,
+        color: "#E8E5DD"
+      },
+      children: [
+        {
+          type: "div",
+          key: "og-hostname",
+          props: {
+            style: {
+              display: "flex",
+              width: 640,
+              minWidth: 0,
+              flexShrink: 1,
+              fontSize: hostnameLength > 60 ? 16 : hostnameLength > 40 ? 18 : 20,
+              lineHeight: 1.15,
+              wordBreak: "break-all"
+            },
+            children: payload.hostname
+          }
+        },
+        {
+          type: "div",
+          key: "og-profile",
+          props: {
+            style: {
+              display: "flex",
+              width: 384,
+              maxWidth: 384,
+              flexShrink: 0,
+              justifyContent: "flex-end",
+              fontSize: 17,
+              fontWeight: 700,
+              lineHeight: 1.15,
+              letterSpacing: "0.08em",
+              textAlign: "right",
+              textTransform: "uppercase",
+              wordBreak: "break-word",
+              color: "#F7F5F0"
+            },
+            children: `BOOK SCAFFOLD \xB7 ${payload.profile.replaceAll("-", " ")}`
+          }
+        }
+      ]
+    }
+  });
+  return {
+    type: "div",
+    key: "og-root",
+    props: {
+      style: {
+        display: "flex",
+        flexDirection: "column",
+        width: CARD_WIDTH,
+        height: CARD_HEIGHT,
+        padding: "66px 72px 58px",
+        borderTop: `14px solid ${theme.accent}`,
+        backgroundColor: theme.background,
+        color: "#FDFCF9",
+        fontFamily: "Inter"
+      },
+      children
+    }
+  };
+}
+function validateCardLayout(boxes) {
+  const required = ["og-root", "og-book", "og-title", "og-footer", "og-hostname", "og-profile"];
+  for (const role of required) {
+    if (!boxes.has(role)) throw new Error(`OG renderer did not report the ${role} layout box.`);
+  }
+  const epsilon = 0.01;
+  for (const [role, box] of boxes) {
+    if (!Number.isFinite(box.left) || !Number.isFinite(box.top) || !Number.isFinite(box.width) || !Number.isFinite(box.height) || box.left < -epsilon || box.top < -epsilon || box.left + box.width > CARD_WIDTH + epsilon || box.top + box.height > CARD_HEIGHT + epsilon) {
+      throw new Error(`OG renderer placed ${role} outside the ${CARD_WIDTH}x${CARD_HEIGHT} card.`);
+    }
+  }
+  const footer = boxes.get("og-footer");
+  const contentBottom = Math.max(
+    boxes.get("og-book").top + boxes.get("og-book").height,
+    boxes.get("og-title").top + boxes.get("og-title").height,
+    ...boxes.has("og-description") ? [boxes.get("og-description").top + boxes.get("og-description").height] : []
+  );
+  if (contentBottom > footer.top + epsilon) {
+    throw new Error("OG renderer content overlaps the footer; shorten or resize the card template.");
+  }
+  const hostname = boxes.get("og-hostname");
+  const profile = boxes.get("og-profile");
+  if (hostname.left + hostname.width > profile.left + epsilon) {
+    throw new Error("OG renderer hostname overlaps the profile mark.");
+  }
+}
+async function readFont(name) {
+  const candidates = [
+    new URL(`../../assets/og-fonts/${name}`, import.meta.url),
+    new URL(`../assets/og-fonts/${name}`, import.meta.url)
+  ];
+  for (const candidate of candidates) {
+    try {
+      return await readFile(candidate);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  throw new Error(`Cannot locate package-owned OG font asset ${name}.`);
+}
+async function renderCard(payload) {
+  const [{ default: satori }, { Resvg }, regular, bold] = await Promise.all([
+    import("satori"),
+    loadResvg(),
+    readFont("Inter-Regular.ttf"),
+    readFont("Inter-Bold.ttf")
+  ]);
+  const boxes = /* @__PURE__ */ new Map();
+  const svg = await satori(cardTree(payload, PROFILE_THEMES[payload.profile]), {
+    width: CARD_WIDTH,
+    height: CARD_HEIGHT,
+    fonts: [
+      { name: "Inter", data: regular, weight: 400, style: "normal" },
+      { name: "Inter", data: bold, weight: 700, style: "normal" }
+    ],
+    onNodeDetected(node) {
+      if (typeof node.key !== "string" || !node.key.startsWith("og-")) return;
+      if (boxes.has(node.key)) throw new Error(`OG renderer reported duplicate ${node.key} layout boxes.`);
+      boxes.set(node.key, {
+        left: node.left,
+        top: node.top,
+        width: node.width,
+        height: node.height
+      });
+    }
+  });
+  validateCardLayout(boxes);
+  const png = new Resvg(svg, {
+    fitTo: { mode: "width", value: CARD_WIDTH }
+  }).render().asPng();
+  return Buffer.from(png);
+}
+async function loadResvg() {
+  try {
+    return await import("@resvg/resvg-js");
+  } catch (error) {
+    throw new Error(
+      "Generated OG cards could not load the @resvg/resvg-js platform binding. Reinstall dependencies for this platform without `--omit=optional` and rebuild.",
+      { cause: error }
+    );
+  }
+}
+async function writeCollisionSafeImage(file, bytes) {
+  let info;
+  try {
+    info = await lstat(file);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    await writeFile(file, bytes, { flag: "wx" });
+    return;
+  }
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw new Error(`${file}: OG card output must be a regular file, never a symlink.`);
+  }
+  const existing = await readFile(file);
+  if (!existing.equals(bytes)) {
+    throw new Error(`${file}: OG content hash collision produced different PNG bytes.`);
+  }
+}
+async function safeOgDirectory(outputDir, create) {
+  const ogDir = join2(outputDir, "_og");
+  let info;
+  try {
+    info = await lstat(ogDir);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    if (!create) return null;
+    await mkdir(ogDir, { recursive: true });
+    info = await lstat(ogDir);
+  }
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new Error(`${ogDir}: OG card output must be a real directory, never a symlink.`);
+  }
+  const [outputReal, ogReal] = await Promise.all([realpath(outputDir), realpath(ogDir)]);
+  if (ogReal !== join2(outputReal, "_og")) {
+    throw new Error(`${ogDir}: OG card output resolved outside the Astro output directory.`);
+  }
+  return ogDir;
+}
+async function pruneStaleCards(ogDir, expectedHashes) {
+  if (ogDir === null) return 0;
+  const entries = await readdir(ogDir, { withFileTypes: true });
+  let removed = 0;
+  entries.sort((left, right) => left.name.localeCompare(right.name, "en"));
+  for (const entry of entries) {
+    const match = /^([a-f\d]{16})\.png$/u.exec(entry.name);
+    if (!match || expectedHashes.has(match[1])) continue;
+    if (entry.isSymbolicLink()) {
+      throw new Error(`${join2(ogDir, entry.name)}: scaffold-owned OG filenames must not be symlinks.`);
+    }
+    if (!entry.isFile()) continue;
+    await unlink(join2(ogDir, entry.name));
+    removed += 1;
+  }
+  return removed;
+}
+async function processBuild(outputDir, site, base, options) {
+  const matchers = options.ogCards.exclude.map(exclusionMatcher);
+  const generatedPlans = [];
+  const staticPlans = [];
+  let skipped = 0;
+  for (const file of await htmlFiles(outputDir)) {
+    const route = routeForHtml(outputDir, file);
+    if (isBuiltInErrorRoute(route) || matchers.some((matcher) => matcher.test(route))) {
+      skipped += 1;
+      continue;
+    }
+    const source = await readFile(file, "utf8");
+    const page = parsePage(source, file, route);
+    if (isRedirect(page.document) || isNoIndex(page.document)) {
+      skipped += 1;
+      continue;
+    }
+    if (existingAuthoredOgImage(page.document, file)) {
+      skipped += 1;
+      continue;
+    }
+    const identity = resolvePageIdentity(page.document, file, options.corpus);
+    const staticImage = identity.book?.image ?? options.staticOgImage;
+    if (staticImage !== void 0) {
+      staticPlans.push({
+        page,
+        source,
+        imageUrl: resolveStaticImageUrl(staticImage, site, base)
+      });
+      continue;
+    }
+    const payload = payloadForPage(page, options, identity);
+    const payloadJson = stablePayloadJson(payload);
+    const hash = shortHash(payloadJson);
+    generatedPlans.push({
+      page,
+      source,
+      payload,
+      payloadJson,
+      hash,
+      imageUrl: cardUrl(site, base, hash)
+    });
+  }
+  const payloadByHash = /* @__PURE__ */ new Map();
+  for (const plan of generatedPlans) {
+    const previous = payloadByHash.get(plan.hash);
+    if (previous !== void 0 && previous !== plan.payloadJson) {
+      throw new Error(`OG payload hash collision at ${plan.hash}; refusing to overwrite card output.`);
+    }
+    payloadByHash.set(plan.hash, plan.payloadJson);
+  }
+  const ogDir = await safeOgDirectory(outputDir, generatedPlans.length > 0);
+  const rendered = /* @__PURE__ */ new Map();
+  let reused = 0;
+  for (const plan of generatedPlans) {
+    if (rendered.has(plan.hash)) {
+      reused += 1;
+      continue;
+    }
+    const bytes = await renderCard(plan.payload);
+    if (bytes.length === 0) throw new Error(`${plan.page.file}: OG renderer returned an empty PNG.`);
+    await writeCollisionSafeImage(join2(ogDir, `${plan.hash}.png`), bytes);
+    rendered.set(plan.hash, bytes);
+  }
+  const pruned = await pruneStaleCards(ogDir, new Set(generatedPlans.map(({ hash }) => hash)));
+  for (const plan of staticPlans) {
+    const tags = staticImageTags(plan.page, plan.imageUrl);
+    await writeFile(plan.page.file, insertIntoHead(plan.page, plan.source, tags), "utf8");
+  }
+  for (const plan of generatedPlans) {
+    const tags = generatedImageTags(plan.page, plan.imageUrl);
+    await writeFile(plan.page.file, insertIntoHead(plan.page, plan.source, tags), "utf8");
+  }
+  return {
+    generated: rendered.size,
+    reused,
+    staticImages: staticPlans.length,
+    skipped,
+    pruned
+  };
+}
+function createOgCardsIntegration(options) {
+  if (!options.ogCards?.enabled) {
+    throw new Error("createOgCardsIntegration requires an enabled normalized ogCards config.");
+  }
+  let site = null;
+  let base = "/";
+  let output = null;
+  return {
+    name: "book-scaffold-og-cards",
+    hooks: {
+      "astro:config:done": ({ config }) => {
+        output = config.output;
+        base = normalizeBase(config.base);
+        if (output !== "static") {
+          throw new Error(
+            `Generated OG cards require Astro output "static" (received ${JSON.stringify(output)}).`
+          );
+        }
+        if (!config.site) {
+          throw new Error("Generated OG cards require an absolute http(s) Astro site URL.");
+        }
+        site = new URL(config.site);
+        if (site.protocol !== "http:" && site.protocol !== "https:" || !site.hostname) {
+          throw new Error("Generated OG cards require an absolute http(s) Astro site URL.");
+        }
+      },
+      "astro:build:done": async ({ dir, logger }) => {
+        if (output !== "static" || !site) {
+          throw new Error(
+            "Generated OG cards were not initialized with a supported static Astro site configuration."
+          );
+        }
+        const outputDir = fileURLToPath2(dir);
+        const info = await stat(outputDir);
+        if (!info.isDirectory()) {
+          throw new Error(`Generated OG card output is not a directory: ${outputDir}`);
+        }
+        const result = await processBuild(outputDir, site, base, options);
+        logger.info(
+          `OG cards: ${result.generated} generated, ${result.reused} reused, ${result.staticImages} static-precedence, ${result.skipped} skipped, ${result.pruned} stale pruned.`
+        );
+      }
+    }
+  };
+}
+
 // src/config.ts
 var BRANDON_PORTFOLIO_DEFAULT = {
   url: "https://brandon-behring.dev",
@@ -1911,6 +2782,7 @@ async function defineBookConfig(opts) {
   const sitemapOptions = {};
   if (sitemapFilter) sitemapOptions.filter = sitemapFilter;
   if (sitemapCustomPages) sitemapOptions.customPages = sitemapCustomPages;
+  const ogCards = normalizeOgCardsConfig(opts.seo?.ogCards);
   const integrations = [
     mdx(),
     preact(),
@@ -1964,7 +2836,17 @@ async function defineBookConfig(opts) {
         apparatusRoutes: opts.apparatusRoutes
       }
     }),
-    ...mergedExtraIntegrations
+    ...mergedExtraIntegrations,
+    // Post-render card generation must observe the final output from every
+    // consumer/style integration, so its build:done hook is installed last.
+    ...ogCards ? [createOgCardsIntegration({
+      profile,
+      corpus,
+      title: opts.title,
+      description: opts.description,
+      staticOgImage: opts.seo?.ogImage,
+      ogCards
+    })] : []
   ];
   const finalRemark = [
     ...remarkPlugins,
@@ -2218,13 +3100,13 @@ function resolveBookHref(siblingBooks, book, to) {
 }
 
 // src/lib/nav-href.ts
-function normalizeBase(baseUrl) {
+function normalizeBase2(baseUrl) {
   return (baseUrl || "/").replace(/\/*$/, "/");
 }
 function baseNoSlash(baseUrl) {
   return (baseUrl || "/").replace(/\/+$/, "");
 }
-var normBase = normalizeBase;
+var normBase = normalizeBase2;
 function fillTokens(pattern, tokens) {
   return pattern.replace(/:(book|slug|route|id)\b/g, (_m, k) => tokens[k] ?? "");
 }
@@ -2552,7 +3434,7 @@ export {
   localCorpusEntryId,
   minimalChapterSchema,
   minimalStyle,
-  normalizeBase,
+  normalizeBase2 as normalizeBase,
   normalizeFrontmatterConfig,
   originUrlFromGitConfig,
   parseRepoSlug,