@ingram-tech/nk-blog 0.1.4 → 0.1.6

package/dist/render.d.ts

@@ -35,4 +35,16 @@ export declare function PostBody(props: {
     elements?: BlogElements;
     bespoke?: BespokeComponents;
 }): Promise<ReactElement>;
+/**
+ * The hardened JSON-LD script tag, re-exported from nk-seo so it sits with the
+ * node builders that feed it (`blogPostArticle`, `blogPostBreadcrumbs`).
+ *
+ * nk-blog hands sites schema *nodes* and left rendering to them, which meant
+ * every site hand-rolled `<script type="application/ld+json"
+ * dangerouslySetInnerHTML={{ __html: JSON.stringify(nodes) }} />` — and a post
+ * title or FAQ answer containing `</script>` then closes the tag and injects
+ * markup into the page. `JsonLd` escapes `<`, so the safe path is now the one
+ * already in reach.
+ */
+export { JsonLd, serializeJsonLd } from "@ingram-tech/nk-seo/components";
 //# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAiB,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAG3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,YAAY,EACX,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACnB,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC;AAGtC,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;AAErE,0EAA0E;AAC1E,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,YAAY,CAAC;CACxB,CAIA,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,YAAY,CAAC,CAcxB;AAED,wEAAwE;AACxE,wBAAsB,QAAQ,CAAC,KAAK,EAAE;IACrC,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC5B,GAAG,OAAO,CAAC,YAAY,CAAC,CAUxB"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAiB,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAG3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,YAAY,EACX,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACnB,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC;AAGtC,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;AAErE,0EAA0E;AAC1E,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,YAAY,CAAC;CACxB,CAIA,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,YAAY,CAAC,CAcxB;AAED,wEAAwE;AACxE,wBAAsB,QAAQ,CAAC,KAAK,EAAE;IACrC,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC5B,GAAG,OAAO,CAAC,YAAY,CAAC,CAUxB;AAED;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/render.js

@@ -39,4 +39,16 @@ export async function PostBody(props) {
         bespoke: props.bespoke,
     });
 }
+/**
+ * The hardened JSON-LD script tag, re-exported from nk-seo so it sits with the
+ * node builders that feed it (`blogPostArticle`, `blogPostBreadcrumbs`).
+ *
+ * nk-blog hands sites schema *nodes* and left rendering to them, which meant
+ * every site hand-rolled `<script type="application/ld+json"
+ * dangerouslySetInnerHTML={{ __html: JSON.stringify(nodes) }} />` — and a post
+ * title or FAQ answer containing `</script>` then closes the tag and injects
+ * markup into the page. `JsonLd` escapes `<`, so the safe path is now the one
+ * already in reach.
+ */
+export { JsonLd, serializeJsonLd } from "@ingram-tech/nk-seo/components";
 //# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -1 +1 @@
