@birdapi/velinstyle 1.2.1 → 1.3.0

package/cli/production/report.js

@@ -0,0 +1,168 @@
+/**
+ * Production report — text + JSON with before/after breakdown.
+ */
+export function buildReport(data) {
+  const {
+    originalBytes = 0,
+    productionBytes = 0,
+    breakdown = {},
+    categories = null,
+    themes = [],
+    icons = [],
+    components = [],
+    tags = [],
+    themeCountBefore = null,
+    themeCountAfter = null,
+    motionBefore = null,
+    motionAfter = null,
+    componentsBefore = null,
+    componentsAfter = null,
+    imagesSkipped = true,
+    filesScanned = 0,
+  } = data;
+
+  const saved = Math.max(0, originalBytes - productionBytes);
+  const pct = originalBytes > 0 ? Math.round((saved / originalBytes) * 100) : 0;
+
+  const rows = categories || buildCategoryRows({
+    breakdown,
+    themes,
+    icons,
+    components,
+    tags,
+    themeCountBefore,
+    themeCountAfter,
+    motionBefore,
+    motionAfter,
+    componentsBefore,
+    componentsAfter,
+    fullCss: data.fullCss,
+    fullJs: data.fullJs,
+    fullIcons: data.fullIcons,
+    cssBytes: data.cssBytes,
+    jsBytes: data.jsBytes,
+    iconBytes: data.iconBytes,
+  });
+
+  const lines = [
+    'Production Report',
+    '',
+  ];
+
+  for (const row of rows) {
+    const before = row.beforeCount != null ? String(row.beforeCount) : formatKb(row.before);
+    const after = row.afterCount != null ? String(row.afterCount) : formatKb(row.after);
+    lines.push(`${String(row.label).padEnd(14)}${before.padStart(8)}  →  ${after}`);
+  }
+
+  lines.push('');
+  lines.push(`${'Savings'.padEnd(14)}${pct} %`);
+
+  if (imagesSkipped) {
+    lines.push('');
+    lines.push('Images: skipped (coming soon)');
+  }
+
+  lines.push('');
+  lines.push(`Scanned files: ${filesScanned}`);
+  if (themes.length) lines.push(`Themes kept: ${themes.join(', ')}`);
+  if (icons.length) lines.push(`Icons (${icons.length}): ${icons.slice(0, 12).join(', ')}${icons.length > 12 ? '…' : ''}`);
+  if (tags.length) lines.push(`Web Components: ${tags.join(', ')}`);
+  if (components.length) lines.push(`CSS modules: ${components.length}`);
+
+  return {
+    version: 2,
+    originalBytes,
+    productionBytes,
+    savedBytes: saved,
+    savedPercent: pct,
+    breakdown,
+    categories: rows,
+    themes,
+    icons,
+    tags,
+    components,
+    filesScanned,
+    images: imagesSkipped ? { status: 'skipped', note: 'coming soon' } : null,
+    text: lines.join('\n'),
+  };
+}
+
+function buildCategoryRows(opts) {
+  const {
+    fullCss = 0,
+    fullJs = 0,
+    fullIcons = 0,
+    cssBytes = 0,
+    jsBytes = 0,
+    iconBytes = 0,
+    themeCountBefore,
+    themeCountAfter,
+    motionBefore,
+    motionAfter,
+    componentsBefore,
+    componentsAfter,
+    breakdown = {},
+    themes = [],
+    components = [],
+    tags = [],
+  } = opts;
+
+  return [
+    { label: 'CSS', before: fullCss || (cssBytes + (breakdown.CSS || 0)), after: cssBytes },
+    { label: 'Runtime', before: fullJs || (jsBytes + (breakdown.JS || 0)), after: jsBytes },
+    { label: 'Icons', before: fullIcons || (iconBytes + (breakdown.Icons || 0)), after: iconBytes },
+    {
+      label: 'Themes',
+      beforeCount: themeCountBefore != null ? themeCountBefore : (themes.length + (breakdown.Themes ? 1 : 0)),
+      afterCount: themeCountAfter != null ? themeCountAfter : themes.length,
+    },
+    {
+      label: 'Motion',
+      beforeCount: motionBefore != null ? motionBefore : 18,
+      afterCount: motionAfter != null ? motionAfter : (breakdown.Motion ? 4 : 18),
+    },
+    {
+      label: 'Components',
+      beforeCount: componentsBefore != null ? componentsBefore : Math.max(components.length, tags.length, 43),
+      afterCount: componentsAfter != null ? componentsAfter : Math.max(tags.length, components.length ? Math.min(components.length, tags.length || components.length) : tags.length),
+    },
+  ];
+}
+
+export function formatKb(bytes) {
+  if (bytes == null || Number.isNaN(bytes)) return '—';
+  return `${(bytes / 1024).toFixed(bytes >= 10240 ? 0 : 1)} KB`;
+}
+
+export function measureBytes(parts) {
+  let total = 0;
+  for (const p of parts) {
+    if (typeof p === 'number') total += p;
+    else if (typeof p === 'string') total += Buffer.byteLength(p, 'utf-8');
+    else if (p && typeof p.bytes === 'number') total += p.bytes;
+  }
+  return total;
+}
+
+/** Map report → Experience contract widgets */
+export function reportToExperienceWidgets(report) {
+  return [
+    {
+      id: 'hero',
+      props: {
+        title: 'Production Builder',
+        subtitle: 'Build only what your project actually uses',
+        eyebrow: 'Velin Experience',
+      },
+    },
+    {
+      id: 'bundle',
+      props: {
+        title: 'Production Report',
+        rows: report.categories || [],
+        savingsPct: report.savedPercent,
+      },
+    },
+  ];
+}

