styleproof 3.19.0 → 3.21.0

package/dist/report.d.ts

@@ -1,5 +1,5 @@
-import { type PropChange } from './diff.js';
 export { describeChange, colorName, tokenIndex, toHex } from './describe.js';
+export { summarizeProps, prettyLabel } from './change-groups.js';
 /**
  * Visual diff report: for every surface with findings, crop the before/after
  * full-page screenshots around the changed elements and write a markdown
@@ -77,8 +77,5 @@ export type ReportResult = {
     reportMdPath: string;
     reportJsonPath: string;
 };
-export declare function summarizeProps(props: PropChange[]): PropChange[];
-/** `div.who-grid`, `a.nav-cta`, `h3` — the semantic marker class, else the tag. */
-export declare function prettyLabel(p: string, cls: string): string;
 export declare function excerptPair(before: string, after: string): [string, string];
 export declare function generateStyleMapReport(opts: ReportOptions): ReportResult;

package/dist/report.js

@@ -1,16 +1,22 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { PNG } from 'pngjs';
-import { loadStyleMap, readInventories, } from './capture.js';
+import { loadStyleMap, readInventories, surfaceElementPaths, } from './capture.js';
 import { isMapFile } from './map-store.js';
 import { fillRect } from './png-util.js';
 import { diffStyleMapDirs, diffContentDirs, } from './diff.js';
-import { describeChange, tokenIndex, toHex, trackCount } from './describe.js';
+import { describeChange, tokenIndex, toHex } from './describe.js';
 import { auditCoverage, auditDeterminism, COVERAGE_LEDGER, } from './coverage.js';
 import { auditRunInventory, readAckFile } from './inventory.js';
+// The pure grouping / classification brain — shared with the CLI. report.ts keeps
+// the crop-and-PNG rendering on top of these.
+import { cleanFindings, groupByPath, groupTitle, isNonValue, prettyLabel, safeKey, signatureOf, summarizeProps, surfaceBase, surfaceWidth, pushSurfaceWidth, renderSurfaceGroups, formatSurfaceList, classifyChrome, } from './change-groups.js';
 // Re-export the plain-English summariser so consumers (and tests) reach it
 // through the package's report module rather than a deep path.
 export { describeChange, colorName, tokenIndex, toHex } from './describe.js';
+// Re-export the grouping primitives historically exported from here so existing
+// imports (`from 'styleproof'` → report) keep resolving.
+export { summarizeProps, prettyLabel } from './change-groups.js';
 // Hidden marker appended to a new-surface heading. Invisible in rendered
 // markdown; lets the PR-comment layer recognize one-sided surfaces.
 const NEW_SURFACE_MARKER = '<!-- styleproof-new -->';
@@ -52,16 +58,6 @@ function changeCountLabel(shown) {
         parts.push(`${shown.state} state-delta difference(s)`);
     return parts.join(' · ');
 }
