@wildo-ai/saas-website 1.1.1

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

@@ -0,0 +1,95 @@
+import type { ComponentType, ReactNode } from 'react';
+
+import { MDXProvider } from '@mdx-js/react';
+
+/**
+ * @wildo_source:part:start saas.website.blog.mdx-provider facet:layer:mdx facet:family:website
+ *
+ * `WebsiteMdxProvider` — thin wrapper around `@mdx-js/react`'s
+ * `MDXProvider` that scopes a consumer-supplied `components` map for
+ * the entire MDX subtree it wraps.
+ *
+ * # Why a framework wrapper at all (vs. consumers using `MDXProvider` directly)
+ *
+ * Three application-facing reasons:
+ *
+ *   1. **Single API surface for embedded business sections.** The framework
+ *      owns the provider boundary so consumers
+ *      never directly import from `@mdx-js/react` — they ship a single
+ *      `mdxComponents` object literal and the framework picks the
+ *      provider implementation. If `@mdx-js/react` ever splits its
+ *      package or changes its provider semantics (it has shipped
+ *      breaking changes between major versions before), the swap
+ *      lands in this file with zero consumer churn.
+ *   2. **Bundle-isolation discipline.** `@mdx-js/react` is browser-safe
+ *      but heavy (`mdx/types.js`, `react-context` propagation). Walling
+ *      it behind a single re-export keeps the import surface auditable
+ *      through the package's client-bundle boundary: the `mdx` public entry is
+ *      checked separately and lists `@mdx-js/react` exactly once.
+ *   3. **`disableParentContext: false` (default) is the right default.**
+ *      MDX 3 lets a nested `MDXProvider` inherit components from the
+ *      parent provider, which is what we want when the per-blog-post
+ *      provider sits inside a site-wide MDX provider used by landing-page
+ *      islands.
+ *      Pinning the option here makes the framework's posture explicit;
+ *      a future change documents itself as a breaking framework decision
+ *      rather than a silent `@mdx-js/react` default flip.
+ *
+ * # The `components` map shape
+ *
+ * The map is `Record<string, ComponentType<any>>` — every key is the
+ * tag name an MDX file uses (`<CTASection ref="post-cta" />` resolves
+ * via the `CTASection` key). Values are React components the consumer
+ * authored under their own `src/sections/blog.sections.tsx` and
+ * wrapped in `<WebsiteSection sectionRef={…} category={…}>` so the
+ * label-key context is established before the section's
+ * `useWebsiteLabel(slot)` calls fire. The framework does NOT inspect
+ * the shape — discipline lives in the consumer's section registry
+ * + the label-pack validation boundary (which proves the locale pack covers
+ * each section's expected keys).
+ *
+ * # Why a `ComponentType<any>` value type and not a stricter generic
+ *
+ * MDX components receive their own props (children, plus whatever the
+ * MDX author writes inline as JSX attributes). The type system cannot
+ * narrow this through the provider boundary because the MDX compiler
+ * does the routing at compile time. `ComponentType<any>` is the
+ * convention `@mdx-js/react` itself uses (`MDXComponents` in
+ * `mdx/types.js`) — staying compatible with the upstream type avoids
+ * a wrap/unwrap dance at every consumer call site.
+ *
+ * # Bundle boundary
+ *
+ * Ships into the React-island bundle (consumed transitively from
+ * `BlogPost.tsx` which itself sits behind the consumer's per-page
+ * bridge file). MUST stay clear of `node:*` and SSR-tier specifiers
+ * — the bundle-isolation test walks `mdx.ts` as one of its entries.
+ */
+export interface WebsiteMdxComponentsMap {
+  /**
+   * Tag-name → component map. The MDX compiler resolves each
+   * `<TagName />` in a blog post's body against this object.
+   */
+  readonly [tagName: string]: ComponentType<any>;
+}
+
+export interface WebsiteMdxProviderProps {
+  /**
+   * Consumer-supplied component overrides. Keys are MDX tag names;
+   * values are the React components those tags resolve to.
+   */
+  components: WebsiteMdxComponentsMap;
+  /**
+   * MDX subtree (typically the compiled `<MdxBody/>` from a content
+   * collection entry). May render any number of provider-scoped
+   * components.
+   */
+  children: ReactNode;
+}
+
+export function WebsiteMdxProvider(props: WebsiteMdxProviderProps): ReactNode {
+  const { components, children } = props;
+  return <MDXProvider components={components}>{children}</MDXProvider>;
+}
+WebsiteMdxProvider.displayName = 'WebsiteMdxProvider';
+/** @wildo_source:part:end saas.website.blog.mdx-provider */

