@wildo-ai/saas-website 1.1.1

package/src/core/contexts/WebsiteRuntimeContext.tsx

@@ -0,0 +1,175 @@
+import React, { createContext, type ReactNode } from 'react';
+
+import type { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import type { WebsiteDesignTokens } from '../../schemas/design-tokens/website-design-tokens.shared.schemas';
+import type { FrontendWebsiteProviderRegistry } from '../external-providers/frontend-provider-registry.website';
+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.runtime.context facet:layer:core facet:family:website
+ *
+ * `WebsiteRuntimeContext` — site-wide runtime state for the marketing
+ * surface. Created **once per page render** by the host adapter
+ * (Phase 5 `WebsitePageBridge.astro` reads `WebsiteRootConfig` and the
+ * resolved label pack from disk and calls
+ * `<WebsiteRuntimeContextProvider value={…}>` around the page tree).
+ *
+ * **Why "runtime" and not "config"**: the values here are the
+ * locale-resolved subset of `WebsiteRootConfig` — only the active
+ * locale's label pack travels with the React tree (the other locales
+ * live in their own per-locale static builds). A `*Config` name would
+ * suggest the full multi-locale surface is in scope.
+ *
+ * **Three pieces of state**:
+ *
+ * - `locale` — the currently-rendering locale. Sections that need
+ *   locale-aware formatting (number/date in marketing copy is rare
+ *   but legitimate) read it via `useWebsiteRuntime()`.
+ * - `labelPack` — the locale-resolved flat key→string map, validated
+ *   against the manifest by `validateLabelPackAgainstManifest` at
+ *   build start. Consumed by `useWebsiteLabel` and
+ *   `useWebsiteLabelByKey`.
+ * - `designTokens` — the `WebsiteDesignTokens` from
+ *   `WebsiteRootConfig.designTokens`. Consumed by
+ *   `useWebsiteDesignTokens` and by the Phase 5 CSS emitter that
+ *   materializes them as `--website-*` custom properties on the
+ *   `<WebsitePageLayout>` root.
+ * - `navigation` — the `WebsiteNavigationConfig` from
+ *   `WebsiteRootConfig.navigation`. Carried in the runtime context
+ *   (rather than as a separate `WebsiteNavigationContext`) because
+ *   `<WebsitePageLayout>` already reads runtime state and
+ *   header/footer slots are inseparable from "the site is rendering
+ *   right now". A second context for two component refs would split
+ *   the host-adapter's wiring surface without buying isolation.
+ * - `frontendProviderRegistry` — optional website-facing public provider
+ *   registry hydrated from the materialized provider artifact for the
+ *   concrete `STATIC_WEBSITE` service. This keeps analytics / captcha /
+ *   browser-monitoring integrations on the same frontend-provider
+ *   contract the SaaS app now uses, instead of inventing a website-only
+ *   metadata seam.
+ *
+ * **Why a separate file from the hook + provider**: split for React
+ * Fast Refresh — when a `.tsx` exports both a React component and a
+ * React Context object, edits to either one invalidate the entire
+ * module's HMR boundary. Keeping the bare context here, the hook in
+ * `useWebsiteRuntime.ts`, and the provider component in
+ * `WebsiteRuntimeContextProvider.tsx` makes section authors edit
+ * components without retriggering the runtime context's identity.
+ */
+export interface WebsiteRuntimeContextValue {
+  /**
+   * The currently-rendering locale. Marketing-site routing emits one
+   * static build per locale (D8), so this value is constant per build
+   * — never re-renders mid-session.
+   */
+  locale: AvailableLanguage;
+  /**
+   * The site's default locale (mirrors `WebsiteRootConfig.defaultLocale`).
+   * Carried in the runtime context so client-tier components — namely
+   * `WebsiteInternalLink` (Phase 6 fix H-β) — can compute the correct
+   * locale-prefixed pathname (`/pricing` on the EN site,
+   * `/fr/pricing` on the FR site) without re-importing the root
+   * config. Plumbing it through the runtime keeps the routing rule
+   * a framework-internal concern: section authors NEVER hand-prefix
+   * paths.
+   */
+  defaultLocale: AvailableLanguage;
+  /**
+   * Flat `Record<string, string>` label pack for the active locale.
+   * Lookup keys MUST be fully-composed `website.<page>.<section>.<slot>`
+   * strings; consumers that hold leaf paths use `useWebsiteLabel(leaf)`
+   * which composes the full key against the page+section context.
+   */
+  labelPack: LabelPack;
+  /**
+   * Design-token bundle for the active site. Same object referenced
+   * by `WebsiteRootConfig.designTokens`; passed by reference (not
+   * cloned) so token-aware components can rely on referential
+   * stability across renders.
+   */
+  designTokens: WebsiteDesignTokens;
+  /**
+   * Site-wide navigation slot bindings (header / footer components).
+   * Same object referenced by `WebsiteRootConfig.navigation`. Read
+   * by `<WebsitePageLayout>` to render the chrome around each page's
+   * `<main>` content; per-page `header` / `footer` props on
+   * `<WebsitePageLayout>` override these defaults.
+   */
+  navigation: WebsiteNavigationConfig;
+  /**
+   * Fully-composed label key the framework reads to render the
+   * "Skip to main content" affordance as the FIRST focusable element
+   * on every page (Phase 6 third audit fix M-α). Mirrors
+   * `WebsiteRootConfig.skipToMainContentLabelKey`. Carried in the
+   * runtime context (NOT re-derived from the root config inside
+   * `WebsitePageLayout`) for two reasons:
+   *   - The layout is a client-tier React component; it cannot import
+   *     the consumer's `WEBSITE_ROOT_CONFIG` symbol without dragging
+   *     server-only code (manifest registry, page components) into
+   *     the client bundle.
+   *   - Threading the key through the runtime keeps the layout's
+   *     contract symmetric with how every other localized text on the
+   *     page is sourced (label pack + key), so the skip link is
+   *     translated automatically without any per-locale branching.
+   */
+  skipToMainContentLabelKey: WebsiteLabelKey;
+  /**
+   * Website-facing public providers for the active static website
+   * service. Optional so older tests and provider-free sites can omit
+   * it, but when present it is the canonical frontend-safe provider
+   * catalog for analytics / captcha / browser-monitoring slices.
+   */
+  frontendProviderRegistry?: FrontendWebsiteProviderRegistry;
+  /**
+   * Backend API origin (WITHOUT a trailing slash) that anonymous-capture
+   * sections POST to when constructing a `WebsiteAnonymousSessionClient`
+   * (lead / draft-note forms). Sourced from
+   * `WildoMarketingWebsiteConfig.apiOrigin` and passed as a
+   * JSON-serializable island prop (the `.astro` page resolves the
+   * per-environment value and forwards it).
+   *
+   * Optional because only pages that host an anonymous-capture section
+   * need it — brochure pages omit it. A capture section that reads
+   * `undefined` here surfaces a loud misconfiguration rather than
+   * silently failing to submit.
+   */
+  apiOrigin?: string;
+}
+
+/**
+ * Bare React context. Default `null` — `useWebsiteRuntime()` throws
+ * with a clear error message when invoked outside of
+ * `<WebsiteRuntimeContextProvider>`. The defensive throw is preferred
+ * over a silent default value so a missing provider is detected at
+ * the first hook call rather than at render time when a missing
+ * label silently renders as the key string.
+ */
+export const WebsiteRuntimeContext: React.Context<WebsiteRuntimeContextValue | null> =
+  createContext<WebsiteRuntimeContextValue | null>(null);
+
+export interface WebsiteRuntimeContextProviderProps {
+  value: WebsiteRuntimeContextValue;
+  children: ReactNode;
+}
+
+/**
+ * Provider component. Authored as a thin wrapper so consumers do NOT
+ * have to import `WebsiteRuntimeContext.Provider` directly — the
+ * provider component carries the documented authoring API and is the
+ * Fast-Refresh-stable surface section authors compose against.
+ */
+export function WebsiteRuntimeContextProvider({
+  value,
+  children,
+}: WebsiteRuntimeContextProviderProps): ReactNode {
+  return (
+    <WebsiteRuntimeContext.Provider value={value}>
+      {children}
+    </WebsiteRuntimeContext.Provider>
+  );
+}
+WebsiteRuntimeContextProvider.displayName = 'WebsiteRuntimeContextProvider';
+/** @wildo_source:part:end saas.website.runtime.context */

