@wildo-ai/saas-website 1.1.4 → 1.1.6

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,9 +1,10 @@
-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';
+import type { AvailableLanguage, PublicPricingCatalog } from '@wildo-ai/saas-models/public-runtime';
 
 import type { WebsiteDesignTokens } from '../../schemas/design-tokens/website-design-tokens.shared.schemas';
 import type { FrontendWebsiteProviderRegistry } from '../external-providers/frontend-provider-registry.website';
+import type { WebsiteProviderComponentRegistry } from '../external-providers/provider-component-registry.website';
 import type { WebsiteLabelKey } from '../../schemas/label-keys/website-label-key.schemas';
 import type { WebsiteNavigationConfig } from '../../schemas/manifests/website-root-config.shared.schemas';
 import type { LabelPack } from '../../schemas/validators/label-pack.validator';
@@ -12,10 +13,10 @@ import type { LabelPack } from '../../schemas/validators/label-pack.validator';
  * @wildo_source:part:start saas.website.runtime.context facet:layer:core facet:family:website
  *
  * `WebsiteRuntimeContext` — site-wide runtime state for the marketing
- * surface. Created **once per page render** by the host adapter
- * (Phase 5 `WebsitePageBridge.astro` reads `WebsiteRootConfig` and the
- * resolved label pack from disk and calls
- * `<WebsiteRuntimeContextProvider value={…}>` around the page tree).
+ * surface. Created **once per page render** by the host adapter: the
+ * page's `.astro` frontmatter loads the site context and the resolved label
+ * pack, and its bridge island (`createWebsitePageBridgeIsland`) calls
+ * `<WebsiteRuntimeContextProvider value={…}>` around the page tree.
  *
  * **Why "runtime" and not "config"**: the values here are the
  * locale-resolved subset of `WebsiteRootConfig` — only the active
@@ -152,6 +153,21 @@ export interface WebsiteRuntimeContextValue {
    * catalog for analytics / captcha / browser-monitoring slices.
    */
   frontendProviderRegistry?: FrontendWebsiteProviderRegistry;
+  /**
+   * Components the live providers contribute, keyed `capability:providerRef` (#1703) — the same
+   * registry the application builds, from the same `components` declaration. Built by the page bridge
+   * once per island from `frontendProviderRegistry`; read through `useWebsiteProviderComponent` and
+   * rendered by `WebsiteProviderComponent`. Optional for the same reason as the registry above: a
+   * provider-free site, or a test runtime, has none, and every slot then renders nothing.
+   */
+  providerComponentRegistry?: WebsiteProviderComponentRegistry;
+  /**
+   * 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`
@@ -166,6 +182,17 @@ export interface WebsiteRuntimeContextValue {
    * silently failing to submit.
    */
   apiOrigin?: string;
+  /**
+   * The application's public pricing catalogue (#1835), derived at build time from the billing
+   * catalogue the backend sells from — so a pricing section states the prices the application
+   * actually charges instead of a hand copy of them. Node-loaded
+   * (`loadWebsitePricingCatalog` on `/config-loader`) and carried as an island prop for the
+   * reason `appOrigin` above is. Read it with `useWebsitePricingCatalog()`.
+   *
+   * Optional because only pricing pages need it; a section that reads it on a page that did not
+   * pass it fails loudly rather than rendering no plans.
+   */
+  pricingCatalog?: PublicPricingCatalog;
 }
 
 /**

package/src/core/contexts/useWebsiteRuntime.ts

@@ -1,5 +1,7 @@
 import { useContext } from 'react';
 
+import type { PublicPricingCatalog } from '@wildo-ai/saas-models/public-runtime';
+
 import {
   WebsiteRuntimeContext,
   type WebsiteRuntimeContextValue,
@@ -25,10 +27,39 @@ export function useWebsiteRuntime(): WebsiteRuntimeContextValue {
   if (value === null) {
     throw new Error(
       '[useWebsiteRuntime] must be called inside <WebsiteRuntimeContextProvider>. ' +
-        'In Astro pages this is provided by `WebsitePageBridge.astro` — make sure ' +
-        'your page imports the bridge instead of rendering React components directly.',
+        'In Astro pages this is provided by the page\'s bridge island (`createWebsitePageBridgeIsland` ' +
+        'from @wildo-ai/saas-website/astro-island) — make sure the page renders its bridge instead of ' +
+        'rendering React components directly.',
     );
   }
   return value;
 }
 /** @wildo_source:part:end saas.website.use-runtime.hook */
