The design language that makes your AI harness better at design.
JavaScript
Add comp-diff, comp-spec, and build-phase: measured comp fidelity for the build phase
Paul Bakausb0fc2e8801eb
diff --git a/scripts/test-suites.mjs b/scripts/test-suites.mjsindex 1c1f64c58..52f3b1c2e 100644--- a/scripts/test-suites.mjs+++ b/scripts/test-suites.mjs@@ -26,7 +26,7 @@ export const SUITES = {triggers: [...COMMON_INFRA_PATTERNS,/^scripts\/(?!benchmark-detector|build-browser-detector|build-extension)/,- /^skill\/(SKILL\.src\.md|agents\/|reference\/|scripts\/(cleanup-deprecated|concept-seed|context|context-signals|critique-storage|design-parser|doctor|hook|impeccable-paths|is-generated|lib\/(artifact-schema|composition-catalog|concept-catalog|provider|staleness|staleness-deep|staleness-notice|surface-briefs|target-slug|template-extensions)|pin|surface-brief))/,+ /^skill\/(SKILL\.src\.md|agents\/|reference\/|scripts\/(cleanup-deprecated|comp-diff|comp-spec|build-phase|concept-seed|context|context-signals|critique-storage|design-parser|doctor|hook|impeccable-paths|is-generated|lib\/(artifact-schema|png|raster|image-metrics|composition-catalog|concept-catalog|provider|staleness|staleness-deep|staleness-notice|surface-briefs|target-slug|template-extensions)|pin|surface-brief))/,/^README(\.npm)?\.md$/,/^cli\/bin\//,],@@ -54,6 +54,8 @@ export const SUITES = {'tests/ci-test-plan.test.mjs','tests/cli-args.test.mjs','tests/concept-seed.test.mjs',+ 'tests/comp-diff.test.mjs',+ 'tests/build-phase.test.mjs','tests/serve-question.test.mjs','tests/context.test.mjs','tests/context-signals.test.mjs',diff --git a/skill/scripts/build-phase.mjs b/skill/scripts/build-phase.mjsnew file mode 100644index 000000000..8344047bc--- /dev/null+++ b/skill/scripts/build-phase.mjs@@ -0,0 +1,295 @@+#!/usr/bin/env node+/**+ * build-phase: the comp-led build as a state machine on disk, so the phases+ * new-work.md names are gated by scripts instead of remembered by the model.+ *+ * State lives at .impeccable/build/state.json. Phases, in order:+ *+ * spec the approved comp is measured (comp-spec.mjs wrote spec.json)+ * plates every raster region in the spec has its plate on disk+ * hero the first viewport is reproduced: comp-diff of hero-repro.png+ * against the comp clears the gate+ * sections the rest of the surface is built inside the spec's system+ * motion interaction, reveals, motion+ * responsive the other viewports+ * review the finish reviewer ran; disposition recorded+ *+ * node build-phase.mjs start --comp <approved.png> [--breakpoint 1440x900]+ * node build-phase.mjs status # human-readable, plus NEXT line+ * node build-phase.mjs status --json+ * node build-phase.mjs advance # try to close the current phase; runs its gate+ * node build-phase.mjs advance --force --reason "<why>" # skip a gate; recorded, never silent+ * node build-phase.mjs record hero --build .impeccable/review/hero-repro.png # run the hero gate explicitly+ * node build-phase.mjs note "<text>" # append a note to the current phase+ * node build-phase.mjs finish --disposition ship|fix|rebuild|recapture+ *+ * Gates:+ * spec -> spec.json exists and has >= 1 region+ * plates -> every region with medium raster has its plate file, decodable,+ * at least 2x the comp region's pixel size in width, and the+ * plate scores >= PLATE_MIN against the comp crop (comp-diff,+ * detail-weighted). A missing or thin plate names itself.+ * hero -> .impeccable/review/hero-repro.png exists and comp-diff overall+ * >= HERO_MIN (default 0.72) with no region `missing`. The+ * score, the report path, and the attempt count are recorded.+ * sections / motion / responsive -> no mechanical gate; advancing records+ * the moment, and the finish reviewer reads the timeline.+ *+ * Exit codes: 0 ok / advanced, 2 gate failed (state unchanged, reasons+ * printed), 1 usage.+ *+ * Nothing here needs a browser. Screenshots come from the harness; this+ * script only measures them.+ */+import fs from 'node:fs';+import path from 'node:path';+import { spawnSync } from 'node:child_process';+import { fileURLToPath } from 'node:url';+import { decodePng } from './lib/png.mjs';+import { crop } from './lib/raster.mjs';+import { compare, verdictFor } from './comp-diff.mjs';+import { SPEC_PATH, BUILD_DIR, loadSpec } from './comp-spec.mjs';++const HERE = path.dirname(fileURLToPath(import.meta.url));+export const STATE_PATH = path.join(BUILD_DIR, 'state.json');+export const PHASES = ['spec', 'plates', 'hero', 'sections', 'motion', 'responsive', 'review'];+export const HERO_MIN = 0.72;+export const PLATE_MIN = 0.6;+export const HERO_REPRO = path.join('.impeccable', 'review', 'hero-repro.png');++function arg(name, fallback = null) {+ const i = process.argv.indexOf(`--${name}`);+ if (i === -1) return fallback;+ const v = process.argv[i + 1];+ return v && !v.startsWith('--') ? v : fallback;+}+const flag = (name) => process.argv.includes(`--${name}`);+const now = () => new Date().toISOString();++export function loadState(statePath = STATE_PATH) {+ if (!fs.existsSync(statePath)) return null;+ return JSON.parse(fs.readFileSync(statePath, 'utf8'));+}++export function saveState(state, statePath = STATE_PATH) {+ fs.mkdirSync(path.dirname(statePath), { recursive: true });+ fs.writeFileSync(statePath, JSON.stringify(state, null, 2));+}++export function newState({ comp, breakpoint = null }) {+ return {+ tool: 'build-phase',+ version: 1,+ startedAt: now(),+ comp,+ breakpoint,+ phase: 'spec',+ phases: Object.fromEntries(PHASES.map((p) => [p, { status: p === 'spec' ? 'open' : 'pending', openedAt: p === 'spec' ? now() : null, closedAt: null, attempts: 0, notes: [], gate: null, forced: null }])),+ finish: null,+ };+}++// ---- gates -----------------------------------------------------------------++export function gateSpec(state, { specPath = SPEC_PATH } = {}) {+ const spec = loadSpec(specPath);+ if (!spec) return { ok: false, reasons: [`no spec at ${specPath}: run comp-spec.mjs --comp ${state.comp} --grid, name the regions, then --regions regions.json`] };+ if (!spec.regions || spec.regions.length < 1) return { ok: false, reasons: ['spec has no regions'] };+ if (spec.comp && state.comp && path.resolve(spec.comp) !== path.resolve(state.comp)) {+ return { ok: false, reasons: [`spec measures ${spec.comp}, but this build started on ${state.comp}; re-run comp-spec on the approved comp`] };+ }+ const plates = spec.regions.filter((r) => r.medium === 'raster').length;+ return { ok: true, reasons: [], summary: `${spec.regions.length} regions, ${plates} plates` };+}++export function gatePlates(state, { specPath = SPEC_PATH } = {}) {+ const spec = loadSpec(specPath);+ if (!spec) return { ok: false, reasons: ['no spec'] };+ const rasterRegions = spec.regions.filter((r) => r.medium === 'raster');+ if (!rasterRegions.length) return { ok: true, reasons: [], summary: 'no plates owed', plates: [] };+ let comp = null;+ try { comp = decodePng(fs.readFileSync(spec.comp)); } catch { /* scored without the comp crop below */ }+ const reasons = [], plates = [];+ for (const r of rasterRegions) {+ const file = r.plate;+ if (!file || !fs.existsSync(file)) { reasons.push(`plate missing for ${r.id}: expected ${file || '(no path)'}; produce it from comp-spec.mjs --crop ${r.id} with generate-image.mjs --plate`); plates.push({ id: r.id, file, status: 'missing' }); continue; }+ let img;+ try { img = decodePng(fs.readFileSync(file)); } catch (e) { reasons.push(`plate ${file} is not a decodable PNG: ${e.message}`); plates.push({ id: r.id, file, status: 'unreadable' }); continue; }+ const minW = r.px.w * 1.5;+ if (img.width < minW) reasons.push(`plate ${file} is ${img.width}px wide; the comp region is ${r.px.w}px and a shipping plate needs at least 1.5x (${Math.round(minW)}px). Regenerate at asset size, do not crop the comp.`);+ let score = null;+ if (comp) {+ const ref = crop(comp, r.px.x, r.px.y, r.px.w, r.px.h);+ const res = compare({ comp: ref, build: img, align: 'stretch', spec: null });+ score = res.whole;+ if (score.overall < PLATE_MIN) reasons.push(`plate ${file} scores ${(score.overall * 100).toFixed(0)}% against the comp region ${r.id} (structure ${(score.structure * 100).toFixed(0)}%, color ${(score.color * 100).toFixed(0)}%, detail ${(score.detail * 100).toFixed(0)}%); it does not read as the same region. Regenerate with the crop as --ref and the comp-spec plate prompt.`);+ }+ plates.push({ id: r.id, file, status: 'ok', size: `${img.width}x${img.height}`, score: score ? score.overall : null });+ }+ return { ok: reasons.length === 0, reasons, summary: `${plates.filter((p) => p.status === 'ok').length}/${rasterRegions.length} plates`, plates };+}++export function gateHero(state, { buildPath = HERO_REPRO, specPath = SPEC_PATH, min = HERO_MIN, outDir = path.join('.impeccable', 'review', 'diff', 'hero') } = {}) {+ if (!fs.existsSync(buildPath)) return { ok: false, reasons: [`no hero capture at ${buildPath}: screenshot the first viewport at the comp's own dimensions (${state.breakpoint || 'comp size'}) into that path`] };+ const script = path.join(HERE, 'comp-diff.mjs');+ const args = [script, '--comp', state.comp, '--build', buildPath, '--out-dir', outDir, '--label', 'hero', '--json'];+ const spec = loadSpec(specPath);+ if (spec) args.push('--spec', specPath);+ const res = spawnSync(process.execPath, args, { encoding: 'utf8' });+ if (res.status !== 0 && res.status !== 3) return { ok: false, reasons: [`comp-diff failed: ${res.stderr || res.stdout}`] };+ let report;+ try { report = JSON.parse(res.stdout); } catch { return { ok: false, reasons: ['comp-diff produced no report'] }; }+ const reasons = [];+ if (report.overall < min) reasons.push(`hero overall ${(report.overall * 100).toFixed(0)}% < ${(min * 100).toFixed(0)}% (structure ${(report.scores.structure * 100).toFixed(0)}%, color ${(report.scores.color * 100).toFixed(0)}%, detail ${(report.scores.detail * 100).toFixed(0)}%)`);+ const missing = report.regions.filter((r) => r.verdict === 'missing');+ for (const r of missing) reasons.push(`region ${r.id} is missing (detail ${(r.score.detail * 100).toFixed(0)}%, structure ${(r.score.structure * 100).toFixed(0)}%): the comp shows material the build does not`);+ const contradicted = report.regions.filter((r) => r.verdict === 'contradicted');+ if (contradicted.length > Math.max(1, Math.floor(report.regions.length / 3))) reasons.push(`${contradicted.length} of ${report.regions.length} regions contradicted: ${contradicted.map((r) => r.id).join(', ')}`);+ return {+ ok: reasons.length === 0,+ reasons,+ summary: `hero ${(report.overall * 100).toFixed(0)}% (${report.verdict})`,+ score: report.overall,+ verdict: report.verdict,+ report: path.join(outDir, 'report.json'),+ sideBySide: report.files ? report.files.sideBySide : null,+ worst: [...report.regions].sort((a, b) => a.score.overall - b.score.overall).slice(0, 3).map((r) => `${r.id} ${r.verdict} ${(r.score.overall * 100).toFixed(0)}%`),+ };+}++const GATES = { spec: gateSpec, plates: gatePlates, hero: gateHero };++// ---- transitions -----------------------------------------------------------++export function runGate(state, phase, opts = {}) {+ const gate = GATES[phase];+ if (!gate) return { ok: true, reasons: [], summary: 'no mechanical gate' };+ return gate(state, opts);+}++export function advance(state, { force = false, reason = null, gateOpts = {} } = {}) {+ const phase = state.phase;+ const idx = PHASES.indexOf(phase);+ if (idx === -1 || phase === 'review') return { ok: false, reasons: [`phase ${phase} cannot advance; use finish`] };+ const p = state.phases[phase];+ p.attempts += 1;+ const gate = runGate(state, phase, gateOpts);+ const { plates: _p, ...gateRecord } = gate;+ p.gate = { ...gateRecord, at: now() };+ if (!gate.ok && !force) { p.status = 'open'; return { ok: false, phase, reasons: gate.reasons, gate }; }+ if (!gate.ok && force) p.forced = { at: now(), reason: reason || '(no reason given)', reasons: gate.reasons };+ p.status = 'closed'; p.closedAt = now();+ const next = PHASES[idx + 1];+ state.phase = next;+ state.phases[next].status = 'open'; state.phases[next].openedAt = now();+ return { ok: true, phase, next, gate, forced: !!p.forced };+}++export function nextInstruction(state) {+ switch (state.phase) {+ case 'spec': return `Measure the comp: node comp-spec.mjs --comp ${state.comp} --grid, open ${path.join(BUILD_DIR, 'comp-grid.png')}, write regions.json (every illustration, photo, texture as its own plate region), run comp-spec.mjs --comp ${state.comp} --regions regions.json, then build-phase.mjs advance.`;+ case 'plates': return 'Produce every plate in the spec (comp-spec.mjs --print lists them): comp-spec.mjs --crop <id>, then generate-image.mjs --plate <id> (or the harness image tool with the crop as reference and the comp-spec plate prompt). Then build-phase.mjs advance. Write no page code before this passes.';+ case 'hero': return `Build only the first viewport at ${state.breakpoint || 'the comp size'} using the plates and the spec's boxes and palette; capture it into ${HERO_REPRO}; run build-phase.mjs advance. Fix the worst regions it names and re-run; do not build past the hero until it passes.`;+ case 'sections': return 'Build the remaining sections inside the spec system (same corner language, rules, and palette; nothing the comp does not show). Then build-phase.mjs advance.';+ case 'motion': return 'Add the signature interaction, reveals, and motion. Then build-phase.mjs advance.';+ case 'responsive': return 'Build the other viewports (mobile first if the surface is mobile). Capture desktop.png and mobile.png into .impeccable/review/. Then build-phase.mjs advance.';+ case 'review': return 'Spawn the finish reviewer with the state file, the hero diff report, and the captures; record its disposition with build-phase.mjs finish --disposition <word>.';+ default: return '';+ }+}++export function renderStatus(state) {+ const lines = [`BUILD-PHASE ${state.phase.toUpperCase()} comp ${state.comp}${state.breakpoint ? ` breakpoint ${state.breakpoint}` : ''}`];+ for (const p of PHASES) {+ const s = state.phases[p];+ let line = ` ${p.padEnd(11)} ${s.status.padEnd(8)}`;+ if (s.gate && s.gate.summary) line += ` ${s.gate.summary}`;+ if (s.attempts > 1) line += ` (${s.attempts} attempts)`;+ if (s.forced) line += ` FORCED: ${s.forced.reason}`;+ lines.push(line);+ }+ if (state.finish) lines.push(` finish ${state.finish.disposition} at ${state.finish.at}`);+ lines.push(`NEXT ${nextInstruction(state)}`);+ return lines.join('\n');+}++async function main() {+ const cmd = process.argv[2];+ if (!cmd || flag('help')) {+ console.error('usage: build-phase.mjs start --comp <png> [--breakpoint WxH] | status [--json] | advance [--force --reason "..."] | record hero --build <png> | note "<text>" | finish --disposition <word>');+ process.exit(1);+ }+ if (cmd === 'start') {+ const comp = arg('comp');+ if (!comp || !fs.existsSync(comp)) { console.error('build-phase: --comp <approved comp png> is required and must exist'); process.exit(1); }+ let breakpoint = arg('breakpoint');+ if (!breakpoint) { try { const i = decodePng(fs.readFileSync(comp)); breakpoint = `${i.width}x${i.height}`; } catch { /* leave null */ } }+ const existing = loadState();+ if (existing && !flag('reset')) {+ console.log(`build-phase: state exists (phase ${existing.phase}); pass --reset to start over`);+ console.log(renderStatus(existing));+ return;+ }+ const state = newState({ comp, breakpoint });+ saveState(state);+ console.log(renderStatus(state));+ return;+ }+ const state = loadState();+ if (!state) { console.error(`build-phase: no state at ${STATE_PATH}; run build-phase.mjs start --comp <approved comp>`); process.exit(1); }+ if (cmd === 'status') {+ if (flag('json')) console.log(JSON.stringify(state, null, 2)); else console.log(renderStatus(state));+ return;+ }+ if (cmd === 'note') {+ const text = process.argv.slice(3).filter((a) => !a.startsWith('--')).join(' ');+ state.phases[state.phase].notes.push({ at: now(), text });+ saveState(state);+ console.log(`noted on ${state.phase}`);+ return;+ }+ if (cmd === 'record') {+ const which = process.argv[3];+ if (which !== 'hero') { console.error('build-phase: record hero --build <png>'); process.exit(1); }+ const gate = gateHero(state, { buildPath: arg('build', HERO_REPRO), min: arg('min') ? parseFloat(arg('min')) : HERO_MIN });+ state.phases.hero.attempts += 1;+ state.phases.hero.gate = { ...gate, at: now() };+ saveState(state);+ console.log(`${gate.ok ? 'PASS' : 'FAIL'} ${gate.summary || ''}`);+ for (const r of gate.reasons) console.log(` - ${r}`);+ if (gate.worst) console.log(` worst: ${gate.worst.join('; ')}`);+ if (gate.sideBySide) console.log(` open ${gate.sideBySide}`);+ process.exit(gate.ok ? 0 : 2);+ }+ if (cmd === 'advance') {+ const gateOpts = {};+ if (arg('build')) gateOpts.buildPath = arg('build');+ if (arg('min')) gateOpts.min = parseFloat(arg('min'));+ const res = advance(state, { force: flag('force'), reason: arg('reason'), gateOpts });+ saveState(state);+ if (!res.ok) {+ console.log(`GATE ${res.phase ? res.phase.toUpperCase() : ''} FAILED (state unchanged)`);+ for (const r of res.reasons) console.log(` - ${r}`);+ if (res.gate && res.gate.worst) console.log(` worst: ${res.gate.worst.join('; ')}`);+ if (res.gate && res.gate.sideBySide) console.log(` open ${res.gate.sideBySide} and the worst region pairs before editing`);+ process.exit(2);+ }+ console.log(`ADVANCED ${res.phase} -> ${res.next}${res.forced ? ' (FORCED; recorded)' : ''}${res.gate.summary ? ` ${res.gate.summary}` : ''}`);+ console.log(`NEXT ${nextInstruction(state)}`);+ return;+ }+ if (cmd === 'finish') {+ const disposition = arg('disposition');+ if (!['ship', 'fix', 'rebuild', 'recapture'].includes(disposition)) { console.error('build-phase: finish --disposition ship|fix|rebuild|recapture'); process.exit(1); }+ state.finish = { disposition, at: now(), phaseAtFinish: state.phase };+ if (state.phase === 'review') { state.phases.review.status = 'closed'; state.phases.review.closedAt = now(); }+ saveState(state);+ console.log(renderStatus(state));+ return;+ }+ console.error(`build-phase: unknown command ${cmd}`);+ process.exit(1);+}++const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);+if (isMain) main();diff --git a/skill/scripts/comp-diff.mjs b/skill/scripts/comp-diff.mjsnew file mode 100644index 000000000..ed0e7cfa1--- /dev/null+++ b/skill/scripts/comp-diff.mjs@@ -0,0 +1,290 @@+#!/usr/bin/env node+/**+ * comp-diff: measure a build screenshot against its approved comp and produce+ * the evidence a reviewer (human or model) needs to judge fidelity without+ * trusting anyone's memory of the image.+ *+ * node comp-diff.mjs --comp .impeccable/mocks/approved.png --build .impeccable/review/hero-repro.png+ * node comp-diff.mjs --comp comp.png --build desktop.png --spec .impeccable/build/spec.json --out-dir .impeccable/review/diff+ * node comp-diff.mjs ... --json # machine-readable report on stdout+ * node comp-diff.mjs ... --threshold 0.75 # exit 3 when the overall score is below+ *+ * Inputs: two PNGs. The build capture may be taller than the comp (a full-page+ * screenshot); it is scaled to the comp's width and the top comp-height rows+ * are compared, because the comp is the first viewport. `--align stretch`+ * squashes the whole build onto the comp instead, for a comp that covers a+ * whole page.+ *+ * Outputs (in --out-dir, default .impeccable/review/diff):+ * side-by-side.png comp | build, same size, labeled, with the score+ * heatmap.png build with the difference painted over it (red = wrong)+ * regions/<id>.png paired crops per region at legible scale, scored+ * report.json every number below, plus per-region rows+ *+ * Scores (0..1): structure (blurred SSIM: is the composition the same?),+ * color (histogram + dominant palette: is it the same palette at the same+ * coverage?), detail (high-frequency energy ratio: did the material survive,+ * or did an illustration become a gradient?), bands (do the horizontal+ * sections line up?). `overall` weights them 0.35 / 0.25 / 0.25 / 0.15.+ *+ * Regions come from --spec (comp-spec.mjs output: normalized boxes) or, with+ * none, from the comp's own horizontal bands, so the per-region crops exist+ * either way. Every region row carries the same four scores plus `verdict`:+ * match (>= 0.8), drift (>= 0.6), missing (detail ratio < 0.35 with structure+ * < 0.6), or contradicted (everything else). The words are the finish+ * reviewer's fidelity vocabulary on purpose.+ *+ * Exit codes: 0 measured (and above threshold when one is given), 1 usage or+ * unreadable input, 3 below threshold.+ */+import fs from 'node:fs';+import path from 'node:path';+import { decodePng, encodePng } from './lib/png.mjs';+import { crop, resize, fit, blit, createImage, fillRect, strokeRect, drawLabel } from './lib/raster.mjs';+import { structureScore, colorScore, detailScore, diffMap, horizontalBands, bandScore, dominantColors } from './lib/image-metrics.mjs';++function arg(name, fallback = null) {+ const i = process.argv.indexOf(`--${name}`);+ if (i === -1) return fallback;+ const v = process.argv[i + 1];+ return v && !v.startsWith('--') ? v : fallback;+}+const flag = (name) => process.argv.includes(`--${name}`);++export function readPng(file) {+ return decodePng(fs.readFileSync(file));+}++/** Scale the build to the comp's width; take the top comp-height rows (align=top) or squash (align=stretch). */+export function alignBuild(comp, build, align = 'top') {+ if (align === 'stretch') return resize(build, comp.width, comp.height);+ const scaled = build.width === comp.width ? build : resize(build, comp.width, Math.round((build.height / build.width) * comp.width));+ if (scaled.height === comp.height) return scaled;+ if (scaled.height > comp.height) return crop(scaled, 0, 0, comp.width, comp.height);+ // shorter than the comp: pad with white so a short page reads as missing content, not as a resize+ const out = createImage(comp.width, comp.height, [255, 255, 255, 255]);+ blit(out, scaled, 0, 0);+ return out;+}++/** Weights per region kind: what a region is made of decides what losing it looks like. */+const WEIGHTS = {+ default: { structure: 0.35, color: 0.25, detail: 0.25, bands: 0.15 },+ plate: { structure: 0.25, color: 0.2, detail: 0.5, bands: 0.05 },+ image: { structure: 0.25, color: 0.2, detail: 0.5, bands: 0.05 },+ texture: { structure: 0.15, color: 0.35, detail: 0.5, bands: 0 },+ text: { structure: 0.5, color: 0.25, detail: 0.15, bands: 0.1 },+ control: { structure: 0.45, color: 0.35, detail: 0.2, bands: 0 },+};++export function scorePair(a, b, kind = null) {+ const structure = structureScore(a, b);+ const color = colorScore(a, b);+ const detail = detailScore(a, b);+ const bandsA = horizontalBands(a), bandsB = horizontalBands(b);+ const bands = bandScore(bandsA, bandsB);+ const w = WEIGHTS[kind] || WEIGHTS.default;+ const overall = w.structure * structure + w.color * color.score + w.detail * detail.score + w.bands * bands;+ return {+ overall: r4(overall),+ structure: r4(structure),+ color: r4(color.score),+ colorIntersection: r4(color.intersection),+ paletteMatch: r4(color.paletteMatch),+ detail: r4(detail.score),+ detailAdded: r4(detail.addedFraction),+ bands: r4(bands),+ _detail: detail,+ _bands: { comp: bandsA, build: bandsB },+ };+}++export function verdictFor(s, kind = null) {+ const painted = kind === 'plate' || kind === 'image' || kind === 'texture';+ if (painted && s.detail < 0.5) return 'missing';+ if (s.detail < 0.35 && s.structure < 0.6) return 'missing';+ if (s.overall >= 0.8) return 'match';+ if (s.overall >= 0.6) return 'drift';+ return 'contradicted';+}++const r4 = (v) => Math.round(v * 10000) / 10000;++/** Regions from a spec (normalized boxes) or derived from the comp's bands. */+export function resolveRegions(comp, spec) {+ const regions = [];+ if (spec && Array.isArray(spec.regions) && spec.regions.length) {+ for (const r of spec.regions) {+ const box = r.box || r;+ if ([box.x, box.y, box.w, box.h].some((v) => typeof v !== 'number')) continue;+ regions.push({ id: r.id || `region-${regions.length + 1}`, x: box.x, y: box.y, w: box.w, h: box.h, kind: r.kind || null });+ }+ if (regions.length) return regions;+ }+ const bands = horizontalBands(comp).filter((b) => b.strength > 0.2);+ const cuts = [0, ...bands.map((b) => b.y), 1].filter((v, i, arr) => i === 0 || v - arr[i - 1] > 0.06);+ if (cuts[cuts.length - 1] !== 1) cuts.push(1);+ for (let i = 0; i + 1 < cuts.length; i++) {+ regions.push({ id: `band-${i + 1}`, x: 0, y: cuts[i], w: 1, h: cuts[i + 1] - cuts[i], kind: 'band' });+ }+ if (regions.length < 2) {+ return [+ { id: 'top', x: 0, y: 0, w: 1, h: 0.5, kind: 'band' },+ { id: 'bottom', x: 0, y: 0.5, w: 1, h: 0.5, kind: 'band' },+ ];+ }+ return regions;+}++/** Crop a normalized region; regions thinner than 48px in either axis are grown to that so tiny strips do not swing on subpixel noise. */+function regionCrop(img, r) {+ const minPx = 48;+ let x = r.x * img.width, y = r.y * img.height, w = r.w * img.width, h = r.h * img.height;+ if (h < minPx) { y -= (minPx - h) / 2; h = minPx; }+ if (w < minPx) { x -= (minPx - w) / 2; w = minPx; }+ return crop(img, x, y, w, h);+}++const HEAT_LABEL = { match: [40, 160, 80, 255], drift: [220, 160, 30, 255], missing: [200, 40, 40, 255], contradicted: [200, 40, 40, 255] };++export function renderSideBySide(comp, build, label, score) {+ const gap = 24, pad = 48;+ const targetW = Math.min(comp.width, 1400);+ const a = fit(comp, targetW, 100000), b = resize(build, a.width, a.height);+ const out = createImage(a.width * 2 + gap + pad * 2, a.height + pad * 2 + 24, [24, 24, 28, 255]);+ blit(out, a, pad, pad + 24);+ blit(out, b, pad + a.width + gap, pad + 24);+ drawLabel(out, 'COMP', pad, pad - 4, { scale: 2 });+ drawLabel(out, `BUILD ${label ? label.toUpperCase() : ''}`.trim(), pad + a.width + gap, pad - 4, { scale: 2 });+ const s = `OVERALL ${(score.overall * 100).toFixed(0)}% STRUCT ${(score.structure * 100).toFixed(0)}% COLOR ${(score.color * 100).toFixed(0)}% DETAIL ${(score.detail * 100).toFixed(0)}% BANDS ${(score.bands * 100).toFixed(0)}%`;+ drawLabel(out, s, pad, out.height - pad + 8, { scale: 2, bg: HEAT_LABEL[verdictFor(score)] });+ return out;+}++export function renderHeatmap(comp, build) {+ const map = diffMap(comp, build);+ const base = resize(build, map.width, map.height);+ const out = { width: base.width, height: base.height, data: new Uint8Array(base.data) };+ for (let i = 0, p = 0; i < map.data.length; i++, p += 4) {+ const d = map.data[i];+ if (d < 0.12) { // dim what matches so wrong stands out+ out.data[p] = out.data[p] * 0.55 + 255 * 0.45 * 0.2; out.data[p + 1] = out.data[p + 1] * 0.55; out.data[p + 2] = out.data[p + 2] * 0.55; continue;+ }+ const a = Math.min(1, (d - 0.12) / 0.5);+ out.data[p] = out.data[p] * (1 - a) + 235 * a; out.data[p + 1] = out.data[p + 1] * (1 - a) + 40 * a; out.data[p + 2] = out.data[p + 2] * (1 - a) + 40 * a;+ }+ const scaled = resize(out, comp.width, comp.height);+ drawLabel(scaled, 'DIFF: RED = DIFFERS FROM COMP', 12, 12, { scale: 2 });+ return scaled;+}++export function renderRegionPair(compCrop, buildCrop, id, score) {+ const gap = 16, pad = 12;+ const maxW = 700;+ const a = fit(compCrop, maxW, 700, true), b = resize(buildCrop, a.width, a.height);+ const out = createImage(a.width * 2 + gap + pad * 2, a.height + pad * 2 + 30, [24, 24, 28, 255]);+ blit(out, a, pad, pad + 30);+ blit(out, b, pad + a.width + gap, pad + 30);+ const v = verdictFor(score);+ drawLabel(out, `${id.toUpperCase()} COMP`, pad, pad, { scale: 2 });+ drawLabel(out, `BUILD ${v.toUpperCase()} ${(score.overall * 100).toFixed(0)}%`, pad + a.width + gap, pad, { scale: 2, bg: HEAT_LABEL[v] });+ return out;+}++export function compare({ comp, build, spec = null, align = 'top', label = '' }) {+ const aligned = alignBuild(comp, build, align);+ const whole = scorePair(comp, aligned);+ const regions = resolveRegions(comp, spec).map((r) => {+ const a = regionCrop(comp, r), b = regionCrop(aligned, r);+ const s = scorePair(a, b, r.kind);+ return { ...r, score: strip(s), verdict: verdictFor(s, r.kind), _a: a, _b: b };+ });+ const compPalette = dominantColors(comp), buildPalette = dominantColors(aligned);+ return { label, align, whole: strip(whole), regions, aligned, compPalette, buildPalette, _whole: whole };+}++function strip(s) {+ const { _detail, _bands, ...rest } = s;+ return rest;+}++export function writeArtifacts(result, comp, outDir) {+ fs.mkdirSync(path.join(outDir, 'regions'), { recursive: true });+ const side = renderSideBySide(comp, result.aligned, result.label, result.whole);+ fs.writeFileSync(path.join(outDir, 'side-by-side.png'), encodePng(side));+ fs.writeFileSync(path.join(outDir, 'heatmap.png'), encodePng(renderHeatmap(comp, result.aligned)));+ const regionFiles = [];+ for (const r of result.regions) {+ const file = path.join(outDir, 'regions', `${r.id}.png`);+ fs.writeFileSync(file, encodePng(renderRegionPair(r._a, r._b, r.id, r.score)));+ regionFiles.push(file);+ }+ return { sideBySide: path.join(outDir, 'side-by-side.png'), heatmap: path.join(outDir, 'heatmap.png'), regionFiles };+}++export function buildReport(result, files, meta) {+ return {+ tool: 'comp-diff',+ version: 1,+ createdAt: new Date().toISOString(),+ ...meta,+ align: result.align,+ overall: result.whole.overall,+ verdict: verdictFor(result.whole),+ scores: result.whole,+ palette: { comp: result.compPalette.map(({ hex, coverage }) => ({ hex, coverage })), build: result.buildPalette.map(({ hex, coverage }) => ({ hex, coverage })) },+ regions: result.regions.map(({ _a, _b, ...r }) => r),+ files,+ };+}++function summarize(report) {+ const lines = [];+ lines.push(`COMP-DIFF ${report.label ? `[${report.label}] ` : ''}overall ${(report.overall * 100).toFixed(0)}% (${report.verdict}) structure ${(report.scores.structure * 100).toFixed(0)}% color ${(report.scores.color * 100).toFixed(0)}% detail ${(report.scores.detail * 100).toFixed(0)}% bands ${(report.scores.bands * 100).toFixed(0)}%`);+ lines.push(`PALETTE comp ${report.palette.comp.slice(0, 5).map((c) => `${c.hex}(${Math.round(c.coverage * 100)}%)`).join(' ')}`);+ lines.push(`PALETTE build ${report.palette.build.slice(0, 5).map((c) => `${c.hex}(${Math.round(c.coverage * 100)}%)`).join(' ')}`);+ for (const r of report.regions) {+ lines.push(`REGION ${r.id.padEnd(18)} ${r.verdict.padEnd(12)} ${(r.score.overall * 100).toFixed(0).padStart(3)}% structure ${(r.score.structure * 100).toFixed(0).padStart(3)}% color ${(r.score.color * 100).toFixed(0).padStart(3)}% detail ${(r.score.detail * 100).toFixed(0).padStart(3)}%${r.score.detailAdded > 0.25 ? ' +invented detail' : ''}`);+ }+ if (report.files) {+ lines.push(`FILES side-by-side ${report.files.sideBySide}`);+ lines.push(`FILES heatmap ${report.files.heatmap}`);+ lines.push(`FILES regions ${report.files.regionFiles.length} under ${path.dirname(report.files.regionFiles[0] || report.files.heatmap)}`);+ }+ const worst = [...report.regions].sort((a, b) => a.score.overall - b.score.overall).slice(0, 3);+ if (worst.length) lines.push(`WORST ${worst.map((r) => `${r.id} (${r.verdict}, ${(r.score.overall * 100).toFixed(0)}%)`).join('; ')}`);+ lines.push('OPEN the side-by-side and the worst region pairs before deciding anything; the numbers rank, the crops decide.');+ return lines.join('\n');+}++async function main() {+ const compPath = arg('comp'), buildPath = arg('build');+ if (!compPath || !buildPath) {+ console.error('usage: comp-diff.mjs --comp <png> --build <png> [--spec spec.json] [--out-dir dir] [--align top|stretch] [--label name] [--threshold 0.75] [--json]');+ process.exit(1);+ }+ let comp, build;+ try { comp = readPng(compPath); } catch (e) { console.error(`comp-diff: cannot read comp ${compPath}: ${e.message}`); process.exit(1); }+ try { build = readPng(buildPath); } catch (e) { console.error(`comp-diff: cannot read build ${buildPath}: ${e.message}`); process.exit(1); }+ let spec = null;+ const specPath = arg('spec');+ if (specPath) {+ try { spec = JSON.parse(fs.readFileSync(specPath, 'utf8')); } catch (e) { console.error(`comp-diff: cannot read spec ${specPath}: ${e.message}`); process.exit(1); }+ }+ const outDir = arg('out-dir', path.join(path.dirname(buildPath), 'diff'));+ const label = arg('label', path.basename(buildPath, '.png'));+ const result = compare({ comp, build, spec, align: arg('align', 'top'), label });+ const files = flag('no-files') ? null : writeArtifacts(result, comp, outDir);+ const report = buildReport(result, files, { label, comp: compPath, build: buildPath, spec: specPath || null, compSize: `${comp.width}x${comp.height}`, buildSize: `${build.width}x${build.height}` });+ if (files) fs.writeFileSync(path.join(outDir, 'report.json'), JSON.stringify(report, null, 2));+ if (flag('json')) console.log(JSON.stringify(report, null, 2));+ else console.log(summarize(report));+ const threshold = arg('threshold') ? parseFloat(arg('threshold')) : null;+ if (threshold != null && report.overall < threshold) {+ if (!flag('json')) console.log(`BELOW THRESHOLD ${(threshold * 100).toFixed(0)}%: the reproduction is not done. Fix the worst regions and re-run; do not build past the hero.`);+ process.exit(3);+ }+}++const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);+if (isMain) main();diff --git a/skill/scripts/comp-spec.mjs b/skill/scripts/comp-spec.mjsnew file mode 100644index 000000000..6d874c914--- /dev/null+++ b/skill/scripts/comp-spec.mjs@@ -0,0 +1,252 @@+#!/usr/bin/env node+/**+ * comp-spec: turn an approved comp into a measured build spec, so the build+ * codes against numbers and crops instead of a memory of the image.+ *+ * Step 1, look at the comp with a coordinate grid on it:+ * node comp-spec.mjs --comp .impeccable/mocks/approved.png --grid+ * writes .impeccable/build/comp-grid.png (10x10 labeled grid, A-J / 0-9)+ * and prints the measured palette and horizontal bands. Open the grid+ * image and name every salient region by its grid span.+ *+ * Step 2, write the regions file (JSON) and measure it:+ * node comp-spec.mjs --comp <comp> --regions regions.json+ * regions.json: { "regions": [ { "id": "exploded-plate", "kind": "plate",+ * "grid": "E0:J4", "note": "exploded carburetor line drawing" }, ... ] }+ * `grid` is "<colrow>:<colrow>" inclusive (A0 top-left cell to J9 bottom+ * right); `box` { x, y, w, h } normalized 0..1 is accepted instead. `kind`+ * is one of plate | image | texture | text | control | chrome | band.+ * Writes .impeccable/build/spec.json: every region with its normalized+ * box, pixel box, sampled palette, detail energy, and its medium: raster+ * for plate / image / texture (produced as a plate, never CSS), semantic+ * for text / control / chrome. `--auto` proposes band regions from the+ * comp itself when you have no regions file yet.+ *+ * Step 3, use it:+ * node comp-spec.mjs --print # compact spec for the build thread+ * node comp-spec.mjs --crop exploded-plate --out tmp/plate-src.png [--scale 2]+ * crops the region from the comp (reference for a plate regeneration; a+ * crop is never a shipping asset, its resolution is comp grade)+ * node comp-spec.mjs --plate-prompt exploded-plate # the regeneration prompt for that region+ *+ * comp-diff.mjs reads the same spec (`--spec`) so its region rows and this+ * file's rows are the same rows.+ */+import fs from 'node:fs';+import path from 'node:path';+import { decodePng, encodePng } from './lib/png.mjs';+import { crop, resize, fillRect, strokeRect, drawLabel, drawText } from './lib/raster.mjs';+import { dominantColors, horizontalBands, detailGrid } from './lib/image-metrics.mjs';++function arg(name, fallback = null) {+ const i = process.argv.indexOf(`--${name}`);+ if (i === -1) return fallback;+ const v = process.argv[i + 1];+ return v && !v.startsWith('--') ? v : fallback;+}+const flag = (name) => process.argv.includes(`--${name}`);++export const BUILD_DIR = path.join('.impeccable', 'build');+export const SPEC_PATH = path.join(BUILD_DIR, 'spec.json');+export const GRID_PATH = path.join(BUILD_DIR, 'comp-grid.png');+export const PLATES_DIR = path.join('assets', 'plates');++export const RASTER_KINDS = new Set(['plate', 'image', 'texture']);+export const KINDS = new Set(['plate', 'image', 'texture', 'text', 'control', 'chrome', 'band']);+const COLS = 'ABCDEFGHIJ';++/** "E0:J4" -> normalized box (inclusive cell span on a 10x10 grid). */+export function gridToBox(span) {+ const m = /^([A-J])(\d):([A-J])(\d)$/i.exec(String(span).trim());+ if (!m) throw new Error(`grid span "${span}" is not <colrow>:<colrow>, e.g. E0:J4`);+ const c0 = COLS.indexOf(m[1].toUpperCase()), r0 = +m[2], c1 = COLS.indexOf(m[3].toUpperCase()), r1 = +m[4];+ const x0 = Math.min(c0, c1), x1 = Math.max(c0, c1), y0 = Math.min(r0, r1), y1 = Math.max(r0, r1);+ return { x: x0 / 10, y: y0 / 10, w: (x1 - x0 + 1) / 10, h: (y1 - y0 + 1) / 10 };+}++export function renderGrid(comp) {+ const targetW = Math.min(1536, comp.width);+ const img = resize(comp, targetW, Math.round((comp.height / comp.width) * targetW));+ const cw = img.width / 10, ch = img.height / 10;+ const line = [255, 40, 40, 200];+ for (let i = 1; i < 10; i++) {+ fillRect(img, Math.round(i * cw), 0, 1, img.height, line);+ fillRect(img, 0, Math.round(i * ch), img.width, 1, line);+ }+ for (let r = 0; r < 10; r++) for (let c = 0; c < 10; c++) {+ drawLabel(img, `${COLS[c]}${r}`, Math.round(c * cw) + 3, Math.round(r * ch) + 3, { scale: 2, bg: [0, 0, 0, 170], fg: [255, 230, 120, 255] });+ }+ return img;+}++function paletteOf(img) {+ return dominantColors(img, 5).map(({ hex, coverage }) => ({ hex, coverage }));+}++function energyOf(img) {+ const g = detailGrid(img, 4, 4, 256);+ let s = 0; for (const v of g.cells) s += v;+ return s / g.cells.length;+}+++export function measureRegions(comp, regionsInput, compPath) {+ const regions = [];+ const seen = new Set();+ for (const raw of regionsInput.regions || []) {+ if (!raw.id) throw new Error('every region needs an id');+ if (seen.has(raw.id)) throw new Error(`duplicate region id ${raw.id}`);+ seen.add(raw.id);+ const kind = raw.kind && KINDS.has(raw.kind) ? raw.kind : 'band';+ const box = raw.box && typeof raw.box.x === 'number' ? raw.box : gridToBox(raw.grid);+ const px = { x: Math.round(box.x * comp.width), y: Math.round(box.y * comp.height), w: Math.round(box.w * comp.width), h: Math.round(box.h * comp.height) };+ const c = crop(comp, px.x, px.y, px.w, px.h);+ const energy = energyOf(c);+ const raster = RASTER_KINDS.has(kind);+ regions.push({+ id: raw.id,+ kind,+ note: raw.note || null,+ box: { x: r4(box.x), y: r4(box.y), w: r4(box.w), h: r4(box.h) },+ px,+ aspect: r4(px.w / px.h),+ palette: paletteOf(c),+ detail: { energy: r4(energy) },+ medium: raw.medium || (raster ? 'raster' : 'semantic'),+ plate: raster ? (raw.plate || path.join(PLATES_DIR, `${raw.id}.png`)) : null,+ text: raw.text || null,+ });+ }+ return {+ tool: 'comp-spec',+ version: 1,+ createdAt: new Date().toISOString(),+ comp: compPath,+ compSize: { width: comp.width, height: comp.height },+ aspect: r4(comp.width / comp.height),+ orientation: comp.width >= comp.height ? 'landscape' : 'portrait',+ palette: paletteOf(comp),+ bands: horizontalBands(comp).filter((b) => b.strength > 0.2).map((b) => ({ y: r4(b.y), strength: r4(b.strength) })),+ regions,+ };+}++/** Propose regions from the comp's bands when no regions file exists yet. */+export function autoRegions(comp) {+ const bands = horizontalBands(comp).filter((b) => b.strength > 0.2);+ const cuts = [0, ...bands.map((b) => b.y), 1].filter((v, i, arr) => i === 0 || v - arr[i - 1] > 0.06);+ if (cuts[cuts.length - 1] !== 1) cuts.push(1);+ const regions = [];+ for (let i = 0; i + 1 < cuts.length; i++) regions.push({ id: `band-${i + 1}`, kind: 'band', box: { x: 0, y: cuts[i], w: 1, h: cuts[i + 1] - cuts[i] } });+ return { regions };+}++const r4 = (v) => Math.round(v * 10000) / 10000;++export function platePrompt(spec, region) {+ const world = spec.palette.slice(0, 3).map((c) => c.hex).join(', ');+ const kindLine = region.kind === 'texture'+ ? 'This is a seamless surface texture. Output a tileable texture plate with no objects, no text, no vignette.'+ : region.kind === 'image'+ ? 'This is a photographic or illustrated image region. Output the same subject, same framing, same lighting.'+ : 'This is a designed illustration plate. Output the same drawing, same style, same line weight and shading.';+ return [+ 'Use the provided crop as the approved visual reference and recreate it as a clean production asset at the target aspect ratio.',+ kindLine,+ `Preserve silhouette, composition, perspective, palette (${world}), lighting, material, and texture exactly.`,+ 'Remove every piece of UI text, label, caption, button, and interface chrome that is not part of the artwork itself.',+ 'Remove letterboxing, borders, card corners, drop shadows, and any layout background that the page will draw in code.',+ 'Do not add objects. Do not change the concept. Do not restyle. Fill the whole frame; no margins.',+ region.note ? `Region: ${region.note}.` : '',+ ].filter(Boolean).join(' ');+}++export function printSpec(spec) {+ const lines = [];+ lines.push(`SPEC comp ${spec.comp} ${spec.compSize.width}x${spec.compSize.height} ${spec.orientation}`);+ lines.push(`PALETTE ${spec.palette.map((c) => `${c.hex}(${Math.round(c.coverage * 100)}%)`).join(' ')}`);+ lines.push(`BANDS ${spec.bands.map((b) => `${Math.round(b.y * 100)}%`).join(' ') || 'none'}`);+ for (const r of spec.regions) {+ const b = r.box;+ lines.push(`REGION ${r.id.padEnd(18)} ${r.kind.padEnd(8)} ${r.medium.padEnd(8)} box x${Math.round(b.x * 100)}% y${Math.round(b.y * 100)}% w${Math.round(b.w * 100)}% h${Math.round(b.h * 100)}% (${r.px.w}x${r.px.h}px, ${r.aspect}:1) palette ${r.palette.slice(0, 3).map((c) => c.hex).join(' ')}${r.plate ? ` plate ${r.plate}` : ''}${r.note ? ` # ${r.note}` : ''}`);+ }+ const plates = spec.regions.filter((r) => r.medium === 'raster');+ lines.push(`PLATES ${plates.length} to produce: ${plates.map((r) => r.id).join(', ') || 'none'}`);+ lines.push('RULE anything not in this list does not exist on the page: no borders, rules, chrome, or containers the comp does not show. Every raster region ships as its plate, never as CSS.');+ return lines.join('\n');+}++export function loadSpec(specPath = SPEC_PATH) {+ if (!fs.existsSync(specPath)) return null;+ return JSON.parse(fs.readFileSync(specPath, 'utf8'));+}++async function main() {+ const specPath = arg('spec', SPEC_PATH);+ if (flag('print')) {+ const spec = loadSpec(specPath);+ if (!spec) { console.error(`comp-spec: no spec at ${specPath}; run with --comp <png> --regions <json> first`); process.exit(1); }+ console.log(printSpec(spec));+ return;+ }+ if (arg('plate-prompt')) {+ const spec = loadSpec(specPath);+ if (!spec) { console.error(`comp-spec: no spec at ${specPath}`); process.exit(1); }+ const region = spec.regions.find((r) => r.id === arg('plate-prompt'));+ if (!region) { console.error(`comp-spec: no region ${arg('plate-prompt')}`); process.exit(1); }+ console.log(platePrompt(spec, region));+ return;+ }+ if (arg('crop')) {+ const spec = loadSpec(specPath);+ if (!spec) { console.error(`comp-spec: no spec at ${specPath}`); process.exit(1); }+ const region = spec.regions.find((r) => r.id === arg('crop'));+ if (!region) { console.error(`comp-spec: no region ${arg('crop')}; ids: ${spec.regions.map((r) => r.id).join(', ')}`); process.exit(1); }+ const comp = decodePng(fs.readFileSync(spec.comp));+ let c = crop(comp, region.px.x, region.px.y, region.px.w, region.px.h);+ const scale = parseFloat(arg('scale', '1'));+ if (scale > 1) c = resize(c, c.width * scale, c.height * scale);+ const out = arg('out', path.join(BUILD_DIR, 'crops', `${region.id}.png`));+ fs.mkdirSync(path.dirname(out), { recursive: true });+ fs.writeFileSync(out, encodePng(c, { text: { 'impeccable:crop-of': `${spec.comp}#${region.id}` } }));+ console.log(`CROP ${out} (${c.width}x${c.height}) region ${region.id} of ${spec.comp}. Reference only: regenerate the plate from it, never ship it.`);+ return;+ }++ const compPath = arg('comp');+ if (!compPath) {+ console.error('usage: comp-spec.mjs --comp <png> (--grid | --regions <json> | --auto) [--spec out.json]\n comp-spec.mjs --print | --crop <id> [--out file] [--scale n] | --plate-prompt <id>');+ process.exit(1);+ }+ let comp;+ try { comp = decodePng(fs.readFileSync(compPath)); } catch (e) { console.error(`comp-spec: cannot read ${compPath}: ${e.message}`); process.exit(1); }++ if (flag('grid')) {+ fs.mkdirSync(path.dirname(GRID_PATH), { recursive: true });+ fs.writeFileSync(GRID_PATH, encodePng(renderGrid(comp)));+ console.log(`GRID ${GRID_PATH} (${comp.width}x${comp.height} comp; cells A0 top-left to J9 bottom-right)`);+ console.log(`PALETTE ${paletteOf(comp).map((c) => `${c.hex}(${Math.round(c.coverage * 100)}%)`).join(' ')}`);+ console.log(`BANDS ${horizontalBands(comp).filter((b) => b.strength > 0.2).map((b) => `${Math.round(b.y * 100)}%`).join(' ') || 'none'}`);+ console.log('NEXT open the grid image, then write regions.json naming every salient region by grid span (e.g. "E0:J4") with kind plate|image|texture|text|control|chrome and a one-line note, and run --regions regions.json. Name every illustration, photo, and texture as its own region: those become plates.');+ return;+ }++ let regionsInput;+ if (arg('regions')) {+ try { regionsInput = JSON.parse(fs.readFileSync(arg('regions'), 'utf8')); } catch (e) { console.error(`comp-spec: cannot read regions ${arg('regions')}: ${e.message}`); process.exit(1); }+ } else if (flag('auto')) {+ regionsInput = autoRegions(comp);+ } else {+ console.error('comp-spec: pass --grid to get the coordinate grid, then --regions <json> (or --auto for band regions)');+ process.exit(1);+ }+ let spec;+ try { spec = measureRegions(comp, regionsInput, compPath); } catch (e) { console.error(`comp-spec: ${e.message}`); process.exit(1); }+ fs.mkdirSync(path.dirname(specPath), { recursive: true });+ fs.writeFileSync(specPath, JSON.stringify(spec, null, 2));+ console.log(`WROTE ${specPath}`);+ console.log(printSpec(spec));+}++const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);+if (isMain) main();diff --git a/skill/scripts/lib/image-metrics.mjs b/skill/scripts/lib/image-metrics.mjsnew file mode 100644index 000000000..2100d7da4--- /dev/null+++ b/skill/scripts/lib/image-metrics.mjs@@ -0,0 +1,302 @@+/**+ * Perceptual measures for comparing a comp with a build screenshot. Pure+ * functions over `{ width, height, data }` RGBA images; no I/O.+ *+ * Three families, because a build fails a comp in three separable ways:+ *+ * - structure: is the composition the same? Measured as SSIM over a blurred+ * grayscale downsample, which forgives font hinting and a few pixels of+ * drift and punishes a moved, missing, or invented region.+ * - color: is the palette and its distribution the same? Histogram+ * intersection in a coarse quantized space plus a dominant-color extraction,+ * so a navy page built from a bone comp fails even if the shapes match.+ * - detail: is the material there? Local high-frequency energy per cell. A+ * comp with an illustration, texture, or photograph carries energy a flat+ * CSS stand-in does not; the ratio build/comp per region is the most direct+ * measure of "the plate got replaced by a gradient".+ */+import { resize } from './raster.mjs';++export function toGray(img) {+ const g = new Float32Array(img.width * img.height);+ for (let i = 0, p = 0; i < g.length; i++, p += 4) {+ const a = img.data[p + 3] / 255;+ // composite over white so transparent regions read as the page ground+ const r = img.data[p] * a + 255 * (1 - a), gg = img.data[p + 1] * a + 255 * (1 - a), b = img.data[p + 2] * a + 255 * (1 - a);+ g[i] = 0.2126 * r + 0.7152 * gg + 0.0722 * b;+ }+ return { width: img.width, height: img.height, data: g };+}++/** Separable box blur on a float gray image, radius r. */+export function blurGray(gray, r) {+ if (r <= 0) return gray;+ const { width, height, data } = gray;+ const tmp = new Float32Array(data.length), out = new Float32Array(data.length);+ const win = 2 * r + 1;+ for (let y = 0; y < height; y++) {+ let acc = 0;+ for (let x = -r; x <= r; x++) acc += data[y * width + Math.min(width - 1, Math.max(0, x))];+ for (let x = 0; x < width; x++) {+ tmp[y * width + x] = acc / win;+ const outX = x - r, inX = x + r + 1;+ acc += data[y * width + Math.min(width - 1, inX)] - data[y * width + Math.max(0, outX)];+ }+ }+ for (let x = 0; x < width; x++) {+ let acc = 0;+ for (let y = -r; y <= r; y++) acc += tmp[Math.min(height - 1, Math.max(0, y)) * width + x];+ for (let y = 0; y < height; y++) {+ out[y * width + x] = acc / win;+ const outY = y - r, inY = y + r + 1;+ acc += tmp[Math.min(height - 1, inY) * width + x] - tmp[Math.max(0, outY) * width + x];+ }+ }+ return { width, height, data: out };+}++/** Global SSIM between two same-size gray images using an 8x8 window grid. */+export function ssim(a, b, win = 8) {+ if (a.width !== b.width || a.height !== b.height) throw new Error('ssim: size mismatch');+ const C1 = (0.01 * 255) ** 2, C2 = (0.03 * 255) ** 2;+ let total = 0, n = 0;+ for (let y = 0; y + win <= a.height; y += win) {+ for (let x = 0; x + win <= a.width; x += win) {+ let ma = 0, mb = 0;+ for (let yy = 0; yy < win; yy++) for (let xx = 0; xx < win; xx++) { const i = (y + yy) * a.width + x + xx; ma += a.data[i]; mb += b.data[i]; }+ ma /= win * win; mb /= win * win;+ let va = 0, vb = 0, cov = 0;+ for (let yy = 0; yy < win; yy++) for (let xx = 0; xx < win; xx++) { const i = (y + yy) * a.width + x + xx; const da = a.data[i] - ma, db = b.data[i] - mb; va += da * da; vb += db * db; cov += da * db; }+ va /= win * win - 1; vb /= win * win - 1; cov /= win * win - 1;+ total += ((2 * ma * mb + C1) * (2 * cov + C2)) / ((ma * ma + mb * mb + C1) * (va + vb + C2));+ n++;+ }+ }+ return n ? total / n : 1;+}++/** SSIM of `a` against `b` shifted by (dx, dy); the overlap is compared, edges dropped. */+function ssimShifted(a, b, dx, dy, win) {+ const w = a.width - Math.abs(dx), h = a.height - Math.abs(dy);+ if (w < win || h < win) return 0;+ const sa = { width: w, height: h, data: new Float32Array(w * h) };+ const sb = { width: w, height: h, data: new Float32Array(w * h) };+ const ax = Math.max(0, -dx), ay = Math.max(0, -dy), bx = Math.max(0, dx), by = Math.max(0, dy);+ for (let y = 0; y < h; y++) {+ sa.data.set(a.data.subarray((y + ay) * a.width + ax, (y + ay) * a.width + ax + w), y * w);+ sb.data.set(b.data.subarray((y + by) * b.width + bx, (y + by) * b.width + bx + w), y * w);+ }+ return ssim(sa, sb, win);+}++/**+ * Structure score 0..1: SSIM over blurred grayscale at a fixed working width,+ * taking the best of a small translation search so a composition that sits a+ * few pixels off (a different masthead height, a scrollbar) is not read as a+ * different composition. Shifts up to ~4% of the width are forgiven; a moved+ * region is not.+ */+export function structureScore(imgA, imgB, workWidth = 256) {+ const h = Math.max(8, Math.round((imgA.height / imgA.width) * workWidth));+ const a = blurGray(toGray(resize(imgA, workWidth, h)), 2);+ const b = blurGray(toGray(resize(imgB, workWidth, h)), 2);+ const win = Math.min(8, Math.max(2, Math.floor(Math.min(workWidth, h) / 8)));+ let best = ssim(a, b, win);+ const maxShift = Math.max(2, Math.round(workWidth * 0.04));+ for (const dy of [-maxShift, -maxShift / 2, 0, maxShift / 2, maxShift]) {+ for (const dx of [-maxShift, -maxShift / 2, 0, maxShift / 2, maxShift]) {+ if (!dx && !dy) continue;+ best = Math.max(best, ssimShifted(a, b, Math.round(dx), Math.round(dy), win));+ }+ }+ return Math.max(0, Math.min(1, best));+}++// ---- color -----------------------------------------------------------------++function rgbToLab(r, g, b) {+ const lin = (c) => { c /= 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };+ const R = lin(r), G = lin(g), B = lin(b);+ const X = (R * 0.4124 + G * 0.3576 + B * 0.1805) / 0.95047;+ const Y = (R * 0.2126 + G * 0.7152 + B * 0.0722) / 1.0;+ const Z = (R * 0.0193 + G * 0.1192 + B * 0.9505) / 1.08883;+ const f = (t) => (t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116);+ const fx = f(X), fy = f(Y), fz = f(Z);+ return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];+}++export function deltaE(lab1, lab2) {+ return Math.hypot(lab1[0] - lab2[0], lab1[1] - lab2[1], lab1[2] - lab2[2]);+}++/** Quantized color histogram (4 bits per channel = 4096 bins), normalized. */+export function colorHistogram(img, sampleStep = 2) {+ const bins = new Float32Array(4096);+ let n = 0;+ for (let y = 0; y < img.height; y += sampleStep) {+ for (let x = 0; x < img.width; x += sampleStep) {+ const p = (y * img.width + x) * 4;+ if (img.data[p + 3] < 16) continue;+ const key = ((img.data[p] >> 4) << 8) | ((img.data[p + 1] >> 4) << 4) | (img.data[p + 2] >> 4);+ bins[key]++; n++;+ }+ }+ if (n) for (let i = 0; i < bins.length; i++) bins[i] /= n;+ return bins;+}++export function histogramIntersection(h1, h2) {+ let s = 0;+ for (let i = 0; i < h1.length; i++) s += Math.min(h1[i], h2[i]);+ return s;+}++/**+ * Dominant colors: merge histogram bins greedily by Lab distance into up to+ * `k` clusters and return them sorted by coverage.+ */+export function dominantColors(img, k = 6, sampleStep = 3) {+ const hist = colorHistogram(img, sampleStep);+ const entries = [];+ for (let i = 0; i < hist.length; i++) if (hist[i] > 0.0005) entries.push({ key: i, w: hist[i] });+ entries.sort((a, b) => b.w - a.w);+ const clusters = [];+ for (const e of entries) {+ const r = ((e.key >> 8) & 15) * 16 + 8, g = ((e.key >> 4) & 15) * 16 + 8, b = (e.key & 15) * 16 + 8;+ const lab = rgbToLab(r, g, b);+ let best = null, bestD = Infinity;+ for (const c of clusters) { const d = deltaE(c.lab, lab); if (d < bestD) { bestD = d; best = c; } }+ if (best && bestD < 14) {+ const tw = best.w + e.w;+ best.rgb = [(best.rgb[0] * best.w + r * e.w) / tw, (best.rgb[1] * best.w + g * e.w) / tw, (best.rgb[2] * best.w + b * e.w) / tw];+ best.lab = rgbToLab(...best.rgb); best.w = tw;+ } else clusters.push({ rgb: [r, g, b], lab, w: e.w });+ }+ clusters.sort((a, b) => b.w - a.w);+ const top = clusters.slice(0, k);+ const covered = top.reduce((s, c) => s + c.w, 0) || 1;+ return top.map((c) => ({ hex: toHex(c.rgb), coverage: +(c.w / covered).toFixed(4), lab: c.lab }));+}++export function toHex(rgb) {+ return '#' + rgb.map((v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('');+}++/**+ * Palette match 0..1: for each dominant comp color, coverage-weighted best+ * Lab match in the build's dominant set (dE 0 -> 1, dE >= 40 -> 0).+ */+export function paletteMatch(compColors, buildColors) {+ if (!compColors.length) return 1;+ let s = 0, wsum = 0;+ for (const c of compColors) {+ let best = Infinity;+ for (const b of buildColors) best = Math.min(best, deltaE(c.lab, b.lab));+ s += c.coverage * Math.max(0, 1 - best / 40); wsum += c.coverage;+ }+ return wsum ? s / wsum : 1;+}++/** Color score 0..1: blend of histogram intersection and dominant-palette match. */+export function colorScore(imgA, imgB) {+ const inter = histogramIntersection(colorHistogram(imgA), colorHistogram(imgB));+ const pm = paletteMatch(dominantColors(imgA), dominantColors(imgB));+ return { score: 0.35 * inter + 0.65 * pm, intersection: inter, paletteMatch: pm };+}++// ---- detail ----------------------------------------------------------------++/** Mean absolute gradient (Sobel-lite) per cell over a cols x rows grid. */+export function detailGrid(img, cols = 12, rows = 8, workWidth = 512) {+ const h = Math.max(rows, Math.round((img.height / img.width) * workWidth));+ const g = toGray(resize(img, workWidth, h));+ const grid = new Float32Array(cols * rows);+ const counts = new Float32Array(cols * rows);+ for (let y = 1; y < g.height - 1; y++) {+ const cy = Math.min(rows - 1, Math.floor((y / g.height) * rows));+ for (let x = 1; x < g.width - 1; x++) {+ const cx = Math.min(cols - 1, Math.floor((x / g.width) * cols));+ const i = y * g.width + x;+ const gx = Math.abs(g.data[i + 1] - g.data[i - 1]);+ const gy = Math.abs(g.data[i + g.width] - g.data[i - g.width]);+ grid[cy * cols + cx] += gx + gy; counts[cy * cols + cx]++;+ }+ }+ for (let i = 0; i < grid.length; i++) grid[i] = counts[i] ? grid[i] / counts[i] : 0;+ return { cols, rows, cells: grid };+}++/**+ * Detail score 0..1 and per-cell ratio. Cells where the comp is nearly flat+ * are ignored (nothing to lose); the score is the coverage-weighted mean of+ * min(1, build/comp) over cells with comp energy, so extra detail in the+ * build (invented chrome) is reported separately as `added`.+ */+export function detailScore(imgA, imgB, cols = 12, rows = 8) {+ const a = detailGrid(imgA, cols, rows), b = detailGrid(imgB, cols, rows);+ const floor = 1.5; // energy below this is a flat field at the 512px working width+ let s = 0, w = 0, added = 0, addedW = 0;+ const ratios = new Float32Array(cols * rows);+ for (let i = 0; i < a.cells.length; i++) {+ const ca = a.cells[i], cb = b.cells[i];+ ratios[i] = ca > floor ? cb / ca : (cb > floor ? Infinity : 1);+ if (ca > floor) { s += Math.min(1, cb / ca) * ca; w += ca; }+ if (cb > ca * 1.8 && cb > floor * 2) { added += 1; }+ addedW += 1;+ }+ return { score: w ? s / w : 1, addedFraction: addedW ? added / addedW : 0, comp: a, build: b, ratios };+}++// ---- pixel diff -----------------------------------------------------------++/** Per-pixel Lab-ish difference map (0..1) at a working width; blurred a little. */+export function diffMap(imgA, imgB, workWidth = 384) {+ const h = Math.max(8, Math.round((imgA.height / imgA.width) * workWidth));+ const a = resize(imgA, workWidth, h), b = resize(imgB, workWidth, h);+ const out = new Float32Array(workWidth * h);+ for (let i = 0, p = 0; i < out.length; i++, p += 4) {+ const dr = a.data[p] - b.data[p], dg = a.data[p + 1] - b.data[p + 1], db = a.data[p + 2] - b.data[p + 2];+ out[i] = Math.min(1, Math.sqrt(dr * dr + dg * dg + db * db) / 200);+ }+ return blurGray({ width: workWidth, height: h, data: out }, 1);+}++// ---- bands (horizontal layout structure) ---------------------------------++/**+ * Detect horizontal band boundaries: rows where the mean color changes+ * sharply. Returns normalized y positions (0..1) with strengths. This is the+ * "layout grid" read of a page: header / hero / index / footer as bands.+ */+export function horizontalBands(img, workWidth = 128, minGap = 0.02) {+ const h = Math.max(16, Math.round((img.height / img.width) * workWidth));+ const s = resize(img, workWidth, h);+ const rowMean = new Float32Array(h * 3);+ for (let y = 0; y < h; y++) {+ let r = 0, g = 0, b = 0;+ for (let x = 0; x < workWidth; x++) { const p = (y * workWidth + x) * 4; r += s.data[p]; g += s.data[p + 1]; b += s.data[p + 2]; }+ rowMean[y * 3] = r / workWidth; rowMean[y * 3 + 1] = g / workWidth; rowMean[y * 3 + 2] = b / workWidth;+ }+ const edges = [];+ for (let y = 1; y < h; y++) {+ const d = Math.hypot(rowMean[y * 3] - rowMean[(y - 1) * 3], rowMean[y * 3 + 1] - rowMean[(y - 1) * 3 + 1], rowMean[y * 3 + 2] - rowMean[(y - 1) * 3 + 2]);+ if (d > 18) edges.push({ y: y / h, strength: Math.min(1, d / 120) });+ }+ // merge close edges+ const merged = [];+ for (const e of edges) {+ const last = merged[merged.length - 1];+ if (last && e.y - last.y < minGap) { if (e.strength > last.strength) { last.y = e.y; last.strength = e.strength; } }+ else merged.push({ ...e });+ }+ return merged;+}++/** Band agreement 0..1: fraction of comp bands with a build band within tolerance, and vice versa. */+export function bandScore(bandsA, bandsB, tol = 0.04) {+ if (!bandsA.length && !bandsB.length) return 1;+ const match = (from, to) => from.filter((a) => to.some((b) => Math.abs(a.y - b.y) <= tol)).length;+ const recall = bandsA.length ? match(bandsA, bandsB) / bandsA.length : 1;+ const precision = bandsB.length ? match(bandsB, bandsA) / bandsB.length : 1;+ return 0.6 * recall + 0.4 * precision;+}diff --git a/skill/scripts/lib/png.mjs b/skill/scripts/lib/png.mjsnew file mode 100644index 000000000..faa8d45a9--- /dev/null+++ b/skill/scripts/lib/png.mjs@@ -0,0 +1,250 @@+/**+ * Dependency-free PNG decode/encode for the skill scripts.+ *+ * decodePng(buffer) -> { width, height, data } where data is RGBA8 (Uint8Array,+ * width*height*4). Handles every color type (0, 2, 3, 4, 6), bit depths 1-16+ * (16-bit is reduced to 8), all five filters, and Adam7 interlacing.+ *+ * encodePng({ width, height, data }) -> Buffer, RGBA8 in, 8-bit RGBA PNG out.+ *+ * Kept small on purpose: the skill scripts ship without npm dependencies, and+ * comps (gpt-image PNGs) and screenshots (Playwright / harness PNGs) are the+ * only formats the comp-fidelity tooling has to read.+ */+import zlib from 'node:zlib';++const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);++const crcTable = (() => {+ const t = new Uint32Array(256);+ for (let n = 0; n < 256; n++) {+ let c = n;+ for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;+ t[n] = c >>> 0;+ }+ return t;+})();++function crc32(data) {+ let c = 0xffffffff;+ for (let i = 0; i < data.length; i++) c = crcTable[(c ^ data[i]) & 0xff] ^ (c >>> 8);+ return (c ^ 0xffffffff) >>> 0;+}++export function isPng(buf) {+ return buf && buf.length > 8 && buf.subarray(0, 8).equals(SIGNATURE);+}++function readChunks(buf) {+ const chunks = [];+ let pos = 8;+ while (pos + 8 <= buf.length) {+ const length = buf.readUInt32BE(pos);+ const type = buf.toString('latin1', pos + 4, pos + 8);+ const data = buf.subarray(pos + 8, pos + 8 + length);+ chunks.push({ type, data });+ pos += 12 + length;+ if (type === 'IEND') break;+ }+ return chunks;+}++const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };++function paeth(a, b, c) {+ const p = a + b - c;+ const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);+ if (pa <= pb && pa <= pc) return a;+ if (pb <= pc) return b;+ return c;+}++/** Unfilter one pass of scanlines in place; returns the raw (unfiltered) bytes. */+function unfilter(raw, width, height, bpp, bitDepth, channels) {+ const stride = Math.ceil((width * channels * bitDepth) / 8);+ const out = new Uint8Array(stride * height);+ let inPos = 0;+ let prev = null;+ for (let y = 0; y < height; y++) {+ const filter = raw[inPos++];+ const line = out.subarray(y * stride, (y + 1) * stride);+ line.set(raw.subarray(inPos, inPos + stride));+ inPos += stride;+ switch (filter) {+ case 0: break;+ case 1: for (let i = bpp; i < stride; i++) line[i] = (line[i] + line[i - bpp]) & 0xff; break;+ case 2: if (prev) for (let i = 0; i < stride; i++) line[i] = (line[i] + prev[i]) & 0xff; break;+ case 3:+ for (let i = 0; i < stride; i++) {+ const left = i >= bpp ? line[i - bpp] : 0;+ const up = prev ? prev[i] : 0;+ line[i] = (line[i] + ((left + up) >> 1)) & 0xff;+ }+ break;+ case 4:+ for (let i = 0; i < stride; i++) {+ const left = i >= bpp ? line[i - bpp] : 0;+ const up = prev ? prev[i] : 0;+ const ul = prev && i >= bpp ? prev[i - bpp] : 0;+ line[i] = (line[i] + paeth(left, up, ul)) & 0xff;+ }+ break;+ default: throw new Error(`png: unknown filter ${filter} on row ${y}`);+ }+ prev = line;+ }+ return { bytes: out, stride, consumed: inPos };+}++/** Read sample `index` (0-based across the row) from a packed scanline. */+function sampleReader(bitDepth) {+ if (bitDepth === 8) return (line, i) => line[i];+ if (bitDepth === 16) return (line, i) => line[i * 2]; // high byte+ const perByte = 8 / bitDepth;+ const mask = (1 << bitDepth) - 1;+ const scale = 255 / mask;+ return (line, i) => {+ const byte = line[(i / perByte) | 0];+ const shift = 8 - bitDepth * ((i % perByte) + 1);+ return Math.round(((byte >> shift) & mask) * scale);+ };+}++function writePixels(dst, dstWidth, bytes, stride, passWidth, passHeight, colorType, bitDepth, palette, trns, mapX, mapY) {+ const channels = CHANNELS[colorType];+ const read = sampleReader(bitDepth);+ const rawIndex = bitDepth < 8 ? (line, i) => {+ const perByte = 8 / bitDepth;+ const mask = (1 << bitDepth) - 1;+ const byte = line[(i / perByte) | 0];+ const shift = 8 - bitDepth * ((i % perByte) + 1);+ return (byte >> shift) & mask;+ } : read;+ for (let y = 0; y < passHeight; y++) {+ const line = bytes.subarray(y * stride, (y + 1) * stride);+ const dy = mapY(y);+ for (let x = 0; x < passWidth; x++) {+ const dx = mapX(x);+ const o = (dy * dstWidth + dx) * 4;+ let r, g, b, a = 255;+ switch (colorType) {+ case 0: {+ r = g = b = read(line, x);+ if (trns && trns.gray === rawIndex(line, x)) a = 0;+ break;+ }+ case 2: {+ r = read(line, x * 3); g = read(line, x * 3 + 1); b = read(line, x * 3 + 2);+ break;+ }+ case 3: {+ const idx = rawIndex(line, x);+ r = palette[idx * 3]; g = palette[idx * 3 + 1]; b = palette[idx * 3 + 2];+ if (trns && trns.alpha && idx < trns.alpha.length) a = trns.alpha[idx];+ break;+ }+ case 4: {+ r = g = b = read(line, x * 2); a = read(line, x * 2 + 1);+ break;+ }+ case 6: {+ r = read(line, x * 4); g = read(line, x * 4 + 1); b = read(line, x * 4 + 2); a = read(line, x * 4 + 3);+ break;+ }+ default: throw new Error(`png: unsupported color type ${colorType}`);+ }+ dst[o] = r; dst[o + 1] = g; dst[o + 2] = b; dst[o + 3] = a;+ }+ }+ return channels;+}++export function decodePng(buf) {+ if (!isPng(buf)) throw new Error('png: not a PNG (bad signature)');+ const chunks = readChunks(buf);+ const ihdr = chunks.find((c) => c.type === 'IHDR');+ if (!ihdr) throw new Error('png: missing IHDR');+ const width = ihdr.data.readUInt32BE(0);+ const height = ihdr.data.readUInt32BE(4);+ const bitDepth = ihdr.data[8];+ const colorType = ihdr.data[9];+ const interlace = ihdr.data[12];+ const channels = CHANNELS[colorType];+ if (!channels) throw new Error(`png: unsupported color type ${colorType}`);+ const palChunk = chunks.find((c) => c.type === 'PLTE');+ const palette = palChunk ? palChunk.data : null;+ const trnsChunk = chunks.find((c) => c.type === 'tRNS');+ let trns = null;+ if (trnsChunk) {+ if (colorType === 3) trns = { alpha: trnsChunk.data };+ else if (colorType === 0) trns = { gray: trnsChunk.data.readUInt16BE(0) >> (bitDepth === 16 ? 8 : 0) };+ }+ const idat = Buffer.concat(chunks.filter((c) => c.type === 'IDAT').map((c) => c.data));+ const raw = zlib.inflateSync(idat);+ const bpp = Math.max(1, Math.ceil((channels * bitDepth) / 8));+ const data = new Uint8Array(width * height * 4);+ const text = {};+ for (const c of chunks) {+ if (c.type === 'tEXt') {+ const z = c.data.indexOf(0);+ if (z > 0) text[c.data.toString('latin1', 0, z)] = c.data.toString('utf8', z + 1);+ }+ }++ if (interlace === 0) {+ const { bytes, stride } = unfilter(raw, width, height, bpp, bitDepth, channels);+ writePixels(data, width, bytes, stride, width, height, colorType, bitDepth, palette, trns, (x) => x, (y) => y);+ } else {+ // Adam7+ const passes = [+ [0, 0, 8, 8], [4, 0, 8, 8], [0, 4, 4, 8], [2, 0, 4, 4], [0, 2, 2, 4], [1, 0, 2, 2], [0, 1, 1, 2],+ ];+ let offset = 0;+ for (const [sx, sy, dx, dy] of passes) {+ const pw = Math.ceil((width - sx) / dx);+ const ph = Math.ceil((height - sy) / dy);+ if (pw <= 0 || ph <= 0) continue;+ const { bytes, stride, consumed } = unfilter(raw.subarray(offset), pw, ph, bpp, bitDepth, channels);+ offset += consumed;+ writePixels(data, width, bytes, stride, pw, ph, colorType, bitDepth, palette, trns, (x) => sx + x * dx, (y) => sy + y * dy);+ }+ }+ return { width, height, data, text };+}++function chunk(type, data) {+ const len = Buffer.alloc(4);+ len.writeUInt32BE(data.length, 0);+ const typeBuf = Buffer.from(type, 'latin1');+ const crc = Buffer.alloc(4);+ crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);+ return Buffer.concat([len, typeBuf, data, crc]);+}++/**+ * Encode RGBA8 to PNG. `text` (optional) is a map of tEXt keyword -> value.+ * Uses filter type 0 on every row: comps and screenshots compress fine and the+ * encoder stays trivial.+ */+export function encodePng({ width, height, data }, { text = null, level = 6 } = {}) {+ if (data.length !== width * height * 4) throw new Error(`png: data length ${data.length} != ${width}x${height}x4`);+ const stride = width * 4;+ const raw = Buffer.alloc((stride + 1) * height);+ for (let y = 0; y < height; y++) {+ raw[y * (stride + 1)] = 0;+ raw.set(data.subarray(y * stride, (y + 1) * stride), y * (stride + 1) + 1);+ }+ const ihdr = Buffer.alloc(13);+ ihdr.writeUInt32BE(width, 0);+ ihdr.writeUInt32BE(height, 4);+ ihdr[8] = 8; ihdr[9] = 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0;+ const parts = [SIGNATURE, chunk('IHDR', ihdr)];+ if (text) {+ for (const [k, v] of Object.entries(text)) {+ parts.push(chunk('tEXt', Buffer.concat([Buffer.from(k, 'latin1'), Buffer.from([0]), Buffer.from(String(v), 'utf8')])));+ }+ }+ parts.push(chunk('IDAT', zlib.deflateSync(raw, { level })));+ parts.push(chunk('IEND', Buffer.alloc(0)));+ return Buffer.concat(parts);+}diff --git a/skill/scripts/lib/raster.mjs b/skill/scripts/lib/raster.mjsnew file mode 100644index 000000000..2d3e0ae3a--- /dev/null+++ b/skill/scripts/lib/raster.mjs@@ -0,0 +1,194 @@+/**+ * Small RGBA raster toolkit shared by the comp-fidelity scripts: crop, resize+ * (area-averaging down, bilinear up), composite, fills, rectangles, and a+ * bitmap-font label so composites can be captioned without a font stack.+ *+ * An image is `{ width, height, data }` with RGBA8 data (Uint8Array).+ */++export function createImage(width, height, fill = [0, 0, 0, 0]) {+ const data = new Uint8Array(width * height * 4);+ if (fill[0] || fill[1] || fill[2] || fill[3]) {+ for (let i = 0; i < data.length; i += 4) { data[i] = fill[0]; data[i + 1] = fill[1]; data[i + 2] = fill[2]; data[i + 3] = fill[3]; }+ }+ return { width, height, data };+}++export function clampRect(img, x, y, w, h) {+ const x0 = Math.max(0, Math.min(img.width, Math.round(x)));+ const y0 = Math.max(0, Math.min(img.height, Math.round(y)));+ const x1 = Math.max(x0, Math.min(img.width, Math.round(x + w)));+ const y1 = Math.max(y0, Math.min(img.height, Math.round(y + h)));+ return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };+}++export function crop(img, x, y, w, h) {+ const r = clampRect(img, x, y, w, h);+ const out = createImage(Math.max(1, r.w), Math.max(1, r.h));+ for (let yy = 0; yy < r.h; yy++) {+ const src = ((r.y + yy) * img.width + r.x) * 4;+ out.data.set(img.data.subarray(src, src + r.w * 4), yy * out.width * 4);+ }+ return out;+}++/** Resize with area averaging when shrinking and bilinear when growing. */+export function resize(img, width, height) {+ width = Math.max(1, Math.round(width));+ height = Math.max(1, Math.round(height));+ if (width === img.width && height === img.height) return { width, height, data: new Uint8Array(img.data) };+ const out = createImage(width, height);+ const sx = img.width / width, sy = img.height / height;+ if (sx >= 1 && sy >= 1) {+ for (let y = 0; y < height; y++) {+ const y0 = Math.floor(y * sy), y1 = Math.min(img.height, Math.max(y0 + 1, Math.floor((y + 1) * sy)));+ for (let x = 0; x < width; x++) {+ const x0 = Math.floor(x * sx), x1 = Math.min(img.width, Math.max(x0 + 1, Math.floor((x + 1) * sx)));+ let r = 0, g = 0, b = 0, a = 0, n = 0;+ for (let yy = y0; yy < y1; yy++) {+ let p = (yy * img.width + x0) * 4;+ for (let xx = x0; xx < x1; xx++, p += 4) { r += img.data[p]; g += img.data[p + 1]; b += img.data[p + 2]; a += img.data[p + 3]; n++; }+ }+ const o = (y * width + x) * 4;+ out.data[o] = r / n; out.data[o + 1] = g / n; out.data[o + 2] = b / n; out.data[o + 3] = a / n;+ }+ }+ return out;+ }+ for (let y = 0; y < height; y++) {+ const fy = Math.min(img.height - 1, (y + 0.5) * sy - 0.5);+ const y0 = Math.max(0, Math.floor(fy)), y1 = Math.min(img.height - 1, y0 + 1), wy = fy - y0;+ for (let x = 0; x < width; x++) {+ const fx = Math.min(img.width - 1, (x + 0.5) * sx - 0.5);+ const x0 = Math.max(0, Math.floor(fx)), x1 = Math.min(img.width - 1, x0 + 1), wx = fx - x0;+ const o = (y * width + x) * 4;+ for (let c = 0; c < 4; c++) {+ const p00 = img.data[(y0 * img.width + x0) * 4 + c], p10 = img.data[(y0 * img.width + x1) * 4 + c];+ const p01 = img.data[(y1 * img.width + x0) * 4 + c], p11 = img.data[(y1 * img.width + x1) * 4 + c];+ out.data[o + c] = (p00 * (1 - wx) + p10 * wx) * (1 - wy) + (p01 * (1 - wx) + p11 * wx) * wy;+ }+ }+ }+ return out;+}++/** Scale to fit inside (maxW x maxH) preserving aspect; never upscale unless `allowUpscale`. */+export function fit(img, maxW, maxH, allowUpscale = false) {+ const s = Math.min(maxW / img.width, maxH / img.height);+ if (s >= 1 && !allowUpscale) return img;+ return resize(img, img.width * s, img.height * s);+}++/** Alpha-composite `src` onto `dst` at (x, y). */+export function blit(dst, src, x, y) {+ x = Math.round(x); y = Math.round(y);+ for (let yy = 0; yy < src.height; yy++) {+ const dy = y + yy; if (dy < 0 || dy >= dst.height) continue;+ for (let xx = 0; xx < src.width; xx++) {+ const dx = x + xx; if (dx < 0 || dx >= dst.width) continue;+ const s = (yy * src.width + xx) * 4, d = (dy * dst.width + dx) * 4;+ const a = src.data[s + 3] / 255;+ if (a >= 1) { dst.data[d] = src.data[s]; dst.data[d + 1] = src.data[s + 1]; dst.data[d + 2] = src.data[s + 2]; dst.data[d + 3] = 255; continue; }+ if (a <= 0) continue;+ const da = dst.data[d + 3] / 255, oa = a + da * (1 - a);+ for (let c = 0; c < 3; c++) dst.data[d + c] = (src.data[s + c] * a + dst.data[d + c] * da * (1 - a)) / (oa || 1);+ dst.data[d + 3] = oa * 255;+ }+ }+}++export function fillRect(img, x, y, w, h, rgba) {+ const r = clampRect(img, x, y, w, h);+ const a = (rgba[3] ?? 255) / 255;+ for (let yy = r.y; yy < r.y + r.h; yy++) {+ for (let xx = r.x; xx < r.x + r.w; xx++) {+ const o = (yy * img.width + xx) * 4;+ if (a >= 1) { img.data[o] = rgba[0]; img.data[o + 1] = rgba[1]; img.data[o + 2] = rgba[2]; img.data[o + 3] = 255; }+ else { for (let c = 0; c < 3; c++) img.data[o + c] = rgba[c] * a + img.data[o + c] * (1 - a); img.data[o + 3] = Math.max(img.data[o + 3], a * 255); }+ }+ }+}++export function strokeRect(img, x, y, w, h, rgba, thickness = 2) {+ fillRect(img, x, y, w, thickness, rgba);+ fillRect(img, x, y + h - thickness, w, thickness, rgba);+ fillRect(img, x, y, thickness, h, rgba);+ fillRect(img, x + w - thickness, y, thickness, h, rgba);+}++// 5x7 bitmap font, uppercase + digits + a little punctuation. Enough for labels.+const GLYPHS = {+ A: ['01110', '10001', '10001', '11111', '10001', '10001', '10001'],+ B: ['11110', '10001', '10001', '11110', '10001', '10001', '11110'],+ C: ['01110', '10001', '10000', '10000', '10000', '10001', '01110'],+ D: ['11110', '10001', '10001', '10001', '10001', '10001', '11110'],+ E: ['11111', '10000', '10000', '11110', '10000', '10000', '11111'],+ F: ['11111', '10000', '10000', '11110', '10000', '10000', '10000'],+ G: ['01110', '10001', '10000', '10111', '10001', '10001', '01111'],+ H: ['10001', '10001', '10001', '11111', '10001', '10001', '10001'],+ I: ['11111', '00100', '00100', '00100', '00100', '00100', '11111'],+ J: ['00111', '00010', '00010', '00010', '00010', '10010', '01100'],+ K: ['10001', '10010', '10100', '11000', '10100', '10010', '10001'],+ L: ['10000', '10000', '10000', '10000', '10000', '10000', '11111'],+ M: ['10001', '11011', '10101', '10101', '10001', '10001', '10001'],+ N: ['10001', '10001', '11001', '10101', '10011', '10001', '10001'],+ O: ['01110', '10001', '10001', '10001', '10001', '10001', '01110'],+ P: ['11110', '10001', '10001', '11110', '10000', '10000', '10000'],+ Q: ['01110', '10001', '10001', '10001', '10101', '10010', '01101'],+ R: ['11110', '10001', '10001', '11110', '10100', '10010', '10001'],+ S: ['01111', '10000', '10000', '01110', '00001', '00001', '11110'],+ T: ['11111', '00100', '00100', '00100', '00100', '00100', '00100'],+ U: ['10001', '10001', '10001', '10001', '10001', '10001', '01110'],+ V: ['10001', '10001', '10001', '10001', '10001', '01010', '00100'],+ W: ['10001', '10001', '10001', '10101', '10101', '10101', '01010'],+ X: ['10001', '10001', '01010', '00100', '01010', '10001', '10001'],+ Y: ['10001', '10001', '01010', '00100', '00100', '00100', '00100'],+ Z: ['11111', '00001', '00010', '00100', '01000', '10000', '11111'],+ 0: ['01110', '10001', '10011', '10101', '11001', '10001', '01110'],+ 1: ['00100', '01100', '00100', '00100', '00100', '00100', '01110'],+ 2: ['01110', '10001', '00001', '00010', '00100', '01000', '11111'],+ 3: ['11110', '00001', '00001', '01110', '00001', '00001', '11110'],+ 4: ['00010', '00110', '01010', '10010', '11111', '00010', '00010'],+ 5: ['11111', '10000', '11110', '00001', '00001', '10001', '01110'],+ 6: ['00110', '01000', '10000', '11110', '10001', '10001', '01110'],+ 7: ['11111', '00001', '00010', '00100', '01000', '01000', '01000'],+ 8: ['01110', '10001', '10001', '01110', '10001', '10001', '01110'],+ 9: ['01110', '10001', '10001', '01111', '00001', '00010', '01100'],+ ' ': ['00000', '00000', '00000', '00000', '00000', '00000', '00000'],+ '.': ['00000', '00000', '00000', '00000', '00000', '01100', '01100'],+ ':': ['00000', '01100', '01100', '00000', '01100', '01100', '00000'],+ '-': ['00000', '00000', '00000', '11111', '00000', '00000', '00000'],+ '/': ['00001', '00010', '00010', '00100', '01000', '01000', '10000'],+ '%': ['11001', '11010', '00010', '00100', '01000', '01011', '10011'],+ '(': ['00010', '00100', '01000', '01000', '01000', '00100', '00010'],+ ')': ['01000', '00100', '00010', '00010', '00010', '00100', '01000'],+ '#': ['01010', '01010', '11111', '01010', '11111', '01010', '01010'],+ '_': ['00000', '00000', '00000', '00000', '00000', '00000', '11111'],+ '?': ['01110', '10001', '00001', '00010', '00100', '00000', '00100'],+ '=': ['00000', '00000', '11111', '00000', '11111', '00000', '00000'],+ '+': ['00000', '00100', '00100', '11111', '00100', '00100', '00000'],+ ',': ['00000', '00000', '00000', '00000', '01100', '00100', '01000'],+};++export function textWidth(text, scale = 2) {+ return text.length * 6 * scale;+}++/** Draw uppercase bitmap text. Returns width drawn. */+export function drawText(img, text, x, y, rgba, scale = 2) {+ let cx = Math.round(x);+ for (const chRaw of String(text).toUpperCase()) {+ const g = GLYPHS[chRaw] || GLYPHS['?'];+ for (let r = 0; r < 7; r++) for (let c = 0; c < 5; c++) if (g[r][c] === '1') fillRect(img, cx + c * scale, y + r * scale, scale, scale, rgba);+ cx += 6 * scale;+ }+ return cx - x;+}++/** Draw a label with a background pill. */+export function drawLabel(img, text, x, y, { fg = [255, 255, 255, 255], bg = [0, 0, 0, 220], scale = 2, pad = 4 } = {}) {+ const w = textWidth(text, scale) + pad * 2, h = 7 * scale + pad * 2;+ fillRect(img, x, y, w, h, bg);+ drawText(img, text, x + pad, y + pad, fg, scale);+ return { w, h };+}diff --git a/tests/build-phase.test.mjs b/tests/build-phase.test.mjsnew file mode 100644index 000000000..b175979c7--- /dev/null+++ b/tests/build-phase.test.mjs@@ -0,0 +1,168 @@+import { describe, it, before, after } from 'node:test';+import assert from 'node:assert/strict';+import { spawnSync } from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++import { encodePng } from '../skill/scripts/lib/png.mjs';+import { createImage, fillRect, blit, resize } from '../skill/scripts/lib/raster.mjs';+import { gridToBox, measureRegions, platePrompt } from '../skill/scripts/comp-spec.mjs';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const SPEC_SCRIPT = path.join(ROOT, 'skill', 'scripts', 'comp-spec.mjs');+const PHASE_SCRIPT = path.join(ROOT, 'skill', 'scripts', 'build-phase.mjs');++function lcg(seed) { let s = seed >>> 0; return () => ((s = (s * 1664525 + 1013904223) >>> 0) / 0xffffffff); }++function makeComp(w = 640, h = 400) {+ const img = createImage(w, h, [240, 237, 226, 255]);+ fillRect(img, 0, 0, w, 40, [19, 33, 48, 255]);+ fillRect(img, 20, 60, 220, 20, [19, 33, 48, 255]);+ fillRect(img, 20, 90, 180, 20, [19, 33, 48, 255]);+ const rnd = lcg(3);+ for (let y = 40; y < 200; y++) for (let x = 320; x < 640; x++) {+ const v = 100 + Math.floor(rnd() * 140);+ const p = (y * w + x) * 4; img.data[p] = v; img.data[p + 1] = v; img.data[p + 2] = v;+ }+ for (let i = 0; i < 3; i++) { fillRect(img, 0, 220 + i * 50, w, 1, [19, 33, 48, 255]); fillRect(img, 20, 232 + i * 50, 300, 12, [19, 33, 48, 255]); }+ return img;+}++function run(script, args, cwd) {+ return spawnSync(process.execPath, [script, ...args], { cwd, encoding: 'utf8' });+}++describe('comp-spec', () => {+ it('parses grid spans into normalized boxes', () => {+ assert.deepEqual(gridToBox('A0:A0'), { x: 0, y: 0, w: 0.1, h: 0.1 });+ assert.deepEqual(gridToBox('E0:J4'), { x: 0.4, y: 0, w: 0.6, h: 0.5 });+ assert.deepEqual(gridToBox('j4:e0'), { x: 0.4, y: 0, w: 0.6, h: 0.5 });+ assert.throws(() => gridToBox('K0:A1'));+ });++ it('measures regions with palette, pixel box, medium, and plate path', () => {+ const comp = makeComp();+ const spec = measureRegions(comp, { regions: [+ { id: 'masthead', kind: 'chrome', grid: 'A0:J0' },+ { id: 'art', kind: 'plate', grid: 'F1:J4', note: 'noise plate' },+ ] }, 'comp.png');+ assert.equal(spec.regions.length, 2);+ const art = spec.regions.find((r) => r.id === 'art');+ assert.equal(art.medium, 'raster');+ assert.equal(art.plate, path.join('assets', 'plates', 'art.png'));+ assert.equal(art.px.x, 320);+ assert.ok(art.palette.length > 0);+ assert.equal(spec.regions[0].medium, 'semantic');+ assert.equal(spec.orientation, 'landscape');+ assert.match(platePrompt(spec, art), /noise plate/);+ });++ it('rejects duplicate ids and missing ids', () => {+ const comp = makeComp();+ assert.throws(() => measureRegions(comp, { regions: [{ id: 'a', grid: 'A0:A0' }, { id: 'a', grid: 'B0:B0' }] }, 'c.png'), /duplicate/);+ assert.throws(() => measureRegions(comp, { regions: [{ grid: 'A0:A0' }] }, 'c.png'), /id/);+ });+});++describe('build-phase state machine (CLI)', () => {+ let dir;+ before(() => {+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'build-phase-'));+ fs.writeFileSync(path.join(dir, 'comp.png'), encodePng(makeComp()));+ fs.writeFileSync(path.join(dir, 'regions.json'), JSON.stringify({ regions: [+ { id: 'masthead', kind: 'chrome', grid: 'A0:J0' },+ { id: 'headline', kind: 'text', grid: 'A1:D2' },+ { id: 'art', kind: 'plate', grid: 'F1:J4', note: 'noise plate' },+ { id: 'list', kind: 'control', grid: 'A5:J9' },+ ] }));+ });+ after(() => { try { fs.rmSync(dir, { recursive: true, force: true }); } catch {} });++ it('start writes state at spec and prints NEXT', () => {+ const res = run(PHASE_SCRIPT, ['start', '--comp', 'comp.png'], dir);+ assert.equal(res.status, 0, res.stderr);+ assert.match(res.stdout, /BUILD-PHASE SPEC/);+ assert.match(res.stdout, /NEXT Measure the comp/);+ assert.ok(fs.existsSync(path.join(dir, '.impeccable', 'build', 'state.json')));+ });++ it('spec gate fails without a spec, passes once comp-spec wrote one', () => {+ let res = run(PHASE_SCRIPT, ['advance'], dir);+ assert.equal(res.status, 2);+ assert.match(res.stdout, /GATE SPEC FAILED/);+ res = run(SPEC_SCRIPT, ['--comp', 'comp.png', '--grid'], dir);+ assert.equal(res.status, 0, res.stderr);+ assert.ok(fs.existsSync(path.join(dir, '.impeccable', 'build', 'comp-grid.png')));+ res = run(SPEC_SCRIPT, ['--comp', 'comp.png', '--regions', 'regions.json'], dir);+ assert.equal(res.status, 0, res.stderr);+ assert.match(res.stdout, /PLATES 1 to produce: art/);+ res = run(PHASE_SCRIPT, ['advance'], dir);+ assert.equal(res.status, 0, res.stdout + res.stderr);+ assert.match(res.stdout, /ADVANCED spec -> plates/);+ });++ it('plates gate names the missing plate, rejects a comp-size crop, accepts a 2x plate', () => {+ let res = run(PHASE_SCRIPT, ['advance'], dir);+ assert.equal(res.status, 2);+ assert.match(res.stdout, /plate missing for art/);+ // comp-size crop: too small+ res = run(SPEC_SCRIPT, ['--crop', 'art', '--out', 'assets/plates/art.png'], dir);+ assert.equal(res.status, 0, res.stderr);+ res = run(PHASE_SCRIPT, ['advance'], dir);+ assert.equal(res.status, 2);+ assert.match(res.stdout, /needs at least 1.5x/);+ // 2x crop passes size and similarity+ res = run(SPEC_SCRIPT, ['--crop', 'art', '--scale', '2', '--out', 'assets/plates/art.png'], dir);+ assert.equal(res.status, 0, res.stderr);+ res = run(PHASE_SCRIPT, ['advance'], dir);+ assert.equal(res.status, 0, res.stdout);+ assert.match(res.stdout, /ADVANCED plates -> hero/);+ });++ it('hero gate fails on a flat build and passes on a faithful one, recording attempts', () => {+ const comp = makeComp();+ const flat = createImage(comp.width, comp.height, [240, 237, 226, 255]);+ fillRect(flat, 0, 0, comp.width, 40, [19, 33, 48, 255]);+ fs.mkdirSync(path.join(dir, '.impeccable', 'review'), { recursive: true });+ fs.writeFileSync(path.join(dir, '.impeccable', 'review', 'hero-repro.png'), encodePng(flat));+ let res = run(PHASE_SCRIPT, ['advance'], dir);+ assert.equal(res.status, 2, res.stdout);+ assert.match(res.stdout, /GATE HERO FAILED/);+ assert.match(res.stdout, /region art is missing/);+ assert.ok(fs.existsSync(path.join(dir, '.impeccable', 'review', 'diff', 'hero', 'side-by-side.png')));+ // faithful: the comp shifted by a few px, captured at 1.5x width+ const shifted = createImage(comp.width, comp.height, [240, 237, 226, 255]);+ blit(shifted, comp, 3, 2);+ fs.writeFileSync(path.join(dir, '.impeccable', 'review', 'hero-repro.png'), encodePng(resize(shifted, comp.width * 1.5, comp.height * 1.5)));+ res = run(PHASE_SCRIPT, ['advance'], dir);+ assert.equal(res.status, 0, res.stdout);+ assert.match(res.stdout, /ADVANCED hero -> sections/);+ const state = JSON.parse(fs.readFileSync(path.join(dir, '.impeccable', 'build', 'state.json'), 'utf8'));+ assert.equal(state.phases.hero.attempts, 2);+ assert.ok(state.phases.hero.gate.score >= 0.72);+ });++ it('later phases advance without a gate; force is recorded; finish records the disposition', () => {+ for (const from of ['sections', 'motion']) {+ const res = run(PHASE_SCRIPT, ['advance'], dir);+ assert.equal(res.status, 0, res.stdout);+ assert.match(res.stdout, new RegExp(`ADVANCED ${from}`));+ }+ let res = run(PHASE_SCRIPT, ['advance', '--force', '--reason', 'test'], dir);+ assert.equal(res.status, 0);+ res = run(PHASE_SCRIPT, ['finish', '--disposition', 'fix'], dir);+ assert.equal(res.status, 0);+ assert.match(res.stdout, /finish fix/);+ res = run(PHASE_SCRIPT, ['status', '--json'], dir);+ const state = JSON.parse(res.stdout);+ assert.equal(state.phase, 'review');+ assert.equal(state.finish.disposition, 'fix');+ });++ it('refuses a bad disposition and an unknown command', () => {+ assert.equal(run(PHASE_SCRIPT, ['finish', '--disposition', 'great'], dir).status, 1);+ assert.equal(run(PHASE_SCRIPT, ['dance'], dir).status, 1);+ });+});diff --git a/tests/comp-diff.test.mjs b/tests/comp-diff.test.mjsnew file mode 100644index 000000000..1fdce1921--- /dev/null+++ b/tests/comp-diff.test.mjs@@ -0,0 +1,225 @@+import { describe, it, before } from 'node:test';+import assert from 'node:assert/strict';+import { spawnSync } from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++import { decodePng, encodePng } from '../skill/scripts/lib/png.mjs';+import { createImage, fillRect, blit, crop, resize, drawText } from '../skill/scripts/lib/raster.mjs';+import { compare, verdictFor, alignBuild } from '../skill/scripts/comp-diff.mjs';+import { dominantColors, structureScore, detailScore } from '../skill/scripts/lib/image-metrics.mjs';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const SCRIPT = path.join(ROOT, 'skill', 'scripts', 'comp-diff.mjs');++// A synthetic "comp": bone ground, navy masthead, a red-gutter table, and a+// noisy "illustration" region on the right of the fold. Deterministic noise.+function lcg(seed) { let s = seed >>> 0; return () => ((s = (s * 1664525 + 1013904223) >>> 0) / 0xffffffff); }++function makeComp(w = 768, h = 512) {+ const img = createImage(w, h, [240, 237, 226, 255]);+ fillRect(img, 0, 0, w, 32, [19, 33, 48, 255]); // masthead+ drawText(img, 'CARBURETOR CLUB', 12, 8, [240, 237, 226, 255], 2);+ // headline block+ fillRect(img, 24, 70, 280, 22, [19, 33, 48, 255]);+ fillRect(img, 24, 100, 240, 22, [19, 33, 48, 255]);+ fillRect(img, 24, 136, 90, 4, [176, 40, 32, 255]);+ // illustration: high-frequency noise plate+ const rnd = lcg(7);+ for (let y = 48; y < 240; y++) for (let x = 340; x < 740; x++) {+ const v = 120 + Math.floor(rnd() * 120);+ const p = (y * w + x) * 4; img.data[p] = v; img.data[p + 1] = v; img.data[p + 2] = v + 10;+ }+ // table with red gutter+ fillRect(img, 0, 260, w, 2, [19, 33, 48, 255]);+ for (let i = 0; i < 3; i++) {+ const y = 270 + i * 60;+ fillRect(img, 0, y, 10, 50, i === 0 ? [176, 40, 32, 255] : [19, 33, 48, 255]);+ fillRect(img, 30, y + 10, 300, 14, [19, 33, 48, 255]);+ fillRect(img, 30, y + 30, 200, 8, [120, 120, 120, 255]);+ fillRect(img, 0, y + 56, w, 1, [19, 33, 48, 255]);+ }+ // CTA+ fillRect(img, 24, 460, 160, 36, [19, 33, 48, 255]);+ return img;+}++function flattenIllustration(comp) {+ const img = { ...comp, data: new Uint8Array(comp.data) };+ fillRect(img, 340, 48, 400, 192, [200, 200, 205, 255]); // a flat gray box where the plate was+ return img;+}++function recolor(comp) {+ const img = { ...comp, data: new Uint8Array(comp.data) };+ for (let i = 0; i < img.data.length; i += 4) {+ if (img.data[i] > 220 && img.data[i + 1] > 210) { img.data[i] = 20; img.data[i + 1] = 40; img.data[i + 2] = 60; }+ }+ return img;+}++function shifted(comp, dx, dy) {+ const img = createImage(comp.width, comp.height, [240, 237, 226, 255]);+ blit(img, comp, dx, dy);+ return img;+}++function tallPage(comp) {+ // a full-page screenshot: comp on top, then more page below+ const img = createImage(comp.width, comp.height * 3, [240, 237, 226, 255]);+ blit(img, comp, 0, 0);+ fillRect(img, 0, comp.height + 40, comp.width, 200, [19, 33, 48, 255]);+ return img;+}++const SPEC = {+ regions: [+ { id: 'masthead', kind: 'control', box: { x: 0, y: 0, w: 1, h: 32 / 512 } },+ { id: 'headline', kind: 'text', box: { x: 0.02, y: 60 / 512, w: 0.4, h: 100 / 512 } },+ { id: 'plate', kind: 'plate', box: { x: 340 / 768, y: 48 / 512, w: 400 / 768, h: 192 / 512 } },+ { id: 'table', kind: 'control', box: { x: 0, y: 260 / 512, w: 1, h: 190 / 512 } },+ ],+};++describe('png codec', () => {+ it('round-trips RGBA through encode/decode', () => {+ const img = createImage(20, 10, [10, 20, 30, 255]);+ img.data.set([200, 100, 50, 128], (2 * 20 + 2) * 4);+ const back = decodePng(encodePng(img, { text: { 'impeccable:prompt': 'hello' } }));+ assert.equal(back.width, 20); assert.equal(back.height, 10);+ assert.deepEqual([...back.data.subarray(0, 4)], [10, 20, 30, 255]);+ assert.deepEqual([...back.data.subarray((2 * 20 + 2) * 4, (2 * 20 + 2) * 4 + 4)], [200, 100, 50, 128]);+ assert.equal(back.text['impeccable:prompt'], 'hello');+ });++ it('decodes a real gpt-image / Playwright style PNG when one is on disk (skips otherwise)', () => {+ const sample = path.join(ROOT, 'tests', 'fixtures', 'comp-fidelity', 'sample.png');+ if (!fs.existsSync(sample)) return;+ const img = decodePng(fs.readFileSync(sample));+ assert.ok(img.width > 0 && img.height > 0);+ });+});++describe('image metrics', () => {+ const comp = makeComp();+ it('identity scores 1', () => {+ assert.ok(structureScore(comp, comp) > 0.999);+ assert.ok(detailScore(comp, comp).score > 0.999);+ });+ it('dominant colors find the ground and the ink', () => {+ const cols = dominantColors(comp).map((c) => c.hex);+ assert.ok(cols.some((h) => h.startsWith('#f') || h.startsWith('#e')), `ground missing in ${cols}`);+ assert.ok(cols.some((h) => h.startsWith('#1') || h.startsWith('#0') || h.startsWith('#2')), `ink missing in ${cols}`);+ });+ it('a flattened plate loses detail', () => {+ const d = detailScore(comp, flattenIllustration(comp));+ assert.ok(d.score < 0.85, `expected detail loss, got ${d.score}`);+ });+});++describe('comp-diff compare', () => {+ const comp = makeComp();++ it('scores the comp against itself as a match everywhere', () => {+ const r = compare({ comp, build: comp, spec: SPEC });+ assert.equal(r.whole.overall, 1);+ for (const region of r.regions) assert.equal(region.verdict, 'match', region.id);+ });++ it('forgives a small translation', () => {+ const r = compare({ comp, build: shifted(comp, 6, 4), spec: SPEC });+ assert.ok(r.whole.overall >= 0.8, `overall ${r.whole.overall}`);+ assert.equal(verdictFor(r.whole), 'match');+ });++ it('reads the top of a full-page screenshot as the first viewport', () => {+ const r = compare({ comp, build: tallPage(comp), spec: SPEC });+ assert.equal(r.aligned.height, comp.height);+ assert.ok(r.whole.overall > 0.95, `overall ${r.whole.overall}`);+ });++ it('flags a flattened plate region as missing while the rest matches', () => {+ const r = compare({ comp, build: flattenIllustration(comp), spec: SPEC });+ const plate = r.regions.find((x) => x.id === 'plate');+ assert.equal(plate.verdict, 'missing');+ assert.equal(r.regions.find((x) => x.id === 'table').verdict, 'match');+ assert.equal(r.regions.find((x) => x.id === 'masthead').verdict, 'match');+ });++ it('fails a recolored page on color and structure', () => {+ const r = compare({ comp, build: recolor(comp), spec: SPEC });+ assert.ok(r.whole.color < 0.7, `color ${r.whole.color}`);+ assert.ok(r.whole.overall < 0.6, `overall ${r.whole.overall}`);+ assert.notEqual(verdictFor(r.whole), 'match');+ });++ it('derives band regions when no spec is given', () => {+ const r = compare({ comp, build: comp });+ assert.ok(r.regions.length >= 2);+ assert.ok(r.regions.every((x) => x.kind === 'band'));+ });++ it('pads a shorter build with white so a truncated page reads as missing content', () => {+ const half = crop(comp, 0, 0, comp.width, comp.height / 2);+ const aligned = alignBuild(comp, half);+ assert.equal(aligned.height, comp.height);+ const r = compare({ comp, build: half, spec: SPEC });+ assert.notEqual(r.regions.find((x) => x.id === 'table').verdict, 'match');+ });++ it('scales a build captured at a different width onto the comp', () => {+ const wide = resize(comp, comp.width * 1.5, comp.height * 1.5);+ const r = compare({ comp, build: wide, spec: SPEC });+ assert.ok(r.whole.overall > 0.9, `overall ${r.whole.overall}`);+ });+});++describe('comp-diff CLI', () => {+ let dir;+ before(() => {+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'comp-diff-'));+ const comp = makeComp();+ fs.writeFileSync(path.join(dir, 'comp.png'), encodePng(comp));+ fs.writeFileSync(path.join(dir, 'flat.png'), encodePng(flattenIllustration(comp)));+ fs.writeFileSync(path.join(dir, 'spec.json'), JSON.stringify(SPEC));+ });++ it('writes side-by-side, heatmap, region pairs, and report.json', () => {+ const out = path.join(dir, 'diff');+ const res = spawnSync(process.execPath, [SCRIPT, '--comp', path.join(dir, 'comp.png'), '--build', path.join(dir, 'flat.png'), '--spec', path.join(dir, 'spec.json'), '--out-dir', out], { encoding: 'utf8' });+ assert.equal(res.status, 0, res.stderr + res.stdout);+ assert.match(res.stdout, /^COMP-DIFF/m);+ assert.match(res.stdout, /REGION plate\s+missing/);+ for (const f of ['side-by-side.png', 'heatmap.png', 'report.json', path.join('regions', 'plate.png')]) {+ assert.ok(fs.existsSync(path.join(out, f)), `${f} missing`);+ }+ const report = JSON.parse(fs.readFileSync(path.join(out, 'report.json'), 'utf8'));+ assert.equal(report.tool, 'comp-diff');+ assert.equal(report.regions.length, 4);+ assert.ok(report.palette.comp.length > 0);+ // artifacts decode+ const side = decodePng(fs.readFileSync(path.join(out, 'side-by-side.png')));+ assert.ok(side.width > 768);+ });++ it('exits 3 below --threshold and prints the instruction', () => {+ const res = spawnSync(process.execPath, [SCRIPT, '--comp', path.join(dir, 'comp.png'), '--build', path.join(dir, 'flat.png'), '--no-files', '--threshold', '0.99'], { encoding: 'utf8' });+ assert.equal(res.status, 3);+ assert.match(res.stdout, /BELOW THRESHOLD/);+ });++ it('--json prints the report', () => {+ const res = spawnSync(process.execPath, [SCRIPT, '--comp', path.join(dir, 'comp.png'), '--build', path.join(dir, 'comp.png'), '--no-files', '--json'], { encoding: 'utf8' });+ assert.equal(res.status, 0);+ const report = JSON.parse(res.stdout);+ assert.equal(report.verdict, 'match');+ });++ it('exits 1 with usage on missing args', () => {+ const res = spawnSync(process.execPath, [SCRIPT], { encoding: 'utf8' });+ assert.equal(res.status, 1);+ assert.match(res.stderr, /usage/);+ });+});diff --git a/tests/fixtures/comp-fidelity/sample.png b/tests/fixtures/comp-fidelity/sample.pngnew file mode 100644index 000000000..1c95e0065Binary files /dev/null and b/tests/fixtures/comp-fidelity/sample.png differ