@analitikisler/ai-tag-debugger 0.16.0 → 0.18.0

package/src/plan-html.js

@@ -1,24 +1,67 @@
-import { CSS, VERSION, escapeHtml, logo, platformLabel } from "./report.js";
+import { VERSION } from "./report-shared.js";
+import { TOKENS, COMPONENTS, PRODUCT } from "./html/css.js";
+import { chip, escapeHtml, logo, plat, platformLabel, sprite } from "./html/lib.js";
 import { LOGOS } from "./brand.js";
 
 const e = escapeHtml;
 const text = (v) => (v === undefined || v === null || v === "" ? `<span class="muted">–</span>` : e(v));
 
+// Only what the plan page needs on top of the report's tokens and components: the top bar (a trimmed copy of the
+// report shell's, which this page does not load, with no rail or verdict), the page column, and the event list. Colours come from tokens, so dark mode
+// follows both selectors in TOKENS and nothing here names a colour.
 const PLAN_CSS = `
-.pl-event{padding:16px 20px}
+.top{display:flex;align-items:center;gap:var(--s3);height:var(--top);padding:0 var(--s4);background:var(--card);border-bottom:1px solid var(--border);white-space:nowrap}
+.top .brand{display:inline-flex;align-items:center;flex:none}
+.top .l-mark{display:none}
+.top-site{display:flex;align-items:baseline;gap:var(--s2);min-width:0;overflow:hidden}
+.top-site b{font-weight:600;overflow:hidden;text-overflow:ellipsis}
+.top-end{margin-left:auto;display:flex;align-items:center;gap:var(--s2)}
+.byline{display:inline-flex;align-items:center;gap:var(--s2);font-size:12px;color:var(--muted)}
+.logo{display:inline-flex}
+.logo .l-dark{display:none}
+html[data-theme="dark"] .logo .l-light{display:none}
+html[data-theme="dark"] .logo .l-dark{display:inline}
+@media (prefers-color-scheme:dark){html:not([data-theme="light"]) .logo .l-light{display:none}html:not([data-theme="light"]) .logo .l-dark{display:inline}}
+.eyebrow{font:600 11px/1.4 var(--font-sans);text-transform:uppercase;letter-spacing:.06em;color:var(--muted)}
+.plan{max-width:1100px;margin:0 auto;padding:var(--s5) var(--s6) var(--s7)}
+.plan-title{display:grid;gap:var(--s2);margin-bottom:var(--s5)}
+.plan-title .chips{margin-top:var(--s1)}
+.plan .card+.card{margin-top:var(--s4)}
+.pl-card-h{padding:var(--s3) var(--s4);border-bottom:1px solid var(--border)}
+.pl-card-d{margin-top:2px;font-size:12.5px;color:var(--muted)}
+.pl-empty{padding:var(--s3) var(--s4)}
+.pl-event{padding:var(--s4)}
 .pl-event+.pl-event{border-top:1px solid var(--border)}
-.pl-head{display:flex;flex-wrap:wrap;align-items:center;gap:8px}
+.pl-head{display:flex;flex-wrap:wrap;align-items:center;gap:var(--s2)}
 .pl-head code{font-size:14px}
 .pl-desc{margin:6px 0 10px}
 .pl-trigger{font-size:12px;color:var(--muted);margin-bottom:10px}
 .pl-trigger b{font-weight:500;color:var(--fg)}
-.flag{display:inline-flex;align-items:center;font:500 12px/1 var(--font-sans);padding:4px 8px;border-radius:4px;background:var(--muted-bg);color:var(--muted)}
-.flag.on{background:var(--accent-bg);color:var(--accent-fg)}
-.flag.req{background:var(--warn-bg);color:var(--warn)}
-table.dt td,table.dt th{vertical-align:top}
+.chip .plat{display:inline-flex;align-items:center;gap:5px}
+.chip.on{--k:var(--accent);--k-fg:var(--accent-fg);background:var(--accent-bg)}
+.chip.req{--k:var(--sev-warning);--k-fg:var(--sev-warning-fg);background:var(--sev-warning-bg)}
+.pl-card-body{padding:var(--s4)}
+.tbl td,.tbl th{vertical-align:top}
+/* a narrow table scrolls inside its .tscroll instead of breaking names mid-word */
+.plan .tbl{min-width:480px}
+.plan .tbl td:first-child code{white-space:nowrap}
+.footer{display:flex;align-items:center;gap:var(--s4);padding:var(--s4);border-top:1px solid var(--border);background:var(--card)}
+.footer a{color:var(--fg)}
+.logo-link{display:inline-flex}
+.f-links{display:flex;flex-wrap:wrap;gap:var(--s2) var(--s4)}
+.footer .f-meta{margin-left:auto}
+@media (max-width:719.98px){
+  :root{--top:44px}
+  .top{gap:var(--s2);padding:0 var(--s3)}
+  .top .l-lockup,.top-site .eyebrow,.byline{display:none}
+  .top .l-mark{display:block}
+  .plan{padding:var(--s4) var(--s4) var(--s6)}
+  .footer{flex-wrap:wrap}
+}
+@media print{.top{display:none}.plan{padding:0}}
 `;
 