package/cli/production/run.js

@@ -0,0 +1,355 @@
+/**
+ * Production Builder orchestration.
+ */
+import {
+  existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, statSync, readdirSync,
+} from 'fs';
+import { join, resolve, dirname } from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { extractProject, extractToPlain, DEFAULT_IGNORE } from './extract.js';
+import { resolveClosure, listKnownThemeNames } from './graph.js';
+import { buildProductionCss } from './trim-css.js';
+import { buildProductionJs, detectRuntimeFeatures } from './trim-js.js';
+import { resolveUsedThemes, writeThemes } from './trim-themes.js';
+import { buildIconSpriteSubset } from './trim-icons.js';
+import { shouldIncludeMotion, motionClassSet } from './trim-motion.js';
+import { buildReport } from './report.js';
+import { buildExplain } from './explain.js';
+import { watchProduction } from './watch.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const PKG_ROOT = join(__dirname, '../..');
+
+function parseSafelist(raw) {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw.map(String);
+  const s = String(raw);
+  if (existsSync(s) && statSync(s).isFile()) {
+    return readFileSync(s, 'utf-8')
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith('#'));
+  }
+  return s.split(/[,]+/).map((x) => x.trim()).filter(Boolean);
+}
+
+async function loadUserConfig(cwd) {
+  const configPath = resolve(cwd, 'velinstyle.config.js');
+  if (!existsSync(configPath)) return {};
+  try {
+    const mod = await import(pathToFileURL(configPath).href);
+    return mod.default || {};
+  } catch {
+    return {};
+  }
+}
+
+function lightningBundle(css, outFile, { minify = true } = {}) {
+  mkdirSync(dirname(outFile), { recursive: true });
+  const tmpPath = resolve(dirname(outFile), '.velin-production-tmp.css');
+  writeFileSync(tmpPath, css);
+  let ok = false;
+  try {
+    const binName = process.platform === 'win32' ? 'lightningcss.cmd' : 'lightningcss';
+    const localBin = join(PKG_ROOT, 'node_modules', '.bin', binName);
+    const cli = existsSync(localBin) ? `"${localBin}"` : 'npx lightningcss';
+    const minifyFlag = minify ? '--minify' : '';
+    execSync(`${cli} --bundle ${minifyFlag} "${tmpPath}" -o "${outFile}"`, {
+      stdio: 'pipe',
+      cwd: PKG_ROOT,
+      shell: true,
+    });
+    ok = true;
+  } catch {
+    writeFileSync(outFile, css);
+  } finally {
+    try { unlinkSync(tmpPath); } catch { /* ignore */ }
+  }
+  return ok;
+}
+
+function originalBytesEstimate() {
+  let n = 0;
+  const css = join(PKG_ROOT, 'dist', 'velinstyle.min.css');
+  const js = join(PKG_ROOT, 'dist', 'velinstyle-components.min.js');
+  const icons = join(PKG_ROOT, 'dist', 'velin-icons.svg');
+  for (const f of [css, js, icons]) {
+    if (existsSync(f)) n += statSync(f).size;
+  }
+  const themeDir = join(PKG_ROOT, 'dist', 'themes');
+  if (existsSync(themeDir)) {
+    for (const f of readdirSync(themeDir)) {
+      if (f.endsWith('.css')) n += statSync(join(themeDir, f)).size;
+    }
+  }
+  return n;
+}
+
+/**
+ * @param {object} opts
+ * @param {string[]} [opts.args] raw CLI args after command
+ * @param {object} [opts.helpers] { getArg, hasFlag, C }
+ */
+export async function runProduction(opts = {}) {
+  const {
+    args = [],
+    helpers = {},
+    cwd = process.cwd(),
+  } = opts;
+  const getArg = helpers.getArg || ((flag, alias) => {
+    const i = args.indexOf(flag);
+    const a = alias ? args.indexOf(alias) : -1;
+    const idx = i !== -1 ? i : a;
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : null;
+  });
+  const hasFlag = helpers.hasFlag || ((flag, alias) => args.includes(flag) || (alias && args.includes(alias)));
+  const C = helpers.C || {
+    green: (s) => s, yellow: (s) => s, cyan: (s) => s, dim: (s) => s, bold: (s) => s, red: (s) => s,
+  };
+
+  const config = await loadUserConfig(cwd);
+  const prodCfg = config.production || {};
+
+  const pathArg = args.find((a) => a && !a.startsWith('-')) || '.';
+  const targetPath = resolve(cwd, pathArg);
+  const outDir = resolve(cwd, getArg('--out', '-o') || prodCfg.out || './dist/velin-production');
+  const explain = hasFlag('--explain');
+  const doWatch = hasFlag('--watch');
+  const reportPath = getArg('--report') || null;
+  const safelist = [
+    ...parseSafelist(prodCfg.safelist),
+    ...parseSafelist(getArg('--safelist')),
+  ];
+  const noJs = hasFlag('--no-js');
+  const noIcons = hasFlag('--no-icons');
+  const noThemes = hasFlag('--no-themes');
+  const noMotion = hasFlag('--no-motion');
+  const minify = !hasFlag('--no-minify');
+
+  const once = async () => {
+    mkdirSync(outDir, { recursive: true });
+
+    const extracted = extractProject(targetPath, {
+      ignore: DEFAULT_IGNORE,
+      safelist,
+      outDir,
+      cwd,
+    });
+
+    const closure = resolveClosure(
+      { classes: extracted.classes, tags: extracted.tags },
+      {
+        safelistFiles: safelist.filter((s) => s.endsWith('.css') || s.includes('/')),
+      },
+    );
+
+    const includeMotion = shouldIncludeMotion(extracted, { force: noMotion ? false : null });
+    const motionUsed = motionClassSet(extracted);
+
+    const utilitySet = new Set(closure.utilityFiles);
+    const componentFiles = closure.cssFiles.filter((f) => !utilitySet.has(f));
+    const utilityFiles = closure.utilityFiles.filter((f) => {
+      if (!includeMotion && /animation|view-transition|scroll-animation|chart-animation/.test(f)) return false;
+      return true;
+    });
+
+    const cssResult = buildProductionCss({
+      pkgRoot: PKG_ROOT,
+      readFile: (p) => readFileSync(p, 'utf-8'),
+      exists: existsSync,
+      componentFiles,
+      utilityFiles,
+      usedClasses: extracted.classes,
+      includeMotionFiles: includeMotion,
+      motionUsed,
+    });
+
+    const cssOut = join(outDir, 'velinstyle.css');
+    const bundled = lightningBundle(cssResult.css, cssOut, { minify });
+    const cssBytes = existsSync(cssOut) ? statSync(cssOut).size : Buffer.byteLength(cssResult.css);
+
+    let jsBytes = 0;
+    let jsOut = null;
+    const features = detectRuntimeFeatures(extracted);
+    if (!noJs) {
+      jsOut = join(outDir, 'velinstyle.js');
+      const js = buildProductionJs({ tags: closure.tags, features });
+      writeFileSync(jsOut, js);
+      jsBytes = Buffer.byteLength(js);
+    }
+
+    let themeMeta = { selected: [], skipped: [], written: [] };
+    if (!noThemes) {
+      const resolved = resolveUsedThemes(extracted, {
+        configThemes: prodCfg.themes ?? 'auto',
+        pkgRoot: PKG_ROOT,
+        defaultThemes: [],
+      });
+      const written = writeThemes({
+        pkgRoot: PKG_ROOT,
+        outDir,
+        themes: resolved.selected,
+        minifyPrefer: minify,
+      });
+      themeMeta = { ...resolved, ...written };
+    } else {
+      themeMeta.skipped = listKnownThemeNames(PKG_ROOT);
+    }
+
+    let iconMeta = { included: [], skipped: [], bytes: 0, availableCount: 0 };
+    if (!noIcons) {
+      iconMeta = buildIconSpriteSubset({
+        pkgRoot: PKG_ROOT,
+        outDir,
+        iconNames: extracted.icons,
+      });
+    }
+
+    const themeBytes = (themeMeta.written || []).reduce((n, w) => {
+      try { return n + statSync(w.file).size; } catch { return n; }
+    }, 0);
+
+    const productionBytes = cssBytes + jsBytes + (iconMeta.bytes || 0) + themeBytes;
+    const original = originalBytesEstimate();
+
+    const fullCss = existsSync(join(PKG_ROOT, 'dist', 'velinstyle.min.css'))
+      ? statSync(join(PKG_ROOT, 'dist', 'velinstyle.min.css')).size : 0;
+    const fullJs = existsSync(join(PKG_ROOT, 'dist', 'velinstyle-components.min.js'))
+      ? statSync(join(PKG_ROOT, 'dist', 'velinstyle-components.min.js')).size : 0;
+    const fullIcons = existsSync(join(PKG_ROOT, 'dist', 'velin-icons.svg'))
+      ? statSync(join(PKG_ROOT, 'dist', 'velin-icons.svg')).size : 0;
+
+    let themeSaved = 0;
+    for (const name of themeMeta.skipped || []) {
+      const p = join(PKG_ROOT, 'dist', 'themes', `${name}.min.css`);
+      if (existsSync(p)) themeSaved += statSync(p).size;
+    }
+
+    const report = buildReport({
+      originalBytes: original || (fullCss + fullJs + fullIcons),
+      productionBytes,
+      fullCss,
+      fullJs,
+      fullIcons,
+      cssBytes,
+      jsBytes,
+      iconBytes: iconMeta.bytes || 0,
+      breakdown: {
+        CSS: Math.max(0, fullCss - cssBytes),
+        JS: Math.max(0, fullJs - jsBytes),
+        Icons: Math.max(0, fullIcons - (iconMeta.bytes || 0)),
+        Themes: themeSaved,
+        Motion: includeMotion ? 0 : 8 * 1024,
+        Fonts: 2 * 1024,
+      },
+      themes: themeMeta.selected || [],
+      themeCountBefore: listKnownThemeNames(PKG_ROOT).length,
+      themeCountAfter: (themeMeta.selected || []).length,
+      motionBefore: 18,
+      motionAfter: includeMotion ? 18 : 4,
+      componentsBefore: 43,
+      componentsAfter: Math.max(closure.tags.length, 1),
+      icons: iconMeta.included || [],
+      components: cssResult.included,
+      tags: closure.tags,
+      filesScanned: extracted.files.length,
+      imagesSkipped: true,
+    });
+
+    writeFileSync(join(outDir, 'production-report.json'), JSON.stringify(report, null, 2));
+    writeFileSync(join(outDir, 'production-report.txt'), report.text);
+    writeFileSync(join(outDir, 'used.json'), JSON.stringify({
+      ...extractToPlain(extracted),
+      closure: {
+        cssFiles: closure.cssFiles,
+        tags: closure.tags,
+        matchedPrefixes: closure.matchedPrefixes,
+      },
+    }, null, 2));
+
+    if (reportPath) {
+      const absReport = resolve(cwd, reportPath);
+      mkdirSync(dirname(absReport), { recursive: true });
+      if (absReport.endsWith('.md') || absReport.endsWith('.txt')) {
+        writeFileSync(absReport, report.text);
+      } else {
+        writeFileSync(absReport, JSON.stringify(report, null, 2));
+      }
+    }
+
+    let explainOut = null;
+    if (explain) {
+      explainOut = buildExplain({
+        skippedCss: cssResult.skipped,
+        skippedThemes: themeMeta.skipped || [],
+        skippedIcons: iconMeta.skipped || [],
+        skippedMotion: !includeMotion,
+        graphExplain: closure.explain,
+      });
+      writeFileSync(join(outDir, 'explain.txt'), explainOut.text);
+      console.log(`\n${explainOut.text}`);
+    }
+
+    console.log(C.green(`\nProduction build → ${outDir}`));
+    try {
+      const { createExperienceSession, parseExperienceFlags, writeRecording, loadExperienceConfig } = await import('../experience.js');
+      const { reportToExperienceWidgets } = await import('./report.js');
+      const overrides = parseExperienceFlags(args || process.argv.slice(2), helpers || {
+        getArg: () => null,
+        hasFlag: () => false,
+      });
+      const config = loadExperienceConfig(cwd, overrides);
+      const session = createExperienceSession(config);
+      const contract = {
+        project: { outDir, filesScanned: extracted.files.length },
+        lifecycle: { stage: 'summary', stages: [] },
+        result: { status: 'PASS', message: `Saved ${report.savedPercent}%` },
+        stats: { savedPercent: report.savedPercent, productionBytes, originalBytes: report.originalBytes },
+        widgets: reportToExperienceWidgets(report),
+        suggestions: explain
+          ? [{ text: 'See explain.txt for removed CSS/themes/icons' }]
+          : [{ text: 'Add --explain for removed-asset details' }],
+        diagnostics: [],
+        notifications: [
+          { tone: 'ok', message: `Production savings ${report.savedPercent}%` },
+        ],
+        meta: { commandId: 'production', layout: 'build', durationMs: 0 },
+      };
+      console.log(session.render(contract));
+      if (config.record || overrides.record) {
+        const paths = writeRecording({ contract, events: [], config });
+        console.log(`\nRecorded → ${paths.json}`);
+      }
+    } catch {
+      console.log(report.text);
+    }
+    console.log(C.dim(`\nCSS: ${cssOut}${bundled ? ' (lightningcss)' : ' (raw)'}`));
+    if (jsOut) console.log(C.dim(`JS:  ${jsOut} (${closure.tags.length} components)`));
+    if (!noIcons) console.log(C.dim(`Icons: ${iconMeta.included.length} / ${iconMeta.availableCount || '?'}`));
+    if (!noThemes) console.log(C.dim(`Themes: ${(themeMeta.selected || []).join(', ') || '(none)'}`));
+
+    return {
+      outDir,
+      report,
+      explain: explainOut,
+      extracted,
+      closure,
+      cssOut,
+      jsOut,
+    };
+  };
+
+  const result = await once();
+
+  if (doWatch) {
+    console.log(C.cyan(`\nWatching ${targetPath} … (Ctrl+C to stop)`));
+    watchProduction(targetPath, async () => {
+      console.log(C.dim('\n[watch] rebuild…'));
+      await once();
+    });
+    await new Promise(() => {});
+  }
+
+  return result;
+}

