@softure-ai/blog 0.0.0-stage → 0.1.5

package/src/next/pages.tsx

@@ -0,0 +1,251 @@
+// The blog's pages, ready to mount with one line each (docs/02-module-standard.md §8):
+//
+//   app/blog/page.tsx                  export { BlogIndexPage as default, generateBlogIndexMetadata as generateMetadata } from "@softure-ai/blog/next";
+//                                      export const dynamic = "force-dynamic";
+//   app/blog/[slug]/page.tsx           export { BlogArticlePage as default, generateArticleMetadata as generateMetadata, generateBlogStaticParams as generateStaticParams } from "@softure-ai/blog/next";
+//                                      export const revalidate = 300;
+//   app/blog/glossary/page.tsx         GlossaryIndexPage, generateGlossaryIndexMetadata; dynamic
+//   app/blog/glossary/[slug]/page.tsx  GlossaryTermPage, generateTermMetadata, generateBlogStaticParams; revalidate
+//   app/blog/how-we-write/page.tsx     BlogMethodPage, generateMethodMetadata (with `blog({ methodPage: true })`)
+//   app/blog/rss.xml/route.ts          serveBlogRss as GET; dynamic (see discovery.ts)
+//
+// Next reads `dynamic` and `revalidate` statically, so they stay literals in the app's files: the
+// listing and the glossary index render per request (a build has no database) over cached reads;
+// articles and terms render on their first request and are kept for `revalidate` seconds (ISR).
+// 301 and 410 are answered before the page by `@softure-ai/blog/proxy`; anything else that is not a
+// published text of the page's kind is a 404 here.
+import { formatMessage, getSiteUrls, type SoftureConfig } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+// `next/types.js`, not `next`: the root entry adds Next's globals (a read-only NODE_ENV) to every
+// program that includes this file.
+import type { Metadata } from "next/types.js";
+import { notFound } from "next/navigation";
+import type { ReactNode } from "react";
+import type { BlogArticle } from "../contract.js";
+import { getRelatedArticles } from "../discovery/related.js";
+import { findArticlesLinkingTerm, renderPageBody, type RenderPageBodyOptions } from "../pages/body.js";
+import { getArticleDates } from "../pages/dates.js";
+import { getArticleJsonLd, getGlossaryJsonLd, getTermJsonLd, serializeJsonLd, type JsonLdContext } from "../pages/json-ld.js";
+import { getArticleCrumbs, getClusterLabel, getTermCrumbs, groupByCluster, sortTerms, type CrumbLabels } from "../pages/listing.js";
+import { getArticlePath, getTermPath } from "../pages/paths.js";
+import { toGlossary } from "../render/glossary.js";
+import { getBlogOptions } from "../server/options.js";
+import { BlogArticleView } from "../ui/blog-article.js";
+import { GlossaryIndexView, GlossaryTermView } from "../ui/blog-glossary.js";
+import { BlogListingView } from "../ui/blog-listing.js";
+import { BlogMethodView } from "../ui/blog-method.js";
+import type { BlogPageContext } from "../ui/page-context.js";
+import { getPageContext } from "./context.js";
+import { getPublishedArticles, getPublishedTerms, getTextBySlug } from "./data.js";
+
+type SlugParams = Promise<{ readonly slug: string }>;
+
+export interface BlogIndexPageProps {
+  /** The app's call to action under the cards. */
+  readonly cta?: ReactNode;
+}
+
+export interface BlogArticlePageProps {
+  readonly params: SlugParams;
+  /** The app's call to action right after the text. */
+  readonly cta?: ReactNode;
+  /** The app's block under the article, e.g. `<Waitlist placement="blog" />`. */
+  readonly afterArticle?: ReactNode;
+}
+
+export interface GlossaryTermPageProps {
+  readonly params: SlugParams;
+  readonly cta?: ReactNode;
+}
+
+/** No page is built ahead: the build has no database. The first request renders a slug. */
+export function generateBlogStaticParams(): { slug: string }[] {
+  return [];
+}
+
+function isPublished(text: BlogArticle | null, kind: BlogArticle["kind"]): text is BlogArticle {
+  return text !== null && text.status === "published" && text.kind === kind;
+}
+
+function getCrumbLabels(config: SoftureConfig, context: BlogPageContext): CrumbLabels {
+  const clusters = getBlogOptions(config).clusters;
+  return {
+    blog: context.messages.pages.blogTitle,
+    glossary: context.messages.glossary.title,
+    cluster: (cluster) => getClusterLabel(cluster, clusters, config.locale),
+  };
+}
+
+function getJsonLdContext(config: SoftureConfig, context: BlogPageContext): JsonLdContext {
+  return { urls: getSiteUrls(config), routes: context.routes, locale: config.locale, timezone: config.timezone, brand: context.brand };
+}
+
+function getBodyOptions(config: SoftureConfig, context: BlogPageContext, terms: readonly BlogArticle[]): RenderPageBodyOptions {
+  const origins = [config.appOrigin, getSiteUrls(config).origin];
+  return { glossary: toGlossary(terms), routes: context.routes, options: getBlogOptions(config), origins, messages: context.messages };
+}
+
+function withBrand(title: string, context: BlogPageContext): string {
+  return context.brand === null ? title : formatMessage(context.messages.pages.titleWithBrand, { title, brand: context.brand });
+}
+
+/** A page's canonical URL: seo's host and trailing-slash rule when the app lists seo, else on `appOrigin`. */
+function getCanonicalUrl(config: SoftureConfig, path: string): string {
+  return getSiteUrls(config).getCanonicalUrl(path);
+}
+
+/** The feed link a reader finds in `<head>` (`<link rel="alternate" type="application/rss+xml">`); a file, so no trailing-slash rule. */
+function getFeedAlternates(config: SoftureConfig, context: BlogPageContext): NonNullable<Metadata["alternates"]>["types"] {
+  return { "application/rss+xml": [{ url: `${getSiteUrls(config).origin}${context.routes.rss}`, title: withBrand(context.messages.pages.blogTitle, context) }] };
+}
+
+/** Metadata of a page with a fixed path; an empty listing stays out of the index (thin content). */
+function getStaticMetadata(config: SoftureConfig, context: BlogPageContext, page: { title: string; description: string; path: string; isEmpty?: boolean; hasFeed?: boolean }): Metadata {
+  return {
+    title: withBrand(page.title, context),
+    description: page.description,
+    robots: { index: page.isEmpty !== true, follow: true },
+    alternates: { canonical: getCanonicalUrl(config, page.path), ...(page.hasFeed === true ? { types: getFeedAlternates(config, context) } : {}) },
+    openGraph: { type: "website", title: page.title, description: page.description, url: getCanonicalUrl(config, page.path), ...(context.brand === null ? {} : { siteName: context.brand }) },
+  };
+}
+
+function getTextMetadata(config: SoftureConfig, context: BlogPageContext, text: BlogArticle, path: string, options: { hasFeed?: boolean } = {}): Metadata {
+  const dates = getArticleDates(text, config.timezone);
+  const url = getCanonicalUrl(config, path);
+  return {
+    title: withBrand(text.title, context),
+    description: text.description,
+    robots: { index: true, follow: true },
+    alternates: { canonical: url, ...(options.hasFeed === true ? { types: getFeedAlternates(config, context) } : {}) },
+    openGraph: {
+      type: "article",
+      title: text.title,
+      description: text.description,
+      url,
+      locale: config.locale,
+      publishedTime: dates.published,
+      modifiedTime: dates.updated ?? dates.published,
+      ...(context.brand === null ? {} : { siteName: context.brand }),
+    },
+  };
+}
+
+export async function generateBlogIndexMetadata(): Promise<Metadata> {
+  const config = getSoftureConfig();
+  const context = getPageContext(config);
+  const articles = await getPublishedArticles(config);
+  const copy = context.messages.pages;
+  return getStaticMetadata(config, context, { title: copy.blogTitle, description: copy.blogDescription, path: context.routes.index, isEmpty: articles.length === 0, hasFeed: true });
+}
+
+/** The listing: cards grouped by cluster, the pillar first. Mount with `dynamic = "force-dynamic"`. */
+export async function BlogIndexPage({ cta }: BlogIndexPageProps = {}) {
+  const config = getSoftureConfig();
+  const context = getPageContext(config);
+  const labels = getCrumbLabels(config, context);
+  const [articles, terms] = await Promise.all([getPublishedArticles(config), getPublishedTerms(config)]);
+  const groups = groupByCluster(articles, labels.cluster, context.messages.pages.otherCluster);
+  return <BlogListingView context={context} groups={groups} termCount={terms.length} timezone={config.timezone} cta={cta} />;
+}
+
+export async function generateArticleMetadata({ params }: { readonly params: SlugParams }): Promise<Metadata> {
+  const config = getSoftureConfig();
+  const { slug } = await params;
+  const article = await getTextBySlug(config, slug);
+  if (!isPublished(article, "article")) return {};
+  const context = getPageContext(config);
+  return getTextMetadata(config, context, article, getArticlePath(context.routes, article.slug), { hasFeed: true });
+}
+
+/** An article with "read next" under it. Mount with `revalidate` and `generateBlogStaticParams`. */
+export async function BlogArticlePage({ params, cta, afterArticle }: BlogArticlePageProps) {
+  const config = getSoftureConfig();
+  const { slug } = await params;
+  const article = await getTextBySlug(config, slug);
+  if (!isPublished(article, "article")) notFound();
+  const context = getPageContext(config);
+  const [terms, published] = await Promise.all([getPublishedTerms(config), getPublishedArticles(config)]);
+  const body = renderPageBody<ReactNode>(article, getBodyOptions(config, context, terms));
+  const crumbs = getArticleCrumbs(article, context.routes, getCrumbLabels(config, context));
+  const jsonLd = serializeJsonLd(getArticleJsonLd(article, crumbs, getJsonLdContext(config, context)));
+  return (
+    <BlogArticleView
+      context={context}
+      article={article}
+      dates={getArticleDates(article, config.timezone)}
+      body={body}
+      crumbs={crumbs}
+      jsonLd={jsonLd}
+      cta={cta}
+      afterArticle={afterArticle}
+      related={getRelatedArticles(article, published)}
+    />
+  );
+}
+
+export async function generateGlossaryIndexMetadata(): Promise<Metadata> {
+  const config = getSoftureConfig();
+  const context = getPageContext(config);
+  const terms = await getPublishedTerms(config);
+  const copy = context.messages.glossary;
+  return getStaticMetadata(config, context, { title: copy.title, description: copy.description, path: context.routes.glossary, isEmpty: terms.length === 0 });
+}
+
+/** The glossary index. Mount with `dynamic = "force-dynamic"`. */
+export async function GlossaryIndexPage() {
+  const config = getSoftureConfig();
+  const context = getPageContext(config);
+  const terms = sortTerms(await getPublishedTerms(config), config.locale);
+  const jsonLd = terms.length === 0 ? null : serializeJsonLd(getGlossaryJsonLd(terms, getJsonLdContext(config, context), context.messages.glossary.title));
+  return <GlossaryIndexView context={context} terms={terms} jsonLd={jsonLd} />;
+}
+
+export async function generateTermMetadata({ params }: { readonly params: SlugParams }): Promise<Metadata> {
+  const config = getSoftureConfig();
+  const { slug } = await params;
+  const term = await getTextBySlug(config, slug);
+  if (!isPublished(term, "term")) return {};
+  const context = getPageContext(config);
+  return getTextMetadata(config, context, term, getTermPath(context.routes, term.slug));
+}
+
+/** A glossary term with the articles that expand on it. Mount with `revalidate` and `generateBlogStaticParams`. */
+export async function GlossaryTermPage({ params, cta }: GlossaryTermPageProps) {
+  const config = getSoftureConfig();
+  const { slug } = await params;
+  const term = await getTextBySlug(config, slug);
+  if (!isPublished(term, "term")) notFound();
+  const context = getPageContext(config);
+  const [terms, articles] = await Promise.all([getPublishedTerms(config), getPublishedArticles(config)]);
+  const bodyOptions = getBodyOptions(config, context, terms);
+  const crumbs = getTermCrumbs(term, context.routes, getCrumbLabels(config, context));
+  const jsonLd = serializeJsonLd(getTermJsonLd(term, crumbs, getJsonLdContext(config, context), context.messages.glossary.title));
+  return (
+    <GlossaryTermView
+      context={context}
+      term={term}
+      dates={getArticleDates(term, config.timezone)}
+      body={renderPageBody<ReactNode>(term, bodyOptions)}
+      crumbs={crumbs}
+      jsonLd={jsonLd}
+      articles={findArticlesLinkingTerm(articles, term.slug, bodyOptions)}
+      cta={cta}
+    />
+  );
+}
+
+export function generateMethodMetadata(): Metadata {
+  const config = getSoftureConfig();
+  const context = getPageContext(config);
+  const copy = context.messages.method;
+  return getStaticMetadata(config, context, { title: copy.title, description: copy.description, path: context.routes.method });
+}
+
+/** "How our texts are made". Mount it with `blog({ methodPage: true })`; without that it is a 404. */
+export function BlogMethodPage() {
+  const config = getSoftureConfig();
+  const context = getPageContext(config);
+  if (context.methodPath === null) notFound();
+  return <BlogMethodView context={context} />;
+}

