@wildo-ai/saas-website 1.1.1

package/src/schemas/manifests/website-root-config.shared.schemas.ts

@@ -0,0 +1,504 @@
+import type { ComponentType } from 'react';
+import { z } from 'zod';
+
+import { WebsiteDesignTokensSchema } from '../design-tokens/website-design-tokens.shared.schemas';
+import { WebsiteLabelKeySchema } from '../label-keys/website-label-key.schemas';
+import {
+  WebsitePageManifestSchema,
+  type WebsitePageManifest,
+} from './website-page-manifest.shared.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.seo.sitemap-config facet:layer:shared facet:family:website
+ *
+ * `WebsiteSitemapConfig` — site-wide sitemap policy block.
+ *
+ * Materialized at build time by `@astrojs/sitemap` (the official
+ * Astro plugin) when the consumer wires it into `astro.config.ts`
+ * (see `website-seo-aeo-geo` SKILL). The framework owns the
+ * **schema** (so config + enforcement live in lock-step with the
+ * page registry) but the framework does NOT own the runtime
+ * generator — `@astrojs/sitemap` already covers per-page
+ * `lastmod` / `changefreq` / `priority` + i18n `xhtml:link
+ * hreflang` annotations natively, and re-implementing that surface
+ * inside the engine would duplicate well-trodden Astro tooling for
+ * zero added value.
+ *
+ * # Field rationale
+ *
+ * **Why `enabled` defaults to `true`**:
+ *   - Marketing sites that want to ship public pages overwhelmingly
+ *     also want them in `sitemap.xml` (search engines treat its
+ *     absence as a discoverability signal). The opt-OUT shape avoids
+ *     a silent regression where a consumer ships pages that crawlers
+ *     never index because they forgot to flip a flag.
+ *   - The escape hatch (`enabled: false`) covers staging deployments
+ *     and the rare per-app decision to suppress sitemap emission
+ *     entirely (e.g. a private beta surface routed under a
+ *     `noindex` policy).
+ *
+ * **Why `changefreq` / `priority` are OPTIONAL** (no defaults):
+ *   - Both fields are non-binding hints — Google explicitly
+ *     ignores `priority` and treats `changefreq` as a soft signal.
+ *     Forcing the consumer to pick a value would either invite
+ *     superstitious authoring (`priority: 1.0` on every page) or
+ *     bury the field's actual ergonomic shape (per-page overrides
+ *     via `WebsitePageManifest.seo` — deferred until a real
+ *     consumer requests it).
+ *   - Unset values are simply omitted from the emitted `<url>`
+ *     entries; `@astrojs/sitemap` handles that automatically.
+ *
+ * **Validation**:
+ *   - `priority` is `z.number().min(0).max(1)` — outside the spec
+ *     range would silently break crawler ingestion.
+ *   - `changefreq` is the union of the seven values the sitemap
+ *     spec defines; arbitrary strings would be silently dropped by
+ *     compliant crawlers.
+ */
+const _WebsiteSitemapConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  changefreq: z
+    .enum(['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never'])
+    .optional(),
+  priority: z
+    .number()
+    .min(0, { error: 'WebsiteSitemapConfig.priority must be between 0 and 1' })
+    .max(1, { error: 'WebsiteSitemapConfig.priority must be between 0 and 1' })
+    .optional(),
+});
+
+export const WebsiteSitemapConfigSchema: typeof _WebsiteSitemapConfigSchema =
+  _WebsiteSitemapConfigSchema;
+
+export type WebsiteSitemapConfig = z.infer<typeof _WebsiteSitemapConfigSchema>;
+/** @wildo_source:part:end saas.website.seo.sitemap-config */
+
+/**
+ * @wildo_source:part:start saas.website.seo.robots-config facet:layer:shared facet:family:website
+ *
+ * `WebsiteRobotsConfig` — site-wide `robots.txt` policy block.
+ *
+ * Materialized at request time by `renderRobotsTxt(siteContext)`
+ * from `@wildo-ai/saas-website/astro` (consumer wires a thin
+ * `src/pages/robots.txt.ts` Astro endpoint that returns the helper's
+ * output). Scoped to the SITE-WIDE policy surface — per-page
+ * `noindex` is a separate concern that lands on
+ * `WebsitePageManifest.seo` once a real consumer requests it (today
+ * the site-wide `disallow[]` covers staging-environment exclusion of
+ * specific path prefixes, the dominant real-world use case).
+ *
+ * # Field rationale
+ *
+ * **Why `policy` defaults to `'index'`**:
+ *   - The default for a public marketing site is "let crawlers in";
+ *     `'noindex'` is the deliberate exception (staging environments,
+ *     beta surfaces, sites still under construction). The opt-OUT
+ *     shape mirrors `WebsiteSitemapConfig.enabled` for consistency.
+ *   - `'noindex'` emits a `User-agent: *\nDisallow: /` block — the
+ *     standard "tell every well-behaved crawler to stay away"
+ *     primitive.
+ *
+ * **Why `disallow[]` is a path-prefix list (not a regex)**:
+ *   - The `robots.txt` spec only supports literal path prefixes
+ *     with `*` / `$` wildcards; Disallow is NOT a regex surface.
+ *     Typing it as `string[]` (validated to start with `/`) keeps
+ *     the contract honest and lets consumers paste from their CDN
+ *     allowlists without translation.
+ *
+ * **Why `allowedCrawlers` and `disallowedCrawlers` are mutually
+ * exclusive**:
+ *   - The two fields are two halves of the SAME AI-crawler policy
+ *     decision. `allowedCrawlers` is the deny-by-default shape
+ *     (only the named bots may crawl); `disallowedCrawlers` is the
+ *     allow-by-default shape (every bot except the named ones may
+ *     crawl). Mixing both would emit a contradictory `robots.txt`
+ *     (a bot in both lists would receive conflicting directives).
+ *     A `superRefine` enforces the mutual-exclusion invariant at
+ *     parse time so the build fails fast.
+ *
+ * **Validation**:
+ *   - `disallow[]` entries must start with `/` (sitemap path-prefix
+ *     spec) — anything else would silently match nothing.
+ *   - `allowedCrawlers` / `disallowedCrawlers` entries must be
+ *     non-empty strings (a blank User-agent token would emit
+ *     `User-agent: ` which compliant crawlers ignore — silent
+ *     misconfig).
+ *   - `superRefine` rejects the combined-list anti-pattern.
+ */
+const _WebsiteRobotsConfigSchema = z
+  .object({
+    policy: z.enum(['index', 'noindex']).default('index'),
+    disallow: z
+      .array(
+        z
+          .string()
+          .min(1)
+          .refine((path) => path.startsWith('/'), {
+            error: 'WebsiteRobotsConfig.disallow[] entries must start with "/"',
+          }),
+      )
+      .optional(),
+    /**
+     * Deny-by-default AI-crawler allowlist. When set, the emitted
+     * `robots.txt` lists each named bot under its own
+     * `User-agent: <bot>\nAllow: /` block, then closes with a
+     * catch-all `User-agent: *\nDisallow: /`. Mutually exclusive
+     * with `disallowedCrawlers` (see `superRefine` below).
+     */
+    allowedCrawlers: z.array(z.string().min(1)).optional(),
+    /**
+     * Allow-by-default AI-crawler denylist. When set, the emitted
+     * `robots.txt` lists each named bot under its own
+     * `User-agent: <bot>\nDisallow: /` block. Mutually exclusive
+     * with `allowedCrawlers` (see `superRefine` below).
+     */
+    disallowedCrawlers: z.array(z.string().min(1)).optional(),
+  })
+  .superRefine((value, ctx) => {
+    if (value.allowedCrawlers !== undefined && value.disallowedCrawlers !== undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['allowedCrawlers'],
+        message:
+          'WebsiteRobotsConfig.allowedCrawlers and disallowedCrawlers are mutually exclusive — pick one policy direction (deny-by-default vs allow-by-default).',
+      });
+    }
+  });
+
+export const WebsiteRobotsConfigSchema: typeof _WebsiteRobotsConfigSchema =
+  _WebsiteRobotsConfigSchema;
+
+export type WebsiteRobotsConfig = z.infer<typeof _WebsiteRobotsConfigSchema>;
+/** @wildo_source:part:end saas.website.seo.robots-config */
+
+/**
+ * @wildo_source:part:start saas.website.seo.llms-txt-config facet:layer:shared facet:family:website
+ *
+ * `WebsiteLlmsTxtConfig` — site-wide `llms.txt` publication policy.
+ *
+ * The framework owns only the SERVING surface; the CONTENT remains
+ * hand-authored in `src/content/llms.txt`. This block therefore needs
+ * exactly one knob:
+ *
+ * - `enabled?: boolean`
+ *   - `true`  → publish when the file exists
+ *   - `false` → suppress publication even if the file exists
+ *   - `undefined` → auto-detect (`readLlmsTxtBody` publishes when the
+ *     file exists, returns `null` when absent)
+ *
+ * Keeping the "auto-detect when undefined" convention in the HELPER
+ * (not as a schema default) is deliberate: schema defaults are static,
+ * while file presence is runtime/build-time state.
+ */
+const _WebsiteLlmsTxtConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+});
+
+export const WebsiteLlmsTxtConfigSchema: typeof _WebsiteLlmsTxtConfigSchema =
+  _WebsiteLlmsTxtConfigSchema;
+
+export type WebsiteLlmsTxtConfig = z.infer<typeof _WebsiteLlmsTxtConfigSchema>;
+/** @wildo_source:part:end saas.website.seo.llms-txt-config */
+
+/**
+ * @wildo_source:part:start saas.website.root-config.seo facet:layer:shared facet:family:website
+ *
+ * `WebsiteSeoConfig` — site-wide SEO/social-graph configuration
+ * AUTHORED ON THE ROOT CONFIG.
+ *
+ * # Scope
+ *
+ * The public marketing-site origin belongs only in the per-service
+ * `wildo.website.config.ts` declaration. Keep it out of this site-level SEO
+ * block so the origin and localized routing have one source of truth.
+ *
+ * What stays on this block: site-level branding + hero-image
+ * fallbacks that are co-authored with chrome labels and page
+ * manifests respectively, NOT with the URL/i18n routing surface.
+ *
+ * # Field rationale
+ *
+ * **Why `siteName` is REQUIRED**:
+ *   - `og:site_name` is the brand label social platforms render
+ *     above the page title in shared previews. Without it, every
+ *     LinkedIn / Facebook / Slack preview shows the bare title with
+ *     no brand context.
+ *   - It is also the recommended `application-name` meta tag value
+ *     and a useful default for JSON-LD `Organization.name` schema
+ *     when the application ships structured data.
+ *
+ * **Why `defaultOgImageUrl` is OPTIONAL**:
+ *   - Each page's `WebsitePageManifest.metaLabelKeys.ogImageUrl`
+ *     takes precedence; the site-level default is a fallback for
+ *     pages that did not commit to a hero image.
+ *   - Marketing surfaces shipping no OG images at all (acceptable
+ *     for a placeholder build) should not be forced to author one.
+ *
+ * **Why `sitemap?` and `robots?` are OPTIONAL** (with sensible
+ * defaults inside each sub-schema):
+ *   - The marketing-site default ships a public surface — every
+ *     page indexable, no AI-crawler restrictions, no per-path
+ *     disallow. Forcing every consumer to author both blocks just
+ *     to land in that default state would pollute the call site.
+ *   - Omitting either block at the call site is equivalent to
+ *     authoring `{}` — `WebsiteSitemapConfig.enabled` defaults to
+ *     `true`, `WebsiteRobotsConfig.policy` defaults to `'index'`.
+ *     The per-block field rationale lives on each sub-schema.
+ *   - `llmsTxt?` is similarly optional, but with a different default
+ *     mechanic: omitting the block means "auto-detect from file
+ *     presence" rather than "use a static schema default". The helper
+ *     `readLlmsTxtBody(...)` publishes when `src/content/llms.txt`
+ *     exists and returns `null` otherwise.
+ *
+ * **Validation**:
+ *   - `siteName` is `z.string().min(1)` — empty strings would emit
+ *     `<meta property="og:site_name" content="" />` which social
+ *     platforms render as a blank line.
+ *   - `defaultOgImageUrl` (when present) is `z.url()`.
+ *   - `sitemap` / `robots` validation lives on the sub-schemas.
+ */
+const _WebsiteSeoConfigSchema = z
+  .object({
+    siteName: z
+      .string()
+      .min(1, { error: 'WebsiteSeoConfig.siteName must be a non-empty string' }),
+    defaultOgImageUrl: z
+      .url({ error: 'WebsiteSeoConfig.defaultOgImageUrl must be a fully-qualified URL' })
+      .optional(),
+    /**
+     * Sitemap policy block. Optional — omitting it is equivalent to
+     * `{ enabled: true }` (the marketing-site default). See
+     * `WebsiteSitemapConfigSchema` for field-by-field rationale.
+     */
+    sitemap: _WebsiteSitemapConfigSchema.optional(),
+    /**
+     * Robots.txt policy block. Optional — omitting it is equivalent
+     * to `{ policy: 'index' }` (the marketing-site default). See
+     * `WebsiteRobotsConfigSchema` for field-by-field rationale.
+     */
+    robots: _WebsiteRobotsConfigSchema.optional(),
+    /**
+     * `llms.txt` publication policy. Optional — omitting it means
+     * "auto-detect from file presence". See
+     * `WebsiteLlmsTxtConfigSchema` for the serving contract.
+     */
+    llmsTxt: _WebsiteLlmsTxtConfigSchema.optional(),
+  });
+
+export const WebsiteSeoConfigSchema: typeof _WebsiteSeoConfigSchema = _WebsiteSeoConfigSchema;
+
+export type WebsiteSeoConfig = z.infer<typeof _WebsiteSeoConfigSchema>;
+/** @wildo_source:part:end saas.website.root-config.seo */
+
+/**
+ * @wildo_source:part:start saas.website.root-config.navigation facet:layer:shared facet:family:website
+ *
+ * `WebsiteNavigationConfig` — site-wide header/footer slot bindings.
+ *
+ * The framework intentionally ships no concrete header or footer. The
+ * application authors both as React components, registers them once here, and
+ * the page layout renders the site-wide chrome around every page.
+ *
+ * Both fields are typed as `unknown` at the schema layer with the
+ * `WebsiteNavigationConfig` interface narrowing them to
+ * `ComponentType<unknown>` — same rationale as
+ * `WebsiteSectionDefinition.Component` and `WebsitePageManifest.pageComponent`.
+ */
+const _WebsiteNavigationConfigSchema = z.object({
+  headerComponent: z.unknown(),
+  footerComponent: z.unknown(),
+});
+
+export const WebsiteNavigationConfigSchema: typeof _WebsiteNavigationConfigSchema =
+  _WebsiteNavigationConfigSchema;
+
+export interface WebsiteNavigationConfig
+  extends z.infer<typeof _WebsiteNavigationConfigSchema> {
+  headerComponent: ComponentType<unknown>;
+  footerComponent: ComponentType<unknown>;
+}
+/** @wildo_source:part:end saas.website.root-config.navigation */
+
+/**
+ * @wildo_source:part:start saas.website.root-config.schema facet:layer:shared facet:family:website
+ *
+ * `WebsiteRootConfig` — the site-level configuration consumed by:
+ *   - the Astro adapter to drive i18n routing, page mounting,
+ *     and design-token CSS emission,
+ *   - the website audit command to validate label-pack
+ *     coverage and SEO structured-data conformance,
+ *   - the runtime `<WebsitePageLayout>` to render navigation
+ *     and apply design tokens.
+ *
+ * **Authoring convention**: each marketing-site service exports a single
+ * `WEBSITE_ROOT_CONFIG: WebsiteRootConfig` from `src/website-root.config.ts`.
+ * The Astro adapter and the audit command
+ * both consume this canonical entry point; there is exactly one site
+ * config per marketing site (no per-page or per-section overrides at
+ * this level — overrides flow through the L0/L1/L1.5 component
+ * registration hierarchy described in D6).
+ *
+ * # Scope
+ *
+ * This block carries site-level chrome and registry data only. Per-locale
+ * routing (`locales` / `defaultLocale`) and the public origin belong in the
+ * per-service `wildo.website.config.ts` declaration, avoiding duplicated
+ * configuration that could diverge during site generation.
+ *
+ * **Field-by-field rationale**:
+ *
+ * - `pageManifests` — the registry of every page on the site. Indexed
+ *   downstream by `manifest.ref`. Refs MUST be unique (refinement
+ *   below).
+ * - `designTokens` — see `WebsiteDesignTokensSchema`.
+ * - `navigation` — see `WebsiteNavigationConfigSchema`.
+ * - `chromeLabelKeys` — OPTIONAL. The set of fully-composed label keys
+ *   the site-wide chrome (header / footer / any global slot the
+ *   consumer renders outside a section context) reads via
+ *   `useWebsiteLabelByKey(...)`. Declared here, NOT in section
+ *   `expectedLabelKeys`, because chrome is rendered outside the
+ *   page+section context — `useWebsiteLabel(slot)` is structurally
+ *   unavailable to it. Threading these through the label-pack
+ *   validator (a) silences the always-on "orphaned chrome key" build
+ *   warnings and (b) lets the build fail fast when a chrome key is
+ *   missing from a locale pack, the same way section keys do.
+ *   Defaults to an empty array; sites with no chrome label reads
+ *   may omit the field entirely.
+ * - `seo` — site-level branding + hero-image fallback (see
+ *   `WebsiteSeoConfigSchema`). The marketing-site origin USED to live
+ *   here as `seo.siteOrigin`; it now lives only on
+ *   `WildoMarketingWebsiteConfig.publicOrigin`.
+ * - `skipToMainContentLabelKey` — see field JSDoc below.
+ *
+ * **Refinements**:
+ *   - `pageManifests[].ref` uniqueness — the registry is keyed by ref;
+ *     duplicates would silently overwrite each other in the lookup
+ *     table the bridge uses for cross-page links.
+ *   - `pageManifests[].routePath` uniqueness — two pages cannot mount
+ *     at the same path (Astro would error at build time, but we
+ *     surface it earlier here with a clearer diagnostic).
+ *   - `chromeLabelKeys` uniqueness — duplicates indicate copy-paste
+ *     bugs at the consumer's call site; surface them here.
+ */
+const _WebsiteRootConfigSchema = z
+  .object({
+    pageManifests: z.array(WebsitePageManifestSchema).min(1, {
+      error: 'WebsiteRootConfig must declare at least one page manifest',
+    }),
+    designTokens: WebsiteDesignTokensSchema,
+    navigation: _WebsiteNavigationConfigSchema,
+    chromeLabelKeys: z.array(WebsiteLabelKeySchema).default([]),
+    /**
+     * Site-level branding + hero-image fallback used by the Astro
+     * head renderer to compose `<meta property="og:site_name">` and
+     * the per-page OG image fallback. The marketing-site origin
+     * (`siteOrigin`) USED to live here; it was moved to
+     * `WildoMarketingWebsiteConfig.publicOrigin` in the seam-collapse
+     * (single source of truth for "what's the origin this site is
+     * reachable at").
+     */
+    seo: _WebsiteSeoConfigSchema,
+    /**
+     * Label key the framework reads to render the "Skip to main
+     * content" link as the first focusable element on every page
+     * Required because:
+     *   - Skip-to-main is a baseline keyboard-accessibility
+     *     affordance — WCAG 2.1 §2.4.1 "Bypass Blocks" (Level A)
+     *     mandates it. A marketing-site framework that omits it
+     *     fails AA for the entire surface; making the contract
+     *     opt-in invites that regression on every new consumer.
+     *   - The text is announced verbatim by assistive tech, so it
+     *     MUST be localized — a hardcoded English fallback would
+     *     speak "Skip to main content" to French users. Forcing the
+     *     key through the label-pack validation surface means the
+     *     dev server fails fast when the consumer forgets to add
+     *     the entry to a locale pack.
+     *   - The framework (NOT the consumer's chrome) owns rendering
+     *     the skip link because the chrome is itself the obstacle
+     *     the link bypasses — a chrome-side implementation would
+     *     either be inside the chrome (impossible to focus before
+     *     the chrome) or above it (creating a structural surface
+     *     the framework needs anyway).
+     *
+     * The key MUST also be present in `chromeLabelKeys` (the
+     * label-pack validator silences "orphaned" warnings off
+     * `chromeLabelKeys`) — the framework adds it automatically via
+     * the `superRefine` pass below so consumers cannot forget.
+     */
+    skipToMainContentLabelKey: WebsiteLabelKeySchema,
+  })
+  .superRefine((config, ctx) => {
+    const seenRefs = new Set<string>();
+    const seenRoutePaths = new Set<string>();
+    for (const [index, manifest] of config.pageManifests.entries()) {
+      const refKey = manifest.ref as unknown as string;
+      if (seenRefs.has(refKey)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['pageManifests', index, 'ref'],
+          message: `Duplicate page ref "${refKey}" in WebsiteRootConfig.pageManifests`,
+        });
+      }
+      seenRefs.add(refKey);
+
+      const routeKey = manifest.routePath as unknown as string;
+      if (seenRoutePaths.has(routeKey)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['pageManifests', index, 'routePath'],
+          message: `Duplicate routePath "${routeKey}" in WebsiteRootConfig.pageManifests`,
+        });
+      }
+      seenRoutePaths.add(routeKey);
+    }
+
+    /**
+     * `chromeLabelKeys` uniqueness — a duplicate is harmless at
+     * runtime (the validator de-dupes via a Set) but always indicates
+     * a copy-paste bug at the consumer's call site. Surfacing it here
+     * keeps the chrome contract tidy and matches the discipline applied
+     * to `pageManifests[].ref` and `locales`.
+     */
+    const seenChromeKeys = new Set<string>();
+    for (const [index, key] of config.chromeLabelKeys.entries()) {
+      const keyStr = key as unknown as string;
+      if (seenChromeKeys.has(keyStr)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['chromeLabelKeys', index],
+          message: `Duplicate chrome label key "${keyStr}" in WebsiteRootConfig.chromeLabelKeys`,
+        });
+      }
+      seenChromeKeys.add(keyStr);
+    }
+  });
+
+export const WebsiteRootConfigSchema: typeof _WebsiteRootConfigSchema = _WebsiteRootConfigSchema;
+
+/**
+ * Runtime shape of `WebsiteRootConfig`.
+ *
+ * Hand-written (NOT a bare `z.infer<typeof _WebsiteRootConfigSchema>`)
+ * because `z.infer` walks the schema tree and would type
+ * `pageManifests[number].pageComponent`, `navigation.headerComponent`
+ * and `navigation.footerComponent` as `unknown` (their schema field
+ * type), losing the `ComponentType<unknown>` narrowing carried by the
+ * hand-written `WebsitePageManifest` and `WebsiteNavigationConfig`
+ * interfaces. Factories such as `defineWebsiteRootConfig` and the
+ * layout primitives consume `WebsiteRootConfig` and must see those
+ * fields pre-narrowed; otherwise every consumer would need a local
+ * `as ComponentType` cast at the JSX call site, defeating the type-safe
+ * component contract.
+ *
+ * The `Omit` + intersection pattern keeps the rest of the inferred
+ * shape (`designTokens`, `seo`, `chromeLabelKeys`,
+ * `skipToMainContentLabelKey`) sourced directly from the schema.
+ */
+export type WebsiteRootConfig = Omit<
+  z.infer<typeof _WebsiteRootConfigSchema>,
+  'pageManifests' | 'navigation'
+> & {
+  pageManifests: WebsitePageManifest[];
+  navigation: WebsiteNavigationConfig;
+};
+/** @wildo_source:part:end saas.website.root-config.schema */

