@wildo-ai/saas-website 1.1.4 → 1.1.6

package/src/core/external-providers/__tests__/website-provider-component.test.tsx

@@ -0,0 +1,238 @@
+/**
+ * A provider component on the website (#1703), through the real page bridge.
+ *
+ * What this pins, in order of how badly each would fail:
+ *
+ * 1. The server render ships NOTHING of the vendor — the loader is never called, and the HTML holds
+ *    only the reserved box. Astro renders every island on the server; a component that ran there
+ *    would put vendor markup into HTML a visitor downloads before consenting to anything.
+ * 2. One declaration serves the website: the provider module's `components[capability].load`, the
+ *    same field the application reads, is what renders here.
+ * 3. A consent-based provider downloads nothing until the visitor agrees, shows an announced,
+ *    labelled refusal with a real button, and loads in place once the visitor grants the purpose.
+ * 4. A failed load says so, in the site's words.
+ */
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import {
+  AvailableLanguage,
+  ConsentPurpose,
+  ENGINE_PROVIDER_ORIGIN,
+  ProviderAddressLookupPlaceIdRetention,
+  ProviderTier,
+  defineFrontendPublicConfigSchema,
+  defineProviderMetadata,
+  type FrontendProvidersBlock,
+  type ProviderCapability,
+} from '@wildo-ai/saas-models/public-runtime';
+import { ProviderComponentStatus, type GeneratedWebsiteProviderModules } from '@wildo-ai/external-connectors-public/website';
+
+import { createWebsitePageBridgeIsland } from '../../../astro/bridge-runtime';
+import { WebsiteLabelKeySchema } from '../../../schemas/label-keys/website-label-key.schemas';
+import {
+  WEBSITE_CONSENT_LABEL_KEYS,
+  WebsiteConsentLabelSlot,
+  websiteConsentLabelKey,
+  websiteConsentPurposeLabelKey,
+} from '../../../schemas/label-keys/website-consent-label-keys.schemas';
+import {
+  WEBSITE_PROVIDER_COMPONENT_LABEL_KEYS,
+  WebsiteProviderComponentLabelSlot,
+  websiteProviderComponentLabelKey,
+} from '../../../schemas/label-keys/website-provider-component-label-keys.schemas';
+import type { WebsitePageRef } from '../../../schemas/refs/page-ref.schemas';
+import { writeWebsiteVisitorConsent } from '../../consent/website-consent-storage';
+import { WebsiteProviderComponent } from '../WebsiteProviderComponent';
+
+const LOOKUP = 'FRONTEND_ADDRESS_LOOKUP' as ProviderCapability;
+const SKIP_KEY = WebsiteLabelKeySchema.parse('website.chrome.layout.skip-to-main-content');
+// Every framework-owned key resolves to itself, so the rendered states are found by the key they show.
+const LABEL_PACK = Object.fromEntries(
+  [SKIP_KEY, ...WEBSITE_CONSENT_LABEL_KEYS, ...WEBSITE_PROVIDER_COMPONENT_LABEL_KEYS].map((key) => [key as unknown as string, key as unknown as string]),
+);
+const text = (key: unknown): string => key as string;
+
+const DESIGN_TOKENS = {
+  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' },
+};
+
+/** The vendor's component: renders the prop the page passed, so the test can see it arrived. */
+function PlacesLookup({ fieldLabel }: { fieldLabel: string }): React.ReactNode {
+  return <input aria-label={fieldLabel} data-testid="places-lookup" />;
+}
+
+const metadata = defineProviderMetadata({ ref: 'places', packageName: '@wildo-ai/provider-places', tier: ProviderTier.CATALOGUE, origin: ENGINE_PROVIDER_ORIGIN });
+
+/** The DATA and CODE channels for one provider declaring ONE address-lookup component. */
+function site(input: { load: () => Promise<unknown>; consentPurposes?: ConsentPurpose[]; scripts?: Array<{ src: string }>; withComponent?: boolean }): {
+  entries: FrontendProvidersBlock;
+  modules: GeneratedWebsiteProviderModules;
+} {
+  const descriptor = { placeIdRetention: ProviderAddressLookupPlaceIdRetention.NONE };
+  const common = {
+    metadata,
+    providerCapabilities: [LOOKUP],
+    protocols: ['FRONTEND_SDK'],
+    ...(input.consentPurposes !== undefined ? { consentPurposes: input.consentPurposes } : {}),
+    ...(input.scripts !== undefined ? { scripts: input.scripts } : {}),
+  };
+  const withComponent = input.withComponent ?? true;
+  return {
+    entries: { providers: { places: { ...common, ...(withComponent ? { components: { [LOOKUP]: descriptor } } : {}) } } } as unknown as FrontendProvidersBlock,
+    modules: {
+      places: {
+        ...common,
+        ...(withComponent ? { components: { [LOOKUP]: { ...descriptor, load: input.load } } } : {}),
+        publicConfigSchema: defineFrontendPublicConfigSchema({}),
+      },
+    } as unknown as GeneratedWebsiteProviderModules,
+  };
+}
+
+function ContactPage(): React.ReactNode {
+  return (
+    <form>
+      <WebsiteProviderComponent capability={LOOKUP} providerRef="places" componentProps={{ fieldLabel: 'Address' }} reservedMinHeight="3rem" />
+    </form>
+  );
+}
+
+function EmptyPage(): React.ReactNode {
+  return <p>No form on this page</p>;
+}
+
+function island(channels: ReturnType<typeof site>, PageComponent: () => React.ReactNode = ContactPage): React.ReactElement {
+  const Island = createWebsitePageBridgeIsland({
+    PageComponent,
+    pageRef: 'contact' as unknown as WebsitePageRef,
+    navigation: { headerComponent: () => null, footerComponent: () => null },
+    frontendProviderModules: channels.modules,
+  });
+  return (
+    <Island
+      locale={AvailableLanguage.EN}
+      defaultLocale={AvailableLanguage.EN}
+      labelPack={LABEL_PACK}
+      designTokens={DESIGN_TOKENS as never}
+      skipToMainContentLabelKey={SKIP_KEY}
+      frontendProviders={channels.entries}
+    />
+  );
+}
+
+const SCRIPT_SRC = 'https://maps.vendor.example/places.js';
+const injectedScripts = (): string[] => [...document.querySelectorAll('script')].map((script) => script.getAttribute('src') ?? '').filter((src) => src === SCRIPT_SRC);
+
+beforeEach(() => {
+  window.localStorage.clear();
+  for (const script of document.querySelectorAll('script')) script.remove();
+});
+afterEach(cleanup);
+
+describe('a provider component on the website (#1703)', () => {
+  it('ships NOTHING of the vendor in the server render — only the reserved box', async () => {
+    const load = vi.fn(async () => PlacesLookup);
+
+    const html = renderToString(island(site({ load })));
+    // The registry starts a loader on a microtask; wait one macrotask so a load begun by the render is seen.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(load).not.toHaveBeenCalled();
+    expect(html).toContain(`data-website-provider-component="${LOOKUP}"`);
+    expect(html).toContain(`data-website-provider-component-state="${ProviderComponentStatus.NONE}"`);
+    expect(html).toContain('min-height:3rem');
+    expect(html).not.toContain('places-lookup');
+  });
+
+  it('has its live region in the FIRST render, before anything is announced', () => {
+    // A screen reader announces changes to a live region it already knows about; a region inserted together with its
+    // text is often read late or not at all. So the empty role="status" must exist in the server render, in the NONE
+    // state, before any refusal can be written into it (#1703 review F3).
+    const html = renderToString(island(site({ load: vi.fn(async () => PlacesLookup) })));
+
+    expect(html).toContain(`data-website-provider-component-state="${ProviderComponentStatus.NONE}"`);
+    expect(html).toMatch(/<div role="status"><\/div>/);
+  });
+
+  it('renders the component the provider DECLARED, with the props the page passed, in the browser', async () => {
+    const load = vi.fn(async () => PlacesLookup);
+
+    render(island(site({ load })));
+
+    expect(await screen.findByLabelText('Address')).toBeInTheDocument();
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+
+  it('downloads nothing until the visitor agrees, says so accessibly, and loads in place once they do', async () => {
+    const load = vi.fn(async () => PlacesLookup);
+
+    render(island(site({ load, consentPurposes: [ConsentPurpose.MARKETING] })));
+    // The visitor declines everything in the panel the layout shows.
+    fireEvent.click(await screen.findByText(text(websiteConsentLabelKey(WebsiteConsentLabelSlot.DECLINE_ALL))));
+
+    const refusal = await screen.findByText(text(websiteProviderComponentLabelKey(WebsiteProviderComponentLabelSlot.CONSENT_REQUIRED)));
+    expect(refusal.closest('[role="status"]')).not.toBeNull();
+    expect(screen.getByText(text(websiteConsentPurposeLabelKey(ConsentPurpose.MARKETING)))).toBeInTheDocument();
+    expect(load).not.toHaveBeenCalled();
+
+    // The refusal's own button opens the panel; granting there loads the component without a re-mount.
+    const manage = screen.getAllByRole('button', { name: text(websiteConsentLabelKey(WebsiteConsentLabelSlot.MANAGE)) });
+    fireEvent.click(manage[0]!);
+    fireEvent.click(await screen.findByText(text(websiteConsentLabelKey(WebsiteConsentLabelSlot.ACCEPT_ALL))));
+
+    expect(await screen.findByLabelText('Address')).toBeInTheDocument();
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+
+  it('loads at once for a visitor who agreed on an earlier page', async () => {
+    writeWebsiteVisitorConsent([ConsentPurpose.MARKETING]);
+    const load = vi.fn(async () => PlacesLookup);
+
+    render(island(site({ load, consentPurposes: [ConsentPurpose.MARKETING] })));
+
+    expect(await screen.findByLabelText('Address')).toBeInTheDocument();
+  });
+
+  it('says the feature is unavailable when the component cannot load — never a blank', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    render(island(site({ load: async () => { throw new Error('vendor CDN unreachable'); } })));
+
+    const statement = await screen.findByText(text(websiteProviderComponentLabelKey(WebsiteProviderComponentLabelSlot.UNAVAILABLE)));
+    expect(statement.closest('[role="status"]')).not.toBeNull();
+    await waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining('LOAD_FAILED')));
+    warn.mockRestore();
+  });
+
+  it('says nothing, rather than "try again later", for a provider that offers no component here', async () => {
+    render(island(site({ load: async () => PlacesLookup, withComponent: false })));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(screen.queryByText(text(websiteProviderComponentLabelKey(WebsiteProviderComponentLabelSlot.UNAVAILABLE)))).toBeNull();
+    expect(document.querySelector(`[data-website-provider-component-state="${ProviderComponentStatus.NONE}"]`)).not.toBeNull();
+  });
+});
+
+describe('a component-bearing provider\'s scripts load WITH its component, not on every page (#1703)', () => {
+  it('injects nothing at startup on a page without the component', async () => {
+    render(island(site({ load: async () => PlacesLookup, scripts: [{ src: SCRIPT_SRC }] }), EmptyPage));
+    await screen.findByText('No form on this page');
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(injectedScripts()).toEqual([]);
+  });
+
+  it('loads the script when the page shows the component', async () => {
+    render(island(site({ load: async () => PlacesLookup, scripts: [{ src: SCRIPT_SRC }] })));
+    await waitFor(() => expect(injectedScripts()).toEqual([SCRIPT_SRC]));
+  });
+
+  it('still injects at startup the scripts of a provider that contributes NO component', async () => {
+    render(island(site({ load: async () => PlacesLookup, scripts: [{ src: SCRIPT_SRC }], withComponent: false }), EmptyPage));
+    await waitFor(() => expect(injectedScripts()).toEqual([SCRIPT_SRC]));
+  });
+});

package/src/core/external-providers/__tests__/website-provider-sdks.test.tsx

@@ -0,0 +1,72 @@
+/**
+ * #1704 — the website's consent-based providers start on the visitor's grant, stop on withdrawal, and a start never
+ * overlaps the previous stop of the same page-global vendor.
+ *
+ * The runner and the lane are the real ones; only the vendor is a double.
+ */
+import React from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, waitFor } from '@testing-library/react';
+import { BUILTIN_PROVIDER_CAPABILITY, ConsentPurpose } from '@wildo-ai/saas-models/public-runtime';
+import type { FrontendWebsiteProviderRegistry } from '@wildo-ai/external-connectors-public/website';
+
+import { useWebsiteProviderSdks } from '../useWebsiteProviderScripts';
+
+afterEach(() => { cleanup(); });
+
+function Harness({ registry, granted }: { registry: FrontendWebsiteProviderRegistry; granted: ConsentPurpose[] }) {
+  useWebsiteProviderSdks(registry, granted);
+  return null;
+}
+
+function registryOf(activate: () => Promise<unknown>): FrontendWebsiteProviderRegistry {
+  const module = {
+    metadata: { ref: 'posthog' },
+    providerCapabilities: [BUILTIN_PROVIDER_CAPABILITY.FRONTEND_PRODUCT_ANALYTICS],
+    protocols: ['FRONTEND_SDK'],
+    publicConfig: {},
+    sdk: { descriptor: { packageName: '@vendor/posthog' }, stoppable: true, activate },
+  };
+  return { modules: new Map([['posthog', module]]) } as unknown as FrontendWebsiteProviderRegistry;
+}
+
+describe('useWebsiteProviderSdks — the consent-based group (#1704)', () => {
+  it('starts nothing before the grant, starts on it and stops on withdrawal', async () => {
+    const deactivate = vi.fn();
+    const activate = vi.fn(async () => ({ handle: {}, deactivate }));
+    const registry = registryOf(activate);
+    const view = render(<Harness registry={registry} granted={[]} />);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(activate).not.toHaveBeenCalled();
+
+    view.rerender(<Harness registry={registry} granted={[ConsentPurpose.ANALYTICS]} />);
+    await waitFor(() => expect(activate).toHaveBeenCalledTimes(1));
+    view.rerender(<Harness registry={registry} granted={[]} />);
+    await waitFor(() => expect(deactivate).toHaveBeenCalledTimes(1));
+  });
+
+  it('does not start again until the previous start has fully stopped (grant, withdraw, grant while the vendor loads)', async () => {
+    const order: string[] = [];
+    let releaseFirst!: () => void;
+    const firstLoaded = new Promise<void>((resolve) => { releaseFirst = resolve; });
+    let starts = 0;
+    const activate = vi.fn(async () => {
+      starts += 1;
+      const n = starts;
+      order.push(`start:${n}`);
+      if (n === 1) await firstLoaded;
+      return { handle: {}, deactivate: () => { order.push(`stop:${n}`); } };
+    });
+    const registry = registryOf(activate);
+    const view = render(<Harness registry={registry} granted={[ConsentPurpose.ANALYTICS]} />);
+    await waitFor(() => expect(order).toEqual(['start:1']));
+
+    view.rerender(<Harness registry={registry} granted={[]} />);
+    view.rerender(<Harness registry={registry} granted={[ConsentPurpose.ANALYTICS]} />);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(order).toEqual(['start:1']);
+
+    releaseFirst();
+    await waitFor(() => expect(order).toEqual(['start:1', 'stop:1', 'start:2']));
+  });
+});

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

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

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