package/src/next/refresh.ts

@@ -0,0 +1,85 @@
+// The cache refresh route: `softure-blog publish --commit` calls it so the running app shows the change
+// at once instead of after `revalidateSeconds`. Mount it in app/api/blog/refresh/route.ts:
+//
+//   export { refreshBlogCache as POST } from "@softure-ai/blog/next";
+//
+// The caller is the command, not a person: no session, so the route checks a Bearer secret from the
+// environment (BLOG_REFRESH_SECRET). Order, as in mcp-access: identify the client, count the
+// request, check the secret, then expire the tag. Each refusal happens before the next step costs
+// anything. security is an optional dependency of the blog, reached through a dynamic import.
+import { createHash, timingSafeEqual } from "node:crypto";
+import { errorLogLabel, getModule, type SoftureConfig } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { revalidateTag } from "next/cache";
+import { BLOG_REFRESH_RATE_LIMIT_BUCKET, BLOG_REFRESH_SECRET_ENV, MIN_REFRESH_SECRET_LENGTH } from "../discovery/refresh.js";
+import { getBlogContext } from "./context.js";
+import { BLOG_CACHE_TAG } from "./data.js";
+
+const SECURITY_MODULE_ID = "security";
+/**
+ * The one rate limit key of every caller `identifyClient` cannot place: the command often calls the
+ * app on a private name (`--app-url http://web:3000`), past the proxy that sets the client header.
+ */
+const UNIDENTIFIED_CLIENT_KEY = "unidentified";
+const BEARER_PREFIX = /^Bearer[ \t]+/i;
+const NO_STORE = { "cache-control": "no-store" };
+
+function answer(status: number, headers: Readonly<Record<string, string>> = {}): Response {
+  return new Response(null, { status, headers: { ...NO_STORE, ...headers } });
+}
+
+/**
+ * `POST <routes.refresh>`: expires every cached read of the blog, so the next request reads the
+ * tables again. Answers 204 refreshed, 401 for a missing or wrong secret, 429 over the `blog-refresh`
+ * bucket (per client address; callers without one share a single count), 503 when counting fails,
+ * 500 when the secret is not set or shorter than 32 characters. A missing security module or bucket
+ * is a setup error, thrown.
+ */
+export async function refreshBlogCache(request: Request): Promise<Response> {
+  const secret = (process.env[BLOG_REFRESH_SECRET_ENV] ?? "").trim();
+  if (secret.length < MIN_REFRESH_SECRET_LENGTH) {
+    console.error(`@softure-ai/blog: the cache refresh route needs ${BLOG_REFRESH_SECRET_ENV} of at least ${String(MIN_REFRESH_SECRET_LENGTH)} characters`);
+    return answer(500);
+  }
+  const config = getSoftureConfig();
+  assertRateLimitBucket(config);
+  const { consumeRateLimit, identifyClient } = await import("@softure-ai/security/server");
+
+  const client = identifyClient({ config }, request.headers);
+  let limit;
+  try {
+    // Counted before the secret is checked, so a flood of guesses is stopped first.
+    limit = await consumeRateLimit(await getBlogContext(config), { bucket: BLOG_REFRESH_RATE_LIMIT_BUCKET, key: client.ok ? client.value : UNIDENTIFIED_CLIENT_KEY });
+  } catch (error) {
+    // Fails closed and says nothing: the route is public and this runs before authentication.
+    console.error(`@softure-ai/blog: counting a cache refresh failed: ${errorLogLabel(error)}`);
+    return answer(503);
+  }
+  if (!limit.ok) return answer(429, { "retry-after": String(limit.retryAfterSeconds) });
+
+  if (!hasSecret(request.headers.get("authorization"), secret)) return answer(401, { "www-authenticate": "Bearer" });
+  // `expire: 0`: the next request waits for fresh reads. The "max" profile would serve the old page once more.
+  revalidateTag(BLOG_CACHE_TAG, { expire: 0 });
+  return answer(204);
+}
+
+/** Compares digests in constant time, so the answer time says nothing about the secret's length or prefix. */
+function hasSecret(header: string | null, secret: string): boolean {
+  if (header === null || !BEARER_PREFIX.test(header)) return false;
+  const given = createHash("sha256").update(header.replace(BEARER_PREFIX, "").trim()).digest();
+  return timingSafeEqual(given, createHash("sha256").update(secret).digest());
+}
+
+/** A missing module or bucket is a setup bug: thrown, so it reaches the log by name instead of a quiet 503. */
+function assertRateLimitBucket(config: SoftureConfig): void {
+  const security = getModule(config, SECURITY_MODULE_ID);
+  if (security === undefined) {
+    throw new Error("@softure-ai/blog: the cache refresh route is rate-limited by the security module; add security() to modules");
+  }
+  const options = security.options as { buckets?: Record<string, unknown> } | undefined;
+  if (options?.buckets?.[BLOG_REFRESH_RATE_LIMIT_BUCKET] === undefined) {
+    throw new Error(
+      `@softure-ai/blog: the security module has no "${BLOG_REFRESH_RATE_LIMIT_BUCKET}" bucket; spread BLOG_RATE_LIMIT_BUCKETS into security({ buckets })`,
+    );
+  }
+}

