@softure-ai/blog 0.0.0-stage → 0.1.5

package/src/index.ts

@@ -0,0 +1,99 @@
+// Public API of @softure-ai/blog: the module factory for softure.config.ts, its options, the content
+// contract and the tables. Parsing article files, the store, the publish run and the read functions
+// are in `@softure-ai/blog/server`, the `softure-blog` command in `/cli`.
+import { defineModule, resolveMigrationsDir } from "@softure-ai/core";
+import { blogMessages } from "./messages/index.js";
+import { BLOG_REFRESH_RATE_LIMIT_BUCKET, BLOG_REFRESH_SECRET_ENV } from "./discovery/refresh.js";
+import { blogOptionsSchema } from "./options.js";
+import { checkArticlesTable } from "./server/health.js";
+
+export const MODULE_ID = "blog";
+
+/**
+ * The rate limit bucket of the cache refresh route (`refreshBlogCache`), to spread into
+ * `security({ buckets })`: requests per client address, counted before the secret is checked. A
+ * publish sends one; the limit leaves room for a few retries and stops guessing.
+ */
+export const BLOG_RATE_LIMIT_BUCKETS = {
+  [BLOG_REFRESH_RATE_LIMIT_BUCKET]: { limit: 10, windowMinutes: 15 },
+} as const;
+
+/**
+ * Enables the blog in `softure.config.ts`: `blog()`, or with options
+ * `blog({ brand: { name: "Example" }, methodPage: true, fields: z.object({ scenario: z.string().optional() }) })`.
+ * Pages mount under `routes` (`index` `/blog`, `glossary` `/blog/glossary`, `method` `/blog/how-we-write`,
+ * `rss` `/blog/rss.xml`). With `seo()` listed too, `blogSitemap()` feeds its sitemap and a publish pings IndexNow.
+ * With `security()` listed and `refreshBlogCache` mounted at `refresh` (`/api/blog/refresh`), a publish from
+ * the command refreshes the running app's cache.
+ */
+export const blog = defineModule({
+  manifest: {
+    id: MODULE_ID,
+    version: "0.1.5",
+    // seo is optional: with it the sitemap lists the texts and a publish pings IndexNow. security is
+    // optional too: only the cache refresh route needs it, for its rate limit.
+    dependsOn: { seo: "^0.1.0?", security: "^0.1.0?" },
+    dbSchema: "blog",
+    tables: ["articles", "slug_history"],
+    env: [
+      {
+        name: BLOG_REFRESH_SECRET_ENV,
+        required: false,
+        description:
+          "Shared secret (at least 32 characters) of the cache refresh route refreshBlogCache, set for the running app and for softure-blog publish; without it a publish shows after revalidateSeconds.",
+      },
+    ],
+    switches: [],
+    routes: { index: "/blog", glossary: "/blog/glossary", method: "/blog/how-we-write", rss: "/blog/rss.xml", refresh: "/api/blog/refresh" },
+    mount: [
+      { kind: "page", path: "app/blog/page.tsx", export: "BlogIndexPage" },
+      { kind: "page", path: "app/blog/[slug]/page.tsx", export: "BlogArticlePage" },
+      { kind: "route-handler", path: "app/blog/[slug]/opengraph-image.tsx", export: "BlogArticleOgImage" },
+      { kind: "page", path: "app/blog/glossary/page.tsx", export: "GlossaryIndexPage" },
+      { kind: "page", path: "app/blog/glossary/[slug]/page.tsx", export: "GlossaryTermPage" },
+      { kind: "page", path: "app/blog/how-we-write/page.tsx", export: "BlogMethodPage" },
+      { kind: "route-handler", path: "app/blog/rss.xml/route.ts", export: "serveBlogRss" },
+      { kind: "route-handler", path: "app/api/blog/refresh/route.ts", export: "refreshBlogCache" },
+      { kind: "middleware", path: "proxy.ts", export: "createBlogRedirects" },
+    ],
+    privacy: { exports: false, deletes: false },
+  },
+  messages: blogMessages,
+  options: blogOptionsSchema,
+  migrations: { dir: resolveMigrationsDir(import.meta.url, "../migrations/") },
+  health: checkArticlesTable,
+});
+
+export {
+  BLOG_ARTICLE_KINDS,
+  BLOG_ARTICLE_STATUSES,
+  type BlogArticle,
+  type BlogArticleContent,
+  type BlogArticleInput,
+  type BlogArticleKind,
+  type BlogArticleState,
+  type BlogArticleStatus,
+  type BlogFaqEntry,
+  type BlogFields,
+  type BlogPublishAction,
+  type BlogPublishResult,
+  type BlogSlugErrorCode,
+  type BlogSource,
+} from "./contract.js";
+export { blogMessages, type BlogMessages } from "./messages/index.js";
+export {
+  DEFAULT_CONTENT_DIR,
+  DEFAULT_REVALIDATE_SECONDS,
+  FRONTMATTER_KEYS,
+  type BlogFieldsParseResult,
+  type BlogFieldsSchema,
+  type BlogOptions,
+  type BlogOptionsInput,
+  type BlogSkillSection,
+  type LocalizedText,
+} from "./options.js";
+export { articles, blogSchema, slugHistory } from "./db/schema.js";
+export type { BlogSitemapEntry } from "./discovery/sitemap.js";
+export { blogSitemap, readBlogSitemap } from "./sitemap.js";
+/** Builds a voice phrase for `blog({ quality: { voice: { phrases } } })` in the config. */
+export { wordPattern } from "./quality/text.js";

