@tractiontactics/tt-fidelity 0.2.2 → 0.2.3

package/AGENTS.md

@@ -10,6 +10,7 @@ You are measuring a prototype against a TT WP Theme draft. **You are not the gra
 4. **One WORK PLAN task**, then re-run with `--round` incremented. Do not batch speculative fixes.
 5. **Never apply a rule site-wide** until `instances_per_page` (in clusters / QUEUE) shows it is a real default. Blanket CSS from a rare seam creates hundreds of false findings.
 6. **Cache:** the tool cache-busts by default. If draft and live disagree, purge host/CDN and re-run — do not “fix” ghosts.
+6b. **Capture prep (0.2.3+):** the tool scrolls the full page, forces lazy images, and unlocks common scroll-reveal (`opacity:0`) before section shots. If prototype PNGs look blank cream with only sticky widgets, you are on an old package — upgrade. Separately, **404 images** on the prototype (or `onerror` hiding media) are real source defects, not capture bugs.
 7. **Escalate** tokens → block Style/Advanced → minimal `PUT /custom-css` → theme change → HTML template. Cite `ttRowId` / `ttBlockIds` when present.
 8. **Default `--scope content`** (page body). Use `--scope chrome` for header/footer. Use `--scope full` only when you intentionally want both (TT draft may then count header/footer rows the prototype does not).
 9. **QUEUE lifetime:** `ttRowId` values persist across *renders* of the same layout JSON, but a **republish / rebuild that regenerates row ids** invalidates the QUEUE. Re-measure after any full layout rewrite.

package/README.md

@@ -129,12 +129,15 @@ Schema: [`fidelity.schema.json`](./fidelity.schema.json) (`schema_version: 2`).
 ## How measurement works
 
 1. Load both URLs at the same viewport (cache-busted by default).
-2. Discover **sections**: draft prefers `.tt-pb-row` / `data-tt-row`; prototype prefers `main > section`.
-3. Align by document order; count mismatch → structural task.
-4. Screenshot each pair, normalize canvas, `pixelmatch` → score + band.
-5. Optionally capture landmark computed styles (explainer).
-6. Cluster failing headings across `--pages` → `QUEUE.md` leverage list.
-7. Emit TT ids (`data-tt-row` / `data-tt-block`) when present for `PUT /pages/{id}/layout`.
+2. **Prepare for capture (0.2.3+):** full-page scroll (scroll-reveal / IntersectionObserver), eager lazy images, unlock common `opacity:0` reveal classes, hide sticky tip/chat overlays.
+3. Discover **sections**: draft prefers `.tt-pb-row` / `data-tt-row`; prototype prefers `main > section` (or `body > section`).
+4. Align by document order; count mismatch → structural task.
+5. Screenshot each pair (scroll section into view again), normalize canvas, `pixelmatch` → score + band.
+6. Optionally capture landmark computed styles (explainer).
+7. Cluster failing headings across `--pages` → `QUEUE.md` leverage list.
+8. Emit TT ids (`data-tt-row` / `data-tt-block`) when present for `PUT /pages/{id}/layout`.
+
+If prototype shots look like blank cream with only a sticky widget, you are on a pre-0.2.3 build — upgrade. Broken/404 media on the prototype itself will still appear empty.
 
 ## Agent contract
 

package/fixtures/self-test.mjs

