@birdapi/velinstyle 1.2.1 → 1.3.0

package/cli/production/component-graph.json

@@ -0,0 +1,166 @@
+{
+  "version": 1,
+  "alwaysCss": [
+    "tokens/fonts.css",
+    "tokens/color.css",
+    "tokens/spacing.css",
+    "tokens/typography.css",
+    "tokens/radius.css",
+    "tokens/shadow.css",
+    "tokens/motion.css",
+    "tokens/z-index.css",
+    "tokens/aspect-ratio.css",
+    "base/root.css",
+    "base/reset.css",
+    "base/focus.css",
+    "base/content.css",
+    "a11y/sr-only.css",
+    "a11y/skip-link.css",
+    "a11y/reduced-motion.css",
+    "a11y/forced-colors.css",
+    "a11y/focus-appearance.css",
+    "a11y/target-size.css",
+    "layout/breakpoints.css",
+    "layout/container.css"
+  ],
+  "classPrefixes": {
+    "velin-btn": { "css": ["components/button.css"] },
+    "velin-card": { "css": ["components/card.css"] },
+    "velin-input": { "css": ["components/input.css", "components/form-validation.css"] },
+    "velin-textarea": { "css": ["components/input.css", "components/form-validation.css"] },
+    "velin-select": { "css": ["components/input.css", "components/form-validation.css"] },
+    "velin-label": { "css": ["components/input.css"] },
+    "velin-field": { "css": ["components/input.css", "components/form-validation.css"] },
+    "velin-nav": { "css": ["components/nav.css"] },
+    "velin-navbar": { "css": ["components/nav.css"] },
+    "velin-alert": { "css": ["components/alert.css"] },
+    "velin-badge": { "css": ["components/badge.css"] },
+    "velin-table": { "css": ["components/table.css"] },
+    "velin-data-table": { "css": ["components/data-table.css", "components/table.css"] },
+    "velin-tooltip": { "css": ["components/tooltip.css"] },
+    "velin-modal": { "css": ["components/modal.css", "components/button.css"] },
+    "velin-dialog": { "css": ["components/modal.css", "components/button.css"] },
+    "velin-breadcrumb": { "css": ["components/breadcrumb.css"] },
+    "velin-pagination": { "css": ["components/pagination.css"] },
+    "velin-progress": { "css": ["components/progress.css"] },
+    "velin-spinner": { "css": ["components/spinner.css"] },
+    "velin-list": { "css": ["components/list-group.css"] },
+    "velin-avatar": { "css": ["components/avatar.css"] },
+    "velin-switch": { "css": ["components/switch.css"] },
+    "velin-divider": { "css": ["components/divider.css"] },
+    "velin-chip": { "css": ["components/chip.css"] },
+    "velin-timeline": { "css": ["components/timeline.css"] },
+    "velin-stepper": { "css": ["components/stepper.css"] },
+    "velin-stat": { "css": ["components/stat.css"] },
+    "velin-drawer": { "css": ["components/drawer.css", "components/button.css"] },
+    "velin-sheet": { "css": ["components/drawer.css", "components/button.css"] },
+    "velin-input-group": { "css": ["components/input-group.css", "components/input.css"] },
+    "velin-collapse": { "css": ["components/collapse.css"] },
+    "velin-accordion": { "css": ["components/collapse.css"] },
+    "velin-calendar": { "css": ["components/calendar-dropzone.css"] },
+    "velin-dropzone": { "css": ["components/calendar-dropzone.css"] },
+    "velin-grid": { "css": ["layout/grid.css"] },
+    "velin-flex": { "css": ["layout/flex.css"] },
+    "velin-container": { "css": ["layout/container.css"] },
+    "velin-stack": { "css": ["layout/patterns.css"] },
+    "velin-cluster": { "css": ["layout/patterns.css"] },
+    "velin-sidebar": { "css": ["layout/patterns.css", "layout/app-shell.css"] },
+    "velin-app": { "css": ["layout/app-shell.css"] },
+    "velin-shell": { "css": ["layout/app-shell.css"] },
+    "velin-skeleton": { "css": ["a11y/skeleton.css"] },
+    "velin-sr-only": { "css": ["a11y/sr-only.css"] },
+    "velin-skip": { "css": ["a11y/skip-link.css"] },
+    "velin-transparency": { "css": ["components/transparency.css"] },
+    "velin-disclosure": { "css": ["components/transparency.css"] },
+    "velin-otp-input": { "css": ["components/empty-auth.css", "components/input.css"] },
+    "velin-password-strength": { "css": ["components/empty-auth.css", "components/progress.css"] },
+    "velin-empty-state": { "css": ["components/empty-auth.css", "components/button.css"] }
+  },
+  "wc": {
+    "velin-modal": { "css": ["components/modal.css", "components/button.css"], "peers": ["velin-icon"] },
+    "velin-dialog": { "css": ["components/modal.css", "components/button.css"], "peers": ["velin-icon"] },
+    "velin-drawer": { "css": ["components/drawer.css", "components/button.css"], "peers": [] },
+    "velin-sheet": { "css": ["components/drawer.css", "components/button.css"], "peers": [] },
+    "velin-toast": { "css": ["components/alert.css"], "peers": ["velin-icon"] },
+    "velin-tooltip": { "css": ["components/tooltip.css"], "peers": [] },
+    "velin-tooltip-wc": { "css": ["components/tooltip.css"], "peers": [] },
+    "velin-tabs": { "css": ["components/nav.css"], "peers": [] },
+    "velin-icon": { "css": [], "peers": [] },
+    "velin-accordion": { "css": ["components/collapse.css"], "peers": [] },
+    "velin-collapse": { "css": ["components/collapse.css"], "peers": [] },
+    "velin-dropdown": { "css": ["components/nav.css", "components/button.css"], "peers": [] },
+    "velin-popover": { "css": ["components/tooltip.css"], "peers": [] },
+    "velin-carousel": { "css": [], "peers": ["velin-icon"] },
+    "velin-lightbox": { "css": ["components/modal.css"], "peers": ["velin-icon"] },
+    "velin-data-table": { "css": ["components/data-table.css", "components/table.css"], "peers": [] },
+    "velin-stepper": { "css": ["components/stepper.css"], "peers": [] },
+    "velin-stepper-wc": { "css": ["components/stepper.css"], "peers": [] },
+    "velin-theme-toggle": { "css": ["components/button.css"], "peers": ["velin-icon"] },
+    "velin-search": { "css": ["components/input.css", "components/input-group.css"], "peers": ["velin-icon"] },
+    "velin-combobox": { "css": ["components/input.css"], "peers": [] },
+    "velin-command": { "css": ["components/modal.css", "components/input.css"], "peers": [] },
+    "velin-bottom-nav": { "css": ["components/nav.css"], "peers": ["velin-icon"] },
+    "velin-menubar": { "css": ["components/nav.css"], "peers": [] },
+    "velin-calendar": { "css": ["components/calendar-dropzone.css"], "peers": [] },
+    "velin-file-dropzone": { "css": ["components/calendar-dropzone.css"], "peers": [] },
+    "velin-progress-ring": { "css": ["components/progress.css"], "peers": [] },
+    "velin-rating": { "css": ["components/chip.css"], "peers": ["velin-icon"] },
+    "velin-scroll-top": { "css": ["components/button.css"], "peers": ["velin-icon"] },
+    "velin-scrollspy": { "css": [], "peers": [] },
+    "velin-sparkline": { "css": [], "peers": [] },
+    "velin-countdown": { "css": ["components/stat.css"], "peers": [] },
+    "velin-counter": { "css": ["components/stat.css"], "peers": [] },
+    "velin-live-dot": { "css": ["components/badge.css"], "peers": [] },
+    "velin-announcer": { "css": ["a11y/sr-only.css"], "peers": [] },
+    "velin-copy": { "css": ["components/button.css"], "peers": ["velin-icon"] },
+    "velin-email": { "css": ["components/input.css"], "peers": [] },
+    "velin-secure-field": { "css": ["components/input.css", "a11y/security.css"], "peers": [] },
+    "velin-form-summary": { "css": ["components/form-validation.css", "components/alert.css"], "peers": [] },
+    "velin-persist": { "css": [], "peers": [] },
+    "velin-code-block": { "css": [], "peers": [] },
+    "velin-segmented-control": { "css": ["components/chip.css", "components/button.css"], "peers": [] },
+    "velin-otp-input": { "css": ["components/empty-auth.css", "components/input.css"], "peers": [] },
+    "velin-password-strength": { "css": ["components/empty-auth.css", "components/progress.css"], "peers": [] },
+    "velin-empty-state": { "css": ["components/empty-auth.css", "components/button.css"], "peers": [] }
+  },
+  "utilityFiles": [
+    "utilities/color.css",
+    "utilities/spacing.css",
+    "utilities/display.css",
+    "utilities/text.css",
+    "utilities/sizing.css",
+    "utilities/border.css",
+    "utilities/position.css",
+    "utilities/animation.css",
+    "utilities/gradient.css",
+    "utilities/print.css",
+    "utilities/responsive.css",
+    "utilities/divide.css",
+    "utilities/scroll.css",
+    "utilities/color-mix.css",
+    "utilities/scroll-animation.css",
+    "utilities/view-transition.css",
+    "utilities/scope.css",
+    "utilities/anchor.css",
+    "utilities/filter.css",
+    "utilities/filter-effects.css",
+    "utilities/chart-animation.css",
+    "utilities/container-style.css",
+    "utilities/state.css",
+    "utilities/safe-area.css"
+  ],
+  "motionFiles": [
+    "utilities/animation.css",
+    "utilities/scroll-animation.css",
+    "utilities/chart-animation.css",
+    "utilities/view-transition.css",
+    "tokens/motion.css",
+    "a11y/reduced-motion.css"
+  ],
+  "fontClassPrefixes": [
+    "velin-font-",
+    "velin-text-",
+    "velin-leading-",
+    "velin-tracking-"
+  ]
+}

