@owlmeans/web-gtm 0.1.18-rc.9 → 0.1.18

package/README.md

@@ -1,3 +1,189 @@
+# @owlmeans/web-gtm
+
+The Google tag half of OwlMeans cookie consent. It emits the inline `<head>` script for any Google
+id — Tag Manager (`GTM-`), GA4 (`G-`), Google tag (`GT-`), Google Ads (`AW-`), Floodlight (`DC-`) —
+with the Consent Mode defaults declared **before** the loader runs, plus the id validator, the CSP
+host lists, the cookie-policy disclosure for a tag, the `<noscript>` frame and a script-side loader
+for hosts that cannot edit their HTML. It produces strings and data, holds no state, and reads the
+consent decision from `@owlmeans/consent`. A web app or static site uses it whenever it runs a Google
+tag. It does not render the consent dialog (`@owlmeans/web-consent`) and has no event API — events
+reach `dataLayer` through `@owlmeans/log` with `@owlmeans/web-log`'s `gtmAnalyticsPlugin`. The
+`web-gtm` skill covers this package; the `consent` skill covers the model and ordering rule it
+implements.
+
+## Installation
+
+```bash
+bun add @owlmeans/web-gtm@^0.1.18
+```
+
+## Concepts
+
+- **Order** — a Google tag decides what it may do from the consent state present when it loads. A
+  React bundle always arrives too late, so the head script emits the consent bootstrap first and the
+  loader after it, as one inline script stamped from HTML.
+- **Mode** — `'basic'` (the default, `GOOGLE_TAG_DEFAULT_MODE`) withholds the loader until a
+  signal-bearing, non-required category is granted, from storage or a later `CONSENT_EVENT`.
+  `'advanced'` loads immediately with Consent Mode signals denied.
+- **Bootstrap** — `consentModeHelper.consentBootstrapScript(opts)` from `@owlmeans/consent`: declares
+  `consent/default` and applies a stored decision in the same turn. It runs in both modes.
+- **Kind** — `'gtm'` (container, `gtm.js`) for `GTM-`; `'gtag'` (`gtag/js` + `js` + `config`) for
+  `G-`, `GT-`, `AW-`, `DC-`.
+- **Disclosure** — `ConsentService` entries describing who receives data, derived from the id prefix
+  for `CookiePolicy`'s `services`.
+
+## Usage
+
+### 1. Stamp the head script from HTML
+
+Stamp it first in `<head>`, from the HTML build — never from the application bundle. A Vite app does
+it with a `transformIndexHtml` plugin:
+
+```typescript
+import type { Plugin } from 'vite'
+import { googleTagHelper } from '@owlmeans/web-gtm'
+
+export const googleTagPlugin = (id: string): Plugin => ({
+  name: 'google-tag',
+  transformIndexHtml: html => html.replace(
+    '<!-- google-tag -->',
+    `<script>${googleTagHelper.googleTagHeadScript({ id })}</script>`
+  ),
+})
+```
+
+An invalid or empty id yields the consent bootstrap alone, so the call is safe to make
+unconditionally. The output escapes `</` and `<!--`, so it can be placed inline as-is.
+
+### 2. Keep the consent options in parity
+
+`GoogleTagOptions` extends `ConsentOptions`. Pass the same `categories`, `storageKey` and `linker`
+here as to `CookieConsent`, or the snippet and the dialog disagree about what was asked.
+
+```typescript
+import { googleTagHelper } from '@owlmeans/web-gtm'
+
+const head = googleTagHelper.googleTagHeadScript({
+  id: 'GTM-ABC1234',
+  categories: appCategories,
+  linker: { domains: ['owlmeans.com', 'owlmeans.pl'] },
+})
+
+// a site that has decided to load before consent, with signals denied
+const eager = googleTagHelper.googleTagHeadScript({ id: 'G-ABCD1234', mode: 'advanced' })
+```
+
+### 3. Validate the id where it is stored
+
+```typescript
+import { googleTagHelper } from '@owlmeans/web-gtm'
+
+if (!googleTagHelper.isGoogleTagId(form.googleTag)) {
+  throw new Error('invalid-google-tag')
+}
+googleTagHelper.googleTagKind('GTM-ABC1234')   // 'gtm'
+googleTagHelper.googleTagKind('AW-123456789')  // 'gtag'
+googleTagHelper.googleTagKind('UA-1234-1')     // null — Universal Analytics is retired
+```
+
+### 4. Allow the tag in the CSP
+
+```typescript
+import { GOOGLE_TAG_CSP_SOURCES, GOOGLE_TAG_FRAME_SOURCES } from '@owlmeans/web-gtm'
+
+const csp = [
+  `script-src 'self' ${scriptHash} ${GOOGLE_TAG_CSP_SOURCES.join(' ')}`,
+  `connect-src 'self' ${GOOGLE_TAG_CSP_SOURCES.join(' ')}`,
+  `img-src 'self' data: ${GOOGLE_TAG_CSP_SOURCES.join(' ')}`,
+  `frame-src ${GOOGLE_TAG_FRAME_SOURCES.join(' ')}`,
+].join('; ')
+```
+
+### 5. Disclose the tag on the cookie policy
+
+```tsx
+import { CookiePolicy } from '@owlmeans/web-consent'
+import { googleTagHelper } from '@owlmeans/web-gtm'
+
+<CookiePolicy services={googleTagHelper.googleTagServices(googleTag)} privacyHref="/legal/privacy" />
+```
+
+### 6. Load from script when the HTML is not yours
+
+For a single-page app that cannot edit its own head. It calls `consentStore.init(opts)` first,
+refuses to load twice, gates the same way in `'basic'` mode, and does nothing without a `document`.
+
+```typescript
+import { googleTagHelper } from '@owlmeans/web-gtm'
+
+googleTagHelper.loadGtm({ id: 'GTM-ABC1234', categories: appCategories })
+```
+
+## API
+
+### `googleTagHelper` (`GoogleTagHelper`, built by `createGoogleTagHelper()`)
+
+| Member | Returns | Purpose |
+|---|---|---|
+| `googleTagHeadScript(opts: GoogleTagOptions)` | `string` | Bootstrap, then `ads_data_redaction` on and `url_passthrough` off, then the loader for the id's kind (gated in `'basic'`); HTML-inline-safe. **The default for new code** |
+| `gtmHeadScript(opts: GtmOptions)` | `string` | Older container-only form: bootstrap then `gtm.js`; gated the same way; does not escape `</` |
+| `gtmNoscriptFrame(opts: GtmOptions)` | `string` | Hidden `<noscript>` iframe for `<body>`; `''` in `'basic'` mode |
+| `loadGtm(opts: GtmOptions)` | `void` | Script-side container load (fallback) |
+| `isGoogleTagId(id)` | `boolean` | Strict id check: `GTM-` + 4–12, or `G-`/`GT-`/`AW-`/`DC-` + 4–16 upper-case letters and digits |
+| `googleTagKind(id)` | `'gtm' \| 'gtag' \| null` | Which loader an id takes |
+| `googleTagServices(id)` | `ConsentService[]` | Cookie-policy disclosure read off the prefix |
+
+`googleTagServices` returns: `G-` → Google Analytics (analytics; `_ga`, `_ga_<id>`); `AW-` → Google
+Ads (marketing; `_gcl_au`, `_gcl_aw`); `DC-` → Floodlight (marketing; `_gcl_au`, `_gcl_dc`); `GTM-`
+and `GT-` → one analytics and one advertising entry; an invalid id → `[]`.
+
+### Constants
+
+| Symbol | Value |
+|---|---|
+| `GOOGLE_TAG_DEFAULT_MODE` | `'basic'` |
+| `GOOGLE_TAG_CSP_SOURCES` | frozen list for `script-src`, `connect-src`, `img-src`: `*.googletagmanager.com`, `*.google-analytics.com`, `*.g.doubleclick.net`, `ad.doubleclick.net`, `www.googleadservices.com`, `pagead2.googlesyndication.com`, `*.google.com` (all `https://`) |
+| `GOOGLE_TAG_FRAME_SOURCES` | frozen list for `frame-src`: `https://www.googletagmanager.com`, `https://td.doubleclick.net` |
+
+### Types
+
+| Symbol | Shape |
+|---|---|
+| `GoogleTagOptions` | `ConsentOptions` + `{ id, dataLayerName?, mode? }` |
+| `GtmOptions` | `ConsentOptions` + `{ id, dataLayerName?, mode? }` (container id) |
+| `GoogleTagMode` | `'basic' \| 'advanced'` |
+| `GoogleTagKind` | `'gtm' \| 'gtag'` |
+| `GoogleTagHelper` | the helper interface above |
+
+### Deprecated wrappers
+
+`gtmHeadScript`, `gtmNoscriptFrame`, `isGoogleTagId`, `googleTagHeadScript`, `googleTagServices` —
+top-level functions delegating to `googleTagHelper`. Use the helper members.
+
+## Common pitfalls
+
+- Loading the tag from the bundle (or with `loadGtm` where the head is editable) lets it run before
+  the consent defaults exist; stamp the head script from HTML.
+- `dataLayerName`: Consent Mode always speaks on `window.dataLayer`, so a tag on another queue never
+  hears a consent command. Leave it unset on a consent-gated page.
+- Code written before `'basic'` became the default and expects the tag to load unconditionally must
+  pass `mode: 'advanced'` explicitly.
+- In `'basic'` mode a page counts as "tagged" in Tag Manager only after a consenting visitor loaded
+  it; a URL that redirects before the loader runs stays "not tagged".
+- `isGoogleTagId` rejects lower case and `UA-` ids — normalise in the form, and validate where the
+  id is stored, not only where it is emitted.
+- Under a hash-based CSP, Tag Manager Custom HTML tags and Custom JavaScript variables cannot run;
+  build containers from Google's built-in tag templates.
+- Never build the snippet or the noscript frame by hand — the helpers JSON- or URL-encode the id and
+  queue name.
+
+## Related packages
+
+- [`@owlmeans/consent`](../consent) — the bootstrap, `consentGateScript`, `trackingGranted` and `consentStore`
+- [`@owlmeans/web-consent`](../web-consent) — the dialog and `CookiePolicy` that consume `googleTagServices`
+- [`@owlmeans/web-log`](../web-log) — consent-gated analytics events onto `dataLayer`
+- [`@owlmeans/astro`](../astro) — composes these head strings for an Astro layout
+
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
 
