@wildo-ai/saas-website 1.1.3 → 1.1.5

package/src/schemas/label-keys/__tests__/scaffolded-consent-label-pack.parity.test.ts

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import { WEBSITE_CONSENT_LABEL_KEYS } from '../website-consent-label-keys.schemas';
+
+/**
+ * The `add-website` scaffold must author EVERY framework-owned consent key.
+ *
+ * ## The failure this exists to stop, measured 2026-09-20
+ *
+ * `WEBSITE_CONSENT_LABEL_KEYS` is what a locale pack must carry, and a pack missing one fails the
+ * site's build rather than showing a visitor a raw key — that refusal is deliberate, and its own
+ * declaration says why: *"a site that adds analytics tomorrow must not ship it with an unlabelled —
+ * or absent — way to refuse."*
+ *
+ * The key set then GREW by four (the always-active row, and one explanation per purpose). The
+ * dogfood site's packs were updated by hand and the SCAFFOLD was not, so every newly composed
+ * website would have shipped four keys short — a scaffold that cannot build, produced by a change
+ * two packages away, with nothing between the two but somebody remembering.
+ *
+ * ## Why a parity test rather than a shared constant
+ *
+ * The template is Handlebars, so no TypeScript can import it and no type can relate the two. That
+ * leaves the same choice this repository has made before for exactly this shape
+ * (`scaffolded-resource-operations.parity.test.ts`): a COPY of a fact, with a test holding the copy
+ * equal to its source. What makes it worth having is the direction of the failure — a missing key is
+ * invisible until somebody composes a site, and the person who composes it is not the person who
+ * added the key.
+ *
+ * It asserts EQUALITY, not containment, in both directions: a key the template authors and the
+ * framework no longer asks for is a label nobody renders, which is the defect `#54` started from.
+ */
+const TEMPLATE_RELATIVE_PATH = 'templates/saas/scenarios/add-website/files/website/src/i18n/en.json.hbs';
+
+function findRepositoryRoot(): string {
+  let directory = dirname(fileURLToPath(import.meta.url));
+  while (!existsSync(join(directory, TEMPLATE_RELATIVE_PATH))) {
+    const parent = dirname(directory);
+    if (parent === directory) throw new Error(`Could not locate ${TEMPLATE_RELATIVE_PATH} above ${fileURLToPath(import.meta.url)}.`);
+    directory = parent;
+  }
+  return directory;
+}
+
+describe('the add-website scaffold’s locale pack', () => {
+  it('authors exactly the consent keys the framework requires of every site', () => {
+    const template = readFileSync(join(findRepositoryRoot(), TEMPLATE_RELATIVE_PATH), 'utf8');
+    const authored = [...template.matchAll(/"(website\.chrome\.consent\.[^"]+)"\s*:/gu)].map((match) => match[1]!);
+
+    /*
+     * Guards the guard: a regex that matched nothing would report perfect agreement with an empty
+     * template, which is the shape `--self-test` exists for everywhere else in this repository.
+     */
+    expect(authored.length, 'the template no longer authors consent keys this test can read').toBeGreaterThan(0);
+
+    const required = WEBSITE_CONSENT_LABEL_KEYS.map((key) => key as unknown as string);
+    expect([...authored].sort()).toEqual([...required].sort());
+  });
+
+  it('gives every authored consent key a non-empty value', () => {
+    // A key present with an empty string satisfies a pack validator and shows a visitor nothing —
+    // the same outcome as the missing key, arrived at through the check rather than around it.
+    const template = readFileSync(join(findRepositoryRoot(), TEMPLATE_RELATIVE_PATH), 'utf8');
+    const entries = [...template.matchAll(/"(website\.chrome\.consent\.[^"]+)"\s*:\s*"([^"]*)"/gu)];
+    expect(entries.length).toBe(WEBSITE_CONSENT_LABEL_KEYS.length);
+    for (const [, key, value] of entries) expect(value!.trim(), `${key!} is authored empty`).not.toBe('');
+  });
+});

package/src/schemas/label-keys/website-consent-label-keys.schemas.ts