package/cli/production/explain.js

@@ -0,0 +1,52 @@
+/**
+ * --explain: human-readable removals with reasons.
+ */
+export function buildExplain({
+  skippedCss = [],
+  skippedThemes = [],
+  skippedIcons = [],
+  skippedMotion = false,
+  graphExplain = [],
+} = {}) {
+  const removed = [];
+
+  for (const item of skippedCss) {
+    removed.push({
+      id: item.file || item,
+      reason: item.reason || 'Nicht benutzt',
+    });
+  }
+  for (const theme of skippedThemes) {
+    removed.push({ id: `${theme}.theme.css`, reason: 'Nicht benutzt' });
+  }
+  for (const icon of skippedIcons.slice(0, 40)) {
+    removed.push({ id: `icon:${icon}`, reason: 'Nicht benutzt' });
+  }
+  if (skippedIcons.length > 40) {
+    removed.push({ id: `icon:…(+${skippedIcons.length - 40})`, reason: 'Nicht benutzt' });
+  }
+  if (skippedMotion) {
+    removed.push({ id: 'motion utilities', reason: 'Keine Animate-/Motion-Klassen gefunden' });
+  }
+
+  const kept = [];
+  const seen = new Set();
+  for (const e of graphExplain) {
+    if (!e.keep || seen.has(e.keep)) continue;
+    seen.add(e.keep);
+    kept.push({ id: e.keep, reason: e.reason });
+  }
+
+  const lines = ['Entfernt'];
+  if (!removed.length) lines.push('(nichts entfernt — oder Scan fand fast alles)');
+  for (const r of removed) {
+    lines.push(`${r.id.padEnd(28)} ${r.reason}`);
+  }
+  lines.push('');
+  lines.push('Behalten (Auszug)');
+  for (const k of kept.slice(0, 30)) {
+    lines.push(`${k.id.padEnd(28)} ${k.reason}`);
+  }
+
+  return { removed, kept, text: lines.join('\n') };
+}