-const flag = (label, cls = "") => `<span class="flag ${cls}">${e(label)}</span>`;
+const flag = (label, cls = "") => `<span class="chip ${cls}">${e(label)}</span>`;
 
 function paramsTable(event) {
   const params = Object.entries(event.parameters ?? {});
@@ -27,13 +70,14 @@ function paramsTable(event) {
   const rows = params
     .map(([name, p]) => `<tr><td><code>${e(name)}</code>${p?.custom ? ` ${flag("custom")}` : ""}</td><td>${required.has(name) ? flag("required", "req") : `<span class="muted">optional</span>`}</td><td class="mono">${text(p?.example)}</td><td>${text(p?.description)}</td></tr>`)
     .join("");
-  return `<div class="tscroll"><table class="dt"><thead><tr><th>Parameter</th><th>Required</th><th>Example</th><th>Description</th></tr></thead><tbody>${rows}</tbody></table></div>`;
+  return `<div class="tscroll"><table class="tbl"><thead><tr><th>Parameter</th><th>Required</th><th>Example</th><th>Description</th></tr></thead><tbody>${rows}</tbody></table></div>`;
 }
 
 function eventCard(event) {
   const trigger = event.trigger ?? {};
+  const platform = event.platform ?? "ga4";
   return `<div class="pl-event">
-<div class="pl-head"><span class="ptag">${e(platformLabel(event.platform ?? "ga4"))}</span><code>${e(event.name)}</code>${flag(event.custom ? "custom event" : "standard event", event.custom ? "on" : "")}</div>
+<div class="pl-head">${chip("plat", platform, plat(platform, 13, platformLabel(platform)))}<code>${e(event.name)}</code>${flag(event.custom ? "custom event" : "standard event", event.custom ? "on" : "")}</div>
 <p class="pl-desc">${text(event.description)}</p>
 <p class="pl-trigger"><b>Trigger</b> · page: ${text(trigger.page)} · element: ${text(trigger.element)}</p>
 ${paramsTable(event)}
@@ -42,12 +86,12 @@ ${paramsTable(event)}
 
 function userPropertiesCard(props) {
   const body = props.length
-    ? `<div class="tscroll"><table class="dt"><thead><tr><th>Name</th><th>Example</th><th>Description</th></tr></thead><tbody>${props
+    ? `<div class="pl-card-body"><div class="tscroll"><table class="tbl"><thead><tr><th>Name</th><th>Example</th><th>Description</th></tr></thead><tbody>${props
         .map((p) => (typeof p === "string" ? { name: p } : p))
         .map((p) => `<tr><td><code>${e(p.name)}</code></td><td class="mono">${text(p.example)}</td><td>${text(p.description)}</td></tr>`)
-        .join("")}</tbody></table></div>`
-    : `<p class="muted xs">No user properties.</p>`;
-  return `<section class="card"><div class="card-h"><div class="card-t">User properties</div></div><div class="card-c">${body}</div></section>`;
+        .join("")}</tbody></table></div></div>`
+    : `<p class="pl-empty muted xs">No user properties.</p>`;
+  return `<section class="card"><div class="pl-card-h"><h2>User properties</h2></div>${body}</section>`;
 }
 
 /** A single self-contained, readable page for a measurement plan. Respects branding false like the report. */
@@ -58,19 +102,21 @@ export function renderPlanHtml(plan, { id = "", generatedAt = "", branding = tru
   const meta = [id && `Plan ${id}`, generatedAt, `${events.length} events (${custom} custom)`, `ai-tag-debugger ${VERSION}`].filter(Boolean).join(" · ");
   const consent = plan.consent_mode ? flag("Consent mode on", "on") : flag("Consent mode off");
   const footer = branding
-    ? `<div class="wrap"><a href="https://analitikisler.com" class="logo-link" aria-label="analitikisler.com" rel="noopener noreferrer">${logo("stacked", "Analitik İşler", 56, "logo-s")}</a><div><div class="f-links"><a href="https://analitikisler.com" rel="noopener noreferrer">analitikisler.com</a><a href="https://github.com/analitikisler/ai-tag-debugger" rel="noopener noreferrer">GitHub</a></div></div><div class="f-meta">v${VERSION}</div></div>`
-    : `<div class="wrap plain"><div class="f-meta">AI Tag Debugger</div><div class="f-meta">v${VERSION}</div></div>`;
+    ? `<a href="https://analitikisler.com" class="logo-link" aria-label="analitikisler.com" rel="noopener noreferrer">${logo("stacked", "Analitik İşler", 40, "logo-s")}</a><div class="f-links xs"><a href="https://analitikisler.com" rel="noopener noreferrer">analitikisler.com</a><a href="https://github.com/analitikisler/ai-tag-debugger" rel="noopener noreferrer">GitHub</a></div><p class="f-meta xs muted">v${VERSION}</p>`
+    : `<p class="xs">AI Tag Debugger</p><p class="f-meta xs muted">v${VERSION}</p>`;
+  const body = `<header class="top"><span class="brand">${logo("atd-lockup", "AI Tag Debugger", 22, "l-lockup")}<img class="l-mark" src="${LOGOS["atd-icon"]}" alt="AI Tag Debugger" height="24"></span><span class="top-site"><span class="eyebrow">Measurement plan</span>${plan.site ? `<b>${e(plan.site)}</b>` : ""}</span><div class="top-end">${branding ? `<a href="https://analitikisler.com" class="byline" rel="noopener noreferrer"><span>by</span>${logo("horizontal", "Analitik İşler", 16, "logo-h")}</a>` : ""}</div></header>
+<main class="plan">
+<div class="plan-title"><div class="eyebrow">Measurement plan</div><h1>${e(title)}</h1><div class="muted xs">${e(meta)}</div><div class="chips">${consent}</div></div>
+<section class="card"><div class="pl-card-h"><h2>Events</h2><p class="pl-card-d">What should be tracked, where it fires and which parameters it carries.</p></div>${events.length ? events.map(eventCard).join("") : `<p class="pl-empty muted xs">No events.</p>`}</section>
+${userPropertiesCard(plan.user_properties ?? [])}
+</main>
+<footer class="footer">${footer}</footer>`;
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
 <title>${e(title)}</title><link rel="icon" type="image/png" href="${LOGOS.favicon}">
-<style>${CSS}${PLAN_CSS}</style></head><body>
-<div class="topbar"><div class="wrap"><span class="product-logo">${logo("atd-lockup", "AI Tag Debugger", 26, "logo-atd")}</span>${branding ? `<a href="https://analitikisler.com" class="byline" rel="noopener noreferrer"><span>by</span>${logo("horizontal", "Analitik İşler", 18, "logo-h")}</a>` : ""}</div></div>
-<header class="wrap title"><div class="eyebrow">Measurement plan</div><h1>${e(title)}</h1><div class="meta">${e(meta)}</div></header>
-<main class="wrap" style="padding-top:24px;padding-bottom:64px"><div class="stack">
-<div>${consent}</div>
-<section class="card"><div class="card-h"><div class="card-t">Events</div><div class="card-d">What should be tracked, where it fires and which parameters it carries.</div></div><div class="card-c tight">${events.length ? events.map(eventCard).join("") : `<p class="muted xs" style="padding:12px">No events.</p>`}</div></section>
-${userPropertiesCard(plan.user_properties ?? [])}
-</div></main>
-<footer class="footer">${footer}</footer>
+<style>${TOKENS}\n${COMPONENTS}\n${PRODUCT}\n${PLAN_CSS}</style></head><body>
+${sprite(body)}
+${body}
 </body></html>`;
 }

package/src/plan.js

@@ -2,9 +2,14 @@ import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { renderPlanHtml } from "./plan-html.js";
 import { PLAN_FILE, PLAN_HTML_FILE, newPlanDir } from "./workspace.js";
+import { validatePlan } from "./schema.js";
 
-/** Saves a plan (measurement-plan.json and plan.html) in a new aitd/<domain>/plans/<id>/ folder and returns where. */
+/**
+ * Saves a plan (measurement-plan.json and plan.html) in a new aitd/<domain>/plans/<id>/ folder and returns where.
+ * The plan is checked first, so nothing a later run would refuse gets saved.
+ */
 export async function savePlan(plan, { dataDir, site, now, branding = true } = {}) {
+  validatePlan(plan);
   const { id, dir } = await newPlanDir(dataDir, site, now);
   await mkdir(dir, { recursive: true });
   const file = path.join(dir, PLAN_FILE);

package/src/pool.js

@@ -0,0 +1,34 @@
+// Runs independent jobs a few at a time. Each journey and consent scenario opens its own browser,
+// so an audit with several journeys and viewports finishes sooner when they run side by side.
+export const MAX_CONCURRENCY = 8;
+
+/** The number of jobs to run at once, from --concurrency, the config or the MCP tool. Default 1, at most 8. */
+export function parseConcurrency(value) {
+  if (value === undefined || value === null || value === "") return 1;
+  // Only a number or a numeric string counts: true would otherwise pass as 1.
+  const n = typeof value === "number" || typeof value === "string" ? Number(value) : NaN;
+  if (!(Number.isInteger(n) && n >= 1 && n <= MAX_CONCURRENCY)) throw new Error(`"concurrency" must be a whole number from 1 to ${MAX_CONCURRENCY} (--concurrency <n>, or "concurrency" in the config).`);
+  return n;
+}
+
+/**
+ * Runs worker(job, index) for every job, at most `limit` at a time, and returns the results in the jobs'
+ * order, not the order they finished in. A worker that throws rejects the pool, so callers keep each
+ * job's errors inside the worker. With a limit of 1 the jobs run strictly one after another.
+ */
+export async function runPool(jobs, limit, worker) {
+  const results = new Array(jobs.length);
+  let next = 0;
+  // Each lane takes the next job as soon as its own is done, so the lanes stay busy whatever the job lengths.
+  const lane = async () => {
+    while (next < jobs.length) {
+      const i = next++;
+      results[i] = await worker(jobs[i], i);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, jobs.length)) }, lane));
+  return results;
+}
+
+/** A log whose every line starts with a tag, so the lines of jobs running side by side can be told apart. */
+export const taggedLog = (log, tag) => (message) => log(String(message).replace(/^(?=.)/gm, `${tag} `));

