@tractiontactics/tt-fidelity 0.2.1

package/src/pixel.mjs

@@ -0,0 +1,197 @@
+import { createRequire } from 'node:module';
+import { BANDS } from './constants.mjs';
+
+const require = createRequire(import.meta.url);
+const { PNG } = require('pngjs');
+const pixelmatchMod = require('pixelmatch');
+const pixelmatch = typeof pixelmatchMod === 'function' ? pixelmatchMod : pixelmatchMod.default;
+
+/** Default pixelmatch colour threshold (0–1). Slightly tolerant of AA. */
+export const DEFAULT_AA_THRESHOLD = 0.14;
+
+/**
+ * Build luminance plane (0–255) from RGBA buffer.
+ * @param {Uint8Array|Buffer} data
+ * @param {number} width
+ * @param {number} height
+ * @returns {Float64Array}
+ */
+function luminancePlane(data, width, height) {
+	const out = new Float64Array(width * height);
+	for (let i = 0, p = 0; i < out.length; i += 1, p += 4) {
+		const r = data[p];
+		const g = data[p + 1];
+		const b = data[p + 2];
+		const a = data[p + 3] / 255;
+		// Premultiply-ish against white for transparent pads
+		const rr = r * a + 255 * (1 - a);
+		const gg = g * a + 255 * (1 - a);
+		const bb = b * a + 255 * (1 - a);
+		out[i] = 0.2126 * rr + 0.7152 * gg + 0.0722 * bb;
+	}
+	return out;
+}
+
+/**
+ * Mean SSIM over 8×8 windows (simplified but stable for section screenshots).
+ * Returns 1 = identical, 0 = unrelated.
+ */
+export function computeSsim(dataA, dataB, width, height) {
+	const L = 255;
+	const c1 = (0.01 * L) ** 2;
+	const c2 = (0.03 * L) ** 2;
+	const a = luminancePlane(dataA, width, height);
+	const b = luminancePlane(dataB, width, height);
+	const win = 8;
+	let sum = 0;
+	let count = 0;
+
+	for (let y = 0; y + win <= height; y += win) {
+		for (let x = 0; x + win <= width; x += win) {
+			let n = 0;
+			let meanA = 0;
+			let meanB = 0;
+			for (let j = 0; j < win; j += 1) {
+				for (let i = 0; i < win; i += 1) {
+					const idx = (y + j) * width + (x + i);
+					meanA += a[idx];
+					meanB += b[idx];
+					n += 1;
+				}
+			}
+			meanA /= n;
+			meanB /= n;
+			let varA = 0;
+			let varB = 0;
+			let cov = 0;
+			for (let j = 0; j < win; j += 1) {
+				for (let i = 0; i < win; i += 1) {
+					const idx = (y + j) * width + (x + i);
+					const da = a[idx] - meanA;
+					const db = b[idx] - meanB;
+					varA += da * da;
+					varB += db * db;
+					cov += da * db;
+				}
+			}
+			varA /= n;
+			varB /= n;
+			cov /= n;
+			const num = (2 * meanA * meanB + c1) * (2 * cov + c2);
+			const den = (meanA * meanA + meanB * meanB + c1) * (varA + varB + c2);
+			sum += den > 0 ? num / den : 1;
+			count += 1;
+		}
+	}
+
+	if (!count) {
+		// Tiny images: fall back to global means
+		let meanA = 0;
+		let meanB = 0;
+		const n = a.length || 1;
+		for (let i = 0; i < a.length; i += 1) {
+			meanA += a[i];
+			meanB += b[i];
+		}
+		meanA /= n;
+		meanB /= n;
+		let varA = 0;
+		let varB = 0;
+		let cov = 0;
+		for (let i = 0; i < a.length; i += 1) {
+			const da = a[i] - meanA;
+			const db = b[i] - meanB;
+			varA += da * da;
+			varB += db * db;
+			cov += da * db;
+		}
+		varA /= n;
+		varB /= n;
+		cov /= n;
+		const num = (2 * meanA * meanB + c1) * (2 * cov + c2);
+		const den = (meanA * meanA + meanB * meanB + c1) * (varA + varB + c2);
+		return den > 0 ? num / den : 1;
+	}
+	return sum / count;
+}
+
+/**
+ * Normalize two PNG buffers and compare.
+ * @param {Buffer} protoBuf
+ * @param {Buffer} draftBuf
+ * @param {{ threshold?: number, includeDiff?: boolean, metric?: 'pixel'|'ssim'|'hybrid' }} [opts]
+ * @returns {{ score: number, pixelRatio: number, ssim: number, ssimDivergence: number, diffPixels: number, area: number, width: number, height: number, metric: string, band: string, diffPng?: Buffer }}
+ */
+export function compareSectionPngs(protoBuf, draftBuf, {
+	threshold = DEFAULT_AA_THRESHOLD,
+	includeDiff = false,
+	metric = 'hybrid'
+} = {}) {
+	const a = PNG.sync.read(protoBuf);
+	const b = PNG.sync.read(draftBuf);
+	const width = Math.max(a.width, b.width);
+	const height = Math.max(a.height, b.height);
+
+	const canvasA = new PNG({ width, height, fill: true });
+	const canvasB = new PNG({ width, height, fill: true });
+	for (let i = 0; i < canvasA.data.length; i += 4) {
+		canvasA.data[i] = 255;
+		canvasA.data[i + 1] = 255;
+		canvasA.data[i + 2] = 255;
+		canvasA.data[i + 3] = 255;
+		canvasB.data[i] = 255;
+		canvasB.data[i + 1] = 255;
+		canvasB.data[i + 2] = 255;
+		canvasB.data[i + 3] = 255;
+	}
+	PNG.bitblt(a, canvasA, 0, 0, a.width, a.height, 0, 0);
+	PNG.bitblt(b, canvasB, 0, 0, b.width, b.height, 0, 0);
+
+	const diff = new PNG({ width, height });
+	const diffPixels = pixelmatch(canvasA.data, canvasB.data, diff.data, width, height, {
+		threshold,
+		includeAA: true
+	});
+	const area = width * height;
+	const pixelRatio = area > 0 ? diffPixels / area : 0;
+	const ssim = computeSsim(canvasA.data, canvasB.data, width, height);
+	const ssimDivergence = Math.max(0, Math.min(1, 1 - ssim));
+
+	const m = String(metric || 'hybrid').toLowerCase();
+	let score;
+	if (m === 'ssim') {
+		score = ssimDivergence;
+	} else if (m === 'pixel') {
+		score = pixelRatio;
+	} else {
+		// hybrid: perceptual SSIM primary; pixel ratio floors obvious paint misses
+		score = Math.max(ssimDivergence, pixelRatio * 0.85);
+	}
+
+	const out = {
+		score,
+		pixelRatio,
+		ssim,
+		ssimDivergence,
+		diffPixels,
+		area,
+		width,
+		height,
+		metric: m === 'ssim' || m === 'pixel' ? m : 'hybrid',
+		band: scoreBand(score)
+	};
+	if (includeDiff) {
+		out.diffPng = PNG.sync.write(diff);
+	}
+	return out;
+}
+
+export function scoreBand(score) {
+	if (score < BANDS.clean) return 'clean';
+	if (score < BANDS.fix) return 'fix';
+	return 'rebuild';
+}
+
+export function sectionFailsGate(score, failThreshold = BANDS.clean) {
+	return score >= failThreshold;
+}

