@tractiontactics/tt-fidelity 0.2.1

package/src/run.mjs

@@ -0,0 +1,433 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { BANDS, GROUPS, ALL_PROPS } from './constants.mjs';
+import { openPage, screenshotSection } from './capture.mjs';
+import { inPageSections, alignSections } from './sections.mjs';
+import { compareSectionPngs, sectionFailsGate } from './pixel.mjs';
+import {
+	loadRoles,
+	filterRolesByScope,
+	inPageCapture,
+	diffStyles,
+	assessCoverage,
+	renderCoverageFailure
+} from './styles.mjs';
+import { resolveRenderedFonts, suppressFalseFontFamilyRows } from './fonts.mjs';
+import { buildPlan, renderPixelReport, renderQueueMd, setRoleOrder, renderStyleEvidence } from './plan.mjs';
+import { clusterSections } from './rank.mjs';
+import { buildFidelityDocument } from './schema.mjs';
+
+/**
+ * @typedef {object} FidelityOptions
+ * @property {string} [proto]
+ * @property {string} [draft]
+ * @property {Array<{id?: string, proto: string, draft: string}>} [pages]
+ * @property {string} [pagesFile] path to JSON/txt/sitemap list
+ * @property {number[]} [viewports]
+ * @property {number} [tolerance]
+ * @property {string[]} [only]
+ * @property {boolean} [menus]
+ * @property {string} [auth]
+ * @property {string} [draftAuth]
+ * @property {string} [cookie]
+ * @property {string} [roles]
+ * @property {string} [scope]
+ * @property {number} [round]
+ * @property {number} [maxRounds]
+ * @property {string} [json]
+ * @property {string} [outDir]
+ * @property {'full'|'pixel'|'styles'} [mode]
+ * @property {number} [threshold] fail when score >= this (default BANDS.clean)
+ * @property {boolean} [cacheBust]
+ * @property {number} [concurrency]
+ * @property {boolean} [planOnly]
+ * @property {boolean} [quiet]
+ * @property {boolean} [onlyFailing]
+ * @property {string} [priorJson]
+ */
+
+function log(opts, msg) {
+	if (!opts.quiet) console.error(msg);
+}
+
+function resolvePages(opts) {
+	if (Array.isArray(opts.pages) && opts.pages.length) {
+		return opts.pages.map((p, i) => ({
+			id: p.id || `page-${i + 1}`,
+			proto: p.proto,
+			draft: p.draft
+		}));
+	}
+	if (opts.pagesFile) {
+		return loadPagesFile(opts.pagesFile, opts);
+	}
+	if (opts.proto && opts.draft) {
+		return [{ id: 'page-1', proto: opts.proto, draft: opts.draft }];
+	}
+	throw new Error('provide --proto and --draft, or --pages <file>, or pages[]');
+}
+
+function loadPagesFile(path, opts) {
+	const raw = readFileSync(path, 'utf8');
+	if (path.endsWith('.json')) {
+		const data = JSON.parse(raw);
+		if (Array.isArray(data)) {
+			return data.map((p, i) => ({
+				id: p.id || `page-${i + 1}`,
+				proto: p.proto || p.prototype,
+				draft: p.draft
+			}));
+		}
+		throw new Error('--pages JSON must be an array of {id?, proto, draft}');
+	}
+	// txt: one draft path/url per line; pair with --proto as base or proto|draft per line
+	const lines = raw.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+	return lines.map((line, i) => {
+		if (line.includes('|')) {
+			const [proto, draft] = line.split('|').map((s) => s.trim());
+			return { id: `page-${i + 1}`, proto, draft };
+		}
+		if (!opts.proto) throw new Error('txt --pages with draft-only lines requires --proto as template base');
+		return { id: `page-${i + 1}`, proto: opts.proto, draft: line };
+	});
+}
+
+async function measurePagePair(browser, pageSpec, opts, roles) {
+	const viewports = [];
+	const mode = opts.mode || 'full';
+	const doPixel = mode === 'full' || mode === 'pixel';
+	const doStyles = mode === 'full' || mode === 'styles';
+	const failThreshold = opts.threshold ?? BANDS.clean;
+
+	for (const width of opts.viewports) {
+		log(opts, `  ${pageSpec.id} @ ${width}px …`);
+
+		const protoOpen = await openPage(browser, {
+			url: pageSpec.proto,
+			width,
+			auth: opts.auth,
+			cacheBust: opts.cacheBust !== false,
+			menus: opts.menus
+		});
+		const draftOpen = await openPage(browser, {
+			url: pageSpec.draft,
+			width,
+			auth: opts.draftAuth || opts.auth,
+			cookie: opts.cookie,
+			cacheBust: opts.cacheBust !== false,
+			menus: opts.menus
+		});
+
+		let styleDiff = { elements: [], global: [], structural: [], total: 0 };
+		let coverage = { matched: [], onlyProto: [], onlyDraft: [], absentBoth: [], ratio: 1, unreliable: false };
+		let protoCapture = null;
+		let draftCapture = null;
+
+		if (doStyles) {
+			protoCapture = await protoOpen.page.evaluate(inPageCapture, { props: ALL_PROPS, roles });
+			draftCapture = await draftOpen.page.evaluate(inPageCapture, { props: ALL_PROPS, roles });
+			coverage = assessCoverage(protoCapture, draftCapture, roles);
+			styleDiff = diffStyles(protoCapture, draftCapture, opts.tolerance, opts.only);
+			try {
+				const sels = [
+					...new Set([
+						...styleDiff.elements.map((e) => e.protoSelector),
+						...styleDiff.elements.map((e) => e.draftSelector)
+					])
+				].slice(0, 20);
+				if (sels.length) {
+					const pf = await protoOpen.page.evaluate(resolveRenderedFonts, sels);
+					const df = await draftOpen.page.evaluate(resolveRenderedFonts, sels);
+					styleDiff.elements = suppressFalseFontFamilyRows(styleDiff.elements, pf, df);
+					styleDiff.total = styleDiff.global.length + styleDiff.elements.reduce((n, el) => n + el.rows.length, 0);
+				}
+			} catch (e) {
+				/* font probe optional */
+			}
+		}
+
+		const sections = [];
+		if (doPixel) {
+			const protoSecs = await protoOpen.page.evaluate(inPageSections, { scope: opts.scope });
+			const draftSecs = await draftOpen.page.evaluate(inPageSections, { scope: opts.scope });
+			const { pairs, structural } = alignSections(protoSecs, draftSecs);
+			styleDiff.structural = [...(styleDiff.structural || []), ...structural];
+
+			const shotsDir = opts.outDir
+				? join(opts.outDir, 'shots', 'sections', pageSpec.id, String(width))
+				: null;
+			if (shotsDir) mkdirSync(join(shotsDir, 'prototype'), { recursive: true });
+			if (shotsDir) mkdirSync(join(shotsDir, 'draft'), { recursive: true });
+			if (shotsDir) mkdirSync(join(shotsDir, 'diff'), { recursive: true });
+
+			for (const pair of pairs) {
+				if (opts.onlyFailing && opts.priorClean?.has(`${pageSpec.id}:${width}:${pair.index}`)) {
+					sections.push({
+						index: pair.index,
+						label: pair.draft.label,
+						protoSelector: pair.proto.selector,
+						draftSelector: pair.draft.selector,
+						ttRowId: pair.draft.ttRowId,
+						ttBlockIds: pair.draft.ttBlockIds,
+						score: 0,
+						band: 'clean',
+						skipped: true
+					});
+					continue;
+				}
+
+				const protoPng = await screenshotSection(protoOpen.page, pair.proto);
+				const draftPng = await screenshotSection(draftOpen.page, pair.draft);
+				const cmp = compareSectionPngs(protoPng, draftPng, {
+					includeDiff: Boolean(shotsDir),
+					metric: opts.metric || 'hybrid',
+					threshold: Number.isFinite(opts.aaThreshold) ? opts.aaThreshold : undefined
+				});
+
+				const shotPaths = {};
+				if (shotsDir) {
+					const base = String(pair.index).padStart(2, '0');
+					const pp = join(shotsDir, 'prototype', `${base}.png`);
+					const dp = join(shotsDir, 'draft', `${base}.png`);
+					const dif = join(shotsDir, 'diff', `${base}.png`);
+					writeFileSync(pp, protoPng);
+					writeFileSync(dp, draftPng);
+					if (cmp.diffPng) writeFileSync(dif, cmp.diffPng);
+					shotPaths.proto = pp;
+					shotPaths.draft = dp;
+					shotPaths.diff = dif;
+				}
+
+				sections.push({
+					index: pair.index,
+					label: pair.draft.label || pair.proto.label,
+					protoSelector: pair.proto.selector,
+					draftSelector: pair.draft.selector,
+					ttRowId: pair.draft.ttRowId,
+					ttBlockIds: pair.draft.ttBlockIds,
+					score: cmp.score,
+					band: cmp.band,
+					metric: cmp.metric,
+					pixelRatio: cmp.pixelRatio,
+					ssim: cmp.ssim,
+					diffPixels: cmp.diffPixels,
+					shotPaths
+				});
+			}
+		}
+
+		await protoOpen.context.close();
+		await draftOpen.context.close();
+
+		const plan = buildPlan(styleDiff, { pixelSections: sections });
+		viewports.push({
+			width,
+			coverage,
+			styleDiff,
+			sections,
+			cacheHeaders: draftOpen.cacheHeaders,
+			plan
+		});
+	}
+
+	return {
+		id: pageSpec.id,
+		proto: pageSpec.proto,
+		draft: pageSpec.draft,
+		viewports
+	};
+}
+
+function loadPriorClean(priorJson) {
+	const set = new Set();
+	if (!priorJson || !existsSync(priorJson)) return set;
+	try {
+		const doc = JSON.parse(readFileSync(priorJson, 'utf8'));
+		for (const page of doc.pages || []) {
+			for (const vp of page.viewports || []) {
+				for (const s of vp.sections || []) {
+					if (s.band === 'clean') set.add(`${page.id}:${vp.width}:${s.index}`);
+				}
+			}
+		}
+	} catch (e) { /* ignore */ }
+	return set;
+}
+
+/**
+ * Programmatic entry: run a fidelity comparison.
+ * @param {FidelityOptions} opts
+ * @returns {Promise<{ exitCode: number, summary: object, pages: object[], plan: object[], document: object, text: string }>}
+ */
+export async function runFidelity(opts = {}) {
+	const options = {
+		viewports: [1280, 768, 390],
+		tolerance: 1,
+		mode: 'full',
+		scope: 'full',
+		round: 1,
+		maxRounds: 6,
+		cacheBust: true,
+		concurrency: 1,
+		threshold: BANDS.clean,
+		metric: 'hybrid',
+		...opts
+	};
+
+	let roles;
+	try {
+		roles = filterRolesByScope(loadRoles(options.roles), options.scope);
+	} catch (err) {
+		throw Object.assign(new Error(err.message), { exitCode: 2 });
+	}
+	if (!roles.length) {
+		throw Object.assign(new Error('--scope left no roles to measure.'), { exitCode: 2 });
+	}
+	setRoleOrder(roles);
+
+	const pagesSpec = resolvePages(options);
+	if (options.outDir) mkdirSync(options.outDir, { recursive: true });
+
+	let chromium;
+	try {
+		({ chromium } = await import('playwright'));
+	} catch (err) {
+		throw Object.assign(
+			new Error('Playwright required. Run: npm i -D playwright && npx playwright install chromium'),
+			{ exitCode: 2 }
+		);
+	}
+
+	options.priorClean = options.onlyFailing
+		? loadPriorClean(options.priorJson || (options.outDir && join(options.outDir, 'fidelity.json')))
+		: new Set();
+
+	const browser = await chromium.launch();
+	const pages = [];
+
+	try {
+		const conc = Math.max(1, options.concurrency | 0);
+		for (let i = 0; i < pagesSpec.length; i += conc) {
+			const batch = pagesSpec.slice(i, i + conc);
+			const measured = await Promise.all(
+				batch.map((p) => measurePagePair(browser, p, options, roles))
+			);
+			pages.push(...measured);
+		}
+	} finally {
+		await browser.close();
+	}
+
+	// Coverage guard (styles path)
+	if (options.mode === 'full' || options.mode === 'styles') {
+		for (const page of pages) {
+			for (const vp of page.viewports) {
+				if (vp.coverage?.unreliable) {
+					const text = renderCoverageFailure(vp.coverage, options.roles).join('\n');
+					return {
+						exitCode: 2,
+						summary: { error: 'low_coverage' },
+						pages,
+						plan: [],
+						document: { error: 'low_coverage', pages },
+						text
+					};
+				}
+			}
+		}
+	}
+
+	const clusters = clusterSections(pages);
+	const flatPlan = [];
+	for (const page of pages) {
+		for (const vp of page.viewports) {
+			for (const t of vp.plan?.tasks || []) {
+				flatPlan.push({ ...t, pageId: page.id, width: vp.width });
+			}
+		}
+	}
+
+	const mode = options.mode;
+	let dirty = false;
+	if (mode === 'styles') {
+		dirty = pages.some((p) =>
+			p.viewports.some((vp) => vp.styleDiff?.total || vp.styleDiff?.structural?.length)
+		);
+	} else {
+		dirty = pages.some((p) =>
+			p.viewports.some((vp) =>
+				(vp.sections || []).some((s) => sectionFailsGate(s.score, options.threshold))
+				|| (vp.styleDiff?.structural || []).some((s) => s.kind === 'count' && s.role === 'section')
+			)
+		);
+	}
+
+	let exitCode = dirty ? 1 : 0;
+	if (dirty && options.round >= options.maxRounds) exitCode = 3;
+
+	const document = buildFidelityDocument({
+		mode,
+		threshold: options.threshold,
+		round: options.round,
+		maxRounds: options.maxRounds,
+		pages,
+		clusters,
+		workPlan: flatPlan,
+		exitCode
+	});
+
+	if (options.outDir) {
+		writeFileSync(join(options.outDir, 'fidelity.json'), JSON.stringify(document, null, 2));
+		writeFileSync(join(options.outDir, 'QUEUE.md'), renderQueueMd(clusters, pages));
+		log(options, `wrote ${join(options.outDir, 'fidelity.json')}`);
+	}
+	if (options.json) {
+		writeFileSync(options.json, JSON.stringify(document, null, 2));
+		log(options, `wrote ${options.json}`);
+	}
+
+	let text = '';
+	if (mode === 'styles') {
+		const styleResults = pages.flatMap((p) =>
+			p.viewports.map((vp) => ({
+				width: vp.width,
+				coverage: vp.coverage,
+				diff: vp.styleDiff,
+				pixelSections: []
+			}))
+		);
+		text = renderStyleEvidence(styleResults, options.tolerance, options.planOnly);
+	} else {
+		text = renderPixelReport(pages, { mode });
+		if (mode === 'full' && !options.planOnly) {
+			const styleResults = pages.flatMap((p) =>
+				p.viewports.map((vp) => ({
+					width: vp.width,
+					coverage: vp.coverage,
+					diff: vp.styleDiff,
+					pixelSections: vp.sections
+				}))
+			);
+			text += '\n\n' + renderStyleEvidence(styleResults, options.tolerance, true);
+		}
+	}
+
+	if (options.round > 1 || options.maxRounds !== 6) {
+		text += `\n\nFIDELITY LOOP: round ${options.round} of ${options.maxRounds}.`;
+	}
+	if (exitCode === 3) {
+		text += `\n\nMAX ROUNDS REACHED (${options.round}/${options.maxRounds}) — STOP LOOPING`;
+	}
+
+	return {
+		exitCode,
+		summary: document.summary,
+		pages,
+		plan: flatPlan,
+		clusters,
+		document,
+		text
+	};
+}
+
+export { GROUPS, BANDS, ALL_PROPS };