package/src/options.ts

@@ -0,0 +1,224 @@
+// The options an app passes to `blog({ ... })` in softure.config.ts, parsed at startup.
+import { z } from "zod";
+import { qualitySettingSchema } from "./quality/options.js";
+import type { ArticleImagePolicy } from "./render/images.js";
+import type { BlockPlugin } from "./render/render-article.js";
+
+/** Where the app keeps its article files unless a command names a path. */
+export const DEFAULT_CONTENT_DIR = "content/blog";
+
+/** The frontmatter keys of the module; the app's `fields` may not reuse them. */
+export const FRONTMATTER_KEYS = [
+  "id",
+  "slug",
+  "kind",
+  "cluster",
+  "pillar",
+  "title",
+  "description",
+  "summary",
+  "status",
+  "current_as_of",
+  "published_at",
+  "sources",
+  "faq",
+  "forms",
+] as const;
+
+/** What a schema's `safeParse` reports; zod 3 and 4 both fit. */
+export type BlogFieldsParseResult =
+  | { readonly success: true; readonly data: unknown }
+  | { readonly success: false; readonly error: { readonly issues: readonly { readonly path: readonly PropertyKey[]; readonly message: string }[] } };
+
+/**
+ * The app's own frontmatter fields: an object schema from the app's `zod`, e.g.
+ * `z.object({ scenario: z.string().optional() })`. Its keys join the frontmatter; the parsed value
+ * is stored with the article and enters its content hash. It must parse to plain JSON values.
+ */
+export interface BlogFieldsSchema {
+  readonly shape: Readonly<Record<string, unknown>>;
+  readonly safeParse: (value: unknown) => BlogFieldsParseResult;
+}
+
+const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+function isFieldsSchema(value: unknown): value is BlogFieldsSchema {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { shape?: unknown; safeParse?: unknown };
+  return typeof candidate.shape === "object" && candidate.shape !== null && typeof candidate.safeParse === "function";
+}
+
+function isBlockPlugin(value: unknown): value is BlockPlugin {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { type?: unknown; render?: unknown };
+  return typeof candidate.type === "string" && KEBAB.test(candidate.type) && typeof candidate.render === "function";
+}
+
+/** How long the pages cache their reads by default, in seconds; the app's `revalidate` should match. */
+export const DEFAULT_REVALIDATE_SECONDS = 300;
+
+/** Text the app writes per locale; `en` is the fallback for a locale it leaves out. */
+const localizedTextSchema = z.strictObject({
+  en: z.string().trim().min(1),
+  pl: z.string().trim().min(1).optional(),
+});
+
+export type LocalizedText = z.output<typeof localizedTextSchema>;
+
+const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+const colorSchema = z.string().regex(HEX_COLOR, "must be a six-digit hex colour, e.g. #0c0c0d");
+const HOSTNAME = /^(?=.{1,253}$)[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
+
+/** The weights Satori (`next/og`) draws: static fonts only, in steps of 100. */
+export const OG_FONT_WEIGHTS = [100, 200, 300, 400, 500, 600, 700, 800, 900] as const;
+
+export type OgFontWeight = (typeof OG_FONT_WEIGHTS)[number];
+
+const WOFF2 = /\.woff2$/i;
+
+/** The part of a font source that names the file: a URL's path, or the path as written. */
+function getSourceFileName(src: string): string {
+  return src.startsWith("https://") ? new URL(src).pathname : src;
+}
+
+function isFontSource(src: string): boolean {
+  if (src.startsWith("https://")) return URL.canParse(src);
+  return !/^[a-z][a-z0-9+.-]*:\/\//i.test(src);
+}
+
+const ogFontSchema = z.strictObject({
+  /** The family name the card writes in; a second file of one weight and style needs its own name. */
+  name: z.string().trim().min(1).max(80),
+  weight: z
+    .custom<OgFontWeight>((value) => OG_FONT_WEIGHTS.some((weight) => weight === value), "must be a weight from 100 to 900 in steps of 100")
+    .default(400),
+  style: z.enum(["normal", "italic"]).default("normal"),
+  /** A .ttf, .otf or .woff file: an https URL, an absolute path, or a path from the app's root. */
+  src: z
+    .string()
+    .trim()
+    .min(1)
+    .refine(isFontSource, "must be an https URL or a file path, e.g. fonts/inter-700.woff")
+    .refine((src) => !isFontSource(src) || !WOFF2.test(getSourceFileName(src)), "must be a .ttf, .otf or .woff file; the card cannot read .woff2"),
+});
+
+export type OgFontSource = z.output<typeof ogFontSchema>;
+
+const brandSchema = z.strictObject({
+  /** The site's name: in page titles, as the author and publisher in JSON-LD, on the OG card. */
+  name: z.string().trim().min(1).max(80),
+  /** The OG card's colours; each defaults to the dark scheme of @softure-ai/ui's default theme. */
+  colors: z
+    .strictObject({ background: colorSchema.optional(), foreground: colorSchema.optional(), accent: colorSchema.optional() })
+    .optional(),
+  /**
+   * The OG card's fonts, read by the card's route on its first render and kept for the life of the
+   * process; without them the card uses `next/og`'s default font.
+   */
+  fonts: z
+    .array(ogFontSchema)
+    .min(1, "must list at least one font")
+    .superRefine((fonts, ctx) => {
+      const seen = new Set<string>();
+      for (const [index, font] of fonts.entries()) {
+        const key = `"${font.name}" ${font.weight} ${font.style}`;
+        if (seen.has(key)) {
+          ctx.addIssue({ code: "custom", path: [index], message: `${key} is listed twice; give a second file its own name, e.g. "${font.name} Ext"` });
+        }
+        seen.add(key);
+      }
+    })
+    .optional(),
+});
+
+/** Whether a Markdown body holds a `#` or `##` heading outside fenced code. */
+function hasTopHeading(body: string): boolean {
+  let fence: string | null = null;
+  for (const line of body.split(/\r?\n/)) {
+    const trimmed = line.trimStart();
+    const marker = trimmed.startsWith("```") ? "```" : trimmed.startsWith("~~~") ? "~~~" : null;
+    if (marker !== null) fence = fence === null ? marker : fence === marker ? null : fence;
+    else if (fence === null && /^ {0,3}#{1,2}(?:[ \t]|$)/.test(line)) return true;
+  }
+  return false;
+}
+
+/** One section of the app's own in the writing skill: `## <title>` and the Markdown body, verbatim. */
+const skillSectionSchema = z.strictObject({
+  title: z
+    .string()
+    .trim()
+    .min(1)
+    .max(80)
+    .refine((title) => !/[\r\n]/.test(title), "must be one line"),
+  body: z
+    .string()
+    .trim()
+    .min(1)
+    .refine((body) => !hasTopHeading(body), "must not hold a # or ## heading; use ### and deeper (the title is the section's ## heading)"),
+});
+
+const skillSchema = z.strictObject({
+  /** The app's own sections (its numbers, block plugins, fields), written to `references/app.md` of the skill. */
+  sections: z.array(skillSectionSchema).superRefine((sections, ctx) => {
+    const seen = new Set<string>();
+    for (const [index, section] of sections.entries()) {
+      if (seen.has(section.title)) ctx.addIssue({ code: "custom", path: [index, "title"], message: `"${section.title}" is the title of another section` });
+      seen.add(section.title);
+    }
+  }).default([]),
+});
+
+export type BlogSkillSection = z.output<typeof skillSectionSchema>;
+
+const imagePolicySchema = z.strictObject({
+  /** Hosts whose https images are allowed besides the site's own paths (subdomains included). */
+  hosts: z.array(z.string().regex(HOSTNAME, "must be a host name, e.g. cdn.example.com")).readonly().default([]),
+  /** `(src) => ({ width, height })` in pixels, or `null` for an unknown image. */
+  dimensions: z.custom<ArticleImagePolicy["dimensions"]>((value) => typeof value === "function", "must be a function: (src) => ({ width, height }) or null"),
+});
+
+export const blogOptionsSchema = z
+  .strictObject({
+    /** The folder with the article files, relative to the app's root. */
+    contentDir: z.string().trim().min(1).default(DEFAULT_CONTENT_DIR),
+    /**
+     * Slugs taken by static pages under the blog's path (a glossary index, a method page). A static
+     * route wins over the article route, so an article with such a slug would be unreachable.
+     */
+    reservedSlugs: z.array(z.string().max(100).regex(KEBAB, "must be kebab-case, e.g. how-we-write")).default([]),
+    fields: z.custom<BlogFieldsSchema>(isFieldsSchema, "must be an object schema, e.g. z.object({ scenario: z.string() })").optional(),
+    /** The site's brand for titles, JSON-LD and the OG card; without it pages carry no brand. */
+    brand: brandSchema.optional(),
+    /** Whether the app mounts the "how our texts are made" page (`BlogMethodPage` at `routes.method`). */
+    methodPage: z.boolean().default(false),
+    /** A note under every text (not advice, not a recommendation…); none by default. */
+    disclaimer: localizedTextSchema.optional(),
+    /** Display names of clusters by key; a cluster without one shows its key with spaces. */
+    clusters: z.record(z.string().regex(KEBAB, "must be kebab-case, e.g. investing-basics"), localizedTextSchema).default({}),
+    /** Block plugins for the app's fenced blocks (`renderArticle({ blocks })`), used by the pages. */
+    blocks: z.array(z.custom<BlockPlugin>(isBlockPlugin, "must be a block plugin: { type: \"chart\", render(block) }")).default([]),
+    /** Hosts besides those of `appOrigin` and the canonical site origin (`getSiteUrls`) whose links are not marked external (subdomains included). */
+    siteHosts: z.array(z.string().regex(HOSTNAME, "must be a host name, e.g. example.com")).default([]),
+    /**
+     * Which images article bodies may show (`renderArticle({ images })`), used by the pages and the
+     * quality gate; without it every image renders as its alt text and the gate refuses it.
+     */
+    images: imagePolicySchema.optional(),
+    /** How long the listing and glossary cache their reads; keep it equal to the pages' `revalidate`. */
+    revalidateSeconds: z.number().int().min(1).default(DEFAULT_REVALIDATE_SECONDS),
+    /** The text quality gate (`softure-blog check`, and every publish); `false` turns it off. */
+    quality: qualitySettingSchema,
+    /** What `softure-blog skill install` adds to the generated writing skill. */
+    skill: skillSchema.default({ sections: [] }),
+  })
+  .superRefine((options, ctx) => {
+    for (const key of Object.keys(options.fields?.shape ?? {})) {
+      if ((FRONTMATTER_KEYS as readonly string[]).includes(key)) {
+        ctx.addIssue({ code: "custom", path: ["fields", key], message: `"${key}" is a frontmatter key of the module` });
+      }
+    }
+  });
+
+export type BlogOptionsInput = z.input<typeof blogOptionsSchema>;
+export type BlogOptions = z.output<typeof blogOptionsSchema>;

package/src/pages/body.ts

@@ -0,0 +1,38 @@
+// A stored text's body rendered for its page: the renderer with the app's glossary, block plugins,
+// hosts and image policy, and the module's copy. A term page passes the term itself, so it never links
+// to itself.
+import type { BlogArticle } from "../contract.js";
+import type { BlogMessages } from "../messages/index.js";
+import type { BlogOptions } from "../options.js";
+import type { GlossaryTerm } from "../render/glossary.js";
+import { renderArticle, type BlockPlugin, type RenderedArticle } from "../render/render-article.js";
+import { getTermPath, type BlogRoutes } from "./paths.js";
+
+export interface RenderPageBodyOptions {
+  readonly glossary: readonly GlossaryTerm[];
+  readonly routes: BlogRoutes;
+  readonly options: Pick<BlogOptions, "blocks" | "images" | "siteHosts">;
+  /** The app's own origins (`appOrigin` and the canonical site origin); their hosts are the site's (links to them are not external). */
+  readonly origins: readonly string[];
+  readonly messages: BlogMessages;
+}
+
+export function renderPageBody<TNode = unknown>(text: BlogArticle, input: RenderPageBodyOptions): RenderedArticle<TNode> {
+  return renderArticle<TNode>(text.bodyMarkdown, {
+    glossary: input.glossary,
+    ...(text.kind === "term" ? { selfSlug: text.slug } : {}),
+    termHref: (slug) => getTermPath(input.routes, slug),
+    siteHosts: [...input.origins.map((origin) => new URL(origin).hostname), ...input.options.siteHosts],
+    ...(input.options.images === undefined ? {} : { images: input.options.images }),
+    // The options keep plugins untyped (`unknown` nodes); the pages render React nodes, the type the
+    // app's plugins return.
+    blocks: input.options.blocks as readonly BlockPlugin<TNode>[],
+    article: { currentAsOf: text.currentAsOf, fields: text.fields },
+    messages: input.messages.render,
+  });
+}
+
+/** Published articles whose body links the term, by hand or by its first mention: the same rule as the links. */
+export function findArticlesLinkingTerm(articles: readonly BlogArticle[], termSlug: string, input: RenderPageBodyOptions): BlogArticle[] {
+  return articles.filter((article) => renderPageBody(article, input).linkedTerms.includes(termSlug));
+}

package/src/pages/dates.ts

@@ -0,0 +1,39 @@
+// The days a page shows for a text, in the app's time zone. JSON-LD takes the same days, so the dates
+// a search engine compares (`dateModified` against the visible update) cannot drift apart.
+import type { Locale } from "@softure-ai/core";
+import type { BlogArticle } from "../contract.js";
+
+export interface ArticleDates {
+  /** The day of first publication, `YYYY-MM-DD`. */
+  readonly published: string;
+  /** The day of the last content change; `null` without one, or when it falls on the publication day. */
+  readonly updated: string | null;
+  /** The day the facts were checked, `YYYY-MM-DD`. */
+  readonly currentAsOf: string;
+}
+
+/** The calendar day of a moment in a time zone, `YYYY-MM-DD`. */
+export function getDayInZone(moment: Date, timezone: string): string {
+  // `en-CA` formats a date as YYYY-MM-DD.
+  return new Intl.DateTimeFormat("en-CA", { timeZone: timezone, year: "numeric", month: "2-digit", day: "2-digit" }).format(moment);
+}
+
+/**
+ * The visible dates of a published text. Two equal days one under the other read like a mistake, so
+ * "updated" disappears when it falls on the publication day. A text without a publication date has
+ * no page: calling this for one is a bug.
+ */
+export function getArticleDates(article: Pick<BlogArticle, "slug" | "publishedAt" | "updatedAt" | "currentAsOf">, timezone: string): ArticleDates {
+  if (article.publishedAt === null) {
+    throw new Error(`getArticleDates: article ${article.slug} has no published_at; pages show only published texts`);
+  }
+  const published = getDayInZone(article.publishedAt, timezone);
+  const updated = article.updatedAt === null ? null : getDayInZone(article.updatedAt, timezone);
+  return { published, updated: updated === published ? null : updated, currentAsOf: article.currentAsOf };
+}
+
+/** A `YYYY-MM-DD` day as the locale writes it in full (en: "October 4, 2026"). */
+export function formatDay(day: string, locale: Locale): string {
+  // The day is already a calendar day: format it at UTC midnight in UTC, so no zone shifts it.
+  return new Intl.DateTimeFormat(locale, { dateStyle: "long", timeZone: "UTC" }).format(new Date(`${day}T00:00:00Z`));
+}