package/src/schemas/refs/page-ref.schemas.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+
+/**
+ * @wildo_source:part:start saas.website.refs.page facet:layer:shared facet:family:website
+ *
+ * `WebsitePageRef` — branded kebab-case identifier for a single marketing-site
+ * page (e.g. `'landing'`, `'pricing'`, `'contact-us'`).
+ *
+ * The ref is the **structural identity** of a page across three independent
+ * surfaces:
+ *
+ * 1. **Label-key root**: every label key the page consumes is derived as
+ *    `website.<pageRef>.<sectionRef>.<slot>` (see `WebsiteLabelKeySchema`).
+ *    Renaming a `WebsitePageRef` therefore renames every label key the
+ *    page commits to — handle as a labelled rename, never a silent edit.
+ * 2. **Manifest registry key**: `WebsiteRootConfig.pageManifests[]` is keyed
+ *    by `ref`; the Astro adapter looks pages up by ref when resolving
+ *    cross-page links (`hreflang`, locale switcher, primary nav).
+ * 3. **Skill mapping**: skills like `website-page-authoring` reference the
+ *    ref vocabulary documented here, NOT individual page files.
+ *
+ * **Format**: lowercase ASCII letters, digits and `-`. Must start with a
+ * letter (no leading digit / hyphen). 1–64 characters. The format is the
+ * smallest set that survives URL paths, file names, JSON keys and i18n keys
+ * without escaping or case-folding.
+ *
+ * **Why a brand**: prevents accidental cross-talk with `WebsiteSectionRef`
+ * (also kebab-case) and with arbitrary user-supplied strings. Consumers must
+ * go through `WebsitePageRefSchema.parse(...)` (or the manifest factory)
+ * before a value flows into label-key resolution or routing.
+ *
+ * @example
+ *   const ref = WebsitePageRefSchema.parse('landing');
+ *   // ref: WebsitePageRef ("landing")
+ */
+const _WebsitePageRefSchema = z
+  .string()
+  .min(1, { error: 'WebsitePageRef must be at least 1 character' })
+  .max(64, { error: 'WebsitePageRef must be at most 64 characters' })
+  .regex(
+    /^[a-z][a-z0-9-]*$/,
+    { error: 'WebsitePageRef must be lowercase kebab-case starting with a letter (e.g. "landing", "pricing-tiers")' },
+  )
+  .brand<'WebsitePageRef'>();
+
+export const WebsitePageRefSchema: typeof _WebsitePageRefSchema = _WebsitePageRefSchema;
+
+export type WebsitePageRef = z.infer<typeof _WebsitePageRefSchema>;
+/** @wildo_source:part:end saas.website.refs.page */

