@brandon_m_behring/book-scaffold-astro 5.1.0 → 5.2.0

package/CLAUDE.md

@@ -230,6 +230,25 @@ A consumer `public/_headers` wins unchanged. Use
 or `securityHeaders: false` when another layer owns all headers. Recipe 05 has
 the full precedence and customization contract.
 
+## Build-time Open Graph cards (v5.2, opt-in)
+
+Set `seo: { ogCards: true }` in `defineBookConfig` to generate deterministic
+1200×630 PNG social cards for eligible static HTML that has no authored image.
+The object form accepts `{ enabled?: boolean, exclude?: string[] }`; exclusions
+are base-relative exact routes or whole-segment globs (`*` crosses one segment,
+`**` crosses zero or more). Invalid patterns fail configuration.
+
+Rendered image precedence is page/layout `ogImage` (including chapter
+frontmatter `image`) → current corpus book manifest `image` → static
+`seo.ogImage` → generated card. Generation runs after every consumer
+integration and patches only missing OG/Twitter image tags. It writes
+content-addressed `_og/<hash>.png` assets using package-owned local fonts and
+no network request. Corpus pages retain their resolved book identity; corpus
+surfaces use corpus identity; metadata combines `site` and Astro `base`
+exactly once. A requested card that cannot render, write, or patch fails the
+build. See Recipe 26 before changing card metadata, exclusion matching,
+post-render ordering, or output paths.
+
 ## QA and content readiness
 
 Run `npm exec -- book-scaffold qa` after substantive content changes. It calls

package/README.md

@@ -89,6 +89,27 @@ security defaults. A consumer-owned `public/_headers` wins unchanged;
 and `securityHeaders.contentSecurityPolicy` replaces only the default CSP.
 See [Recipe 05](./recipes/05-deploy-cloudflare.md#default-security-headers).
 
+## Build-time Open Graph cards
+
+Social cards are an explicit, offline build feature:
+
+```ts
+seo: {
+  ogCards: true,
+  // or: { enabled: true, exclude: ['/print/', '/private/*/', '/archive/**'] }
+}
+```
+
+Eligible static pages without a page image, corpus-book manifest image, or
+static `seo.ogImage` receive a deterministic 1200×630 PNG at a
+content-addressed `_og/<hash>.png` URL. Exact exclusions, one-segment `*`, and
+cross-segment `**` are matched after Astro-base normalization. Package-owned
+local fonts keep generation network-free; corpus identity and `site`/`base`
+are applied exactly once. Requested-card failures fail the build instead of
+emitting broken metadata. See
+[Recipe 26](./recipes/26-generated-og-cards.md) for precedence, exclusion
+grammar, output, and verification.
+
 ## Interactive demos
 
 The opt-in `@brandon_m_behring/book-scaffold-astro/demo` entry exports

package/assets/og-fonts/LICENSE.txt

@@ -0,0 +1,89 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The fonts,
+including any derivative works, can be bundled, embedded, redistributed
+and/or sold with any software provided that any reserved names are not used
+by derivative works. The fonts and derivatives, however, cannot be released
+under any other type of license. The requirement for fonts to remain under
+this license does not apply to any document created using the fonts or their
+derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may include
+source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting, or
+substituting -- in part or in whole -- any of the components of the Original
+Version, by changing formats or by porting the Font Software to a new
+environment.
+
+"Author" refers to any designer, engineer, programmer, technical writer or
+other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the Font Software, to use, study, copy, merge, embed, modify, redistribute,
+and sell modified and unmodified copies of the Font Software, subject to the
+following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy contains
+the above copyright notice and this license. These can be included either as
+stand-alone text files, human-readable headers or in the appropriate
+machine-readable metadata fields within text or binary files as long as
+those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font Name(s)
+unless explicit written permission is granted by the corresponding Copyright
+Holder. This restriction only applies to the primary font name as presented
+to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any Modified
+Version, except to acknowledge the contribution(s) of the Copyright Holder(s)
+and the Author(s) or with their explicit written permission.
+
+5) The Font Software, modified or unmodified, in part or in whole, must be
+distributed entirely under this license, and must not be distributed under
+any other license. The requirement for fonts to remain under this license
+does not apply to any document created using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are not
+met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL,
+INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE
+THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/og-fonts/SOURCE.md