package/src/providers.js

@@ -42,9 +42,10 @@ function hasApiKey(env) {
 }
 
 /**
- * @param {{ name?: string, model?: string, baseUrl?: string, client?: any }} opts
+ * @param {{ name?: string, model?: string, baseUrl?: string, client?: any, log?: (msg: string) => void, retry?: { attempts?: number, baseDelayMs?: number, sleep?: (ms: number) => Promise<void> } }} opts
  *   baseUrl: for openai-compatible, e.g. https://api.deepseek.com or http://localhost:11434/v1.
  *   client: an already constructed SDK client (used by tests).
+ *   log: gets one line per retried model request. retry: overrides for withRetry (tests).
  */
 export async function createProvider(opts = {}, env = process.env) {
   // A bare client (tests, embedding) is an Anthropic client unless named otherwise.
@@ -66,39 +67,112 @@ async function buildProvider(name, opts, env) {
     if (!model) throw new Error("openai-compatible needs a model id: --model or OPENAI_COMPATIBLE_MODEL (\"cheap\" has no meaning here, since the API's models are unknown).");
     // Local servers such as Ollama need no key, but the SDK wants a non-empty one.
     const apiKey = env.OPENAI_COMPATIBLE_API_KEY || "not-needed";
-    const client = opts.client ?? new (await import("openai")).default({ baseURL, apiKey });
+    const client = opts.client ?? new (await import("openai")).default(sdkOptions({ baseURL, apiKey }));
     return openaiProvider(client, model, { compatible: true, label: new URL(baseURL).host });
   }
   if (name === "vercel") {
-    const client = opts.client ?? new (await import("openai")).default({ baseURL: VERCEL_GATEWAY, apiKey: env.AI_GATEWAY_API_KEY });
+    const client = opts.client ?? new (await import("openai")).default(sdkOptions({ baseURL: VERCEL_GATEWAY, apiKey: env.AI_GATEWAY_API_KEY }));
     return { ...openaiProvider(client, pickModel("vercel", opts.model), { compatible: true }), name: "vercel" };
   }
   if (name === "cloudflare") {
     const account = env.CLOUDFLARE_ACCOUNT_ID;
     if (!opts.client && !(account && env.CLOUDFLARE_API_TOKEN)) throw new Error("Cloudflare Workers AI needs CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID.");
-    const client = opts.client ?? new (await import("openai")).default({ baseURL: `${CLOUDFLARE_API}/${account}/ai/v1`, apiKey: env.CLOUDFLARE_API_TOKEN });
+    const client = opts.client ?? new (await import("openai")).default(sdkOptions({ baseURL: `${CLOUDFLARE_API}/${account}/ai/v1`, apiKey: env.CLOUDFLARE_API_TOKEN }));
     return { ...openaiProvider(client, pickModel("cloudflare", opts.model), { compatible: true }), name: "cloudflare" };
   }
   const model = pickModel(name, opts.model);
   const gateway = gatewayOptions(name, env);
-  const provider = await builtInProvider(name, model, gateway, opts.client, env);
+  const provider = await builtInProvider(name, model, gateway, opts, env);
   // Shown in the "Using ..." line so a run says whether its calls went through the gateway.
   if (gateway.baseURL && !opts.client) provider.via = "Cloudflare AI Gateway";
   return provider;
 }
 