+
+/**
+ * @wildo_source:part:start saas.website.use-pricing-catalog.hook facet:layer:core facet:family:website facet:audience:app-developer
+ *
+ * `useWebsitePricingCatalog()` — the application's public pricing catalogue, for a pricing section.
+ *
+ * The plans, their prices, which one is recommended, how much of each price may be stated, and which
+ * are announced but not yet on sale — all derived at build time from the billing catalogue the
+ * backend sells from. A pricing section renders from THIS and never keeps its own copy of a price:
+ * a copy is a price that will disagree with the one the application charges.
+ *
+ * Throws when the page did not pass the catalogue to its bridge island: a pricing section with no
+ * plans would silently state that the application sells nothing. The page's `.astro` frontmatter
+ * loads it with `loadWebsitePricingCatalog()` from `@wildo-ai/saas-website/config-loader` and passes
+ * it as the island's `pricingCatalog` prop.
+ */
+export function useWebsitePricingCatalog(): PublicPricingCatalog {
+  const { pricingCatalog } = useWebsiteRuntime();
+  if (pricingCatalog === undefined) {
+    throw new Error(
+      '[useWebsitePricingCatalog] this page did not pass a pricing catalogue to its bridge island. In the page\'s '
+        + '`.astro` frontmatter, load it with `await loadWebsitePricingCatalog()` (the @wildo-ai/saas-website/config-loader '
+        + 'subpath) and pass `pricingCatalog={pricingCatalog}` to the island.',
+    );
+  }
+  return pricingCatalog;
+}
+/** @wildo_source:part:end saas.website.use-pricing-catalog.hook */

package/src/core/external-providers/WebsiteProviderComponent.tsx