package/src/core/contexts/WebsiteSectionContext.tsx

@@ -0,0 +1,59 @@
+import React, { createContext, type ReactNode } from 'react';
+
+import type { WebsiteSectionCategory } from '../../schemas/sections/website-section-category.shared';
+import type { WebsiteSectionRef } from '../../schemas/refs/section-ref.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.section.context facet:layer:core facet:family:website
+ *
+ * `WebsiteSectionContext` — identity + metadata of the section
+ * currently rendering. Provided by `<WebsiteSection>` and consumed
+ * by `useWebsiteLabel(leaf)` to compose the full label key, by
+ * analytics overlays that need the category, and by SEO emitters
+ * that decorate sections with `data-*` attributes.
+ *
+ * **Why expose `category` here (not just `sectionRef`)**: the
+ * category is the section's semantic role (`hero`, `cta`, `social`,
+ * etc.) and is needed by overlay tooling and analytics consumers
+ * that don't know the per-site `sectionRef` vocabulary. Bundling
+ * both saves consumers from having to thread the manifest just to
+ * map a ref back to its category.
+ *
+ * **Why a separate file from the hook**: same Fast-Refresh rationale
+ * as the runtime + page contexts.
+ */
+export interface WebsiteSectionContextValue {
+  /**
+   * The validated `WebsiteSectionRef` of the section currently
+   * rendering. Composed by `useWebsiteLabel(leaf)` into the full key.
+   */
+  sectionRef: WebsiteSectionRef;
+  /**
+   * The semantic category of the section (`hero` / `cta` / etc.).
+   * Sourced from the matching `WebsiteSectionDefinition.category`
+   * by the host adapter and surfaced here so analytics + SEO
+   * tooling does not need to re-resolve it.
+   */
+  category: WebsiteSectionCategory;
+}
+
+export const WebsiteSectionContext: React.Context<WebsiteSectionContextValue | null> =
+  createContext<WebsiteSectionContextValue | null>(null);
+
+export interface WebsiteSectionContextProviderProps {
+  value: WebsiteSectionContextValue;
+  children: ReactNode;
+}
+
+export function WebsiteSectionContextProvider({
+  value,
+  children,
+}: WebsiteSectionContextProviderProps): ReactNode {
+  return (
+    <WebsiteSectionContext.Provider value={value}>
+      {children}
+    </WebsiteSectionContext.Provider>
+  );
+}
+WebsiteSectionContextProvider.displayName = 'WebsiteSectionContextProvider';
+/** @wildo_source:part:end saas.website.section.context */