-{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,KAAK,OAAO,MAAM,mBAAmB,CAAC;AAC7C,OAAO,QAA6B,MAAM,gBAAgB,CAAC;AAC3D,OAAO,SAAS,MAAM,YAAY,CAAC;AAGnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAiBxE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,YAAY,GAGpB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAC/B,KAAC,QAAQ,IAAC,aAAa,EAAE,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,QAAQ,YACxD,OAAO,GACE,CACX,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,KAM7B;IACA,0EAA0E;IAC1E,0EAA0E;IAC1E,gCAAgC;IAChC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;IAC/E,MAAM,KAAK,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;IACxD,MAAM,aAAa,GAAkB,OAAO;QAC3C,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,gBAAgB,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACf,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE;QAC7D,GAAG,OAAO;QACV,aAAa;KACb,CAAC,CAAC;IACH,OAAO,KAAC,UAAU,IAAC,UAAU,EAAE,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,GAAG,KAAK,EAAE,GAAI,CAAC;AACpE,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAK9B;IACA,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAChC,OAAO,KAAC,YAAY,IAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,GAAI,CAAC;IAChF,CAAC;IACD,OAAO,OAAO,CAAC;QACd,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO;QAC3B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;KACtB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,KAAK,OAAO,MAAM,mBAAmB,CAAC;AAC7C,OAAO,QAA6B,MAAM,gBAAgB,CAAC;AAC3D,OAAO,SAAS,MAAM,YAAY,CAAC;AAGnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAiBxE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,YAAY,GAGpB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAC/B,KAAC,QAAQ,IAAC,aAAa,EAAE,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,QAAQ,YACxD,OAAO,GACE,CACX,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,KAM7B;IACA,0EAA0E;IAC1E,0EAA0E;IAC1E,gCAAgC;IAChC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;IAC/E,MAAM,KAAK,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;IACxD,MAAM,aAAa,GAAkB,OAAO;QAC3C,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,gBAAgB,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACf,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE;QAC7D,GAAG,OAAO;QACV,aAAa;KACb,CAAC,CAAC;IACH,OAAO,KAAC,UAAU,IAAC,UAAU,EAAE,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,GAAG,KAAK,EAAE,GAAI,CAAC;AACpE,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAK9B;IACA,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAChC,OAAO,KAAC,YAAY,IAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,GAAI,CAAC;IAChF,CAAC;IACD,OAAO,OAAO,CAAC;QACd,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO;QAC3B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;KACtB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-blog",
-	"version": "0.1.4",
+	"version": "0.1.6",
 	"description": "File-based blog foundation for Next.js sites: frontmatter schema, build-time reader, limited-MDX rendering, a typed component contract with unstyled defaults, GitHub read/publish, and RSS.",
 	"license": "MIT",
 	"type": "module",
@@ -14,7 +14,10 @@
 	},
 	"sideEffects": false,
 	"files": [
-		"dist"
+		"dist",
+		"src",
+		"!src/**/*.test.ts",
+		"!src/**/*.test.tsx"
 	],
 	"exports": {
 		".": {
@@ -40,7 +43,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@ingram-tech/nk-seo": "^0.7.0",
+		"@ingram-tech/nk-seo": "^0.8.1",
 		"@mdx-js/mdx": "^3.1.1",
 		"gray-matter": "^4.0.3",
 		"react-markdown": "^10.1.0",
@@ -61,13 +64,13 @@
 		}
 	},
 	"devDependencies": {
-		"@ingram-tech/nk-dev": "0.10.0",
+		"@ingram-tech/nk-dev": "0.12.0",
 		"@types/mdast": "^4.0.4",
-		"@types/node": "^26.1.2",
+		"@types/node": "^26.2.0",
 		"@types/react": "^19.2.18",
 		"@types/react-dom": "^19.2.4",
 		"mdast-util-mdx-jsx": "^3.2.0",
-		"next": "^16.2.12",
+		"next": "^16.3.1",
 		"react": "^19.2.8",
 		"react-dom": "^19.2.8",
 		"typescript": "^7.0.2",

package/src/blog.ts

@@ -0,0 +1,170 @@
+import matter from "gray-matter";
+import { blogFrontmatterSchema } from "./schema.js";
+import { DEFAULT_WORDS_PER_MINUTE, readingTime } from "./reading-time.js";
+import type { BlogPost, BlogPostPreview, PostFormat } from "./types.js";
+
+/** A content file, named relative to the content dir ("slug.md", "slug/index.mdx"). */
+export interface RawPostFile {
+	name: string;
+	content: string;
+}
+
+export interface BlogSource {
+	load(): Promise<RawPostFile[]>;
+}
+
+export interface BlogConfig {
+	source: BlogSource;
+	/** Byline when a post declares none (each site sets its own). */
+	defaultAuthor?: string;
+	defaultCategory?: string;
+	wordsPerMinute?: number;
+	/** Include drafts (listing pages typically pass `NODE_ENV !== "production"`). */
+	drafts?: boolean;
+	/**
+	 * Site-specific image fallback (e.g. "look in /public/images/posts/<slug>").
+	 * This is config precisely so per-site divergence never forks the reader.
+	 */
+	resolveImage?: (post: { slug: string; image?: string }) => string | undefined;
+	/**
+	 * "throw" (default) fails the build on malformed frontmatter — a real post
+	 * silently missing from a site is worse than a red build. Remote sources
+	 * (admin listing over GitHub) prefer "skip" to keep one bad file from
+	 * hiding a whole target.
+	 */
+	onInvalid?: "throw" | "skip";
+}
+
+export interface Blog {
+	/** All non-draft posts, newest first, with bodies. */
+	posts(): Promise<BlogPost[]>;
+	/** All non-draft posts, newest first, without bodies. */
+	previews(): Promise<BlogPostPreview[]>;
+	post(slug: string): Promise<BlogPost | null>;
+	slugs(): Promise<string[]>;
+	/** The pinned (`featured: true`) post, else the newest. */
+	featured(): Promise<BlogPost | null>;
+}
+
+const POST_FILE = /^(?:(?<flat>[^/]+)|(?<dir>[^/]+)\/index)\.(?<ext>mdx?)$/;
+
+interface ParsedName {
+	slug: string;
+	format: PostFormat;
+	draftByName: boolean;
+}
+
+/** "slug.md", "slug.mdx", "slug/index.md(x)" → slug + format; else null. */
+export function parsePostFileName(name: string): ParsedName | null {
+	const match = POST_FILE.exec(name);
+	const groups = match?.groups;
+	if (!groups) return null;
+	const base = groups.flat ?? groups.dir;
+	if (!base) return null;
+	return {
+		slug: base.replace(/^_/, ""),
+		format: groups.ext === "mdx" ? "mdx" : "md",
+		// Legacy `_draft.md` convention, honored as an alias of `draft: true`.
+		draftByName: base.startsWith("_"),
+	};
+}
+
+export function parsePost(file: RawPostFile, config: BlogConfig): BlogPost | null {
+	const named = parsePostFileName(file.name);
+	if (!named) return null;
+
+	const { data, content } = matter(file.content);
+	const result = blogFrontmatterSchema.safeParse(data);
+	if (!result.success) {
+		if ((config.onInvalid ?? "throw") === "skip") {
+			console.warn(
+				`nk-blog: skipping ${file.name}: ${result.error.issues
+					.map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+					.join("; ")}`,
+			);
+			return null;
+		}
+		throw new Error(
+			`nk-blog: invalid frontmatter in ${file.name}: ${result.error.issues
+				.map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+				.join("; ")}`,
+		);
+	}
+
+	const frontmatter = result.data;
+	const slug = frontmatter.slug ?? named.slug;
+	const body = content.trim();
+	const authors = frontmatter.authors.length
+		? frontmatter.authors
+		: config.defaultAuthor
+			? [config.defaultAuthor]
+			: [];
+	const time = readingTime(body, config.wordsPerMinute ?? DEFAULT_WORDS_PER_MINUTE);
+	const image =
+		config.resolveImage?.({ slug, image: frontmatter.image }) ?? frontmatter.image;
+
+	return {
+		slug,
+		title: frontmatter.title,
+		seoTitle: frontmatter.seoTitle,
+		description: frontmatter.description,
+		date: frontmatter.date,
+		updated: frontmatter.updated,
+		authors,
+		author: authors[0] ?? "",
+		category: frontmatter.category ?? config.defaultCategory,
+		tags: frontmatter.tags,
+		image,
+		draft: frontmatter.draft || named.draftByName,
+		featured: frontmatter.featured,
+		lang: frontmatter.lang,
+		canonical: frontmatter.canonical,
+		format: named.format,
+		readingTimeMinutes: time.minutes,
+		readTime: time.text,
+		content: body,
+	};
+}
+
+export function createBlog(config: BlogConfig): Blog {
+	const posts = async (): Promise<BlogPost[]> => {
+		const files = await config.source.load();
+		const parsed = files
+			.map((file) => parsePost(file, config))
+			.filter((post): post is BlogPost => post !== null);
+
+		// Collision check BEFORE the draft filter: a draft colliding with a live
+		// post must fail the production build too, not only draft-enabled
+		// previews. Two files resolving to one slug is a routing conflict —
+		// always a loud build failure, never a quiet last-one-wins.
+		const seen = new Map<string, BlogPost>();
+		for (const post of parsed) {
+			if (seen.has(post.slug)) {
+				throw new Error(`nk-blog: duplicate slug "${post.slug}"`);
+			}
+			seen.set(post.slug, post);
+		}
+
+		return [...seen.values()]
+			.filter((post) => config.drafts === true || !post.draft)
+			.sort(
+				(a, b) =>
+					new Date(b.date).getTime() - new Date(a.date).getTime() ||
+					// Same-day posts: deterministic order between builds.
+					a.slug.localeCompare(b.slug),
+			);
+	};
+
+	return {
+		posts,
+		previews: async () =>
+			(await posts()).map(({ content: _content, ...preview }) => preview),
+		post: async (slug) =>
+			(await posts()).find((candidate) => candidate.slug === slug) ?? null,
+		slugs: async () => (await posts()).map((post) => post.slug),
+		featured: async () => {
+			const all = await posts();
+			return all.find((post) => post.featured) ?? all[0] ?? null;
+		},
+	};
+}

package/src/contract.ts

@@ -0,0 +1,97 @@
+import type { ComponentType, ReactNode } from "react";
+import { z } from "zod";
+
+/**
+ * The vocabulary manifest — the cross-site component contract.
+ *
+ * A Tier-1 post may reference exactly these components by bare name. The
+ * package owns the names and prop schemas; each site owns the pixels (see
+ * `@ingram-tech/nk-blog/unstyled` for the behavior-correct defaults). The
+ * admin publisher validates a post against this manifest (at the version the
+ * target site pins) before committing it.
+ */
+export const VOCABULARY = [
+	"Callout",
+	"Figure",
+	"YouTube",
+	"Tweet",
+	"NewsletterSubscribe",
+] as const;
+
+export type VocabularyName = (typeof VOCABULARY)[number];
+
+// MDX literal attributes arrive as strings (`width="1200"`), so dimension-ish
+// props coerce rather than demand numbers.
+const dimension = z.union([z.number(), z.string().regex(/^\d+$/)]);
+
+export const calloutProps = z.object({
+	variant: z.enum(["note", "tip", "warning", "important"]).default("note"),
+	title: z.string().optional(),
+});
+
+export const figureProps = z.object({
+	src: z.string().min(1),
+	alt: z.string(),
+	caption: z.string().optional(),
+	width: dimension.optional(),
+	height: dimension.optional(),
+});
+
+export const youTubeProps = z.object({
+	id: z.string().min(1),
+	title: z.string().optional(),
+	start: dimension.optional(),
+});
+
+export const tweetProps = z.object({
+	id: z.string().min(1),
+});
+
+export const newsletterSubscribeProps = z.object({
+	action: z.string().min(1),
+	placeholder: z.string().optional(),
+	buttonLabel: z.string().optional(),
+});
+
+/** Machine-checkable side of the contract, keyed by component name. */
+export const vocabularyProps = {
+	Callout: calloutProps,
+	Figure: figureProps,
+	YouTube: youTubeProps,
+	Tweet: tweetProps,
+	NewsletterSubscribe: newsletterSubscribeProps,
+} satisfies Record<VocabularyName, z.ZodType>;
+
+// React-facing prop types: the schema's input shape plus children/className,
+// which Zod does not model.
+type WithReactExtras<T> = T & { children?: ReactNode; className?: string };
+
+export type CalloutProps = WithReactExtras<z.input<typeof calloutProps>>;
+export type FigureProps = WithReactExtras<z.input<typeof figureProps>>;
+export type YouTubeProps = WithReactExtras<z.input<typeof youTubeProps>>;
+export type TweetProps = WithReactExtras<z.input<typeof tweetProps>>;
+export type NewsletterSubscribeProps = WithReactExtras<
+	z.input<typeof newsletterSubscribeProps>
+>;
+
+export interface VocabularyPropsMap {
+	Callout: CalloutProps;
+	Figure: FigureProps;
+	YouTube: YouTubeProps;
+	Tweet: TweetProps;
+	NewsletterSubscribe: NewsletterSubscribeProps;
+}
+
+/**
+ * The exhaustive registry a site must provide. Exhaustiveness is the point:
+ * a site missing a vocabulary component fails `tsc`, so an admin-published
+ * post can never reference something a site cannot render.
+ */
+export type BlogComponents = {
+	[K in VocabularyName]: ComponentType<VocabularyPropsMap[K]>;
+};
+
+/** Identity helper — exists purely for inference and error locality. */
+export function defineBlogComponents(components: BlogComponents): BlogComponents {
+	return components;
+}

package/src/date.ts

@@ -0,0 +1,22 @@
+/**
+ * The one post-date formatter (one site shipped two of these). Defaults to the
+ * long-form English style every site currently renders: "April 30, 2026".
+ *
+ * Formats in UTC by default: post dates are normalized to UTC midnight, so a
+ * local-zone format would render the previous day anywhere west of UTC (and
+ * hydration-mismatch per viewer when used client-side). Pass `timeZone` in
+ * `options` to override.
+ */
+export function formatPostDate(
+	isoDate: string,
+	locale = "en",
+	options: Intl.DateTimeFormatOptions = {
+		year: "numeric",
+		month: "long",
+		day: "numeric",
+	},
+): string {
+	return new Intl.DateTimeFormat(locale, { timeZone: "UTC", ...options }).format(
+		new Date(isoDate),
+	);
+}

package/src/http.ts

@@ -0,0 +1,16 @@
+export function toErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export async function assertResponseOk(
+	response: Response,
+	message: string,
+): Promise<void> {
+	if (response.ok) return;
+	const body = await response.text().catch(() => "");
+	throw new Error(
+		`${message}: ${response.status} ${response.statusText}${
+			body ? ` — ${body.slice(0, 300)}` : ""
+		}`,
+	);
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// Root entry: the contract — schema, types, vocabulary manifest — plus pure
+// helpers. Importable anywhere (client, admin, route handlers); no fs, no
+// components, no MDX compiler. The reader/sources live at "./server", the
+// renderers at "./render", the default components at "./unstyled".
+export {
+	blogFrontmatterSchema,
+	type BlogFrontmatter,
+	type BlogFrontmatterInput,
+} from "./schema.js";
+export type { BlogPost, BlogPostPreview, PostFormat } from "./types.js";
+export {
+	VOCABULARY,
+	vocabularyProps,
+	defineBlogComponents,
+	calloutProps,
+	figureProps,
+	youTubeProps,
+	tweetProps,
+	newsletterSubscribeProps,
+	type BlogComponents,
+	type VocabularyName,
+	type VocabularyPropsMap,
+	type CalloutProps,
+	type FigureProps,
+	type YouTubeProps,
+	type TweetProps,
+	type NewsletterSubscribeProps,
+} from "./contract.js";
+export {
+	readingTime,
+	DEFAULT_WORDS_PER_MINUTE,
+	type ReadingTime,
+} from "./reading-time.js";
+export { formatPostDate } from "./date.js";
+export {
+	blogPostArticle,
+	blogPostBreadcrumbs,
+	postUrl,
+	type BlogSeoConfig,
+} from "./seo.js";

package/src/keys.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+/**
+ * Env contract. Only the GitHub source/publisher needs anything, and callers
+ * may inject the token directly instead — so everything here is optional.
+ */
+export const keys = () =>
+	z
+		.object({
+			GITHUB_TOKEN: z.string().min(1).optional(),
+		})
+		.parse(process.env);