@wildo-ai/saas-website 1.1.4 → 1.1.6

package/src/core/anonymous-session/__tests__/InboundContactForm.submission-challenge.test.tsx

@@ -0,0 +1,139 @@
+/**
+ * #1735 — the contact form answers the application's submission challenge.
+ *
+ * The client is a double (it records what the form sent and answers like the engine); the challenge helper, the
+ * proof-of-work solver and the refusal detection are the real ones.
+ */
+import React from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import {
+  ProofOfWorkAlgorithm,
+  SUBMISSION_CHALLENGE_PROOF_OF_WORK_PATH,
+  SubmissionChallengeAction,
+  SubmissionChallengeRefusalCode,
+  SubmissionChallengeResponseKind,
+  WildoHeaderKeys,
+  hashProofOfWorkCandidate,
+  type ProofOfWorkChallenge,
+} from '@wildo-ai/saas-models/public-runtime';
+
+import { InboundContactForm, type InboundContactFormLabels } from '../InboundContactForm';
+import { WebsiteAnonymousRequestError, type WebsiteAnonymousSessionClient } from '../website-anonymous-session-client';
+import type { WebsiteSubmissionChallengeSource } from '../website-submission-challenge';
+
+afterEach(() => { cleanup(); });
+
+/** Every label, as the section passes them (#1986: all are required). */
+const LABELS: InboundContactFormLabels = {
+  emailLabel: 'email-label',
+  firstNameLabel: 'first-name-label',
+  lastNameLabel: 'last-name-label',
+  phoneLabel: 'phone-label',
+  marketingConsentLabel: 'marketing-consent-label',
+  submitLabel: 'submit-label',
+  submittingLabel: 'submitting-label',
+  successMessage: 'success-label',
+  errorMessage: 'error-label',
+  challengeRefusedMessage: 'refused-label',
+  invalidEmailMessage: 'invalid-email-label',
+};
+
+async function smallChallenge(): Promise<ProofOfWorkChallenge> {
+  const salt = `${'a'.repeat(24)}?expires=9999999999`;
+  return { algorithm: ProofOfWorkAlgorithm.SHA_256, salt, challenge: await hashProofOfWorkCandidate(salt, 7), maxNumber: 20, signature: 'b'.repeat(64) };
+}
+
+function refusal(code: SubmissionChallengeRefusalCode): WebsiteAnonymousRequestError {
+  return new WebsiteAnonymousRequestError(400, JSON.stringify({ error: { type: 'VALIDATION', code } }));
+}
+
+function clientDouble(answers: Array<'ok' | WebsiteAnonymousRequestError>) {
+  const posts: Array<Record<string, string> | undefined> = [];
+  const gets: string[] = [];
+  const client = {
+    postAnonymous: vi.fn(async (_path: string, _body: unknown, headers?: Record<string, string>) => {
+      posts.push(headers);
+      const next = answers.shift() ?? 'ok';
+      if (next !== 'ok') throw next;
+      return {};
+    }),
+    getPublic: vi.fn(async (path: string) => {
+      gets.push(path);
+      return smallChallenge();
+    }),
+  } as unknown as WebsiteAnonymousSessionClient;
+  return { client, posts, gets };
+}
+
+function submit(): void {
+  fireEvent.change(screen.getByRole('textbox', { name: /email/i }), { target: { value: 'visitor@example.test' } });
+  fireEvent.click(screen.getByRole('button', { name: LABELS.submitLabel }));
+}
+
+const answerIn = (headers: Record<string, string> | undefined) => JSON.parse(headers?.[WildoHeaderKeys.SUBMISSION_CHALLENGE_RESPONSE] ?? 'null');
+
+describe('InboundContactForm — the submission challenge (#1735)', () => {
+  it('sends no answer on a site that declares no captcha', async () => {
+    const { client, posts, gets } = clientDouble(['ok']);
+    render(<InboundContactForm client={client} challengeSource={{ captchaDeclared: false }} labels={LABELS} />);
+    submit();
+    await waitFor(() => expect(screen.getByRole('status')).toBeInTheDocument());
+    expect(posts).toEqual([undefined]);
+    expect(gets).toEqual([]);
+  });
+
+  it('sends the RUNNING vendor\'s token for this form\'s action', async () => {
+    const { client, posts } = clientDouble(['ok']);
+    const execute = vi.fn(async () => 'vendor-token');
+    const source: WebsiteSubmissionChallengeSource = { captchaDeclared: true, runningCaptcha: { providerRef: 'recaptcha', sink: { execute } } };
+    render(<InboundContactForm client={client} challengeSource={source} labels={LABELS} />);
+    submit();
+    await waitFor(() => expect(screen.getByRole('status')).toBeInTheDocument());
+    expect(execute).toHaveBeenCalledWith(SubmissionChallengeAction.INBOUND_CONTACT);
+    expect(answerIn(posts[0])).toEqual({ kind: SubmissionChallengeResponseKind.PROVIDER_TOKEN, providerRef: 'recaptcha', token: 'vendor-token' });
+  });
+
+  it('solves the proof of work when the captcha is declared but not running (no consent)', async () => {
+    const { client, posts, gets } = clientDouble(['ok']);
+    render(<InboundContactForm client={client} challengeSource={{ captchaDeclared: true }} labels={LABELS} />);
+    submit();
+    await waitFor(() => expect(screen.getByRole('status')).toBeInTheDocument());
+    expect(gets).toEqual([SUBMISSION_CHALLENGE_PROOF_OF_WORK_PATH]);
+    expect(answerIn(posts[0])).toMatchObject({ kind: SubmissionChallengeResponseKind.PROOF_OF_WORK, number: 7 });
+  });
+
+  it('answers a refused vendor token ONCE more with the proof of work', async () => {
+    const { client, posts } = clientDouble([refusal(SubmissionChallengeRefusalCode.REFUSED), 'ok']);
+    const source: WebsiteSubmissionChallengeSource = { captchaDeclared: true, runningCaptcha: { providerRef: 'recaptcha', sink: { execute: async () => 'low-score' } } };
+    render(<InboundContactForm client={client} challengeSource={source} labels={LABELS} />);
+    submit();
+    await waitFor(() => expect(screen.getByRole('status')).toBeInTheDocument());
+    expect(posts.map((headers) => answerIn(headers).kind)).toEqual([SubmissionChallengeResponseKind.PROVIDER_TOKEN, SubmissionChallengeResponseKind.PROOF_OF_WORK]);
+  });
+
+  it('answers a site that did not know the backend protects the form (REQUIRED) with the proof of work', async () => {
+    const { client, posts } = clientDouble([refusal(SubmissionChallengeRefusalCode.REQUIRED), 'ok']);
+    render(<InboundContactForm client={client} challengeSource={{ captchaDeclared: false }} labels={LABELS} />);
+    submit();
+    await waitFor(() => expect(screen.getByRole('status')).toBeInTheDocument());
+    expect(posts[0]).toBeUndefined();
+    expect(answerIn(posts[1])).toMatchObject({ kind: SubmissionChallengeResponseKind.PROOF_OF_WORK });
+  });
+
+  it('shows the challenge refusal, in its own words, when the proof of work is refused too', async () => {
+    const { client } = clientDouble([refusal(SubmissionChallengeRefusalCode.REFUSED), refusal(SubmissionChallengeRefusalCode.REFUSED)]);
+    render(<InboundContactForm client={client} challengeSource={{ captchaDeclared: true }} labels={LABELS} />);
+    submit();
+    expect(await screen.findByRole('alert')).toHaveTextContent('refused-label');
+  });
+
+  it('does not retry any other failure', async () => {
+    const { client, posts } = clientDouble([new WebsiteAnonymousRequestError(500, '{}')]);
+    render(<InboundContactForm client={client} challengeSource={{ captchaDeclared: false }} labels={LABELS} />);
+    submit();
+    expect(await screen.findByRole('alert')).toHaveTextContent('error-label');
+    expect(posts).toHaveLength(1);
+  });
+});