@@ -0,0 +1,78 @@
+import { ConsentPurpose, CONSENT_PURPOSES } from '@wildo-ai/saas-models/public-runtime';
+
+import { WebsiteLabelKeySchema, type WebsiteLabelKey } from './website-label-key.schemas';
+
+/**
+ * The label keys the framework's visitor consent surface reads (#534).
+ *
+ * FRAMEWORK-OWNED, like the skip link's key: the consent banner is rendered by `WebsitePageLayout`, not by
+ * the site's chrome, so the site does not list these in `chromeLabelKeys`.
+ * `composeEffectiveChromeLabelKeys` unions them into the label-pack validator's expected set, so a locale
+ * pack missing one fails the build rather than showing a visitor a raw key.
+ *
+ * They are required of every site, including one that runs no consent-based provider today: the words are
+ * cheap, and a site that adds analytics tomorrow must not ship it with an unlabelled — or absent — way to
+ * refuse.
+ *
+ * Purpose names are keyed by the `ConsentPurpose` VALUE and derived from the vocabulary, so a purpose added
+ * to it is a missing label in every site's pack at the next build, not a purpose the banner cannot name.
+ */
+export enum WebsiteConsentLabelSlot {
+  /** Heading of the consent panel. */
+  TITLE = 'title',
+  /** What the panel is for: optional purposes are off until agreed, each chosen separately, changeable later. */
+  DESCRIPTION = 'description',
+  /** Agree to every purpose listed. */
+  ACCEPT_ALL = 'accept-all',
+  /** Agree to none of them — recorded as a choice, so the panel does not return. */
+  DECLINE_ALL = 'decline-all',
+  /** Save exactly the purposes ticked. */
+  SAVE = 'save',
+  /** Re-open the panel to change a choice already made. */
+  MANAGE = 'manage',
+  /**
+   * Name of the row covering what runs whatever the visitor chooses.
+   *
+   * NOT a `ConsentPurpose`, and it must never become one: that vocabulary is what a visitor DECIDES,
+   * and this is the thing they are not being asked about. It is shown because a panel listing only
+   * the optional purposes cannot answer the question a visitor opened it to answer — what is
+   * happening on this site — which is why every specialized consent platform states it.
+   */
+  ESSENTIAL_TITLE = 'essential-title',
+  /** What the always-active row covers, and why its control is checked and cannot be changed. */
+  ESSENTIAL_DESCRIPTION = 'essential-description',
+}
+
+const CONSENT_LABEL_KEY_PREFIX = 'website.chrome.consent';
+
+/** The fully-composed key for one panel slot. */
+export function websiteConsentLabelKey(slot: WebsiteConsentLabelSlot): WebsiteLabelKey {
+  return WebsiteLabelKeySchema.parse(`${CONSENT_LABEL_KEY_PREFIX}.${slot}`);
+}
+
+/** The fully-composed key naming one consent purpose. */
+export function websiteConsentPurposeLabelKey(purpose: ConsentPurpose): WebsiteLabelKey {
+  return WebsiteLabelKeySchema.parse(`${CONSENT_LABEL_KEY_PREFIX}.purpose-${purpose}`);
+}
+
+/**
+ * The key EXPLAINING one consent purpose — what agreeing to it means for this visitor.
+ *
+ * The name above answers *what is it called*; this answers *what will happen to me*, and a choice
+ * made without the second is not an informed one. "Analytics" beside a tick box is a category, not
+ * something a visitor can weigh.
+ *
+ * Derived from the vocabulary exactly as the name is, so a purpose added to `ConsentPurpose` is a
+ * missing label in every site's pack at the next build rather than a row that renders a name with no
+ * explanation beneath it.
+ */
+export function websiteConsentPurposeDescriptionLabelKey(purpose: ConsentPurpose): WebsiteLabelKey {
+  return WebsiteLabelKeySchema.parse(`${CONSENT_LABEL_KEY_PREFIX}.purpose-${purpose}-description`);
+}
+
+/** Every framework-owned consent key — what a locale pack must carry. Total over both vocabularies. */
+export const WEBSITE_CONSENT_LABEL_KEYS: readonly WebsiteLabelKey[] = Object.freeze([
+  ...Object.values(WebsiteConsentLabelSlot).map(websiteConsentLabelKey),
+  ...CONSENT_PURPOSES.map(websiteConsentPurposeLabelKey),
+  ...CONSENT_PURPOSES.map(websiteConsentPurposeDescriptionLabelKey),
+]);

package/dist/esm/core/external-providers/provider-scripts.website.d.ts