package/src/schemas/refs/section-ref.schemas.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+
+/**
+ * @wildo_source:part:start saas.website.refs.section facet:layer:shared facet:family:website
+ *
+ * `WebsiteSectionRef` — branded kebab-case identifier for one section on a
+ * page (e.g. `'hero'`, `'social-proof'`, `'pricing-teaser'`, `'final-cta'`).
+ *
+ * The section ref is the **section-level structural identity**:
+ *
+ * 1. **Label-key root**: every label leaf consumed inside a section is
+ *    rooted at `website.<pageRef>.<sectionRef>.<slot>`. The hook
+ *    `useWebsiteLabel('headline')` (Phase 2) reads `WebsiteSectionContext`
+ *    to derive the full key; the section author never types the page or
+ *    section ref into a label call.
+ * 2. **Page manifest contract**: `WebsitePageManifest.sectionRefs[]`
+ *    declares the refs the page commits to. The label-pack validator
+ *    cross-references the manifest's declared refs against the actual
+ *    sections rendered, surfacing mismatches at build start.
+ * 3. **DOM landmark**: `<WebsiteSection ref="…">` (Phase 2) emits
+ *    `<section data-section-ref="…">` so analytics, scroll-tracking, and
+ *    automated audits can identify sections without parsing class names.
+ *
+ * **Format**: lowercase ASCII letters, digits and `-`. Must start with a
+ * letter. 1–64 characters. Same shape as `WebsitePageRef` for consistency
+ * across both ref scopes.
+ *
+ * **Why a brand**: same reasoning as `WebsitePageRef`. The two refs are
+ * structurally identical strings but semantically distinct — branding
+ * prevents accidental swaps between page-level and section-level APIs at
+ * compile time.
+ *
+ * @example
+ *   const heroRef = WebsiteSectionRefSchema.parse('hero');
+ *   const ctaRef = WebsiteSectionRefSchema.parse('final-cta');
+ */
+const _WebsiteSectionRefSchema = z
+  .string()
+  .min(1, { error: 'WebsiteSectionRef must be at least 1 character' })
+  .max(64, { error: 'WebsiteSectionRef must be at most 64 characters' })
+  .regex(
+    /^[a-z][a-z0-9-]*$/,
+    { error: 'WebsiteSectionRef must be lowercase kebab-case starting with a letter (e.g. "hero", "social-proof")' },
+  )
+  .brand<'WebsiteSectionRef'>();
+
+export const WebsiteSectionRefSchema: typeof _WebsiteSectionRefSchema = _WebsiteSectionRefSchema;
+
+export type WebsiteSectionRef = z.infer<typeof _WebsiteSectionRefSchema>;
+/** @wildo_source:part:end saas.website.refs.section */

