crawlforge-mcp-server 6.24.0 → 6.25.1

package/src/tools/scrape/_brandingComputed.js

@@ -0,0 +1,262 @@
+/**
+ * _brandingComputed.js — colour roles, buttons and type from the rendered page.
+ *
+ *   brandingProbe          runs in the browser and only COLLECTS computed
+ *                          styles: the page background, body text, h1/h2, a
+ *                          few links and the button-sized controls near the
+ *                          top of the page. page.evaluate serializes it, so it
+ *                          must not close over anything in this module.
+ *   buildComputedBranding  decides, in Node where it can be tested, which
+ *                          control is the primary button and what each role
+ *                          is. Every value it returns is source:"computed".
+ *   inferRoles             the fallback when no render ran: role guesses from
+ *                          CSS variable names, marked source:"inferred".
+ */
+
+import { parseColor, toHex, chroma, luminance, distance } from './_brandingColor.js';
+
+export function brandingProbe() {
+  const canvas = document.createElement('canvas');
+  canvas.width = canvas.height = 1;
+  const ctx = canvas.getContext('2d', { willReadFrequently: true });
+  // Any computed colour (oklch, color(), lab) to rgba() through one canvas pixel.
+  const rgba = (c) => {
+    ctx.clearRect(0, 0, 1, 1);
+    ctx.fillStyle = 'rgba(0,0,0,0)';
+    ctx.fillStyle = c || 'rgba(0,0,0,0)';
+    ctx.fillRect(0, 0, 1, 1);
+    const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+    return `rgba(${r},${g},${b},${Math.round((a / 255) * 1000) / 1000})`;
+  };
+  // The colour a reader sees is the fill of the element holding the text. On
+  // a layered headline that is a child span, not the h1: stripe.com's h1
+  // carries a decorative green while its first line is painted #061b31.
+  const textColor = (el) => {
+    const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT, {
+      acceptNode: (n) => (n.textContent.trim() ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP),
+    });
+    const holder = walker.nextNode()?.parentElement || el;
+    const s = getComputedStyle(holder);
+    return rgba(s.webkitTextFillColor || s.color);
+  };
+  const style = (el) => {
+    const s = getComputedStyle(el);
+    return {
+      color: textColor(el),
+      background: rgba(s.backgroundColor),
+      borderColor: rgba(s.borderTopColor),
+      borderWidth: s.borderTopWidth,
+      borderStyle: s.borderTopStyle,
+      borderRadius: s.borderTopLeftRadius,
+      padding: `${s.paddingTop} ${s.paddingRight} ${s.paddingBottom} ${s.paddingLeft}`,
+      fontFamily: s.fontFamily,
+      fontSize: s.fontSize,
+      fontWeight: s.fontWeight,
+      lineHeight: s.lineHeight,
+      letterSpacing: s.letterSpacing,
+      textTransform: s.textTransform,
+      boxShadow: s.boxShadow,
+    };
+  };
+  const OVERLAY = '[id*="cookie" i],[class*="cookie" i],[id*="consent" i],[class*="consent" i],[aria-modal="true"],dialog';
+  // Painted, on the page and not a 1px screen-reader-only box (a "Skip to
+  // content" link sits off-screen until focused).
+  const shown = (el) => {
+    const r = el.getBoundingClientRect();
+    const s = getComputedStyle(el);
+    return r.width > 1 && r.height > 1 && r.right > 0 && r.bottom > 0 && s.visibility !== 'hidden' &&
+      s.display !== 'none' && Number(s.opacity) > 0 && !el.closest(OVERLAY);
+  };
+  const text = (el) => (el.innerText || el.value || '').replace(/\s+/g, ' ').trim().slice(0, 60);
+  const find = (selector, ok = () => true) => {
+    for (const el of document.querySelectorAll(selector)) if (shown(el) && ok(el)) return el;
+    return null;
+  };
+  const describe = (el) => (el ? { tag: el.tagName.toLowerCase(), text: text(el), style: style(el) } : null);
+
+  const collect = () => {
+    const links = [];
+    for (const el of document.querySelectorAll('p a, main a, a')) {
+      if (links.length >= 6) break;
+      if (shown(el) && text(el).length > 1) links.push(describe(el));
+    }
+    const buttons = [];
+    const limit = window.innerHeight * 1.5;
+    for (const el of document.querySelectorAll('button, a, [role="button"], input[type="submit"], input[type="button"]')) {
+      if (buttons.length >= 40) break;
+      const r = el.getBoundingClientRect();
+      const t = text(el);
+      if (r.top > limit || r.height < 24 || r.height > 96 || r.width < 40 || r.width > 480 || !t || t.length > 40) continue;
+      if (!shown(el)) continue;
+      buttons.push({
+        ...describe(el),
+        rect: { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) },
+        inHeader: Boolean(el.closest('header, nav')),
+      });
+    }
+    return {
+      url: location.href,
+      viewport: { w: window.innerWidth, h: window.innerHeight },
+      background: { body: rgba(getComputedStyle(document.body).backgroundColor), html: rgba(getComputedStyle(document.documentElement).backgroundColor) },
+      body: describe(document.body),
+      heading: describe(find('h1')),
+      h2: describe(find('h2')),
+      // Body copy: a sentence-length paragraph at a reading size, so a large
+      // lede set in a <p> is not taken for the body text.
+      paragraph: describe(find('main p, article p, p', (el) => {
+        const size = parseFloat(getComputedStyle(el).fontSize);
+        return text(el).length >= 40 && size >= 14 && size <= 20;
+      }) || find('main p, article p, p', (el) => text(el).length >= 40)),
+      links,
+      buttons,
+    };
+  };
+  // Web fonts change the computed family only once loaded; wait at most 2s.
+  return Promise.race([document.fonts.ready, new Promise((resolve) => setTimeout(resolve, 2000))]).then(collect, collect);
+}
+
+const WHITE = { r: 255, g: 255, b: 255, a: 1 };
+// Two colours closer than this read as the same to a reader.
+const SAME = 24;
+
+const opaque = (v) => {
+  const c = parseColor(v);
+  return c && c.a > 0.05 ? c : null;
+};
+const firstFamily = (stack) => (stack || '').split(',')[0].trim().replace(/^['"]|['"]$/g, '') || null;
+
+function compact(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v != null && v !== '' && v !== 'none'));
+}
+
+/**
+ * Colour roles, button components and type from a brandingProbe() result.
+ * @param {object} probe
+ * @returns {{ colorScheme: string, roles: object, components: object, typography: object }}
+ */
+export function buildComputedBranding(probe) {
+  const pageBg = opaque(probe.background?.body) || opaque(probe.background?.html) || WHITE;
+  const filled = (s) => {
+    const bg = opaque(s.background);
+    return Boolean(bg && distance(bg, pageBg) > SAME);
+  };
+  const outlined = (s) => {
+    const border = opaque(s.borderColor);
+    return parseFloat(s.borderWidth) >= 1 && s.borderStyle !== 'none' && Boolean(border && distance(border, pageBg) > SAME);
+  };
+
+  const roles = {};
+  const role = (name, c, evidence) => {
+    if (c) roles[name] = { value: toHex(c), source: 'computed', evidence };
+  };
+  role('background', pageBg, 'page background');
+  const textEl = probe.paragraph || probe.body;
+  role('text', textEl && opaque(textEl.style.color), probe.paragraph ? 'body paragraph' : 'body');
+  role('heading', probe.heading && opaque(probe.heading.style.color), 'h1');
+  const link = (probe.links || []).find((l) => !filled(l.style) && !outlined(l.style));
+  role('link', link && opaque(link.style.color), link && `link "${link.text}"`);
+
+  // The primary button is the filled control with the most visual weight:
+  // area, boosted by saturation so a brand-coloured CTA beats a grey one.
+  const buttons = (probe.buttons || []).map((b, i) => ({ ...b, i, bg: opaque(b.style.background) }));
+  const filledButtons = buttons.filter((b) => filled(b.style));
+  const weight = (b) => b.rect.w * b.rect.h * (1 + 2 * chroma(b.bg));
+  const primary = [...filledButtons].sort((x, y) => weight(y) - weight(x) || x.i - y.i)[0] || null;
+  // The secondary is the outline button nearest the primary and in the same
+  // band (160px vertically), which keeps it in the CTA pair: linear.app has
+  // no partner for its header CTA, and its nearest outline is an "iOS" pill.
+  const gap = (b) => Math.hypot(b.rect.x - primary.rect.x, b.rect.y - primary.rect.y);
+  const near = (b) => b !== primary && Math.abs(b.rect.y - primary.rect.y) <= 160;
+  const secondary = primary
+    ? buttons.filter((b) => near(b) && !filled(b.style) && outlined(b.style)).sort((x, y) => gap(x) - gap(y))[0] ||
+      filledButtons.find((b) => near(b) && distance(b.bg, primary.bg) > SAME) ||
+      null
+    : null;
+  if (primary) {
+    role('primary', primary.bg, `button "${primary.text}"`);
+    role('onPrimary', opaque(primary.style.color), `label of button "${primary.text}"`);
+  }
+
+  const component = (b) => compact({
+    text: b.text,
+    background: filled(b.style) ? toHex(b.bg) : null,
+    color: opaque(b.style.color) ? toHex(opaque(b.style.color)) : null,
+    borderColor: outlined(b.style) ? toHex(opaque(b.style.borderColor)) : null,
+    borderWidth: outlined(b.style) ? b.style.borderWidth : null,
+    // A pill computes to whatever its huge radius was (calc(infinity * 1px) is 3.35544e+07px).
+    borderRadius: b.style.borderRadius === '0px' ? null : parseFloat(b.style.borderRadius) >= 9999 ? '9999px' : b.style.borderRadius,
+    padding: b.style.padding,
+    fontFamily: firstFamily(b.style.fontFamily),
+    fontSize: b.style.fontSize,
+    fontWeight: b.style.fontWeight,
+    textTransform: b.style.textTransform,
+    boxShadow: b.style.boxShadow,
+    source: 'computed',
+  });
+  const components = {};
+  if (primary) components.buttonPrimary = component(primary);
+  if (secondary) components.buttonSecondary = component(secondary);
+
+  const type = (el) => el && compact({
+    fontFamily: firstFamily(el.style.fontFamily),
+    fontStack: el.style.fontFamily,
+    fontSize: el.style.fontSize,
+    fontWeight: el.style.fontWeight,
+    lineHeight: el.style.lineHeight,
+    letterSpacing: el.style.letterSpacing === 'normal' ? null : el.style.letterSpacing,
+    color: opaque(el.style.color) ? toHex(opaque(el.style.color)) : null,
+    source: 'computed',
+  });
+  const typography = compact({ body: type(textEl), h1: type(probe.heading), h2: type(probe.h2) });
+
+  return {
+    colorScheme: schemeOf(toHex(pageBg)),
+    roles,
+    components,
+    typography,
+  };
+}
+
+/**
+ * Role guesses from CSS variable names, for when the page was not rendered.
+ * A name must end in the role word (optionally -default/-primary/-base), so
+ * --color-background counts and --input-bg-hover does not.
+ * @param {Record<string, string|null>} resolved - '--name' -> resolved value
+ * @param {Array<{value: string, source: string}>} colors - the frequency list
+ */
+export function inferRoles(resolved, colors = []) {
+  const roles = {};
+  const pick = (re, ok = () => true) => {
+    for (const [name, value] of Object.entries(resolved)) {
+      if (value == null || !re.test(name)) continue;
+      const c = parseColor(value);
+      if (c && c.a > 0.5 && ok(c)) return { value: toHex(c), source: 'inferred', evidence: `CSS variable ${name}` };
+    }
+    return null;
+  };
+  const end = (words) => new RegExp(`(?:^--|-)(?:${words})(?:-(?:default|primary|base|500|600))?$`, 'i');
+  const saturated = (c) => chroma(c) >= 0.25;
+
+  const fromList = (source, evidence) => {
+    const hit = colors.find((c) => c.source === source && saturated(parseColor(c.value)));
+    return hit ? { value: hit.value, source: 'inferred', evidence } : null;
+  };
+  const primary = pick(end('primary|brand|accent'), saturated) ||
+    fromList('theme-color', 'meta theme-color') ||
+    fromList('css-var', 'most frequent saturated colour in brand-named CSS variables');
+  const background = pick(end('background|bg|surface'));
+  const text = pick(end('foreground|fg|text'));
+  const link = pick(end('link'));
+
+  if (background) roles.background = background;
+  if (text) roles.text = text;
+  if (link) roles.link = link;
+  if (primary) roles.primary = primary;
+  return roles;
+}
+
+/** 'light' or 'dark' from a background role, or null without one. */
+export function schemeOf(backgroundHex) {
+  const c = parseColor(backgroundHex);
+  return c ? (luminance(c) < 0.4 ? 'dark' : 'light') : null;
+}