package/src/core/contexts/useWebsitePage.ts

@@ -0,0 +1,28 @@
+import { useContext } from 'react';
+
+import {
+  WebsitePageContext,
+  type WebsitePageContextValue,
+} from './WebsitePageContext';
+
+/**
+ * @wildo_source:part:start saas.website.use-page.hook facet:layer:core facet:family:website
+ *
+ * Returns the active page identity. Throws when called outside a
+ * `<WebsitePageLayout>` so a section dropped at the wrong level (eg.
+ * directly under the runtime provider, before the page layout) fails
+ * loud at first render rather than silently composing a malformed
+ * label key.
+ */
+export function useWebsitePage(): WebsitePageContextValue {
+  const value = useContext(WebsitePageContext);
+  if (value === null) {
+    throw new Error(
+      '[useWebsitePage] must be called inside <WebsitePageLayout>. ' +
+        'Sections that need to compose a label key require a page identity ' +
+        '— wrap your content in `<WebsitePageLayout pageRef="…">` first.',
+    );
+  }
+  return value;
+}
+/** @wildo_source:part:end saas.website.use-page.hook */

package/src/core/contexts/useWebsiteRuntime.ts

@@ -0,0 +1,34 @@
+import { useContext } from 'react';
+
+import {
+  WebsiteRuntimeContext,
+  type WebsiteRuntimeContextValue,
+} from './WebsiteRuntimeContext';
+
+/**
+ * @wildo_source:part:start saas.website.use-runtime.hook facet:layer:core facet:family:website
+ *
+ * `useWebsiteRuntime()` — read access to the
+ * `WebsiteRuntimeContextValue`. Throws if invoked outside of a
+ * `<WebsiteRuntimeContextProvider>` so a missing host adapter is
+ * detected at the first hook call (fail-loud).
+ *
+ * Section authors usually do NOT call this directly — prefer the
+ * higher-level hooks (`useWebsiteLabel`, `useWebsiteLabelByKey`,
+ * `useWebsiteDesignTokens`) which expose only the slice they need.
+ * Direct access is reserved for layout primitives and locale-aware
+ * formatters that legitimately need the active locale or the raw
+ * label pack.
+ */
+export function useWebsiteRuntime(): WebsiteRuntimeContextValue {
+  const value = useContext(WebsiteRuntimeContext);
+  if (value === null) {
+    throw new Error(
+      '[useWebsiteRuntime] must be called inside <WebsiteRuntimeContextProvider>. ' +
+        'In Astro pages this is provided by `WebsitePageBridge.astro` — make sure ' +
+        'your page imports the bridge instead of rendering React components directly.',
+    );
+  }
+  return value;
+}
+/** @wildo_source:part:end saas.website.use-runtime.hook */