package/src/messages/en.ts

@@ -0,0 +1,82 @@
+export const en = {
+  kinds: {
+    article: "Article",
+    term: "Glossary term",
+  },
+  statuses: {
+    draft: "Draft",
+    published: "Published",
+    withdrawn: "Withdrawn",
+  },
+  render: {
+    footnotesHeading: "Notes",
+    /** `{number}`: the footnote number. */
+    footnoteLabel: "Footnote {number}",
+    backToText: "Back to text",
+    opensInNewTab: "(opens in a new tab)",
+    tableOfContents: "Contents",
+  },
+  pages: {
+    blogTitle: "Blog",
+    blogDescription: "Articles that explain the topic step by step, with sources and the day the facts were checked.",
+    /** A page title with the brand: `{title}` the page, `{brand}` the site. */
+    titleWithBrand: "{title} | {brand}",
+    empty: "The first texts are on their way.",
+    otherCluster: "Other texts",
+    startHere: "Start here",
+    /** `{minutes}`: whole minutes, at least 1 ("min" does not inflect, so no plural forms). */
+    readingTime: "{minutes} min read",
+    /** `{date}`: the day of the last change, on a card. */
+    updatedOn: "Updated {date}",
+    breadcrumbs: "Breadcrumbs",
+    published: "Published",
+    updated: "Updated",
+    currentAsOf: "Current as of",
+    readingTimeLabel: "Reading time",
+    contents: "In this text",
+    summary: "In short",
+    faq: "Questions and answers",
+    sources: "Sources",
+    /** `{brand}`: the site's name; shown only when the app sets a brand. */
+    signature: "{brand} editorial team",
+    methodLink: "How our texts are made",
+    disclaimerLabel: "Disclaimer",
+    glossaryLink: "Glossary",
+    glossaryTeaser: "short definitions of the terms the texts use.",
+    readNext: "Read next",
+  },
+  glossary: {
+    title: "Glossary",
+    description: "Short definitions of the terms the texts use, each with the day it was checked and its sources.",
+    empty: "The first definitions are on their way.",
+    explainedIn: "Explained in these texts",
+    allTerms: "All terms",
+  },
+  method: {
+    title: "How our texts are made",
+    description: "Who writes the texts, where the facts come from and what is checked before a text is published.",
+    whoTitle: "Who writes",
+    whoBody: "The editorial team chooses every topic and signs every text with the site's name.",
+    factsTitle: "Where the facts come from",
+    factsBody: "Every number comes from a source listed under the text or from a calculation the text shows. Each text says on which day its facts were checked.",
+    sourcesTitle: "Sources",
+    sourcesBody: "We cite laws, official statistics and primary documents first, and link every source so you can check it yourself.",
+    checksTitle: "Checks before publishing",
+    checksBody: "Before a text goes live, automatic checks look at its structure, its links and its sources. A text that fails them is not published.",
+    correctionsTitle: "Corrections",
+    correctionsBody: "When a fact changes, we update the text and its date. A text that can no longer be corrected is withdrawn.",
+  },
+  gone: {
+    title: "Text withdrawn",
+    heading: "This text has been withdrawn",
+    body: "We took it down because it was no longer current or correct.",
+    link: "See the other texts on the blog",
+  },
+  feed: {
+    /** The plain-text body of a 503 when the texts cannot be read. */
+    unavailable: "The feed is unavailable for a moment. Try again in a few minutes.",
+  },
+  og: {
+    alt: "An article from the blog",
+  },
+};

