@birdapi/velinstyle 1.0.0 → 1.2.0

package/cli/meta.js

@@ -29,6 +29,31 @@ export async function buildMeta(options = {}) {
     written.push(llmsFile);
   }
 
+  // JSON twins for agents (pages, sections, knowledge, constraints)
+  const twinDir = join(PKG_ROOT, 'docs', 'generated', 'intelligence');
+  mkdirSync(twinDir, { recursive: true });
+  const twins = {
+    'pages.json': bundle.knowledgeGraph?.pages || [],
+    'sections.json': bundle.knowledgeGraph?.sections || [],
+    'components.json': bundle.knowledgeGraph?.components || [],
+    'design-constraints.json': bundle.knowledgeGraph?.designConstraints || [],
+    'index.json': {
+      version: bundle.framework.version,
+      generatedAt: bundle.generatedAt,
+      pageCount: bundle.knowledgeGraph?.pageCount || 0,
+      sectionCount: bundle.knowledgeGraph?.sectionCount || 0,
+      componentCount: bundle.knowledgeGraph?.componentCount || 0,
+      constraintCount: bundle.knowledgeGraph?.designConstraints?.length || 0,
+      agentBundle: 'dist/velin-agent.json',
+      llmsTxt: 'dist/llms.txt',
+    },
+  };
+  for (const [name, data] of Object.entries(twins)) {
+    const target = join(twinDir, name);
+    writeFileSync(target, JSON.stringify(data, null, 2), 'utf-8');
+    written.push(target);
+  }
+
   return { ok: true, bundle, written, count: written.length };
 }
 
@@ -43,7 +68,30 @@ export function metaPage(htmlPath, options = {}) {
   }
   const html = readFileSync(abs, 'utf-8');
   const rel = htmlPath.replace(/\\/g, '/');