package/src/core/anonymous-session/__tests__/inbound-contact-form.schema.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from "vitest";
 
+import { ConsentPurpose } from "@wildo-ai/saas-models/public-runtime";
+
 import { InboundContactFormSchema, buildInboundContactCreateBody, type InboundContactFormValues } from "../inbound-contact-form.schema";
 
 /**
@@ -36,9 +38,14 @@ describe("buildInboundContactCreateBody — no synthetic legal receipt", () => {
     expect(buildInboundContactCreateBody(values).email).toBe("lead@example.com");
   });
 
-  it("maps the OPTIONAL marketing opt-in to the dataProcessingConsent tier", () => {
-    const tier = (v: InboundContactFormValues): string => (buildInboundContactCreateBody(v).privacy as { dataProcessingConsent: string }).dataProcessingConsent;
-    expect(tier({ ...values, marketingConsent: true })).toBe("marketing");
-    expect(tier({ ...values, marketingConsent: false })).toBe("basic");
+  it("maps the OPTIONAL marketing opt-in to the consented purpose SET — nothing granted when unticked", () => {
+    const purposes = (v: InboundContactFormValues): unknown => (buildInboundContactCreateBody(v).privacy as { consentedPurposes: unknown }).consentedPurposes;
+    expect(purposes({ ...values, marketingConsent: true })).toEqual([ConsentPurpose.MARKETING]);
+    expect(purposes({ ...values, marketingConsent: false })).toEqual([]);
+  });
+
+  it("records that the visitor decided, either way — the server re-stamps the instant", () => {
+    const privacy = buildInboundContactCreateBody(values).privacy as { consentDecidedAt?: string };
+    expect(typeof privacy.consentDecidedAt).toBe("string");
   });
 });

package/src/core/anonymous-session/inbound-contact-form.schema.ts

@@ -11,8 +11,8 @@
  *
  * Mirrors the non-excluded, non-backend-only CREATE inputs of `InboundContact`
  * (`email` required; `firstName` / `lastName` / `phone` optional), plus ONE privacy
- * signal: an OPTIONAL marketing opt-in (mapped to the `privacy.dataProcessingConsent`
- * tier). There is no second, required agreement field: a governed notice, contract or
+ * signal: an OPTIONAL marketing opt-in (mapped to the `privacy.consentedPurposes` set).
+ * There is no second, required agreement field: a governed notice, contract or
  * consent interaction must use the separate exact-release receipt contract, because this
  * DTO cannot manufacture legal evidence from a checkbox and a client timestamp.
  * `relatedUserId` is intentionally absent — it is `.excludeFromCreate()` on the
@@ -21,22 +21,37 @@
 
 import { z } from "zod";
 
+import { ConsentPurpose } from "@wildo-ai/saas-models/public-runtime";
+
+/**
+ * Length ceilings of the optional text fields. Exported so the form puts the SAME numbers on its inputs as
+ * `maxLength`: the browser then stops a visitor at the ceiling, and a length failure is not something the form ever
+ * has to word (#1986).
+ */
+export const INBOUND_CONTACT_NAME_MAX_LENGTH = 200;
+export const INBOUND_CONTACT_PHONE_MAX_LENGTH = 64;
+
 /**
  * The wire payload POSTed to `/api/v1/inbound-contacts`. `privacy` matches the
  * resource's `InboundContactPrivacySchema` shape (a nested consent object) so the
  * backend accepts it verbatim.
+ *
+ * No issue carries a message (#1986). A visitor reads the application's own words, which the form takes from its
+ * section's label pack (`InboundContactFormLabels.invalidEmailMessage`); a message written here would be English in
+ * every locale, and nobody authoring the pack could find it.
  */
 export const InboundContactFormSchema = z.object({
   // Zod 4: top-level `z.email()` (not the deprecated `z.string().email()`), matching
   // the resource schema. An empty string fails it, so it also covers "required".
-  email: z.email("Enter a valid email address"),
-  firstName: z.string().trim().max(200).optional(),
-  lastName: z.string().trim().max(200).optional(),
-  phone: z.string().trim().max(64).optional(),
+  email: z.email(),
+  firstName: z.string().trim().max(INBOUND_CONTACT_NAME_MAX_LENGTH).optional(),
+  lastName: z.string().trim().max(INBOUND_CONTACT_NAME_MAX_LENGTH).optional(),
+  phone: z.string().trim().max(INBOUND_CONTACT_PHONE_MAX_LENGTH).optional(),
   /**
-   * OPTIONAL marketing opt-in — maps into the resource's `privacy.dataProcessingConsent`
-   * tier ('marketing' vs the BASIC default). It is the only privacy field on this form,
-   * and it gates nothing: an unchecked box still submits, at the BASIC tier.
+   * OPTIONAL marketing opt-in — maps into the resource's `privacy.consentedPurposes` set.
+   * It is the only privacy field on this form, and it gates nothing: sending the form is the
+   * essential act and never depends on optional consent, so an unchecked box still submits,
+   * granting nothing.
    */
   marketingConsent: z.boolean().default(false),
 });
