@birdapi/velinstyle 0.7.0 → 0.9.0

package/cli/index.js

@@ -15,7 +15,7 @@ const LAYERS = ['tokens', 'reset', 'base', 'a11y', 'layout', 'components', 'util
 
 const LAYER_FILES = {
   tokens: [
-    'tokens/color.css', 'tokens/spacing.css', 'tokens/typography.css',
+    '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',
   ],
@@ -25,6 +25,8 @@ const LAYER_FILES = {
     'a11y/sr-only.css', 'a11y/skip-link.css', 'a11y/reduced-motion.css',
     'a11y/forced-colors.css', 'a11y/skeleton.css', 'a11y/preferences.css',
     'a11y/focus-not-obscured.css', 'a11y/target-size.css', 'a11y/high-contrast-aaa.css',
+    'a11y/authentication.css', 'a11y/consistent-help.css', 'a11y/dragging-alternatives.css',
+    'a11y/focus-appearance.css',
   ],
   security: ['a11y/security.css'],
   layout: [
@@ -47,8 +49,10 @@ const LAYER_FILES = {
     '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/container-style.css', 'utilities/state.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',
   ],
   helpers: ['helpers/helpers.css'],
 };
@@ -79,7 +83,7 @@ function hasFlag(flag, alias) {
 
 function help() {
   console.log(`
-  ${C.bold('VelinStyle CLI')} v0.7.0
+  ${C.bold('VelinStyle CLI')} v0.9.0
 
   ${C.bold('Usage:')}
     velinstyle init                 Create velinstyle.config.js
@@ -90,7 +94,14 @@ function help() {
     velinstyle scan [path]          Security & accessibility scanner
     velinstyle prefix [path]        Add missing velin- prefix (dry-run; use --write)
     velinstyle blueprint [name]     Print HTML blueprint (run: velinstyle blueprint list)
+    velinstyle scaffold "<prompt>"  Generate layout HTML from a text description
+    velinstyle layout <sub>         Responsive layout audit and fixes
+    velinstyle perf <sub>           Performance audit (images, scripts) with --fix
     velinstyle tokens build         Generate CSS variables from tokens.json
+    velinstyle tokens validate      Validate tokens.json schema
+    velinstyle docs generate        Auto-generate Markdown API reference
+    velinstyle meta                 Build agent context (velin-agent.json, llms.txt)
+    velinstyle search index         Build JSON search index for VelinSearch
 
   ${C.bold('Icons subcommands:')}
     icons list                      Show available icon providers
@@ -107,14 +118,39 @@ function help() {
     velinstyle blueprint list       Print all blueprint ids
     velinstyle blueprint <name> [--output, -o <file>]
 
+  ${C.bold('Scaffold (0.8.0):')}
+    velinstyle scaffold "<prompt>"  Compose blueprints from natural language
+    velinstyle scaffold list-intents  Show supported intent keywords
+    velinstyle scaffold "<prompt>" -o out.html [--json]
+
+  ${C.bold('Layout (0.8.0):')}
+    velinstyle layout audit [path]    Report flex/grid/responsive issues
+    velinstyle layout suggest [path]  Audit with fix suggestions
+    velinstyle layout fix [path]      Apply safe fixes (--dry-run default, --write)
+
+  ${C.bold('Performance (0.9.0):')}
+    velinstyle perf audit [path]      Report CLS, lazy-load, script defer issues
+    velinstyle perf suggest [path]    Same as audit with fix hints
+    velinstyle perf fix [path]        Apply safe fixes (--write)
+
   ${C.bold('Tokens:')}
     velinstyle tokens build [--input <path>] [--output, -o <file>]
+    velinstyle tokens validate [--input <path>]
+
+  ${C.bold('Docs (0.9.0):')}
+    velinstyle docs generate [--scope all|components|tokens|utilities|cli|rules|a11y|meta] [--out docs/generated]
+    velinstyle meta [--out dist/velin-agent.json] [--llms-out dist/llms.txt] [--base-url URL]
+    velinstyle meta page <file.html> [--write]
+
+  ${C.bold('Search:')}
+    velinstyle search index [--out dist/search-index.json] [--extra-html dir1,dir2]
 
   ${C.bold('Scan options:')}
     --fix                           Auto-fix safe issues (writes files)
     --fix-dry-run                   Show files that would be auto-fixed; no write
     --fix-lang <code>               Default lang for a11y/html-lang fix (default: de)
     --severity <level>              Minimum severity: error, warning, info
+    --only <category>               Filter: security, pii, a11y, css, perf
 
   ${C.bold('Prefix options (velinstyle prefix):')}
     --write                         Write files (default is dry-run)
@@ -457,15 +493,66 @@ async function tokensBuildCmd() {
   }
 }
 
+async function tokensValidateCmd() {
+  const input = getArg('--input') || 'examples/tokens.sample.json';
+  const { validateTokensJson } = await import('./tokens-validate.js');
+  const result = validateTokensJson(resolve(input));
+  if (result.ok) {
+    console.log(C.green(`Valid: ${resolve(input)}`));
+    process.exit(0);
+  }
+  console.log(C.red(`Invalid: ${resolve(input)}`));
+  result.errors.forEach((e) => console.log(`  - ${e}`));
+  process.exit(1);
+}
+
 async function tokensCmd() {
   const sub = args[1];
   if (sub === 'build') {
     await tokensBuildCmd();
+  } else if (sub === 'validate') {
+    await tokensValidateCmd();
   } else {
-    console.log('Usage: velinstyle tokens build [--input tokens.json] [--output out.css]');
+    console.log('Usage: velinstyle tokens build|validate [--input tokens.json] [--output, -o <file>]');
   }
 }
 
+async function perfCmd() {
+  const sub = args[1] || 'audit';
+  const rawTarget = args[2] && !args[2].startsWith('-') ? args[2] : '.';
+  const targetPath = resolve(rawTarget);
+  const asJson = hasFlag('--json');
+  const write = hasFlag('--write');
+  const dryRun = hasFlag('--dry-run') || !write;
+
+  const { auditPath, formatTextReport, fixPath } = await import('./perf-audit.js');
+
+  if (sub === 'fix') {
+    const result = fixPath(targetPath, { write, dryRun });
+    if (asJson) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    if (result.changes.length === 0) {
+      console.log(C.green('No safe performance fixes to apply.'));
+      return;
+    }
+    for (const c of result.changes) {
+      console.log(`${dryRun ? '[dry-run] ' : ''}${c.file}`);
+      c.changes.forEach((ch) => console.log(C.dim(`  - ${ch}`)));
+    }
+    return;
+  }
+
+  const { issues, files } = auditPath(targetPath);
+  if (asJson) {
+    console.log(JSON.stringify({ files, issues }, null, 2));
+    return;
+  }
+  console.log(formatTextReport(issues, files));
+  process.exit(issues.some((x) => x.severity === 'error') ? 1 : 0);
+}
+
 async function prefixCmd() {
   const rawTarget = args[1] && !args[1].startsWith('-') ? args[1] : '.';
   const targetPath = resolve(rawTarget);
@@ -497,6 +584,142 @@ async function prefixCmd() {
   }
 }
 
+async function scaffoldCmd() {
+  const sub = args[1];
+  const { scaffoldFromPrompt, listIntents } = await import('./scaffold.js');
+  if (sub === 'list-intents') {
+    console.log(`\n  ${C.bold('Scaffold intents:')}\n`);
+    for (const i of listIntents()) {
+      console.log(`    ${C.cyan(i.id)} — ${i.blueprints.join(' + ')}`);
+      console.log(C.dim(`      keywords: ${i.keywords.slice(0, 5).join(', ')}…`));
+    }
+    console.log('');
+    return;
+  }
+  const promptParts = [];
+  let i = 1;
+  while (i < args.length) {
+    const a = args[i];
+    if (a.startsWith('-')) break;
+    if (a !== 'scaffold') promptParts.push(a);
+    i += 1;
+  }
+  const prompt = promptParts.join(' ').trim() || sub;
+  if (!prompt || prompt === 'list-intents') {
+    console.log('Usage: velinstyle scaffold "<description>" [-o file.html] [--json]');
+    return;
+  }
+  const r = scaffoldFromPrompt(prompt);
+  if (!r.ok) {
+    console.log(C.red(r.error));
+    process.exit(1);
+  }
+  const out = getArg('--output', '-o');
+  const asJson = hasFlag('--json');
+  if (asJson) {
+    console.log(JSON.stringify(r, null, 2));
+  } else if (out) {
+    writeFileSync(resolve(out), r.html, 'utf-8');
+    console.log(C.green(`Wrote ${resolve(out)} (intent: ${r.intent}, ${r.confidence})`));
+    if (r.responsiveHints?.length) {
+      console.log(C.yellow(`  ${r.responsiveHints.length} layout hint(s) — run: velinstyle layout suggest ${out}`));
+    }
+  } else {
+    console.log(r.html);
+  }
+}
+
+async function layoutCmd() {
+  const sub = args[1] || 'audit';
+  const rawTarget = args[2] && !args[2].startsWith('-') ? args[2] : '.';
+  const targetPath = resolve(rawTarget);
+  const asJson = hasFlag('--json');
+  const write = hasFlag('--write');
+  const dryRun = hasFlag('--dry-run') || !write;
+
+  const { auditPath, suggestFromIssues, formatTextReport, fixPath } = await import('./layout-audit.js');
+
+  if (sub === 'fix') {
+    const result = fixPath(targetPath, { write, dryRun });
+    if (!result.ok) {
+      console.log(C.red(result.error || 'Fix failed'));
+      process.exit(1);
+    }
+    if (asJson) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    if (result.changes.length === 0) {
+      console.log(C.green('No safe fixes to apply.'));
+      return;
+    }
+    for (const c of result.changes) {
+      console.log(`${dryRun ? '[dry-run] ' : ''}${c.file}`);
+      c.changes.forEach((ch) => console.log(C.dim(`  - ${ch}`)));
+    }
+    return;
+  }
+
+  const { issues, files } = auditPath(targetPath);
+  const outIssues = sub === 'suggest' ? suggestFromIssues(issues) : issues;
+
+  if (asJson) {
+    console.log(JSON.stringify({ files, issues: outIssues }, null, 2));
+    return;
+  }
+
+  console.log(formatTextReport(outIssues, files));
+  if (sub === 'suggest' && issues.length) {
+    console.log(C.bold('Suggested fixes:'));
+    for (const i of outIssues) {
+      console.log(`  [${i.id}] ${i.fix}`);
+      if (i.responsive?.mobile) {
+        console.log(C.dim(`    mobile: ${i.responsive.mobile}`));
+      }
+    }
+    console.log('');
+  }
+  process.exit(issues.some((x) => x.severity === 'error') ? 1 : 0);
+}
+
+async function docsCmd() {
+  const sub = args[1];
+  if (sub === 'generate') {
+    const scope = getArg('--scope') || 'all';
+    const out = getArg('--out') || join(PKG_ROOT, 'docs', 'generated');
+    const { generateDocs } = await import('./docs-generate.js');
+    const result = await generateDocs({ scope, outDir: resolve(out), searchIndex: true });
+    if (!result.ok) {
+      console.log(C.red(result.error));
+      process.exit(1);
+    }
+    console.log(C.green(`Generated ${result.written} file(s) → ${resolve(out)}`));
+    return;
+  }
+  console.log('Usage: velinstyle docs generate [--scope all|components|tokens|utilities|cli|rules|a11y|meta] [--out <dir>]');
+}
+
+async function metaCmd() {
+  const { metaMain } = await import('./meta.js');
+  await metaMain(process.argv.slice(2));
+}
+
+async function searchCmd() {
+  const sub = args[1];
+  if (sub === 'index') {
+    const out = getArg('--out') || join(PKG_ROOT, 'dist', 'search-index.json');
+    const extra = getArg('--extra-html');
+    const { buildSearchIndex } = await import('./search-index.js');
+    const result = buildSearchIndex({
+      outFile: resolve(out),
+      extraHtmlDirs: extra ? extra.split(',').map((p) => resolve(p.trim())) : [],
+    });
+    console.log(C.green(`Search index: ${result.count} entries → ${result.outFile}`));
+    return;
+  }
+  console.log('Usage: velinstyle search index [--out <file>] [--extra-html dir1,dir2]');
+}
+
 async function scanCmd() {
   const targetPath = args[1] && !args[1].startsWith('-') ? resolve(args[1]) : resolve('.');
   const format = getArg('--format') || 'text';
@@ -508,6 +731,7 @@ async function scanCmd() {
     fixLang = 'de';
   }
   const severity = getArg('--severity') || 'warning';
+  const only = getArg('--only');
 
   const { scan } = await import('./scanner.js');
   const exitCode = scan(targetPath, {
@@ -516,6 +740,7 @@ async function scanCmd() {
     fixDryRun,
     fixLang: fixLang || undefined,
     format,
+    only,
   });
   process.exit(exitCode);
 }
@@ -532,6 +757,12 @@ switch (command) {
   case 'tokens': await tokensCmd(); break;
   case 'scan': scanCmd(); break;
   case 'prefix': await prefixCmd(); break;
+  case 'scaffold': await scaffoldCmd(); break;
+  case 'layout': await layoutCmd(); break;
+  case 'perf': await perfCmd(); break;
+  case 'docs': await docsCmd(); break;
+  case 'meta': await metaCmd(); break;
+  case 'search': await searchCmd(); break;
   case '--help': case '-h': help(); break;
   default: help(); break;
 }

package/cli/layout-audit.js

@@ -0,0 +1,325 @@
+/**
+ * Static layout audit for VelinStyle HTML — flex/grid, containers, responsive display.
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync, statSync } from 'fs';
+import { join, extname, relative } from 'path';
+
+const DEFAULT_IGNORE = ['node_modules', 'dist', '.git', '.next', '.nuxt', 'vendor', 'build'];
+
+export function walkHtmlFiles(dir, ignore = DEFAULT_IGNORE) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (ignore.includes(entry.name)) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkHtmlFiles(full, ignore));
+    } else if (extname(entry.name).toLowerCase() === '.html') {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function lineOf(content, index) {
+  return content.slice(0, index).split('\n').length;
+}
+
+function extractClassTokens(html) {
+  const tokens = new Set();
+  const re = /class\s*=\s*["']([^"']+)["']/gi;
+  let m;
+  while ((m = re.exec(html)) !== null) {
+    for (const c of m[1].split(/\s+/)) {
+      if (c) tokens.add(c);
+    }
+  }
+  return tokens;
+}
+
+function hasAnyClass(tokens, patterns) {
+  return patterns.some((p) => {
+    if (typeof p === 'string') return tokens.has(p);
+    return [...tokens].some((t) => p.test(t));
+  });
+}
+
+/** @typedef {{ id: string, severity: string, message: string, line?: number, file?: string, suggestions?: object, responsive?: object }} LayoutIssue */
+
+/**
+ * @param {string} html
+ * @param {{ file?: string }} meta
+ * @returns {LayoutIssue[]}
+ */
+export function auditHtml(html, meta = {}) {
+  const issues = [];
+  const file = meta.file || '';
+  const classes = extractClassTokens(html);
+  const classStr = html;
+
+  // velin-col-* without velin-row in nearby context (heuristic: same file has col but no row)
+  const hasCol = /\bvelin-(?:sm-|md-|lg-|xl-)?col(?:-\d+)?\b/.test(classStr);
+  const hasRow = /\bvelin-row\b/.test(classStr);
+  if (hasCol && !hasRow) {
+    const idx = classStr.search(/\bvelin-(?:sm-|md-|lg-|xl-)?col/);
+    issues.push({
+      id: 'grid-missing-row',
+      severity: 'warning',
+      message: 'Column classes (velin-col-*) found without a parent velin-row.',
+      line: idx >= 0 ? lineOf(html, idx) : undefined,
+      file,
+      suggestions: { addClasses: ['velin-row', 'velin-g-4'] },
+      responsive: {
+        mobile: 'Stack columns: velin-flex velin-flex--col on small screens or use velin-grid.',
+        tablet: 'velin-row with velin-md-col-* at 48rem+.',
+        desktop: 'velin-row + velin-col-* for 12-column layout.',
+      },
+    });
+  }
+
+  // flex without wrap and many flex children (heuristic: 6+ velin-btn or 8+ class on flex container)
+  const flexNoWrap =
+    /\bvelin-flex\b/.test(classStr) &&
+    !/\bvelin-flex--wrap\b/.test(classStr) &&
+    (classStr.match(/<a\b/gi)?.length || 0) + (classStr.match(/<button\b/gi)?.length || 0) >= 4;
+  if (flexNoWrap) {
+    issues.push({
+      id: 'flex-no-wrap-overflow',
+      severity: 'warning',
+      message: 'Flex layout without velin-flex--wrap may overflow on narrow viewports.',
+      file,
+      suggestions: { addClasses: ['velin-flex--wrap'], alt: ['velin-overflow-x-auto'] },
+      responsive: {
+        mobile: 'Add velin-flex--wrap or velin-flex--col for stacked mobile nav.',
+        tablet: 'velin-flex--wrap with velin-gap-4.',
+        desktop: 'Keep row layout with wrap for many items.',
+      },
+    });
+  }
+
+  // main or section without container
+  const hasMainOrSection = /<(?:main|section)\b/i.test(html);
+  const hasContainer = /\bvelin-container\b/.test(classStr);
+  if (hasMainOrSection && !hasContainer) {
+    issues.push({
+      id: 'missing-container',
+      severity: 'info',
+      message: 'Page sections without velin-container may span edge-to-edge unintentionally.',
+      file,
+      suggestions: { wrapWith: 'velin-container', alt: ['velin-container--fluid'] },
+      responsive: {
+        mobile: 'velin-container keeps readable padding on phones.',
+        tablet: 'Same container max-width scales at 48rem / 62rem breakpoints.',
+        desktop: 'Use velin-container--wide for marketing pages if needed.',
+      },
+    });
+  }
+
+  // velin-hidden without responsive show (velin-md-block etc.)
+  if (hasAnyClass(classes, ['velin-hidden']) && !hasAnyClass(classes, [/^velin-(?:sm|md|lg)-(?:block|flex|grid|inline)/])) {
+    const idx = classStr.indexOf('velin-hidden');
+    issues.push({
+      id: 'mobile-hidden-only',
+      severity: 'warning',
+      message: 'velin-hidden without a matching velin-md-block / velin-md-flex (element may stay hidden on all breakpoints).',
+      line: idx >= 0 ? lineOf(html, idx) : undefined,
+      file,
+      suggestions: { pairWith: ['velin-hidden', 'velin-md-flex'], example: 'velin-hidden velin-md-flex' },
+      responsive: {
+        mobile: 'Hidden on default (mobile-first).',
+        tablet: 'Show from md (48rem) with velin-md-flex or velin-md-block.',
+        desktop: 'Adjust with velin-lg-* if needed.',
+      },
+    });
+  }
+
+  // desktop-only nav without mobile alternative hint
+  const desktopOnlyNav =
+    /\bvelin-desktop-only\b/.test(classStr) &&
+    /<nav\b/i.test(html) &&
+    !/\bvelin-mobile-only\b/.test(classStr) &&
+    !/bottom-nav|velin-bottom-nav/i.test(classStr);
+  if (desktopOnlyNav) {
+    issues.push({
+      id: 'desktop-nav-no-mobile',
+      severity: 'info',
+      message: 'Desktop-only navigation detected; consider velin-mobile-only + bottom-nav-mobile blueprint for phones.',
+      file,
+      suggestions: { blueprint: 'bottom-nav-mobile', addClasses: ['velin-mobile-only'] },
+      responsive: {
+        mobile: 'Use blueprint bottom-nav-mobile or velin-mobile-only block.',
+        tablet: 'velin-md-flex for nav from 48rem.',
+        desktop: 'velin-desktop-only for wide layouts.',
+      },
+    });
+  }
+
+  // 100vw
+  if (/100vw|width:\s*100vw/i.test(html)) {
+    issues.push({
+      id: 'viewport-width',
+      severity: 'warning',
+      message: '100vw can cause horizontal scroll; prefer velin-w-full inside velin-container.',
+      file,
+      suggestions: { replaceWith: 'velin-w-full', wrapWith: 'velin-container' },
+      responsive: {
+        mobile: 'Avoid 100vw; use container + full width children.',
+        tablet: '—',
+        desktop: '—',
+      },
+    });
+  }
+
+  // sticky + overflow hidden on same element or parent snippet
+  if (
+    (/position:\s*sticky|velin-position-sticky/i.test(html)) &&
+    (/overflow:\s*hidden|velin-overflow-hidden/i.test(html))
+  ) {
+    issues.push({
+      id: 'sticky-overflow-parent',
+      severity: 'warning',
+      message: 'Sticky positioning may not work when an ancestor uses overflow: hidden.',
+      file,
+      suggestions: { doc: 'Remove overflow:hidden from sticky ancestors or use velin-position-sticky on a different wrapper.' },
+      responsive: { mobile: 'Test sticky headers on iOS Safari.', tablet: '—', desktop: '—' },
+    });
+  }
+
+  // table without responsive wrapper
+  if (/<table\b/i.test(html) && !/\btable-responsive\b|velin-table-responsive|overflow-x-auto|velin-overflow-x-auto/i.test(html)) {
+    issues.push({
+      id: 'table-not-responsive',
+      severity: 'info',
+      message: 'Tables should scroll horizontally on small screens (blueprint table-responsive or velin-overflow-x-auto).',
+      file,
+      suggestions: { blueprint: 'table-responsive', wrapWith: 'velin-overflow-x-auto' },
+      responsive: {
+        mobile: 'Wrap table in scroll container.',
+        tablet: 'Full table visible from md if columns fit.',
+        desktop: '—',
+      },
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * @param {string} targetPath file or directory
+ * @returns {{ issues: LayoutIssue[], files: string[] }}
+ */
+export function auditPath(targetPath) {
+  let files = [];
+  if (!existsSync(targetPath)) {
+    return { issues: [], files: [] };
+  }
+  const st = statSync(targetPath);
+  if (st.isFile()) {
+    files = extname(targetPath).toLowerCase() === '.html' ? [targetPath] : [];
+  } else {
+    files = walkHtmlFiles(targetPath);
+  }
+
+  const issues = [];
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    issues.push(...auditHtml(html, { file }));
+  }
+  return { issues, files };
+}
+
+/**
+ * @param {LayoutIssue[]} issues
+ */
+export function suggestFromIssues(issues) {
+  return issues.map((i) => ({
+    ...i,
+    fix:
+      i.suggestions?.addClasses?.length ?
+        `Add classes: ${i.suggestions.addClasses.join(', ')}`
+      : i.suggestions?.pairWith ?
+        `Use: ${i.suggestions.pairWith.join(' ')}`
+      : i.suggestions?.wrapWith ?
+        `Wrap content in <div class="${i.suggestions.wrapWith}">…</div>`
+      : i.suggestions?.blueprint ?
+        `Consider blueprint: ${i.suggestions.blueprint}`
+      : i.suggestions?.doc || 'See responsive-layout guide.',
+  }));
+}
+
+/**
+ * Whitelisted safe fixes on HTML string.
+ * @returns {{ html: string, changes: string[] }}
+ */
+export function applySafeFixes(html) {
+  const changes = [];
+  let out = html;
+
+  // Add velin-flex--wrap to velin-flex that lacks wrap/nowrap
+  out = out.replace(
+    /class\s*=\s*["']([^"']*\bvelin-flex\b[^"']*)["']/gi,
+    (match, cls) => {
+      if (/\bvelin-flex--(?:wrap|nowrap)\b/.test(cls)) return match;
+      changes.push('Added velin-flex--wrap to flex container');
+      return `class="${cls} velin-flex--wrap"`;
+    },
+  );
+
+  // velin-hidden alone on same element -> add velin-md-block (conservative: only if exactly velin-hidden)
+  out = out.replace(
+    /class\s*=\s*["']velin-hidden["']/gi,
+    () => {
+      changes.push('Paired velin-hidden with velin-md-block');
+      return 'class="velin-hidden velin-md-block"';
+    },
+  );
+
+  // Wrap bare <main> children - skip (too invasive)
+
+  return { html: out, changes };
+}
+
+/**
+ * @param {string} targetPath
+ * @param {{ write?: boolean, dryRun?: boolean }} opts
+ */
+export function fixPath(targetPath, opts = {}) {
+  const { issues, files } = auditPath(targetPath);
+  if (files.length === 0) {
+    return { ok: false, error: 'No HTML files found.', changes: [] };
+  }
+
+  const allChanges = [];
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    const { html: next, changes } = applySafeFixes(html);
+    if (changes.length) {
+      allChanges.push({ file, changes });
+      if (opts.write && !opts.dryRun) {
+        writeFileSync(file, next, 'utf-8');
+      }
+    }
+  }
+
+  return { ok: true, issues, changes: allChanges, dryRun: !!opts.dryRun && !opts.write };
+}
+
+export function formatTextReport(issues, files) {
+  const lines = [];
+  lines.push(`\nLayout audit: ${files.length} file(s), ${issues.length} issue(s)\n`);
+  if (issues.length === 0) {
+    lines.push('  No layout issues detected.\n');
+    return lines.join('\n');
+  }
+  for (const i of issues) {
+    const loc = i.file ? ` ${relative(process.cwd(), i.file)}` : '';
+    const ln = i.line ? `:${i.line}` : '';
+    lines.push(`  [${i.severity.toUpperCase()}] ${i.id}${loc}${ln}`);
+    lines.push(`    ${i.message}`);
+    if (i.suggestions?.addClasses) {
+      lines.push(`    → Add: ${i.suggestions.addClasses.join(', ')}`);
+    }
+  }
+  lines.push('');
+  return lines.join('\n');
+}