package/src/mdx.ts

@@ -0,0 +1,38 @@
+/**
+ * Top-level barrel for the marketing-blog MDX adapter (Phase 7).
+ *
+ * # Why a dedicated subpath instead of folding into the root barrel
+ *
+ * `@wildo-ai/saas-website/mdx` ships into the React-island bundle
+ * (consumed transitively from a consumer's per-post `.astro` page
+ * which imports `<BlogPost>` and renders it client-side). The
+ * `@mdx-js/react` runtime adds non-trivial weight to the closure;
+ * isolating the entry behind a dedicated subpath:
+ *
+ *   - keeps `index.ts` (the Node + React companion-runtime entry) free
+ *     of MDX runtime dependencies for sites that ship landing-page-only
+ *     marketing surfaces;
+ *   - lets the bundle-isolation test walk this entry independently
+ *     (see `engine/saas-website/src/__tests__/bundle-isolation.test.ts`
+ *     `ENTRY_FILES` list) so an accidental `node:fs` import inside
+ *     `BlogPost.tsx` regresses against the React-bundle constraint
+ *     without polluting the other entries' allow-lists.
+ *
+ * Pattern mirrors `astro.ts` / `astro-island.ts` / `config-loader.ts`:
+ * one purpose, one barrel, one bundle-isolation entry.
+ */
+
+export * from './mdx/index';
+/**
+ * The blog adapter's per-locale bridge factory
+ * (`createWebsiteBlogPostBridgeIsland`). Lives in `astro/` beside
+ * `bridge-runtime.tsx` (same closure-over-deps pattern) but is exported
+ * from THIS entry — not `astro-island.ts` — because it hard-imports
+ * `./mdx/BlogPost`, whose `@mdx-js/react` peer is optional. Exporting it
+ * from the mandatory per-page bridge entry made the optional peer a
+ * de-facto install requirement for every non-blog site (Vite resolves the
+ * whole `export *` graph before tree-shaking). Here, only sites that opt
+ * into the blog adapter — and therefore install `@astrojs/mdx` +
+ * `@mdx-js/react` — ever resolve it.
+ */
+export * from './astro/blog-post-bridge';

package/src/schemas/__tests__/blog-frontmatter.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import { BlogPostFrontmatterSchema } from '../blog/blog-post-frontmatter.shared.schemas';
+
+const VALID_INPUT = {
+  title: 'Why context windows matter for agentic UX',
+  summary: 'A short, focused summary of the post for OG / meta description.',
+  slug: 'why-context-matters',
+  locale: AvailableLanguage.EN,
+  publishedAt: '2026-04-17T10:30:00.000Z',
+  authorRef: 'paul-cayon',
+  tags: ['agents', 'ux'],
+};
+
+describe('BlogPostFrontmatterSchema', () => {
+  it('parses a well-formed frontmatter', () => {
+    const parsed = BlogPostFrontmatterSchema.parse(VALID_INPUT);
+    expect(parsed.slug).toBe('why-context-matters');
+    expect(parsed.tags).toHaveLength(2);
+  });
+
+  it('rejects malformed slug / authorRef / tags', () => {
+    expect(() =>
+      BlogPostFrontmatterSchema.parse({ ...VALID_INPUT, slug: 'Why-Context-Matters' }),
+    ).toThrow();
+    expect(() =>
+      BlogPostFrontmatterSchema.parse({ ...VALID_INPUT, authorRef: 'Paul Cayon' }),
+    ).toThrow();
+    expect(() =>
+      BlogPostFrontmatterSchema.parse({ ...VALID_INPUT, tags: ['UX'] }),
+    ).toThrow();
+  });
+
+  it('rejects non-ISO publishedAt', () => {
+    expect(() =>
+      BlogPostFrontmatterSchema.parse({ ...VALID_INPUT, publishedAt: '2026-04-17' }),
+    ).toThrow();
+  });
+
+  it('accepts optional coverImageUrl', () => {
+    expect(() =>
+      BlogPostFrontmatterSchema.parse({
+        ...VALID_INPUT,
+        coverImageUrl: 'https://cdn.example.com/blog/why-context.jpg',
+      }),
+    ).not.toThrow();
+  });
+});

