@analitikisler/ai-tag-debugger 0.6.3 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.7.1 (2026-10-13)
+
+- A page whose script stops responding after a step can no longer stall a run. Reading the page now has a 1 minute limit too, and when it runs out the journey ends as incomplete with a note. Before, only the model call and the browser action itself had a limit.
+- When a saved site's recording can't be cleaned, a warning now says so before the file is deleted.
+
+Replays of saved sites are closer to the saved run, after the first save of 18 real shops:
+
+- Scripted runs, and so replays, wait 3 seconds after the last step, so tags that send a moment after the last click (GA4 batches events) are captured as in an AI run.
+- A step that failed in the saved run is tried again on replay without ending the journey there.
+- A journey the AI could not finish (no cart, a bot check) stays unfinished on replay, so its missing events are not reported as broken.
+- Cookies the server sets for the page's scripts, such as a country, are kept in the recording; HttpOnly cookies, where sessions and logins live, are still left out. Some sites don't render without them, for example a cookie banner that never appears.
+- Images, fonts and video left out of the recording get an empty answer on replay instead of failing, since a failed image can stop a script.
+- Requests that had no answer yet when the browser closed are left out of the recording. On replay they made the page that asked for them again never finish loading.
+- A site whose recording is missing (the browser closed early) is not saved, and `replay` reports a saved site it can't replay and goes on with the next one instead of stopping.
+
+## 0.7.0 (2026-10-12)
+
+Fixes from the first audit run across 18 real shops.
+
+- **GA4 hits with a `gaf` parameter were missed and sent to the real GA4 property** (since 0.6.2). Some sites send `gaf=2` on every normal hit, so `view_item`, `add_to_cart` and others were reported as missing, and the test visits reached the site's analytics. Only copies to `www.google.com` and `doubleclick.net` are now left out, whatever their parameters, and every GA4 request is answered locally again.
+- More Google tag pings are answered locally instead of reaching the real accounts: Google Ads remarketing (`www.google.com/rmkt/collect`), Merchant Center (`merchant-center-analytics.goog/mc/collect`), the Google tag's `/g/s/collect`, and consent mode pings on any host, including Google tag gateway paths on the site's own domain (`/<id>/gs/ccm/collect`).
+- One browsing step can no longer stall a run: a model call that doesn't answer within 3 minutes, or a browser action that doesn't finish within 2, ends the journey as incomplete with a note.
+- **Saved sites and `replay`.** `run --save-site <dir>` also saves every response the site sent (as a Playwright HAR file per journey and viewport, without tracking requests, cookies sent or set, authorization headers, form bodies, or requests with user data in their address) and the steps taken. `replay <dir>...` audits those pages again offline, with no network and no AI model, and lists findings that are new or gone. It exits with code 1 when any changed; `--update` makes the new findings the expected ones. Steps the AI took by ref are saved as CSS paths, or as visible text inside iframes. Images, fonts and video are left out of the recording; when the browser closed early, there is no recording to clean instead of an error.
+
 ## 0.6.3 (2026-10-12)
 
 - The audited site's own email address in a `mailto:` link or a link field (`link_url`, `link_text`, `gtm.elementUrl`, `gtm.elementText`), such as the contact link in a GTM `gtm.linkClick` push, is no longer reported as unhashed user data or redacted. An own-domain address anywhere else, and every named user data field (`email`, `user_data`, `em`, …), is still redacted and reported.

package/README.md

@@ -169,6 +169,19 @@ Each browsing step is one model call, so usage grows with **journeys × viewport
 - **Replay without AI.** After one AI run, copy the steps into `journeys[].steps` and use `--scripted` (with `--no-ai` for zero model calls) on every deploy.
 - **Use a chat app.** Over MCP, the chat app's own model does the browsing, so no API key is used at all.
 
+### Check a new version against saved sites
+
+`--save-site <dir>` also saves every response the site sent and the steps taken. `replay` then audits the same pages again offline, with no network and no AI model, so it costs nothing. It lists findings that are new or gone compared with the saved run:
+
+```bash
+npx @analitikisler/ai-tag-debugger run --site https://www.yourshop.com --journey purchase --save-site saved/yourshop
+npx @analitikisler/ai-tag-debugger replay saved/*
+✗ https://www.yourshop.com (saved/yourshop): 0 new, 1 gone
+    - warning duplicate purchase desktop ga4 page_view
+```
+
+The first run's findings become the expected ones. When a change is right, for example a false alarm that is fixed, `replay --update` makes the new findings the expected ones. Use it to check a new version of the tool against sites you know, or a site change against its last good run. A saved site is usually a few MB. It leaves out tracking requests, images and video, session cookies and the cookies the browser sent, authorization headers, form data, and requests with an email or other user data in their address. It still holds the site's pages and scripts, so keep sites you don't own out of public repositories.
+
 ## Configure your site
 
 `ai-tag-debugger.config.json`:
@@ -229,6 +242,8 @@ ai-tag-debugger run [--site <url>] [--config <file>] [--journey <id>] [--goal "<
                 [--max-steps <n>] [--out <dir>] [--viewport desktop|mobile] [--providers <list>]
                 [--provider anthropic|openai|gemini|openai-compatible] [--model <id>] [--base-url <url>]
                 [--lang en|tr] [--allow-host <host>] [--keep-bodies] [--scripted] [--no-ai] [--fail-on broken|risk|warning|never] [--headed]
+                [--save-site <dir>]
+ai-tag-debugger replay <dir>... [--update] [--out <dir>]
 ai-tag-debugger mcp [--http] [--port <n>] [--host <addr>] [--token <secret>] [--public-url <https url>] [--reports <dir>]
                 [--allow-private-network]
 ```

package/README.tr.md

@@ -171,6 +171,19 @@ Her gezinme adımı bir model çağrısıdır. Yani kullanım **senaryo × ekran
 - **Yapay zekâ olmadan tekrar oynatın.** Bir yapay zekâ çalıştırmasından sonra adımları `journeys[].steps` içine kopyalayın ve her deploy'da `--scripted` (hiç model çağrısı olmaması için `--no-ai` ile birlikte) kullanın.
 - **Bir yapay zekâ asistanı kullanın.** MCP üzerinden gezinmeyi asistanın kendi modeli yapar, hiç API anahtarı kullanılmaz.
 
+### Yeni bir sürümü kaydedilmiş sitelerle karşılaştırın
+
+`--save-site <klasör>`, sitenin gönderdiği her yanıtı ve atılan adımları da kaydeder. `replay` aynı sayfaları ağ ve yapay zekâ modeli olmadan, çevrimdışı olarak yeniden denetler; bu yüzden hiçbir maliyeti yoktur. Kaydedilen çalıştırmaya göre yeni çıkan ya da kaybolan bulguları listeler:
+
+```bash
+npx @analitikisler/ai-tag-debugger run --site https://www.magazaniz.com --journey purchase --save-site saved/magazaniz
+npx @analitikisler/ai-tag-debugger replay saved/*
+✗ https://www.magazaniz.com (saved/magazaniz): 0 new, 1 gone
+    - warning duplicate purchase desktop ga4 page_view
+```
+
+İlk çalıştırmanın bulguları beklenen bulgular olur. Bir değişiklik doğruysa (örneğin düzeltilmiş bir yanlış alarm), `replay --update` yeni bulguları beklenen bulgular yapar. Aracın yeni bir sürümünü bildiğiniz sitelerle ya da bir site değişikliğini son sağlıklı çalıştırmayla karşılaştırmak için kullanın. Kaydedilmiş bir site genellikle birkaç MB'tır. İzleme isteklerini, görselleri ve videoları, oturum çerezlerini ve tarayıcının gönderdiği çerezleri, yetkilendirme başlıklarını, form verilerini ve adresinde e-posta ya da başka kullanıcı verisi olan istekleri içermez. Yine de sitenin sayfalarını ve betiklerini içerdiği için size ait olmayan siteleri herkese açık depolara koymayın.
+
 ## Sitenizi ayarlayın
 
 `ai-tag-debugger.config.json`:
@@ -231,6 +244,8 @@ ai-tag-debugger run [--site <url>] [--config <file>] [--journey <id>] [--goal "<
                 [--max-steps <n>] [--out <dir>] [--viewport desktop|mobile] [--providers <list>]
                 [--provider anthropic|openai|gemini|openai-compatible] [--model <id>] [--base-url <url>]
                 [--lang en|tr] [--allow-host <host>] [--keep-bodies] [--scripted] [--no-ai] [--fail-on broken|risk|warning|never] [--headed]
+                [--save-site <dir>]
+ai-tag-debugger replay <dir>... [--update] [--out <dir>]
 ai-tag-debugger mcp [--http] [--port <n>] [--host <addr>] [--token <secret>] [--public-url <https url>] [--reports <dir>]
                 [--allow-private-network]
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "description": "Open-source AI agent that QA-tests your website's analytics, ad and consent tracking (GA4, GTM, Google Ads, Meta, TikTok). Bring your own model (Claude, OpenAI, Gemini) or use it from your chat app over MCP.",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { AuditSession } from "./browser.js";
 import { messages } from "./i18n.js";
 import { createProvider, PROVIDERS } from "./providers.js";
@@ -87,18 +88,37 @@ export function validateAction(input) {
   return null;
 }
 
+// One hung page or model request must not stall a whole run. A page whose script never
+// stops (an endless loop after a click, for example) can't be read, so reading it has a limit too.
+const TIMEOUTS = { model: 180_000, action: 120_000, page: 60_000 };
+
+const LAST_STEP_WAIT_MS = 3000;
+
+class StepTimeout extends Error {}
+
+/** The promise's value, or a StepTimeout with this message once ms have passed. */
+function withTimeout(promise, ms, message) {
+  let timer;
+  const timeout = new Promise((_, reject) => (timer = setTimeout(() => reject(new StepTimeout(message)), ms)));
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
 /**
  * Lets the AI model drive the browser through one journey.
  * @param {AuditSession} session
  * @param {{ id: string, goal: string }} journey
- * @param {{ provider?: any, providerName?: string, client?: any, model?: string, maxSteps?: number, lang?: string, log?: (msg: string) => void }} opts
+ * @param {{ provider?: any, providerName?: string, client?: any, model?: string, maxSteps?: number, lang?: string, log?: (msg: string) => void, timeouts?: { model?: number, action?: number, page?: number } }} opts
+ *   timeouts: milliseconds for one model answer, one browser action and one read of the page.
  */
 export async function runAgentJourney(session, journey, opts = {}) {
   const provider = opts.provider ?? (await createProvider({ name: opts.providerName, model: opts.model, client: opts.client }));
   const maxSteps = opts.maxSteps ?? 30;
   const log = opts.log ?? (() => {});
+  const limit = { ...TIMEOUTS, ...opts.timeouts };
+  const seconds = (ms) => (ms % 60_000 ? `${Math.round(ms / 1000)} seconds` : ms === 60_000 ? "a minute" : `${ms / 60_000} minutes`);
+  const readPage = () => withTimeout(session.snapshot(), limit.page, `The page stopped responding: it could not be read for ${seconds(limit.page)}.`);
 
-  const first = await session.snapshot();
+  const first = await readPage();
   const chat = provider.conversation({
     system: systemPrompt(opts.lang ?? "en"),
     tools: TOOLS,
@@ -106,7 +126,7 @@ export async function runAgentJourney(session, journey, opts = {}) {
   });
 
   for (let turn = 0; turn < maxSteps; turn++) {
-    const { toolCalls, stop } = await chat.next();
+    const { toolCalls, stop } = await withTimeout(chat.next(), limit.model, `The model did not answer within ${seconds(limit.model)}.`);
     if (stop === "refusal") return { completed: false, note: "The model declined to continue this journey." };
     if (toolCalls.length === 0) {
       if (stop === "max_tokens") return { completed: false, note: "The model response was cut off." };
@@ -132,8 +152,8 @@ export async function runAgentJourney(session, journey, opts = {}) {
         continue;
       }
       log(`  ${call.input.reason}`);
-      const error = await session.act(call.input);
-      results.push({ id: call.id, content: pageView(await session.snapshot(), error) });
+      const error = await withTimeout(session.act(call.input), limit.action, `The browser action did not finish within ${seconds(limit.action)}.`);
+      results.push({ id: call.id, content: pageView(await readPage(), error) });
     }
     if (finished) return finished;
     chat.addToolResults(results);
@@ -150,23 +170,36 @@ export async function runScriptedJourney(session, journey, opts = {}) {
     const error = await session.act(step);
     if (error && !step.optional) return { completed: false, note: `Step "${step.reason ?? step.action}" failed: ${error}` };
   }
+  // Tags often send a moment after the last click (GA4 batches events). An AI run gives them that time
+  // while the model answers; a scripted run would otherwise close the browser first.
+  await session.page.waitForTimeout(LAST_STEP_WAIT_MS);
+  if (journey.incomplete) return { completed: false, note: journey.incomplete };
   return { completed: true, note: "All scripted steps completed." };
 }
 
+/** The file a saved site keeps one journey's recorded responses in. */
+export const harName = (journeyId, viewport) => `${String(journeyId).replace(/[^\w.-]+/g, "_")}-${viewport}.har`;
+
 /**
  * Runs one journey on one viewport and returns everything the checks need.
+ * opts.saveSite records the site's responses into that folder; opts.replaySite answers from one.
  */
 export async function runJourney(config, journey, viewport, opts = {}) {
-  const session = new AuditSession({ viewport, site: config.site, allowedHosts: config.allowed_hosts, providers: config.providers, keepBodies: config.keep_bodies === true, blockHits: config.block_hits !== false, headless: !opts.headed });
+  const har = (dir) => (dir ? path.join(dir, harName(journey.id, viewport)) : undefined);
+  const session = new AuditSession({
+    viewport, site: config.site, allowedHosts: config.allowed_hosts, providers: config.providers, keepBodies: config.keep_bodies === true,
+    blockHits: config.block_hits !== false, headless: !opts.headed, recordHar: har(opts.saveSite), replayHar: har(opts.replaySite),
+  });
   try {
     await session.start();
     const startUrl = new URL(journey.start ?? "/", config.site).href;
     const startError = await session.act({ action: "goto", url: startUrl, reason: `Open ${startUrl}` });
     if (startError) return { ...collect(session, journey, viewport), completed: false, note: `Could not open the start page: ${startError}` };
 
-    const outcome = opts.scripted
-      ? await runScriptedJourney(session, journey, opts)
-      : await runAgentJourney(session, journey, opts);
+    const outcome = await (opts.scripted ? runScriptedJourney(session, journey, opts) : runAgentJourney(session, journey, opts)).catch((err) => {
+      if (err instanceof StepTimeout) return { completed: false, note: err.message };
+      throw err;
+    });
     return { ...collect(session, journey, viewport), ...outcome, cookies: await session.cookies() };
   } finally {
     await session.close();

package/src/audit.js

@@ -9,6 +9,7 @@ import { LANGUAGES, messages } from "./i18n.js";
 import { createProvider } from "./providers.js";
 import { filterFindings, planRun } from "./journeys.js";
 import { resolveProviders } from "./parsers.js";
+import { writeSavedSite } from "./replay.js";
 
 export async function readJson(file, baseDir = ".") {
   const full = path.resolve(baseDir, file);
@@ -48,10 +49,12 @@ export async function writeReports({ outDir, config, plan, runs, findings, expla
 /**
  * @param {{ config: any, plan?: any, gtmContainer?: any, journeys?: string[], goals?: string[], events?: string[], viewports?: string[],
  *   scripted?: boolean, ai?: boolean, provider?: string, model?: string, baseUrl?: string, maxSteps?: number, lang?: string, headed?: boolean,
- *   outDir?: string, branding?: boolean, providers?: string[], log?: (m: string) => void }} opts
+ *   outDir?: string, branding?: boolean, providers?: string[], saveSite?: string, replaySite?: string, log?: (m: string) => void }} opts
  *   journeys: config journey ids or ready-made journeys (purchase, add_to_cart, sign_up, lead, search).
  *   goals: extra journeys described in plain language. events: only check these events.
  *   providers: tracking providers to check (default: config "providers", else GA4, Google Ads, Meta, TikTok).
+ *   saveSite: record the site's responses and the steps taken into this folder, for replaySite (see replay.js).
+ *   replaySite: answer every request from a folder saved with saveSite, without the network.
  */
 export async function runAudit(opts) {
   const { gtmContainer } = opts;
@@ -76,17 +79,23 @@ export async function runAudit(opts) {
   const provider = useAi ? await createProvider({ name: opts.provider ?? config.provider, model: opts.model ?? config.model, baseUrl: opts.baseUrl ?? config.base_url }) : null;
   if (provider) log(`Using ${provider.name} (${provider.model})`);
 
+  if (opts.saveSite) await mkdir(opts.saveSite, { recursive: true });
   const runs = [];
   for (const journey of journeys) {
     for (const viewport of viewports) {
       log(`\n▶ ${journey.id} (${viewport})`);
-      const run = await runJourney(config, journey, viewport, { scripted: opts.scripted, provider, maxSteps: opts.maxSteps, headed: opts.headed, lang, log });
+      const run = await runJourney(config, journey, viewport, { scripted: opts.scripted, provider, maxSteps: opts.maxSteps, headed: opts.headed, lang, log, saveSite: opts.saveSite, replaySite: opts.replaySite });
       log(`  ${run.completed ? "✓" : "✗"} ${run.note} · ${run.hits.length} tracking hits captured`);
       runs.push(run);
     }
   }
 
   const findings = filterFindings(runs.flatMap((run) => checkRun(plan, run, { lang })), events);
+  if (opts.saveSite) {
+    await writeSavedSite(opts.saveSite, { config, plan, runs, findings })
+      .then(() => log(`\nSaved the site for offline replay in ${opts.saveSite}`))
+      .catch((err) => log(`\nCould not save the site in ${opts.saveSite}: ${err.message}`));
+  }
   let explained = null;
   if (provider) {
     log("\nAsking the model to explain the findings…");

package/src/browser.js

@@ -1,3 +1,4 @@
+import { readFile, rm, writeFile } from "node:fs/promises";
 import { chromium, devices } from "playwright";
 import { parseTrackingRequest, isCollectionEndpoint, providerOf, vendorOf, resolveProviders } from "./parsers.js";
 import { redactBody, redactParams, redactPush, redactUrl } from "./redact.js";
@@ -196,6 +197,76 @@ function trackingBody(request) {
   return body ? (body.length > MAX_BODY ? body.slice(0, MAX_BODY) : body) : null;
 }
 
+/**
+ * How a scripted run can find the element an action used again: the selector it was given,
+ * else a CSS path to the element, else its visible text. Refs only mean something in one run.
+ */
+async function replayTarget(a, locator) {
+  if (a.selector) return { selector: a.selector };
+  const found = await locator
+    .evaluate((el) => {
+      const text = (el.innerText || el.value || el.getAttribute("aria-label") || "").replace(/\s+/g, " ").trim().slice(0, 80);
+      if (window !== window.top) return { text };
+      const parts = [];
+      for (let n = el; n && n !== document.documentElement; n = n.parentElement) {
+        if (n.id && document.querySelectorAll(`#${CSS.escape(n.id)}`).length === 1) {
+          parts.unshift(`#${CSS.escape(n.id)}`);
+          break;
+        }
+        let i = 1;
+        for (let s = n.previousElementSibling; s; s = s.previousElementSibling) if (s.tagName === n.tagName) i++;
+        parts.unshift(`${n.tagName.toLowerCase()}:nth-of-type(${i})`);
+      }
+      return { selector: parts.join(" > "), text };
+    }, null, { timeout: 5000 })
+    .catch(() => null);
+  if (found?.selector) return { selector: found.selector };
+  return found?.text ? { text: found.text } : a.text ? { text: a.text } : {};
+}
+
+// Images, fonts and video don't change what tracking sends, and are most of a recording's size.
+const MEDIA = /^(image|font|video|audio)\//;
+
+const MEDIA_FILE = /\.(png|jpe?g|gif|webp|avif|svg|ico|bmp|woff2?|ttf|otf|eot|mp4|webm|mov|mp3|m4a|ogg|wav)$/i;
+const isDroppedMedia = (request) =>
+  ["image", "font", "media"].includes(request.resourceType()) || MEDIA_FILE.test(new URL(request.url()).pathname);
+
+// Cookies the server sets for the page's scripts (a country or language, for example) are kept, since
+// sites often need them to render; HttpOnly ones, where sessions and logins live, are dropped. Replay
+// applies only one Set-Cookie header, so the kept ones are joined into one, one cookie per line.
+function keptHeaders(headers) {
+  const isSetCookie = (h) => /^set-cookie$/i.test(h.name);
+  const cookies = headers.filter(isSetCookie).flatMap((h) => h.value.split("\n")).filter((c) => !/;\s*httponly\s*(;|$)/i.test(c));
+  return [...headers.filter((h) => !isSetCookie(h)), ...(cookies.length ? [{ name: "Set-Cookie", value: cookies.join("\n") }] : [])];
+}
+
+const SECRET_REQUEST_HEADER = /^(cookie|authorization|proxy-authorization)$/i;
+
+/**
+ * Drops images, fonts, video and tracking requests from a recording (they are answered locally on replay, and their
+ * URLs can hold the user data redacted everywhere else), unanswered requests, requests with user data in their address, form bodies,
+ * the cookies the browser sent, HttpOnly cookies the server set, and authorization headers.
+ */
+async function cleanRecording(file) {
+  const har = JSON.parse(await readFile(file, "utf8"));
+  har.log.entries = har.log.entries
+    .filter((e) => !isCollectionEndpoint(e.request.url) && !MEDIA.test(e.response?.content?.mimeType ?? ""))
+    // A request that had no answer yet when the browser closed would never finish on replay either.
+    .filter((e) => e.response?.status > 0)
+    // A request whose address holds user data (an email in a form GET, for example) is left out whole.
+    .filter((e) => redactUrl(e.request.url).url === e.request.url)
+    .map((e) => {
+      // Form bodies are dropped; replay then matches POSTs by address and method.
+      const { postData: _postData, ...request } = e.request;
+      return {
+        ...e,
+        request: { ...request, cookies: [], headers: request.headers.filter((h) => !SECRET_REQUEST_HEADER.test(h.name)) },
+        response: { ...e.response, cookies: [], headers: keptHeaders(e.response.headers) },
+      };
+    });
+  await writeFile(file, JSON.stringify(har));
+}
+
 export class AuditSession {
   /**
    * @param {{ viewport: string, site?: string, allowedHosts?: string[], providers?: string[], keepBodies?: boolean, blockPrivate?: boolean | ((ip: string) => boolean), blockHits?: boolean, headless?: boolean }} opts
@@ -204,6 +275,8 @@ export class AuditSession {
    *   providers: which tracking providers to record (default GA4, Google Ads, Meta, TikTok). Requests to the
    *     others are still answered locally, but only counted, per step, in this.skipped.
    *   site: navigation is limited to this site's host and its subdomains, plus allowedHosts.
+   *   recordHar: save every response the site sends into this .har file, so the journey can be replayed offline later.
+   *   replayHar: answer requests from a .har file saved with recordHar instead of the network; requests it lacks fail.
    *   blockPrivate: refuse loopback, private and link-local addresses (used when the MCP server is reachable over HTTP).
    *     All browser traffic then goes through the egress proxy. A function decides which addresses count as private (for tests).
    */
@@ -240,7 +313,8 @@ export class AuditSession {
       launch.args = ["--force-webrtc-ip-handling-policy=disable_non_proxied_udp"];
     }
     this.browser = await chromium.launch(launch);
-    this.context = await this.browser.newContext({ ...device, locale: "en-US" });
+    const record = this.opts.recordHar ? { recordHar: { path: this.opts.recordHar, mode: "minimal" } } : {};
+    this.context = await this.browser.newContext({ ...device, locale: "en-US", ...record });
     await this.context.exposeBinding("__atdRecord", (_source, entry) => {
       this.record("dataLayerLog", { ...this.redactEntry(entry), step: this.currentStep, t: Date.now() });
     });
@@ -315,6 +389,15 @@ export class AuditSession {
     // the page navigates away (a page_view on the next load, a beacon on unload) can be
     // cancelled before its route handler runs, but its request event has already fired.
     this.context.on("request", onRequest);
+    // Registered first, so the routes below run before it and tracking requests are still answered locally.
+    if (this.opts.replayHar) {
+      // Requests the recording lacks fail, except the media left out of it: those get an empty answer,
+      // since a failed image or icon can stop a script (a consent banner waiting for its logo, for example).
+      await this.context.route("**/*", (route) =>
+        isDroppedMedia(route.request()) ? route.fulfill({ status: 200, body: "" }) : route.abort(),
+      );
+      await this.context.routeFromHAR(this.opts.replayHar, { notFound: "fallback" });
+    }
     if (this.opts.blockHits) {
       await this.context.route((url) => isCollectionEndpoint(url.href), async (route) => {
         await route.fulfill({ status: 204, body: "" });
@@ -596,14 +679,23 @@ export class AuditSession {
    * @param {{ action: string, ref?: number, selector?: string, text?: string, value?: string, url?: string, reason?: string, accepts_consent?: boolean }} a
    */
   async act(a) {
+    const error = await this.perform(a);
+    // A scripted replay of this step may fail the same way, which must not end the journey there.
+    if (error) this.steps[this.currentStep].error = error;
+    return error;
+  }
+
+  async perform(a) {
     const describe = a.reason || `${a.action} ${a.selector ?? (a.ref != null ? `#${a.ref}` : a.text != null ? `"${a.text}"` : a.url ?? "")}`.trim();
     this.beginStep(describe, { action: a.action, acceptsConsent: !!a.accepts_consent });
+    const step = this.steps[this.currentStep];
     try {
       switch (a.action) {
         case "goto": {
           const target = new URL(a.url, this.page.url() === "about:blank" ? undefined : this.page.url()).href;
           const refused = await this.checkUrl(target);
           if (refused) return refused;
+          step.replay = { action: "goto", url: target };
           await this.page.goto(target, { waitUntil: "domcontentloaded", timeout: 30000 });
           break;
         }
@@ -617,12 +709,14 @@ export class AuditSession {
             if (found.error) return found.error;
             target = found.locator;
           } else return `${a.action} needs a ref or the element's visible text.`;
+          step.replay = { action: a.action, ...(await replayTarget(a, target)), ...(a.value !== undefined ? { value: a.value } : {}) };
           if (a.action === "click") await this.click(target);
           else if (a.action === "fill") await target.fill(a.value ?? "", { timeout: 10000 });
           else await target.selectOption(a.value ?? "", { timeout: 10000 });
           break;
         }
         case "scroll": {
+          step.replay = { action: "scroll", ...(a.value !== undefined ? { value: a.value } : {}) };
           const dy = /^up$/i.test(a.value ?? "") ? -900 : 900;
           const size = this.page.viewportSize() ?? { width: 800, height: 600 };
           const before = await this.page.evaluate(() => window.scrollY);
@@ -634,6 +728,7 @@ export class AuditSession {
           break;
         }
         case "wait":
+          step.replay = { action: "wait", ...(a.value !== undefined ? { value: a.value } : {}) };
           await this.page.waitForTimeout(Math.min(Number(a.value) || 1000, 10000));
           break;
         default:
@@ -654,6 +749,17 @@ export class AuditSession {
   }
 
   async close() {
+    if (this.opts.recordHar && this.context) {
+      // Writes the recording. If the browser already went away, there is none to clean.
+      const written = await this.context.close().then(() => true, () => false);
+      // A recording that could not be cleaned may hold cookies or form data, so it is deleted.
+      if (written) {
+        await cleanRecording(this.opts.recordHar).catch(async (err) => {
+          console.warn(`Could not clean the recording ${this.opts.recordHar}, so it was deleted: ${err.message}`);
+          await rm(this.opts.recordHar, { force: true });
+        });
+      }
+    }
     await this.browser?.close();
     await this.egress?.close();
   }

package/src/cli.js

@@ -6,6 +6,7 @@ import { LANGUAGES, messages } from "./i18n.js";
 import { PROVIDERS } from "./providers.js";
 import { JOURNEY_PRESETS } from "./journeys.js";
 import { PROVIDERS as TRACKING_PROVIDERS, DEFAULT_PROVIDERS } from "./parsers.js";
+import { replaySavedSite } from "./replay.js";
 
 const USAGE = `ai-tag-debugger: an open-source AI agent that QA-tests your analytics and ad tracking.
 
@@ -13,6 +14,8 @@ Usage:
   ai-tag-debugger run --site <url> --journey purchase [options]   Audit ready-made journeys, no config needed.
   ai-tag-debugger run --site <url> --goal "<what to do>"          Audit a journey you describe in plain language.
   ai-tag-debugger run --config <file> [options]                   Run an audit from a config file.
+  ai-tag-debugger replay <dir>... [--update]      Audit sites saved with --save-site again, offline and without AI,
+                                                  and list findings that changed. Exits with code 1 when any did.
   ai-tag-debugger mcp [--http] [--port <n>]       Start the MCP server for Claude, ChatGPT, Gemini and other chat apps.
 
 Run options:
@@ -41,6 +44,12 @@ Run options:
   --keep-bodies        Store tracking requests as sent. By default, emails, phone numbers and user ids sent
                        for ad matching are redacted in the report and capture.json ("keep_bodies" in the config).
   --no-branding        Leave the Analitik İşler logo and credit line out of the reports ("branding": false in the config).
+  --save-site <dir>    Also save the site's responses and the steps taken in this folder, so "replay" can audit
+                       the same pages again offline. Its findings become the expected ones.
+
+Replay options:
+  --update             Make this replay's findings the expected ones (after checking that the changes are right).
+  --out <dir>          Where to write the replay's reports (default: <dir>/last-replay).
 
 MCP options:
   --http               Serve over Streamable HTTP instead of stdio (for apps that connect to a URL).
@@ -87,6 +96,8 @@ async function main() {
       token: { type: "string" },
       reports: { type: "string" },
       "public-url": { type: "string" },
+      "save-site": { type: "string" },
+      update: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false },
     },
   });
@@ -97,6 +108,27 @@ async function main() {
     await startMcp({ http: values.http, port: values.port ? Number(values.port) : undefined, host: values.host, token: values.token, reportsDir: values.reports, publicUrl: values["public-url"], allowPrivateNetwork: values["allow-private-network"] });
     return;
   }
+  if (command === "replay" && !values.help) {
+    const dirs = positionals.slice(1);
+    if (!dirs.length) throw new Error("replay needs the folder of at least one site saved with --save-site.");
+    let changed = false;
+    for (const dir of dirs) {
+      const r = await replaySavedSite(dir, { update: values.update, outDir: dirs.length === 1 ? values.out : undefined }).catch((err) => {
+        console.log(`✗ ${dir}: could not replay: ${err.message.split("\n")[0]}`);
+        changed = true;
+        return null;
+      });
+      if (!r) continue;
+      const same = !r.missing.length && !r.extra.length;
+      changed ||= !same;
+      console.log(`${same ? "✓" : values.update ? "↻" : "✗"} ${r.site} (${dir}): ${same ? "same findings" : `${r.extra.length} new, ${r.missing.length} gone${values.update ? ", saved as expected" : ""}`}`);
+      for (const k of r.extra) console.log(`    + ${k}`);
+      for (const k of r.missing) console.log(`    - ${k}`);
+      for (const note of r.incomplete) console.log(`    ! ${note}`);
+    }
+    if (changed && !values.update) process.exitCode = 1;
+    return;
+  }
   if (values.help || command !== "run" || (!values.config && !values.site)) {
     console.log(USAGE);
     process.exit(values.help ? 0 : 2);
@@ -136,6 +168,7 @@ async function main() {
     headed: values.headed,
     branding: values["no-branding"] ? false : undefined,
     outDir: values.out,
+    saveSite: values["save-site"],
     log: (msg) => console.log(msg),
   });
 

package/src/parsers.js

@@ -35,9 +35,10 @@ export function parseGa4(url, postData) {
   // Matched on the GA4 protocol rather than the host, so server-side GTM
   // endpoints on first-party domains are captured too.
   if (!u.pathname.endsWith("/g/collect") || u.searchParams.get("v") !== "2") return null;
-  // gtag.js resends a hit to www.google.com/g/collect (marked gaf=1) when the first send
-  // seems lost, and copies some to doubleclick.net. GA4 doesn't count these twice, so they aren't hits.
-  if (GOOGLE_COMPANION_HOST.test(u.hostname) || u.searchParams.has("gaf")) return null;
+  // gtag.js resends a hit to www.google.com/g/collect when the first send seems lost, and
+  // copies some to doubleclick.net. GA4 doesn't count these twice, so they aren't hits.
+  // (Primary hits can carry gaf too, e.g. gaf=2, so the host decides, not the parameter.)
+  if (GOOGLE_COMPANION_HOST.test(u.hostname)) return null;
   const base = new URLSearchParams(u.search);
   const lines = postData ? postData.split("\n").filter(Boolean) : [""];
   return lines.map((line) => {
@@ -135,8 +136,12 @@ export function parseTrackingRequest(url, postData) {
 // hits: Google Ads remarketing and consent pings, and the other common ad pixels.
 const OTHER_BEACONS = [
   [/(^|\.)(doubleclick\.net|googleadservices\.com|google\.[a-z.]+)$/, /^\/pagead\/(viewthroughconversion|1p-user-list|landing)\//],
-  [/(^|\.)google\.[a-z.]+$/, /^\/ccm\/collect/],
+  [/(^|\.)google\.[a-z.]+$/, /^\/rmkt\/collect\//],
   [GOOGLE_COMPANION_HOST, /\/g\/collect$/],
+  [/(^|\.)merchant-center-analytics\.goog$/, /^\/mc\/collect/],
+  // Google tag pings on any host: consent mode (ccm), the Google tag's own /g/s/collect, and
+  // Google tag gateway paths served from the site's own domain (/<id>/gs/ccm/collect).
+  [/./, /\/(ccm|ccm\/s|g\/s)\/collect$/],
   [/^td\.doubleclick\.net$/, /^\/td\//],
   [/(^|\.)facebook\.com$/, /^\/privacy_sandbox\/pixel\//],
   [/^bat\.bing\.com$/, /^\/action\//],

package/src/replay.js

@@ -0,0 +1,108 @@
+// Saved sites: the responses a site sent during an audit and the steps taken, so a later
+// version of the tool can audit the same pages offline and show what it now reports
+// differently. Replays need no network and no AI model, so they cost nothing.
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { harName } from "./agent.js";
+import { runAudit } from "./audit.js";
+
+export const SAVED_SITE_FILE = "site.json";
+
+/** The steps a run took, as fixed steps a scripted run can repeat. */
+export function replayableJourney(run) {
+  const steps = run.steps.filter((s) => s.index > 0);
+  const start = steps[0]?.replay?.action === "goto" ? steps[0].replay.url : undefined;
+  return {
+    id: run.journeyId,
+    viewport: run.viewport,
+    ...(start ? { start } : {}),
+    // A journey the AI could not finish (no cart, a bot check) is still incomplete when its steps replay.
+    ...(run.completed ? {} : { incomplete: run.note }),
+    steps: (start ? steps.slice(1) : steps)
+      .filter((s) => s.replay)
+      .map((s) => ({ ...s.replay, reason: s.label, ...(s.acceptsConsent ? { accepts_consent: true } : {}), ...(s.error ? { optional: true } : {}) })),
+  };
+}
+
+/** One line per finding, sorted: what a replay is compared on. */
+export function findingKeys(findings) {
+  return findings.map((f) => [f.severity, f.check, f.journey, f.viewport, f.platform ?? "-", f.event ?? "-"].join(" ")).sort();
+}
+
+/** Lines in one list and not the other, counting repeats. */
+export function compareKeys(expected, actual) {
+  const left = [...actual];
+  const missing = [];
+  for (const k of expected) {
+    const i = left.indexOf(k);
+    if (i === -1) missing.push(k);
+    else left.splice(i, 1);
+  }
+  return { missing, extra: left };
+}
+
+/** Writes site.json next to the recorded responses. The findings of this run become the expected ones. */
+export async function writeSavedSite(dir, { config, plan, runs, findings }) {
+  await mkdir(dir, { recursive: true });
+  for (const run of runs) {
+    const har = path.join(dir, harName(run.journeyId, run.viewport));
+    if (!(await stat(har).catch(() => null))) {
+      throw new Error(`The recording of ${run.journeyId} (${run.viewport}) is missing, probably because the browser closed early. Save the site again.`);
+    }
+  }
+  const { journeys: _journeys, plan: _plan, gtm_container: _gtm, ...site } = config;
+  const saved = {
+    version: 1,
+    saved_at: new Date().toISOString(),
+    config: site,
+    plan,
+    journeys: runs.map(replayableJourney),
+    expected: findingKeys(findings),
+  };
+  await writeFile(path.join(dir, SAVED_SITE_FILE), JSON.stringify(saved, null, 2));
+}
+
+/**
+ * Audits a saved site again, offline and without AI, and compares the findings with the expected ones.
+ * update: make this replay's findings the expected ones.
+ * @returns {Promise<{ site: string, missing: string[], extra: string[], reportPaths: string[], incomplete: string[] }>}
+ */
+export async function replaySavedSite(dir, { update = false, outDir, log = () => {} } = {}) {
+  const file = path.join(dir, SAVED_SITE_FILE);
+  let saved;
+  try {
+    saved = JSON.parse(await readFile(file, "utf8"));
+  } catch (err) {
+    throw new Error(`Could not read ${file}: ${err.message}`);
+  }
+  const viewports = [...new Set(saved.journeys.map((j) => j.viewport))];
+  const findings = [];
+  const reportPaths = [];
+  const incomplete = [];
+  for (const viewport of viewports) {
+    const journeys = saved.journeys.filter((j) => j.viewport === viewport).map(({ viewport: _v, ...j }) => j);
+    const out = path.resolve(outDir ?? path.join(dir, "last-replay"), viewports.length > 1 ? viewport : "");
+    const result = await runAudit({
+      config: { ...saved.config, journeys },
+      plan: saved.plan,
+      viewports: [viewport],
+      scripted: true,
+      ai: false,
+      replaySite: dir,
+      lang: "en",
+      outDir: out,
+      log,
+    });
+    findings.push(...result.findings);
+    reportPaths.push(result.reportPath);
+    // Journeys that were already unfinished when saved are compared through their findings only.
+    const wasIncomplete = (r) => journeys.find((j) => j.id === r.journeyId)?.incomplete === r.note;
+    incomplete.push(...result.runs.filter((r) => !r.completed && !wasIncomplete(r)).map((r) => `${r.journeyId} (${r.viewport}): ${r.note}`));
+  }
+  const actual = findingKeys(findings);
+  const { missing, extra } = compareKeys(saved.expected ?? [], actual);
+  if (update && (missing.length || extra.length)) {
+    await writeFile(file, JSON.stringify({ ...saved, expected: actual }, null, 2));
+  }
+  return { site: saved.config.site, missing, extra, reportPaths, incomplete };
+}