@@ -1,68 +0,0 @@
-/**
- * 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 declare 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 declare function collectDeclaredProviderScripts(registry: FrontendWebsiteProviderRegistry | undefined): ReadonlyArray<DeclaredProviderScript>;
-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 declare function injectProviderScripts(scripts: ReadonlyArray<DeclaredProviderScript>, targetDocument: Document): InjectProviderScriptsResult;
-//# sourceMappingURL=provider-scripts.website.d.ts.map

package/dist/esm/core/external-providers/provider-scripts.website.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"provider-scripts.website.d.ts","sourceRoot":"","sources":["../../../../../src/core/external-providers/provider-scripts.website.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,sCAAsC,CAAC;AAC9F,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,sCAAsC,CAAC;AAE5F;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,+BAA+B,CAAC;AAE7E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,iCAAiC,CAAC;CACzD;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,+BAA+B,GAAG,SAAS,GACpD,aAAa,CAAC,sBAAsB,CAAC,CAUvC;AAED,MAAM,WAAW,2BAA2B;IAC1C,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,CAAC,sBAAsB,CAAC,EAC9C,cAAc,EAAE,QAAQ,GACvB,2BAA2B,CAsC7B"}

package/dist/esm/core/external-providers/provider-scripts.website.js

@@ -1,99 +0,0 @@
-/**
- * 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.
- */
-/**
- * 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';
-/**
- * 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) {
-    if (registry === undefined)
-        return [];
-    const collected = [];
-    for (const provider of registry.modules.values()) {
-        for (const declaration of provider.scripts ?? []) {
-            collected.push({ providerRef: provider.metadata.ref, declaration });
-        }
-    }
-    return collected;
-}
-/**
- * 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, targetDocument) {
-    const injected = [];
-    const alreadyPresent = [];
-    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 };
-}
-//# sourceMappingURL=provider-scripts.website.js.map

package/dist/esm/core/external-providers/provider-scripts.website.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"provider-scripts.website.js","sourceRoot":"","sources":["../../../../../src/core/external-providers/provider-scripts.website.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,4BAA4B,CAAC;AAO7E;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAqD;IAErD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAEtC,MAAM,SAAS,GAA6B,EAAE,CAAC;IAC/C,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACjD,KAAK,MAAM,WAAW,IAAI,QAAQ,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;YACjD,SAAS,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,WAAW,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AASD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAA8C,EAC9C,cAAwB;IAExB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,cAAc,GAAa,EAAE,CAAC;IAEpC,KAAK,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,IAAI,OAAO,EAAE,CAAC;QACnD,0EAA0E;QAC1E,2EAA2E;QAC3E,0EAA0E;QAC1E,mEAAmE;QACnE,MAAM,QAAQ,GAAG;YACf,GAAG,cAAc,CAAC,gBAAgB,CAAC,UAAU,gCAAgC,GAAG,CAAC;SAClF,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,WAAW,CAAC,GAAG,CAAC,CAAC;QACrE,IAAI,QAAQ,EAAE,CAAC;YACb,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACjC,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QACvD,OAAO,CAAC,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC;QAC9B,OAAO,CAAC,YAAY,CAAC,gCAAgC,EAAE,WAAW,CAAC,CAAC;QAEpE,IAAI,WAAW,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACxC,OAAO,CAAC,SAAS,GAAG,WAAW,CAAC,SAAS,CAAC;QAC5C,CAAC;QACD,IAAI,WAAW,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YAC1C,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC,WAAW,CAAC;QAChD,CAAC;QACD,4EAA4E;QAC5E,6EAA6E;QAC7E,gEAAgE;QAChE,OAAO,CAAC,KAAK,GAAG,WAAW,CAAC,KAAK,IAAI,WAAW,CAAC,KAAK,KAAK,IAAI,CAAC;QAChE,OAAO,CAAC,KAAK,GAAG,WAAW,CAAC,KAAK,IAAI,KAAK,CAAC;QAE3C,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACzC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;AACtC,CAAC","sourcesContent":["/**\n * Loading what a website provider actually declared, instead of naming it.\n *\n * `FRONTEND_SDK` was a label on this surface. The layout resolved the analytics,\n * error-monitoring and captcha provider refs and stamped them into `data-*`\n * attributes on the page root; no consumer loaded anything. A provider could be\n * declared, enabled, hydrated — and do nothing at all.\n *\n * This is the consumer for the DATA half of a provider's executable surface: the\n * `scripts` it declares (#332). It serves the case a dynamic `import()` cannot,\n * and it is the dominant case on a marketing site: a vendor that ships a\n * global-installing `<script>` tag rather than an npm module (reCAPTCHA, tag\n * managers, chat widgets, and the CDN distributions of most analytics SDKs).\n *\n * The npm half — `sdk.activate`, a dynamic import inside the provider package —\n * needs the CODE channel, which needs this package to depend on\n * `@wildo-ai/external-connectors-public`. That dependency is not added here; see\n * the note in the S4a ledger. Nothing below anticipates it: a provider that\n * declares both gets its scripts from here and its SDK from there.\n *\n * ## Client-side injection, and the alternative that was rejected\n *\n * This is an Astro static site, so the \"obvious\" home for a third-party tag is\n * the built HTML `<head>`. That was rejected for now: the set of live providers\n * is per SERVICE and per ENVIRONMENT, resolved from the materialized artifact,\n * while the built HTML is one artifact shared across deploys of the same build.\n * Baking the tags in would make the build environment-specific — the same class\n * of coupling the DATA channel exists to avoid. Injecting from the client keeps\n * one build correct everywhere, at the cost of the tag arriving after hydration.\n * Revisit if a provider ever needs to run before first paint.\n */\n\nimport type { ProviderFrontendScriptDeclaration } from '@wildo-ai/saas-models/public-runtime';\nimport type { FrontendWebsiteProviderRegistry } from './frontend-provider-registry.website';\n\n/**\n * Marks a `<script>` this module owns, so a re-render, a client-side route\n * change or a second layout mount finds it instead of appending a duplicate.\n * A vendor tag loaded twice initialises twice — two analytics clients, two sets\n * of events — which is the failure mode this attribute exists to prevent.\n */\nexport const PROVIDER_SCRIPT_MARKER_ATTRIBUTE = 'data-wildo-provider-script';\n\nexport interface DeclaredProviderScript {\n  readonly providerRef: string;\n  readonly declaration: ProviderFrontendScriptDeclaration;\n}\n\n/**\n * Every script declared by the providers live on this surface, in registry\n * order, with the declaring ref kept beside each one so a failure can name it.\n */\nexport function collectDeclaredProviderScripts(\n  registry: FrontendWebsiteProviderRegistry | undefined,\n): ReadonlyArray<DeclaredProviderScript> {\n  if (registry === undefined) return [];\n\n  const collected: DeclaredProviderScript[] = [];\n  for (const provider of registry.modules.values()) {\n    for (const declaration of provider.scripts ?? []) {\n      collected.push({ providerRef: provider.metadata.ref, declaration });\n    }\n  }\n  return collected;\n}\n\nexport interface InjectProviderScriptsResult {\n  /** Refs whose script this call added. */\n  readonly injected: ReadonlyArray<string>;\n  /** Refs whose script was already present, so nothing was added. */\n  readonly alreadyPresent: ReadonlyArray<string>;\n}\n\n/**\n * Adds each declared script to the document, once.\n *\n * Idempotent by `src`: a declaration whose element is already in the document is\n * skipped. Callers may therefore run this on every mount without tracking state.\n *\n * `async` defaults to TRUE when the declaration says nothing. A third-party tag\n * that blocks parsing is the single most common way an analytics provider costs\n * a marketing site its paint metrics, and a provider author who has not thought\n * about it should get the safe answer rather than the blocking one.\n */\nexport function injectProviderScripts(\n  scripts: ReadonlyArray<DeclaredProviderScript>,\n  targetDocument: Document,\n): InjectProviderScriptsResult {\n  const injected: string[] = [];\n  const alreadyPresent: string[] = [];\n\n  for (const { providerRef, declaration } of scripts) {\n    // Matched by reading the attribute rather than by a selector carrying the\n    // URL: a `src` can contain characters a CSS selector would have to escape,\n    // and an escaping bug here would show up as a duplicated vendor tag — two\n    // analytics clients, two sets of events — rather than as an error.\n    const existing = [\n      ...targetDocument.querySelectorAll(`script[${PROVIDER_SCRIPT_MARKER_ATTRIBUTE}]`),\n    ].some((element) => element.getAttribute('src') === declaration.src);\n    if (existing) {\n      alreadyPresent.push(providerRef);\n      continue;\n    }\n\n    const element = targetDocument.createElement('script');\n    element.src = declaration.src;\n    element.setAttribute(PROVIDER_SCRIPT_MARKER_ATTRIBUTE, providerRef);\n\n    if (declaration.integrity !== undefined) {\n      element.integrity = declaration.integrity;\n    }\n    if (declaration.crossOrigin !== undefined) {\n      element.crossOrigin = declaration.crossOrigin;\n    }\n    // Both flags are set explicitly rather than left to the element's defaults:\n    // a dynamically created script is `async` by default, so `defer: true` alone\n    // would be silently ignored without the paired `async = false`.\n    element.async = declaration.async ?? declaration.defer !== true;\n    element.defer = declaration.defer ?? false;\n\n    targetDocument.head.appendChild(element);\n    injected.push(providerRef);\n  }\n\n  return { injected, alreadyPresent };\n}\n"]}

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

@@ -1,146 +0,0 @@
-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/provider-scripts.website.ts

@@ -1,126 +0,0 @@
-/**
- * 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 };
-}