package/src/schema.mjs

@@ -0,0 +1,62 @@
+import { SCHEMA_VERSION, PACKAGE_VERSION, BANDS } from './constants.mjs';
+
+/**
+ * Build fidelity.json v2 document.
+ */
+export function buildFidelityDocument({
+	mode,
+	threshold,
+	round,
+	maxRounds,
+	pages,
+	clusters,
+	workPlan,
+	exitCode
+}) {
+	return {
+		schema_version: SCHEMA_VERSION,
+		package_version: PACKAGE_VERSION,
+		mode,
+		threshold: {
+			clean: threshold ?? BANDS.clean,
+			fix: BANDS.fix,
+			rebuild: BANDS.fix
+		},
+		round,
+		max_rounds: maxRounds,
+		exit_code: exitCode,
+		summary: summarize(pages),
+		clusters: clusters || [],
+		work_plan: workPlan || [],
+		pages
+	};
+}
+
+function summarize(pages) {
+	let sections = 0;
+	let failing = 0;
+	let rebuild = 0;
+	for (const page of pages) {
+		for (const vp of page.viewports || []) {
+			for (const s of vp.sections || []) {
+				sections += 1;
+				if (s.band !== 'clean') failing += 1;
+				if (s.band === 'rebuild') rebuild += 1;
+			}
+		}
+	}
+	return {
+		pages: pages.length,
+		sections,
+		failing,
+		rebuild,
+		clean: sections - failing
+	};
+}
+
+export function mapTtFromSection(section) {
+	return {
+		ttRowId: section.ttRowId || null,
+		ttBlockIds: Array.isArray(section.ttBlockIds) ? section.ttBlockIds : []
+	};
+}