package/src/schemas/__tests__/companion-exports-react-free.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Boundary test: importing the companion entry MUST NOT pull React into
+ * the evaluation graph. Implemented via a tracking Proxy installed on
+ * `globalThis` BEFORE the import: any access to a `'react'`-shaped
+ * module would evaluate React's runtime side-effects (which include
+ * registering a `__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED_*`
+ * symbol on the global). We assert no such symbol exists post-import.
+ *
+ * Approach is intentionally indirect — we cannot stub `react` at the
+ * Vitest bundler level without losing the boundary check we want to
+ * make. Checking the global symbol is React's own canary for
+ * "React's runtime has been evaluated".
+ */
+describe('companion-exports React-free boundary', () => {
+  it('does not boot React when imported in a Node-only context', async () => {
+    const reactCanaryBefore = Object.getOwnPropertySymbols(globalThis).filter((s) =>
+      String(s).includes('react'),
+    );
+    const reactGlobalsBefore = Object.keys(globalThis).filter((k) =>
+      k.includes('__REACT_DEVTOOLS_GLOBAL_HOOK__'),
+    );
+
+    await import('../../companion-exports');
+
+    const reactCanaryAfter = Object.getOwnPropertySymbols(globalThis).filter((s) =>
+      String(s).includes('react'),
+    );
+    const reactGlobalsAfter = Object.keys(globalThis).filter((k) =>
+      k.includes('__REACT_DEVTOOLS_GLOBAL_HOOK__'),
+    );
+
+    expect(reactCanaryAfter).toEqual(reactCanaryBefore);
+    expect(reactGlobalsAfter).toEqual(reactGlobalsBefore);
+  });
+
+  it('exposes the expected schema surface', async () => {
+    const mod = await import('../../companion-exports');
+    expect(mod.WebsitePageRefSchema).toBeDefined();
+    expect(mod.WebsiteSectionRefSchema).toBeDefined();
+    expect(mod.WebsiteLabelKeySchema).toBeDefined();
+    expect(mod.WebsiteSectionCategorySchema).toBeDefined();
+    expect(mod.WebsiteSectionDefinitionSchema).toBeDefined();
+    expect(mod.WebsiteDesignTokensSchema).toBeDefined();
+    expect(mod.WebsitePageManifestSchema).toBeDefined();
+    expect(mod.WebsiteRootConfigSchema).toBeDefined();
+    expect(mod.BlogPostFrontmatterSchema).toBeDefined();
+    expect(mod.validateLabelPackAgainstManifest).toBeDefined();
+  });
+});

