@wildo-ai/saas-website 1.1.5 → 1.1.6

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 } }),
         },
       },
     });

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/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]);
+}