@owlmeans/web-gtm 0.1.18-rc.25 → 0.1.18-rc.26

package/README.md

@@ -6,7 +6,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.32
+npx @owlmeans/agent-skills@^0.1.18-rc.33
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/web-gtm",
-  "version": "0.1.18-rc.25",
-  "generatedAt": "2026-09-22T12:36:21.790Z",
+  "version": "0.1.18-rc.26",
+  "generatedAt": "2026-09-22T17:37:10.898Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/web-gtm/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/web-gtm
 
 **Layer:** Web
-**Install:** `"@owlmeans/web-gtm": "^0.1.18-rc.25"` in `dependencies`
+**Install:** `"@owlmeans/web-gtm": "^0.1.18-rc.26"` in `dependencies`
 
 The tag half of the consent set. It emits **strings and data**, not components, and it holds no
 state — the decision lives in `@owlmeans/consent`, which this package reads through
@@ -25,20 +25,51 @@ for the window that matters*, and nothing in the page reports it.
 So every head snippet here emits the consent bootstrap first and the loader after it, as ONE
 inline script. Everything else in this package exists to serve that.
 
+## Loading mode: gated by default
+
+`googleTagHeadScript`, `gtmHeadScript` and `loadGtm` all take an optional `mode:
+'basic' | 'advanced'`, defaulting to `GOOGLE_TAG_DEFAULT_MODE` — currently `'basic'`, one named
+constant so flipping the platform default later is a one-line change:
+
+| `mode` | What runs, and when |
+|---|---|
+| `'basic'` (default) | The bootstrap and the ads-redaction flags still run unconditionally — Consent Mode's own denied-by-default signals are declared either way. The LOADER itself — `gtm.js`, or `gtag/js` + `js` + `config` — is wrapped in `@owlmeans/consent`'s `consentGateScript`: it runs immediately if the visitor's stored record already `trackingGranted`, and otherwise waits for a later `CONSENT_EVENT` (from `applyConsent`, i.e. an in-page consent decision) that does. Nothing — not even Google's own IP receipt — reaches the tag before a signal-bearing category (`analytics` or `marketing` by default; a `required` or signal-less category never counts) is granted. |
+| `'advanced'` | The original, only behavior before this mode existed: the loader runs immediately, Consent Mode signals denied by default, so the tag itself starts receiving traffic cookielessly from first paint. This is Google's own recommended default for its conversion modeling, and remains available for a site that has decided that tradeoff is acceptable. |
+
+Read `'basic'`'s default as the EU/DE worst-case reading of ePrivacy Art. 5(3): no third party
+receives a connection before consent.
+
+`gtmNoscriptFrame` returns `''` in `'basic'` mode rather than an iframe — a browser with JavaScript
+disabled cannot have granted anything, so an unauthenticated `<noscript>` frame would defeat the
+whole point of gating. It keeps emitting the iframe in `'advanced'` mode, unchanged.
+
+`loadGtm` gates the same way at the DOM level: it still calls `consentStore.init(opts)` first, but
+only appends the container's `<script>` element once `trackingGranted(consentStore.get().record,
+opts.categories)` is true — immediately if already granted, or via a one-shot `consentStore.subscribe`
+that unsubscribes itself on the first update where it becomes true. The anti-double-load guard (the
+element's own id) is unchanged.
+
+None of this is new state: it is one more consumer of `@owlmeans/consent`'s existing surface —
+`trackingGranted(record, categories)` (whether a stored/applied record grants a signal-bearing,
+non-required category) and `consentGateScript(loaderExpr, opts)` (the inline script implementing the
+"run now or wait for `CONSENT_EVENT`" branch). Both live in `@owlmeans/consent`, not here, because a
+target project's own custom loader can reuse the same gate without depending on this package.
+
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `googleTagHeadScript(opts)` | The inline `<head>` script for any Google id: consent bootstrap, ads redaction, then the loader the prefix calls for. **The default for new code** |
+| `googleTagHeadScript(opts)` | The inline `<head>` script for any Google id: consent bootstrap, ads redaction, then the loader the prefix calls for — gated behind `consentGateScript` in `opts.mode`'s default, `'basic'`. **The default for new code** |
 | `isGoogleTagId(id)` / `googleTagKind(id)` | Whether an id is loadable, and whether it takes `gtm` (container) or `gtag` (gtag.js); `null` for anything else |
-| `GoogleTagOptions` / `GoogleTagKind` | `ConsentOptions` plus `id` and optional `dataLayerName`; `'gtm' \| 'gtag'` |
+| `GoogleTagOptions` / `GoogleTagKind` | `ConsentOptions` plus `id`, optional `dataLayerName` and `mode`; `'gtm' \| 'gtag'` |
+| `GoogleTagMode` / `GOOGLE_TAG_DEFAULT_MODE` | `'basic' \| 'advanced'`; the platform default, `'basic'` — see **Loading mode** below |
 | `GOOGLE_TAG_CSP_SOURCES` | The hosts GA4, Tag Manager and Google Ads need in `script-src`, `connect-src` and `img-src` (7, frozen) |
 | `GOOGLE_TAG_FRAME_SOURCES` | The hosts they frame, for `frame-src`: `https://www.googletagmanager.com`, `https://td.doubleclick.net` |
 | `googleTagServices(id)` | The `ConsentService[]` a cookie policy discloses for that tag — pass to `CookiePolicy`'s `services` |
-| `gtmHeadScript(opts)` | The container-only snippet: consent defaults, stored decision, then `gtm.js` |
-| `gtmNoscriptFrame(opts)` | The hidden `<noscript>` iframe, for the top of `<body>` |
-| `loadGtm(opts)` | Script-side container load, for a host that cannot emit into its own head |
-| `GtmOptions` | `ConsentOptions` plus `id` (e.g. `GTM-XXXXXXX`) and optional `dataLayerName` |
+| `gtmHeadScript(opts)` | The container-only snippet: consent defaults, stored decision, then `gtm.js` — gated the same way as `googleTagHeadScript` |
+| `gtmNoscriptFrame(opts)` | The hidden `<noscript>` iframe, for the top of `<body>` — `''` in `'basic'` mode |
+| `loadGtm(opts)` | Script-side container load, for a host that cannot emit into its own head — gated the same way |
+| `GtmOptions` | `ConsentOptions` plus `id` (e.g. `GTM-XXXXXXX`), optional `dataLayerName` and `mode` |
 
 ## Ids
 