@@ -6,7 +192,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.15
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 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,
+  "schemaVersion": 3,
   "package": "@owlmeans/web-gtm",
-  "version": "0.1.18-rc.9",
-  "generatedAt": "2026-09-12T08:39:52.716Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.712Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,6 +1,6 @@
 ---
 name: web-gtm
-description: How to use @owlmeans/web-gtm — the Google Tag Manager head snippet that declares Consent Mode defaults before the container loads, the noscript frame, and the script-side loader for a host that cannot edit its own HTML. Auto-invoked when adding a tag manager to a page, importing gtmHeadScript, gtmNoscriptFrame or loadGtm, or debugging why a tag ignores a stored consent decision.
+description: How to use @owlmeans/web-gtm — the Google tag head snippet for every Google id (Tag Manager GTM-, GA4 G-, Google tag GT-, Ads AW-, Floodlight DC-) that declares Consent Mode defaults before any loader runs, the id validator, the CSP host lists, the cookie-policy disclosure for a tag, the noscript frame, and the script-side loader for a host that cannot edit its own HTML. Auto-invoked when adding a Google tag or tag manager to a page, importing googleTagHelper (googleTagHeadScript, isGoogleTagId, googleTagServices, gtmHeadScript, gtmNoscriptFrame, loadGtm) or GOOGLE_TAG_CSP_SOURCES, or debugging why a tag ignores a stored consent decision or is blocked by CSP.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,89 +8,230 @@ user-invocable: false
 # @owlmeans/web-gtm
 
 **Layer:** Web