package/src/core/contexts/useWebsiteSection.ts

@@ -0,0 +1,28 @@
+import { useContext } from 'react';
+
+import {
+  WebsiteSectionContext,
+  type WebsiteSectionContextValue,
+} from './WebsiteSectionContext';
+
+/**
+ * @wildo_source:part:start saas.website.use-section.hook facet:layer:core facet:family:website
+ *
+ * Returns the active section identity + category. Throws when called
+ * outside `<WebsiteSection>` so a leaf primitive that needs the
+ * section ref (eg. a CMS-bound text block calling `useWebsiteLabel`)
+ * fails loud the moment it's dropped at the wrong nesting depth.
+ */
+export function useWebsiteSection(): WebsiteSectionContextValue {
+  const value = useContext(WebsiteSectionContext);
+  if (value === null) {
+    throw new Error(
+      '[useWebsiteSection] must be called inside <WebsiteSection>. ' +
+        'Leaf primitives that compose label keys (`useWebsiteLabel(leaf)`) ' +
+        'require a section identity — wrap your content in ' +
+        '`<WebsiteSection sectionRef="…" category="…">` first.',
+    );
+  }
+  return value;
+}
+/** @wildo_source:part:end saas.website.use-section.hook */

package/src/core/external-providers/frontend-provider-registry.website.ts

@@ -0,0 +1,62 @@
+import type {
+  FrontendProviderEntry,
+  FrontendProvidersBlock,
+  ProviderCapability,
+} from '@wildo-ai/saas-models/public-runtime';
+
+export type FrontendWebsiteProviderRef = string & {
+  readonly __brand: 'FrontendWebsiteProviderRef';
+};
+
+export type FrontendWebsiteProviderModule = FrontendProviderEntry;
+
+export interface FrontendWebsiteProviderRegistry {
+  readonly modules: ReadonlyMap<
+    FrontendWebsiteProviderRef,
+    FrontendWebsiteProviderModule
+  >;
+
+  getProviderByRef(
+    ref: FrontendWebsiteProviderRef,
+  ): FrontendWebsiteProviderModule | undefined;
+
+  getProvidersByProviderCapability(
+    providerCapability: ProviderCapability,
+  ): ReadonlyArray<FrontendWebsiteProviderModule>;
+
+  findProviderByProviderCapability(
+    providerCapability: ProviderCapability,
+  ): FrontendWebsiteProviderModule | undefined;
+}
+
+/**
+ * Website-side public-provider registry hydrated from the materialized
+ * frontend-provider bootstrap block.
+ */
+export function createFrontendWebsiteProviderRegistry(
+  frontendProviders?: FrontendProvidersBlock,
+): FrontendWebsiteProviderRegistry {
+  const modules = new Map<FrontendWebsiteProviderRef, FrontendWebsiteProviderModule>(
+    Object.entries(frontendProviders?.providers ?? {}).map(([ref, provider]) => [
+      ref as FrontendWebsiteProviderRef,
+      provider as FrontendWebsiteProviderModule,
+    ]),
+  );
+
+  return {
+    modules,
+    getProviderByRef(ref: FrontendWebsiteProviderRef) {
+      return modules.get(ref);
+    },
+    getProvidersByProviderCapability(providerCapability: ProviderCapability) {
+      return [...modules.values()].filter((provider) =>
+        provider.providerCapabilities.includes(providerCapability),
+      );
+    },
+    findProviderByProviderCapability(providerCapability: ProviderCapability) {
+      return [...modules.values()].find((provider) =>
+        provider.providerCapabilities.includes(providerCapability),
+      );
+    },
+  };
+}

