@wildo-ai/saas-website 1.1.2 → 1.1.3

package/src/core/contexts/WebsiteRuntimeContext.tsx

@@ -51,13 +51,22 @@ import type { LabelPack } from '../../schemas/validators/label-pack.validator';
  *   contract the SaaS app now uses, instead of inventing a website-only
  *   metadata seam.
  *
- * **Why a separate file from the hook + provider**: split for React
- * Fast Refresh — when a `.tsx` exports both a React component and a
- * React Context object, edits to either one invalidate the entire
- * module's HMR boundary. Keeping the bare context here, the hook in
- * `useWebsiteRuntime.ts`, and the provider component in
- * `WebsiteRuntimeContextProvider.tsx` makes section authors edit
- * components without retriggering the runtime context's identity.
+ * **Why the hook lives in a separate file**: React Fast Refresh only
+ * preserves state for a module whose every export is a component, so
+ * a module mixing components with plain functions loses its HMR
+ * boundary. This file holds the two things that must be identical
+ * objects at runtime — the context and the provider component that
+ * writes it — while `useWebsiteRuntime` sits alone in
+ * `useWebsiteRuntime.ts`. A section author editing a component that
+ * merely READS the runtime therefore never remounts the provider.
+ *
+ * Until 2026-09-09 this paragraph described a different arrangement:
+ * that only the bare context was kept here and the provider lived in
+ * a file of its own. No such file has ever existed — the provider is
+ * exported below — and splitting it out would be the wrong shape
+ * anyway, since `useContext` matches on object identity.
+ * prose-referent-waiver: the retired file name is quoted only to retire it.
+ * The claim named `WebsiteRuntimeContextProvider.tsx`.
  */
 export interface WebsiteRuntimeContextValue {
   /**
@@ -77,6 +86,26 @@ export interface WebsiteRuntimeContextValue {
    * paths.
    */
   defaultLocale: AvailableLanguage;
+  /**
+   * Origin of the application this marketing site sends visitors INTO — the
+   * marketing → product handoff target, authored once as
+   * `WildoMarketingWebsiteConfig.appOrigin` (#493).
+   *
+   * Carried here for exactly the reason `defaultLocale` above is: a
+   * `wildo.website.config.ts` is Node-loaded and therefore invisible to a
+   * client island, so before this a site resolved the app origin a SECOND
+   * time from a public build-time environment variable it could read in the
+   * browser — one host authored twice, in two files, with no mechanical link
+   * between the copies. That is how a marketing site comes to point at the
+   * wrong environment: a defect nobody notices until a customer follows the
+   * link.
+   *
+   * Threading it through the runtime keeps the handoff a framework-internal
+   * concern, the same way threading `defaultLocale` kept locale-prefixing one:
+   * section authors never hand-assemble the product URL, and there is one
+   * place to change it.
+   */
+  appOrigin?: string;
   /**
    * Flat `Record<string, string>` label pack for the active locale.
    * Lookup keys MUST be fully-composed `website.<page>.<section>.<slot>`

package/src/core/contexts/WebsiteSectionContext.tsx

@@ -19,8 +19,9 @@ import type { WebsiteSectionRef } from '../../schemas/refs/section-ref.schemas';
  * both saves consumers from having to thread the manifest just to
  * map a ref back to its category.
  *
- * **Why a separate file from the hook**: same Fast-Refresh rationale
- * as the runtime + page contexts.
+ * **Why the hook lives in a separate file**: same Fast-Refresh
+ * rationale as the runtime + page contexts — context and provider
+ * together here, the hook alone in `useWebsiteSection.ts`.
  */
 export interface WebsiteSectionContextValue {
   /**

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

@@ -0,0 +1,79 @@
+/**
+ * The website's half of the two-channel design (#332).
+ *
+ * The registry used to build itself by casting each served entry to a module
+ * type that was an alias of that entry — true, and useless: it could never hold
+ * anything a JSON payload cannot carry, so a provider's SDK loader had nowhere
+ * to arrive.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import {
+  ENGINE_PROVIDER_ORIGIN,
+  ProviderTier,
+  defineProviderMetadata,
+  type FrontendProvidersBlock,
+} from '@wildo-ai/saas-models/public-runtime';
+import type { FrontendWebsiteProviderRef } from '@wildo-ai/external-connectors-public/website';
+import { createFrontendWebsiteProviderRegistry } from '../frontend-provider-registry.website';
+
+// FRONTEND_CAPTCHA binds no engine slot, which is what a CATALOGUE provider is
+// allowed to claim (#328). Using an engine-slot capability here would be
+// refused by the tier rule the composer still runs — as it should be.
+const metadata = defineProviderMetadata({
+  ref: 'acme',
+  packageName: '@wildo-ai/provider-acme',
+  tier: ProviderTier.CATALOGUE,
+  origin: ENGINE_PROVIDER_ORIGIN,
+});
+
+function entries(): FrontendProvidersBlock {
+  return {
+    providers: {
+      acme: {
+        metadata,
+        providerCapabilities: ['FRONTEND_CAPTCHA'],
+        protocols: ['FRONTEND_SDK'],
+        publicConfig: { token: 'public-token' },
+      },
+    },
+  } as unknown as FrontendProvidersBlock;
+}
+
+describe('createFrontendWebsiteProviderRegistry', () => {
+  it('joins the served entries with the bundle\'s generated modules', () => {
+    const activate = vi.fn();
+
+    const registry = createFrontendWebsiteProviderRegistry({
+      entries: entries(),
+      modules: {
+        acme: {
+          metadata,
+          providerCapabilities: ['FRONTEND_CAPTCHA'],
+          protocols: ['FRONTEND_SDK'],
+          sdk: { descriptor: { packageName: '@acme/analytics-web' }, activate },
+        },
+      },
+    });
+
+    const provider = registry.getProviderByRef('acme' as FrontendWebsiteProviderRef);
+    expect(provider?.sdk?.descriptor.packageName).toBe('@acme/analytics-web');
+    expect(provider?.publicConfig).toEqual({ token: 'public-token' });
+  });
+
+  it('a provider the bundle has no code for is still listed, and says which command fixes it', () => {
+    const diagnostics: string[] = [];
+
+    const registry = createFrontendWebsiteProviderRegistry({
+      entries: entries(),
+      onDiagnostic: (diagnostic) => diagnostics.push(diagnostic.message),
+    });
+
+    expect(registry.modules.size).toBe(1);
+    expect(registry.getProviderByRef('acme' as FrontendWebsiteProviderRef)?.sdk).toBeUndefined();
+    expect(diagnostics.join(' ')).toContain('wildo config sync');
+  });
+
+  it('hydrates to an empty registry when the website declares nothing', () => {
+    expect(createFrontendWebsiteProviderRegistry().modules.size).toBe(0);
+  });
+});

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

@@ -0,0 +1,146 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+  ENGINE_PROVIDER_ORIGIN,
+  ProviderFrontendScriptCrossOrigin,
+  ProviderTier,
+  defineProviderMetadata,
+  type FrontendProvidersBlock,
+} from '@wildo-ai/saas-models/public-runtime';
+import { createFrontendWebsiteProviderRegistry } from '../frontend-provider-registry.website';
+import {
+  PROVIDER_SCRIPT_MARKER_ATTRIBUTE,
+  collectDeclaredProviderScripts,
+  injectProviderScripts,
+} from '../provider-scripts.website';
+
+function registryWith(scriptsByRef: Record<string, unknown[]>): ReturnType<typeof createFrontendWebsiteProviderRegistry> {
+  const providers = Object.fromEntries(
+    Object.entries(scriptsByRef).map(([ref, scripts]) => [
+      ref,
+      {
+        metadata: defineProviderMetadata({
+          ref,
+          packageName: `@wildo-ai/provider-${ref}`,
+          tier: ProviderTier.CATALOGUE,
+          origin: ENGINE_PROVIDER_ORIGIN,
+        }),
+        providerCapabilities: [],
+        protocols: ['FRONTEND_SDK'],
+        scripts,
+      },
+    ]),
+  );
+  return createFrontendWebsiteProviderRegistry({ entries: { providers } as unknown as FrontendProvidersBlock });
+}
+
+function injectedScripts(): HTMLScriptElement[] {
+  return [...document.querySelectorAll<HTMLScriptElement>(`script[${PROVIDER_SCRIPT_MARKER_ATTRIBUTE}]`)];
+}
+
+describe('website provider scripts', () => {
+  beforeEach(() => {
+    document.head.innerHTML = '';
+  });
+
+  it('collects every declared script with the ref that declared it', () => {
+    const collected = collectDeclaredProviderScripts(
+      registryWith({
+        analytics: [{ src: 'https://cdn.analytics.test/a.js' }],
+        captcha: [{ src: 'https://captcha.test/api.js' }, { src: 'https://captcha.test/extra.js' }],
+      }),
+    );
+
+    expect(collected.map((entry) => `${entry.providerRef}:${entry.declaration.src}`)).toEqual([
+      'analytics:https://cdn.analytics.test/a.js',
+      'captcha:https://captcha.test/api.js',
+      'captcha:https://captcha.test/extra.js',
+    ]);
+  });
+
+  it('collects nothing when no registry is hydrated at all', () => {
+    expect(collectDeclaredProviderScripts(undefined)).toEqual([]);
+  });
+
+  it('injects a declared script into the document head, carrying its SRI and crossorigin', () => {
+    const result = injectProviderScripts(
+      collectDeclaredProviderScripts(
+        registryWith({
+          analytics: [
+            {
+              src: 'https://cdn.analytics.test/a.js',
+              integrity: 'sha384-abc',
+              crossOrigin: ProviderFrontendScriptCrossOrigin.ANONYMOUS,
+            },
+          ],
+        }),
+      ),
+      document,
+    );
+
+    const [element] = injectedScripts();
+    expect(result.injected).toEqual(['analytics']);
+    expect(element.src).toBe('https://cdn.analytics.test/a.js');
+    expect(element.integrity).toBe('sha384-abc');
+    expect(element.crossOrigin).toBe('anonymous');
+    expect(element.getAttribute(PROVIDER_SCRIPT_MARKER_ATTRIBUTE)).toBe('analytics');
+  });
+
+  it('defaults to async, because a blocking third-party tag is how a marketing site loses its paint', () => {
+    injectProviderScripts(
+      collectDeclaredProviderScripts(registryWith({ analytics: [{ src: 'https://cdn.analytics.test/a.js' }] })),
+      document,
+    );
+
+    expect(injectedScripts()[0].async).toBe(true);
+    expect(injectedScripts()[0].defer).toBe(false);
+  });
+
+  it('honours defer by turning async OFF, which a dynamically created script does not do on its own', () => {
+    // A script element created by script is async by default, so `defer: true`
+    // alone would be silently ignored — the exact shape of a declaration that
+    // looks respected and is not.
+    injectProviderScripts(
+      collectDeclaredProviderScripts(
+        registryWith({ analytics: [{ src: 'https://cdn.analytics.test/a.js', defer: true }] }),
+      ),
+      document,
+    );
+
+    expect(injectedScripts()[0].async).toBe(false);
+    expect(injectedScripts()[0].defer).toBe(true);
+  });
+
+  it('is idempotent: a second call adds nothing, so a remount cannot start a vendor twice', () => {
+    const scripts = collectDeclaredProviderScripts(
+      registryWith({ analytics: [{ src: 'https://cdn.analytics.test/a.js' }] }),
+    );
+
+    injectProviderScripts(scripts, document);
+    const second = injectProviderScripts(scripts, document);
+
+    expect(injectedScripts()).toHaveLength(1);
+    expect(second.injected).toEqual([]);
+    expect(second.alreadyPresent).toEqual(['analytics']);
+  });
+
+  it('matches an existing script by its src even when the URL carries query characters', () => {
+    const scripts = collectDeclaredProviderScripts(
+      registryWith({ captcha: [{ src: 'https://captcha.test/api.js?render=abc&hl=fr' }] }),
+    );
+
+    injectProviderScripts(scripts, document);
+    injectProviderScripts(scripts, document);
+
+    expect(injectedScripts()).toHaveLength(1);
+  });
+
+  it('adds nothing for a provider that declares no scripts', () => {
+    const result = injectProviderScripts(
+      collectDeclaredProviderScripts(registryWith({ analytics: [] })),
+      document,
+    );
+
+    expect(result.injected).toEqual([]);
+    expect(injectedScripts()).toHaveLength(0);
+  });
+});

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

@@ -1,62 +1,61 @@
-import type {
-  FrontendProviderEntry,
-  FrontendProvidersBlock,
-  ProviderCapability,
-} from '@wildo-ai/saas-models/public-runtime';
-
-export type FrontendWebsiteProviderRef = string & {
-  readonly __brand: 'FrontendWebsiteProviderRef';
-};
-
-export type FrontendWebsiteProviderModule = FrontendProviderEntry;
-
-export interface FrontendWebsiteProviderRegistry {
-  readonly modules: ReadonlyMap<
-    FrontendWebsiteProviderRef,
-    FrontendWebsiteProviderModule
-  >;
-
-  getProviderByRef(
-    ref: FrontendWebsiteProviderRef,
-  ): FrontendWebsiteProviderModule | undefined;
-
-  getProvidersByProviderCapability(
-    providerCapability: ProviderCapability,
-  ): ReadonlyArray<FrontendWebsiteProviderModule>;
+/**
+ * The website's provider registry — now composed from BOTH channels.
+ *
+ * It used to build itself by casting each served `FrontendProviderEntry` to a
+ * module type that was an alias of that entry, which made the cast true and
+ * useless: the registry could never hold anything a JSON payload could not
+ * carry, so a provider's SDK loader had nowhere to arrive.
+ *
+ *   - **DATA** — the materialized frontend-services block for THIS website
+ *     service. Authoritative for which providers are on, in this environment.
+ *   - **CODE** — `generatedFrontendProviderModules` from the website's own
+ *     `src/generated/frontend-providers.generated.ts`, written by
+ *     `wildo config sync` and handed in by the Astro bridge.
+ *
+ * The types are now the engine's own website-facet types rather than local
+ * aliases, so a provider module authored against
+ * `@wildo-ai/external-connectors-public/website` is the same type this registry
+ * holds. Re-exported under the same names so every consumer's import is
+ * unchanged.
+ */
 
-  findProviderByProviderCapability(
-    providerCapability: ProviderCapability,
-  ): FrontendWebsiteProviderModule | undefined;
+import {
+  composeHydratedFrontendWebsiteProviders,
+  type GeneratedWebsiteProviderModules,
+} from '@wildo-ai/external-connectors-public/website';
+import type { FrontendProvidersBlock } from '@wildo-ai/saas-models/public-runtime';
+import type { FrontendProviderHydrationDiagnostic } from '@wildo-ai/external-connectors-public/website';
+
+export type {
+  FrontendWebsiteProviderModule,
+  FrontendWebsiteProviderRef,
+  FrontendWebsiteProviderRegistry,
+  GeneratedWebsiteProviderModules,
+} from '@wildo-ai/external-connectors-public/website';
+
+import type { FrontendWebsiteProviderRegistry } from '@wildo-ai/external-connectors-public/website';
+
+export interface CreateFrontendWebsiteProviderRegistryInput {
+  /** The DATA channel: the materialized block for this website service. */
+  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.
+   */
+  readonly modules?: GeneratedWebsiteProviderModules;
+  readonly onDiagnostic?: (diagnostic: FrontendProviderHydrationDiagnostic) => void;
 }
 
 /**
- * Website-side public-provider registry hydrated from the materialized
- * frontend-provider bootstrap block.
+ * Website-side public-provider registry, hydrated from both channels.
  */
 export function createFrontendWebsiteProviderRegistry(
-  frontendProviders?: FrontendProvidersBlock,
+  input?: CreateFrontendWebsiteProviderRegistryInput,
 ): FrontendWebsiteProviderRegistry {
-  const modules = new Map<FrontendWebsiteProviderRef, FrontendWebsiteProviderModule>(
-    Object.entries(frontendProviders?.providers ?? {}).map(([ref, provider]) => [
-      ref as FrontendWebsiteProviderRef,
-      provider as FrontendWebsiteProviderModule,
-    ]),
-  );
-
-  return {
-    modules,
-    getProviderByRef(ref: FrontendWebsiteProviderRef) {
-      return modules.get(ref);
-    },
-    getProvidersByProviderCapability(providerCapability: ProviderCapability) {
-      return [...modules.values()].filter((provider) =>
-        provider.providerCapabilities.includes(providerCapability),
-      );
-    },
-    findProviderByProviderCapability(providerCapability: ProviderCapability) {
-      return [...modules.values()].find((provider) =>
-        provider.providerCapabilities.includes(providerCapability),
-      );
-    },
-  };
+  return composeHydratedFrontendWebsiteProviders({
+    entries: input?.entries,
+    modules: input?.modules,
+    onDiagnostic: input?.onDiagnostic,
+  });
 }

package/src/core/external-providers/provider-scripts.website.ts

@@ -0,0 +1,126 @@
+/**
+ * Loading what a website provider actually declared, instead of naming it.
+ *
+ * `FRONTEND_SDK` was a label on this surface. The layout resolved the analytics,
+ * error-monitoring and captcha provider refs and stamped them into `data-*`
+ * attributes on the page root; no consumer loaded anything. A provider could be
+ * declared, enabled, hydrated — and do nothing at all.
+ *
+ * This is the consumer for the DATA half of a provider's executable surface: the
+ * `scripts` it declares (#332). It serves the case a dynamic `import()` cannot,
+ * and it is the dominant case on a marketing site: a vendor that ships a
+ * global-installing `<script>` tag rather than an npm module (reCAPTCHA, tag
+ * managers, chat widgets, and the CDN distributions of most analytics SDKs).
+ *
+ * The npm half — `sdk.activate`, a dynamic import inside the provider package —
+ * needs the CODE channel, which needs this package to depend on
+ * `@wildo-ai/external-connectors-public`. That dependency is not added here; see
+ * the note in the S4a ledger. Nothing below anticipates it: a provider that
+ * declares both gets its scripts from here and its SDK from there.
+ *
+ * ## Client-side injection, and the alternative that was rejected
+ *
+ * This is an Astro static site, so the "obvious" home for a third-party tag is
+ * the built HTML `<head>`. That was rejected for now: the set of live providers
+ * is per SERVICE and per ENVIRONMENT, resolved from the materialized artifact,
+ * while the built HTML is one artifact shared across deploys of the same build.
+ * Baking the tags in would make the build environment-specific — the same class
+ * of coupling the DATA channel exists to avoid. Injecting from the client keeps
+ * one build correct everywhere, at the cost of the tag arriving after hydration.
+ * Revisit if a provider ever needs to run before first paint.
+ */
+
+import type { ProviderFrontendScriptDeclaration } from '@wildo-ai/saas-models/public-runtime';
+import type { FrontendWebsiteProviderRegistry } from './frontend-provider-registry.website';
+
+/**
+ * Marks a `<script>` this module owns, so a re-render, a client-side route
+ * change or a second layout mount finds it instead of appending a duplicate.
+ * A vendor tag loaded twice initialises twice — two analytics clients, two sets
+ * of events — which is the failure mode this attribute exists to prevent.
+ */
+export const PROVIDER_SCRIPT_MARKER_ATTRIBUTE = 'data-wildo-provider-script';
+
+export interface DeclaredProviderScript {
+  readonly providerRef: string;
+  readonly declaration: ProviderFrontendScriptDeclaration;
+}
+
+/**
+ * Every script declared by the providers live on this surface, in registry
+ * order, with the declaring ref kept beside each one so a failure can name it.
+ */
+export function collectDeclaredProviderScripts(
+  registry: FrontendWebsiteProviderRegistry | undefined,
+): ReadonlyArray<DeclaredProviderScript> {
+  if (registry === undefined) return [];
+
+  const collected: DeclaredProviderScript[] = [];
+  for (const provider of registry.modules.values()) {
+    for (const declaration of provider.scripts ?? []) {
+      collected.push({ providerRef: provider.metadata.ref, declaration });
+    }
+  }
+  return collected;
+}
+
+export interface InjectProviderScriptsResult {
+  /** Refs whose script this call added. */
+  readonly injected: ReadonlyArray<string>;
+  /** Refs whose script was already present, so nothing was added. */
+  readonly alreadyPresent: ReadonlyArray<string>;
+}
+
+/**
+ * Adds each declared script to the document, once.
+ *
+ * Idempotent by `src`: a declaration whose element is already in the document is
+ * skipped. Callers may therefore run this on every mount without tracking state.
+ *
+ * `async` defaults to TRUE when the declaration says nothing. A third-party tag
+ * that blocks parsing is the single most common way an analytics provider costs
+ * a marketing site its paint metrics, and a provider author who has not thought
+ * about it should get the safe answer rather than the blocking one.
+ */
+export function injectProviderScripts(
+  scripts: ReadonlyArray<DeclaredProviderScript>,
+  targetDocument: Document,
+): InjectProviderScriptsResult {
+  const injected: string[] = [];
+  const alreadyPresent: string[] = [];
+
+  for (const { providerRef, declaration } of scripts) {
+    // Matched by reading the attribute rather than by a selector carrying the
+    // URL: a `src` can contain characters a CSS selector would have to escape,
+    // and an escaping bug here would show up as a duplicated vendor tag — two
+    // analytics clients, two sets of events — rather than as an error.
+    const existing = [
+      ...targetDocument.querySelectorAll(`script[${PROVIDER_SCRIPT_MARKER_ATTRIBUTE}]`),
+    ].some((element) => element.getAttribute('src') === declaration.src);
+    if (existing) {
+      alreadyPresent.push(providerRef);
+      continue;
+    }
+
+    const element = targetDocument.createElement('script');
+    element.src = declaration.src;
+    element.setAttribute(PROVIDER_SCRIPT_MARKER_ATTRIBUTE, providerRef);
+
+    if (declaration.integrity !== undefined) {
+      element.integrity = declaration.integrity;
+    }
+    if (declaration.crossOrigin !== undefined) {
+      element.crossOrigin = declaration.crossOrigin;
+    }
+    // Both flags are set explicitly rather than left to the element's defaults:
+    // a dynamically created script is `async` by default, so `defer: true` alone
+    // would be silently ignored without the paired `async = false`.
+    element.async = declaration.async ?? declaration.defer !== true;
+    element.defer = declaration.defer ?? false;
+
+    targetDocument.head.appendChild(element);
+    injected.push(providerRef);
+  }
+
+  return { injected, alreadyPresent };
+}

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

@@ -0,0 +1,92 @@
+/**
+ * The website's executable-surface hooks: load what the live providers declared.
+ *
+ * Two mechanisms, one per kind of vendor. `useWebsiteProviderScripts` adds the
+ * `<script>` tags a provider declared — the case a dynamic `import()` cannot
+ * serve, and the dominant one on a marketing site. `useWebsiteProviderSdks`
+ * activates the npm SDK of any provider that ships one, which reaches this
+ * bundle through the CODE channel.
+ *
+ * Both are effect-only, and that is not incidental: this is an Astro site, so
+ * page modules execute in Node at build time. Injecting into a document that
+ * does not exist would throw, and starting a vendor SDK there would run a live
+ * analytics client inside a build.
+ *
+ * SDK activation comes from `@wildo-ai/external-connectors-public/website`, which
+ * this package now depends on. The script injector beside it does NOT yet, and
+ * that is a timing artifact rather than a decision: it belongs in the same
+ * package so the technical doc can use one copy — a second copy of a DOM
+ * mutation eventually disagrees about idempotence, which is how a vendor tag
+ * gets loaded twice. Moving it needs that package's `dist` to carry it, and no
+ * watcher is running in this tree; consolidating it is a one-step follow-up, not
+ * a design question.
+ */
+
+import { useEffect } from 'react';
+import {
+  activateFrontendProviderSdks,
+  type ActivatedFrontendProviderSdks,
+} from '@wildo-ai/external-connectors-public/website';
+import {
+  collectDeclaredProviderScripts,
+  injectProviderScripts,
+} from './provider-scripts.website';
+import { AppFrontendType } from '@wildo-ai/saas-models/public-runtime';
+import type { FrontendWebsiteProviderRegistry } from './frontend-provider-registry.website';
+
+export function useWebsiteProviderScripts(
+  registry: FrontendWebsiteProviderRegistry | undefined,
+): void {
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+
+    const scripts = collectDeclaredProviderScripts(registry);
+    if (scripts.length === 0) return;
+
+    injectProviderScripts(scripts, document);
+    // Deliberately no teardown. A vendor tag installs a global and often starts
+    // work immediately; removing the element undoes neither, so a cleanup that
+    // removed it would only make the next mount inject a SECOND copy of an
+    // already-running script. Idempotence by `src` is the real guard.
+  }, [registry]);
+}
+
+/**
+ * Loads and starts the npm SDK of every live provider that declares one.
+ *
+ * Unlike a script tag, an SDK activation IS undone on unmount where the vendor
+ * offers a teardown — an analytics client that cannot be stopped cannot honour
+ * a consent withdrawal, and accumulates one instance per view transition.
+ */
+export function useWebsiteProviderSdks(
+  registry: FrontendWebsiteProviderRegistry | undefined,
+): void {
+  useEffect(() => {
+    if (registry === undefined) return;
+
+    let unmounted = false;
+    let activated: ActivatedFrontendProviderSdks | undefined;
+
+    void activateFrontendProviderSdks({
+      surface: AppFrontendType.STATIC_WEBSITE,
+      modules: registry.modules.values(),
+      onDiagnostic: (diagnostic) => {
+        // The website runtime has no logger service, and a provider that cannot
+        // start is a developer-facing fact that must not be silent.
+        // eslint-disable-next-line no-console
+        console.warn(`[wildo-provider-sdk] ${diagnostic.kind}: ${diagnostic.message}`);
+      },
+    }).then((result) => {
+      activated = result;
+      // Activation is asynchronous and unmount is not: if the surface went away
+      // while a vendor bundle was still downloading, stop what we just started
+      // rather than leaving a client nobody can reach.
+      if (unmounted) void result.deactivateAll();
+    });
+
+    return () => {
+      unmounted = true;
+      void activated?.deactivateAll();
+    };
+  }, [registry]);
+}