package/src/messages/index.ts

@@ -0,0 +1,7 @@
+import { en } from "./en.js";
+import { pl } from "./pl.js";
+
+export type BlogMessages = typeof en;
+
+/** Complete default dictionaries; apps pass partial overrides per locale. */
+export const blogMessages = { en, pl };

package/src/messages/pl.ts

@@ -0,0 +1,77 @@
+export const pl = {
+  kinds: {
+    article: "Artykuł",
+    term: "Pojęcie w słowniku",
+  },
+  statuses: {
+    draft: "Szkic",
+    published: "Opublikowany",
+    withdrawn: "Wycofany",
+  },
+  render: {
+    footnotesHeading: "Przypisy",
+    footnoteLabel: "Przypis {number}",
+    backToText: "Wróć do tekstu",
+    opensInNewTab: "(otwiera się w nowej karcie)",
+    tableOfContents: "Spis treści",
+  },
+  pages: {
+    blogTitle: "Blog",
+    blogDescription: "Teksty, które wyjaśniają temat krok po kroku, ze źródłami i datą sprawdzenia faktów.",
+    titleWithBrand: "{title} | {brand}",
+    empty: "Pierwsze teksty są w drodze.",
+    otherCluster: "Pozostałe teksty",
+    startHere: "Od tego zacznij",
+    readingTime: "{minutes} min czytania",
+    updatedOn: "Zaktualizowano {date}",
+    breadcrumbs: "Okruszki",
+    published: "Opublikowano",
+    updated: "Zaktualizowano",
+    currentAsOf: "Aktualne na",
+    readingTimeLabel: "Czas czytania",
+    contents: "W tym tekście",
+    summary: "W skrócie",
+    faq: "Pytania i odpowiedzi",
+    sources: "Źródła",
+    signature: "Redakcja {brand}",
+    methodLink: "Jak powstają teksty",
+    disclaimerLabel: "Zastrzeżenie",
+    glossaryLink: "Słownik pojęć",
+    glossaryTeaser: "krótkie definicje pojęć, których używają teksty.",
+    readNext: "Przeczytaj też",
+  },
+  glossary: {
+    title: "Słownik pojęć",
+    description: "Krótkie definicje pojęć, których używają teksty, każda z datą sprawdzenia i źródłami.",
+    empty: "Pierwsze definicje są w drodze.",
+    explainedIn: "Rozwijamy w tekstach",
+    allTerms: "Wszystkie pojęcia",
+  },
+  method: {
+    title: "Jak powstają teksty",
+    description: "Kto pisze teksty, skąd biorą się fakty i co sprawdzamy, zanim tekst zostanie opublikowany.",
+    whoTitle: "Kto pisze",
+    whoBody: "Redakcja wybiera każdy temat i podpisuje każdy tekst nazwą serwisu.",
+    factsTitle: "Skąd fakty",
+    factsBody: "Każda liczba pochodzi ze źródła podanego pod tekstem albo z wyliczenia, które tekst pokazuje. Każdy tekst podaje dzień, w którym sprawdziliśmy fakty.",
+    sourcesTitle: "Źródła",
+    sourcesBody: "Cytujemy najpierw przepisy, oficjalne statystyki i dokumenty źródłowe, a każde źródło linkujemy, żebyś mógł je sprawdzić sam.",
+    checksTitle: "Sprawdzenie przed publikacją",
+    checksBody: "Zanim tekst trafi na stronę, automatyczne testy sprawdzają jego strukturę, linki i źródła. Tekst, który ich nie przejdzie, nie zostanie opublikowany.",
+    correctionsTitle: "Poprawki",
+    correctionsBody: "Gdy fakt się zmienia, aktualizujemy tekst i jego datę. Tekst, którego nie da się już poprawić, wycofujemy.",
+  },
+  gone: {
+    title: "Tekst wycofany",
+    heading: "Ten tekst został wycofany",
+    body: "Zdjęliśmy go, bo przestał być aktualny albo poprawny.",
+    link: "Zobacz pozostałe teksty na blogu",
+  },
+  feed: {
+    /** The plain-text body of a 503 when the texts cannot be read. */
+    unavailable: "Kanał jest chwilowo niedostępny. Spróbuj ponownie za kilka minut.",
+  },
+  og: {
+    alt: "Artykuł z bloga",
+  },
+};