-**Install:** `"@owlmeans/web-gtm": "^0.1.18-rc.9"` in `dependencies`
+**Install:** `"@owlmeans/web-gtm": "^0.1.18"` in `dependencies`
 
-The tag-manager half of the consent set. It emits **strings**, not components, and it holds no
+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
-`consentBootstrapScript` and `consentStore`.
+`consentModeHelper.consentBootstrapScript` and `consentStore`.
 
 ## The one idea: order
 
-Google Tag Manager decides what a tag may do from the consent state present **when the container
-loads**. A React bundle cannot get there first: by the time an island mounts, `gtm.js` has been
-running for hundreds of milliseconds and has already decided. A site whose defaults arrive after
-the container is not configured differently — it is *unconfigured for the window that matters*, and
-nothing in the page reports it.
+A Google tag — the Tag Manager container or gtag.js alike — decides what it may do from the
+consent state present **when it loads**. A React bundle cannot get there first: by the time an
+island mounts, the tag has been running for hundreds of milliseconds and has already decided. A
+site whose defaults arrive after the loader is not configured differently — it is *unconfigured
+for the window that matters*, and nothing in the page reports it.
 
-So `gtmHeadScript` emits the consent bootstrap and then the container, in that order, as one
+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
+
+`googleTagHelper.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 `consentModeHelper.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.
+
+**What `'basic'` does to a tag manager's coverage report.** A page is "Tagged" only after a consenting visitor
+has loaded it; `'advanced'` is what makes every first view count. The report also records URLs it only saw as a
+referrer, so a page the visitor was redirected AWAY from before the loader ran stays "Not tagged" — keep any
+redirect off URLs that already name their locale.
+
+`googleTagHelper.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.
+
+`googleTagHelper.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 `consentModeHelper.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. Give it the same `geo` the consent UI has: its `init` may run first,
+and the store must know to locate the visitor rather than ask. An automatic decision (outside the
+consent countries) is an ordinary grant here — the tag loads on it — while one past its age counts
+as none, in the head gate as in the store, until the visitor is located again.
+
+None of this is new state: it is one more consumer of `@owlmeans/consent`'s existing surface —
+`consentModeHelper.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 |
 |--------|-------------|
