@wildo-ai/saas-website 1.1.1

package/src/mdx/__tests__/BlogPost.test.tsx

@@ -0,0 +1,218 @@
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import {
+  WebsiteRuntimeContextProvider,
+  type WebsiteRuntimeContextValue,
+} from '../../core/contexts/WebsiteRuntimeContext';
+import { WebsiteLabelKeySchema } from '../../schemas/label-keys/website-label-key.schemas';
+import { BlogPost, BLOG_POST_PAGE_REF } from '../BlogPost';
+
+/**
+ * `<BlogPost>` integration coverage.
+ *
+ * The renderer composes three things:
+ *   1. Strict frontmatter parse via `parseBlogPostFrontmatter` (Zod 4).
+ *   2. `<WebsitePageLayout pageRef="blog-post">` for site-wide chrome
+ *      + `WebsitePageContext` provisioning + the
+ *      `data-website-page-ref` analytics attribute.
+ *   3. `<WebsiteMdxProvider>` around `children` so MDX-compiled
+ *      `<TagName />` references resolve against `mdxComponents`.
+ *
+ * Each test focuses on one of those concerns. Render-time chrome
+ * (header/footer slot) is already exercised in `WebsitePageLayout.test.tsx`;
+ * we only assert the slots wire through correctly here.
+ */
+
+const SkipKey = WebsiteLabelKeySchema.parse(
+  'website.chrome.layout.skip-to-main-content',
+);
+
+const RuntimeHeader = (): React.ReactElement => (
+  <span data-testid="runtime-header">RH</span>
+);
+const RuntimeFooter = (): React.ReactElement => (
+  <span data-testid="runtime-footer">RF</span>
+);
+
+const RUNTIME: WebsiteRuntimeContextValue = {
+  locale: AvailableLanguage.EN,
+  defaultLocale: AvailableLanguage.EN,
+  labelPack: { 'website.chrome.layout.skip-to-main-content': 'Skip to main content' },
+  designTokens: {
+    colors: {
+      background: '#fff',
+      foreground: '#000',
+      primary: '#000',
+      primaryForeground: '#fff',
+      accent: '#000',
+      accentForeground: '#fff',
+      surface: '#fff',
+      surfaceForeground: '#000',
+      border: '#ccc',
+      muted: '#eee',
+      mutedForeground: '#666',
+    },
+    radii: { none: '0', sm: '2px', md: '4px', lg: '8px', xl: '12px', full: '9999px' },
+  },
+  navigation: {
+    headerComponent: RuntimeHeader,
+    footerComponent: RuntimeFooter,
+  },
+  skipToMainContentLabelKey: SkipKey,
+};
+
+const wrap = (children: React.ReactNode): React.ReactElement => (
+  <WebsiteRuntimeContextProvider value={RUNTIME}>
+    {children}
+  </WebsiteRuntimeContextProvider>
+);
+
+const VALID = {
+  title: 'Why Context Beats Content',
+  summary: 'Compress the loop your team actually runs every week.',
+  slug: 'why-context-beats-content',
+  locale: 'en' as const,
+  publishedAt: '2026-04-17T09:00:00.000Z',
+  authorRef: 'paul-cayon',
+  tags: ['context', 'product-strategy'],
+  coverImageUrl: 'https://cdn.wildo.ai/blog/why-context-cover.png',
+};
+
+describe('BlogPost', () => {
+  it('exposes the reserved blog-post page ref via the WebsitePageLayout data attribute', () => {
+    const { container } = render(
+      wrap(
+        <BlogPost rawFrontmatter={VALID} source="en/why-context.mdx">
+          <p>Body</p>
+        </BlogPost>,
+      ),
+    );
+    expect(
+      container.querySelector(`[data-website-page-ref="${BLOG_POST_PAGE_REF as unknown as string}"]`),
+    ).not.toBeNull();
+  });
+
+  it('renders the hero block from validated frontmatter', () => {
+    const { getByText, getByRole, container } = render(
+      wrap(
+        <BlogPost rawFrontmatter={VALID} source="en/why-context.mdx">
+          <p>Body content</p>
+        </BlogPost>,
+      ),
+    );
+    expect(getByRole('heading', { level: 1, name: VALID.title })).toBeInTheDocument();
+    expect(getByText(VALID.summary)).toBeInTheDocument();
+    expect(container.querySelector('time[datetime]')).toHaveAttribute(
+      'datetime',
+      VALID.publishedAt,
+    );
+    expect(container.querySelector('img[data-website-blog-post-cover]')).toHaveAttribute(
+      'src',
+      VALID.coverImageUrl,
+    );
+  });
+
+  it('renders all tags as <li> children of <ul data-website-blog-post-tags>', () => {
+    const { container } = render(
+      wrap(
+        <BlogPost rawFrontmatter={VALID} source="en/why-context.mdx">
+          <p>Body</p>
+        </BlogPost>,
+      ),
+    );
+    const tagList = container.querySelector('ul[data-website-blog-post-tags]');
+    expect(tagList).not.toBeNull();
+    const tagItems = tagList!.querySelectorAll('li');
+    expect(tagItems.length).toBe(VALID.tags.length);
+    expect(Array.from(tagItems).map((li) => li.textContent)).toEqual(VALID.tags);
+  });
+
+  it('omits the cover image element when coverImageUrl is absent', () => {
+    const { coverImageUrl: _u, ...withoutCover } = VALID;
+    void _u;
+    const { container } = render(
+      wrap(
+        <BlogPost rawFrontmatter={withoutCover} source="en/no-cover.mdx">
+          <p>Body</p>
+        </BlogPost>,
+      ),
+    );
+    expect(container.querySelector('img[data-website-blog-post-cover]')).toBeNull();
+  });
+
+  it('omits the tag list when tags array is empty', () => {
+    const { container } = render(
+      wrap(
+        <BlogPost rawFrontmatter={{ ...VALID, tags: [] }} source="en/no-tags.mdx">
+          <p>Body</p>
+        </BlogPost>,
+      ),
+    );
+    expect(container.querySelector('ul[data-website-blog-post-tags]')).toBeNull();
+  });
+
+  it('throws a [blog-post]-prefixed error when frontmatter is invalid', () => {
+    const broken = { ...VALID, slug: 'NotKebab' };
+    expect(() =>
+      render(
+        wrap(
+          <BlogPost rawFrontmatter={broken} source="en/broken.mdx">
+            <p>Body</p>
+          </BlogPost>,
+        ),
+      ),
+    ).toThrowError(/\[blog-post\] Frontmatter failed BlogPostFrontmatterSchema validation \(source="en\/broken\.mdx"\)/);
+  });
+
+  it('renders MDX-style children inside the WebsiteMdxProvider boundary', () => {
+    /**
+     * Assert the children land in the document. This proves the
+     * provider does not eat them; the provider's own forwarding
+     * behaviour is exercised in `website-mdx-provider.test.tsx`.
+     */
+    const { getByTestId } = render(
+      wrap(
+        <BlogPost rawFrontmatter={VALID} source="en/why-context.mdx">
+          <p data-testid="mdx-body">Body content</p>
+        </BlogPost>,
+      ),
+    );
+    expect(getByTestId('mdx-body')).toHaveTextContent('Body content');
+  });
+
+  it('honors per-page header/footer overrides', () => {
+    const { getByTestId, queryByTestId } = render(
+      wrap(
+        <BlogPost
+          rawFrontmatter={VALID}
+          source="en/why-context.mdx"
+          header={<div data-testid="custom-header">CH</div>}
+          footer={<div data-testid="custom-footer">CF</div>}
+        >
+          <p>Body</p>
+        </BlogPost>,
+      ),
+    );
+    expect(getByTestId('custom-header')).toBeInTheDocument();
+    expect(getByTestId('custom-footer')).toBeInTheDocument();
+    expect(queryByTestId('runtime-header')).toBeNull();
+    expect(queryByTestId('runtime-footer')).toBeNull();
+  });
+
+  it('falls back to the runtime navigation chrome when no override is supplied', () => {
+    const { getByTestId } = render(
+      wrap(
+        <BlogPost rawFrontmatter={VALID} source="en/why-context.mdx">
+          <p>Body</p>
+        </BlogPost>,
+      ),
+    );
+    expect(getByTestId('runtime-header')).toBeInTheDocument();
+    expect(getByTestId('runtime-footer')).toBeInTheDocument();
+  });
+});

