simplycms 0.4.0

package/skills/redesign-from-reference/scripts/lib/motion-detect.mjs

@@ -0,0 +1,128 @@
+/**
+ * Детекція JS-анімаційних бібліотек і евристика «motion керується JS» (план
+ * Р6, Фаза 1). ЧИСТІ функції без IO і без браузера — сирі маркери збирає
+ * `browserMotionMarkers` (`browser-motion.mjs`), а тут лише зіставлення із
+ * сигнатурами, тож юніти лишаються зеленими навіть без chromium.
+ */
+
+/**
+ * Сигнатури бібліотек: `src` скрипта / window-глобал / імʼя `data-`атрибута.
+ * 🔴 Регекси БЕЗ прапорця `g` — `RegExp.test` із `g` стежить за `lastIndex` і
+ * давав би через раз false на тому самому рядку.
+ */
+export const SIGNATURES = [
+  {
+    name: 'gsap',
+    src: /\bgsap\b|greensock|scrolltrigger/i,
+    globals: [
+      'GreenSockGlobals',
+      'ScrollTrigger',
+      'TweenLite',
+      'TweenMax',
+      'gsap',
+    ],
+    data: /^data-(gsap|scroll-trigger)/i,
+  },
+  {
+    name: 'framer-motion',
+    src: /framer-motion|framer\.com\/motion/i,
+    globals: ['Motion', 'framerMotion'],
+    data: /^data-framer/i,
+  },
+  {
+    name: 'lottie',
+    src: /lottie|bodymovin/i,
+    globals: ['bodymovin', 'lottie'],
+    data: /^data-(lottie|animation-path)/i,
+  },
+  {
+    name: 'anime.js',
+    src: /animejs|\banime(\.min)?\.js\b/i,
+    globals: ['anime'],
+    data: /^data-anime/i,
+  },
+];
+
+/**
+ * Кандидати window-глобалів для проби на сторінці — `motion.mjs` передає список
+ * у `page.evaluate` аргументом (`browserMotionMarkers` фільтрує його по
+ * `window`).
+ *
+ * 🔴 ВИВОДИТЬСЯ із `SIGNATURES`, а не дублює їх руками: глобал, який є в
+ * сигнатурі, але випав зі списку проби, ніколи не питається у сторінки — і
+ * детекція тихо сліпне на цілу бібліотеку (напр. GSAP, підключений як
+ * `TweenMax` без `gsap`). Зворотне дублювання теж шкідливе: зайвий кандидат —
+ * це проба, яку жодна сигнатура не вміє зіставити. Інваріант під тестом.
+ */
+export const MOTION_GLOBALS = [
+  ...new Set(SIGNATURES.flatMap((signature) => signature.globals)),
+].sort();
+
+/**
+ * Зіставити сирі маркери сторінки із сигнатурами (Р6).
+ * @param {{ scriptSrcs?: string[], globals?: string[], dataAttributes?: string[] }} raw
+ * @returns {{ detected: string[], markers: string[] }} обидва масиви — унікальні й відсортовані
+ */
+export function detectMotionLibraries(raw = {}) {
+  const { scriptSrcs = [], globals = [], dataAttributes = [] } = raw;
+  const detected = new Set();
+  const markers = new Set();
+
+  const hit = (name, marker) => {
+    detected.add(name);
+    markers.add(marker);
+  };
+
+  for (const signature of SIGNATURES) {
+    for (const src of scriptSrcs) {
+      if (signature.src.test(src)) hit(signature.name, `script:${src}`);
+    }
+    for (const global of globals) {
+      if (signature.globals.includes(global))
+        hit(signature.name, `global:${global}`);
+    }
+    for (const attribute of dataAttributes) {
+      if (signature.data.test(attribute))
+        hit(signature.name, `data:${attribute}`);
+    }
+  }
+
+  return { detected: [...detected].sort(), markers: [...markers].sort() };
+}
+
+/**
+ * CSS-властивості, поява яких у transition пояснює reveal. `all` — теж
+ * пояснення: під ним ховаються і opacity, і transform.
+ */
+const REVEAL_PROPERTIES = new Set(['all', 'opacity', 'transform']);
+
+/**
+ * Евристика Р6 у ТРЬОХ станах (V-5 інкремента Б.3): reveal на сторінці Є, а ні
+ * transitions по opacity/transform, ні `@keyframes` його не пояснюють → `true`
+ * (анімацію крутить JS, виміряних тривалостей для спеки не буде — автор теми
+ * має дивитись очима); reveal виміряно й механізм видно → `false`; вибірки не
+ * було взагалі → `'unknown'`.
+ *
+ * 🔴 Третій стан — не педантизм. До Б.3 порожня вибірка віддавала той самий
+ * `false`, що й чесно перевірена сторінка, тож сліпий reveal-корінь (розмітка
+ * без `<main>`) читався як «перевірено, підозри немає» — інструмент мовчав про
+ * власну сліпоту. Порожність вибірки видно саме за `reveal`: `diffReveal`
+ * будує рівно один запис на кожен семпльований вузол.
+ *
+ * @param {{ reveal?: Array<{ animated?: boolean }>,
+ *   transitions?: Array<{ property?: string }>,
+ *   keyframes?: { names?: string[] } }} [input]
+ * @returns {boolean | 'unknown'}
+ */
+export function suspectJsDriven({
+  reveal = [],
+  transitions = [],
+  keyframes = {},
+} = {}) {
+  if (reveal.length === 0) return 'unknown';
+  if (!reveal.some((entry) => entry.animated)) return false;
+  const explained =
+    transitions.some((t) => REVEAL_PROPERTIES.has(t.property)) ||
+    (keyframes.names?.length ?? 0) > 0;
+  return !explained;
+}

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

