@brandon_m_behring/book-scaffold-astro 5.1.0 → 5.2.0

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { i as BookSchemasOptions } from './types-D1QZgKMO.js';
+import { i as BookSchemasOptions } from './types-DjqMnwHw.js';
 import 'astro';
 import './schemas-CKipJ5Ie.js';
 import 'astro/zod';

package/dist/{types-D1QZgKMO.d.ts → types-DjqMnwHw.d.ts}

@@ -545,6 +545,17 @@ type SiblingBooks = Record<string, SiblingBookEntry>;
 interface SecurityHeadersConfig {
     contentSecurityPolicy?: string;
 }
+/**
+ * v5.2.0 (#157): build-time Open Graph card generation.
+ *
+ * Omit `enabled` (or set it to `true`) to enable generation when the object
+ * form is present. `exclude` contains base-relative route patterns validated
+ * by the OG-card integration during config evaluation.
+ */
+interface OgCardsConfig {
+    enabled?: boolean;
+    exclude?: readonly string[];
+}
 /**
  * v4.26.2 (#149): book-level release state rendered by
  * `<PreReleaseBanner>` across every page.
@@ -746,9 +757,10 @@ interface BookConfigOptions {
      * `ogImage` — default Open Graph image URL (relative to the site root, or
      * absolute). When omitted, no `<meta property="og:image">` is emitted by
      * default; per-page `Astro.props.ogImage` can still set one. Consumers
-     * opt-in to OG cards by adding e.g. `/og-default.png` to their `public/`
-     * AND setting `seo: { ogImage: '/og-default.png' }`. Avoids broken-link
-     * meta tags on consumers who haven't authored an OG image yet.
+     * opt in to a static default by adding e.g. `/og-default.png` to `public/`
+     * and setting `seo: { ogImage: '/og-default.png' }`. A static default
+     * suppresses generation; use `ogCards` below for generated cards. Omitting
+     * both avoids broken-link meta tags when no image has been authored.
      *
      * `twitterHandle` — adds `<meta name="twitter:site" content="@handle">`
      * when set. Omitted by default.
@@ -765,6 +777,12 @@ interface BookConfigOptions {
     seo?: {
         ogImage?: string;
         twitterHandle?: string;
+        /**
+         * v5.2.0 (#157): opt into deterministic, build-time social cards. `true`
+         * uses the defaults; the object form can disable generation explicitly or
+         * add base-relative route exclusions.
+         */
+        ogCards?: boolean | OgCardsConfig;
         sitemap?: {
             filter?: (page: string) => boolean;
             customPages?: string[];
@@ -963,4 +981,4 @@ declare function resolvePreset(explicitPreset?: BookPreset, explicitProfile?: Bo
  */
 declare function resolveProfile(explicit?: BookProfile): BookProfile;
 
-export { defineProfile as A, BOOK_PRESETS as B, CORPUS_APPARATUS_ROUTES as C, defineStyle as D, normalizeFrontmatterConfig as E, type FreshnessAffordance as F, resolvePreset as G, resolveProfile as H, NUMBER_STYLES as N, type PartKey as P, type ReleaseStatusConfig as R, type SecurityHeadersConfig as S, type VolatilityBadge as V, BOOK_PROFILES as a, BookConfigError as b, type BookConfigOptions as c, type BookCorpus as d, type BookCorpusInput as e, type BookPreset as f, type BookProfile as g, type BookScaffoldIntegrationOptions as h, type BookSchemasOptions as i, type ChapterFor as j, type ChaptersRenderer as k, type CorpusApparatusRoute as l, type CorpusBook as m, type CorpusBookInput as n, type FrontmatterRouteConfig as o, type NumberStyle as p, type PartialRouteToggles as q, type ProfileDefinition as r, type RouteToggles as s, type SiblingBookDescriptor as t, type SiblingBookEntry as u, type SiblingBooks as v, type StatusBadge as w, type Style as x, type StyleInput as y, composeStyles as z };
+export { defineProfile as A, BOOK_PRESETS as B, CORPUS_APPARATUS_ROUTES as C, defineStyle as D, normalizeFrontmatterConfig as E, type FreshnessAffordance as F, resolvePreset as G, resolveProfile as H, NUMBER_STYLES as N, type OgCardsConfig as O, type PartKey as P, type ReleaseStatusConfig as R, type SecurityHeadersConfig as S, type VolatilityBadge as V, BOOK_PROFILES as a, BookConfigError as b, type BookConfigOptions as c, type BookCorpus as d, type BookCorpusInput as e, type BookPreset as f, type BookProfile as g, type BookScaffoldIntegrationOptions as h, type BookSchemasOptions as i, type ChapterFor as j, type ChaptersRenderer as k, type CorpusApparatusRoute as l, type CorpusBook as m, type CorpusBookInput as n, type FrontmatterRouteConfig as o, type NumberStyle as p, type PartialRouteToggles as q, type ProfileDefinition as r, type RouteToggles as s, type SiblingBookDescriptor as t, type SiblingBookEntry as u, type SiblingBooks as v, type StatusBadge as w, type Style as x, type StyleInput as y, composeStyles as z };

package/layouts/Base.astro

@@ -124,18 +124,112 @@ const showToolsChrome = (profile !== 'academic') && showChrome;
 // here. `new URL` resolves the relative pathname against it.
 const canonicalURL = new URL(Astro.url.pathname, Astro.site).toString();
 
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
+
+/**
+ * Public assets are authored relative to the deployment root, while `site`
+ * may already carry that same Astro base. Resolve against the origin and add
+ * the normalized base only when it is not already present so every local
+ * image receives the deployment prefix exactly once.
+ */
+function resolvePublicAssetUrl(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error('Open Graph image must be a non-empty URL or public asset path.');
+  }
+  const site = new URL(Astro.site);
+
+  if (/^https?:\/\//i.test(trimmed)) {
+    try {
+      const absolute = new URL(trimmed);
+      if (absolute.protocol !== 'http:' && absolute.protocol !== 'https:') throw new Error();
+    } catch {
+      throw new Error(`Open Graph image is not a valid http(s) URL: ${JSON.stringify(value)}`);
+    }
+    return trimmed;
+  }
+  if (trimmed.startsWith('//')) {
+    if (trimmed.startsWith('///')) {
+      throw new Error(
+        `Open Graph image has an invalid protocol-relative URL: ${JSON.stringify(value)}`,
+      );
+    }
+    try {
+      const absolute = new URL(`${site.protocol}${trimmed}`);
+      if (absolute.protocol !== 'http:' && absolute.protocol !== 'https:') throw new Error();
+      return absolute.toString();
+    } catch {
+      throw new Error(
+        `Open Graph image has an invalid protocol-relative URL: ${JSON.stringify(value)}`,
+      );
+    }
+  }
+  if (/^[a-z][a-z\d+.-]*:/i.test(trimmed)) {
+    throw new Error(
+      `Open Graph image must use http(s) or a public asset path: ${JSON.stringify(value)}`,
+    );
+  }
+  if (trimmed.includes('\\') || /[\u0000-\u001F\u007F]/u.test(trimmed)) {
+    throw new Error(
+      `Open Graph image contains an invalid path character: ${JSON.stringify(value)}`,
+    );
+  }
+
+  const rawPath = trimmed.split(/[?#]/u, 1)[0] ?? '';
+  if (!rawPath) {
+    throw new Error(`Open Graph image must contain a public asset path: ${JSON.stringify(value)}`);
+  }
+  for (const rawSegment of rawPath.replace(/^\/+/, '').split('/')) {
+    let segment = rawSegment;
+    try {
+      for (let pass = 0; pass < 4; pass += 1) {
+        const decoded = decodeURIComponent(segment);
+        if (decoded === segment) break;
+        segment = decoded;
+      }
+    } catch {
+      throw new Error(
+        `Open Graph image contains invalid percent encoding: ${JSON.stringify(value)}`,
+      );
+    }
+    if (
+      segment === '.'
+      || segment === '..'
+      || segment.includes('/')
+      || segment.includes('\\')
+      || /[\u0000-\u001F\u007F]/u.test(segment)
+    ) {
+      throw new Error(
+        `Open Graph image contains an invalid decoded path segment: ${JSON.stringify(value)}`,
+      );
+    }
+  }
+
+  const localPath = `/${rawPath.replace(/^\/+/, '')}`;
+  const suffix = trimmed.slice(rawPath.length);
+  const basePath = baseUrl.startsWith('/') ? baseUrl : `/${baseUrl}`;
+  const baseWithoutTrailingSlash = basePath.replace(/\/+$/, '');
+  const alreadyPrefixed = basePath === '/'
+    || localPath === baseWithoutTrailingSlash
+    || localPath.startsWith(basePath);
+  const resolvedPath = alreadyPrefixed
+    ? localPath
+    : `${basePath}${localPath.slice(1)}`;
+
+  return new URL(`${resolvedPath}${suffix}`, site.origin).toString();
+}
+
 // Per D3: og:image emits only when an image is explicitly set — either via
 // per-page Astro.props.ogImage or book-level bookConfig.seo.ogImage. No
 // '/og-default.png' fallback to avoid broken-link meta tags on consumers
 // without an OG image authored.
 const resolvedOgImage = ogImage ?? corpusBook?.image ?? bookConfig.seo?.ogImage ?? null;
 const absoluteOgImage = resolvedOgImage
-  ? new URL(resolvedOgImage, Astro.site).toString()
+  ? resolvePublicAssetUrl(resolvedOgImage)
   : null;
 const twitterHandle = bookConfig.seo?.twitterHandle ?? null;
 const ogSiteName = corpusBook?.title ?? bookConfig.title ?? title;
 const ogDescription = description ?? corpusBook?.description ?? bookConfig.description ?? '';
-const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 const searchHref = bookId
   ? `${baseUrl}search/?book=${encodeURIComponent(bookId)}`
   : `${baseUrl}search/`;
@@ -147,7 +241,11 @@ const pagefindFilter = bookId
 ---
 
 <!doctype html>
-<html lang={lang}>
+<html
+  lang={lang}
+  data-book-scaffold-book={corpusBook?.id}
+  data-book-scaffold-surface={pagefindSurface === 'corpus' ? 'corpus' : undefined}
+>
   <head>
     <meta charset="utf-8" />
     <link rel="icon" type="image/svg+xml" href={`${baseUrl}favicon.svg`} />

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books with five typed presets, Tufte typography, citations, search, PDF, and Cloudflare deployment.",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -158,6 +158,7 @@
     "src/schemas.ts",
     "src/types.ts",
     "components",
+    "assets",
     "styles",
     "layouts",
     "pages",
@@ -203,12 +204,14 @@
     "@citation-js/plugin-bibtex": "^0.7.21",
     "@fontsource-variable/roboto": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
+    "@resvg/resvg-js": "^2.6.2",
     "ajv": "^8.20.0",
     "pagefind": "^1.5.2",
     "parse5": "^7.3.0",
     "remark-math": "^6.0.0",
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
+    "satori": "^0.26.0",
     "unified": "^11.0.5",
     "vite": "^7.3.2",
     "yaml": "^2.9.0"

package/recipes/26-generated-og-cards.md

@@ -0,0 +1,205 @@
+# Recipe 26 — Generate Open Graph cards at build time
+
+**Profile**: any, in single-book or corpus mode.
+
+**TL;DR**: Set `seo.ogCards: true` to generate a deterministic 1200×630 PNG
+for each eligible rendered HTML page that does not already have an authored
+Open Graph image. Generation runs offline after all other integrations, writes
+content-addressed files beneath `_og/`, and patches only the missing image
+metadata. A page image, corpus-book manifest image, or static `seo.ogImage`
+always wins.
+
+## Opt in
+
+The short form enables generation with only the built-in exclusions:
+
+```ts
+import {
+  academicStyle,
+  defineBookConfig,
+} from '@brandon_m_behring/book-scaffold-astro';
+
+export default await defineBookConfig({
+  styles: [academicStyle],
+  site: 'https://book.example/',
+  seo: {
+    ogCards: true,
+  },
+});
+```
+
+Use the object form when particular routes should not receive cards:
+
+```ts
+seo: {
+  ogCards: {
+    enabled: true,
+    exclude: [
+      '/print/',       // exact route
+      '/drafts/*/',    // one complete path segment
+      '/archive/**',   // zero or more complete path segments
+    ],
+  },
+}
+```
+
+`ogCards` is `false` by default. `false` and `{ enabled: false }` both disable
+the generator. Exclusion patterns are base-relative route paths, even when
+Astro `base` is not `/`; do not repeat the deployment base in the pattern.
+
+The accepted grammar is deliberately small:
+
+| Form | Meaning |
+|---|---|
+| `/some/route/` | Match that normalized route exactly |
+| `*` path segment | Match exactly one complete segment |
+| `**` path segment | Match zero or more complete segments |
+
+Wildcards are whole segments, not substring syntax, and a trailing slash is
+significant. Patterns must start `/` and cannot contain a host, query,
+fragment, backslash, control character, empty internal segment, `.`/`..`, or
+unsupported `?`/`[]`/`{}` glob syntax. Invalid and duplicate patterns fail
+configuration instead of being ignored. The configured list augments built-in
+skips for emitted 404/500 files, meta-refresh redirects, and
+`robots`/`googlebot` `noindex` pages.
+
+## Know which image wins
+
+Image precedence is strict:
+
+1. a page/layout `ogImage`, including chapter frontmatter `image`;
+2. the current corpus book's manifest `image`;
+3. the static application default at `seo.ogImage`;
+4. a generated per-page card.
+
+The integration inspects the final HTML. If it finds a valid
+`<meta property="og:image">`, it leaves that tag and the page untouched. This
+makes a one-page override, corpus-book image, and application-wide static
+default reliable opt-outs from generation without a second exclusion list.
+
+When generation is selected, the integration adds this complete image set:
+
+```html
+<meta property="og:image" content="https://book.example/_og/0123abcd4567ef89.png">
+<meta property="og:image:width" content="1200">
+<meta property="og:image:height" content="630">
+<meta property="og:image:type" content="image/png">
+<meta name="twitter:image" content="https://book.example/_og/0123abcd4567ef89.png">
+```
+
+Existing title, description, canonical, and Twitter text metadata remain
+authoritative. The integration does not change sitemap or Pagefind inclusion.
+
+## What the build emits
+
+The generator runs in the final `astro:build:done` hook, after scaffold and
+consumer integrations have rendered their output. It walks emitted HTML in
+stable pathname order, derives the card from the rendered metadata, renders an
+SVG tree with Satori, converts it with `@resvg/resvg-js`, and writes a 1200×630
+PNG at:
+
+```text
+_og/<first-16-hex-of-content-sha256>.png
+```
+
+The hash covers template version 1, dimensions, resolved preset and exact
+corpus book id (or `null`), the clamped book/page/description strings, and the
+rendered canonical hostname. The route is not drawn on the card. Two pages
+with the same visual payload reuse one file; changing a visual input produces
+a new immutable URL. A same-hash/different-bytes collision fails the build.
+
+Only images referenced by the current build remain. Astro normally empties the
+output directory first; when `emptyOutDir: false` preserves it, the integration
+automatically prunes stale scaffold-owned `_og` filenames matching exactly 16
+hex characters plus `.png`. It leaves every other file untouched, so there is
+no user-managed cache or cleanup step.
+
+## Offline fonts and deterministic content
+
+Cards contain the page title, optional description, resolved book or corpus
+title, canonical hostname, and a small scaffold/profile mark. After whitespace
+normalization, values are clamped by Unicode code point: page title 96,
+description 180, book/corpus title 72, and hostname 80. Truncated values use a
+word-boundary ellipsis when possible.
+
+Satori receives the package-owned Inter v4.1 assets
+`assets/og-fonts/Inter-Regular.ttf` and `Inter-Bold.ttf` under the OFL 1.1. The
+build never downloads a web font or uses a consumer machine's installed fonts,
+so an unchanged payload produces unchanged bytes on supported platforms. The
+five presets use one accessible layout and type scale with preset-specific
+colors. Corpus books keep the corpus-wide preset; the generator never invents
+a per-book profile.
+
+## Corpus identity and Astro base
+
+Corpus pages use the identity marker emitted by the scaffold runtime. A book
+chapter therefore receives its registered book title, even when two books
+reuse the same local slug or page title. Corpus-level landing and search pages
+use corpus identity and are not attributed to the first manifest book.
+
+The physical file is `<outDir>/_og/<hash>.png`. Its metadata URL combines the
+Astro `site` origin, normalized `base`, and `_og/<hash>.png` exactly once. Keep
+exclusion patterns base-relative: a deployment at `base: '/manual/'` still
+excludes its print page with `/print/`, while emitted metadata points beneath
+`https://book.example/manual/_og/…`.
+
+## Failure and skip behavior
+
+An enabled generator is fail-loud. A generated card requires one absolute
+`http(s)` canonical link and a non-empty rendered `og:title` or `<title>`.
+Missing, invalid, duplicate, or contradictory metadata/identity; unreadable
+output; font or renderer failure; a hash collision; or inability to patch the
+selected HTML fails the Astro build. It never publishes image metadata without
+the corresponding PNG and never silently downgrades a requested card.
+
+Expected exclusions are skips, not errors: a valid absolute `http(s)` authored
+image, configured patterns, emitted 404/500 files, meta-refresh redirects,
+`robots`/`googlebot` `noindex`, and non-HTML output do not generate a PNG.
+Corpus/static precedence injects its image URL without rendering a PNG.
+Server/SSR routes, runtime image services, remote templates, arbitrary
+consumer JSX card templates, and animation are outside this build-time
+contract.
+
+## Verify a deployment
+
+Build normally, then inspect both the metadata and referenced file:
+
+```bash
+npm run build
+find dist -path '*/_og/*.png' -print
+grep -R 'property="og:image"' dist --include='*.html'
+```
+
+For a subpath deployment, confirm the absolute meta URL includes `base` once.
+Build twice without changing metadata and confirm the same payload keeps the
+same filename. Add a page override and confirm its authored image remains
+unchanged.
+
+## Common gotchas
+
+- **Setting both `seo.ogImage` and `seo.ogCards`** — the static image wins on
+  every page without a page or corpus-book image, so no generated fallback is
+  needed there.
+- **Including Astro `base` in `exclude`** — patterns are matched after base
+  normalization; write `/print/`, not `/manual/print/`.
+- **Using `*` for nested paths** — `*` crosses exactly one segment; use `**`
+  for any depth.
+- **Expecting runtime generation** — cards are created only for static HTML
+  present at `astro:build:done`.
+
+## Canonical files
+
+- `src/types.ts` — `OgCardsConfig` and `seo.ogCards`
+- `src/config.ts` — opt-in normalization and final integration ordering
+- `src/lib/og-cards.ts` — route matching, rendered-metadata extraction, rendering,
+  hashing, emission, and HTML patching
+- `assets/og-fonts/` — package-owned Inter v4.1 TTF assets, `LICENSE.txt`, and
+  provenance in `SOURCE.md`
+- `tests/og-cards.test.mjs` — precedence, routes, corpus/base, determinism, and
+  failure contracts
+
+## Reference implementation
+
+The package fixtures exercise all five presets, root and non-root bases, and a
+two-book corpus. A consumer needs no page source or runtime endpoint beyond the
+`seo.ogCards` opt-in shown above.

package/recipes/README.md

@@ -31,6 +31,7 @@ Terse pointers into canonical code for the most common book-authoring workflows.
 | 23 | [Interactive demo substrate](23-interactive-demo-substrate.md) | any | Opt-in Preact shell, slider, stat cards, theme colors, a11y, and reduced motion |
 | 24 | [Figure authoring standard](24-figure-authoring-standard.md) | any | Warm–Tol semantics, Okabe–Ito series, dual-theme exports, contrast, and accessible descriptions |
 | 25 | [QA and content readiness](25-qa-readiness.md) | any | Stable human/JSON readiness verdicts, corpus selection, CI, and `guide_qa.yaml` |
+| 26 | [Build-time Open Graph cards](26-generated-og-cards.md) | any | Opt-in deterministic 1200×630 cards, precedence, exclusions, corpus identity, and base-safe URLs |
 
 ## How to read recipes