package/src/core/factories/define-website-page-manifest.ts

@@ -0,0 +1,102 @@
+import type { ComponentType } from 'react';
+
+import {
+  WebsitePageManifestSchema,
+  type WebsitePageManifest,
+  type WebsitePageMetaLabelKeys,
+  type WebsitePageRoutePath,
+  type WebsitePageSeoConfig,
+  WebsitePageHydrationStrategy,
+} from '../../schemas/manifests/website-page-manifest.shared.schemas';
+import type { WebsitePageRef } from '../../schemas/refs/page-ref.schemas';
+import type { WebsiteSectionRef } from '../../schemas/refs/section-ref.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.factories.define-page-manifest facet:layer:core facet:family:website
+ *
+ * Input shape consumed by `defineWebsitePageManifest<TProps>`.
+ *
+ * `TProps` is rarely non-empty for top-level marketing pages (which
+ * are usually rendered by Astro with no React-side props), but the
+ * generic exists for two legitimate cases:
+ *   - templated pages (eg. `/blog/[slug]` whose page component
+ *     accepts `{ slug, frontmatter }` from the Astro adapter),
+ *   - pages whose host adapter wants to inject server-side resolved
+ *     props (eg. an A/B-test variant id) before hydration.
+ *
+ * **String inputs vs. branded inputs**: `ref`, `routePath`, and
+ * `sectionRefs` accept raw strings — the factory parses them through
+ * the underlying schemas. Same ergonomic + safety trade-off as
+ * `defineWebsiteSection`.
+ */
+export interface DefineWebsitePageManifestInput<TProps> {
+  ref: WebsitePageRef | string;
+  routePath: WebsitePageRoutePath | string;
+  pageComponent: ComponentType<TProps>;
+  sectionRefs: readonly (WebsiteSectionRef | string)[];
+  metaLabelKeys: WebsitePageMetaLabelKeys;
+  hydration?: WebsitePageHydrationStrategy;
+  seo?: WebsitePageSeoConfig;
+}
+
+/**
+ * Return shape of `defineWebsitePageManifest<TProps>`. Identical to
+ * `WebsitePageManifest` except `pageComponent` retains the
+ * caller-supplied generic prop shape.
+ */
+export interface TypedWebsitePageManifest<TProps>
+  extends Omit<WebsitePageManifest, 'pageComponent'> {
+  pageComponent: ComponentType<TProps>;
+}
+
+/**
+ * `defineWebsitePageManifest<TProps>` — factory that materializes a
+ * `WebsitePageManifest` from authored input.
+ *
+ * Same two responsibilities as `defineWebsiteSection`: runtime
+ * validation through the schema (incl. the schema's `superRefine`
+ * for unique sectionRefs and meta-key prefixing) plus type
+ * preservation for `pageComponent`.
+ *
+ * **Why a separate factory** (and not a single `defineWebsite*` API):
+ * a section and a page have different validation semantics
+ * (`expectedLabelKeys` discipline vs. `metaLabelKeys` prefix
+ * discipline) and different override paths (sections via L2
+ * import-swap; pages via root-config registration). Conflating them
+ * would force one of the two contracts onto the other's authors.
+ *
+ * @example
+ *   export const LANDING_PAGE_MANIFEST = defineWebsitePageManifest({
+ *     ref: 'landing',
+ *     routePath: '/',
+ *     pageComponent: LandingPage,
+ *     sectionRefs: ['hero', 'social-proof', 'pricing-teaser', 'final-cta'],
+ *     metaLabelKeys: {
+ *       titleKey: WebsiteLabelKeySchema.parse('website.landing.meta.title'),
+ *       descriptionKey: WebsiteLabelKeySchema.parse('website.landing.meta.description'),
+ *     },
+ *   });
+ */
+export function defineWebsitePageManifest<TProps = Record<string, never>>(
+  input: DefineWebsitePageManifestInput<TProps>,
+): TypedWebsitePageManifest<TProps> {
+  const parsed = WebsitePageManifestSchema.parse({
+    ref: input.ref,
+    routePath: input.routePath,
+    pageComponent: input.pageComponent,
+    sectionRefs: input.sectionRefs,
+    metaLabelKeys: input.metaLabelKeys,
+    hydration: input.hydration,
+    seo: input.seo,
+  });
+  return {
+    ref: parsed.ref,
+    routePath: parsed.routePath,
+    pageComponent: input.pageComponent,
+    sectionRefs: parsed.sectionRefs,
+    metaLabelKeys: parsed.metaLabelKeys,
+    ...(parsed.hydration !== undefined ? { hydration: parsed.hydration } : {}),
+    ...(parsed.seo !== undefined ? { seo: parsed.seo } : {}),
+  };
+}
+/** @wildo_source:part:end saas.website.factories.define-page-manifest */