-/** Group findings by their element path (one group per changed element). */
-function groupByPath(findings) {
-    const byPath = new Map();
-    for (const f of findings) {
-        const arr = byPath.get(f.path) ?? [];
-        arr.push(f);
-        byPath.set(f.path, arr);
-    }
-    return [...byPath.values()];
-}
 function groupRegions(paths, a, b, padBy) {
     const groups = paths.map((p) => {
         const ra = a.elements[p]?.rect;
@@ -197,224 +193,8 @@ function readPng(file) {
         return null;
     return PNG.sync.read(fs.readFileSync(file));
 }
-// --- readable findings: dedupe logical longhands, collapse shorthand families,
-//     humanize values, label by semantic marker, group identical siblings ------
-// Logical longhand → its physical equivalent (LTR, horizontal-tb). Dropped when
-// the physical one changed identically, so each change appears once.
-const LOGICAL_TO_PHYSICAL = (() => {
-    const m = {};
-    const sides = {
-        'block-start': 'top',
-        'block-end': 'bottom',
-        'inline-start': 'left',
-        'inline-end': 'right',
-    };
-    for (const [l, p] of Object.entries(sides)) {
-        for (const k of ['color', 'width', 'style'])
-            m[`border-${l}-${k}`] = `border-${p}-${k}`;
-        m[`margin-${l}`] = `margin-${p}`;
-        m[`padding-${l}`] = `padding-${p}`;
-        m[`inset-${l}`] = p;
-    }
-    const radius = {
-        'start-start': 'top-left',
-        'start-end': 'top-right',
-        'end-start': 'bottom-left',
-        'end-end': 'bottom-right',
-    };
-    for (const [l, p] of Object.entries(radius))
-        m[`border-${l}-radius`] = `border-${p}-radius`;
-    return m;
-})();
-// Length-valued 4-side families → CSS 1–4-value shorthand whenever all four
-// sides changed (e.g. `padding: 26px 24px → 28px`).
-const BOX4 = [
-    { short: 'margin', parts: ['top', 'right', 'bottom', 'left'].map((s) => `margin-${s}`) },
-    { short: 'padding', parts: ['top', 'right', 'bottom', 'left'].map((s) => `padding-${s}`) },
-    { short: 'border-width', parts: ['top', 'right', 'bottom', 'left'].map((s) => `border-${s}-width`) },
-    {
-        short: 'border-radius',
-        parts: ['top-left', 'top-right', 'bottom-right', 'bottom-left'].map((s) => `border-${s}-radius`),
-    },
-];
-// Colour/keyword families → one row only when all four sides match (else
-// per-side, which keeps each colour swatchable).
-const UNIFORM = [
-    { short: 'border-color', parts: ['top', 'right', 'bottom', 'left'].map((s) => `border-${s}-color`) },
-    { short: 'border-style', parts: ['top', 'right', 'bottom', 'left'].map((s) => `border-${s}-style`) },
-];
-const boxShorthand = ([t, r, b, l]) => t === r && r === b && b === l
-    ? t
-    : t === b && r === l
-        ? `${t} ${r}`
-        : r === l
-            ? `${t} ${r} ${b}`
-            : `${t} ${r} ${b} ${l}`;
-const PROP_ORDER = [
-    'display',
-    'position',
-    'grid-template-columns',
-    'grid-template-rows',
-    'flex-direction',
-    'justify-content',
-    'align-items',
-    'gap',
-    'margin',
-    'padding',
-    'border-width',
-    'border-style',
-    'border-color',
-    'border-radius',
-    'outline',
-    'background-color',
-    'background-image',
-    'color',
-    'box-shadow',
-    'opacity',
-    'transform',
-    'font-family',
-    'font-size',
-    'font-weight',
-    'line-height',
-    'letter-spacing',
-    'text-transform',
-    'text-align',
-];
-const orderIdx = (p) => {
-    const i = PROP_ORDER.indexOf(p);
-    return i === -1 ? PROP_ORDER.length : i;
-};
-function cleanVal(v) {
-    // Verbatim by design: no rounding. Rounding once showed alpha 0.18 as 0.2 —
-    // and could erase a real 0.18→0.2 diff entirely via the no-op filter below.
-    let s = v;
-    if (!s.includes('(')) {
-        const toks = s.split(' ');
-        if (toks.length > 1 && new Set(toks).size === 1)
-            s = `${toks[0]} ×${toks.length}`;
-    }
-    return s.replace(/rgba\(\s*0,\s*0,\s*0,\s*0\s*\)/g, 'transparent');
-}
-// These default to `currentColor`, so a `color` change drags them all along —
-// pure echoes, dropped when they match the `color` change.
-const CURRENTCOLOR_FOLLOWERS = [
-    'caret-color',
-    'outline-color',
-    'column-rule-color',
-    'text-decoration-color',
-    'text-emphasis-color',
-    '-webkit-text-fill-color',
-    '-webkit-text-stroke-color',
-];
-// "No value here" markers: a forced-state delta that doesn't apply, an unset
-// longhand, or a capture artifact where a path didn't line up. A change BETWEEN
-// two of these (e.g. `— → (gone)`) is meaningless and must never read as a diff.
-const NON_VALUE = new Set(['(state does not change it)', '(state no longer changes it)', '(unset)', '(gone)']);
-const isNonValue = (v) => NON_VALUE.has(v);
-/** Combine longhands into a shorthand value; all-non-value sides collapse to one. */
-const combineValues = (vals) => (vals.every(isNonValue) ? '(unset)' : vals.join(' '));
-export function summarizeProps(props) {
-    const map = new Map(props.map((p) => [p.prop, { ...p }]));
-    for (const [logical, physical] of Object.entries(LOGICAL_TO_PHYSICAL)) {
-        const lo = map.get(logical);
-        const ph = map.get(physical);
-        if (lo && ph && lo.before === ph.before && lo.after === ph.after)
-            map.delete(logical);
-    }
-    const color = map.get('color');
-    if (color)
-        for (const f of CURRENTCOLOR_FOLLOWERS) {
-            const m = map.get(f);
-            if (m && m.before === color.before && m.after === color.after)
-                map.delete(f);
-        }
-    for (const fam of BOX4) {
-        const members = fam.parts.map((p) => map.get(p));
-        if (members.every((m) => !!m)) {
-            fam.parts.forEach((p) => map.delete(p));
-            map.set(fam.short, {
-                prop: fam.short,
-                before: boxShorthand(members.map((m) => m.before)),
-                after: boxShorthand(members.map((m) => m.after)),
-            });
-        }
-    }
-    const rg = map.get('row-gap');
-    const cg = map.get('column-gap');
-    if (rg && cg) {
-        map.delete('row-gap');
-        map.delete('column-gap');
-        map.set('gap', {
-            prop: 'gap',
-            before: rg.before === cg.before ? rg.before : `${rg.before} ${cg.before}`,
-            after: rg.after === cg.after ? rg.after : `${rg.after} ${cg.after}`,
-        });
-    }
-    for (const fam of UNIFORM) {
-        const members = fam.parts.map((p) => map.get(p)).filter((m) => !!m);
-        if (members.length === fam.parts.length &&
-            members.every((m) => m.before === members[0].before && m.after === members[0].after)) {
-            fam.parts.forEach((p) => map.delete(p));
-            map.set(fam.short, { prop: fam.short, before: members[0].before, after: members[0].after });
-        }
-    }
-    // outline-width/-style/-color → one `outline` row (offset stays separate).
-    const ow = map.get('outline-width');
-    const os = map.get('outline-style');
-    const oc = map.get('outline-color');
-    if (ow && os && oc) {
-        map.delete('outline-width');
-        map.delete('outline-style');
-        map.delete('outline-color');
-        map.set('outline', {
-            prop: 'outline',
-            before: combineValues([ow.before, os.before, oc.before]),
-            after: combineValues([ow.after, os.after, oc.after]),
-        });
-    }
-    return ([...map.values()]
-        .map((p) => ({ prop: p.prop, before: cleanVal(p.before), after: cleanVal(p.after) }))
-        // Drop no-ops: a value that didn't actually change, or a change between two
-        // "no value here" markers (`— → (gone)`), which carries no information.
-        .filter((p) => p.before !== p.after && !(isNonValue(p.before) && isNonValue(p.after)))
-        .sort((a, b) => orderIdx(a.prop) - orderIdx(b.prop) || a.prop.localeCompare(b.prop)));
-}
-/** `div.who-grid`, `a.nav-cta`, `h3` — the semantic marker class, else the tag. */
-export function prettyLabel(p, cls) {
-    const tag = (p.split('>').pop() ?? '').trim().replace(/:nth-child\(\d+\)/, '') || 'el';
-    const first = cls.split(/\s+/)[0] ?? '';
-    return /^[a-z][a-z0-9-]*$/.test(first) ? `${tag}.${first}` : tag;
-}
-// Surface keys originate from artifact filenames — attacker-controlled in the
-// fork capture/report split, and they flow into the PRIVILEGED PR-comment summary
-// (the Action slices report.md above the first `### `). Strip the Markdown/HTML
-// control characters (`` ` ``, [ ] ( ), < >, |) that could inject a link, image,
-// or table into that bot comment. Escaping at the render boundary — the keys stay
-// legible; only the injection surface is removed. (Crop FILENAMES are separately
-// restricted to [a-z0-9-]; this is the display-side equivalent.)
-const safeKey = (s) => s.replace(/[`[\]()<>|]/g, '-');
-const surfaceBase = (s) => s.replace(/@\d+$/, '');
-const surfaceWidth = (s) => Number(s.match(/@(\d+)$/)?.[1] ?? 0);
-function pushSurfaceWidth(byBase, base, surface) {
-    const arr = byBase.get(base) ?? [];
-    arr.push(surfaceWidth(surface));
-    byBase.set(base, arr);
-}
-function renderSurfaceGroups(byBase) {
-    return [...byBase]
-        .map(([base, ws]) => {
-        const widths = ws.filter((w) => w > 0).sort((a, b) => b - a);
-        return widths.length ? `${safeKey(base)} @ ${widths.join(', ')}` : safeKey(base);
-    })
-        .join(' · ');
-}
-/** "landing @ 1280, 1080, 390 · landing-nav-open @ 1080" from the surface keys. */
-function formatSurfaceList(surfaces) {
-    const byBase = new Map();
-    for (const s of surfaces)
-        pushSurfaceWidth(byBase, surfaceBase(s), s);
-    return renderSurfaceGroups(byBase);
-}
+// --- readable findings: the dedupe/summarise/label brain lives in
+//     change-groups.ts (shared with the CLI). report.ts renders crops on top. ---
 function surfaceContext(...maps) {
     const metadata = maps.find((m) => m?.metadata)?.metadata;
     if (!metadata?.variantKey)
@@ -457,47 +237,6 @@ function collectLiveCandidateLabels(beforeDir, afterDir) {
     }
     return [...seen].sort();
 }
-// Grid-track longhands compute to width-dependent pixels (`282px ×2` at one width,
-// `282px 228px` at another), so the SAME responsive change would otherwise get a
-// different signature per width. Key them by track COUNT — what actually
-// identifies the change — so responsive variants group into one section.
-function sigValue(c) {
-    if (c.prop === 'grid-template-columns' || c.prop === 'grid-template-rows') {
-        return `${c.prop}=${trackCount(c.before)}t>${trackCount(c.after)}t`;
-    }
-    return `${c.prop}=${c.before}>${c.after}`;
-}
-/** Canonical signature of a surface's findings: surfaces that changed in the
- *  same way collapse into one section + one image (the rects differ per width;
- *  the change itself does not). */
-function signatureOf(findings) {
-    return JSON.stringify(findings
-        .map((f) => ({
-        p: f.path,
-        k: f.kind,
-        t: f.kind === 'dom' ? f.change : f.kind === 'state' ? f.state : (f.pseudo ?? ''),
-        v: f.kind === 'dom' ? '' : summarizeProps(f.props).map(sigValue).join('|'),
-    }))
-        .sort((a, b) => `${a.p}|${a.k}|${a.t}`.localeCompare(`${b.p}|${b.k}|${b.t}`)));
-}
-/** A one-line heading for a change group: "1 element added", "2 elements restyled". */
-function groupTitle(findings) {
-    const added = new Set(findings.filter((f) => f.kind === 'dom' && f.change === 'added').map((f) => f.path));
-    const removed = new Set(findings.filter((f) => f.kind === 'dom' && f.change === 'removed').map((f) => f.path));
-    const retagged = new Set(findings.filter((f) => f.kind === 'dom' && f.change === 'retagged').map((f) => f.path));
-    const restyled = new Set(findings.filter((f) => f.kind !== 'dom' && !added.has(f.path) && !removed.has(f.path)).map((f) => f.path));
-    const n = (c, w) => `${c} ${w}${c === 1 ? '' : 's'}`;
-    const parts = [];
-    if (added.size)
-        parts.push(`${n(added.size, 'element')} added`);
-    if (removed.size)
-        parts.push(`${n(removed.size, 'element')} removed`);
-    if (retagged.size)
-        parts.push(`${n(retagged.size, 'element')} retagged`);
-    if (restyled.size)
-        parts.push(`${n(restyled.size, 'element')} restyled`);
-    return parts.join(', ') || `${n(new Set(findings.map((f) => f.path)).size, 'element')} changed`;
-}
 /**
  * A crop's heading: the element it's anchored on, then what happened inside it —
  * `` `who-grid` · 5 elements restyled ``. Naming the anchor is what ties the
@@ -704,80 +443,6 @@ function renderCropChanges(findings, foldAt, ctx) {
     const summary = bullets.length ? bullets.map((b) => `- ${b}`) : ['_see changes_'];
     return ['', ...summary, '', '<details>', `<summary>${foldSummary(findings)}</summary>`, ...tables, '', '</details>'];
 }
-// Computed values that follow from an element's box size or position rather than
-// its styling. On any reflow they change all the way up the ancestor chain
-// (body, main, section…), so an element whose ONLY changes are these is a reflow
-// casualty: it must not anchor a crop region (that would zoom to the whole page)
-// nor clutter the findings. The certification differ keeps them — a reflow IS a
-// change to certify — but the visual report focuses on styling intent.
-const DERIVED_PROPS = new Set([
-    'width',
-    'height',
-    'block-size',
-    'inline-size',
-    'min-width',
-    'min-height',
-    'max-width',
-    'max-height',
-    'perspective-origin',
-    'transform-origin',
-    // position offsets shift with the document on any reflow
-    'top',
-    'right',
-    'bottom',
-    'left',
-    'inset-block-start',
-    'inset-block-end',
-    'inset-inline-start',
-    'inset-inline-end',
-]);
-// Props stripped from forced :hover/:focus/:active deltas specifically. Layout
-// and grid-track values that shift when a state forces a relayout are capture
-// noise, not interaction feedback — a state finding is meant to catch a changed
-// hover/focus/active *style* (colour, outline, shadow), not a reflow.
-const STATE_STRIP = new Set([
-    ...DERIVED_PROPS,
-    'grid-template-columns',
-    'grid-template-rows',
-    'grid-template-areas',
-    'grid-auto-columns',
-    'grid-auto-rows',
-    'grid-auto-flow',
-]);
-/**
- * Strip the noise the visual report shouldn't carry, cross-referencing each
- * element's layers so the forced-state layer stops echoing the base:
- *   - base/pseudo styles: drop size/position-derived longhands (reflow casualties);
- *   - forced states: drop derived + grid-track props, drop a delta the BASE
- *     already changed (a `:hover color` that just follows a recoloured base is an
- *     echo, not a dropped variant), and drop non-value↔non-value rows;
- *   - any finding left with no props is removed entirely.
- */
-function cleanFindings(findings) {
-    const out = [];
-    for (const group of groupByPath(findings)) {
-        const base = group.find((f) => f.kind === 'style' && f.pseudo === null);
-        const baseChanged = new Set(base?.props.map((p) => p.prop) ?? []);
-        // For an ADDED element the base style is a full (unset)→value snapshot, not a
-        // delta — so a forced-state value is never an "echo" of a base *change*; keep
-        // every state row (suppressing them would drop a real :hover/:focus value).
-        const isAdded = group.some((f) => f.kind === 'dom' && f.change === 'added');
-        for (const f of group) {
-            if (f.kind === 'dom') {
-                out.push(f);
-                continue;
-            }
-            const props = f.kind === 'style'
-                ? f.props.filter((p) => !DERIVED_PROPS.has(p.prop))
-                : f.props.filter((p) => !STATE_STRIP.has(p.prop) &&
-                    (isAdded || !baseChanged.has(p.prop)) &&
-                    !(isNonValue(p.before) && isNonValue(p.after)));
-            if (props.length)
-                out.push({ ...f, props });
-        }
-    }
-    return out;
-}
 /** Per-element view for the plain-English summariser: the base deltas (summarised)
  *  plus which interactive states genuinely changed. */
 function buildElementChanges(findings) {
@@ -923,13 +588,29 @@ function determinismLine(det) {
         return `- **Determinism** — ✗ NOT proven (base ${det.base}, head ${det.head}) — a clean diff could be two nondeterministic reads`;
     return '- **Determinism** — ⚠ unknown (a capture predates the determinism ledger)';
 }
+// Truncated, escaped, comma-joined key list — the same discipline for removals and
+// additions, so neither can inject Markdown into the privileged PR-comment summary.
+function keyList(items) {
+    const keys = items.map((i) => safeKey(i.key));
+    return `${keys.slice(0, 8).join(', ')}${keys.length > 8 ? ', …' : ''}`;
+}
+// Additions never gate, but the report must not contradict the diff (which prints
+// them) — so echo them as an informational, still-✓-class clause. Returns a leading
+// `; …` fragment to append after whatever the removal side decided, or '' when none.
+function additionsClause(added) {
+    if (added.length === 0)
+        return '';
+    return `; ${added.length} navigable affordance(s) added: ${keyList(added)} (additions don't gate)`;
+}
 function inventoryLine(inv) {
-    if (inv.unexplained.length > 0) {
-        const keys = inv.unexplained.map((i) => safeKey(i.key));
-        return `- **Inventory** — ⚠ ${inv.unexplained.length} navigable affordance(s) removed, unacknowledged: ${keys.slice(0, 8).join(', ')}${keys.length > 8 ? ', …' : ''}`;
-    }
+    const added = additionsClause(inv.delta.added);
+    if (inv.unexplained.length > 0)
+        return `- **Inventory** — ⚠ ${inv.unexplained.length} navigable affordance(s) removed, unacknowledged: ${keyList(inv.unexplained)}${added}`;
     if (inv.delta.removed.length > 0)
-        return `- **Inventory** — ✓ ${inv.delta.removed.length} removal(s), all acknowledged`;
+        return `- **Inventory** — ✓ ${inv.delta.removed.length} removal(s), all acknowledged${added}`;
+    // Addition-only: drop the leading `; ` so the clause reads as the whole ✓ line.
+    if (added)
+        return `- **Inventory** — ✓${added.slice(1)}`;
     return '- **Inventory** — ✓ navigable set unchanged';
 }
 // Acknowledged removals for the report — lenient: a missing OR malformed ack file
@@ -1221,6 +902,24 @@ function renderNewSurface(p, ctx, cropSeq) {
     md.push('', `_No baseline to compare against — this surface is new. Review and approve it before it becomes part of the baseline._`);
     return { md, json, cropSeq };
 }
+/** The shared-chrome tier banner (#193), emitted once above the promoted groups:
+ *  "the frame every view draws changed" — so the reviewer reads it as one global
+ *  change, not a per-view surprise. The affected group(s) render in full beneath.
+ *  `nChrome` is how many distinct chrome changes were promoted; `nSurfaces` is the
+ *  captured-surface-base count they span. */
+function chromeCalloutLines(nChrome, nSurfaces) {
+    const what = nChrome === 1 ? 'change' : 'changes';
+    return [
+        '',
+        '---',
+        '',
+        `## 🧱 Global chrome ${what} — across all ${nSurfaces} surface(s)`,
+        '',
+        `_${nChrome} change(s) rode the shared frame every view draws (a persistent nav, header, or footer): ` +
+            `each touched every surface that renders the affected element, so it reads as ONE global change, not a ` +
+            `per-view one. The detail is folded beneath — review it once._`,
+    ];
+}
 /** The one-time banner where report.md switches from full detail to one-line
  *  summaries, so the reader knows nothing is missing — only relocated to report.json. */
 function cappedNoticeLines(budget) {
@@ -1271,6 +970,14 @@ export function generateStyleMapReport(opts) {
         .filter((p) => p.sd.missing || p.findings.length > 0);
     const missing = prepared.filter((p) => p.sd.missing);
     const changeGroups = groupBySignature(prepared);
+    // Shared-chrome tier (#193): promote a change that rode the frame every view
+    // draws (nav rail, header) to a callout, so the reviewer reads "the nav changed
+    // everywhere" once instead of inferring it from a long surface list on several
+    // entries. Purely presentational — counts, groups, exit code, and report.json
+    // are unchanged; only the render order and one heading differ. In the common
+    // small-surface case (e.g. the demo) nothing qualifies and this is a no-op.
+    const { chrome, rest } = classifyChrome(changeGroups, surfaceElementPaths(beforeDir, afterDir));
+    const orderedGroups = [...chrome, ...rest];
     const shown = countShownChanges(changeGroups);
     // Surfaces carrying a reviewable change — NOT the new (one-sided) ones, which
     // have no baseline to compare and are summarised on their own line below so the
@@ -1331,12 +1038,23 @@ export function generateStyleMapReport(opts) {
         md.push(summary);
         reportBytes += summary.length + 1;
     };
-    for (const cg of changeGroups) {
+    // The captured-surface-base count (all surfaces, not just changed ones) so the
+    // chrome callout can read "N of M surfaces". M is bases, matching the tier's
+    // base-keyed coverage rule.
+    const totalSurfaceBases = new Set(surfaceKeysIn(afterDir).map(surfaceBase)).size;
+    const chromeSet = new Set(chrome);
+    let chromeHeaderEmitted = false;
+    for (const cg of orderedGroups) {
         const r = renderChangeGroup(cg, ctx, maxCrops, cropSeq);
         json.push(r.json);
         totalFindings += r.findingCount;
         cropSeq = r.cropSeq;
-        emitDetail(r.md, compactChangeSummary(cg, r.json, img));
+        // Prepend the shared-chrome banner once, above the first promoted group. It
+        // rides on the same emitDetail budget so the cap still applies.
+        const detail = chromeSet.has(cg) && !chromeHeaderEmitted
+            ? ((chromeHeaderEmitted = true), [...chromeCalloutLines(chrome.length, totalSurfaceBases), ...r.md])
+            : r.md;
+        emitDetail(detail, compactChangeSummary(cg, r.json, img));
     }
     for (const p of missing) {
         const r = renderNewSurface(p, ctx, cropSeq);