@wildo-ai/saas-website 1.1.5 → 1.1.7

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/inbound-contact-form.schema.ts

@@ -23,18 +23,30 @@ 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.consentedPurposes` set.
    * It is the only privacy field on this form, and it gates nothing: sending the form is the

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,8 +121,24 @@ 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> {
-    return this.requestAnonymous<TResponse>('POST', path, body);
+  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;
   }
 
   /**
@@ -122,12 +151,18 @@ export class WebsiteAnonymousSessionClient {
    * 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> {
+  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,
-      headers: this.buildHeaders(),
+      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

@@ -1,6 +1,7 @@
 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';
@@ -49,7 +50,7 @@ const ROW_STYLE: React.CSSProperties = {
   columnGap: '0.625rem',
   alignItems: 'center',
   padding: '0.5rem 0.75rem',
-  borderBottom: '1px solid var(--website-colors-border, #ccc)',
+  borderBottom: `1px solid ${websiteDesignTokenCssVar('colors', 'border', '#ccc')}`,
 };
 
 const ROW_DESCRIPTION_STYLE: React.CSSProperties = { margin: 0, gridColumn: 2, fontSize: '0.75rem', opacity: 0.8 };
@@ -79,10 +80,10 @@ function PurposeChoice({ purpose, checked, onChange }: { purpose: ConsentPurpose
 
 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)',
+  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',
 };
 
@@ -141,10 +142,10 @@ export function WebsiteConsentBanner(): ReactNode {
         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)',
+        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>
@@ -154,7 +155,7 @@ export function WebsiteConsentBanner(): ReactNode {
           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)' }}
+        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

package/src/core/contexts/WebsiteRuntimeContext.tsx

@@ -1,9 +1,10 @@
 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,14 @@ 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.
@@ -173,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 */