@owlmeans/web-gtm 0.1.18-rc.10

package/README.md

@@ -0,0 +1,15 @@
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18-rc.16
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/web-gtm",
+  "version": "0.1.18-rc.10",
+  "generatedAt": "2026-09-12T12:33:32.485Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "web-gtm",
+      "category": "package-specific",
+      "file": "skills/web-gtm/SKILL.md",
+      "canonicalPath": ".agents/skills/web-gtm/SKILL.md"
+    }
+  ]
+}

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

@@ -0,0 +1,96 @@
+---
+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.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/web-gtm
+
+**Layer:** Web
+**Install:** `"@owlmeans/web-gtm": "^0.1.18-rc.10"` in `dependencies`
+
+The tag-manager half of the consent set. It emits **strings**, not components, and it holds no
+state — the decision lives in `@owlmeans/consent`, which this package reads through
+`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.
+
+So `gtmHeadScript` emits the consent bootstrap and then the container, in that order, as one
+inline script. Everything else in this package exists to serve that.
+
+## 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` |
+
+## Stamping it
+
+```typescript
+import { gtmHeadScript, gtmNoscriptFrame } 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>
+```
+
+The snippet is stamped **from HTML**, never from the application bundle. How each surface does it:
+
+- 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.
+
+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.
+
+`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.
+
+## 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
+  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.
+- **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
+  also runs during server rendering.
+
+## Depends On
+
+- `@owlmeans/consent` — `consentBootstrapScript`, `consentStore`, `ConsentOptions`, the category
+  model and the Consent Mode signal mapping
+
+## 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

package/build/index.d.ts

@@ -0,0 +1,30 @@
+import type { ConsentOptions } from '@owlmeans/consent';
+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;
+}
+/**
+ * The inline `<head>` snippet, consent first and the container second.
+ *
+ * The ORDER is the whole point of this package. Google Tag Manager decides what a tag may do from
+ * the consent state present when the container loads, and a React bundle cannot get there first —
+ * by the time an island mounts, the container has been running for hundreds of milliseconds. A
+ * site whose defaults arrive after `gtm.js` is not configured differently; it is unconfigured for
+ * the window that matters, and nothing in the page reports it.
+ *
+ * Emit this into the document head, above everything else, as an inline script.
+ */
+export declare const gtmHeadScript: (opts: GtmOptions) => string;
+/** The `<noscript>` iframe, for the body. */
+export declare const gtmNoscriptFrame: (opts: GtmOptions) => string;
+/**
+ * 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.
+ */
+export declare const loadGtm: (opts: GtmOptions) => void;
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAA;IACV,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,SAAU,UAAU,KAAG,MAWhD,CAAA;AAED,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB,SAAU,UAAU,KAAG,MAEsB,CAAA;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,SAAU,UAAU,KAAG,IAkB1C,CAAA"}

package/build/index.js

@@ -0,0 +1,52 @@
+import { consentBootstrapScript, consentStore } from '@owlmeans/consent';
+/**
+ * The inline `<head>` snippet, consent first and the container second.
+ *
+ * The ORDER is the whole point of this package. Google Tag Manager decides what a tag may do from
+ * the consent state present when the container loads, and a React bundle cannot get there first —
+ * by the time an island mounts, the container has been running for hundreds of milliseconds. A
+ * site whose defaults arrive after `gtm.js` is not configured differently; it is unconfigured for
+ * the window that matters, and nothing in the page reports it.
+ *
+ * Emit this into the document head, above everything else, as an inline script.
+ */
+export const gtmHeadScript = (opts) => {
+    const layer = opts.dataLayerName ?? 'dataLayer';
+    return `${consentBootstrapScript(opts)};` +
+        `(function(w,d,s,l,i){w[l]=w[l]||[];` +
+        `w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});` +
+        `var f=d.getElementsByTagName(s)[0],j=d.createElement(s),` +
+        `dl=l!='dataLayer'?'&l='+l:'';j.async=true;` +
+        `j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;` +
+        `f.parentNode.insertBefore(j,f)})` +
+        `(window,document,'script',${JSON.stringify(layer)},${JSON.stringify(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>`;
+/**
+ * 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.
+ */
+export const loadGtm = (opts) => {
+    if (typeof document === 'undefined') {
+        return;
+    }
+    const marker = `owl-gtm-${opts.id}`;
+    if (document.getElementById(marker) != null) {
+        return;
+    }
+    // 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);
+};
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAUxE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAgB,EAAU,EAAE;IACxD,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,IAAI,WAAW,CAAA;IAE/C,OAAO,GAAG,sBAAsB,CAAC,IAAI,CAAC,GAAG;QACvC,qCAAqC;QACrC,+DAA+D;QAC/D,0DAA0D;QAC1D,4CAA4C;QAC5C,2DAA2D;QAC3D,kCAAkC;QAClC,6BAA6B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAA;AACpF,CAAC,CAAA;AAED,6CAA6C;AAC7C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAAgB,EAAU,EAAE,CAC3D,4DAA4D,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG;IAC1F,wEAAwE,CAAA;AAE1E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAgB,EAAQ,EAAE;IAChD,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QACpC,OAAM;IACR,CAAC;IACD,MAAM,MAAM,GAAG,WAAW,IAAI,CAAC,EAAE,EAAE,CAAA;IACnC,IAAI,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QAC5C,OAAM;IACR,CAAC;IACD,6FAA6F;IAC7F,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAEvB,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,IAAI,WAAW,CAAA;IAC/C,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAA;IAC/C,MAAM,CAAC,EAAE,GAAG,MAAM,CAAA;IAClB,MAAM,CAAC,KAAK,GAAG,IAAI,CAAA;IACnB,MAAM,CAAC,GAAG,GAAG,8CAA8C,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;UACpF,CAAC,KAAK,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACpE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;AACnC,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@owlmeans/web-gtm",
+  "version": "0.1.18-rc.10",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 2 && nodemon -e ts,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/consent": "^0.1.18-rc.4"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@types/bun": "^1.4.0",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+import { consentBootstrapScript, consentStore } from '@owlmeans/consent'
+import type { ConsentOptions } from '@owlmeans/consent'
+
+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
+}
+
+/**
+ * The inline `<head>` snippet, consent first and the container second.
+ *
+ * The ORDER is the whole point of this package. Google Tag Manager decides what a tag may do from
+ * the consent state present when the container loads, and a React bundle cannot get there first —
+ * by the time an island mounts, the container has been running for hundreds of milliseconds. A
+ * site whose defaults arrive after `gtm.js` is not configured differently; it is unconfigured for
+ * the window that matters, and nothing in the page reports it.
+ *
+ * Emit this into the document head, above everything else, as an inline script.
+ */
+export const gtmHeadScript = (opts: GtmOptions): string => {
+  const layer = opts.dataLayerName ?? 'dataLayer'
+
+  return `${consentBootstrapScript(opts)};` +
+    `(function(w,d,s,l,i){w[l]=w[l]||[];` +
+    `w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});` +
+    `var f=d.getElementsByTagName(s)[0],j=d.createElement(s),` +
+    `dl=l!='dataLayer'?'&l='+l:'';j.async=true;` +
+    `j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;` +
+    `f.parentNode.insertBefore(j,f)})` +
+    `(window,document,'script',${JSON.stringify(layer)},${JSON.stringify(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>`
+
+/**
+ * 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.
+ */
+export const loadGtm = (opts: GtmOptions): void => {
+  if (typeof document === 'undefined') {
+    return
+  }
+  const marker = `owl-gtm-${opts.id}`
+  if (document.getElementById(marker) != null) {
+    return
+  }
+  // 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)
+}

package/tests/head.spec.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from 'bun:test'
+import { CONSENT_KEY } from '@owlmeans/consent'
+import { gtmHeadScript, gtmNoscriptFrame } from '../src/index.js'
+
+const ID = 'GTM-TESTID1'
+
+describe('@owlmeans/web-gtm — the head snippet', () => {
+  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 defaults = script.indexOf("'consent','default'")
+    const container = script.indexOf('gtm.js')
+
+    expect(defaults).toBeGreaterThanOrEqual(0)
+    expect(container).toBeGreaterThanOrEqual(0)
+    expect(defaults).toBeLessThan(container)
+  })
+
+  test('it reads a stored decision, so a returning visitor is not treated as denied', async () => {
+    const script = gtmHeadScript({ id: ID })
+
+    expect(script).toContain(JSON.stringify(CONSENT_KEY))
+    expect(script).toContain("'consent','update'")
+    // And the read happens before the container too — a decision applied afterwards is a decision
+    // the first tag never saw.
+    expect(script.indexOf("'consent','update'")).toBeLessThan(script.indexOf('gtm.js'))
+  })
+
+  test('the container id and queue name are injected as data, never interpolated raw', async () => {
+    // These come from configuration, and configuration reaches this function as a string. JSON
+    // 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' })
+
+    expect(script).toContain(JSON.stringify(`${ID}"+alert(1)+"`))
+    expect(script).toContain(JSON.stringify('owlLayer'))
+    // The escaped form is what makes it inert; the bare form would have closed the literal.
+    expect(script).toContain('\\"+alert(1)+\\"')
+    expect(script).not.toContain(`"${ID}"+alert(1)+""`)
+  })
+
+  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'))
+  })
+})
+
+describe('@owlmeans/web-gtm — the noscript frame', () => {
+  test('it names the container and stays invisible', async () => {
+    const frame = gtmNoscriptFrame({ id: ID })
+
+    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')
+  })
+})

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json"
+  ],
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM"],
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
+}