@wildo-ai/saas-website 1.1.1

package/LICENSE

@@ -0,0 +1,34 @@
+Copyright (c) 2026 P2C Consulting, s.à r.l.-S
+RCS Luxembourg B307591
+6C, Porte de France, L-4360 Esch-sur-Alzette, Luxembourg
+
+All rights reserved.
+
+This software and its accompanying materials (the "Software") are the
+confidential and proprietary property of P2C Consulting, s.à r.l.-S (the
+"Licensor"). The Software is made available for viewing only. No licence,
+right, or permission of any kind is granted by its publication or by its
+availability on any package registry or source repository.
+
+Without the Licensor's prior written permission, you may not use, copy,
+reproduce, modify, adapt, translate, merge, publish, distribute, sublicense,
+sell, host, or create derivative works of the Software, in whole or in part,
+nor use it to provide a service to any third party.
+
+Publication of the Software in any public registry is for distribution to
+authorised recipients and for technical evaluation of its packaging only. It
+does not place the Software in the public domain, does not constitute an open
+source release, and does not waive any right of the Licensor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Third-party components distributed with the Software remain governed by their
+own licences.
+
+Contact: P2C Consulting, s.à r.l.-S, 6C, Porte de France, L-4360
+Esch-sur-Alzette, Luxembourg.

package/dist/esm/.builder.pid

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "writerPid": 95147,
+  "orchestratorPid": 94847,
+  "orchestratorSessionId": null,
+  "orchestratorStartedAt": "Mon Aug 31 09:18:19 2026",
+  "distDirectory": "/Users/paulcayon/Projects/Wildo.ai/dev/wildo-ai/engine/saas-website/dist/esm",
+  "acquiredAt": "2026-08-31T07:18:20.760Z"
+}

package/dist/esm/astro/blog-post-bridge.d.ts

