@tractiontactics/tt-fidelity 0.2.1

package/fixtures/self-test.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Self-test harness for @tractiontactics/tt-fidelity 0.2
+ */
+import { pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { runFidelity } from '../src/index.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIX = __dirname;
+const fileUrl = (name) => pathToFileURL(join(FIX, name)).href;
+
+let failed = 0;
+function assert(cond, msg) {
+	if (!cond) {
+		console.error('FAIL:', msg);
+		failed += 1;
+	} else {
+		console.log('ok:', msg);
+	}
+}
+
+async function main() {
+	// 1. Known style drift — exit 1 in styles mode
+	{
+		const r = await runFidelity({
+			proto: fileUrl('proto.html'),
+			draft: fileUrl('draft.html'),
+			viewports: [1280],
+			mode: 'styles',
+			quiet: true
+		});
+		assert(r.exitCode === 1, 'styles mode: draft vs proto exits 1');
+	}
+
+	// 2. Identical — exit 0
+	{
+		const r = await runFidelity({
+			proto: fileUrl('pixel-identical.html'),
+			draft: fileUrl('pixel-identical.html'),
+			viewports: [1280],
+			mode: 'pixel',
+			quiet: true
+		});
+		assert(r.exitCode === 0, 'pixel identical pages exit 0');
+		assert(r.summary.failing === 0, 'pixel identical: 0 failing sections');
+	}
+
+	// 3. Pixel diverge (gradient) — exit 1
+	{
+		const out = mkdtempSync(join(tmpdir(), 'tt-fid-'));
+		const r = await runFidelity({
+			proto: fileUrl('pixel-identical.html'),
+			draft: fileUrl('pixel-diverge.html'),
+			viewports: [1280],
+			mode: 'pixel',
+			outDir: out,
+			quiet: true
+		});
+		assert(r.exitCode === 1, 'pixel diverge exits 1');
+		assert(r.summary.failing >= 1, 'pixel diverge: at least one failing section');
+		rmSync(out, { recursive: true, force: true });
+	}
+
+	// 4. Opaque markup — coverage guard in styles mode
+	{
+		const r = await runFidelity({
+			proto: fileUrl('proto.html'),
+			draft: fileUrl('draft-opaque.html'),
+			viewports: [1280],
+			mode: 'styles',
+			quiet: true
+		});
+		assert(r.exitCode === 2 || r.exitCode === 1, 'opaque draft: exit 2 (coverage) or 1 (diffs)');
+		if (r.exitCode === 2) assert(r.summary.error === 'low_coverage' || r.text.includes('CANNOT MEASURE'), 'opaque: low coverage message');
+	}
+
+	// 5. Multi-page cluster
+	{
+		const pages = [
+			{ id: 'cluster-a', proto: fileUrl('pages/cluster-a-proto.html'), draft: fileUrl('pages/cluster-a-draft.html') },
+			{ id: 'cluster-b', proto: fileUrl('pages/cluster-b-proto.html'), draft: fileUrl('pages/cluster-b-draft.html') }
+		];
+		const out = mkdtempSync(join(tmpdir(), 'tt-fid-c-'));
+		const r = await runFidelity({
+			pages,
+			viewports: [1280],
+			mode: 'pixel',
+			outDir: out,
+			quiet: true
+		});
+		assert(r.exitCode === 1, 'cluster pages exit 1');
+		const talk = (r.clusters || []).find((c) => /talk it through/i.test(c.label || c.key));
+		assert(talk && talk.pages >= 2, 'cluster: Prefer to talk it through spans 2 pages');
+		rmSync(out, { recursive: true, force: true });
+	}
+
+	if (failed) {
+		console.error(`\n${failed} assertion(s) failed`);
+		process.exit(1);
+	}
+	console.log('\nAll fidelity self-tests passed.');
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(2);
+});

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@tractiontactics/tt-fidelity",
+	"version": "0.2.1",
+	"description": "Section-first visual fidelity: hybrid SSIM+pixel gate + computed-style explainer for TT Platform prototype→site builds.",
+	"type": "module",
+	"bin": {
+		"tt-fidelity": "bin/tt-fidelity.js"
+	},
+	"main": "./src/index.mjs",
+	"exports": {
+		".": "./src/index.mjs",
+		"./package.json": "./package.json",
+		"./fidelity.schema.json": "./fidelity.schema.json"
+	},
+	"files": [
+		"bin",
+		"fidelity-diff.mjs",
+		"fidelity.schema.json",
+		"src",
+		"README.md",
+		"AGENTS.md",
+		"fixtures"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"keywords": [
+		"fidelity",
+		"visual-regression",
+		"pixelmatch",
+		"wordpress",
+		"tt-platform"
+	],
+	"license": "GPL-2.0-or-later",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tractiontactics/tt-wp-platform.git",
+		"directory": "tools/fidelity-diff"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"playwright": ">=1.40.0"
+	},
+	"peerDependenciesMeta": {
+		"playwright": {
+			"optional": true
+		}
+	},
+	"dependencies": {
+		"pixelmatch": "^7.2.0",
+		"pngjs": "^7.0.0"
+	}
+}

