@wildo-ai/saas-website 1.1.1

package/src/config/wildo-website-config.schemas.ts

@@ -0,0 +1,322 @@
+/**
+ * @wildo_source:part:start engine.saas-website.config facet:layer:engine facet:family:marketing-website
+ *
+ * Per-service marketing-website configuration block, authored in
+ * the website service folder as `wildo.website.config.ts`.
+ *
+ * # What this file's loaded value is used for TODAY
+ *
+ * This schema is the single source of truth for the marketing-site routing
+ * and origin surface. Every consumer reads here:
+ *
+ *   - `defaultLocale` + `locales` — read by `buildAstroI18nConfig(...)`,
+ *     `assertLabelPacksValid(...)`, `loadWebsitePageRuntime(...)` and
+ *     `renderWebsitePageHeadHtml(...)` via the shared `WebsiteSiteContext`.
+ *   - `publicOrigin` — read by the head renderer to compose absolute
+ *     `<link rel="canonical">`, `og:url`, hreflang `href` URLs and
+ *     the structured-data `mainEntityOfPage`. The previous
+ *     `WebsiteRootConfig.seo.siteOrigin` was deleted.
+ *   - `appOrigin` — has NO runtime consumer today. The
+ *     marketing → app handoff link surface that will read it does
+ *     not exist yet. Authored eagerly so the link-surface PR is a
+ *     single framework-owned move; until then the field is exercised
+ *     only by the schema parser.
+ *   - `csp?` — read by the website-local `sync-nginx-csp` build step,
+ *     which merges the app-static posture with `infra.csp?.<serviceKey>`,
+ *     emits the generated artifact consumed by Astro pages, and rewrites
+ *     the checked-in nginx marker file used by the website Docker image.
+ *
+ * Future companion subprocesses that introspect the marketing
+ * surface (locale-coverage audits, label-pack validation against
+ * authored locales, SEO-link sanity checks) will also read here —
+ * none exist today.
+ *
+ * # Why this is per-service website configuration
+ *
+ * Co-locating the schema with the engine package that owns its semantics
+ * keeps three concerns separate from application-root service declarations:
+ *
+ *   1. **Right reuse axis.** Marketing-site content (locales, SEO origins,
+ *      future label-pack overrides, marketing-only CTAs) is conceptually
+ *      different from saas-app-level service declarations (`path`,
+ *      `serviceName`, `frontendType`, `sessionStorage`). The marketing
+ *      config travels with the website service folder, NOT with the
+ *      SaaS app root. Two unrelated lifecycles, two different review
+ *      audiences.
+ *   2. **Engine boundary.** `platform-config-lib` no longer needs to
+ *      depend on `@wildo-ai/presets-components-models` (the home of
+ *      `AvailableLanguage`) just to type the marketing-site locale
+ *      enum. Adding a new website primitive (a new SEO field, a new
+ *      locale-pack id) belongs with the website package and its public
+ *      configuration contract.
+ *   3. **Disambiguator hazard.** The previous root-level
+ *      `marketingWebsite?` block silently assumed "one STATIC_WEBSITE
+ *      service per SaaS app" — but nothing in the schema enforced it.
+ *      Two STATIC_WEBSITE services would have silently shared one
+ *      config block with no obvious "which one wins?" answer. The
+ *      application configuration rejects more than one STATIC_WEBSITE (and
+ *      TECH_DOC) service, so the per-service config-file lookup is
+ *      deterministic by construction.
+ *
+ * # Schema decisions encoded here
+ *
+ * - `z.strictObject` so authoring an unknown key surfaces as a parse
+ *   error at `defineWebsiteConfig` time instead of being silently
+ *   dropped (same posture as `WildoSaasConfigSchema` and
+ *   `WildoTechnicalDocConfigSchema`).
+ *
+ * - **No `enabled` field.** The gate is "is there a `wildo.website.config.ts`
+ *   in a `frontendType: STATIC_WEBSITE` service folder?" — file
+ *   presence under a STATIC_WEBSITE service IS the enable signal.
+ *   The Astro build / dev companion / future audit CLI requires the
+ *   file when it walks a STATIC_WEBSITE service folder, so a
+ *   half-authored config simply cannot exist (the loader fails
+ *   closed). Removing the boolean closes a foot-gun: an authored
+ *   `enabled: false` block was previously a silent way to keep the
+ *   config "warm" without shipping anything, and consumers had to
+ *   remember to read the flag in addition to the file presence — a
+ *   future read-the-config / forget-the-flag bug waiting to happen.
+ *   A separate `services.<key>.enabled` pattern (orthogonal to
+ *   marketing-website) is the right place for any "temporarily
+ *   disable this service" story (deferred — see DASHBOARD).
+ *
+ * - URL fields are `z.url()` (Zod 4 native validator) so we get
+ *   protocol + host parsing for free, matching the rest of the
+ *   codebase.
+ *
+ * - `csp?` is typed against `WildoCspConfigSchema` from
+ *   `@wildo-ai/platform-config-lib`, mirroring the docs service's
+ *   `wildo.tech-doc.config.ts` contract. The parsed value is consumed by
+ *   the shared `resolveCspPolicy()` / `emitCspArtifacts()` generator flow.
+ *
+ * - `defaultLocale ∈ locales` cross-check via `.superRefine` —
+ *   keeping `defaultLocale` as a top-level field is product-explicit
+ *   ("which locale URL is the canonical one") and decouples it from
+ *   list ordering. Locale-path uniqueness AND locale-value
+ *   uniqueness are also enforced — duplicate paths would silently
+ *   overwrite each other in the Astro build and corrupt the sitemap;
+ *   duplicate locales would produce duplicate hreflang entries.
+ *
+ * - Locale primitive is `AvailableLanguage`. The schema imports it
+ *   from `@wildo-ai/presets-components-models/public-runtime` (the
+ *   side-effect-free public-runtime seam), but **consumers authoring
+ *   `wildo.website.config.ts` must import it from
+ *   `@wildo-ai/saas-models/public-runtime`**. Both paths produce identical
+ *   values; saas-models simply re-exports the presets atom. Picking
+ *   one path consistently across consumer files prevents drift in
+ *   docs / examples / search results. Values authored in
+ *   `wildo.website.config.ts` are the lowercase BCP-47 strings
+ *   (`'en'`, `'fr'`), NOT the UPPERCASE TS enum member names
+ *   (`EN`, `FR`). `z.enum(AvailableLanguage)` parses against the
+ *   enum VALUES, which is what we want.
+ */
+
+import { WildoCspConfigSchema } from '@wildo-ai/platform-config-lib';
+import { z } from 'zod';
+import { AvailableLanguage } from '@wildo-ai/presets-components-models/public-runtime';
+
+/**
+ * Per-locale configuration. Each authored locale gets one entry.
+ *
+ * `path` is the locale URL prefix segment (e.g. `'en'`, `'fr'`) — the
+ * Astro builder maps `/en/...` and `/fr/...` paths via this value. We
+ * do NOT auto-derive `path` from the locale string because some
+ * deployments may want a flat root for the default locale (`/...`
+ * instead of `/en/...`); keeping it explicit per locale leaves that
+ * door open without a config-shape change.
+ */
+export const WebsiteLocaleConfigSchema = z.strictObject({
+  locale: z.enum(AvailableLanguage),
+  path: z
+    .string()
+    .min(1)
+    .regex(
+      /^[a-z0-9-]+$/,
+      'locale path must be lowercase alphanumeric with hyphens (becomes a URL segment)',
+    ),
+});
+export type WebsiteLocaleConfig = z.infer<typeof WebsiteLocaleConfigSchema>;
+
+/**
+ * Per-service marketing-website configuration block.
+ *
+ * Authored as `export default defineWebsiteConfig({...})` in
+ * `<website-service-root>/wildo.website.config.ts`. The Astro
+ * build loads this file once at bootstrap via jiti and composes
+ * a `WebsiteSiteContext`; helpers consume that composed context rather than
+ * this raw value.
+ *
+ * @example
+ * ```ts
+ * import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+ * import { defineWebsiteConfig } from '@wildo-ai/saas-website';
+ *
+ * export default defineWebsiteConfig({
+ *   publicOrigin: 'https://example.com',
+ *   appOrigin: 'https://app.example.com',
+ *   defaultLocale: AvailableLanguage.EN,
+ *   locales: [
+ *     { locale: AvailableLanguage.EN, path: 'en' },
+ *     { locale: AvailableLanguage.FR, path: 'fr' },
+ *   ],
+ *   csp: { enabled: true, reportOnly: true },
+ * });
+ * ```
+ */
+export const WildoMarketingWebsiteConfigSchema = z
+  .strictObject({
+    /**
+     * Public origin of the marketing site (apex / www) — canonical
+     * input the Astro head renderer emits as absolute URLs
+     * (`<link rel="canonical">`, `og:url`, hreflang `href`,
+     * sitemap base, structured-data `mainEntityOfPage`).
+     *
+     * MUST NOT end with `/` — the head renderer composes
+     * `${publicOrigin}${routePath}` and a trailing slash would emit
+     * `https://example.com//`. Surface the constraint loudly here
+     * rather than silently corrupting URLs at build time.
+     */
+    publicOrigin: z
+      .url()
+      .refine((value) => !value.endsWith('/'), {
+        error:
+          'WildoMarketingWebsiteConfig.publicOrigin must NOT end with "/" (the head ' +
+          'renderer concatenates publicOrigin + routePath; trailing slash would emit "//")',
+      }),
+
+    /**
+     * Origin of the SaaS application the marketing site links into
+     * (signup / login / pricing → checkout).
+     *
+     * **Today**: NO runtime consumer. The cross-origin handoff
+     * surface that will read it does not exist yet. Authored
+     * eagerly so the link-surface PR is a single framework-owned move
+     * — until then the field is exercised only by the schema
+     * parser.
+     *
+     * Distinct from the general `WildoSaasConfig.services.<name>`
+     * URL surface because the marketing site is a separate Astro
+     * project that does not load the full SaaS app graph at build
+     * time.
+     */
+    appOrigin: z.url(),
+
+    /**
+     * Backend API origin the marketing site POSTs to for anonymous
+     * captures (lead / draft-note forms) — e.g.
+     * `https://api.example.com`. Threaded through
+     * `WebsiteRuntimeContext.apiOrigin` into the React island that
+     * constructs the `WebsiteAnonymousSessionClient`.
+     *
+     * OPTIONAL because a pure brochure site with no capture forms never
+     * talks to an API — only sites that host an anonymous-capture
+     * section need it. When such a section renders without a resolved
+     * `apiOrigin`, the section surfaces a loud misconfiguration rather
+     * than silently POSTing nowhere.
+     *
+     * MUST NOT end with `/` — the anon client composes
+     * `${apiOrigin}${MAIN_API_BASE_PATH}${path}` and a trailing slash
+     * would emit a doubled `//` in the request URL. (The client also
+     * defensively strips trailing slashes, but the refine surfaces the
+     * mistake at authoring time.)
+     *
+     * Distinct from `appOrigin` (the human-facing app the marketing CTAs
+     * link into) and `publicOrigin` (the marketing site's own canonical
+     * origin): this is the machine-to-machine API host.
+     */
+    apiOrigin: z
+      .url()
+      .refine((value) => !value.endsWith('/'), {
+        error:
+          'WildoMarketingWebsiteConfig.apiOrigin must NOT end with "/" (the anonymous ' +
+          'client concatenates apiOrigin + MAIN_API_BASE_PATH + path; a trailing slash ' +
+          'would emit "//")',
+      })
+      .optional(),
+
+    /**
+     * Optional Content-Security-Policy override for the marketing site.
+     * Consumed by the website-local `sync-nginx-csp` step, which emits
+     * the generated artifact for Astro page injection and rewrites the
+     * website nginx marker file from the same resolved output.
+     */
+    csp: WildoCspConfigSchema.optional(),
+
+    /**
+     * Default locale the marketing site serves for unmatched URLs
+     * and as the canonical hreflang signal. Must appear in
+     * `locales` below (cross-check enforced by the schema-level
+     * `.superRefine`).
+     *
+     * Read by `buildAstroI18nConfig(...)` (drives Astro's own
+     * `i18n.defaultLocale`) and by the head renderer (drives
+     * `<html lang="...">`, `og:locale`, hreflang `x-default`).
+     */
+    defaultLocale: z.enum(AvailableLanguage),
+
+    /**
+     * Ordered list of locales the marketing site builds. Order is
+     * preserved (used by the language switcher rendering and by
+     * the sitemap emitter — when the sitemap surface lands).
+     *
+     * Read by `buildAstroI18nConfig(...)` (Astro `i18n.locales`),
+     * by `assertLabelPacksValid(...)` (one label pack per locale),
+     * by `loadWebsitePageRuntime(...)` (per-page locale resolution),
+     * and by the head renderer (hreflang alternates).
+     */
+    locales: z.array(WebsiteLocaleConfigSchema).min(1),
+  })
+  .superRefine((config, ctx) => {
+    const declaredLocales = new Set(config.locales.map((entry) => entry.locale));
+    if (!declaredLocales.has(config.defaultLocale)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['defaultLocale'],
+        message:
+          `defaultLocale '${config.defaultLocale}' is not declared in 'locales' ` +
+          `(declared: [${[...declaredLocales].join(', ')}]). The default locale ` +
+          `must be one of the locales the site actually builds.`,
+      });
+    }
+
+    // Locale-path uniqueness: two entries collapsing to the same URL
+    // segment would silently overwrite each other in the Astro build
+    // and corrupt the sitemap. Fail closed at parse time.
+    const pathOwners = new Map<string, AvailableLanguage>();
+    for (const entry of config.locales) {
+      const previous = pathOwners.get(entry.path);
+      if (previous !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['locales'],
+          message:
+            `Locale path '${entry.path}' is declared by both '${previous}' and ` +
+            `'${entry.locale}'. Each locale must have a unique URL path segment.`,
+        });
+        continue;
+      }
+      pathOwners.set(entry.path, entry.locale);
+    }
+
+    // Locale-value uniqueness: same locale appearing twice would
+    // produce duplicate hreflang entries and ambiguous default-locale
+    // resolution.
+    const localeOwners = new Map<AvailableLanguage, string>();
+    for (const entry of config.locales) {
+      const previousPath = localeOwners.get(entry.locale);
+      if (previousPath !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['locales'],
+          message:
+            `Locale '${entry.locale}' is declared twice (paths '${previousPath}' ` +
+            `and '${entry.path}'). Each locale must appear at most once.`,
+        });
+        continue;
+      }
+      localeOwners.set(entry.locale, entry.path);
+    }
+  });
+export type WildoMarketingWebsiteConfig = z.infer<typeof WildoMarketingWebsiteConfigSchema>;
+export type WildoMarketingWebsiteConfigInput = z.input<typeof WildoMarketingWebsiteConfigSchema>;
+/** @wildo_source:part:end engine.saas-website.config */

