@decocms/parity 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.10.1](https://github.com/decocms/parity/compare/v0.10.0...v0.10.1) (2026-05-30)
+
+### Fixed
+
+* **Adaptive `scrollFullPage` — actually reaches the bottom on long pages.** Previous fixed-step loop with a 10s outer race only covered ~15000px before bailing, so 25000-40000px e-commerce homepages were captured with half the content still as skeletons. New loop re-measures `scrollHeight` every tick, waits inline for in-view skeleton placeholders to clear (up to 1.5s per step), and exits once page height has been stable for 3 consecutive checks. On miess home: 15 steps, 8862px reached, **0 skeletons at screenshot time** (was 7+ before). Race timeout bumped 10s → 45s, `capturePage` visual-diff `timeoutMs` 45s → 90s to fit the new scroll budget.
+
+* **Silent `ReferenceError: __name is not defined` inside `page.evaluate`.** Took two debug rounds to isolate — `tsx`/esbuild injects a `__name` helper to preserve `.name` on arrow-function declarations (`const foo = () => ...`), but that helper doesn't exist in the page's browser context. The function threw immediately and `.catch(() => undefined)` swallowed it, making it look like a legitimate timeout. Fix: inlined the helper Promises inside `scrollFullPage`'s `page.evaluate`, and replaced silent `.catch` with one that logs the actual error message.
+
+* **`SKELETON_DOWNGRADE_PCT_DIFF_CEILING = 0.25`.** The skeleton-vs-loaded downgrade was masking structural failures: any diff where the LLM mentioned "skeleton"/"placeholder" was forced to `low`, even when prod had a half-empty page (34%+ pctDiff). Now the downgrade only fires when pctDiff is under 25% — above that, the imbalance is treated as a real regression, not timing noise.
+
+### Changed
+
+* `waitForSkeletonsToResolve` budget reduced 10s → 5s. The new adaptive scroll does inter-step skeleton waits, so the global safety net is a last-resort for off-screen skeletons rather than the primary defense.
+
+* New `pre-screenshot skeletons=N` diagnostic log (via `DEBUG_PARITY=1`) so anyone investigating "is the page actually ready when we capture it?" can answer in one run.
+
+## [0.10.0](https://github.com/decocms/parity/compare/v0.9.0...v0.10.0) (2026-05-29)
+
+### Added
+
+* **skeleton-aware capture pipeline:** `capturePage` now waits up to 6s for skeleton/loader placeholders (`.skeleton`, `[aria-busy]`, `.animate-pulse`, `.shimmer*`, `react-loading-skeleton`, generic `[class*='skeleton' i]`) to resolve before the screenshot fires. Stops the visual-diff LLM from reporting phantom "missing-component" diffs because one side raced ahead. `DomSnapshot.skeletonCount` exposes residual skeletons to downstream consumers.
+* **skeleton-vs-loaded downgrade post-process:** when prod and cand differ in skeleton count by ≥5, LLM-reported `missing-component`/`different-component`/`extra-component` diffs whose description mentions skeleton/placeholder/shimmer wording are downgraded to `low` with an explanatory `[downgraded: skeleton-vs-loaded — ...]` suffix. Mirrors the carousel safety net from issue #22.
+
+### Fixed
+
+* **scrollFullPage timing on heavy storefronts:** scroll step delay raised from 220ms → 400ms (gives shelf APIs time to dispatch before viewport moves past), bottom dwell from 400ms → 1500ms (footer + bottom carousels get to finish), plus a new 700ms settle after returning to the top (covers lazy frameworks that re-skeletonize on IntersectionObserver "leave"). This was the root cause of prod screenshots capturing 30-60% skeleton placeholders on Miess `/`, `/super-live`, `/intt-day`.
+* **post-scroll networkidle wait:** added a 3s `networkidle` race after `scrollFullPage` in `capturePage`, plus 800ms (was 600ms) settle. Catches the lazy-fetch wave kicked off during the scroll-through before the screenshot fires.
+* **visual-diff `settleMs` for the dedicated capture pass:** bumped from 1.8s → 4s and outer `timeoutMs` from 30s → 45s. These screenshots are the source of truth for the LLM verdict — flaky captures translate directly to flaky verdicts.
+
+### Changed
+
+* **`LLM_PROMPT_VERSION` → `v3-skeleton`:** prompt now includes an explicit "skeleton/loading is timing, not regression" rule plus the prod/cand skeleton-count imbalance context. Bump invalidates all v2-keyed cache entries so prior verdicts get re-judged under the new heuristic.
+
 ## [0.9.0](https://github.com/decocms/parity/compare/v0.8.1...v0.9.0) (2026-05-29)
 
 ### Added

package/dist/cli.js

@@ -884,7 +884,28 @@ function snapshotDom(html) {
     if (v)
       decoSectionsRendered.push(v);
   });
