@wildo-ai/saas-website 1.1.1

package/src/schemas/design-tokens/website-design-tokens.shared.schemas.ts

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+
+/**
+ * CSS-injection-safe value validator shared by every design-token field.
+ *
+ * **Threat model** — TWO escape surfaces, BOTH covered:
+ *
+ *   1. CSS *declaration* break-out (Phase 6 third audit fix H-α):
+ *      the renderer `renderWebsiteDesignTokensCss` interpolates token
+ *      values **raw** into a `:root { --website-<group>-<token>: <value>; }`
+ *      block. A value containing any of `;`, `}`, `{`, `/*`, `*\/`, or a
+ *      newline can break out of the property declaration and inject
+ *      arbitrary CSS — at minimum a config typo silently corrupts the
+ *      page; at worst a malicious or untrusted config author injects a
+ *      `body { display: none; }` rule that blanks the entire site.
+ *
+ *   2. HTML *style-element* break-out (Phase 6 fourth audit fix H-Χ):
+ *      the rendered `:root { ... }` block is itself wrapped in an inline
+ *      `<style>…</style>` element by the head renderer. Per the HTML spec
+ *      the `<style>` element is a *raw-text* element — its only
+ *      terminator is the literal sequence `</style`. A token value
+ *      containing `<` (or, for symmetry, `>`) can therefore close the
+ *      `<style>` element early and follow up with `<svg onload=alert(1)>`
+ *      or any other HTML / JS payload, which the H-α deny-list (which
+ *      did NOT forbid `<` / `>`) failed to catch. CSS values legitimately
+ *      need NEITHER `<` NOR `>` (no CSS grammar uses them — no color,
+ *      length, variable reference, calc expression, or functional
+ *      notation does), so denying both is conservative and correct.
+ *
+ * **Why validate at the schema layer (not inside the renderer)**:
+ *   1. Fail at config load (build-time / boot-time), not at every
+ *      `<head>` render — a malformed token surfaces in the schema-parse
+ *      error message instead of silently emitting broken CSS / HTML.
+ *   2. Single source of truth — every field that flows into the
+ *      `<style>`-wrapped CSS block gets the same guard (impossible to
+ *      add a future token field that bypasses the renderer's escape
+ *      pass).
+ *   3. The renderer stays a simple interpolator, which makes its own
+ *      audit surface trivially small.
+ *
+ * **Why a `.refine` over a strict color-string regex**: colors accept
+ * `currentColor`, named colors, `var(--foo)` references, oklch
+ * functional notation, etc. — a strict positive grammar is ~80 lines
+ * and high-maintenance. A negative deny-list of the eight characters
+ * that are LITERALLY the only ones that can break out of either the CSS
+ * property declaration OR the wrapping `<style>` element is small,
+ * complete, and obviously correct.
+ */
+const CSS_INJECTION_FORBIDDEN_PATTERN = /[;{}<>\n\r]|\/\*|\*\//;
+const cssSafeValue = (fieldName: string): z.ZodString =>
+  z
+    .string()
+    .min(1, { error: `${fieldName} must not be empty` })
+    .refine((value) => !CSS_INJECTION_FORBIDDEN_PATTERN.test(value), {
+      error:
+        `${fieldName} must not contain CSS-injection or HTML break-out ` +
+        `metacharacters (; { } < > /* */ newline) — token values are ` +
+        `interpolated raw into <style>:root { --website-...: <value>; }</style>`,
+    }) as unknown as z.ZodString;
+
+/**
+ * @wildo_source:part:start saas.website.design-tokens.colors facet:layer:shared facet:family:website
+ *
+ * `WebsiteColorTokens` — minimal palette the marketing-site exposes as
+ * CSS custom properties (`--website-color-<token>`) on the
+ * `<WebsitePageLayout>` root.
+ *
+ * **Why a dedicated marketing palette** (vs. reusing
+ * `presets-components-models/design-tokens-config`):
+ *
+ * - The SaaS app's design tokens carry many semantic states (`muted`,
+ *   `destructive`, `ring`, `sidebar-*`, …) that have no marketing-site
+ *   analogue. Forcing the website to consume the full palette would
+ *   leak app-internal semantics into a public surface.
+ * - Marketing pages need *display-grade* colors (heavily branded
+ *   accents, gradient stops, hero-overlay tints) that the SaaS app's
+ *   functional palette deliberately avoids.
+ * - Designers overriding website tokens (Phase 6 dogfood proves this
+ *   path) should not be able to break the SaaS app by editing one
+ *   tailwind.config — the two surfaces stay decoupled.
+ *
+ * **Token format**: every value is a CSS color string. Shape validation
+ * is intentionally permissive (accepts hex, rgb/rgba, hsl/hsla, oklch,
+ * `currentColor`, named colors, CSS variable references) — a strict
+ * color-string regex would reject legitimate values (oklch grammar
+ * alone is ~80 lines) and a malformed-but-syntactically-valid color
+ * fails loudly at render time.
+ *
+ * **What IS strictly enforced**: every value passes `cssSafeValue`,
+ * which rejects the six characters that can break out of a CSS
+ * property declaration (`;`, `{`, `}`, `/*`, `*\/`, newline). See the
+ * `cssSafeValue` JSDoc above for the full threat model.
+ *
+ * **Adding a token**: append the field here using `cssSafeValue(...)`,
+ * document its semantic intent in the JSDoc, and update the matching
+ * CSS-emit helper in Phase 2 (`emitWebsiteColorTokensCss`).
+ */
+const _WebsiteColorTokensSchema = z.object({
+  background: cssSafeValue('background color'),
+  foreground: cssSafeValue('foreground color'),
+  primary: cssSafeValue('primary color'),
+  primaryForeground: cssSafeValue('primaryForeground color'),
+  accent: cssSafeValue('accent color'),
+  accentForeground: cssSafeValue('accentForeground color'),
+  surface: cssSafeValue('surface color'),
+  surfaceForeground: cssSafeValue('surfaceForeground color'),
+  border: cssSafeValue('border color'),
+  muted: cssSafeValue('muted color'),
+  mutedForeground: cssSafeValue('mutedForeground color'),
+});
+
+export const WebsiteColorTokensSchema: typeof _WebsiteColorTokensSchema = _WebsiteColorTokensSchema;
+
+export type WebsiteColorTokens = z.infer<typeof _WebsiteColorTokensSchema>;
+/** @wildo_source:part:end saas.website.design-tokens.colors */
+
+/**
+ * @wildo_source:part:start saas.website.design-tokens.radius facet:layer:shared facet:family:website
+ *
+ * `WebsiteRadiusTokens` — border-radius scale exposed as
+ * `--website-radius-<token>` CSS variables.
+ *
+ * Marketing radii are intentionally a separate token set from the
+ * SaaS app's radii: the website typically wants larger pill / hero
+ * radii than the app's compact-UI radii. Keeping them separate lets
+ * either surface evolve without coupling.
+ *
+ * Values are CSS length strings (`'0.25rem'`, `'12px'`,
+ * `'9999px'`). Same permissive-shape + strict-CSS-injection
+ * rationale as `WebsiteColorTokens` (every value runs through
+ * `cssSafeValue`).
+ */
+const _WebsiteRadiusTokensSchema = z.object({
+  none: cssSafeValue('none radius'),
+  sm: cssSafeValue('sm radius'),
+  md: cssSafeValue('md radius'),
+  lg: cssSafeValue('lg radius'),
+  xl: cssSafeValue('xl radius'),
+  full: cssSafeValue('full radius'),
+});
+
+export const WebsiteRadiusTokensSchema: typeof _WebsiteRadiusTokensSchema = _WebsiteRadiusTokensSchema;
+
+export type WebsiteRadiusTokens = z.infer<typeof _WebsiteRadiusTokensSchema>;
+/** @wildo_source:part:end saas.website.design-tokens.radius */
+
+/**
+ * @wildo_source:part:start saas.website.design-tokens.bundle facet:layer:shared facet:family:website
+ *
+ * `WebsiteDesignTokens` — the complete design-token bundle attached to
+ * `WebsiteRootConfig.designTokens`. Currently colors + radii only
+ * (per plan Phase 1 scope: "WebsiteColorTokensSchema + WebsiteRadiusTokensSchema (only)").
+ *
+ * Future expansions (typography scale, motion tokens, shadow elevation)
+ * will land as additional fields here without breaking the
+ * `WebsiteRootConfig` shape.
+ */
+const _WebsiteDesignTokensSchema = z.object({
+  colors: _WebsiteColorTokensSchema,
+  radii: _WebsiteRadiusTokensSchema,
+});
+
+export const WebsiteDesignTokensSchema: typeof _WebsiteDesignTokensSchema = _WebsiteDesignTokensSchema;
+
+export type WebsiteDesignTokens = z.infer<typeof _WebsiteDesignTokensSchema>;
+/** @wildo_source:part:end saas.website.design-tokens.bundle */