package/src/core/factories/define-website-section.ts

@@ -0,0 +1,128 @@
+import type { ComponentType } from 'react';
+
+import { WebsiteSectionDefinitionSchema } from '../../schemas/sections/website-section-definition.shared.schemas';
+import type { WebsiteSectionDefinition } from '../../schemas/sections/website-section-definition.shared.schemas';
+import type { WebsiteSectionCategory } from '../../schemas/sections/website-section-category.shared';
+import type { WebsiteSectionRef } from '../../schemas/refs/section-ref.schemas';
+import type { WebsiteLabelKey } from '../../schemas/label-keys/website-label-key.schemas';
+import type { WebsiteStructuredDataReturn } from '../../schemas/structured-data/website-structured-data.shared.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.factories.define-section facet:layer:core facet:family:website
+ *
+ * Input shape consumed by `defineWebsiteSection<TProps>`. Mirrors
+ * `WebsiteSectionDefinition` but keeps `Component` typed against the
+ * caller-supplied generic so the precise prop shape survives end-to-end
+ * (the consumer's `<HeroSection />` JSX can keep its strongly-typed
+ * props after going through the factory).
+ *
+ * **String inputs vs. branded inputs**: `sectionRef` and
+ * `expectedLabelKeys` accept raw strings as well as already-branded
+ * values. The factory parses them through the underlying schemas, so
+ * either path is safe — accepting strings directly removes the
+ * ergonomic drag of forcing every section author to remember to call
+ * `WebsiteSectionRefSchema.parse(...)` in their definition.
+ */
+export interface DefineWebsiteSectionInput<TProps> {
+  sectionRef: WebsiteSectionRef | string;
+  category: WebsiteSectionCategory;
+  expectedLabelKeys: readonly (WebsiteLabelKey | string)[];
+  Component: ComponentType<TProps>;
+  /**
+   * See `WebsiteSectionDefinition.getStructuredData?` JSDoc for the
+   * full authoring contract. The factory passes the function through
+   * unchanged; the framework invokes it at static-build time and
+   * forwards the return value to `renderPageStructuredData()`.
+   */
+  getStructuredData?: () => WebsiteStructuredDataReturn;
+}
+
+/**
+ * Return shape of `defineWebsiteSection<TProps>`. Identical to
+ * `WebsiteSectionDefinition` except `Component` retains the
+ * caller-supplied generic prop shape rather than the schema's
+ * lowest-common-denominator `ComponentType<unknown>`.
+ *
+ * **Why this matters**: a consumer's `pageComponent` JSX composes
+ * sections like `<HERO_SECTION.Component {...heroProps} />`. Without
+ * preserving `TProps`, the spread would be untyped and a renamed prop
+ * would silently miss the type system. With `TProps` preserved, the
+ * call site fails to compile the moment the prop contract drifts.
+ */
+export interface TypedWebsiteSectionDefinition<TProps>
+  extends Omit<WebsiteSectionDefinition, 'Component' | 'getStructuredData'> {
+  Component: ComponentType<TProps>;
+  getStructuredData?: () => WebsiteStructuredDataReturn;
+}
+
+/**
+ * `defineWebsiteSection<TProps>` — factory that materializes a
+ * `WebsiteSectionDefinition` from authored input.
+ *
+ * **Two responsibilities**, one entry point:
+ *   1. Runtime validation — parses the input through
+ *      `WebsiteSectionDefinitionSchema` so brand checks, regex
+ *      validations, and array refinements run at module load time
+ *      (not at render time, not at build-output time).
+ *   2. Type preservation — returns an object whose `Component` field
+ *      keeps the caller-supplied `TProps`, so JSX usage of the
+ *      returned section retains compile-time prop checking.
+ *
+ * **Why a factory instead of constructing the literal directly**:
+ *   - Consumers don't have to remember to parse refs / keys
+ *     themselves before assembling the literal.
+ *   - The schema parse provides a single audited validation chokepoint
+ *     so `wildo website audit` (Phase 7) can re-validate definitions
+ *     without re-entering the React graph.
+ *   - The factory is the documented authoring API the
+ *     `website_factory_authoring` skill targets — keeping the
+ *     authoring surface narrow lets the framework evolve the
+ *     internal schema (add fields, refinements) without churning
+ *     every section definition in every consumer app.
+ *
+ * @param input section authoring input (see `DefineWebsiteSectionInput`).
+ * @returns a `TypedWebsiteSectionDefinition<TProps>` with `Component`
+ *          preserved at the precise prop type.
+ *
+ * @example
+ *   interface HeroProps {
+ *     headlineKey: WebsiteLabelKey;
+ *     subheadlineKey: WebsiteLabelKey;
+ *   }
+ *   function HeroSection({ headlineKey, subheadlineKey }: HeroProps) {
+ *     // …
+ *   }
+ *   export const HERO_SECTION = defineWebsiteSection<HeroProps>({
+ *     sectionRef: 'hero',
+ *     category: WebsiteSectionCategory.HERO,
+ *     expectedLabelKeys: [
+ *       'website.landing.hero.headline',
+ *       'website.landing.hero.subheadline',
+ *     ],
+ *     Component: HeroSection,
+ *   });
+ */
+export function defineWebsiteSection<TProps>(
+  input: DefineWebsiteSectionInput<TProps>,
+): TypedWebsiteSectionDefinition<TProps> {
+  const parsed = WebsiteSectionDefinitionSchema.parse({
+    sectionRef: input.sectionRef,
+    category: input.category,
+    expectedLabelKeys: input.expectedLabelKeys,
+    Component: input.Component,
+    getStructuredData: input.getStructuredData,
+  });
+  /**
+   * Re-attach `Component` and `getStructuredData` from the original
+   * input so the precise generic types survive — `parsed.Component`
+   * is `unknown` per the schema's `z.unknown()` contract.
+   */
+  return {
+    sectionRef: parsed.sectionRef,
+    category: parsed.category,
+    expectedLabelKeys: parsed.expectedLabelKeys,
+    Component: input.Component,
+    ...(input.getStructuredData ? { getStructuredData: input.getStructuredData } : {}),
+  };
+}
+/** @wildo_source:part:end saas.website.factories.define-section */