package/src/core/layouts/WebsitePageLayout.tsx

@@ -2,6 +2,10 @@ import React, { useMemo, type ReactNode } from 'react';
 import { BUILTIN_PROVIDER_CAPABILITY } from '@wildo-ai/saas-models/public-runtime';
 
 import { WebsitePageContextProvider } from '../contexts/WebsitePageContext';
+import {
+  useWebsiteProviderScripts,
+  useWebsiteProviderSdks,
+} from '../external-providers/useWebsiteProviderScripts';
 import type { WebsitePageContextValue } from '../contexts/WebsitePageContext';
 import { useWebsiteRuntime } from '../contexts/useWebsiteRuntime';
 import { useWebsiteLabelByKey } from '../hooks/useWebsiteLabel';
@@ -232,6 +236,13 @@ export function WebsitePageLayout({
     return <FooterComponent />;
   }, [footer, runtime.navigation.footerComponent]);
 
+  // Load whatever the live providers declared. Until this landed, the surface
+  // resolved provider refs and stamped them into the attributes below and
+  // stopped there — a provider could be declared, enabled and hydrated without
+  // anything of it ever running.
+  useWebsiteProviderScripts(runtime.frontendProviderRegistry);
+  useWebsiteProviderSdks(runtime.frontendProviderRegistry);
+
   const providerRootAttributes = useMemo<Record<string, string>>(() => {
     const attrs: Record<string, string> = {};
     const productAnalyticsProviderRef = runtime.frontendProviderRegistry