@wildo-ai/saas-website 1.1.3 → 1.1.5

package/src/core/__tests__/website-consent.test.tsx

@@ -0,0 +1,311 @@
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import {
+  ANONYMOUS_CONSENT_RECORD_METHOD,
+  ANONYMOUS_CONSENT_RECORD_PATH,
+  AvailableLanguage,
+  BUILTIN_PROVIDER_CAPABILITY,
+  ConsentPurpose,
+  defineProviderMetadata,
+  ProviderOriginKind,
+  ProviderTier,
+  WEBSITE_VISITOR_CONSENT_STORAGE_KEY,
+} from '@wildo-ai/saas-models/public-runtime';
+
+import { WebsitePageLayout } from '../layouts/WebsitePageLayout';
+import { WebsiteRuntimeContextProvider, type WebsiteRuntimeContextValue } from '../contexts/WebsiteRuntimeContext';
+import { WebsiteConsentGate } from '../consent/WebsiteConsentGate';
+import { readWebsiteVisitorConsent, writeWebsiteVisitorConsent } from '../consent/website-consent-storage';
+import { WebsiteLabelKeySchema } from '../../schemas/label-keys/website-label-key.schemas';
+import {
+  WEBSITE_CONSENT_LABEL_KEYS,
+  WebsiteConsentLabelSlot,
+  websiteConsentLabelKey,
+  websiteConsentPurposeDescriptionLabelKey,
+  websiteConsentPurposeLabelKey,
+} from '../../schemas/label-keys/website-consent-label-keys.schemas';
+import type { FrontendWebsiteProviderRegistry } from '../external-providers/frontend-provider-registry.website';
+
+/**
+ * The visitor tier of the consent gate (#534), through the real layout.
+ *
+ * What this pins is the property the whole feature exists for: an analytics SDK the site declares does
+ * NOT start until the visitor grants ANALYTICS, starts when they do, and is STOPPED when they withdraw —
+ * while a provider resting on no consent (error monitoring) starts regardless and is never restarted.
+ */
+
+const SKIP_KEY = WebsiteLabelKeySchema.parse('website.chrome.layout.skip-to-main-content');
+// Every consent key resolves to itself, so buttons are found by the key they render.
+const LABEL_PACK = Object.fromEntries([SKIP_KEY, ...WEBSITE_CONSENT_LABEL_KEYS].map((key) => [key as unknown as string, key as unknown as string]));
+const label = (slot: WebsiteConsentLabelSlot): string => websiteConsentLabelKey(slot) as unknown as string;
+
+function registryOf(modules: Record<string, unknown>[]): FrontendWebsiteProviderRegistry {
+  const map = new Map(modules.map((module) => [(module.metadata as { ref: string }).ref, module]));
+  return {
+    modules: map,
+    getProviderByRef: (ref: string) => map.get(ref),
+    getProvidersByProviderCapability: () => [],
+    findProviderByProviderCapability: () => undefined,
+  } as unknown as FrontendWebsiteProviderRegistry;
+}
+
+function provider(ref: string, capability: string, activate: ReturnType<typeof vi.fn>): Record<string, unknown> {
+  return {
+    metadata: defineProviderMetadata({ ref, packageName: '@test/providers', tier: ProviderTier.EXTENSION, origin: { kind: ProviderOriginKind.APPLICATION } }),
+    providerCapabilities: [capability],
+    protocols: ['FRONTEND_SDK'],
+    sdk: { descriptor: { packageName: `@vendor/${ref}` }, activate },
+  };
+}
+
+function renderSite(registry: FrontendWebsiteProviderRegistry | undefined, children: React.ReactNode = <p>page</p>, consentRecorder?: { requestAnonymous: (method: string, path: string, body: unknown) => Promise<unknown> }): void {
+  const runtime: WebsiteRuntimeContextValue = {
+    locale: AvailableLanguage.EN,
+    defaultLocale: AvailableLanguage.EN,
+    labelPack: LABEL_PACK,
+    designTokens: {
+      colors: {
+        background: '#fff', foreground: '#000', primary: '#000', primaryForeground: '#fff', accent: '#000', accentForeground: '#fff',
+        surface: '#fff', surfaceForeground: '#000', border: '#ccc', muted: '#eee', mutedForeground: '#666',
+      },
+      radii: { none: '0', sm: '2px', md: '4px', lg: '8px', xl: '12px', full: '9999px' },
+    },
+    navigation: { headerComponent: () => null, footerComponent: () => null },
+    skipToMainContentLabelKey: SKIP_KEY,
+    ...(registry ? { frontendProviderRegistry: registry } : {}),
+  };
+  render(
+    <WebsiteRuntimeContextProvider value={runtime}>
+      <WebsitePageLayout pageRef="landing" {...(consentRecorder ? { consentRecorder } : {})}>{children}</WebsitePageLayout>
+    </WebsiteRuntimeContextProvider>,
+  );
+}
+
+beforeEach(() => window.localStorage.clear());
+afterEach(cleanup);
+
+describe('website consent storage', () => {
+  it('reads nothing when nothing, or nothing valid, is stored', () => {
+    expect(readWebsiteVisitorConsent()).toBeNull();
+    window.localStorage.setItem(WEBSITE_VISITOR_CONSENT_STORAGE_KEY, '{not json');
+    expect(readWebsiteVisitorConsent()).toBeNull();
+    window.localStorage.setItem(WEBSITE_VISITOR_CONSENT_STORAGE_KEY, JSON.stringify({ schemaVersion: 2, grantedPurposes: ['analytics'], decidedAt: new Date().toISOString() }));
+    expect(readWebsiteVisitorConsent()).toBeNull();
+  });
+
+  it('round-trips a decision as a normalized SET, dropping purposes the vocabulary no longer has', () => {
+    const decidedAt = new Date('2026-09-13T08:00:00.000Z');
+    writeWebsiteVisitorConsent([ConsentPurpose.MARKETING, ConsentPurpose.ANALYTICS], decidedAt);
+    expect(readWebsiteVisitorConsent()).toEqual({ grantedPurposes: [ConsentPurpose.ANALYTICS, ConsentPurpose.MARKETING], decidedAt: decidedAt.toISOString() });
+
+    window.localStorage.setItem(WEBSITE_VISITOR_CONSENT_STORAGE_KEY, JSON.stringify({ schemaVersion: 1, grantedPurposes: ['analytics', 'retired'], decidedAt: decidedAt.toISOString() }));
+    expect(readWebsiteVisitorConsent()?.grantedPurposes).toEqual([ConsentPurpose.ANALYTICS]);
+  });
+
+  it('keeps an EMPTY decision distinct from no decision — declining is a recorded answer', () => {
+    writeWebsiteVisitorConsent([]);
+    expect(readWebsiteVisitorConsent()?.grantedPurposes).toEqual([]);
+  });
+
+  it('still returns the decision when storage refuses the write', () => {
+    const refusing = { getItem: () => null, setItem: () => { throw new Error('quota'); } } as unknown as Storage;
+    expect(writeWebsiteVisitorConsent([ConsentPurpose.ANALYTICS], new Date(), refusing).grantedPurposes).toEqual([ConsentPurpose.ANALYTICS]);
+  });
+});
+
+describe('WebsitePageLayout enforces visitor consent on provider SDKs', () => {
+  it('starts error monitoring at once, withholds analytics until ACCEPT, and stops analytics on withdrawal', async () => {
+    const analyticsDeactivate = vi.fn();
+    const analyticsActivate = vi.fn().mockResolvedValue({ handle: 'posthog', deactivate: analyticsDeactivate });
+    const monitoringActivate = vi.fn().mockResolvedValue({ handle: 'sentry' });
+    renderSite(registryOf([
+      provider('posthog', BUILTIN_PROVIDER_CAPABILITY.FRONTEND_PRODUCT_ANALYTICS, analyticsActivate),
+      provider('sentry', BUILTIN_PROVIDER_CAPABILITY.FRONTEND_ERROR_MONITORING, monitoringActivate),
+    ]));
+
+    await waitFor(() => expect(monitoringActivate).toHaveBeenCalledTimes(1));
+    // The panel asks, and nothing optional has started.
+    expect(await screen.findByRole('region', { name: label(WebsiteConsentLabelSlot.TITLE) })).toBeInTheDocument();
+    // The OPTIONAL box, reached through the row's own `data-website-consent-purpose` hook — the
+    // always-active row carries a checkbox too (checked, disabled), so an unqualified role query
+    // would now match two, and the accessible name is the row's title AND its explanation.
+    expect(document.querySelector<HTMLInputElement>('[data-website-consent-purpose="analytics"] input')).not.toBeChecked();
+    expect(analyticsActivate).not.toHaveBeenCalled();
+
+    await act(async () => { fireEvent.click(screen.getByRole('button', { name: label(WebsiteConsentLabelSlot.ACCEPT_ALL) })); });
+    await waitFor(() => expect(analyticsActivate).toHaveBeenCalledTimes(1));
+    expect(readWebsiteVisitorConsent()?.grantedPurposes).toEqual([ConsentPurpose.ANALYTICS]);
+    expect(screen.queryByRole('region', { name: label(WebsiteConsentLabelSlot.TITLE) })).toBeNull();
+
+    // Withdraw through the always-reachable reopen button.
+    fireEvent.click(screen.getByRole('button', { name: label(WebsiteConsentLabelSlot.MANAGE) }));
+    await act(async () => { fireEvent.click(screen.getByRole('button', { name: label(WebsiteConsentLabelSlot.DECLINE_ALL) })); });
+    await waitFor(() => expect(analyticsDeactivate).toHaveBeenCalledTimes(1));
+    expect(readWebsiteVisitorConsent()?.grantedPurposes).toEqual([]);
+    // Error monitoring was never restarted by any of it.
+    expect(monitoringActivate).toHaveBeenCalledTimes(1);
+  });
+
+  it('honours a stored refusal: no panel, no analytics, and a way to change it', async () => {
+    writeWebsiteVisitorConsent([]);
+    const analyticsActivate = vi.fn().mockResolvedValue({ handle: 'posthog' });
+    renderSite(registryOf([provider('posthog', BUILTIN_PROVIDER_CAPABILITY.FRONTEND_PRODUCT_ANALYTICS, analyticsActivate)]));
+
+    expect(await screen.findByRole('button', { name: label(WebsiteConsentLabelSlot.MANAGE) })).toBeInTheDocument();
+    expect(screen.queryByRole('region', { name: label(WebsiteConsentLabelSlot.TITLE) })).toBeNull();
+    expect(analyticsActivate).not.toHaveBeenCalled();
+  });
+
+  it('shows no consent surface at all on a site whose providers rest on no consent', async () => {
+    const monitoringActivate = vi.fn().mockResolvedValue({ handle: 'sentry' });
+    renderSite(registryOf([provider('sentry', BUILTIN_PROVIDER_CAPABILITY.FRONTEND_ERROR_MONITORING, monitoringActivate)]));
+    await waitFor(() => expect(monitoringActivate).toHaveBeenCalledTimes(1));
+    expect(screen.queryByRole('region')).toBeNull();
+    expect(screen.queryByRole('button', { name: label(WebsiteConsentLabelSlot.MANAGE) })).toBeNull();
+  });
+});
+
+/**
+ * #1258 — what a visitor can actually SEE in the panel.
+ *
+ * The banner showed a tick box labelled "Analytics" and nothing else. That is a category, not
+ * something a visitor can weigh, and consent is only valid if it is INFORMED — so the panel was
+ * asking for a decision it had not given anybody the means to make. A marketing-site consent panel
+ * is also the surface with the tightest constraints anywhere in the product: it must state what runs
+ * regardless, explain each choice, and never push its own refusal below the fold.
+ */
+describe('the visitor panel shows the WHOLE picture, not only the tick boxes', () => {
+  const analytics = () => provider('posthog', BUILTIN_PROVIDER_CAPABILITY.FRONTEND_PRODUCT_ANALYTICS, vi.fn().mockResolvedValue({ handle: 'posthog' }));
+
+  it('explains each purpose, states what is always active, and keeps the actions out of the scroll box', async () => {
+    renderSite(registryOf([analytics()]), <p>page</p>);
+
+    // Each offered purpose carries its explanation, not only its name.
+    expect(await screen.findByText(websiteConsentPurposeLabelKey(ConsentPurpose.ANALYTICS) as unknown as string)).toBeInTheDocument();
+    expect(screen.getByText(websiteConsentPurposeDescriptionLabelKey(ConsentPurpose.ANALYTICS) as unknown as string)).toBeInTheDocument();
+
+    /*
+     * The always-active row is STATED, and carries a real control — checked and disabled. A row with
+     * no control does not read as "cannot be changed": a visitor scans DOWN the column of boxes, and
+     * a gap there reads as a row that was forgotten. The disabled assertion is also what holds the
+     * line that this is not a purpose — the moment the box is operable, the panel is offering a
+     * choice about processing that has none.
+     */
+    expect(screen.getByText(label(WebsiteConsentLabelSlot.ESSENTIAL_TITLE))).toBeInTheDocument();
+    const boxes = screen.getAllByRole('checkbox');
+    // The COUNT first: a destructure of the first two cannot see a third row appearing, and the order
+    // it depends on would be unstated. One always-active row, one purpose in use.
+    expect(boxes).toHaveLength(2);
+    const [essentialBox, analyticsBox] = boxes;
+    expect(essentialBox).toBeChecked();
+    expect(essentialBox).toBeDisabled();
+    expect(analyticsBox).not.toBeChecked();
+    expect(analyticsBox).toBeEnabled();
+
+    /*
+     * And no SAVE: with one purpose in use, decline-all and accept-all already cover the whole space,
+     * so a third button could only repeat them — which is exactly the confusion it caused.
+     */
+    expect(screen.queryByRole('button', { name: label(WebsiteConsentLabelSlot.SAVE) })).toBeNull();
+
+    /*
+     * The rows scroll; the panel does not grow. 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. Asserting the ACCEPT button is outside the scroll box is what catches a
+     * "simplification" that puts the whole panel in one scroller.
+     */
+    const panel = screen.getByRole('region');
+    expect(panel.style.maxHeight).toBe('85dvh');
+    /*
+     * Anchored on the scroll box's OWN hook. `closest('div[style*="auto"]')` matched the essential
+     * ROW — its grid template is `auto 1fr` — so it resolved to a box that is not the scroller and
+     * both following assertions passed for free, including with the scroller deleted.
+     */
+    const scrollBox = document.querySelector('[data-website-consent-rows]');
+    expect(scrollBox, 'the purpose rows must sit in their own scroll box').not.toBeNull();
+    // …and it must actually SCROLL. Containment alone holds for a plain div, so deleting the
+    // overflow — the change that puts the rows' height back onto the panel — would pass without this.
+    expect((scrollBox as HTMLElement).style.overflowY).toBe('auto');
+    expect(scrollBox!.contains(screen.getByText(label(WebsiteConsentLabelSlot.ESSENTIAL_TITLE))), 'the rows must be INSIDE it').toBe(true);
+    expect(scrollBox!.contains(screen.getByRole('button', { name: label(WebsiteConsentLabelSlot.ACCEPT_ALL) })), 'the actions must not').toBe(false);
+  });
+});
+
+describe('WebsiteConsentGate', () => {
+  it('always renders essential content, and consent-based content only once its purpose is granted', async () => {
+    renderSite(undefined, (
+      <>
+        <WebsiteConsentGate><form aria-label="contact" /></WebsiteConsentGate>
+        <WebsiteConsentGate purpose={ConsentPurpose.MARKETING} fallback={<p>withheld</p>}><p>pixel</p></WebsiteConsentGate>
+      </>
+    ));
+    expect(screen.getByRole('form', { name: 'contact' })).toBeInTheDocument();
+    expect(await screen.findByText('withheld')).toBeInTheDocument();
+    expect(screen.queryByText('pixel')).toBeNull();
+
+    await act(async () => { writeWebsiteVisitorConsent([ConsentPurpose.MARKETING]); });
+    expect(await screen.findByText('pixel')).toBeInTheDocument();
+  });
+});
+
+/**
+ * #1258 Step 1c — the visitor's decision reaching the server, so it can follow them to an account.
+ *
+ * What these pin is the pair of properties the carry depends on: the decision is recorded with the
+ * set that was actually OFFERED (without which the application cannot tell a decline from a
+ * never-asked), and the local decision is never hostage to that request succeeding.
+ */
+describe('a visitor decision is recorded server-side when the site wires a recorder', () => {
+  const analytics = () => provider('posthog', BUILTIN_PROVIDER_CAPABILITY.FRONTEND_PRODUCT_ANALYTICS, vi.fn().mockResolvedValue({ handle: 'posthog' }));
+
+  it('posts the granted set AND the offered set to the anonymous consent route', async () => {
+    const requestAnonymous = vi.fn().mockResolvedValue({});
+    renderSite(registryOf([analytics()]), <p>page</p>, { requestAnonymous });
+
+    await act(async () => { fireEvent.click(await screen.findByRole('button', { name: label(WebsiteConsentLabelSlot.ACCEPT_ALL) })); });
+
+    await waitFor(() => expect(requestAnonymous).toHaveBeenCalledTimes(1));
+    const [method, path, body] = requestAnonymous.mock.calls[0] as [string, string, { grantedPurposes: string[]; offeredPurposes: string[] }];
+    // PUT, not POST. The door's operation borrows UPDATE_MANY; sending POST answered 404, and this
+    // provider's failure path is deliberately silent, so nothing surfaced it (#1258 Step 1d).
+    expect(method).toBe(ANONYMOUS_CONSENT_RECORD_METHOD);
+    expect(path).toBe(ANONYMOUS_CONSENT_RECORD_PATH);
+    expect(body.grantedPurposes).toEqual([ConsentPurpose.ANALYTICS]);
+    // The OFFERED set is what this panel actually showed — derived from the site's live providers,
+    // which is why it can differ from what the application would ask.
+    expect(body.offeredPurposes).toEqual([ConsentPurpose.ANALYTICS]);
+  });
+
+  it('records a DECLINE too — an empty grant is a decision and must carry as one', async () => {
+    const requestAnonymous = vi.fn().mockResolvedValue({});
+    renderSite(registryOf([analytics()]), <p>page</p>, { requestAnonymous });
+
+    await act(async () => { fireEvent.click(await screen.findByRole('button', { name: label(WebsiteConsentLabelSlot.DECLINE_ALL) })); });
+
+    await waitFor(() => expect(requestAnonymous).toHaveBeenCalledTimes(1));
+    const [, , body] = requestAnonymous.mock.calls[0] as [string, string, { grantedPurposes: string[]; offeredPurposes: string[] }];
+    expect(body.grantedPurposes).toEqual([]);
+    expect(body.offeredPurposes).toEqual([ConsentPurpose.ANALYTICS]);
+  });
+
+  it('holds the decision locally even when the server write fails, and tells the visitor nothing', async () => {
+    const requestAnonymous = vi.fn().mockRejectedValue(new Error('offline'));
+    renderSite(registryOf([analytics()]), <p>page</p>, { requestAnonymous });
+
+    await act(async () => { fireEvent.click(await screen.findByRole('button', { name: label(WebsiteConsentLabelSlot.ACCEPT_ALL) })); });
+
+    // The decision HELD: stored, panel closed. Losing the carry must never look like losing the choice.
+    await waitFor(() => expect(readWebsiteVisitorConsent()?.grantedPurposes).toEqual([ConsentPurpose.ANALYTICS]));
+    expect(screen.queryByRole('region', { name: label(WebsiteConsentLabelSlot.TITLE) })).toBeNull();
+  });
+
+  it('posts nothing at all when the site wires no recorder — the pre-#1258 behaviour, unchanged', async () => {
+    renderSite(registryOf([analytics()]));
+
+    await act(async () => { fireEvent.click(await screen.findByRole('button', { name: label(WebsiteConsentLabelSlot.ACCEPT_ALL) })); });
+
+    expect(readWebsiteVisitorConsent()?.grantedPurposes).toEqual([ConsentPurpose.ANALYTICS]);
+  });
+});

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,6 +21,8 @@
 
 import { z } from "zod";
 