package/src/core/hooks/useWebsiteDesignTokens.ts

@@ -0,0 +1,26 @@
+import { useWebsiteRuntime } from '../contexts/useWebsiteRuntime';
+import type { WebsiteDesignTokens } from '../../schemas/design-tokens/website-design-tokens.shared.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.use-tokens.hook facet:layer:core facet:family:website
+ *
+ * `useWebsiteDesignTokens()` — narrow read of the runtime context's
+ * `designTokens` slice.
+ *
+ * Existence rationale (vs. asking section authors to call
+ * `useWebsiteRuntime().designTokens` directly): hook discoverability
+ * + intent clarity. A section needing tokens has a single hook to
+ * import; refactoring the runtime context to add unrelated fields
+ * (eg. a future `analytics` slice) does NOT broaden the API surface
+ * the section consumes. Keeps the dependency graph between sections
+ * and runtime state explicit and minimal.
+ *
+ * Read-by-reference — the returned object is the same instance held
+ * by the runtime context, so memoization (`useMemo` /
+ * `React.memo` deps) using the returned reference works correctly
+ * across the static build's single render lifecycle.
+ */
+export function useWebsiteDesignTokens(): WebsiteDesignTokens {
+  return useWebsiteRuntime().designTokens;
+}
+/** @wildo_source:part:end saas.website.use-tokens.hook */