@@ -0,0 +1,126 @@
+/**
+ * Node-обгортка motion-капчера (план Р1/Р4/Р5/Р6): збирає секцію `motion`
+ * для `inspection.json` із пʼяти каналів — transitions, keyframes, reveal,
+ * hover, jsLibraries. Функції, що виконуються в браузері, — `browser-motion.mjs`,
+ * `browser-keyframes.mjs`, `browser-reveal.mjs`; чиста детекція — `motion-detect.mjs`;
+ * ховер-прохід — `hover-sweep.mjs` (Фаза 2).
+ */
+import { browserKeyframes } from './browser-keyframes.mjs';
+import { browserMotionMarkers, browserTransitions } from './browser-motion.mjs';
+import { browserRevealSnapshot } from './browser-reveal.mjs';
+import { scrollThrough } from './browser.mjs';
+import {
+  detectMotionLibraries,
+  MOTION_GLOBALS,
+  suspectJsDriven,
+} from './motion-detect.mjs';
+import { SAMPLE_LIMIT } from './sample.mjs';
+
+/** Поріг «секція реально проявилась» за дельтою opacity (Р4). */
+export const REVEAL_OPACITY_DELTA = 0.2;
+
+/**
+ * @typedef {{ index: number, tag: string, selector: string, opacity: number,
+ *   transform: string }} RevealSnapshotEntry
+ * @typedef {{ entries: RevealDiffEntry[], root: string, sampled: number }} RevealCapture
+ * @typedef {{ index: number, tag: string, selector: string,
+ *   opacityBefore: number, opacityAfter: number, transformChanged: boolean,
+ *   animated: boolean }} RevealDiffEntry
+ */
+
+/**
+ * Різниця двох reveal-знімків (чиста функція — юніти без браузера). Пари
+ * зводяться за `index`, метадані (`tag`/`selector`) беруться зі знімка ДО:
+ * після розкриття класи вузла інші, і «після» дав би нестабільний ключ.
+ * @param {RevealSnapshotEntry[]} before
+ * @param {RevealSnapshotEntry[]} after
+ * @returns {RevealDiffEntry[]}
+ */
+export function diffReveal(before, after) {
+  const afterByIndex = new Map(after.map((entry) => [entry.index, entry]));
+
+  return before
+    .map((from) => {
+      const to = afterByIndex.get(from.index) ?? from;
+      const transformChanged = to.transform !== from.transform;
+      const opacityDelta = Math.abs(to.opacity - from.opacity);
+      return {
+        index: from.index,
+        tag: from.tag,
+        selector: from.selector,
+        opacityBefore: from.opacity,
+        opacityAfter: to.opacity,
+        transformChanged,
+        animated: opacityDelta >= REVEAL_OPACITY_DELTA || transformChanged,
+      };
+    })
+    .sort((a, b) => a.index - b.index);
+}
+
+/**
+ * Зняти reveal-дельту (Р4).
+ *
+ * 🔴 Викликати ЛИШЕ на свіжозавантаженій сторінці й ДО будь-якого іншого
+ * скролу: `scrollThrough` за одну інспекцію відпрацьовує щонайменше пʼять
+ * разів (тричі всередині `captureScreenshots` + під light- і dark-семпли), а
+ * reveal-once секція після першого проходу лишається розкритою назавжди —
+ * у другому проході дельта opacity/transform тотожно нульова.
+ */
+export async function captureReveal(page) {
+  const before = await page.evaluate(browserRevealSnapshot);
+  await scrollThrough(page);
+  const after = await page.evaluate(browserRevealSnapshot);
+  // `sampled`/`root` — зі знімка ДО: саме на ньому будується діф (пари
+  // зводяться за `index` вузлів «до»), тож саме він і є чесним обсягом
+  // вибірки. Порожня вибірка тут — не «сторінка не рухається», а «міряти не
+  // було на чому», і далі це видно в `jsDrivenSuspected` (V-5).
+  return {
+    entries: diffReveal(before.nodes, after.nodes),
+    root: before.root,
+    sampled: before.nodes.length,
+  };
+}
+
+/**
+ * Зібрати секцію `motion` для `inspection.json`. `reveal` і `hover` приходять
+ * ззовні з тієї самої причини — обидва звʼязані порядком кроків інспекції, і
+ * зняти їх тут, наприкінці, було б уже пізно (див. коментар до `captureReveal`
+ * і шапку `hover-sweep.mjs`).
+ * @param {import('@playwright/test').Page} page
+ * @param {{ reveal: RevealCapture, hover: object }} captured
+ * @returns {Promise<{
+ *   transitions: Array<{ property: string, durationMs: number, easing: string, count: number }>,
+ *   keyframes: { names: string[], inaccessibleSheets: number },
+ *   reveal: Array<object>,
+ *   revealSampled: number,
+ *   revealRoot: string,
+ *   hover: { entries: Array<object>, skipped: number },
+ *   jsLibraries: { detected: string[], markers: string[] },
+ *   jsDrivenSuspected: boolean | 'unknown',
+ * }>}
+ */
+export async function captureMotion(page, { reveal, hover }) {
+  const transitions = await page.evaluate(browserTransitions, SAMPLE_LIMIT);
+  const keyframes = await page.evaluate(browserKeyframes);
+  const markers = await page.evaluate(browserMotionMarkers, {
+    globalNames: MOTION_GLOBALS,
+    limit: SAMPLE_LIMIT,
+  });
+
+  return {
+    transitions,
+    keyframes,
+    // Форма `reveal` — той самий масив дифів, що й до Б.3 (спеки компонентів
+    // читають саме його); обсяг вибірки їде СУСІДНІМИ полями, аддитивно.
+    reveal: reveal.entries,
+    revealSampled: reveal.sampled,
+    revealRoot: reveal.root,
+    hover,
+    jsLibraries: detectMotionLibraries(markers),
+    jsDrivenSuspected: suspectJsDriven({
+      reveal: reveal.entries,
+      transitions,
+      keyframes,
+    }),
+  };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Node-обгортка семплінгу computed styles + скріншоти (задача §2.A). Сама
+ * функція, що виконується В БРАУЗЕРІ через `page.evaluate` —
+ * `browser-sample.mjs` (самодостатня, без замикань на цей модуль:
+ * Playwright серіалізує лише її `toString()`).
+ */
+import { browserFonts } from './browser-fonts.mjs';
+import { browserSample } from './browser-sample.mjs';
+import { scrollThrough } from './browser.mjs';
+
+/** Ліміт елементів на семпл (задача §2.A). */
+export const SAMPLE_LIMIT = 2000;
+
+/** Три контрольні viewport задачі §2.A. */
+export const VIEWPORTS = { desktop: 1440, tablet: 768, mobile: 390 };
+
+/** Висота контрольного viewport — спільна для скріншотів і семплу (Р1b). */
+export const VIEWPORT_HEIGHT = 900;
+
+/**
+ * Sanity-межа радіуса, px (план Р2). Карткові/кнопкові радіуси — ≤48px;
+ * усе понад цю межу — pill/full (Tailwind `rounded-full` →
+ * `calc(infinity*1px)` → computed `33554400px`). Фільтр — ТУТ, у Node-
+ * обгортці `samplePalette`, а НЕ всередині `browserSample`: та функція
+ * серіалізується в сторінковий контекст, і модульна константа там дала б
+ * `ReferenceError`.
+ */
+export const RADIUS_SANITY_MAX = 64;
+
+/**
+ * Семпл computed styles сторінки (Node-обгортка `page.evaluate`). Радіус-
+ * кластери понад `RADIUS_SANITY_MAX` — відкидаються тут (Р2), а не в
+ * `browserSample`; `radiusDropped` — чесна лічильна ознака для `inspection.json`.
+ *
+ * Шрифт-сімʼї знімає ОКРЕМИЙ evaluate (`browserFonts`, Р7): вага сімʼї —
+ * сума довжин тексту, і власний обхід текстових вузлів у `browserSample`
+ * уже не вміщався в канонні 150 рядків. Обидва проходи бачать той самий
+ * лейаут (виклик один, viewport між ними не змінюється).
+ */
+export async function samplePalette(page) {
+  const sample = await page.evaluate(browserSample, SAMPLE_LIMIT);
+  const fonts = await page.evaluate(browserFonts, SAMPLE_LIMIT);
+  const radius = sample.radius.filter((r) => r.valuePx <= RADIUS_SANITY_MAX);
+  const radiusDropped = sample.radius.length - radius.length;
+  return { ...sample, fonts, radius, radiusDropped };
+}
+
+/**
+ * Full-page скріншоти на 1440/768/390 → `<outDir>/{desktop,tablet,mobile}.png`.
+ * Перед КОЖНИМ знімком — `scrollThrough` (Р1): ліниві секції, видимі лише на
+ * якомусь одному з трьох viewport-ів (mobile/tablet-only лейаути), інакше
+ * лишаються нерозкритими саме там.
+ */
+export async function captureScreenshots(page, outDir) {
+  const files = {
+    desktop: 'desktop.png',
+    tablet: 'tablet.png',
+    mobile: 'mobile.png',
+  };
+  for (const [key, width] of Object.entries(VIEWPORTS)) {
+    await page.setViewportSize({ width, height: VIEWPORT_HEIGHT });
+    await scrollThrough(page);
+    await page.screenshot({ path: `${outDir}/${files[key]}`, fullPage: true });
+  }
+  return VIEWPORTS;
+}

package/skills/redesign-from-reference/scripts/lib/sitemap-links.mjs

@@ -0,0 +1,24 @@
+/**
+ * Запис ВХОДУ класифікатора для `sitemap-proposal.json` (інкремент Б.3, Р4/V-3).
+ * Окремий модуль, бо `lib/sitemap.mjs` після типізованого блокування пар
+ * (`visit-mismatch`) не має вільних рядків під канон ≤150.
+ */
+import { groupLinksByPathname } from './classify.mjs';
+
+/**
+ * Дедуплікований за нормалізованим pathname зріз лінків з агрегованими
+ * якорями. 🔴 Групування — ТА САМА `groupLinksByPathname`, що й у
+ * класифікаторі (разом зі стартовим pathname): друга реалізація мовчки
+ * розійшлася б із першою, і поле `links` перестало б бути тим, що бачив
+ * класифікатор. 🔴 Будується з ВХІДНОГО набору — до будь-яких виключень
+ * перепідбору: це протокол того, що інструмент побачив, а не знімок робочого
+ * стану. Порядок — лексикографічний за pathname.
+ * @param {Array<{ url: string, anchors?: string[] }>} links
+ * @param {string} startUrl стартовий URL прогону — теж запис входу
+ * @returns {Array<{ pathname: string, anchors: string[] }>}
+ */
+export function summarizeLinks(links, startUrl) {
+  return [...groupLinksByPathname(links, startUrl)]
+    .map(([pathname, { anchors }]) => ({ pathname, anchors: [...anchors] }))
+    .sort((a, b) => a.pathname.localeCompare(b.pathname));
+}

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

@@ -0,0 +1,144 @@
+/**
+ * Побудова `sitemap-proposal.json` з уже зібраних лінків (задача §2.C.3-4,
+ * план Р4/Р5). Чиста оркестрація — `classifyLinks` (Фаза 2, не переписуємо)
+ * дає найкращого кандидата на тип; `visit` — інжектована async-функція
+ * `(url, type) => Promise<{ok, title?, probe?}>` (у CLI — `page.goto` плюс
+ * `browserVisitProbe`, у юніт-тестах — фейк), тож і перепідбір, і
+ * контент-верифікація тестуються без браузера.
+ *
+ * 🔴 Провалів візиту два роди, і виключення в них РІЗНІ за обсягом.
+ * `visit-failed` (не-2xx або мережева помилка) — сторінки немає ні для кого,
+ * тож її pathname вибуває з робочого набору лінків цілком. `visit-mismatch`
+ * (сторінка відкрилась, але зміст суперечить типу — `detectVisitMismatch`)
+ * навпаки: «це не картка товару, а сітка» — ПОЗИТИВНИЙ доказ на користь
+ * `listing`, і глобальне вирізання знищило б доказ разом із помилкою. Тому
+ * блокується лише пара (тип, pathname) — `blockedPairs` віддається
+ * `classifyLinks`, і той самий pathname лишається доступним іншим типам.
+ *
+ * 🔴 Кандидат, чий візит НЕ ok, НЕ лишається «знайденим»: `classifyLinks`
+ * перераховується — тип отримує наступного за score кандидата, якщо він є
+ * (Р4). Цикл завершується, коли черговий прохід нікого не виключив
+ * (стабілізація). 🔴 Термінацію дають ДВА факти, і жоден із них — не гард
+ * `excludedAny`: кожна ітерація з провалом витрачає ≥1 візит, а на
+ * `visitsUsed >= maxVisits` усі `pending` фіналізуються як `visited: false`,
+ * тож наступний прохід має порожній `pending`; плюс множина пар
+ * (тип, pathname) скінченна. Перевірки «виключення справді НОВЕ» — захисні:
+ * `classifyLinks` заблоковану пару вдруге не пропонує, тож повторного
+ * блокування на нинішній семантиці не буває (доведено інструментацією в
+ * ревʼю). Бюджет візитів (`maxVisits`) — спільний на ВСІ типи; кандидат
+ * понад бюджет лишається знайденим, але чесно `visited: false`.
+ *
+ * 🔴 `schemaVersion: 2` (інкремент Б.3, Р4/V-3): голе число `linksSeen`
+ * ЗАМІНЕНО масивом `links` — саме те, що бачив класифікатор, включно зі
+ * стартовим pathname (той є кандидатом навіть без вхідних лінків на себе).
+ * Без цього поля діагностика помилки класифікації вимагала власного зонда: з
+ * пропозиції не було видно ні які pathname зібрано, ні з якими якорями.
+ */
+import { classifyLinks, normalizePathname } from './classify.mjs';
+import { URL_PATTERNS } from './classify-terms.mjs';
+import { detectVisitMismatch } from './visit-probe.mjs';
+import { summarizeLinks } from './sitemap-links.mjs';
+
+// 2 (інкремент Б.3, Р4/V-3) — голе число `linksSeen` ЗАМІНЕНО масивом `links`.
+// 🔴 Це ТРЕТІЙ незалежний лічильник версій інструмента, і плутати їх не можна:
+// `lib/inspect-page.mjs` версіонує `inspection.json` (вхід інспекції),
+// `lib/map.mjs` — `tokens-proposal.json` (вихід мапінгу), тут —
+// `sitemap-proposal.json` (вихід дискаверера). Рухаються незалежно.
+const SCHEMA_VERSION = 2;
+
+/** Усі канонічні типи сторінок — `home` (окреме правило в `classifyLinks`) + словник Фази 2. */
+const ALL_TYPES = ['home', ...Object.keys(URL_PATTERNS)];
+
+/**
+ * @param {{
+ *   links: Array<{ url: string, anchors: string[] }>,
+ *   startUrl: string,
+ *   maxVisits: number,
+ *   visit: (url: string, type: string) => Promise<{
+ *     ok: boolean, title?: string | null,
+ *     probe?: { jsonLdTypes: string[], cardLinks: number },
+ *   }>,
+ * }} params
+ * @returns {Promise<{
+ *   schemaVersion: typeof SCHEMA_VERSION, startUrl: string,
+ *   links: Array<{ pathname: string, anchors: string[] }>,
+ *   pageTypes: Record<string, { url: string, score: number, evidence: unknown[], visited: boolean, title?: string }>,
+ *   unresolved: Array<{ type: string, reason: 'no-candidate' | 'visit-failed' | 'visit-mismatch' }>,
+ * }>}
+ */
+export async function buildSitemapProposal({
+  links,
+  startUrl,
+  maxVisits,
+  visit,
+}) {
+  let workingLinks = links;
+  const finalPageTypes = {};
+  // 🔴 Не Set, а Map: причина відмови — частина відповіді. Якщо тип провалив
+  // кілька кандидатів поспіль, лишається причина ОСТАННЬОГО — саме він і є
+  // тим, на чому перепідбір зупинився.
+  const failedTypes = new Map();
+  /** pathname → типи, спростовані пробом саме для цієї сторінки (Б.3, фікс рев'ю). */
+  const blockedPairs = new Map();
+  let visitsUsed = 0;
+
+  for (;;) {
+    const { pageTypes } = classifyLinks(workingLinks, startUrl, blockedPairs);
+    const pending = Object.keys(pageTypes).filter(
+      (type) => !finalPageTypes[type],
+    );
+    if (pending.length === 0) break;
+
+    let excludedAny = false;
+    for (const type of pending) {
+      const candidate = pageTypes[type];
+      if (visitsUsed >= maxVisits) {
+        finalPageTypes[type] = { ...candidate, visited: false };
+        continue;
+      }
+      visitsUsed += 1;
+      const result = await visit(candidate.url, type);
+      const mismatch = result.ok && detectVisitMismatch(type, result.probe);
+      if (result.ok && !mismatch) {
+        finalPageTypes[type] = {
+          ...candidate,
+          visited: true,
+          ...(result.title ? { title: result.title } : {}),
+        };
+      } else if (mismatch) {
+        failedTypes.set(type, 'visit-mismatch');
+        const pathname = normalizePathname(candidate.url);
+        const blocked = blockedPairs.get(pathname) ?? new Set();
+        if (!blocked.has(type)) {
+          blocked.add(type);
+          blockedPairs.set(pathname, blocked);
+          excludedAny = true;
+        }
+      } else {
+        failedTypes.set(type, 'visit-failed');
+        const failedPathname = normalizePathname(candidate.url);
+        const before = workingLinks.length;
+        workingLinks = workingLinks.filter(
+          (link) => normalizePathname(link.url) !== failedPathname,
+        );
+        if (workingLinks.length < before) excludedAny = true;
+      }
+    }
+    if (!excludedAny) break; // усі pending або підтверджені, або бюджет вичерпано
+  }
+
+  const unresolved = ALL_TYPES.filter((type) => !finalPageTypes[type]).map(
+    (type) => ({
+      type,
+      reason: failedTypes.get(type) ?? 'no-candidate',
+    }),
+  );
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    startUrl,
+    links: summarizeLinks(links, startUrl),
+    pageTypes: finalPageTypes,
+    unresolved,
+  };
+}

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