@@ -64,11 +95,14 @@ Lower case is rejected rather than folded; normalise in the form if you want to
    owns it, so app code can send events), `js`, `config`, and the gtag.js `<script async>`
    element created from the inline script — one inline script rather than Google's two elements,
    so a build stamps one thing. The element carries id `owl-gtag-<id>`, so running the snippet
-   twice configures the tag once instead of double-counting page views.
+   twice configures the tag once instead of double-counting page views. In `mode`'s default,
+   `'basic'`, this whole step 3 is what `consentGateScript` withholds — steps 1 and 2 always run;
+   pass `mode: 'advanced'` to run step 3 unconditionally too, as before this mode existed.
 
-An **invalid id yields the consent bootstrap alone** — a mistyped tag must never cost a page its
-consent defaults. So a host may stamp `googleTagHeadScript({ id: configured })` unconditionally,
-or stamp `consentBootstrapScript()` when no tag is configured; both are correct.
+An **invalid id yields the consent bootstrap alone, regardless of `mode`** — a mistyped tag must
+never cost a page its consent defaults. So a host may stamp `googleTagHeadScript({ id: configured
+})` unconditionally, or stamp `consentBootstrapScript()` when no tag is configured; both are
+correct.
 
 **The output is safe to place inline in HTML as-is.** JSON encoding keeps configured values inside
 their string literals, but the HTML parser ends a script element at the first `</script` wherever
@@ -148,7 +182,13 @@ cookie page does so when a Google tag is set. The strings are English data, not
 - **`loadGtm` is the fallback, not the default.** It is for a single-page app whose HTML is not
   yours to edit. It still pushes the defaults first (through `consentStore.init`) and refuses to
   load a second time — it marks its own `<script>` element with an id derived from the container —
-  but it runs after the bundle, which is exactly the window the head snippet closes.
+  but it runs after the bundle, which is exactly the window the head snippet closes. In `'basic'`
+  mode it additionally withholds the element itself until `trackingGranted`, same as the head
+  snippets.
+- **The default flipped to `'basic'`.** Code written before this mode existed called
+  `googleTagHeadScript({ id })` / `gtmHeadScript({ id })` expecting the tag to load unconditionally.
+  It now gates by default; pass `mode: 'advanced'` explicitly to keep the old behavior for a site
+  that has made that call deliberately.
 - **A second `consent/default` after a tag has loaded can WIDEN what was already narrowed**, so the
   bootstrap is idempotent through a window flag. A page may therefore carry the call twice — once
   inline, once from the bundle that mounts the dialog — without harm. Do not defeat the flag.
@@ -158,7 +198,8 @@ cookie page does so when a Google tag is set. The strings are English data, not
 ## Depends On
 
 - `@owlmeans/consent` — `consentBootstrapScript`, `consentStore`, `ConsentOptions`,
-  `ConsentService`, the category keys and the Consent Mode signal mapping
+  `ConsentService`, the category keys and the Consent Mode signal mapping, plus (for the `'basic'`
+  gated mode) `consentGateScript` and `trackingGranted`
 
 ## Related
 

package/build/index.d.ts

@@ -1,9 +1,27 @@
 import type { ConsentOptions, ConsentService } from '@owlmeans/consent';
+/** `'gtm'` container / `'gtag'` — see {@link GtmOptions.mode} / {@link GoogleTagOptions.mode}. */
+export type GoogleTagMode = 'basic' | 'advanced';
+/**
+ * The platform default for {@link GtmOptions.mode} / {@link GoogleTagOptions.mode}.
+ *
+ * One named constant so flipping it later is a one-line change.
+ *
+ * - `'basic'` withholds the loader until a signal-bearing category is granted — which holds back
+ *   Google's own IP receipt too, not only what a granted tag may then do with it.
+ * - `'advanced'` loads immediately with Consent Mode signals denied — today's only behavior, and
+ *   Google's own recommended default for its own conversion modeling.
+ *
+ * Default is `'basic'`: read it as the EU/DE worst-case reading of ePrivacy Art. 5(3) — no third
+ * party receives a connection before consent.
+ */
+export declare const GOOGLE_TAG_DEFAULT_MODE: GoogleTagMode;
 export interface GtmOptions extends ConsentOptions {
     /** Container id, e.g. `GTM-XXXXXXX`. */
     id: string;
     /** The queue name, when a page runs more than one container. */
     dataLayerName?: string;
+    /** See {@link GOOGLE_TAG_DEFAULT_MODE}. Defaults to `GOOGLE_TAG_DEFAULT_MODE` (`'basic'`). */
+    mode?: GoogleTagMode;
 }
 /**
  * The inline `<head>` snippet, consent first and the container second.
@@ -15,9 +33,20 @@ export interface GtmOptions extends ConsentOptions {
  * the window that matters, and nothing in the page reports it.
  *
  * Emit this into the document head, above everything else, as an inline script.
+ *
+ * In `GOOGLE_TAG_DEFAULT_MODE` (`'basic'`) the container is not requested at all until a
+ * signal-bearing category is granted — {@link consentGateScript} wraps it, reading any stored
+ * decision immediately and otherwise waiting for `@owlmeans/consent`'s `CONSENT_EVENT`. Pass
+ * `mode: 'advanced'` for the original, unconditional load.
  */
 export declare const gtmHeadScript: (opts: GtmOptions) => string;