-  const meta = buildPageMeta(html, rel, PKG_ROOT);
+  let meta = buildPageMeta(html, rel, PKG_ROOT);
+
+  // Merge curated fields from existing velin-meta so --write does not clobber goals/intent.
+  const existingMatch = html.match(
+    /<script[^>]*id=["']velin-meta["'][^>]*>([\s\S]*?)<\/script>/i,
+  );
+  if (existingMatch) {
+    try {
+      const prev = JSON.parse(existingMatch[1]);
+      meta = mergePageMeta(prev, meta);
+      if (options.write && meta._droppedKeys?.length) {
+        console.warn(
+          `velin-meta --write: dropping non-allowlisted keys: ${meta._droppedKeys.join(', ')} ` +
+            `(kept: ${[...META_MERGE_ALLOWLIST].join(', ')})`,
+        );
+      }
+      delete meta._droppedKeys;
+    } catch {
+      /* keep generated meta */
+    }
+  } else {
+    delete meta._droppedKeys;
+  }
+
   const script = serializePageMetaScript(meta);
 
   if (options.write) {
@@ -63,6 +111,41 @@ export function metaPage(htmlPath, options = {}) {
   return { ok: true, meta, script };
 }
 
+/** Keys preserved from previous velin-meta on --write (plus nested page.*). */
+const META_MERGE_ALLOWLIST = new Set([
+  'page', 'goals', 'intent', 'notes', 'curated', 'id', 'title',
+]);
+
+/** Preserve curated page goals/intent while refreshing component inventory. */
+function mergePageMeta(prev, next) {
+  const out = { ...next };
+  const dropped = [];
+  if (prev && typeof prev === 'object') {
+    for (const key of Object.keys(prev)) {
+      if (!META_MERGE_ALLOWLIST.has(key) && !(key in next)) {
+        dropped.push(key);
+      }
+    }
+    out.page = { ...(next.page || {}), ...(prev.page || {}), ...(next.page || {}) };
+    if (prev.page?.intent) out.page.intent = prev.page.intent;
+    if (prev.page?.goals) out.page.goals = prev.page.goals;
+    if (prev.page?.title) out.page.title = prev.page.title;
+    if (prev.page?.id) out.page.id = prev.page.id;
+    if (prev.goals) out.goals = prev.goals;
+    if (prev.intent) out.intent = prev.intent;
+    if (prev.notes) out.notes = prev.notes;
+    if (prev.curated) out.curated = prev.curated;
+    if (prev.id && !out.id) out.id = prev.id;
+  }
+  out.allowed = next.allowed;
+  out.attributes = next.attributes;
+  out.a11y = next.a11y;
+  out.version = next.version;
+  out.mime = next.mime;
+  out._droppedKeys = dropped;
+  return out;
+}
+
 export async function metaMain(argv = process.argv.slice(2)) {
   const pageIdx = argv.indexOf('page');
   if (pageIdx !== -1 && argv[pageIdx + 1]) {

package/cli/perf-audit.js

@@ -1,7 +1,7 @@
 /**
  * Performance audit for static HTML — images, scripts, inline styles.
  */
-import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
 import { join, extname, relative } from 'path';
 
 const DEFAULT_IGNORE = ['node_modules', 'dist', '.git', '.next', 'build'];
@@ -18,6 +18,19 @@ export function walkHtmlFiles(dir, ignore = DEFAULT_IGNORE) {
   return results;
 }
 
+/** Accept a single .html file or a directory. */
+function collectHtmlFiles(targetPath, ignore = DEFAULT_IGNORE) {
+  if (!existsSync(targetPath)) return [];
+  const st = statSync(targetPath);
+  if (st.isFile()) {
+    return extname(targetPath).toLowerCase() === '.html' ? [targetPath] : [];
+  }
+  if (st.isDirectory()) {
+    return walkHtmlFiles(targetPath, ignore);
+  }
+  return [];
+}
+
 function lineOf(content, index) {
   return content.slice(0, index).split('\n').length;
 }
@@ -118,7 +131,7 @@ export function auditHtml(html, meta = {}) {
 }
 
 export function auditPath(targetPath) {
-  const files = walkHtmlFiles(targetPath);
+  const files = collectHtmlFiles(targetPath);
   const issues = [];
   for (const file of files) {
     const html = readFileSync(file, 'utf-8');

package/cli/prompt-engine.js

@@ -0,0 +1,243 @@
+/**
+ * Prompt Engine — plan before HTML.
+ * Order: Mensch → Framework → KI (page registry + section graphs).
+ */
+import { readFileSync, existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { emitBlueprint } from './blueprint.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+const PKG_VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8')).version;
+
+function readJson(rel) {
+  const p = join(ROOT, rel);
+  if (!existsSync(p)) return null;
+  return JSON.parse(readFileSync(p, 'utf-8'));
+}
+
+function loadPages() {
+  return readJson('core/meta/pages/registry.json')?.pages || [];
+}
+
+function loadSections() {
+  return readJson('core/meta/sections/registry.json')?.sections || [];
+}
+
+function loadConstraintPack(id) {
+  const file = join(ROOT, 'core/meta/design-constraints', `${id}.json`);
+  if (!existsSync(file)) return null;
+  return JSON.parse(readFileSync(file, 'utf-8'));
+}
+
+function mapSectionToBlueprint(sectionId) {
+  const map = {
+    hero: 'hero-section',
+    'trust-bar': 'trust-bar',
+    benefits: 'benefits-grid',
+    services: 'services-grid',
+    process: 'process-steps',
+    testimonials: 'testimonials',
+    pricing: 'pricing-table',
+    faq: 'faq-section',
+    contact: 'form-contact',
+    cta: 'cta-band',
+    footer: 'footer-simple',
+    navbar: 'navbar-header',
+  };
+  return map[sectionId] || sectionId;
+}
+
+/**
+ * @param {string} prompt
+ */
+export function analyzePrompt(prompt) {
+  const lower = (prompt || '').toLowerCase();
+  const pages = loadPages();
+  let best = null;
+  let bestScore = 0;
+  for (const page of pages) {
+    let score = 0;
+    for (const kw of page.promptKeywords || []) {
+      if (lower.includes(kw.toLowerCase())) score += kw.length;
+    }
+    if (score > bestScore) {
+      bestScore = score;
+      best = page;
+    }
+  }
+
+  const audience =
+    /patient|clinic|healthcare|praxis/i.test(prompt) ? 'patients'
+      : /developer|docs|api/i.test(prompt) ? 'developers'
+        : /buyer|shop|store/i.test(prompt) ? 'buyers'
+          : 'prospects';
+
+  const conversionGoal =
+    /contact|beratung|consultation|anfrage|kontakt/i.test(prompt) ? 'contact form'
+      : /signup|trial|register/i.test(prompt) ? 'signup'
+        : best?.conversionGoal || 'lead';
+
+  return {
+    intent: best ? `page:${best.id}` : 'page:landing',
+    targetAudience: audience,
+    businessType: best?.businessType || 'general',
+    pageGoal: best?.pageGoal || 'explain offer and convert',
+    conversionGoal,
+    pageId: best?.id || 'landing',
+    confidence: bestScore > 0 ? 'high' : 'low',
+  };
+}
+
+/**
+ * @param {ReturnType<typeof analyzePrompt>} analysis
+ * @param {string} prompt
+ */
+export function buildPlan(analysis, prompt) {
+  const pages = loadPages();
+  const sectionsMeta = loadSections();
+  const page = pages.find((p) => p.id === analysis.pageId) || pages.find((p) => p.id === 'landing');
+  const lower = (prompt || '').toLowerCase();
+
+  const sections = [...(page?.requiredSections || [])];
+  for (const opt of page?.optionalSections || []) {
+    if (opt === 'pricing' && /pric|tarif|abo/i.test(lower) && !sections.includes(opt)) {
+      sections.splice(Math.max(sections.length - 2, 0), 0, opt);
+    }
+    if (opt === 'trust-bar' && /trust|kunden|marken/i.test(lower) && !sections.includes(opt)) {
+      sections.splice(1, 0, opt);
+    }
+    if (opt === 'process' && /process|ablauf|how it works|schritte/i.test(lower) && !sections.includes(opt)) {
+      sections.splice(Math.min(4, sections.length), 0, opt);
+    }
+    if (opt === 'contact' && /contact|kontakt|formular/i.test(lower) && !sections.includes(opt)) {
+      sections.splice(Math.max(sections.length - 1, 0), 0, opt);
+    }
+  }
+
+  if (/kontakt|contact|formular|steuerberater|leistungen/i.test(lower) && !sections.includes('contact')) {
+    sections.splice(Math.max(sections.length - 1, 0), 0, 'contact');
+  }
+
+  const uniqueSections = [...new Set(sections)];
+  const resolved = uniqueSections.map((id) => {
+    const meta = sectionsMeta.find((s) => s.id === id);
+    return {
+      id,
+      role: meta?.role || id,
+      blueprint: mapSectionToBlueprint(id),
+      designRules: meta?.designRules || [],
+      a11yRules: meta?.a11yRules || [],
+      seoRules: meta?.seoRules || [],
+    };
+  });
+
+  const constraints = ['hero', 'faq', 'contact']
+    .map(loadConstraintPack)
+    .filter(Boolean);
+
+  return {
+    version: 1,
+    analysis,
+    page: {
+      id: page?.id,
+      name: page?.name,
+      seoIntent: page?.seoIntent,
+      defaultTone: page?.defaultTone,
+      recommendedComponents: page?.recommendedComponents || [],
+    },
+    sections: resolved,
+    layout: {
+      container: 'velin-container',
+      density: ['dashboard', 'crm', 'erp'].includes(page?.id) ? 'data-dense' : 'comfortable',
+    },
+    designConstraints: constraints,
+    accessibility: {
+      checklist: [
+        'One H1',
+        'Labeled form fields',
+        'Focus-visible controls',
+        'Respect prefers-reduced-motion',
+      ],
+      risks: page?.accessibilityRisks || [],
+    },
+    seo: {
+      intent: page?.seoIntent,
+      notes: ['Meaningful H1', 'Section H2s', 'Descriptive link text'],
+    },
+    warnings: analysis.confidence === 'low'
+      ? ['Low page-type confidence — defaulted to landing. Refine prompt with business type keywords.']
+      : [],
+  };
+}
+
+/**
+ * @param {object} plan
+ * @param {{ brand?: string, title?: string, cta?: string }} slots
+ */
+export function renderPlan(plan, slots = {}) {
+  const parts = [];
+  const missing = [];
+  for (const section of plan.sections || []) {
+    const emitId = section.blueprint || mapSectionToBlueprint(section.id);
+    const r = emitBlueprint(emitId);
+    if (!r.ok) {
+      missing.push(`${section.id}: ${r.error}`);
+      continue;
+    }
+    parts.push(r.text);
+  }
+
+  let html = parts.join('\n\n');
+  if (slots.brand) html = html.replace(/\bBrand\b/g, slots.brand);
+  if (slots.title) html = html.replace(/>Headline</g, `>${slots.title}<`);
+  if (slots.cta) {
+    html = html.replace(/Primary CTA/g, slots.cta);
+    html = html.replace(/Request a consultation/g, slots.cta);
+    html = html.replace(/Kontakt aufnehmen/g, slots.cta);
+  }
+
+  const doc = `<!DOCTYPE html>
+<html lang="de" data-velin-theme="light">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${slots.title || plan.page?.name || 'VelinStyle page'}</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@birdapi/velinstyle@${PKG_VERSION}/dist/velinstyle.min.css">
+</head>
+<body>
+${html}
+<script type="module">
+  import { bootFromDOM } from 'https://cdn.jsdelivr.net/npm/@birdapi/velinstyle@${PKG_VERSION}/+esm';
+  bootFromDOM();
+</script>
+</body>
+</html>
+`;
+
+  return { html: doc, missing };
+}
+
+/**
+ * @param {string} prompt
+ */
+export function planFromPrompt(prompt) {
+  if (!prompt?.trim()) return { ok: false, error: 'Prompt is required.' };
+  const analysis = analyzePrompt(prompt);
+  const plan = buildPlan(analysis, prompt);
+  const slots = {
+    brand: 'Brand',
+    title: /steuerberater/i.test(prompt) ? 'Steuerberatung mit Klarheit' : 'Headline',
+    cta: /kontakt|consultation|beratung/i.test(prompt) ? 'Kontakt aufnehmen' : 'Primary CTA',
+  };
+  const rendered = renderPlan(plan, slots);
+  return {
+    ok: true,
+    analysis,
+    plan,
+    html: rendered.html,
+    missing: rendered.missing,
+    warnings: plan.warnings,
+  };
+}

package/cli/review.js

@@ -0,0 +1,268 @@
+/**
+ * Review Engine — design / a11y / seo / performance / conversion / prompt score.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+
+const PROFILES = new Set(['marketing', 'app', 'docs', 'fragment', 'ecommerce']);
+
+function loadConstraint(id) {
+  const p = join(ROOT, 'core/meta/design-constraints', `${id}.json`);
+  if (!existsSync(p)) return null;
+  return JSON.parse(readFileSync(p, 'utf-8'));
+}
+
+/** Strip non-DOM noise so review heuristics do not count meta JSON or code demos. */
+function stripNonRenderableHtml(html) {
+  return String(html || '')
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<velin-code-block\b[^>]*>[\s\S]*?<\/velin-code-block>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ');
+}
+
+function visibleWordCount(html) {
+  const clean = stripNonRenderableHtml(html)
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&[a-z]+;/gi, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!clean) return 0;
+  return clean.split(' ').filter(Boolean).length;
+}
+
+function detectProfile(html, ctx = {}) {
+  if (ctx.profile && PROFILES.has(ctx.profile)) return ctx.profile;
+  const intent = ctx.plan?.page?.intent || ctx.plan?.page?.id || '';
+  const metaIntent = html.match(/"intent"\s*:\s*"([^"]+)"/)?.[1] || '';
+  const blob = `${intent} ${metaIntent}`.toLowerCase();
+  if (/dashboard|crm|erp|admin|app-shell|auth|login/.test(blob)) return 'app';
+  if (/docs|documentation|guide/.test(blob)) return 'docs';
+  if (/shop|ecommerce|store|checkout|cart/.test(blob)) return 'ecommerce';
+  if (ctx.fragment) return 'fragment';
+  // Short recipe-like HTML without document chrome → fragment
+  if (!/<html\b/i.test(html) && !/<main\b/i.test(html)) return 'fragment';
+  return 'marketing';
+}
+
+/**
+ * Hero scope: explicit hero markers first, else prefix until common section ids.
+ * Counts only real <a>/<button> tags with primary/outline CTA classes.
+ */
+function countHeroCtas(html) {
+  const clean = stripNonRenderableHtml(html);
+  let heroChunk = '';
+  const heroSection =
+    clean.match(/<section\b[^>]*(?:\bid=["']hero["']|data-velin-section=["']hero["'])[^>]*>[\s\S]*?<\/section>/i)
+    || clean.match(/<(?:header|section)\b[^>]*\bid=["']top["'][^>]*>[\s\S]*?<\/(?:header|section)>/i);
+  if (heroSection) {
+    heroChunk = heroSection[0];
+  } else {
+    heroChunk = clean.split(/id=["'](?:services|faq|testimonials)["']/i)[0] || clean.slice(0, 2000);
+  }
+  const ctaRe = /<(?:a|button)\b[^>]*\bvelin-btn--(?:primary|outline)\b[^>]*>/gi;
+  return [...heroChunk.matchAll(ctaRe)].length;
+}
+
+/**
+ * @param {string} html
+ * @param {{ plan?: object, prompt?: string, profile?: string, fragment?: boolean }} [ctx]
+ */
+export function reviewHtml(html, ctx = {}) {
+  const issues = [];
+  const text = html || '';
+  const profile = detectProfile(text, ctx);
+  const isFragment = profile === 'fragment';
+
+  const isMarketing = profile === 'marketing' || profile === 'ecommerce';
+
+  const h1 = [...text.matchAll(/<h1\b/gi)];
+  if (!isFragment) {
+    if (h1.length === 0) {
+      const h1Fix = profile === 'app' || profile === 'docs'
+        ? 'Add a single page H1 in the primary content (header/main) — not necessarily a marketing hero.'
+        : 'Add a single page H1 in the hero.';
+      issues.push({ code: 'a11y.missing-h1', severity: 'error', message: 'Missing H1', fix: h1Fix });
+    } else if (h1.length > 1) {
+      issues.push({ code: 'a11y.multiple-h1', severity: 'warning', message: `Found ${h1.length} H1 elements`, fix: 'Keep exactly one H1.' });
+    }
+  }
+
+  if (!isFragment && !/<html\b[^>]*\blang=/i.test(text) && /<html\b/i.test(text)) {
+    issues.push({
+      code: 'a11y.missing-lang',
+      severity: 'error',
+      message: 'Missing lang on <html>',
+      fix: 'Add lang="en" (or your locale) on <html>.',
+    });
+  }
+
+  if (!isFragment) {
+    const imgs = [...text.matchAll(/<img\b[^>]*>/gi)];
+    for (const m of imgs) {
+      const tag = m[0];
+      if (/\brole=["']presentation["']/i.test(tag) || /\baria-hidden=["']true["']/i.test(tag)) continue;
+      if (!/\balt=/i.test(tag)) {
+        issues.push({
+          code: 'a11y.img-missing-alt',
+          severity: 'error',
+          message: 'Image without alt attribute',
+          fix: 'Add alt text (or alt="" for decorative images).',
+        });
+        break;
+      }
+    }
+  }
+
+  if (/<input\b/i.test(text) && !isFragment) {
+    const inputs = [...text.matchAll(/<input\b[^>]*>/gi)];
+    let unlabeled = 0;
+    for (const m of inputs) {
+      const tag = m[0];
+      if (/\btype=["']hidden["']/i.test(tag)) continue;
+      if (/\baria-label=/i.test(tag) || /\baria-labelledby=/i.test(tag) || /\bid=/i.test(tag)) continue;
+      if (/\bplaceholder=/i.test(tag)) unlabeled += 1;
+    }
+    if (unlabeled > 0 && !/<label\b/i.test(text)) {
+      issues.push({
+        code: 'a11y.unlabeled-input',
+        severity: 'error',
+        message: 'Input(s) without associated label',
+        fix: 'Wire <label for="…"> to each input id (or use aria-label).',
+      });
+    }
+  }
+
+  const ctaPrimary = [...text.matchAll(/velin-btn--primary/g)];
+  if (isMarketing && ctaPrimary.length > 4) {
+    issues.push({ code: 'design.too-many-primary-ctas', severity: 'warning', message: 'Many primary CTAs competing', fix: 'Limit primary CTAs; demote extras to outline/ghost.' });
+  }
+  if (/<form\b/i.test(text)) {
+    const skipFormSummary = profile === 'docs' && /type=["']search["']/i.test(text) && !/<textarea\b/i.test(text);
+    if (!skipFormSummary && !/velin-form-summary/i.test(text)) {
+      issues.push({ code: 'a11y.missing-form-summary', severity: 'error', message: 'Form without velin-form-summary', fix: 'Add <velin-form-summary> before fields.' });
+    }
+    if (/placeholder=/.test(text) && !/<label\b/i.test(text)) {
+      issues.push({ code: 'a11y.placeholder-only', severity: 'error', message: 'Possible placeholder-only fields', fix: 'Use visible <label> elements.' });
+    }
+  }
+
+  if (/id="faq"|FAQ/i.test(text) && !/<(details|velin-accordion)\b/i.test(text)) {
+    issues.push({ code: 'design.faq-not-disclosure', severity: 'warning', message: 'FAQ section without disclosure pattern', fix: 'Use velin-accordion or details/summary.' });
+  }
+
+  if (!isFragment && !/<title\b/i.test(text)) {
+    issues.push({ code: 'seo.missing-title', severity: 'warning', message: 'Missing document title', fix: 'Add a descriptive <title>.' });
+  }
+
+  if (/style="[^"]*background:[^"]*#|color:#[0-9a-f]{3,8}/i.test(text)) {
+    issues.push({ code: 'design.raw-hex', severity: 'warning', message: 'Raw hex colors detected', fix: 'Prefer --velin-color-* tokens.' });
+  }
+
+  if (/animation:\s*[^;]*infinite/i.test(text)) {
+    issues.push({ code: 'perf.infinite-animation', severity: 'warning', message: 'Infinite animation found', fix: 'Avoid infinite motion; respect prefers-reduced-motion.' });
+  }
+
+  // Thin / junk page floors (anti false-confidence)
+  const words = visibleWordCount(text);
+  const hasMain = /<main\b/i.test(text);
+  const mainEmpty = hasMain && /<main\b[^>]*>\s*<\/main>/i.test(text);
+  const thin = !isFragment && (words < 40 || !hasMain || mainEmpty || h1.length === 0);
+
+  if (!isFragment && words < 40) {
+    issues.push({
+      code: 'seo.thin-content',
+      severity: 'warning',
+      message: `Very little visible content (${words} words)`,
+      fix: 'Add meaningful page copy, headings, and sections.',
+    });
+    issues.push({
+      code: 'conversion.thin-page',
+      severity: 'warning',
+      message: 'Page is too thin to score conversion highly',
+      fix: 'Add a clear offer, proof, and primary CTA path.',
+    });
+  }
+  if (!isFragment && (!hasMain || mainEmpty)) {
+    issues.push({
+      code: 'seo.thin-content',
+      severity: 'warning',
+      message: hasMain ? 'Empty <main> landmark' : 'Missing <main> landmark',
+      fix: 'Wrap primary content in <main>.',
+    });
+  }
+
+  const plan = ctx.plan;
+  if (plan?.sections && isMarketing) {
+    const ids = plan.sections.map((s) => s.id);
+    for (const need of ['hero', 'footer']) {
+      if (!ids.includes(need) && /landing|lawyer|saas/i.test(plan.page?.id || '')) {
+        issues.push({ code: `plan.missing-${need}`, severity: 'error', message: `Plan missing section ${need}`, fix: `Include ${need} in page template.` });
+      }
+    }
+  }
+
+  if (ctx.prompt && /steuerberater|lawyer|tax advisor/i.test(ctx.prompt)) {
+    for (const need of ['services', 'testimonials', 'faq', 'contact']) {
+      if (plan && !plan.sections.some((s) => s.id === need)) {
+        issues.push({ code: `conversion.missing-${need}`, severity: 'error', message: `Professional-services page missing ${need}`, fix: `Add ${need} section.` });
+      }
+    }
+  }
+
+  const heroRules = loadConstraint('hero');
+  if (heroRules && isMarketing && /velin-btn--primary/g.test(text)) {
+    const heroCtas = countHeroCtas(text);
+    if (heroCtas > 2) {
+      issues.push({ code: 'design.hero-cta-max', severity: 'error', message: 'Hero exceeds 2 CTAs', fix: 'Keep at most two CTAs in the hero (real <a>/<button> only; scripts and code samples are ignored).' });
+    }
+  }
+
+  const errors = issues.filter((i) => i.severity === 'error').length;
+  const warnings = issues.filter((i) => i.severity === 'warning').length;
+
+  const score = (base, penalty) => Math.max(0, Math.round((base - penalty) * 10) / 10);
+
+  let scores = {
+    design: score(10, errors * 1.5 + warnings * 0.5),
+    accessibility: score(10, issues.filter((i) => i.code.startsWith('a11y')).length * 2),
+    seo: score(10, issues.filter((i) => i.code.startsWith('seo')).length * 2),
+    performance: score(10, issues.filter((i) => i.code.startsWith('perf')).length * 2),
+    conversion: score(10, issues.filter((i) => i.code.startsWith('conversion')).length * 2),
+    visual: score(9, issues.filter((i) => i.code.startsWith('design')).length * 1.2),
+  };
+
+  if (thin) {
+    // Cap soft categories so junk pages cannot claim 10/10
+    scores.seo = Math.min(scores.seo, 4);
+    scores.conversion = Math.min(scores.conversion, 4);
+    scores.design = Math.min(scores.design, 6);
+    scores.visual = Math.min(scores.visual, 5);
+  }
+
+  if (profile === 'app' || profile === 'docs') {
+    // Conversion/SEO marketing heuristics are not the primary signal for app/docs shells
+    scores.conversion = Math.min(scores.conversion, 6);
+    if (profile === 'app') scores.seo = Math.min(scores.seo, 7);
+  }
+
+  const avg = Object.values(scores).reduce((a, b) => a + b, 0) / Object.values(scores).length;
+  const promptScore = Math.max(0, Math.min(10, avg - (ctx.plan?.warnings?.length ? 1 : 0)));
+
+  const gate = errors > 0 ? 'fail' : warnings > 0 ? 'warn' : 'pass';
+
+  return {
+    version: 1,
+    profile,
+    promptScore,
+    scores,
+    issues,
+    gate,
+  };
+}
+
+export { PROFILES, detectProfile };