package/src/next/context.ts

@@ -0,0 +1,30 @@
+// What the adapter hands the store: the registered config, the process-wide database handle and the
+// wall clock; and what it hands the components: the copy, paths, brand and disclaimer.
+import { systemClock, type SoftureConfig } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { getSharedDatabase } from "@softure-ai/db";
+import type { BlogContext } from "../db/articles.js";
+import { getBlogMessages, getBlogOptions, getBlogRoutes } from "../server/options.js";
+import type { BlogPageContext } from "../ui/page-context.js";
+
+export async function getBlogContext(config: SoftureConfig = getSoftureConfig()): Promise<BlogContext> {
+  if (config.database === null) {
+    // Unreachable for a validated config: the module has a database schema.
+    throw new Error("@softure-ai/blog: softure.config.ts has no database; the blog needs one");
+  }
+  const { db } = await getSharedDatabase(config.database.url);
+  return { db, clock: systemClock, config };
+}
+
+export function getPageContext(config: SoftureConfig): BlogPageContext {
+  const options = getBlogOptions(config);
+  const routes = getBlogRoutes(config);
+  return {
+    messages: getBlogMessages(config),
+    locale: config.locale,
+    routes,
+    methodPath: options.methodPage ? routes.method : null,
+    brand: options.brand?.name ?? null,
+    disclaimer: options.disclaimer === undefined ? null : (options.disclaimer[config.locale] ?? options.disclaimer.en),
+  };
+}

package/src/next/data.ts

@@ -0,0 +1,55 @@
+// The pages' reads through Next's data cache: one query per key per `revalidateSeconds`, shared by the
+// listing, the glossary and the metadata of a request. The listing and the glossary index render on
+// every request (a build has no database), so without the cache every view would cost a query.
+import type { SoftureConfig } from "@softure-ai/core";
+import { unstable_cache } from "next/cache";
+import type { BlogArticle } from "../contract.js";
+import { findArticleBySlug, listArticles } from "../db/articles.js";
+import { getBlogOptions } from "../server/options.js";
+import { getBlogContext } from "./context.js";
+
+/** The tag of every cached read: `revalidateTag("softure-blog", { expire: 0 })` refreshes the blog at once (`refreshBlogCache`). */
+export const BLOG_CACHE_TAG = "softure-blog";
+
+interface CachedReads {
+  readonly published: () => Promise<BlogArticle[]>;
+  readonly bySlug: (slug: string) => Promise<BlogArticle | null>;
+}
+
+/**
+ * The cache keeps JSON, so a `Date` comes back as a string: revive them, or every page served from
+ * the cache would fail on its dates (FIRE's bug, kept fixed).
+ */
+function reviveDates(article: BlogArticle): BlogArticle {
+  const toDate = (value: Date | string | null) => (value === null ? null : new Date(value));
+  return { ...article, publishedAt: toDate(article.publishedAt), updatedAt: toDate(article.updatedAt), createdAt: new Date(article.createdAt) };
+}
+
+let reads: { readonly config: SoftureConfig; readonly value: CachedReads } | null = null;
+
+function getCachedReads(config: SoftureConfig): CachedReads {
+  if (reads?.config === config) return reads.value;
+  const options = { revalidate: getBlogOptions(config).revalidateSeconds, tags: [BLOG_CACHE_TAG] };
+  const value: CachedReads = {
+    published: unstable_cache(async () => listArticles(await getBlogContext(config)), ["softure-blog", "published"], options),
+    bySlug: unstable_cache(async (slug: string) => findArticleBySlug(await getBlogContext(config), slug), ["softure-blog", "by-slug"], options),
+  };
+  reads = { config, value };
+  return value;
+}
+
+/** Published articles (not terms), newest first. */
+export async function getPublishedArticles(config: SoftureConfig): Promise<BlogArticle[]> {
+  return (await getCachedReads(config).published()).filter((text) => text.kind === "article").map(reviveDates);
+}
+
+/** Published glossary terms, in the store's order (pages sort them). */
+export async function getPublishedTerms(config: SoftureConfig): Promise<BlogArticle[]> {
+  return (await getCachedReads(config).published()).filter((text) => text.kind === "term").map(reviveDates);
+}
+
+/** The row under a slug in any status: the page decides what to show. */
+export async function getTextBySlug(config: SoftureConfig, slug: string): Promise<BlogArticle | null> {
+  const text = await getCachedReads(config).bySlug(slug);
+  return text === null ? null : reviveDates(text);
+}

