Redesign an existing website to make it better. Built on top of impeccable.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
#!/usr/bin/env node
/* eslint-disable import/no-extraneous-dependencies, import/extensions, no-await-in-loop, no-restricted-syntax, brace-style, object-curly-newline, max-len, no-console, no-continue, no-nested-ternary, no-plusplus, no-underscore-dangle, no-restricted-globals, newline-per-chained-call, object-property-newline */
/* global __clipChain, __controlOf, __isControl, __norm, __pageRect, __parent, __path, __rendered, __sel, __srOnly, __visibleText, __walk */
/**
* skills/diff/scripts/content-presence.mjs — the CONTENT-PRESENCE gate of the published-origin gate
* (#125, D2): live origin vs served page, same minute, same settle, compared per band.
*
* content-diff.mjs's role classifier is tuned to a prototype's DOM; on live commerce origins its
* per-node findings were false. This probe asks the smaller question the pixel gate cannot: is every
* VISIBLE heading, link, button, image and text block of the origin present AND visible on the served
* page, band by band, and does every control show the same state? Both pages load in the same
* window-free real-Chrome tier and settle the same way (measure-live.mjs). Visibility = rendered,
* non-zero box, on-page, not clipped past 50 % (clip-probe's model): in the DOM but clipped = HIDDEN.
* Bands: the visible h1–h3 sequences aligned by text (LCS); items fall into bands by y.
*
* MISSING / HIDDEN HEADING, MISSING / HIDDEN LINK ×n 🔴 (exit 2)
* MISSING / HIDDEN BUTTON, CONTROL STATE 🟠
* COUNT TEXT|IMAGES|LINKS, MOVED LINK, EXTRA …, HEADING AS TEXT 🟡
*
* Links and buttons are one pool on the served side; text-less image anchors count as images. Scope
* is symmetric (root only when BOTH sides have one, else whole page); header / footer and everything
* above / below them are left to the chrome crop gate unless --chrome. `--variable <selO=selE,…>`
* marks session-variable regions (counts only, HIDDEN still counts). The origin side fails loud on
* HTTP ≥ 400 (exit 4) and on a bot challenge (exit 3). Trap: an infinite-scroll origin keeps loading
* under the settle — mark that region --variable.
*
* Usage: node skills/diff/scripts/content-presence.mjs <originUrl> <edsUrl> [--width 1440]
* [--main <sel>[=<selEds>]] [--variable <sel,…>] [--chrome] [--json [<file>]] [--min-cut 2]
* [--settle-passes 4] [--max-findings 40] [--count-words <w,…>] [--plain] [--warmup <url>]
* `presenceInventoryInPage`, `alignHeadings`, `diffPresence`, `formatReport`, `norm` are exported.
*/
import { mkdirSync, realpathSync, writeFileSync } from 'node:fs';
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { clipInventoryInPage, inPage, morePrelude, summarize } from './clip-probe.mjs';
import { browserTier, openBrowser, openPage, visit } from './measure-live.mjs';
const HELP = `content-presence — origin vs served page: visible headings / links / buttons / images / text per band + control state (#125 D2)
Usage: node content-presence.mjs <originUrl> <edsUrl> [options]
--width <px> viewport width (default 1440)
--main <sel>[=<selEds>] content root(s) (default main, else body)
--variable <sel,…> session-variable subtrees, counts only (selO=selE pairs allowed)
--json [<file>] JSON (inventories, bands, findings, totals, clip, textBoxes)
--min-cut <px> clip partial-cut floor (default 2)
--chrome include header / footer items (default: left to the chrome crop gate)
--settle-passes <n> slow-scroll passes until the height is stable (default 4; infinite-scroll
origins keep loading — mark those regions --variable)
--max-findings <n> printed findings per kind (default 40)
--count-words <w,…> result-count nouns (default English: results, items, products, coupons, offers, reviews, stores, matches)
--more-words <re> "read more" toggle labels for the clip model (default English)
--plain bundled Chromium instead of the window-free real-Chrome tier
--warmup <url> visit this URL first on the ORIGIN side (bot-managed sites)
--locale <tag> default en-US
--help this text
Exit: 0 clean, 2 any MISSING/HIDDEN link or heading, 1 error, 3 bot challenge, 4 origin HTTP >= 400.`;
// ---- in-page inventory (needs IN_PAGE_LIB — run via inPage()) -----------------------------------------
/** page.evaluate(inPage(presenceInventoryInPage, { rootSel, variableSels })) → { docH, pageW, root, items[] } */
export function presenceInventoryInPage({ rootSel = null, variableSels = [], countWords = 'results?|items?|products?|coupons?|offers?|reviews?|stores?|matches' } = {}) {
const COUNT_RE = new RegExp(`\\b(\\d[\\d,]*)\\s+(${countWords})\\b`, 'i');
// Always walk the whole body; each item carries `inRoot`. The differ picks the scope SYMMETRICALLY: root
// only when BOTH sides have one, else the whole page (a live origin without <main> against a build with
// one would otherwise compare chrome against content).
const root = document.body;
const rootEl = (rootSel && document.querySelector(rootSel)) || (!rootSel && document.querySelector('main')) || null;
// chrome landmarks: items inside them are flagged so the differ can leave the header / footer to the chrome
// crop gate (the chrome repeats on every page and its live promo strips / account state are session-variable)
// Chrome = the landmarks AND everything above the header's bottom edge / below the footer's top edge
// (promo strips often sit OUTSIDE <header>); the chrome crop gate judges that region, --chrome includes it.
const chromeEls = [...document.querySelectorAll('header, [role="banner"], footer, [role="contentinfo"]')].filter((c) => !rootEl || !rootEl.contains(c));
const banner = chromeEls.filter((c) => c.matches('header, [role="banner"]')).map((c) => __pageRect(c.getBoundingClientRect())).filter((r) => r.h > 0);
const contentinfo = chromeEls.filter((c) => c.matches('footer, [role="contentinfo"]')).map((c) => __pageRect(c.getBoundingClientRect())).filter((r) => r.h > 0);
const chromeTop = banner.length ? Math.max(...banner.map((r) => r.b)) : 0;
const chromeBottom = contentinfo.length ? Math.min(...contentinfo.map((r) => r.t)) : Infinity;
const inChrome = (el) => { if (chromeEls.some((c) => c.contains(el))) return true; const r = __pageRect(el.getBoundingClientRect()); return r.b <= chromeTop || r.t >= chromeBottom; };
const pageW = document.documentElement.clientWidth;
const variableEls = variableSels.flatMap((s) => { try { return [...document.querySelectorAll(s)]; } catch { return []; } });
const inVariable = (el) => variableEls.some((v) => v.contains(el));
const overlap = (a0, a1, b0, b1) => Math.max(0, Math.min(a1, b1) - Math.max(a0, b0));
// 'visible' | 'hidden' (clipped past 50 % by the nearest overflow ancestor) | null (not rendered / off-page / collapsed)
const state = (el) => {
if (!__rendered(el) || __srOnly(el)) return null;
const br = el.getBoundingClientRect();
if (br.width <= 0 || br.height <= 0) return null;
const r = __pageRect(br);
if (r.r <= 0 || r.l >= pageW) return null;
const cc = __clipChain(el, false);
if (cc.skip) return null;
for (const clip of cc.chain) {
if (clip.mode === 'scroll') continue;
const vis = (clip.axes.y ? overlap(r.t, r.b, clip.rect.t, clip.rect.b) : r.h) * (clip.axes.x ? overlap(r.l, r.r, clip.rect.l, clip.rect.r) : r.w);
if (vis / (r.w * r.h) < 0.5) return 'hidden';
}
return 'visible';
};
const rectOf = (el) => { const r = __pageRect(el.getBoundingClientRect()); return { x: Math.round(r.l), y: Math.round(r.t), w: Math.round(r.w), h: Math.round(r.h) }; };
const label = (el) => __norm(__visibleText(el)) || __norm((el.querySelector('img') || {}).alt) || __norm(el.getAttribute('aria-label')) || __norm(el.getAttribute('title')) || '';
const file = (src) => { try { return new URL(src, window.location.href).pathname.split('/').pop().replace(/\.[a-z0-9]+$/i, '').slice(0, 40); } catch { return ''; } };
const items = [];
const push = (kind, el, extra) => { const st = state(el); if (!st) return; items.push({ kind, state: st, variable: inVariable(el), inRoot: rootEl ? rootEl.contains(el) : null, inChrome: inChrome(el), path: __path(el, 3), ...rectOf(el), ...extra }); };
const textBlocks = new Set();
const ownText = (el) => [...el.childNodes].filter((n) => n.nodeType === 3).map((n) => n.textContent).join(' ').replace(/\s+/g, ' ').trim();
const hasCountedAncestor = (el) => { for (let a = __parent(el); a && a !== root; a = __parent(a)) if (textBlocks.has(a)) return true; return false; };
const controlLabel = (el) => {
const al = __norm(el.getAttribute('aria-label'));
if (al) return al;
if (el.labels && el.labels.length) return __norm(el.labels[0].textContent);
const lb = el.closest && el.closest('label');
if (lb) return __norm(lb.textContent).slice(0, 60);
const id = el.getAttribute('aria-labelledby'); if (id) { const l = document.getElementById(id); if (l) return __norm(l.textContent); }
return __norm(el.getAttribute('name')) || '';
};
for (const el of __walk(root)) {
if (el.nodeType !== 1) continue;
const tag = el.tagName;
if (/^H[1-6]$/.test(tag) || el.getAttribute('role') === 'heading') {
const level = /^H[1-6]$/.test(tag) ? Number(tag[1]) : Number(el.getAttribute('aria-level') || 2);
const text = label(el); if (text) push('heading', el, { level, text: text.slice(0, 120) });
continue;
}
if (tag === 'A' && el.hasAttribute('href')) { const text = label(el); let href = ''; try { href = new URL(el.getAttribute('href'), window.location.href).pathname; } catch { href = el.getAttribute('href'); } push('link', el, { text: text.slice(0, 80), href }); }
else if (tag === 'BUTTON' || (tag === 'INPUT' && /^(button|submit|reset)$/i.test(el.type)) || el.getAttribute('role') === 'button') {
const text = tag === 'INPUT' ? __norm(el.value) : label(el);
push('button', el, { text: text.slice(0, 80) });
const pop = el.getAttribute('aria-haspopup'); const exp = el.getAttribute('aria-expanded');
if ((pop && pop !== 'false') || exp !== null || el.getAttribute('role') === 'combobox') push('control', el, { label: controlLabel(el) || 'trigger', value: text.slice(0, 60), via: 'trigger' });
}
else if (tag === 'IMG') { const br = el.getBoundingClientRect(); if (br.width >= 16 && br.height >= 16) push('image', el, { text: __norm(el.alt).slice(0, 60), file: file(el.currentSrc || el.src) }); }
else if (tag === 'SELECT') { const o = el.options[el.selectedIndex]; push('control', el, { label: controlLabel(el) || 'select', value: o ? __norm(o.textContent).slice(0, 60) : '', via: 'select' }); }
else if (tag === 'INPUT' && /^(radio|checkbox)$/i.test(el.type)) { if (el.checked) push('control', el, { label: controlLabel(el) || el.type, value: controlLabel(el) || 'checked', via: el.type }); }
else if (el.getAttribute('role') === 'combobox') push('control', el, { label: controlLabel(el) || 'combobox', value: (__norm(el.value) || label(el)).slice(0, 60), via: 'combobox' });
else if ((el.getAttribute('role') === 'tab' || el.getAttribute('role') === 'option') && el.getAttribute('aria-selected') === 'true') push('control', el, { label: `${el.getAttribute('role')} selected`, value: label(el).slice(0, 60), via: 'aria-selected' });
else if (el.getAttribute('aria-pressed') === 'true') push('control', el, { label: 'pressed', value: label(el).slice(0, 60), via: 'aria-pressed' });
else if (el.hasAttribute('aria-current') && el.getAttribute('aria-current') !== 'false') push('control', el, { label: 'current', value: label(el).slice(0, 60), via: 'aria-current' });
// text blocks: own text ≥ 3 chars, not inside an already counted block, not a control / heading
if (tag !== 'A' && tag !== 'BUTTON' && !__isControl(el)) {
const own = ownText(el);
if (own.length >= 3 && !hasCountedAncestor(el) && !__controlOf(el)) {
textBlocks.add(el);
push('text', el, { text: own.slice(0, 80) });
const m = own.match(COUNT_RE);
if (m) push('control', el, { label: `count ${m[2].toLowerCase().replace(/s$/, '')}`, value: m[1].replace(/,/g, ''), via: 'count' });
}
}
}
return { docH: document.documentElement.scrollHeight, pageW, root: rootEl ? __sel(rootEl) : null, items };
}
// ---- pure: alignment + diff --------------------------------------------------------------------------
// Matching key: lower-case; trademark / footnote glyphs and a trailing footnote digit dropped ("no annual
// fee †", "$50/month. 1"); a bare "tm" token dropped (a <sup>TM</sup> serialises as text on one side and as
// the glyph on the other — 17 false MISSING on one recorded page); punctuation runs collapsed.
export const norm = (s) => (s || '')
.toLowerCase()
.replace(/[®™©†‡§*]/g, ' ')
.replace(/\b(tm|sm)\b/g, ' ')
.replace(/[\u2018\u2019]/g, "'")
.replace(/[\u201c\u201d]/g, '"')
.replace(/\s+/g, ' ')
.replace(/(\D)\s+\d{1,2}\s*$/g, '$1')
.replace(/\s*([.,;:!?])\s*/g, '$1 ')
.replace(/\s+/g, ' ')
.trim();
const sameHeading = (a, b) => a === b || (a.length >= 8 && b.length >= 8 && (a.startsWith(b) || b.startsWith(a)));
/** Longest common subsequence over the two visible h1–h3 sequences → [{ oi, ei }] index pairs. */
export function alignHeadings(origin, eds) {
const n = origin.length; const m = eds.length;
const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
for (let i = n - 1; i >= 0; i -= 1) for (let j = m - 1; j >= 0; j -= 1) dp[i][j] = sameHeading(origin[i], eds[j]) ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
const pairs = []; let i = 0; let j = 0;
while (i < n && j < m) {
if (sameHeading(origin[i], eds[j])) { pairs.push({ oi: i, ei: j }); i += 1; j += 1; }
else if (dp[i + 1][j] >= dp[i][j + 1]) i += 1; else j += 1;
}
return pairs;
}
const countBy = (arr, key) => { const m = new Map(); for (const it of arr) { const k = key(it); m.set(k, (m.get(k) || 0) + 1); } return m; };
const linkKey = (it) => norm(it.text) || `href:${it.href}`;
/**
* diffPresence(originInv, edsInv, { countTol }) → { bands, findings, totals }
* Inventories are the in-page result ({ items }); items hidden on the origin are dropped first.
*/
export function diffPresence(originInv, edsInv, { countTol = 0.25, chrome = false } = {}) {
const scope = originInv.root && edsInv.root ? 'root' : 'page';
const inScope = (it) => (scope === 'page' || it.inRoot) && (chrome || !it.inChrome);
const O = originInv.items.filter((it) => it.state === 'visible' && inScope(it));
const E = edsInv.items.filter(inScope);
const bandHeads = (items) => items.filter((it) => it.kind === 'heading' && it.level <= 3 && it.state === 'visible').sort((a, b) => a.y - b.y);
const oh = bandHeads(O); const eh = bandHeads(E);
const pairs = alignHeadings(oh.map((h) => norm(h.text)), eh.map((h) => norm(h.text)));
const findings = [];
const add = (sev, kind, msg, extra = {}) => findings.push({ sev, kind, msg, ...extra });
// unaligned headings
const alignedO = new Set(pairs.map((p) => p.oi)); const alignedE = new Set(pairs.map((p) => p.ei));
const edsHeadingsAll = E.filter((it) => it.kind === 'heading');
const edsVisibleTexts = new Set(E.filter((it) => it.state === 'visible' && (it.kind === 'text' || it.kind === 'link' || it.kind === 'heading')).map((it) => norm(it.text)));
oh.forEach((h, i) => {
if (alignedO.has(i)) return;
const hidden = edsHeadingsAll.find((x) => sameHeading(norm(x.text), norm(h.text)) && x.state === 'hidden');
if (hidden) add('🔴', 'HIDDEN HEADING', `h${h.level} "${h.text}" is in the served DOM but clipped away (${hidden.path})`, { band: i, text: h.text });
else if (edsVisibleTexts.has(norm(h.text))) add('🟡', 'HEADING AS TEXT', `origin h${h.level} "${h.text}" is served as plain text / a link, not a heading (visually present — semantics only)`, { band: i, text: h.text });
else add('🔴', 'MISSING HEADING', `h${h.level} "${h.text}" (origin y ${h.y}) has no served heading`, { band: i, text: h.text });
});
eh.forEach((h, j) => { if (!alignedE.has(j)) add('🟡', 'EXTRA HEADING', `served h${h.level} "${h.text}" (y ${h.y}) has no origin heading`, { text: h.text }); });
// bands: one per aligned heading pair, plus band 0 (above the first aligned heading)
const bounds = (heads, idxs) => { const ys = idxs.map((i) => heads[i].y); return [0, ...ys, Infinity]; };
const ob = bounds(oh, pairs.map((p) => p.oi)); const eb = bounds(eh, pairs.map((p) => p.ei));
const bandOf = (b, y) => { let k = 0; while (k + 1 < b.length - 1 && y >= b[k + 1]) k += 1; return k; };
const bands = [];
for (let k = 0; k < ob.length - 1; k += 1) {
const name = k === 0 ? '(top)' : oh[pairs[k - 1].oi].text;
const oItems = O.filter((it) => bandOf(ob, it.y) === k); const eItems = E.filter((it) => bandOf(eb, it.y) === k);
const variable = oItems.some((it) => it.variable) || eItems.some((it) => it.variable);
const band = { index: k, heading: name, variable, origin: {}, eds: {}, findings: [] };
for (const kind of ['link', 'button', 'text', 'image']) {
band.origin[kind] = oItems.filter((it) => it.kind === kind).length;
band.eds[kind] = eItems.filter((it) => it.kind === kind && it.state === 'visible').length;
band.eds[`${kind}Hidden`] = eItems.filter((it) => it.kind === kind && it.state === 'hidden').length;
}
bands.push(band);
// links + buttons by text
for (const [kind, sev, missingKind, hiddenKind] of [['link', '🔴', 'MISSING LINK', 'HIDDEN LINK'], ['button', '🟠', 'MISSING BUTTON', 'HIDDEN BUTTON']]) {
// links and buttons are ONE pool on the served side (a "Sign in" button served as a link is the same
// visible control); the ORIGIN kind decides the severity.
const action = (it) => it.kind === 'link' || it.kind === 'button';
// a text-less link (an image-only anchor without alt) is the image's presence (counted there); its href
// does not survive a migration's path rewrite — text-keyed only.
const oFixed = oItems.filter((it) => it.kind === kind && !it.variable && norm(it.text)); const oVar = oItems.filter((it) => it.kind === kind && it.variable && norm(it.text));
const eVis = countBy(eItems.filter((it) => action(it) && it.state === 'visible'), linkKey);
const eHid = countBy(eItems.filter((it) => action(it) && it.state === 'hidden'), linkKey);
const eVisAll = countBy(E.filter((it) => action(it) && it.state === 'visible'), linkKey);
const oAll = countBy(O.filter(action), linkKey);
for (const [key, cO] of countBy(oFixed, linkKey)) {
const vE = eVis.get(key) || 0; if (vE >= cO) continue;
let deficit = cO - vE;
const hid = Math.min(deficit, eHid.get(key) || 0);
const sample = oFixed.find((it) => linkKey(it) === key);
if (hid) { add(sev, hiddenKind, `${hid > 1 ? `×${hid} ` : ''}"${sample.text || sample.href}" in band "${name}" — in the served DOM but clipped away (${(eItems.find((it) => action(it) && it.state === 'hidden' && linkKey(it) === key) || {}).path || ''})`, { band: k, n: hid, text: sample.text, href: sample.href }); deficit -= hid; }
if (deficit > 0) {
if ((eVisAll.get(key) || 0) >= (oAll.get(key) || 0)) add('🟡', kind === 'link' ? 'MOVED LINK' : 'MOVED BUTTON', `${deficit > 1 ? `×${deficit} ` : ''}"${sample.text || sample.href}" short in band "${name}" but visible elsewhere on the served page`, { band: k, n: deficit, text: sample.text });
else add(sev, missingKind, `${deficit > 1 ? `×${deficit} ` : ''}"${sample.text || sample.href}"${sample.href ? ` → ${sample.href}` : ''} in band "${name}" (origin y ${sample.y}) not on the served page`, { band: k, n: deficit, text: sample.text, href: sample.href });
}
}
if (oVar.length) { const eVarVis = eItems.filter((it) => it.kind === kind && it.variable && it.state === 'visible').length; const eVarHid = eItems.filter((it) => it.kind === kind && it.variable && it.state === 'hidden').length; if (eVarHid) add(sev, hiddenKind, `×${eVarHid} ${kind}s clipped away inside the session-variable region of band "${name}"`, { band: k, n: eVarHid, variable: true }); if (Math.abs(eVarVis - oVar.length) > Math.max(2, countTol * oVar.length)) add('🟡', `COUNT ${kind.toUpperCase()}S`, `session-variable region in band "${name}": ${oVar.length} origin → ${eVarVis} served`, { band: k }); }
// extra
if (kind === 'link') for (const [key, cE] of eVis) { const cO = oAll.get(key) || 0; if (cO === 0 && !key.startsWith('href:')) { const s = eItems.find((it) => action(it) && linkKey(it) === key); add('🟡', 'EXTRA LINK', `${cE > 1 ? `×${cE} ` : ''}"${s.text || s.href}" served in band "${name}", no origin link or button`, { band: k, n: cE, text: s.text }); } }
}
for (const kind of ['text', 'image']) {
const cO = band.origin[kind]; const cE = band.eds[kind]; const hid = band.eds[`${kind}Hidden`];
if (Math.abs(cE - cO) > Math.max(kind === 'text' ? 3 : 2, countTol * cO) || hid > Math.max(2, countTol * cO)) add('🟡', `COUNT ${kind.toUpperCase()}${kind === 'text' ? '' : 'S'}`, `band "${name}": ${cO} origin → ${cE} served visible${hid ? ` (+${hid} clipped away)` : ''}`, { band: k, origin: cO, eds: cE, hidden: hid });
}
// control state: by label, else by ordinal among generic triggers
const oC = oItems.filter((it) => it.kind === 'control'); const eC = eItems.filter((it) => it.kind === 'control' && it.state === 'visible');
const used = new Set();
for (const c of oC) {
const lab = norm(c.label); const generic = /^(trigger|combobox|select|checked|radio|checkbox|pressed|current|tab selected|option selected)$/.test(lab);
let m = null;
if (!generic) m = eC.find((x, idx) => !used.has(idx) && norm(x.label) === lab && (used.add(idx) || true));
// ordinal fallback only for GENERIC labels: a specifically labelled trigger with no served counterpart is
// CONTROL MISSING, never paired with an unrelated trigger
if (!m && generic) { const sameVia = eC.map((x, idx) => ({ x, idx })).filter(({ x, idx }) => !used.has(idx) && x.via === c.via); const exact = sameVia.find(({ x }) => norm(x.value) === norm(c.value)); const pick = exact || sameVia[0]; if (pick) { used.add(pick.idx); m = pick.x; } }
if (!m) {
if (/^count/.test(lab)) { add('🟠', 'CONTROL STATE', `${c.label}: origin "${c.value}", served: none`, { band: k, label: c.label, value: c.value }); continue; }
const dup = findings.find((f) => f.kind === 'CONTROL MISSING' && f.band === k && f.label === c.label && f.value === c.value);
if (dup) { dup.n = (dup.n || 1) + 1; dup.msg = dup.msg.replace(/^(×\d+ )?/, `×${dup.n} `); } else add('🟡', 'CONTROL MISSING', `${c.label} = "${c.value}" (band "${name}") has no served counterpart`, { band: k, label: c.label, value: c.value });
continue;
}
if (norm(m.value) !== norm(c.value)) add('🟠', 'CONTROL STATE', `${c.label}: origin "${c.value}" → served "${m.value}" (band "${name}")`, { band: k, label: c.label, origin: c.value, eds: m.value });
}
band.findings = findings.filter((f) => f.band === k).map((f) => f.kind);
}
const order = { '🔴': 0, '🟠': 1, '🟡': 2 };
findings.sort((a, b) => order[a.sev] - order[b.sev]);
const sum = (kind) => findings.filter((f) => f.kind === kind).reduce((a, f) => a + (f.n || 1), 0);
const totals = {
missingHeadings: sum('MISSING HEADING'), hiddenHeadings: sum('HIDDEN HEADING'), extraHeadings: sum('EXTRA HEADING'),
missingLinks: sum('MISSING LINK'), hiddenLinks: sum('HIDDEN LINK'), movedLinks: sum('MOVED LINK'), extraLinks: sum('EXTRA LINK'),
missingButtons: sum('MISSING BUTTON'), hiddenButtons: sum('HIDDEN BUTTON'),
controlState: findings.filter((f) => f.kind === 'CONTROL STATE').length, countDeltas: findings.filter((f) => f.kind.startsWith('COUNT')).length,
findings: findings.length, structural: findings.filter((f) => f.sev === '🔴').length,
};
totals.missing = totals.missingHeadings + totals.missingLinks; totals.hidden = totals.hiddenHeadings + totals.hiddenLinks;
return { scope, chrome, bands, findings, totals };
}
export function formatReport(res, { maxPerKind = 40 } = {}) {
const lines = [];
lines.push('| band | heading | links O/E (+hidden) | buttons O/E (+hidden) | text O/E | images O/E | findings |', '|---|---|---|---|---|---|---|');
for (const b of res.bands) lines.push(`| ${b.index} | ${b.heading.slice(0, 40)}${b.variable ? ' (variable)' : ''} | ${b.origin.link}/${b.eds.link}${b.eds.linkHidden ? ` (+${b.eds.linkHidden})` : ''} | ${b.origin.button}/${b.eds.button}${b.eds.buttonHidden ? ` (+${b.eds.buttonHidden})` : ''} | ${b.origin.text}/${b.eds.text} | ${b.origin.image}/${b.eds.image} | ${[...new Set(b.findings)].join(', ') || '-'} |`);
const seen = new Map();
for (const f of res.findings) { const n = (seen.get(f.kind) || 0) + 1; seen.set(f.kind, n); if (n <= maxPerKind) lines.push(` ${f.sev} ${f.kind}: ${f.msg}`); else if (n === maxPerKind + 1) lines.push(` … more ${f.kind} (${res.findings.filter((x) => x.kind === f.kind).length} total)`); }
const t = res.totals;
lines.push(`Content: MISSING ${t.missing} (headings ${t.missingHeadings}, links ${t.missingLinks}) / HIDDEN ${t.hidden} (headings ${t.hiddenHeadings}, links ${t.hiddenLinks}) / control-state ${t.controlState} / buttons missing ${t.missingButtons} hidden ${t.hiddenButtons} / moved ${t.movedLinks} extra ${t.extraLinks} / count deltas ${t.countDeltas}`);
lines.push(`Findings: ${t.findings ? `${t.findings} (${t.structural} structural 🔴)` : 'none — every visible origin heading and link is visible on the served page'}`);
return lines.join('\n');
}
// ---- CLI ---------------------------------------------------------------------------------------------
export function parseArgs(argv) {
const rest = argv.slice(2);
if (rest.length < 2 || rest.includes('--help') || rest.includes('-h')) { console.log(HELP); process.exit(rest.includes('--help') || rest.includes('-h') || !rest.length ? 0 : 1); }
const opts = { origin: null, eds: null, width: 1440, main: null, mainEds: null, variable: [], variableEds: [], json: false, jsonFile: null, minCut: 2, maxFindings: 40, plain: false, warmup: null, locale: 'en-US', chrome: false, settlePasses: 4, countWords: null, moreWords: null };
for (let i = 0; i < rest.length; i += 1) {
const a = rest[i];
if (a === '--width') opts.width = Number(rest[++i]);
else if (a === '--main') { const [o, e] = rest[++i].split('='); opts.main = o; opts.mainEds = e || o; }
else if (a === '--variable') { for (const s of rest[++i].split(',').map((x) => x.trim()).filter(Boolean)) { const [o, e] = s.split('='); opts.variable.push(o); opts.variableEds.push(e || o); } }
else if (a === '--json') { opts.json = true; if (rest[i + 1] && !rest[i + 1].startsWith('--')) opts.jsonFile = rest[++i]; }
else if (a === '--min-cut') opts.minCut = Number(rest[++i]);
else if (a === '--chrome') opts.chrome = true;
else if (a === '--settle-passes') opts.settlePasses = Number(rest[++i]);
else if (a === '--count-words') opts.countWords = rest[++i].split(',').map((w) => w.trim()).filter(Boolean).join('|');
else if (a === '--more-words') opts.moreWords = rest[++i];
else if (a === '--max-findings') opts.maxFindings = Number(rest[++i]);
else if (a === '--plain') opts.plain = true;
else if (a === '--warmup') opts.warmup = rest[++i];
else if (a === '--locale') opts.locale = rest[++i];
else if (a.startsWith('--')) { console.error(`unknown flag ${a}\n\n${HELP}`); process.exit(1); }
else if (!opts.origin) opts.origin = a; else if (!opts.eds) opts.eds = a;
}
if (!opts.origin || !opts.eds) { console.error(`need <originUrl> <edsUrl>\n\n${HELP}`); process.exit(1); }
return opts;
}
/** Inventory one side: visit + settle, presence inventory, clip inventory. */
export async function inventorySide(browser, url, { width, locale, warmup, rootSel, variableSels, minCut, settlePasses = 4, httpError = 'measure', countWords = null, moreWords = null }) {
const { ctx, page } = await openPage(browser, { width, locale, stateUrl: url });
try {
const v = await visit(page, url, { warmup, settle: { passes: settlePasses }, httpError });
const inv = await page.evaluate(inPage(presenceInventoryInPage, countWords ? { rootSel, variableSels, countWords } : { rootSel, variableSels }, morePrelude(moreWords)));
const clip = await page.evaluate(inPage(clipInventoryInPage, { minCut, rootSel: null, maxFindings: 400 }, morePrelude(moreWords)));
return { url, at: new Date().toISOString(), status: v.status, settlePasses: v.passes, ...inv, clip: { counts: clip.counts, groups: summarize(clip.findings), findings: clip.findings }, textBoxes: clip.textBoxes };
} finally { await ctx.close(); }
}
async function main() {
const opts = parseArgs(process.argv);
const browser = await openBrowser({ mode: opts.plain ? 'plain' : 'headed' });
let o; let e; let tier;
try {
tier = browserTier(browser);
// ORIGIN side fails loud on any HTTP ≥ 400 (a 403 page measured as the origin reads "100 EXTRA on the
// build"); the SERVED side is measured with a warning (a 404 build before preview propagation is the
// advisory contract).
o = await inventorySide(browser, opts.origin, { width: opts.width, locale: opts.locale, warmup: opts.warmup, rootSel: opts.main, variableSels: opts.variable, minCut: opts.minCut, settlePasses: opts.settlePasses, httpError: 'throw', countWords: opts.countWords, moreWords: opts.moreWords });
e = await inventorySide(browser, opts.eds, { width: opts.width, locale: opts.locale, warmup: null, rootSel: opts.mainEds, variableSels: opts.variableEds, minCut: opts.minCut, settlePasses: opts.settlePasses, countWords: opts.countWords, moreWords: opts.moreWords });
} finally { await browser.close(); }
const res = diffPresence(o, e, { chrome: opts.chrome });
const strip = (side) => ({ url: side.url, at: side.at, status: side.status, settlePasses: side.settlePasses, docH: side.docH, root: side.root, items: side.items, clip: { counts: side.clip.counts, groups: side.clip.groups } });
const out = { _provenance: { writtenBy: 'content-presence.mjs', at: new Date().toISOString(), width: opts.width, variable: opts.variable, tier }, origin: strip(o), eds: { ...strip(e), clip: e.clip }, bands: res.bands, findings: res.findings, totals: res.totals, textBoxes: { origin: o.textBoxes, eds: e.textBoxes } };
if (opts.json && !opts.jsonFile) console.log(JSON.stringify(out, null, 1));
else {
console.log(`content-presence @ ${opts.width}px (${tier}) — origin ${opts.origin} (docH ${o.docH}, ${o.items.length} items, HTTP ${o.status}) vs served ${opts.eds} (docH ${e.docH}, ${e.items.length} items, HTTP ${e.status})`);
console.log(`scope: ${res.scope === 'root' ? `${o.root} vs ${e.root}` : 'whole page (one side has no <main> / --main root)'}${res.chrome ? ' + chrome' : ' (header/footer left to the chrome crop gate; --chrome to include)'}`);
console.log(formatReport(res, { maxPerKind: opts.maxFindings }));
console.log(`Clipped (served side): ${e.clip.counts.total} — origin side ${o.clip.counts.total}`);
if (opts.jsonFile) { mkdirSync(dirname(opts.jsonFile) || '.', { recursive: true }); writeFileSync(opts.jsonFile, JSON.stringify(out, null, 1)); console.log(`json → ${opts.jsonFile}`); }
}
process.exitCode = res.totals.missing + res.totals.hidden > 0 ? 2 : 0;
}
function safeRealpath(p) { try { return realpathSync(p); } catch { return p; } }
if (process.argv[1] && fileURLToPath(import.meta.url) === safeRealpath(process.argv[1])) {
main().catch((err) => { console.error(`content-presence error: ${String(err.message).split('\n')[0]}`); process.exit(err.name === 'BotChallengeError' ? 3 : err.name === 'LiveHTTPError' ? 4 : 1); });
}.tessl-plugin
skills
audit
reference
deploy
reference
scripts
test
diff
direct
dynamics
extract
migrate
prepare-migration
prototype
assets
motion
fixtures
reference
qa
replica
reference
scripts
test
reskin
rollout
spec
stardust
uplift
reference