meno-core 1.1.3 → 1.1.4

package/lib/server/cssAudit.ts

@@ -0,0 +1,815 @@
+/**
+ * CSS Audit — ownership map for a monolithic (e.g. Webflow-exported) stylesheet.
+ *
+ * This is the read-only "first step" of de-mirroring: it never rewrites or moves a byte. It
+ * parses a stylesheet into an AST, re-unites every selector with the responsive variants that a
+ * Webflow export pools at the end of the file, cross-references each class against the project's
+ * page DOM, and proposes how the rules would split into buckets:
+ *
+ *   - base         — element/reset rules with no class (normalize + bare typography)
+ *   - vendor       — Webflow framework classes (`.w-*`)
+ *   - webflow-auto — Webflow's auto-generated element wrappers (`div-block-2`, `text-block`, `heading-5`)
+ *   - shared       — cross-cutting design-system classes (utilities, state/combo, used across pages)
+ *   - sections     — everything else, grouped by class-name prefix (team-*, home-*, case-*, …); tiny
+ *                    or typo prefixes fold into the nearest real section or a `misc` catch-all
+ *
+ * It also flags the cases that make a naive split unsafe: selectors that straddle two section
+ * buckets, the "fuzzy middle" classes near the shared/local threshold, dead classes, and classes
+ * used in pages but absent from this sheet. The output is data to decide from, not a change.
+ *
+ * Pure and dependency-light (css-tree only) so it is unit-testable and reusable across every
+ * Webflow-style import — no filesystem or HTTP here; the route layer feeds it `css` + `pages`.
+ */
+
+import * as csstree from 'css-tree';
+
+/** Classes used on a single page (the page's DOM, flattened to class tokens). */
+export interface PageClassUsage {
+  path: string;
+  classes: string[];
+}
+
+export interface CssAuditOptions {
+  /**
+   * Minimum number of pages a class must appear on to be proposed as "shared" rather than
+   * section-local. Defaults to `max(2, ceil(pageCount / 2))`.
+   */
+  sharedMinPages?: number;
+  /**
+   * Regex sources (matched against the class name) that force a class into the shared bucket
+   * regardless of page usage — for spacing/layout utilities that are clearly cross-cutting even
+   * when they happen to be used on few pages. Defaults to {@link DEFAULT_UTILITY_HINTS}.
+   */
+  utilityHints?: string[];
+  /**
+   * Regex sources matched against the class name that route Webflow's auto-generated element
+   * wrappers (`div-block-2`, `text-block`, `heading-5`) into the `webflow-auto` bucket instead of
+   * letting them masquerade as sections. Defaults to {@link DEFAULT_WEBFLOW_AUTO}.
+   */
+  webflowAuto?: string[];
+  /**
+   * A section-prefix bucket with fewer than this many classes is not worth its own file: it folds
+   * into the nearest kept bucket (typo) or the misc catch-all. Default 3. Set to 1 to disable.
+   */
+  minSectionClasses?: number;
+  /** Name of the catch-all bucket that small/orphan section classes fold into. Default `'misc'`. */
+  miscBucketName?: string;
+  /**
+   * Fold a small section prefix into a near-identical kept prefix (designer typos like
+   * `testiimonial` → `testimonial`) instead of dumping it in misc. Default true.
+   */
+  mergeTypos?: boolean;
+  /** Cap on how many sample selectors to keep per class. Default 5. */
+  selectorSampleLimit?: number;
+  /** Cap on how many entries to keep in each `flags` list. Default 200. */
+  flagLimit?: number;
+}
+
+/**
+ * Name patterns treated as shared even at low page usage — utilities, state/combo classes, colors,
+ * and cross-cutting UI bits that a Webflow designer scattered without a section prefix. Matched
+ * (unanchored regex) against the whole class name, so `arrow` also catches `left-arrow-team`.
+ * Kept deliberately conservative to avoid folding real component classes into shared.
+ */
+export const DEFAULT_UTILITY_HINTS: string[] = [
+  // Spacing / sizing
+  '^(margin|padding|gap)(-|$)',
+  '^no-(padding|margin|overflow)',
+  '(^|-)auto-margin$',
+  '^(max|min)-(w|h|width|height)',
+  '^(w|h)-[0-9]',
+  '^size-[0-9]',
+  '^(small|medium|large)(-|$)',
+  // Layout / display
+  '^align(-|$)',
+  '^justify(-|$)',
+  '^(grid|col|flex)-',
+  '^container(-|$)',
+  '(^|-)(overflow|opacity|relative|absolute|sticky|inline|centered)(-|$)',
+  '^(hide|show|hidden|visible)$',
+  // State / Webflow combo classes
+  '^is--?',
+  '^has--?',
+  '^on-h[0-9]',
+  '^type-[0-9]+$',
+  '(^|-)active$',
+  // Colors
+  '(^|-)(white|black|dark|light|primary|secondary|grey|gray)(-|$)',
+  // Cross-cutting UI
+  '(^|-)arrow',
+  // Relume / newer-Webflow utility families (text-size-*, heading-style-*, spacer-*, max-width-*)
+  '^text-(size|align|color|weight|style)',
+  '^heading-style',
+  '^(spacer|max-width|background-color)(-|$)',
+];
+
+/**
+ * Webflow's auto-generated element wrappers — not real components, just default class names it
+ * assigns to blocks/headings/images (often with a numeric suffix). Routed to their own bucket so
+ * they don't masquerade as sections. Unambiguous wrappers match bare or numbered; the ambiguous
+ * element words (heading/paragraph/image/…) match ONLY when numbered, since a bare `.heading` or
+ * `.image` is usually a real design-system class.
+ */
+export const DEFAULT_WEBFLOW_AUTO: string[] = [
+  '^(div-block|text-block|link-block|bold-text|block-quote|rich-text-block|html-embed)(-\\d+)?$',
+  '^(heading|paragraph|image|list|list-item|figure|grid|columns?|field-label|text-field)-\\d+$',
+];
+
+export type ClassCategory = 'vendor' | 'webflow-auto' | 'shared' | 'section';
+
+export interface BucketStat {
+  classes: number;
+  rules: number;
+  declarations: number;
+  approxBytes: number;
+}
+
+export interface ClassInfo {
+  name: string;
+  category: ClassCategory;
+  /** `'vendor'`, `'shared'`, or the section prefix the class would live under. */
+  proposedBucket: string;
+  ruleCount: number;
+  declarations: number;
+  /** Distinct `@media` preludes this class appears under (`''` = base, no media). */
+  breakpoints: string[];
+  pagesUsedIn: number;
+  /** Up to `selectorSampleLimit` selectors that mention this class. */
+  selectors: string[];
+  /** True when the class is never the lone subject of a rule — it only modifies/co-occurs. */
+  compoundOnly: boolean;
+}
+
+export interface CrossBoundaryFlag {
+  selector: string;
+  media: string | null;
+  classes: string[];
+  /** The distinct section buckets this one selector touches. */
+  buckets: string[];
+}
+
+/** A small/typo section prefix that was folded away during refinement. */
+export interface FoldedSection {
+  /** The original prefix bucket. */
+  from: string;
+  /** Where its classes ended up — a kept prefix (typo) or the misc bucket (small). */
+  into: string;
+  classes: number;
+  reason: 'small' | 'typo';
+}
+
+export interface CssAuditReport {
+  source: {
+    bytes: number;
+    rules: number;
+    selectors: number;
+    declarations: number;
+    pageCount: number;
+    sharedMinPages: number;
+  };
+  /** Distinct `@media` preludes, in first-seen (source) order. */
+  breakpoints: string[];
+  buckets: {
+    base: BucketStat;
+    vendor: BucketStat;
+    /** Webflow auto-generated element wrappers (`div-block-*`, `text-block`, `heading-N`). */
+    webflowAuto: BucketStat;
+    shared: BucketStat;
+    sections: Record<string, BucketStat>;
+  };
+  classes: ClassInfo[];
+  flags: {
+    crossBoundarySelectors: CrossBoundaryFlag[];
+    /** Section classes used on 2..sharedMinPages-1 pages — the borderline shared/local calls. */
+    fuzzyMiddle: string[];
+    /** Classes defined in the sheet but used on 0 pages (vendor excluded). */
+    deadClasses: string[];
+    /** Class tokens used on pages but absent from this sheet (Meno utilities, other sheets). */
+    pageOnlyClasses: string[];
+    /** Section prefixes folded into a kept bucket or misc during refinement (transparency). */
+    foldedSections: FoldedSection[];
+  };
+}
+
+const CLASS_TOKEN_RE = /\.(-?[_a-zA-Z][\w-]*)/g;
+// Strips the inner argument of functional pseudos so their contents don't fool combinator splitting.
+const FUNCTIONAL_PSEUDO_RE = /:(not|is|where|has|matches)\([^()]*\)/gi;
+
+function emptyBucket(): BucketStat {
+  return { classes: 0, rules: 0, declarations: 0, approxBytes: 0 };
+}
+
+function classTokens(selector: string): string[] {
+  const out: string[] = [];
+  let m: RegExpExecArray | null;
+  CLASS_TOKEN_RE.lastIndex = 0;
+  // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+  while ((m = CLASS_TOKEN_RE.exec(selector)) !== null) {
+    if (m[1]) out.push(m[1]);
+  }
+  return out;
+}
+
+/**
+ * The section prefix a class name would bucket under: its first dash/underscore segment, with any
+ * trailing digits stripped. The digit-strip collapses Webflow's newer numeric-suffixed section IDs
+ * (`header76`, `cta39`, `blog38`, `layout225`, `testimonial26`) onto their real prefix so all the
+ * numbered variants land in one bucket instead of fragmenting into dozens.
+ */
+export function sectionPrefix(name: string): string {
+  const seg = name.split(/[-_]/)[0] ?? name;
+  const stripped = seg.replace(/\d+$/, '');
+  return stripped.length > 0 ? stripped : seg;
+}
+
+/** Length of the shared leading run of characters between two strings. */
+function commonPrefixLength(a: string, b: string): number {
+  const max = Math.min(a.length, b.length);
+  let i = 0;
+  while (i < max && a[i] === b[i]) i++;
+  return i;
+}
+
+/** Levenshtein edit distance between two short strings. */
+function editDistance(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  let curr = new Array<number>(n + 1).fill(0);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n] ?? 0;
+}
+
+/**
+ * Find the kept section prefix a likely-typo prefix should merge into (e.g. `testiimonial` →
+ * `testimonial`), or null if none is close enough. Deliberately conservative — a merge requires a
+ * SINGLE edit (distance 1), a length gap of ≤1, and ≥2 shared leading chars. That keeps real
+ * single-letter typos (`teem`↔`team`, `homve`↔`home`, `careers`↔`career`, `meetup`↔`meetap`) while
+ * rejecting the distance-2 / low-overlap false pairs a looser rule produced across real sites
+ * (`content`↔`contact`, `footer`↔`filter`, `bottom`↔`button`, `next`↔`text`, `book`↔`ebook`). Rare
+ * two-edit typos (`testimonail`) simply fall to misc instead of merging into the wrong section.
+ * On ties, the candidate sharing the longest leading run wins (deterministic).
+ */
+function nearestKeptPrefix(prefix: string, kept: Iterable<string>): string | null {
+  let best: string | null = null;
+  let bestShared = -1;
+  for (const candidate of kept) {
+    if (Math.abs(candidate.length - prefix.length) > 1) continue;
+    const shared = commonPrefixLength(prefix, candidate);
+    if (shared < 2) continue;
+    if (editDistance(prefix, candidate) !== 1) continue;
+    if (shared > bestShared) {
+      bestShared = shared;
+      best = candidate;
+    }
+  }
+  return best;
+}
+
+interface SelectorShape {
+  allClasses: string[];
+  subjectClasses: string[];
+  compound: boolean;
+}
+
+/**
+ * Split a selector into its compound segments to find the *subject* (rightmost) classes — the
+ * element the rule actually styles — versus classes that merely scope it (`.scope .subject`).
+ */
+function analyzeSelector(selector: string): SelectorShape {
+  const cleaned = selector.replace(FUNCTIONAL_PSEUDO_RE, ' ');
+  const segments = cleaned.split(/\s*[>+~]\s*|\s+/).filter((s) => s.trim().length > 0);
+  const subject = segments[segments.length - 1] ?? cleaned;
+  const subjectClasses = classTokens(subject);
+  const allClasses = classTokens(selector);
+  const compound = segments.length > 1 || subjectClasses.length > 1;
+  return { allClasses, subjectClasses, compound };
+}
+
+interface RuleRecord {
+  media: string | null;
+  bytes: number;
+  declarations: number;
+  classes: string[];
+  subjectClasses: string[];
+}
+
+interface ClassAccum {
+  name: string;
+  ruleCount: number;
+  declarations: number;
+  breakpoints: Set<string>;
+  selectors: string[];
+  ownsSimple: boolean;
+}
+
+function countDeclarations(block: csstree.CssNode | null | undefined): number {
+  let count = 0;
+  if (block && block.type === 'Block') {
+    block.children.forEach((child) => {
+      if (child.type === 'Declaration') count++;
+    });
+  }
+  return count;
+}
+
+/** One selector's worth of a class rule, flattened out of the stylesheet. */
+export interface ExtractedRule {
+  /** The single selector this entry represents (one entry per selector in a list). */
+  selector: string;
+  /** The `@media` prelude this rule sits under (`null` = base, no media). */
+  media: string | null;
+  /** All class tokens mentioned anywhere in the selector. */
+  classes: string[];
+  /** The rightmost (subject) compound's class tokens — the element actually styled. */
+  subjectClasses: string[];
+  /** Number of declarations in the rule's block. */
+  declarations: number;
+  /** Approx bytes attributed to this selector (whole-rule bytes / #class-selectors). */
+  bytes: number;
+  /** True when the selector is compound (`.a.b`) or a descendant chain (`.a .b`). */
+  compound: boolean;
+}
+
+/**
+ * Flatten a stylesheet to a per-selector list of its CLASS rules (rules whose selector
+ * mentions at least one class), threading `@media` context so responsive variants keep
+ * their condition. Element-only selectors and at-rule inner blocks (`@keyframes` /
+ * `@font-face`) are omitted — they belong to the always-loaded global sheet, not to any
+ * component.
+ *
+ * This is the de-mirror MIGRATION view (vs {@link auditStylesheet}'s aggregate audit): the
+ * planner attributes each rule to an owner, and the eventual writer matches rules back to
+ * source by `(selector, media)`. Reuses the same selector analysis as the audit.
+ */
+export function extractRules(css: string): ExtractedRule[] {
+  const ast = csstree.parse(css, { parseValue: false, parseCustomProperty: false });
+  const out: ExtractedRule[] = [];
+
+  const visit = (container: csstree.CssNode, media: string | null, insideSkippedAtrule: boolean): void => {
+    const children =
+      'children' in container ? (container as { children: csstree.List<csstree.CssNode> }).children : null;
+    if (!children) return;
+
+    children.forEach((node) => {
+      if (node.type === 'Atrule') {
+        const name = node.name.toLowerCase();
+        if (name === 'media') {
+          const prelude = node.prelude ? csstree.generate(node.prelude) : '';
+          if (node.block) visit(node.block, prelude, false);
+        } else if (name === 'supports') {
+          if (node.block) visit(node.block, media, false);
+        } else if (node.block) {
+          visit(node.block, media, true); // @keyframes/@font-face — skip inner rules
+        }
+        return;
+      }
+
+      if (node.type !== 'Rule' || insideSkippedAtrule) return;
+      if (node.prelude?.type !== 'SelectorList') return;
+
+      const decls = countDeclarations(node.block);
+      const ruleBytes = csstree.generate(node).length;
+
+      // Collect only the class-bearing selectors, so the rule's bytes split across them.
+      const classSelectors: { text: string; shape: SelectorShape }[] = [];
+      node.prelude.children.forEach((selectorNode) => {
+        const text = csstree.generate(selectorNode);
+        const shape = analyzeSelector(text);
+        if (shape.allClasses.length > 0) classSelectors.push({ text, shape });
+      });
+      if (classSelectors.length === 0) return;
+
+      const perBytes = Math.max(1, Math.round(ruleBytes / classSelectors.length));
+      for (const { text, shape } of classSelectors) {
+        out.push({
+          selector: text,
+          media,
+          classes: shape.allClasses,
+          subjectClasses: shape.subjectClasses,
+          declarations: decls,
+          bytes: perBytes,
+          compound: shape.compound,
+        });
+      }
+    });
+  };
+
+  visit(ast, null, false);
+  return out;
+}
+
+/**
+ * Audit a stylesheet against project page usage and return the ownership map.
+ */
+export function auditStylesheet(input: {
+  css: string;
+  pages: PageClassUsage[];
+  options?: CssAuditOptions;
+}): CssAuditReport {
+  const { css, pages, options = {} } = input;
+  const selectorSampleLimit = options.selectorSampleLimit ?? 5;
+  const flagLimit = options.flagLimit ?? 200;
+  const minSectionClasses = options.minSectionClasses ?? 3;
+  const miscBucketName = options.miscBucketName ?? 'misc';
+  const mergeTypos = options.mergeTypos ?? true;
+  const utilityHints = (options.utilityHints ?? DEFAULT_UTILITY_HINTS).map((s) => new RegExp(s));
+  const webflowAutoPatterns = (options.webflowAuto ?? DEFAULT_WEBFLOW_AUTO).map((s) => new RegExp(s));
+
+  const pageCount = pages.length;
+  const sharedMinPages = options.sharedMinPages ?? Math.max(2, Math.ceil(pageCount / 2));
+
+  // Page usage: class -> number of pages it appears on.
+  const pageUseCount = new Map<string, number>();
+  for (const page of pages) {
+    for (const cls of new Set(page.classes)) {
+      pageUseCount.set(cls, (pageUseCount.get(cls) ?? 0) + 1);
+    }
+  }
+
+  const ast = csstree.parse(css, { parseValue: false, parseCustomProperty: false });
+
+  const classMap = new Map<string, ClassAccum>();
+  const rules: RuleRecord[] = [];
+  const breakpoints: string[] = [];
+  const seenMedia = new Set<string>();
+  const base = emptyBucket();
+  let totalRules = 0;
+  let totalSelectors = 0;
+  let totalDeclarations = 0;
+
+  const accumFor = (name: string): ClassAccum => {
+    let a = classMap.get(name);
+    if (!a) {
+      a = { name, ruleCount: 0, declarations: 0, breakpoints: new Set(), selectors: [], ownsSimple: false };
+      classMap.set(name, a);
+    }
+    return a;
+  };
+
+  // Recurse the AST, threading the active @media prelude so responsive variants land on the same
+  // class as their base rule (Webflow pools these at the end of the file).
+  const visit = (container: csstree.CssNode, media: string | null, insideSkippedAtrule: boolean): void => {
+    const children =
+      'children' in container ? (container as { children: csstree.List<csstree.CssNode> }).children : null;
+    if (!children) return;
+
+    children.forEach((node) => {
+      if (node.type === 'Atrule') {
+        const name = node.name.toLowerCase();
+        if (name === 'media') {
+          const prelude = node.prelude ? csstree.generate(node.prelude) : '';
+          if (!seenMedia.has(prelude)) {
+            seenMedia.add(prelude);
+            breakpoints.push(prelude);
+          }
+          if (node.block) visit(node.block, prelude, false);
+        } else if (name === 'supports') {
+          if (node.block) visit(node.block, media, false);
+        } else if (node.block) {
+          // @keyframes / @font-face etc. — their inner blocks aren't class rules; skip rules within.
+          visit(node.block, media, true);
+        }
+        return;
+      }
+
+      if (node.type !== 'Rule' || insideSkippedAtrule) return;
+      if (node.prelude?.type !== 'SelectorList') return;
+
+      const ruleBytes = csstree.generate(node).length;
+      const decls = countDeclarations(node.block);
+      totalDeclarations += decls;
+      totalRules += 1;
+
+      const ruleAllClasses = new Set<string>();
+      const ruleSubjectClasses = new Set<string>();
+      let hasAnyClass = false;
+
+      node.prelude.children.forEach((selectorNode) => {
+        totalSelectors += 1;
+        const selectorText = csstree.generate(selectorNode);
+        const shape = analyzeSelector(selectorText);
+        if (shape.allClasses.length === 0) return; // element-only selector contributes to base below
+
+        hasAnyClass = true;
+        for (const c of shape.allClasses) ruleAllClasses.add(c);
+        for (const c of shape.subjectClasses) ruleSubjectClasses.add(c);
+
+        const subjectSet = new Set(shape.subjectClasses);
+        for (const cls of shape.allClasses) {
+          const a = accumFor(cls);
+          a.ruleCount += 1;
+          a.declarations += decls;
+          a.breakpoints.add(media ?? '');
+          if (a.selectors.length < selectorSampleLimit && !a.selectors.includes(selectorText)) {
+            a.selectors.push(selectorText);
+          }
+          // The class "owns" a simple rule when it is the sole class of the subject segment.
+          if (subjectSet.size === 1 && subjectSet.has(cls)) a.ownsSimple = true;
+        }
+      });
+
+      if (!hasAnyClass) {
+        // Element/reset/typography rule — base bucket.
+        base.rules += 1;
+        base.declarations += decls;
+        base.approxBytes += ruleBytes;
+        return;
+      }
+
+      rules.push({
+        media,
+        bytes: ruleBytes,
+        declarations: decls,
+        classes: [...ruleAllClasses],
+        subjectClasses: [...ruleSubjectClasses],
+      });
+    });
+  };
+
+  visit(ast, null, false);
+
+  // ---- Classify, then refine the section buckets ----------------------------------------------
+  // Phase 1 — preliminary classification: vendor (`.w-*`) / shared (utility hint or cross-page
+  // usage) / section (by name prefix). Tally section-bucket sizes for the refinement pass.
+  interface Prelim {
+    category: ClassCategory;
+    bucket: string;
+    pagesUsedIn: number;
+    accum: ClassAccum;
+  }
+  const prelim = new Map<string, Prelim>();
+  const sectionSizes = new Map<string, number>();
+  for (const a of classMap.values()) {
+    const pagesUsedIn = pageUseCount.get(a.name) ?? 0;
+    let category: ClassCategory;
+    let bucket: string;
+    if (/^w-/.test(a.name)) {
+      category = 'vendor';
+      bucket = 'vendor';
+    } else if (webflowAutoPatterns.some((re) => re.test(a.name))) {
+      category = 'webflow-auto';
+      bucket = 'webflow-auto';
+    } else if (utilityHints.some((re) => re.test(a.name)) || pagesUsedIn >= sharedMinPages) {
+      category = 'shared';
+      bucket = 'shared';
+    } else {
+      category = 'section';
+      bucket = sectionPrefix(a.name);
+      sectionSizes.set(bucket, (sectionSizes.get(bucket) ?? 0) + 1);
+    }
+    prelim.set(a.name, { category, bucket, pagesUsedIn, accum: a });
+  }
+
+  // Phase 2 — refine: a section prefix with >= minSectionClasses is "kept". Each smaller prefix
+  // folds into the nearest kept prefix (typo) or the misc catch-all (small). This is what collapses
+  // the long tail of singleton/typo buckets into the dozen-or-so real sections.
+  const keptSections = new Set<string>();
+  for (const [prefix, count] of sectionSizes) {
+    if (count >= minSectionClasses) keptSections.add(prefix);
+  }
+  const sectionRemap = new Map<string, { bucket: string; reason: 'small' | 'typo' }>();
+  for (const [prefix, count] of sectionSizes) {
+    if (keptSections.has(prefix) || count === 0) continue;
+    const near = mergeTypos && prefix.length >= 4 ? nearestKeptPrefix(prefix, keptSections) : null;
+    sectionRemap.set(prefix, near ? { bucket: near, reason: 'typo' } : { bucket: miscBucketName, reason: 'small' });
+  }
+
+  // Phase 3 — finalize per-class classification, applying the remap and recording what folded.
+  const foldedAgg = new Map<string, { from: string; into: string; reason: 'small' | 'typo'; classes: number }>();
+  const classified = new Map<string, { category: ClassCategory; bucket: string }>();
+  const classes: ClassInfo[] = [];
+  for (const [name, p] of prelim) {
+    let bucket = p.bucket;
+    if (p.category === 'section') {
+      const remap = sectionRemap.get(p.bucket);
+      if (remap) {
+        bucket = remap.bucket;
+        const key = `${p.bucket}→${remap.bucket}`;
+        const agg = foldedAgg.get(key) ?? { from: p.bucket, into: remap.bucket, reason: remap.reason, classes: 0 };
+        agg.classes += 1;
+        foldedAgg.set(key, agg);
+      }
+    }
+    classified.set(name, { category: p.category, bucket });
+    classes.push({
+      name,
+      category: p.category,
+      proposedBucket: bucket,
+      ruleCount: p.accum.ruleCount,
+      declarations: p.accum.declarations,
+      breakpoints: [...p.accum.breakpoints].sort(),
+      pagesUsedIn: p.pagesUsedIn,
+      selectors: p.accum.selectors,
+      compoundOnly: !p.accum.ownsSimple,
+    });
+  }
+  classes.sort((x, y) => y.declarations - x.declarations || x.name.localeCompare(y.name));
+
+  const foldedSections: FoldedSection[] = [...foldedAgg.values()]
+    .map(({ from, into, classes: c, reason }) => ({ from, into, classes: c, reason }))
+    .sort((a, b) => b.classes - a.classes || a.from.localeCompare(b.from));
+
+  // Bucket byte/rule accounting: assign each rule to a single owner bucket (section > shared >
+  // vendor), and flag rules whose classes straddle two or more distinct section buckets.
+  const vendor = emptyBucket();
+  const webflowAuto = emptyBucket();
+  const shared = emptyBucket();
+  const sections: Record<string, BucketStat> = {};
+  const crossBoundary: CrossBoundaryFlag[] = [];
+
+  const bucketStat = (bucket: string): BucketStat => {
+    if (bucket === 'vendor') return vendor;
+    if (bucket === 'webflow-auto') return webflowAuto;
+    if (bucket === 'shared') return shared;
+    let stat = sections[bucket];
+    if (!stat) {
+      stat = emptyBucket();
+      sections[bucket] = stat;
+    }
+    return stat;
+  };
+
+  for (const rule of rules) {
+    const ownerPool = rule.subjectClasses.length > 0 ? rule.subjectClasses : rule.classes;
+    let owner = 'base';
+    let bestRank = -1;
+    const sectionBucketsTouched = new Set<string>();
+    for (const cls of rule.classes) {
+      const c = classified.get(cls);
+      // misc is a heterogeneous grab-bag, so straddling it isn't a meaningful boundary.
+      if (c?.category === 'section' && c.bucket !== miscBucketName) sectionBucketsTouched.add(c.bucket);
+    }
+    for (const cls of ownerPool) {
+      const c = classified.get(cls);
+      if (!c) continue;
+      // section > shared > webflow-auto > vendor — so a rule touching a real section is attributed
+      // to it even when it also carries an auto/utility class.
+      const rank = c.category === 'section' ? 4 : c.category === 'shared' ? 3 : c.category === 'webflow-auto' ? 2 : 1;
+      if (rank > bestRank) {
+        bestRank = rank;
+        owner = c.bucket;
+      }
+    }
+    const stat = bucketStat(owner);
+    stat.rules += 1;
+    stat.declarations += rule.declarations;
+    stat.approxBytes += rule.bytes;
+
+    if (sectionBucketsTouched.size >= 2 && crossBoundary.length < flagLimit) {
+      crossBoundary.push({
+        selector: rule.classes.map((c) => `.${c}`).join(''),
+        media: rule.media,
+        classes: rule.classes,
+        buckets: [...sectionBucketsTouched].sort(),
+      });
+    }
+  }
+
+  // Per-bucket class counts.
+  for (const info of classes) {
+    bucketStat(info.proposedBucket).classes += 1;
+  }
+
+  // Flags derived from classification + usage.
+  const fuzzyMiddle: string[] = [];
+  const deadClasses: string[] = [];
+  for (const info of classes) {
+    if (info.category === 'section' && info.pagesUsedIn >= 2 && info.pagesUsedIn < sharedMinPages) {
+      fuzzyMiddle.push(info.name);
+    }
+    if (info.category !== 'vendor' && info.pagesUsedIn === 0) {
+      deadClasses.push(info.name);
+    }
+  }
+  const pageOnlyClasses: string[] = [];
+  for (const cls of pageUseCount.keys()) {
+    if (!classMap.has(cls)) pageOnlyClasses.push(cls);
+  }
+  pageOnlyClasses.sort();
+  deadClasses.sort();
+
+  return {
+    source: {
+      bytes: css.length,
+      rules: totalRules,
+      selectors: totalSelectors,
+      declarations: totalDeclarations,
+      pageCount,
+      sharedMinPages,
+    },
+    breakpoints,
+    buckets: { base, vendor, webflowAuto, shared, sections },
+    classes,
+    flags: {
+      crossBoundarySelectors: crossBoundary,
+      fuzzyMiddle: fuzzyMiddle.slice(0, flagLimit),
+      deadClasses: deadClasses.slice(0, flagLimit),
+      pageOnlyClasses: pageOnlyClasses.slice(0, flagLimit),
+      foldedSections,
+    },
+  };
+}
+
+/**
+ * Walk a parsed page (JSONPage node tree, component defs, anything) and collect every static
+ * class token. Robust to the exact node schema: it harvests any string-valued `class`/`className`
+ * property anywhere in the structure, which is where the codec lands static class strings.
+ */
+export function collectClassesFromPageData(pageData: unknown): string[] {
+  const out = new Set<string>();
+  const walk = (value: unknown): void => {
+    if (!value) return;
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item);
+      return;
+    }
+    if (typeof value === 'object') {
+      for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+        if ((key === 'class' || key === 'className') && typeof v === 'string') {
+          for (const token of v.split(/\s+/)) {
+            if (token) out.add(token);
+          }
+        } else {
+          walk(v);
+        }
+      }
+    }
+  };
+  walk(pageData);
+  return [...out];
+}
+
+/** Render a compact human-readable summary of a report (for `?format=md`). */
+export function renderAuditMarkdown(report: CssAuditReport): string {
+  const { source, buckets, breakpoints, flags } = report;
+  const kb = (n: number) => `${(n / 1024).toFixed(1)} KB`;
+  const lines: string[] = [];
+
+  lines.push('# CSS audit');
+  lines.push('');
+  lines.push(
+    `**${kb(source.bytes)}** · ${source.rules} rules · ${source.selectors} selectors · ` +
+      `${source.declarations} declarations · ${source.pageCount} pages · shared threshold = ${source.sharedMinPages} pages`,
+  );
+  lines.push('');
+  lines.push(`Breakpoints: ${breakpoints.length ? breakpoints.map((b) => `\`${b}\``).join(', ') : '(none)'}`);
+  lines.push('');
+
+  lines.push('## Proposed buckets');
+  lines.push('');
+  lines.push('| bucket | classes | rules | declarations | ~size |');
+  lines.push('| --- | --- | --- | --- | --- |');
+  const row = (name: string, b: BucketStat) =>
+    `| ${name} | ${b.classes} | ${b.rules} | ${b.declarations} | ${kb(b.approxBytes)} |`;
+  lines.push(row('base (reset/typography)', buckets.base));
+  lines.push(row('vendor (.w-*)', buckets.vendor));
+  lines.push(row('webflow-auto (div-block/text-block/…)', buckets.webflowAuto));
+  lines.push(row('shared', buckets.shared));
+  // Real sections first (by size); the misc catch-all always last.
+  const sectionEntries = Object.entries(buckets.sections).sort((a, b) => b[1].approxBytes - a[1].approxBytes);
+  for (const [prefix, stat] of sectionEntries) {
+    if (prefix === 'misc') continue;
+    lines.push(row(`section: ${prefix}`, stat));
+  }
+  const misc = buckets.sections.misc;
+  if (misc) lines.push(row('misc (folded small/orphan)', misc));
+  lines.push('');
+  lines.push(`_${sectionEntries.filter(([p]) => p !== 'misc').length} real sections + ${misc ? 'misc' : 'no misc'}_`);
+  lines.push('');
+
+  lines.push('## Flags');
+  lines.push('');
+  lines.push(`- Cross-boundary selectors (touch ≥2 sections): **${flags.crossBoundarySelectors.length}**`);
+  lines.push(`- Fuzzy-middle classes (near shared threshold): **${flags.fuzzyMiddle.length}**`);
+  lines.push(`- Dead classes (defined, unused on any page): **${flags.deadClasses.length}**`);
+  lines.push(`- Page-only classes (used in pages, not in this sheet): **${flags.pageOnlyClasses.length}**`);
+  const foldedClasses = flags.foldedSections.reduce((n, f) => n + f.classes, 0);
+  lines.push(
+    `- Folded section buckets (small/typo → misc/kept): **${flags.foldedSections.length}** (${foldedClasses} classes)`,
+  );
+  const typos = flags.foldedSections.filter((f) => f.reason === 'typo');
+  if (typos.length) {
+    lines.push('');
+    lines.push('Typo merges:');
+    for (const f of typos) lines.push(`- \`${f.from}\` → \`${f.into}\` (${f.classes})`);
+  }
+  if (flags.crossBoundarySelectors.length) {
+    lines.push('');
+    lines.push('Sample cross-boundary selectors:');
+    for (const f of flags.crossBoundarySelectors.slice(0, 10)) {
+      lines.push(`- \`${f.selector}\`${f.media ? ` @ ${f.media}` : ''} → ${f.buckets.join(' + ')}`);
+    }
+  }
+
+  return lines.join('\n');
+}