package/src/tools/scrape/_brandingExtractor.js

@@ -1,14 +1,17 @@
 /**
- * _brandingExtractor.js — static design-token / branding extraction.
+ * _brandingExtractor.js — design-token / branding extraction.
  *
- * Extracts a site's visual identity from HTML + CSS WITHOUT a browser:
+ * Extracts a site's visual identity from HTML + CSS:
  *   - colors      (CSS custom properties, theme-color, declarations) -> hex + frequency
  *   - fonts       (font-family, @font-face, Google/Adobe webfont links)
  *   - logo        (favicons, og:image, header img/svg candidates)
- *   - tokens      (border-radius, box-shadow, spacing custom props)
+ *   - tokens      (CSS custom properties, var() chains resolved, grouped; _brandingTokens.js)
+ *   - roles       (background, text, heading, link, primary) plus button
+ *                 components and type, from a rendered page's computed styles
+ *                 when the caller passes a probe result (_brandingComputed.js),
+ *                 otherwise guessed from variable names and marked "inferred"
  *
- * Static-only limits (documented in the returned `notes`): computed/cascaded
- * styles and JS-injected CSS are not visible without rendering. Linked CSS is
+ * Without a probe result, JS-injected CSS is not visible. Linked CSS is
  * fetched through the SSRF guard, capped in count/size/time.
  *
  * Every helper is defensive: failures push to `warnings` and never throw.
@@ -16,6 +19,9 @@
 
 import { safeFetch } from '../../utils/ssrfGuard.js';
 import { mediaAppliesToScreen } from '../../utils/hiddenContent.js';
+import { parseColor, toHex } from './_brandingColor.js';
+import { resolveValue, groupTokens, toDtcg } from './_brandingTokens.js';
+import { buildComputedBranding, inferRoles, schemeOf } from './_brandingComputed.js';
 
 const GENERIC_FAMILIES = new Set([
   'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy', 'system-ui',
@@ -23,14 +29,6 @@ const GENERIC_FAMILIES = new Set([
   'initial', 'unset', 'revert', 'emoji', 'math', 'fangsong',
 ]);
 
-const NAMED_COLORS = {
-  black: '#000000', white: '#ffffff', red: '#ff0000', green: '#008000',
-  blue: '#0000ff', yellow: '#ffff00', orange: '#ffa500', purple: '#800080',
-  gray: '#808080', grey: '#808080', silver: '#c0c0c0', navy: '#000080',
-  teal: '#008080', maroon: '#800000', olive: '#808000', lime: '#00ff00',
-  aqua: '#00ffff', fuchsia: '#ff00ff',
-};
-
 // CSS variable names that strongly indicate brand colors.
 const BRAND_VAR_RE = /(primary|secondary|brand|accent|theme|background|surface|foreground|text|link)/i;
 
@@ -38,71 +36,13 @@ function clamp(n, lo, hi) {
   return Math.max(lo, Math.min(hi, n));
 }
 
-function toHex2(n) {
-  return clamp(Math.round(n), 0, 255).toString(16).padStart(2, '0');
-}
-
 /**
  * Normalize a CSS color token to lowercase #rrggbb (drops alpha). Returns null
  * for values we can't confidently parse (gradients, currentColor, var(), etc.).
  */
 export function normalizeColor(raw) {
-  if (!raw) return null;
-  const v = String(raw).trim().toLowerCase();
-
-  if (NAMED_COLORS[v]) return NAMED_COLORS[v];
-
-  // hex
-  let m = v.match(/^#([0-9a-f]{3,8})$/);
-  if (m) {
-    const h = m[1];
-    if (h.length === 3) return '#' + h.split('').map((c) => c + c).join('');
-    if (h.length === 4) return '#' + h.slice(0, 3).split('').map((c) => c + c).join('');
-    if (h.length === 6) return '#' + h;
-    if (h.length === 8) return '#' + h.slice(0, 6);
-    return null;
-  }
-
-  // rgb()/rgba()
-  m = v.match(/^rgba?\(([^)]+)\)$/);
-  if (m) {
-    const parts = m[1].split(/[,/\s]+/).filter(Boolean);
-    if (parts.length >= 3) {
-      const [r, g, b] = parts;
-      const pn = (x) => (x.endsWith('%') ? (parseFloat(x) / 100) * 255 : parseFloat(x));
-      const rr = pn(r), gg = pn(g), bb = pn(b);
-      if ([rr, gg, bb].every((x) => !Number.isNaN(x))) return '#' + toHex2(rr) + toHex2(gg) + toHex2(bb);
-    }
-    return null;
-  }
-
-  // hsl()/hsla()
-  m = v.match(/^hsla?\(([^)]+)\)$/);
-  if (m) {
-    const parts = m[1].split(/[,/\s]+/).filter(Boolean);
-    if (parts.length >= 3) {
-      const h = parseFloat(parts[0]);
-      const s = parseFloat(parts[1]) / 100;
-      const l = parseFloat(parts[2]) / 100;
-      if (![h, s, l].some((x) => Number.isNaN(x))) {
-        const c = (1 - Math.abs(2 * l - 1)) * s;
-        const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
-        const mm = l - c / 2;
-        let r = 0, g = 0, b = 0;
-        const hh = ((h % 360) + 360) % 360;
-        if (hh < 60) [r, g, b] = [c, x, 0];
-        else if (hh < 120) [r, g, b] = [x, c, 0];
-        else if (hh < 180) [r, g, b] = [0, c, x];
-        else if (hh < 240) [r, g, b] = [0, x, c];
-        else if (hh < 300) [r, g, b] = [x, 0, c];
-        else [r, g, b] = [c, 0, x];
-        return '#' + toHex2((r + mm) * 255) + toHex2((g + mm) * 255) + toHex2((b + mm) * 255);
-      }
-    }
-    return null;
-  }
-
-  return null;
+  const c = parseColor(raw);
+  return c ? toHex(c) : null;
 }
 
 function resolveUrl(href, base) {
@@ -245,7 +185,7 @@ function extractColors(cssText, $, cssVariables) {
   // brand-ish CSS variables (high confidence)
   for (const [name, value] of Object.entries(cssVariables)) {
     if (BRAND_VAR_RE.test(name)) {
-      const hex = normalizeColor(value);
+      const hex = normalizeColor(resolveValue(value, cssVariables, new Set([name])));
       if (hex) add(hex, 'css-var');
     }
   }
@@ -396,33 +336,40 @@ function extractLogo($, pageUrl) {
 }
 
 function extractTokens(cssText, cssVariables) {
+  // Declarations that reference a variable count under the value it resolves to.
   const collect = (re) => {
     const counts = new Map();
     let m;
     while ((m = re.exec(cssText)) !== null) {
-      const v = m[1].trim();
+      const v = resolveValue(m[1].replace(/!important/i, '').trim(), cssVariables);
       if (v && !v.includes('var(')) counts.set(v, (counts.get(v) || 0) + 1);
     }
     return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([value, count]) => ({ value, count }));
   };
 
-  const spacing = {};
-  for (const [name, value] of Object.entries(cssVariables)) {
-    if (/(space|spacing|gap|radius|size)/i.test(name)) spacing[name] = value;
-  }
-
   return {
     radii: collect(/border-radius\s*:\s*([^;}{]+)/gi),
     shadows: collect(/box-shadow\s*:\s*([^;}{]+)/gi),
-    spacingVariables: spacing,
   };
 }
 
+// What each `source` value in the result means, returned with it so a reader
+// of the output can audit any value without this file.
+const PROVENANCE = {
+  computed: 'read from the rendered page with getComputedStyle',
+  'css-variable': 'a CSS custom property, var() references resolved',
+  'css-var': 'counted in brand-named CSS custom properties',
+  'theme-color': 'the page\'s theme-color meta tag',
+  declaration: 'counted in CSS declarations',
+  inferred: 'a guess from CSS variable names; no rendered element confirmed it',
+};
+
 /**
  * Extract the full branding object from a loaded cheerio $.
  * @param {import('cheerio').CheerioAPI} $
  * @param {string} pageUrl
- * @param {{ fetchLinkedCss?: boolean, maxStylesheets?: number, perFileTimeoutMs?: number, timeoutMs?: number, overallTimeoutMs?: number, stylesheetConcurrency?: number, media?: 'screen'|'unconditional-screen', inlineStyles?: boolean }} [opts]
+ * @param {{ fetchLinkedCss?: boolean, maxStylesheets?: number, perFileTimeoutMs?: number, timeoutMs?: number, overallTimeoutMs?: number, stylesheetConcurrency?: number, media?: 'screen'|'unconditional-screen', inlineStyles?: boolean, computed?: object|null, rawVariables?: boolean, dtcg?: boolean }} [opts]
+ *   `computed` is a brandingProbe() result from a render of the same page.
  * @returns {Promise<object>}
  */
 export async function extractBranding($, pageUrl, opts = {}) {
@@ -445,26 +392,51 @@ export async function extractBranding($, pageUrl, opts = {}) {
   const colors = safe(() => extractColors(sources.cssText, $, cssVariables), [], 'colors');
   const fontInfo = safe(() => extractFonts(sources.cssText, $, cssVariables), { fonts: [], genericFallbacks: [], webfontProviders: [], fontFaces: [] }, 'fonts');
   const logo = safe(() => extractLogo($, pageUrl), { favicons: [], ogImage: null, candidates: [], inlineHeaderSvg: null }, 'logo');
-  const tokens = safe(() => extractTokens(sources.cssText, cssVariables), { radii: [], shadows: [], spacingVariables: {} }, 'tokens');
+  const declTokens = safe(() => extractTokens(sources.cssText, cssVariables), { radii: [], shadows: [] }, 'tokens');
+  const tokens = safe(() => groupTokens(cssVariables), null, 'token grouping');
+
+  const computed = options.computed ? safe(() => buildComputedBranding(options.computed), null, 'computed styles') : null;
+  const resolved = safe(() => Object.fromEntries(Object.entries(cssVariables).map(([k, v]) => [k, resolveValue(v, cssVariables, new Set([k]))])), {}, 'variable resolution');
+  // Computed roles win; an inferred guess fills only a role no element showed.
+  const roles = { ...(computed?.roles || {}) };
+  for (const [name, guess] of Object.entries(safe(() => inferRoles(resolved, colors), {}, 'role inference'))) {
+    if (!roles[name]) roles[name] = guess;
+  }
 
-  return {
-    colors,
+  const result = {
+    colorScheme: computed?.colorScheme || schemeOf(roles.background?.value) || undefined,
+    roles,
+    components: computed?.components || {},
+    typography: computed?.typography || {},
     fonts: fontInfo.fonts,
     genericFallbacks: fontInfo.genericFallbacks,
     webfontProviders: fontInfo.webfontProviders,
     fontFaces: fontInfo.fontFaces,
     logo,
-    cssVariables,
-    radii: tokens.radii,
-    shadows: tokens.shadows,
-    spacing: tokens.spacingVariables,
+    colors,
+    tokens: tokens ? { source: 'css-variable', ...tokens } : undefined,
+    radii: declTokens.radii,
+    shadows: declTokens.shadows,
+  };
+  if (options.rawVariables) result.cssVariables = cssVariables;
+  if (options.dtcg && tokens) {
+    result.dtcg = safe(() => toDtcg({ tokens, roles, fonts: fontInfo.fonts, url: pageUrl }), undefined, 'dtcg');
+  }
+
+  return {
+    ...result,
     sources: {
       styleBlocks: sources.styleBlocks,
       inlineStyleEls: sources.inlineStyleEls,
       linkedStylesheetsFetched: sources.fetchedUrls,
+      rendered: Boolean(computed),
     },
+    provenance: PROVENANCE,
     notes: [
-      'Static extraction from HTML + linked/inline CSS. Computed/cascaded colors and JS-injected styles require browser rendering and are not reflected here.',
+      computed
+        ? 'Roles, components and typography were read from the rendered page (source "computed"); tokens come from CSS custom properties with var() references resolved.'
+        : 'Not rendered: roles marked "inferred" are guesses from CSS variable names, and components and typography are empty. JS-injected styles are not reflected.',
+      ...(options.rawVariables ? [] : ['cssVariables (every custom property as found) is left out; pass brandingOptions.rawVariables:true to include it.']),
     ],
     warnings: warnings.length ? warnings : undefined,
   };