@@ -26,7 +26,7 @@ function assert(cond, msg) {
 }
 
 async function main() {
-	assert(PACKAGE_VERSION === '0.2.2', 'package version constant is 0.2.2');
+	assert(PACKAGE_VERSION === '0.2.3', 'package version constant is 0.2.3');
 
 	// Align: unpaired + structural when counts differ
 	{

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tractiontactics/tt-fidelity",
-	"version": "0.2.2",
+	"version": "0.2.3",
 	"description": "Section-first visual fidelity: hybrid SSIM+pixel gate + computed-style explainer for TT Platform prototype→site builds.",
 	"type": "module",
 	"bin": {

package/src/capture.mjs

@@ -72,9 +72,9 @@ export async function openPage(browser, {
 			}
 		} catch (e) { /* ignore */ }
 	});
-	await page.goto(target, { waitUntil: 'networkidle', timeout: 45000 });
+	await page.goto(target, { waitUntil: 'networkidle', timeout: 60000 });
 	await page.evaluate(() => document.fonts && document.fonts.ready).catch(() => {});
-	await page.waitForTimeout(250);
+	await preparePageForCapture(page);
 
 	if (menus) {
 		for (const s of ['nav li:has(ul)', '.menu-item-has-children', 'nav [aria-haspopup]']) {
@@ -92,23 +92,133 @@ export async function openPage(browser, {
 	return { page, context: ctx, cacheHeaders, finalUrl: page.url() };
 }
 
+/**
+ * Prototypes often use scroll-reveal (opacity:0 until .in) and loading=lazy images.
+ * Without a full scroll + image wait, section screenshots are blank cream and the
+ * pixel gate is meaningless.
+ */
+export async function preparePageForCapture(page) {
+	await page.evaluate(async () => {
+		const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+		// Force-eager lazy images / common data-src patterns.
+		for (const img of document.querySelectorAll('img')) {
+			try {
+				img.loading = 'eager';
+				const ds = img.getAttribute('data-src') || img.getAttribute('data-lazy-src');
+				if (ds && !img.getAttribute('src')) img.setAttribute('src', ds);
+				const dss = img.getAttribute('data-srcset') || img.getAttribute('data-lazy-srcset');
+				if (dss && !img.getAttribute('srcset')) img.setAttribute('srcset', dss);
+			} catch (e) { /* ignore */ }
+		}
+
+		// Scroll the full document so IntersectionObservers / reveal classes fire.
+		const step = Math.max(240, Math.floor(window.innerHeight * 0.7));
+		const maxY = Math.max(document.body.scrollHeight, document.documentElement.scrollHeight);
+		for (let y = 0; y < maxY; y += step) {
+			window.scrollTo(0, y);
+			await sleep(80);
+		}
+		window.scrollTo(0, maxY);
+		await sleep(150);
+		window.scrollTo(0, 0);
+		await sleep(200);
+
+		// If reveal never fired (no IO), force common "in view" classes / opacity.
+		for (const el of document.querySelectorAll('section, .sec, .sec-alt, .trust, .lead, .phero, [class*=reveal i], [class*=fade i]')) {
+			try {
+				const cs = getComputedStyle(el);
+				if (parseFloat(cs.opacity) < 0.5) {
+					el.classList.add('in', 'is-inview', 'is-visible', 'visible', 'aos-animate');
+					el.style.opacity = '1';
+					el.style.transform = 'none';
+					el.style.visibility = 'visible';
+				}
+			} catch (e) { /* ignore */ }
+		}
+
+		// Hide sticky tips/chat that paint over section shots (not page content).
+		for (const el of document.querySelectorAll(
+			'[class*=did-you i], [class*=cookie i], [id*=cookie i], .bc-widget, [class*=chat-widget i], [class*=intercom i]'
+		)) {
+			try {
+				const cs = getComputedStyle(el);
+				if (cs.position === 'fixed' || cs.position === 'sticky') {
+					el.style.setProperty('display', 'none', 'important');
+				}
+			} catch (e) { /* ignore */ }
+		}
+	});
+
+	// Wait for images that already have a layout box.
+	await page.evaluate(async () => {
+		const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+		const deadline = Date.now() + 8000;
+		while (Date.now() < deadline) {
+			const pending = [...document.images].filter((img) => {
+				if (!img.src || img.src.startsWith('data:')) return false;
+				const r = img.getBoundingClientRect();
+				if (r.width < 2 || r.height < 2) return false;
+				return !(img.complete && img.naturalWidth > 0);
+			});
+			if (!pending.length) break;
+			await sleep(150);
+		}
+		if (document.fonts?.ready) await document.fonts.ready;
+	}).catch(() => {});
+
+	await page.waitForTimeout(200);
+}
+
 /**
  * Screenshot a section by clipping from the page (element bounding box).
  */
 export async function screenshotSection(page, section) {
 	const handle = await page.$(section.selector);
-	if (!handle) {
-		// fallback clip from stored box
-		const { x, viewportTop, width, height } = section.box;
-		return page.screenshot({
-			type: 'png',
-			clip: {
-				x: Math.max(0, x),
-				y: Math.max(0, viewportTop),
-				width: Math.max(1, width),
-				height: Math.max(1, height)
-			}
-		});
+	if (handle) {
+		try {
+			await handle.evaluate((el) => {
+				el.scrollIntoView({ block: 'center', inline: 'nearest' });
+				const cs = getComputedStyle(el);
+				if (parseFloat(cs.opacity) < 0.5) {
+					el.classList.add('in', 'is-inview', 'is-visible', 'visible', 'aos-animate');
+					el.style.opacity = '1';
+					el.style.transform = 'none';
+					el.style.visibility = 'visible';
+				}
+				for (const img of el.querySelectorAll('img')) {
+					img.loading = 'eager';
+					const ds = img.getAttribute('data-src') || img.getAttribute('data-lazy-src');
+					if (ds && !img.getAttribute('src')) img.setAttribute('src', ds);
+				}
+			});
+			await page.waitForTimeout(120);
+			// Wait briefly for in-section images.
+			await handle.evaluate(async (el) => {
+				const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+				const deadline = Date.now() + 2500;
+				while (Date.now() < deadline) {
+					const pending = [...el.querySelectorAll('img')].filter(
+						(img) => img.src && !(img.complete && img.naturalWidth > 0)
+					);
+					if (!pending.length) break;
+					await sleep(100);
+				}
+			}).catch(() => {});
+			return await handle.screenshot({ type: 'png', timeout: 20000 });
+		} catch (e) {
+			/* fall through to clip */
+		}
 	}
-	return handle.screenshot({ type: 'png' });
+	const { x, viewportTop, width, height } = section.box || {};
+	return page.screenshot({
+		type: 'png',
+		clip: {
+			x: Math.max(0, x || 0),
+			y: Math.max(0, viewportTop || 0),
+			width: Math.max(1, width || 1),
+			height: Math.max(1, Math.min(height || 1, 8000))
+		},
+		timeout: 15000
+	});
 }

package/src/constants.mjs

@@ -70,4 +70,4 @@ export const BANDS = {
 };
 
 export const SCHEMA_VERSION = 2;
-export const PACKAGE_VERSION = '0.2.2';
+export const PACKAGE_VERSION = '0.2.3';