package/src/capture.mjs

@@ -0,0 +1,114 @@
+/**
+ * Playwright capture helpers: cache-bust, auth, fonts, section shots.
+ */
+
+export function basic(pair) {
+	if (!pair) return undefined;
+	const i = pair.indexOf(':');
+	if (i < 0) return undefined;
+	return { username: pair.slice(0, i), password: pair.slice(i + 1) };
+}
+
+export function cacheBustUrl(url, enabled = true) {
+	if (!enabled) return url;
+	try {
+		const u = new URL(url);
+		if (u.protocol === 'file:') return url;
+		u.searchParams.set('tt_nocache', String(Date.now()));
+		return u.toString();
+	} catch (e) {
+		return url;
+	}
+}
+
+export function pickCacheHeaders(headers) {
+	const out = {};
+	for (const key of ['x-cache', 'x-cacheable', 'age', 'cf-cache-status', 'cache-control', 'x-drupal-cache']) {
+		const v = headers[key] || headers[key.toLowerCase()];
+		if (v) out[key] = v;
+	}
+	return out;
+}
+
+/**
+ * Navigate and wait for fonts / network.
+ * @returns {{ page, context, cacheHeaders, finalUrl }}
+ */
+export async function openPage(browser, {
+	url,
+	width,
+	height = 900,
+	auth,
+	cookie,
+	cacheBust = true,
+	menus = false
+}) {
+	const target = cacheBustUrl(url, cacheBust);
+	const httpCredentials = basic(auth);
+	const ctx = await browser.newContext({
+		viewport: { width, height },
+		httpCredentials,
+		ignoreHTTPSErrors: true
+	});
+	if (cookie) {
+		try {
+			const { hostname } = new URL(url);
+			await ctx.addCookies(
+				cookie.split(';').map((pair) => {
+					const [name, ...rest] = pair.trim().split('=');
+					return { name, value: rest.join('='), domain: hostname, path: '/' };
+				})
+			);
+		} catch (e) {
+			/* file:// has no hostname */
+		}
+	}
+	const page = await ctx.newPage();
+	let cacheHeaders = {};
+	page.on('response', (res) => {
+		try {
+			if (res.url().split('?')[0] === target.split('?')[0] || res.url() === target) {
+				cacheHeaders = pickCacheHeaders(res.headers());
+			}
+		} catch (e) { /* ignore */ }
+	});
+	await page.goto(target, { waitUntil: 'networkidle', timeout: 45000 });
+	await page.evaluate(() => document.fonts && document.fonts.ready).catch(() => {});
+	await page.waitForTimeout(250);
+
+	if (menus) {
+		for (const s of ['nav li:has(ul)', '.menu-item-has-children', 'nav [aria-haspopup]']) {
+			try {
+				const el = page.locator(s).first();
+				if (await el.count()) {
+					await el.hover({ timeout: 2000 });
+					await page.waitForTimeout(350);
+					break;
+				}
+			} catch (e) { /* try next */ }
+		}
+	}
+
+	return { page, context: ctx, cacheHeaders, finalUrl: page.url() };
+}
+
+/**
+ * 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)
+			}
+		});
+	}
+	return handle.screenshot({ type: 'png' });
+}

package/src/cli.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * CLI for @tractiontactics/tt-fidelity
+ */
+import { pathToFileURL } from 'node:url';
+import { runFidelity } from './run.mjs';
+import { GROUPS } from './constants.mjs';
+
+function parseArgs(argv) {
+	const out = {
+		viewports: [1280, 768, 390],
+		tolerance: 1,
+		only: null,
+		menus: false,
+		quiet: false,
+		scope: 'full',
+		round: 1,
+		maxRounds: 6,
+		mode: 'full',
+		cacheBust: true,
+		concurrency: 1,
+		planOnly: false,
+		onlyFailing: false
+	};
+	for (let i = 0; i < argv.length; i += 1) {
+		const a = argv[i];
+		const next = () => argv[++i];
+		if (a === '--proto') out.proto = next();
+		else if (a === '--draft') out.draft = next();
+		else if (a === '--pages') out.pagesFile = next();
+		else if (a === '--out') out.outDir = next();
+		else if (a === '--mode') out.mode = next();
+		else if (a === '--metric') out.metric = next();
+		else if (a === '--aa-threshold') out.aaThreshold = parseFloat(next());
+		else if (a === '--threshold') out.threshold = parseFloat(next());
+		else if (a === '--cache-bust') out.cacheBust = true;
+		else if (a === '--no-cache-bust') out.cacheBust = false;
+		else if (a === '--concurrency') out.concurrency = Math.max(1, parseInt(next(), 10) || 1);
+		else if (a === '--only-failing') out.onlyFailing = true;
+		else if (a === '--prior') out.priorJson = next();
+		else if (a === '--viewports') out.viewports = next().split(',').map((s) => parseInt(s.trim(), 10)).filter(Boolean);
+		else if (a === '--tolerance') out.tolerance = parseFloat(next());
+		else if (a === '--only') out.only = next().split(',').map((s) => s.trim()).filter(Boolean);
+		else if (a === '--menus') out.menus = true;
+		else if (a === '--auth') out.auth = next();
+		else if (a === '--draft-auth') out.draftAuth = next();
+		else if (a === '--cookie') out.cookie = next();
+		else if (a === '--roles') out.roles = next();
+		else if (a === '--scope') out.scope = next();
+		else if (a === '--round') out.round = Math.max(1, parseInt(next(), 10) || 1);
+		else if (a === '--max-rounds') out.maxRounds = Math.max(1, parseInt(next(), 10) || 6);
+		else if (a === '--json') out.json = next();
+		else if (a === '--plan-only') out.planOnly = true;
+		else if (a === '--quiet') out.quiet = true;
+		else if (a === '--help' || a === '-h') out.help = true;
+	}
+	return out;
+}
+
+function usage() {
+	console.log(`tt-fidelity — section pixel gate + style explainer for prototype→site builds.
+
+  npx @tractiontactics/tt-fidelity --proto <url> --draft <url> [options]
+  node fidelity-diff.mjs --proto <url> --draft <url> [options]
+
+  --proto / --draft          single page pair
+  --pages <file>             JSON [{id,proto,draft}] or txt (proto|draft per line)
+  --out <dir>                write fidelity.json, QUEUE.md, shots/
+  --mode full|pixel|styles   default full (pixel/SSIM gates exit 0; styles explain)
+  --metric hybrid|ssim|pixel default hybrid (SSIM divergence + AA-aware pixel floor)
+  --aa-threshold <0-1>       pixelmatch colour threshold (default 0.14)
+  --threshold <0-1>          section fail when score >= (default 0.10 = clean band)
+  --viewports 1280,768,390
+  --tolerance 1              px tolerance for style lengths
+  --only fonts,colours       style buckets only (${Object.keys(GROUPS).join(',')},menus)
+  --menus                    hover nav for dropdowns
+  --auth u:p / --draft-auth  basic auth
+  --cookie "n=v"             draft cookies
+  --roles roles.json         project role map
+  --scope full|chrome|content
+  --round / --max-rounds     fidelity loop (exit 3 at max with diffs)
+  --cache-bust / --no-cache-bust  default ON (tt_nocache=)
+  --concurrency <n>          parallel pages (default 1)
+  --only-failing             skip sections clean in prior fidelity.json
+  --prior <path>             prior fidelity.json for --only-failing
+  --json out.json            also write document
+  --plan-only                suppress raw evidence tables
+  --quiet
+
+Exit 0 = pixel gate clean (or styles clean in --mode styles)
+Exit 1 = differences remain
+Exit 2 = could not run / low coverage
+Exit 3 = max rounds reached with diffs`);
+}
+
+export async function main(argv = process.argv.slice(2)) {
+	const args = parseArgs(argv);
+	if (args.help || ((!args.proto || !args.draft) && !args.pagesFile)) {
+		usage();
+		process.exit(args.help ? 0 : 2);
+	}
+	if (args.mode && !['full', 'pixel', 'styles'].includes(args.mode)) {
+		console.error(`unknown --mode "${args.mode}" (use full, pixel, or styles)`);
+		process.exit(2);
+	}
+	if (args.metric && !['hybrid', 'ssim', 'pixel'].includes(args.metric)) {
+		console.error(`unknown --metric "${args.metric}" (use hybrid, ssim, or pixel)`);
+		process.exit(2);
+	}
+
+	try {
+		const result = await runFidelity(args);
+		if (result.text) console.log(result.text);
+		process.exit(result.exitCode);
+	} catch (err) {
+		console.error(`tt-fidelity failed: ${err && err.message ? err.message : err}`);
+		process.exit(err?.exitCode || 2);
+	}
+}
+
+// Only auto-run when this file is the process entry (not when imported by fidelity-diff.mjs).
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	main();
+}

