@wildo-ai/saas-website 1.1.1

package/src/astro/headers-renderer.ts

@@ -0,0 +1,82 @@
+import { buildLocalizedRoutePath } from '../core/routing/internal-routing.utils';
+import type { WebsitePageManifest } from '../schemas/manifests/website-page-manifest.shared.schemas';
+
+import type { WebsiteSiteContext } from './website-site-context';
+
+const NOAI_ROBOTS_HEADER_VALUE = 'noai, noimageai' as const;
+
+/**
+ * @wildo_source:part:start saas.website.astro.headers-renderer facet:layer:astro facet:family:website
+ *
+ * Render a static-host-compatible `_headers` body for every page
+ * manifest whose `seo.noaiOptOut === true`.
+ *
+ * The output format matches Cloudflare Pages / Netlify / Vercel's
+ * path-scoped `_headers` conventions:
+ *
+ * ```txt
+ * /pricing
+ *   X-Robots-Tag: noai, noimageai
+ *
+ * /fr/pricing
+ *   X-Robots-Tag: noai, noimageai
+ * ```
+ */
+export function renderWebsitePageNoaiHeaders(siteContext: WebsiteSiteContext): string {
+  const flaggedPages = siteContext.rootConfig.pageManifests.filter(
+    (manifest) => manifest.seo?.noaiOptOut === true,
+  );
+  if (flaggedPages.length === 0) {
+    return '';
+  }
+
+  const lines: string[] = [];
+  for (const manifest of flaggedPages) {
+    appendManifestHeaders(lines, manifest, siteContext);
+  }
+  return lines.slice(0, -1).join('\n');
+}
+/** @wildo_source:part:end saas.website.astro.headers-renderer */
+
+/**
+ * Future blog-post companion for the same header channel. Kept small
+ * and pure so a consumer's `[slug].astro` route or `_headers`
+ * generation script can opt blog posts out of AI training without
+ * re-implementing the locale-path logic.
+ */
+export function renderBlogPostNoaiHeaders(params: {
+  siteContext: WebsiteSiteContext;
+  routePath: string;
+  noaiOptOut?: boolean;
+}): string {
+  const { siteContext, routePath, noaiOptOut } = params;
+  if (noaiOptOut !== true) {
+    return '';
+  }
+
+  const lines: string[] = [];
+  for (const { locale } of siteContext.websiteConfig.locales) {
+    const localizedPath = buildLocalizedRoutePath({
+      locale,
+      defaultLocale: siteContext.websiteConfig.defaultLocale,
+      routePath,
+    });
+    lines.push(localizedPath, `  X-Robots-Tag: ${NOAI_ROBOTS_HEADER_VALUE}`, '');
+  }
+  return lines.slice(0, -1).join('\n');
+}
+
+function appendManifestHeaders(
+  lines: string[],
+  manifest: WebsitePageManifest,
+  siteContext: WebsiteSiteContext,
+): void {
+  for (const { locale } of siteContext.websiteConfig.locales) {
+    const localizedPath = buildLocalizedRoutePath({
+      locale,
+      defaultLocale: siteContext.websiteConfig.defaultLocale,
+      routePath: String(manifest.routePath),
+    });
+    lines.push(localizedPath, `  X-Robots-Tag: ${NOAI_ROBOTS_HEADER_VALUE}`, '');
+  }
+}

package/src/astro/i18n-routing.helper.ts