+import { ConsentPurpose } from "@wildo-ai/saas-models/public-runtime";
+
 /**
  * The wire payload POSTed to `/api/v1/inbound-contacts`. `privacy` matches the
  * resource's `InboundContactPrivacySchema` shape (a nested consent object) so the
@@ -34,9 +36,10 @@ export const InboundContactFormSchema = z.object({
   lastName: z.string().trim().max(200).optional(),
   phone: z.string().trim().max(64).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 +48,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 +58,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

@@ -109,10 +109,24 @@ export class WebsiteAnonymousSessionClient {
    * JSON response. Throws `WebsiteAnonymousRequestError` on a non-2xx status.
    */
   async postAnonymous<TResponse = unknown>(path: string, body: unknown): Promise<TResponse> {
+    return this.requestAnonymous<TResponse>('POST', path, body);
+  }
+
+  /**
+   * 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): Promise<TResponse> {
     this.ensureSessionStarted();
 
     const response = await fetch(`${this.apiBaseUrl}${path}`, {
-      method: 'POST',
+      method,
       headers: this.buildHeaders(),
       body: JSON.stringify(body),
       // Carry the parent-domain `__wildo_anon_session` cookie to the API so the

package/src/core/consent/WebsiteConsentBanner.tsx

@@ -0,0 +1,222 @@
+import React, { useEffect, useId, useState, type ReactNode } from 'react';
+import type { ConsentPurpose } from '@wildo-ai/saas-models/public-runtime';
+
+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 var(--website-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: 'var(--website-radii-md, 0.375rem)',
+  border: '1px solid var(--website-colors-border, #ccc)',
+  background: 'var(--website-colors-background, #fff)',
+  color: 'var(--website-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: 'var(--website-colors-surface, #fff)',
+        color: 'var(--website-colors-surface-foreground, #000)',
+        border: '1px solid var(--website-colors-border, #ccc)',
+        borderRadius: 'var(--website-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 var(--website-colors-border, #ccc)', borderRadius: 'var(--website-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 */