@wildo-ai/saas-website 1.1.5 → 1.1.7

package/src/core/external-providers/useWebsiteProviderComponent.ts

@@ -0,0 +1,76 @@
+/**
+ * Reading provider-contributed components on the website (#1703) — the website's counterpart of the
+ * application's `useProviderComponentChoices` / `useProviderComponent`, over the same registry and
+ * the same status vocabulary (`ProviderComponentStatus`).
+ *
+ * Two differences from the application, both about WHO answers:
+ *
+ *   - the consent grant is the VISITOR's decision from `WebsiteConsentContext`, not a signed-in
+ *     person's stored preference;
+ *   - nothing starts before that decision has been read from storage (`isResolved`). The server render
+ *     and the first client render read no storage, and asking the registry then would report a
+ *     consent-required state to a visitor who already agreed, flashing the refusal on every page.
+ *
+ * Neither hook picks a provider: when several providers offer a component for one capability,
+ * choosing is the page's job.
+ */
+
+import { useEffect, useState } from 'react';
+import {
+  idleProviderComponentLoadState,
+  startProviderComponentLoad,
+  type ProviderComponentLoadState,
+} from '@wildo-ai/external-connectors-public/website';
+import type { ProviderCapability } from '@wildo-ai/saas-models/public-runtime';
+
+import { useWebsiteConsent } from '../consent/useWebsiteConsent';
+import { useWebsiteRuntime } from '../contexts/useWebsiteRuntime';
+import type { WebsiteProviderComponentType } from './provider-component-registry.website';
+
+/** What `useWebsiteProviderComponent` returns: the shared load state, holding a React component. */
+export type WebsiteProviderComponentState = ProviderComponentLoadState<WebsiteProviderComponentType>;
+
+/**
+ * The providers that are BOTH live for this website service and carry a component for this
+ * capability, in the order the service declared them. Synchronous, so a page can render its choice
+ * on the first frame.
+ */
+export function useWebsiteProviderComponentChoices(capability: ProviderCapability): ReadonlyArray<string> {
+  const { providerComponentRegistry } = useWebsiteRuntime();
+  return providerComponentRegistry?.listProviders(capability) ?? [];
+}
+
+/**
+ * Loads one provider's component for a capability, once the visitor's consent decision is known.
+ *
+ * Pass `undefined` for the ref while nothing is chosen. The load runs in an effect, so it never runs
+ * during the Astro server render; `CONSENT_REQUIRED` means nothing of the provider was downloaded,
+ * and granting the missing purposes through the consent panel loads it without a re-mount.
+ */
+export function useWebsiteProviderComponent(
+  capability: ProviderCapability,
+  providerRef: string | undefined,
+): WebsiteProviderComponentState {
+  const { providerComponentRegistry } = useWebsiteRuntime();
+  const consent = useWebsiteConsent();
+  const grantedKey = [...consent.grantedPurposes].sort().join(',');
+  const [state, setState] = useState<WebsiteProviderComponentState>(() => idleProviderComponentLoadState<WebsiteProviderComponentType>());
+
+  useEffect(() => {
+    if (!consent.isResolved) {
+      setState(idleProviderComponentLoadState<WebsiteProviderComponentType>());
+      return undefined;
+    }
+    return startProviderComponentLoad({
+      registry: providerComponentRegistry,
+      capability,
+      providerRef,
+      grantedConsentPurposes: consent.grantedPurposes,
+      onState: setState,
+    });
+    // `grantedPurposes` is read through `grantedKey`: keyed by the granted SET, not the array's identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [capability, providerRef, providerComponentRegistry, consent.isResolved, grantedKey]);
+
+  return state;
+}

package/src/core/external-providers/useWebsiteProviderScripts.ts

@@ -31,16 +31,18 @@
  * Revisit if a provider ever needs to run before first paint.
  */
 
-import { useEffect } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import {
   activateFrontendProviderSdks,
-  collectDeclaredProviderScripts,
+  collectProviderScriptsWithoutComponents,
   consentPurposesRequiredByProvider,
+  createFrontendProviderSdkActivationLane,
   injectProviderScripts,
-  type ActivatedFrontendProviderSdks,
 } from '@wildo-ai/external-connectors-public/website';
 import { AppFrontendType, type ConsentPurpose } from '@wildo-ai/saas-models/public-runtime';
 import type { FrontendWebsiteProviderRegistry } from './frontend-provider-registry.website';
+import type { WebsiteProviderComponentRegistry } from './provider-component-registry.website';
+import type { WebsiteProviderSdkActivation } from './website-provider-sdk-activations';
 
 /**
  * A stable key for a granted-purpose set, so an effect re-runs when the SET changes and not when a new
@@ -50,20 +52,28 @@ function grantedKey(grantedConsentPurposes: readonly ConsentPurpose[]): string {
   return [...grantedConsentPurposes].sort().join(',');
 }
 
+/**
+ * Injects the `<script>` tags of the live providers that rest on NO consent purpose and render no component.
+ *
+ * No consent input, deliberately (#1704): an executed `<script>` cannot be stopped, so a provider that rests on a
+ * purpose must ship as a stoppable SDK (started on the grant and stopped on withdrawal by
+ * {@link useWebsiteProviderSdks}); a consent-based module declaring `scripts` is refused at projection and skipped by
+ * the collector. No grant could change what this injects.
+ */
 export function useWebsiteProviderScripts(
   registry: FrontendWebsiteProviderRegistry | undefined,
   /**
-   * The purposes the visitor granted (#534). A provider resting on an ungranted purpose injects nothing;
-   * granting it later injects its script then. A withdrawal cannot remove an executed script, so it takes
-   * effect on the next page load.
+   * The website's provider-component registry (#1703). A provider with a registered component loads its
+   * scripts WITH that component, when a page first shows it — so an address lookup's vendor loader is
+   * not downloaded on every page of the site, only on the one with the form. This hook injects the rest.
    */
-  grantedConsentPurposes: readonly ConsentPurpose[],
+  componentRegistry?: WebsiteProviderComponentRegistry,
 ): void {
-  const key = grantedKey(grantedConsentPurposes);
   useEffect(() => {
     if (typeof document === 'undefined') return;
 
-    const scripts = collectDeclaredProviderScripts(registry?.modules.values(), grantedConsentPurposes);
+    const withComponents = [...(componentRegistry?.providersWithComponents() ?? [])].map((providerRef) => ({ providerRef }));
+    const scripts = collectProviderScriptsWithoutComponents(registry?.modules.values() ?? [], withComponents);
     if (scripts.length === 0) return;
 
     injectProviderScripts(scripts, document);
@@ -71,8 +81,7 @@ export function useWebsiteProviderScripts(
     // work immediately; removing the element undoes neither, so a cleanup that
     // removed it would only make the next mount inject a SECOND copy of an
     // already-running script. Idempotence by `src` is the real guard.
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed by the granted SET, see grantedKey.
-  }, [registry, key]);
+  }, [registry, componentRegistry]);
 }
 
 /**
@@ -91,16 +100,20 @@ export function useWebsiteProviderSdks(
    * is withdrawn — which is the only way a withdrawal stops a running analytics client.
    */
   grantedConsentPurposes: readonly ConsentPurpose[],
-): void {
-  useProviderSdkGroup(registry, false, []);
-  useProviderSdkGroup(registry, true, grantedConsentPurposes);
+): ReadonlyArray<WebsiteProviderSdkActivation> {
+  const consentFree = useProviderSdkGroup(registry, false, []);
+  const consentBased = useProviderSdkGroup(registry, true, grantedConsentPurposes);
+  // The providers RUNNING on this page, both groups, published by the page layout (#1735): a form reads the captcha
+  // vendor's handle from here. Emptied the moment a group stops, so nothing holds a handle past a withdrawal.
+  return useMemo(() => [...consentFree, ...consentBased], [consentFree, consentBased]);
 }
 
 function useProviderSdkGroup(
   registry: FrontendWebsiteProviderRegistry | undefined,
   consentBased: boolean,
   grantedConsentPurposes: readonly ConsentPurpose[],
-): void {
+): ReadonlyArray<WebsiteProviderSdkActivation> {
+  const [running, setRunning] = useState<ReadonlyArray<WebsiteProviderSdkActivation>>([]);
   // Keyed by the grants this group's providers actually rest on, so changing an unrelated purpose does
   // not stop and restart a running analytics client.
   const relevant = registry === undefined
@@ -110,6 +123,8 @@ function useProviderSdkGroup(
       .flatMap((module) => consentPurposesRequiredByProvider(module))
       .filter((purpose) => grantedConsentPurposes.includes(purpose));
   const key = grantedKey(relevant);
+  // One lane per group for the page's lifetime: a start waits for the previous stop.
+  const lane = useRef(createFrontendProviderSdkActivationLane());
   useEffect(() => {
     if (registry === undefined) return;
     const modules = [...registry.modules.values()].filter(
@@ -117,31 +132,35 @@ function useProviderSdkGroup(
     );
     if (modules.length === 0) return;
 
-    let unmounted = false;
-    let activated: ActivatedFrontendProviderSdks | undefined;
-
-    void activateFrontendProviderSdks({
-      surface: AppFrontendType.STATIC_WEBSITE,
-      modules,
-      grantedConsentPurposes,
-      onDiagnostic: (diagnostic) => {
-        // The website runtime has no logger service, and a provider that cannot
-        // start is a developer-facing fact that must not be silent.
-        // eslint-disable-next-line no-console
-        console.warn(`[wildo-provider-sdk] ${diagnostic.kind}: ${diagnostic.message}`);
+    // Through the group's lane, so a start never overlaps the previous stop of the same page-global vendor (#1704): a
+    // visitor who grants, withdraws and grants again while the bundle downloads must not have the first run's stop
+    // switch off the second run's client. The stop also covers an unmount mid-download.
+    const stop = lane.current.start(
+      () => activateFrontendProviderSdks({
+        surface: AppFrontendType.STATIC_WEBSITE,
+        modules,
+        grantedConsentPurposes,
+        onDiagnostic: (diagnostic) => {
+          // The website runtime has no logger service, and a provider that cannot
+          // start is a developer-facing fact that must not be silent.
+          // eslint-disable-next-line no-console
+          console.warn(`[wildo-provider-sdk] ${diagnostic.kind}: ${diagnostic.message}`);
+        },
+      }),
+      (result) => {
+        setRunning(modules.flatMap((module) => {
+          const activation = result.activations.get(module.metadata.ref);
+          return activation === undefined
+            ? []
+            : [{ providerRef: module.metadata.ref, providerCapabilities: [...module.providerCapabilities], activation }];
+        }));
       },
-    }).then((result) => {
-      activated = result;
-      // Activation is asynchronous and unmount is not: if the surface went away
-      // while a vendor bundle was still downloading, stop what we just started
-      // rather than leaving a client nobody can reach.
-      if (unmounted) void result.deactivateAll();
-    });
-
+    );
     return () => {
-      unmounted = true;
-      void activated?.deactivateAll();
+      setRunning([]);
+      stop();
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed by the granted SET, see grantedKey.
   }, [registry, consentBased, key]);
+  return running;
 }

package/src/core/external-providers/website-provider-sdk-activations.ts

@@ -0,0 +1,23 @@
+/**
+ * The provider SDKs RUNNING on this website page (#1735), published by the page layout.
+ *
+ * A section reaches a running vendor through here rather than through a global — the contact form asks the consented
+ * captcha vendor for a token this way. The list is emptied the moment a provider is stopped (a consent withdrawal, a
+ * navigation), so a consumer that reads it at the moment it needs a handle never holds one past a withdrawal.
+ */
+import { createContext, useContext } from 'react';
+import type { ProviderFrontendSdkActivation } from '@wildo-ai/external-connectors-public/website';
+
+/** One running provider: its ref, the capabilities it serves, and its activation (whose `handle` is the vendor's client). */
+export interface WebsiteProviderSdkActivation {
+  readonly providerRef: string;
+  readonly providerCapabilities: ReadonlyArray<string>;
+  readonly activation: ProviderFrontendSdkActivation;
+}
+
+export const WebsiteProviderSdkActivationsContext = createContext<ReadonlyArray<WebsiteProviderSdkActivation>>([]);
+
+/** The provider SDKs running on this page, in declaration order. Empty outside a page layout and before any start. */
+export function useWebsiteProviderSdkActivations(): ReadonlyArray<WebsiteProviderSdkActivation> {
+  return useContext(WebsiteProviderSdkActivationsContext);
+}

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

@@ -71,9 +71,9 @@ export interface TypedWebsiteSectionDefinition<TProps>
  * **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 schema parse provides a single audited validation chokepoint,
+ *     and the parsed `expectedLabelKeys` are what `wildo website audit`
+ *     checks every locale pack against, 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

package/src/core/layouts/WebsitePageLayout.tsx

@@ -7,8 +7,10 @@ import {
   useWebsiteProviderScripts,
   useWebsiteProviderSdks,
 } from '../external-providers/useWebsiteProviderScripts';
+import { WebsiteProviderSdkActivationsContext } from '../external-providers/website-provider-sdk-activations';
 import type { WebsitePageContextValue } from '../contexts/WebsitePageContext';
 import { useWebsiteRuntime } from '../contexts/useWebsiteRuntime';
+import { websiteDesignTokenCssVar } from '../../schemas/design-tokens/website-design-tokens.shared.schemas';
 import { useWebsiteLabelByKey } from '../hooks/useWebsiteLabel';
 import { WebsiteConsentProvider, WebsiteConsentStatus, type WebsiteConsentRecorder } from '../consent/WebsiteConsentContext';
 import { useWebsiteConsent } from '../consent/useWebsiteConsent';
@@ -100,10 +102,10 @@ const SKIP_LINK_FOCUS_CSS = `
   overflow: visible !important;
   clip: auto !important;
   white-space: normal !important;
-  background: var(--website-colors-background, #fff) !important;
-  color: var(--website-colors-foreground, #000) !important;
-  border: 2px solid var(--website-colors-primary, #000) !important;
-  border-radius: var(--website-radii-md, 0.375rem) !important;
+  background: ${websiteDesignTokenCssVar('colors', 'background', '#fff')} !important;
+  color: ${websiteDesignTokenCssVar('colors', 'foreground', '#000')} !important;
+  border: 2px solid ${websiteDesignTokenCssVar('colors', 'primary', '#000')} !important;
+  border-radius: ${websiteDesignTokenCssVar('radii', 'md', '0.375rem')} !important;
   z-index: 9999 !important;
   text-decoration: none !important;
 }
@@ -281,8 +283,9 @@ function WebsitePageLayoutContent({
   //
   // Consent-based providers start only once their purpose is granted (#534). Before the stored decision is
   // read, nothing is granted — the static HTML and the first render start nothing optional.
-  useWebsiteProviderScripts(runtime.frontendProviderRegistry, consent.grantedPurposes);
-  useWebsiteProviderSdks(runtime.frontendProviderRegistry, consent.grantedPurposes);
+  useWebsiteProviderScripts(runtime.frontendProviderRegistry, runtime.providerComponentRegistry);
+  // The running SDKs are published to the page (#1735): the contact form asks the consented captcha vendor for a token.
+  const runningProviderSdks = useWebsiteProviderSdks(runtime.frontendProviderRegistry, consent.grantedPurposes);
 
   const providerRootAttributes = useMemo<Record<string, string>>(() => {
     const attrs: Record<string, string> = {};
@@ -330,6 +333,7 @@ function WebsitePageLayoutContent({
 
   return (
     <WebsitePageContextProvider value={pageContextValue}>
+      <WebsiteProviderSdkActivationsContext.Provider value={runningProviderSdks}>
       <div
         data-website-page-ref={safePageRef as unknown as string}
         className={className}
@@ -357,6 +361,7 @@ function WebsitePageLayoutContent({
         {resolvedFooter !== null ? <footer>{resolvedFooter}</footer> : null}
         {renderConsentSurface(consent, runtime.consentBannerComponent)}
       </div>
+      </WebsiteProviderSdkActivationsContext.Provider>
     </WebsitePageContextProvider>
   );
 }

package/src/index.ts

@@ -11,75 +11,33 @@
  * accompanying SKILLs in `framework-knowledge`.
  *
  * @wildo-boundary
- *   - This barrel MAY re-export from any subdirectory of `src/`.
- *   - Subdirectories MUST observe their own boundary contracts (see
- *     each subdirectory's own `index.ts` `@wildo-boundary` block):
+ *   This barrel re-exports the React-side surface: `schemas/`, `core/`,
+ *   `components/`. The other entries are separate subpaths with their own
+ *   audiences — `/astro` (Node, Astro frontmatter), `/astro-island` (the
+ *   bridge factory), `/config` and `/config-loader` (Node), `/mdx`,
+ *   `/companion` (React-free). Per directory:
  *       - `schemas/`            : NO React, NO Astro, NO `~wildo-frontend-lib/**`
- *       - `seo/`                : NO React, NO Astro
- *       - `core/`               : MAY use React; NO `~wildo-frontend-lib/**` (Q17=B)
- *       - `astro/`              : MAY use Astro; NO React component runtime imports
+ *       - `core/`, `components/`: MAY use React; NO `~wildo-frontend-lib/**` (Q17=B)
+ *       - `astro/`              : MAY use Astro and Node; NO React component runtime imports
+ *       - `config/`             : Node-side loaders; never reachable from a React-island entry
  *       - `mdx/`                : MAY use `@mdx-js/*`
- *       - `integration/`        : MAY use React; MAY import the
- *                                 `@wildo-ai/saas-models/public-runtime` SUBPATH,
- *                                 the `@wildo-ai/presets-components-models/public-runtime`
- *                                 SUBPATH, `@wildo-ai/zod-decorators`,
- *                                 plus the SSR / Astro-middleware tier
- *                                 (`axios`, `jsonwebtoken`, `socket.io-client`,
- *                                 `reflect-metadata`) — D12 revised
- *                                 2026-04-19 (second same-day loosening);
- *                                 the ROOT barrels of `@wildo-ai/saas-models`
- *                                 and `@wildo-ai/presets-components-models`
- *                                 are FORBIDDEN (they boot the decorator
- *                                 framework / pull the heavy registry);
- *                                 the saas-app DI / backend stack
- *                                 (`inversify`, `mongoose`, `express`,
- *                                 `pino`, `helmet`, `argon2`, `bcrypt`,
- *                                 the `@wildo-ai/saas-frontend-lib` /
- *                                 `@wildo-ai/saas-backend-lib` /
- *                                 `@wildo-ai/external-connectors-models`
- *                                 root + subpath surfaces) is FORBIDDEN;
- *                                 MUST NOT import `~wildo-frontend-lib/**`
- *                                 (Q17=B / D16)
  *
- *   D12 (client-bundle import discipline, all `core/`/`schemas/`/`integration/`
- *   files): the entire saas-website source tree ships into a browser bundle
- *   (Astro SSG + React islands). Every shared model atom MUST come from a
- *   side-effect-free `/public-runtime` subpath:
- *     - `@wildo-ai/saas-models/public-runtime` is the primary door
- *       (saas-models-public-runtime.md K-6 — consumers see one path).
- *     - `@wildo-ai/presets-components-models/public-runtime` is the
- *       internal seam for symbols not (yet) re-exported by saas-models.
- *     - `@wildo-ai/zod-decorators` is allowed to import (first revision
- *       2026-04-19). The package itself is side-effect-free; only an
- *       explicit `initZodDecorators()` call mutates `z.ZodType.prototype`,
- *       which neither saas-website nor the saas-models /public-runtime
- *       barrel does.
- *     - `axios`, `jsonwebtoken`, `socket.io-client`, `reflect-metadata` are
- *       allowed for SSR / Astro-middleware code paths (second same-day
- *       revision 2026-04-19). The website engine needs them to provide
- *       middleware utilities (HTTP proxying to the SaaS backend, JWT
- *       verification of cross-frontend handoff codes, real-time push,
- *       decorator-metadata reads). They are SSR-tier — discipline
- *       (and a future strict/loose entry split for React islands vs
- *       middleware) keeps them out of the React-island bundle.
+ *   D12 (client-bundle import discipline): everything reachable from a
+ *   React-island entry ships to the browser, so every shared model atom
+ *   comes from a side-effect-free `/public-runtime` subpath —
+ *   `@wildo-ai/saas-models/public-runtime` first,
+ *   `@wildo-ai/presets-components-models/public-runtime` for symbols it does
+ *   not re-export yet — and `@wildo-ai/zod-decorators` is allowed because
+ *   only an explicit `initZodDecorators()` mutates Zod's prototype.
  *
- *   The ROOT barrel of `@wildo-ai/saas-models` is forbidden everywhere in
- *   this package — it calls `initZodDecorators()` at module load and pulls
- *   `@wildo-ai/external-connectors-models` + the full schema graph into
- *   the bundle. Same forbid applies to the root barrel of
- *   `@wildo-ai/presets-components-models`, the saas-app DI runtime
- *   (`inversify`, `@wildo-ai/saas-frontend-lib`, `@wildo-ai/saas-backend-lib`),
- *   and pure-backend libs (`mongoose`, `express`, `pino`, `helmet`,
- *   `argon2`, `bcrypt`). Enforced by `src/__tests__/bundle-isolation.test.ts`.
- *
- *   These boundaries are enforced by review + the bundle-isolation test
- *   above until Phase 8 promotes them to a programmatic ESLint check
- *   (cf. `saas-website-slice.md`
- *   §"DEFERRED to Phase 8 — boundary lint mechanism design").
- *
- * Phase 1+2 status: schemas + runtime contexts/hooks + layout
- * primitives + L1 placeholders + factories are all exported. Phase 5
- * adds the Astro adapter; Phase 5.7 the `integration/` layer.
+ *   The ROOT barrels of `@wildo-ai/saas-models` and
+ *   `@wildo-ai/presets-components-models` are forbidden everywhere in this
+ *   package (they boot the decorator framework and pull the full schema
+ *   graph), as are the saas-app DI runtime (`inversify`,
+ *   `@wildo-ai/saas-frontend-lib`, `@wildo-ai/saas-backend-lib`) and
+ *   pure-backend libs (`mongoose`, `express`, `pino`, `helmet`, `argon2`,
+ *   `bcrypt`). Enforced by `src/__tests__/bundle-isolation.test.ts`, which
+ *   walks every entry's import graph against an allow-list.
  *
  * D18 (L1 boundary, Phase 2): the L1 primitives (`WebsiteHeading`,
  * `WebsiteText`, `WebsiteButton`, `WebsiteLink`, `WebsiteImage`) are
@@ -96,10 +54,12 @@ export * from './schemas/refs/page-ref.schemas';
 export * from './schemas/refs/section-ref.schemas';
 export * from './schemas/label-keys/website-label-key.schemas';
 export * from './schemas/label-keys/website-consent-label-keys.schemas';
+export * from './schemas/label-keys/website-provider-component-label-keys.schemas';
 export * from './schemas/sections/website-section-category.shared';
 export * from './schemas/sections/website-section-definition.shared.schemas';
 export * from './schemas/structured-data/website-structured-data.shared.schemas';
 export * from './schemas/structured-data/structured-data-reconciliation.shared';
+export * from './schemas/structured-data/pricing-offer-structured-data.shared';
 export * from './schemas/design-tokens/website-design-tokens.shared.schemas';
 export * from './schemas/manifests/website-page-manifest.shared.schemas';
 export * from './schemas/manifests/website-root-config.shared.schemas';
@@ -125,9 +85,15 @@ export * from './core/consent/useWebsiteConsent';
 export * from './core/consent/WebsiteConsentGate';
 export * from './core/consent/WebsiteConsentBanner';
 
+export * from './core/external-providers/provider-component-registry.website';
+export * from './core/external-providers/useWebsiteProviderComponent';
+export * from './core/external-providers/WebsiteProviderComponent';
+export * from './core/external-providers/website-provider-sdk-activations';
+
 export * from './core/anonymous-session/website-anonymous-session-client';
 export * from './core/anonymous-session/inbound-contact-form.schema';
 export * from './core/anonymous-session/InboundContactForm';
+export * from './core/anonymous-session/website-submission-challenge';
 
 export * from './components/low-level/WebsiteHeading';
 export * from './components/low-level/WebsiteText';

package/src/schemas/__tests__/design-token-css-property.test.ts

@@ -0,0 +1,72 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import { renderWebsiteDesignTokensCss } from '../../astro/website-page-head.renderer';
+import {
+  WebsiteDesignTokensSchema,
+  websiteDesignTokenCssProperty,
+  websiteDesignTokenCssVar,
+  type WebsiteDesignTokens,
+} from '../design-tokens/website-design-tokens.shared.schemas';
+
+const TOKENS: WebsiteDesignTokens = WebsiteDesignTokensSchema.parse({
+  colors: {
+    background: '#fff',
+    foreground: '#111',
+    primary: '#222',
+    primaryForeground: '#fff',
+    accent: '#333',
+    accentForeground: '#fff',
+    surface: '#eee',
+    surfaceForeground: '#444',
+    border: '#ccc',
+    muted: '#ddd',
+    mutedForeground: '#555',
+  },
+  radii: { none: '0', sm: '0.25rem', md: '0.5rem', lg: '0.75rem', xl: '1rem', full: '9999px' },
+});
+
+const SOURCE_ROOT = join(__dirname, '..', '..');
+
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir).flatMap((entry) => {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) return entry === '__tests__' ? [] : sourceFiles(full);
+    return /\.(ts|tsx)$/.test(entry) ? [full] : [];
+  });
+}
+
+describe('design-token CSS property naming', () => {
+  it('the renderer emits every token under the name the readers reference', () => {
+    const css = renderWebsiteDesignTokensCss(TOKENS);
+    for (const [group, values] of Object.entries(TOKENS)) {
+      for (const token of Object.keys(values)) {
+        expect(css).toContain(`${websiteDesignTokenCssProperty(group, token)}:`);
+      }
+    }
+    // The key is verbatim: the reader the consent banner used to be spelled `surface-foreground`.
+    expect(css).toContain('--website-colors-surfaceForeground: #444;');
+    expect(websiteDesignTokenCssVar('colors', 'surfaceForeground', '#000')).toBe('var(--website-colors-surfaceForeground, #000)');
+    expect(websiteDesignTokenCssVar('radii', 'md')).toBe('var(--website-radii-md)');
+  });
+
+  it('no engine source spells a token custom property by hand', () => {
+    // Positive control: the walk reaches the component that used to carry the defect.
+    const files = sourceFiles(SOURCE_ROOT);
+    expect(files.some((file) => file.endsWith('WebsiteConsentBanner.tsx'))).toBe(true);
+
+    const offenders = files
+      .filter((file) => !file.endsWith('website-design-tokens.shared.schemas.ts'))
+      .flatMap((file) =>
+        readFileSync(file, 'utf8')
+          .split('\n')
+          .map((line, index) => ({ line, index }))
+          // A `var(--website-…)` in code, not in a comment explaining the naming rule.
+          .filter(({ line }) => /var\(--website-/.test(line) && !/^\s*(\*|\/\/)/.test(line))
+          .map(({ index }) => `${relative(SOURCE_ROOT, file)}:${index + 1}`),
+      );
+    expect(offenders).toEqual([]);
+  });
+});