@analitikisler/ai-tag-debugger 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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, cookies, 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ı, ç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.0",
   "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,6 +88,19 @@ export function validateAction(input) {
   return null;
 }
 
+// One hung page or model request must not stall a whole run.
+const MODEL_TIMEOUT_MS = 180_000;
+const ACTION_TIMEOUT_MS = 120_000;
+
+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
@@ -106,7 +120,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(), MODEL_TIMEOUT_MS, "The model did not answer within 3 minutes.");
     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,7 +146,7 @@ export async function runAgentJourney(session, journey, opts = {}) {
         continue;
       }
       log(`  ${call.input.reason}`);
-      const error = await session.act(call.input);
+      const error = await withTimeout(session.act(call.input), ACTION_TIMEOUT_MS, "The browser action did not finish within 2 minutes.");
       results.push({ id: call.id, content: pageView(await session.snapshot(), error) });
     }
     if (finished) return finished;
@@ -153,20 +167,29 @@ export async function runScriptedJourney(session, journey, opts = {}) {
   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,22 @@ 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 });
+    log(`\nSaved the site for offline replay in ${opts.saveSite}`);
+  }
   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,62 @@ 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 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), requests with user data in their address, form bodies,
+ * cookies both ways 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 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: e.response.headers.filter((h) => !/^set-cookie$/i.test(h.name)) },
+      };
+    });
+  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 +261,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 +299,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 +375,8 @@ 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) await this.context.routeFromHAR(this.opts.replayHar, { notFound: "abort" });
     if (this.opts.blockHits) {
       await this.context.route((url) => isCollectionEndpoint(url.href), async (route) => {
         await route.fulfill({ status: 204, body: "" });
@@ -598,12 +660,14 @@ export class AuditSession {
   async act(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 +681,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 +700,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 +721,12 @@ 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(() => 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,22 @@ 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 });
+      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 +163,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,97 @@
+// 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, writeFile } from "node:fs/promises";
+import path from "node:path";
+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 } : {}),
+    steps: (start ? steps.slice(1) : steps)
+      .filter((s) => s.replay)
+      .map((s) => ({ ...s.replay, reason: s.label, ...(s.acceptsConsent ? { accepts_consent: 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 });
+  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);
+    incomplete.push(...result.runs.filter((r) => !r.completed).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 };
+}