package/src/next/discovery.ts

@@ -0,0 +1,49 @@
+// The blog's RSS feed route in Next, over the cached reads of `data.ts` (one query per
+// `revalidateSeconds`). The sitemap contributor is `blogSitemap()` of the root entry (`../sitemap.ts`).
+//
+//   app/blog/rss.xml/route.ts   export { serveBlogRss as GET } from "@softure-ai/blog/next";
+//                               export const dynamic = "force-dynamic";
+import { errorLogLabel, formatMessage, getSiteUrls } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { buildBlogRss } from "../discovery/rss.js";
+import { getClusterLabel } from "../pages/listing.js";
+import { getBlogOptions } from "../server/options.js";
+import { getPageContext } from "./context.js";
+import { getPublishedArticles, getPublishedTerms } from "./data.js";
+
+/** Seconds a feed reader should wait after a 503: the cache's own lifetime is a fair guess. */
+const RETRY_AFTER_SECONDS = 300;
+
+/**
+ * `GET <routes.rss>`: the RSS 2.0 feed of the published articles and terms. A failed read answers
+ * **503**, never an empty feed: a reader that got a feed without items could take the texts as deleted.
+ */
+export async function serveBlogRss(): Promise<Response> {
+  const config = getSoftureConfig();
+  const context = getPageContext(config);
+  try {
+    const [articles, terms] = await Promise.all([getPublishedArticles(config), getPublishedTerms(config)]);
+    const { clusters } = getBlogOptions(config);
+    const copy = context.messages;
+    const xml = buildBlogRss({
+      articles,
+      terms,
+      urls: getSiteUrls(config),
+      routes: context.routes,
+      feedPath: context.routes.rss,
+      channel: {
+        title: context.brand === null ? copy.pages.blogTitle : formatMessage(copy.pages.titleWithBrand, { title: copy.pages.blogTitle, brand: context.brand }),
+        description: copy.pages.blogDescription,
+        language: config.locale,
+      },
+      getCategory: (text) => (text.kind === "term" ? copy.glossary.title : text.cluster === null ? null : getClusterLabel(text.cluster, clusters, config.locale)),
+    });
+    return new Response(xml, { headers: { "content-type": "application/rss+xml; charset=utf-8" } });
+  } catch (error) {
+    console.error(`blog: the RSS feed could not read the texts: ${errorLogLabel(error)}`);
+    return new Response(context.messages.feed.unavailable, {
+      status: 503,
+      headers: { "content-type": "text/plain; charset=utf-8", "retry-after": String(RETRY_AFTER_SECONDS) },
+    });
+  }
+}

package/src/next/index.ts

