@wildo-ai/saas-website 1.1.1

package/src/core/routing/__tests__/internal-routing.utils.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from 'vitest';
+
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import { buildLocalizedRoutePath } from '../internal-routing.utils';
+
+describe('buildLocalizedRoutePath', () => {
+  describe('default locale (un-prefixed routing)', () => {
+    it('returns the route verbatim for the default locale', () => {
+      expect(
+        buildLocalizedRoutePath({
+          locale: AvailableLanguage.EN,
+          defaultLocale: AvailableLanguage.EN,
+          routePath: '/pricing',
+        }),
+      ).toBe('/pricing');
+    });
+
+    it('returns "/" verbatim for the default-locale root', () => {
+      expect(
+        buildLocalizedRoutePath({
+          locale: AvailableLanguage.EN,
+          defaultLocale: AvailableLanguage.EN,
+          routePath: '/',
+        }),
+      ).toBe('/');
+    });
+  });
+
+  describe('non-default locale (prefixed routing)', () => {
+    it('prefixes a typical route with /<locale>', () => {
+      expect(
+        buildLocalizedRoutePath({
+          locale: AvailableLanguage.FR,
+          defaultLocale: AvailableLanguage.EN,
+          routePath: '/pricing',
+        }),
+      ).toBe('/fr/pricing');
+    });
+
+    it('collapses the root path to /<locale> (NOT /<locale>/)', () => {
+      expect(
+        buildLocalizedRoutePath({
+          locale: AvailableLanguage.FR,
+          defaultLocale: AvailableLanguage.EN,
+          routePath: '/',
+        }),
+      ).toBe('/fr');
+    });
+
+    it('handles deeper routes', () => {
+      expect(
+        buildLocalizedRoutePath({
+          locale: AvailableLanguage.FR,
+          defaultLocale: AvailableLanguage.EN,
+          routePath: '/blog/launch',
+        }),
+      ).toBe('/fr/blog/launch');
+    });
+  });
+
+  /**
+   * Phase 6 fourth audit fix M-Κ — coverage gap follow-ups for the
+   * three "tricky path shape" cases the original test grid skipped.
+   * `buildLocalizedRoutePath` is a low-level prefixer that does NOT
+   * try to interpret query strings, hash fragments, or already-
+   * prefixed paths — those are the responsibility of the calling
+   * primitive (`WebsiteInternalLink` / `WebsiteInternalButton`,
+   * which both throw on already-prefixed paths). These tests pin
+   * the helper's literal behavior so a future "be smart" refactor
+   * cannot silently change the contract.
+   */
+  describe('path shape edge cases (M-Κ — pin literal behavior)', () => {
+    it('preserves a query string by suffix-pasting (no parsing)', () => {
+      expect(
+        buildLocalizedRoutePath({
+          locale: AvailableLanguage.FR,
+          defaultLocale: AvailableLanguage.EN,
+          routePath: '/pricing?plan=pro',
+        }),
+      ).toBe('/fr/pricing?plan=pro');
+    });
+
+    it('preserves a hash fragment by suffix-pasting (no parsing)', () => {
+      expect(
+        buildLocalizedRoutePath({
+          locale: AvailableLanguage.FR,
+          defaultLocale: AvailableLanguage.EN,
+          routePath: '/pricing#tiers',
+        }),
+      ).toBe('/fr/pricing#tiers');
+    });
+
+    it('preserves both query and fragment in order', () => {
+      expect(
+        buildLocalizedRoutePath({
+          locale: AvailableLanguage.FR,
+          defaultLocale: AvailableLanguage.EN,
+          routePath: '/pricing?plan=pro#tiers',
+        }),
+      ).toBe('/fr/pricing?plan=pro#tiers');
+    });
+
+    it('DOES NOT detect already-prefixed paths — produces a double-prefix on FR pages', () => {
+      // Documents the helper's deliberate dumb-prefix contract: the
+      // caller is responsible for guarding against accidental locale
+      // prefixes. `WebsiteInternalLink` / `WebsiteInternalButton`
+      // both throw before reaching this helper when the routePath
+      // begins with a known locale segment (see their
+      // `detectAccidentalLocalePrefix` guard).
+      expect(
+        buildLocalizedRoutePath({
+          locale: AvailableLanguage.FR,
+          defaultLocale: AvailableLanguage.EN,
+          routePath: '/fr/pricing',
+        }),
+      ).toBe('/fr/fr/pricing');
+    });
+
+    it('DOES NOT detect already-prefixed paths — silently passes on default-locale pages', () => {
+      // The other half of the silent-bug surface: on a default-locale
+      // page (no prefix added), an already-prefixed path renders
+      // unchanged, so the EN visitor lands on the FR page with no
+      // visible warning. Same caller-responsibility contract.
+      expect(
+        buildLocalizedRoutePath({
+          locale: AvailableLanguage.EN,
+          defaultLocale: AvailableLanguage.EN,
+          routePath: '/fr/pricing',
+        }),
+      ).toBe('/fr/pricing');
+    });
+  });
+});