@@ -0,0 +1,153 @@
+import React, { type ReactNode } from 'react';
+import { ProviderComponentStatus } from '@wildo-ai/external-connectors-public/website';
+import type { ConsentPurpose, ProviderCapability } from '@wildo-ai/saas-models/public-runtime';
+
+import { websiteDesignTokenCssVar } from '../../schemas/design-tokens/website-design-tokens.shared.schemas';
+import {
+  WebsiteConsentLabelSlot,
+  websiteConsentLabelKey,
+  websiteConsentPurposeLabelKey,
+} from '../../schemas/label-keys/website-consent-label-keys.schemas';
+import {
+  WebsiteProviderComponentLabelSlot,
+  websiteProviderComponentLabelKey,
+} from '../../schemas/label-keys/website-provider-component-label-keys.schemas';
+import { useWebsiteConsent } from '../consent/useWebsiteConsent';
+import { useWebsiteLabelByKey } from '../hooks/useWebsiteLabel';
+import { useWebsiteProviderComponent } from './useWebsiteProviderComponent';
+
+const STATE_STYLE: React.CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: '0.5rem',
+  padding: '0.75rem',
+  border: `1px solid ${websiteDesignTokenCssVar('colors', 'border', '#ccc')}`,
+  borderRadius: websiteDesignTokenCssVar('radii', 'md', '0.375rem'),
+};
+
+const BUTTON_STYLE: React.CSSProperties = {
+  alignSelf: 'flex-start',
+  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',
+};
+
+function PurposeName({ purpose }: { purpose: ConsentPurpose }): ReactNode {
+  return <li data-website-provider-component-purpose={purpose}>{useWebsiteLabelByKey(websiteConsentPurposeLabelKey(purpose))}</li>;
+}
+
+/**
+ * The words announced for a refusal. Rendered INTO the always-present live region, so a screen reader
+ * announces the change when it happens; a region inserted already filled is often not announced at all.
+ */
+function RefusalStatement({ status, missingPurposes }: { status: ProviderComponentStatus; missingPurposes: readonly ConsentPurpose[] }): ReactNode {
+  const consentRequired = useWebsiteLabelByKey(websiteProviderComponentLabelKey(WebsiteProviderComponentLabelSlot.CONSENT_REQUIRED));
+  const unavailable = useWebsiteLabelByKey(websiteProviderComponentLabelKey(WebsiteProviderComponentLabelSlot.UNAVAILABLE));
+  if (status === ProviderComponentStatus.UNAVAILABLE) return <p style={{ margin: 0 }}>{unavailable}</p>;
+  return (
+    <>
+      <p style={{ margin: 0 }}>{consentRequired}</p>
+      <ul style={{ margin: 0 }}>
+        {missingPurposes.map((purpose) => <PurposeName key={purpose} purpose={purpose} />)}
+      </ul>
+    </>
+  );
+}
+
+function ManageConsentButton({ onClick }: { onClick: () => void }): ReactNode {
+  return <button type="button" style={BUTTON_STYLE} onClick={onClick}>{useWebsiteLabelByKey(websiteConsentLabelKey(WebsiteConsentLabelSlot.MANAGE))}</button>;
+}
+
+/**
+ * @wildo_source:part:start saas.website.provider-component.slot facet:layer:core facet:family:website
+ *
+ * `<WebsiteProviderComponent>` — places ONE provider's component on a website page (#1703): an
+ * address lookup on a contact form, a vendor widget on a marketing page. The component comes from the
+ * provider's own `components[capability]` declaration, the same one the application reads, through
+ * the website's provider-component registry.
+ *
+ * What it guarantees, so a page does not have to:
+ *
+ * - **Nothing of the vendor reaches the static HTML.** The component loads from an effect, which never
+ *   runs during the Astro server render, and the registry itself refuses to load where there is no
+ *   browser document. The server renders only the reserved box.
+ * - **No layout shift.** `reservedMinHeight` applies to the box in EVERY state — the server
+ *   placeholder, loading, the refusals and the loaded component — so the page does not jump when the
+ *   component arrives. Set it to the component's rendered height.
+ * - **The vendor's scripts load with the component**, not on every page: the layout injects at startup
+ *   only the scripts of providers that contribute no component.
+ * - **Consent before download.** A provider resting on a purpose the visitor has not granted downloads
+ *   nothing; the box states that the feature is off, names the purposes it rests on, and offers the
+ *   consent panel (`openSettings`). Granting there loads the component in place.
+ * - **Announced, and operable by keyboard.** The box holds a `role="status"` live region from the first
+ *   render, so a refusal is announced when it appears; the consent button sits outside it, so it is not
+ *   read out as part of the message, and is a real button.
+ * - **A failure says so.** A component that could not load renders the site's `unavailable` wording,
+ *   never a blank. A provider that offers no component here (left off in this environment) renders the
+ *   empty box, since there is nothing to retry.
+ *
+ * The words come from the site's label pack: `website.chrome.provider-component.consent-required` and
+ * `.unavailable` are framework-owned keys every pack must carry, and the purpose names and the button
+ * reuse the consent panel's keys. Pass `renderConsentRequired` to word the refusal in the page's own
+ * chrome instead; it receives the missing purposes and the action that opens the panel, and then owns
+ * its own announcement.
+ *
+ * It does not choose a provider. Pass the ref the page chose — `useWebsiteProviderComponentChoices`
+ * lists the candidates — or `undefined` while nothing is chosen.
+ */
+export interface WebsiteProviderComponentProps<TProps extends object> {
+  /** The capability the component fills, e.g. `FRONTEND_ADDRESS_LOOKUP`. */
+  capability: ProviderCapability;
+  /** The provider the page chose, or `undefined` while nothing is chosen. */
+  providerRef: string | undefined;
+  /** The props the loaded component receives — the capability's slot contract. */
+  componentProps: TProps;
+  /** CSS length reserved for the box in every state, so the page does not shift when the component loads. */
+  reservedMinHeight?: string;
+  /** Replaces the default consent-required state. */
+  renderConsentRequired?: (input: { missingPurposes: readonly ConsentPurpose[]; openConsentSettings: () => void }) => ReactNode;
+}
+
+export function WebsiteProviderComponent<TProps extends object>({
+  capability,
+  providerRef,
+  componentProps,
+  reservedMinHeight,
+  renderConsentRequired,
+}: WebsiteProviderComponentProps<TProps>): ReactNode {
+  const consent = useWebsiteConsent();
+  const { status, Component, missingConsentPurposes } = useWebsiteProviderComponent(capability, providerRef);
+
+  const isReady = status === ProviderComponentStatus.READY && Component !== null;
+  const isConsentRequired = status === ProviderComponentStatus.CONSENT_REQUIRED;
+  const isUnavailable = status === ProviderComponentStatus.UNAVAILABLE;
+  const useDefaultRefusal = isUnavailable || (isConsentRequired && renderConsentRequired === undefined);
+  // The registry cannot know a capability's props; the page states them through `componentProps`.
+  const Loaded = isReady ? (Component as unknown as React.ComponentType<TProps>) : null;
+
+  return (
+    <div
+      data-website-provider-component={capability}
+      data-website-provider-component-state={status}
+      aria-busy={status === ProviderComponentStatus.LOADING ? true : undefined}
+      style={reservedMinHeight !== undefined ? { minHeight: reservedMinHeight } : undefined}
+    >
+      {Loaded !== null ? <Loaded {...componentProps} /> : null}
+      {isConsentRequired && renderConsentRequired !== undefined
+        ? renderConsentRequired({ missingPurposes: missingConsentPurposes, openConsentSettings: consent.openSettings })
+        : null}
+      {Loaded === null ? (
+        <div style={useDefaultRefusal ? STATE_STYLE : undefined}>
+          <div role="status">
+            {useDefaultRefusal ? <RefusalStatement status={status} missingPurposes={missingConsentPurposes} /> : null}
+          </div>
+          {isConsentRequired && renderConsentRequired === undefined ? <ManageConsentButton onClick={consent.openSettings} /> : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+/** @wildo_source:part:end saas.website.provider-component.slot */

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

@@ -10,7 +10,9 @@ import { describe, expect, it, vi } from 'vitest';
 import {
   ENGINE_PROVIDER_ORIGIN,
   ProviderTier,
+  defineFrontendPublicConfigSchema,
   defineProviderMetadata,
+  FrontendPublicConfigValueKind,
   type FrontendProvidersBlock,
 } from '@wildo-ai/saas-models/public-runtime';
 import type { FrontendWebsiteProviderRef } from '@wildo-ai/external-connectors-public/website';
@@ -51,6 +53,8 @@ describe('createFrontendWebsiteProviderRegistry', () => {
           providerCapabilities: ['FRONTEND_CAPTCHA'],
           protocols: ['FRONTEND_SDK'],
           sdk: { descriptor: { packageName: '@acme/analytics-web' }, activate },
+          // A readable key list is mandatory since #1705, or hydration withholds the code.
+          publicConfigSchema: defineFrontendPublicConfigSchema({ token: { kind: FrontendPublicConfigValueKind.STRING } }),
         },
       },
     });