@@ -45,7 +60,7 @@ export type InboundContactFormValues = z.infer<typeof InboundContactFormSchema>;
 
 /**
  * Build the exact JSON body the backend CREATE expects from validated form values.
- * Keeps the `privacy` nesting + the consent enum mapping in ONE place so the form
+ * Keeps the `privacy` nesting + the consent purpose mapping in ONE place so the form
  * component stays declarative.
  */
 export function buildInboundContactCreateBody(values: InboundContactFormValues): Record<string, unknown> {
@@ -55,9 +70,11 @@ export function buildInboundContactCreateBody(values: InboundContactFormValues):
     ...(values.lastName ? { lastName: values.lastName } : {}),
     ...(values.phone ? { phone: values.phone } : {}),
     privacy: {
-      // OPTIONAL marketing tier: 'marketing' when the visitor opted in, else the
-      // resource's BASIC default.
-      dataProcessingConsent: values.marketingConsent ? "marketing" : "basic",
+      // The visitor SAW the opt-in and submitted, so this is a decision either way (#534): the set
+      // they granted — MARKETING or nothing — plus a CLAIM that they decided now. The backend's
+      // CREATE prefix replaces the instant with its own clock; a browser clock is never recorded.
+      consentedPurposes: values.marketingConsent ? [ConsentPurpose.MARKETING] : [],
+      consentDecidedAt: new Date().toISOString(),
     },
   };
 }

