Redesign an existing website to make it better. Built on top of impeccable.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
#!/usr/bin/env node
/* eslint-disable import/no-extraneous-dependencies, import/extensions, no-restricted-syntax, brace-style, object-curly-newline, max-len, no-console, no-continue, no-nested-ternary, no-plusplus */
/**
* skills/diff/scripts/chrome-compare.mjs — the header-parity gate: a build's chrome-explore record
* against the source's (the header contract). Controls pair by name, then by family (search, cart,
* account, locale, drawer); every state the source opens must open the same way on the build, with
* its links and headings, its keyboard behaviour (Enter opens, Escape closes and returns focus, Tab
* reaches the panel, aria-expanded follows) and its close paths. Profile `replica` (keep-design flow)
* also gates the open-state crops (pixelmatch 0.1, --bar), motion (property set; duration within
* max(80 ms, 25 %)) and the header's scroll states; `functional` (redesign, reskin) checks behaviour
* and content only. Build evidence not observed because its request budget stopped the record warns
* instead of failing parity; observed failures remain errors.
*
* A finding clears only by a fix or by a site-owner decision in --decisions
* ({ decisions: [{ finding: "<key or prefix*>", decision, reason, by, at }] }); entries without
* `by`/`at`, or signed by an agent, are ignored and reported.
*
* Usage: node skills/diff/scripts/chrome-compare.mjs <source.json> <build.json> [options]
* --profile replica|functional default replica
* --bar <ratio> open-state crop bar (default 0.02)
* --decisions <file> default stardust/chrome/header-decisions.json
* --json <file> write the verdict (stardust/chrome/header-parity.json is what done-check reads)
* --src-shots <dir> / --build-shots <dir> crop folders when not where the records say
* Exit: 0 no undecided error · 2 errors · 1 usage. `compareDocs`, `applyDecisions`, `findingKey` are exported.
*/
import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import { dirname, join } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { normName } from './chrome-explore.mjs';
// The shared rules (contracts.mjs) live beside browser.mjs in the master skill's scripts dir: the plugin tree or the Setup step 7 copy.
const CONTRACTS = ['../../stardust/scripts/contracts.mjs', '../stardust/contracts.mjs']
.map((p) => new URL(p, import.meta.url)).find((u) => existsSync(u));
// Missing, --help still answers; the first comparison stops with the copy instruction.
const missing = () => { throw new Error('contracts.mjs not found (looked in ../../stardust/scripts/ and ../stardust/). Copy the master skill\'s scripts dir to stardust/scripts/stardust/ (skills/stardust/SKILL.md § Setup).'); };
// a header link's identity: decoded lower-case pathname, extension/index/slash folded, query kept (lib/paths.mjs)
const { chromeHrefKey: hrefKey } = CONTRACTS ? await import(CONTRACTS.href) : { chromeHrefKey: missing };
const TOUCH_BELOW = 768;
const FAMILIES = new Set(['search', 'cart', 'account', 'locale', 'drawer']);
const AGENT = /^(agent|assistant|stardust|claude|codex|bot|auto)/i;
const REQUEST_BUDGET_SUFFIX = ' — not observed: the build record stopped at the request budget (run the build side with --max-requests 0)';
const absentEvidence = (incomplete, detail, severity = 'error') => ({ severity: incomplete ? 'warn' : severity, detail: `${detail}${incomplete ? REQUEST_BUDGET_SUFFIX : ''}` });
/** The decision key of a finding: `<id>@<width> <path>[ [action]]`. Pure. */
export const findingKey = (f) => `${f.id}@${f.width} ${f.path}${f.action ? ` [${f.action}]` : ''}`;
const openOf = (c) => ['click', 'hover', 'key'].find((a) => c.actions && c.actions[a] && c.actions[a].opened);
/** Pair two control lists: by name, then by family in order. Pure. */
export function pairControls(src, bld) {
const used = new Set(); const pairs = [];
for (const s of src) {
let b = s.key ? bld.find((x) => !used.has(x) && x.key === s.key) : null;
if (!b && FAMILIES.has(s.kind)) b = bld.find((x) => !used.has(x) && x.kind === s.kind);
if (b) used.add(b);
pairs.push([s, b || null]);
}
return pairs;
}
const searchControls = (cs, out = []) => { for (const c of cs || []) { if (c.role === 'input' && c.kind === 'search') out.push(c); searchControls(c.children, out); } return out; };
function compareState(ss, bs, base, { profile, add, visual }, full) {
// content, motion and crops once per control (the first action both sides open on); keyboard facts per action
if (ss.tabReachesPanel && bs.tabReachesPanel === false) add({ ...base, id: 'keyboard', severity: 'error', detail: 'Tab moves into the panel on the source, not on the build' });
if (!full) return;
const bl = new Map(bs.panel.links.map((l) => [normName(l.text) || hrefKey(l.href), l]));
const missing = []; const moved = [];
for (const l of ss.panel.links) {
const k = normName(l.text) || hrefKey(l.href); const m = bl.get(k);
if (!m) missing.push(l.text || l.href); else if (hrefKey(m.href) !== hrefKey(l.href)) moved.push(`${l.text}: ${hrefKey(l.href)} → ${hrefKey(m.href)}`);
}
const bh = new Set(bs.panel.headings.map(normName));
const hMissing = ss.panel.headings.filter((h) => !bh.has(normName(h)));
const iMissing = ss.panel.inputs.length && !bs.panel.inputs.length;
if (missing.length || hMissing.length || iMissing) {
add({ ...base, id: 'panel-content', severity: 'error', detail: [missing.length && `${missing.length} of ${ss.panel.links.length} links missing (${missing.slice(0, 6).join(', ')}${missing.length > 6 ? ', …' : ''})`, hMissing.length && `headings missing: ${hMissing.slice(0, 4).join(', ')}`, iMissing && 'the source panel has an input, the build none'].filter(Boolean).join('; ') });
}
if (moved.length) add({ ...base, id: 'link-href', severity: 'warn', detail: `${moved.length} link(s) point elsewhere: ${moved.slice(0, 4).join('; ')}` });
if (ss.panel.images && !bs.panel.images) add({ ...base, id: 'panel-content', severity: 'warn', detail: `the source panel shows ${ss.panel.images} image(s), the build none` });
if (ss.expanded === 'true' && bs.expanded !== 'true') add({ ...base, id: 'keyboard', severity: 'error', detail: 'aria-expanded is "true" on the source trigger when open; the build does not set it' });
if (ss.scrollLock && !bs.scrollLock) add({ ...base, id: 'scroll-lock', severity: 'error', detail: 'the source locks page scroll while open; the build does not' });
if (profile !== 'replica') return;
// per property, every duration that ran (two elements may animate the same property at different speeds)
const mv = (s) => { const m = new Map(); for (const x of (s.motion || []).filter((y) => y.ms > 0 && y.prop !== 'visibility')) m.set(x.prop, [...(m.get(x.prop) || []), x.ms]); return m; };
const sm = mv(ss); const bm = mv(bs);
const list = (m) => [...m].map(([p, ms]) => `${p} ${[...new Set(ms)].join('/')}ms`).join(', ');
if (sm.size && !bm.size) add({ ...base, id: 'motion', severity: 'error', detail: `the source animates ${list(sm)}; the build opens without motion` });
else if (!sm.size && bm.size) add({ ...base, id: 'motion', severity: 'warn', detail: `the build animates ${[...bm.keys()].join(', ')}; the source does not` });
else {
for (const [p, ms] of sm) {
const b = bm.get(p);
if (!b) { add({ ...base, id: 'motion', severity: 'warn', detail: `the source animates ${p}; the build does not` }); continue; }
const off = [...new Set(ms)].filter((m) => !b.some((x) => Math.abs(x - m) <= Math.max(80, 0.25 * m)));
if (off.length) add({ ...base, id: 'motion', severity: 'error', detail: `${p}: ${off.join('/')}ms on the source, ${[...new Set(b)].join('/')}ms on the build` });
}
}
if (ss.shot) visual.push({ ...base, src: ss.shot, build: bs.shot || null });
}
function walk(src, bld, ctx, path) {
const { width, add, budgetIncomplete = false } = ctx;
const touch = width < TOUCH_BELOW;
for (const [s, b] of pairControls(src.filter((c) => c.role !== 'input'), bld.filter((c) => c.role !== 'input'))) {
const p = path ? `${path} > ${s.name || s.kind}` : (s.name || s.kind);
const base = { width, path: p };
const sOpen = openOf(s);
if (!b) {
if (sOpen) add({ ...base, id: 'control-missing', ...absentEvidence(budgetIncomplete, `the source ${s.kind} control opens on ${sOpen}; the build has no control named "${s.name}"${FAMILIES.has(s.kind) ? ` or of family ${s.kind}` : ''}`) });
else if (!path && s.role === 'link') add({ ...base, id: 'link-missing', ...absentEvidence(budgetIncomplete, `top-level link ${s.href ? hrefKey(s.href) : ''} not in the build header`, 'warn') });
continue;
}
const incomplete = budgetIncomplete || b.partial === 'request-budget';
let full = true;
for (const a of touch ? ['click', 'key'] : ['hover', 'click', 'key']) {
const ss = s.actions && s.actions[a]; const observed = Object.hasOwn(b.actions || {}, a); const bs = b.actions && b.actions[a];
const so = !!(ss && ss.opened); const bo = !!(bs && bs.opened);
if (so && !bo) add({ ...base, action: a, id: a === 'key' ? 'keyboard' : 'state-missing', ...absentEvidence(incomplete && !observed, `opens on ${a === 'key' ? 'Enter' : a} on the source (${ss.panel.links.length} links); ${bs && bs.navigates ? `navigates to ${hrefKey(bs.navigates)} on the build` : b.role === 'link' ? `the build control is a plain link${b.href ? ` to ${hrefKey(b.href)}` : ''}` : 'nothing opens on the build'}`) });
else if (!so && bo && !(ss && ss.navigates)) add({ ...base, action: a, id: 'state-extra', severity: 'warn', detail: `opens on ${a} on the build only` });
else if (so && bo) { compareState(ss, bs, { ...base, action: a }, ctx, full); full = false; }
}
if (sOpen && openOf(b) && s.close) {
for (const k of ['escape', 'outside', 'toggle', 'leave']) {
if (s.close[k] === true && !(b.close && b.close[k] === true)) add({ ...base, id: 'close-path', ...absentEvidence(incomplete && !Object.hasOwn(b.close || {}, k), `${k === 'escape' ? 'Escape' : k === 'outside' ? 'a click outside' : k === 'toggle' ? 'clicking the trigger again' : 'moving the pointer away'} closes it on the source, not on the build`) });
}
if (s.close.focusReturn && !(b.close && b.close.focusReturn)) add({ ...base, id: 'keyboard', ...absentEvidence(incomplete && !Object.hasOwn(b.close || {}, 'focusReturn'), 'Escape returns focus to the trigger on the source, not on the build') });
}
if (sOpen && openOf(b) && !s.returns) walk(s.children || [], b.children || [], { ...ctx, budgetIncomplete: incomplete }, p);
}
}
/** All findings except the crop pixels (returned as `visual` pairs for the image pass). Pure. */
export function compareDocs(src, bld, { profile = 'replica' } = {}) {
const findings = []; const visual = [];
const add = (f) => findings.push(f);
for (const [w, sw] of Object.entries(src.widths || {})) {
const width = Number(w);
const bw = (bld.widths || {})[w];
if (!bw) { add({ width, path: '(page)', id: 'width-missing', severity: 'error', detail: `the build was not explored at ${w}` }); continue; }
const budgetIncomplete = bw.truncated === 'request-budget';
const addBuildTruncation = () => { if (bw.truncated) add({ width, path: '(build)', id: 'budget-truncated', severity: 'warn', detail: `the build record stopped at ${bw.truncated}${budgetIncomplete ? ': run the build side with --max-requests 0' : ''}` }); };
if (!bw.root && sw.root) { add({ width, path: '(page)', id: 'control-missing', ...absentEvidence(budgetIncomplete, 'no header root on the build') }); addBuildTruncation(); continue; }
walk(sw.controls || [], bw.controls || [], { width, add, profile, visual, budgetIncomplete }, '');
const ssr = searchControls(sw.controls); const bsr = searchControls(bw.controls);
if (ssr.length && !bsr.length) add({ width, path: 'search', id: 'control-missing', ...absentEvidence(budgetIncomplete, 'the source header has a search input; the build none') });
else if (ssr.length) {
const s = ssr[0].search; const buildInput = bsr[0]; const b = buildInput.search;
if (s) {
const capped = b === null && buildInput.skipped === 'typeahead-cap';
const capSuffix = capped ? ' — not observed: the build input was skipped past --max-typeahead' : '';
if ((s.typeahead.links || s.typeahead.options) && !(b && b.typeahead && (b.typeahead.links || b.typeahead.options))) {
const unobserved = budgetIncomplete && !b;
add({ width, path: 'search', id: 'state-missing', action: 'type', severity: unobserved || capped ? 'warn' : 'error', detail: `typing "${s.probe}" shows ${s.typeahead.links || s.typeahead.options} suggestion(s) on the source, none on the build${unobserved ? REQUEST_BUDGET_SUFFIX : capSuffix}` });
}
if (s.submit && !(b && b.submit)) {
const unobserved = budgetIncomplete && !b;
add({ width, path: 'search', id: 'state-missing', action: 'submit', severity: unobserved || capped ? 'warn' : 'error', detail: `Enter submits to ${hrefKey(s.submit)} on the source; nothing on the build${unobserved ? REQUEST_BUDGET_SUFFIX : capSuffix}` });
}
else if (s.submit && b.submit && hrefKey(s.submit).split('?')[0] !== hrefKey(b.submit).split('?')[0]) add({ width, path: 'search', id: 'link-href', action: 'submit', severity: 'warn', detail: `submits to ${hrefKey(s.submit)} on the source, ${hrefKey(b.submit)} on the build` });
}
}
const sev = profile === 'replica' ? 'error' : 'warn';
for (const s of sw.scroll || []) {
const b = (bw.scroll || []).find((x) => x.at === s.at);
if (!b) { if ((bw.scroll || []).length) add({ width, path: '(header)', id: 'scroll-state', ...absentEvidence(budgetIncomplete, `no ${s.at} sample on the build`, sev) }); continue; }
const pin = (x) => (x.position === 'fixed' || x.position === 'sticky' ? 'pinned' : 'static');
if (s.inView !== b.inView || pin(s) !== pin(b)) add({ width, path: '(header)', action: s.at, id: 'scroll-state', severity: sev, detail: `scrolled ${s.at}: the source header is ${pin(s)} and ${s.inView ? 'in view' : 'out of view'}, the build's ${pin(b)} and ${b.inView ? 'in view' : 'out of view'}` });
else if (Math.abs(s.height - b.height) > Math.max(8, 0.1 * s.height)) add({ width, path: '(header)', action: s.at, id: 'scroll-state', severity: sev, detail: `scrolled ${s.at}: header ${s.height}px on the source, ${b.height}px on the build` });
}
if (sw.truncated) add({ width, path: '(source)', id: 'budget-truncated', severity: 'warn', detail: `the source record stopped at ${sw.truncated}: raise --max-states/--max-depth for full coverage` });
addBuildTruncation();
}
return { findings, visual: profile === 'replica' ? visual : [] };
}
/** Mark findings cleared by a valid site-owner decision; invalid entries become warnings. Pure. */
export function applyDecisions(findings, decisions = []) {
const valid = []; const out = [...findings];
for (const d of decisions) {
if (!d || !d.finding || !d.by || !d.at || AGENT.test(String(d.by))) { out.push({ width: 0, path: '(decisions)', id: 'decision-invalid', severity: 'warn', detail: `ignored: ${d && d.finding ? d.finding : '(no finding)'} — a decision needs the site owner's \`by\` and \`at\`` }); continue; }
valid.push(d);
}
for (const f of out) {
const k = findingKey(f);
const d = valid.find((x) => (x.finding.endsWith('*') ? k.startsWith(x.finding.slice(0, -1)) : k === x.finding));
if (d && f.severity === 'error') f.decided = { decision: d.decision || 'accepted', by: d.by, at: d.at, reason: d.reason || '' };
}
return out;
}
const loadDep = async (name) => {
try { const req = createRequire(join(process.cwd(), 'package.json')); const m = await import(pathToFileURL(req.resolve(name)).href); return m.default || m; } catch { /* fall through */ }
const m = await import(name); return m.default || m;
};
/** Crop pairs → ratio of differing pixels over the union box (size differences count as different). */
export async function visualFindings(pairs, { srcDir, buildDir, bar }) {
if (!pairs.length) return [];
let PNG; let pixelmatch;
try { ({ PNG } = await loadDep('pngjs')); pixelmatch = await loadDep('pixelmatch'); } catch { return pairs.map((p) => ({ ...p, id: 'panel-visual', severity: 'error', detail: 'crops not compared: pngjs + pixelmatch are not installed in this project' })); }
const out = [];
for (const p of pairs) {
const fa = join(srcDir, p.src); const fb = p.build && join(buildDir, p.build);
if (!existsSync(fa)) { out.push({ ...p, id: 'panel-visual', severity: 'error', detail: `source crop ${fa} missing: re-run chrome-explore on the source` }); continue; }
if (!fb || !existsSync(fb)) { out.push({ ...p, id: 'panel-visual', severity: 'error', detail: 'the build state has no crop' }); continue; }
const a = PNG.sync.read(readFileSync(fa)); const b = PNG.sync.read(readFileSync(fb));
const w = Math.min(a.width, b.width); const h = Math.min(a.height, b.height);
const crop = (img) => { const o = new PNG({ width: w, height: h }); PNG.bitblt(img, o, 0, 0, w, h, 0, 0); return o.data; };
const mask = Buffer.alloc(w * h * 4);
const diff = pixelmatch(crop(a), crop(b), mask, w, h, { threshold: 0.1 });
const union = Math.max(a.width, b.width) * Math.max(a.height, b.height);
const ratio = (diff + (union - w * h)) / union;
// crop-compare's texture: a differing pixel with ≥5 differing neighbours is thick (paint, misalignment); glyph antialiasing is thin
const on = (x, y) => x >= 0 && y >= 0 && x < w && y < h && mask[(y * w + x) * 4] === 255 && mask[(y * w + x) * 4 + 1] === 0;
let thick = 0;
for (let y = 0; y < h; y += 1) for (let x = 0; x < w; x += 1) if (on(x, y)) { let k = 0; for (let dy = -1; dy <= 1; dy += 1) for (let dx = -1; dx <= 1; dx += 1) if ((dx || dy) && on(x + dx, y + dy)) k += 1; if (k >= 5) thick += 1; }
const thickPct = diff ? Math.round((thick / diff) * 100) : 0;
if (ratio > bar) out.push({ ...p, id: 'panel-visual', severity: 'error', detail: `open-state crop differs by ${(ratio * 100).toFixed(1)}% (bar ${(bar * 100).toFixed(0)}%; source ${a.width}×${a.height}, build ${b.width}×${b.height}; texture ${thickPct}% thick${thickPct <= 15 && a.width === b.width && a.height === b.height ? ', thin-edge: glyph antialiasing, a font substitution the site owner can accept' : ''})` });
}
return out.map(({ src, build, ...f }) => f);
}
async function main() {
const argv = process.argv.slice(2);
if (argv.includes('--help') || argv.includes('-h')) { console.log(readFileSync(fileURLToPath(import.meta.url), 'utf8').match(/\/\*\*([\s\S]*?)\*\//)[1].replace(/^ \* ?/gm, '').trim()); process.exit(0); }
const arg = (k, d) => { const i = argv.indexOf(`--${k}`); return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : d; };
const [sf, bf] = argv.filter((a, i) => !a.startsWith('--') && !(i > 0 && argv[i - 1].startsWith('--')));
if (!sf || !bf || !existsSync(sf) || !existsSync(bf)) { console.error('usage: chrome-compare.mjs <source.json> <build.json> [--profile replica|functional] [--bar 0.02] [--decisions f] [--json f]'); process.exit(1); }
const src = JSON.parse(readFileSync(sf, 'utf8')); const bld = JSON.parse(readFileSync(bf, 'utf8'));
const profile = arg('profile', 'replica'); const bar = Number(arg('bar', 0.02));
const { findings, visual } = compareDocs(src, bld, { profile });
findings.push(...await visualFindings(visual, { srcDir: arg('src-shots', src.shots || '.'), buildDir: arg('build-shots', bld.shots || '.'), bar }));
const df = arg('decisions', join('stardust', 'chrome', 'header-decisions.json'));
const all = applyDecisions(findings, existsSync(df) ? (JSON.parse(readFileSync(df, 'utf8')).decisions || []) : []);
const errors = all.filter((f) => f.severity === 'error' && !f.decided); const warns = all.filter((f) => f.severity === 'warn'); const decided = all.filter((f) => f.decided);
for (const f of [...errors, ...warns]) console.log(`${f.severity === 'error' ? '🔴' : '🟡'} ${findingKey(f)} — ${f.detail}`);
const widths = Object.keys(src.widths || {}).map(Number);
const verdict = { tool: 'chrome-compare', at: new Date().toISOString(), source: src.url, build: bld.url, profile, bar, widths, counts: { error: errors.length, warn: warns.length, decided: decided.length }, findings: all.map((f) => ({ key: findingKey(f), ...f })) };
const out = arg('json', null);
if (out) { mkdirSync(dirname(out), { recursive: true }); writeFileSync(out, `${JSON.stringify(verdict, null, 1)}\n`); }
console.log(`chrome-compare: ${errors.length} error(s), ${warns.length} warning(s), ${decided.length} decided (profile ${profile}, widths ${widths.join(',')})${out ? ` → ${out}` : ''}`);
process.exit(errors.length ? 2 : 0);
}
const self = (() => { try { return realpathSync(fileURLToPath(import.meta.url)); } catch { return ''; } })();
if (process.argv[1] && (() => { try { return realpathSync(process.argv[1]) === self; } catch { return false; } })()) main().catch((e) => { console.error(`chrome-compare: ${e.message}`); process.exit(1); });.tessl-plugin
skills
audit
reference
deploy
reference
scripts
test
diff
direct
dynamics
extract
migrate
prepare-migration
prototype
assets
motion
fixtures
reference
qa
replica
reference
scripts
test
reskin
rollout
spec
stardust
uplift
reference