package/src/mdx/__tests__/blog-post-collection.config.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  buildBlogPostCollectionConfig,
+  parseBlogPostFrontmatter,
+  type AstroZodFactoryShape,
+} from '../blog-post-collection.config';
+import { parseBlogPostFrontmatterFromMdxSource } from '../blog-post-frontmatter-source';
+
+/**
+ * Coverage for the Astro content-collection bridge (Path Z).
+ *
+ * Two surfaces:
+ *   - `buildBlogPostCollectionConfig({ astroZ })` — assembles the
+ *     passthrough schema slot the consumer spreads into Astro's
+ *     `defineCollection({ ... })`. We feed it a tiny stub matching
+ *     `AstroZodFactoryShape` (the engine intentionally cannot import
+ *     `astro:content` directly; the consumer-supplied factory IS the
+ *     bridge) and assert the right calls land.
+ *   - `parseBlogPostFrontmatter(raw, ctx)` — the strict Zod-4 validator
+ *     called at the top of `<BlogPost>` rendering. We exercise both
+ *     happy-path branding + failure-case error formatting (the
+ *     `[blog-post]` prefix + per-issue path/message lines + optional
+ *     `(source="…")` suffix that names the offending file).
+ */
+
+const VALID_FRONTMATTER = {
+  title: 'Why Context Beats Content',
+  summary:
+    'Content tools optimize the wrong loop. Context tools compress the loop your team actually runs every week.',
+  slug: 'why-context-beats-content',
+  locale: 'en' as const,
+  publishedAt: '2026-04-17T09:00:00.000Z',
+  authorRef: 'paul-cayon',
+  tags: ['context', 'product-strategy'],
+  coverImageUrl: 'https://cdn.wildo.ai/blog/why-context-cover.png',
+};
+
+describe('buildBlogPostCollectionConfig', () => {
+  it('calls astroZ.object({}) followed by .passthrough() and surfaces the result', () => {
+    const passthroughSchema = { __mock__: 'passthrough-schema' };
+    const passthroughSpy = vi.fn(() => passthroughSchema);
+    const objectSpy = vi.fn(() => ({ passthrough: passthroughSpy }));
+    const astroZ: AstroZodFactoryShape = {
+      object: objectSpy as unknown as AstroZodFactoryShape['object'],
+    };
+
+    const config = buildBlogPostCollectionConfig({ astroZ });
+
+    expect(objectSpy).toHaveBeenCalledTimes(1);
+    expect(objectSpy).toHaveBeenCalledWith({});
+    expect(passthroughSpy).toHaveBeenCalledTimes(1);
+    expect(config.schema).toBe(passthroughSchema);
+  });
+});
+
+describe('parseBlogPostFrontmatter', () => {
+  it('returns a branded BlogPostFrontmatter on a valid input', () => {
+    const result = parseBlogPostFrontmatter(VALID_FRONTMATTER);
+    expect(result.title).toBe(VALID_FRONTMATTER.title);
+    expect(result.slug as unknown as string).toBe(VALID_FRONTMATTER.slug);
+    expect(result.tags.map((t) => t as unknown as string)).toEqual(
+      VALID_FRONTMATTER.tags,
+    );
+  });
+
+  it('accepts a frontmatter without the optional coverImageUrl', () => {
+    const { coverImageUrl: _unused, ...rest } = VALID_FRONTMATTER;
+    void _unused;
+    const result = parseBlogPostFrontmatter(rest);
+    expect(result.coverImageUrl).toBeUndefined();
+  });
+
+  it('throws with a [blog-post] prefix and includes the source suffix when ctx.source is set', () => {
+    const broken = { ...VALID_FRONTMATTER, slug: 'NotKebab' };
+    expect(() => parseBlogPostFrontmatter(broken, { source: 'en/why-context.mdx' }))
+      .toThrowError(/\[blog-post\] Frontmatter failed BlogPostFrontmatterSchema validation \(source="en\/why-context\.mdx"\):/);
+  });
+
+  it('omits the source suffix when ctx is empty', () => {
+    const broken = { ...VALID_FRONTMATTER, slug: '' };
+    expect(() => parseBlogPostFrontmatter(broken, {}))
+      .toThrowError(/\[blog-post\] Frontmatter failed BlogPostFrontmatterSchema validation:\n  - slug:/);
+  });
+
+  it('includes the failing field path in the error message', () => {
+    const broken = { ...VALID_FRONTMATTER, publishedAt: 'not-a-datetime' };
+    expect(() => parseBlogPostFrontmatter(broken)).toThrowError(/publishedAt:/);
+  });
+
+  it('reports multiple issues on multiple bad fields', () => {
+    const broken = { ...VALID_FRONTMATTER, title: '', summary: '' };
+    expect(() => parseBlogPostFrontmatter(broken)).toThrowError(/title:[\s\S]*summary:/);
+  });
+});
+
+describe('parseBlogPostFrontmatterFromMdxSource', () => {
+  it('parses YAML frontmatter from raw MDX source through the canonical schema', () => {
+    const result = parseBlogPostFrontmatterFromMdxSource(
+      `---
+title: Why Context Beats Content
+summary: Content tools optimize the wrong loop. Context tools compress the loop your team actually runs every week.
+slug: why-context-beats-content
+locale: en
+publishedAt: "2026-04-17T09:00:00.000Z"
+authorRef: paul-cayon
+tags:
+  - context
+  - product-strategy
+coverImageUrl: https://cdn.wildo.ai/blog/why-context-cover.png
+---
+
+# Body
+`,
+      { source: 'en/why-context-beats-content.mdx' },
+    );
+
+    expect(result.slug as unknown as string).toBe(VALID_FRONTMATTER.slug);
+    expect(result.tags.map((t) => t as unknown as string)).toEqual(VALID_FRONTMATTER.tags);
+  });
+
+  it('fails with source context when raw MDX frontmatter is missing', () => {
+    expect(() =>
+      parseBlogPostFrontmatterFromMdxSource('# Body only', { source: 'en/broken.mdx' }),
+    ).toThrowError(/\[blog-post\] MDX file is missing YAML frontmatter \(source="en\/broken\.mdx"\)\./);
+  });
+});