package/src/core/anonymous-session/website-anonymous-session-client.ts

@@ -58,6 +58,19 @@ export class WebsiteAnonymousRequestError extends Error {
     super(`Anonymous request failed with status ${status}`);
     this.name = 'WebsiteAnonymousRequestError';
   }
+
+  /**
+   * The refusal's stable `error.code` — what a client branches on (the engine hoists an error's `context.code` there) —
+   * or `undefined` when the body is not the engine's error envelope or carries no code.
+   */
+  get errorCode(): string | undefined {
+    try {
+      const code = (JSON.parse(this.bodyText) as { error?: { code?: unknown } }).error?.code;
+      return typeof code === 'string' ? code : undefined;
+    } catch {
+      return undefined;
+    }
+  }
 }
 
 export class WebsiteAnonymousSessionClient {
@@ -108,12 +121,48 @@ export class WebsiteAnonymousSessionClient {
    * service-name headers, captures any returned session token, and returns the parsed
    * JSON response. Throws `WebsiteAnonymousRequestError` on a non-2xx status.
    */
-  async postAnonymous<TResponse = unknown>(path: string, body: unknown): Promise<TResponse> {
+  async postAnonymous<TResponse = unknown>(path: string, body: unknown, extraHeaders?: Readonly<Record<string, string>>): Promise<TResponse> {
+    return this.requestAnonymous<TResponse>('POST', path, body, extraHeaders);
+  }
+
+  /**
+   * GET a PUBLIC endpoint — one that needs no session (a proof-of-work challenge, #1735). Starts no anonymous session
+   * and sends no session header or cookie: asking for a challenge must not mint an identity for the visitor.
+   */
+  async getPublic<TResponse = unknown>(path: string): Promise<TResponse> {
+    const response = await fetch(`${this.apiBaseUrl}${path}`, {
+      method: 'GET',
+      headers: { [WildoHeaderKeys.FRONTEND_SERVICE_NAME]: this.frontendServiceName },
+      credentials: 'omit',
+    });
+    if (!response.ok) {
+      throw new WebsiteAnonymousRequestError(response.status, await safeReadText(response));
+    }
+    return (await response.json()) as TResponse;
+  }
+
+  /**
+   * Send `body` to an anonymous endpoint with an explicit METHOD.
+   *
+   * `postAnonymous` above is the POST case and delegates here. This exists because not every anonymous
+   * door is a POST and the method is not guessable from the path: the visitor consent door declares
+   * `resourceOperationLike: UPDATE_MANY`, which the engine maps to PUT, so a POST to it answers 404 —
+   * and this client's one silent caller swallowed exactly that. A caller reads the door's method from
+   * the same place it reads the path (`ANONYMOUS_CONSENT_RECORD_METHOD` beside
+   * `ANONYMOUS_CONSENT_RECORD_PATH`) rather than inferring it from a method name.
+   */
+  async requestAnonymous<TResponse = unknown>(
+    method: string,
+    path: string,
+    body: unknown,
+    /** Request-specific headers, such as a public form's challenge answer (#1735). Never overrides the session headers. */
+    extraHeaders?: Readonly<Record<string, string>>,
+  ): Promise<TResponse> {
     this.ensureSessionStarted();
 
     const response = await fetch(`${this.apiBaseUrl}${path}`, {
-      method: 'POST',
-      headers: this.buildHeaders(),
+      method,
+      headers: { ...extraHeaders, ...this.buildHeaders() },
       body: JSON.stringify(body),
       // Carry the parent-domain `__wildo_anon_session` cookie to the API so the
       // session is continuous across the apex/app/api origins.

package/src/core/anonymous-session/website-submission-challenge.ts

@@ -0,0 +1,99 @@
+/**
+ * The answer a public website form sends with its submission when the application protects it with a captcha (#1735), to
+ * any operation that declares a submission challenge (#1985).
+ *
+ * Two answers, one header (`x-submission-challenge-response`), chosen in the visitor's browser:
+ *
+ * - the consented captcha vendor's TOKEN, when its browser part is running on the page (it starts only once the
+ *   visitor grants the purpose the vendor rests on — Google reCAPTCHA rests on ANALYTICS);
+ * - otherwise the engine's PROOF OF WORK: a challenge fetched from the backend and solved here. Consent-exempt —
+ *   nothing is stored in the browser and nothing reaches a third party — so a visitor who declined still submits.
+ *
+ * The backend requires one of the two whenever it declares a captcha provider, and refuses a submission with neither.
+ * A site that declares none sends nothing. A refused vendor token is retried ONCE with the proof of work (a low score or
+ * an unreachable vendor must not lock a real person out); see {@link isSubmissionChallengeRefusal}.
+ */
+import { useContext, useMemo } from 'react';
+import {
+  BUILTIN_PROVIDER_CAPABILITY,
+  SUBMISSION_CHALLENGE_PROOF_OF_WORK_PATH,
+  SubmissionChallengeRefusalCode,
+  SubmissionChallengeResponseKind,
+  encodeSubmissionChallengeResponse,
+  isFrontendCaptchaSink,
+  solveProofOfWorkChallenge,
+  type FrontendCaptchaSink,
+  type ProofOfWorkChallenge,
+} from '@wildo-ai/saas-models/public-runtime';
+
+import { WebsiteRuntimeContext } from '../contexts/WebsiteRuntimeContext';
+import { useWebsiteProviderSdkActivations } from '../external-providers/website-provider-sdk-activations';
+import { WebsiteAnonymousRequestError, type WebsiteAnonymousSessionClient } from './website-anonymous-session-client';
+
+/** @wildo_source:part:start saas.website.submission-challenge facet:layer:frontend facet:audience:app-developer */
+/** What a form knows about the page's captcha when it submits. */
+export interface WebsiteSubmissionChallengeSource {
+  /** This website declares a captcha provider, so its public forms answer a challenge. */
+  readonly captchaDeclared: boolean;
+  /** The captcha vendor RUNNING on the page — present only once the visitor consented and it started. */
+  readonly runningCaptcha?: { readonly providerRef: string; readonly sink: FrontendCaptchaSink };
+}
+
+/** The challenge source of the current page: its declared captcha provider and, if started, its running client. */
+export function useWebsiteSubmissionChallengeSource(): WebsiteSubmissionChallengeSource {
+  // Read without `useWebsiteRuntime`'s throw: a form rendered outside a page (a test, a storybook) simply has no captcha.
+  const runtime = useContext(WebsiteRuntimeContext);
+  const running = useWebsiteProviderSdkActivations();
+  const captchaDeclared = runtime?.frontendProviderRegistry?.findProviderByProviderCapability(BUILTIN_PROVIDER_CAPABILITY.FRONTEND_CAPTCHA) !== undefined;
+  return useMemo(() => {
+    const captcha = running.find((entry) => entry.providerCapabilities.includes(BUILTIN_PROVIDER_CAPABILITY.FRONTEND_CAPTCHA)
+      && isFrontendCaptchaSink(entry.activation.handle));
+    return {
+      captchaDeclared,
+      ...(captcha === undefined ? {} : { runningCaptcha: { providerRef: captcha.providerRef, sink: captcha.activation.handle as FrontendCaptchaSink } }),
+    };
+  }, [captchaDeclared, running]);
+}
+
+/**
+ * The encoded answer to send, or `undefined` when this site asks for none. `proofOfWorkOnly` skips the vendor (the
+ * retry after a refused token). Throws only when the proof-of-work challenge cannot be fetched or solved; the caller
+ * then shows its ordinary failure and does not submit unanswered (`InboundContactForm` shows its `errorMessage`).
+ */
+export async function obtainSubmissionChallengeAnswer(params: {
+  readonly source: WebsiteSubmissionChallengeSource;
+  /**
+   * The action the operation the form posts to DECLARES in its `submissionChallenge` (#1985): the engine's
+   * `SubmissionChallengeAction.INBOUND_CONTACT` for `/inbound-contacts`, your own action for your own operation. A token
+   * minted for any other action is refused.
+   */
+  readonly action: string;
+  readonly client: Pick<WebsiteAnonymousSessionClient, 'getPublic'>;
+  readonly proofOfWorkOnly?: boolean;
+  readonly signal?: AbortSignal;
+}): Promise<string | undefined> {
+  const { source, action, client, proofOfWorkOnly = false, signal } = params;
+  if (!proofOfWorkOnly && source.runningCaptcha !== undefined) {
+    const token = await source.runningCaptcha.sink.execute(action);
+    if (token !== undefined) {
+      return encodeSubmissionChallengeResponse({
+        kind: SubmissionChallengeResponseKind.PROVIDER_TOKEN,
+        providerRef: source.runningCaptcha.providerRef,
+        token,
+      });
+    }
+  }
+  if (!source.captchaDeclared && !proofOfWorkOnly) return undefined;
+  const challenge = await client.getPublic<ProofOfWorkChallenge>(SUBMISSION_CHALLENGE_PROOF_OF_WORK_PATH);
+  const answer = await solveProofOfWorkChallenge(challenge, { signal });
+  if (answer === undefined) throw new Error('The proof-of-work challenge could not be solved.');
+  return encodeSubmissionChallengeResponse(answer);
+}
+
+/** Whether a failed submission was refused at its challenge — the one refusal a form answers again, with the proof of work. */
+export function isSubmissionChallengeRefusal(error: unknown): boolean {
+  if (!(error instanceof WebsiteAnonymousRequestError)) return false;
+  const code = error.errorCode;
+  return code === SubmissionChallengeRefusalCode.REQUIRED || code === SubmissionChallengeRefusalCode.REFUSED;
+}
+/** @wildo_source:part:end saas.website.submission-challenge */

package/src/core/consent/WebsiteConsentBanner.tsx

@@ -0,0 +1,223 @@
+import React, { useEffect, useId, useState, type ReactNode } from 'react';
+import type { ConsentPurpose } from '@wildo-ai/saas-models/public-runtime';
+
+import { websiteDesignTokenCssVar } from '../../schemas/design-tokens/website-design-tokens.shared.schemas';
+import { useWebsiteLabelByKey } from '../hooks/useWebsiteLabel';
+import { WebsiteConsentStatus } from './WebsiteConsentContext';
+import { useWebsiteConsent } from './useWebsiteConsent';
+import {
+  WebsiteConsentLabelSlot,
+  websiteConsentLabelKey,
+  websiteConsentPurposeDescriptionLabelKey,
+  websiteConsentPurposeLabelKey,
+} from '../../schemas/label-keys/website-consent-label-keys.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.consent.banner facet:layer:core facet:family:website
+ *
+ * `WebsiteConsentBanner` — the framework's default visitor consent panel (#534).
+ *
+ * Rendered by `WebsitePageLayout` when the site runs a consent-based provider and the visitor has not
+ * decided, or re-opened the panel. A site replaces it by passing `consentBannerComponent` to its bridge
+ * island; a replacement reads `useWebsiteConsent()` exactly as this one does and must keep its three
+ * properties:
+ *
+ * 1. **No box is pre-ticked.** A pre-ticked box is not a choice.
+ * 2. **Declining is as easy as accepting**, and is RECORDED — so the panel does not return on every page.
+ * 3. **Only purposes in use are offered** (`purposesInUse`), each named by its label.
+ *
+ * Styled only through the site's `--website-*` design tokens, like the skip link, so it needs no
+ * stylesheet and cannot be shadowed by a utility class.
+ */
+function useWebsiteConsentSlotLabel(slot: WebsiteConsentLabelSlot): string {
+  return useWebsiteLabelByKey(websiteConsentLabelKey(slot));
+}
+
+/**
+ * Every row has the SAME shape: the control, then the name on its line, then the explanation beneath
+ * the NAME rather than beneath the control — a two-column grid, so the second line starts where the
+ * first line's words do and the row stays scannable.
+ *
+ * That includes the row that cannot be changed, which carries a real checkbox, CHECKED and DISABLED,
+ * rather than a text status. A person scanning the panel reads DOWN the column of controls, and a row
+ * whose control is missing does not read as "cannot be changed" — it reads as a row that was
+ * forgotten. A checked, disabled box says it in the vocabulary the rest of the list already uses, and
+ * a screen reader announces "checked, unavailable" without any extra words.
+ */
+const ROW_STYLE: React.CSSProperties = {
+  display: 'grid',
+  gridTemplateColumns: 'auto 1fr',
+  columnGap: '0.625rem',
+  alignItems: 'center',
+  padding: '0.5rem 0.75rem',
+  borderBottom: `1px solid ${websiteDesignTokenCssVar('colors', 'border', '#ccc')}`,
+};
+
+const ROW_DESCRIPTION_STYLE: React.CSSProperties = { margin: 0, gridColumn: 2, fontSize: '0.75rem', opacity: 0.8 };
+
+/** Slightly larger than a default box: this is the one control the whole panel exists to offer. */
+const ROW_CONTROL_STYLE: React.CSSProperties = { width: '1.15rem', height: '1.15rem' };
+
+/**
+ * One purpose: its NAME, what agreeing to it MEANS for this visitor, and the control.
+ *
+ * The explanation is the half that was missing. A tick box labelled "Analytics" is a category, not
+ * something a visitor can weigh, and consent is only valid if it is informed — which is why every
+ * specialized consent platform pairs the two and why the label key is derived from the vocabulary,
+ * so a purpose can never arrive with a name and no explanation.
+ */
+function PurposeChoice({ purpose, checked, onChange }: { purpose: ConsentPurpose; checked: boolean; onChange: (checked: boolean) => void }): ReactNode {
+  const label = useWebsiteLabelByKey(websiteConsentPurposeLabelKey(purpose));
+  const description = useWebsiteLabelByKey(websiteConsentPurposeDescriptionLabelKey(purpose));
+  return (
+    <label data-website-consent-purpose={purpose} style={{ ...ROW_STYLE, cursor: 'pointer' }}>
+      <input type="checkbox" checked={checked} style={ROW_CONTROL_STYLE} onChange={(event) => onChange(event.target.checked)} />
+      <span style={{ fontWeight: 600 }}>{label}</span>
+      <span style={ROW_DESCRIPTION_STYLE}>{description}</span>
+    </label>
+  );
+}
+
+const BUTTON_STYLE: React.CSSProperties = {
+  padding: '0.5rem 1rem',
+  borderRadius: websiteDesignTokenCssVar('radii', 'md', '0.375rem'),
+  border: `1px solid ${websiteDesignTokenCssVar('colors', 'border', '#ccc')}`,
+  background: websiteDesignTokenCssVar('colors', 'background', '#fff'),
+  color: websiteDesignTokenCssVar('colors', 'foreground', '#000'),
+  cursor: 'pointer',
+};
+
+export function WebsiteConsentBanner(): ReactNode {
+  const consent = useWebsiteConsent();
+  const headingId = useId();
+  const [selected, setSelected] = useState<readonly ConsentPurpose[]>(consent.grantedPurposes);
+  // Re-seed from the stored decision each time the panel is re-opened, so it shows what is in force.
+  useEffect(() => setSelected(consent.grantedPurposes), [consent.grantedPurposes, consent.isSettingsOpen]);
+
+  const title = useWebsiteConsentSlotLabel(WebsiteConsentLabelSlot.TITLE);
+  const description = useWebsiteConsentSlotLabel(WebsiteConsentLabelSlot.DESCRIPTION);
+  const acceptAll = useWebsiteConsentSlotLabel(WebsiteConsentLabelSlot.ACCEPT_ALL);
+  const declineAll = useWebsiteConsentSlotLabel(WebsiteConsentLabelSlot.DECLINE_ALL);
+  const save = useWebsiteConsentSlotLabel(WebsiteConsentLabelSlot.SAVE);
+  const essentialTitle = useWebsiteConsentSlotLabel(WebsiteConsentLabelSlot.ESSENTIAL_TITLE);
+  const essentialDescription = useWebsiteConsentSlotLabel(WebsiteConsentLabelSlot.ESSENTIAL_DESCRIPTION);
+
+  const offered = consent.purposesInUse;
+  // Purposes the panel does not offer keep their stored grant; offered ones are granted exactly when ticked.
+  const choose = (chosen: readonly ConsentPurpose[]): void =>
+    consent.decide([...consent.grantedPurposes.filter((purpose) => !offered.includes(purpose)), ...chosen]);
+
+  return (
+    <section
+      role="region"
+      aria-labelledby={headingId}
+      data-website-consent-banner={consent.status === WebsiteConsentStatus.UNDECIDED ? 'undecided' : 'settings'}
+      style={{
+        /*
+         * BOTTOM-RIGHT CORNER, and the three properties together are what make that work on a phone
+         * too. `left` and `right` both bound the box to the viewport with a gutter; `maxWidth` caps it
+         * on a wide screen; `marginLeft: auto` pushes the remaining slack to the left so the box hugs
+         * the right edge. On a narrow screen the gutters bind before the cap does and it simply spans
+         * the width — a corner popup that overflowed a phone would be worse than a bar.
+         *
+         * Inline styles, not a media query: this ships into a static marketing page with no stylesheet
+         * of its own, which is the same constraint that keeps the rest of this file inline.
+         */
+        position: 'fixed',
+        left: '1rem',
+        right: '1rem',
+        bottom: '1rem',
+        zIndex: 9000,
+        maxWidth: '30rem',
+        marginLeft: 'auto',
+        /*
+         * The panel never exceeds the viewport, and its ACTIONS are never what gets cut off: the rows
+         * scroll inside `maxHeight`, the buttons sit outside that box. A panel that grows with its
+         * content pushes accept and reject off the bottom of a short screen — and a refusal that
+         * cannot be reached is a refusal that was not offered, whatever the markup says. `dvh` rather
+         * than `vh` because a mobile browser's toolbars make `vh` taller than the visible page.
+         */
+        maxHeight: '85dvh',
+        padding: '0.875rem 1rem',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '0.625rem',
+        background: websiteDesignTokenCssVar('colors', 'surface', '#fff'),
+        color: websiteDesignTokenCssVar('colors', 'surfaceForeground', '#000'),
+        border: `1px solid ${websiteDesignTokenCssVar('colors', 'border', '#ccc')}`,
+        borderRadius: websiteDesignTokenCssVar('radii', 'lg', '0.5rem'),
+      }}
+    >
+      <h2 id={headingId} style={{ margin: 0, fontSize: '1.125rem' }}>{title}</h2>
+      <p style={{ margin: 0 }}>{description}</p>
+      {/* `data-website-consent-rows` is the scroll box's own hook. A test anchoring on a style
+          substring instead matched the ROW (whose grid template also contains "auto") and asserted
+          nothing — the same vacuous pin the app tier already had to repair. */}
+      <div
+        data-website-consent-rows=""
+        style={{ minHeight: 0, flex: 1, overflowY: 'auto', border: `1px solid ${websiteDesignTokenCssVar('colors', 'border', '#ccc')}`, borderRadius: websiteDesignTokenCssVar('radii', 'md', '0.375rem') }}
+      >
+        {/*
+          * The always-active row, first, carrying a CHECKED and DISABLED box. It is not a purpose the
+          * visitor decides — which is exactly why it is stated: a panel listing only the optional
+          * purposes leaves them unable to see what is happening on the site at all, which is the
+          * question they opened it to answer.
+          *
+          * It carried a text status instead until 2026-09-20, on the argument that a disabled control
+          * invites a click that cannot work. The reversal: a visitor scans DOWN the column of boxes,
+          * and a gap there does not read as "cannot be changed", it reads as a row that was
+          * forgotten. A disabled box says it in the vocabulary the rest of the list already uses.
+          */}
+        <div data-website-consent-essential="" style={ROW_STYLE}>
+          {/*
+            * `aria-label`, because this row is a `div` rather than a `<label>` — nothing else names
+            * the control, and a checkbox with no accessible name is announced as an unlabelled
+            * checkbox. Its own note claimed AT would announce "checked, unavailable"; it announced
+            * no words at all.
+            *
+            * `readOnly` is gone: it is inert on a checkbox per HTML, and leaving it invites a later
+            * reader to delete `disabled` believing the lock survives.
+            */}
+          <input type="checkbox" checked disabled aria-label={essentialTitle} style={ROW_CONTROL_STYLE} />
+          <span style={{ fontWeight: 600 }}>{essentialTitle}</span>
+          <span style={ROW_DESCRIPTION_STYLE}>{essentialDescription}</span>
+        </div>
+        {offered.map((purpose) => (
+          <PurposeChoice
+            key={purpose}
+            purpose={purpose}
+            checked={selected.includes(purpose)}
+            onChange={(checked) => setSelected((current) => (checked ? [...current.filter((entry) => entry !== purpose), purpose] : current.filter((entry) => entry !== purpose)))}
+          />
+        ))}
+      </div>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5rem', justifyContent: 'flex-end' }}>
+        <button type="button" style={BUTTON_STYLE} onClick={() => choose([])}>{declineAll}</button>
+        {/*
+          * SAVE appears only when a MIXED choice exists to save — two or more purposes in use.
+          *
+          * With one purpose the button is unanswerable: "decline all" and "accept all" already cover
+          * the whole space, so a third action beside them describes nothing a visitor can picture and
+          * reads as a question rather than an answer. Derived from the offered set, so a site that
+          * adds a second purpose gets the control with no edit here.
+          */}
+        {offered.length > 1 && (
+          <button type="button" style={BUTTON_STYLE} onClick={() => choose(selected.filter((purpose) => offered.includes(purpose)))}>{save}</button>
+        )}
+        <button type="button" style={BUTTON_STYLE} onClick={() => choose(offered)}>{acceptAll}</button>
+      </div>
+    </section>
+  );
+}
+
+/** The reopen affordance: always reachable once a visitor decided, so every choice can be changed. */
+export function WebsiteConsentSettingsButton(): ReactNode {
+  const consent = useWebsiteConsent();
+  const manage = useWebsiteConsentSlotLabel(WebsiteConsentLabelSlot.MANAGE);
+  return (
+    <button type="button" data-website-consent-manage="" style={BUTTON_STYLE} onClick={consent.openSettings}>
+      {manage}
+    </button>
+  );
+}
+/** @wildo_source:part:end saas.website.consent.banner */