package/src/config-loader.ts

@@ -0,0 +1,35 @@
+/**
+ * @wildo-package @wildo-ai/saas-website (Node-only config-loader entry)
+ *
+ * Dedicated subpath for the per-service `wildo.website.config.ts`
+ * loader (`saas-website-slice.md` Step 7.5 — mirrors the
+ * `saas-technical-doc.md` Step 7.5 ship). Consumers:
+ *
+ *   - `examples/wonder-todos/website/astro.config.ts` — wires the
+ *     loader into the Astro build's `i18n` config.
+ *   - Future companion subprocesses that introspect the marketing
+ *     surface (locale coverage audits, SEO-link sanity checks).
+ *
+ * @wildo-boundary
+ *   This entry is on the **Node-only** side of the bundle boundary.
+ *   It re-exports `loadWebsiteConfig` (which transitively pulls
+ *   `loadConfig` from `@wildo-ai/platform-config-lib` — jiti-backed,
+ *   uses `node:fs` / `node:path` / `node:crypto`) and is therefore
+ *   carved into its own package subpath so it cannot leak into the
+ *   browser-side React-island bundle.
+ *
+ *   Enforced by `engine/saas-website/src/__tests__/bundle-isolation.test.ts`:
+ *     - This file IS in `ENTRY_FILES` (so the closure walker covers it).
+ *     - `@wildo-ai/platform-config-lib` is in `ALLOWED_BARE_SPECIFIERS`
+ *       AND `SSR_ONLY_BARE_SPECIFIERS`, which together prove the
+ *       specifier reaches the closure ONLY through this entry — never
+ *       through `index.ts`, `companion-exports.ts`, or `astro-island.ts`.
+ *
+ *   Re-exporting `loadWebsiteConfig` from `index.ts` would (a) drag
+ *   `@wildo-ai/platform-config-lib`'s heavy graph into the marketing-
+ *   site browser bundle and (b) trip the SSR-tier negative test
+ *   above — both fail-loud signals that this subpath separation
+ *   exists for a reason.
+ */
+
+export * from './config/load-website-config';