@@ -0,0 +1,116 @@
+import type { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import type { WebsiteSiteContext } from './website-site-context';
+
+/**
+ * @wildo_source:part:start saas.website.astro.i18n-helper facet:layer:astro facet:family:website
+ *
+ * `buildAstroI18nConfig(siteContext)` — derives the `i18n` block consumed
+ * by `astro/config`'s `defineConfig({ i18n })` from the shared
+ * `WebsiteSiteContext`.
+ *
+ * **Why a helper and not hand-authored in `astro.config.mjs`**: a
+ * marketing site has TWO sources of truth for "which locales does this
+ * site ship?" — the `WildoMarketingWebsiteConfig.locales` array
+ * (consumed by every Astro build helper) AND the Astro routing config
+ * (consumed by the file-based router and the dev server). Letting the
+ * consumer hand-author both creates a silent-drift surface: a locale
+ * added to one but not the other ships a working dev server with a
+ * missing label pack (or vice versa). This helper makes
+ * `WildoMarketingWebsiteConfig` (the per-service `wildo.website.config.ts`)
+ * the single source of truth.
+ *
+ * **Design decisions** (each carrying its own semantic weight):
+ *
+ * - **`prefixDefaultLocale = false`**. Astro's default routing strategy
+ *   is the marketing-site convention: the default locale mounts at the
+ *   un-prefixed path (`/`, `/pricing`, `/contact`) and other locales
+ *   live under `/<locale>/…`. Forcing prefixes for the default locale
+ *   would surface a `/en/` URL alongside `/` — duplicate content from
+ *   an SEO standpoint and a UX wart. Marketing teams overwhelmingly
+ *   ship the default at the root.
+ *
+ * - **`redirectToDefaultLocale = false`**. The default value Astro
+ *   would otherwise infer (`true`) issues a redirect from `/` to
+ *   `/<defaultLocale>/`, which directly contradicts the
+ *   `prefixDefaultLocale = false` convention above. Setting both
+ *   explicitly makes the contract loud at the call site (and in the
+ *   compiled config) instead of relying on Astro's defaults staying
+ *   stable across versions.
+ *
+ * - **`fallbackType = 'redirect'` is INTENTIONALLY OMITTED**.
+ *   Marketing sites typically prefer one of two strategies: ship a
+ *   page in every advertised locale OR hide the un-shipped locale
+ *   entirely (no entry in `locales`). The `fallback` machinery (which
+ *   would redirect `/de/pricing` to `/en/pricing` when the German
+ *   page is missing) creates SEO duplicate-content risk that's hard
+ *   to undo once Google indexes the redirected URL. Consumers who
+ *   genuinely need fallback can spread this helper's output and
+ *   add `fallback: { … }` themselves.
+ *
+ * **Type rationale**: the return type uses Astro's published `i18n`
+ * shape but we declare it as a structural literal type rather than
+ * importing from `astro` so this module stays in the saas-website
+ * source closure without forcing `astro` into the React-island side of the
+ * bundle. The package's bundle-boundary checks enforce that separation.
+ * The structural type is straightforward and matches Astro 4+ — see
+ * https://docs.astro.build/en/reference/configuration-reference/#i18n.
+ *
+ * @example
+ *   // astro.config.mjs
+ *   import { defineConfig } from 'astro/config';
+ *   import { buildAstroI18nConfig } from '@wildo-ai/saas-website/astro';
+ *   import { WEBSITE_SITE_CONTEXT } from './src/website-site-context';
+ *
+ *   export default defineConfig({
+ *     i18n: buildAstroI18nConfig(WEBSITE_SITE_CONTEXT),
+ *   });
+ */
+export interface AstroI18nConfig {
+  /** ISO locale string Astro mounts at the un-prefixed path. */
+  defaultLocale: string;
+  /** Every locale the site ships in (default included). */
+  locales: readonly string[];
+  routing: {
+    /**
+     * `false` means the default locale is served at the root path
+     * (`/`); other locales sit under `/<locale>/`. Typed as a
+     * widened `boolean` (not a literal `false`) so consumers who
+     * spread the config and override the field downstream do not
+     * fight literal-type narrowing — the runtime still emits
+     * `false` here, the type system just allows the override.
+     */
+    prefixDefaultLocale: boolean;
+    /**
+     * `false` means a request for `/` is served as the default-locale
+     * landing page (no implicit redirect to `/<defaultLocale>/`). Same
+     * literal-vs-widened rationale as `prefixDefaultLocale` above.
+     */
+    redirectToDefaultLocale: boolean;
+  };
+}
+
+export function buildAstroI18nConfig(siteContext: WebsiteSiteContext): AstroI18nConfig {
+  const { websiteConfig } = siteContext;
+  /**
+   * Defensive copy: `WildoMarketingWebsiteConfig.locales` is an array
+   * of `{ locale, path }` entries; Astro's i18n config wants raw
+   * locale strings in declaration order. We extract `locale` and map
+   * through `String()` so the `AvailableLanguage` brand layer does
+   * not leak into the Astro public API surface, and we freeze the
+   * result so an Astro plugin authored against this shape cannot
+   * mutate the source-of-truth array indirectly.
+   */
+  const locales: readonly string[] = Object.freeze(
+    websiteConfig.locales.map((entry: { locale: AvailableLanguage }) => String(entry.locale)),
+  );
+  return {
+    defaultLocale: String(websiteConfig.defaultLocale),
+    locales,
+    routing: {
+      prefixDefaultLocale: false,
+      redirectToDefaultLocale: false,
+    },
+  };
+}
+/** @wildo_source:part:end saas.website.astro.i18n-helper */

package/src/astro/internal/html-escape.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared HTML-escape helpers used by every Astro head-block string
+ * builder in the saas-website engine (page-head + blog-post-head, and
+ * any future per-route renderer that interpolates consumer-supplied
+ * copy into a string-output `<head>` template).
+ *
+ * # Why a shared module rather than duplicating per-renderer
+ *
+ * Marketing copy frequently contains characters (quotes, ampersands,
+ * the rare `<`) that would break the surrounding tag if interpolated
+ * raw. Two renderers escaping with two slightly-different character
+ * sets is exactly the kind of silent-drift surface this codebase
+ * forbids — one renderer might forget the `'` → `&#39;` substitution
+ * and produce attribute breakouts in JSON-LD copy, while the other
+ * does it correctly. Centralizing both helpers here gives every
+ * renderer ONE escape contract to audit.
+ *
+ * # Why both `Attribute` and `Text` variants exist (currently identical)
+ *
+ * Conceptually distinct (an attribute escape needs `"`/`'` covered;
+ * a text-content escape technically only needs `<`/`>`/`&`). Today
+ * they share a body for convenience — the cost of over-escaping `"`
+ * inside text content is negligible (browsers render the entity
+ * correctly) and the win is one fewer code path to audit. Splitting
+ * the implementations later (when a real divergence shows up — e.g. a
+ * JSON-LD emitter that legitimately wants raw `<script type="application/ld+json">`
+ * inner-content escaping rules) is a one-file change.
+ */
+
+export function escapeHtmlAttribute(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+export function escapeHtmlText(value: string): string {
+  return escapeHtmlAttribute(value);
+}

package/src/astro/label-pack-loader.ts

@@ -0,0 +1,385 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import type { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import type { WebsiteLabelKey } from '../schemas/label-keys/website-label-key.schemas';
+import type { WebsitePageManifest } from '../schemas/manifests/website-page-manifest.shared.schemas';
+import type { WebsiteRootConfig } from '../schemas/manifests/website-root-config.shared.schemas';
+import {
+  validateLabelPackAgainstManifest,
+  type ExpectedLabelKeysBySectionRef,
+  type LabelPack,
+  type LabelPackValidationResult,
+} from '../schemas/validators/label-pack.validator';
+
+import type { WebsiteSiteContext } from './website-site-context';
+
+/**
+ * @wildo_source:part:start saas.website.astro.label-loader facet:layer:astro facet:family:website
+ *
+ * `label-pack-loader.ts` — synchronous, fs-backed loader for
+ * marketing-site label packs. Consumed by:
+ *   - the Astro adapter (`WebsitePageBridge.astro` reads the active
+ *     locale's pack at request time during SSR / pre-render),
+ *   - the `wildo website audit` CLI (Phase 7) to validate every
+ *     locale pack against every manifest at CI time,
+ *   - any build-time hook that wants to fail fast on a missing or
+ *     malformed pack.
+ *
+ * **Convention** (matches the slice plan + the validator's contract):
+ *
+ *   - One file per locale: `<packsDir>/<locale>.json`
+ *   - JSON object: flat key-value map, `Record<string, string>`
+ *   - Keys are fully-composed `WebsiteLabelKey`s (`website.<page>.<section>.<slot>`)
+ *   - Values are the localized strings
+ *
+ * **Why synchronous I/O**:
+ *   - The Astro frontmatter executes at build / SSR time in a Node
+ *     process (no event loop pressure to relieve), and the bridge
+ *     wants the pack resolved before it emits any HTML — async would
+ *     force the consumer to `await` inside an Astro frontmatter,
+ *     which is supported but adds a needless yield-point on a single
+ *     small JSON file.
+ *   - The validator is pure and synchronous; making the loader async
+ *     would add a coloring boundary for no benefit.
+ *
+ * **Failure modes — all surfaced as thrown errors with actionable
+ * messages**:
+ *   - File missing — wrapped in a `[label-pack-loader] Could not read
+ *     pack at <path>` error so a typo in the dir / locale is obvious.
+ *   - JSON parse failure — error includes the file path and the
+ *     parser's own message.
+ *   - Top-level shape is not an object, or a value is not a string —
+ *     error names the offending key + observed type.
+ *
+ * **Why three exports** (loader, multi-loader, validator-runner):
+ *   - `loadLabelPack(packsDir, locale)` is the atomic primitive
+ *     (one file → one validated `LabelPack`). Used by the bridge at
+ *     request time.
+ *   - `loadAllLabelPacks(packsDir, siteContext)` is the build-time
+ *     batch — every locale pack at once. Used by the CLI auditor
+ *     and by the build-start hook.
+ *   - `validateAllLabelPacks(packsDir, siteContext, expectedKeysBySectionRef)`
+ *     is the highest-level entry point: load every pack, run the
+ *     validator on each, and either return the diagnostic results
+ *     or throw on the first hard error. The returned shape carries
+ *     per-locale diagnostics so the caller can format a CLI report.
+ *
+ * **`siteContext` parameter** — the consumer's composed
+ * `WebsiteSiteContext` (see `website-site-context.ts`). The loader
+ * reads `siteContext.websiteConfig.locales` for "which locales does
+ * the site ship?" and `siteContext.rootConfig.{pageManifests,
+ * chromeLabelKeys, skipToMainContentLabelKey}` for the manifest
+ * registry / chrome-key set the validator runs against.
+ */
+
+/**
+ * Load and validate a single locale's label pack. Synchronous —
+ * suitable for Astro frontmatter execution.
+ *
+ * @param packsDir Absolute or cwd-relative path to the directory
+ *                 containing per-locale `<locale>.json` files.
+ * @param locale   The locale to load. Must be a member of
+ *                 `WildoMarketingWebsiteConfig.locales`.
+ * @returns A flat `LabelPack` (`Record<string, string>`) ready to
+ *          feed into `WebsiteRuntimeContextValue.labelPack`.
+ * @throws  When the file is missing, malformed JSON, not an object,
+ *          or contains a non-string value.
+ */
+export function loadLabelPack(packsDir: string, locale: AvailableLanguage): LabelPack {
+  const filePath = resolve(packsDir, `${locale}.json`);
+
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, 'utf-8');
+  } catch (cause) {
+    throw new Error(
+      `[label-pack-loader] Could not read label pack at ${filePath} ` +
+        `(locale="${locale}"). ` +
+        `Make sure the directory exists and contains a "${locale}.json" file. ` +
+        `Underlying error: ${(cause as Error).message}`,
+      { cause },
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new Error(
+      `[label-pack-loader] Failed to parse JSON in ${filePath} ` +
+        `(locale="${locale}"). Underlying parser error: ${(cause as Error).message}`,
+      { cause },
+    );
+  }
+
+  return assertLabelPackShape(parsed, filePath, locale);
+}
+
+/**
+ * Batch loader — every locale declared on the site at once. The map
+ * iteration order matches the declaration order of
+ * `siteContext.websiteConfig.locales` so CLI reports come out in a
+ * deterministic, authored sequence.
+ */
+export function loadAllLabelPacks(
+  packsDir: string,
+  siteContext: WebsiteSiteContext,
+): Map<AvailableLanguage, LabelPack> {
+  const packs = new Map<AvailableLanguage, LabelPack>();
+  for (const entry of siteContext.websiteConfig.locales) {
+    packs.set(entry.locale, loadLabelPack(packsDir, entry.locale));
+  }
+  return packs;
+}
+
+/**
+ * Per-locale validation result — the validator's flat output extended
+ * with the locale tag so a multi-locale report can flatten + group.
+ */
+export interface LocaleLabelPackValidation {
+  locale: AvailableLanguage;
+  result: LabelPackValidationResult;
+}
+
+/**
+ * Highest-level entry point: load every locale's pack and run the
+ * label-pack validator against the manifest registry.
+ *
+ * **Return shape decision** — this function does NOT throw on
+ * `missing` keys; it returns the per-locale results so the caller
+ * (the build-start hook OR the CLI auditor OR a debugging
+ * subprocess) can decide how to surface the failure (process exit
+ * code, formatted CLI output, JSON report, …). A thin `throwIfAny…`
+ * helper sits next to it for the common "fail the build on first
+ * missing key" path.
+ */
+export function loadAndValidateAllLabelPacks(
+  packsDir: string,
+  siteContext: WebsiteSiteContext,
+  expectedKeysBySectionRef: ExpectedLabelKeysBySectionRef,
+): readonly LocaleLabelPackValidation[] {
+  const { rootConfig } = siteContext;
+  const packs = loadAllLabelPacks(packsDir, siteContext);
+  const manifests: readonly WebsitePageManifest[] = rootConfig.pageManifests;
+  const effectiveChromeKeys = composeEffectiveChromeLabelKeys(rootConfig);
+
+  const validations: LocaleLabelPackValidation[] = [];
+  for (const [locale, pack] of packs) {
+    validations.push({
+      locale,
+      result: validateLabelPackAgainstManifest(
+        manifests,
+        expectedKeysBySectionRef,
+        pack,
+        effectiveChromeKeys,
+      ),
+    });
+  }
+  return validations;
+}
+
+/**
+ * Compose the chrome-label-key set the validator should treat as
+ * "expected" — `WebsiteRootConfig.chromeLabelKeys` (consumer-authored)
+ * UNION the framework-required `skipToMainContentLabelKey`.
+ *
+ * Centralized here because:
+ *   - Both `loadAndValidateAllLabelPacks` (used at build time) and
+ *     `buildKeyOriginMap` (used to annotate missing-key errors) need
+ *     the same composed list, and forking the union into two places
+ *     would be a drift hazard.
+ *   - The framework owns the skip-link key (it is rendered by
+ *     `WebsitePageLayout`, not the consumer's chrome), so the
+ *     consumer should NOT have to remember to also list it in
+ *     `chromeLabelKeys`. Auto-injection here keeps the contract
+ *     minimal at the consumer's call site (just declare the key in
+ *     `WebsiteRootConfig.skipToMainContentLabelKey` once + ship the
+ *     translation in every locale pack) while still surfacing the key
+ *     through the validator's "missing"/"orphaned" diagnostics.
+ *   - De-duplication is via `Set` semantics so a consumer who
+ *     defensively lists the key in both places (no-op but harmless)
+ *     does not produce a duplicate-key warning downstream.
+ */
+function composeEffectiveChromeLabelKeys(
+  rootConfig: WebsiteRootConfig,
+): readonly WebsiteLabelKey[] {
+  const set = new Set<WebsiteLabelKey>(rootConfig.chromeLabelKeys);
+  set.add(rootConfig.skipToMainContentLabelKey);
+  return Array.from(set);
+}
+
+/**
+ * Convenience wrapper for the build-start hook: validates every
+ * declared locale's pack and throws a SINGLE aggregated error if any
+ * locale has a hard failure (`missing` keys or `unmappedSectionRefs`).
+ * Orphaned keys are logged via `console.warn` (soft warning per the
+ * validator's contract) but do NOT throw.
+ *
+ * **Why aggregate (not first-fail)**: a multi-locale marketing site
+ * with `en` and `fr` packs both missing keys would, under a
+ * first-fail policy, force the author to fix `en`, re-run the build,
+ * THEN see `fr`'s problem. Aggregating means one build run surfaces
+ * every locale's hard errors together — material UX win for the
+ * authoring loop. The aggregated message keeps each locale's failure
+ * in its own block so the diagnostic stays scannable.
+ *
+ * **Why throw vs. return**: the build-start hook lives in
+ * `astro.config.mjs` (or a `vite-plugin`-style integration) and
+ * benefits from the shortest possible code path — a thrown error
+ * naturally aborts `astro build` with a non-zero exit code and
+ * surfaces the message in the build log. The richer
+ * `loadAndValidateAllLabelPacks` is what `wildo website audit` calls
+ * when it wants programmatic access to the per-locale results.
+ *
+ * **Key-origin annotation**: every `missing` key is tagged with the
+ * page (and, if section-scoped, the section) that declared it, so the
+ * author can grep + open the right `defineWebsiteSection` /
+ * `defineWebsitePageManifest` call site without leaving the build log.
+ */
+export function assertLabelPacksValid(
+  packsDir: string,
+  siteContext: WebsiteSiteContext,
+  expectedKeysBySectionRef: ExpectedLabelKeysBySectionRef,
+): void {
+  const { rootConfig } = siteContext;
+  const validations = loadAndValidateAllLabelPacks(
+    packsDir,
+    siteContext,
+    expectedKeysBySectionRef,
+  );
+
+  /**
+   * Build a key → origin map ONCE per assert call (cost is bounded by
+   * the total number of declared keys across the whole site, which is
+   * typically small for a marketing surface). Enriches the missing-key
+   * error with the page/section that committed to each key — the
+   * author can grep the ref to find the site authoring call site.
+   */
+  const keyOrigins = buildKeyOriginMap(
+    rootConfig.pageManifests,
+    expectedKeysBySectionRef,
+    composeEffectiveChromeLabelKeys(rootConfig),
+  );
+
+  const localeErrorBlocks: string[] = [];
+
+  for (const { locale, result } of validations) {
+    const blocks: string[] = [];
+    if (result.unmappedSectionRefs.length > 0) {
+      blocks.push(
+        `  unmappedSectionRefs (build-pipeline bug — sections referenced by a ` +
+          `manifest but missing from the expected-keys collector): ` +
+          `[${(result.unmappedSectionRefs as unknown as readonly string[]).join(', ')}]. ` +
+          `Add every referenced section to the array passed to ` +
+          `collectExpectedLabelKeysFromSections().`,
+      );
+    }
+    if (result.missing.length > 0) {
+      const annotated = (result.missing as unknown as readonly string[]).map(
+        (key) => `    "${key}"  ← ${keyOrigins.get(key) ?? 'unknown origin'}`,
+      );
+      blocks.push(
+        `  missing ${result.missing.length} required key(s) in ${packsDir}/${locale}.json:\n` +
+          annotated.join('\n'),
+      );
+    }
+    if (blocks.length > 0) {
+      localeErrorBlocks.push(`Locale "${locale}":\n${blocks.join('\n')}`);
+    }
+    if (result.orphaned.length > 0) {
+      console.warn(
+        `[label-pack-loader] Locale "${locale}": ${result.orphaned.length} ` +
+          `orphaned key(s) in ${locale}.json (declared in pack but not consumed ` +
+          `by any section or page manifest):\n  ${result.orphaned.join('\n  ')}`,
+      );
+    }
+  }
+
+  if (localeErrorBlocks.length > 0) {
+    throw new Error(
+      `[label-pack-loader] Label pack validation failed for ` +
+        `${localeErrorBlocks.length} locale(s):\n\n${localeErrorBlocks.join('\n\n')}`,
+    );
+  }
+}
+
+/**
+ * Build a `keyString -> "page <pageRef> meta titleKey" | "section <sectionRef> in page <pageRef>"`
+ * lookup so the assert message can name the call site that committed
+ * to each missing key. Pure and small (cost is O(totalKeys) per build
+ * — bounded by the marketing surface).
+ */
+function buildKeyOriginMap(
+  manifests: readonly WebsitePageManifest[],
+  expectedKeysBySectionRef: ExpectedLabelKeysBySectionRef,
+  chromeLabelKeys: readonly WebsiteLabelKey[],
+): Map<string, string> {
+  const origins = new Map<string, string>();
+  for (const manifest of manifests) {
+    const pageRefStr = manifest.ref as unknown as string;
+    const titleKey = manifest.metaLabelKeys.titleKey as unknown as string;
+    const descriptionKey = manifest.metaLabelKeys.descriptionKey as unknown as string;
+    if (!origins.has(titleKey)) {
+      origins.set(titleKey, `page "${pageRefStr}" metaLabelKeys.titleKey`);
+    }
+    if (!origins.has(descriptionKey)) {
+      origins.set(descriptionKey, `page "${pageRefStr}" metaLabelKeys.descriptionKey`);
+    }
+    for (const sectionRef of manifest.sectionRefs) {
+      const sectionRefStr = sectionRef as unknown as string;
+      const sectionKeys = expectedKeysBySectionRef.get(sectionRef);
+      if (sectionKeys === undefined) continue;
+      for (const sectionKey of sectionKeys) {
+        const keyStr = sectionKey as unknown as string;
+        if (!origins.has(keyStr)) {
+          origins.set(keyStr, `section "${sectionRefStr}" in page "${pageRefStr}"`);
+        }
+      }
+    }
+  }
+  for (const chromeKey of chromeLabelKeys) {
+    const keyStr = chromeKey as unknown as string;
+    if (!origins.has(keyStr)) {
+      origins.set(keyStr, `WebsiteRootConfig.chromeLabelKeys`);
+    }
+  }
+  return origins;
+}
+
+/**
+ * Defensive shape guard. Surface the offending key + observed type
+ * so the consumer can find the malformed entry quickly. Pure
+ * validation — no transformation; the returned value is the same
+ * object reference passed in (cast to `LabelPack`) so the caller
+ * does not pay an unnecessary copy.
+ */
+function assertLabelPackShape(
+  parsed: unknown,
+  filePath: string,
+  locale: AvailableLanguage,
+): LabelPack {
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(
+      `[label-pack-loader] ${filePath} (locale="${locale}") must contain a ` +
+        `JSON object at the top level (got ${describeJson(parsed)}).`,
+    );
+  }
+  for (const [key, value] of Object.entries(parsed)) {
+    if (typeof value !== 'string') {
+      throw new Error(
+        `[label-pack-loader] ${filePath} (locale="${locale}"): key "${key}" ` +
+          `must map to a string (got ${describeJson(value)}).`,
+      );
+    }
+  }
+  return parsed as LabelPack;
+}
+
+function describeJson(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+/** @wildo_source:part:end saas.website.astro.label-loader */

package/src/astro/llms-txt-server.ts

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import type { WebsiteSiteContext } from './website-site-context';
+
+export interface ReadLlmsTxtBodyOptions {
+  /**
+   * Directory containing the hand-authored `llms.txt` file. Defaults
+   * to the conventional `./src/content` path from the website package
+   * root.
+   */
+  contentDir?: string;
+  /**
+   * File name under `contentDir`. Exposed for tests; consumers should
+   * stick to the canonical `llms.txt`.
+   */
+  fileName?: string;
+}
+
+/**
+ * @wildo_source:part:start saas.website.astro.llms-txt-server facet:layer:astro facet:family:website
+ *
+ * Read the hand-authored `llms.txt` body for the marketing site.
+ *
+ * Publication policy:
+ * - `seo.llmsTxt?.enabled === false` → return `null`
+ * - `seo.llmsTxt?.enabled === true`  → read the file if present, else `null`
+ * - `seo.llmsTxt === undefined` or `enabled === undefined` → auto-detect:
+ *   publish when the file exists, otherwise return `null`
+ */
+export function readLlmsTxtBody(
+  siteContext: WebsiteSiteContext,
+  options: ReadLlmsTxtBodyOptions = {},
+): string | null {
+  const contentDir = options.contentDir ?? './src/content';
+  const fileName = options.fileName ?? 'llms.txt';
+  const filePath = resolve(contentDir, fileName);
+
+  if (siteContext.rootConfig.seo.llmsTxt?.enabled === false) {
+    return null;
+  }
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    return readFileSync(filePath, 'utf-8');
+  } catch (cause) {
+    throw new Error(
+      `[llms-txt-server] Could not read llms.txt at ${filePath}. ` +
+        `Underlying error: ${(cause as Error).message}`,
+      { cause },
+    );
+  }
+}
+/** @wildo_source:part:end saas.website.astro.llms-txt-server */