@@ -0,0 +1,97 @@
+/**
+ * Структурований звіт про кольори, які нікуди не лягли (план Р7; знахідки
+ * V-6 + V-7 прогону №2). Окремий модуль, а не доважок до `color-tokens.mjs` —
+ * той уже впритул до канону 150 рядків, і предмет тут інший: не мапінг, а
+ * ЧЕСНІСТЬ виводу. До Б.3 `unmapped` був голим списком hex із дублікатами:
+ * ні ролі, ні частоти, ні контрасту — тож провальний за AA текстовий колір
+ * (`#6a7282` на полотні, 4.44) дві сесії поспіль проходив повз попередження,
+ * бо `contrastWarnings` дивиться ЛИШЕ на змаповані пари.
+ */
+import {
+  contrastRatio,
+  hslToRgb,
+  parseColor,
+  parseHslTriple,
+  rgbToHex,
+} from './color.mjs';
+import { AA_MIN_RATIO } from './contrast.mjs';
+
+/**
+ * @typedef {{ value: string, hsl: { h: number, s: number, l: number },
+ *   frequency: number, area?: number }} ColorCluster
+ * @typedef {{ hex: string, role: string, count: number, area: number,
+ *   contrastOnBackground: number | null, contrastOnCard: number | null,
+ *   belowAA: boolean }} UnmappedEntry
+ */
+
+/**
+ * Контраст кольору проти токена-поверхні (`"H S% L%"`), округлений до сотих.
+ * `null` — токена в пропозиції немає (а НЕ `0`: нуль читався б як виміряний
+ * і катастрофічний контраст, якого ніхто не міряв).
+ */
+function contrastAgainst(rgb, tokenValue) {
+  const hsl = parseHslTriple(tokenValue);
+  if (!hsl) return null;
+  return Math.round(contrastRatio(rgb, hslToRgb(hsl)) * 100) / 100;
+}
+
+/**
+ * Зібрати `unmapped` із кластерів, що не потрапили в жоден токен.
+ * @param {Record<string, ColorCluster[]>} byRole кластери за роллю семпла
+ * @param {Set<object>} used кластери, вже витрачені мапінгом (посилання, не значення)
+ * @param {Record<string, string>} tokens запропоновані токени — потрібні `background`/`card`
+ * @returns {UnmappedEntry[]}
+ */
+export function collectUnmapped(byRole, used, tokens) {
+  const entries = new Map();
+
+  for (const [role, clusters] of Object.entries(byRole)) {
+    for (const cluster of clusters) {
+      if (used.has(cluster)) continue;
+      const rgb = parseColor(cluster.value) ?? hslToRgb(cluster.hsl);
+      const hex = rgbToHex(rgb);
+      // 🔴 Ключ дедупу — hex + РОЛЬ. Той самий колір як текст і як фон секції —
+      // це два різні факти про сторінку (саме тому `used` у `color-tokens.mjs`
+      // тримає посилання на кластери, а не значення), і злиття їх приховало б
+      // роль, від якої залежить `belowAA`. Дублі ж усередині однієї ролі
+      // (`rgb(17,17,17)` і `#111111` — різні рядки, один колір) схлопуються.
+      const key = `${hex}|${role}`;
+      const known = entries.get(key);
+      if (known) {
+        known.count += cluster.frequency;
+        known.area += cluster.area ?? 0;
+        continue;
+      }
+
+      const onBackground = contrastAgainst(rgb, tokens.background);
+      const onCard = contrastAgainst(rgb, tokens.card);
+      const measured = [onBackground, onCard].filter((r) => r !== null);
+      entries.set(key, {
+        hex,
+        role,
+        count: cluster.frequency,
+        area: cluster.area ?? 0,
+        contrastOnBackground: onBackground,
+        contrastOnCard: onCard,
+        // 🔴 Прапорець має сенс ЛИШЕ для ролі `text`: контраст фонового
+        // кольору «на фоні» ≈1 за визначенням, і на решті ролей прапорець
+        // засвітив би геть усе, тобто не означав би нічого. Беремо НАЙГІРШУ
+        // з доступних поверхонь: провал на картці так само тихий, як провал
+        // на полотні (V-7), а поверхонь у пропозиції дві.
+        belowAA:
+          role === 'text' &&
+          measured.length > 0 &&
+          Math.min(...measured) < AA_MIN_RATIO,
+      });
+    }
+  }
+
+  // Стабільний порядок (Р7): частота ↓, далі hex, далі роль — щоб два прогони
+  // на тому самому `inspection.json` давали побайтово однаковий файл.
+  return [...entries.values()].sort(
+    (a, b) =>
+      b.count - a.count ||
+      a.hex.localeCompare(b.hex) ||
+      a.role.localeCompare(b.role),
+  );
+}