-/** The `<noscript>` iframe, for the body. */
+/**
+ * The `<noscript>` iframe, for the body.
+ *
+ * In `'basic'` mode this is an empty string: the whole point of gating is that an unauthenticated
+ * `<noscript>` iframe would defeat it — a browser with JavaScript disabled cannot have granted
+ * anything, so there is nothing lawful left to render. `'advanced'` keeps the frame.
+ */
 export declare const gtmNoscriptFrame: (opts: GtmOptions) => string;
 /**
  * Load the container from script, for a host that cannot emit into its own head.
@@ -25,6 +54,11 @@ export declare const gtmNoscriptFrame: (opts: GtmOptions) => string;
  * The head snippet is strictly better and should be preferred; this exists for a single-page app
  * whose HTML is not ours to edit. It still pushes the defaults first, and it still refuses to load
  * a second time.
+ *
+ * In `'basic'` mode the container element is not appended until `trackingGranted` is true: either
+ * the stored record already grants it, or — since this runs after the bundle mounted, past the
+ * window the head snippet exists to close — a subscription to `consentStore` catches the first
+ * update where it becomes true and unsubscribes. `'advanced'` appends it immediately, as before.
  */
 export declare const loadGtm: (opts: GtmOptions) => void;
 /**
@@ -46,6 +80,8 @@ export interface GoogleTagOptions extends ConsentOptions {
      * given another queue never hears a consent command. Leave it unset on a consent-gated page.
      */
     dataLayerName?: string;
+    /** See {@link GOOGLE_TAG_DEFAULT_MODE}. Defaults to `GOOGLE_TAG_DEFAULT_MODE` (`'basic'`). */
+    mode?: GoogleTagMode;
 }
 /**
  * The one inline `<head>` script for a Google tag of any kind: the consent bootstrap FIRST, then
@@ -60,6 +96,14 @@ export interface GoogleTagOptions extends ConsentOptions {
  * An id that is not a loadable id ({@link isGoogleTagId}) yields the consent bootstrap alone — a
  * page must never lose its consent defaults because someone mistyped a tag. The result is safe to
  * place inline in HTML as-is: `</` and `<!--` inside any configured value are escaped.
+ *
+ * In `GOOGLE_TAG_DEFAULT_MODE` (`'basic'`) the loader itself — the last piece — is wrapped in
+ * `consentGateScript`: it runs immediately for a returning visitor whose stored record already
+ * grants a signal-bearing category, and otherwise waits for `@owlmeans/consent`'s `CONSENT_EVENT`
+ * before ever requesting the tag. The bootstrap and the redaction flags are unaffected and still
+ * run unconditionally — Consent Mode's OWN denied-by-default signals are declared either way, so a
+ * tag that later does load still starts from `ad_storage`/`analytics_storage` denied. Pass
+ * `mode: 'advanced'` for the original, unconditional load.
  */
 export declare const googleTagHeadScript: (opts: GoogleTagOptions) => string;
 /**

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvE,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAA;IACV,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAYD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,SAAU,UAAU,KAAG,MACoD,CAAA;AAErG,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB,SAAU,UAAU,KAAG,MAEsB,CAAA;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,SAAU,UAAU,KAAG,IAkB1C,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAA;AAc1C,sFAAsF;AACtF,eAAO,MAAM,aAAa,OAAQ,MAAM,KAAG,OACO,CAAA;AAElD,4EAA4E;AAC5E,eAAO,MAAM,aAAa,OAAQ,MAAM,KAAG,aAAa,GAAG,IACS,CAAA;AAEpE,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAyDD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,SAAU,gBAAgB,KAAG,MAU5D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAQlD,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAGpD,CAAA;AAkBF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,OAAQ,MAAM,KAAG,cAAc,EA8C5D,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvE,kGAAkG;AAClG,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,CAAA;AAEhD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,EAAE,aAAuB,CAAA;AAE7D,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAA;IACV,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,8FAA8F;IAC9F,IAAI,CAAC,EAAE,aAAa,CAAA;CACrB;AAYD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,SAAU,UAAU,KAAG,MAShD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,SAAU,UAAU,KAAG,MAOnD,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,SAAU,UAAU,KAAG,IA0C1C,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAA;AAc1C,sFAAsF;AACtF,eAAO,MAAM,aAAa,OAAQ,MAAM,KAAG,OACO,CAAA;AAElD,4EAA4E;AAC5E,eAAO,MAAM,aAAa,OAAQ,MAAM,KAAG,aAAa,GAAG,IACS,CAAA;AAEpE,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,8FAA8F;IAC9F,IAAI,CAAC,EAAE,aAAa,CAAA;CACrB;AAyDD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB,SAAU,gBAAgB,KAAG,MAe5D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAQlD,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAGpD,CAAA;AAkBF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,OAAQ,MAAM,KAAG,cAAc,EA8C5D,CAAA"}

package/build/index.js

@@ -1,4 +1,18 @@
-import { CONSENT_ANALYTICS, CONSENT_MARKETING, consentBootstrapScript, consentStore, } from '@owlmeans/consent';
+import { CONSENT_ANALYTICS, CONSENT_MARKETING, consentBootstrapScript, consentGateScript, consentStore, trackingGranted, } from '@owlmeans/consent';
+/**
+ * The platform default for {@link GtmOptions.mode} / {@link GoogleTagOptions.mode}.
+ *
+ * One named constant so flipping it later is a one-line change.
+ *
+ * - `'basic'` withholds the loader until a signal-bearing category is granted — which holds back
+ *   Google's own IP receipt too, not only what a granted tag may then do with it.
+ * - `'advanced'` loads immediately with Consent Mode signals denied — today's only behavior, and
+ *   Google's own recommended default for its own conversion modeling.
+ *
+ * Default is `'basic'`: read it as the EU/DE worst-case reading of ePrivacy Art. 5(3) — no third
+ * party receives a connection before consent.
+ */
+export const GOOGLE_TAG_DEFAULT_MODE = 'basic';
 /** Google's own container IIFE, the id and queue name injected as JSON data. */
 const gtmContainerScript = (layer, id) => `(function(w,d,s,l,i){w[l]=w[l]||[];` +
     `w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});` +
@@ -17,17 +31,45 @@ const gtmContainerScript = (layer, id) => `(function(w,d,s,l,i){w[l]=w[l]||[];`
  * the window that matters, and nothing in the page reports it.
  *
  * Emit this into the document head, above everything else, as an inline script.
+ *
+ * In `GOOGLE_TAG_DEFAULT_MODE` (`'basic'`) the container is not requested at all until a
+ * signal-bearing category is granted — {@link consentGateScript} wraps it, reading any stored
+ * decision immediately and otherwise waiting for `@owlmeans/consent`'s `CONSENT_EVENT`. Pass
+ * `mode: 'advanced'` for the original, unconditional load.
  */