package/src/mdx/__tests__/website-mdx-provider.test.tsx

@@ -0,0 +1,82 @@
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+import { useMDXComponents } from '@mdx-js/react';
+
+import {
+  WebsiteMdxProvider,
+  type WebsiteMdxComponentsMap,
+} from '../website-mdx-provider';
+
+/**
+ * The provider is intentionally a thin wrapper around `@mdx-js/react`'s
+ * `MDXProvider`. We don't re-test the upstream library — we test that
+ * the framework boundary correctly forwards the `components` map and
+ * exposes its identity to descendants via `useMDXComponents()` (the
+ * upstream hook the MDX-compiled JSX call sites use to resolve tag
+ * names → React components).
+ *
+ * If the upstream API ever shifts (e.g. a major bumps `MDXProvider`'s
+ * prop name or splits the package), these tests fail at this seam
+ * instead of propagating into every consumer's blog body.
+ */
+
+function ProbeComponents(): React.ReactElement {
+  const components = useMDXComponents();
+  return (
+    <ul>
+      {Object.keys(components)
+        .sort()
+        .map((key) => (
+          <li key={key} data-testid={`mdx-key-${key}`}>
+            {key}
+          </li>
+        ))}
+    </ul>
+  );
+}
+
+describe('WebsiteMdxProvider', () => {
+  it('makes provider components available to descendants via useMDXComponents()', () => {
+    const components: WebsiteMdxComponentsMap = {
+      CTASection: () => <span>cta</span>,
+      Newsletter: () => <span>news</span>,
+    };
+    const { getByTestId } = render(
+      <WebsiteMdxProvider components={components}>
+        <ProbeComponents />
+      </WebsiteMdxProvider>,
+    );
+    expect(getByTestId('mdx-key-CTASection')).toBeInTheDocument();
+    expect(getByTestId('mdx-key-Newsletter')).toBeInTheDocument();
+  });
+
+  it('renders its children unmodified', () => {
+    const { getByTestId } = render(
+      <WebsiteMdxProvider components={{}}>
+        <span data-testid="child">hello</span>
+      </WebsiteMdxProvider>,
+    );
+    expect(getByTestId('child')).toHaveTextContent('hello');
+  });
+
+  it('inherits parent provider components when nested (default disableParentContext = false)', () => {
+    const parent: WebsiteMdxComponentsMap = {
+      ParentOnly: () => <span>p</span>,
+    };
+    const child: WebsiteMdxComponentsMap = {
+      ChildOnly: () => <span>c</span>,
+    };
+    const { getByTestId } = render(
+      <WebsiteMdxProvider components={parent}>
+        <WebsiteMdxProvider components={child}>
+          <ProbeComponents />
+        </WebsiteMdxProvider>
+      </WebsiteMdxProvider>,
+    );
+    expect(getByTestId('mdx-key-ParentOnly')).toBeInTheDocument();
+    expect(getByTestId('mdx-key-ChildOnly')).toBeInTheDocument();
+  });
+});