package/src/schemas/__tests__/design-tokens.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  WebsiteColorTokensSchema,
+  WebsiteDesignTokensSchema,
+  WebsiteRadiusTokensSchema,
+} from '../design-tokens/website-design-tokens.shared.schemas';
+
+describe('WebsiteColorTokensSchema', () => {
+  it('parses every required token as a non-empty string', () => {
+    const tokens = {
+      background: '#fff',
+      foreground: '#111',
+      primary: 'oklch(0.7 0.1 200)',
+      primaryForeground: '#fff',
+      accent: 'rgb(255 94 91)',
+      accentForeground: '#fff',
+      surface: 'var(--brand-surface)',
+      surfaceForeground: '#111',
+      border: '#e5e5e5',
+      muted: '#f5f5f5',
+      mutedForeground: 'currentColor',
+    };
+    expect(() => WebsiteColorTokensSchema.parse(tokens)).not.toThrow();
+  });
+
+  it('rejects empty strings', () => {
+    expect(() =>
+      WebsiteColorTokensSchema.parse({
+        background: '',
+        foreground: '#111',
+        primary: '#0070f3',
+        primaryForeground: '#fff',
+        accent: '#ff5e5b',
+        accentForeground: '#fff',
+        surface: '#fafafa',
+        surfaceForeground: '#111',
+        border: '#e5e5e5',
+        muted: '#f5f5f5',
+        mutedForeground: '#737373',
+      }),
+    ).toThrow();
+  });
+});
+
+describe('WebsiteRadiusTokensSchema', () => {
+  it('parses every required token as a non-empty string', () => {
+    expect(() =>
+      WebsiteRadiusTokensSchema.parse({
+        none: '0',
+        sm: '0.125rem',
+        md: '0.375rem',
+        lg: '0.75rem',
+        xl: '1.5rem',
+        full: '9999px',
+      }),
+    ).not.toThrow();
+  });
+});
+
+describe('CSS-injection guard on token values (Phase 6 fix H-α)', () => {
+  const validRadii = {
+    none: '0',
+    sm: '0.125rem',
+    md: '0.375rem',
+    lg: '0.75rem',
+    xl: '1.5rem',
+    full: '9999px',
+  };
+  const validColors = {
+    background: '#fff',
+    foreground: '#111',
+    primary: '#0070f3',
+    primaryForeground: '#fff',
+    accent: '#ff5e5b',
+    accentForeground: '#fff',
+    surface: '#fafafa',
+    surfaceForeground: '#111',
+    border: '#e5e5e5',
+    muted: '#f5f5f5',
+    mutedForeground: '#737373',
+  };
+
+  it.each([
+    ['semicolon', 'red; color: blue'],
+    ['close-brace', 'red } body { display: none'],
+    ['open-brace', 'red { hack: 1'],
+    ['block-comment-open', 'red /* hack'],
+    ['block-comment-close', 'red */ hack'],
+    ['newline', 'red\nfake: 1'],
+    ['carriage-return', 'red\rfake: 1'],
+  ])('rejects color values containing %s', (_name, value) => {
+    expect(() =>
+      WebsiteColorTokensSchema.parse({ ...validColors, primary: value }),
+    ).toThrow();
+  });
+
+  it.each([
+    ['style-element terminator', '#fff</style><svg onload=alert(1)>'],
+    ['raw open-angle-bracket', '#fff<script'],
+    ['raw close-angle-bracket', '#fff>hack'],
+  ])(
+    'rejects color values containing HTML break-out metacharacters (%s) — Phase 6 fourth audit fix H-Χ',
+    (_name, value) => {
+      expect(() =>
+        WebsiteColorTokensSchema.parse({ ...validColors, primary: value }),
+      ).toThrow();
+    },
+  );
+
+  it.each([
+    ['semicolon', '0.5rem; color: red'],
+    ['close-brace', '0.5rem }'],
+    ['block-comment-open', '0.5rem /*'],
+    ['style-element terminator (H-Χ)', '0.5rem</style>'],
+    ['raw open-angle-bracket (H-Χ)', '0.5rem<'],
+    ['raw close-angle-bracket (H-Χ)', '0.5rem>'],
+  ])('rejects radius values containing %s', (_name, value) => {
+    expect(() => WebsiteRadiusTokensSchema.parse({ ...validRadii, md: value })).toThrow();
+  });
+
+  it('accepts legitimate var() references with parentheses (no metacharacters)', () => {
+    expect(() =>
+      WebsiteColorTokensSchema.parse({ ...validColors, primary: 'var(--brand-primary)' }),
+    ).not.toThrow();
+  });
+
+  it('accepts oklch() functional notation', () => {
+    expect(() =>
+      WebsiteColorTokensSchema.parse({ ...validColors, primary: 'oklch(0.7 0.1 200 / 0.5)' }),
+    ).not.toThrow();
+  });
+});
+
+describe('WebsiteDesignTokensSchema', () => {
+  it('parses the colors+radii bundle', () => {
+    const parsed = WebsiteDesignTokensSchema.parse({
+      colors: {
+        background: '#fff',
+        foreground: '#111',
+        primary: '#0070f3',
+        primaryForeground: '#fff',
+        accent: '#ff5e5b',
+        accentForeground: '#fff',
+        surface: '#fafafa',
+        surfaceForeground: '#111',
+        border: '#e5e5e5',
+        muted: '#f5f5f5',
+        mutedForeground: '#737373',
+      },
+      radii: {
+        none: '0',
+        sm: '0.125rem',
+        md: '0.375rem',
+        lg: '0.75rem',
+        xl: '1.5rem',
+        full: '9999px',
+      },
+    });
+    expect(parsed.colors.primary).toBe('#0070f3');
+    expect(parsed.radii.full).toBe('9999px');
+  });
+});