@@ -0,0 +1,13 @@
+# Inter font provenance
+
+The renderer vendors the unmodified static TTF files from the official Inter
+4.1 release. Builds never download a font or read a system font.
+
+- Release: <https://github.com/rsms/inter/releases/tag/v4.1>
+- Archive: <https://github.com/rsms/inter/releases/download/v4.1/Inter-4.1.zip>
+- Archive SHA-256: `9883fdd4a49d4fb66bd8177ba6625ef9a64aa45899767dde3d36aa425756b11e`
+- `extras/ttf/Inter-Regular.ttf` SHA-256: `40d692fce188e4471e2b3cba937be967878f631ad3ebbbdcd587687c7ebe0c82`
+- `extras/ttf/Inter-Bold.ttf` SHA-256: `288316099b1e0a47a4716d159098005eef7c0066921f34e3200393dbdb01947f`
+
+The adjacent `LICENSE.txt` is copied verbatim from that release (SIL Open Font
+License 1.1).

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration, MarkdownHeading } from 'astro';
-import { c as BookConfigOptions, h as BookScaffoldIntegrationOptions, d as BookCorpus, l as CorpusApparatusRoute, e as BookCorpusInput, m as CorpusBook, k as ChaptersRenderer, v as SiblingBooks, x as Style } from './types-D1QZgKMO.js';
-export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, f as BookPreset, g as BookProfile, i as BookSchemasOptions, C as CORPUS_APPARATUS_ROUTES, j as ChapterFor, n as CorpusBookInput, F as FreshnessAffordance, o as FrontmatterRouteConfig, N as NUMBER_STYLES, p as NumberStyle, P as PartKey, q as PartialRouteToggles, r as ProfileDefinition, R as ReleaseStatusConfig, s as RouteToggles, S as SecurityHeadersConfig, t as SiblingBookDescriptor, u as SiblingBookEntry, w as StatusBadge, y as StyleInput, V as VolatilityBadge, z as composeStyles, A as defineProfile, D as defineStyle, E as normalizeFrontmatterConfig, G as resolvePreset, H as resolveProfile } from './types-D1QZgKMO.js';
+import { c as BookConfigOptions, h as BookScaffoldIntegrationOptions, d as BookCorpus, l as CorpusApparatusRoute, e as BookCorpusInput, m as CorpusBook, k as ChaptersRenderer, v as SiblingBooks, x as Style } from './types-DjqMnwHw.js';
+export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, f as BookPreset, g as BookProfile, i as BookSchemasOptions, C as CORPUS_APPARATUS_ROUTES, j as ChapterFor, n as CorpusBookInput, F as FreshnessAffordance, o as FrontmatterRouteConfig, N as NUMBER_STYLES, p as NumberStyle, O as OgCardsConfig, P as PartKey, q as PartialRouteToggles, r as ProfileDefinition, R as ReleaseStatusConfig, s as RouteToggles, S as SecurityHeadersConfig, t as SiblingBookDescriptor, u as SiblingBookEntry, w as StatusBadge, y as StyleInput, V as VolatilityBadge, z as composeStyles, A as defineProfile, D as defineStyle, E as normalizeFrontmatterConfig, G as resolvePreset, H as resolveProfile } from './types-DjqMnwHw.js';
 import { E as volatilityLevels, c as academicParts, Q as Question } from './schemas-CKipJ5Ie.js';
 export { A as AcademicChapter, B as BloomLevel, C as CourseNotesChapter, G as GlossaryTerm, M as MinimalChapter, P as Provenance, a as QuestionType, R as ResearchPortfolioChapter, T as ToolsChapter, b as academicChapterSchema, d as bloomLevels, e as changeKinds, f as changelogSchema, g as chapterStatus, h as citationBackstops, i as courseNotesChapterSchema, j as glossarySchema, l as layoutModes, m as minimalChapterSchema, p as patternCategories, k as patternsSchema, n as provenanceObject, o as provenanceSchema, q as questionDifficulties, r as questionSchema, s as questionTypes, t as refineQuestion, u as refinedQuestionSchema, v as researchPortfolioChapterSchema, w as sourceTiers, x as sourceTiersResearch, y as sourcesSchema, z as toolSlugs, D as toolsChapterSchema } from './schemas-CKipJ5Ie.js';
 export { KIND_LABEL, ResolvedTheoremLabel, THEOREM_KINDS, TheoremKind, TheoremLabelProps, resolveTheoremNumber, theoremLabel } from './lib/theorem-label.js';