package/src/schemas/sections/website-section-category.shared.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+
+/**
+ * @wildo_source:part:start saas.website.sections.category-enum facet:layer:shared facet:family:website
+ *
+ * `WebsiteSectionCategory` — closed vocabulary tagging the **structural
+ * intent** of a section.
+ *
+ * The category is NOT a layout-shape constraint and NOT a CSS class; the
+ * framework ships zero concrete sections and never inspects
+ * the category at render time. The category exists for three orthogonal
+ * non-render concerns:
+ *
+ * 1. **Structured-data dispatch**: the
+ *    SEO library reads `WebsiteSectionDefinition.category` to decide
+ *    which JSON-LD vocabulary the section's `getStructuredData()` hook
+ *    is allowed to emit. e.g. `PRICING` may emit `Product` /
+ *    `AggregateOffer`; `FAQ` may emit `FAQPage`; `HERO` may emit
+ *    `Organization` / `WebSite`. Mismatches are surfaced as build-time
+ *    warnings.
+ * 2. **Authoring guidance**: each value has matching application-builder
+ *    guidance. When introducing a new category, provide its public authoring
+ *    method before asking an application to use it.
+ * 3. **Analytics labelling**: the runtime emits
+ *    `data-section-category="…"` on the `<WebsiteSection>` wrapper so
+ *    analytics tooling can group section impressions
+ *    without parsing className conventions.
+ *
+ * **Closed vocabulary on purpose**: a free-string `category` would
+ * defeat the skill-mapping and SEO-dispatch contracts. Consumers who
+ * need a wholly-novel section shape use the `RAW` advanced path
+ * (`website-factory-advanced` skill) which bypasses the category
+ * vocabulary entirely.
+ *
+ * **Adding a value**: requires (a) a new entry here, (b) a matching
+ * `website_section_<value>` skill stub, (c) (optionally) a
+ * structured-data dispatch entry in the SEO library. Removing a value
+ * is a labelled rename — every consumer's
+ * `defineWebsiteSection({ category: … })` declaration breaks at compile
+ * time, which is the desired loud failure.
+ */
+export enum WebsiteSectionCategory {
+  HERO = 'hero',
+  CTA = 'cta',
+  FEATURE_BENEFIT_SUMMARY = 'feature-benefit-summary',
+  FEATURE_DETAIL = 'feature-detail',
+  PRICING = 'pricing',
+  CONTACT = 'contact',
+  SOCIAL_PROOF = 'social-proof',
+  FAQ = 'faq',
+  FOOTER_CTA = 'footer-cta',
+  /**
+   * Escape hatch for sections that don't fit any standard category
+   * (third-party widgets, custom one-off marketing pieces). Skips the
+   * SEO-dispatch contract — the section's `getStructuredData()` may
+   * return any vocabulary, no validation. Authors should prefer a
+   * concrete category whenever possible; using `RAW` opts the section
+   * out of the framework's structured-data safety net.
+   */
+  RAW = 'raw',
+}
+
+export const WebsiteSectionCategorySchema: z.ZodEnum<typeof WebsiteSectionCategory> =
+  z.enum(WebsiteSectionCategory);
+/** @wildo_source:part:end saas.website.sections.category-enum */