-| `gtmHeadScript(opts)` | The inline `<head>` snippet: consent defaults, stored decision, then the container |
-| `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` |
+| `googleTagHelper.googleTagHeadScript(opts)` | The inline `<head>` script for any Google id: consent bootstrap, ads redaction, then the loader the prefix calls for — gated behind `consentModeHelper.consentGateScript` in `opts.mode`'s default, `'basic'`. **The default for new code** |
+| `googleTagHelper.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`, 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` |
+| `googleTagHelper.googleTagServices(id)` | The `ConsentService[]` a cookie policy discloses for that tag — pass to `CookiePolicy`'s `services` |
+| `googleTagHelper.gtmHeadScript(opts)` | The container-only snippet: consent defaults, stored decision, then `gtm.js` — gated the same way as `.googleTagHeadScript` |
+| `googleTagHelper.gtmNoscriptFrame(opts)` | The hidden `<noscript>` iframe, for the top of `<body>` — `''` in `'basic'` mode |
+| `googleTagHelper.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
+
+`googleTagHelper.isGoogleTagId` accepts exactly `GTM-` + 4–12, or `G-` / `GT-` / `AW-` / `DC-` + 4–16, upper-case
+letters and digits. It is strict on purpose: the id is typed into a settings form and ends up in
+an inline script and a script URL, and a value it accepts cannot carry a quote, a tag or a second
+query parameter — so **validate with it where the id is stored**, not only where it is emitted.
+Lower case is rejected rather than folded; normalise in the form if you want to be forgiving.
+`UA-` (Universal Analytics, retired) is rejected: it would promise measurement that never comes.
+
+| Prefix | Kind | Loader |
+|---|---|---|
+| `GTM-` | `gtm` | `gtm.js` — Google's container IIFE |
+| `G-` GA4, `GT-` Google tag, `AW-` Google Ads, `DC-` Floodlight | `gtag` | `gtag/js`, then `js` and `config` |
+
+## `googleTagHelper.googleTagHeadScript` — what it emits
+
+1. `consentModeHelper.consentBootstrapScript(opts)` — `consent/default` (everything denied except
+   `security_storage`) and, for a returning visitor, `consent/update` from the stored record.
+2. `set ads_data_redaction true` and `set url_passthrough false` — both have to precede the tag's
+   `config`. Redaction strips ad-click ids and goes cookieless while `ad_storage` is denied.
+3. The loader. For `gtag`: a queue function (published as `window.gtag` only when nothing else
+   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. In `mode`'s default,
+   `'basic'`, this whole step 3 is what `consentModeHelper.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, regardless of `mode`** — a mistyped tag must
+never cost a page its consent defaults. So a host may stamp `googleTagHelper.googleTagHeadScript({ id: configured
+})` unconditionally, or stamp `consentModeHelper.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
+it sits, so every `</` and `<!--` in the output is backslash-escaped (`<\/`, `<\!--` — JavaScript
+reads them unchanged). `googleTagHelper.gtmHeadScript` predates this and does not escape; prefer
+`.googleTagHeadScript` wherever category keys or a storage key come from configuration.
 
 ## Stamping it
 
 ```typescript
-import { gtmHeadScript, gtmNoscriptFrame } from '@owlmeans/web-gtm'
+import { googleTagHelper } from '@owlmeans/web-gtm'
 
-const opts = { id: 'GTM-XXXXXXX' }
-const head = gtmHeadScript(opts)      // inline <script> content for <head>, first
-const frame = gtmNoscriptFrame(opts)  // <noscript> content for the top of <body>
+const head = googleTagHelper.googleTagHeadScript({ id: 'G-XXXXXXXXXX' })   // inline <script> content, first in <head>
 ```
 
-The snippet is stamped **from HTML**, never from the application bundle. How each surface does it:
+The snippet is stamped **from HTML**, never from the application bundle:
+
+- a Vite app — a `transformIndexHtml` plugin substituting a marker, so the snippet cannot drift
+  from the package;
+- an Astro site — `astroHelper.owlHeadScripts()` from `@owlmeans/astro`, `set:html` in the base layout;
+- a **generated Viable app** — its Rollup build writes `index.html` and puts
+  `googleTagHelper.googleTagHeadScript({ id })` in the `<head>` when the project owner has set a Google tag
+  (`BRANDING_GOOGLE_TAG`), and `consentModeHelper.consentBootstrapScript()` otherwise. The tag is attached in
+  **preview and production** alike; the consent default is first in both.
 
-- a Vite app — a `transformIndexHtml` plugin substituting the two markers, so the snippet cannot
-  drift from the package;
-- an Astro site — `owlHeadScripts()` from `@owlmeans/astro`, `set:html` in the base layout.
+The snippet **reads the stored decision**, so the same `ConsentOptions` (categories, `storageKey`)
+must be passed here and to the dialog: two category sets in one page mean the snippet and the
+component disagree about what was asked.
 
-A surface that runs no container of its own stamps only `consentBootstrapScript()` from
-`@owlmeans/consent` — that is the case for the bundler-generated `index.html` of a generated
-application, which carries the consent bootstrap and no tag manager. The bootstrap and this
-snippet are separate stampings: adding a container means adding `gtmHeadScript` /
-`gtmNoscriptFrame` beside it.
+**Cross-domain consent needs nothing new here.** `GtmOptions`/`GoogleTagOptions` both extend
+`ConsentOptions`, so `linker` (see the `consent` skill's plugin-seam section) passed to either head
+script reaches `consentModeHelper.consentBootstrapScript` unchanged, which embeds the adopt-and-strip fragment right
+after `consent/default` when it is set:
+
+```typescript
+googleTagHelper.googleTagHeadScript({ id: 'GTM-XXXXXXX', linker: { domains: ['owlmeans.com', 'owlmeans.pl'] } })
+```
 
-`gtmHeadScript` also **reads the stored decision** and pushes `consent/update` before the
-container, so a returning visitor's tags are not denied for the first paint of every page. That
-read is why the same `ConsentOptions` (categories, `storageKey`) must be passed here and to the
-dialog: two different category sets in one page mean the snippet and the component disagree about
-what was asked.
+An app that does not stamp a tag at all still gets the fragment from a bare
+`consentModeHelper.consentBootstrapScript({ linker: { domains } })`.
+
+## Content Security Policy
+
+A page served with a CSP must allow the tag's hosts, or the loader is blocked and nothing on the
+page says so.
+
+- `GOOGLE_TAG_CSP_SOURCES` goes into `script-src`, `connect-src` and `img-src` — one list for all
+  three, folded from Google's CSP guide (developers.google.com/tag-platform/security/guides/csp):
+  `*.googletagmanager.com`, `*.google-analytics.com`, `*.g.doubleclick.net`, `ad.doubleclick.net`,
+  `www.googleadservices.com`, `pagead2.googlesyndication.com`, `*.google.com`. Each is
+  `https://` + optional `*.` + a dotted host, the only shape the Viable publisher's source filter
+  admits, and few enough to fit its per-slot cap. Google's country domains (`google.<TLD>`) cannot
+  be expressed in that shape; what is lost is a remarketing ping, never the tag.
+- `GOOGLE_TAG_FRAME_SOURCES` goes into `frame-src`.
+- The inline head script itself is covered by the document's own script hash — the Viable
+  publisher derives `'sha256-…'` from the document it sends — so nothing else is needed for it.
+- **Tag Manager Custom HTML tags do not run under a hash-based CSP**: they inject inline scripts
+  no hash names, and `'unsafe-inline'` is not an option. Custom JavaScript variables need
+  `'unsafe-eval'` and fail the same way. Build a container for such a page from Google's
+  **built-in tag templates** (GA4, Google Ads, Floodlight, Conversion Linker) and Community
+  Gallery templates, which load from the allowed hosts.
+
+## Sending events
+
+This package emits the head snippet and decides when the loader may run; it has no event-push API. An
+application sends its own events through `@owlmeans/log` calls that carry an `analytics` option, and
+`@owlmeans/web-log`'s `gtmAnalyticsPlugin` pushes them onto `window.dataLayer` only while analytics
+consent is granted (`/web-log`).
+
+## Disclosing it
+
+`googleTagHelper.googleTagServices(id)` returns what the cookie policy lists under each category, read off the
+prefix — the page knows nothing more:
+
+| Id | Entries |
+|---|---|
+| `G-` | Google Analytics — `analytics`; `_ga`, `_ga_<id without G->` |
+| `AW-` | Google Ads — `marketing`; `_gcl_au`, `_gcl_aw` |
+| `DC-` | Floodlight — `marketing`; `_gcl_au`, `_gcl_dc` |
+| `GTM-`, `GT-` | one `analytics` AND one `marketing` entry, worded as "configured in the container" / "for it at Google" — the policy may not claim less than the tag can do |
+| invalid | `[]` — it loads nothing, so it discloses nothing |
+
+Pass them to `CookiePolicy` (`services`) wherever the tag is stamped; a generated Viable app's
+cookie page does so when a Google tag is set. The strings are English data, not translation keys.
 
 ## Gotchas
 
-- **The container id and queue name are injected as data, never interpolated raw.** Both come from
-  configuration, and configuration reaches these functions as a string. `gtmHeadScript` JSON-encodes
-  them, so a quote inside an id is escaped rather than closing the literal and turning the rest into
-  executable script; `gtmNoscriptFrame` URL-encodes the id so it cannot break out of the attribute.
-  Never build either string by hand.
-- **`dataLayerName` is for a page running more than one container.** It is passed through to the
-  container the way Google's own snippet does (`&l=` when it is not `dataLayer`); leave it unset
-  otherwise, or tags looking at the default queue see nothing.
-- **`loadGtm` is the fallback, not the default.** It is for a single-page app whose HTML is not
+- **Consent Mode speaks on `window.dataLayer`.** The bootstrap and the dialog's later
+  `consent/update` both push there, so a tag given another `dataLayerName` never hears a consent
+  command. Leave `dataLayerName` unset on any consent-gated page; it exists for a page running a
+  second, separately-consented container. `googleTagHelper.googleTagHeadScript` falls back to `dataLayer` when the
+  name is not a plain identifier.
+- **Ids and queue names are injected as data, never interpolated raw.** `googleTagHelper.gtmHeadScript` and
+  `.googleTagHeadScript` JSON-encode them; `.gtmNoscriptFrame` URL-encodes the id so it cannot break
+  out of the attribute. Never build either string by hand.
+- **`googleTagHelper.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. Prefer the
-  head snippet wherever the document can be edited.
+  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 `consentModeHelper.trackingGranted`, same as the head
+  snippets.
+- **The default flipped to `'basic'`.** Code written before this mode existed called
+  `googleTagHelper.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.
-- `loadGtm` returns immediately when there is no `document`, so it is safe to call from code that
+- `googleTagHelper.loadGtm` returns immediately when there is no `document`, so it is safe to call from code that
   also runs during server rendering.
 
 ## Depends On
 
-- `@owlmeans/consent` — `consentBootstrapScript`, `consentStore`, `ConsentOptions`, the category
-  model and the Consent Mode signal mapping
+- `@owlmeans/consent` — `consentModeHelper.consentBootstrapScript`, `consentStore`, `ConsentOptions`,
+  `ConsentService`, the category keys and the Consent Mode signal mapping, plus (for the `'basic'`
+  gated mode) `.consentGateScript` and `.trackingGranted`
 
 ## Related
 
 - `consent` — categories, the storage record and its migration, Consent Mode v2 signalling, and the
   ordering rule this package implements
-- `web-consent` — the dialog and the cookie-policy page that produce the decision
-- `astro` — `owlHeadScripts()`, which composes both strings for an Astro layout
+- `web-consent` — the dialog and the cookie-policy page (`services`) that produce and disclose the
+  decision
+- `astro` — `astroHelper.owlHeadScripts()`, which composes the head strings for an Astro layout

package/build/consts.d.ts

@@ -0,0 +1,43 @@
+import type { GoogleTagMode } from './types.js';
+/**
+ * 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;
+/**
+ * The hosts a page running a Google tag has to allow in `script-src`, `connect-src` and
+ * `img-src`, for Google Analytics 4, Tag Manager and Google Ads together.
+ *
+ * Taken from Google's CSP guide (developers.google.com/tag-platform/security/guides/csp) and
+ * folded into one list, because the platform adds one list to all three directives:
+ *
+ * - `*.googletagmanager.com` — gtm.js and gtag/js (`www.`), and their measurement pings;
+ * - `*.google-analytics.com` — GA4 collection (`region1.`, `www.`);
+ * - `*.g.doubleclick.net` — GA4 with Google signals and Ads (`stats.g.`, `googleads.g.`);
+ * - `ad.doubleclick.net` — Ads and Floodlight conversions;
+ * - `www.googleadservices.com` — the Ads conversion script;
+ * - `pagead2.googlesyndication.com` — Ads and GA4-with-ads pings;
+ * - `*.google.com` — `www.google.com` (the Ads script, consent-mode pings), `adservice.`, and the
+ *   `analytics.google.com` collection endpoints.
+ *
+ * Every entry is an `https://` scheme, an optional `*.` label and a dotted host — the only shape
+ * the publisher's CSP filter lets through — and there are few enough to stay inside its per-slot
+ * cap. Google's country domains (`google.<TLD>`) cannot be named in that shape and are left out:
+ * what is lost is a remarketing ping from visitors on those domains, never the tag itself.
+ */
+export declare const GOOGLE_TAG_CSP_SOURCES: readonly string[];
+/**
+ * The hosts a Google tag frames: Tag Manager's service-worker and preview frames, and the Ads
+ * remarketing frame. For `frame-src`, which otherwise stays `'none'`.
+ */
+export declare const GOOGLE_TAG_FRAME_SOURCES: readonly string[];
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,EAAE,aAAuB,CAAA;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAQlD,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAGpD,CAAA"}

package/build/consts.js

@@ -0,0 +1,53 @@
+/**
+ * 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';
+/**
+ * The hosts a page running a Google tag has to allow in `script-src`, `connect-src` and
+ * `img-src`, for Google Analytics 4, Tag Manager and Google Ads together.
+ *
+ * Taken from Google's CSP guide (developers.google.com/tag-platform/security/guides/csp) and
+ * folded into one list, because the platform adds one list to all three directives:
+ *
+ * - `*.googletagmanager.com` — gtm.js and gtag/js (`www.`), and their measurement pings;
+ * - `*.google-analytics.com` — GA4 collection (`region1.`, `www.`);
+ * - `*.g.doubleclick.net` — GA4 with Google signals and Ads (`stats.g.`, `googleads.g.`);
+ * - `ad.doubleclick.net` — Ads and Floodlight conversions;
+ * - `www.googleadservices.com` — the Ads conversion script;
+ * - `pagead2.googlesyndication.com` — Ads and GA4-with-ads pings;
+ * - `*.google.com` — `www.google.com` (the Ads script, consent-mode pings), `adservice.`, and the
+ *   `analytics.google.com` collection endpoints.
+ *
+ * Every entry is an `https://` scheme, an optional `*.` label and a dotted host — the only shape
+ * the publisher's CSP filter lets through — and there are few enough to stay inside its per-slot
+ * cap. Google's country domains (`google.<TLD>`) cannot be named in that shape and are left out:
+ * what is lost is a remarketing ping from visitors on those domains, never the tag itself.
+ */
+export const GOOGLE_TAG_CSP_SOURCES = Object.freeze([
+    'https://*.googletagmanager.com',
+    'https://*.google-analytics.com',
+    'https://*.g.doubleclick.net',
+    'https://ad.doubleclick.net',
+    'https://www.googleadservices.com',
+    'https://pagead2.googlesyndication.com',
+    'https://*.google.com',
+]);
+/**
+ * The hosts a Google tag frames: Tag Manager's service-worker and preview frames, and the Ads
+ * remarketing frame. For `frame-src`, which otherwise stays `'none'`.
+ */
+export const GOOGLE_TAG_FRAME_SOURCES = Object.freeze([
+    'https://www.googletagmanager.com',
+    'https://td.doubleclick.net',
+]);
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAkB,OAAO,CAAA;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACrE,gCAAgC;IAChC,gCAAgC;IAChC,6BAA6B;IAC7B,4BAA4B;IAC5B,kCAAkC;IAClC,uCAAuC;IACvC,sBAAsB;CACvB,CAAC,CAAA;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACvE,kCAAkC;IAClC,4BAA4B;CAC7B,CAAC,CAAA"}

package/build/consts.local.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The id shapes Google issues today, and nothing else.
+ *
+ * Deliberately strict — upper case, a known prefix, a bounded run of letters and digits — because
+ * the id is typed by a person into a settings form and ends up inside an inline script and a
+ * script URL. A value this pattern accepts cannot carry a quote, a tag or a second parameter, so
+ * the check is what makes it safe to store, not only to emit. `UA-` is not here: Universal
+ * Analytics stopped processing data in 2024, and accepting its ids would promise measurement that
+ * never arrives.
+ */
+export declare const GOOGLE_TAG_ID: RegExp;
+/** A queue name has to be a plain identifier: it becomes `window[name]` in the emitted script. */
+export declare const JS_IDENTIFIER: RegExp;
+export declare const GOOGLE = "Google LLC";
+export declare const GOOGLE_PRIVACY = "https://policies.google.com/privacy";
+export declare const UNTIL_ANALYTICS: string;
+export declare const UNTIL_MARKETING: string;
+//# sourceMappingURL=consts.local.d.ts.map

package/build/consts.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.d.ts","sourceRoot":"","sources":["../src/consts.local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,QAAuD,CAAA;AAEjF,kGAAkG;AAClG,eAAO,MAAM,aAAa,QAA+B,CAAA;AAEzD,eAAO,MAAM,MAAM,eAAe,CAAA;AAElC,eAAO,MAAM,cAAc,wCAAwC,CAAA;AAEnE,eAAO,MAAM,eAAe,QACS,CAAA;AAErC,eAAO,MAAM,eAAe,QACG,CAAA"}