@@ -0,0 +1,115 @@
+/**
+ * The website's provider-component registry (#1703): the SAME registry the application builds, from
+ * the SAME `components` declaration, over the website's live provider modules.
+ *
+ * A provider declares its components once, on its frontend module. Before this, the website facet
+ * type accepted `components` and nothing on the website read it, so a contact form could not host an
+ * address lookup (#561) and a marketing page could not host any provider component at all. The
+ * registry is `createProviderComponentRegistry` from `@wildo-ai/external-connectors-public/website`
+ * — keyed `capability:providerRef`, consent-gated, script-before-component and browser-only — and
+ * this file only feeds it the website's two inputs:
+ *
+ *   - the HYDRATED website provider registry (both channels joined, so a provider not live for this
+ *     website service contributes no component);
+ *   - the loaders the site's facet library contributes for components an engine provider module
+ *     declares but cannot import (the module lives in a renderer-free package), handed in through the
+ *     page bridge's `providerComponentLoaders` rather than through module-level state, because the
+ *     bridge is the website's one construction site and can carry it explicitly.
+ *
+ * Nothing is loaded here. A component loads when a `WebsiteProviderComponent` slot asks for it, from
+ * an effect — never during the Astro server render.
+ */
+
+import { useMemo, type ComponentType } from 'react';
+import {
+  collectProviderComponentRegistrations,
+  createProviderComponentRegistry,
+  indexProviderComponentLoaderContributions,
+  type ProviderComponentDiagnostic,
+  type ProviderComponentLoaderContribution,
+  type ProviderComponentRegistry,
+} from '@wildo-ai/external-connectors-public/website';
+
+import type { FrontendProvidersBlock } from '@wildo-ai/saas-models/public-runtime';
+
+import {
+  createFrontendWebsiteProviderRegistry,
+  type FrontendWebsiteProviderRegistry,
+  type GeneratedWebsiteProviderModules,
+} from './frontend-provider-registry.website';
+
+/** A component type the website's registry hands back once loaded. */
+export type WebsiteProviderComponentType = ComponentType<never>;
+
+/** The website's provider-component registry: the shared registry, holding React components. */
+export type WebsiteProviderComponentRegistry = ProviderComponentRegistry<WebsiteProviderComponentType>;
+
+export interface CreateWebsiteProviderComponentRegistryInput {
+  /** The hydrated website provider registry; absent on a site with no providers. */
+  readonly providerRegistry: FrontendWebsiteProviderRegistry | undefined;
+  /** Loaders the site's facet library contributes for engine-declared components. */
+  readonly providerComponentLoaders?: Iterable<ProviderComponentLoaderContribution>;
+  /**
+   * Where a registration or load problem is reported. Defaults to `console.warn`: the website runtime
+   * has no logger service, and a provider component that cannot be offered is a developer-facing fact
+   * that must not be silent.
+   */
+  readonly onDiagnostic?: (diagnostic: ProviderComponentDiagnostic) => void;
+}
+
+function warnProviderComponentDiagnostic(diagnostic: ProviderComponentDiagnostic): void {
+  // Reported in the BROWSER only. The registry is built during the server render or prerender too, once per
+  // page, and a declaration nothing can load would otherwise fill the build log with one warning per page
+  // for a fact the first page already stated. The browser is where somebody can see and act on it.
+  if (typeof document === 'undefined') return;
+  // eslint-disable-next-line no-console
+  console.warn(`[wildo-provider-component] ${diagnostic.kind}: ${diagnostic.message}`);
+}
+
+/** Builds the website's provider-component registry from its live provider modules. */
+export function createWebsiteProviderComponentRegistry(
+  input: CreateWebsiteProviderComponentRegistryInput,
+): WebsiteProviderComponentRegistry {
+  const onDiagnostic = input.onDiagnostic ?? warnProviderComponentDiagnostic;
+  const registrations = collectProviderComponentRegistrations(input.providerRegistry?.modules.values() ?? [], {
+    contributedLoaders: indexProviderComponentLoaderContributions(input.providerComponentLoaders),
+    onDiagnostic,
+  });
+  return createProviderComponentRegistry<WebsiteProviderComponentType>({ registrations, onDiagnostic });
+}
+
+/** What a page bridge builds once per island: the hydrated provider registry and its component registry. */
+export interface WebsiteProviderRegistries {
+  readonly frontendProviderRegistry: FrontendWebsiteProviderRegistry;
+  readonly providerComponentRegistry: WebsiteProviderComponentRegistry;
+}
+
+/**
+ * Builds both registries for a page bridge, MEMOISED on their inputs.
+ *
+ * Memoised because the component registry caches each loaded component: a registry rebuilt on every
+ * render would forget what it loaded, hand every slot a new registry identity, and make each slot's
+ * load effect run again — a download loop. The inputs are an island prop (`frontendProviders`, fixed
+ * for the island's life) and two module-load-time bridge dependencies, so in practice this builds
+ * once per island.
+ */
+export function useWebsiteProviderRegistries(input: {
+  readonly frontendProviders: FrontendProvidersBlock | undefined;
+  readonly frontendProviderModules: GeneratedWebsiteProviderModules | undefined;
+  readonly providerComponentLoaders: Iterable<ProviderComponentLoaderContribution> | undefined;
+}): WebsiteProviderRegistries {
+  const { frontendProviders, frontendProviderModules, providerComponentLoaders } = input;
+  return useMemo(() => {
+    const frontendProviderRegistry = createFrontendWebsiteProviderRegistry({
+      entries: frontendProviders,
+      modules: frontendProviderModules,
+    });
+    return {
+      frontendProviderRegistry,
+      providerComponentRegistry: createWebsiteProviderComponentRegistry({
+        providerRegistry: frontendProviderRegistry,
+        ...(providerComponentLoaders !== undefined ? { providerComponentLoaders } : {}),
+      }),
+    };
+  }, [frontendProviders, frontendProviderModules, providerComponentLoaders]);
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Reading provider-contributed components on the website (#1703) — the website's counterpart of the
+ * application's `useProviderComponentChoices` / `useProviderComponent`, over the same registry and
+ * the same status vocabulary (`ProviderComponentStatus`).
+ *
+ * Two differences from the application, both about WHO answers:
+ *
+ *   - the consent grant is the VISITOR's decision from `WebsiteConsentContext`, not a signed-in
+ *     person's stored preference;
+ *   - nothing starts before that decision has been read from storage (`isResolved`). The server render
+ *     and the first client render read no storage, and asking the registry then would report a
+ *     consent-required state to a visitor who already agreed, flashing the refusal on every page.
+ *
+ * Neither hook picks a provider: when several providers offer a component for one capability,
+ * choosing is the page's job.
+ */
+
+import { useEffect, useState } from 'react';
+import {
+  idleProviderComponentLoadState,
+  startProviderComponentLoad,
+  type ProviderComponentLoadState,
+} from '@wildo-ai/external-connectors-public/website';
+import type { ProviderCapability } from '@wildo-ai/saas-models/public-runtime';
+
+import { useWebsiteConsent } from '../consent/useWebsiteConsent';
+import { useWebsiteRuntime } from '../contexts/useWebsiteRuntime';
+import type { WebsiteProviderComponentType } from './provider-component-registry.website';
+
+/** What `useWebsiteProviderComponent` returns: the shared load state, holding a React component. */
+export type WebsiteProviderComponentState = ProviderComponentLoadState<WebsiteProviderComponentType>;
+
+/**
+ * The providers that are BOTH live for this website service and carry a component for this
+ * capability, in the order the service declared them. Synchronous, so a page can render its choice
+ * on the first frame.
+ */
+export function useWebsiteProviderComponentChoices(capability: ProviderCapability): ReadonlyArray<string> {
+  const { providerComponentRegistry } = useWebsiteRuntime();
+  return providerComponentRegistry?.listProviders(capability) ?? [];
+}
+
+/**
+ * Loads one provider's component for a capability, once the visitor's consent decision is known.
+ *
+ * Pass `undefined` for the ref while nothing is chosen. The load runs in an effect, so it never runs
+ * during the Astro server render; `CONSENT_REQUIRED` means nothing of the provider was downloaded,
+ * and granting the missing purposes through the consent panel loads it without a re-mount.
+ */
+export function useWebsiteProviderComponent(
+  capability: ProviderCapability,
+  providerRef: string | undefined,
+): WebsiteProviderComponentState {
+  const { providerComponentRegistry } = useWebsiteRuntime();
+  const consent = useWebsiteConsent();
+  const grantedKey = [...consent.grantedPurposes].sort().join(',');
+  const [state, setState] = useState<WebsiteProviderComponentState>(() => idleProviderComponentLoadState<WebsiteProviderComponentType>());
+
+  useEffect(() => {
+    if (!consent.isResolved) {
+      setState(idleProviderComponentLoadState<WebsiteProviderComponentType>());
+      return undefined;
+    }
+    return startProviderComponentLoad({
+      registry: providerComponentRegistry,
+      capability,
+      providerRef,
+      grantedConsentPurposes: consent.grantedPurposes,
+      onState: setState,
+    });
+    // `grantedPurposes` is read through `grantedKey`: keyed by the granted SET, not the array's identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [capability, providerRef, providerComponentRegistry, consent.isResolved, grantedKey]);
+
+  return state;
+}