package/skills/redesign-from-reference/scripts/lib/visit-candidate.mjs

@@ -0,0 +1,53 @@
+/**
+ * Візит кандидатної сторінки для дискаверера (інкремент Б.3, план Р4/Р5).
+ * Винесено з `discover.mjs` окремим модулем, бо після двох фіксів рев'ю
+ * (скрол перед пробом і власний `catch` навколо проба) функція перестала
+ * бути «одним рядком поверх `page.goto`» — а канон тримає CLI тонким.
+ *
+ * 🔴 Провал проба НЕ провалює візит. Проб — додатковий сигнал; CSP, detached
+ * frame чи таймаут `evaluate` не роблять сторінку, яка чесно віддала 2xx,
+ * неіснуючою. Тому проб має власний `try/catch`, а при помилці візит
+ * повертається БЕЗ поля `probe` — і `detectVisitMismatch` на відсутньому
+ * пробі за контрактом віддає `false` («не міряли» ≠ «не збіглось»).
+ * Без цього поділу будь-яка помилка проба перетворювалась на `visit-failed` —
+ * рівно той клас «інструмент бачить не все й мовчить», проти якого весь
+ * інкремент.
+ */
+import { scrollThrough } from './browser.mjs';
+
+/** Типи, зміст яких верифікується пробом (Б.3, Р5) — решті сторінок вірять на слово. */
+export const PROBED_TYPES = new Set(['listing', 'product']);
+
+/**
+ * @param {import('playwright').Page} page
+ * @param {string} url
+ * @param {string} type канонічний тип, під який кандидата перевіряють
+ * @param {(...args: unknown[]) => unknown} probeFn самодостатня функція проба
+ *   (серіалізується в браузер через `page.evaluate`)
+ * @returns {Promise<{ ok: boolean, title?: string | null, probe?: object }>}
+ */
+export async function visitCandidate(page, url, type, probeFn) {
+  let title;
+  try {
+    const response = await page.goto(url, {
+      waitUntil: 'networkidle',
+      timeout: 30_000,
+    });
+    if (!response || !response.ok()) return { ok: false };
+    title = (await page.title()) || null;
+  } catch {
+    return { ok: false }; // мережева помилка чи таймаут переходу — сторінки немає
+  }
+  if (!PROBED_TYPES.has(type)) return { ok: true, title };
+  try {
+    // 🔴 Скрол ПЕРЕД пробом, як і на стартовій сторінці: сітку карток масово
+    // дорендеровують на скролі, і знятий одразу після `goto` проб побачив би
+    // нуль карток на цілком нормальному каталозі.
+    await scrollThrough(page);
+    // Тип їде аргументом у браузер: від нього залежить відсікання батьківської
+    // сімʼї карток (лише для `product`; ревʼю Б.3, флет-каталоги для `listing`).
+    return { ok: true, title, probe: await page.evaluate(probeFn, type) };
+  } catch {
+    return { ok: true, title };
+  }
+}