@@ -0,0 +1,324 @@
+import type { ComponentType, FunctionComponent } from 'react';
+import type { FrontendProvidersBlock } from '@wildo-ai/saas-models/public-runtime';
+import type { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+import { BLOG_POST_PAGE_REF } from '../mdx/BlogPost';
+import type { WebsiteMdxComponentsMap } from '../mdx/website-mdx-provider';
+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 { LabelPack } from '../schemas/validators/label-pack.validator';
+/**
+ * @wildo_source:part:start saas.website.blog.bridge facet:layer:astro facet:family:website
+ *
+ * `createWebsiteBlogPostBridgeIsland(deps)` — factory that returns the
+ * React island a consumer's per-locale `*.bridge.tsx` module exports for
+ * mounting blog post pages. **Sibling** of `createWebsitePageBridgeIsland`
+ * but adapted to the dynamic-routing constraint of the marketing-blog
+ * adapter (Phase 7, D-6 = Option A).
+ *
+ * # Why blog posts cannot reuse the page bridge factory
+ *
+ * Three structural differences between marketing pages and blog posts
+ * forced this dedicated factory shape:
+ *
+ *   1. **Per-slug body resolution.** A marketing page (`landing`,
+ *      `pricing`, etc.) has ONE `PageComponent` known at bridge-module
+ *      load time — the page bridge closes over it. A blog post's body
+ *      is the compiled MDX module, which varies per slug. Closing the
+ *      MDX body inside the factory at module load time would force one
+ *      bridge file per post (defeats Q16=B "one MDX file per post").
+ *      Instead, the factory closes over a `slugToMdxBody: Record<string,
+ *      ComponentType>` map — typically built from
+ *      `import.meta.glob('./content/blog/<locale>/*.mdx', { eager: true })`
+ *      on the consumer side — and the island accepts the active `slug`
+ *      as a primitive (JSON-serializable) prop.
+ *
+ *   2. **Layout already wrapped by `<BlogPost>`.** The page bridge wraps
+ *      its `PageComponent` in `<WebsitePageLayout pageRef={…}>`. The
+ *      `<BlogPost>` renderer ALREADY wraps its tree in
+ *      `<WebsitePageLayout pageRef={BLOG_POST_PAGE_REF}>` (the framework
+ *      reserves the page ref for the entire blog surface — see
+ *      `BLOG_POST_PAGE_REF` JSDoc in `BlogPost.tsx`). Reusing the page
+ *      bridge would double-wrap the layout. This factory instead
+ *      provides the runtime context and yields directly to `<BlogPost>`,
+ *      which owns the layout boundary itself.
+ *
+ *   3. **Astro's React-children context-propagation gap.** Astro
+ *      renders React component children INDEPENDENTLY of the parent
+ *      component when the boundary is `.astro` ↔ `.tsx`, even on the
+ *      server side. This means
+ *      `<BlogPost client:load><Content /></BlogPost>` written in an
+ *      `.astro` file would NOT propagate the `<WebsiteMdxProvider>`
+ *      context to the React components embedded inside `<Content />`
+ *      (the embedded `<CTASection />` would render WITHOUT the engine's
+ *      MDX provider scope; the `mdxComponents` map would be ignored).
+ *      Confirmed via the Astro docs, `@astrojs/react` integration
+ *      readme, and the documented "Bridging two JSX runtimes" gotcha.
+ *
+ *      The fix: the entire blog post tree (BlogPost + MDX body +
+ *      embedded section components) lives inside ONE React island. The
+ *      MDX module is imported as a React component via Astro's
+ *      `import.meta.glob`, and the bridge renders it as JSX children
+ *      of `<BlogPost>` from INSIDE the island — no `.astro` ↔ `.tsx`
+ *      boundary is crossed during the body render.
+ *
+ * # Why hydration is required (vs. pure SSR)
+ *
+ * The `WebsiteRuntimeContextProvider` + `<BlogPost>` tree could in
+ * theory render on the server only (no `client:*` directive). But:
+ *
+ *   - Embedded sections (`<CTASection />`) typically have their own
+ *     interactivity (analytics handlers, A/B variant flippers, etc.)
+ *     that need React event listeners to attach client-side.
+ *   - The framework's `useWebsiteLabel(...)` hook chain assumes a live
+ *     React render tree — a pure-SSR tree would freeze label resolution
+ *     at build time, but any future client-driven label override (e.g.
+ *     a debug-mode label inspector) would silently break.
+ *
+ * The factory therefore returns an island that the consumer's `.astro`
+ * mounts with `client:load` (or `client:idle` for posts known to be
+ * non-interactive). The hydration cost is bounded by the per-locale MDX
+ * glob — see "Bundle scaling cliff" below.
+ *
+ * # Bundle scaling cliff (deferred trade-off)
+ *
+ * `import.meta.glob({ eager: true })` materializes EVERY post's
+ * compiled JS into the per-locale React-island bundle (~5–20 KB per
+ * post depending on length and embedded section count). For the
+ * Phase 7 dogfood (≤10 posts) this is fine and matches the documented
+ * Astro+MDX pattern. Past ~50 posts this becomes a real budget concern.
+ * The factory's API is forward-compatible with `{ eager: false }`
+ * (lazy loaders): swap the consumer's glob to lazy mode and the
+ * `slugToMdxBody[slug]` lookup returns a `() => Promise<{ default:
+ * ComponentType }>`; wrap in `React.lazy()` + `<Suspense>` and the
+ * factory call site stays unchanged. The migration is a consumer-side
+ * change, not an engine API break.
+ *
+ * # Authoring pattern
+ *
+ * **Per-locale bridge file** (consumer side, ONE per locale):
+ *
+ * ```tsx
+ * // examples/<app>/website/src/pages-impl/blog-post-en.bridge.tsx
+ * import type { ComponentType } from 'react';
+ *
+ * import { createWebsiteBlogPostBridgeIsland }
+ *   from '@wildo-ai/saas-website/mdx';
+ * import { BLOG_POST_MDX_COMPONENTS }
+ *   from './blog-post.mdx-components';
+ * import { WEBSITE_ROOT_CONFIG } from '../website-root.config';
+ *
+ * // Static analyzable glob — Vite resolves at build time. The glob
+ * // pattern MUST be a single string literal (no concatenation, no
+ * // variable interpolation); Vite parses it AST-side. The `as` cast
+ * // narrows the unknown record to the per-MDX-file shape Astro's mdx
+ * // integration emits (default export = the compiled React component).
+ * const rawModules = import.meta.glob('./content/blog/en/*.mdx', {
+ *   eager: true,
+ * }) as Record<string, { default: ComponentType }>;
+ *
+ * const slugToMdxBody: Record<string, ComponentType> = {};
+ * for (const [path, mod] of Object.entries(rawModules)) {
+ *   // './content/blog/en/why-context.mdx' -> 'why-context'
+ *   const slug = path.split('/').pop()!.replace(/\.mdx$/, '');
+ *   slugToMdxBody[slug] = mod.default;
+ * }
+ *
+ * export const BlogPostEnBridgeIsland =
+ *   createWebsiteBlogPostBridgeIsland({
+ *     slugToMdxBody,
+ *     navigation: WEBSITE_ROOT_CONFIG.navigation,
+ *     mdxComponents: BLOG_POST_MDX_COMPONENTS,
+ *   });
+ * ```
+ *
+ * **Per-locale `[slug].astro` shell** (consumer side):
+ *
+ * ```astro
+ * ---
+ * import { getCollection } from 'astro:content';
+ * import {
+ *   loadWebsitePageRuntime,
+ *   renderBlogPostHeadHtml,
+ *   renderWebsiteDesignTokensCss,
+ * } from '@wildo-ai/saas-website/astro';
+ * import { parseBlogPostFrontmatter } from '@wildo-ai/saas-website/mdx';
+ * import { BlogPostEnBridgeIsland } from '@/pages-impl/blog-post-en.bridge';
+ * import { BLOG_POST_PAGE_MANIFEST } from '@/pages-impl/blog-post.page';
+ * import { WEBSITE_SITE_CONTEXT } from '@/website-site-context';
+ *
+ * export async function getStaticPaths() {
+ *   const posts = await getCollection('blog');
+ *   const defaultLocale = WEBSITE_SITE_CONTEXT.websiteConfig.defaultLocale;
+ *   return posts
+ *     .filter((p) => p.data.locale === defaultLocale)
+ *     .map((p) => ({ params: { slug: p.data.slug }, props: { entry: p } }));
+ * }
+ * const { entry } = Astro.props;
+ *
+ * const runtime = loadWebsitePageRuntime({
+ *   manifest: BLOG_POST_PAGE_MANIFEST,
+ *   siteContext: WEBSITE_SITE_CONTEXT,
+ *   labelPacksDir: './src/i18n',
+ *   astroLocale: Astro.currentLocale,
+ * });
+ * const frontmatter = parseBlogPostFrontmatter(entry.data, { source: entry.id });
+ * const headHtml = renderBlogPostHeadHtml({
+ *   siteContext: WEBSITE_SITE_CONTEXT,
+ *   locale: runtime.locale,
+ *   routePath: `/blog/${frontmatter.slug}`,
+ *   frontmatter,
+ * });
+ * const designTokensCss = renderWebsiteDesignTokensCss(
+ *   WEBSITE_SITE_CONTEXT.rootConfig.designTokens,
+ * );
+ * ---
+ * <!doctype html>
+ * <html lang={runtime.locale}>
+ *   <head>
+ *     <meta charset="UTF-8" />
+ *     <meta name="viewport" content="width=device-width,initial-scale=1.0" />
+ *     <Fragment set:html={headHtml} />
+ *     <style set:html={designTokensCss}></style>
+ *   </head>
+ *   <body>
+ *     <BlogPostEnBridgeIsland
+ *       client:load
+ *       slug={frontmatter.slug}
+ *       rawFrontmatter={entry.data}
+ *       source={entry.id}
+ *       locale={runtime.locale}
+ *       defaultLocale={runtime.defaultLocale}
+ *       labelPack={runtime.labelPack}
+ *       designTokens={WEBSITE_SITE_CONTEXT.rootConfig.designTokens}
+ *       skipToMainContentLabelKey={
+ *         WEBSITE_SITE_CONTEXT.rootConfig.skipToMainContentLabelKey
+ *       }
+ *     />
+ *   </body>
+ * </html>
+ * ```
+ *
+ * # Boundary
+ *
+ * Strictly client-bundle-safe (re-exported from `mdx.ts` — NOT from
+ * `astro-island.ts`, because this module hard-imports the MDX adapter
+ * whose `@mdx-js/react` peer is optional; walked by the
+ * bundle-isolation test). MUST stay clear of `node:*` and SSR-tier
+ * specifiers.
+ */
+/**
+ * Module-load-time dependencies — closed over inside the returned
+ * island. NEVER cross the hydration boundary as serialized props.
+ */
+export interface CreateWebsiteBlogPostBridgeIslandDeps {
+    /**
+     * Per-slug map of compiled MDX bodies (each entry is a React
+     * component — the `.default` export of the MDX module). Typically
+     * built from `import.meta.glob('./content/blog/<locale>/*.mdx',
+     * { eager: true })` with the path-key normalized to the slug. Closed
+     * over at module-load time so the entire MDX body graph for the
+     * locale lands inside ONE React island bundle (D-6 Option A) — this
+     * is the structural fix for Astro's React-children context-propagation
+     * gap (see file preamble).
+     *
+     * The map is read by `slugToMdxBody[props.slug]` at island render
+     * time. A missing slug throws a clear framework-owned error (rather than
+     * rendering an empty body silently); the consumer's `getStaticPaths`
+     * is responsible for not emitting routes for slugs absent from the
+     * map.
+     *
+     * **Why `ComponentType<any>` and not a stricter generic**: matches
+     * the upstream `@mdx-js/react` convention (`MDXContent` from
+     * `mdx/types` is parameterized over an open `MDXProps` shape). MDX
+     * compilation hands the body a compiler-managed props object that
+     * the type system cannot narrow at the framework boundary; using
+     * `<any>` here keeps the consumer's
+     * `import.meta.glob(...) as Record<string, { default: ComponentType }>`
+     * cast assignable without an additional wrap/unwrap. Same posture
+     * as `WebsiteMdxComponentsMap` (intentional symmetry).
+     */
+    slugToMdxBody: Readonly<Record<string, ComponentType<any>>>;
+    /**
+     * Site-wide navigation slot bindings (header / footer components).
+     * Closed over here for the same reason as the page bridge: both
+     * fields are `ComponentType` refs that cannot survive Astro's
+     * serialization boundary.
+     */
+    navigation: WebsiteNavigationConfig;
+    /**
+     * MDX-tag → React-component map forwarded into `<BlogPost>` and
+     * scoped via `<WebsiteMdxProvider>`. Typically a small object
+     * literal exporting the consumer-authored business sections that
+     * blog posts can embed (`<CTASection />`, etc.). Closed over here
+     * (rather than passed as an island prop) because the values are
+     * `ComponentType` refs.
+     */
+    mdxComponents?: WebsiteMdxComponentsMap;
+}
+/**
+ * Hydration-boundary props — what the consumer's `.astro` page passes
+ * to `<BlogPostEnBridgeIsland client:load ...{primitiveProps}/>`.
+ * Every field is JSON-serializable.
+ */
+export interface WebsiteBlogPostBridgeIslandProps {
+    /**
+     * Slug of the post being rendered. Used by the island to look up
+     * the matching MDX body in `deps.slugToMdxBody`. Carried as a plain
+     * string (not the branded `BlogPostSlug`) because Astro's
+     * serialization boundary unwraps brands.
+     */
+    slug: string;
+    /**
+     * Raw frontmatter object Astro hands the page from `entry.data`.
+     * Forwarded straight to `<BlogPost>` for strict Zod-4 validation.
+     * The bridge does NOT re-validate (single validation surface, owned
+     * by the renderer).
+     */
+    rawFrontmatter: unknown;
+    /**
+     * Diagnostic source identifier echoed into validation errors —
+     * typically `entry.id` from Astro's content collection. Optional
+     * but recommended for actionable error messages.
+     */
+    source?: string;
+    /** The locale Astro resolved (with default-locale fallback). */
+    locale: AvailableLanguage;
+    /**
+     * The site's default locale. Required for `WebsiteInternalLink`
+     * locale-prefix logic (mirrors the page bridge's `defaultLocale`
+     * island prop).
+     */
+    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. Mirrors
+     * `WebsiteRootConfig.skipToMainContentLabelKey`. Carried as a
+     * primitive island prop for the same reason as the page bridge.
+     */
+    skipToMainContentLabelKey: WebsiteLabelKey;
+    /** Optional website-facing public providers materialized at build time. */
+    frontendProviders?: FrontendProvidersBlock;
+}
+/**
+ * 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 declaring it
+ * cost callers the ability to invoke the island directly (which the bridge suites do, to observe
+ * the synchronous throw for an unregistered slug without routing it through React's reconciler
+ * error path). `FunctionComponent` is assignable to `ComponentType`, so no consumer narrows.
+ */
+export declare function createWebsiteBlogPostBridgeIsland(deps: CreateWebsiteBlogPostBridgeIslandDeps): FunctionComponent<WebsiteBlogPostBridgeIslandProps>;
+/**
+ * Re-export of the framework-reserved blog-post page ref. Consumers
+ * authoring `BLOG_POST_PAGE_MANIFEST` need this constant to satisfy
+ * the manifest's `ref` field; re-exporting it from the bridge module
+ * means the consumer's per-locale bridge file can grab both symbols
+ * from the one `@wildo-ai/saas-website/mdx` import it already has.
+ */
+export { BLOG_POST_PAGE_REF };
+/** @wildo_source:part:end saas.website.blog.bridge */
+//# sourceMappingURL=blog-post-bridge.d.ts.map

package/dist/esm/astro/blog-post-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blog-post-bridge.d.ts","sourceRoot":"","sources":["../../../../src/astro/blog-post-bridge.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAa,MAAM,OAAO,CAAC;AAEzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AACnF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAO9E,OAAO,EAAY,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+DAA+D,CAAC;AACzG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iDAAiD,CAAC;AACvF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yDAAyD,CAAC;AACvG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuMG;AAEH;;;GAGG;AACH,MAAM,WAAW,qCAAqC;IACpD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC5D;;;;;OAKG;IACH,UAAU,EAAE,uBAAuB,CAAC;IACpC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,uBAAuB,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;OAIG;IACH,aAAa,EAAE,iBAAiB,CAAC;IACjC,2DAA2D;IAC3D,SAAS,EAAE,SAAS,CAAC;IACrB,iEAAiE;IACjE,YAAY,EAAE,mBAAmB,CAAC;IAClC;;;;;OAKG;IACH,yBAAyB,EAAE,eAAe,CAAC;IAC3C,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;CAC5C;AAID;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,qCAAqC,GAC1C,iBAAiB,CAAC,gCAAgC,CAAC,CAiErD;AAED;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAC9B,sDAAsD"}

package/dist/esm/astro/blog-post-bridge.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { WebsiteRuntimeContextProvider, } from '../core/contexts/WebsiteRuntimeContext.js';
+import { createFrontendWebsiteProviderRegistry } from '../core/external-providers/frontend-provider-registry.website.js';
+import { BlogPost, BLOG_POST_PAGE_REF } from '../mdx/BlogPost.js';
+const EMPTY_MDX_COMPONENTS = Object.freeze({});
+/**
+ * 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 declaring it
+ * cost callers the ability to invoke the island directly (which the bridge suites do, to observe
+ * the synchronous throw for an unregistered slug without routing it through React's reconciler
+ * error path). `FunctionComponent` is assignable to `ComponentType`, so no consumer narrows.
+ */
+export function createWebsiteBlogPostBridgeIsland(deps) {
+    const { slugToMdxBody, navigation, mdxComponents = EMPTY_MDX_COMPONENTS, } = deps;
+    function WebsiteBlogPostBridgeIsland({ slug, rawFrontmatter, source, locale, defaultLocale, labelPack, designTokens, skipToMainContentLabelKey, frontendProviders, }) {
+        const MdxBody = slugToMdxBody[slug];
+        if (MdxBody === undefined) {
+            /**
+             * Loud failure — the consumer's `getStaticPaths` is supposed to
+             * only emit routes for slugs present in the MDX glob. A missing
+             * lookup means the glob and the collection are out of sync; the
+             * operator needs an actionable error string with the offending
+             * slug + the keys that ARE present (truncated to keep the build
+             * log readable).
+             */
+            const knownKeys = Object.keys(slugToMdxBody);
+            const known = knownKeys.length <= 5
+                ? knownKeys.join(', ')
+                : `${knownKeys.slice(0, 5).join(', ')}, … (${knownKeys.length} total)`;
+            throw new Error(`[blog-post-bridge] No MDX body registered for slug="${slug}". ` +
+                `The bridge factory's slugToMdxBody map only knows: ${known}. ` +
+                `Verify the consumer's import.meta.glob('...content/blog/<locale>/*.mdx') ` +
+                `pattern matches the source file naming.`);
+        }
+        const runtimeValue = {
+            locale,
+            defaultLocale,
+            labelPack,
+            designTokens,
+            navigation,
+            skipToMainContentLabelKey,
+            frontendProviderRegistry: createFrontendWebsiteProviderRegistry(frontendProviders),
+        };
+        return (_jsx(WebsiteRuntimeContextProvider, { value: runtimeValue, children: _jsx(BlogPost, { rawFrontmatter: rawFrontmatter, source: source, mdxComponents: mdxComponents, children: _jsx(MdxBody, {}) }) }));
+    }
+    WebsiteBlogPostBridgeIsland.displayName = 'WebsiteBlogPostBridgeIsland';
+    return WebsiteBlogPostBridgeIsland;
+}
+/**
+ * Re-export of the framework-reserved blog-post page ref. Consumers
+ * authoring `BLOG_POST_PAGE_MANIFEST` need this constant to satisfy
+ * the manifest's `ref` field; re-exporting it from the bridge module
+ * means the consumer's per-locale bridge file can grab both symbols
+ * from the one `@wildo-ai/saas-website/mdx` import it already has.
+ */
+export { BLOG_POST_PAGE_REF };
+//# sourceMappingURL=blog-post-bridge.js.map

package/dist/esm/astro/blog-post-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blog-post-bridge.js","sourceRoot":"","sources":["../../../../src/astro/blog-post-bridge.tsx"],"names":[],"mappings":";AAKA,OAAO,EACL,6BAA6B,GAE9B,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,qCAAqC,EAAE,MAAM,+DAA+D,CAAC;AACtH,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAmT/D,MAAM,oBAAoB,GAA4B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,UAAU,iCAAiC,CAC/C,IAA2C;IAE3C,MAAM,EACJ,aAAa,EACb,UAAU,EACV,aAAa,GAAG,oBAAoB,GACrC,GAAG,IAAI,CAAC;IAET,SAAS,2BAA2B,CAAC,EACnC,IAAI,EACJ,cAAc,EACd,MAAM,EACN,MAAM,EACN,aAAa,EACb,SAAS,EACT,YAAY,EACZ,yBAAyB,EACzB,iBAAiB,GACgB;QACjC,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B;;;;;;;eAOG;YACH,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAC7C,MAAM,KAAK,GACT,SAAS,CAAC,MAAM,IAAI,CAAC;gBACnB,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;gBACtB,CAAC,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,SAAS,CAAC,MAAM,SAAS,CAAC;YAC3E,MAAM,IAAI,KAAK,CACb,uDAAuD,IAAI,KAAK;gBAC9D,sDAAsD,KAAK,IAAI;gBAC/D,2EAA2E;gBAC3E,yCAAyC,CAC5C,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAA+B;YAC/C,MAAM;YACN,aAAa;YACb,SAAS;YACT,YAAY;YACZ,UAAU;YACV,yBAAyB;YACzB,wBAAwB,EAAE,qCAAqC,CAAC,iBAAiB,CAAC;SACnF,CAAC;QACF,OAAO,CACL,KAAC,6BAA6B,IAAC,KAAK,EAAE,YAAY,YAChD,KAAC,QAAQ,IACP,cAAc,EAAE,cAAc,EAC9B,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,aAAa,YAE5B,KAAC,OAAO,KAAG,GACF,GACmB,CACjC,CAAC;IACJ,CAAC;IACD,2BAA2B,CAAC,WAAW,GAAG,6BAA6B,CAAC;IAExE,OAAO,2BAA2B,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAE,CAAC","sourcesContent":["import type { ComponentType, FunctionComponent, ReactNode } from 'react';\n\nimport type { FrontendProvidersBlock } from '@wildo-ai/saas-models/public-runtime';\nimport type { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';\n\nimport {\n  WebsiteRuntimeContextProvider,\n  type WebsiteRuntimeContextValue,\n} from '../core/contexts/WebsiteRuntimeContext';\nimport { createFrontendWebsiteProviderRegistry } from '../core/external-providers/frontend-provider-registry.website';\nimport { BlogPost, BLOG_POST_PAGE_REF } from '../mdx/BlogPost';\nimport type { WebsiteMdxComponentsMap } from '../mdx/website-mdx-provider';\nimport type { WebsiteDesignTokens } from '../schemas/design-tokens/website-design-tokens.shared.schemas';\nimport type { WebsiteLabelKey } from '../schemas/label-keys/website-label-key.schemas';\nimport type { WebsiteNavigationConfig } from '../schemas/manifests/website-root-config.shared.schemas';\nimport type { LabelPack } from '../schemas/validators/label-pack.validator';\n\n/**\n * @wildo_source:part:start saas.website.blog.bridge facet:layer:astro facet:family:website\n *\n * `createWebsiteBlogPostBridgeIsland(deps)` — factory that returns the\n * React island a consumer's per-locale `*.bridge.tsx` module exports for\n * mounting blog post pages. **Sibling** of `createWebsitePageBridgeIsland`\n * but adapted to the dynamic-routing constraint of the marketing-blog\n * adapter (Phase 7, D-6 = Option A).\n *\n * # Why blog posts cannot reuse the page bridge factory\n *\n * Three structural differences between marketing pages and blog posts\n * forced this dedicated factory shape:\n *\n *   1. **Per-slug body resolution.** A marketing page (`landing`,\n *      `pricing`, etc.) has ONE `PageComponent` known at bridge-module\n *      load time — the page bridge closes over it. A blog post's body\n *      is the compiled MDX module, which varies per slug. Closing the\n *      MDX body inside the factory at module load time would force one\n *      bridge file per post (defeats Q16=B \"one MDX file per post\").\n *      Instead, the factory closes over a `slugToMdxBody: Record<string,\n *      ComponentType>` map — typically built from\n *      `import.meta.glob('./content/blog/<locale>/*.mdx', { eager: true })`\n *      on the consumer side — and the island accepts the active `slug`\n *      as a primitive (JSON-serializable) prop.\n *\n *   2. **Layout already wrapped by `<BlogPost>`.** The page bridge wraps\n *      its `PageComponent` in `<WebsitePageLayout pageRef={…}>`. The\n *      `<BlogPost>` renderer ALREADY wraps its tree in\n *      `<WebsitePageLayout pageRef={BLOG_POST_PAGE_REF}>` (the framework\n *      reserves the page ref for the entire blog surface — see\n *      `BLOG_POST_PAGE_REF` JSDoc in `BlogPost.tsx`). Reusing the page\n *      bridge would double-wrap the layout. This factory instead\n *      provides the runtime context and yields directly to `<BlogPost>`,\n *      which owns the layout boundary itself.\n *\n *   3. **Astro's React-children context-propagation gap.** Astro\n *      renders React component children INDEPENDENTLY of the parent\n *      component when the boundary is `.astro` ↔ `.tsx`, even on the\n *      server side. This means\n *      `<BlogPost client:load><Content /></BlogPost>` written in an\n *      `.astro` file would NOT propagate the `<WebsiteMdxProvider>`\n *      context to the React components embedded inside `<Content />`\n *      (the embedded `<CTASection />` would render WITHOUT the engine's\n *      MDX provider scope; the `mdxComponents` map would be ignored).\n *      Confirmed via the Astro docs, `@astrojs/react` integration\n *      readme, and the documented \"Bridging two JSX runtimes\" gotcha.\n *\n *      The fix: the entire blog post tree (BlogPost + MDX body +\n *      embedded section components) lives inside ONE React island. The\n *      MDX module is imported as a React component via Astro's\n *      `import.meta.glob`, and the bridge renders it as JSX children\n *      of `<BlogPost>` from INSIDE the island — no `.astro` ↔ `.tsx`\n *      boundary is crossed during the body render.\n *\n * # Why hydration is required (vs. pure SSR)\n *\n * The `WebsiteRuntimeContextProvider` + `<BlogPost>` tree could in\n * theory render on the server only (no `client:*` directive). But:\n *\n *   - Embedded sections (`<CTASection />`) typically have their own\n *     interactivity (analytics handlers, A/B variant flippers, etc.)\n *     that need React event listeners to attach client-side.\n *   - The framework's `useWebsiteLabel(...)` hook chain assumes a live\n *     React render tree — a pure-SSR tree would freeze label resolution\n *     at build time, but any future client-driven label override (e.g.\n *     a debug-mode label inspector) would silently break.\n *\n * The factory therefore returns an island that the consumer's `.astro`\n * mounts with `client:load` (or `client:idle` for posts known to be\n * non-interactive). The hydration cost is bounded by the per-locale MDX\n * glob — see \"Bundle scaling cliff\" below.\n *\n * # Bundle scaling cliff (deferred trade-off)\n *\n * `import.meta.glob({ eager: true })` materializes EVERY post's\n * compiled JS into the per-locale React-island bundle (~5–20 KB per\n * post depending on length and embedded section count). For the\n * Phase 7 dogfood (≤10 posts) this is fine and matches the documented\n * Astro+MDX pattern. Past ~50 posts this becomes a real budget concern.\n * The factory's API is forward-compatible with `{ eager: false }`\n * (lazy loaders): swap the consumer's glob to lazy mode and the\n * `slugToMdxBody[slug]` lookup returns a `() => Promise<{ default:\n * ComponentType }>`; wrap in `React.lazy()` + `<Suspense>` and the\n * factory call site stays unchanged. The migration is a consumer-side\n * change, not an engine API break.\n *\n * # Authoring pattern\n *\n * **Per-locale bridge file** (consumer side, ONE per locale):\n *\n * ```tsx\n * // examples/<app>/website/src/pages-impl/blog-post-en.bridge.tsx\n * import type { ComponentType } from 'react';\n *\n * import { createWebsiteBlogPostBridgeIsland }\n *   from '@wildo-ai/saas-website/mdx';\n * import { BLOG_POST_MDX_COMPONENTS }\n *   from './blog-post.mdx-components';\n * import { WEBSITE_ROOT_CONFIG } from '../website-root.config';\n *\n * // Static analyzable glob — Vite resolves at build time. The glob\n * // pattern MUST be a single string literal (no concatenation, no\n * // variable interpolation); Vite parses it AST-side. The `as` cast\n * // narrows the unknown record to the per-MDX-file shape Astro's mdx\n * // integration emits (default export = the compiled React component).\n * const rawModules = import.meta.glob('./content/blog/en/*.mdx', {\n *   eager: true,\n * }) as Record<string, { default: ComponentType }>;\n *\n * const slugToMdxBody: Record<string, ComponentType> = {};\n * for (const [path, mod] of Object.entries(rawModules)) {\n *   // './content/blog/en/why-context.mdx' -> 'why-context'\n *   const slug = path.split('/').pop()!.replace(/\\.mdx$/, '');\n *   slugToMdxBody[slug] = mod.default;\n * }\n *\n * export const BlogPostEnBridgeIsland =\n *   createWebsiteBlogPostBridgeIsland({\n *     slugToMdxBody,\n *     navigation: WEBSITE_ROOT_CONFIG.navigation,\n *     mdxComponents: BLOG_POST_MDX_COMPONENTS,\n *   });\n * ```\n *\n * **Per-locale `[slug].astro` shell** (consumer side):\n *\n * ```astro\n * ---\n * import { getCollection } from 'astro:content';\n * import {\n *   loadWebsitePageRuntime,\n *   renderBlogPostHeadHtml,\n *   renderWebsiteDesignTokensCss,\n * } from '@wildo-ai/saas-website/astro';\n * import { parseBlogPostFrontmatter } from '@wildo-ai/saas-website/mdx';\n * import { BlogPostEnBridgeIsland } from '@/pages-impl/blog-post-en.bridge';\n * import { BLOG_POST_PAGE_MANIFEST } from '@/pages-impl/blog-post.page';\n * import { WEBSITE_SITE_CONTEXT } from '@/website-site-context';\n *\n * export async function getStaticPaths() {\n *   const posts = await getCollection('blog');\n *   const defaultLocale = WEBSITE_SITE_CONTEXT.websiteConfig.defaultLocale;\n *   return posts\n *     .filter((p) => p.data.locale === defaultLocale)\n *     .map((p) => ({ params: { slug: p.data.slug }, props: { entry: p } }));\n * }\n * const { entry } = Astro.props;\n *\n * const runtime = loadWebsitePageRuntime({\n *   manifest: BLOG_POST_PAGE_MANIFEST,\n *   siteContext: WEBSITE_SITE_CONTEXT,\n *   labelPacksDir: './src/i18n',\n *   astroLocale: Astro.currentLocale,\n * });\n * const frontmatter = parseBlogPostFrontmatter(entry.data, { source: entry.id });\n * const headHtml = renderBlogPostHeadHtml({\n *   siteContext: WEBSITE_SITE_CONTEXT,\n *   locale: runtime.locale,\n *   routePath: `/blog/${frontmatter.slug}`,\n *   frontmatter,\n * });\n * const designTokensCss = renderWebsiteDesignTokensCss(\n *   WEBSITE_SITE_CONTEXT.rootConfig.designTokens,\n * );\n * ---\n * <!doctype html>\n * <html lang={runtime.locale}>\n *   <head>\n *     <meta charset=\"UTF-8\" />\n *     <meta name=\"viewport\" content=\"width=device-width,initial-scale=1.0\" />\n *     <Fragment set:html={headHtml} />\n *     <style set:html={designTokensCss}></style>\n *   </head>\n *   <body>\n *     <BlogPostEnBridgeIsland\n *       client:load\n *       slug={frontmatter.slug}\n *       rawFrontmatter={entry.data}\n *       source={entry.id}\n *       locale={runtime.locale}\n *       defaultLocale={runtime.defaultLocale}\n *       labelPack={runtime.labelPack}\n *       designTokens={WEBSITE_SITE_CONTEXT.rootConfig.designTokens}\n *       skipToMainContentLabelKey={\n *         WEBSITE_SITE_CONTEXT.rootConfig.skipToMainContentLabelKey\n *       }\n *     />\n *   </body>\n * </html>\n * ```\n *\n * # Boundary\n *\n * Strictly client-bundle-safe (re-exported from `mdx.ts` — NOT from\n * `astro-island.ts`, because this module hard-imports the MDX adapter\n * whose `@mdx-js/react` peer is optional; walked by the\n * bundle-isolation test). MUST stay clear of `node:*` and SSR-tier\n * specifiers.\n */\n\n/**\n * Module-load-time dependencies — closed over inside the returned\n * island. NEVER cross the hydration boundary as serialized props.\n */\nexport interface CreateWebsiteBlogPostBridgeIslandDeps {\n  /**\n   * Per-slug map of compiled MDX bodies (each entry is a React\n   * component — the `.default` export of the MDX module). Typically\n   * built from `import.meta.glob('./content/blog/<locale>/*.mdx',\n   * { eager: true })` with the path-key normalized to the slug. Closed\n   * over at module-load time so the entire MDX body graph for the\n   * locale lands inside ONE React island bundle (D-6 Option A) — this\n   * is the structural fix for Astro's React-children context-propagation\n   * gap (see file preamble).\n   *\n   * The map is read by `slugToMdxBody[props.slug]` at island render\n   * time. A missing slug throws a clear framework-owned error (rather than\n   * rendering an empty body silently); the consumer's `getStaticPaths`\n   * is responsible for not emitting routes for slugs absent from the\n   * map.\n   *\n   * **Why `ComponentType<any>` and not a stricter generic**: matches\n   * the upstream `@mdx-js/react` convention (`MDXContent` from\n   * `mdx/types` is parameterized over an open `MDXProps` shape). MDX\n   * compilation hands the body a compiler-managed props object that\n   * the type system cannot narrow at the framework boundary; using\n   * `<any>` here keeps the consumer's\n   * `import.meta.glob(...) as Record<string, { default: ComponentType }>`\n   * cast assignable without an additional wrap/unwrap. Same posture\n   * as `WebsiteMdxComponentsMap` (intentional symmetry).\n   */\n  slugToMdxBody: Readonly<Record<string, ComponentType<any>>>;\n  /**\n   * Site-wide navigation slot bindings (header / footer components).\n   * Closed over here for the same reason as the page bridge: both\n   * fields are `ComponentType` refs that cannot survive Astro's\n   * serialization boundary.\n   */\n  navigation: WebsiteNavigationConfig;\n  /**\n   * MDX-tag → React-component map forwarded into `<BlogPost>` and\n   * scoped via `<WebsiteMdxProvider>`. Typically a small object\n   * literal exporting the consumer-authored business sections that\n   * blog posts can embed (`<CTASection />`, etc.). Closed over here\n   * (rather than passed as an island prop) because the values are\n   * `ComponentType` refs.\n   */\n  mdxComponents?: WebsiteMdxComponentsMap;\n}\n\n/**\n * Hydration-boundary props — what the consumer's `.astro` page passes\n * to `<BlogPostEnBridgeIsland client:load ...{primitiveProps}/>`.\n * Every field is JSON-serializable.\n */\nexport interface WebsiteBlogPostBridgeIslandProps {\n  /**\n   * Slug of the post being rendered. Used by the island to look up\n   * the matching MDX body in `deps.slugToMdxBody`. Carried as a plain\n   * string (not the branded `BlogPostSlug`) because Astro's\n   * serialization boundary unwraps brands.\n   */\n  slug: string;\n  /**\n   * Raw frontmatter object Astro hands the page from `entry.data`.\n   * Forwarded straight to `<BlogPost>` for strict Zod-4 validation.\n   * The bridge does NOT re-validate (single validation surface, owned\n   * by the renderer).\n   */\n  rawFrontmatter: unknown;\n  /**\n   * Diagnostic source identifier echoed into validation errors —\n   * typically `entry.id` from Astro's content collection. Optional\n   * but recommended for actionable error messages.\n   */\n  source?: string;\n  /** The locale Astro resolved (with default-locale fallback). */\n  locale: AvailableLanguage;\n  /**\n   * The site's default locale. Required for `WebsiteInternalLink`\n   * locale-prefix logic (mirrors the page bridge's `defaultLocale`\n   * island prop).\n   */\n  defaultLocale: AvailableLanguage;\n  /** Already-loaded + already-shape-validated label pack. */\n  labelPack: LabelPack;\n  /** Design-token bundle from `WebsiteRootConfig.designTokens`. */\n  designTokens: WebsiteDesignTokens;\n  /**\n   * Fully-composed label key the framework reads to render the\n   * \"Skip to main content\" affordance. Mirrors\n   * `WebsiteRootConfig.skipToMainContentLabelKey`. Carried as a\n   * primitive island prop for the same reason as the page bridge.\n   */\n  skipToMainContentLabelKey: WebsiteLabelKey;\n  /** Optional website-facing public providers materialized at build time. */\n  frontendProviders?: FrontendProvidersBlock;\n}\n\nconst EMPTY_MDX_COMPONENTS: WebsiteMdxComponentsMap = Object.freeze({});\n\n/**\n * Returns a FUNCTION component, not the wider `ComponentType` union. The island IS a function\n * component — Astro hydrates nothing else here — and the union is not callable, so declaring it\n * cost callers the ability to invoke the island directly (which the bridge suites do, to observe\n * the synchronous throw for an unregistered slug without routing it through React's reconciler\n * error path). `FunctionComponent` is assignable to `ComponentType`, so no consumer narrows.\n */\nexport function createWebsiteBlogPostBridgeIsland(\n  deps: CreateWebsiteBlogPostBridgeIslandDeps,\n): FunctionComponent<WebsiteBlogPostBridgeIslandProps> {\n  const {\n    slugToMdxBody,\n    navigation,\n    mdxComponents = EMPTY_MDX_COMPONENTS,\n  } = deps;\n\n  function WebsiteBlogPostBridgeIsland({\n    slug,\n    rawFrontmatter,\n    source,\n    locale,\n    defaultLocale,\n    labelPack,\n    designTokens,\n    skipToMainContentLabelKey,\n    frontendProviders,\n  }: WebsiteBlogPostBridgeIslandProps): ReactNode {\n    const MdxBody = slugToMdxBody[slug];\n    if (MdxBody === undefined) {\n      /**\n       * Loud failure — the consumer's `getStaticPaths` is supposed to\n       * only emit routes for slugs present in the MDX glob. A missing\n       * lookup means the glob and the collection are out of sync; the\n       * operator needs an actionable error string with the offending\n       * slug + the keys that ARE present (truncated to keep the build\n       * log readable).\n       */\n      const knownKeys = Object.keys(slugToMdxBody);\n      const known =\n        knownKeys.length <= 5\n          ? knownKeys.join(', ')\n          : `${knownKeys.slice(0, 5).join(', ')}, … (${knownKeys.length} total)`;\n      throw new Error(\n        `[blog-post-bridge] No MDX body registered for slug=\"${slug}\". ` +\n          `The bridge factory's slugToMdxBody map only knows: ${known}. ` +\n          `Verify the consumer's import.meta.glob('...content/blog/<locale>/*.mdx') ` +\n          `pattern matches the source file naming.`,\n      );\n    }\n\n    const runtimeValue: WebsiteRuntimeContextValue = {\n      locale,\n      defaultLocale,\n      labelPack,\n      designTokens,\n      navigation,\n      skipToMainContentLabelKey,\n      frontendProviderRegistry: createFrontendWebsiteProviderRegistry(frontendProviders),\n    };\n    return (\n      <WebsiteRuntimeContextProvider value={runtimeValue}>\n        <BlogPost\n          rawFrontmatter={rawFrontmatter}\n          source={source}\n          mdxComponents={mdxComponents}\n        >\n          <MdxBody />\n        </BlogPost>\n      </WebsiteRuntimeContextProvider>\n    );\n  }\n  WebsiteBlogPostBridgeIsland.displayName = 'WebsiteBlogPostBridgeIsland';\n\n  return WebsiteBlogPostBridgeIsland;\n}\n\n/**\n * Re-export of the framework-reserved blog-post page ref. Consumers\n * authoring `BLOG_POST_PAGE_MANIFEST` need this constant to satisfy\n * the manifest's `ref` field; re-exporting it from the bridge module\n * means the consumer's per-locale bridge file can grab both symbols\n * from the one `@wildo-ai/saas-website/mdx` import it already has.\n */\nexport { BLOG_POST_PAGE_REF };\n/** @wildo_source:part:end saas.website.blog.bridge */\n"]}

package/dist/esm/astro/blog-post-head.renderer.d.ts

@@ -0,0 +1,129 @@
+import type { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+import type { BlogPostFrontmatter } from '../schemas/blog/blog-post-frontmatter.shared.schemas';
+import type { WebsiteStructuredDataPayload } from '../schemas/structured-data/website-structured-data.shared.schemas';
+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 declare function buildBlogPostStructuredDataPayload(opts: BuildBlogPostStructuredDataPayloadOptions): WebsiteStructuredDataPayload;
+export declare function renderBlogPostHeadHtml(opts: RenderBlogPostHeadHtmlOptions): string;
+/** @wildo_source:part:end saas.website.blog.head-renderer */
+//# sourceMappingURL=blog-post-head.renderer.d.ts.map

package/dist/esm/astro/blog-post-head.renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blog-post-head.renderer.d.ts","sourceRoot":"","sources":["../../../../src/astro/blog-post-head.renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAG9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sDAAsD,CAAC;AAChG,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mEAAmE,CAAC;AAItH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,MAAM,WAAW,6BAA6B;IAC5C;;;;;;;;;OASG;IACH,WAAW,EAAE,kBAAkB,CAAC;IAChC;;;;OAIG;IACH,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,WAAW,EAAE,mBAAmB,CAAC;IACjC;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,yCAAyC;IACxD,WAAW,EAAE,mBAAmB,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,yCAAyC,GAC9C,4BAA4B,CAuB9B;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,6BAA6B,GAAG,MAAM,CAkIlF;AACD,6DAA6D"}