package/src/core/__tests__/WebsitePageLayout.test.tsx

@@ -0,0 +1,184 @@
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { BUILTIN_PROVIDER_CAPABILITY } from '@wildo-ai/saas-models/public-runtime';
+
+import { WebsitePageLayout } from '../layouts/WebsitePageLayout';
+import {
+  WebsiteRuntimeContextProvider,
+  type WebsiteRuntimeContextValue,
+} from '../contexts/WebsiteRuntimeContext';
+import { useWebsitePage } from '../contexts/useWebsitePage';
+import { WebsiteLabelKeySchema } from '../../schemas/label-keys/website-label-key.schemas';
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+const RuntimeHeader = (): React.ReactElement => <span data-testid="runtime-header">RH</span>;
+const RuntimeFooter = (): React.ReactElement => <span data-testid="runtime-footer">RF</span>;
+
+const SKIP_KEY = WebsiteLabelKeySchema.parse('website.chrome.layout.skip-to-main-content');
+
+const RUNTIME: WebsiteRuntimeContextValue = {
+  locale: AvailableLanguage.EN,
+  defaultLocale: AvailableLanguage.EN,
+  labelPack: { 'website.chrome.layout.skip-to-main-content': 'Skip to main content' },
+  designTokens: {
+    colors: {
+      background: '#fff', foreground: '#000', primary: '#000',
+      primaryForeground: '#fff', accent: '#000', accentForeground: '#fff',
+      surface: '#fff', surfaceForeground: '#000', border: '#ccc',
+      muted: '#eee', mutedForeground: '#666',
+    },
+    radii: { none: '0', sm: '2px', md: '4px', lg: '8px', xl: '12px', full: '9999px' },
+  },
+  navigation: {
+    headerComponent: RuntimeHeader,
+    footerComponent: RuntimeFooter,
+  },
+  skipToMainContentLabelKey: SKIP_KEY,
+};
+
+const RUNTIME_WITH_FRONTEND_PROVIDERS: WebsiteRuntimeContextValue = {
+  ...RUNTIME,
+  frontendProviderRegistry: {
+    modules: new Map(),
+    getProviderByRef() {
+      return undefined;
+    },
+    getProvidersByProviderCapability() {
+      return [];
+    },
+    findProviderByProviderCapability(providerCapability) {
+      switch (providerCapability) {
+        case BUILTIN_PROVIDER_CAPABILITY.FRONTEND_PRODUCT_ANALYTICS:
+          return {
+            metadata: { ref: 'posthog' },
+            providerCapabilities: [BUILTIN_PROVIDER_CAPABILITY.FRONTEND_PRODUCT_ANALYTICS],
+            protocols: ['FRONTEND_SDK'],
+            publicConfig: { integrationKind: 'product-analytics' },
+          };
+        case BUILTIN_PROVIDER_CAPABILITY.FRONTEND_ERROR_MONITORING:
+          return {
+            metadata: { ref: 'sentry' },
+            providerCapabilities: [BUILTIN_PROVIDER_CAPABILITY.FRONTEND_ERROR_MONITORING],
+            protocols: ['FRONTEND_SDK'],
+            publicConfig: { integrationKind: 'browser-error-monitoring' },
+          };
+        case BUILTIN_PROVIDER_CAPABILITY.FRONTEND_CAPTCHA:
+          return {
+            metadata: { ref: 'recaptcha' },
+            providerCapabilities: [BUILTIN_PROVIDER_CAPABILITY.FRONTEND_CAPTCHA],
+            protocols: ['FRONTEND_SDK'],
+            publicConfig: { integrationKind: 'captcha' },
+          };
+        default:
+          return undefined;
+      }
+    },
+  },
+};
+
+const wrap = (children: React.ReactNode) => (
+  <WebsiteRuntimeContextProvider value={RUNTIME}>{children}</WebsiteRuntimeContextProvider>
+);
+
+function PageRefProbe(): React.ReactElement {
+  const { pageRef } = useWebsitePage();
+  return <span data-testid="page-ref">{pageRef as unknown as string}</span>;
+}
+
+describe('WebsitePageLayout', () => {
+  it('provides the page ref to descendants and stamps the data attribute', () => {
+    const { getByTestId, container } = render(
+      wrap(
+        <WebsitePageLayout pageRef="landing">
+          <PageRefProbe />
+        </WebsitePageLayout>,
+      ),
+    );
+    expect(getByTestId('page-ref')).toHaveTextContent('landing');
+    expect(container.querySelector('[data-website-page-ref="landing"]')).not.toBeNull();
+  });
+
+  it('renders runtime navigation header + footer by default', () => {
+    const { getByTestId } = render(
+      wrap(
+        <WebsitePageLayout pageRef="landing">
+          <span>body</span>
+        </WebsitePageLayout>,
+      ),
+    );
+    expect(getByTestId('runtime-header')).toBeInTheDocument();
+    expect(getByTestId('runtime-footer')).toBeInTheDocument();
+  });
+
+  it('honors per-page header/footer overrides', () => {
+    const { getByTestId, queryByTestId } = render(
+      wrap(
+        <WebsitePageLayout
+          pageRef="landing"
+          header={<div data-testid="custom-header">CH</div>}
+          footer={<div data-testid="custom-footer">CF</div>}
+        >
+          <span>body</span>
+        </WebsitePageLayout>,
+      ),
+    );
+    expect(getByTestId('custom-header')).toBeInTheDocument();
+    expect(getByTestId('custom-footer')).toBeInTheDocument();
+    expect(queryByTestId('runtime-header')).toBeNull();
+    expect(queryByTestId('runtime-footer')).toBeNull();
+  });
+
+  it('suppresses chrome when header/footer are explicitly null', () => {
+    const { container } = render(
+      wrap(
+        <WebsitePageLayout pageRef="landing" header={null} footer={null}>
+          <span>body</span>
+        </WebsitePageLayout>,
+      ),
+    );
+    expect(container.querySelector('header')).toBeNull();
+    expect(container.querySelector('footer')).toBeNull();
+  });
+
+  it('uses semantic <main> for the body wrapper', () => {
+    const { container } = render(
+      wrap(
+        <WebsitePageLayout pageRef="landing">
+          <span data-testid="body">body</span>
+        </WebsitePageLayout>,
+      ),
+    );
+    const main = container.querySelector('main');
+    expect(main).not.toBeNull();
+    expect(main?.querySelector('[data-testid="body"]')).not.toBeNull();
+  });
+
+  it('stamps active website provider refs on the layout root when available', () => {
+    const { container } = render(
+      <WebsiteRuntimeContextProvider value={RUNTIME_WITH_FRONTEND_PROVIDERS}>
+        <WebsitePageLayout pageRef="landing">
+          <span>body</span>
+        </WebsitePageLayout>
+      </WebsiteRuntimeContextProvider>,
+    );
+    const layoutRoot = container.querySelector('[data-website-page-ref="landing"]');
+    expect(layoutRoot).not.toBeNull();
+    expect(layoutRoot).toHaveAttribute('data-website-product-analytics-provider-ref', 'posthog');
+    expect(layoutRoot).toHaveAttribute('data-website-error-monitoring-provider-ref', 'sentry');
+    expect(layoutRoot).toHaveAttribute('data-website-captcha-provider-ref', 'recaptcha');
+  });
+
+  it('rejects malformed pageRef at parse time', () => {
+    expect(() =>
+      render(
+        wrap(
+          <WebsitePageLayout pageRef="INVALID UPPERCASE">
+            <span />
+          </WebsitePageLayout>,
+        ),
+      ),
+    ).toThrowError(/WebsitePageRef/);
+  });
+});

