#!/usr/bin/env node // Checks a finished set of covers. It fails any title or kicker that falls outside the 3:4 profile-grid crop or // into the Reels and TikTok interface zones (assets/safe-zones.json), any title that does not match the plan // letter for letter, a title too small to read on a grid tile, low contrast, a cover of the wrong size, or a // cover, grid or manifest that is out of date. Then open the covers and the grid and check them by eye // (references/output-spec.md). // // Usage: // node scripts/check-covers.mjs --series series.json --manifest covers/manifest.json [--grid grid.png] [--preview preview.webp] // // Node 18 or newer. No npm packages. Exit code 1 when a check fails. import { createHash } from 'node:crypto' import { existsSync, readFileSync, statSync } from 'node:fs' import { dirname, isAbsolute, join, resolve } from 'node:path' const FLAGS = new Set(['series', 'manifest', 'grid', 'preview']) function fail(message) { console.error(message) process.exit(1) } const opts = {} const argv = process.argv.slice(2) for (let i = 0; i < argv.length; i++) { const a = argv[i] if (!a.startsWith('--')) fail(`Unexpected argument "${a}". Flags look like --name value.`) const key = a.slice(2) if (!FLAGS.has(key)) fail(`Unknown flag --${key}. Allowed: ${[...FLAGS].map((f) => `--${f}`).join(', ')}`) const value = argv[i + 1] if (value === undefined || value.startsWith('--')) fail(`--${key} needs a value.`) opts[key] = value i++ } if (!opts.series || !opts.manifest) fail('Usage: node scripts/check-covers.mjs --series series.json --manifest covers/manifest.json [--grid grid.png] [--preview preview.webp]') const readJson = (path, what) => { if (!existsSync(path)) fail(`${what} not found: ${path}`) try { return JSON.parse(readFileSync(path, 'utf8')) } catch { fail(`${what} is not valid JSON: ${path}`) } } /** Width and height from a PNG, JPEG or WebP header, without decoding the image. */ function imageSize(path) { const b = readFileSync(path) if (b.length > 24 && b.readUInt32BE(0) === 0x89504e47) return { type: 'png', width: b.readUInt32BE(16), height: b.readUInt32BE(20) } if (b.length > 4 && b[0] === 0xff && b[1] === 0xd8) { let p = 2 while (p + 9 < b.length) { if (b[p] !== 0xff) { p++; continue } const marker = b[p + 1] if (marker === 0xff) { p++; continue } if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) { p += 2; continue } const len = b.readUInt16BE(p + 2) if ((marker >= 0xc0 && marker <= 0xcf) && ![0xc4, 0xc8, 0xcc].includes(marker)) return { type: 'jpeg', width: b.readUInt16BE(p + 7), height: b.readUInt16BE(p + 5) } p += 2 + len } return null } if (b.length > 30 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP') { const chunk = b.toString('ascii', 12, 16) if (chunk === 'VP8 ') return { type: 'webp', width: b.readUInt16LE(26) & 0x3fff, height: b.readUInt16LE(28) & 0x3fff } if (chunk === 'VP8L') { const bits = b.readUInt32LE(21) return { type: 'webp', width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 } } if (chunk === 'VP8X') return { type: 'webp', width: 1 + b.readUIntLE(24, 3), height: 1 + b.readUIntLE(27, 3) } } return null } const sha = (path) => createHash('sha256').update(readFileSync(path)).digest('hex') const issues = [] const warnings = [] const notes = [] const plan = readJson(opts.series, 'Plan') const manifest = readJson(opts.manifest, 'Manifest') const zones = JSON.parse(readFileSync(new URL('../assets/safe-zones.json', import.meta.url), 'utf8')) const planDir = dirname(resolve(opts.series)) const outDir = dirname(resolve(opts.manifest)) const fromPlan = (p) => (isAbsolute(p) ? p : join(planDir, p)) const fromOut = (p) => (isAbsolute(p) ? p : join(outDir, p)) const style = plan.style ?? {} const series = plan.series ?? {} const covers = plan.covers ?? [] // The plan. if (plan.schema !== 'reel-cover-set/1') issues.push(`${opts.series} schema is "${plan.schema}", expected reel-cover-set/1.`) if (![3, 6, 9].includes(covers.length)) issues.push(`The plan has ${covers.length} covers; a set is 3, 6 or 9 (full rows of the profile grid).`) const unfilled = [] const walk = (v, path) => { if (typeof v === 'string' && v.includes('FILL:')) unfilled.push(path) else if (Array.isArray(v)) v.forEach((x, i) => walk(x, `${path}[${i}]`)) else if (v && typeof v === 'object') for (const [k, x] of Object.entries(v)) walk(x, path ? `${path}.${k}` : k) } walk(plan, '') if (unfilled.length) issues.push(`Still marked FILL: ${unfilled.join(', ')}.`) covers.forEach((c, i) => { if (c.n !== i + 1) issues.push(`Covers are not numbered 1 to ${covers.length} in order (found ${c.n} at position ${i + 1}).`) const words = String(c.title ?? '').trim().split(/\s+/).filter(Boolean) if (!words.length) issues.push(`Cover ${c.n} has no title.`) else if (words.length > 6 || c.title.length > 32) issues.push(`Cover ${c.n} title "${c.title}" is over 6 words or 32 characters.`) }) const withPerson = covers.filter((c) => c.still && c.still_has_person) if (withPerson.length && (series.people !== 'real-with-consent' || series.consent_confirmed !== true)) { issues.push(`Cover(s) ${withPerson.map((c) => c.n).join(', ')} use a still with a person, but the plan does not record consent (series.people "real-with-consent" and series.consent_confirmed true). Do not deliver until the person shown has agreed.`) } if (series.people === 'real-with-consent' && !withPerson.length) warnings.push('series.people is real-with-consent, but no still is marked still_has_person.') // The manifest against the plan. if (manifest.schema !== 'reel-cover-set-manifest/1') issues.push(`${opts.manifest} is not a cover manifest (make it with scripts/compose-covers.mjs).`) const records = manifest.covers ?? [] if (records.length !== covers.length) issues.push(`The manifest has ${records.length} covers; the plan has ${covers.length}. Re-run compose-covers.mjs.`) const set = manifest.settings ?? {} for (const key of ['ink', 'accent', 'treatment', 'position', 'align', 'case']) { const want = key === 'ink' || key === 'accent' ? String(style[key] ?? '').toLowerCase() : style[key] if (want && set[key] !== want) issues.push(`The covers were drawn with ${key} "${set[key]}", but the plan now says "${want}". Re-run compose-covers.mjs.`) } if (manifest.zones_checked !== zones.checked) warnings.push(`The covers were drawn against safe zones checked ${manifest.zones_checked}; the zone file now says ${zones.checked}. Re-run compose-covers.mjs.`) const expectedTitle = (c) => (set.case === 'upper' ? c.title.toUpperCase() : c.title) const expectedKicker = (c) => (c.kicker || style.kicker || '').replace(/\{\{nn\}\}/g, String(c.n).padStart(2, '0')).replace(/\{\{n\}\}/g, String(c.n)).trim().toUpperCase() const inside = (b, r) => b.x >= r.x && b.y >= r.y && b.x + b.width <= r.x + r.width && b.y + b.height <= r.y + r.height const overlaps = (b, r) => b.x < r.x + r.width && b.x + b.width > r.x && b.y < r.y + r.height && b.y + b.height > r.y const sizes = [] const soft = {} for (const c of covers) { const r = records.find((x) => x.n === c.n) const where = `Cover ${c.n}` if (!r) { issues.push(`${where} is missing from the manifest. Re-run compose-covers.mjs.`) continue } // The file itself. const file = fromOut(r.file) if (!existsSync(file)) issues.push(`${where} file not found: ${file}`) else { const dim = imageSize(file) if (!dim || dim.type !== 'png') issues.push(`${where} ${r.file} is not a PNG.`) else if (dim.width !== zones.frame.width || dim.height !== zones.frame.height) issues.push(`${where} is ${dim.width} x ${dim.height}; a cover is ${zones.frame.width} x ${zones.frame.height}.`) if (sha(file) !== r.sha256) issues.push(`${where} ${r.file} has changed since it was composed (edited by hand?). Re-run compose-covers.mjs, then check again.`) } // The art it was drawn on is the art the plan names now. if (!c.art) issues.push(`${where} has no "art" in the plan.`) else if (!existsSync(fromPlan(c.art))) issues.push(`${where} art not found: ${fromPlan(c.art)}`) else { if (sha(fromPlan(c.art)) !== r.art_sha256) issues.push(`${where} was composed on other art than the plan names now. Re-run compose-covers.mjs.`) const a = imageSize(fromPlan(c.art)) if (a && (a.width < zones.frame.width || a.height < zones.frame.height)) warnings.push(`${where} art is ${a.width} x ${a.height}, smaller than the cover, so it was upscaled (a draft used as final?).`) } // Exact words. if (r.title !== c.title) issues.push(`${where} title on the cover is "${r.title}", but the plan says "${c.title}". Re-run compose-covers.mjs.`) if (r.title_drawn !== expectedTitle(c)) issues.push(`${where} drew "${r.title_drawn}", expected "${expectedTitle(c)}".`) if ((r.lines ?? []).join(' ') !== r.title_drawn) issues.push(`${where} title lines "${(r.lines ?? []).join(' / ')}" do not add up to "${r.title_drawn}".`) if ((r.lines ?? []).length > 3) issues.push(`${where} title runs to ${(r.lines ?? []).length} lines; at most 3.`) if ((r.kicker_drawn ?? '') !== expectedKicker(c)) issues.push(`${where} kicker is "${r.kicker_drawn}", expected "${expectedKicker(c)}". Re-run compose-covers.mjs.`) // Safe zones. const boxes = r.boxes ?? [] if (!boxes.some((b) => b.role === 'title')) issues.push(`${where} has no title box in the manifest.`) for (const b of boxes) { const what = b.role === 'title' ? `title line ${b.line}` : 'kicker' for (const z of zones.zones) { const bad = z.kind === 'keep-inside' ? !inside(b, z.rect) : overlaps(b, z.rect) if (!bad) continue const message = `${where} ${what} (x ${b.x}-${b.x + b.width}, y ${b.y}-${b.y + b.height}) ${z.kind === 'keep-inside' ? 'falls outside' : 'enters'} ${z.label}.` if (z.severity === 'fail') issues.push(message) else (soft[z.id] ??= { label: z.label, covers: new Set() }).covers.add(c.n) } if (!inside(b, zones.title_box) && !issues.some((m) => m.startsWith(`${where} ${what} `))) issues.push(`${where} ${what} falls outside the safe title box.`) } // Readable on a grid tile. if (!(r.title_px >= zones.min_title_px)) issues.push(`${where} title is ${r.title_px} px; at least ${zones.min_title_px} px reads on a phone grid tile. Shorten the title.`) sizes.push(r.title_px) if (!(r.contrast >= zones.min_contrast)) issues.push(`${where} title contrast is ${r.contrast}:1, under ${zones.min_contrast}:1. Use the block treatment, change the title colour, or regenerate with a calmer, plainer band.`) if (set.treatment !== 'block' && r.busy > 45) warnings.push(`${where}: the art behind the title is busy (spread ${r.busy}). Read it small; if it is hard to read, use the block treatment or regenerate with a calmer band.`) } for (const z of Object.values(soft)) warnings.push(`Text on cover(s) ${[...z.covers].join(', ')} falls outside ${z.label}.`) if (sizes.length && set.shared_size && new Set(sizes).size > 1) issues.push(`The set was meant to share one title size, but the covers use ${[...new Set(sizes)].join(', ')} px. Re-run compose-covers.mjs.`) if (sizes.length && !set.shared_size && Math.max(...sizes) / Math.min(...sizes) > 1.15) warnings.push(`Title sizes run from ${Math.min(...sizes)} to ${Math.max(...sizes)} px. One size across the set reads more like a series (drop --per-cover-size).`) // The grid preview. if (opts.grid) { if (!existsSync(opts.grid)) issues.push(`Grid not found: ${opts.grid}. Run scripts/grid-preview.mjs.`) else { const dim = imageSize(opts.grid) const sidecar = `${opts.grid}.json` if (!dim || dim.type !== 'png') issues.push(`${opts.grid} is not a PNG.`) if (!existsSync(sidecar)) issues.push(`${sidecar} is missing. Re-run grid-preview.mjs.`) else { const g = readJson(sidecar, 'Grid record') const current = new Map(records.map((r) => [r.n, r.sha256])) if ((g.covers ?? []).length !== records.length || (g.covers ?? []).some((x) => current.get(x.n) !== x.sha256)) issues.push(`${opts.grid} was made from other covers than the manifest lists now. Re-run grid-preview.mjs.`) if (dim && (dim.width !== g.width || dim.height !== g.height)) issues.push(`${opts.grid} is ${dim.width} x ${dim.height}, not the ${g.width} x ${g.height} its record says.`) const rows = Math.ceil(records.length / zones.grid.columns) if (dim && g.tile && Math.abs(dim.height - (rows * Math.round((g.tile * 4) / 3) + (rows - 1) * g.gap)) > 1) issues.push(`${opts.grid} tiles are not 3:4.`) notes.push(`Grid ${opts.grid}: ${dim?.width} x ${dim?.height}, ${g.order}.`) } } } if (opts.preview) { if (!existsSync(opts.preview)) issues.push(`Preview not found: ${opts.preview}`) else { const dim = imageSize(opts.preview) const kb = statSync(opts.preview).size / 1024 if (!dim || dim.type !== 'webp') issues.push(`${opts.preview} is not a WebP.`) else if (Math.max(dim.width, dim.height) > 2048) issues.push(`${opts.preview} is ${dim.width} x ${dim.height}; keep previews at most 2048 px on the long edge.`) if (kb > 400) warnings.push(`${opts.preview} is ${Math.round(kb)} KB; aim for 150-400 KB (a smaller --tile).`) notes.push(`Preview ${opts.preview}: ${dim ? `${dim.width} x ${dim.height}, ` : ''}${Math.round(kb)} KB.`) } } console.log(`${opts.series}: ${covers.length} covers for "${series.name ?? ''}", title ${set.treatment ?? '?'} ${set.position ?? '?'} ${set.align ?? '?'}, ${sizes.length ? `${Math.min(...sizes)} px` : 'no sizes'}.`) for (const n of notes) console.log(`note: ${n}`) for (const w of warnings) console.log(`warning: ${w}`) if (issues.length) { for (const i of issues) console.log(`FAIL: ${i}`) process.exit(1) } console.log('PASS: technical checks. Every title sits inside the 3:4 grid crop and clear of the Reels and TikTok interface. Now open every cover and the grid at full size and go through references/output-spec.md by eye: one look across the set, no stray text in the art, natural hands, no extra people, every title read letter by letter.')