package/src/schemas/__tests__/label-key.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  WebsiteLabelKeySchema,
+  composeWebsiteLabelKey,
+} from '../label-keys/website-label-key.schemas';
+import { WebsitePageRefSchema } from '../refs/page-ref.schemas';
+import { WebsiteSectionRefSchema } from '../refs/section-ref.schemas';
+
+describe('WebsiteLabelKeySchema', () => {
+  it('accepts simple page.section.slot keys', () => {
+    expect(WebsiteLabelKeySchema.parse('website.landing.hero.headline')).toBe(
+      'website.landing.hero.headline',
+    );
+  });
+
+  it('accepts dot-nested and bracket-indexed slots', () => {
+    expect(WebsiteLabelKeySchema.parse('website.landing.hero.cta.primary')).toBeDefined();
+    expect(WebsiteLabelKeySchema.parse('website.pricing.tiers.tiers[0].name')).toBeDefined();
+    expect(
+      WebsiteLabelKeySchema.parse('website.contact.form.field.email-placeholder'),
+    ).toBeDefined();
+  });
+
+  it('rejects non-website prefixes and missing parts', () => {
+    expect(() => WebsiteLabelKeySchema.parse('app.landing.hero.headline')).toThrow();
+    expect(() => WebsiteLabelKeySchema.parse('website.landing.hero')).toThrow();
+    expect(() => WebsiteLabelKeySchema.parse('website..hero.headline')).toThrow();
+    expect(() => WebsiteLabelKeySchema.parse('website.Landing.hero.headline')).toThrow();
+  });
+});
+
+describe('composeWebsiteLabelKey', () => {
+  it('round-trips through the full ref → key pipeline', () => {
+    const pageRef = WebsitePageRefSchema.parse('landing');
+    const sectionRef = WebsiteSectionRefSchema.parse('hero');
+    const key = composeWebsiteLabelKey({ pageRef, sectionRef, slotPath: 'headline' });
+    expect(key).toBe('website.landing.hero.headline');
+  });
+
+  it('throws on stale refs that would compose an invalid key', () => {
+    expect(() =>
+      composeWebsiteLabelKey({ pageRef: 'Landing', sectionRef: 'hero', slotPath: 'headline' }),
+    ).toThrow();
+  });
+});

