monomind 2.5.1 → 2.5.3

package/packages/@monomind/cli/.claude/skills/monodesign/scripts/detector/engines/static-html/detect-html.mjs

@@ -0,0 +1,253 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { GENERIC_FONTS, OVERUSED_FONTS } from '../../shared/constants.mjs';
+import {
+  checkSourceDesignSystem,
+  collectStaticDesignSystemFindings,
+  mergeDesignSystemFindings,
+} from '../../design-system.mjs';
+import { isFullPage } from '../../shared/page.mjs';
+import { applyInlineIgnores } from '../../shared/inline-ignores.mjs';
+import { finding } from '../../findings.mjs';
+import { profileFindings, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
+import {
+  checkElementBorders,
+  checkElementClippedOverflow,
+  checkElementColors,
+  checkElementGlow,
+  checkElementGptBorderShadow,
+  checkElementHeroEyebrow,
+  checkElementIconTile,
+  checkElementItalicSerif,
+  checkElementMotion,
+  checkElementOversizedH1,
+  checkElementQuality,
+  checkCreamPalette,
+  checkHtmlPatterns,
+  checkPageLayout,
+  checkPageQualityFromDoc,
+  checkRepeatedSectionKickersFromDoc,
+  checkElementImageDimensions,
+  checkElementSmallTouchTarget,
+  checkFocusVisible,
+  checkHoverOnlyAffordance,
+  checkDarkSchemeContrast,
+  resolveBackground,
+  resolveBorderRadiusPx,
+} from '../../rules/checks.mjs';
+import { filterByProviders } from '../../registry/antipatterns.mjs';
+import { detectText, runTextContentAnalyzers } from '../regex/detect-text.mjs';
+import {
+  StaticDocument,
+  buildStaticStyleMap,
+  buildStaticWindow,
+  collectStaticCssText,
+} from './css-cascade.mjs';
+
+function checkStaticPageTypography(document, window) {
+  const findings = [];
+  const fonts = new Set();
+  const overusedFound = new Set();
+  for (const el of document.querySelectorAll('p, h1, h2, h3, h4, h5, h6, li, td, th, dd, blockquote, figcaption, a, button, label, span, div')) {
+    const hasText = el.childNodes.some(n => n.nodeType === 3 && n.textContent.trim().length > 0);
+    if (!hasText) continue;
+    const ff = window.getComputedStyle(el).fontFamily || '';
+    const stack = ff.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
+    const primary = stack.find(f => f && !GENERIC_FONTS.has(f));
+    if (!primary) continue;
+    fonts.add(primary);
+    if (OVERUSED_FONTS.has(primary)) overusedFound.add(primary);
+  }
+  for (const font of overusedFound) {
+    findings.push({ id: 'overused-font', snippet: `Primary font: ${font}` });
+  }
+  if (fonts.size === 1 && document.querySelectorAll('*').length >= 20) {
+    findings.push({ id: 'single-font', snippet: `only font used is ${[...fonts][0]}` });
+  }
+  const sizes = new Set();
+  for (const el of document.querySelectorAll('h1, h2, h3, h4, h5, h6, p, span, a, li, td, th, label, button, div')) {
+    const fontSize = parseFloat(window.getComputedStyle(el).fontSize);
+    if (fontSize >= 8 && fontSize < 200) sizes.add(Math.round(fontSize * 10) / 10);
+  }
+  if (sizes.size >= 3) {
+    const sorted = [...sizes].sort((a, b) => a - b);
+    const ratio = sorted[sorted.length - 1] / sorted[0];
+    if (ratio < 2.0) {
+      findings.push({ id: 'flat-type-hierarchy', snippet: `Sizes: ${sorted.map(s => s + 'px').join(', ')} (ratio ${ratio.toFixed(1)}:1)` });
+    }
+  }
+  return findings;
+}
+
+function checkElementBrokenImage(el) {
+  const src = (el.getAttribute && el.getAttribute('src')) ?? el.attribs?.src;
+  // Missing src attribute entirely
+  if (src === undefined || src === null) {
+    return [{ id: 'broken-image', snippet: '<img> with no src attribute' }];
+  }
+  const trimmed = String(src).trim();
+  // Empty or placeholder-only src values
+  if (trimmed === '' || trimmed === '#') {
+    return [{ id: 'broken-image', snippet: `<img src="${src}">` }];
+  }
+  return [];
+}
+
+const STATIC_ELEMENT_RULES = [
+  { id: 'border-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementBorders(tag, style, null, resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window)) },
+  { id: 'color-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementColors(el, style, tag, window, customPropMap, false) },
+  { id: 'dark-glow', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementGlow(tag, style, resolveBackground(el.parentElement || el, window, customPropMap)) },
+  { id: 'motion-rules', selector: '*', run: (el, tag, style) => checkElementMotion(tag, style) },
+  { id: 'icon-tile-stack', selector: 'h1,h2,h3,h4,h5,h6', run: (el, tag, _style, window) => checkElementIconTile(el, tag, window) },
+  { id: 'italic-serif-display', selector: 'h1,h2', run: (el, tag, style) => checkElementItalicSerif(el, style, tag) },
+  { id: 'hero-eyebrow-chip', selector: 'h1', run: (el, tag, style, window, customPropMap) => checkElementHeroEyebrow(el, style, tag, window, customPropMap) },
+  { id: 'broken-image', selector: 'img', run: (el) => checkElementBrokenImage(el) },
+  { id: 'quality-rules', selector: '*', run: (el, tag, style, window) => checkElementQuality(el, style, tag, window) },
+  { id: 'oversized-h1', selector: 'h1', run: (el, tag, style, window) => checkElementOversizedH1(el, style, tag, window) },
+  { id: 'clipped-overflow-container', selector: '*', run: (el, tag, style, window) => checkElementClippedOverflow(el, style, tag, window) },
+  { id: 'gpt-thin-border-wide-shadow', selector: '*', run: (el, tag, style) => checkElementGptBorderShadow(el, style) },
+  { id: 'image-missing-dimensions', selector: 'img', run: (el, tag, style) => checkElementImageDimensions(el, style) },
+  { id: 'small-touch-target', selector: 'a,button,input,select,summary,[role=button],[role=link],[role=menuitem],[role=tab],[role=switch]', run: (el, tag, style) => checkElementSmallTouchTarget(el, style, tag) },
+];
+
+async function detectHtml(filePath, options = {}) {
+  const profile = options?.profile;
+  const html = profileStep(profile, {
+    engine: 'static-html',
+    phase: 'setup',
+    ruleId: 'read-html',
+    target: filePath,
+  }, () => fs.readFileSync(filePath, 'utf-8'));
+
+  let modules;
+  try {
+    modules = await profileStepAsync(profile, {
+      engine: 'static-html',
+      phase: 'setup',
+      ruleId: 'import-static-parser',
+      target: filePath,
+    }, async () => {
+      const [htmlparser2, cssSelect, csstree, domutils] = await Promise.all([
+        import('htmlparser2'),
+        import('css-select'),
+        import('css-tree'),
+        import('domutils'),
+      ]);
+      return {
+        parseDocument: htmlparser2.parseDocument,
+        selectAll: cssSelect.selectAll,
+        selectOne: cssSelect.selectOne,
+        is: cssSelect.is,
+        csstree,
+        domutils,
+      };
+    });
+  } catch {
+    return detectText(html, filePath, options);
+  }
+
+  const resolvedPath = path.resolve(filePath);
+  const fileDir = path.dirname(resolvedPath);
+  const root = profileStep(profile, {
+    engine: 'static-html',
+    phase: 'parse-html',
+    ruleId: 'parse-document',
+    target: filePath,
+  }, () => modules.parseDocument(html, { lowerCaseAttributeNames: false, lowerCaseTags: true }));
+
+  const cssText = collectStaticCssText(root, fileDir, profile, filePath, modules);
+  const document = new StaticDocument(root, modules);
+  buildStaticStyleMap(root, document, cssText, modules, profile, filePath);
+  const window = buildStaticWindow(document);
+
+  const customPropMap = null;
+
+  const findings = [];
+  const runElementCheck = (ruleId, callback) => profile
+    ? profileFindings(profile, { engine: 'static-html', phase: 'element', ruleId, target: filePath }, callback)
+    : callback();
+
+  const visitedByRule = new Map();
+  for (const rule of STATIC_ELEMENT_RULES) {
+    const elements = document.querySelectorAll(rule.selector);
+    visitedByRule.set(rule.id, elements.length);
+    for (const el of elements) {
+      const tag = el.tagName.toLowerCase();
+      const style = window.getComputedStyle(el);
+      for (const f of runElementCheck(rule.id, () => rule.run(el, tag, style, window, customPropMap))) {
+        findings.push(finding(f.id, filePath, f.snippet));
+      }
+    }
+  }
+
+  if (options?.designSystem) {
+    const sourceDesignFindings = profileFindings(profile, {
+      engine: 'static-html',
+      phase: 'source',
+      ruleId: 'design-system',
+      target: filePath,
+    }, () => checkSourceDesignSystem(html, filePath, { designSystem: options.designSystem }));
+    const staticDesignFindings = profileFindings(profile, {
+      engine: 'static-html',
+      phase: 'page',
+      ruleId: 'design-system',
+      target: filePath,
+    }, () => collectStaticDesignSystemFindings(document, window, filePath, options.designSystem));
+    findings.push(...mergeDesignSystemFindings(staticDesignFindings, sourceDesignFindings));
+  }
+
+  if (isFullPage(html)) {
+    const runPageCheck = (ruleId, callback) => profile
+      ? profileFindings(profile, { engine: 'static-html', phase: 'page', ruleId, target: filePath }, callback)
+      : callback();
+    for (const f of runPageCheck('typography-rules', () => checkStaticPageTypography(document, window))) {
+      findings.push(finding(f.id, filePath, f.snippet));
+    }
+    for (const f of runPageCheck('repeated-section-kickers', () => checkRepeatedSectionKickersFromDoc(document, window))) {
+      findings.push(finding(f.id, filePath, f.snippet));
+    }
+    for (const f of runPageCheck('layout-rules', () => checkPageLayout(document, window))) {
+      findings.push(finding(f.id, filePath, f.snippet));
+    }
+    for (const f of runPageCheck('cream-palette', () => checkCreamPalette(document, window))) {
+      findings.push(finding(f.id, filePath, f.snippet));
+    }
+    for (const f of runPageCheck('skipped-heading', () => checkPageQualityFromDoc(document))) {
+      findings.push(finding(f.id, filePath, f.snippet));
+    }
+    // Stylesheet-level accessibility rules operate on the concatenated CSS
+    // text (<style> blocks + linked sheets) — :hover / :focus-visible /
+    // prefers-color-scheme conditions can't be read off a resting element.
+    for (const f of runPageCheck('missing-focus-visible', () => checkFocusVisible(cssText))) {
+      findings.push(finding(f.id, filePath, f.snippet));
+    }
+    for (const f of runPageCheck('hover-only-affordance', () => checkHoverOnlyAffordance(cssText))) {
+      findings.push(finding(f.id, filePath, f.snippet));
+    }
+    for (const f of runPageCheck('dark-scheme-contrast-blindspot', () => checkDarkSchemeContrast(cssText))) {
+      findings.push(finding(f.id, filePath, f.snippet));
+    }
+    for (const f of runPageCheck('html-patterns', () => checkHtmlPatterns(html).filter(item =>
+      item.id !== 'bounce-easing' && item.id !== 'layout-transition'
+    ))) {
+      findings.push(finding(f.id, filePath, f.snippet));
+    }
+    // Text-content analyzers (em-dash overuse, marketing buzzwords,
+    // numbered section markers, aphoristic cadence) live in the regex
+    // engine. Call them from here so .html files get the same coverage
+    // as .css/.tsx files. These are scoped to text content only and
+    // don't overlap with static-html's element/page rules.
+    for (const f of runPageCheck('text-content', () => runTextContentAnalyzers(html, filePath, options))) {
+      findings.push(finding(f.antipattern, filePath, f.snippet));
+    }
+  }
+
+  const byProvider = filterByProviders(findings, options.providers);
+  // Static-HTML findings carry no line number, so only whole-file
+  // `monodesign-disable` directives apply here — exactly the standalone-document
+  // waiver this primitive targets. Bypassed by `--no-config` / `--no-inline-ignores`.
+  return options?.inlineIgnores === false ? byProvider : applyInlineIgnores(byProvider, html);
+}
+
+export { checkStaticPageTypography, STATIC_ELEMENT_RULES, detectHtml };

package/packages/@monomind/cli/.claude/skills/monodesign/scripts/detector/engines/visual/screenshot-contrast.mjs

@@ -0,0 +1,198 @@
+//
+// Visual-contrast pixel fallback. `page` is the driver page abstraction from
+// ../browser/drivers.mjs (a raw puppeteer Page also satisfies it): it only
+// needs `evaluate(fn, arg)` roundtrips and `screenshot({ encoding: 'base64',
+// clip, captureBeyondViewport })` returning a base64 PNG string. The logic is
+// driver-agnostic: hide the glyphs via CSS, screenshot the clip twice, and
+// diff the pixels in-page on a canvas. Both the monobrowse (CDP
+// Page.captureScreenshot + Runtime.evaluate) and puppeteer drivers support
+// this fully.
+function sanitizeScreenshotClip(clip, viewport) {
+  if (!clip) return null;
+  const x = Math.max(0, Math.floor(clip.x || 0));
+  const y = Math.max(0, Math.floor(clip.y || 0));
+  const width = Math.min(
+    Math.max(1, Math.ceil(clip.width || 0)),
+    Math.max(1, viewport?.width || 1600),
+  );
+  const height = Math.min(
+    Math.max(1, Math.ceil(clip.height || 0)),
+    320,
+  );
+  if (width < 1 || height < 1) return null;
+  return { x, y, width, height };
+}
+
+async function compareScreenshotContrast(page, beforeBase64, afterBase64, candidate) {
+  return page.evaluate(async ({ beforeBase64, afterBase64, candidate }) => {
+    const loadImage = (base64) => new Promise((resolve, reject) => {
+      const img = new Image();
+      img.onload = () => resolve(img);
+      img.onerror = () => reject(new Error('Could not decode contrast screenshot'));
+      img.src = `data:image/png;base64,${base64}`;
+    });
+    const [before, after] = await Promise.all([loadImage(beforeBase64), loadImage(afterBase64)]);
+    const width = Math.min(before.width, after.width);
+    const height = Math.min(before.height, after.height);
+    if (width < 1 || height < 1) return null;
+
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d', { willReadFrequently: true });
+    if (!ctx) return null;
+
+    ctx.drawImage(before, 0, 0, width, height);
+    const beforePixels = ctx.getImageData(0, 0, width, height).data;
+    ctx.clearRect(0, 0, width, height);
+    ctx.drawImage(after, 0, 0, width, height);
+    const afterPixels = ctx.getImageData(0, 0, width, height).data;
+
+    const luminance = ({ r, g, b }) => {
+      const convert = c => {
+        const v = c / 255;
+        return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+      };
+      return 0.2126 * convert(r) + 0.7152 * convert(g) + 0.0722 * convert(b);
+    };
+    const ratio = (a, b) => {
+      const l1 = luminance(a);
+      const l2 = luminance(b);
+      return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+    };
+
+    const cssTextColor = candidate.textColor && !candidate.preferRenderedForeground
+      ? {
+          r: candidate.textColor.r,
+          g: candidate.textColor.g,
+          b: candidate.textColor.b,
+        }
+      : null;
+    const ratios = [];
+    let glyphPixels = 0;
+    let strongestDelta = 0;
+    for (let i = 0; i < beforePixels.length; i += 4) {
+      const delta = Math.abs(beforePixels[i] - afterPixels[i])
+        + Math.abs(beforePixels[i + 1] - afterPixels[i + 1])
+        + Math.abs(beforePixels[i + 2] - afterPixels[i + 2])
+        + Math.abs(beforePixels[i + 3] - afterPixels[i + 3]);
+      strongestDelta = Math.max(strongestDelta, delta);
+      if (delta < 10) continue;
+      glyphPixels++;
+      const fg = cssTextColor || {
+        r: beforePixels[i],
+        g: beforePixels[i + 1],
+        b: beforePixels[i + 2],
+      };
+      const bg = {
+        r: afterPixels[i],
+        g: afterPixels[i + 1],
+        b: afterPixels[i + 2],
+      };
+      ratios.push(ratio(fg, bg));
+    }
+
+    if (ratios.length < 8) {
+      return {
+        glyphPixels,
+        strongestDelta,
+        worstRatio: null,
+        p10Ratio: null,
+        medianRatio: null,
+      };
+    }
+
+    ratios.sort((a, b) => a - b);
+    const pick = pct => ratios[Math.min(ratios.length - 1, Math.max(0, Math.floor((pct / 100) * ratios.length)))];
+    return {
+      glyphPixels,
+      strongestDelta,
+      worstRatio: ratios[0],
+      p10Ratio: pick(10),
+      medianRatio: pick(50),
+    };
+  }, { beforeBase64, afterBase64, candidate });
+}
+
+async function captureVisualContrastCandidate(page, candidate, viewport) {
+  const clip = sanitizeScreenshotClip(candidate.clip, viewport);
+  if (!clip) return null;
+
+  const beforeBase64 = await page.screenshot({
+    encoding: 'base64',
+    clip,
+    captureBeyondViewport: true,
+  });
+  const token = `monodesign-contrast-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const applied = await page.evaluate(({ selector, token, backgroundClipText }) => {
+    let el;
+    try {
+      el = document.querySelector(selector);
+    } catch {
+      return false;
+    }
+    if (!el) return false;
+    let style = document.getElementById('monodesign-visual-contrast-hide-style');
+    if (!style) {
+      style = document.createElement('style');
+      style.id = 'monodesign-visual-contrast-hide-style';
+      style.textContent = [
+        '[data-monodesign-visual-contrast-target] {',
+        '  color: transparent !important;',
+        '  -webkit-text-fill-color: transparent !important;',
+        '  text-shadow: none !important;',
+        '}',
+        '[data-monodesign-visual-contrast-target][data-monodesign-bgclip-text="true"] {',
+        '  background-image: none !important;',
+        '}',
+      ].join('\n');
+      document.head.appendChild(style);
+    }
+    el.setAttribute('data-monodesign-visual-contrast-target', token);
+    if (backgroundClipText) el.setAttribute('data-monodesign-bgclip-text', 'true');
+    return true;
+  }, {
+    selector: candidate.selector,
+    token,
+    backgroundClipText: candidate.backgroundClipText,
+  });
+  if (!applied) return null;
+
+  let afterBase64;
+  try {
+    afterBase64 = await page.screenshot({
+      encoding: 'base64',
+      clip,
+      captureBeyondViewport: true,
+    });
+  } finally {
+    await page.evaluate(({ selector }) => {
+      try {
+        const el = document.querySelector(selector);
+        if (el) {
+          el.removeAttribute('data-monodesign-visual-contrast-target');
+          el.removeAttribute('data-monodesign-bgclip-text');
+        }
+      } catch {
+        // Ignore invalid or stale selectors during cleanup.
+      }
+    }, { selector: candidate.selector }).catch(() => {});
+  }
+
+  const metrics = await compareScreenshotContrast(page, beforeBase64, afterBase64, candidate);
+  if (!metrics || !Number.isFinite(metrics.p10Ratio) || metrics.glyphPixels < 8) return null;
+  const measuredRatio = metrics.p10Ratio;
+  if (measuredRatio >= candidate.threshold) return null;
+  const textLabel = candidate.text ? ` "${candidate.text}"` : '';
+  const reasonLabel = (candidate.reasons || []).slice(0, 3).join(', ') || 'visual background';
+  return {
+    id: 'low-contrast',
+    snippet: `pixel contrast ${measuredRatio.toFixed(1)}:1 median ${metrics.medianRatio.toFixed(1)}:1 (need ${candidate.threshold}:1) on ${reasonLabel}${textLabel}`,
+  };
+}
+
+export {
+  sanitizeScreenshotClip,
+  compareScreenshotContrast,
+  captureVisualContrastCandidate,
+};

package/packages/@monomind/cli/.claude/skills/monodesign/scripts/detector/findings.mjs

@@ -0,0 +1,12 @@
+import { getAntipattern } from './registry/antipatterns.mjs';
+
+function getAP(id) {
+  return getAntipattern(id);
+}
+
+function finding(id, filePath, snippet, line = 0) {
+  const ap = getAP(id);
+  return { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', file: filePath, line, snippet };
+}
+
+export { getAP, finding };

package/packages/@monomind/cli/.claude/skills/monodesign/scripts/detector/fix/css-regions.mjs

@@ -0,0 +1,181 @@
+/**
+ * CSS region extraction and declaration scanning for the auto-fix engine.
+ *
+ * Fixers never parse a full DOM — they operate on the raw source text of the
+ * "CSS-shaped" regions of a file:
+ *   - whole file for .css/.scss/.sass/.less
+ *   - <style> blocks and style="" attributes for HTML-family files
+ *   - styled-components / emotion template literals for JS/TS files
+ *
+ * All offsets returned here are absolute within the original file content, so
+ * edits computed against a region can be applied directly to the file.
+ */
+
+const CSS_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
+const HTML_FAMILY_EXTENSIONS = new Set(['.html', '.htm', '.vue', '.svelte', '.astro']);
+const JS_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs']);
+
+/**
+ * A region of file content that can be scanned as CSS declarations.
+ * kind:
+ *   'css'        — full stylesheet syntax (selectors + blocks)
+ *   'style-attr' — a bare declaration list from a style="" attribute;
+ *                  selectorHint carries the owning tag name
+ */
+function extractCssRegions(content, ext) {
+  ext = (ext || '').toLowerCase();
+  if (CSS_EXTENSIONS.has(ext)) {
+    return [{ start: 0, end: content.length, text: content, kind: 'css', selectorHint: null }];
+  }
+
+  const regions = [];
+  if (HTML_FAMILY_EXTENSIONS.has(ext)) {
+    const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+    let m;
+    while ((m = styleBlockRe.exec(content)) !== null) {
+      const start = m.index + m[0].indexOf(m[1]);
+      regions.push({ start, end: start + m[1].length, text: m[1], kind: 'css', selectorHint: null });
+    }
+    const styleAttrRe = /<([a-zA-Z][\w-]*)\b[^>]*?\sstyle\s*=\s*("([^"]*)"|'([^']*)')/gi;
+    while ((m = styleAttrRe.exec(content)) !== null) {
+      const value = m[3] !== undefined ? m[3] : m[4];
+      if (!value) continue;
+      const start = m.index + m[0].length - value.length - 1; // inside the closing quote
+      regions.push({
+        start,
+        end: start + value.length,
+        text: value,
+        kind: 'style-attr',
+        selectorHint: m[1].toLowerCase(),
+      });
+    }
+    return regions;
+  }
+
+  if (JS_EXTENSIONS.has(ext)) {
+    const cssInJsRe = /(?:styled(?:\.\w+|\([^)]+\))|css)\s*`([\s\S]*?)`/g;
+    let m;
+    while ((m = cssInJsRe.exec(content)) !== null) {
+      const start = m.index + m[0].indexOf('`') + 1;
+      regions.push({ start, end: start + m[1].length, text: m[1], kind: 'css', selectorHint: null });
+    }
+    return regions;
+  }
+
+  return regions;
+}
+
+/**
+ * Find every `prop: value` declaration in a CSS-shaped text. Returns local
+ * offsets (relative to the given text):
+ *   { declStart, valueStart, valueEnd, value, terminator }
+ * `value` is the raw trimmed value text (may include !important).
+ * `terminator` is the index just past the trailing `;` when present,
+ * otherwise valueEnd.
+ */
+function findDeclarations(text, prop) {
+  const re = new RegExp(`(^|[{;])(\\s*)(${prop})\\s*:\\s*([^;{}]*)`, 'gi');
+  const results = [];
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const declStart = m.index + m[1].length + m[2].length;
+    const rawValue = m[4];
+    const trimmed = rawValue.replace(/\s+$/, '');
+    const valueStart = m.index + m[0].length - rawValue.length;
+    const valueEnd = valueStart + trimmed.length;
+    const terminator = text[m.index + m[0].length] === ';'
+      ? m.index + m[0].length + 1
+      : valueEnd;
+    results.push({ declStart, valueStart, valueEnd, value: trimmed.trim(), terminator });
+  }
+  return results;
+}
+
+/**
+ * The enclosing `{ ... }` block for a declaration at `index`, with its
+ * selector text. For bare declaration lists (style attributes) there is no
+ * block — the whole text is the body and selector is null.
+ */
+function declBlockInfo(text, index) {
+  let i = index - 1;
+  let depth = 0;
+  while (i >= 0) {
+    const ch = text[i];
+    if (ch === '}') depth++;
+    else if (ch === '{') {
+      if (depth === 0) break;
+      depth--;
+    }
+    i--;
+  }
+  if (i < 0) {
+    return { bodyStart: 0, bodyEnd: text.length, body: text, selector: null };
+  }
+  const braceIdx = i;
+  let s = braceIdx - 1;
+  while (s >= 0 && !'};{'.includes(text[s])) s--;
+  const selector = text.slice(s + 1, braceIdx).trim();
+  let j = braceIdx + 1;
+  let d = 0;
+  while (j < text.length) {
+    const ch = text[j];
+    if (ch === '{') d++;
+    else if (ch === '}') {
+      if (d === 0) break;
+      d--;
+    }
+    j++;
+  }
+  return { bodyStart: braceIdx + 1, bodyEnd: j, body: text.slice(braceIdx + 1, j), selector };
+}
+
+/** Parse a single CSS length/number value, tolerating !important. */
+function parseCssValue(raw) {
+  const important = /!\s*important/i.test(raw);
+  const cleaned = raw.replace(/!\s*important/i, '').trim();
+  const m = cleaned.match(/^(-?(?:\d+\.?\d*|\.\d+))([a-z%]*)$/i);
+  if (!m) return null;
+  return { num: parseFloat(m[1]), unit: (m[2] || '').toLowerCase(), important };
+}
+
+/** Resolve a block's font-size to px when statically computable, else null. */
+function blockFontSizePx(body) {
+  const decls = findDeclarations(body, 'font-size');
+  if (decls.length === 0) return null;
+  const parsed = parseCssValue(decls[decls.length - 1].value);
+  if (!parsed) return null;
+  if (parsed.unit === 'px') return parsed.num;
+  if (parsed.unit === 'rem') return parsed.num * 16;
+  return null;
+}
+
+/** Split a CSS value list on top-level commas (paren-aware, for cubic-bezier). */
+function splitTopLevel(value) {
+  const parts = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of value) {
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    if (ch === ',' && depth === 0) {
+      parts.push(current.trim());
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+
+export {
+  CSS_EXTENSIONS,
+  HTML_FAMILY_EXTENSIONS,
+  JS_EXTENSIONS,
+  extractCssRegions,
+  findDeclarations,
+  declBlockInfo,
+  parseCssValue,
+  blockFontSizePx,
+  splitTopLevel,
+};