package/cli/production/trim-css.js

@@ -0,0 +1,177 @@
+/**
+ * Filter CSS source to rules that reference used velin-/expo- classes.
+ */
+import { join } from 'path';
+
+const CLASS_IN_SEL = /\.(?:velin|expo)-[\w:-]+/g;
+
+const ALWAYS_KEEP_RE = [
+  /:root\b/,
+  /\[data-velin-/,
+  /prefers-reduced-motion/,
+  /prefers-contrast/,
+  /forced-colors/,
+  /@font-face/,
+];
+
+function selectorNeedsClass(selector, used) {
+  const classes = selector.match(CLASS_IN_SEL);
+  if (!classes || !classes.length) return true;
+  return classes.some((c) => used.has(c.slice(1)));
+}
+
+function shouldAlwaysKeep(block) {
+  return ALWAYS_KEEP_RE.some((re) => re.test(block));
+}
+
+export function filterCssByUsedClasses(css, usedClasses, { keepAllWithoutVelinClass = true } = {}) {
+  const used = usedClasses instanceof Set ? usedClasses : new Set(usedClasses);
+  const keptKeyframes = new Set();
+  const chunks = [];
+  const parts = splitCssTopLevel(css);
+
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+
+    if (trimmed.startsWith('@keyframes') || trimmed.startsWith('@-webkit-keyframes')) {
+      const name = trimmed.match(/@[-a-z]*keyframes\s+([\w-]+)/i)?.[1];
+      chunks.push({ type: 'keyframes', name, text: ensureBrace(trimmed) });
+      continue;
+    }
+
+    if (trimmed.startsWith('@media') || trimmed.startsWith('@supports') || trimmed.startsWith('@container')) {
+      const innerMatch = trimmed.match(/^(@[^{]+)\{([\s\S]*)\}$/);
+      if (!innerMatch) {
+        chunks.push({ type: 'raw', text: ensureBrace(trimmed) });
+        continue;
+      }
+      const filteredInner = filterCssByUsedClasses(innerMatch[2], used, { keepAllWithoutVelinClass });
+      if (filteredInner.trim()) {
+        const block = `${innerMatch[1].trim()} {\n${filteredInner}\n}`;
+        chunks.push({ type: 'at', text: block });
+        collectAnimationNames(filteredInner, keptKeyframes);
+      }
+      continue;
+    }
+
+    if (shouldAlwaysKeep(trimmed)) {
+      chunks.push({ type: 'rule', text: ensureBrace(trimmed) });
+      continue;
+    }
+
+    const sel = trimmed.split('{')[0] || '';
+    CLASS_IN_SEL.lastIndex = 0;
+    const hasVelin = CLASS_IN_SEL.test(sel);
+    CLASS_IN_SEL.lastIndex = 0;
+    if (!hasVelin) {
+      if (keepAllWithoutVelinClass) chunks.push({ type: 'rule', text: ensureBrace(trimmed) });
+      continue;
+    }
+    if (selectorNeedsClass(sel, used)) {
+      const text = ensureBrace(trimmed);
+      chunks.push({ type: 'rule', text });
+      collectAnimationNames(text, keptKeyframes);
+    }
+  }
+
+  const out = [];
+  for (const c of chunks) {
+    if (c.type === 'keyframes') {
+      if (c.name && keptKeyframes.has(c.name)) out.push(c.text);
+      continue;
+    }
+    out.push(c.text);
+  }
+  return out.join('\n\n') + (out.length ? '\n' : '');
+}
+
+function ensureBrace(s) {
+  return s.endsWith('}') ? s : `${s}}`;
+}
+
+function collectAnimationNames(text, into) {
+  for (const m of text.matchAll(/animation(?:-name)?\s*:\s*([^;}+]+)/gi)) {
+    for (const name of m[1].split(/[\s,]+/)) {
+      if (name && name !== 'none' && !name.startsWith('var(')) into.add(name.trim());
+    }
+  }
+}
+
+function splitCssTopLevel(css) {
+  const src = String(css || '').replace(/\/\*[\s\S]*?\*\//g, '');
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < src.length; i++) {
+    const ch = src[i];
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      depth--;
+      if (depth === 0) {
+        parts.push(src.slice(start, i + 1));
+        start = i + 1;
+      }
+    }
+  }
+  if (start < src.length) {
+    const tail = src.slice(start).trim();
+    if (tail) parts.push(tail);
+  }
+  return parts;
+}
+
+export function buildProductionCss({
+  pkgRoot,
+  readFile,
+  exists,
+  componentFiles = [],
+  utilityFiles = [],
+  usedClasses,
+  includeMotionFiles = true,
+  motionUsed = null,
+}) {
+  const used = usedClasses instanceof Set ? usedClasses : new Set(usedClasses);
+  let css = '/* VelinStyle Production Build */\n';
+  const included = [];
+  const skipped = [];
+  const seen = new Set();
+
+  for (const rel of componentFiles) {
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    const path = join(pkgRoot, 'src', rel);
+    if (!exists(path)) {
+      skipped.push({ file: rel, reason: 'missing' });
+      continue;
+    }
+    css += readFile(path) + '\n';
+    included.push(rel);
+  }
+
+  for (const rel of utilityFiles) {
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    const path = join(pkgRoot, 'src', rel);
+    if (!exists(path)) {
+      skipped.push({ file: rel, reason: 'missing' });
+      continue;
+    }
+    const isMotion = /animation|motion|view-transition|scroll-animation|chart-animation/.test(rel);
+    if (isMotion && !includeMotionFiles) {
+      skipped.push({ file: rel, reason: 'motion disabled' });
+      continue;
+    }
+    const raw = readFile(path);
+    const filterSet = isMotion && motionUsed ? new Set([...used, ...motionUsed]) : used;
+    const filtered = filterCssByUsedClasses(raw, filterSet);
+    if (!filtered.trim()) {
+      skipped.push({ file: rel, reason: 'no matching utilities' });
+      continue;
+    }
+    css += filtered + '\n';
+    included.push(rel);
+  }
+
+  return { css, included, skipped };
+}