package/src/schemas/__tests__/label-pack-validator.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest';
+
+import { WebsiteLabelKeySchema, type WebsiteLabelKey } from '../label-keys/website-label-key.schemas';
+import { WebsitePageManifestSchema, type WebsitePageManifest } from '../manifests/website-page-manifest.shared.schemas';
+import { WebsitePageRefSchema } from '../refs/page-ref.schemas';
+import { WebsiteSectionRefSchema } from '../refs/section-ref.schemas';
+import {
+  validateLabelPackAgainstManifest,
+  type ExpectedLabelKeysBySectionRef,
+  type LabelPack,
+} from '../validators/label-pack.validator';
+
+const NoopComponent = () => null;
+
+const HERO_REF = WebsiteSectionRefSchema.parse('hero');
+const CTA_REF = WebsiteSectionRefSchema.parse('cta');
+
+const HERO_KEYS: readonly WebsiteLabelKey[] = [
+  WebsiteLabelKeySchema.parse('website.landing.hero.headline'),
+  WebsiteLabelKeySchema.parse('website.landing.hero.subheadline'),
+];
+const CTA_KEYS: readonly WebsiteLabelKey[] = [
+  WebsiteLabelKeySchema.parse('website.landing.cta.headline'),
+  WebsiteLabelKeySchema.parse('website.landing.cta.primary-cta'),
+];
+
+// The SCHEMA infers `pageComponent` as `unknown` (it is validated as an opaque value), while the
+// declared `WebsitePageManifest` the validator takes says `ComponentType`. The parse still runs —
+// this fixture is checked against the schema — and the annotation names the one field on which
+// the two disagree.
+const MANIFEST: WebsitePageManifest = WebsitePageManifestSchema.parse({
+  ref: WebsitePageRefSchema.parse('landing'),
+  routePath: '/',
+  pageComponent: NoopComponent,
+  sectionRefs: [HERO_REF, CTA_REF],
+  metaLabelKeys: {
+    titleKey: WebsiteLabelKeySchema.parse('website.landing.meta.title'),
+    descriptionKey: WebsiteLabelKeySchema.parse('website.landing.meta.description'),
+  },
+}) as WebsitePageManifest;
+
+const EXPECTED: ExpectedLabelKeysBySectionRef = new Map([
+  [HERO_REF, HERO_KEYS],
+  [CTA_REF, CTA_KEYS],
+]);
+
+describe('validateLabelPackAgainstManifest', () => {
+  it('returns empty diagnostics for a complete pack', () => {
+    const pack: LabelPack = {
+      'website.landing.meta.title': 'Welcome',
+      'website.landing.meta.description': 'A great product',
+      'website.landing.hero.headline': 'Hello',
+      'website.landing.hero.subheadline': 'World',
+      'website.landing.cta.headline': 'Try now',
+      'website.landing.cta.primary-cta': 'Sign up',
+    };
+    const result = validateLabelPackAgainstManifest([MANIFEST], EXPECTED, pack);
+    expect(result.missing).toEqual([]);
+    expect(result.orphaned).toEqual([]);
+    expect(result.unmappedSectionRefs).toEqual([]);
+  });
+
+  it('reports missing keys (sorted)', () => {
+    const pack: LabelPack = {
+      'website.landing.meta.title': 'Welcome',
+      'website.landing.meta.description': 'A great product',
+      'website.landing.hero.headline': 'Hello',
+    };
+    const result = validateLabelPackAgainstManifest([MANIFEST], EXPECTED, pack);
+    expect(result.missing).toEqual([
+      'website.landing.cta.headline',
+      'website.landing.cta.primary-cta',
+      'website.landing.hero.subheadline',
+    ]);
+    expect(result.orphaned).toEqual([]);
+  });
+
+  it('reports orphaned keys (sorted)', () => {
+    const pack: LabelPack = {
+      'website.landing.meta.title': 'Welcome',
+      'website.landing.meta.description': 'A great product',
+      'website.landing.hero.headline': 'Hello',
+      'website.landing.hero.subheadline': 'World',
+      'website.landing.cta.headline': 'Try now',
+      'website.landing.cta.primary-cta': 'Sign up',
+      'website.landing.hero.stale-key-1': 'orphan',
+      'website.landing.cta.stale-key-2': 'orphan',
+    };
+    const result = validateLabelPackAgainstManifest([MANIFEST], EXPECTED, pack);
+    expect(result.missing).toEqual([]);
+    expect(result.orphaned).toEqual([
+      'website.landing.cta.stale-key-2',
+      'website.landing.hero.stale-key-1',
+    ]);
+  });
+
+  it('surfaces unmapped section refs separately from missing keys', () => {
+    const expectedPartial: ExpectedLabelKeysBySectionRef = new Map([[HERO_REF, HERO_KEYS]]);
+    const pack: LabelPack = {
+      'website.landing.meta.title': 'Welcome',
+      'website.landing.meta.description': 'A great product',
+      'website.landing.hero.headline': 'Hello',
+      'website.landing.hero.subheadline': 'World',
+    };
+    const result = validateLabelPackAgainstManifest([MANIFEST], expectedPartial, pack);
+    expect(result.unmappedSectionRefs).toEqual([CTA_REF]);
+    expect(result.missing).toEqual([]);
+    expect(result.orphaned).toEqual([]);
+  });
+
+  it('treats chromeLabelKeys as expected — declared chrome keys are NOT orphaned', () => {
+    const chromeKeys: readonly WebsiteLabelKey[] = [
+      WebsiteLabelKeySchema.parse('website.chrome.header.brand'),
+      WebsiteLabelKeySchema.parse('website.chrome.footer.copyright'),
+    ];
+    const pack: LabelPack = {
+      'website.landing.meta.title': 'Welcome',
+      'website.landing.meta.description': 'A great product',
+      'website.landing.hero.headline': 'Hello',
+      'website.landing.hero.subheadline': 'World',
+      'website.landing.cta.headline': 'Try now',
+      'website.landing.cta.primary-cta': 'Sign up',
+      'website.chrome.header.brand': 'Acme',
+      'website.chrome.footer.copyright': '© 2026',
+    };
+    const result = validateLabelPackAgainstManifest([MANIFEST], EXPECTED, pack, chromeKeys);
+    expect(result.missing).toEqual([]);
+    expect(result.orphaned).toEqual([]);
+  });
+
+  it('reports missing chromeLabelKeys alongside missing section keys', () => {
+    const chromeKeys: readonly WebsiteLabelKey[] = [
+      WebsiteLabelKeySchema.parse('website.chrome.header.brand'),
+    ];
+    const pack: LabelPack = {
+      'website.landing.meta.title': 'Welcome',
+      'website.landing.meta.description': 'A great product',
+      'website.landing.hero.headline': 'Hello',
+      'website.landing.hero.subheadline': 'World',
+      'website.landing.cta.headline': 'Try now',
+      'website.landing.cta.primary-cta': 'Sign up',
+    };
+    const result = validateLabelPackAgainstManifest([MANIFEST], EXPECTED, pack, chromeKeys);
+    expect(result.missing).toEqual(['website.chrome.header.brand']);
+  });
+});