package/src/constants.mjs

@@ -0,0 +1,73 @@
+/** Shared measurement constants for @tractiontactics/tt-fidelity */
+
+export const GROUPS = {
+	flow: ['display', 'position', 'flex-direction', 'justify-content', 'flex-wrap', 'grid-template-columns'],
+	alignment: ['text-align', 'align-items', 'vertical-align'],
+	padding_margin: [
+		'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+		'margin-top', 'margin-right', 'margin-bottom', 'margin-left'
+	],
+	gaps: ['row-gap', 'column-gap'],
+	widths: ['max-width', 'min-height'],
+	fonts: [
+		'font-family', 'font-size', 'font-weight', 'line-height',
+		'letter-spacing', 'text-transform', 'font-style'
+	],
+	colours: [
+		'color', 'background-color', 'border-radius', 'box-shadow', 'opacity',
+		'border-top-width', 'border-top-color', 'border-bottom-width', 'border-bottom-color',
+		'border-left-width', 'border-left-color', 'border-right-width', 'border-right-color'
+	],
+	motion: ['transition-duration', 'transition-property', 'animation-name'],
+	imagery: ['object-fit', 'object-position']
+};
+
+export const ALL_PROPS = [...new Set(Object.values(GROUPS).flat())];
+
+export const BUCKET_OF = Object.fromEntries(
+	Object.entries(GROUPS).flatMap(([bucket, props]) => props.map((p) => [p, bucket]))
+);
+
+/**
+ * Landmark roles. First matching selector wins.
+ * Draft-side section probes prefer TT builder rows (see sections.mjs).
+ */
+export const DEFAULT_ROLES = [
+	['header', ['header', '[role=banner]', '.site-header', '.header', '#header',
+		'[class*=header i]', '[class*=hdr i]', '[class*=masthead i]', 'body > *:first-child'], 1],
+	['logo', ['.logo', '.site-logo', '[class*=logo i] img', '[class*=logo i]',
+		'[class*=brand i]', 'header img'], 1],
+	['nav', ['nav', '[role=navigation]', '.main-navigation', '.menu',
+		'[class*=nav i]', '[class*=menu i]'], 1],
+	['nav-item', ['nav a', '[role=navigation] a', '.menu a',
+		'[class*=nav i] a', '[class*=menu i] a'], 8],
+	['submenu', ['nav ul ul', '.sub-menu', '[class*=dropdown i]', '[class*=submenu i]',
+		'[class*=subnav i]'], 2],
+	['submenu-item', ['nav ul ul a', '.sub-menu a', '[class*=dropdown i] a',
+		'[class*=submenu i] a'], 6],
+	['main', ['main', '[role=main]', '.site-main', '#main', '#content',
+		'[class*=container i]', '[class*=wrapper i]', '[class*=wrap i]'], 1],
+	['h1', ['h1', '[class*=title i]', '[class*=headline i]'], 1],
+	['h2', ['h2', '[class*=subtitle i]'], 4],
+	['h3', ['h3'], 4],
+	['button', ['a.button', 'button', '.btn', '[class*=btn i]', '[class*=button i]',
+		'[class*=cta i]'], 6],
+	['section', ['main > section', 'main > .tt-pb-row', '.tt-pb-row', 'main > div', 'body > section',
+		'main > *'], 8],
+	['card', ['.tt-pb-card-grid__card', '.tt-pb-fcar', '[class*=card i]', '[class*=tile i]'], 6],
+	['img', ['main img', 'img'], 4],
+	['footer', ['footer', '[role=contentinfo]', '.site-footer', '.footer',
+		'[class*=footer i]', '[class*=ftr i]', 'body > *:last-child'], 1]
+];
+
+export const CHROME_ROLES = new Set(['header', 'logo', 'nav', 'nav-item', 'submenu', 'submenu-item', 'footer']);
+export const CHROME_ROLE_SET = CHROME_ROLES;
+
+/** Pixel severity bands (Halo §2.7). score = differing pixels / area. */
+export const BANDS = {
+	clean: 0.1,
+	fix: 0.4
+};
+
+export const SCHEMA_VERSION = 2;
+export const PACKAGE_VERSION = '0.2.1';