package/src/mdx/blog-post-collection.config.ts

@@ -0,0 +1,177 @@
+import { formatZodIssues } from '@wildo-ai/saas-models/public-runtime';
+import {
+  BlogPostFrontmatterSchema,
+  type BlogPostFrontmatter,
+} from '../schemas/blog/blog-post-frontmatter.shared.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.blog.collection-config facet:layer:mdx facet:family:website
+ *
+ * Astro content-collection bridge for blog posts (Phase 7 D-3 = Path Z).
+ *
+ * # The Zod-version bridge problem
+ *
+ * Astro's `astro:content` ships its own bundled Zod (currently 3.x).
+ * Our `BlogPostFrontmatterSchema` is Zod 4 and uses Zod-4-only APIs
+ * (`z.iso.datetime`, `z.url(...)`, `.brand<>()`). The two cannot share
+ * a schema instance directly across the version boundary, and shimming
+ * a Zod 4 schema down to a Zod 3 schema would create either:
+ *
+ *   - a hand-mirrored copy (Path X) — maintained in `src/content/config.ts`
+ *     using Astro's `z`, with silent-drift risk every time a field is
+ *     added/removed/refined; or
+ *   - a runtime bridge package (Path C) — a non-trivial maintenance
+ *     surface for a marginal gain.
+ *
+ * Path Z (this file) sidesteps the bridge entirely: the consumer's
+ * `src/content/config.ts` declares a `passthrough` collection schema
+ * that lets Astro accept any frontmatter shape; the engine then
+ * validates with the canonical Zod 4 schema at render time inside
+ * `<BlogPost>`. Astro's static site generator runs the page render
+ * during the build, so a malformed frontmatter still surfaces as a
+ * BUILD-TIME error (the `.parse()` call throws synchronously and Astro
+ * reports it with the page URL) — the only practical difference vs.
+ * Path X is the error-message stack location.
+ *
+ * # Why the engine ships an opaque shape (rather than the consumer
+ *   importing the Astro `z` directly)
+ *
+ * Astro's content-collection API has churned across Astro 4 → 5
+ * (loaders moved from string-keyed `type` to a callable `loader`
+ * factory; the `glob()` loader's signature changed). Every consumer
+ * touching `defineCollection` directly inherits that churn; centralizing
+ * the wiring in the engine means the framework absorbs the upgrade
+ * cost in ONE place when Astro bumps a major.
+ *
+ * The shape returned here is `{ schema: <passthrough record> }`. The
+ * consumer spreads it into their `defineCollection` call:
+ *
+ * ```ts
+ * // examples/<app>/website/src/content/config.ts
+ * import { defineCollection, z } from 'astro:content';
+ * import { buildBlogPostCollectionConfig } from '@wildo-ai/saas-website/mdx';
+ *
+ * export const collections = {
+ *   blog: defineCollection({
+ *     type: 'content',
+ *     ...buildBlogPostCollectionConfig({ astroZ: z }),
+ *   }),
+ * };
+ * ```
+ *
+ * The consumer passes Astro's own `z` in (because the engine cannot
+ * import `astro:content` — that virtual module only exists inside
+ * the Astro build context, never at the engine package's compile
+ * time, and importing it would also pull `astro` into the engine's
+ * walked closure which the bundle-isolation test forbids). The engine
+ * builds a passthrough `z.object({}).passthrough()` from the supplied
+ * factory and returns the schema slot.
+ *
+ * # `parseBlogPostFrontmatter`
+ *
+ * Companion render-time validator. Called at the top of `<BlogPost>`
+ * with the raw `entry.data` Astro hands the page; returns the
+ * branded, validated `BlogPostFrontmatter` (Zod 4) or throws with
+ * the standard Zod-4 issue formatting + a `[blog-post]` prefix that
+ * tells the SSG operator which file to fix.
+ *
+ * # Boundary
+ *
+ * This file is React-runtime-safe: it only imports the (also
+ * React-safe) `BlogPostFrontmatterSchema` from `schemas/blog/`. It
+ * ships into the React-island bundle via the `mdx.ts` barrel, which
+ * the bundle-isolation test walks as a dedicated entry. Helpers that
+ * parse raw MDX source live in `blog-post-frontmatter-source.ts` so the
+ * `yaml` package stays on the build-time/Node side of the boundary.
+ */
+
+/**
+ * Minimal contract for the Astro-side Zod factory we accept. Typed
+ * structurally (rather than imported from `astro:content`) so the
+ * engine package can compile/test without an Astro install. Astro's
+ * actual `z.object` returns a much richer Zod-3 schema; we narrow to
+ * just the `.passthrough()` call we make below.
+ */
+export interface AstroZodFactoryShape {
+  object: (shape: Record<string, never>) => {
+    passthrough: () => unknown;
+  };
+}
+
+export interface BuildBlogPostCollectionConfigOptions {
+  /**
+   * Astro's bundled `z` object — pass `import { z } from 'astro:content'`
+   * from the consumer-side `src/content/config.ts`. The engine cannot
+   * import `astro:content` itself (virtual module, only present inside
+   * the Astro build pipeline; would also bloat the bundle-isolation
+   * walked closure with the `astro` runtime).
+   */
+  astroZ: AstroZodFactoryShape;
+}
+
+export interface BlogPostCollectionConfigShape {
+  /**
+   * The schema slot consumed by Astro's `defineCollection({...})`.
+   * A `passthrough` record (no field constraints at this layer) so
+   * Astro accepts any frontmatter; the strict Zod-4 validation runs
+   * at render time inside `<BlogPost>` via
+   * `parseBlogPostFrontmatter(...)`.
+   */
+  schema: unknown;
+}
+
+export function buildBlogPostCollectionConfig(
+  opts: BuildBlogPostCollectionConfigOptions,
+): BlogPostCollectionConfigShape {
+  const { astroZ } = opts;
+  return {
+    schema: astroZ.object({}).passthrough(),
+  };
+}
+
+/**
+ * Strict Zod-4 validator for blog-post frontmatter. Called at the top
+ * of `<BlogPost>` rendering against `entry.data` (whatever Astro's
+ * passthrough collection schema accepted). Throws on validation
+ * failure with a `[blog-post]`-prefixed message that points to the
+ * offending file via the surrounding render call site.
+ *
+ * @param raw — the unvalidated frontmatter object Astro supplies
+ *   (`entry.data` from `getEntry('blog', slug)` or `getCollection('blog')`).
+ * @param ctx — diagnostic context appended to the error message so
+ *   the consumer can find the failing source file when SSG halts.
+ *   Optional but recommended.
+ */
+export interface ParseBlogPostFrontmatterContext {
+  /**
+   * The MDX file's path or slug. Echoed into the error message when
+   * validation fails so the operator can grep for it. Astro typically
+   * gives consumers `entry.id` (the slug + extension) — passing it
+   * through here is enough for an actionable error.
+   */
+  readonly source?: string;
+}
+
+export function parseBlogPostFrontmatter(
+  raw: unknown,
+  ctx: ParseBlogPostFrontmatterContext = {},
+): BlogPostFrontmatter {
+  const result = BlogPostFrontmatterSchema.safeParse(raw);
+  if (result.success) {
+    return result.data;
+  }
+  const sourceSuffix = ctx.source !== undefined ? ` (source="${ctx.source}")` : '';
+  /**
+   * Zod 4's `result.error.message` is the JSON-stringified `issues[]` array —
+   * long-form, it floods the Astro build log, and the path is what an operator
+   * needs to find the broken frontmatter field. `formatZodIssues` is the
+   * framework-canonical rendering (one `path: message` per entry); we only own
+   * the bullet prefix. Unbounded on purpose: every bad field in a post should
+   * be fixable from one build run.
+   */
+  const issueLines = formatZodIssues(result.error.issues).map((entry) => `  - ${entry}`);
+  throw new Error(
+    `[blog-post] Frontmatter failed BlogPostFrontmatterSchema validation${sourceSuffix}:\n${issueLines.join('\n')}`,
+  );
+}
+/** @wildo_source:part:end saas.website.blog.collection-config */