package/src/schemas/label-keys/website-label-key.schemas.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+
+/**
+ * @wildo_source:part:start saas.website.label-keys.format facet:layer:shared facet:family:i18n
+ *
+ * `WebsiteLabelKey` — branded i18n key for marketing-site copy.
+ *
+ * **Format**: `website.<pageRef>.<sectionRef>.<slotPath>`
+ *
+ * - `website.` — fixed namespace prefix that disambiguates marketing-site
+ *   labels from app i18n keys (`labels.`, `errors.`, `notifications.`).
+ *   Marketing-site label packs ship as a separate file per locale
+ *   (`website/src/i18n/<locale>.json`) so they never bloat the SaaS app
+ *   bundle.
+ * - `<pageRef>` — kebab-case page ref (validated independently by
+ *   `WebsitePageRefSchema`).
+ * - `<sectionRef>` — kebab-case section ref (validated independently by
+ *   `WebsiteSectionRefSchema`).
+ * - `<slotPath>` — leaf identifier the section consumes via
+ *   `useWebsiteLabel('<slotPath>')` (Phase 2). Allows dots for nested
+ *   structures (`'cta.primary'`), brackets for indexed array slots
+ *   (`'tiers[0].name'`), and hyphens for multi-word leaves.
+ *
+ * **Examples**:
+ *   - `website.landing.hero.headline`
+ *   - `website.landing.hero.cta.primary`
+ *   - `website.pricing.tiers.tiers[0].name`
+ *   - `website.contact.form.field.email-placeholder`
+ *
+ * **Why a brand**: prevents the "label key as bare string" failure mode
+ * where a typo in `'webiste.landing.hero.headline'` (note the typo) silently
+ * resolves to undefined at runtime. Sections must accept
+ * `WebsiteLabelKey`-typed props; consumers go through
+ * `WebsiteLabelKeySchema.parse(...)` (or the manifest's `metaLabelKeys`
+ * fields, which are typed against this schema) before a string flows into
+ * label resolution.
+ *
+ * **Why a single regex**: the three nested refs (`page`, `section`, `slot`)
+ * are validated separately by their own schemas inside the `defineWebsiteSection`
+ * factory and `WebsitePageManifestSchema`. This schema's job is to validate
+ * a fully-composed key — typically inserted directly into JSX as a string
+ * literal — without re-parsing the parts.
+ */
+const _WebsiteLabelKeySchema = z
+  .string()
+  .min(10, { error: 'WebsiteLabelKey is too short (must include website.<page>.<section>.<slot>)' })
+  .max(256, { error: 'WebsiteLabelKey must be at most 256 characters' })
+  .regex(
+    /^website\.[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*\.[a-zA-Z0-9.\[\]_-]+$/,
+    {
+      error:
+        'WebsiteLabelKey must match `website.<page>.<section>.<slot>` where page/section are kebab-case and slot allows dot/bracket/hyphen/underscore (e.g. "website.landing.hero.headline")',
+    },
+  )
+  .brand<'WebsiteLabelKey'>();
+
+export const WebsiteLabelKeySchema: typeof _WebsiteLabelKeySchema = _WebsiteLabelKeySchema;
+
+export type WebsiteLabelKey = z.infer<typeof _WebsiteLabelKeySchema>;
+/** @wildo_source:part:end saas.website.label-keys.format */
+
+/**
+ * @wildo_source:part:start saas.website.label-keys.compose-helper facet:layer:shared facet:family:i18n
+ *
+ * `composeWebsiteLabelKey` — pure helper that composes a `WebsiteLabelKey`
+ * from its three parts. Used by `useWebsiteLabel` (Phase 2) and by the
+ * label-pack validator to materialize the keys a section commits to.
+ *
+ * Returns the key as a parsed `WebsiteLabelKey` (brand applied), throwing
+ * if the composed string fails the format check (defensive guard against
+ * stale refs / inconsistent slot paths leaking past type-system narrowing).
+ *
+ * @example
+ *   composeWebsiteLabelKey({
+ *     pageRef: WebsitePageRefSchema.parse('landing'),
+ *     sectionRef: WebsiteSectionRefSchema.parse('hero'),
+ *     slotPath: 'headline',
+ *   });
+ *   // -> WebsiteLabelKey ("website.landing.hero.headline")
+ */
+export function composeWebsiteLabelKey(parts: {
+  pageRef: string;
+  sectionRef: string;
+  slotPath: string;
+}): WebsiteLabelKey {
+  return WebsiteLabelKeySchema.parse(`website.${parts.pageRef}.${parts.sectionRef}.${parts.slotPath}`);
+}
+/** @wildo_source:part:end saas.website.label-keys.compose-helper */

package/src/schemas/manifests/website-page-manifest.shared.schemas.ts

@@ -0,0 +1,266 @@
+import type { ComponentType } from 'react';
+import { z } from 'zod';
+
+import { WebsiteLabelKeySchema } from '../label-keys/website-label-key.schemas';
+import { WebsitePageRefSchema } from '../refs/page-ref.schemas';
+import { WebsiteSectionRefSchema } from '../refs/section-ref.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.page-manifest.meta-label-keys facet:layer:shared facet:family:website
+ *
+ * `WebsitePageMetaLabelKeys` — the i18n keys the Astro adapter (Phase 5)
+ * resolves at static-build time to populate `<title>` / `<meta>` /
+ * Open Graph tags for the page.
+ *
+ * - `titleKey` — REQUIRED. Renders into `<title>` AND `og:title`. The
+ *   manifest commits to declaring this key in every locale's label
+ *   pack; the validator surfaces missing entries at build start.
+ * - `descriptionKey` — REQUIRED. Renders into `<meta name="description">`,
+ *   `og:description`, and `twitter:description`. Same per-locale
+ *   commitment.
+ * - `ogImageUrl` — OPTIONAL. Static URL (typically a per-locale CDN
+ *   path) for `og:image` / `twitter:image`. Not a label key because
+ *   marketing teams overwhelmingly ship one localized asset URL per
+ *   page rather than authoring image URLs in label packs. When
+ *   per-locale images are needed, the consumer supplies a function
+ *   in their site-root config that resolves locale → URL (Phase 5).
+ *
+ * **Why these three only**: the JSON-LD / canonical / `hreflang` /
+ * robots tags are NOT label-key-driven — they are derived
+ * mechanically from the manifest (`routePath`), the root config
+ * (`locales`, `defaultLocale`), and the section-level
+ * `getStructuredData()` hooks. Mixing them into the meta-label-keys
+ * shape would conflate human-authored copy with structural metadata.
+ */
+const _WebsitePageMetaLabelKeysSchema = z.object({
+  titleKey: WebsiteLabelKeySchema,
+  descriptionKey: WebsiteLabelKeySchema,
+  ogImageUrl: z.url({ error: 'ogImageUrl must be a valid URL' }).optional(),
+});
+
+export const WebsitePageMetaLabelKeysSchema: typeof _WebsitePageMetaLabelKeysSchema =
+  _WebsitePageMetaLabelKeysSchema;
+
+export type WebsitePageMetaLabelKeys = z.infer<typeof _WebsitePageMetaLabelKeysSchema>;
+/** @wildo_source:part:end saas.website.page-manifest.meta-label-keys */
+
+/**
+ * @wildo_source:part:start saas.website.page-manifest.route-path facet:layer:shared facet:family:website
+ *
+ * `WebsitePageRoutePath` — the URL path the page mounts at (locale
+ * prefix stripped).
+ *
+ * **Format**:
+ *   - MUST start with `/`
+ *   - MAY be the root (`'/'`) for the landing page
+ *   - segments are lowercase kebab-case
+ *   - parameter segments use Astro's `[param]` convention
+ *     (e.g. `'/blog/[slug]'`, `'/case-studies/[slug]'`)
+ *
+ * The Astro adapter (Phase 5) prepends the locale prefix
+ * (`/en`, `/fr`, …) when generating routes. The manifest stores the
+ * locale-neutral path because the same `pageComponent` renders for
+ * every locale.
+ *
+ * **Brand**: prevents accidental cross-talk with absolute URLs
+ * (`https://…`), with locale-prefixed paths (`/en/pricing`), and with
+ * arbitrary string props in the manifest factory.
+ */
+const _WebsitePageRoutePathSchema = z
+  .string()
+  .min(1, { error: 'routePath must not be empty' })
+  .max(256, { error: 'routePath must be at most 256 characters' })
+  .regex(
+    /^\/(?:[a-z0-9][a-z0-9-]*(?:\/[a-z0-9-]+|\/\[[a-z][a-zA-Z0-9]*\])*)?\/?$/,
+    {
+      error:
+        'routePath must start with `/`, use lowercase kebab-case segments, and may include Astro `[param]` segments (e.g. "/", "/pricing", "/blog/[slug]")',
+    },
+  )
+  .brand<'WebsitePageRoutePath'>();
+
+export const WebsitePageRoutePathSchema: typeof _WebsitePageRoutePathSchema =
+  _WebsitePageRoutePathSchema;
+
+export type WebsitePageRoutePath = z.infer<typeof _WebsitePageRoutePathSchema>;
+/** @wildo_source:part:end saas.website.page-manifest.route-path */
+
+/**
+ * @wildo_source:part:start saas.website.page-manifest.schema facet:layer:shared facet:family:website
+ *
+ * `WebsitePageManifest` — the registration-time descriptor for one
+ * marketing-site page.
+ *
+ * **Authoring path**: each page-impl module exports both a
+ * `<PageName>Page` React component AND a `<PAGE_NAME>_PAGE_MANIFEST`
+ * literal. The manifest is collected into `WebsiteRootConfig.pageManifests[]`;
+ * the Astro page file (`src/pages/<page>.astro`) imports the manifest
+ * and hands it to `<WebsitePageBridge manifest={…}>` (Phase 5).
+ *
+ * **Field-by-field rationale** (semantic-weight discipline):
+ *
+ * - `ref` — the page's structural identity. Used for label-key
+ *   derivation (`website.<ref>.<sectionRef>.<slot>`), for
+ *   cross-page navigation lookup, and as the manifest registry key.
+ * - `routePath` — the locale-neutral URL path. Decoupled from `ref`
+ *   because the same page (e.g. `ref: 'pricing'`) may mount at a
+ *   localized path (`/tarifs` in French) — the locale-aware path
+ *   resolution is a Phase 5 concern; this field is the canonical
+ *   English-language path.
+ * - `pageComponent` — the React component the bridge renders inside
+ *   `<WebsitePageContext value={{ pageRef: ref }}>`. Type relaxed to
+ *   `unknown` at the schema layer for the same reasons as
+ *   `WebsiteSectionDefinition.Component`; the manifest factory
+ *   (`defineWebsitePageManifest`, Phase 2) preserves precise typing
+ *   at the consumer call site.
+ * - `sectionRefs` — the contractual list of section refs the page
+ *   declares. Used by the label-pack validator to cross-reference
+ *   `expectedLabelKeys` collected from each section against the
+ *   page's commitment. **Order matters** for the validator's
+ *   diagnostic output (sections are reported in declaration order)
+ *   but does NOT control render order — render order is whatever the
+ *   `pageComponent` JSX lays out.
+ * - `metaLabelKeys` — see `WebsitePageMetaLabelKeysSchema`.
+ * - `hydration` — opt-in flag. `'lazy'` (default) corresponds to
+ *   `client:idle` in the Astro adapter (deferred hydration); `'eager'`
+ *   corresponds to `client:load` (immediate hydration). The page
+ *   author flips this to `'eager'` only when the page hosts
+ *   above-the-fold interactive sections (e.g. a contact form).
+ *
+ *   **Important — informational, NOT auto-wired**: Astro's
+ *   `client:*` directives MUST resolve to a literal token at compile
+ *   time (the Astro compiler reads the directive from the JSX source
+ *   to decide which hydration helper to bundle); a runtime-computed
+ *   value will not work. The framework therefore CANNOT translate
+ *   this field into the directive on the consumer's behalf — the
+ *   manifest field is the single source of truth a consumer's
+ *   per-page `.astro` template should USE to pick the matching
+ *   `client:idle` / `client:load` directive by hand. Keeping the two
+ *   in lock-step is a discipline obligation; the audit CLI (Phase 7)
+ *   will surface a drift warning when a page's hydration field does
+ *   not match the directive in its `.astro` file.
+ *
+ * **Refinements**:
+ *   - `sectionRefs` MUST contain unique values. Duplicates indicate
+ *     either a copy-paste bug (two sections pointing at the same
+ *     label-key root) or an intent to share a label-key root that
+ *     the framework rejects to keep the per-page validation
+ *     unambiguous (consumers who need a shared label-key root
+ *     across two distinct sections should pull the shared content
+ *     to the page level via `WebsiteRootConfig`-level globals,
+ *     Phase 2.5).
+ */
+export enum WebsitePageHydrationStrategy {
+  /** `client:idle` in the Astro adapter (deferred hydration). */
+  LAZY = 'lazy',
+  /** `client:load` in the Astro adapter (immediate hydration). */
+  EAGER = 'eager',
+}
+
+export const WebsitePageHydrationStrategySchema: z.ZodEnum<typeof WebsitePageHydrationStrategy> =
+  z.enum(WebsitePageHydrationStrategy);
+
+/**
+ * @wildo_source:part:start saas.website.page-manifest.seo facet:layer:shared facet:family:website
+ *
+ * `WebsitePageSeoConfig` — per-page SEO/AEO/GEO knobs.
+ *
+ * The marketing-site default is to be FULLY discoverable by every
+ * crawler (search engines AND AI training crawlers). This block holds
+ * the per-page opt-out levers that flip a page out of that default.
+ *
+ * **Field rationale**:
+ *
+ * - `noaiOptOut?` — when `true`, the page emits
+ *   `<meta name="robots" content="noai, noimageai">` AND a sibling
+ *   `_headers` file entry signalling `X-Robots-Tag: noai, noimageai`
+ *   for crawlers that don't honor in-document meta. ONE knob drives
+ *   BOTH channels (`headers-renderer.ts` reads the same flag) — the
+ *   framework owns the dual emission so consumers can't accidentally
+ *   set one and forget the other.
+ *
+ *   **Why default-IN to AI training (D-AG3)**: the marketing-site
+ *   default is `false` (consent to AI training). Marketing pages
+ *   benefit from AI-engine citation; opting out is a per-page
+ *   editorial decision (typically pricing pages — to avoid stale
+ *   price training; or legal/internal pages — to avoid free-text
+ *   reproduction of contractual language). Per-blog-post opt-out
+ *   would mirror this knob on a sibling blog-post manifest schema
+ *   if that need materializes.
+ */
+const _WebsitePageSeoConfigSchema = z.object({
+  noaiOptOut: z.boolean().optional(),
+});
+
+export const WebsitePageSeoConfigSchema: typeof _WebsitePageSeoConfigSchema =
+  _WebsitePageSeoConfigSchema;
+
+export type WebsitePageSeoConfig = z.infer<typeof _WebsitePageSeoConfigSchema>;
+/** @wildo_source:part:end saas.website.page-manifest.seo */
+
+const _WebsitePageManifestSchema = z
+  .object({
+    ref: WebsitePageRefSchema,
+    routePath: _WebsitePageRoutePathSchema,
+    pageComponent: z.unknown(),
+    sectionRefs: z.array(WebsiteSectionRefSchema).min(1, {
+      error: 'A page manifest must declare at least one sectionRef',
+    }),
+    metaLabelKeys: _WebsitePageMetaLabelKeysSchema,
+    hydration: WebsitePageHydrationStrategySchema.optional(),
+    seo: _WebsitePageSeoConfigSchema.optional(),
+  })
+  .superRefine((manifest, ctx) => {
+    const seen = new Set<string>();
+    for (const [index, sectionRef] of manifest.sectionRefs.entries()) {
+      const key = sectionRef as unknown as string;
+      if (seen.has(key)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['sectionRefs', index],
+          message: `Duplicate sectionRef "${key}" in page manifest "${manifest.ref as unknown as string}"`,
+        });
+      }
+      seen.add(key);
+    }
+
+    const expectedPagePrefix = `website.${manifest.ref as unknown as string}.`;
+    for (const [field, key] of [
+      ['titleKey', manifest.metaLabelKeys.titleKey] as const,
+      ['descriptionKey', manifest.metaLabelKeys.descriptionKey] as const,
+    ]) {
+      if (!(key as unknown as string).startsWith(expectedPagePrefix)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['metaLabelKeys', field],
+          message: `metaLabelKeys.${field} ("${key as unknown as string}") must be rooted under the page ref "${manifest.ref as unknown as string}" (expected prefix "${expectedPagePrefix}")`,
+        });
+      }
+    }
+  });
+
+export const WebsitePageManifestSchema: typeof _WebsitePageManifestSchema =
+  _WebsitePageManifestSchema;
+
+/**
+ * Runtime shape of `WebsitePageManifest`.
+ *
+ * **Why `ComponentType<any>` and NOT `ComponentType<unknown>`** —
+ * same variance reasoning as `WebsiteSectionDefinition.Component`:
+ * `ComponentType<TProps>` is CONTRAVARIANT in `TProps`, so a
+ * narrower `TypedWebsitePageManifest<TProps>` (returned by
+ * `defineWebsitePageManifest<TProps>`) was not assignable to a
+ * `WebsitePageManifest` typed with `ComponentType<unknown>`. That
+ * blocked every consumer call-site that passed a typed manifest to
+ * helpers / registries / validators expecting the bare type
+ * (root config's `pageManifests[]`, the Astro adapter's
+ * `loadWebsitePageRuntime`, and the head-renderer). Using `any`
+ * matches the React-canonical pattern for heterogeneous component
+ * containers and reflects the runtime contract: the framework only
+ * RENDERS these components — it never constructs ad-hoc props for
+ * them; the consumer's JSX call site supplies the precise props.
+ */
+export interface WebsitePageManifest extends z.infer<typeof _WebsitePageManifestSchema> {
+  pageComponent: ComponentType<any>;
+}
+/** @wildo_source:part:end saas.website.page-manifest.schema */