package/src/fonts.mjs

@@ -0,0 +1,61 @@
+/**
+ * Resolve the font family that actually paints (Halo §2.2).
+ * Runs inside the page via page.evaluate.
+ */
+
+/* eslint-disable no-undef */
+export function resolveRenderedFonts(selectors) {
+	const probe = (family) => {
+		const canvas = document.createElement('canvas');
+		const ctx = canvas.getContext('2d');
+		const sample = 'mmmmmmmmmmlli';
+		ctx.font = '72px monospace';
+		const baseline = ctx.measureText(sample).width;
+		ctx.font = `72px ${family}, monospace`;
+		return Math.abs(ctx.measureText(sample).width - baseline) > 0.5;
+	};
+
+	const out = {};
+	for (const sel of selectors) {
+		let el;
+		try {
+			el = document.querySelector(sel);
+		} catch (e) {
+			continue;
+		}
+		if (!el) continue;
+		const stack = getComputedStyle(el).fontFamily || '';
+		const families = stack.split(',').map((f) => f.trim().replace(/^["']|["']$/g, ''));
+		let rendered = families[families.length - 1] || stack;
+		for (const f of families) {
+			if (!f || f.toLowerCase() === 'inherit') continue;
+			const quoted = /\s/.test(f) ? `"${f}"` : f;
+			if (probe(quoted)) {
+				rendered = f;
+				break;
+			}
+		}
+		out[sel] = { declared: stack, rendered };
+	}
+	return out;
+}
+/* eslint-enable no-undef */
+
+/**
+ * Drop font-family style rows where declared stacks differ but rendered faces match.
+ */
+export function suppressFalseFontFamilyRows(elements, protoFonts, draftFonts) {
+	if (!protoFonts || !draftFonts) return elements;
+	return elements
+		.map((el) => {
+			const rows = el.rows.filter((row) => {
+				if (row.prop !== 'font-family') return true;
+				const pf = protoFonts[el.protoSelector];
+				const df = draftFonts[el.draftSelector];
+				if (!pf || !df) return true;
+				return pf.rendered.toLowerCase() !== df.rendered.toLowerCase();
+			});
+			return { ...el, rows };
+		})
+		.filter((el) => el.rows.length);
+}

package/src/index.mjs

@@ -0,0 +1,6 @@
+export { runFidelity } from './run.mjs';
+export { GROUPS, BANDS, DEFAULT_ROLES, SCHEMA_VERSION, PACKAGE_VERSION } from './constants.mjs';
+export { compareSectionPngs, scoreBand, computeSsim, DEFAULT_AA_THRESHOLD } from './pixel.mjs';
+export { clusterSections } from './rank.mjs';
+export { buildFidelityDocument } from './schema.mjs';
+export { buildPlan } from './plan.mjs';