-async function builtInProvider(name, model, gateway, client, env) {
-  if (name === "anthropic") return anthropicProvider(client ?? new (await import("@anthropic-ai/sdk")).default(gateway), model);
-  if (name === "openai") return openaiProvider(client ?? new (await import("openai")).default(gateway), model);
+async function builtInProvider(name, model, gateway, { client, log, retry }, env) {
+  if (name === "anthropic") return anthropicProvider(client ?? new (await import("@anthropic-ai/sdk")).default(sdkOptions(gateway)), model);
+  if (name === "openai") return openaiProvider(client ?? new (await import("openai")).default(sdkOptions(gateway)), model);
   const { GoogleGenAI } = await import("@google/genai");
   const apiKey = env.GEMINI_API_KEY ?? env.GOOGLE_API_KEY;
+  // The Gemini SDK retries only when asked (httpOptions.retryOptions) and says nothing when it does,
+  // so its calls go through withRetry below instead, which logs each retry.
   const httpOptions = gateway.baseURL ? { httpOptions: { baseUrl: gateway.baseURL, headers: gateway.defaultHeaders } } : {};
-  return geminiProvider(client ?? new GoogleGenAI({ ...(apiKey ? { apiKey } : {}), ...httpOptions }), model);
+  return geminiProvider(client ?? new GoogleGenAI({ ...(apiKey ? { apiKey } : {}), ...httpOptions }), model, { ...retry, log });
 }
 
 const VERCEL_GATEWAY = "https://ai-gateway.vercel.sh/v1";
 const CLOUDFLARE_API = "https://api.cloudflare.com/client/v4/accounts";
 
+// --- Retries -----------------------------------------------------------------
+
+/** How many times a failed model request is tried in all (the first try included). */
+export const MODEL_ATTEMPTS = 3;
+/** The wait before the first retry; each later one waits twice as long, give or take some jitter. */
+export const RETRY_BASE_DELAY_MS = 2000;
+/** The longest wait a retry-after header is allowed to ask for, so a run never hangs on one request. */
+const RETRY_AFTER_MAX_MS = 60_000;
+/** How long one request may take before it counts as failed. The SDKs' own 10 minutes would outlast the step. */
+const MODEL_TIMEOUT_MS = 300_000;
+
+/**
+ * The Anthropic and OpenAI SDKs retry on their own (408, 409, 429, 5xx, connection errors, with backoff
+ * and retry-after), so they only get the attempt count and a timeout; withRetry is not stacked on them.
+ */
+function sdkOptions(extra = {}) {
+  // maxRetries counts retries, not attempts, so this gives the SDKs the same total as withRetry.
+  return { maxRetries: MODEL_ATTEMPTS - 1, timeout: MODEL_TIMEOUT_MS, ...extra };
+}
+
+const TRANSIENT_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504, 529]);
+const TRANSIENT_MESSAGES = /overloaded|ECONNRESET|ETIMEDOUT|ECONNREFUSED|EAI_AGAIN|EPIPE|fetch failed|socket hang up|network error|terminated/i;
+
+/**
+ * True for a failure a second try can get past: a rate limit, an overloaded or restarting API, a dropped
+ * connection. Bad requests, bad keys, missing models, refusals and schema errors fail at once.
+ */
+export function isTransientModelError(err) {
+  const status = err?.status ?? err?.statusCode ?? err?.response?.status;
+  if (Number.isInteger(status)) return TRANSIENT_STATUSES.has(status);
+  return TRANSIENT_MESSAGES.test([err?.code, err?.message, err?.cause?.code, err?.cause?.message].filter(Boolean).join(" "));
+}
+
+/** The wait a retry-after header asks for, in milliseconds (seconds or an HTTP date), or null when there is none. */
+export function retryAfterMs(err, now = Date.now()) {
+  const headers = err?.headers ?? err?.response?.headers;
+  const header = (name) => (typeof headers?.get === "function" ? headers.get(name) : headers?.[name]) ?? null;
+  const ms = Number(header("retry-after-ms"));
+  if (ms > 0) return Math.min(ms, RETRY_AFTER_MAX_MS);
+  const after = header("retry-after");
+  if (after == null || after === "") return null;
+  const seconds = Number(after);
+  const wait = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(after) - now;
+  return wait > 0 ? Math.min(wait, RETRY_AFTER_MAX_MS) : null;
+}
+
+/** What the log line says went wrong: the HTTP status when there is one, else the error code or message. */
+const describeError = (err) => err?.status ?? err?.statusCode ?? err?.response?.status ?? err?.code ?? err?.cause?.code ?? String(err?.message ?? err).split("\n")[0].slice(0, 80);
+
+/**
+ * Runs fn, trying again after a transient failure with exponential backoff (2s, 4s, 8s... with jitter),
+ * or after the wait a retry-after header asks for. Any other failure, or the last one, is thrown as is.
+ * @param {() => Promise<any>} fn
+ * @param {{ attempts?: number, baseDelayMs?: number, isTransient?: (err: any) => boolean, log?: (msg: string) => void, sleep?: (ms: number) => Promise<void>, random?: () => number }} opts
+ *   sleep and random are injectable so tests run without waiting.
+ */
+export async function withRetry(fn, { attempts = MODEL_ATTEMPTS, baseDelayMs = RETRY_BASE_DELAY_MS, isTransient = isTransientModelError, log = () => {}, sleep = wait, random = Math.random } = {}) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt >= attempts || !isTransient(err)) throw err;
+      const delay = retryAfterMs(err) ?? Math.round(baseDelayMs * 2 ** (attempt - 1) * (1 + random() * 0.25));
+      log(`  Model request failed (${describeError(err)}); retrying in ${Math.round(delay / 1000)}s (attempt ${attempt + 1} of ${attempts})`);
+      await sleep(delay);
+    }
+  }
+}
+
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
 /** An openai-compatible API has no known cheap model, so `cheap` falls back to OPENAI_COMPATIBLE_MODEL. */
 function compatibleModel(model, env) {
   return (model === "cheap" ? undefined : model) ?? env.OPENAI_COMPATIBLE_MODEL;
@@ -160,6 +234,7 @@ function anthropicProvider(client, model) {
   return {
     name: "anthropic",
     model,
+    client, // exposed so the retry settings can be checked
     conversation({ system, tools, firstMessage }) {
       const messages = [{ role: "user", content: firstMessage }];
       const toolDefs = tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.schema }));
@@ -217,6 +292,7 @@ function openaiProvider(client, model, { compatible = false, label } = {}) {
   return {
     name: compatible ? `openai-compatible (${label})` : "openai",
     model,
+    client, // exposed so the retry settings can be checked
     conversation({ system, tools, firstMessage }) {
       const messages = [
         { role: "system", content: system },
@@ -275,10 +351,12 @@ function openaiProvider(client, model, { compatible = false, label } = {}) {
 
 // --- Google Gemini -----------------------------------------------------------
 
-function geminiProvider(ai, model) {
+function geminiProvider(ai, model, retry = {}) {
+  const generate = (params) => withRetry(() => ai.models.generateContent(params), retry);
   return {
     name: "gemini",
     model,
+    client: ai,
     conversation({ system, tools, firstMessage }) {
       const contents = [{ role: "user", parts: [{ text: firstMessage }] }];
       const config = {
@@ -288,7 +366,7 @@ function geminiProvider(ai, model) {
       let pendingNames = new Map();
       return {
         async next() {
-          const response = await ai.models.generateContent({ model, contents, config });
+          const response = await generate({ model, contents, config });
           const candidate = response.candidates?.[0];
           if (!candidate?.content) return { toolCalls: [], stop: candidate?.finishReason === "MAX_TOKENS" ? "max_tokens" : "refusal" };
           contents.push(candidate.content);
@@ -322,7 +400,7 @@ function geminiProvider(ai, model) {
       };
     },
     async json({ system, texts, schema }) {
-      const response = await ai.models.generateContent({
+      const response = await generate({
         model,
         contents: [{ role: "user", parts: texts.map((text) => ({ text })) }],
         config: { systemInstruction: system, responseMimeType: "application/json", responseJsonSchema: schema },

package/src/replay.js

@@ -5,12 +5,15 @@ import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { harName } from "./agent.js";
 import { runAudit } from "./audit.js";
+import { listRunIds, runsDir } from "./workspace.js";
 
 export const SAVED_SITE_FILE = "site.json";
+/** The steps every run leaves in its folder, so the next run can repeat them without a model. */
+export const STEPS_FILE = "steps.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 steps = (run.steps ?? []).filter((s) => s.index > 0);
   const start = steps[0]?.replay?.action === "goto" ? steps[0].replay.url : undefined;
   return {
     id: run.journeyId,
@@ -24,6 +27,30 @@ export function replayableJourney(run) {
   };
 }
 
+/** What a run folder's steps.json holds: one entry per journey and viewport, leaving out journeys that took no repeatable step. */
+export function savedSteps({ site, runs }) {
+  return { site, journeys: runs.map(replayableJourney).filter((j) => j.steps.length || j.start) };
+}
+
+/**
+ * The steps of the site's newest completed run of a journey, read from the steps.json each run leaves
+ * behind: { runId, viewport, start, steps } or null. The same viewport is preferred; when no run completed
+ * the journey on it, the newest completed run on another viewport is used, since most sites take the
+ * same path on both. Runs that did not complete the journey are skipped, since their steps led nowhere.
+ */
+export async function lastSteps(dataDir, site, { journeyId, viewport }) {
+  let other = null;
+  for (const runId of (await listRunIds(dataDir, site)).reverse()) {
+    const saved = await readFile(path.join(runsDir(dataDir, site), runId, STEPS_FILE), "utf8").then(JSON.parse).catch(() => null);
+    const done = (saved?.journeys ?? []).filter((j) => j.id === journeyId && !j.incomplete && (j.steps?.length || j.start));
+    const pick = (j) => ({ runId, viewport: j.viewport, start: j.start, steps: j.steps ?? [] });
+    const same = done.find((j) => j.viewport === viewport);
+    if (same) return pick(same);
+    if (done.length && !other) other = pick(done[0]);
+  }
+  return other;
+}
+
 /**
  * Writes the steps each journey took into journeys[].steps of a config file, so a later
  * --scripted --no-ai run repeats them without an AI model. Creates the file when it doesn't exist.

package/src/report-shared.js

@@ -0,0 +1,123 @@
+// What the Markdown and the HTML renderers share: the version, escaping, the grouped findings, platform names and
+// order, the plan-check lines and the verdict sentence. src/report.js and src/html/*.js both import from here and
+// this module imports neither, so the two renderers never import each other.
+import { readFileSync } from "node:fs";
+import { groupFindings } from "./checks.js";
+import { messages } from "./i18n.js";
+import { PROVIDERS } from "./parsers.js";
+
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+const SEVERITIES = ["broken", "risk", "warning", "info"];
+
+/** The summary as { headline, points, also_check }. Older plain-text summaries become a headline-only paragraph. */
+function summaryParts(summary) {
+  if (!summary) return null;
+  if (typeof summary === "string") return { text: summary, points: [], also_check: [] };
+  return {
+    headline: String(summary.headline ?? ""),
+    points: (Array.isArray(summary.points) ? summary.points : []).filter((p) => p && p.text).map((p) => ({ severity: SEVERITIES.includes(p.severity) ? p.severity : "info", text: String(p.text) })),
+    also_check: (Array.isArray(summary.also_check) ? summary.also_check : []).map(String).filter(Boolean),
+  };
+}
+
+/** Fix steps of an explanation; older explanations had one "fix" string. */
+const fixSteps = (e) => (Array.isArray(e?.fix_steps) && e.fix_steps.length ? e.fix_steps.map(String) : e?.fix ? [String(e.fix)] : []);
+
+export const escapeHtml = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+
+function attachExplanations(findings, explained) {
+  const byIndex = new Map((explained?.explanations ?? []).map((e) => [e.finding, e]));
+  // A finding a baseline accepted carries `accepted: true`; the grouped card is accepted when every place it covers is.
+  const key = (f) => [f.severity, f.check, f.platform, f.event, f.detail].join("|");
+  const accepted = new Map();
+  for (const f of findings) if (f.severity !== "ok") accepted.set(key(f), (accepted.get(key(f)) ?? true) && f.accepted === true);
+  return groupFindings(findings).map((f, i) => ({ ...f, explanation: byIndex.get(i), ...(accepted.get(key(f)) ? { accepted: true } : {}) }));
+}
+
+const SEVERITY_RANK = { broken: 0, risk: 1, warning: 2 };
+
+const seconds = (run, t) => `+${((t - run.startedAt) / 1000).toFixed(1)}s`;
+const isConsentEntry = (value) => Array.isArray(value) && value[0] === "consent";
+
+const routeList = (ch) => (ch?.routes ?? []).map((r) => `${r.journeyId} (${r.viewport})`).join(", ");
+
+const isProblem = (f) => f.severity in SEVERITY_RANK;
+const placeKey = (w) => `${w.journey}|${w.viewport}`;
+const uniqPlaces = (where) => [...new Map(where.map((w) => [placeKey(w), w])).values()];
+/** The problem the verdict is about: the one that costs the score most, else the most severe and widespread. */
+function mdLead(rows, metrics) {
+  const top = metrics.score?.deductions?.[0];
+  const problems = rows.filter(isProblem);
+  return (top && problems.find((f) => f.check === top.check && f.severity === top.severity && (f.platform ?? null) === top.platform && (f.event ?? null) === top.event)) ?? problems[0] ?? null;
+}
+
+/** " on mobile" when the lead problem is on one viewport of several, " on checkout" for one journey of several, " on every journey" when it is everywhere. */
+function mdScope(m, runs, lead) {
+  if (!lead) return "";
+  const places = uniqPlaces(lead.where);
+  if (runs.length > 1 && places.length === runs.length) return m.ui.md.everywhere;
+  const viewports = new Set(places.map((w) => w.viewport));
+  const journeys = new Set(places.map((w) => w.journey));
+  if (viewports.size === 1 && new Set(runs.map((r) => r.viewport)).size > 1) return m.ui.md.onViewport(String([...viewports][0]));
+  if (journeys.size === 1 && new Set(runs.map((r) => r.journeyId)).size > 1) return m.ui.md.onJourney(String([...journeys][0]));
+  return "";
+}
+
+/**
+ * The verdict sentence for the title, with no model, keyed the same way as metrics.verdict.headline. It names
+ * the lead problem and where it is ("purchase tracking is broken on mobile"): the counts sit next to the
+ * headline on every surface, so the count-based sentences in `verdict.headline` are left to the HTML verdict block.
+ */
+function mdHeadline(m, runs, rows, metrics) {
+  const v = metrics.verdict;
+  const lead = mdLead(rows, metrics);
+  const what = lead ? (lead.event ? m.ui.md.tracking(String(lead.event)) : m.ui.md.setup(String(lead.check).replace(/_/g, " "))) : "";
+  const scope = mdScope(m, runs, lead);
+  const incomplete = runs.find((r) => !r.completed);
+  const ctx = { key: v.headline, what, scope, journey: incomplete ? String(incomplete.journeyId) : "", events: metrics.coverage?.checkable ?? 0, journeys: runs.length, counts: v.counts, lead };
+  const fallback = m.ui.md.headline[v.headline] ?? m.ui.md.headline.attention_nothing_tested;
+  if (v.headline === "fail_incomplete") return fallback(ctx.journey);
+  if (v.headline === "pass") return fallback(ctx.events, ctx.journeys);
+  if (v.headline === "attention_no_hits" || v.headline === "attention_nothing_tested") return fallback();
+  return fallback(what, scope);
+}
+
+/**
+ * The verdict as the CLI, the alert subject and the Markdown title say it: { status, statusText, headline,
+ * score }, in the report's language and with no Markdown in it. `metrics` is computeMetrics' result.
+ */
+export function verdictHeadline({ findings = [], runs = [], metrics, lang = "en" }) {
+  const m = messages(lang);
+  const rows = groupFindings(findings).sort((a, b) => SEVERITY_ORDER_MD[a.severity] - SEVERITY_ORDER_MD[b.severity] || b.where.length - a.where.length);
+  return { status: metrics.verdict.status, statusText: m.verdict.status[metrics.verdict.status], headline: mdHeadline(m, runs, rows, metrics), score: metrics.score?.score ?? null };
+}
+
+const SEVERITY_ORDER_MD = { broken: 0, risk: 1, warning: 2, info: 3, ok: 4 };
+
+const PLATFORM_ORDER = ["ga4", "google_ads", "meta", "tiktok", "x", "linkedin", "microsoft_ads", "pinterest", "snapchat", "criteo", "klaviyo", "adobe", "matomo", "piwik_pro", "clarity", "hotjar"];
+export const platformLabel = (p) => PROVIDERS[p] ?? String(p).replace(/[_-]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+const platformRank = (p) => (PLATFORM_ORDER.includes(p) ? PLATFORM_ORDER.indexOf(p) : PLATFORM_ORDER.length);
+
+// Platform keys go into class names, ids and attribute selectors.
+const safeKey = (k) => String(k ?? "").toLowerCase().replace(/[^a-z0-9_-]/g, "") || "other";
+const sortPlatforms = (keys) => [...keys].sort((a, b) => platformRank(a) - platformRank(b) || platformLabel(a).localeCompare(platformLabel(b)));
+const changeLabel = (c) => `${platformLabel(c.platform ?? "")} ${c.event ?? ""}`.trim() || c.check;
+const coverageLines = (m, pc) => [
+  m.ui.coverageLine(pc.coverage),
+  ...sortPlatforms(Object.keys(pc.coverage.platforms)).map((p) => `${platformLabel(p)}: ${m.ui.coverageLine(pc.coverage.platforms[p])}`),
+];
+const pcSort = (pc) => [...pc.events].sort((a, b) => BUCKET_ORDER.indexOf(a.bucket) - BUCKET_ORDER.indexOf(b.bucket) || platformRank(a.platform) - platformRank(b.platform));
+const BUCKET_ORDER = ["missing", "missing_params", "wrong_values", "implemented", "unplanned", "not_checked"];
+
+const planChangeItems = (pc) => [
+  ...pc.added.map((c) => `+ ${changeLabel(c)}`),
+  ...pc.removed.map((c) => `− ${changeLabel(c)}`),
+  ...pc.changed.map((c) => `~ ${changeLabel(c)}: ${c.what.join(", ")}`),
+];
+
+export {
+  SEVERITIES, summaryParts, fixSteps, attachExplanations, SEVERITY_RANK, SEVERITY_ORDER_MD, seconds, isConsentEntry, routeList,
+  isProblem, placeKey, uniqPlaces, mdHeadline, PLATFORM_ORDER, platformRank, safeKey, sortPlatforms, changeLabel,
+  coverageLines, pcSort, BUCKET_ORDER, planChangeItems,
+};