@tracelog/capture-web 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -18,6 +18,20 @@ 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.
 
+## [1.2.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@1.1.0...capture-web@1.2.0) (2026-09-22)
+
+
+### Added
+
+* **capture-web:** read Meta's form and report its beacon as unread ([bd78f98](https://github.com/nacorga/tracelog-sdk/commit/bd78f98a9c478b863399d9e86090b31a906743c5))
+
+## [1.1.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@1.0.0...capture-web@1.1.0) (2026-09-21)
+
+
+### Added
+
+* **capture-web:** read the page's tag requests through Resource Timing ([3de9b5c](https://github.com/nacorga/tracelog-sdk/commit/3de9b5ccea21ed82f198b9885c1d6143f7ca71c1))
+
 ## 1.0.0
 
 The first published runtime.

package/README.md

@@ -1,7 +1,9 @@
 # @tracelog/capture-web
 
 The TraceLog browser capture runtime. It captures the conversion path a project
-declares — each conversion and the steps preceding it — and nothing else.
+declares — each conversion and the steps preceding it — and, beside each
+conversion, which GA4, Meta and Google Ads tags the page requested; nothing
+else.
 
 TraceLog is Trustworthy Conversion Intelligence — conversion intelligence you
 can verify: it verifies the conversion path a project declares against the
@@ -12,20 +14,21 @@ incomplete, and never makes up a number.
 
 ## Install
 
-**Every integration names a version.** There is no `latest` on npm and no
-`v/latest/` on the CDN, so the version you pin is the bytes you get, for as long
+**Every integration names a version, exactly.** Install with `--save-exact`,
+so your manifest names this version rather than a range, and there is no
+`v/latest/` on the CDN: the version you pin is the bytes you get, for as long
 as they are served.
 
 <!-- x-release-please-start-version -->
 
 ```bash
-npm install @tracelog/capture-web@1.0.0
+npm install --save-exact @tracelog/capture-web@1.2.0
 ```
 
 Without a build step, the same runtime as a script tag:
 
 ```html
-<script src="https://cdn.tracelog.io/v/1.0.0/tracelog.js"></script>
+<script src="https://cdn.tracelog.io/v/1.2.0/tracelog.js"></script>
 ```
 
 <!-- x-release-please-end -->
@@ -86,6 +89,17 @@ The events your tracking plan declares, with their context. Not page views, not
 clicks, not scroll, not keystrokes. Errors are captured only when they occur
 inside the conversion path, attached to the step where they happened.
 
+Beside each conversion, which GA4, Meta and Google Ads tags the page requested
+just before and after it — the tag's kind, its id and, for Meta, the event —
+read from the browser's own record of the page's requests and, for the one
+Meta request that record leaves out, from the two fields of the form Meta's
+script adds to the page that name the pixel and the event. Nothing else of
+those requests is kept. A Meta request whose pixel the page does not show is
+reported as Meta, unread. A conversion is held ten seconds so those requests can
+be seen, sent at once when the page is hidden — its report then says whether it
+was cut short — and never held in verification mode. Context keys beginning
+with `__tl.` are TraceLog's and are removed.
+
 Identity is first-party and per site: no cross-site tracking, no fingerprinting.
 An IP address is read once when the event arrives to derive a two-letter country
 code, then discarded.

package/dist/tracelog.esm.js

@@ -3,10 +3,17 @@ const MAX_BATCH_BYTES = 262144;
 const MAX_BATCH_EVENTS = 50;
 const MAX_CONTEXT_BYTES = 8192;
 const MAX_ERROR_MESSAGE_BYTES = 1024;
+const MAX_TAG_SIGHTINGS = 16;
+const TAG_SIGHTINGS_CONTEXT_KEY = "__tl.tags";
+const TAG_ID_PATTERNS = {"ga4":"^G-[A-Z0-9]{4,15}$","meta":"^[0-9]{6,20}$","google_ads":"^AW-[0-9]{6,15}(?:/[A-Za-z0-9_-]{1,64})?$"};
+const TAG_EVENT_PATTERN = "^[A-Za-z0-9_]{1,64}$";
+const tagSightingKinds = ["ga4","meta","google_ads"];
 const CONSENT_KEY = "__tl.c";
 const SESSION_KEY = "__tl.s";
 const ACTIVITY_KEY = "__tl.a";
 const QUEUE_KEY = "__tl.q";
+/** The namespace the runtime owns, in storage and in an event's context. */
+const RUNTIME_KEY_PREFIX = "__tl.";
 /**
  * How many events wait in memory before consent. A platform artifact that
  * buffers its own platform's events ahead of this engine holds the same line,
@@ -30,6 +37,13 @@ const PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
 const MAX_IDENTIFIER_LENGTH = 256;
 const CURRENCY_PATTERN = /^[A-Z]{3}$/;
 const textEncoder = new TextEncoder();
+/**
+ * The tag sighting window around a conversion ([spec/capture.md] § Tag
+ * sightings). Ten seconds after is almost twice the longest hold measured:
+ * GA4 was measured holding a purchase 5.0 to 5.6 seconds.
+ */
+const TAG_SIGHTING_BEFORE_MS = 30000;
+const TAG_SIGHTING_AFTER_MS = 10000;
 function safeGet(storage, key) {
     try {
         return storage.getItem(key);
@@ -120,7 +134,12 @@ function jsonContext(value) {
             Array.isArray(parsed)) {
             return undefined;
         }
-        return parsed;
+        const context = parsed;
+        for (const key of Object.keys(context)) {
+            if (key.startsWith(RUNTIME_KEY_PREFIX))
+                delete context[key];
+        }
+        return context;
     }
     catch {
         return undefined;
@@ -149,6 +168,9 @@ function isConversionValid(options) {
             (Number.isFinite(options.value) && options.value >= 0)) &&
         (options.currency === undefined || CURRENCY_PATTERN.test(options.currency)));
 }
