comparison-bench.mjs
Manifest validation, exact-version IDs, immutable archives and HTML composition.
// Explicit reference/output pairs extend the existing before/after builder.
// The existing SceneBench server owns the append-only rating ledger.
import {readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync} from 'node:fs';
import {resolve, dirname, relative, extname, isAbsolute} from 'node:path';
import {createHash} from 'node:crypto';
import {fileURLToPath} from 'node:url';
const here = dirname(fileURLToPath(import.meta.url));
const esc = s => String(s ?? '').replace(/[&<>"']/g,c=>({'&':'&','<':'<','>':'>','"':'"',"'":'''}[c]));
const sha = data => createHash('sha256').update(data).digest('hex');
const embed = data => JSON.stringify(data).replace(/</g,'\\u003c');
export function buildComparisonBench(m, manifestPath, outPath) {
if (!m.title || !m.brand || !Array.isArray(m.pairs) || !m.pairs.length) throw Error('title, brand and nonempty pairs required');
const base = dirname(resolve(manifestPath));
const out = resolve(outPath || resolve(base,m.out || 'compare.html'));
const outDir = dirname(out); mkdirSync(outDir,{recursive:true});
const mediaRoot=resolve(base,m.mediaRoot || '.');
const ids = new Set();
const file = asset => {
if (!asset?.file) throw Error('media file required');
const abs = resolve(base,asset.file);
if (!existsSync(abs)) throw Error('missing media: '+asset.file);
const rel = relative(outDir,abs);
const bounded=relative(mediaRoot,abs);
if (isAbsolute(rel) || isAbsolute(bounded) || bounded==='..' || bounded.startsWith('..'+(process.platform==='win32'?'\\':'/'))) throw Error('media must be inside the served output tree: '+asset.file);
const data = readFileSync(abs), hash = sha(data);
if (asset.sha256 && asset.sha256 !== hash) throw Error('source/output hash changed: '+asset.file);
return {...asset,src:rel.split('\\').join('/'),sha256:hash};
};
const downloads=(m.downloads || []).map(file);
for(const link of m.links || []) if(!link.href || !['http:','https:'].includes(new URL(link.href,'http://localhost/').protocol)) throw Error('review link must be http(s) or a local path');
const rows = m.pairs.map(p=> {
if (!/^[a-z0-9][a-z0-9-]*$/.test(p.id) || ids.has(p.id)) throw Error('invalid or duplicate pair id: '+p.id);
ids.add(p.id);
if (!p.title || !p.reference?.file) throw Error('pair title and actual reference required: '+p.id);
const reference = file(p.reference), output = p.output ? file(p.output) : null;
if(reference.url && !['http:','https:'].includes(new URL(reference.url).protocol)) throw Error('source URL must be http(s)');
const downloadAsset=p.download?file({file:p.download}):null;
const additionalReferences = (p.additionalReferences || []).map(file);
const previous = (p.previous || []).map(file);
if (reference.crop && (!Array.isArray(reference.crop) || reference.crop.length!==4 || reference.crop.some(n=>!Number.isFinite(n)||n<0||n>1) || reference.crop[2]===0 || reference.crop[3]===0 || reference.crop[0]+reference.crop[2]>1.000001 || reference.crop[1]+reference.crop[3]>1.000001 || !reference.dimensions?.every(n=>Number.isFinite(n)&&n>0))) throw Error('invalid normalized source crop: '+p.id);
const recipe = {brand:m.brand,assetId:p.id,outputSha256:output?.sha256 || null,downloadSha256:downloadAsset?.sha256 || null,copy:p.copy || '',caption:p.caption || '',referenceSha256:reference.sha256,additionalReferenceHashes:additionalReferences.map(r=>r.sha256),crop:reference.crop || null,recipe:p.recipe || null,missing:output?null:p.note};
const versionHash = sha(embed(recipe));
return {...p,download:downloadAsset?.src || null,reference,additionalReferences,output,previous,recipe,versionHash,ratingId:p.id+'@'+versionHash.slice(0,16)};
});
const framesPath=resolve(outDir,'frames.json');
const archive=new Map((existsSync(framesPath)?JSON.parse(readFileSync(framesPath,'utf8')).frames:[]).map(f=>[f.id,f]));
for(const r of rows) archive.set(r.ratingId,{...archive.get(r.ratingId),id:r.ratingId,assetId:r.id,client:m.brand,file:r.output?.src || '',download:r.download,reference:r.reference.src,versionHash:r.versionHash,recipe:r.recipe,title:r.title,reviewLabel:r.reviewLabel || null,note:r.note || '',method:r.method || 'reference comparison',scope:r.output?'Client asset and wording':'Replacement brief'});
// A historical grade must always show its original pixels, even when a client reuses an export name.
// Run once BEFORE replacing exports when adopting this archive over an older bench.
const history=[];
for(const frame of archive.values()) {
if(frame.client!==m.brand || !frame.recipe?.outputSha256) continue;
if(!/^[a-z0-9][a-z0-9-]*@[a-f0-9]{16}$/.test(frame.id)) throw Error('invalid historical frame id');
const freeze=(src,hash,label)=>{
if(!src || !hash) return null;
const candidates=[src,...rows.filter(r=>r.id===frame.assetId).flatMap(r=>r.previous.map(p=>p.src))];
for(const candidate of candidates) {
const abs=resolve(outDir,candidate),bound=relative(mediaRoot,abs);
if(isAbsolute(bound)||bound==='..'||bound.startsWith('..'+(process.platform==='win32'?'\\':'/'))||!existsSync(abs)) continue;
if(sha(readFileSync(abs))!==hash) continue;
const target=resolve(outDir,'versions',frame.id,label+extname(abs));mkdirSync(dirname(target),{recursive:true});
if(existsSync(target)&&sha(readFileSync(target))!==hash) throw Error('immutable version collision: '+frame.id);
if(!existsSync(target)) copyFileSync(abs,target);
return relative(outDir,target).split('\\').join('/');
}
return null;
};
const frozen=freeze(frame.file,frame.recipe.outputSha256,'output');
if(frozen) frame.file=frozen;
frame.archiveAvailable=!!frozen;
const ref=freeze(frame.reference,frame.recipe.referenceSha256,'reference');if(ref) frame.reference=ref;
const proof=freeze(frame.download,frame.recipe.downloadSha256,'download');if(proof) frame.download=proof;
history.push({id:frame.id,assetId:frame.assetId,title:frame.title,file:frozen,reference:ref,
current:rows.some(r=>r.ratingId===frame.id),versionHash:frame.versionHash,reviewLabel:frame.reviewLabel || null});
}
writeFileSync(framesPath,JSON.stringify({schema:'comparison-bench-frames/v1',currentIds:rows.map(r=>r.ratingId),frames:[...archive.values()]},null,2)+'\n');
const media = (a,label) => {
const src=a.src+'?v='+a.sha256.slice(0,16);
if(extname(a.src).toLowerCase()==='.mp4') return `<video controls muted loop preload="metadata" aria-label="${esc(label)}" src="${esc(src)}"></video>`;
let visual=`<img src="${esc(src)}" alt="${esc(label)}" loading="lazy">`;
if(a.crop) {const [w,h]=a.dimensions,[x,y,cw,ch]=a.crop;visual=`<svg role="img" aria-label="${esc(label)} — selected region" viewBox="${x*w} ${y*h} ${cw*w} ${ch*h}"><image href="${esc(src)}" width="${w}" height="${h}"/></svg>`;}
return `<a class="visual" href="${esc(src)}" data-zoom aria-label="Enlarge ${esc(label)}">${visual}</a>`;
};
const sectionHTML=rows.map((r,i)=>`<section class="comparison" id="${esc(r.id)}" data-rating-id="${r.ratingId}" data-batch-id="${esc(r.batchId || '')}" data-kind="${esc(r.kind || 'asset')}" ${i?'hidden':''}>
<div class="pair-heading"><div><small>${String(i+1).padStart(2,'0')} / ${rows.length} · ${esc(m.kindLabels?.[r.kind] || r.kind || 'asset')}</small><h2>${esc(r.title)}</h2></div><span class="state">${esc(r.status || (r.output?'Needs your review':'Needs a replacement'))}</span></div>${r.reviewLabel?`<div class="revision-summary"><strong>${esc(r.reviewLabel.revision)}</strong><span>${esc(r.reviewLabel.round)} · ${esc(r.reviewLabel.date)}</span><p>${esc(r.reviewLabel.change)}</p></div>`:''}
<div class="comparison-grid"><figure><figcaption>${esc(r.reference.label || m.referenceLabel || 'Reference')}</figcaption>${media(r.reference,r.reference.label || r.title+' reference')}<small>${esc(r.reference.description || r.reference.file)}</small></figure>
<figure class="output"><figcaption>${esc(m.outputLabel || m.brand)} <span>${esc(r.reviewLabel?.revision || r.method || 'Current version')}</span></figcaption>${r.output?media(r.output,r.title):`<div class="missing"><strong>Replacement pending</strong><p>${esc(r.note)}</p></div>`}<small>${esc(r.output?.description || r.placement || '')}</small></figure>
<aside class="feedback" aria-label="Feedback for ${esc(r.title)}" data-produced="${!!r.output}" data-review="${esc(r.review || 'Visual acceptance remains open.')}" data-judge="${esc(r.judge || 'Judge not run')}"></aside></div>
<details class="pair-details"><summary>Copy, references & version history</summary><div class="detail-grid"><div><h3>Words on this version</h3><pre>${esc(r.copy || 'No text asset.')}</pre>${r.caption?`<h3>Caption</h3><p>${esc(r.caption)}</p>`:''}<p>${esc(r.note || '')}</p>${r.reference.url?`<a href="${esc(r.reference.url)}" target="_blank" rel="noopener">Source page ↗</a>`:''}</div><div>${r.output?`<a href="${esc(r.output.src)}" download>Download this image</a>`:''}${r.download?` · <a href="${esc(r.download)}" download>${esc(r.downloadLabel || 'Download file')}</a>`:''}<p class="version">Version ${r.ratingId} · ${esc(r.recipe?.recipe?.studioId || '')}</p>${r.additionalReferences.map(a=>`<p>${esc(a.label || 'Additional reference')}</p>${media(a,a.label || 'Additional reference')}`).join('')}${r.previous.map(a=>`<p>${esc(a.label || 'Earlier version — retained for comparison')}</p>${media(a,'Earlier '+r.title)}`).join('')}</div></div></details>
</section>`);
const hasBatch=!!m.batch?.id && rows.some(r=>r.batchId===m.batch.id);
const currentSections=sectionHTML.filter((_,i)=>!hasBatch || rows[i].batchId===m.batch.id).join('\n');
const earlierSections=sectionHTML.filter((_,i)=>hasBatch && rows[i].batchId!==m.batch.id).join('\n');
const earlierCount=hasBatch?rows.filter(r=>r.batchId!==m.batch.id).length:0;
const sections=currentSections+(earlierCount?`<details id="earlier-work" class="earlier-work"><summary>Earlier rounds & open gaps · ${earlierCount} assets <span>Expand to compare or edit previous feedback</span></summary><div class="chapter-heading"><small>PREVIOUS WORK</small><h2>Earlier rounds & open gaps</h2><p>Previous designs keep their own ratings. These are separate from the current round above.</p></div>${earlierSections}</details>`:'');
const kinds=[...new Set(rows.map(r=>r.kind || 'asset'))];
const css=readFileSync(resolve(here,'comparison-bench.css'),'utf8');
const ui=readFileSync(resolve(here,'comparison-bench-ui.js'),'utf8');
const store=readFileSync(resolve(here,'rating-store.js'),'utf8');
const page=`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(m.title)}</title><style>${css}</style></head><body>
<header><div><small>PRIVATE DESIGN REVIEW</small><h1>${esc(m.title)}</h1><p>${esc(m.intro || 'Compare the reference with our version. Rate it and tell us what to change.')}</p></div><div class="save-state" id="rating-connection" role="status">Connecting to saved feedback…</div></header>
<nav class="toolbar" aria-label="Comparison navigation"><a id="batch-jump" href="#${esc(rows[0].id)}">Current batch</a><select id="asset-select" aria-label="Choose asset">${rows.map(r=>`<option value="${esc(r.id)}">${esc(r.title)}${r.reviewLabel?' · '+esc(r.reviewLabel.revision):''}</option>`).join('')}</select><select id="view" aria-label="Comparison view"><option value="all">All down the page</option><option value="single">One at a time</option></select><select id="kind" aria-label="Filter asset type"><option value="all">All types</option>${kinds.map(k=>`<option value="${esc(k)}">${esc(m.kindLabels?.[k] || k)}</option>`).join('')}</select><select id="rated" aria-label="Filter by rating"><option value="all">All ratings</option><option value="unrated">Not rated</option><option value="no">No</option><option value="low">Maybe</option><option value="high">Good</option><option value="heart">Love</option></select><button id="prev" aria-label="Previous asset">←</button><span id="position" aria-live="polite"></span><button id="next" aria-label="Next asset">→</button></nav>
<main><nav class="review-chapters" aria-label="Review sections"><a href="#current-work">${esc(m.batch?.title || 'Current work')}</a><a href="#approved-library">Good / Love library</a><a href="#review-history">Rating history</a>${(m.links||[]).map(l=>`<a href="${esc(l.href)}">${esc(l.label)}</a>`).join('')}</nav><div id="current-work" class="chapter-heading"><small>REVIEW NEXT</small><h2>${esc(m.batch?.title || 'Current work')}</h2><p>${esc(m.batch?.description || 'New versions start unrated. Each score stays with the artwork you reviewed.')}</p><div class="review-legend" aria-label="Review color key"><span>Green · new, not rated</span><span>Lavender · already rated</span></div></div>${sections}<p id="empty" hidden>No assets match these filters.</p><section id="approved-library" class="library"><div class="chapter-heading"><small>KEEP THESE DIRECTIONS</small><h2>Good / Love library</h2><p>Pieces you rated Good or Love, best first. Earlier favorites stay here when a new version is made.</p></div><div id="approved-gallery" class="gallery-grid"></div></section><section id="review-history" class="library"><div class="chapter-heading"><small>EVERY SAVED VERSION</small><h2>Rating history</h2><p>Highest scores first, lowest last. Original images, comments and previous saves are retained.</p><button id="refresh-history">Refresh saved feedback</button></div><div id="history-gallery" class="gallery-grid"></div></section><details id="asset-list"><summary>All ${rows.length} assets · side-by-side list</summary><table><thead><tr><th>Asset</th><th>Reference</th><th>Current version</th></tr></thead><tbody>${rows.map(r=>`<tr><td><a href="#${esc(r.id)}">${esc(r.title)}</a></td><td>${esc(r.reference.label || r.reference.file)}</td><td>${esc(r.status || (r.output?'Needs your review':'Replacement pending'))}</td></tr>`).join('')}</tbody></table></details></main>
<div class="bench-downloads">${downloads.map(d=>`<a href="${esc(d.src)}" download>${esc(d.label || d.file)}</a>`).join('')}</div><footer>${esc(m.footer || 'Feedback guides revisions. Each grade belongs to the exact image and copy shown.')}</footer><dialog id="zoom"><button aria-label="Close enlarged image">×</button><img alt="Enlarged asset"></dialog>
<script>const BENCH=${embed({brand:m.brand,key:m.key || m.brand+':'+m.title,history,batch:m.batch || null,ledger:m.ledger?file({file:m.ledger}).src:null,tags:m.tags || ['on brand','great idea','copy needs work','design needs work','product wrong','looks AI','too busy'],rows:rows.map(r=>({id:r.id,ratingId:r.ratingId,batchId:r.batchId || null,reviewLabel:r.reviewLabel || null,previousRatingIds:r.previousRatingIds || []}))})};</script><script>${store}</script><script>${ui}</script></body></html>`;
writeFileSync(out,page);
writeFileSync(resolve(outDir,'comparison-receipt.json'),JSON.stringify({schema:'comparison-bench-receipt/v1',builderSha256:sha(readFileSync(fileURLToPath(import.meta.url))),rendererInputs:['comparison-bench.mjs','comparison-bench.css','comparison-bench-ui.js','rating-store.js'].map(file=>({file,sha256:sha(readFileSync(resolve(here,file)))})),title:m.title,brand:m.brand,downloads,pairs:rows.map(r=>({id:r.id,ratingId:r.ratingId,reference:r.reference,output:r.output,recipe:r.recipe}))},null,2)+'\n');
return {ok:true,out,pairs:rows.length,generated:rows.filter(r=>r.method==='Image generated').length,missing:rows.filter(r=>!r.output).length};
}