package/src/core/__tests__/WebsiteSection.test.tsx

@@ -0,0 +1,85 @@
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+import { WebsiteSection } from '../layouts/WebsiteSection';
+import { useWebsiteSection } from '../contexts/useWebsiteSection';
+import { WebsiteSectionCategory } from '../../schemas/sections/website-section-category.shared';
+
+function SectionRefProbe(): React.ReactElement {
+  const { sectionRef, category } = useWebsiteSection();
+  return (
+    <span data-testid="probe">
+      {(sectionRef as unknown as string)}|{category}
+    </span>
+  );
+}
+
+describe('WebsiteSection', () => {
+  it('renders a semantic <section> with data-section-ref + data-section-category', () => {
+    const { container } = render(
+      <WebsiteSection sectionRef="hero" category={WebsiteSectionCategory.HERO}>
+        <span>body</span>
+      </WebsiteSection>,
+    );
+    const section = container.querySelector('section');
+    expect(section).not.toBeNull();
+    expect(section?.getAttribute('data-section-ref')).toBe('hero');
+    expect(section?.getAttribute('data-section-category')).toBe('hero');
+  });
+
+  it('provides the section context to descendants', () => {
+    const { getByTestId } = render(
+      <WebsiteSection sectionRef="pricing" category={WebsiteSectionCategory.PRICING}>
+        <SectionRefProbe />
+      </WebsiteSection>,
+    );
+    expect(getByTestId('probe')).toHaveTextContent('pricing|pricing');
+  });
+
+  it('forwards id, className, aria-label, aria-labelledby', () => {
+    const { container } = render(
+      <WebsiteSection
+        sectionRef="cta"
+        category={WebsiteSectionCategory.CTA}
+        id="primary-cta"
+        className="my-section"
+        ariaLabel="Primary call to action"
+        ariaLabelledBy="cta-heading"
+      >
+        <span>body</span>
+      </WebsiteSection>,
+    );
+    const section = container.querySelector('section');
+    expect(section?.id).toBe('primary-cta');
+    expect(section?.className).toBe('my-section');
+    expect(section?.getAttribute('aria-label')).toBe('Primary call to action');
+    expect(section?.getAttribute('aria-labelledby')).toBe('cta-heading');
+  });
+
+  it('omits aria-* attributes when not provided', () => {
+    const { container } = render(
+      <WebsiteSection sectionRef="hero" category={WebsiteSectionCategory.HERO}>
+        <span>body</span>
+      </WebsiteSection>,
+    );
+    const section = container.querySelector('section');
+    expect(section?.hasAttribute('aria-label')).toBe(false);
+    expect(section?.hasAttribute('aria-labelledby')).toBe(false);
+    expect(section?.hasAttribute('id')).toBe(false);
+  });
+
+  it('rejects malformed sectionRef at parse time', () => {
+    expect(() =>
+      render(
+        <WebsiteSection
+          sectionRef="UPPER_BAD"
+          category={WebsiteSectionCategory.HERO}
+        >
+          <span />
+        </WebsiteSection>,
+      ),
+    ).toThrowError(/WebsiteSectionRef/);
+  });
+});