@wildo-ai/saas-website 1.1.3 → 1.1.5

package/src/core/consent/WebsiteConsentContext.tsx

@@ -0,0 +1,164 @@
+import React, { createContext, useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+import { ANONYMOUS_CONSENT_RECORD_METHOD, ANONYMOUS_CONSENT_RECORD_PATH } from '@wildo-ai/saas-models/public-runtime';
+import type { ConsentPurpose } from '@wildo-ai/saas-models/public-runtime';
+
+import {
+  readWebsiteVisitorConsent,
+  subscribeWebsiteVisitorConsent,
+  writeWebsiteVisitorConsent,
+  type WebsiteVisitorConsentRecord,
+} from './website-consent-storage';
+
+/**
+ * @wildo_source:part:start saas.website.consent.context facet:layer:core facet:family:website
+ *
+ * `WebsiteConsentContext` — a website visitor's consent state (#534), provided once per page by
+ * `WebsitePageLayout`.
+ *
+ * Consent is a SET of `ConsentPurpose`s, each granted or not on its own. Nothing optional runs until its
+ * purpose is granted: the layout's provider SDKs and scripts read `grantedPurposes`, and so does
+ * `<WebsiteConsentGate purpose={…}>`.
+ *
+ * `purposesInUse` is DERIVED from the live providers (`consentPurposesInUseByProviders`), so the panel asks
+ * about exactly the purposes this site processes and nothing else. A site running no consent-based
+ * provider shows no panel at all.
+ */
+export enum WebsiteConsentStatus {
+  /** The visitor has not decided — or their decision cannot be read. Nothing optional runs. */
+  UNDECIDED = 'undecided',
+  /** The visitor decided; `grantedPurposes` is their answer, possibly empty. */
+  DECIDED = 'decided',
+}
+
+export interface WebsiteConsentContextValue {
+  status: WebsiteConsentStatus;
+  /**
+   * `false` during the server render and the first client render, before storage has been read. A
+   * consent panel must not render while this is false: it would flash for a visitor who already decided,
+   * and differ from the static HTML. Optional behaviour stays off either way.
+   */
+  isResolved: boolean;
+  /** What the visitor granted. Empty while UNDECIDED. */
+  grantedPurposes: readonly ConsentPurpose[];
+  /** When the visitor decided, ISO-8601; absent while UNDECIDED. */
+  decidedAt?: string;
+  /** The purposes this site's live providers rest on — what a consent panel offers. */
+  purposesInUse: readonly ConsentPurpose[];
+  /** Whether the visitor re-opened the panel to change a decision already made. */
+  isSettingsOpen: boolean;
+  /** Whether `purpose` is granted. */
+  hasGranted: (purpose: ConsentPurpose) => boolean;
+  /** Record the WHOLE set the visitor grants — a purpose left out is not granted. Closes the panel. */
+  decide: (grantedPurposes: readonly ConsentPurpose[]) => void;
+  /** Re-open the panel so the visitor can change their decision. */
+  openSettings: () => void;
+  /** Close a re-opened panel without changing anything. */
+  closeSettings: () => void;
+}
+
+export const WebsiteConsentContext: React.Context<WebsiteConsentContextValue | null> = createContext<WebsiteConsentContextValue | null>(null);
+
+/**
+ * The narrow slice of `WebsiteAnonymousSessionClient` this provider needs, declared structurally
+ * rather than imported (#1258).
+ *
+ * Structural because the provider does not want the client's construction concerns — an `apiOrigin`
+ * and the application's own `frontendServiceName`, which only the application knows — and because it
+ * makes the durable write trivially substitutable in a test.
+ */
+export interface WebsiteConsentRecorder {
+  /**
+   * NOT generic, deliberately, though `WebsiteAnonymousSessionClient.requestAnonymous` is: this
+   * provider ignores the response entirely, so a type parameter here would be a promise to the caller
+   * that nothing keeps. The client's generic method satisfies this shape structurally.
+   *
+   * It takes the METHOD rather than being named after one. The consent door is a PUT — its operation
+   * borrows `UPDATE_MANY` — and this interface previously named `postAnonymous`, so every decision a
+   * visitor made 404'd, silently, by this provider's own (correct) design of never telling a visitor
+   * their privacy choice failed. A door's method is part of its address, so it is passed like one.
+   */
+  requestAnonymous(method: string, path: string, body: unknown): Promise<unknown>;
+}
+
+export interface WebsiteConsentProviderProps {
+  purposesInUse: readonly ConsentPurpose[];
+  /**
+   * OPTIONAL. When present, a decision is ALSO recorded server-side against the visitor's anonymous
+   * session, which is what lets it follow them into the account they go on to create (#1258).
+   *
+   * Absent is a first-class answer and is exactly today's behaviour: the decision lives in this
+   * browser and nowhere else. A site with no anonymous-session wiring keeps working, gates the same
+   * way, and simply carries nothing forward.
+   */
+  recorder?: WebsiteConsentRecorder;
+  children: ReactNode;
+}
+
+export function WebsiteConsentProvider({ purposesInUse, recorder, children }: WebsiteConsentProviderProps): ReactNode {
+  const [record, setRecord] = useState<WebsiteVisitorConsentRecord | null>(null);
+  const [isResolved, setIsResolved] = useState(false);
+  const [isSettingsOpen, setIsSettingsOpen] = useState(false);
+
+  // Read after mount, never during render: the static HTML was produced with no storage at all.
+  useEffect(() => {
+    setRecord(readWebsiteVisitorConsent());
+    setIsResolved(true);
+    return subscribeWebsiteVisitorConsent(() => setRecord(readWebsiteVisitorConsent()));
+  }, []);
+
+  const decide = useCallback((grantedPurposes: readonly ConsentPurpose[]): void => {
+    /*
+     * Local storage FIRST, and it is what gates this page (D6). The site is statically built, so a
+     * refusal that only held while an API answered would not hold at all — and the visitor's panel
+     * must close on their click, not on a round trip.
+     */
+    setRecord(writeWebsiteVisitorConsent(grantedPurposes));
+    setIsSettingsOpen(false);
+
+    /*
+     * Then the DURABLE copy, best-effort. This is the one that survives the browser and is carried
+     * onto the account at signup; its failure changes nothing the visitor can see, so it is never
+     * awaited and never surfaced.
+     *
+     * `purposesInUse` is sent as the OFFERED set — what this panel actually put in front of them.
+     * Without it the application could not tell a declined purpose from one this site never asked
+     * about, and would record a decision the visitor never made
+     * (`AnonymousUserPrivacySchema.offeredPurposes`).
+     */
+    if (recorder !== undefined && purposesInUse.length > 0) {
+      void recorder
+        .requestAnonymous(ANONYMOUS_CONSENT_RECORD_METHOD, ANONYMOUS_CONSENT_RECORD_PATH, {
+          grantedPurposes: [...grantedPurposes],
+          offeredPurposes: [...purposesInUse],
+        })
+        .catch(() => {
+          /*
+           * Deliberately silent. The decision HELD — it is in this browser and gating this page. All
+           * that is lost is the carry, and telling a visitor their privacy choice failed when it did
+           * not would be worse than losing it.
+           */
+        });
+    }
+  }, [recorder, purposesInUse]);
+  const openSettings = useCallback((): void => setIsSettingsOpen(true), []);
+  const closeSettings = useCallback((): void => setIsSettingsOpen(false), []);
+
+  const value = useMemo<WebsiteConsentContextValue>(() => {
+    const grantedPurposes = record?.grantedPurposes ?? [];
+    return {
+      status: record === null ? WebsiteConsentStatus.UNDECIDED : WebsiteConsentStatus.DECIDED,
+      isResolved,
+      grantedPurposes,
+      ...(record !== null ? { decidedAt: record.decidedAt } : {}),
+      purposesInUse,
+      isSettingsOpen,
+      hasGranted: (purpose) => grantedPurposes.includes(purpose),
+      decide,
+      openSettings,
+      closeSettings,
+    };
+  }, [record, isResolved, purposesInUse, isSettingsOpen, decide, openSettings, closeSettings]);
+
+  return <WebsiteConsentContext.Provider value={value}>{children}</WebsiteConsentContext.Provider>;
+}
+/** @wildo_source:part:end saas.website.consent.context */

package/src/core/consent/WebsiteConsentGate.tsx

@@ -0,0 +1,34 @@
+import React, { type ReactNode } from 'react';
+import type { ConsentPurpose } from '@wildo-ai/saas-models/public-runtime';
+
+import { useWebsiteConsent } from './useWebsiteConsent';
+
+/**
+ * @wildo_source:part:start saas.website.consent.gate facet:layer:core facet:family:website
+ *
+ * `<WebsiteConsentGate>` — renders its children only when the visitor's consent allows it (#534).
+ *
+ * - **No `purpose`** — the content is ESSENTIAL and always renders. This is the right wrapper for a
+ *   contact form: submitting a form the visitor chose to fill in never depends on optional consent, and the
+ *   form's own opt-ins (marketing) are recorded with the submission, not here.
+ * - **`purpose`** — the content rests on that purpose (an embedded video that tracks, a chat widget, a
+ *   marketing pixel). It renders only once the visitor granted it; until then `fallback` renders — a
+ *   placeholder that says what is withheld and offers `useWebsiteConsent().openSettings()`.
+ *
+ * It renders `fallback` during the server render and before the stored decision is read, so a static page
+ * never ships consent-based content in its HTML.
+ */
+export interface WebsiteConsentGateProps {
+  /** The purpose the children rest on. Omit for essential content. */
+  purpose?: ConsentPurpose;
+  /** Rendered in place of consent-based children until the purpose is granted. Defaults to nothing. */
+  fallback?: ReactNode;
+  children: ReactNode;
+}
+
+export function WebsiteConsentGate({ purpose, fallback = null, children }: WebsiteConsentGateProps): ReactNode {
+  const consent = useWebsiteConsent();
+  if (purpose === undefined) return <>{children}</>;
+  return <>{consent.isResolved && consent.hasGranted(purpose) ? children : fallback}</>;
+}
+/** @wildo_source:part:end saas.website.consent.gate */

package/src/core/consent/useWebsiteConsent.ts

@@ -0,0 +1,18 @@
+import { useContext } from 'react';
+
+import { WebsiteConsentContext, type WebsiteConsentContextValue } from './WebsiteConsentContext';
+
+/**
+ * The visitor's consent state (#534). Read this — never storage, never a cookie — to decide whether
+ * optional behaviour may run.
+ *
+ * Throws outside `WebsitePageLayout`, which provides it: a consumer that silently read "nothing granted"
+ * would look correct and hide a page mounted outside the layout.
+ */
+export function useWebsiteConsent(): WebsiteConsentContextValue {
+  const value = useContext(WebsiteConsentContext);
+  if (value === null) {
+    throw new Error('useWebsiteConsent must be used inside <WebsitePageLayout>, which provides the visitor consent state.');
+  }
+  return value;
+}

package/src/core/consent/website-consent-storage.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import {
+  ConsentPurpose,
+  normalizeConsentPurposes,
+  WEBSITE_VISITOR_CONSENT_STORAGE_KEY,
+} from '@wildo-ai/saas-models/public-runtime';
+
+/**
+ * The ONE place a Wildo website reads or writes a visitor's consent decision (#534).
+ *
+ * Page and section components never touch storage for consent: they read `useWebsiteConsent()`. A second
+ * reader would be a second interpretation of the record — the defect the old `CONSENT_ORDER` was, one
+ * layer down.
+ *
+ * ## Why web storage and not a cookie
+ *
+ * Nothing on the server reads a visitor's consent — the marketing site is static — so a cookie would be
+ * sent on every request for no reader. Web storage stays in the browser. The key is declared in the
+ * engine's cookie table (`ENGINE_CLIENT_STORAGE_ENTRIES`) as strictly necessary: a refusal that is not
+ * remembered does not hold.
+ *
+ * ## Fail closed, never loud
+ *
+ * Storage can be absent (a server render), disabled (a privacy mode) or corrupt (a hand edit). Every one
+ * of those reads as "no decision": the visitor is asked, and nothing optional starts. A corrupt record is
+ * not repaired silently — it is ignored, and the next decision overwrites it.
+ */
+
+/** Stored shape. `schemaVersion` so a future shape change can refuse an old record instead of misreading it. */
+const StoredWebsiteVisitorConsentSchema = z.object({
+  schemaVersion: z.literal(1),
+  /** Strings, not the enum: a purpose later removed from the vocabulary must not invalidate the rest. */
+  grantedPurposes: z.array(z.string()),
+  decidedAt: z.iso.datetime(),
+});
+
+/** A visitor's decision, as the website runtime uses it. */
+export interface WebsiteVisitorConsentRecord {
+  readonly grantedPurposes: readonly ConsentPurpose[];
+  /** When the visitor decided, ISO-8601. Its presence is what separates "declined everything" from "never asked". */
+  readonly decidedAt: string;
+}
+
+/**
+ * Dispatched on `window` after this document writes a decision, so every island on the page updates. The
+ * browser's own `storage` event covers OTHER documents only.
+ */
+export const WEBSITE_CONSENT_CHANGED_EVENT = 'wildo:website-consent-changed';
+
+function browserStorage(): Storage | null {
+  try {
+    return typeof window === 'undefined' ? null : window.localStorage;
+  } catch {
+    // Accessing `localStorage` throws when the browser blocks site data.
+    return null;
+  }
+}
+
+/** The stored decision, or `null` when there is none or it cannot be read. */
+export function readWebsiteVisitorConsent(storage: Storage | null = browserStorage()): WebsiteVisitorConsentRecord | null {
+  if (storage === null) return null;
+  let raw: string | null;
+  try {
+    raw = storage.getItem(WEBSITE_VISITOR_CONSENT_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+  if (raw === null) return null;
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const parsed = StoredWebsiteVisitorConsentSchema.safeParse(json);
+  if (!parsed.success) return null;
+  return { grantedPurposes: normalizeConsentPurposes(parsed.data.grantedPurposes), decidedAt: parsed.data.decidedAt };
+}
+
+/**
+ * Store a decision and tell the page. Returns whether it was stored: when storage is unavailable the
+ * decision still applies for this page, and the visitor is asked again on the next one.
+ */
+export function writeWebsiteVisitorConsent(
+  grantedPurposes: readonly ConsentPurpose[],
+  now: Date = new Date(),
+  storage: Storage | null = browserStorage(),
+): WebsiteVisitorConsentRecord {
+  const record: WebsiteVisitorConsentRecord = { grantedPurposes: normalizeConsentPurposes(grantedPurposes), decidedAt: now.toISOString() };
+  if (storage !== null) {
+    try {
+      storage.setItem(
+        WEBSITE_VISITOR_CONSENT_STORAGE_KEY,
+        JSON.stringify({ schemaVersion: 1, grantedPurposes: record.grantedPurposes, decidedAt: record.decidedAt }),
+      );
+    } catch {
+      // Quota or blocked storage: the decision holds for this page only.
+    }
+  }
+  if (typeof window !== 'undefined') window.dispatchEvent(new CustomEvent(WEBSITE_CONSENT_CHANGED_EVENT));
+  return record;
+}
+
+/** Calls `listener` whenever a decision changes in this document or in another tab. Returns the unsubscribe. */
+export function subscribeWebsiteVisitorConsent(listener: () => void): () => void {
+  if (typeof window === 'undefined') return () => {};
+  const onStorage = (event: StorageEvent): void => {
+    if (event.key === null || event.key === WEBSITE_VISITOR_CONSENT_STORAGE_KEY) listener();
+  };
+  window.addEventListener(WEBSITE_CONSENT_CHANGED_EVENT, listener);
+  window.addEventListener('storage', onStorage);
+  return () => {
+    window.removeEventListener(WEBSITE_CONSENT_CHANGED_EVENT, listener);
+    window.removeEventListener('storage', onStorage);
+  };
+}

package/src/core/contexts/WebsiteRuntimeContext.tsx

@@ -1,4 +1,4 @@
-import React, { createContext, type ReactNode } from 'react';
+import React, { createContext, type ComponentType, type ReactNode } from 'react';
 
 import type { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
 
@@ -152,6 +152,13 @@ export interface WebsiteRuntimeContextValue {
    * catalog for analytics / captcha / browser-monitoring slices.
    */
   frontendProviderRegistry?: FrontendWebsiteProviderRegistry;
+  /**
+   * Replaces the framework's visitor consent panel (#534). Reads `useWebsiteConsent()`; see
+   * `WebsiteConsentBanner` for the three properties a replacement must keep. Absent uses the default.
+   * Closed over by the bridge rather than passed as an island prop, like `navigation`, because a
+   * component cannot cross Astro's serialization boundary.
+   */
+  consentBannerComponent?: ComponentType;
   /**
    * Backend API origin (WITHOUT a trailing slash) that anonymous-capture
    * sections POST to when constructing a `WebsiteAnonymousSessionClient`

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

@@ -40,8 +40,7 @@ export interface CreateFrontendWebsiteProviderRegistryInput {
   readonly entries?: FrontendProvidersBlock;
   /**
    * The CODE channel. Absent is the ordinary case for a website that declares
-   * no package-shipped provider — `wildo config sync` writes no generated file,
-   * so there is nothing to import and nothing to pass.
+   * no providers. Config sync still writes an empty map so startup imports remain stable.
    */
   readonly modules?: GeneratedWebsiteProviderModules;
   readonly onDiagnostic?: (diagnostic: FrontendProviderHydrationDiagnostic) => void;

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

@@ -12,35 +12,58 @@
  * does not exist would throw, and starting a vendor SDK there would run a live
  * analytics client inside a build.
  *
- * SDK activation comes from `@wildo-ai/external-connectors-public/website`, which
- * this package now depends on. The script injector beside it does NOT yet, and
- * that is a timing artifact rather than a decision: it belongs in the same
- * package so the technical doc can use one copy — a second copy of a DOM
- * mutation eventually disagrees about idempotence, which is how a vendor tag
- * gets loaded twice. Moving it needs that package's `dist` to carry it, and no
- * watcher is running in this tree; consolidating it is a one-step follow-up, not
- * a design question.
+ * Both come from `@wildo-ai/external-connectors-public/website`. The script
+ * injector lives there rather than here so the SaaS application, the technical
+ * doc and this site run ONE copy of it: a second copy of a DOM mutation
+ * eventually disagrees about idempotence, which is how a vendor tag gets loaded
+ * twice. It first shipped here alone, and that is how the application came to
+ * declare its Drive Picker's Google API script and never inject it.
+ *
+ * ## Client-side injection, and the alternative that was rejected
+ *
+ * This is an Astro static site, so the "obvious" home for a third-party tag is
+ * the built HTML `<head>`. That was rejected for now: the set of live providers
+ * is per SERVICE and per ENVIRONMENT, resolved from the materialized artifact,
+ * while the built HTML is one artifact shared across deploys of the same build.
+ * Baking the tags in would make the build environment-specific — the same class
+ * of coupling the DATA channel exists to avoid. Injecting from the client keeps
+ * one build correct everywhere, at the cost of the tag arriving after hydration.
+ * Revisit if a provider ever needs to run before first paint.
  */
 
 import { useEffect } from 'react';
 import {
   activateFrontendProviderSdks,
-  type ActivatedFrontendProviderSdks,
-} from '@wildo-ai/external-connectors-public/website';
-import {
   collectDeclaredProviderScripts,
+  consentPurposesRequiredByProvider,
   injectProviderScripts,
-} from './provider-scripts.website';
-import { AppFrontendType } from '@wildo-ai/saas-models/public-runtime';
+  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';
 
+/**
+ * A stable key for a granted-purpose set, so an effect re-runs when the SET changes and not when a new
+ * array with the same members is handed in.
+ */
+function grantedKey(grantedConsentPurposes: readonly ConsentPurpose[]): string {
+  return [...grantedConsentPurposes].sort().join(',');
+}
+
 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.
+   */
+  grantedConsentPurposes: readonly ConsentPurpose[],
 ): void {
+  const key = grantedKey(grantedConsentPurposes);
   useEffect(() => {
     if (typeof document === 'undefined') return;
 
-    const scripts = collectDeclaredProviderScripts(registry);
+    const scripts = collectDeclaredProviderScripts(registry?.modules.values(), grantedConsentPurposes);
     if (scripts.length === 0) return;
 
     injectProviderScripts(scripts, document);
@@ -48,7 +71,8 @@ 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.
-  }, [registry]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed by the granted SET, see grantedKey.
+  }, [registry, key]);
 }
 
 /**
@@ -60,16 +84,46 @@ export function useWebsiteProviderScripts(
  */
 export function useWebsiteProviderSdks(
   registry: FrontendWebsiteProviderRegistry | undefined,
+  /**
+   * The purposes the visitor granted (#534). Providers are activated in TWO groups on purpose: those that
+   * rest on no purpose (error monitoring, captcha) are started once and never restarted by a consent
+   * change, while the consent-based ones start when their purpose is granted and are DEACTIVATED when it
+   * 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);
+}
+
+function useProviderSdkGroup(
+  registry: FrontendWebsiteProviderRegistry | undefined,
+  consentBased: boolean,
+  grantedConsentPurposes: readonly ConsentPurpose[],
 ): void {
+  // 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
+    ? []
+    : [...registry.modules.values()]
+      .filter((module) => (consentPurposesRequiredByProvider(module).length > 0) === consentBased)
+      .flatMap((module) => consentPurposesRequiredByProvider(module))
+      .filter((purpose) => grantedConsentPurposes.includes(purpose));
+  const key = grantedKey(relevant);
   useEffect(() => {
     if (registry === undefined) return;
+    const modules = [...registry.modules.values()].filter(
+      (module) => (consentPurposesRequiredByProvider(module).length > 0) === consentBased,
+    );
+    if (modules.length === 0) return;
 
     let unmounted = false;
     let activated: ActivatedFrontendProviderSdks | undefined;
 
     void activateFrontendProviderSdks({
       surface: AppFrontendType.STATIC_WEBSITE,
-      modules: registry.modules.values(),
+      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.
@@ -88,5 +142,6 @@ export function useWebsiteProviderSdks(
       unmounted = true;
       void activated?.deactivateAll();
     };
-  }, [registry]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed by the granted SET, see grantedKey.
+  }, [registry, consentBased, key]);
 }

package/src/core/layouts/WebsitePageLayout.tsx

@@ -1,5 +1,6 @@
 import React, { useMemo, type ReactNode } from 'react';
 import { BUILTIN_PROVIDER_CAPABILITY } from '@wildo-ai/saas-models/public-runtime';
+import { consentPurposesInUseByProviders } from '@wildo-ai/external-connectors-public/website';
 
 import { WebsitePageContextProvider } from '../contexts/WebsitePageContext';
 import {
@@ -9,6 +10,9 @@ import {
 import type { WebsitePageContextValue } from '../contexts/WebsitePageContext';
 import { useWebsiteRuntime } from '../contexts/useWebsiteRuntime';
 import { useWebsiteLabelByKey } from '../hooks/useWebsiteLabel';
+import { WebsiteConsentProvider, WebsiteConsentStatus, type WebsiteConsentRecorder } from '../consent/WebsiteConsentContext';
+import { useWebsiteConsent } from '../consent/useWebsiteConsent';
+import { WebsiteConsentBanner, WebsiteConsentSettingsButton } from '../consent/WebsiteConsentBanner';
 import {
   WebsitePageRefSchema,
   type WebsitePageRef,
@@ -133,6 +137,14 @@ const SKIP_LINK_FOCUS_CSS = `
  *      captcha so non-React tooling can detect the configured vendor
  *      without reverse-engineering app code.
  *
+ *   4. **Provides the visitor's consent state and enforces it** (#534) —
+ *      mounts `WebsiteConsentProvider`, starts a provider SDK or script only
+ *      once the purpose it rests on is granted (and stops the SDK when it is
+ *      withdrawn), and renders the consent panel when the site runs a
+ *      consent-based provider and the visitor has not decided. Here rather
+ *      than in each bridge because every page — including every blog post —
+ *      renders through this layout, so no page can be mounted without it.
+ *
  * **Why semantic `<header>` / `<main>` / `<footer>` elements**:
  * marketing-site SEO scoring penalizes pages that ship a single
  * unstructured `<div>` tree. Using semantic landmarks costs nothing
@@ -178,6 +190,17 @@ export interface WebsitePageLayoutProps {
    * vertical-rhythm overrides on long-scroll landing pages.
    */
   mainClassName?: string;
+  /**
+   * OPTIONAL anonymous-session client. When supplied, a visitor's consent decision is ALSO recorded
+   * server-side against their session, which is what lets it follow them into the account they go on
+   * to create (#1258). Pass the SAME instance the page's capture sections use, so one `uuidRef`
+   * carries the decision, the lead and the draft note together.
+   *
+   * Absent keeps today's behaviour exactly: the decision lives in this browser and nowhere else.
+   * The engine cannot construct the client here — it needs the application's own
+   * `frontendServiceName` — which is why it arrives as a prop rather than off the runtime context.
+   */
+  consentRecorder?: WebsiteConsentRecorder;
   /**
    * The page's section composition. Typically a sequence of
    * `<WebsiteSection>` wrappers around concrete section components.
@@ -185,7 +208,21 @@ export interface WebsitePageLayoutProps {
   children: ReactNode;
 }
 
-export function WebsitePageLayout({
+export function WebsitePageLayout(props: WebsitePageLayoutProps): ReactNode {
+  const runtime = useWebsiteRuntime();
+  // Derived from the LIVE providers, so the panel asks about exactly what this site processes.
+  const purposesInUse = useMemo(
+    () => consentPurposesInUseByProviders(runtime.frontendProviderRegistry?.modules.values()),
+    [runtime.frontendProviderRegistry],
+  );
+  return (
+    <WebsiteConsentProvider purposesInUse={purposesInUse} recorder={props.consentRecorder}>
+      <WebsitePageLayoutContent {...props} />
+    </WebsiteConsentProvider>
+  );
+}
+
+function WebsitePageLayoutContent({
   pageRef,
   header,
   footer,
@@ -194,6 +231,7 @@ export function WebsitePageLayout({
   children,
 }: WebsitePageLayoutProps): ReactNode {
   const runtime = useWebsiteRuntime();
+  const consent = useWebsiteConsent();
 
   /**
    * Defensive parse: callers should pass a `WebsitePageManifest.ref`
@@ -240,8 +278,11 @@ export function WebsitePageLayout({
   // resolved provider refs and stamped them into the attributes below and
   // stopped there — a provider could be declared, enabled and hydrated without
   // anything of it ever running.
-  useWebsiteProviderScripts(runtime.frontendProviderRegistry);
-  useWebsiteProviderSdks(runtime.frontendProviderRegistry);
+  //
+  // 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);
 
   const providerRootAttributes = useMemo<Record<string, string>>(() => {
     const attrs: Record<string, string> = {};
@@ -314,9 +355,31 @@ export function WebsitePageLayout({
           {children}
         </main>
         {resolvedFooter !== null ? <footer>{resolvedFooter}</footer> : null}
+        {renderConsentSurface(consent, runtime.consentBannerComponent)}
       </div>
     </WebsitePageContextProvider>
   );
 }
 WebsitePageLayout.displayName = 'WebsitePageLayout';
+
+/**
+ * The panel while a decision is owed (or re-opened), the reopen button once one is made, and nothing at
+ * all on a site whose live providers rest on no consent. Nothing renders before the stored decision is
+ * read, so a visitor who already decided never sees the panel flash.
+ */
+function renderConsentSurface(
+  consent: ReturnType<typeof useWebsiteConsent>,
+  BannerOverride: React.ComponentType | undefined,
+): ReactNode {
+  if (!consent.isResolved || consent.purposesInUse.length === 0) return null;
+  if (consent.status === WebsiteConsentStatus.UNDECIDED || consent.isSettingsOpen) {
+    const Banner = BannerOverride ?? WebsiteConsentBanner;
+    return <Banner />;
+  }
+  return (
+    <div data-website-consent-settings="">
+      <WebsiteConsentSettingsButton />
+    </div>
+  );
+}
 /** @wildo_source:part:end saas.website.page-layout.component */

package/src/index.ts

@@ -95,6 +95,7 @@
 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/sections/website-section-category.shared';
 export * from './schemas/sections/website-section-definition.shared.schemas';
 export * from './schemas/structured-data/website-structured-data.shared.schemas';
@@ -118,6 +119,12 @@ export * from './core/factories/define-website-page-manifest';
 export * from './core/layouts/WebsitePageLayout';
 export * from './core/layouts/WebsiteSection';
 
+export * from './core/consent/website-consent-storage';
+export * from './core/consent/WebsiteConsentContext';
+export * from './core/consent/useWebsiteConsent';
+export * from './core/consent/WebsiteConsentGate';
+export * from './core/consent/WebsiteConsentBanner';
+
 export * from './core/anonymous-session/website-anonymous-session-client';
 export * from './core/anonymous-session/inbound-contact-form.schema';
 export * from './core/anonymous-session/InboundContactForm';