@wildo-ai/saas-website 1.1.1

package/src/astro/blog-post-head.renderer.ts

@@ -0,0 +1,293 @@
+import type { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import { buildLocalizedRoutePath } from '../core/routing/internal-routing.utils';
+import type { BlogPostFrontmatter } from '../schemas/blog/blog-post-frontmatter.shared.schemas';
+import type { WebsiteStructuredDataPayload } from '../schemas/structured-data/website-structured-data.shared.schemas';
+
+import { escapeHtmlAttribute, escapeHtmlText } from './internal/html-escape';
+import { renderPageStructuredData } from './structured-data.renderer';
+import type { WebsiteSiteContext } from './website-site-context';
+
+/**
+ * @wildo_source:part:start saas.website.blog.head-renderer facet:layer:astro facet:family:website
+ *
+ * `renderBlogPostHeadHtml(opts)` — sibling of `renderWebsitePageHeadHtml`
+ * that emits the SEO `<head>` block for an individual blog post,
+ * sourcing per-render copy from a validated `BlogPostFrontmatter`
+ * instead of the page manifest's `metaLabelKeys`.
+ *
+ * # Why a separate renderer (not an overload of the page-head renderer)
+ *
+ * The framework-mindset rule "every type / bucket / field must carry
+ * its semantic weight" pushes against overloading
+ * `renderWebsitePageHeadHtml` with a "blog-post mode" flag:
+ *
+ *   - The two renderers have STRUCTURALLY different inputs.
+ *     `renderWebsitePageHeadHtml` reads `manifest.metaLabelKeys.{titleKey,
+ *     descriptionKey, ogImageUrl}` + the matching `labelPack` lookup;
+ *     this renderer reads `frontmatter.{title, summary, coverImageUrl,
+ *     publishedAt, authorRef, tags}` directly — no label-pack
+ *     dependency at all (blog body copy is per-post, not
+ *     per-locale-pack, by design).
+ *   - The two renderers emit DIFFERENT meta surfaces.
+ *     `og:type=website` vs. `og:type=article`; the article variant
+ *     additionally emits `article:published_time`,
+ *     `article:author`, and `article:tag` (one per `frontmatter.tags`
+ *     entry). Folding both into one helper would require an
+ *     `articleMeta?: { ... }` discriminated branch that carries no
+ *     value when called from a non-blog page — exactly the kind of
+ *     "convenience union" the framework rules forbid.
+ *   - The blog-post route itself uses a parameterized `routePath`
+ *     (`/blog/[slug]`) that needs the SLUG substituted at render time
+ *     to produce the absolute canonical/hreflang URLs. Page-level
+ *     routes are always literal — keeping the substitution in this
+ *     renderer (rather than at the manifest layer) means the page
+ *     manifest stays free of per-render concerns.
+ *
+ * Both renderers share the exact same hreflang/canonical/OG locale
+ * composition logic — duplicating ~30 lines of stable URL composition
+ * is the lesser evil compared to threading a generic options bag
+ * through both. If a third renderer ever lands (a "campaign-page" or
+ * "tag-page" head emitter, say), the right move is to extract a
+ * shared `composeHreflangAndCanonical(...)` helper at that point;
+ * doing it now would be premature against the YAGNI line.
+ *
+ * # The `routePath` argument
+ *
+ * The blog-post page manifest's `routePath` is `/blog/[slug]` (Astro
+ * route-parameter syntax). At render time the consumer's `[slug].astro`
+ * has already resolved the slug, so we accept the FULLY-SUBSTITUTED
+ * locale-neutral path (e.g. `/blog/why-context-beats-content`) here.
+ * `buildLocalizedRoutePath` then handles the locale-prefix decision,
+ * mirroring how `WebsiteInternalLink` and `renderWebsitePageHeadHtml`
+ * handle their own routes — the locale-prefix rule never lives in two
+ * places.
+ *
+ * # Failure modes
+ *
+ * Throws nothing — all required frontmatter fields are guaranteed by
+ * `parseBlogPostFrontmatter` upstream (same Zod 4 schema). The
+ * optional `coverImageUrl` is the only branch: when absent, the
+ * Twitter card kind degrades to `summary` (text-only) and `og:image`
+ * is omitted entirely.
+ */
+
+export interface RenderBlogPostHeadHtmlOptions {
+  /**
+   * Composed `WebsiteSiteContext` — the renderer reads
+   * `websiteConfig.{defaultLocale, locales, publicOrigin}` for the
+   * URL/locale surface and `rootConfig.seo.{siteName}` for the
+   * brand fallback. `seo.defaultOgImageUrl` is intentionally NOT
+   * consulted: blog posts that ship without a `coverImageUrl` get a
+   * smaller-card degradation rather than a generic site-wide image
+   * (the default OG image is meaningful for marketing pages but
+   * misleading for blog posts).
+   */
+  siteContext: WebsiteSiteContext;
+  /**
+   * The locale Astro resolved (with default-locale fallback) for the
+   * current request. Drives the `<html lang>` value upstream + the
+   * `og:locale` line and the canonical URL's locale-prefix decision.
+   */
+  locale: AvailableLanguage;
+  /**
+   * The fully-substituted locale-neutral route path for the post —
+   * typically `/blog/<slug>` with `<slug>` already resolved by the
+   * consumer's `[slug].astro` `getStaticPaths()`. Passing the
+   * substituted path (rather than the parameterized one) keeps the
+   * renderer agnostic of the consumer's route-parameter naming.
+   */
+  routePath: string;
+  /**
+   * Validated frontmatter — the result of `parseBlogPostFrontmatter`.
+   * Carrying the parsed (branded) shape here means an unvalidated
+   * `entry.data` cannot reach this renderer accidentally (the
+   * branded-type signature would reject a raw `unknown`).
+   */
+  frontmatter: BlogPostFrontmatter;
+  /**
+   * AI-training opt-out (D-AG3) — when `true`, the renderer emits
+   * `<meta name="robots" content="noai, noimageai">`. The sibling
+   * `_headers` entry is produced by `renderBlogPostNoaiHeaders()`
+   * (one knob, two channels — see the page-head renderer's
+   * companion).
+   *
+   * **Why a renderer-level option, not a frontmatter field**: the
+   * blog-post frontmatter schema (`BlogPostFrontmatterSchema`)
+   * doesn't yet expose a per-post AI-opt-out knob — when it does,
+   * the consumer's `[slug].astro` will read it from the parsed
+   * frontmatter and pass it through here. Keeping the option at
+   * the renderer surface NOW means a third-party blog-post catalog
+   * (campaigns, customer stories) can opt out without authoring a
+   * new frontmatter schema first.
+   */
+  noaiOptOut?: boolean;
+}
+
+export interface BuildBlogPostStructuredDataPayloadOptions {
+  frontmatter: BlogPostFrontmatter;
+  canonicalUrl: string;
+  siteOrigin: string;
+  siteName: string;
+  locale: AvailableLanguage;
+}
+
+export function buildBlogPostStructuredDataPayload(
+  opts: BuildBlogPostStructuredDataPayloadOptions,
+): WebsiteStructuredDataPayload {
+  const { frontmatter, canonicalUrl, siteOrigin, siteName, locale } = opts;
+  return {
+    '@type': 'BlogPosting',
+    '@id': `${canonicalUrl}#blog-post`,
+    headline: frontmatter.title,
+    description: frontmatter.summary,
+    datePublished: frontmatter.publishedAt,
+    author: {
+      '@type': 'Person',
+      name: String(frontmatter.authorRef),
+    },
+    publisher: {
+      '@type': 'Organization',
+      name: siteName,
+      url: siteOrigin,
+    },
+    mainEntityOfPage: canonicalUrl,
+    url: canonicalUrl,
+    inLanguage: String(locale),
+    ...(frontmatter.coverImageUrl ? { image: frontmatter.coverImageUrl } : {}),
+    ...(frontmatter.tags.length > 0 ? { keywords: frontmatter.tags.join(', ') } : {}),
+  };
+}
+
+export function renderBlogPostHeadHtml(opts: RenderBlogPostHeadHtmlOptions): string {
+  const { siteContext, locale, routePath, frontmatter, noaiOptOut } = opts;
+  const { rootConfig, websiteConfig } = siteContext;
+
+  const title = frontmatter.title;
+  const description = frontmatter.summary;
+  const ogImageUrl = frontmatter.coverImageUrl;
+  const titleAttr = escapeHtmlAttribute(title);
+  const descriptionAttr = escapeHtmlAttribute(description);
+  const titleText = escapeHtmlText(title);
+
+  const siteOrigin = websiteConfig.publicOrigin;
+  const defaultLocale = websiteConfig.defaultLocale;
+  const currentLocaleStr = String(locale);
+
+  /**
+   * Same locale-prefix composition rule as `renderWebsitePageHeadHtml`
+   * — delegated to the shared `buildLocalizedRoutePath` helper so a
+   * future change to the prefix policy lands in ONE place and propagates
+   * consistently to internal links + page heads + blog-post heads.
+   */
+  function buildAbsoluteUrl(forLocale: AvailableLanguage): string {
+    const path = buildLocalizedRoutePath({
+      locale: forLocale,
+      defaultLocale,
+      routePath,
+    });
+    return `${siteOrigin}${path}`;
+  }
+
+  const canonicalUrl = buildAbsoluteUrl(locale);
+
+  const hreflangLines: string[] = [];
+  for (const entry of websiteConfig.locales) {
+    const localeStr = String(entry.locale);
+    hreflangLines.push(
+      `<link rel="alternate" hreflang="${escapeHtmlAttribute(localeStr)}" href="${escapeHtmlAttribute(buildAbsoluteUrl(entry.locale))}" />`,
+    );
+  }
+  hreflangLines.push(
+    `<link rel="alternate" hreflang="x-default" href="${escapeHtmlAttribute(buildAbsoluteUrl(defaultLocale))}" />`,
+  );
+
+  const ogImageLines: string[] = [];
+  if (ogImageUrl !== undefined) {
+    const ogImageAttr = escapeHtmlAttribute(ogImageUrl);
+    ogImageLines.push(
+      `<meta property="og:image" content="${ogImageAttr}" />`,
+      `<meta name="twitter:image" content="${ogImageAttr}" />`,
+    );
+  }
+  const twitterCardKind = ogImageUrl !== undefined ? 'summary_large_image' : 'summary';
+
+  const ogLocaleAlternateLines: string[] = [];
+  for (const entry of websiteConfig.locales) {
+    const localeStr = String(entry.locale);
+    if (localeStr === currentLocaleStr) continue;
+    ogLocaleAlternateLines.push(
+      `<meta property="og:locale:alternate" content="${escapeHtmlAttribute(localeStr)}" />`,
+    );
+  }
+
+  /**
+   * `og:article:*` block — the per-post metadata that distinguishes
+   * the blog-post head from the page head. The Open Graph "article"
+   * vertical defines:
+   *   - `article:published_time` (ISO-8601 — already validated by
+   *     the frontmatter schema's `z.iso.datetime`).
+   *   - `article:author` (free text or URL — we emit the author
+   *     ref as a free-text string; a future author-registry
+   *     resolution would emit the author's profile URL instead).
+   *   - `article:tag` (one tag per emission; the OG spec uses
+   *     repeated `<meta property="article:tag">` lines, NOT a
+   *     comma-joined list).
+   *
+   * `article:section` (the OG "section" field, e.g. "Engineering" /
+   * "Product") is intentionally NOT emitted — Wonder Todos has no
+   * blog-section taxonomy yet, and emitting an empty section would
+   * be worse than omission.
+   */
+  const articleMetaLines: string[] = [
+    `<meta property="article:published_time" content="${escapeHtmlAttribute(frontmatter.publishedAt)}" />`,
+    `<meta property="article:author" content="${escapeHtmlAttribute(frontmatter.authorRef as unknown as string)}" />`,
+  ];
+  for (const tag of frontmatter.tags) {
+    articleMetaLines.push(
+      `<meta property="article:tag" content="${escapeHtmlAttribute(tag as unknown as string)}" />`,
+    );
+  }
+
+  const siteNameAttr = escapeHtmlAttribute(rootConfig.seo.siteName);
+  const canonicalAttr = escapeHtmlAttribute(canonicalUrl);
+  const ogLocaleAttr = escapeHtmlAttribute(currentLocaleStr);
+  const noaiMetaLines: string[] = [];
+  if (noaiOptOut === true) {
+    noaiMetaLines.push(`<meta name="robots" content="noai, noimageai" />`);
+  }
+
+  const structuredDataHtml = renderPageStructuredData({
+    pagePayloads: [
+      buildBlogPostStructuredDataPayload({
+        frontmatter,
+        canonicalUrl,
+        siteOrigin,
+        siteName: rootConfig.seo.siteName,
+        locale,
+      }),
+    ],
+  });
+
+  return [
+    `<title>${titleText}</title>`,
+    `<meta name="description" content="${descriptionAttr}" />`,
+    `<link rel="canonical" href="${canonicalAttr}" />`,
+    `<meta property="og:title" content="${titleAttr}" />`,
+    `<meta property="og:description" content="${descriptionAttr}" />`,
+    `<meta property="og:type" content="article" />`,
+    `<meta property="og:url" content="${canonicalAttr}" />`,
+    `<meta property="og:site_name" content="${siteNameAttr}" />`,
+    `<meta property="og:locale" content="${ogLocaleAttr}" />`,
+    ...ogLocaleAlternateLines,
+    ...ogImageLines,
+    `<meta name="twitter:card" content="${twitterCardKind}" />`,
+    `<meta name="twitter:title" content="${titleAttr}" />`,
+    `<meta name="twitter:description" content="${descriptionAttr}" />`,
+    ...articleMetaLines,
+    ...noaiMetaLines,
+    structuredDataHtml,
+    ...hreflangLines,
+  ].join('\n');
+}
+/** @wildo_source:part:end saas.website.blog.head-renderer */

package/src/astro/bridge-runtime.tsx

@@ -0,0 +1,270 @@
+import type { ComponentType, FunctionComponent, ReactNode } from 'react';
+
+import type { FrontendProvidersBlock } from '@wildo-ai/saas-models/public-runtime';
+import type { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import {
+  WebsiteRuntimeContextProvider,
+  type WebsiteRuntimeContextValue,
+} from '../core/contexts/WebsiteRuntimeContext';
+import { createFrontendWebsiteProviderRegistry } from '../core/external-providers/frontend-provider-registry.website';
+import { WebsitePageLayout } from '../core/layouts/WebsitePageLayout';
+import type { WebsiteDesignTokens } from '../schemas/design-tokens/website-design-tokens.shared.schemas';
+import type { WebsiteLabelKey } from '../schemas/label-keys/website-label-key.schemas';
+import type { WebsiteNavigationConfig } from '../schemas/manifests/website-root-config.shared.schemas';
+import type { WebsitePageRef } from '../schemas/refs/page-ref.schemas';
+import type { LabelPack } from '../schemas/validators/label-pack.validator';
+
+/**
+ * @wildo_source:part:start saas.website.astro.bridge facet:layer:astro facet:family:website
+ *
+ * `createWebsitePageBridgeIsland(deps)` — factory that returns the
+ * React island a consumer's per-page `.astro` file mounts with a
+ * `client:idle` (or `client:load`) directive.
+ *
+ * **The hard architectural constraint this design solves**: Astro
+ * serializes React-island props via `devalue`-style JSON to transfer
+ * them across the SSR → client-hydration boundary. Function values —
+ * including `ComponentType` references — are NOT serializable. Any
+ * design that tried to pass `pageComponent`, `headerComponent`, or
+ * `footerComponent` AS island props would render correctly server-side
+ * (the function ref is in-process during SSR) and then mismatch on
+ * first hydration (the client receives `undefined`/broken placeholders
+ * for the function-typed fields). The Vitest suite would not catch
+ * this because Vitest renders React in a single process — there is no
+ * serialization boundary in unit tests.
+ *
+ * **The factory pattern fixes the constraint by closing over** the
+ * `pageComponent`, `pageRef`, and `navigation` (header / footer
+ * component refs) at MODULE LOAD TIME on the consumer side. The
+ * returned island accepts only PRIMITIVE-VALUED props (`locale`,
+ * `labelPack`, `designTokens`) — all JSON-serializable, all safe to
+ * cross the hydration boundary. The component refs never appear in
+ * the prop signature; they live in the lexical closure that the
+ * client-side bundle includes naturally as part of the island's
+ * compiled module.
+ *
+ * **Authoring pattern (per-page bridge module)**:
+ *
+ * ```tsx
+ * // consumer's src/pages-impl/landing.bridge.tsx
+ * import { createWebsitePageBridgeIsland } from '@wildo-ai/saas-website/astro-island';
+ * import { LandingPage, LANDING_PAGE_MANIFEST } from './landing.page';
+ * import { WEBSITE_ROOT_CONFIG } from '../website-root.config';
+ *
+ * export const LandingBridgeIsland = createWebsitePageBridgeIsland({
+ *   PageComponent: LandingPage,
+ *   pageRef: LANDING_PAGE_MANIFEST.ref,
+ *   navigation: WEBSITE_ROOT_CONFIG.navigation,
+ * });
+ * ```
+ *
+ * ```astro
+ * ---
+ * // consumer's src/pages/index.astro
+ * import {
+ *   loadWebsitePageRuntime,
+ *   renderWebsitePageHeadHtml,
+ *   renderWebsiteDesignTokensCss,
+ * } from '@wildo-ai/saas-website/astro';
+ * import { LandingBridgeIsland } from '../pages-impl/landing.bridge';
+ * import { LANDING_PAGE_MANIFEST } from '../pages-impl/landing.page';
+ * import { WEBSITE_ROOT_CONFIG } from '../website-root.config';
+ *
+ * const runtime = loadWebsitePageRuntime({
+ *   manifest: LANDING_PAGE_MANIFEST,
+ *   rootConfig: WEBSITE_ROOT_CONFIG,
+ *   labelPacksDir: './src/i18n',
+ *   astroLocale: Astro.currentLocale,
+ * });
+ * const headHtml = renderWebsitePageHeadHtml({
+ *   manifest: LANDING_PAGE_MANIFEST,
+ *   rootConfig: WEBSITE_ROOT_CONFIG,
+ *   locale: runtime.locale,
+ *   labelPack: runtime.labelPack,
+ * });
+ * const designTokensCss = renderWebsiteDesignTokensCss(
+ *   WEBSITE_ROOT_CONFIG.designTokens,
+ * );
+ * ---
+ * <!doctype html>
+ * <html lang={runtime.locale}>
+ *   <head>
+ *     <Fragment set:html={headHtml} />
+ *     <style set:html={designTokensCss}></style>
+ *   </head>
+ *   <body>
+ *     <LandingBridgeIsland
+ *       client:idle
+ *       locale={runtime.locale}
+ *       labelPack={runtime.labelPack}
+ *       designTokens={WEBSITE_ROOT_CONFIG.designTokens}
+ *     />
+ *   </body>
+ * </html>
+ * ```
+ *
+ * **Why a per-page bridge file** (rather than constructing the island
+ * inline in the consumer's `.astro` frontmatter):
+ *
+ * Astro's `client:*` directive requires the JSX tag to reference a
+ * statically-resolvable module export at compile time — that is how
+ * Astro knows which module to bundle for client-side hydration. A
+ * factory call inside `.astro` frontmatter (`const Island =
+ * createWebsitePageBridgeIsland({...}); <Island client:idle/>`) does
+ * NOT round-trip through Astro's module-graph analyzer: Astro would
+ * see a runtime-constructed component reference and fail to bundle
+ * the closure for the client. The per-page bridge file gives Astro a
+ * static export to bind the directive to. The cost is one ~6-line
+ * file per page; the win is the only architecture that is safe
+ * against the H-2 hydration-mismatch failure mode AND uses Astro's
+ * native bundling pipeline.
+ *
+ * **Why `ComponentType` refs in `Deps` and not in `Props`**: this is
+ * the entire point of the redesign. `Deps` is consumed at module load
+ * time on the consumer side — the closure traps the function refs
+ * inside the returned component. `Props` is consumed at island-mount
+ * time and crosses Astro's serialization boundary. Keeping the two
+ * concerns lexically separate makes the boundary visible in the type
+ * signature.
+ *
+ * **Boundary** (D12 client-bundle discipline): this module ships into
+ * the React-island bundle. It MUST stay clear of `node:*` imports,
+ * fs / path helpers, and the SSR-tier specifiers
+ * (`axios`, `jsonwebtoken`, …). The bundle-isolation test catches
+ * regressions both globally (closure-wide allow-list) AND with the
+ * targeted Phase-5 negative test that asserts `node:fs` / `node:path`
+ * reach this island closure ONLY through `astro.ts`, never through
+ * `index.ts` or `companion-exports.ts`.
+ */
+
+/**
+ * Module-load-time dependencies — closed over inside the returned
+ * island. NEVER cross the hydration boundary as serialized props.
+ */
+export interface CreateWebsitePageBridgeIslandDeps {
+  /**
+   * The page's React component. Typically the same value that was
+   * passed to `defineWebsitePageManifest({ pageComponent })` — the
+   * authoring convention re-imports it here to keep the closure
+   * explicit and the per-page bridge file self-contained.
+   *
+   * Typed as `ComponentType<any>` to mirror
+   * `WebsitePageManifest.pageComponent` and dodge React's `ComponentType`
+   * contravariance: a narrower `ComponentType<TProps>` returned by
+   * `defineWebsitePageManifest<TProps>` would not be assignable to a
+   * `ComponentType<unknown>` slot, blocking every per-page bridge
+   * call site. The component is invoked with no props at the
+   * `<PageComponent />` JSX call site below, so widening here is
+   * runtime-safe.
+   */
+  PageComponent: ComponentType<any>;
+  /**
+   * The active page's ref. Carried as a primitive (string-branded)
+   * value so the inner `WebsitePageLayout` can register the
+   * `WebsitePageContext` without re-resolving it from the manifest.
+   */
+  pageRef: WebsitePageRef;
+  /**
+   * Site-wide navigation slot bindings (header / footer components).
+   * Closed over here rather than passed as island props because both
+   * fields are `ComponentType` refs that cannot survive Astro's
+   * serialization boundary.
+   */
+  navigation: WebsiteNavigationConfig;
+}
+
+/**
+ * Hydration-boundary props — what the consumer's `.astro` page passes
+ * to `<LandingBridgeIsland client:idle ...{primitiveProps}/>`. Every
+ * field is JSON-serializable.
+ */
+export interface WebsitePageBridgeIslandProps {
+  /** The locale Astro resolved (with default-locale fallback). */
+  locale: AvailableLanguage;
+  /**
+   * The site's default locale. Carried as an island prop (not closed
+   * over in `Deps`) because it is JSON-primitive and consumers
+   * already pass `runtime.locale` from the per-locale Astro page
+   * frontmatter — passing the matching `runtime.defaultLocale` from
+   * the same `loadWebsitePageRuntime(...)` return value keeps the
+   * authoring story symmetric. Required for `WebsiteInternalLink`
+   * (Phase 6 fix H-β) which needs both locales to compute the
+   * correct prefix.
+   */
+  defaultLocale: AvailableLanguage;
+  /** Already-loaded + already-shape-validated label pack. */
+  labelPack: LabelPack;
+  /** Design-token bundle from `WebsiteRootConfig.designTokens`. */
+  designTokens: WebsiteDesignTokens;
+  /**
+   * Fully-composed label key the framework reads to render the
+   * "Skip to main content" affordance (Phase 6 third audit fix M-α).
+   * Mirrors `WebsiteRootConfig.skipToMainContentLabelKey`. Carried as
+   * a JSON-serializable string prop (NOT closed over in `Deps`)
+   * because it is a primitive value the consumer already has on the
+   * root config in the `.astro` frontmatter — passing it as an island
+   * prop keeps the per-page bridge module dependency-free of the
+   * site root config (the bridge stays page-local; only the per-page
+   * `.astro` page knows about `WEBSITE_ROOT_CONFIG`).
+   */
+  skipToMainContentLabelKey: WebsiteLabelKey;
+  /** Optional website-facing public providers materialized at build time. */
+  frontendProviders?: FrontendProvidersBlock;
+  /**
+   * Optional backend API origin (no trailing slash) forwarded into
+   * `WebsiteRuntimeContext.apiOrigin` for anonymous-capture sections
+   * (lead / draft-note forms) to construct their
+   * `WebsiteAnonymousSessionClient`. A JSON-serializable string, so it
+   * crosses the hydration boundary as an island prop; the `.astro` page
+   * resolves the per-environment value from
+   * `WildoMarketingWebsiteConfig.apiOrigin`. Omitted on pages with no
+   * capture section.
+   */
+  apiOrigin?: string;
+}
+
+/**
+ * Returns a FUNCTION component, not the wider `ComponentType` union. The island IS a function
+ * component — Astro hydrates nothing else here — and the union is not callable, so the wider
+ * declaration cost callers the ability to invoke the island directly. Mirrors
+ * `createWebsiteBlogPostBridgeIsland`, whose suite depends on that call. `FunctionComponent` is
+ * assignable to `ComponentType`, so no consumer narrows.
+ */
+export function createWebsitePageBridgeIsland(
+  deps: CreateWebsitePageBridgeIslandDeps,
+): FunctionComponent<WebsitePageBridgeIslandProps> {
+  const { PageComponent, pageRef, navigation } = deps;
+
+  function WebsitePageBridgeIsland({
+    locale,
+    defaultLocale,
+    labelPack,
+    designTokens,
+    skipToMainContentLabelKey,
+    frontendProviders,
+    apiOrigin,
+  }: WebsitePageBridgeIslandProps): ReactNode {
+    const runtimeValue: WebsiteRuntimeContextValue = {
+      locale,
+      defaultLocale,
+      labelPack,
+      designTokens,
+      navigation,
+      skipToMainContentLabelKey,
+      frontendProviderRegistry: createFrontendWebsiteProviderRegistry(frontendProviders),
+      apiOrigin,
+    };
+    return (
+      <WebsiteRuntimeContextProvider value={runtimeValue}>
+        <WebsitePageLayout pageRef={pageRef}>
+          <PageComponent />
+        </WebsitePageLayout>
+      </WebsiteRuntimeContextProvider>
+    );
+  }
+  WebsitePageBridgeIsland.displayName = 'WebsitePageBridgeIsland';
+
+  return WebsitePageBridgeIsland;
+}
+/** @wildo_source:part:end saas.website.astro.bridge */

package/src/astro/collect-expected-label-keys.ts

@@ -0,0 +1,113 @@
+import type { WebsiteSectionDefinition } from '../schemas/sections/website-section-definition.shared.schemas';
+import type { WebsiteSectionRef } from '../schemas/refs/section-ref.schemas';
+import type { WebsiteLabelKey } from '../schemas/label-keys/website-label-key.schemas';
+import type { ExpectedLabelKeysBySectionRef } from '../schemas/validators/label-pack.validator';
+
+/**
+ * @wildo_source:part:start saas.website.astro.label-key-collector facet:layer:astro facet:family:website
+ *
+ * `collectExpectedLabelKeysFromSections(sections)` — pure, no-I/O
+ * collector that materializes the
+ * `ExpectedLabelKeysBySectionRef` map the label-pack validator
+ * (`validateLabelPackAgainstManifest`) consumes.
+ *
+ * **Why an explicit-list collector and not a JSX walker**
+ * (Phase 5 plan originally proposed walking each manifest's
+ * `pageComponent` to discover its `defineWebsiteSection` calls —
+ * we deliberately rejected that approach):
+ *
+ *   - **No runtime React introspection.** A JSX walker would either
+ *     (a) require booting React + a virtual DOM at build time just to
+ *     render every page once and observe its section composition, or
+ *     (b) require static AST analysis of the `pageComponent` source
+ *     file to discover `<HeroSection/>`-style imports. Both add a
+ *     non-trivial dependency surface (jsdom or a TS AST walker) and
+ *     both fail silently on dynamic composition (a section rendered
+ *     conditionally by a feature flag is invisible to the static
+ *     walker but visible to the renderer, and vice versa).
+ *   - **The consumer already has the list.** Each page-impl module
+ *     already imports its sections (that's how JSX renders them);
+ *     `WebsiteRootConfig` already lists every page manifest; the
+ *     consumer's `website-root.config.ts` is therefore one line away
+ *     from also exporting a flat `[HeroSection, PricingSection, …]`
+ *     array. Asking for that array trades a frame of build-time magic
+ *     for a single hand-authored line and turns "did the build see
+ *     this section?" into a TypeScript-checked import — a far better
+ *     trade than a JSX walker.
+ *   - **Section reuse across pages is naturally handled.** Two pages
+ *     reusing the same `HeroSection` definition (with the same
+ *     `sectionRef`) collide silently in a JSX walker (which would
+ *     register the section twice with identical expected keys).
+ *     Here, the array deduplicates per `sectionRef` (a same-ref
+ *     duplicate with NON-matching `expectedLabelKeys` is a hard
+ *     authoring bug — see refinement below).
+ *
+ * **Refinement — duplicate `sectionRef` with non-matching keys**:
+ * if the same `sectionRef` appears twice with different
+ * `expectedLabelKeys`, the collector throws. This catches the
+ * "two distinct sections accidentally using the same ref" bug
+ * (typically a copy-paste during section authoring) at build time
+ * with an actionable message rather than letting the second
+ * `Map.set` silently overwrite the first.
+ *
+ * **Pure / no I/O**: the collector is invoked at build start by
+ * the Astro adapter and at audit time by `wildo website audit`;
+ * it does not read files and does not boot React.
+ *
+ * @param sections Every `WebsiteSectionDefinition` registered on the
+ *                 site. Order does not matter — the result is an
+ *                 unordered map keyed by `sectionRef`.
+ * @returns A `Map<WebsiteSectionRef, readonly WebsiteLabelKey[]>`
+ *          ready to feed into `validateLabelPackAgainstManifest`.
+ * @throws  When two distinct sections share a `sectionRef` but
+ *          declare different `expectedLabelKeys` arrays (length or
+ *          membership) — the collector's hard-error path.
+ */
+export function collectExpectedLabelKeysFromSections(
+  sections: readonly WebsiteSectionDefinition[],
+): ExpectedLabelKeysBySectionRef {
+  const map = new Map<WebsiteSectionRef, readonly WebsiteLabelKey[]>();
+
+  for (const section of sections) {
+    const existing = map.get(section.sectionRef);
+    if (existing === undefined) {
+      map.set(section.sectionRef, section.expectedLabelKeys);
+      continue;
+    }
+    if (!areLabelKeyArraysEqual(existing, section.expectedLabelKeys)) {
+      throw new Error(
+        `[collectExpectedLabelKeysFromSections] Duplicate sectionRef ` +
+          `"${section.sectionRef as unknown as string}" registered with ` +
+          `non-matching expectedLabelKeys. ` +
+          `First registration: [${(existing as readonly string[]).join(', ')}]. ` +
+          `Second registration: [${(section.expectedLabelKeys as readonly string[]).join(', ')}]. ` +
+          `Either rename one section's sectionRef or align both expectedLabelKeys arrays.`,
+      );
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Order-insensitive equality for two `readonly WebsiteLabelKey[]`.
+ * Used by the collector to validate that a duplicate-ref registration
+ * is intentional (same keys) vs. a copy-paste bug (different keys).
+ *
+ * Quadratic in the array length, but `expectedLabelKeys` is bounded by
+ * the number of slots a single section consumes (typically <20), so
+ * the cost is negligible compared to surface readability of the
+ * comparison.
+ */
+function areLabelKeyArraysEqual(
+  a: readonly WebsiteLabelKey[],
+  b: readonly WebsiteLabelKey[],
+): boolean {
+  if (a.length !== b.length) return false;
+  const aSet = new Set(a as readonly string[]);
+  for (const key of b as readonly string[]) {
+    if (!aSet.has(key)) return false;
+  }
+  return true;
+}
+/** @wildo_source:part:end saas.website.astro.label-key-collector */