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
/**
* skills/replica/scripts/cap-probe.mjs — the content-cap probe (#124): the page's container
* sizing MODEL — which boxes stop growing, at what width, at which tier — measured on a page
* (capture) or compared live vs build (compare). Shared by extract (records the model into
* DESIGN.json), replica (the mandatory wide row of the pass bar) and deploy (qa-gate.mjs imports
* probePage for its wide pass).
*
* Why: both pixel gates run NARROWER than most caps — at 1440 a 1600 px article and a 1920 px
* shell are both wider than the viewport, so a build that renders edge to edge at every width
* passes both gates by construction (recorded: a live site with two nested centered caps, 1920
* shell + 1600 content; the build declared the token and never applied it; both gates green).
* A probe pinned AT a cap's width cannot see the cap either (at 1920 the shell reads as the
* viewport) — so the probe width is DERIVED, never fixed: max(2560, largest cap × 1.25).
*
* Method (one navigation per URL, no diff loop): render at the base width (1440), remember every
* visible box ≥ 240 px wide, then read the same boxes at the probe width and at 0.9 × the probe
* width (resizes, not navigations). A box is CAPPED when its width is identical at the two wide
* reads and short of the viewport — a 90 % container scales, a `max-width`/fixed box does not; a
* cap ORIGIN is a capped box whose parent is fluid, or that is narrower than its parent's content
* box by its own `max-width` / fixed `width` (padding and auto margins are layout, not caps). When
* a cap is found at ≥ probe ÷ 1.25 the probe width is re-derived and the wide reads repeated once.
* Kinds, by how much of the content root a cap holds: `shell` — the outermost cap holding ≥ 90 %
* of the root's text (or an ancestor of the root); `content` — a further cap inside it holding
* ≥ 90 %; `module` — a cap inside one top-level section (the root's children, descending through
* single-child wrappers); caps in header/footer are chrome and are not modelled. The
* page's contentMaxWidth is the innermost shell/content cap; without one, the module cap shared by
* at least half of the capped sections; else null (fluid). Compare pairs the two sides by KIND and
* by section order (never by DOM depth — EDS wrappers are full width by design).
*
* Usage:
* capture node cap-probe.mjs <url> [<url>…] [--main <sel>] [--write-design <DESIGN.json>]
* compare node cap-probe.mjs <live-url> --against <build-url> [--design <DESIGN.json>]
* [--slug <s> [--label <l>]] [--main <sel>] [--build-main <sel>]
* --width <px> base width (default 1440)
* --probe-width <px> PIN the probe width and skip derivation — evidence runs only (a probe
* at a cap's own width misses it); the default derives
* --tolerance <px> cap match tolerance in compare (default 20)
* --main <sel> content root on the live side (default: main, else body)
* --build-main <sel> content root on the build side (default: main)
* --design <file> compare: read extensions.breakpoints.probeWidth (and containerMaxWidth)
* so every skill probes at the width extract derived
* --write-design <file> capture: merge the model into <file> extensions.breakpoints —
* containerMaxWidth ("1600px" | null), probeWidth, caps[], modules[]
* --slug <s> compare: evidence to stardust/replica/gates/<slug>-<probeWidth>/
* cap-<label>.json (+ .txt), like the pixel rounds (--label default iter)
* --json / --out <file> the JSON on stdout / written to <file>
* --timeout-ms, --ua, --consent <sel>, --dismiss <sel,…>, --headed, --locale <tag> as measure.mjs
*
* Output (capture): per URL the probe width and its derivation, one line per cap origin (kind, px,
* via, selector, tier, share), a modules line (capped values × count, full-bleed count); then across
* URLs: `contentMaxWidth`, `shellMaxWidth`, `probeWidth`, and `consistent: yes|NO` — a cap that
* differs between archetypes, or a module cap on a single section, is a register item, not a token.
* Compare rows: `wrapper cap` (innermost shell/content cap, live vs build, ±tolerance; a live cap
* missing on the build, or a build cap over a fluid live, is ✗), `module i/n` per section (same
* rule; advisory when the section counts differ — fix structure first) and, when neither side has
* a wrapper, `content cap` (the shared module cap). Outer shell caps beyond the wrapper cap are
* informational. The verdict line:
* `cap-probe: PASS|FAIL at <probeWidth> — <n> of <m> rows…`. A ✗ names the sizing rule to fix
* (deploy Step 3 scaffold); never iterate pixels on it.
*
* Exit codes: 0 pass / measured, 2 compare FAIL, 1 a page failed to load or playwright missing,
* 3 bot challenge on the live side (escalate --headed), 125 usage. probePage and the pure
* functions (classifyCaps, deriveProbeWidth, aggregateCaps, compareCaps, formatCapture,
* formatCompare, parseArgs) are exported — the contract test runs them without a browser.
* Requires playwright importable from this file's location and the master skill's browser.mjs
* (../../stardust/scripts/ or ../stardust/ — replica SKILL.md § Setup copies both dirs as siblings).
*/
import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
import { dirname, resolve as resolvePath } from 'node:path';
import { fileURLToPath } from 'node:url';
// --help prints this file's usage header, so an agent never reads the source to learn the flags.
if (process.argv.includes('--help') || process.argv.includes('-h')) {
const src = readFileSync(new URL(import.meta.url), 'utf8');
const header = src.match(/\/\*\*[\s\S]*?\*\//);
console.log(header ? header[0].replace(/^\/\*\*\s*|\s*\*\/$/g, '').replace(/^\s*\* ?/gm, '').trim() : 'no usage header');
process.exit(0);
}
export const BASE_WIDTH = 1440;
export const MIN_PROBE_WIDTH = 2560;
export const PROBE_FACTOR = 1.25;
export const CAP_TOLERANCE = 20;
export const WRAPPER_SHARE = 0.9;
const VIEWPORT_H = 900;
const EDGE = 8; // px: a box this close to the viewport is full width
export class UsageError extends Error { constructor(msg) { super(msg); this.code = 125; } }
const BROWSER = ['../../stardust/scripts/browser.mjs', '../stardust/browser.mjs']
.map((p) => new URL(p, import.meta.url)).find((u) => existsSync(u));
async function loadLiveSession() {
if (!BROWSER) throw new UsageError('browser.mjs not found (looked in ../../stardust/scripts/ and ../stardust/). Copy the master skill\'s scripts dir to stardust/scripts/stardust/ (skills/stardust/SKILL.md § Setup).');
return import(BROWSER.href);
}
const splitList = (s) => String(s || '').split(',').map((x) => x.trim()).filter(Boolean);
export function parseArgs(argv) {
const o = { urls: [], against: null, width: BASE_WIDTH, probeWidth: null, tolerance: CAP_TOLERANCE, main: null, buildMain: 'main', design: null, writeDesign: null, slug: null, label: 'iter', json: false, out: null, timeoutMs: 30000, ua: null, consent: null, dismiss: [], headed: false, locale: null };
const need = (i, flag) => { if (i + 1 >= argv.length || argv[i + 1].startsWith('--')) throw new UsageError(`${flag} needs a value`); return argv[i + 1]; };
const int = (v, flag) => { const n = Number(v); if (!Number.isInteger(n) || n <= 0) throw new UsageError(`${flag} must be a positive integer, got ${v}`); return n; };
for (let i = 0; i < argv.length; i += 1) {
const a = argv[i];
if (a === '--against') { o.against = need(i, a); i += 1; }
else if (a === '--width') { o.width = int(need(i, a), a); i += 1; }
else if (a === '--probe-width') { o.probeWidth = int(need(i, a), a); i += 1; }
else if (a === '--tolerance') { o.tolerance = int(need(i, a), a); i += 1; }
else if (a === '--main') { o.main = need(i, a); i += 1; }
else if (a === '--build-main') { o.buildMain = need(i, a); i += 1; }
else if (a === '--design') { o.design = need(i, a); i += 1; }
else if (a === '--write-design') { o.writeDesign = need(i, a); i += 1; }
else if (a === '--slug') { o.slug = need(i, a); i += 1; }
else if (a === '--label') { o.label = need(i, a); i += 1; }
else if (a === '--json') { o.json = true; }
else if (a === '--out') { o.out = need(i, a); i += 1; }
else if (a === '--timeout-ms') { o.timeoutMs = int(need(i, a), a); i += 1; }
else if (a === '--ua') { o.ua = need(i, a); i += 1; }
else if (a === '--consent') { o.consent = need(i, a); i += 1; }
else if (a === '--dismiss') { o.dismiss.push(...splitList(need(i, a))); i += 1; }
else if (a === '--headed') { o.headed = true; }
else if (a === '--locale') { o.locale = need(i, a); i += 1; }
else if (a.startsWith('--')) { throw new UsageError(`unknown flag ${a} (see --help)`); }
else { o.urls.push(a); }
}
if (!o.urls.length) throw new UsageError('need <url> (see --help)');
if (o.against && o.urls.length > 1) throw new UsageError('compare takes ONE live url and --against <build-url>');
if (o.against && o.writeDesign) throw new UsageError('--write-design is a capture flag; compare reads --design');
if (o.slug && !o.against) throw new UsageError('--slug records compare evidence; it needs --against');
if (o.probeWidth && o.probeWidth <= o.width) throw new UsageError(`--probe-width must exceed the base width ${o.width}`);
return o;
}
// ---- in-page passes (serialised by playwright — no outer-scope references) -----------------------
/* eslint-disable no-undef */
// Pass 1 at the base width: remember every visible box ≥ 240 px wide with its base width, and the
// content root. Stored on window so pass 2 reads the SAME elements after the resize (no DOM stamping).
function basePassInPage({ rootSel }) {
const vis = (el) => { const r = el.getBoundingClientRect(); const cs = getComputedStyle(el); return r.width > 0 && r.height > 0 && cs.display !== 'none' && cs.visibility !== 'hidden'; };
const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'SVG', 'PATH', 'G', 'USE', 'DEFS', 'BR', 'IFRAME']);
let root = null;
if (rootSel) { try { root = document.querySelector(rootSel); } catch { root = null; } }
const rootMatched = !rootSel || !!root;
if (!root) root = document.querySelector('main') || document.body;
const els = []; const base = [];
for (const el of [document.body, ...document.body.querySelectorAll('*')]) {
if (SKIP.has(el.tagName.toUpperCase()) || !vis(el)) continue;
const r = el.getBoundingClientRect();
if (r.width < 240 || r.height < 24) continue;
els.push(el); base.push(Math.round(r.width));
}
window.__capProbe = { els, base, root, rootSel: rootSel || null };
return { viewport: document.documentElement.clientWidth, candidates: els.length, rootMatched, rootIsBody: root === document.body };
}
// Pass 2 at the probe width: the same boxes, with everything the classifier needs.
function probePassInPage() {
const S = window.__capProbe;
const vw = document.documentElement.clientWidth;
const norm = (s) => String(s || '').replace(/\s+/g, ' ').trim();
const cssPath = (el) => {
const parts = [];
for (let n = el; n && n.nodeType === 1 && n !== document.documentElement && parts.length < 4; n = n.parentElement) {
const tag = n.tagName.toLowerCase();
if (n.id && /^[A-Za-z][\w-]{0,40}$/.test(n.id) && !/\d{3,}/.test(n.id)) { parts.unshift(`#${n.id}`); break; }
const cls = [...n.classList].filter((c) => /^[A-Za-z][\w-]{0,30}$/.test(c) && !/\d{3,}/.test(c)).slice(0, 2);
parts.unshift(tag + (cls.length ? `.${cls.join('.')}` : ''));
}
return parts.join(' > ');
};
const { root } = S;
// Text leaves of the root: what "holds the content" is measured against.
const leaves = [];
for (const el of root.querySelectorAll('*')) {
if (!el.getClientRects().length) continue;
for (const n of el.childNodes) if (n.nodeType === 3 && norm(n.nodeValue)) { leaves.push(el); break; }
}
// Top-level sections: the root's children — descending through single-child wrappers (a live
// `main > div.content > div.wrapper > section*` is common) until a node has two or more.
// A wrapper whose children are fixed/absolute has no height of its own — it qualifies when it holds text.
const qualifying = (node) => [...node.children].filter((kid) => { const r = kid.getBoundingClientRect(); return r.width > 0 && getComputedStyle(kid).display !== 'none' && (r.height >= 40 || leaves.some((l) => kid.contains(l))); });
let sectionRoot = root; let kids = qualifying(sectionRoot);
for (let guard = 0; kids.length === 1 && guard < 8; guard += 1) { sectionRoot = kids[0]; kids = qualifying(sectionRoot); }
const sections = kids.map((kid) => { const r = kid.getBoundingClientRect(); return { el: kid, selector: cssPath(kid), w: Math.round(r.width), h: Math.round(r.height) }; });
const sectionOf = (el) => { for (let i = 0; i < sections.length; i += 1) if (sections[i].el.contains(el)) return i; return -1; };
const depthFromRoot = (el) => {
if (el.contains(root)) { let d = 0; for (let n = root; n && n !== el; n = n.parentElement) d -= 1; return d; }
let d = 0; for (let n = el; n && n !== root; n = n.parentElement) d += 1; return d;
};
const chromeOf = (el) => !!(el.closest('header, footer, nav, [role="banner"], [role="contentinfo"]'));
const idx = new Map(S.els.map((e, k) => [e, k]));
const boxes = [];
S.els.forEach((el, i) => {
if (!el.isConnected) return;
const r = el.getBoundingClientRect(); const cs = getComputedStyle(el);
if (r.width <= 0 || cs.display === 'none') return;
const p = el.parentElement; const pr = p ? p.getBoundingClientRect() : null; const pcs = p ? getComputedStyle(p) : null;
const inRoot = root.contains(el); const aboveRoot = el !== root && el.contains(root);
let held = 0;
if (aboveRoot) held = leaves.length; else if (inRoot) for (const l of leaves) if (el.contains(l)) held += 1;
const contentBearing = held > 0 || !!el.querySelector('img, picture, video, svg, canvas');
boxes.push({
i, selector: cssPath(el), tag: el.tagName.toLowerCase(),
w1: S.base[i], w2: Math.round(r.width), h2: Math.round(r.height),
maxWidth: cs.maxWidth, boxSizing: cs.boxSizing, padL: parseFloat(cs.paddingLeft) || 0, padR: parseFloat(cs.paddingRight) || 0,
parent: p ? { i: idx.has(p) ? idx.get(p) : -1, w2: Math.round(pr.width), padL: parseFloat(pcs.paddingLeft) || 0, padR: parseFloat(pcs.paddingRight) || 0 } : null,
share: leaves.length ? held / leaves.length : 0, contentBearing,
inRoot, aboveRoot, isRoot: el === root, tier: depthFromRoot(el), section: inRoot && !aboveRoot ? sectionOf(el) : -1,
chrome: el !== root && !aboveRoot && chromeOf(el), // header/nav/footer caps are chrome wherever they sit
});
});
return { viewport: vw, root: { selector: cssPath(root), isBody: root === document.body, leaves: leaves.length, w2: Math.round(root.getBoundingClientRect().width) }, sections: sections.map(({ selector, w, h }) => ({ selector, w, h })), boxes };
}
// Pass 3 at 0.9 × the probe width: the same boxes' widths only, by index.
function wideReadInPage() {
return window.__capProbe.els.map((el) => (el.isConnected ? Math.round(el.getBoundingClientRect().width) : null));
}
/* eslint-enable no-undef */
// ---- classification (pure) ------------------------------------------------------------------------
// Capped = the same width at the two wide reads (probe and 0.9 × probe) while short of the viewport:
// a 90 % container scales between them, a max-width/fixed box does not. Without a third read (older
// fixtures) fall back to the growth test: full width at the probe, or a constant share of the
// viewport (a `width: 50%` column), is fluid; everything else stopped growing somewhere.
export function isCapped(b, baseWidth, probeWidth) {
if (b.w2 >= probeWidth - EDGE) return false;
if (Number.isFinite(b.w3)) return Math.abs(b.w2 - b.w3) <= 1;
const grew = b.w2 - b.w1; const dv = probeWidth - baseWidth;
if (grew >= dv - EDGE) return false;
const proportional = Math.abs(b.w2 / probeWidth - b.w1 / baseWidth) < 0.02 && b.w1 < baseWidth - EDGE;
return !proportional;
}
// How the cap is authored: its own max-width (content-box adds the padding), a fixed px width (same
// at both reads), or anything else (clamp(), min(), a percentage of a capped parent, …).
export function capVia(b) {
const mw = parseFloat(b.maxWidth);
if (Number.isFinite(mw)) { const own = mw + (b.boxSizing === 'content-box' ? b.padL + b.padR : 0); if (Math.abs(own - b.w2) <= 2) return 'max-width'; }
if (Math.abs(b.w2 - b.w1) <= 1) return 'fixed';
return 'other';
}
// Boxes → cap origins with kinds, the per-section module map, and the page's content cap.
export function classifyCaps(pass, { baseWidth = BASE_WIDTH, probeWidth = MIN_PROBE_WIDTH } = {}) {
const byIndex = new Map(pass.boxes.map((b) => [b.i, b]));
const capped = new Map();
for (const b of pass.boxes) capped.set(b.i, isCapped(b, baseWidth, probeWidth));
const origins = [];
for (const b of pass.boxes) {
if (!capped.get(b.i) || !b.contentBearing || b.chrome) continue;
const p = b.parent && byIndex.get(b.parent.i);
const parentCapped = p ? capped.get(p.i) : false;
const via = capVia(b);
if (parentCapped) {
const parentContent = b.parent.w2 - b.parent.padL - b.parent.padR;
if (b.w2 >= parentContent - 2 || via === 'other') continue; // inherited width, or padding/margins — layout, not a cap
}
origins.push({ kind: null, px: b.w2, via, selector: b.selector, tier: b.tier, share: Math.round(b.share * 100) / 100, section: b.section, w1: b.w1, maxWidth: b.maxWidth });
}
// Wrappers: hold ≥ 90 % of the root's text (ancestors of the root hold all of it). Outermost first.
const wrappers = origins.filter((o) => o.share >= WRAPPER_SHARE || o.tier <= 0).sort((a, b) => a.tier - b.tier || b.px - a.px);
wrappers.forEach((o, k) => { o.kind = k === 0 ? 'shell' : 'content'; });
for (const o of origins) if (!o.kind) o.kind = o.section >= 0 ? 'module' : 'other';
// One module cap per section: the widest module origin inside it (the section's content column).
const modules = pass.sections.map((s, index) => {
const inSection = origins.filter((o) => o.kind === 'module' && o.section === index);
const top = inSection.sort((a, b) => b.px - a.px)[0] || null;
return { index, selector: s.selector, px: top ? top.px : null, capSelector: top ? top.selector : null };
});
const shell = wrappers[0] || null;
const innerWrapper = wrappers[wrappers.length - 1] || null;
let contentMaxWidth = innerWrapper ? innerWrapper.px : null; let contentFrom = innerWrapper ? innerWrapper.kind : null;
if (contentMaxWidth === null) {
const cappedModules = modules.filter((m) => m.px !== null);
const groups = groupPx(cappedModules.map((m) => m.px));
if (groups.length && groups[0].count * 2 >= cappedModules.length && cappedModules.length) { contentMaxWidth = groups[0].px; contentFrom = 'module'; }
}
const maxCap = origins.reduce((m, o) => Math.max(m, o.px), 0);
return { baseWidth, probeWidth, root: pass.root, origins, modules, shellMaxWidth: shell ? shell.px : null, contentMaxWidth, contentFrom, maxCap, fluid: !origins.length };
}
// px values → groups within the tolerance, most frequent first (then widest).
export function groupPx(values, tol = CAP_TOLERANCE) {
const groups = [];
for (const v of [...values].sort((a, b) => b - a)) {
const g = groups.find((x) => Math.abs(x.px - v) <= tol);
if (g) g.count += 1; else groups.push({ px: v, count: 1 });
}
return groups.sort((a, b) => b.count - a.count || b.px - a.px);
}
// max(2560, largest cap × 1.25) — a probe AT a cap's width cannot see the cap.
export function deriveProbeWidth(maxCap) { return Math.max(MIN_PROBE_WIDTH, Math.ceil((maxCap || 0) * PROBE_FACTOR)); }
// Several archetypes → one model: caps grouped by kind + px with the pages that carry them, the
// content/shell cap when every page agrees (±tolerance), and the register items when they don't.
export function aggregateCaps(perUrl, tol = CAP_TOLERANCE) {
const urls = Object.keys(perUrl);
const caps = [];
for (const url of urls) for (const o of perUrl[url].origins) {
if (o.kind === 'other') continue;
const g = caps.find((c) => c.kind === o.kind && Math.abs(c.px - o.px) <= tol);
if (g) { if (!g.pages.includes(url)) g.pages.push(url); } else caps.push({ kind: o.kind, px: o.px, via: o.via, selector: o.selector, pages: [url] });
}
caps.sort((a, b) => ['shell', 'content', 'module'].indexOf(a.kind) - ['shell', 'content', 'module'].indexOf(b.kind) || b.px - a.px);
const agree = (key) => {
const vals = urls.map((u) => perUrl[u][key]);
const set = vals.filter((v) => v !== null);
if (!set.length) return { value: null, consistent: true, perUrl: vals };
const g = groupPx(set, tol)[0];
return { value: g.px, consistent: set.length === vals.length && g.count === set.length, perUrl: vals };
};
const content = agree('contentMaxWidth'); const shell = agree('shellMaxWidth');
const register = [];
if (!content.consistent) register.push(`contentMaxWidth differs between archetypes: ${urls.map((u, i) => `${content.perUrl[i] ?? 'fluid'} (${u})`).join(', ')} — decide per template in the inconsistency register`);
if (!shell.consistent) register.push(`shellMaxWidth differs between archetypes: ${urls.map((u, i) => `${shell.perUrl[i] ?? 'fluid'} (${u})`).join(', ')}`);
for (const c of caps) if (c.kind === 'module' && c.pages.length === 1 && urls.length > 1) {
const page = perUrl[c.pages[0]]; const n = page.modules.filter((m) => m.px !== null && Math.abs(m.px - c.px) <= tol).length;
if (n === 1) register.push(`module cap ${c.px}px on a single section (${c.selector}, ${c.pages[0]}) — intent or mistake? register it`);
}
const maxCap = Math.max(0, ...urls.map((u) => perUrl[u].maxCap));
const modules = urls.flatMap((u) => perUrl[u].modules.map((m) => ({ url: u, section: m.index, selector: m.selector, px: m.px })));
return { containerMaxWidth: content.value === null ? null : `${content.value}px`, contentMaxWidth: content.value, shellMaxWidth: shell.value, consistent: content.consistent && shell.consistent && !register.length, probeWidth: deriveProbeWidth(maxCap), caps, modules, register };
}
// Live model vs build model → rows and a verdict. Pairing is by KIND and by section order: the
// wrapper row (innermost shell/content cap) first, then one module row per top-level section; when
// neither side has a wrapper the module-derived content cap gets its own row so a section-count
// mismatch (advisory module rows) still leaves one deciding row.
export function compareCaps(live, build, tol = CAP_TOLERANCE) {
const rows = [];
const row = (ok, label, detail, advisory = false) => rows.push({ ok, label, detail, advisory });
const wrapperOf = (m) => { const w = m.origins.filter((o) => o.kind === 'shell' || o.kind === 'content'); return w.length ? w[w.length - 1] : null; };
const rule = (px, tier) => `fix the sizing rule, not pixels — deploy Step 3 scaffold: ${tier === 'wrapper' ? `main { max-width: ${px}px; margin: 0 auto }` : `main > .section > div { max-width: ${px}px; margin: 0 auto }`}`;
const lw = wrapperOf(live); const bw = wrapperOf(build);
const modulesNote = (m) => { const c = m.modules.filter((x) => x.px !== null); return c.length ? `module caps only: ${groupPx(c.map((x) => x.px), tol).map((g) => `${g.px}px ×${g.count}`).join(', ')}` : 'no cap at all'; };
if (lw && !bw) row(false, 'wrapper cap', `live ${lw.px}px (${lw.kind}, ${lw.selector}) → build NONE: content runs ${build.root.w2}px wide at ${build.probeWidth} (${modulesNote(build)}) — ${rule(lw.px, 'wrapper')}`);
else if (!lw && bw) row(false, 'wrapper cap', `build ${bw.px}px (${bw.selector}) but live has no wrapper cap (${modulesNote(live)}; live content runs ${live.root.w2}px at ${live.probeWidth}) — fix the sizing rule, not pixels: remove the wrapper cap, the live site does not have one`);
else if (lw && bw && Math.abs(lw.px - bw.px) <= tol) row(true, 'wrapper cap', `live ${lw.px}px = build ${bw.px}px (±${tol})`);
else if (lw && bw) row(false, 'wrapper cap', `live ${lw.px}px (${lw.selector}) → build ${bw.px}px (${bw.selector}), Δ${bw.px - lw.px}px — ${rule(lw.px, 'wrapper')}`);
else {
const L = live.contentMaxWidth; const B = build.contentMaxWidth;
if (L === null && B === null) row(true, 'content cap', 'fluid on both sides — no wrapper, no shared module cap');
else if (L !== null && B === null) row(false, 'content cap', `live ${L}px (${modulesNote(live)}) → build NONE: content runs ${build.root.w2}px wide at ${build.probeWidth} — ${rule(L, 'module')}`);
else if (L === null && B !== null) row(false, 'content cap', `build ${B}px (${modulesNote(build)}) but live modules are fluid — fix the sizing rule, not pixels: remove the module cap`);
else if (Math.abs(L - B) <= tol) row(true, 'content cap', `live ${L}px = build ${B}px (±${tol}, shared module cap)`);
else row(false, 'content cap', `live ${L}px → build ${B}px, Δ${B - L}px (shared module cap) — ${rule(L, 'module')}`);
}
for (const o of live.origins.filter((x) => (x.kind === 'shell' || x.kind === 'content') && x !== lw)) row(true, `outer ${o.kind}`, `live ${o.px}px (${o.selector}) encloses the ${lw.px}px wrapper cap — informational, no content bound of its own`, true);
const advisory = live.modules.length !== build.modules.length;
if (advisory) row(true, 'sections', `live ${live.modules.length} vs build ${build.modules.length} top-level sections — module rows compared by order up to the shorter side, advisory until the structure matches`, true);
const n = Math.min(live.modules.length, build.modules.length);
for (let i = 0; i < n; i += 1) {
const a = live.modules[i]; const b = build.modules[i]; const label = `module ${i + 1}/${live.modules.length}`;
if (a.px === null && b.px === null) row(true, label, 'full-bleed on both');
else if (a.px !== null && b.px === null) row(advisory, label, `live ${a.px}px (${a.capSelector}) → build full-bleed (${b.selector})`, advisory);
else if (a.px === null && b.px !== null) row(advisory, label, `live full-bleed (${a.selector}) → build ${b.px}px (${b.capSelector})`, advisory);
else if (Math.abs(a.px - b.px) <= tol) row(true, label, `${a.px}px = ${b.px}px`);
else row(advisory, label, `live ${a.px}px → build ${b.px}px, Δ${b.px - a.px}px (${b.capSelector})`, advisory);
}
const fails = rows.filter((r) => !r.ok).length;
return { probeWidth: live.probeWidth, rows, fails, pass: fails === 0 };
}
// ---- formatting (pure) ----------------------------------------------------------------------------
const pxs = (v) => (v === null || v === undefined ? 'fluid' : `${v}px`);
export function formatModel(m) {
const lines = [];
if (!m.origins.length) lines.push(` no cap origin — content runs ${m.root.w2}px wide at ${m.probeWidth} (fluid)`);
for (const o of m.origins.filter((x) => x.kind === 'shell' || x.kind === 'content')) lines.push(` ${o.kind.padEnd(8)} ${String(o.px).padStart(5)}px ${o.via.padEnd(9)} ${o.selector} (tier ${o.tier}, holds ${Math.round(o.share * 100)}% of the text)`);
const other = m.origins.filter((x) => x.kind === 'other');
if (other.length) lines.push(` other ${other.length} capped box(es) outside the section tier (in the JSON) — e.g. ${other[0].px}px ${other[0].selector}`);
const capped = m.modules.filter((x) => x.px !== null);
const groups = groupPx(capped.map((x) => x.px)).map((g) => `${g.px} ×${g.count}`).join(', ');
lines.push(` modules ${m.modules.length} sections: ${capped.length ? `capped ${groups}` : 'none capped'} · full-bleed ×${m.modules.length - capped.length}`);
lines.push(` contentMaxWidth ${pxs(m.contentMaxWidth)}${m.contentFrom ? ` (${m.contentFrom})` : ''} · shellMaxWidth ${pxs(m.shellMaxWidth)} · root ${m.root.selector}`);
return lines.join('\n');
}
export function formatCapture(result) {
const out = [];
for (const [url, m] of Object.entries(result.pages)) { out.push(`${url} base ${m.baseWidth} → probe ${m.probeWidth}${m.probeNote ? ` (${m.probeNote})` : ''}`); out.push(formatModel(m)); }
const a = result.aggregate;
if (a) {
out.push(`contentMaxWidth: ${a.containerMaxWidth ?? 'null (fluid)'} shellMaxWidth: ${pxs(a.shellMaxWidth)} probeWidth: ${a.probeWidth} consistent: ${a.consistent ? 'yes' : 'NO'}`);
for (const r of a.register) out.push(` register: ${r}`);
}
return out.join('\n');
}
export function formatCompare(result) {
const out = [`cap-probe base ${result.live.baseWidth} → probe ${result.live.probeWidth} (${result.probeNote})`, `live ${result.urls[0]}`, formatModel(result.live), `build ${result.urls[1]}`, formatModel(result.build), 'rows'];
for (const r of result.compare.rows) out.push(` ${r.ok ? (r.advisory ? '⚠' : '✓') : '✗'} ${r.label}: ${r.detail}`);
out.push(`cap-probe: ${result.compare.pass ? 'PASS' : 'FAIL'} at ${result.live.probeWidth} — ${result.compare.fails} of ${result.compare.rows.length} rows failed${result.evidence ? ` (evidence ${result.evidence})` : ''}`);
return out.join('\n');
}
// ---- browser ---------------------------------------------------------------------------------------
export function isLiveHttpUrl(url) {
try { const u = new URL(url); return /^https?:$/.test(u.protocol) && !/^(localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0)$/.test(u.hostname); } catch { return false; }
}
async function settle(page) {
await page.evaluate(async () => {
const h = document.documentElement.scrollHeight;
for (let y = 0; y < h; y += 700) { window.scrollTo(0, y); await new Promise((r) => { setTimeout(r, 80); }); }
window.scrollTo(0, 0);
await new Promise((r) => { setTimeout(r, 400); });
});
await page.waitForTimeout(300);
}
// The two-pass read on an OPEN page (qa-gate.mjs calls this on its own page). Returns the classified
// model; `probeWidth` pins the width, otherwise it derives from what the first wide read found.
export async function probePage(page, { rootSel = null, baseWidth = BASE_WIDTH, probeWidth = null } = {}) {
await page.setViewportSize({ width: baseWidth, height: VIEWPORT_H });
await settle(page);
const base = await page.evaluate(basePassInPage, { rootSel });
if (!base.rootMatched) console.error(`cap-probe: root selector "${rootSel}" matched nothing — probing under main (else body)`);
let width = probeWidth || MIN_PROBE_WIDTH; let note = probeWidth ? 'pinned' : `derived: max(${MIN_PROBE_WIDTH}, largest cap × ${PROBE_FACTOR})`;
const wideReads = async (w) => {
await page.setViewportSize({ width: w, height: VIEWPORT_H });
await settle(page);
const pass = await page.evaluate(probePassInPage);
await page.setViewportSize({ width: Math.round(w * 0.9), height: VIEWPORT_H });
await settle(page);
const w3 = await page.evaluate(wideReadInPage);
for (const b of pass.boxes) b.w3 = w3[b.i];
return classifyCaps(pass, { baseWidth, probeWidth: w });
};
let model = await wideReads(width);
const derived = deriveProbeWidth(model.maxCap);
if (!probeWidth && derived > width) {
width = derived; note = `derived: ${model.maxCap} × ${PROBE_FACTOR} → ${width}, re-read once`;
model = await wideReads(width);
}
return { ...model, probeNote: note, candidates: base.candidates };
}
async function openAndProbe(browser, url, o, session, { rootSel, probeWidth }) {
const { goto, newContext } = session;
const live = isLiveHttpUrl(url);
const viewport = { width: o.width, height: VIEWPORT_H };
const common = { reducedMotion: 'reduce', colorScheme: 'light', ignoreHTTPSErrors: true };
const context = live
? await session.newLiveContext(browser, { ua: o.ua, locale: o.locale, viewport, stateUrl: url, ...common })
: await newContext(browser, { ...(o.ua ? { userAgent: o.ua } : {}), viewport, locale: 'en-US', ...common });
const page = await context.newPage();
try {
if (live) {
await session.gotoLive(page, url, { waitUntil: session.defaultWaitUntil(url), timeoutMs: o.timeoutMs, settleMs: 1500, solveWindow: o.headed });
const d = await session.dismissOverlays(page, { extra: [...(o.consent ? [o.consent] : []), ...o.dismiss], lateWindowMs: 6000 });
for (const sel of [d.consent, ...d.extra, ...d.marketing].filter(Boolean)) console.error(`cap-probe: overlay dismissed via ${sel}`);
} else {
const resp = await goto(page, url, { waitUntil: 'networkidle', timeout: o.timeoutMs });
if (resp && resp.status() >= 400) throw new Error(`HTTP ${resp.status()}`);
}
return await probePage(page, { rootSel, baseWidth: o.width, probeWidth });
} finally {
await context.close().catch(() => {});
}
}
// DESIGN.json: read the persisted sizing model / merge the measured one into extensions.breakpoints.
export function readDesignSizing(file) {
if (!file || !existsSync(file)) return null;
const bp = ((JSON.parse(readFileSync(file, 'utf8')) || {}).extensions || {}).breakpoints || {};
const cmw = parseFloat(bp.containerMaxWidth);
return { probeWidth: Number.isInteger(bp.probeWidth) ? bp.probeWidth : null, containerMaxWidth: Number.isFinite(cmw) ? cmw : null };
}
export function mergeDesign(text, aggregate, provenance) {
const data = JSON.parse(text);
data.extensions = data.extensions || {};
const bp = (data.extensions.breakpoints = data.extensions.breakpoints || {});
bp.containerMaxWidth = aggregate.containerMaxWidth;
bp.probeWidth = aggregate.probeWidth;
bp.shellMaxWidth = aggregate.shellMaxWidth === null ? null : `${aggregate.shellMaxWidth}px`;
bp.caps = aggregate.caps.map(({ kind, px, via, selector, pages }) => ({ kind, px, via, selector, pages }));
bp.modules = aggregate.modules;
bp.capRegister = aggregate.register;
bp.capProvenance = provenance;
const m = text.match(/^[{[]\r?\n([ \t]+)/);
return `${JSON.stringify(data, null, m ? m[1] : 2)}${text.endsWith('\n') ? '\n' : ''}`;
}
async function main(argv) {
const o = parseArgs(argv);
const session = await loadLiveSession();
const { loadPlaywright, openBrowser } = session;
try { await loadPlaywright(); } catch (e) { throw Object.assign(new Error(e.message), { code: 1 }); }
const provenance = { writtenBy: 'skills/replica/scripts/cap-probe.mjs', writtenAt: new Date().toISOString(), baseWidth: o.width };
const browser = await openBrowser(o.headed ? { mode: 'headed' } : { mode: 'plain', launchOptions: { headless: true } });
let result; let code = 0;
try {
if (o.against) {
const design = readDesignSizing(o.design);
if (o.design && !design) console.error(`cap-probe: --design ${o.design} not found — deriving the probe width from the live side`);
const pinned = o.probeWidth || (design && design.probeWidth) || null;
const live = await openAndProbe(browser, o.urls[0], o, session, { rootSel: o.main, probeWidth: pinned });
const build = await openAndProbe(browser, o.against, o, session, { rootSel: o.buildMain, probeWidth: live.probeWidth });
const compare = compareCaps(live, build, o.tolerance);
const probeNote = o.probeWidth ? 'pinned by --probe-width' : (design && design.probeWidth ? `from ${o.design}` : live.probeNote);
result = { _provenance: { ...provenance, urls: [o.urls[0], o.against], probeWidth: live.probeWidth, probeNote, tolerance: o.tolerance }, urls: [o.urls[0], o.against], probeNote, live, build, compare };
if (design && design.containerMaxWidth !== null && live.contentMaxWidth !== null && Math.abs(design.containerMaxWidth - live.contentMaxWidth) > o.tolerance) console.error(`cap-probe: DESIGN.json containerMaxWidth ${design.containerMaxWidth}px differs from the live content cap ${live.contentMaxWidth}px — re-run capture with --write-design`);
if (o.slug) {
const dir = `stardust/replica/gates/${o.slug}-${live.probeWidth}`;
mkdirSync(dir, { recursive: true });
result.evidence = `${dir}/cap-${o.label}.json`;
writeFileSync(result.evidence, JSON.stringify(result, null, 2));
writeFileSync(`${dir}/cap-${o.label}.txt`, `${formatCompare(result)}\n`);
}
code = compare.pass ? 0 : 2;
} else {
const pages = {}; const failed = [];
for (const url of o.urls) {
try { pages[url] = await openAndProbe(browser, url, o, session, { rootSel: o.main, probeWidth: o.probeWidth }); } catch (e) {
if (e.name === 'BotChallengeError') { e.code = 3; throw e; }
const msg = String(e.message || e).split('\n')[0]; failed.push({ url, error: msg }); console.error(`cap-probe: ${url} failed to load — ${msg}`);
}
}
const aggregate = Object.keys(pages).length ? aggregateCaps(pages, o.tolerance) : null;
result = { _provenance: { ...provenance, urls: o.urls, failed, pinned: o.probeWidth }, pages, aggregate };
if (o.writeDesign && aggregate) {
const text = existsSync(o.writeDesign) ? readFileSync(o.writeDesign, 'utf8') : '{}\n';
mkdirSync(dirname(resolvePath(o.writeDesign)), { recursive: true });
writeFileSync(o.writeDesign, mergeDesign(text, aggregate, { ...provenance, urls: Object.keys(pages) }));
console.error(`cap-probe: ${o.writeDesign} extensions.breakpoints ← containerMaxWidth ${aggregate.containerMaxWidth}, probeWidth ${aggregate.probeWidth}, ${aggregate.caps.length} caps, ${aggregate.modules.length} modules`);
}
code = failed.length ? 1 : 0;
}
} finally {
await browser.close().catch(() => {});
}
if (o.out) { mkdirSync(dirname(resolvePath(o.out)), { recursive: true }); writeFileSync(o.out, JSON.stringify(result, null, 2)); }
console.log(o.json ? JSON.stringify(result, null, 2) : (o.against ? formatCompare(result) : formatCapture(result)));
return code;
}
// Compare by real path: a symlinked checkout or temp dir must not turn the CLI into a silent no-op.
function safeRealpath(p) { try { return realpathSync(p); } catch { return p; } }
if (process.argv[1] && fileURLToPath(import.meta.url) === safeRealpath(process.argv[1])) {
main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (e) => {
const blocked = e.name === 'BotChallengeError';
console.error(`cap-probe: ${blocked ? 'BLOCKED (bot challenge on the live side — escalate --headed) — ' : ''}${e.message}`);
process.exitCode = blocked ? 3 : (e.code || 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