package/src/plan.mjs

@@ -0,0 +1,410 @@
+import { CHROME_ROLES } from './constants.mjs';
+
+const PROP_FAMILY = {
+	'padding-top': 'padding', 'padding-right': 'padding',
+	'padding-bottom': 'padding', 'padding-left': 'padding',
+	'margin-top': 'margin', 'margin-right': 'margin',
+	'margin-bottom': 'margin', 'margin-left': 'margin',
+	'font-size': 'type', 'line-height': 'type', 'letter-spacing': 'type',
+	'text-transform': 'type', 'font-style': 'type', 'font-weight': 'type',
+	'font-family': 'family',
+	color: 'colour', 'background-color': 'colour',
+	'border-top-color': 'border', 'border-bottom-color': 'border',
+	'border-left-color': 'border', 'border-right-color': 'border',
+	'border-top-width': 'border', 'border-bottom-width': 'border',
+	'border-left-width': 'border', 'border-right-width': 'border',
+	'border-radius': 'radius',
+	'box-shadow': 'shadow',
+	opacity: 'opacity',
+	gap: 'gap', 'row-gap': 'gap', 'column-gap': 'gap',
+	'grid-template-columns': 'columns',
+	'max-width': 'size', 'min-height': 'size',
+	display: 'layout', position: 'layout', 'flex-direction': 'layout', 'flex-wrap': 'layout',
+	'justify-content': 'align', 'align-items': 'align', 'text-align': 'align', 'vertical-align': 'align',
+	'transition-duration': 'motion', 'transition-property': 'motion', 'animation-name': 'motion',
+	'object-fit': 'media', 'object-position': 'media'
+};
+
+const FAMILY_LABEL = {
+	padding: 'padding', margin: 'margin', type: 'type scale', family: 'font family',
+	colour: 'colour', border: 'borders', radius: 'corner radius', shadow: 'shadow',
+	opacity: 'opacity', gap: 'gap', columns: 'column count', size: 'size limits',
+	layout: 'layout mode', align: 'alignment', motion: 'motion', media: 'image fit',
+	pixel: 'visual / pixel'
+};
+
+const FIX_HINT = {
+	family: 'Design preset → typography (base font). Set ONCE globally, never per element.',
+	type: 'If it affects headings site-wide, the design preset type scale. Otherwise the block’s Style → Typography.',
+	colour: 'If the pair recurs, map a design preset palette role. Otherwise block Style → Colour.',
+	border: 'Design preset border token if it recurs; otherwise block Style → Border.',
+	radius: 'Design preset radius token if global; otherwise block Style → Border radius.',
+	shadow: 'Design preset shadow token if global; otherwise block Style → Shadow.',
+	padding: 'Block Style → Spacing on the row / column / block. Not Custom CSS.',
+	margin: 'Block Style → Spacing (outer). Check for a doubled gap before adding margin.',
+	gap: 'The containing row’s gap setting — not a margin on each child.',
+	columns: 'The row’s column count / grid setting. Never emulate with widths.',
+	size: 'Row content width (full-bleed vs inset) or block Style → Dimensions.',
+	layout: 'The row/column layout setting (stack vs row, wrap). Not Custom CSS.',
+	align: 'Block Style → Alignment on the block or its column.',
+	motion: 'Block motion setting; minimal Custom CSS only if the platform cannot express it.',
+	opacity: 'Block Style → Colour / opacity.',
+	media: 'Image block fit / crop setting, or re-sideload a correctly cropped asset.',
+	pixel: 'Inspect section screenshots; fix via tokens → block settings → minimal Custom CSS. Re-measure with tt-fidelity.'
+};
+
+const FAMILY_RANK = [
+	'layout', 'columns', 'size', 'gap', 'padding', 'margin', 'align',
+	'family', 'type', 'border', 'radius', 'shadow', 'colour', 'opacity',
+	'motion', 'media', 'pixel'
+];
+
+const CHROME_FIX = 'Header/footer builder (GET/PUT /header, /footer) — not page content.';
+const MENU_FIX = 'Menu structure via POST/PUT /menus with real page IDs — add the item, do not style around it.';
+
+let roleOrder = [];
+
+export function setRoleOrder(roles) {
+	roleOrder = roles.map(([r]) => r);
+}
+
+const roleRank = (role) => {
+	const i = roleOrder.indexOf(role);
+	return i === -1 ? roleOrder.length : i;
+};
+
+function familyOf(prop) {
+	return PROP_FAMILY[prop] || 'layout';
+}
+
+function pxOf(v) {
+	const m = /^(-?[\d.]+)px$/.exec(String(v ?? '').trim());
+	return m ? parseFloat(m[1]) : null;
+}
+
+function describeTracks(value) {
+	const tracks = String(value || '').trim().split(/\s+/).filter(Boolean);
+	if (!tracks.length) return String(value || '');
+	const px = tracks.map((t) => pxOf(t)).filter((n) => n !== null);
+	const uniform = px.length === tracks.length && px.every((n) => Math.abs(n - px[0]) < 1);
+	const detail = uniform ? `${Math.round(px[0])}px each` : tracks.join(' ');
+	return `${tracks.length} column${tracks.length === 1 ? '' : 's'} (${detail})`;
+}
+
+function describeRow(row) {
+	if (row.prop === 'grid-template-columns') {
+		return `column count: ${describeTracks(row.proto)} -> ${describeTracks(row.draft)}`;
+	}
+	return `${row.prop}: ${row.proto} -> ${row.draft}`;
+}
+
+function fixHintFor(family, role, kind) {
+	if (kind === 'structural') return role && role.startsWith('nav') ? MENU_FIX : 'Page layout — add the missing section via PUT /pages/{id}/layout.';
+	if (kind === 'pixel') {
+		return 'Visual divergence — inspect shots; tokens → block Style → minimal Custom CSS. Cite section score in the fidelity report.';
+	}
+	if (CHROME_ROLES.has(role) && family !== 'family') return CHROME_FIX;
+	return FIX_HINT[family] || 'Block Style first; minimal Custom CSS only as a last resort.';
+}
+
+/**
+ * Build ordered work plan from style diff + optional pixel section findings.
+ */
+export function buildPlan(d, { pixelSections = [] } = {}) {
+	const tasks = [];
+
+	const structuralByRole = new Map();
+	for (const s of d.structural || []) {
+		const role = s.role || 'structure';
+		if (!structuralByRole.has(role)) structuralByRole.set(role, []);
+		structuralByRole.get(role).push(s);
+	}
+	for (const [role, items] of structuralByRole) {
+		const unmatched = items.some((i) => i.kind === 'unmatched' || i.kind === 'extra');
+		tasks.push({
+			kind: 'structural',
+			title: unmatched
+				? `Confirm ${role} — matched on one page only`
+				: `Reconcile ${role} — count differs from the prototype`,
+			why: items.map((i) => i.text),
+			fixAt: unmatched
+				? `FIRST verify it is really absent (inspect the page). If it exists under different markup, add its selector via --roles and re-run — do not "fix" it. If genuinely absent: ${fixHintFor(null, role, 'structural')}`
+				: fixHintFor(null, role, 'structural'),
+			rows: [],
+			affects: items.length,
+			mayResolve: 0
+		});
+	}
+
+	// Pixel sections — severity-ranked, before global style (rebuild first).
+	const failing = (pixelSections || [])
+		.filter((s) => s.band && s.band !== 'clean')
+		.sort((a, b) => b.score - a.score);
+	for (const sec of failing) {
+		const idHint = sec.ttRowId
+			? `row ${sec.ttRowId}${sec.ttBlockIds?.length ? ` → blocks ${sec.ttBlockIds.join(', ')}` : ''}`
+			: `section ${sec.index}`;
+		tasks.push({
+			kind: 'pixel',
+			severity: sec.band === 'rebuild' ? 'P0' : 'P1',
+			title: `[${sec.band.toUpperCase()}] ${idHint}: ${(sec.score * 100).toFixed(1)}% pixels differ`,
+			why: [
+				`label: "${sec.label || ''}"`,
+				`proto: ${sec.protoSelector}`,
+				`draft: ${sec.draftSelector}`,
+				sec.shotPaths ? `shots: ${sec.shotPaths.proto} | ${sec.shotPaths.draft}` : 'shots: see --out shots/'
+			],
+			fixAt: fixHintFor('pixel', null, 'pixel'),
+			rows: [],
+			affects: 1,
+			mayResolve: 0,
+			ttRowId: sec.ttRowId || null,
+			ttBlockIds: sec.ttBlockIds || [],
+			score: sec.score,
+			band: sec.band
+		});
+	}
+
+	const globalByFamily = new Map();
+	for (const g of d.global || []) {
+		const fam = familyOf(g.prop);
+		if (!globalByFamily.has(fam)) globalByFamily.set(fam, []);
+		globalByFamily.get(fam).push(g);
+	}
+	for (const [fam, rows] of globalByFamily) {
+		const reach = rows.reduce((n, r) => Math.max(n, r.count), 0);
+		tasks.push({
+			kind: 'global',
+			family: fam,
+			title: `Set ${FAMILY_LABEL[fam] || fam} globally (affects up to ${reach} elements)`,
+			why: rows.map((r) => `${describeRow(r)} on ${r.count} elements`),
+			fixAt: fixHintFor(fam, null, 'global'),
+			rows,
+			affects: reach,
+			mayResolve: reach
+		});
+	}
+
+	const downstream = [];
+	const elementTasks = [];
+	for (const el of d.elements || []) {
+		let real = el.rows.filter((r) => !r.geometry);
+		const symptoms = el.rows.filter((r) => r.geometry);
+
+		const hasSize = real.some((r) => familyOf(r.prop) === 'size');
+		const ml = real.find((r) => r.prop === 'margin-left');
+		const mr = real.find((r) => r.prop === 'margin-right');
+		if (hasSize && ml && mr && ml.proto === mr.proto && ml.draft === mr.draft) {
+			real = real.filter((r) => r !== ml && r !== mr);
+		}
+		if (!real.length) {
+			if (symptoms.length) downstream.push({ key: el.key, label: el.label, symptoms });
+			continue;
+		}
+
+		const byFamily = new Map();
+		for (const row of real) {
+			const fam = familyOf(row.prop);
+			if (!byFamily.has(fam)) byFamily.set(fam, []);
+			byFamily.get(fam).push(row);
+		}
+		const ordered = [...byFamily.entries()].sort(
+			(a, b) => FAMILY_RANK.indexOf(a[0]) - FAMILY_RANK.indexOf(b[0])
+		);
+		let firstForElement = true;
+		for (const [fam, rows] of ordered) {
+			elementTasks.push({
+				kind: 'element',
+				family: fam,
+				role: el.role,
+				key: el.key,
+				label: el.label,
+				selector: el.draftSelector,
+				title: `${el.key}: correct the ${FAMILY_LABEL[fam] || fam}`,
+				why: rows.map(describeRow),
+				fixAt: fixHintFor(fam, el.role, 'element'),
+				rows,
+				evidence: firstForElement ? symptoms.map(describeRow) : [],
+				affects: 1,
+				mayResolve: 0
+			});
+			firstForElement = false;
+		}
+	}
+
+	elementTasks.sort((a, b) => roleRank(a.role) - roleRank(b.role) || a.key.localeCompare(b.key));
+	tasks.push(...elementTasks);
+
+	return { tasks, downstream };
+}
+
+export function renderPlan(plan, width) {
+	const out = [];
+	const { tasks, downstream } = plan;
+	if (!tasks.length) return out;
+
+	out.push('');
+	out.push('-'.repeat(64));
+	out.push(`WORK PLAN @ ${width}px — ${tasks.length} tasks, in this order`);
+	out.push('-'.repeat(64));
+	out.push('Do ONE task, re-measure, then continue. Order: structural → pixel (by severity)');
+	out.push('→ global styles → local styles. Pixel gate is authoritative for exit 0.');
+	out.push('');
+
+	tasks.forEach((t, i) => {
+		const tag = t.kind === 'structural' ? 'STRUCTURAL'
+			: t.kind === 'pixel' ? `PIXEL${t.severity ? ` ${t.severity}` : ''}`
+			: t.kind === 'global' ? 'GLOBAL' : 'LOCAL';
+		out.push(`TASK ${i + 1} [${tag}] ${t.title}`);
+		if (t.selector) out.push(`  element:  ${t.selector}${t.label ? `  ("${t.label}")` : ''}`);
+		if (t.ttRowId) out.push(`  tt ids:   ${t.ttRowId}${(t.ttBlockIds || []).length ? ` / ${t.ttBlockIds.join(', ')}` : ''}`);
+		out.push('  set:');
+		for (const w of t.why) out.push(`    - ${w}`);
+		out.push(`  fix at:   ${t.fixAt}`);
+		if (t.mayResolve > 1) {
+			out.push(`  note:     may clear up to ${t.mayResolve} element rows — re-measure before doing local work.`);
+		}
+		if (t.evidence && t.evidence.length) {
+			out.push(`  symptom:  ${t.evidence.join('; ')} (should follow automatically)`);
+		}
+		out.push('');
+	});
+
+	if (downstream.length) {
+		out.push('DO NOT TOUCH — downstream only (geometry differs, but no property of');
+		out.push('their own is wrong; these follow from the tasks above):');
+		for (const dsn of downstream) {
+			out.push(`  - ${dsn.key}: ${dsn.symptoms.map((s) => s.prop).join(', ')}`);
+		}
+		out.push('');
+	}
+
+	return out;
+}
+
+export function renderStyleEvidence(results, tol, plansOnly) {
+	const out = [];
+	out.push('STYLE EXPLAINER — computed styles (does NOT alone certify exit 0 in --mode full|pixel)');
+	out.push('Read as:  property  PROTOTYPE(target)  ->  DRAFT(current)');
+	out.push(`Tolerance: +/-${tol}px on lengths.`);
+	out.push('');
+
+	for (const r of results) {
+		const { width, diff: d } = r;
+		if (!d) continue;
+		out.push(`${'='.repeat(64)}`);
+		out.push(`VIEWPORT ${width}px — ${d.total} style findings${d.global?.length ? ` (${d.global.length} global)` : ''}`);
+		out.push(`${'='.repeat(64)}`);
+		if (r.coverage) {
+			const { renderCoverage } = awaitImportCoverage();
+			out.push(...renderCoverage(r.coverage));
+		}
+		out.push(...renderPlan(buildPlan(d, { pixelSections: r.pixelSections || [] }), width));
+		if (plansOnly) continue;
+
+		if (d.structural?.length) {
+			out.push('');
+			out.push('STRUCTURAL:');
+			for (const s of d.structural) out.push(`  - ${s.text}`);
+		}
+		if (d.global?.length) {
+			out.push('');
+			out.push('GLOBAL / INHERITED:');
+			for (const g of d.global) {
+				out.push(`  ${g.prop}  ${g.proto}  ->  ${g.draft}  (×${g.count})`);
+			}
+		}
+		for (const el of d.elements || []) {
+			out.push('');
+			out.push(`[${el.key}]${el.label ? ` "${el.label}"` : ''}`);
+			for (const row of el.rows) {
+				out.push(`  ${row.prop}  ${row.proto}  ->  ${row.draft}${row.geometry ? '   (symptom)' : ''}`);
+			}
+		}
+		out.push('');
+	}
+	return out.join('\n');
+}
+
+function awaitImportCoverage() {
+	// sync helper — coverage lines inlined to avoid circular import issues at render time
+	return {
+		renderCoverage(cov) {
+			const pct = Math.round(cov.ratio * 100);
+			const lines = [
+				`COVERAGE: ${cov.matched.length}/${cov.matched.length + cov.onlyProto.length + cov.onlyDraft.length} roles matched on both pages (${pct}%).`
+			];
+			if (cov.onlyProto.length) lines.push(`  matched on the prototype only: ${cov.onlyProto.join(', ')}`);
+			if (cov.onlyDraft.length) lines.push(`  matched on the draft only:     ${cov.onlyDraft.join(', ')}`);
+			return lines;
+		}
+	};
+}
+
+/**
+ * Human report for pixel-first runs.
+ */
+export function renderPixelReport(pages, { mode }) {
+	const lines = [];
+	lines.push('PIXEL GATE — AUTHORITATIVE (section screenshots)');
+	lines.push(`Mode: ${mode}. Exit 0 only when every compared section is < clean threshold.`);
+	lines.push('"Matched" means measured. Do not self-certify parity.');
+	lines.push('');
+
+	for (const page of pages) {
+		lines.push(`${'='.repeat(64)}`);
+		lines.push(`PAGE ${page.id || page.proto} @ viewports ${page.viewports.map((v) => v.width).join(',')}`);
+		lines.push(`${'='.repeat(64)}`);
+		for (const vp of page.viewports) {
+			const secs = vp.sections || [];
+			const failing = secs.filter((s) => s.band !== 'clean');
+			lines.push(`@ ${vp.width}px — ${secs.length} sections, ${failing.length} failing`);
+			if (vp.cacheHeaders && Object.keys(vp.cacheHeaders).length) {
+				lines.push(`  cache headers (draft): ${JSON.stringify(vp.cacheHeaders)}`);
+			}
+			for (const s of secs) {
+				const pct = (s.score * 100).toFixed(1);
+				const mark = s.band === 'clean' ? 'OK' : s.band.toUpperCase();
+				const id = s.ttRowId || `section:${s.index}`;
+				lines.push(`  [${mark} ${pct}%] ${id} — "${s.label || ''}"`);
+			}
+			lines.push(...renderPlan(buildPlan(vp.styleDiff || { structural: [], global: [], elements: [], total: 0 }, { pixelSections: secs }), vp.width));
+		}
+		lines.push('');
+	}
+	return lines.join('\n');
+}
+
+export function renderQueueMd(clusters, pages) {
+	const lines = [];
+	lines.push('# Fidelity QUEUE');
+	lines.push('');
+	lines.push('Ranked by leverage. Do one task, re-measure, continue.');
+	lines.push('');
+	if (clusters?.length) {
+		lines.push('## Cross-page clusters (fix these first)');
+		lines.push('');
+		clusters.forEach((c, i) => {
+			lines.push(`${i + 1}. **${c.label || c.key}** — ${c.pages} pages, avg ${(c.avgScore * 100).toFixed(1)}% divergent`);
+			if (c.instancesPerPage != null) {
+				lines.push(`   - instances/page: ${c.instancesPerPage.toFixed(2)} (≪1 ≈ page-specific; ≫1 ≈ safe default)`);
+			}
+		});
+		lines.push('');
+	}
+	lines.push('## Per-page summary');
+	lines.push('');
+	for (const page of pages) {
+		let fail = 0;
+		let total = 0;
+		for (const vp of page.viewports) {
+			for (const s of vp.sections || []) {
+				total += 1;
+				if (s.band !== 'clean') fail += 1;
+			}
+		}
+		lines.push(`- \`${page.id}\`: ${fail}/${total} sections failing`);
+	}
+	lines.push('');
+	return lines.join('\n');
+}