+function serializedBytes(value) {
+    return textEncoder.encode(JSON.stringify(value)).byteLength;
+}
 function batchFrom(events) {
     const selected = [];
     const unsendable = [];
@@ -159,7 +181,7 @@ function batchFrom(events) {
             v: EVENT_ENVELOPE_VERSION,
             events: [...selected, event],
         };
-        if (textEncoder.encode(JSON.stringify(candidate)).byteLength > MAX_BATCH_BYTES) {
+        if (serializedBytes(candidate) > MAX_BATCH_BYTES) {
             if (selected.length === 0) {
                 unsendable.push(event);
                 continue;
@@ -176,7 +198,20 @@ function createCaptureEngine(ports, acquisition) {
     let config = { key: "", endpoint: "/v1/events" };
     let pending = [];
     let lastDeclaredName;
-    let sending = false;
+    /**
+     * Every send in flight, by count and by the union of their event ids: a
+     * page hide sends alongside one rather than wait for it, so there can be
+     * two, and each must leave the other's events alone.
+     */
+    let sendsInFlight = 0;
+    const inFlight = new Set();
+    /**
+     * The conversions this page emitted and holds for their tag sighting
+     * window: the instant each was emitted, and whether its report can be
+     * complete. In memory only — a held conversion is in the stored queue like
+     * any other, and a reload sends it as it is.
+     */
+    const held = new Map();
     let flushTimer;
     let consecutiveFailures = 0;
     let circuit = "closed";
@@ -224,7 +259,12 @@ function createCaptureEngine(ports, acquisition) {
         addDrop(queue, "invalid_event");
         writeQueue(ports.storage, queue);
     }
-    function emit(pendingEvent) {
+    /**
+     * `buffered` is a conversion made before consent was granted and emitted
+     * at the grant: its window is placed there, after the conversion itself,
+     * so its report is never complete.
+     */
+    function emit(pendingEvent, buffered = false) {
         if (!EVENT_NAME_PATTERN.test(pendingEvent.name)) {
             recordInvalidEvent();
             return;
@@ -261,8 +301,13 @@ function createCaptureEngine(ports, acquisition) {
         else {
             const options = pendingEvent.options;
             const context = jsonContext(options.context);
+            const base = baseEvent(now, session.id);
+            if (acquisition.mode !== "verification" &&
+                ports.sightings?.observing() === true) {
+                held.set(base.eventId, { at: now.getTime(), whole: !buffered });
+            }
             persistEvent({
-                ...baseEvent(now, session.id),
+                ...base,
                 kind: "conversion",
                 name: pendingEvent.name,
                 identifier: options.identifier,
@@ -285,12 +330,82 @@ function createCaptureEngine(ports, acquisition) {
         }
         emit(pendingEvent);
     }
+    /**
+     * Gives each held conversion whose window has closed — or every one, at
+     * page hide — the report of what the port saw around it, and lets it go.
+     */
+    function release(all) {
+        if (held.size === 0)
+            return;
+        const now = ports.clock.now().getTime();
+        const due = [...held].filter(([, hold]) => all || now - hold.at >= TAG_SIGHTING_AFTER_MS);
+        if (due.length === 0)
+            return;
+        const queue = readQueue(ports.storage);
+        let reported = false;
+        for (const [eventId, hold] of due) {
+            held.delete(eventId);
+            // Gone from the queue — sent by another tab, or dropped by overflow.
+            const event = queue.events.find((candidate) => candidate.eventId === eventId);
+            const answer = event === undefined
+                ? null
+                : (ports.sightings?.around(new Date(hold.at)) ?? null);
+            if (event === undefined || answer === null)
+                continue;
+            const unread = ports.sightings?.unreadAround?.(new Date(hold.at)) ?? null;
+            const report = {
+                complete: hold.whole &&
+                    now - hold.at >= TAG_SIGHTING_AFTER_MS &&
+                    answer.length <= MAX_TAG_SIGHTINGS,
+                sightings: answer.slice(0, MAX_TAG_SIGHTINGS),
+                ...(unread === null ? {} : { unread }),
+            };
+            const context = {
+                ...event.context,
+                [TAG_SIGHTINGS_CONTEXT_KEY]: report,
+            };
+            if (serializedBytes(context) <= MAX_CONTEXT_BYTES) {
+                event.context = context;
+                reported = true;
+            }
+        }
+        if (reported)
+            writeQueue(ports.storage, queue);
+    }
+    /** Until the earliest held conversion's window closes. */
+    function untilRelease() {
+        const now = ports.clock.now().getTime();
+        let earliest = Number.POSITIVE_INFINITY;
+        for (const hold of held.values()) {
+            earliest = Math.min(earliest, hold.at + TAG_SIGHTING_AFTER_MS);
+        }
+        return Math.max(0, earliest - now);
+    }
     async function flush(keepalive = false) {
-        if (!initialized || consentState !== "granted" || sending)
+        release(keepalive);
+        if (!initialized || consentState !== "granted")
+            return;
+        if (sendsInFlight > 0 && !keepalive)
             return;
         const queue = readQueue(ports.storage);
-        if (queue.events.length === 0 || !PUBLIC_KEY_PATTERN.test(config.key)) {
-            scheduleFlush(FLUSH_INTERVAL_MS);
+        const ready = queue.events.filter((event) => !held.has(event.eventId) && !inFlight.has(event.eventId));
+        if (ready.length === 0 || !PUBLIC_KEY_PATTERN.test(config.key)) {
+            if (sendsInFlight === 0) {
+                scheduleFlush(ready.length === 0 && held.size > 0
+                    ? untilRelease()
+                    : FLUSH_INTERVAL_MS);
+            }
+            return;
+        }
+        /**
+         * A page being hidden gets no later chance, so it sends what no send in
+         * flight carries at once, whatever the circuit's state, and the answer is
+         * read as any other's.
+         */
+        if (sendsInFlight > 0) {
+            const { batch } = batchFrom(ready);
+            if (batch.events.length > 0)
+                await deliver(batch, true);
             return;
         }
         const now = ports.clock.now().getTime();
@@ -301,7 +416,7 @@ function createCaptureEngine(ports, acquisition) {
             }
             circuit = "half_open";
         }
-        const { batch, unsendable } = batchFrom(queue.events);
+        const { batch, unsendable } = batchFrom(ready);
         if (unsendable.length > 0) {
             const dropped = new Set(unsendable.map((event) => event.eventId));
             queue.events = queue.events.filter((event) => !dropped.has(event.eventId));
@@ -312,7 +427,18 @@ function createCaptureEngine(ports, acquisition) {
             scheduleFlush(FLUSH_INTERVAL_MS);
             return;
         }
-        sending = true;
+        await deliver(batch, keepalive);
+    }
+    /**
+     * One send, and its answer. It removes from the stored queue exactly what
+     * it carried, by its own read, filter and write at the moment it settles,
+     * so a send beside it keeps what it delivered.
+     */
+    async function deliver(batch, keepalive) {
+        const carried = new Set(batch.events.map((event) => event.eventId));
+        for (const eventId of carried)
+            inFlight.add(eventId);
+        sendsInFlight += 1;
         try {
             const response = await ports.transport.send({
                 endpoint: config.endpoint,
@@ -322,8 +448,7 @@ function createCaptureEngine(ports, acquisition) {
             });
             if (response.status >= 200 && response.status < 300) {
                 const currentQueue = readQueue(ports.storage);
-                const delivered = new Set(batch.events.map((event) => event.eventId));
-                currentQueue.events = currentQueue.events.filter((event) => !delivered.has(event.eventId));
+                currentQueue.events = currentQueue.events.filter((event) => !carried.has(event.eventId));
                 if ((response.rejected ?? 0) > 0) {
                     addDrop(currentQueue, "server_rejected", response.rejected);
                 }
@@ -345,8 +470,7 @@ function createCaptureEngine(ports, acquisition) {
                 response.status < 500 &&
                 response.status !== 429) {
                 const currentQueue = readQueue(ports.storage);
-                const rejected = new Set(batch.events.map((event) => event.eventId));
-                currentQueue.events = currentQueue.events.filter((event) => !rejected.has(event.eventId));
+                currentQueue.events = currentQueue.events.filter((event) => !carried.has(event.eventId));
                 addDrop(currentQueue, "server_rejected", batch.events.length);
                 writeQueue(ports.storage, currentQueue);
                 consecutiveFailures = 0;
@@ -369,7 +493,9 @@ function createCaptureEngine(ports, acquisition) {
             }
         }
         finally {
-            sending = false;
+            for (const eventId of carried)
+                inFlight.delete(eventId);
+            sendsInFlight -= 1;
         }
     }
     const engine = {
@@ -384,8 +510,10 @@ function createCaptureEngine(ports, acquisition) {
                 storedConsent === "granted" || storedConsent === "denied"
                     ? storedConsent
                     : "unknown";
-            if (consentState === "granted")
+            if (consentState === "granted") {
+                ports.sightings?.start();
                 scheduleFlush(FLUSH_INTERVAL_MS);
+            }
         },
         consent: {
             grant() {
@@ -393,10 +521,11 @@ function createCaptureEngine(ports, acquisition) {
                     return;
                 consentState = "granted";
                 safeSet(ports.storage, CONSENT_KEY, "granted");
+                ports.sightings?.start();
                 const buffered = pending;
                 pending = [];
                 for (const pendingEvent of buffered)
-                    emit(pendingEvent);
+                    emit(pendingEvent, true);
                 scheduleFlush(FLUSH_INTERVAL_MS);
             },
             deny() {
@@ -405,6 +534,8 @@ function createCaptureEngine(ports, acquisition) {
                 consentState = "denied";
                 pending = [];
                 lastDeclaredName = undefined;
+                ports.sightings?.stop();
+                held.clear();
                 safeSet(ports.storage, CONSENT_KEY, "denied");
                 safeRemove(ports.storage, SESSION_KEY);
                 safeRemove(ports.storage, ACTIVITY_KEY);
@@ -480,6 +611,265 @@ function createCaptureEngine(ports, acquisition) {
 const systemClock = {
     now: () => new Date(Date.now()),
 };
+/**
+ * A Resource Timing entry's start, on the system clock: its reading minus the
+ * entry's monotonic age. `performance.timeOrigin` would be a second clock, and
+ * it can disagree with this one by as much as the machine's clock drifted
+ * since the page loaded; the age is read on one clock and the instant on the
+ * other, so a sighting and the conversion it is compared with are dated alike
+ * ([spec/capture.md] § Tag sightings).
+ */
+function instantOfEntry(startTime) {
+    return new Date(systemClock.now().getTime() - (performance.now() - startTime));
+}
+/**
+ * How many matches the port keeps. A page making more tag requests than this
+ * inside one window is one whose report the port declines to give, never one
+ * it gives short.
+ */
+const TAG_SIGHTING_MEMORY = 100;
+const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
+const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
+const adsIdPattern = new RegExp(TAG_ID_PATTERNS.google_ads);
+const tagEventPattern = new RegExp(TAG_EVENT_PATTERN);
+const adsPathPattern = /^\/pagead\/(?:conversion|viewthroughconversion|1p-conversion)\/([0-9]{6,15})\/$/;
+function onMetaEndpoint(url) {
+    const host = url.hostname;
+    return ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
+        (url.pathname === "/tr" || url.pathname === "/tr/"));
+}
+/** A request on Meta's endpoint whose pixel id does not fit is Meta, unread. */
+function metaMatch(id, event) {
+    return id !== null && metaIdPattern.test(id)
+        ? {
+            sighting: {
+                kind: "meta",
+                id,
+                event: event !== null && tagEventPattern.test(event) ? event : null,
+            },
+        }
+        : { unread: "meta" };
+}
+/**
+ * The matching table ([spec/capture.md] § Tag sightings): GA4 and Google Ads
+ * key on the path and the id, so a regional host and a first-party tagging
+ * domain that keeps the path both match; Meta keys on its host as well. What
+ * is answered is the tag's kind, its id and Meta's event — nothing else of
+ * the URL, which carries the page address and the vendor's client id. Meta's
+ * beacon leaves an entry named by its bare endpoint, which names no pixel:
+ * that is Meta, unread.
+ */
+function matchTagRequest(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const path = parsed.pathname;
+    const parameters = parsed.searchParams;
+    if (path.endsWith("/g/collect")) {
+        const id = parameters.get("tid");
+        return id !== null && ga4IdPattern.test(id)
+            ? { sighting: { kind: "ga4", id, event: null } }
+            : null;
+    }
+    if (onMetaEndpoint(parsed)) {
+        return metaMatch(parameters.get("id"), parameters.get("ev"));
+    }
+    const ads = adsPathPattern.exec(path);
+    if (ads !== null) {
+        const id = `AW-${ads[1]}`;
+        const labelled = `${id}/${parameters.get("label") ?? ""}`;
+        return {
+            sighting: {
+                kind: "google_ads",
+                id: adsIdPattern.test(labelled) ? labelled : id,
+                event: null,
+            },
+        };
+    }
+    return null;
+}
+/**
+ * Meta's long request in Chrome: a form posted into a hidden frame, which
+ * leaves no Resource Timing entry ([spec/capture.md] § Tag sightings, _Meta's
+ * long request_). Two fields are asked for, the ones that name the pixel and
+ * the event, and nothing else of the form is read: its other fields carry the
+ * visitor's identifiers, hashed.
+ */
+function matchTagForm(form) {
+    let action;
+    try {
+        action = new URL(form.action);
+    }
+    catch {
+        return null;
+    }
+    if (!onMetaEndpoint(action))
+        return null;
+    const id = form.querySelector('input[name="id"]');
+    const event = form.querySelector('input[name="ev"]');
+    return metaMatch(id?.value ?? null, event?.value ?? null);
+}
+/**
+ * The browser's own record of the page's requests, read through a buffered
+ * `PerformanceObserver` once consent is granted and never before — and, for
+ * the one request that record leaves out, the forms the page's body gains,
+ * read through a `MutationObserver` on the body's own children. Nothing is
+ * wrapped, patched or replaced — no `fetch`, no beacon, no vendor's global —
+ * because the runtime runs on somebody else's page and nothing it does may
+ * change what another script sees.
+ */
+function createTagSightingPort() {
+    let observer;
+    let bodyObserver;
+    /**
+     * From when the body's children were watched, on the system clock: minus
+     * infinity when observation began before the body existed, and so saw every
+     * form a script added to it; undefined while no body observer runs — never
+     * created, still waiting for the body, or failed.
+     */
+    let watchedFrom;
+    /** Ordered by `at`, oldest first; at most `TAG_SIGHTING_MEMORY`. */
+    let matches = [];
+    function remember(match, at) {
+        if (match === null)
+            return;
+        let index = matches.length;
+        while (index > 0 && matches[index - 1].at > at)
+            index -= 1;
+        matches.splice(index, 0, { match, at });
+        if (matches.length > TAG_SIGHTING_MEMORY)
+            matches.shift();
+    }
+    function record(entries) {
+        for (const entry of entries) {
+            remember(matchTagRequest(entry.name), instantOfEntry(entry.startTime).getTime());
+        }
+    }
+    /**
+     * One observer, on the body's children and nothing below them. Before the
+     * body exists it watches the root's children for the body, and moves to it.
+     */
+    function watchBody() {
+        try {
+            const document = window.document;
+            let body = document.body;
+            const created = new window.MutationObserver((records) => {
+                try {
+                    for (const change of records) {
+                        const added = change.addedNodes;
+                        for (let index = 0; index < added.length; index += 1) {
+                            const node = added[index];
+                            if (change.target === body) {
+                                if (node.nodeName === "FORM") {
+                                    remember(matchTagForm(node), systemClock.now().getTime());
+                                }
+                            }
+                            else if (body === null && node.nodeName === "BODY") {
+                                body = node;
+                                created.disconnect();
+                                created.observe(node, { childList: true });
+                                watchedFrom = Number.NEGATIVE_INFINITY;
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Capture must never break the host page.
+                }
+            });
+            if (body === null) {
+                created.observe(document.documentElement, { childList: true });
+            }
+            else {
+                created.observe(body, { childList: true });
+                watchedFrom = systemClock.now().getTime();
+            }
+            bodyObserver = created;
+        }
+        catch {
+            watchedFrom = undefined;
+        }
+    }
+    /** What was matched inside the window around `at`, or null. */
+    function within(at) {
+        if (observer === undefined)
+            return null;
+        // What the browser recorded and has not delivered yet: a page being
+        // hidden may not run the callback before the conversion leaves.
+        record(observer.takeRecords());
+        const from = at.getTime() - TAG_SIGHTING_BEFORE_MS;
+        const to = at.getTime() + TAG_SIGHTING_AFTER_MS;
+        if (matches.length >= TAG_SIGHTING_MEMORY && matches[0].at > from) {
+            return null;
+        }
+        return matches
+            .filter(({ at: started }) => started >= from && started <= to)
+            .map(({ match }) => match);
+    }
+    return {
+        start() {
+            if (observer !== undefined)
+                return;
+            try {
+                const Observer = window.PerformanceObserver;
+                if (Observer === undefined ||
+                    !Observer.supportedEntryTypes.includes("resource")) {
+                    return;
+                }
+                const created = new Observer((list) => record(list.getEntries()));
+                created.observe({ type: "resource", buffered: true });
+                observer = created;
+            }
+            catch {
+                observer = undefined;
+                return;
+            }
+            watchBody();
+        },
+        stop() {
+            observer?.disconnect();
+            observer = undefined;
+            bodyObserver?.disconnect();
+            bodyObserver = undefined;
+            watchedFrom = undefined;
+            matches = [];
+        },
+        observing() {
+            return observer !== undefined;
+        },
+        around(at) {
+            const found = within(at);
+            if (found === null)
+                return null;
+            const seen = new Set();
+            const sightings = [];
+            for (const match of found) {
+                if (!("sighting" in match))
+                    continue;
+                const { sighting } = match;
+                const key = `${sighting.kind} ${sighting.id} ${sighting.event ?? ""}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                sightings.push(sighting);
+            }
+            return sightings;
+        },
+        unreadAround(at) {
+            const found = within(at);
+            if (found === null ||
+                watchedFrom === undefined ||
+                watchedFrom > at.getTime() - TAG_SIGHTING_BEFORE_MS) {
+                return null;
+            }
+            return tagSightingKinds.filter((kind) => found.some((match) => "unread" in match && match.unread === kind));
+        },
+    };
+}
 const WEB_PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
 class MemoryStorage {
     constructor() {
@@ -656,6 +1046,7 @@ function init(options) {
                     }
                 },
             },
+            sightings: createTagSightingPort(),
         }, acquisition());
         engine = runtime.engine;
     }

package/dist/tracelog.iife.js

@@ -4,10 +4,17 @@ const MAX_BATCH_BYTES = 262144;
 const MAX_BATCH_EVENTS = 50;
 const MAX_CONTEXT_BYTES = 8192;
 const MAX_ERROR_MESSAGE_BYTES = 1024;
+const MAX_TAG_SIGHTINGS = 16;
+const TAG_SIGHTINGS_CONTEXT_KEY = "__tl.tags";
+const TAG_ID_PATTERNS = {"ga4":"^G-[A-Z0-9]{4,15}$","meta":"^[0-9]{6,20}$","google_ads":"^AW-[0-9]{6,15}(?:/[A-Za-z0-9_-]{1,64})?$"};
+const TAG_EVENT_PATTERN = "^[A-Za-z0-9_]{1,64}$";
+const tagSightingKinds = ["ga4","meta","google_ads"];
 const CONSENT_KEY = "__tl.c";
 const SESSION_KEY = "__tl.s";
 const ACTIVITY_KEY = "__tl.a";
 const QUEUE_KEY = "__tl.q";
+/** The namespace the runtime owns, in storage and in an event's context. */
+const RUNTIME_KEY_PREFIX = "__tl.";
 /**
  * How many events wait in memory before consent. A platform artifact that
  * buffers its own platform's events ahead of this engine holds the same line,
@@ -31,6 +38,13 @@ const PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
 const MAX_IDENTIFIER_LENGTH = 256;
 const CURRENCY_PATTERN = /^[A-Z]{3}$/;
 const textEncoder = new TextEncoder();
+/**
+ * The tag sighting window around a conversion ([spec/capture.md] § Tag
+ * sightings). Ten seconds after is almost twice the longest hold measured:
+ * GA4 was measured holding a purchase 5.0 to 5.6 seconds.
+ */
+const TAG_SIGHTING_BEFORE_MS = 30000;
+const TAG_SIGHTING_AFTER_MS = 10000;
 function safeGet(storage, key) {
     try {
         return storage.getItem(key);
@@ -121,7 +135,12 @@ function jsonContext(value) {
             Array.isArray(parsed)) {
             return undefined;
         }
-        return parsed;
+        const context = parsed;
+        for (const key of Object.keys(context)) {
+            if (key.startsWith(RUNTIME_KEY_PREFIX))
+                delete context[key];
+        }
+        return context;
     }
     catch {
         return undefined;
@@ -150,6 +169,9 @@ function isConversionValid(options) {
             (Number.isFinite(options.value) && options.value >= 0)) &&
         (options.currency === undefined || CURRENCY_PATTERN.test(options.currency)));
 }
+function serializedBytes(value) {
+    return textEncoder.encode(JSON.stringify(value)).byteLength;
+}
 function batchFrom(events) {
     const selected = [];
     const unsendable = [];
@@ -160,7 +182,7 @@ function batchFrom(events) {
             v: EVENT_ENVELOPE_VERSION,
             events: [...selected, event],
         };
-        if (textEncoder.encode(JSON.stringify(candidate)).byteLength > MAX_BATCH_BYTES) {
+        if (serializedBytes(candidate) > MAX_BATCH_BYTES) {
             if (selected.length === 0) {
                 unsendable.push(event);
                 continue;
@@ -177,7 +199,20 @@ function createCaptureEngine(ports, acquisition) {
     let config = { key: "", endpoint: "/v1/events" };
     let pending = [];
     let lastDeclaredName;
-    let sending = false;
+    /**
+     * Every send in flight, by count and by the union of their event ids: a
+     * page hide sends alongside one rather than wait for it, so there can be
+     * two, and each must leave the other's events alone.
+     */
+    let sendsInFlight = 0;
+    const inFlight = new Set();
+    /**
+     * The conversions this page emitted and holds for their tag sighting
+     * window: the instant each was emitted, and whether its report can be
+     * complete. In memory only — a held conversion is in the stored queue like
+     * any other, and a reload sends it as it is.
+     */
+    const held = new Map();
     let flushTimer;
     let consecutiveFailures = 0;
     let circuit = "closed";
@@ -225,7 +260,12 @@ function createCaptureEngine(ports, acquisition) {
         addDrop(queue, "invalid_event");
         writeQueue(ports.storage, queue);
     }
-    function emit(pendingEvent) {
+    /**
+     * `buffered` is a conversion made before consent was granted and emitted
+     * at the grant: its window is placed there, after the conversion itself,
+     * so its report is never complete.
+     */
+    function emit(pendingEvent, buffered = false) {
         if (!EVENT_NAME_PATTERN.test(pendingEvent.name)) {
             recordInvalidEvent();
             return;
@@ -262,8 +302,13 @@ function createCaptureEngine(ports, acquisition) {
         else {
             const options = pendingEvent.options;
             const context = jsonContext(options.context);
+            const base = baseEvent(now, session.id);
+            if (acquisition.mode !== "verification" &&
+                ports.sightings?.observing() === true) {
+                held.set(base.eventId, { at: now.getTime(), whole: !buffered });
+            }
             persistEvent({
-                ...baseEvent(now, session.id),
+                ...base,
                 kind: "conversion",
                 name: pendingEvent.name,
                 identifier: options.identifier,
@@ -286,12 +331,82 @@ function createCaptureEngine(ports, acquisition) {
         }
         emit(pendingEvent);
     }
+    /**
+     * Gives each held conversion whose window has closed — or every one, at
+     * page hide — the report of what the port saw around it, and lets it go.
+     */
+    function release(all) {
+        if (held.size === 0)
+            return;
+        const now = ports.clock.now().getTime();
+        const due = [...held].filter(([, hold]) => all || now - hold.at >= TAG_SIGHTING_AFTER_MS);
+        if (due.length === 0)
+            return;
+        const queue = readQueue(ports.storage);
+        let reported = false;
+        for (const [eventId, hold] of due) {
+            held.delete(eventId);
+            // Gone from the queue — sent by another tab, or dropped by overflow.
+            const event = queue.events.find((candidate) => candidate.eventId === eventId);
+            const answer = event === undefined
+                ? null
+                : (ports.sightings?.around(new Date(hold.at)) ?? null);
+            if (event === undefined || answer === null)
+                continue;
+            const unread = ports.sightings?.unreadAround?.(new Date(hold.at)) ?? null;
+            const report = {
+                complete: hold.whole &&
+                    now - hold.at >= TAG_SIGHTING_AFTER_MS &&
+                    answer.length <= MAX_TAG_SIGHTINGS,
+                sightings: answer.slice(0, MAX_TAG_SIGHTINGS),
+                ...(unread === null ? {} : { unread }),
+            };
+            const context = {
+                ...event.context,
+                [TAG_SIGHTINGS_CONTEXT_KEY]: report,
+            };
+            if (serializedBytes(context) <= MAX_CONTEXT_BYTES) {
+                event.context = context;
+                reported = true;
+            }
+        }
+        if (reported)
+            writeQueue(ports.storage, queue);
+    }
+    /** Until the earliest held conversion's window closes. */
+    function untilRelease() {
+        const now = ports.clock.now().getTime();
+        let earliest = Number.POSITIVE_INFINITY;
+        for (const hold of held.values()) {
+            earliest = Math.min(earliest, hold.at + TAG_SIGHTING_AFTER_MS);
+        }
+        return Math.max(0, earliest - now);
+    }
     async function flush(keepalive = false) {
-        if (!initialized || consentState !== "granted" || sending)
+        release(keepalive);
+        if (!initialized || consentState !== "granted")
+            return;
+        if (sendsInFlight > 0 && !keepalive)
             return;
         const queue = readQueue(ports.storage);
-        if (queue.events.length === 0 || !PUBLIC_KEY_PATTERN.test(config.key)) {
-            scheduleFlush(FLUSH_INTERVAL_MS);
+        const ready = queue.events.filter((event) => !held.has(event.eventId) && !inFlight.has(event.eventId));
+        if (ready.length === 0 || !PUBLIC_KEY_PATTERN.test(config.key)) {
+            if (sendsInFlight === 0) {
+                scheduleFlush(ready.length === 0 && held.size > 0
+                    ? untilRelease()
+                    : FLUSH_INTERVAL_MS);
+            }
+            return;
+        }
+        /**
+         * A page being hidden gets no later chance, so it sends what no send in
+         * flight carries at once, whatever the circuit's state, and the answer is
+         * read as any other's.
+         */
+        if (sendsInFlight > 0) {
+            const { batch } = batchFrom(ready);
+            if (batch.events.length > 0)
+                await deliver(batch, true);
             return;
         }
         const now = ports.clock.now().getTime();
@@ -302,7 +417,7 @@ function createCaptureEngine(ports, acquisition) {
             }
             circuit = "half_open";
         }
-        const { batch, unsendable } = batchFrom(queue.events);
+        const { batch, unsendable } = batchFrom(ready);
         if (unsendable.length > 0) {
             const dropped = new Set(unsendable.map((event) => event.eventId));
             queue.events = queue.events.filter((event) => !dropped.has(event.eventId));
@@ -313,7 +428,18 @@ function createCaptureEngine(ports, acquisition) {
             scheduleFlush(FLUSH_INTERVAL_MS);
             return;
         }
-        sending = true;
+        await deliver(batch, keepalive);
+    }
+    /**
+     * One send, and its answer. It removes from the stored queue exactly what
+     * it carried, by its own read, filter and write at the moment it settles,
+     * so a send beside it keeps what it delivered.
+     */
+    async function deliver(batch, keepalive) {
+        const carried = new Set(batch.events.map((event) => event.eventId));
+        for (const eventId of carried)
+            inFlight.add(eventId);
+        sendsInFlight += 1;
         try {
             const response = await ports.transport.send({
                 endpoint: config.endpoint,
@@ -323,8 +449,7 @@ function createCaptureEngine(ports, acquisition) {
             });
             if (response.status >= 200 && response.status < 300) {
                 const currentQueue = readQueue(ports.storage);
-                const delivered = new Set(batch.events.map((event) => event.eventId));
-                currentQueue.events = currentQueue.events.filter((event) => !delivered.has(event.eventId));
+                currentQueue.events = currentQueue.events.filter((event) => !carried.has(event.eventId));
                 if ((response.rejected ?? 0) > 0) {
                     addDrop(currentQueue, "server_rejected", response.rejected);
                 }
@@ -346,8 +471,7 @@ function createCaptureEngine(ports, acquisition) {
                 response.status < 500 &&
                 response.status !== 429) {
                 const currentQueue = readQueue(ports.storage);
-                const rejected = new Set(batch.events.map((event) => event.eventId));
-                currentQueue.events = currentQueue.events.filter((event) => !rejected.has(event.eventId));
+                currentQueue.events = currentQueue.events.filter((event) => !carried.has(event.eventId));
                 addDrop(currentQueue, "server_rejected", batch.events.length);
                 writeQueue(ports.storage, currentQueue);
                 consecutiveFailures = 0;
@@ -370,7 +494,9 @@ function createCaptureEngine(ports, acquisition) {
             }
         }
         finally {
-            sending = false;
+            for (const eventId of carried)
+                inFlight.delete(eventId);
+            sendsInFlight -= 1;
         }
     }
     const engine = {
@@ -385,8 +511,10 @@ function createCaptureEngine(ports, acquisition) {
                 storedConsent === "granted" || storedConsent === "denied"
                     ? storedConsent
                     : "unknown";
-            if (consentState === "granted")
+            if (consentState === "granted") {
+                ports.sightings?.start();
                 scheduleFlush(FLUSH_INTERVAL_MS);
+            }
         },
         consent: {
             grant() {
@@ -394,10 +522,11 @@ function createCaptureEngine(ports, acquisition) {
                     return;
                 consentState = "granted";
                 safeSet(ports.storage, CONSENT_KEY, "granted");
+                ports.sightings?.start();
                 const buffered = pending;
                 pending = [];
                 for (const pendingEvent of buffered)
-                    emit(pendingEvent);
+                    emit(pendingEvent, true);
                 scheduleFlush(FLUSH_INTERVAL_MS);
             },
             deny() {
@@ -406,6 +535,8 @@ function createCaptureEngine(ports, acquisition) {
                 consentState = "denied";
                 pending = [];
                 lastDeclaredName = undefined;
+                ports.sightings?.stop();
+                held.clear();
                 safeSet(ports.storage, CONSENT_KEY, "denied");
                 safeRemove(ports.storage, SESSION_KEY);
                 safeRemove(ports.storage, ACTIVITY_KEY);
@@ -481,6 +612,265 @@ function createCaptureEngine(ports, acquisition) {
 const systemClock = {
     now: () => new Date(Date.now()),
 };
+/**
+ * A Resource Timing entry's start, on the system clock: its reading minus the
+ * entry's monotonic age. `performance.timeOrigin` would be a second clock, and
+ * it can disagree with this one by as much as the machine's clock drifted
+ * since the page loaded; the age is read on one clock and the instant on the
+ * other, so a sighting and the conversion it is compared with are dated alike
+ * ([spec/capture.md] § Tag sightings).
+ */
+function instantOfEntry(startTime) {
+    return new Date(systemClock.now().getTime() - (performance.now() - startTime));
+}
+/**
+ * How many matches the port keeps. A page making more tag requests than this
+ * inside one window is one whose report the port declines to give, never one
+ * it gives short.
+ */
+const TAG_SIGHTING_MEMORY = 100;
+const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
+const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
+const adsIdPattern = new RegExp(TAG_ID_PATTERNS.google_ads);
+const tagEventPattern = new RegExp(TAG_EVENT_PATTERN);
+const adsPathPattern = /^\/pagead\/(?:conversion|viewthroughconversion|1p-conversion)\/([0-9]{6,15})\/$/;
+function onMetaEndpoint(url) {
+    const host = url.hostname;
+    return ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
+        (url.pathname === "/tr" || url.pathname === "/tr/"));
+}
+/** A request on Meta's endpoint whose pixel id does not fit is Meta, unread. */
+function metaMatch(id, event) {
+    return id !== null && metaIdPattern.test(id)
+        ? {
+            sighting: {
+                kind: "meta",
+                id,
+                event: event !== null && tagEventPattern.test(event) ? event : null,
+            },
+        }
+        : { unread: "meta" };
+}
+/**
+ * The matching table ([spec/capture.md] § Tag sightings): GA4 and Google Ads
+ * key on the path and the id, so a regional host and a first-party tagging
+ * domain that keeps the path both match; Meta keys on its host as well. What
+ * is answered is the tag's kind, its id and Meta's event — nothing else of
+ * the URL, which carries the page address and the vendor's client id. Meta's
+ * beacon leaves an entry named by its bare endpoint, which names no pixel:
+ * that is Meta, unread.
+ */
+function matchTagRequest(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const path = parsed.pathname;
+    const parameters = parsed.searchParams;
+    if (path.endsWith("/g/collect")) {
+        const id = parameters.get("tid");
+        return id !== null && ga4IdPattern.test(id)
+            ? { sighting: { kind: "ga4", id, event: null } }
+            : null;
+    }
+    if (onMetaEndpoint(parsed)) {
+        return metaMatch(parameters.get("id"), parameters.get("ev"));
+    }
+    const ads = adsPathPattern.exec(path);
+    if (ads !== null) {
+        const id = `AW-${ads[1]}`;
+        const labelled = `${id}/${parameters.get("label") ?? ""}`;
+        return {
+            sighting: {
+                kind: "google_ads",
+                id: adsIdPattern.test(labelled) ? labelled : id,
+                event: null,
+            },
+        };
+    }
+    return null;
+}
+/**
+ * Meta's long request in Chrome: a form posted into a hidden frame, which
+ * leaves no Resource Timing entry ([spec/capture.md] § Tag sightings, _Meta's
+ * long request_). Two fields are asked for, the ones that name the pixel and
+ * the event, and nothing else of the form is read: its other fields carry the
+ * visitor's identifiers, hashed.
+ */
+function matchTagForm(form) {
+    let action;
+    try {
+        action = new URL(form.action);
+    }
+    catch {
+        return null;
+    }
+    if (!onMetaEndpoint(action))
+        return null;
+    const id = form.querySelector('input[name="id"]');
+    const event = form.querySelector('input[name="ev"]');
+    return metaMatch(id?.value ?? null, event?.value ?? null);
+}
+/**
+ * The browser's own record of the page's requests, read through a buffered
+ * `PerformanceObserver` once consent is granted and never before — and, for
+ * the one request that record leaves out, the forms the page's body gains,
+ * read through a `MutationObserver` on the body's own children. Nothing is
+ * wrapped, patched or replaced — no `fetch`, no beacon, no vendor's global —
+ * because the runtime runs on somebody else's page and nothing it does may
+ * change what another script sees.
+ */
+function createTagSightingPort() {
+    let observer;
+    let bodyObserver;
+    /**
+     * From when the body's children were watched, on the system clock: minus
+     * infinity when observation began before the body existed, and so saw every
+     * form a script added to it; undefined while no body observer runs — never
+     * created, still waiting for the body, or failed.
+     */
+    let watchedFrom;
+    /** Ordered by `at`, oldest first; at most `TAG_SIGHTING_MEMORY`. */
+    let matches = [];
+    function remember(match, at) {
+        if (match === null)
+            return;
+        let index = matches.length;
+        while (index > 0 && matches[index - 1].at > at)
+            index -= 1;
+        matches.splice(index, 0, { match, at });
+        if (matches.length > TAG_SIGHTING_MEMORY)
+            matches.shift();
+    }
+    function record(entries) {
+        for (const entry of entries) {
+            remember(matchTagRequest(entry.name), instantOfEntry(entry.startTime).getTime());
+        }
+    }
+    /**
+     * One observer, on the body's children and nothing below them. Before the
+     * body exists it watches the root's children for the body, and moves to it.
+     */
+    function watchBody() {
+        try {
+            const document = window.document;
+            let body = document.body;
+            const created = new window.MutationObserver((records) => {
+                try {
+                    for (const change of records) {
+                        const added = change.addedNodes;
+                        for (let index = 0; index < added.length; index += 1) {
+                            const node = added[index];
+                            if (change.target === body) {
+                                if (node.nodeName === "FORM") {
+                                    remember(matchTagForm(node), systemClock.now().getTime());
+                                }
+                            }
+                            else if (body === null && node.nodeName === "BODY") {
+                                body = node;
+                                created.disconnect();
+                                created.observe(node, { childList: true });
+                                watchedFrom = Number.NEGATIVE_INFINITY;
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Capture must never break the host page.
+                }
+            });
+            if (body === null) {
+                created.observe(document.documentElement, { childList: true });
+            }
+            else {
+                created.observe(body, { childList: true });
+                watchedFrom = systemClock.now().getTime();
+            }
+            bodyObserver = created;
+        }
+        catch {
+            watchedFrom = undefined;
+        }
+    }
+    /** What was matched inside the window around `at`, or null. */
+    function within(at) {
+        if (observer === undefined)
+            return null;
+        // What the browser recorded and has not delivered yet: a page being
+        // hidden may not run the callback before the conversion leaves.
+        record(observer.takeRecords());
+        const from = at.getTime() - TAG_SIGHTING_BEFORE_MS;
+        const to = at.getTime() + TAG_SIGHTING_AFTER_MS;
+        if (matches.length >= TAG_SIGHTING_MEMORY && matches[0].at > from) {
+            return null;
+        }
+        return matches
+            .filter(({ at: started }) => started >= from && started <= to)
+            .map(({ match }) => match);
+    }
+    return {
+        start() {
+            if (observer !== undefined)
+                return;
+            try {
+                const Observer = window.PerformanceObserver;
+                if (Observer === undefined ||
+                    !Observer.supportedEntryTypes.includes("resource")) {
+                    return;
+                }
+                const created = new Observer((list) => record(list.getEntries()));
+                created.observe({ type: "resource", buffered: true });
+                observer = created;
+            }
+            catch {
+                observer = undefined;
+                return;
+            }
+            watchBody();
+        },
+        stop() {
+            observer?.disconnect();
+            observer = undefined;
+            bodyObserver?.disconnect();
+            bodyObserver = undefined;
+            watchedFrom = undefined;
+            matches = [];
+        },
+        observing() {
+            return observer !== undefined;
+        },
+        around(at) {
+            const found = within(at);
+            if (found === null)
+                return null;
+            const seen = new Set();
+            const sightings = [];
+            for (const match of found) {
+                if (!("sighting" in match))
+                    continue;
+                const { sighting } = match;
+                const key = `${sighting.kind} ${sighting.id} ${sighting.event ?? ""}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                sightings.push(sighting);
+            }
+            return sightings;
+        },
+        unreadAround(at) {
+            const found = within(at);
+            if (found === null ||
+                watchedFrom === undefined ||
+                watchedFrom > at.getTime() - TAG_SIGHTING_BEFORE_MS) {
+                return null;
+            }
+            return tagSightingKinds.filter((kind) => found.some((match) => "unread" in match && match.unread === kind));
+        },
+    };
+}
 const WEB_PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
 class MemoryStorage {
     constructor() {
@@ -657,6 +1047,7 @@ function init(options) {
                     }
                 },
             },
+            sightings: createTagSightingPort(),
         }, acquisition());
         engine = runtime.engine;
     }

package/package.json

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