simplycms 0.4.0

package/skills/redesign-from-reference/scripts/lib/fonts.mjs

@@ -0,0 +1,67 @@
+/**
+ * Мапінг шрифтів `inspection.fonts` → `font-sans`/`font-heading` +
+ * пропозиція `fonts`-stylesheet (Фаза 1, задача §2.B.1, план Р7).
+ *
+ * Винесено окремо від `map.mjs`, щоб той лишався ≤150 рядків (канон файлу) —
+ * логіка суто про шрифти, кольорової математики тут немає.
+ */
+
+/** Витягти назву сімʼї з CSS font-stack (`"'Inter', sans-serif"` → `inter`). */
+function familyOf(stack) {
+  return stack.split(',')[0].replace(/['"]/g, '').trim().toLowerCase();
+}
+
+/**
+ * Google Fonts stylesheet-и, у яких `family=`-параметр (`css`/`css2`-URL)
+ * підтверджує одну з `families`. Без підтвердження сімʼя лишається лише у
+ * font-stack (Р7: `fonts`-пропозиція ЛИШЕ з підтвердженням із
+ * `fontStylesheets`) — саме тому інспекція окремо звітує `fontStylesheets`,
+ * бо самих `getComputedStyle` недостатньо, щоб довести походження шрифту.
+ */
+function confirmedStylesheets(fontStylesheets, families) {
+  const wanted = families.map(familyOf);
+  const matches = [];
+
+  for (const href of fontStylesheets ?? []) {
+    let family;
+    try {
+      family = (new URL(href).searchParams.get('family') ?? '')
+        .split(':')[0]
+        .toLowerCase();
+    } catch {
+      continue; // Не URL або нерозпізнаний формат — чесно пропускаємо, не падаємо.
+    }
+    if (wanted.includes(family) && !matches.includes(href)) matches.push(href);
+  }
+
+  return matches;
+}
+
+/**
+ * Мапити `inspection.fonts` (`heading`/`body`, кожен `{ family, weight?, sizePx? }`)
+ * → `{ tokens: { 'font-sans'?, 'font-heading'? }, fonts: ThemeFontSource[] | null }`.
+ *
+ * `font-heading` додається лише якщо відрізняється від `font-sans` — інакше
+ * теми і так успадковують `font-sans` для заголовків (без дублювання значення).
+ */
+export function mapFonts(inspection) {
+  const heading = inspection.fonts?.heading?.family;
+  const body = inspection.fonts?.body?.family;
+
+  const tokens = {};
+  if (body) tokens['font-sans'] = body;
+  if (heading && heading !== body) tokens['font-heading'] = heading;
+
+  const stylesheets = confirmedStylesheets(
+    inspection.fontStylesheets,
+    [body, heading].filter(Boolean),
+  );
+
+  return {
+    tokens,
+    fonts:
+      stylesheets.length > 0
+        ? stylesheets.map((stylesheet) => ({ stylesheet }))
+        : null,
+  };
+}

package/skills/redesign-from-reference/scripts/lib/hover-sweep.mjs

@@ -0,0 +1,150 @@
+/**
+ * Hover-sweep інспекції (план Р5, Фаза 2): детерміністичний прохід Playwright
+ * `hover()` по обмеженому списку інтерактивних елементів із фіксацією дельти
+ * computed styles. Результат їде в `motion.hover`. Окремий модуль, а не
+ * доважок до `inspect-page.mjs` (канон ≤150 рядків: там і так уже reveal,
+ * скріншоти, два семпли палітри й запис файлу).
+ */
+import { browserHoverMeta, browserNeutralPoint } from './browser-hover.mjs';
+
+/**
+ * Що взагалі ховеримо. `querySelectorAll` зі списком селекторів віддає вузли в
+ * DOM-порядку і БЕЗ дублікатів (`<button role="button">` матчиться двома
+ * селекторами, а в наборі буде раз) — на цьому тримається детермінізм.
+ */
+export const HOVER_SELECTOR = 'header a, nav a, button, [role="button"]';
+
+/**
+ * Властивості, дельту яких фіксуємо (Р5). Список навмисно за абеткою: він же
+ * задає порядок `changes` у виводі, тож окреме сортування не потрібне.
+ * 🔴 `border-color` за замовчуванням дорівнює `currentColor`, тож зміна
+ * `color` тягне його за собою навіть при `border-style: none` — це не шум
+ * капчера, а реальний computed-стан.
+ */
+export const HOVER_PROPERTIES = [
+  'background-color',
+  'border-color',
+  'box-shadow',
+  'color',
+  'transform',
+];
+
+/**
+ * Стеля кандидатів. Саме СТЕЛЯ, а не «скільки є»: кожен елемент коштує
+ * `hover()` плюс settle-паузу, тож мега-меню з двох сотень посилань
+ * перетворило б інспекцію однієї сторінки на хвилини. Ховер-палітра сайту —
+ * стилістичний ЗРАЗОК, а не інвентаризація: перші два десятки вузлів у
+ * DOM-порядку (шапка, навігація, перший екран) уже містять усі типові стани.
+ */
+export const HOVER_LIMIT = 20;
+
+/**
+ * Пауза між `hover()` і зняттям стану «після», мс. Має перекривати типову
+ * UI-транзицію (150–300 мс), інакше семпл ловить СЕРЕДИНУ переходу — значення,
+ * яке в наступному прогоні буде іншим, і глибока рівність двох прогонів
+ * розсиплеться. 400 мс — запас над 300 мс і все ще ≤8 с на повну стелю.
+ */
+export const HOVER_SETTLE_MS = 400;
+
+/**
+ * Таймаут actionability-очікування `hover()`, мс. 🔴 Дефолт Playwright — 30 с:
+ * сторінка з cookie-оверлеєм поверх шапки повісила б прохід на десять хвилин
+ * замість чесно порахувати перекриті елементи як пропущені.
+ */
+export const HOVER_ACTION_TIMEOUT_MS = 2000;
+
+/** Порівняння рядків для стабільного сортування. */
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+/**
+ * Значущі зміни між станом спокою і станом під курсором.
+ * @returns {Array<{ property: string, from: string, to: string }>}
+ */
+function diffStyles(before, after) {
+  return HOVER_PROPERTIES.filter((p) => before[p] !== after[p]).map((p) => ({
+    property: p,
+    from: before[p],
+    to: after[p],
+  }));
+}
+
+/**
+ * Відібрати видимих кандидатів у DOM-порядку й зняти їхній стан СПОКОЮ одним
+ * проходом, ДО першого `hover()`: читати «до» безпосередньо перед ховером
+ * кожного було б крихко — курсор на той момент ще стоїть на попередньому
+ * елементі, і якщо той предок/нащадок поточного, «до» містило б чужий ховер.
+ */
+async function selectCandidates(page, limit) {
+  const handles = await page.$$(HOVER_SELECTOR);
+  const selected = [];
+
+  for (const handle of handles) {
+    if (selected.length >= limit) break;
+    const meta = await handle.evaluate(browserHoverMeta, HOVER_PROPERTIES);
+    if (!meta.visible) continue;
+    selected.push({
+      handle,
+      index: selected.length,
+      selector: meta.selector,
+      before: meta.styles,
+    });
+  }
+  return selected;
+}
+
+/**
+ * Прохід ховером по сторінці. У виводі — лише елементи з РЕАЛЬНОЮ дельтою;
+ * `skipped` — чесний лічильник тих, на кому ховер не вдався (вузол
+ * відʼєднався від DOM, перекритий оверлеєм, не дочекався actionability). Форма
+ * «дані + лічильник втрат» — та сама, що в `keyframes.inaccessibleSheets`:
+ * мовчазного дропу в секції `motion` немає.
+ *
+ * 🔴 Викликати ПІСЛЯ скріншотів (курсор не має потрапити в кадр) і ДО
+ * семплу палітри — слід ховера прибирає завершальний `mouse.move`.
+ *
+ * @param {import('@playwright/test').Page} page
+ * @param {{ limit?: number, settleMs?: number }} [options]
+ * @returns {Promise<{ entries: Array<{ index: number, selector: string,
+ *   changes: Array<{ property: string, from: string, to: string }> }>,
+ *   skipped: number }>}
+ */
+export async function sweepHover(page, options = {}) {
+  const limit = options.limit ?? HOVER_LIMIT;
+  const settleMs = options.settleMs ?? HOVER_SETTLE_MS;
+
+  const candidates = await selectCandidates(page, limit);
+  const entries = [];
+  let skipped = 0;
+
+  for (const candidate of candidates) {
+    try {
+      await candidate.handle.hover({ timeout: HOVER_ACTION_TIMEOUT_MS });
+      await page.waitForTimeout(settleMs);
+      const after = await candidate.handle.evaluate(
+        browserHoverMeta,
+        HOVER_PROPERTIES,
+      );
+      const changes = diffStyles(candidate.before, after.styles);
+      if (changes.length > 0)
+        entries.push({
+          index: candidate.index,
+          selector: candidate.selector,
+          changes,
+        });
+    } catch {
+      // Один проблемний вузол не валить прохід — лише збільшує лічильник.
+      skipped += 1;
+    }
+  }
+
+  // `hover()` сам скролить елемент у в'юпорт — повертаємо сторінку на верх,
+  // щоб подальші кроки інспекції бачили ту саму позицію, що й до проходу.
+  await page.evaluate(() => window.scrollTo(0, 0));
+  const neutral = await page.evaluate(browserNeutralPoint);
+  await page.mouse.move(neutral.x, neutral.y);
+  // Hover-out теж транзиція: без паузи семпл палітри читав би її середину.
+  await page.waitForTimeout(settleMs);
+
+  entries.sort((a, b) => cmp(a.selector, b.selector) || a.index - b.index);
+  return { entries, skipped };
+}

package/skills/redesign-from-reference/scripts/lib/inspect-page.mjs

@@ -0,0 +1,110 @@
+/**
+ * Інспекція вже завантаженої сторінки (задача §2.A, план Р1b). Виокремлено з
+ * `inspect.mjs` (канон ≤150 рядків) — той лишається тонким CLI (аргументи +
+ * launch chromium + `page.goto`); тут — скріншоти + світлий/темний семпл і
+ * запис `inspection.json`.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { scrollThrough } from './browser.mjs';
+import { sweepHover } from './hover-sweep.mjs';
+import { captureMotion, captureReveal } from './motion.mjs';
+import {
+  captureScreenshots,
+  samplePalette,
+  VIEWPORTS,
+  VIEWPORT_HEIGHT,
+} from './sample.mjs';
+
+// 2 (Фаза 1 інкремента Б.2) — додано верхньорівневу секцію `motion`.
+// 3 (інкремент Б.3) — форма `motion` ЗМІНИЛАСЬ: `jsDrivenSuspected` розширив
+// домен до `boolean | 'unknown'`, додались `revealSampled`/`revealRoot`. Бамп
+// не косметичний: у файлі v2 `jsDrivenSuspected: false` при порожньому
+// `reveal` означав «нема на чому міряти», а скіл велить читати `false` як
+// «перевірено, підозри немає». 🔴 Версія тут РОЗРІЗНЯЄ форми, а не відхиляє
+// старі: `SUPPORTED_INSPECTION_VERSIONS` і далі містить 1 і 2 (мапінг від
+// motion не залежить), тож стару інспекцію гейт пропускає — але вже видно,
+// що вона стара, і `revealSampled` у ній шукати марно.
+// 🔴 Лічильників версій у інструменті ТРИ, і плутати їх не можна: тут —
+// `inspection.json` (вхід мапінгу), `lib/map.mjs` — `tokens-proposal.json`
+// (вихід мапінгу), `lib/sitemap.mjs` — `sitemap-proposal.json` (вихід
+// дискаверера). Рухаються незалежно: motion у токени не мапиться взагалі.
+const SCHEMA_VERSION = 3;
+
+/** Порівняння світлого/темного семплу за фоном+текстом — чесний `darkDetected`. */
+function paletteSignature(colors) {
+  return colors
+    .filter((c) => c.role === 'background' || c.role === 'text')
+    .map((c) => c.value)
+    .sort()
+    .join(',');
+}
+
+/**
+ * Інспектувати вже завантажену сторінку (навігацію робить викликач: CLI —
+ * `page.goto`, тест-фікстура — `page.setContent`): скріншоти + світлий +
+ * опційно темний семпл (`dark`). Пише `inspection.json` в `out`, повертає
+ * той самий обʼєкт.
+ */
+export async function inspectPage(page, { url, out, dark }) {
+  mkdirSync(out, { recursive: true });
+
+  // Р1b: `captureScreenshots` лишає сторінку на останньому viewport циклу
+  // (мобільний, 390px) — без явного повернення на десктоп палітра де-факто
+  // мобільна: десктопні секції (`display:none` на вузькому лейауті) мають
+  // area<=0 і випадають із семплу. Той самий viewport — і для light-, і для
+  // dark-проходу, інакше вони порівнюють різні лейаути.
+  const sampleViewport = { width: VIEWPORTS.desktop, height: VIEWPORT_HEIGHT };
+
+  // 🔴 Р4: reveal — ПЕРШИМ і окремим проходом, ДО скріншотів. Далі
+  // `scrollThrough` відпрацює ще щонайменше пʼять разів, а reveal-once секція
+  // після першого проходу лишається розкритою назавжди: у будь-якому
+  // пізнішому вимірі дельта opacity/transform тотожно нульова.
+  await page.setViewportSize(sampleViewport);
+  const reveal = await captureReveal(page);
+
+  const viewports = await captureScreenshots(page, out);
+  await page.setViewportSize(sampleViewport);
+  await scrollThrough(page);
+  // 🔴 Р5: ховер-прохід — ПІСЛЯ скріншотів (курсор не має потрапити в кадр) і
+  // ДО семплу палітри. `sweepHover` прибирає ховер за собою (курсор у
+  // нейтральну точку), інакше стан однієї кнопки протік би в кольори сайту.
+  const hover = await sweepHover(page);
+  const light = await samplePalette(page);
+  const motion = await captureMotion(page, { reveal, hover });
+
+  let darkColors = null;
+  if (dark) {
+    await page.emulateMedia({ colorScheme: 'dark' });
+    await scrollThrough(page); // лейаут міг перерендеритись під темною темою
+    const darkSample = await samplePalette(page);
+    await page.emulateMedia({ colorScheme: 'light' });
+    if (paletteSignature(light.colors) !== paletteSignature(darkSample.colors))
+      darkColors = darkSample.colors;
+  }
+  const darkDetected = darkColors !== null;
+
+  const inspection = {
+    schemaVersion: SCHEMA_VERSION,
+    url,
+    viewports,
+    sampleViewport,
+    colors: light.colors,
+    fonts: light.fonts,
+    radius: light.radius,
+    radiusDropped: light.radiusDropped,
+    shadows: light.shadows,
+    spacing: light.spacing,
+    fontStylesheets: light.fontStylesheets,
+    motion,
+    darkDetected,
+    ...(darkColors ? { dark: { colors: darkColors } } : {}),
+  };
+
+  writeFileSync(
+    join(out, 'inspection.json'),
+    JSON.stringify(inspection, null, 2),
+    'utf8',
+  );
+  return inspection;
+}

package/skills/redesign-from-reference/scripts/lib/inspection-version.mjs

@@ -0,0 +1,38 @@
+/**
+ * Гейт версії `inspection.json` (план Р2). Виокремлено з `map-tokens.mjs` за
+ * тим самим правилом, що й `browser-fonts.mjs` із семплера: CLI-файл уперся в
+ * канонні 150 рядків, а гейт — самостійна перевірка, яку хочеться мати під
+ * юнітом БЕЗ `spawnSync` (процес доводить лише exit-код, не форму помилки).
+ */
+
+/**
+ * Версії `inspection.json`, які тулчейн уміє читати: 1 — до motion-капчера,
+ * 2 — із секцією `motion`, 3 — із чесним reveal-каналом (`revealSampled`/
+ * `revealRoot`, `jsDrivenSuspected: boolean | 'unknown'`). Мапінг усі три
+ * споживає однаково (motion у токени НЕ йде), тож сумісність зі старими
+ * файлами лишається; гейт застосовується до ПРОЧИТАНИХ файлів, а не всередині
+ * `mapTokens`: при мультивході той отримує вже злитий обʼєкт, у якому поля
+ * `schemaVersion` немає взагалі.
+ */
+export const SUPPORTED_INSPECTION_VERSIONS = [1, 2, 3];
+
+/** «1, 2 або 3» — перелік для тексту помилки, яку читає людина в терміналі. */
+function listVersions(versions) {
+  if (versions.length < 2) return String(versions[0] ?? '');
+  return `${versions.slice(0, -1).join(', ')} або ${versions.at(-1)}`;
+}
+
+/**
+ * Гучна відмова на незнайомій версії — краще, ніж тихо змапити чужу форму.
+ * @param {string} path шлях до файлу (потрапляє в текст помилки)
+ * @param {{ schemaVersion?: unknown }} [inspection] розібраний JSON
+ * @throws {Error} якщо `schemaVersion` відсутній або не з підтримуваних
+ */
+export function assertSupportedVersion(path, inspection) {
+  if (SUPPORTED_INSPECTION_VERSIONS.includes(inspection?.schemaVersion)) return;
+  throw new Error(
+    `${path}: schemaVersion=${inspection?.schemaVersion} — непідтримувана ` +
+      `версія inspection.json (очікується ${listVersions(SUPPORTED_INSPECTION_VERSIONS)}); ` +
+      'перезніміть інспекцію актуальним inspect.mjs',
+  );
+}

package/skills/redesign-from-reference/scripts/lib/map.mjs

@@ -0,0 +1,69 @@
+/**
+ * Евристики мапінгу `inspection.json` → `tokens-proposal.json` (задача
+ * §2.B.1, план Р4/Р7). Чиста детерміністична логіка: без IO — його робить
+ * тонкий CLI `map-tokens.mjs` (Фаза 3). Колірна частина — `color-tokens.mjs`,
+ * шрифтова — `fonts.mjs`; тут лише радіус і збірка фінальної форми.
+ */
+import { mapColorTokens } from './color-tokens.mjs';
+import { checkContrastPairs } from './contrast.mjs';
+import { mapFonts } from './fonts.mjs';
+
+// 2 (інкремент Б.3, Р7) — `unmapped` став масивом записів
+// `{ hex, role, count, area, contrastOnBackground, contrastOnCard, belowAA }`
+// замість масиву рядків: форма ЛАМАЄТЬСЯ, тож бамп чесний. 🔴 Лічильників
+// версій у інструменті ТРИ, і цей — не той, що в `lib/inspect-page.mjs`
+// (`inspection.json`, вхід — уже 3) і не той, що в `lib/sitemap.mjs`
+// (`sitemap-proposal.json`). Рухаються незалежно.
+const SCHEMA_VERSION = 2;
+
+/** Радіус-кластер із найбільшою частотою → `rem` (16px root, конвенція теми). */
+function pickRadius(radiusEntries) {
+  if (!Array.isArray(radiusEntries) || radiusEntries.length === 0) return null;
+  const top = [...radiusEntries].sort(
+    (a, b) => b.frequency - a.frequency || a.valuePx - b.valuePx,
+  )[0];
+  return `${(top.valuePx / 16).toFixed(3).replace(/\.?0+$/, '')}rem`;
+}
+
+/**
+ * Мапити `inspection.json`-подібний обʼєкт (Р4) → `tokens-proposal.json`
+ * (`{ schemaVersion, tokens, fonts?, confidence, contrastWarnings, unmapped }`).
+ * @returns {{
+ *   schemaVersion: 2,
+ *   tokens: Record<string, string> & { dark?: Record<string, string> },
+ *   fonts?: Array<{ stylesheet: string }>,
+ *   confidence: Record<string, number>,
+ *   contrastWarnings: Array<{ pair: string, ratio: number, required: number }>,
+ *   unmapped: import('./unmapped.mjs').UnmappedEntry[],
+ * }}
+ */
+export function mapTokens(inspection) {
+  const light = mapColorTokens(inspection.colors ?? []);
+  const tokens = { ...light.tokens };
+
+  const radius = pickRadius(inspection.radius);
+  if (radius) tokens.radius = radius;
+
+  const fontResult = mapFonts(inspection);
+  Object.assign(tokens, fontResult.tokens);
+
+  // `dark` — усередині `tokens` (форма `DesignTokens` 1:1, Р4). Власний `unmapped`/
+  // `confidence` темного набору не виводимо — dark лишається діагностованим через
+  // ті самі `contrastWarnings` нижче (з префіксом `dark:`).
+  if (inspection.darkDetected && inspection.dark?.colors) {
+    const dark = mapColorTokens(inspection.dark.colors).tokens;
+    if (Object.keys(dark).length > 0) tokens.dark = dark;
+  }
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    tokens,
+    ...(fontResult.fonts ? { fonts: fontResult.fonts } : {}),
+    confidence: light.confidence,
+    contrastWarnings: [
+      ...checkContrastPairs(tokens),
+      ...(tokens.dark ? checkContrastPairs(tokens.dark, 'dark:') : []),
+    ],
+    unmapped: light.unmapped,
+  };
+}

package/skills/redesign-from-reference/scripts/lib/merge.mjs

@@ -0,0 +1,150 @@
+/**
+ * Злиття кількох `inspection.json` в один синтетичний обʼєкт для `mapTokens`
+ * (задача §2.D, план Р6/Р6b). Чиста функція, без IO — CLI-обгортка (Р6b,
+ * `map-tokens.mjs`) читає файли й вирішує, чи взагалі викликати merge (при
+ * N=1 — НЕ викликає, early return на чинний одновходовий шлях).
+ *
+ * Детермінізм незалежно від порядку вхідних файлів (Р6, «стабільні
+ * сортування — перестановка вхідних файлів дає той самий результат») —
+ * досягається глобальним сортуванням перед злиттям, а не порядком обходу
+ * масиву `inspections`: сума/OR — комутативні операції, але порядок ключів у
+ * вихідному масиві й вибір «представника» при нічиї інакше плавали б.
+ */
+
+/** Сума `frequency` усіх колірних семплів сторінки — вага для tie-break шрифтів. */
+function pageColorFreqSum(inspection) {
+  return (inspection.colors ?? []).reduce(
+    (sum, c) => sum + (c.frequency ?? 0),
+    0,
+  );
+}
+
+/**
+ * Злити кілька масивів колірних семплів (Р6): частоти й area сумуються по
+ * парі (role,value), `interactive` — OR. Вхід спершу сортується глобально за
+ * (role,value) — вихідний порядок Map-а тоді збігається з цим сортуванням
+ * (перша поява ключа), незалежно від того, з якої сторінки й у якому порядку
+ * прийшли семпли.
+ */
+function mergeColorSamples(colorArrays) {
+  const flat = colorArrays.flat();
+  const sorted = [...flat].sort((a, b) => {
+    if (a.role !== b.role) return a.role < b.role ? -1 : 1;
+    if (a.value !== b.value) return a.value < b.value ? -1 : 1;
+    return 0;
+  });
+
+  const merged = new Map();
+  for (const c of sorted) {
+    const key = `${c.role}:${c.value}`;
+    const existing = merged.get(key);
+    if (existing) {
+      existing.frequency += c.frequency ?? 0;
+      existing.area += c.area ?? 0;
+      existing.interactive = existing.interactive || Boolean(c.interactive);
+    } else {
+      merged.set(key, {
+        role: c.role,
+        value: c.value,
+        frequency: c.frequency ?? 0,
+        area: c.area ?? 0,
+        interactive: Boolean(c.interactive),
+      });
+    }
+  }
+  return [...merged.values()];
+}
+
+/**
+ * Голосування шрифтів по сторінках (Р6): кожен вхід — 1 голос за свій
+ * `family`; перемагає більшість; при нічиї — сторінка з більшою сумою
+ * колірних частот (`pageFreqSum`), далі лексикографічно за `family`. Вхід
+ * спершу сортується (freqSum↓ → family → weight → sizePx) — «представник»
+ * сімʼї (значення weight/sizePx у виводі) визначається цим сортуванням, а НЕ
+ * порядком проходження сторінок.
+ */
+function voteFontConsensus(entries) {
+  if (entries.length === 0) return null;
+
+  const sorted = [...entries].sort((a, b) => {
+    if (a.pageFreqSum !== b.pageFreqSum) return b.pageFreqSum - a.pageFreqSum;
+    if (a.family !== b.family) return a.family < b.family ? -1 : 1;
+    const aw = String(a.weight ?? '');
+    const bw = String(b.weight ?? '');
+    if (aw !== bw) return aw < bw ? -1 : 1;
+    return (a.sizePx ?? 0) - (b.sizePx ?? 0);
+  });
+
+  const groups = new Map();
+  for (const e of sorted) {
+    const g = groups.get(e.family);
+    if (g) g.count += 1;
+    else groups.set(e.family, { count: 1, freqSum: e.pageFreqSum, entry: e });
+  }
+
+  const [, winner] = [...groups.entries()].sort(
+    (a, b) =>
+      b[1].count - a[1].count ||
+      b[1].freqSum - a[1].freqSum ||
+      (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0),
+  )[0];
+
+  return {
+    family: winner.entry.family,
+    weight: winner.entry.weight,
+    sizePx: winner.entry.sizePx,
+  };
+}
+
+/** Витягти `fonts[key]` (`'heading'|'body'`) з кожної сторінки, що його має, + вагу для tie-break. */
+function fontEntries(inspections, freqSums, key) {
+  return inspections
+    .map((insp, i) =>
+      insp.fonts?.[key]
+        ? { ...insp.fonts[key], pageFreqSum: freqSums[i] }
+        : null,
+    )
+    .filter((e) => e !== null);
+}
+
+/**
+ * Злити N `inspection.json`-подібних обʼєктів в один (Р6). Викликач
+ * (`map-tokens.mjs`) передає результат прямо в `mapTokens`.
+ */
+export function mergeInspections(inspections) {
+  const freqSums = inspections.map(pageColorFreqSum);
+
+  const darkPages = inspections.filter(
+    (insp) => insp.darkDetected && insp.dark?.colors,
+  );
+
+  // Р6: «конкатенація» — без сумування по valuePx (на відміну від кольорів);
+  // сортування нижче — лише канонічний порядок виводу, детермінований
+  // незалежно від порядку вхідних файлів (порядок ВСЕРЕДИНІ valuePx не
+  // визначено — записи з тим самим valuePx зі сторінок не мержаться).
+  const radius = inspections
+    .flatMap((insp) => insp.radius ?? [])
+    .sort((a, b) => a.valuePx - b.valuePx || b.frequency - a.frequency);
+
+  return {
+    colors: mergeColorSamples(inspections.map((insp) => insp.colors ?? [])),
+    radius,
+    fonts: {
+      heading: voteFontConsensus(fontEntries(inspections, freqSums, 'heading')),
+      body: voteFontConsensus(fontEntries(inspections, freqSums, 'body')),
+    },
+    fontStylesheets: [
+      ...new Set(inspections.flatMap((insp) => insp.fontStylesheets ?? [])),
+    ].sort(),
+    darkDetected: inspections.some((insp) => Boolean(insp.darkDetected)),
+    ...(darkPages.length > 0
+      ? {
+          dark: {
+            colors: mergeColorSamples(
+              darkPages.map((insp) => insp.dark.colors),
+            ),
+          },
+        }
+      : {}),
+  };
+}