package/src/schemas/__tests__/page-manifest.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+
+import { WebsiteLabelKeySchema } from '../label-keys/website-label-key.schemas';
+import { WebsitePageManifestSchema } from '../manifests/website-page-manifest.shared.schemas';
+import { WebsitePageRefSchema } from '../refs/page-ref.schemas';
+import { WebsiteSectionRefSchema } from '../refs/section-ref.schemas';
+
+const NoopPageComponent = () => null;
+
+const VALID_MANIFEST_INPUT = {
+  ref: WebsitePageRefSchema.parse('landing'),
+  routePath: '/' as unknown,
+  pageComponent: NoopPageComponent,
+  sectionRefs: [WebsiteSectionRefSchema.parse('hero'), WebsiteSectionRefSchema.parse('cta')],
+  metaLabelKeys: {
+    titleKey: WebsiteLabelKeySchema.parse('website.landing.meta.title'),
+    descriptionKey: WebsiteLabelKeySchema.parse('website.landing.meta.description'),
+  },
+};
+
+describe('WebsitePageManifestSchema', () => {
+  it('parses a well-formed manifest', () => {
+    const parsed = WebsitePageManifestSchema.parse(VALID_MANIFEST_INPUT);
+    expect(parsed.ref).toBe('landing');
+    expect(parsed.sectionRefs).toHaveLength(2);
+  });
+
+  it('parses Astro-style parameter routes', () => {
+    expect(() =>
+      WebsitePageManifestSchema.parse({
+        ...VALID_MANIFEST_INPUT,
+        routePath: '/blog/[slug]',
+      }),
+    ).not.toThrow();
+  });
+
+  it('rejects duplicate section refs', () => {
+    expect(() =>
+      WebsitePageManifestSchema.parse({
+        ...VALID_MANIFEST_INPUT,
+        sectionRefs: [WebsiteSectionRefSchema.parse('hero'), WebsiteSectionRefSchema.parse('hero')],
+      }),
+    ).toThrow(/Duplicate sectionRef/);
+  });
+
+  it('rejects meta label keys not rooted under the page ref', () => {
+    expect(() =>
+      WebsitePageManifestSchema.parse({
+        ...VALID_MANIFEST_INPUT,
+        metaLabelKeys: {
+          titleKey: WebsiteLabelKeySchema.parse('website.pricing.meta.title'),
+          descriptionKey: WebsiteLabelKeySchema.parse('website.landing.meta.description'),
+        },
+      }),
+    ).toThrow(/must be rooted under the page ref/);
+  });
+
+  it('rejects empty section ref lists', () => {
+    expect(() =>
+      WebsitePageManifestSchema.parse({
+        ...VALID_MANIFEST_INPUT,
+        sectionRefs: [],
+      }),
+    ).toThrow();
+  });
+});