@@ -0,0 +1,25 @@
+// The Next.js adapter of @softure-ai/blog: the pages, their metadata, the article's OG image, the RSS
+// feed, the cache refresh route and the cached reads (docs/02-module-standard.md §8).
+export { getBlogContext, getPageContext } from "./context.js";
+export { serveBlogRss } from "./discovery.js";
+export { refreshBlogCache } from "./refresh.js";
+export { BLOG_CACHE_TAG, getPublishedArticles, getPublishedTerms, getTextBySlug } from "./data.js";
+export { createOgFontLoader, loadBrandOgFonts, type OgFontLoaderOptions, type OgFontsResult } from "./og-fonts.js";
+export { BlogArticleOgImage, getOgColors, getOgFontFamily, OG_IMAGE_SIZE, renderArticleOgImage, type OgFont, type RenderArticleOgImageInput } from "./og-image.js";
+export type { OgFontSource, OgFontWeight } from "../options.js";
+export {
+  BlogArticlePage,
+  BlogIndexPage,
+  BlogMethodPage,
+  generateArticleMetadata,
+  generateBlogIndexMetadata,
+  generateBlogStaticParams,
+  generateGlossaryIndexMetadata,
+  generateMethodMetadata,
+  generateTermMetadata,
+  GlossaryIndexPage,
+  GlossaryTermPage,
+  type BlogArticlePageProps,
+  type BlogIndexPageProps,
+  type GlossaryTermPageProps,
+} from "./pages.js";

package/src/next/next-modules.d.ts

@@ -0,0 +1,15 @@
+// Next.js has no `exports` map, so NodeNext resolution (tsconfig.base.json) only finds `next/*.js`.
+// The code must still import the bare specifiers: Next's bundler aliases them per runtime, and the
+// `.js` form bypasses the alias (docs/02-module-standard.md §8, measured in @softure-ai/waitlist).
+// These declarations give the bare specifiers their types.
+declare module "next/cache" {
+  export * from "next/cache.js";
+}
+
+declare module "next/navigation" {
+  export * from "next/navigation.js";
+}
+
+declare module "next/og" {
+  export * from "next/og.js";
+}

package/src/next/og-fonts.ts

@@ -0,0 +1,14 @@
+// The brand's fonts for the article OG card (`blog({ brand: { fonts } })`): each source is read on the
+// first card and kept for the life of the process (the loader lives in `src/server/og-fonts.ts`, which
+// `softure-blog check` uses too).
+import type { OgFontSource } from "../options.js";
+import { createOgFontLoader, type OgFontsResult } from "../server/og-fonts.js";
+
+export { createOgFontLoader, type OgFontLoaderOptions, type OgFontsResult } from "../server/og-fonts.js";
+
+const loadFromApp = createOgFontLoader({ root: process.cwd() });
+
+/** The brand's fonts for the card, read from the app's root (where Next runs) and cached. */
+export function loadBrandOgFonts(fonts: readonly OgFontSource[]): Promise<OgFontsResult> {
+  return loadFromApp(fonts);
+}

package/src/next/og-image.tsx