package/src/rank.mjs

@@ -0,0 +1,52 @@
+/**
+ * Cross-page clustering by section heading / component label.
+ */
+
+export function clusterSections(pages) {
+	const map = new Map();
+	for (const page of pages) {
+		const seenOnPage = new Set();
+		for (const vp of page.viewports || []) {
+			for (const sec of vp.sections || []) {
+				if (!sec.band || sec.band === 'clean') continue;
+				const key = normalizeLabel(sec.label) || sec.ttRowId || `idx:${sec.index}`;
+				if (!map.has(key)) {
+					map.set(key, {
+						key,
+						label: sec.label || key,
+						scores: [],
+						pageIds: new Set(),
+						instances: 0
+					});
+				}
+				const c = map.get(key);
+				c.scores.push(sec.score);
+				c.pageIds.add(page.id);
+				c.instances += 1;
+				seenOnPage.add(key);
+			}
+		}
+	}
+
+	const pageCount = Math.max(1, pages.length);
+	const clusters = [...map.values()]
+		.map((c) => ({
+			key: c.key,
+			label: c.label,
+			pages: c.pageIds.size,
+			avgScore: c.scores.reduce((a, b) => a + b, 0) / c.scores.length,
+			instances: c.instances,
+			instancesPerPage: c.instances / pageCount
+		}))
+		.sort((a, b) => b.pages - a.pages || b.avgScore - a.avgScore);
+
+	return clusters;
+}
+
+function normalizeLabel(label) {
+	return String(label || '')
+		.toLowerCase()
+		.replace(/\s+/g, ' ')
+		.trim()
+		.slice(0, 60);
+}