@tracelog/capture-web 1.3.1 → 2.0.0

package/CHANGELOG.md

@@ -18,6 +18,23 @@ patch, and neither requires reading your code.
 Entries after 1.0.0 are drafted from the commits that touched this package and
 edited before release.
 
+## [2.0.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@1.3.1...capture-web@2.0.0) (2026-10-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* **capture-core:** call TraceLog.consent.grant() on every load while the visitor's consent stands, not only when they accept.
+
+### Added
+
+* **capture-web:** calls before init are held ([b8d4fe5](https://github.com/nacorga/tracelog-sdk/commit/b8d4fe5e4bb104c2343aeceeb1b17f70d8cc697a))
+
+
+### Fixed
+
+* **capture-core:** a grant is not remembered across loads ([75d4cac](https://github.com/nacorga/tracelog-sdk/commit/75d4cac28055007553e36b97d4eef0dbabf27103))
+* **capture-web:** the verification mark follows its tab ([9653074](https://github.com/nacorga/tracelog-sdk/commit/9653074fb57ef5523a43a7fa6bc681f8b8a8814f))
+
 ## [1.3.1](https://github.com/nacorga/tracelog-sdk/compare/capture-web@1.3.0...capture-web@1.3.1) (2026-09-30)
 
 

package/README.md

@@ -22,13 +22,13 @@ as they are served.
 <!-- x-release-please-start-version -->
 
 ```bash
-npm install --save-exact @tracelog/capture-web@1.3.1
+npm install --save-exact @tracelog/capture-web@2.0.0
 ```
 
 Without a build step, the same runtime as a script tag:
 
 ```html
-<script src="https://cdn.tracelog.io/v/1.3.1/tracelog.js"></script>
+<script src="https://cdn.tracelog.io/v/2.0.0/tracelog.js"></script>
 ```
 
 <!-- x-release-please-end -->
@@ -42,7 +42,7 @@ the floor before a release.
 Before consent is granted the runtime creates no identifiers, writes no storage,
 and sends no network traffic — none, not a reduced set. Consent is a state
 machine you drive; until it reaches `granted`, capture is inert. Denying keeps it
-inert without breaking the page.
+inert without breaking the page, and is remembered; a grant is not.
 
 ```js
 import TraceLog from "@tracelog/capture-web";
@@ -52,10 +52,16 @@ TraceLog.init({
   endpoint: "https://api.tracelog.io/v1/events",
 });
 
-// Only once your consent surface says yes:
+// When your consent surface says yes, and on every later load while
+// that consent stands:
 TraceLog.consent.grant();
 ```
 
+A grant lasts the page it was given on. Your consent surface keeps the
+visitor's answer and its expiry, so call `grant()` on each load where that
+answer is still yes; a grant that outlived it would capture a visitor whose
+consent has lapsed.
+
 A site that never calls `consent.grant()` captures nothing and costs its
 visitors nothing.
 
@@ -74,11 +80,17 @@ That is all of it, and it is what the major version protects.
 
 `init` also accepts `mode: "verification"`, which a distributed platform artifact
 declares for its platform's own test order. A site's own snippet never sets it —
-the runtime derives verification mode from the window that opened the page.
+the runtime derives verification mode from the window that opened the page, and
+once consent is granted there the tab keeps it (`sessionStorage`, `__tl.v`) for
+the site's next pages and the return from a payment taken elsewhere, to the same
+origin. A denial forgets it.
 
 Call `init` once per page load. The runtime is built on the first call and
 kept; a later call re-reads the key and the endpoint and rebuilds nothing else,
-so a mode or an acquisition the first call decided stands for the page.
+so a mode or an acquisition the first call decided stands for the page. A
+call made before it — a grant, a step, a conversion — is held, up to 100, and
+made once it has run. The runtime can hold only what reaches it: a page that
+imports it lazily holds what it calls before the import resolves.
 
 The application generates the exact calls your declared plan needs, so you never
 type a name TraceLog already knows.

package/dist/tracelog.esm.js

@@ -550,22 +550,26 @@ function createCaptureEngine(ports, acquisition) {
                 endpoint: options.endpoint ?? "/v1/events",
             };
             initialized = true;
+            /**
+             * Only a denial is remembered; a grant is the integrator's on every load
+             * while consent stands, so it never outlives the banner that gave it
+             * ([spec/capture.md] § Consent first). A grant an earlier runtime
+             * stored is deleted. A second init keeps the decision this page made.
+             */
+            if (consentState !== "unknown")
+                return;
             const storedConsent = safeGet(ports.storage, CONSENT_KEY);
-            consentState =
-                storedConsent === "granted" || storedConsent === "denied"
-                    ? storedConsent
-                    : "unknown";
-            if (consentState === "granted") {
-                ports.sightings?.start();
-                scheduleFlush(FLUSH_INTERVAL_MS);
-            }
+            if (storedConsent === "denied")
+                consentState = "denied";
+            else if (storedConsent !== null)
+                safeRemove(ports.storage, CONSENT_KEY);
         },
         consent: {
             grant() {
                 if (!initialized)
                     return;
                 consentState = "granted";
-                safeSet(ports.storage, CONSENT_KEY, "granted");
+                safeRemove(ports.storage, CONSENT_KEY);
                 ports.sightings?.start();
                 const buffered = pending;
                 pending = [];
@@ -918,6 +922,8 @@ function createTagSightingPort() {
     };
 }
 const WEB_PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
+/** The tab's verification nonce, in `sessionStorage`, written at the grant. */
+const VERIFICATION_KEY = "__tl.v";
 class MemoryStorage {
     constructor() {
         this.values = new Map();
@@ -938,6 +944,20 @@ let engine;
 let verification;
 let configValid = false;
 let listenersInstalled = false;
+/**
+ * Calls made before `init`, made in order once it has run, up to the same 100
+ * the engine holds before consent; past that they are dropped
+ * ([spec/capture.md] § Consent first).
+ */
+let early = [];
+/** True when there is no engine yet, and the call was held, or dropped. */
+function heldForInit(call) {
+    if (engine !== undefined)
+        return false;
+    if (early.length < PRE_CONSENT_CAP)
+        early.push(call);
+    return true;
+}
 function browserStorage() {
     try {
         return window.localStorage;
@@ -946,11 +966,39 @@ function browserStorage() {
         return new MemoryStorage();
     }
 }
+/**
+ * A page opened from a verification session carries the marker and has an
+ * opener. Once consent is granted there, the tab keeps the nonce, so the mark
+ * follows it to the site's next pages and back from a payment taken
+ * elsewhere, to the same origin ([spec/capture.md] § Verification mode).
+ */
 function verificationMode() {
     const nonce = new URL(window.location.href).searchParams.get("__tl_verify");
-    return nonce !== null && nonce.length > 0 && window.opener !== null
-        ? { nonce, opener: window.opener }
-        : undefined;
+    if (nonce !== null && nonce.length > 0 && window.opener !== null) {
+        return { nonce, opener: window.opener };
+    }
+    let kept = null;
+    try {
+        kept = window.sessionStorage.getItem(VERIFICATION_KEY);
+    }
+    catch {
+        // An unreadable tab storage keeps no mark.
+    }
+    return kept === null || kept.length === 0
+        ? undefined
+        : { nonce: kept, opener: window.opener };
+}
+function keepVerification(keep) {
+    try {
+        if (!keep)
+            window.sessionStorage.removeItem(VERIFICATION_KEY);
+        else if (verification !== undefined) {
+            window.sessionStorage.setItem(VERIFICATION_KEY, verification.nonce);
+        }
+    }
+    catch {
+        // A tab that cannot keep it marks this page only.
+    }
 }
 function landingPage() {
     const url = new URL(window.location.href);
@@ -1005,7 +1053,7 @@ function isEndpointValid(endpoint) {
     }
 }
 function reportDiagnostic() {
-    if (verification === undefined)
+    if (verification === undefined || verification.opener === null)
         return;
     verification.opener.postMessage({
         type: "tracelog:diag",
@@ -1102,17 +1150,28 @@ function init(options) {
         ...(options.endpoint === undefined ? {} : { endpoint }),
     });
     installListeners();
+    const held = early;
+    early = [];
+    for (const call of held)
+        call();
     reportDiagnostic();
 }
 const TraceLog = {
     init,
     consent: {
         grant() {
+            if (heldForInit(() => TraceLog.consent.grant()))
+                return;
             engine?.consent.grant();
+            if (engine?.consent.state() === "granted")
+                keepVerification(true);
             reportDiagnostic();
         },
         deny() {
+            if (heldForInit(() => TraceLog.consent.deny()))
+                return;
             engine?.consent.deny();
+            keepVerification(false);
             reportDiagnostic();
         },
         state() {
@@ -1120,10 +1179,14 @@ const TraceLog = {
         },
     },
     step(name, context) {
+        if (heldForInit(() => TraceLog.step(name, context)))
+            return;
         engine?.step(name, context);
         reportDiagnostic();
     },
     conversion(name, options) {
+        if (heldForInit(() => TraceLog.conversion(name, options)))
+            return;
         engine?.conversion(name, options);
         reportDiagnostic();
     },

package/dist/tracelog.iife.js

@@ -551,22 +551,26 @@ function createCaptureEngine(ports, acquisition) {
                 endpoint: options.endpoint ?? "/v1/events",
             };
             initialized = true;
+            /**
+             * Only a denial is remembered; a grant is the integrator's on every load
+             * while consent stands, so it never outlives the banner that gave it
+             * ([spec/capture.md] § Consent first). A grant an earlier runtime
+             * stored is deleted. A second init keeps the decision this page made.
+             */
+            if (consentState !== "unknown")
+                return;
             const storedConsent = safeGet(ports.storage, CONSENT_KEY);
-            consentState =
-                storedConsent === "granted" || storedConsent === "denied"
-                    ? storedConsent
-                    : "unknown";
-            if (consentState === "granted") {
-                ports.sightings?.start();
-                scheduleFlush(FLUSH_INTERVAL_MS);
-            }
+            if (storedConsent === "denied")
+                consentState = "denied";
+            else if (storedConsent !== null)
+                safeRemove(ports.storage, CONSENT_KEY);
         },
         consent: {
             grant() {
                 if (!initialized)
                     return;
                 consentState = "granted";
-                safeSet(ports.storage, CONSENT_KEY, "granted");
+                safeRemove(ports.storage, CONSENT_KEY);
                 ports.sightings?.start();
                 const buffered = pending;
                 pending = [];
@@ -919,6 +923,8 @@ function createTagSightingPort() {
     };
 }
 const WEB_PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
+/** The tab's verification nonce, in `sessionStorage`, written at the grant. */
+const VERIFICATION_KEY = "__tl.v";
 class MemoryStorage {
     constructor() {
         this.values = new Map();
@@ -939,6 +945,20 @@ let engine;
 let verification;
 let configValid = false;
 let listenersInstalled = false;
+/**
+ * Calls made before `init`, made in order once it has run, up to the same 100
+ * the engine holds before consent; past that they are dropped
+ * ([spec/capture.md] § Consent first).
+ */
+let early = [];
+/** True when there is no engine yet, and the call was held, or dropped. */
+function heldForInit(call) {
+    if (engine !== undefined)
+        return false;
+    if (early.length < PRE_CONSENT_CAP)
+        early.push(call);
+    return true;
+}
 function browserStorage() {
     try {
         return window.localStorage;
@@ -947,11 +967,39 @@ function browserStorage() {
         return new MemoryStorage();
     }
 }
+/**
+ * A page opened from a verification session carries the marker and has an
+ * opener. Once consent is granted there, the tab keeps the nonce, so the mark
+ * follows it to the site's next pages and back from a payment taken
+ * elsewhere, to the same origin ([spec/capture.md] § Verification mode).
+ */
 function verificationMode() {
     const nonce = new URL(window.location.href).searchParams.get("__tl_verify");
-    return nonce !== null && nonce.length > 0 && window.opener !== null
-        ? { nonce, opener: window.opener }
-        : undefined;
+    if (nonce !== null && nonce.length > 0 && window.opener !== null) {
+        return { nonce, opener: window.opener };
+    }
+    let kept = null;
+    try {
+        kept = window.sessionStorage.getItem(VERIFICATION_KEY);
+    }
+    catch {
+        // An unreadable tab storage keeps no mark.
+    }
+    return kept === null || kept.length === 0
+        ? undefined
+        : { nonce: kept, opener: window.opener };
+}
+function keepVerification(keep) {
+    try {
+        if (!keep)
+            window.sessionStorage.removeItem(VERIFICATION_KEY);
+        else if (verification !== undefined) {
+            window.sessionStorage.setItem(VERIFICATION_KEY, verification.nonce);
+        }
+    }
+    catch {
+        // A tab that cannot keep it marks this page only.
+    }
 }
 function landingPage() {
     const url = new URL(window.location.href);
@@ -1006,7 +1054,7 @@ function isEndpointValid(endpoint) {
     }
 }
 function reportDiagnostic() {
-    if (verification === undefined)
+    if (verification === undefined || verification.opener === null)
         return;
     verification.opener.postMessage({
         type: "tracelog:diag",
@@ -1103,17 +1151,28 @@ function init(options) {
         ...(options.endpoint === undefined ? {} : { endpoint }),
     });
     installListeners();
+    const held = early;
+    early = [];
+    for (const call of held)
+        call();
     reportDiagnostic();
 }
 const TraceLog = {
     init,
     consent: {
         grant() {
+            if (heldForInit(() => TraceLog.consent.grant()))
+                return;
             engine?.consent.grant();
+            if (engine?.consent.state() === "granted")
+                keepVerification(true);
             reportDiagnostic();
         },
         deny() {
+            if (heldForInit(() => TraceLog.consent.deny()))
+                return;
             engine?.consent.deny();
+            keepVerification(false);
             reportDiagnostic();
         },
         state() {
@@ -1121,10 +1180,14 @@ const TraceLog = {
         },
     },
     step(name, context) {
+        if (heldForInit(() => TraceLog.step(name, context)))
+            return;
         engine?.step(name, context);
         reportDiagnostic();
     },
     conversion(name, options) {
+        if (heldForInit(() => TraceLog.conversion(name, options)))
+            return;
         engine?.conversion(name, options);
         reportDiagnostic();
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tracelog/capture-web",
-  "version": "1.3.1",
+  "version": "2.0.0",
   "description": "The TraceLog browser capture runtime: consent-first, pinned per version.",
   "keywords": [
     "conversion",
@@ -45,8 +45,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@tracelog/capture-core": "1.3.1",
-    "@tracelog/event-contract": "1.3.1"
+    "@tracelog/capture-core": "2.0.0",
+    "@tracelog/event-contract": "2.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node build.mjs",