-  return { counts, meta, imageStats, decoSectionsRendered: [...new Set(decoSectionsRendered)] };
+  let skeletonCount = 0;
+  for (const sel of [
+    "[aria-busy='true']",
+    "[data-skeleton]",
+    "[data-loading='true']",
+    ".skeleton",
+    "[class*='skeleton' i]",
+    "[class*='Skeleton']",
+    "[class*='shimmer' i]",
+    ".animate-pulse",
+    ".placeholder-shimmer",
+    ".react-loading-skeleton"
+  ]) {
+    skeletonCount += $(sel).length;
+  }
+  return {
+    counts,
+    meta,
+    imageStats,
+    decoSectionsRendered: [...new Set(decoSectionsRendered)],
+    skeletonCount
+  };
 }
 function diffDom(prod, cand, opts = {}) {
   const tol = opts.countTolerance ?? 2;
@@ -1905,28 +1926,65 @@ function parseIntOrNull(v) {
   const n = Number.parseInt(v, 10);
   return Number.isFinite(n) ? n : null;
 }
-async function scrollFullPage(page) {
-  await page.evaluate(async () => {
-    await new Promise((resolve) => {
-      const step = Math.max(window.innerHeight * 0.8, 600);
-      let y = 0;
-      const max = document.documentElement.scrollHeight;
-      const tick = () => {
-        window.scrollTo(0, y);
-        y += step;
-        if (y < max) {
-          setTimeout(tick, 220);
+var SKELETON_SELECTOR = "[aria-busy='true'],[data-skeleton],[data-loading='true'],.skeleton,[class*='skeleton' i],[class*='Skeleton'],[class*='shimmer' i],.animate-pulse,.placeholder-shimmer,.react-loading-skeleton";
+async function waitForSkeletonsToResolve(page, maxMs = 1e4) {
+  const start = Date.now();
+  while (Date.now() - start < maxMs) {
+    const count = await page.evaluate((sel) => document.querySelectorAll(sel).length, SKELETON_SELECTOR).catch(() => 0);
+    if (count === 0)
+      return;
+    await page.waitForTimeout(500).catch(() => {
+      return;
+    });
+  }
+}
+async function scrollFullPage(page, budgetMs = 45000) {
+  const start = Date.now();
+  const result = await page.evaluate(async (budget) => {
+    const SK = "[aria-busy='true'],[data-skeleton],[data-loading='true'],.skeleton,[class*='skeleton' i],[class*='Skeleton'],[class*='shimmer' i],.animate-pulse,.placeholder-shimmer,.react-loading-skeleton";
+    const innerStart = Date.now();
+    let y = 0;
+    let prevHeight = 0;
+    let stableTicks = 0;
+    let steps = 0;
+    const STABLE_THRESHOLD = 3;
+    while (budget - (Date.now() - innerStart) > 2000) {
+      window.scrollTo(0, y);
+      steps++;
+      await new Promise((r) => setTimeout(r, 400));
+      const stepWaitStart = Date.now();
+      while (document.querySelectorAll(SK).length > 0 && Date.now() - stepWaitStart < 1500 && budget - (Date.now() - innerStart) > 1000) {
+        await new Promise((r) => setTimeout(r, 200));
+      }
+      const height = document.documentElement.scrollHeight;
+      const viewport = window.innerHeight;
+      if (y + viewport >= height - 50) {
+        if (height === prevHeight) {
+          stableTicks++;
+          if (stableTicks >= STABLE_THRESHOLD)
+            break;
         } else {
-          window.scrollTo(0, max);
-          setTimeout(() => {
-            window.scrollTo(0, 0);
-            resolve();
-          }, 400);
+          stableTicks = 0;
+          prevHeight = height;
         }
-      };
-      tick();
-    });
-  });
+        await new Promise((r) => setTimeout(r, 500));
+      } else {
+        y = Math.min(y + Math.max(viewport * 0.8, 600), height);
+      }
+    }
+    const finalHeight = document.documentElement.scrollHeight;
+    window.scrollTo(0, finalHeight);
+    await new Promise((r) => setTimeout(r, 1500));
+    window.scrollTo(0, 0);
+    await new Promise((r) => setTimeout(r, 700));
+    return { steps, finalHeight, stableAtEnd: stableTicks >= STABLE_THRESHOLD };
+  }, budgetMs);
+  return {
+    steps: result.steps,
+    finalHeight: result.finalHeight,
+    stableAtEnd: result.stableAtEnd,
+    durationMs: Date.now() - start
+  };
 }
 function isFromHttpCache(resp) {
   const h = resp.headers();
@@ -1995,15 +2053,27 @@ async function capturePage(page, opts) {
         dlog(opts.side, opts.viewport, `    capturePage: settle (cap=${Math.min(opts.settleMs ?? 2000, remaining())}ms)`);
         await page.waitForTimeout(Math.min(opts.settleMs ?? 2000, remaining()));
         if (opts.scrollToLoad !== false && remaining() > 3000) {
-          dlog(opts.side, opts.viewport, `    capturePage: scrollFullPage start (remaining=${remaining()}ms)`);
-          await Promise.race([
-            scrollFullPage(page).catch(() => {
+          const scrollBudget = Math.min(45000, remaining());
+          dlog(opts.side, opts.viewport, `    capturePage: scrollFullPage start (budget=${scrollBudget}ms, remaining=${remaining()}ms)`);
+          const scrollResult = await Promise.race([
+            scrollFullPage(page, scrollBudget).catch((err) => {
+              dlog(opts.side, opts.viewport, `    capturePage: scrollFullPage threw: ${err.message}`);
               return;
             }),
-            new Promise((resolve) => setTimeout(resolve, Math.min(1e4, remaining())))
+            new Promise((resolve) => setTimeout(() => resolve(undefined), scrollBudget + 2000))
           ]);
-          dlog(opts.side, opts.viewport, `    capturePage: scrollFullPage done (remaining=${remaining()}ms)`);
-          await page.waitForTimeout(Math.min(600, remaining()));
+          if (scrollResult) {
+            dlog(opts.side, opts.viewport, `    capturePage: scrollFullPage done steps=${scrollResult.steps} finalHeight=${scrollResult.finalHeight} stable=${scrollResult.stableAtEnd} duration=${scrollResult.durationMs}ms (remaining=${remaining()}ms)`);
+          } else {
+            dlog(opts.side, opts.viewport, `    capturePage: scrollFullPage timed out at outer race (remaining=${remaining()}ms)`);
+          }
+          if (remaining() > 2000) {
+            dlog(opts.side, opts.viewport, `    capturePage: post-scroll networkidle (cap=${Math.min(3000, remaining())}ms)`);
+            await page.waitForLoadState("networkidle", { timeout: Math.min(3000, remaining()) }).catch(() => {
+              return;
+            });
+          }
+          await page.waitForTimeout(Math.min(800, remaining()));
         }
       }
     } catch (err) {
@@ -2024,6 +2094,20 @@ async function capturePage(page, opts) {
         }),
         new Promise((resolve) => setTimeout(resolve, Math.min(3000, remaining())))
       ]);
+      const skeletonBudget = Math.min(5000, remaining());
+      if (skeletonBudget > 500) {
+        dlog(opts.side, opts.viewport, `    capturePage: waitForSkeletons (cap=${skeletonBudget}ms)`);
+        await Promise.race([
+          waitForSkeletonsToResolve(page, skeletonBudget).catch(() => {
+            return;
+          }),
+          new Promise((resolve) => setTimeout(resolve, skeletonBudget))
+        ]);
+      }
+      try {
+        const skeletonsAtCapture = await page.evaluate((sel) => document.querySelectorAll(sel).length, SKELETON_SELECTOR).catch(() => -1);
+        dlog(opts.side, opts.viewport, `    capturePage: pre-screenshot skeletons=${skeletonsAtCapture}`);
+      } catch {}
       dlog(opts.side, opts.viewport, `    capturePage: screenshot start (cap=${Math.min(15000, remaining())}ms)`);
       await Promise.race([
         page.screenshot({ path: opts.screenshotPath, fullPage: true, animations: "disabled" }).catch(() => {
@@ -5756,13 +5840,15 @@ import ora3 from "ora";
 
 // src/checks/lib/pairing.ts
 function pairCaptures(prod, cand) {
+  const prodByKey = new Map;
+  for (const p of prod)
+    prodByKey.set(captureKey(p), p);
   const candByKey = new Map;
   for (const c of cand)
     candByKey.set(captureKey(c), c);
   const pairs = [];
   const orphansProd = [];
-  for (const p of prod) {
-    const key = captureKey(p);
+  for (const [key, p] of prodByKey) {
     const c = candByKey.get(key);
     if (c) {
       pairs.push({ prod: p, cand: c, viewport: p.viewport, key });
@@ -6337,7 +6423,7 @@ async function callOpenRouterMessage(params) {
 import { readFileSync as readFileSync5 } from "node:fs";
 import { PNG as PNG2 } from "pngjs";
 var MAX_HEIGHT = 8000;
-var LLM_PROMPT_VERSION = "v2-heatmap";
+var LLM_PROMPT_VERSION = "v3-skeleton";
 var REPORT_VISUAL_DIFFS_TOOL = {
   name: "report_visual_differences",
   description: "Report semantic visual differences between prod and cand screenshots.",
@@ -6427,6 +6513,19 @@ IGNORE COMO RUÍDO (não reporte):
 - Stock counters / preços com pequena variação dinâmica
 - Pixel-level rendering quirks
 
+REGRA DE SKELETON / LOADING (timing — não regressão):
+- Skeletons / shimmers / placeholders cinzas com padrão de "card vazio" indicam
+  que o lado em questão ainda estava buscando dados quando a screenshot foi
+  tirada. Se UM lado mostra skeletons e o OUTRO lado mostra o componente real
+  carregado pra o MESMO slot (mesma região, mesmo tipo de componente), isso é
+  timing-noise, NÃO regressão.
+- Nesses casos a severidade deve ser \`low\` no máximo. Nunca \`critical\` ou
+  \`high\`. Indique no \`description\` algo como "skeleton-vs-loaded — pode ser
+  timing" pra o leitor humano não perder tempo.
+- Exceção: se um lado mostra a região INTEIRA em skeleton infinito (sem
+  componente nem placeholder) enquanto o outro tem o conteúdo completo, isso
+  pode ser um bug real de fetch — aí severity \`medium\`.
+
 REGRA DE MODAL/POPUP (importante — não confundir com rota-errada):
 - Modal/popup visível em SÓ um lado é ruído APENAS se o conteúdo de fundo dos
   dois lados é o mesmo (ex: cookie banner em prod, sem cookie banner em cand,
@@ -6469,6 +6568,13 @@ function buildContextBlock(input) {
   if (input.bothHaveCarousel) {
     lines.push("", "**Ambos os lados expõem um carousel/slider no DOM.** Diferenças no conteúdo do hero (banner diferente, texto diferente, imagem diferente) provavelmente são apenas slides diferentes do mesmo carousel capturados em momentos distintos. NÃO reporte essas diferenças como critical/high. Se o carousel inteiro sumir, ou o layout do hero quebrar, isso sim reporte normalmente.");
   }
+  const prodSkel = input.prodSkeletonCount ?? 0;
+  const candSkel = input.candSkeletonCount ?? 0;
+  if (Math.abs(prodSkel - candSkel) >= 5) {
+    const heavier = prodSkel > candSkel ? "prod" : "cand";
+    const lighter = prodSkel > candSkel ? "cand" : "prod";
+    lines.push("", `**Desbalanço de skeleton/loaders detectado no DOM**: ${heavier} ainda tem ${Math.max(prodSkel, candSkel)} elementos skeleton enquanto ${lighter} tem ${Math.min(prodSkel, candSkel)}. Isso indica que ${heavier} não terminou o data fetch quando a screenshot foi tirada. Diferenças onde ${heavier} mostra placeholder cinza e ${lighter} mostra o componente carregado são TIMING NOISE — reporte com severity \`low\` no máximo e mencione "skeleton-vs-loaded" no description.`);
+  }
   if (input.prodSections && input.prodSections.length > 0) {
     lines.push("", `Total sections em prod: ${input.prodSections.length}; em cand: ${input.candSections?.length ?? 0}.`);
   }
@@ -6623,6 +6729,36 @@ function downgradeCarouselFramingDiffs(diffs, bothHaveCarousel) {
     };
   });
 }
+var SKELETON_DESCRIPTION_RE = /skeleton|placeholder|shimmer|loading|carregando|esqueleto|esquemático|cinza|gray box|gray card|empty card|empty placeholder|loader/i;
+var SKELETON_DOWNGRADE_PCT_DIFF_CEILING = 0.25;
+function downgradeSkeletonImbalanceDiffs(diffs, prodSkeletonCount, candSkeletonCount, pctDiff) {
+  if (Math.abs(prodSkeletonCount - candSkeletonCount) < SKELETON_IMBALANCE_THRESHOLD) {
+    return diffs;
+  }
+  if (pctDiff > SKELETON_DOWNGRADE_PCT_DIFF_CEILING) {
+    return diffs;
+  }
+  const heavier = prodSkeletonCount > candSkeletonCount ? "prod" : "cand";
+  return diffs.map((d) => {
+    if (d.severity === "low")
+      return d;
+    const eligible = [
+      "missing-component",
+      "different-component",
+      "extra-component"
+    ];
+    if (!eligible.includes(d.type))
+      return d;
+    if (!SKELETON_DESCRIPTION_RE.test(d.description))
+      return d;
+    return {
+      ...d,
+      severity: "low",
+      description: `${d.description} [downgraded: skeleton-vs-loaded — ${heavier} ainda tinha placeholders carregando quando a screenshot foi tirada; provável timing noise]`
+    };
+  });
+}
+var SKELETON_IMBALANCE_THRESHOLD = 5;
 function decideVerdict(args) {
   const hasCritical = args.differences.some((d) => d.severity === "critical" || d.severity === "high");
   const hasAnyDiff = args.differences.length > 0 || args.sectionsOnlyInProd.length > 0;
@@ -6682,6 +6818,8 @@ async function visualRegressionKeyframes(ctx) {
     const prodSet = new Set(prodSections);
     const sectionsOnlyInProd = prodSections.filter((s) => !candSet.has(s));
     const sectionsOnlyInCand = candSections.filter((s) => !prodSet.has(s));
+    const prodSkeletonCount = prodSnapshot?.skeletonCount ?? 0;
+    const candSkeletonCount = candSnapshot?.skeletonCount ?? 0;
     const bothHaveCarousel = hasCarouselSection(prodSections) && hasCarouselSection(candSections);
     let hash2;
     let cacheHit;
@@ -6708,6 +6846,8 @@ async function visualRegressionKeyframes(ctx) {
       sectionsOnlyInProd,
       sectionsOnlyInCand,
       bothHaveCarousel,
+      prodSkeletonCount,
+      candSkeletonCount,
       hash: hash2,
       cacheHit,
       preflightIssues
@@ -6750,7 +6890,9 @@ async function visualRegressionKeyframes(ctx) {
           prodSections: p.prodSections,
           candSections: p.candSections,
           sectionsOnlyInProd: p.sectionsOnlyInProd,
-          bothHaveCarousel: p.bothHaveCarousel
+          bothHaveCarousel: p.bothHaveCarousel,
+          prodSkeletonCount: p.prodSkeletonCount,
+          candSkeletonCount: p.candSkeletonCount
         });
         differences = diffs ?? [];
       } catch (err) {
@@ -6759,6 +6901,7 @@ async function visualRegressionKeyframes(ctx) {
     }
     if (differences.length > 0) {
       differences = downgradeCarouselFramingDiffs(differences, p.bothHaveCarousel);
+      differences = downgradeSkeletonImbalanceDiffs(differences, p.prodSkeletonCount, p.candSkeletonCount, p.pctDiff);
     }
     const verdict = decideVerdict({
       llmError,
@@ -17032,18 +17175,10 @@ async function runCommand(rawOpts) {
       const visualSpinner = ora6(explicitPaths ? `Visual diff: ${explicitPaths.length} página(s) explícita(s) via --pages/--pages-file…` : "Descobrindo páginas pra visual diff…").start();
       try {
         const visualPaths = explicitPaths ?? (await discoverPagesFromSitemap(opts.prod, { sampleSize: visualPagesLimit })).all.map((p) => p.path);
-        const alreadyCapturedKeys = new Set;
-        for (const p of allPageCaptures) {
-          try {
-            alreadyCapturedKeys.add(`${new URL(p.url).pathname}::${p.viewport}::${p.side}`);
-          } catch {}
-        }
         const tasks = [];
         for (const viewport of viewports) {
           for (const path of visualPaths) {
             for (const side of ["prod", "cand"]) {
-              if (alreadyCapturedKeys.has(`${path}::${viewport}::${side}`))
-                continue;
               tasks.push({ path, viewport, side });
             }
           }
@@ -17068,8 +17203,8 @@ async function runCommand(rawOpts) {
                   side: task.side,
                   viewport: task.viewport,
                   screenshotPath: screenshotPath2,
-                  settleMs: 1800,
-                  timeoutMs: 30000,
+                  settleMs: 4000,
+                  timeoutMs: 90000,
                   scrollToLoad: true
                 });
                 allPageCaptures.push(cap);
@@ -17261,8 +17396,9 @@ async function preflightCheck(prodUrl, candUrl, viewport) {
       errors.push(`${label}: URL inválida (${url})`);
       return;
     }
+    const PREFLIGHT_TIMEOUT_MS = 30000;
     const controller = new AbortController;
-    const t = setTimeout(() => controller.abort(), 1e4);
+    const t = setTimeout(() => controller.abort(), PREFLIGHT_TIMEOUT_MS);
     try {
       const res = await fetch(url, {
         method: "GET",
@@ -17278,7 +17414,7 @@ async function preflightCheck(prodUrl, candUrl, viewport) {
         errors.push(`${label}: HTTP ${res.status} ${res.statusText} (${url})`);
     } catch (err) {
       const e = err;
-      const msg = e.name === "AbortError" ? "timeout (10s)" : e.message;
+      const msg = e.name === "AbortError" ? `timeout (${PREFLIGHT_TIMEOUT_MS / 1000}s)` : e.message;
       errors.push(`${label}: ${msg} (${url})`);
     } finally {
       clearTimeout(t);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@decocms/parity",
-	"version": "0.9.0",
+	"version": "0.10.1",
 	"description": "E2E parity validator for site migrations. Compares prod vs cand and reports UI, functional, SEO, visual, and Web Vitals deltas with an LLM-ranked HTML report.",
 	"type": "module",
 	"license": "MIT",