package/src/mdx/blog-post-frontmatter-source.ts

@@ -0,0 +1,31 @@
+import { parse as parseYaml } from 'yaml';
+
+import {
+  parseBlogPostFrontmatter,
+  type ParseBlogPostFrontmatterContext,
+} from './blog-post-collection.config';
+import type { BlogPostFrontmatter } from '../schemas/blog/blog-post-frontmatter.shared.schemas';
+
+/**
+ * Build-time helper for code that reads raw MDX files from disk and
+ * needs the canonical Zod-4 blog frontmatter validation. This module is
+ * intentionally kept out of `@wildo-ai/saas-website/mdx`, because its
+ * `yaml` dependency belongs to the Node/build-time graph, not the
+ * React-island bundle walked by the D12 isolation test.
+ */
+export type ParseBlogPostFrontmatterFromMdxSourceContext = ParseBlogPostFrontmatterContext;
+
+export function parseBlogPostFrontmatterFromMdxSource(
+  source: string,
+  ctx: ParseBlogPostFrontmatterFromMdxSourceContext = {},
+): BlogPostFrontmatter {
+  const normalizedSource = source.replace(/\r\n/g, '\n');
+  const match = normalizedSource.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  if (!match) {
+    const sourceSuffix = ctx.source !== undefined ? ` (source="${ctx.source}")` : '';
+    throw new Error(`[blog-post] MDX file is missing YAML frontmatter${sourceSuffix}.`);
+  }
+
+  const rawFrontmatter = parseYaml(match[1]);
+  return parseBlogPostFrontmatter(rawFrontmatter, ctx);
+}