package/cli/production/extract.js

@@ -0,0 +1,278 @@
+/**
+ * Content extract for Production Builder — used classes, WC tags, themes, icons, motion, fonts.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join, extname, resolve, relative } from 'path';
+
+export const DEFAULT_IGNORE = [
+  'node_modules', 'dist', '.git', '.next', '.nuxt', 'vendor', 'build', 'coverage',
+];
+
+export const CONTENT_EXTS = new Set([
+  '.html', '.htm',
+  '.blade.php',
+  '.twig',
+  '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx',
+  '.vue',
+  '.astro',
+  '.md', '.mdx',
+  '.css',
+]);
+
+/** Resolve multi-dot extensions (.blade.php, .mdx) before extname. */
+export function contentExtOf(filePath) {
+  const name = String(filePath || '').toLowerCase().replace(/\\/g, '/');
+  const base = name.includes('/') ? name.slice(name.lastIndexOf('/') + 1) : name;
+  if (base.endsWith('.blade.php')) return '.blade.php';
+  if (base.endsWith('.mdx')) return '.mdx';
+  return extname(base).toLowerCase();
+}
+
+export function isContentFile(filePath) {
+  return CONTENT_EXTS.has(contentExtOf(filePath));
+}
+
+/** Strip template expressions so {{ class }} / {% %} are not mistaken for tokens. */
+export function stripTemplateNoise(content, ext) {
+  let text = String(content || '');
+  if (ext === '.astro') {
+    text = text.replace(/^---[\s\S]*?---\s*/, ' ');
+  }
+  if (ext === '.blade.php' || ext === '.twig' || ext === '.vue' || ext === '.astro' || ext === '.mdx') {
+    text = text
+      .replace(/\{\{[\s\S]*?\}\}/g, ' ')
+      .replace(/\{!![\s\S]*?!!\}/g, ' ')
+      .replace(/\{%[\s\S]*?%\}/g, ' ')
+      .replace(/@\{\{[\s\S]*?\}\}/g, ' ');
+  }
+  return text;
+}
+
+const CLASS_ATTR_RE = /class(?:Name)?\s*=\s*["'`]([^"'`]+)["'`]/gi;
+const CLASS_TOKEN_RE = /\b((?:velin|expo)-[\w:-]+)\b/g;
+const TAG_RE = /<(velin-[a-z0-9-]+)\b/gi;
+const DATA_COMPONENT_RE = /data-velin-component\s*=\s*["'](velin-[a-z0-9-]+)["']/gi;
+const THEME_RE = /data-velin-theme\s*=\s*["']([^"']+)["']/gi;
+const THEMES_LIST_RE = /themes\s*[:=]\s*\[([^\]]+)\]/gi;
+const ICON_NAME_RE = /(?:name|icon)\s*=\s*["']([a-z0-9][a-z0-9_-]*)["']/gi;
+const ICON_HASH_RE = /velin-icons\.svg#([a-z0-9][a-z0-9_-]*)/gi;
+const MOTION_ATTR_RE = /data-velin-(?:animate|motion|scroll)\s*=\s*["']([^"']+)["']/gi;
+const MOTION_BARE_RE = /\svelin-(?:motion|reveal|fade|slide|scale|parallax|hover|stagger|scroll|trigger|timeline|motion-sequence)(?:\s|=|>)/gi;
+const FONT_FACE_RE = /@font-face\s*\{([\s\S]*?)\}/gi;
+const FONT_WEIGHT_RE = /font-weight\s*:\s*([0-9]+|normal|bold)/gi;
+
+function shouldIgnore(name, ignore) {
+  return ignore.includes(name);
+}
+
+export function walkContentFiles(dir, { ignore = DEFAULT_IGNORE, out = [], root = dir } = {}) {
+  if (!existsSync(dir)) return out;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (shouldIgnore(entry.name, ignore)) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkContentFiles(full, { ignore, out, root });
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const ext = contentExtOf(entry.name);
+    if (!CONTENT_EXTS.has(ext)) continue;
+    out.push(full);
+  }
+  return out;
+}
+
+export function collectContentFiles(targetPath, { ignore = DEFAULT_IGNORE, extraIgnore = [] } = {}) {
+  const abs = resolve(targetPath);
+  const ignoreList = [...new Set([...ignore, ...extraIgnore])];
+  if (!existsSync(abs)) return [];
+  const st = statSync(abs);
+  if (st.isFile()) {
+    return isContentFile(abs) ? [abs] : [];
+  }
+  return walkContentFiles(abs, { ignore: ignoreList });
+}
+
+function addClassTokens(text, classes) {
+  for (const m of String(text || '').matchAll(CLASS_TOKEN_RE)) {
+    classes.add(m[1]);
+    // Responsive / state variants: velin-md:flex → also keep flex base if present as velin-flex
+    const bare = m[1].replace(/^(?:velin|expo)-(?:sm|md|lg|xl|2xl):/, (pref) => {
+      const ns = pref.startsWith('expo') ? 'expo-' : 'velin-';
+      return ns;
+    });
+    if (bare !== m[1] && bare.startsWith('velin-')) classes.add(bare);
+  }
+}
+
+/**
+ * @param {string} content
+ * @param {{ isCss?: boolean }} [opts]
+ */
+export function extractFromText(content, { isCss = false } = {}) {
+  const classes = new Set();
+  const tags = new Set();
+  const themes = new Set();
+  const icons = new Set();
+  const motion = new Set();
+  const fontWeights = new Set();
+  const attrs = new Set();
+
+  const text = String(content || '');
+
+  if (!isCss) {
+    for (const m of text.matchAll(CLASS_ATTR_RE)) {
+      addClassTokens(m[1], classes);
+    }
+  }
+  addClassTokens(text, classes);
+
+  for (const m of text.matchAll(TAG_RE)) tags.add(m[1].toLowerCase());
+  for (const m of text.matchAll(DATA_COMPONENT_RE)) tags.add(m[1].toLowerCase());
+
+  for (const m of text.matchAll(THEME_RE)) {
+    for (const t of m[1].split(/[\s,|]+/)) {
+      if (t) themes.add(t.trim().toLowerCase());
+    }
+  }
+  for (const m of text.matchAll(THEMES_LIST_RE)) {
+    for (const part of m[1].split(/[,'"`\s]+/)) {
+      if (part && /^[a-z][a-z0-9_-]*$/i.test(part)) themes.add(part.toLowerCase());
+    }
+  }
+
+  for (const m of text.matchAll(ICON_NAME_RE)) icons.add(m[1].toLowerCase());
+  for (const m of text.matchAll(ICON_HASH_RE)) icons.add(m[1].toLowerCase());
+
+  for (const m of text.matchAll(MOTION_ATTR_RE)) {
+    for (const part of m[1].split(/[\s,]+/)) {
+      if (part) motion.add(part.trim());
+    }
+  }
+  for (const m of text.matchAll(MOTION_BARE_RE)) {
+    motion.add(m[0].trim().replace(/=.*/, '').trim() || 'velin-motion');
+  }
+  for (const cls of classes) {
+    if (cls.includes('animate') || cls.includes('motion') || cls.startsWith('velin-scroll-')) {
+      motion.add(cls);
+    }
+  }
+
+  for (const cls of classes) {
+    if (cls.startsWith('velin-font-') || cls.startsWith('velin-text-')) {
+      fontWeights.add(cls);
+    }
+  }
+
+  for (const m of text.matchAll(FONT_FACE_RE)) {
+    for (const w of m[1].matchAll(FONT_WEIGHT_RE)) fontWeights.add(String(w[1]));
+  }
+
+  for (const m of text.matchAll(/data-velin-([\w-]+)/gi)) {
+    attrs.add(`data-velin-${m[1].toLowerCase()}`);
+  }
+
+  return { classes, tags, themes, icons, motion, fontWeights, attrs };
+}
+
+/**
+ * Scan a project path and merge all extracts.
+ * @returns {{
+ *   files: string[],
+ *   classes: Set<string>,
+ *   tags: Set<string>,
+ *   themes: Set<string>,
+ *   icons: Set<string>,
+ *   motion: Set<string>,
+ *   fontWeights: Set<string>,
+ *   attrs: Set<string>,
+ * }}
+ */
+export function extractProject(targetPath, options = {}) {
+  const {
+    ignore = DEFAULT_IGNORE,
+    contentGlobs, // reserved
+    safelist = [],
+    outDir,
+    cwd = process.cwd(),
+  } = options;
+
+  const extraIgnore = [];
+  if (outDir) {
+    try {
+      const rel = relative(resolve(cwd), resolve(outDir)).split(/[/\\]/)[0];
+      if (rel && rel !== '..' && rel !== '.') extraIgnore.push(rel);
+    } catch { /* ignore */ }
+  }
+
+  const files = collectContentFiles(targetPath, { ignore, extraIgnore });
+  const merged = {
+    files,
+    classes: new Set(),
+    tags: new Set(),
+    themes: new Set(),
+    icons: new Set(),
+    motion: new Set(),
+    fontWeights: new Set(),
+    attrs: new Set(),
+  };
+
+  for (const file of files) {
+    let body = '';
+    try {
+      body = readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+    const ext = contentExtOf(file);
+    const isCss = ext === '.css';
+    const part = extractFromText(isCss ? body : stripTemplateNoise(body, ext), { isCss });
+    for (const c of part.classes) merged.classes.add(c);
+    for (const t of part.tags) merged.tags.add(t);
+    for (const t of part.themes) merged.themes.add(t);
+    for (const i of part.icons) merged.icons.add(i);
+    for (const m of part.motion) merged.motion.add(m);
+    for (const f of part.fontWeights) merged.fontWeights.add(f);
+    for (const a of part.attrs) merged.attrs.add(a);
+  }
+
+  for (const item of safelist) {
+    const s = String(item).trim();
+    if (!s) continue;
+    if (s.startsWith('velin-') && !s.includes('.')) {
+      if (s.includes('-') && /^velin-[a-z]+-[a-z]/.test(s) && !s.includes('--') && s.split('-').length >= 3 && !s.startsWith('velin-btn') && !s.startsWith('velin-card')) {
+        // could be tag or class — add both conservatively
+        merged.tags.add(s);
+        merged.classes.add(s);
+      } else {
+        merged.classes.add(s);
+      }
+    } else if (s.endsWith('.css') || s.includes('/')) {
+      // handled by trim safelist files
+    } else if (/^[a-z][a-z0-9_-]*$/i.test(s)) {
+      merged.themes.add(s.toLowerCase());
+      merged.icons.add(s.toLowerCase());
+    }
+  }
+
+  return merged;
+}
+
+export function extractToPlain(extracted) {
+  return {
+    files: extracted.files,
+    classes: [...extracted.classes].sort(),
+    tags: [...extracted.tags].sort(),
+    themes: [...extracted.themes].sort(),
+    icons: [...extracted.icons].sort(),
+    motion: [...extracted.motion].sort(),
+    fontWeights: [...extracted.fontWeights].sort(),
+    attrs: [...extracted.attrs].sort(),
+  };
+}

package/cli/production/graph.js

@@ -0,0 +1,102 @@
+/**
+ * Component dependency graph — closure over used classes/tags → CSS files + WC tags.
+ */
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const GRAPH_PATH = join(__dirname, 'component-graph.json');
+
+let _graphCache = null;
+
+export function loadGraph(path = GRAPH_PATH) {
+  if (_graphCache && path === GRAPH_PATH) return _graphCache;
+  const graph = JSON.parse(readFileSync(path, 'utf-8'));
+  if (path === GRAPH_PATH) _graphCache = graph;
+  return graph;
+}
+
+function longestPrefixMatch(className, prefixes) {
+  let best = null;
+  let bestLen = -1;
+  for (const prefix of Object.keys(prefixes)) {
+    if (className === prefix || className.startsWith(`${prefix}-`) || className.startsWith(`${prefix}--`)) {
+      if (prefix.length > bestLen) {
+        best = prefix;
+        bestLen = prefix.length;
+      }
+    }
+  }
+  return best;
+}
+
+/**
+ * @param {{ classes: Iterable<string>, tags: Iterable<string> }} used
+ * @param {{ graph?: object, safelistFiles?: string[] }} [opts]
+ */
+export function resolveClosure(used, opts = {}) {
+  const graph = opts.graph || loadGraph();
+  const cssFiles = new Set(graph.alwaysCss || []);
+  const tags = new Set();
+  const matchedPrefixes = new Set();
+  const explain = [];
+
+  for (const f of opts.safelistFiles || []) {
+    const norm = String(f).replace(/^src\//, '');
+    cssFiles.add(norm);
+    explain.push({ keep: norm, reason: 'safelist' });
+  }
+
+  for (const cls of used.classes || []) {
+    const prefix = longestPrefixMatch(cls, graph.classPrefixes || {});
+    if (!prefix) continue;
+    matchedPrefixes.add(prefix);
+    const entry = graph.classPrefixes[prefix];
+    for (const file of entry.css || []) {
+      cssFiles.add(file);
+      explain.push({ keep: file, reason: `class ${cls} → ${prefix}` });
+    }
+  }
+
+  const queue = [...(used.tags || [])];
+  const seen = new Set();
+
+  while (queue.length) {
+    const tag = queue.shift();
+    if (!tag || seen.has(tag)) continue;
+    seen.add(tag);
+    tags.add(tag);
+    const entry = graph.wc?.[tag];
+    if (!entry) {
+      explain.push({ keep: tag, reason: 'unknown WC — keep tag, no CSS edges' });
+      continue;
+    }
+    for (const file of entry.css || []) {
+      cssFiles.add(file);
+      explain.push({ keep: file, reason: `wc ${tag}` });
+    }
+    for (const peer of entry.peers || []) {
+      if (!seen.has(peer)) queue.push(peer);
+    }
+  }
+
+  return {
+    cssFiles: [...cssFiles].sort(),
+    tags: [...tags].sort(),
+    matchedPrefixes: [...matchedPrefixes].sort(),
+    utilityFiles: [...(graph.utilityFiles || [])],
+    motionFiles: [...(graph.motionFiles || [])],
+    alwaysCss: [...(graph.alwaysCss || [])],
+    explain,
+  };
+}
+
+export function listKnownThemeNames(pkgRoot) {
+  const dir = join(pkgRoot, 'src', 'themes');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.css'))
+    .map((f) => f.replace(/\.css$/, ''))
+    .sort();
+}