@decocms/parity 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.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,6 +1926,18 @@ function parseIntOrNull(v) {
   const n = Number.parseInt(v, 10);
   return Number.isFinite(n) ? n : null;
 }
+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) {
   await page.evaluate(async () => {
     await new Promise((resolve) => {
@@ -1915,13 +1948,13 @@ async function scrollFullPage(page) {
         window.scrollTo(0, y);
         y += step;
         if (y < max) {
-          setTimeout(tick, 220);
+          setTimeout(tick, 400);
         } else {
           window.scrollTo(0, max);
           setTimeout(() => {
             window.scrollTo(0, 0);
-            resolve();
-          }, 400);
+            setTimeout(resolve, 700);
+          }, 1500);
         }
       };
       tick();
@@ -2003,7 +2036,13 @@ async function capturePage(page, opts) {
             new Promise((resolve) => setTimeout(resolve, Math.min(1e4, remaining())))
           ]);
           dlog(opts.side, opts.viewport, `    capturePage: scrollFullPage done (remaining=${remaining()}ms)`);
-          await page.waitForTimeout(Math.min(600, remaining()));
+          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 +2063,16 @@ async function capturePage(page, opts) {
         }),
         new Promise((resolve) => setTimeout(resolve, Math.min(3000, remaining())))
       ]);
+      const skeletonBudget = Math.min(1e4, 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))
+        ]);
+      }
       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 +5805,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 +6388,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 +6478,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 +6533,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 +6694,32 @@ 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;
+function downgradeSkeletonImbalanceDiffs(diffs, prodSkeletonCount, candSkeletonCount) {
+  if (Math.abs(prodSkeletonCount - candSkeletonCount) < SKELETON_IMBALANCE_THRESHOLD) {
+    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 +6779,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 +6807,8 @@ async function visualRegressionKeyframes(ctx) {
       sectionsOnlyInProd,
       sectionsOnlyInCand,
       bothHaveCarousel,
+      prodSkeletonCount,
+      candSkeletonCount,
       hash: hash2,
       cacheHit,
       preflightIssues
@@ -6750,7 +6851,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 +6862,7 @@ async function visualRegressionKeyframes(ctx) {
     }
     if (differences.length > 0) {
       differences = downgradeCarouselFramingDiffs(differences, p.bothHaveCarousel);
+      differences = downgradeSkeletonImbalanceDiffs(differences, p.prodSkeletonCount, p.candSkeletonCount);
     }
     const verdict = decideVerdict({
       llmError,
@@ -17032,18 +17136,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 +17164,8 @@ async function runCommand(rawOpts) {
                   side: task.side,
                   viewport: task.viewport,
                   screenshotPath: screenshotPath2,
-                  settleMs: 1800,
-                  timeoutMs: 30000,
+                  settleMs: 4000,
+                  timeoutMs: 45000,
                   scrollToLoad: true
                 });
                 allPageCaptures.push(cap);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@decocms/parity",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"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",