package/src/core/routing/internal-routing.utils.ts

@@ -0,0 +1,77 @@
+import type { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+/**
+ * @wildo_source:part:start saas.website.routing.localized-path facet:layer:core facet:family:website
+ *
+ * `buildLocalizedRoutePath(opts)` — pure, isomorphic helper that
+ * returns the locale-prefixed pathname for a given route, honoring the
+ * marketing-site routing convention enforced by `buildAstroI18nConfig`
+ * (`prefixDefaultLocale: false`).
+ *
+ * **The architectural problem this solves**: the marketing site mounts the
+ * default locale at the
+ * un-prefixed path (`/`, `/pricing`, `/contact`) and every other locale
+ * under `/<locale>/…` (`/fr/`, `/fr/pricing`, `/fr/contact`). Internal
+ * links authored as raw `href="/pricing"` therefore work on
+ * default-locale pages and SILENTLY BREAK on non-default-locale pages
+ * (a French visitor on `/fr/index` clicking "Pricing" lands on the
+ * English `/pricing`, falling out of their locale).
+ *
+ * **Why a helper rather than asking authors to construct the path**:
+ * the rule is a framework-level routing convention — every consumer
+ * authors links the same way, every consumer must apply the same
+ * prefix logic, and getting it wrong produces a silent locale-leak
+ * that test suites do not catch (they navigate inside a single
+ * locale). A single helper makes the rule the framework's
+ * responsibility, not the section author's.
+ *
+ * **Routing rule** (matches `buildAstroI18nConfig` and the head
+ * renderer's `buildAbsoluteUrl` helper, which delegates here as the
+ * single source of truth):
+ *   - When `locale === defaultLocale`: return `routePath` verbatim
+ *     (the un-prefixed path).
+ *   - Otherwise: return `/<locale>${routePath}`, with the special
+ *     case that `routePath === '/'` collapses to `/<locale>` (no
+ *     trailing slash) so the locale-prefixed root does not become
+ *     the awkward `/<locale>/`.
+ *
+ * **Inputs are validated by the calling layer**, not here:
+ *   - `locale` is `AvailableLanguage` (branded), so the type system
+ *     prevents an unknown locale from reaching this function.
+ *   - `routePath` is the same `routePath` field validated by the page
+ *     manifest schema (`WebsitePageRoutePathSchema` enforces it
+ *     starts with `/`). We do not re-validate here — duplicate
+ *     validation costs CPU on every link render with no incremental
+ *     safety, and the page-manifest layer fails loud at config-load
+ *     time if a malformed path leaks in.
+ *
+ * **Boundary**: pure function, zero React / DOM / fs dependencies.
+ * Safe to import from both the React-island bundle (consumed by
+ * `WebsiteInternalLink`) and the SSR head renderer (consumed by
+ * `buildAbsoluteUrl`). The package's routing tests pin this behavior.
+ */
+export interface BuildLocalizedRoutePathOptions {
+  /** The currently-active locale (typically from `useWebsiteRuntime().locale`). */
+  locale: AvailableLanguage;
+  /** The site's default locale (typically from `useWebsiteRuntime().defaultLocale`). */
+  defaultLocale: AvailableLanguage;
+  /**
+   * The page's route path, exactly as declared in
+   * `WebsitePageManifest.routePath` (always starts with `/`).
+   */
+  routePath: string;
+}
+
+export function buildLocalizedRoutePath(opts: BuildLocalizedRoutePathOptions): string {
+  const { locale, defaultLocale, routePath } = opts;
+  const localeStr = String(locale);
+  const defaultLocaleStr = String(defaultLocale);
+  if (localeStr === defaultLocaleStr) {
+    return routePath;
+  }
+  if (routePath === '/') {
+    return `/${localeStr}`;
+  }
+  return `/${localeStr}${routePath}`;
+}
+/** @wildo_source:part:end saas.website.routing.localized-path */

package/src/index.ts

@@ -0,0 +1,132 @@
+/**
+ * @wildo-package @wildo-ai/saas-website
+ *
+ * SaaS marketing/landing website engine — schemas + helpers + layout
+ * placeholders + Astro/MDX adapters + SEO/AEO/GEO builder library.
+ *
+ * Per `saas-website-slice.md` D6/D15: this engine ships **NO concrete
+ * business sections** (no Hero, no CTA, no Pricing). It ships the
+ * structural and helper machinery; consumers author every business
+ * section themselves via the `defineWebsiteSection` factory and the
+ * accompanying SKILLs in `framework-knowledge`.
+ *
+ * @wildo-boundary
+ *   - This barrel MAY re-export from any subdirectory of `src/`.
+ *   - Subdirectories MUST observe their own boundary contracts (see
+ *     each subdirectory's own `index.ts` `@wildo-boundary` block):
+ *       - `schemas/`            : NO React, NO Astro, NO `~wildo-frontend-lib/**`
+ *       - `seo/`                : NO React, NO Astro
+ *       - `core/`               : MAY use React; NO `~wildo-frontend-lib/**` (Q17=B)
+ *       - `astro/`              : MAY use Astro; NO React component runtime imports
+ *       - `mdx/`                : MAY use `@mdx-js/*`
+ *       - `integration/`        : MAY use React; MAY import the
+ *                                 `@wildo-ai/saas-models/public-runtime` SUBPATH,
+ *                                 the `@wildo-ai/presets-components-models/public-runtime`
+ *                                 SUBPATH, `@wildo-ai/zod-decorators`,
+ *                                 plus the SSR / Astro-middleware tier
+ *                                 (`axios`, `jsonwebtoken`, `socket.io-client`,
+ *                                 `reflect-metadata`) — D12 revised
+ *                                 2026-04-19 (second same-day loosening);
+ *                                 the ROOT barrels of `@wildo-ai/saas-models`
+ *                                 and `@wildo-ai/presets-components-models`
+ *                                 are FORBIDDEN (they boot the decorator
+ *                                 framework / pull the heavy registry);
+ *                                 the saas-app DI / backend stack
+ *                                 (`inversify`, `mongoose`, `express`,
+ *                                 `pino`, `helmet`, `argon2`, `bcrypt`,
+ *                                 the `@wildo-ai/saas-frontend-lib` /
+ *                                 `@wildo-ai/saas-backend-lib` /
+ *                                 `@wildo-ai/external-connectors-models`
+ *                                 root + subpath surfaces) is FORBIDDEN;
+ *                                 MUST NOT import `~wildo-frontend-lib/**`
+ *                                 (Q17=B / D16)
+ *
+ *   D12 (client-bundle import discipline, all `core/`/`schemas/`/`integration/`
+ *   files): the entire saas-website source tree ships into a browser bundle
+ *   (Astro SSG + React islands). Every shared model atom MUST come from a
+ *   side-effect-free `/public-runtime` subpath:
+ *     - `@wildo-ai/saas-models/public-runtime` is the primary door
+ *       (saas-models-public-runtime.md K-6 — consumers see one path).
+ *     - `@wildo-ai/presets-components-models/public-runtime` is the
+ *       internal seam for symbols not (yet) re-exported by saas-models.
+ *     - `@wildo-ai/zod-decorators` is allowed to import (first revision
+ *       2026-04-19). The package itself is side-effect-free; only an
+ *       explicit `initZodDecorators()` call mutates `z.ZodType.prototype`,
+ *       which neither saas-website nor the saas-models /public-runtime
+ *       barrel does.
+ *     - `axios`, `jsonwebtoken`, `socket.io-client`, `reflect-metadata` are
+ *       allowed for SSR / Astro-middleware code paths (second same-day
+ *       revision 2026-04-19). The website engine needs them to provide
+ *       middleware utilities (HTTP proxying to the SaaS backend, JWT
+ *       verification of cross-frontend handoff codes, real-time push,
+ *       decorator-metadata reads). They are SSR-tier — discipline
+ *       (and a future strict/loose entry split for React islands vs
+ *       middleware) keeps them out of the React-island bundle.
+ *
+ *   The ROOT barrel of `@wildo-ai/saas-models` is forbidden everywhere in
+ *   this package — it calls `initZodDecorators()` at module load and pulls
+ *   `@wildo-ai/external-connectors-models` + the full schema graph into
+ *   the bundle. Same forbid applies to the root barrel of
+ *   `@wildo-ai/presets-components-models`, the saas-app DI runtime
+ *   (`inversify`, `@wildo-ai/saas-frontend-lib`, `@wildo-ai/saas-backend-lib`),
+ *   and pure-backend libs (`mongoose`, `express`, `pino`, `helmet`,
+ *   `argon2`, `bcrypt`). Enforced by `src/__tests__/bundle-isolation.test.ts`.
+ *
+ *   These boundaries are enforced by review + the bundle-isolation test
+ *   above until Phase 8 promotes them to a programmatic ESLint check
+ *   (cf. `saas-website-slice.md`
+ *   §"DEFERRED to Phase 8 — boundary lint mechanism design").
+ *
+ * Phase 1+2 status: schemas + runtime contexts/hooks + layout
+ * primitives + L1 placeholders + factories are all exported. Phase 5
+ * adds the Astro adapter; Phase 5.7 the `integration/` layer.
+ *
+ * D18 (L1 boundary, Phase 2): the L1 primitives (`WebsiteHeading`,
+ * `WebsiteText`, `WebsiteButton`, `WebsiteLink`, `WebsiteImage`) are
+ * self-contained placeholders — they do NOT consume
+ * `ComponentRegistryService` from `saas-frontend-lib` and do NOT
+ * re-export `saas-frontend-lib` primitives. Consumers override at the
+ * L1 boundary by barrel-re-exporting their preferred styled variant
+ * from their app's `app/website/primitives/<Primitive>.tsx`. Phase 6
+ * dogfood will revisit and decide whether to promote a registry-based
+ * override mechanism.
+ */
+
+export * from './schemas/refs/page-ref.schemas';
+export * from './schemas/refs/section-ref.schemas';
+export * from './schemas/label-keys/website-label-key.schemas';
+export * from './schemas/sections/website-section-category.shared';
+export * from './schemas/sections/website-section-definition.shared.schemas';
+export * from './schemas/structured-data/website-structured-data.shared.schemas';
+export * from './schemas/structured-data/structured-data-reconciliation.shared';
+export * from './schemas/design-tokens/website-design-tokens.shared.schemas';
+export * from './schemas/manifests/website-page-manifest.shared.schemas';
+export * from './schemas/manifests/website-root-config.shared.schemas';
+export * from './schemas/blog/blog-post-frontmatter.shared.schemas';
+export * from './schemas/validators/label-pack.validator';
+
+export * from './core/contexts/WebsiteRuntimeContext';
+export * from './core/contexts/useWebsiteRuntime';
+export * from './core/contexts/WebsitePageContext';
+export * from './core/contexts/useWebsitePage';
+export * from './core/contexts/WebsiteSectionContext';
+export * from './core/contexts/useWebsiteSection';
+export * from './core/hooks/useWebsiteLabel';
+export * from './core/hooks/useWebsiteDesignTokens';
+export * from './core/factories/define-website-section';
+export * from './core/factories/define-website-page-manifest';
+export * from './core/layouts/WebsitePageLayout';
+export * from './core/layouts/WebsiteSection';
+
+export * from './core/anonymous-session/website-anonymous-session-client';
+export * from './core/anonymous-session/inbound-contact-form.schema';
+export * from './core/anonymous-session/InboundContactForm';
+
+export * from './components/low-level/WebsiteHeading';
+export * from './components/low-level/WebsiteText';
+export * from './components/low-level/WebsiteLink';
+export * from './components/low-level/WebsiteInternalLink';
+export * from './core/routing/internal-routing.utils';
+export * from './components/low-level/WebsiteButton';
+export * from './components/low-level/WebsiteInternalButton';
+export * from './components/low-level/WebsiteImage';

package/src/mdx/BlogPost.tsx

@@ -0,0 +1,296 @@
+import type { ComponentType, ReactNode } from 'react';
+
+import { WebsitePageLayout } from '../core/layouts/WebsitePageLayout';
+import type { WebsitePageRef } from '../schemas/refs/page-ref.schemas';
+
+import {
+  parseBlogPostFrontmatter,
+  type ParseBlogPostFrontmatterContext,
+} from './blog-post-collection.config';
+import {
+  WebsiteMdxProvider,
+  type WebsiteMdxComponentsMap,
+} from './website-mdx-provider';
+
+/**
+ * @wildo_source:part:start saas.website.blog.post-renderer facet:layer:mdx facet:family:website
+ *
+ * `<BlogPost>` — engine-owned per-post page renderer for the marketing
+ * blog adapter.
+ *
+ * # What it does, end-to-end
+ *
+ *   1. **Strict frontmatter parse.** Reads the raw `entry.data` Astro
+ *      hands the page (passthrough at the content-collection layer per
+ *      Path Z, see `blog-post-collection.config.ts`) and runs it
+ *      through `BlogPostFrontmatterSchema` (Zod 4) — branded `slug` /
+ *      `authorRef` / `tags`, ISO-8601 `publishedAt`, optional
+ *      `coverImageUrl`. A failure throws synchronously with a
+ *      `[blog-post] (source="…")` message; Astro halts the build and
+ *      points the operator to the offending MDX file.
+ *   2. **Renders `<WebsitePageLayout>` with a stable blog-post page
+ *      ref.** The framework reserves `'blog-post'` as the
+ *      `WebsitePageRef` for every blog post (see `BLOG_POST_PAGE_REF`
+ *      below for the rationale). All blog posts share one page ref
+ *      because the SECTION ref under that page is what's
+ *      blog-author-controlled (see point 3) — the page-level chrome,
+ *      label scope, and analytics signal are the same across the entire
+ *      blog surface.
+ *   3. **Wraps the MDX body in `<WebsiteMdxProvider>`.** The consumer
+ *      passes a `mdxComponents` map (typically containing one or two
+ *      business-section refs they want available inside post bodies —
+ *      `<CTASection ref="post-cta" />`, etc.). The provider scopes the
+ *      map for the duration of the render and ONLY the duration of the
+ *      render, so two blog posts on the same site can ship different
+ *      provider configs without leaking.
+ *   4. **Emits a hero block (title / summary / publish date / author
+ *      handle / cover image)** from the parsed frontmatter, then yields
+ *      to the MDX body. Hero markup is intentionally minimal — the
+ *      consumer styles it via `WebsiteDesignTokens` custom properties.
+ *      No CSS file ships from this component; everything is inline
+ *      style + design-token references.
+ *
+ * # Why a blog-specific page renderer (vs. the generic page bridge)
+ *
+ * The `createWebsitePageBridgeIsland` factory takes a `PageComponent`
+ * — a React component the page author writes. A blog post has NO React
+ * component; the MDX file IS the component (compiled by `@astrojs/mdx`
+ * to a default-export React tree). Reusing the page-bridge factory
+ * would force the consumer to write a ten-line wrapper per post that
+ * imports the MDX module, calls `<MdxBody />`, and re-passes the
+ * frontmatter — a cold violation of the "every blog post is one MDX
+ * file, period" principle. `<BlogPost>` is the framework's
+ * single ten-line wrapper, written once.
+ *
+ * # Why no per-post `pageRef` / per-section `sectionRef` knobs
+ *
+ * Two reasons:
+ *
+ *   - **Label-key scope semantics.** A blog post's body has no
+ *     framework-routed labels (the prose IS in the MDX). The section
+ *     refs that DO need labels are those an MDX file embeds via the
+ *     `mdxComponents` map — and those sections were already registered
+ *     in the consumer's `WEBSITE_SECTIONS` registry with their
+ *     own `expectedLabelKeys`. Letting blog authors pass arbitrary
+ *     `sectionRef`s would create unbounded label-key surface area that
+ *     `assertLabelPacksValid` cannot validate at build start.
+ *   - **Analytics + chrome consistency.** Marketing teams treat "the
+ *     blog" as one funnel. A single `pageRef='blog-post'` keeps the
+ *     `data-website-page-ref` attribute on the layout root constant
+ *     across every post, so the analytics ingest sees one blog-post
+ *     page event regardless of slug. Per-post overrides would fragment
+ *     this without buying any operator value.
+ *
+ * # Hydration + bundle boundary
+ *
+ * This component is NOT itself a Bridge factory — it's plain React
+ * meant to be rendered inside an Astro `.astro` page. The consumer's
+ * per-post Astro template (typically `src/pages/[locale]/blog/[slug].astro`)
+ * imports `<BlogPost>` directly and renders it; the surrounding
+ * `<WebsitePageBridgeIsland>` provides the runtime context. The MDX
+ * runtime (`@mdx-js/react`) is React-only and pulls into the React
+ * island bundle — bundle-isolation tests walk `mdx.ts` as their own
+ * entry to keep the browser-facing closure auditable.
+ *
+ * Authoring example:
+ *
+ * ```astro
+ * ---
+ * // src/pages/blog/[slug].astro
+ * import { getCollection, getEntry } from 'astro:content';
+ * import { BlogPost } from '@wildo-ai/saas-website/mdx';
+ * import { BLOG_POST_MDX_COMPONENTS } from '@/blog/mdx-components';
+ *
+ * export async function getStaticPaths() {
+ *   const posts = await getCollection('blog');
+ *   return posts
+ *     .filter((p) => p.data.locale === 'en')
+ *     .map((p) => ({ params: { slug: p.data.slug }, props: { entry: p } }));
+ * }
+ *
+ * const { entry } = Astro.props;
+ * const { Content } = await entry.render();
+ * ---
+ * <BlogPost
+ *   rawFrontmatter={entry.data}
+ *   source={entry.id}
+ *   mdxComponents={BLOG_POST_MDX_COMPONENTS}
+ *   client:load
+ * >
+ *   <Content />
+ * </BlogPost>
+ * ```
+ */
+
+/**
+ * Reserved `WebsitePageRef` for every blog post page. Exported so
+ * consumers can register a matching `BLOG_POST_PAGE_MANIFEST` in
+ * their site root config (the page manifest carries the navigation
+ * + label-pack scope; the renderer carries the structural layout).
+ *
+ * Branded as a plain string literal (cast through `unknown`) because:
+ *   - The `WebsitePageRef` brand is enforced via Zod's `.brand<>()`,
+ *     and parsing a string literal at module load time would require
+ *     dragging the Zod runtime into module init — gratuitous when the
+ *     ref is a compile-time constant.
+ *   - `WebsitePageLayout` re-parses any incoming `pageRef` string
+ *     defensively (see `WebsitePageLayoutProps.pageRef` JSDoc), so the
+ *     brand is re-asserted at render time anyway.
+ */
+export const BLOG_POST_PAGE_REF: WebsitePageRef = 'blog-post' as unknown as WebsitePageRef;
+
+export interface BlogPostProps {
+  /**
+   * Raw frontmatter object Astro hands the page from `entry.data` (or
+   * equivalent). The renderer validates this through
+   * `BlogPostFrontmatterSchema` synchronously — invalid shapes throw
+   * with a `[blog-post]`-prefixed message. Pass `entry.data` directly;
+   * do NOT pre-parse on the consumer side (the framework owns the
+   * validation surface so a future schema change lands in ONE place).
+   */
+  rawFrontmatter: unknown;
+  /**
+   * Diagnostic source identifier echoed into validation errors —
+   * typically `entry.id` from Astro's content collection (`'en/why-context.mdx'`
+   * or similar). Optional but strongly recommended; without it,
+   * `parseBlogPostFrontmatter` throws with a generic
+   * `[blog-post] Frontmatter failed …` message that does not name the
+   * offending file.
+   */
+  source?: string;
+  /**
+   * MDX-tag → React-component map made available inside the post
+   * body via `<WebsiteMdxProvider>`. Typically a small object literal
+   * exporting one or two business sections the consumer wants
+   * available everywhere in the blog surface
+   * (`<CTASection ref="post-cta" />`, `<NewsletterSignup />`, etc.).
+   *
+   * Empty maps are valid — a post body using only standard markdown
+   * (no embedded React) needs no overrides.
+   */
+  mdxComponents?: WebsiteMdxComponentsMap;
+  /**
+   * Per-page chrome overrides forwarded straight into
+   * `<WebsitePageLayout>`. `null` suppresses the slot entirely;
+   * `undefined` (the default) inherits the runtime navigation
+   * config's header/footer components. Most blog posts leave both
+   * unset to inherit the site-wide chrome.
+   */
+  header?: ReactNode | null;
+  footer?: ReactNode | null;
+  /**
+   * The compiled MDX body — typically `<Content />` from Astro's
+   * `await entry.render()` call. Rendered inside the
+   * `<WebsiteMdxProvider>` boundary so its inline `<TagName />`
+   * references resolve against `mdxComponents`.
+   */
+  children: ReactNode;
+}
+
+/**
+ * Empty default for `mdxComponents` — defined at module scope (NOT
+ * inline in the destructure default) so the object identity is
+ * stable across re-renders. Stable identity matters here because
+ * `<MDXProvider>`'s internal context value is `useMemo`-derived from
+ * the `components` prop; inline `{}` would invalidate every render.
+ */
+const EMPTY_MDX_COMPONENTS: WebsiteMdxComponentsMap = Object.freeze({});
+
+export function BlogPost(props: BlogPostProps): ReactNode {
+  const {
+    rawFrontmatter,
+    source,
+    mdxComponents = EMPTY_MDX_COMPONENTS,
+    header,
+    footer,
+    children,
+  } = props;
+
+  /**
+   * Build the diagnostic context once per render. We do not memoize
+   * (one object literal per render is cheaper than the `useMemo`
+   * accounting), but we also do not pass `source: undefined`
+   * unconditionally because `parseBlogPostFrontmatter` switches on
+   * `ctx.source !== undefined` for the error-suffix; passing `{}`
+   * when undefined keeps the suffix absent in that case.
+   */
+  const parseCtx: ParseBlogPostFrontmatterContext =
+    source !== undefined ? { source } : {};
+  const frontmatter = parseBlogPostFrontmatter(rawFrontmatter, parseCtx);
+
+  /**
+   * The hero markup intentionally uses semantic HTML5 elements
+   * (`<header>`, `<h1>`, `<time>`, `<address>`) rather than raw
+   * `<div>`s so screen readers and crawlers see the post structure
+   * without consumer styling intervention. The styling story is:
+   * design tokens via the surrounding `WebsiteRuntimeContext` +
+   * the consumer's stylesheet — NO CSS ships from this file.
+   */
+  return (
+    <WebsitePageLayout
+      pageRef={BLOG_POST_PAGE_REF}
+      header={header}
+      footer={footer}
+    >
+      <article data-website-blog-post-slug={frontmatter.slug as unknown as string}>
+        <header>
+          {frontmatter.coverImageUrl !== undefined ? (
+            <img
+              src={frontmatter.coverImageUrl}
+              alt=""
+              loading="eager"
+              data-website-blog-post-cover
+            />
+          ) : null}
+          <h1>{frontmatter.title}</h1>
+          <p data-website-blog-post-summary>{frontmatter.summary}</p>
+          {/*
+           * Meta line is a `<div>`, not a `<p>` — `<address>` is a flow-
+           * content element and cannot be a descendant of `<p>` per HTML5
+           * (browsers auto-close the `<p>` on `<address>`, which produces
+           * a hydration mismatch in React 19). The `<div>` keeps the
+           * semantic `<time>` + `<address>` landmarks intact for screen
+           * readers + crawlers without violating the parsing rules.
+           */}
+          <div data-website-blog-post-meta>
+            <time dateTime={frontmatter.publishedAt}>
+              {frontmatter.publishedAt}
+            </time>
+            {' · '}
+            <address data-website-blog-post-author>
+              {frontmatter.authorRef as unknown as string}
+            </address>
+          </div>
+          {frontmatter.tags.length > 0 ? (
+            <ul data-website-blog-post-tags>
+              {frontmatter.tags.map((tag) => (
+                <li key={tag as unknown as string}>
+                  {tag as unknown as string}
+                </li>
+              ))}
+            </ul>
+          ) : null}
+        </header>
+        <WebsiteMdxProvider components={mdxComponents}>
+          {children}
+        </WebsiteMdxProvider>
+      </article>
+    </WebsitePageLayout>
+  );
+}
+BlogPost.displayName = 'BlogPost';
+
+/**
+ * Type alias re-export so consumers writing `BLOG_POST_MDX_COMPONENTS:
+ * BlogPostMdxComponents = { … }` have a stable name (the underlying
+ * type is the same `WebsiteMdxComponentsMap` from the provider).
+ */
+export type BlogPostMdxComponents = WebsiteMdxComponentsMap;
+
+/**
+ * Convenience type — the Astro `ComponentType` consumers write inline
+ * inside a `mdxComponents` map. Re-exported so consumer authoring
+ * doesn't need to import from `react` directly.
+ */
+export type BlogPostMdxComponent = ComponentType<any>;
+/** @wildo_source:part:end saas.website.blog.post-renderer */