package/src/mdx/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Sub-barrel for the marketing-blog MDX adapter (Phase 7). Re-exports
+ * the three engine surfaces consumers wire up:
+ *
+ *   - `<BlogPost>` — the per-post page renderer that strict-validates
+ *     frontmatter + composes `WebsitePageLayout` + `WebsiteMdxProvider`.
+ *   - `<WebsiteMdxProvider>` — the `@mdx-js/react` boundary the
+ *     framework owns so the upstream package is swap-safe.
+ *   - `buildBlogPostCollectionConfig(...)` + `parseBlogPostFrontmatter(...)`
+ *     — the Astro content-collection bridge (Path Z passthrough at the
+ *     collection layer, strict Zod-4 validation at render time). Raw
+ *     MDX-source parsing is exported separately from `./mdx-source` so
+ *     `yaml` stays out of the React-island graph.
+ *
+ * Re-exported through the top-level `mdx.ts` barrel so the public
+ * import surface is `'@wildo-ai/saas-website/mdx'` (matching the
+ * `astro.ts` / `astro-island.ts` naming pattern).
+ */
+
+export {
+  BlogPost,
+  BLOG_POST_PAGE_REF,
+  type BlogPostProps,
+  type BlogPostMdxComponents,
+  type BlogPostMdxComponent,
+} from './BlogPost';
+export {
+  buildBlogPostCollectionConfig,
+  parseBlogPostFrontmatter,
+  type AstroZodFactoryShape,
+  type BuildBlogPostCollectionConfigOptions,
+  type BlogPostCollectionConfigShape,
+  type ParseBlogPostFrontmatterContext,
+} from './blog-post-collection.config';
+export {
+  WebsiteMdxProvider,
+  type WebsiteMdxComponentsMap,
+  type WebsiteMdxProviderProps,
+} from './website-mdx-provider';