-export const gtmHeadScript = (opts) => `${consentBootstrapScript(opts)};${gtmContainerScript(opts.dataLayerName ?? 'dataLayer', opts.id)}`;
-/** The `<noscript>` iframe, for the body. */
-export const gtmNoscriptFrame = (opts) => `<iframe src="https://www.googletagmanager.com/ns.html?id=${encodeURIComponent(opts.id)}"` +
-    ` height="0" width="0" style="display:none;visibility:hidden"></iframe>`;
+export const gtmHeadScript = (opts) => {
+    const bootstrap = consentBootstrapScript(opts);
+    const loader = gtmContainerScript(opts.dataLayerName ?? 'dataLayer', opts.id);
+    if ((opts.mode ?? GOOGLE_TAG_DEFAULT_MODE) === 'basic') {
+        return `${bootstrap};${consentGateScript(loader, opts)}`;
+    }
+    return `${bootstrap};${loader}`;
+};
+/**
+ * The `<noscript>` iframe, for the body.
+ *
+ * In `'basic'` mode this is an empty string: the whole point of gating is that an unauthenticated
+ * `<noscript>` iframe would defeat it — a browser with JavaScript disabled cannot have granted
+ * anything, so there is nothing lawful left to render. `'advanced'` keeps the frame.
+ */
+export const gtmNoscriptFrame = (opts) => {
+    if ((opts.mode ?? GOOGLE_TAG_DEFAULT_MODE) === 'basic') {
+        return '';
+    }
+    return `<iframe src="https://www.googletagmanager.com/ns.html?id=${encodeURIComponent(opts.id)}"` +
+        ` height="0" width="0" style="display:none;visibility:hidden"></iframe>`;
+};
 /**
  * Load the container from script, for a host that cannot emit into its own head.
  *
  * The head snippet is strictly better and should be preferred; this exists for a single-page app
  * whose HTML is not ours to edit. It still pushes the defaults first, and it still refuses to load
  * a second time.
+ *
+ * In `'basic'` mode the container element is not appended until `trackingGranted` is true: either
+ * the stored record already grants it, or — since this runs after the bundle mounted, past the
+ * window the head snippet exists to close — a subscription to `consentStore` catches the first
+ * update where it becomes true and unsubscribes. `'advanced'` appends it immediately, as before.
  */
 export const loadGtm = (opts) => {
     if (typeof document === 'undefined') {
@@ -39,13 +81,32 @@ export const loadGtm = (opts) => {
     }
     // Defaults before the container, every time — the same rule the head snippet exists to keep.
     consentStore.init(opts);
-    const layer = opts.dataLayerName ?? 'dataLayer';
-    const script = document.createElement('script');
-    script.id = marker;
-    script.async = true;
-    script.src = `https://www.googletagmanager.com/gtm.js?id=${encodeURIComponent(opts.id)}`
-        + (layer !== 'dataLayer' ? `&l=${encodeURIComponent(layer)}` : '');
-    document.head.appendChild(script);
+    const inject = () => {
+        if (document.getElementById(marker) != null) {
+            return;
+        }
+        const layer = opts.dataLayerName ?? 'dataLayer';
+        const script = document.createElement('script');
+        script.id = marker;
+        script.async = true;
+        script.src = `https://www.googletagmanager.com/gtm.js?id=${encodeURIComponent(opts.id)}`
+            + (layer !== 'dataLayer' ? `&l=${encodeURIComponent(layer)}` : '');
+        document.head.appendChild(script);
+    };
+    if ((opts.mode ?? GOOGLE_TAG_DEFAULT_MODE) !== 'basic') {
+        inject();
+        return;
+    }
+    if (trackingGranted(consentStore.get().record, opts.categories)) {
+        inject();
+        return;
+    }
+    const unsubscribe = consentStore.subscribe(state => {
+        if (trackingGranted(state.record, opts.categories)) {
+            unsubscribe();
+            inject();
+        }
+    });
 };
 /**
  * The id shapes Google issues today, and nothing else.
@@ -121,6 +182,14 @@ const gtagScript = (layer, id) => `(function(w,d,l,i){var m='owl-gtag-'+i;if(d.g
  * An id that is not a loadable id ({@link isGoogleTagId}) yields the consent bootstrap alone — a
  * page must never lose its consent defaults because someone mistyped a tag. The result is safe to
  * place inline in HTML as-is: `</` and `<!--` inside any configured value are escaped.
+ *
+ * In `GOOGLE_TAG_DEFAULT_MODE` (`'basic'`) the loader itself — the last piece — is wrapped in
+ * `consentGateScript`: it runs immediately for a returning visitor whose stored record already
+ * grants a signal-bearing category, and otherwise waits for `@owlmeans/consent`'s `CONSENT_EVENT`
+ * before ever requesting the tag. The bootstrap and the redaction flags are unaffected and still
+ * run unconditionally — Consent Mode's OWN denied-by-default signals are declared either way, so a
+ * tag that later does load still starts from `ad_storage`/`analytics_storage` denied. Pass
+ * `mode: 'advanced'` for the original, unconditional load.
  */
 export const googleTagHeadScript = (opts) => {
     const bootstrap = consentBootstrapScript(opts);
@@ -130,7 +199,11 @@ export const googleTagHeadScript = (opts) => {
     }
     const layer = layerOf(opts);
     const loader = kind === 'gtm' ? gtmContainerScript(layer, opts.id) : gtagScript(layer, opts.id);
-    return inlineSafe(`${bootstrap};${redactionScript(layer)};${loader}`);
+    const redaction = redactionScript(layer);
+    if ((opts.mode ?? GOOGLE_TAG_DEFAULT_MODE) === 'basic') {
+        return inlineSafe(`${bootstrap};${redaction};${consentGateScript(loader, opts)}`);
+    }
+    return inlineSafe(`${bootstrap};${redaction};${loader}`);
 };
 /**
  * The hosts a page running a Google tag has to allow in `script-src`, `connect-src` and

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/web-gtm",
-  "version": "0.1.18-rc.25",
+  "version": "0.1.18-rc.26",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,7 +22,7 @@
     }
   },
   "dependencies": {
-    "@owlmeans/consent": "^0.1.18-rc.5"
+    "@owlmeans/consent": "^0.1.18-rc.6"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/src/index.ts

@@ -1,13 +1,34 @@
 import {
-  CONSENT_ANALYTICS, CONSENT_MARKETING, consentBootstrapScript, consentStore,
+  CONSENT_ANALYTICS, CONSENT_MARKETING, consentBootstrapScript, consentGateScript, consentStore,
+  trackingGranted,
 } from '@owlmeans/consent'
 import type { ConsentOptions, ConsentService } from '@owlmeans/consent'
 
+/** `'gtm'` container / `'gtag'` — see {@link GtmOptions.mode} / {@link GoogleTagOptions.mode}. */
+export type GoogleTagMode = 'basic' | 'advanced'
+
+/**
+ * The platform default for {@link GtmOptions.mode} / {@link GoogleTagOptions.mode}.
+ *
+ * One named constant so flipping it later is a one-line change.
+ *
+ * - `'basic'` withholds the loader until a signal-bearing category is granted — which holds back
+ *   Google's own IP receipt too, not only what a granted tag may then do with it.
+ * - `'advanced'` loads immediately with Consent Mode signals denied — today's only behavior, and
+ *   Google's own recommended default for its own conversion modeling.
+ *
+ * Default is `'basic'`: read it as the EU/DE worst-case reading of ePrivacy Art. 5(3) — no third
+ * party receives a connection before consent.
+ */
+export const GOOGLE_TAG_DEFAULT_MODE: GoogleTagMode = 'basic'
+
 export interface GtmOptions extends ConsentOptions {
   /** Container id, e.g. `GTM-XXXXXXX`. */
   id: string
   /** The queue name, when a page runs more than one container. */
   dataLayerName?: string
+  /** See {@link GOOGLE_TAG_DEFAULT_MODE}. Defaults to `GOOGLE_TAG_DEFAULT_MODE` (`'basic'`). */
+  mode?: GoogleTagMode
 }
 
 /** Google's own container IIFE, the id and queue name injected as JSON data. */
@@ -30,14 +51,38 @@ const gtmContainerScript = (layer: string, id: string): string =>
  * the window that matters, and nothing in the page reports it.
  *
  * Emit this into the document head, above everything else, as an inline script.
+ *
+ * In `GOOGLE_TAG_DEFAULT_MODE` (`'basic'`) the container is not requested at all until a
+ * signal-bearing category is granted — {@link consentGateScript} wraps it, reading any stored
+ * decision immediately and otherwise waiting for `@owlmeans/consent`'s `CONSENT_EVENT`. Pass
+ * `mode: 'advanced'` for the original, unconditional load.
  */
-export const gtmHeadScript = (opts: GtmOptions): string =>
-  `${consentBootstrapScript(opts)};${gtmContainerScript(opts.dataLayerName ?? 'dataLayer', opts.id)}`
+export const gtmHeadScript = (opts: GtmOptions): string => {
+  const bootstrap = consentBootstrapScript(opts)
+  const loader = gtmContainerScript(opts.dataLayerName ?? 'dataLayer', opts.id)
 
-/** The `<noscript>` iframe, for the body. */
-export const gtmNoscriptFrame = (opts: GtmOptions): string =>
-  `<iframe src="https://www.googletagmanager.com/ns.html?id=${encodeURIComponent(opts.id)}"` +
-  ` height="0" width="0" style="display:none;visibility:hidden"></iframe>`
+  if ((opts.mode ?? GOOGLE_TAG_DEFAULT_MODE) === 'basic') {
+    return `${bootstrap};${consentGateScript(loader, opts)}`
+  }
+
+  return `${bootstrap};${loader}`
+}
+
+/**
+ * The `<noscript>` iframe, for the body.
+ *
+ * In `'basic'` mode this is an empty string: the whole point of gating is that an unauthenticated
+ * `<noscript>` iframe would defeat it — a browser with JavaScript disabled cannot have granted
+ * anything, so there is nothing lawful left to render. `'advanced'` keeps the frame.
+ */
+export const gtmNoscriptFrame = (opts: GtmOptions): string => {
+  if ((opts.mode ?? GOOGLE_TAG_DEFAULT_MODE) === 'basic') {
+    return ''
+  }
+
+  return `<iframe src="https://www.googletagmanager.com/ns.html?id=${encodeURIComponent(opts.id)}"` +
+    ` height="0" width="0" style="display:none;visibility:hidden"></iframe>`
+}
 
 /**
  * Load the container from script, for a host that cannot emit into its own head.
@@ -45,6 +90,11 @@ export const gtmNoscriptFrame = (opts: GtmOptions): string =>
  * The head snippet is strictly better and should be preferred; this exists for a single-page app
  * whose HTML is not ours to edit. It still pushes the defaults first, and it still refuses to load
  * a second time.
+ *
+ * In `'basic'` mode the container element is not appended until `trackingGranted` is true: either
+ * the stored record already grants it, or — since this runs after the bundle mounted, past the
+ * window the head snippet exists to close — a subscription to `consentStore` catches the first
+ * update where it becomes true and unsubscribes. `'advanced'` appends it immediately, as before.
  */
 export const loadGtm = (opts: GtmOptions): void => {
   if (typeof document === 'undefined') {
@@ -57,13 +107,37 @@ export const loadGtm = (opts: GtmOptions): void => {
   // Defaults before the container, every time — the same rule the head snippet exists to keep.
   consentStore.init(opts)
 
-  const layer = opts.dataLayerName ?? 'dataLayer'
-  const script = document.createElement('script')
-  script.id = marker
-  script.async = true
-  script.src = `https://www.googletagmanager.com/gtm.js?id=${encodeURIComponent(opts.id)}`
-    + (layer !== 'dataLayer' ? `&l=${encodeURIComponent(layer)}` : '')
-  document.head.appendChild(script)
+  const inject = (): void => {
+    if (document.getElementById(marker) != null) {
+      return
+    }
+    const layer = opts.dataLayerName ?? 'dataLayer'
+    const script = document.createElement('script')
+    script.id = marker
+    script.async = true
+    script.src = `https://www.googletagmanager.com/gtm.js?id=${encodeURIComponent(opts.id)}`
+      + (layer !== 'dataLayer' ? `&l=${encodeURIComponent(layer)}` : '')
+    document.head.appendChild(script)
+  }
+
+  if ((opts.mode ?? GOOGLE_TAG_DEFAULT_MODE) !== 'basic') {
+    inject()
+
+    return
+  }
+
+  if (trackingGranted(consentStore.get().record, opts.categories)) {
+    inject()
+
+    return
+  }
+
+  const unsubscribe = consentStore.subscribe(state => {
+    if (trackingGranted(state.record, opts.categories)) {
+      unsubscribe()
+      inject()
+    }
+  })
 }
 
 /**
@@ -102,6 +176,8 @@ export interface GoogleTagOptions extends ConsentOptions {
    * given another queue never hears a consent command. Leave it unset on a consent-gated page.
    */
   dataLayerName?: string
+  /** See {@link GOOGLE_TAG_DEFAULT_MODE}. Defaults to `GOOGLE_TAG_DEFAULT_MODE` (`'basic'`). */
+  mode?: GoogleTagMode
 }
 
 /** A queue name has to be a plain identifier: it becomes `window[name]` in the emitted script. */
@@ -172,6 +248,14 @@ const gtagScript = (layer: string, id: string): string =>
  * An id that is not a loadable id ({@link isGoogleTagId}) yields the consent bootstrap alone — a
  * page must never lose its consent defaults because someone mistyped a tag. The result is safe to
  * place inline in HTML as-is: `</` and `<!--` inside any configured value are escaped.
+ *
+ * In `GOOGLE_TAG_DEFAULT_MODE` (`'basic'`) the loader itself — the last piece — is wrapped in
+ * `consentGateScript`: it runs immediately for a returning visitor whose stored record already
+ * grants a signal-bearing category, and otherwise waits for `@owlmeans/consent`'s `CONSENT_EVENT`
+ * before ever requesting the tag. The bootstrap and the redaction flags are unaffected and still
+ * run unconditionally — Consent Mode's OWN denied-by-default signals are declared either way, so a
+ * tag that later does load still starts from `ad_storage`/`analytics_storage` denied. Pass
+ * `mode: 'advanced'` for the original, unconditional load.
  */
 export const googleTagHeadScript = (opts: GoogleTagOptions): string => {
   const bootstrap = consentBootstrapScript(opts)
@@ -181,8 +265,13 @@ export const googleTagHeadScript = (opts: GoogleTagOptions): string => {
   }
   const layer = layerOf(opts)
   const loader = kind === 'gtm' ? gtmContainerScript(layer, opts.id) : gtagScript(layer, opts.id)
+  const redaction = redactionScript(layer)
+
+  if ((opts.mode ?? GOOGLE_TAG_DEFAULT_MODE) === 'basic') {
+    return inlineSafe(`${bootstrap};${redaction};${consentGateScript(loader, opts)}`)
+  }
 
-  return inlineSafe(`${bootstrap};${redactionScript(layer)};${loader}`)
+  return inlineSafe(`${bootstrap};${redaction};${loader}`)
 }
 
 /**

package/tests/head.spec.ts

@@ -1,17 +1,17 @@
 import { describe, expect, test } from 'bun:test'
-import { CONSENT_KEY } from '@owlmeans/consent'
+import { CONSENT_EVENT, CONSENT_KEY } from '@owlmeans/consent'
 import { gtmHeadScript, gtmNoscriptFrame } from '../src/index.js'
 
 const ID = 'GTM-TESTID1'
 
-describe('@owlmeans/web-gtm — the head snippet', () => {
+describe('@owlmeans/web-gtm — the head snippet ("advanced" mode — the original, unconditional load)', () => {
   test('the consent defaults are declared BEFORE the container is requested', async () => {
     // The entire reason this package exists. Consent Mode decides what a tag may do from the state
     // present when the container loads, so a `consent/default` that arrives after `gtm.js` leaves
     // the page unconfigured for the window that matters — and nothing reports it. Asserted on
     // offsets rather than on presence, because both strings are always present and only the order
     // has ever been wrong.
-    const script = gtmHeadScript({ id: ID })
+    const script = gtmHeadScript({ id: ID, mode: 'advanced' })
 
     const defaults = script.indexOf("'consent','default'")
     const container = script.indexOf('gtm.js')
@@ -22,7 +22,7 @@ describe('@owlmeans/web-gtm — the head snippet', () => {
   })
 
   test('it reads a stored decision, so a returning visitor is not treated as denied', async () => {
-    const script = gtmHeadScript({ id: ID })
+    const script = gtmHeadScript({ id: ID, mode: 'advanced' })
 
     expect(script).toContain(JSON.stringify(CONSENT_KEY))
     expect(script).toContain("'consent','update'")
@@ -36,7 +36,7 @@ describe('@owlmeans/web-gtm — the head snippet', () => {
     // encoding is what keeps a stray quote from closing the literal and turning the rest of an id
     // into executable script — the value still appears verbatim, and that is fine; what matters is
     // that a quote inside it is ESCAPED rather than terminating the string.
-    const script = gtmHeadScript({ id: `${ID}"+alert(1)+"`, dataLayerName: 'owlLayer' })
+    const script = gtmHeadScript({ id: `${ID}"+alert(1)+"`, dataLayerName: 'owlLayer', mode: 'advanced' })
 
     expect(script).toContain(JSON.stringify(`${ID}"+alert(1)+"`))
     expect(script).toContain(JSON.stringify('owlLayer'))
@@ -46,20 +46,46 @@ describe('@owlmeans/web-gtm — the head snippet', () => {
   })
 
   test('a custom queue name is passed to the container', async () => {
-    expect(gtmHeadScript({ id: ID, dataLayerName: 'owlLayer' })).toContain("l!='dataLayer'")
-    expect(gtmHeadScript({ id: ID })).toContain(JSON.stringify('dataLayer'))
+    expect(gtmHeadScript({ id: ID, dataLayerName: 'owlLayer', mode: 'advanced' }))
+      .toContain("l!='dataLayer'")
+    expect(gtmHeadScript({ id: ID, mode: 'advanced' })).toContain(JSON.stringify('dataLayer'))
+  })
+})
+
+describe('@owlmeans/web-gtm — the head snippet ("basic" mode — the default)', () => {
+  test('gtmHeadScript gates the container behind consentGateScript by default', async () => {
+    const script = gtmHeadScript({ id: ID })
+    const advanced = gtmHeadScript({ id: ID, mode: 'advanced' })
+
+    // The container is still IN the script — it's the loader `consentGateScript` withholds, not a
+    // fact removed from the page — but it now sits behind the gate's own listener wiring.
+    expect(script).toContain('gtm.js')
+    expect(script).toContain(JSON.stringify(CONSENT_EVENT))
+    expect(script).toContain('addEventListener')
+    expect(script).not.toEqual(advanced)
+  })
+
+  test('mode: "basic" is the same as omitting mode entirely', async () => {
+    expect(gtmHeadScript({ id: ID })).toBe(gtmHeadScript({ id: ID, mode: 'basic' }))
   })
 })
 
 describe('@owlmeans/web-gtm — the noscript frame', () => {
-  test('it names the container and stays invisible', async () => {
-    const frame = gtmNoscriptFrame({ id: ID })
+  test('"advanced" mode names the container and stays invisible', async () => {
+    const frame = gtmNoscriptFrame({ id: ID, mode: 'advanced' })
 
     expect(frame).toContain(`id=${ID}`)
     expect(frame).toContain('display:none')
   })
 
   test('an id is URL-encoded, so it cannot break out of the attribute', async () => {
-    expect(gtmNoscriptFrame({ id: 'a"b' })).not.toContain('a"b')
+    expect(gtmNoscriptFrame({ id: 'a"b', mode: 'advanced' })).not.toContain('a"b')
+  })
+
+  test('"basic" mode (the default) renders nothing at all', async () => {
+    // The point of gating is defeated by an unauthenticated `<noscript>` iframe: a browser with
+    // JavaScript disabled cannot have granted anything, so there is nothing lawful to frame.
+    expect(gtmNoscriptFrame({ id: ID })).toBe('')
+    expect(gtmNoscriptFrame({ id: ID, mode: 'basic' })).toBe('')
   })
 })

package/tests/tag.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test'
 import {
-  CONSENT_KEY, DEFAULT_CONSENT_CATEGORIES, consentBootstrapScript,
+  CONSENT_EVENT, CONSENT_KEY, DEFAULT_CONSENT_CATEGORIES, consentBootstrapScript,
 } from '@owlmeans/consent'
 import type { ConsentCategory } from '@owlmeans/consent'
 import {
@@ -35,8 +35,18 @@ const browser = (stored?: { key?: string, record: Record<string, unknown> }) =>
     loaded.push(element)
     if (element.id != null) byId.set(element.id, element)
   }
-  const win: Record<string, unknown> = {
+  const listeners = new Map<string, ((event: unknown) => void)[]>()
+  const win: Record<string, unknown> & {
+    addEventListener: (type: string, cb: (event: unknown) => void) => void
+    removeEventListener: (type: string, cb: (event: unknown) => void) => void
+  } = {
     localStorage: { getItem: (key: string) => storage.get(key) ?? null },
+    addEventListener: (type, cb) => {
+      listeners.set(type, [...(listeners.get(type) ?? []), cb])
+    },
+    removeEventListener: (type, cb) => {
+      listeners.set(type, (listeners.get(type) ?? []).filter(listener => listener !== cb))
+    },
   }
   const doc = {
     cookie: '',
@@ -53,6 +63,13 @@ const browser = (stored?: { key?: string, record: Record<string, unknown> }) =>
       // eslint-disable-next-line no-new-func
       new Function('window', 'document', script)(win, doc)
     },
+    /** Fire a `CONSENT_EVENT` the way `applyConsent` does, for the gated ("basic" mode) loader. */
+    grant: (record: Record<string, unknown>) => {
+      for (const cb of listeners.get(CONSENT_EVENT) ?? []) {
+        cb({ detail: { record } })
+      }
+    },
+    listenerCount: (type = CONSENT_EVENT) => listeners.get(type)?.length ?? 0,
     /** The queue as `command:arg` strings; gtm.js's own object entry shows as `event:gtm.js`. */
     queue: (name = 'dataLayer'): string[] =>
       ((win[name] as unknown[] | undefined) ?? []).map(entry => {
@@ -108,9 +125,9 @@ describe('isGoogleTagId / googleTagKind', () => {
   })
 })
 
-describe('googleTagHeadScript — the order', () => {
+describe('googleTagHeadScript — the order ("advanced" mode — the original, unconditional load)', () => {
   test('gtag.js: consent default, then redaction, then js/config, then the library', () => {
-    const script = googleTagHeadScript({ id: 'G-ABCD1234' })
+    const script = googleTagHeadScript({ id: 'G-ABCD1234', mode: 'advanced' })
     const page = browser()
     page.run(script)
 
@@ -133,7 +150,7 @@ describe('googleTagHeadScript — the order', () => {
 
   test('the redaction flags carry the right values', () => {
     const page = browser()
-    page.run(googleTagHeadScript({ id: 'AW-123456789' }))
+    page.run(googleTagHeadScript({ id: 'AW-123456789', mode: 'advanced' }))
     const sets = ((page.win.dataLayer as ArrayLike<unknown>[]) ?? [])
       .map(entry => Array.from(entry))
       .filter(args => args[0] === 'set')
@@ -142,7 +159,7 @@ describe('googleTagHeadScript — the order', () => {
   })
 
   test('Tag Manager: consent default, then redaction, then the container', () => {
-    const script = googleTagHeadScript({ id: 'GTM-ABC1234' })
+    const script = googleTagHeadScript({ id: 'GTM-ABC1234', mode: 'advanced' })
     const page = browser()
     page.run(script)
 
@@ -172,7 +189,7 @@ describe('googleTagHeadScript — the order', () => {
   test('running it twice configures the tag once', () => {
     // Two stampings or a hot reload must not double-count every page view.
     const page = browser()
-    const script = googleTagHeadScript({ id: 'G-ABCD1234' })
+    const script = googleTagHeadScript({ id: 'G-ABCD1234', mode: 'advanced' })
     page.run(script)
     page.run(script)
 
@@ -183,19 +200,19 @@ describe('googleTagHeadScript — the order', () => {
 
   test('window.gtag is published for application events, and never replaced', () => {
     const page = browser()
-    page.run(googleTagHeadScript({ id: 'G-ABCD1234' }))
+    page.run(googleTagHeadScript({ id: 'G-ABCD1234', mode: 'advanced' }))
     expect(typeof page.win.gtag).toBe('function')
 
     const owned = () => undefined
     const other = browser()
     other.win.gtag = owned
-    other.run(googleTagHeadScript({ id: 'G-ABCD1234' }))
+    other.run(googleTagHeadScript({ id: 'G-ABCD1234', mode: 'advanced' }))
     expect(other.win.gtag).toBe(owned)
   })
 
   test('a custom queue is used by the tag and passed to the library', () => {
     const page = browser()
-    page.run(googleTagHeadScript({ id: 'G-ABCD1234', dataLayerName: 'owlLayer' }))
+    page.run(googleTagHeadScript({ id: 'G-ABCD1234', dataLayerName: 'owlLayer', mode: 'advanced' }))
 
     expect(page.queue('owlLayer')).toContain('config:G-ABCD1234')
     expect(page.loaded[0].src).toBe('https://www.googletagmanager.com/gtag/js?id=G-ABCD1234&l=owlLayer')
@@ -203,23 +220,78 @@ describe('googleTagHeadScript — the order', () => {
 
   test('a queue name that is not an identifier falls back to dataLayer', () => {
     const page = browser()
-    page.run(googleTagHeadScript({ id: 'G-ABCD1234', dataLayerName: 'a-b' }))
+    page.run(googleTagHeadScript({ id: 'G-ABCD1234', dataLayerName: 'a-b', mode: 'advanced' }))
 
     expect(page.queue()).toContain('config:G-ABCD1234')
     expect(page.loaded[0].src).toBe('https://www.googletagmanager.com/gtag/js?id=G-ABCD1234')
   })
 })
 
-describe('googleTagHeadScript — an invalid id', () => {
-  test('yields the consent bootstrap alone', () => {
-    // A mistyped tag must never cost the page its consent defaults.
+describe('googleTagHeadScript — "basic" mode (the default)', () => {
+  test('an invalid id still yields only the bootstrap, regardless of mode', () => {
+    // A mistyped tag must never cost the page its consent defaults — in either mode, since an id
+    // this invalid never reaches the gate at all.
     for (const id of ['', 'UA-1234-1', 'G-x"+alert(1)']) {
-      const script = googleTagHeadScript({ id })
+      for (const mode of ['basic', 'advanced'] as const) {
+        const script = googleTagHeadScript({ id, mode })
 
-      expect(script).toBe(consentBootstrapScript({ id } as never))
-      expect(script).not.toContain('googletagmanager')
-      expect(script).not.toContain('ads_data_redaction')
+        expect(script).toBe(consentBootstrapScript({ id } as never))
+        expect(script).not.toContain('googletagmanager')
+        expect(script).not.toContain('ads_data_redaction')
+      }
     }
+    // And omitting `mode` altogether is the same as the default, `'basic'`.
+    expect(googleTagHeadScript({ id: '' })).toBe(googleTagHeadScript({ id: '', mode: 'basic' }))
+  })
+
+  test('a valid id with no stored consent does not load the tag synchronously', () => {
+    const page = browser()
+    page.run(googleTagHeadScript({ id: 'G-ABCD1234' }))
+
+    // The consent bootstrap and the redaction flags still run unconditionally — Consent Mode's
+    // OWN denied-by-default signals are declared either way — but nothing asked for the tag itself.
+    expect(page.queue()).toEqual(['consent:default', 'set:ads_data_redaction', 'set:url_passthrough'])
+    expect(page.loaded).toHaveLength(0)
+    expect(page.listenerCount()).toBe(1)
+  })
+
+  test('it loads once the visitor grants a signal-bearing category, and not before', () => {
+    const page = browser()
+    page.run(googleTagHeadScript({ id: 'G-ABCD1234' }))
+
+    // Denying, or granting only a category with no Consent Mode signal, changes nothing.
+    page.grant({ essential: true, analytics: false, marketing: false })
+    expect(page.loaded).toHaveLength(0)
+
+    page.grant({ essential: true, analytics: true, marketing: false })
+    expect(page.loaded).toHaveLength(1)
+    expect(page.queue().filter(entry => entry.startsWith('config:'))).toEqual(['config:G-ABCD1234'])
+    expect(page.listenerCount()).toBe(0)
+
+    // A later grant does nothing further — the listener already removed itself, and the loader's
+    // own anti-double-load guard would refuse a second run in any case.
+    page.grant({ essential: true, analytics: true, marketing: true })
+    expect(page.loaded).toHaveLength(1)
+  })
+
+  test('a returning visitor with a stored grant loads immediately, with no listener left behind', () => {
+    const page = browser({ record: { essential: true, analytics: true, marketing: false, v: 2 } })
+    page.run(googleTagHeadScript({ id: 'G-ABCD1234' }))
+
+    expect(page.loaded).toHaveLength(1)
+    expect(page.queue().filter(entry => entry.startsWith('config:'))).toEqual(['config:G-ABCD1234'])
+    expect(page.listenerCount()).toBe(0)
+  })
+
+  test('the Tag Manager container is gated the same way', () => {
+    const page = browser()
+    page.run(googleTagHeadScript({ id: 'GTM-ABC1234' }))
+
+    expect(page.loaded).toHaveLength(0)
+
+    page.grant({ essential: true, marketing: true })
+    expect(page.loaded).toHaveLength(1)
+    expect(page.loaded[0].src).toBe('https://www.googletagmanager.com/gtm.js?id=GTM-ABC1234')
   })
 })