package/src/sections.mjs

@@ -0,0 +1,119 @@
+/**
+ * Section discovery for pixel grading.
+ * Draft (TT): prefer .tt-pb-row / data-tt-row.
+ * Prototype: prefer main > section, then body sections.
+ */
+
+/* eslint-disable no-undef */
+export function inPageSections({ scope }) {
+	const visible = (el) => {
+		if (!el) return false;
+		const cs = getComputedStyle(el);
+		if (cs.visibility === 'hidden' || cs.display === 'none') return false;
+		const r = el.getBoundingClientRect();
+		return r.width > 2 && r.height > 2;
+	};
+
+	const selOf = (el) => {
+		if (!el) return '';
+		if (el.getAttribute('data-tt-row')) return `[data-tt-row="${el.getAttribute('data-tt-row')}"]`;
+		if (el.id) return `#${CSS.escape(el.id)}`;
+		const tag = el.tagName.toLowerCase();
+		const parent = el.parentElement;
+		if (!parent) return tag;
+		const sibs = [...parent.children].filter((c) => c.tagName === el.tagName);
+		const idx = sibs.indexOf(el) + 1;
+		return `${tag}:nth-of-type(${idx})`;
+	};
+
+	const heading = (el) => {
+		const h = el.querySelector('h1,h2,h3,h4,[class*=headline i],[class*=heading i]');
+		return h ? (h.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80) : '';
+	};
+
+	const box = (el) => {
+		const r = el.getBoundingClientRect();
+		const top = Math.round(r.top + window.scrollY);
+		return {
+			x: Math.round(r.left),
+			y: top,
+			width: Math.round(r.width),
+			height: Math.round(r.height),
+			viewportTop: Math.round(r.top),
+			viewportLeft: Math.round(r.left)
+		};
+	};
+
+	const ttMeta = (el) => {
+		const rowId = el.getAttribute('data-tt-row') || (el.id && /^row_/.test(el.id) ? el.id : '');
+		const blocks = [...el.querySelectorAll('[data-tt-block], .tt-pb-block[id^="blk_"]')]
+			.map((b) => b.getAttribute('data-tt-block') || b.id)
+			.filter(Boolean);
+		return { ttRowId: rowId || null, ttBlockIds: blocks };
+	};
+
+	let nodes = [];
+	const s = String(scope || 'full').toLowerCase();
+
+	if (s === 'chrome') {
+		const chrome = [
+			...document.querySelectorAll('header, [role=banner], .site-header, footer, [role=contentinfo], .site-footer')
+		].filter(visible);
+		nodes = chrome;
+	} else {
+		const ttRows = [...document.querySelectorAll('.tt-pb-row, [data-tt-row]')].filter(visible);
+		if (ttRows.length) {
+			nodes = ttRows;
+		} else {
+			const main = document.querySelector('main, [role=main], .site-main') || document.body;
+			const sections = [...main.querySelectorAll(':scope > section')].filter(visible);
+			if (sections.length) {
+				nodes = sections;
+			} else {
+				nodes = [...main.children].filter(
+					(el) => visible(el) && !['SCRIPT', 'STYLE', 'LINK', 'NOSCRIPT'].includes(el.tagName)
+				);
+			}
+		}
+		if (s === 'content') {
+			nodes = nodes.filter((el) => !el.closest('header, footer, [role=banner], [role=contentinfo]'));
+		}
+	}
+
+	return nodes.map((el, i) => {
+		const meta = ttMeta(el);
+		return {
+			index: i,
+			selector: selOf(el),
+			label: heading(el) || (el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 48),
+			box: box(el),
+			ttRowId: meta.ttRowId,
+			ttBlockIds: meta.ttBlockIds
+		};
+	});
+}
+/* eslint-enable no-undef */
+
+/**
+ * Align sections by document order. Length mismatch → structural findings.
+ */
+export function alignSections(protoSections, draftSections) {
+	const n = Math.min(protoSections.length, draftSections.length);
+	const pairs = [];
+	for (let i = 0; i < n; i += 1) {
+		pairs.push({ index: i, proto: protoSections[i], draft: draftSections[i] });
+	}
+	const structural = [];
+	if (protoSections.length !== draftSections.length) {
+		structural.push({
+			kind: 'count',
+			role: 'section',
+			text: `section: prototype has ${protoSections.length}, draft has ${draftSections.length}${
+				draftSections.length < protoSections.length
+					? ` (draft is missing ${protoSections.length - draftSections.length})`
+					: ` (draft has ${draftSections.length - protoSections.length} extra)`
+			}`
+		});
+	}
+	return { pairs, structural };
+}