@@ -0,0 +1,108 @@
+// The social card of an article (`opengraph-image`): its title on the brand's background, the brand's
+// name above and the blog's name below. Mount it in `app/blog/[slug]/opengraph-image.tsx`:
+//
+//   export { BlogArticleOgImage as default, generateBlogStaticParams as generateStaticParams } from "@softure-ai/blog/next";
+//   export const size = { width: 1200, height: 630 };
+//   export const contentType = "image/png";
+//   export const revalidate = 300;
+//
+// A slug that is not a published article gets the blog's own card, never a 404: a crawler that
+// fetched the page earlier would show an empty preview.
+//
+// The card writes in `blog({ brand: { fonts } })` when the app lists them (`next/og`'s default font
+// otherwise): each file is read on the first card and kept, and a file that cannot be read fails the
+// card with a message naming it. A path is read from the app's root on the Node.js runtime (the
+// route's default); a route moved to the edge runtime takes https URLs only.
+import { formatMessage, type SoftureConfig } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { DEFAULT_THEME } from "@softure-ai/ui";
+import { ImageResponse } from "next/og";
+import type { BlogOptions } from "../options.js";
+import type { OgFont } from "../server/og-fonts.js";
+import { getBlogOptions } from "../server/options.js";
+import { getPageContext } from "./context.js";
+import { getTextBySlug } from "./data.js";
+import { loadBrandOgFonts } from "./og-fonts.js";
+
+export type { OgFont } from "../server/og-fonts.js";
+
+/** The card's size: the 1.91:1 every network crops to. */
+export const OG_IMAGE_SIZE = { width: 1200, height: 630 } as const;
+
+
+export interface RenderArticleOgImageInput {
+  readonly title: string;
+  /** Under the title: the blog's name. */
+  readonly label: string;
+  readonly brand: BlogOptions["brand"];
+  /** Fonts for the card; `next/og`'s default font otherwise. */
+  readonly fonts?: readonly OgFont[];
+}
+
+/** The card's colours: the brand's, else the dark scheme of @softure-ai/ui's default theme. */
+export function getOgColors(brand: BlogOptions["brand"]): { background: string; foreground: string; accent: string } {
+  const dark = DEFAULT_THEME.dark;
+  return {
+    background: brand?.colors?.background ?? dark["color-background"],
+    foreground: brand?.colors?.foreground ?? dark["color-foreground"],
+    accent: brand?.colors?.accent ?? dark["color-accent-fill"],
+  };
+}
+
+/**
+ * The card's `font-family`: every family it is given, once each and in order, so a second family (a
+ * `latin-ext` subset file under its own name) draws the characters the first lacks.
+ */
+export function getOgFontFamily(fonts: readonly OgFont[]): string | undefined {
+  const names = [...new Set(fonts.map((font) => font.name))];
+  return names.length === 0 ? undefined : names.map((name) => JSON.stringify(name)).join(", ");
+}
+
+export function renderArticleOgImage({ title, label, brand, fonts }: RenderArticleOgImageInput): ImageResponse {
+  const colors = getOgColors(brand);
+  const fontFamily = getOgFontFamily(fonts ?? []);
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: "100%",
+          height: "100%",
+          display: "flex",
+          flexDirection: "column",
+          justifyContent: "space-between",
+          background: colors.background,
+          color: colors.foreground,
+          padding: "56px 72px 64px",
+          ...(fontFamily === undefined ? {} : { fontFamily }),
+        }}
+      >
+        <div style={{ display: "flex", fontSize: 34, fontWeight: 700 }}>{brand?.name ?? ""}</div>
+        <div style={{ display: "flex", fontSize: title.length > 60 ? 56 : 68, fontWeight: 700, lineHeight: 1.08 }}>{title}</div>
+        <div style={{ display: "flex", alignItems: "center", gap: 14, fontSize: 28 }}>
+          <div style={{ display: "flex", width: 12, height: 12, borderRadius: 2, background: colors.accent }} />
+          <div style={{ display: "flex" }}>{label}</div>
+        </div>
+      </div>
+    ),
+    { ...OG_IMAGE_SIZE, ...(fonts === undefined ? {} : { fonts: [...fonts] }) },
+  );
+}
+
+function getLabel(config: SoftureConfig): string {
+  const context = getPageContext(config);
+  const name = context.messages.pages.blogTitle;
+  return context.brand === null ? name : formatMessage(context.messages.pages.titleWithBrand, { title: name, brand: context.brand });
+}
+
+/** The default export of an article's `opengraph-image.tsx`. */
+export async function BlogArticleOgImage({ params }: { readonly params: Promise<{ readonly slug: string }> }): Promise<ImageResponse> {
+  const config = getSoftureConfig();
+  const { slug } = await params;
+  const article = await getTextBySlug(config, slug);
+  const isVisible = article !== null && article.status === "published" && article.kind === "article";
+  const label = getLabel(config);
+  const { brand } = getBlogOptions(config);
+  const fonts = await loadBrandOgFonts(brand?.fonts ?? []);
+  if (!fonts.ok) throw new Error(fonts.error);
+  return renderArticleOgImage({ title: isVisible ? article.title : label, label, brand, fonts: fonts.fonts.length === 0 ? undefined : fonts.fonts });
+}