@birdapi/velinstyle 1.1.0 → 1.2.1

package/cli/scaffold.js

@@ -1,11 +1,13 @@
 /**
- * Prompt-based scaffolding: map natural language to VelinStyle blueprint composition.
+ * Prompt-based scaffolding: plan-first for pages; recipe fallback for fragments.
  */
 import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { emitBlueprint } from './blueprint.js';
 import { auditHtml, suggestFromIssues } from './layout-audit.js';
+import { planFromPrompt, analyzePrompt } from './prompt-engine.js';
+import { reviewHtml } from './review.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const RECIPES_PATH = join(__dirname, 'scaffold-recipes.json');
@@ -14,10 +16,59 @@ function loadRecipes() {
   return JSON.parse(readFileSync(RECIPES_PATH, 'utf-8'));
 }
 
+/**
+ * Fragment intents (navbar, modal, …) stay recipe-based.
+ * Full pages go through the Prompt Engine (plan → render → review).
+ * Low-confidence hero-only fallback is removed in favor of page planning.
+ * @param {string} prompt
+ */
+function isPagePrompt(prompt) {
+  const recipes = loadRecipes();
+  const lower = (prompt || '').toLowerCase();
+
+  const pageHints = [
+    'landing page', 'landingpage', 'homepage', 'website', 'webseite',
+    'steuerberater', 'lawyer', 'kanzlei', 'tax advisor', 'attorney',
+    'clinic', 'healthcare', 'praxis', 'restaurant', 'saas', 'portfolio',
+    'agency', 'corporate', 'shop', 'online store', 'blog post page',
+    'course landing', 'community site', 'event page', 'page for',
+  ];
+  if (pageHints.some((h) => lower.includes(h))) return true;
+
+  let bestRecipe = { id: null, score: 0 };
+  for (const [id, def] of Object.entries(recipes.intents)) {
+    let score = 0;
+    for (const kw of def.keywords) {
+      if (lower.includes(kw.toLowerCase())) score += kw.length;
+    }
+    if (score > bestRecipe.score) bestRecipe = { id, score };
+  }
+
+  const fragmentIds = new Set([
+    'navbar', 'modal', 'card', 'dashboard', 'login', 'footer', 'pricing', 'empty', 'table', 'onboarding',
+  ]);
+  if (bestRecipe.id && fragmentIds.has(bestRecipe.id) && bestRecipe.score >= 5) {
+    return false;
+  }
+
+  // Hero-only recipe with "landing" keyword but no full-page phrasing → still plan a page
+  if (bestRecipe.id === 'hero' && /landing|homepage|website|webseite|seite/i.test(prompt)) {
+    return true;
+  }
+
+  const analysis = analyzePrompt(prompt);
+  return analysis.confidence === 'high' && !fragmentIds.has(analysis.pageId);
+}
+
 /**
  * @param {string} prompt
  */
 export function parseIntent(prompt) {
+  if (isPagePrompt(prompt)) {
+    const analysis = analyzePrompt(prompt);
+    return { id: analysis.pageId || 'landing', confidence: analysis.confidence, mode: 'plan' };
+  }
+
   const recipes = loadRecipes();
   const lower = prompt.toLowerCase();
   let best = { id: recipes.fallback.intent, confidence: recipes.fallback.confidence, score: 0 };
@@ -32,7 +83,7 @@ export function parseIntent(prompt) {
     }
   }
 
-  return { id: best.id, confidence: best.score > 0 ? best.confidence : 'low' };
+  return { id: best.id, confidence: best.score > 0 ? best.confidence : 'low', mode: 'recipe' };
 }
 
 /**
@@ -108,7 +159,68 @@ export function scaffoldFromPrompt(prompt, options = {}) {
     return { ok: false, error: 'Prompt is required.' };
   }
 
+  if (isPagePrompt(prompt)) {
+    const planned = planFromPrompt(prompt);
+    if (!planned.ok) return planned;
+
+    const review = reviewHtml(planned.html, { plan: planned.plan, prompt });
+    const banner =
+      `<!-- Generated by velinstyle scaffold (1.2.0) — mode: plan, page: ${planned.plan.page?.id}, confidence: ${planned.analysis.confidence} -->\n` +
+      `<!-- Sections: ${(planned.plan.sections || []).map((s) => s.id).join(', ')} — run: velinstyle review -->\n`;
+
+    const fullHtml = banner + planned.html;
+    const issues = auditHtml(fullHtml);
+    const responsiveHints = suggestFromIssues(issues);
+
+    return {
+      ok: true,
+      mode: 'plan',
+      intent: planned.plan.page?.id || planned.analysis.pageId,
+      confidence: planned.analysis.confidence,
+      blueprints: (planned.plan.sections || []).map((s) => s.blueprint),
+      plan: planned.plan,
+      analysis: planned.analysis,
+      review,
+      html: fullHtml,
+      slots: {
+        brand: 'Brand',
+        title: /steuerberater/i.test(prompt) ? 'Steuerberatung mit Klarheit' : 'Headline',
+        cta: /kontakt|consultation|beratung/i.test(prompt) ? 'Kontakt aufnehmen' : 'Primary CTA',
+      },
+      missing: planned.missing,
+      warnings: planned.warnings,
+      responsiveHints,
+      nextSteps: ['velinstyle review <file>', 'velinstyle layout suggest <file>', 'velinstyle scan <file>'],
+    };
+  }
+
   const intent = parseIntent(prompt);
+  // No silent hero-only fallback — unknown prompts plan a landing page.
+  if (intent.mode !== 'plan' && intent.id === 'hero' && intent.confidence === 'low') {
+    const planned = planFromPrompt(prompt);
+    if (!planned.ok) return planned;
+    const review = reviewHtml(planned.html, { plan: planned.plan, prompt });
+    const fullHtml =
+      `<!-- Generated by velinstyle scaffold (1.2.0) — mode: plan-fallback, page: ${planned.plan.page?.id} -->\n` +
+      planned.html;
+    return {
+      ok: true,
+      mode: 'plan',
+      intent: planned.plan.page?.id || 'landing',
+      confidence: planned.analysis.confidence,
+      blueprints: (planned.plan.sections || []).map((s) => s.blueprint),
+      plan: planned.plan,
+      analysis: planned.analysis,
+      review,
+      html: fullHtml,
+      slots: extractSlots(prompt),
+      missing: planned.missing,
+      warnings: [...(planned.warnings || []), 'Used page planner instead of silent hero fallback.'],
+      responsiveHints: suggestFromIssues(auditHtml(fullHtml)),
+      nextSteps: ['velinstyle review <file>', 'velinstyle layout suggest <file>', 'velinstyle scan <file>'],
+    };
+  }
+
   const slots = extractSlots(prompt);
   const blueprintIds = resolveBlueprints(intent.id, { prompt, slots });
 
@@ -125,22 +237,25 @@ export function scaffoldFromPrompt(prompt, options = {}) {
   html = applySlots(html, slots);
 
   const banner =
-    `<!-- Generated by velinstyle scaffold (0.8.0) — intent: ${intent.id}, confidence: ${intent.confidence} -->\n` +
+    `<!-- Generated by velinstyle scaffold (1.2.0) — mode: recipe, intent: ${intent.id}, confidence: ${intent.confidence} -->\n` +
     `<!-- Blueprints: ${blueprintIds.join(', ')} — run: velinstyle layout suggest & velinstyle scan -->\n`;
 
   const fullHtml = banner + html;
   const issues = auditHtml(fullHtml);
   const responsiveHints = suggestFromIssues(issues);
+  const review = reviewHtml(fullHtml, { prompt });
 
   return {
     ok: true,
+    mode: 'recipe',
     intent: intent.id,
     confidence: intent.confidence,
     blueprints: blueprintIds,
     html: fullHtml,
     slots,
+    review,
     responsiveHints,
-    nextSteps: ['velinstyle layout suggest <file>', 'velinstyle scan <file>'],
+    nextSteps: ['velinstyle review <file>', 'velinstyle layout suggest <file>', 'velinstyle scan <file>'],
   };
 }
 

package/cli/scanner-rules-data.js

@@ -44,6 +44,13 @@ export const SCANNER_RULES = [
   { id: 'a11y/iframe-title', category: 'a11y', severity: 'error', message: '<iframe> without title.', fixHint: 'Add descriptive title attribute.' },
   { id: 'a11y/autocomplete-auth', category: 'a11y', severity: 'warning', message: 'Auth field missing autocomplete (WCAG 2.2).', fixHint: 'Add autocomplete="username" or "current-password".' },
   { id: 'a11y/invalid-describedby', category: 'a11y', severity: 'warning', message: 'aria-invalid without aria-describedby.', fixHint: 'Link to error message element id.' },
+  { id: 'a11y/duplicate-id', category: 'a11y', severity: 'error', message: 'Duplicate id attribute in the document.', fixHint: 'Make every id unique.' },
+  { id: 'a11y/target-size-min', category: 'a11y', severity: 'warning', message: 'Interactive control appears smaller than ~24px (WCAG 2.5.8 heuristic).', fixHint: 'Increase hit target to at least 24×24 CSS px.' },
+  { id: 'a11y/nested-interactive', category: 'a11y', severity: 'error', message: 'Nested interactive elements (button/a/role).', fixHint: 'Use a single control; do not nest button/a/role=button.' },
+  { id: 'a11y/contrast-inline', category: 'a11y', severity: 'error', message: 'Inline or authored color pair fails WCAG AA contrast.', fixHint: 'Raise contrast to ≥4.5:1 (or ≥3:1 large text).' },
+  { id: 'a11y/role-button-contract', category: 'a11y', severity: 'warning', message: 'role=button without tabindex and/or Enter/Space handling.', fixHint: 'Prefer native <button>, or tabindex="0" + keydown for Enter/Space.' },
+  { id: 'css/unknown-velin-class', category: 'css', severity: 'warning', message: 'Unknown velin-* utility/component class.', fixHint: 'Use classes from the CSS bundle or blueprint --strict.' },
+  { id: 'wc/invalid-attribute', category: 'wc', severity: 'warning', message: 'Attribute is not part of this Web Component API.', fixHint: 'Use observed / documented attributes only.' },
   // CSS
   { id: 'css/var-fallback', category: 'css', severity: 'info', message: 'CSS variable without fallback in var().', fixHint: 'Use var(--velin-*, fallback).' },
   { id: 'css/z-index-token', category: 'css', severity: 'warning', message: 'Raw z-index instead of --velin-z-* token.', fixHint: 'Use tokens from z-index.css — --fix suggests token.' },

package/cli/scanner.js

@@ -1,7 +1,9 @@
-import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, writeFileSync, statSync } from 'fs';
 import { join, relative, extname } from 'path';
 import { applyFixes, fixSafeExternalLinkLine, fixZIndexLine } from './apply-fixes.js';
 import { scanPIIHTML, scanPIIJS } from './pii-scanner.js';
+import { loadKnownCssClasses } from './blueprint.js';
+import { contrastFromInlineStyle, parseColor, contrastRatio, relLuminance } from './contrast-utils.js';
 
 export { SCANNER_RULES, PERF_RULES } from './scanner-rules-data.js';
 
@@ -37,6 +39,19 @@ function walkFiles(dir, exts, ignore = DEFAULT_IGNORE) {
   return results;
 }
 
+/** Accept a single file or a directory (same pattern as layout-audit). */
+function collectFiles(targetPath, exts, ignore = DEFAULT_IGNORE) {
+  if (!existsSync(targetPath)) return [];
+  const st = statSync(targetPath);
+  if (st.isFile()) {
+    return exts.includes(extname(targetPath).toLowerCase()) ? [targetPath] : [];
+  }
+  if (st.isDirectory()) {
+    return walkFiles(targetPath, exts, ignore);
+  }
+  return [];
+}
+
 // ── Security Scanner ─────────────────────────────────────────────────────────
 
 const INLINE_EVENTS = [
@@ -102,6 +117,15 @@ function scanSecurityHTML(content, file) {
       });
     }
 
+    if (/document\.write\s*\(/.test(line)) {
+      issues.push({
+        file, line: ln, severity: 0,
+        rule: 'security/no-document-write',
+        message: 'document.write() detected in HTML/script. This is dangerous and blocks parsing.',
+        fixable: false,
+      });
+    }
+
     if (/(?:href|src)\s*=\s*["']data:text\/html/i.test(line)) {
       issues.push({
         file, line: ln, severity: 0,
@@ -203,10 +227,311 @@ function issueCategory(rule) {
   if (rule.startsWith('pii/')) return 'pii';
   if (rule.startsWith('a11y/')) return 'a11y';
   if (rule.startsWith('css/')) return 'css';
+  if (rule.startsWith('wc/')) return 'wc';
   if (rule.startsWith('perf/')) return 'perf';
   return 'other';
 }
 
+/** Author-facing attrs per tag (observed + documented aliases). Global HTML attrs ignored. */
+const WC_ATTR_ALLOW = {
+  'velin-tooltip': new Set(['content', 'placement']),
+  'velin-copy': new Set(['value', 'text', 'label']),
+  'velin-icon': new Set(['name', 'size', 'label', 'provider', 'variant', 'sprite', 'aria-label', 'aria-hidden', 'class']),
+  'velin-sparkline': new Set(['values', 'width', 'height', 'min', 'max', 'area', 'glow', 'animate', 'label']),
+  'velin-data-table': new Set(['page-size', 'filter-input', 'empty-text', 'label', 'editable', 'sortable', 'class']),
+  'velin-form-summary': new Set([]),
+  'velin-theme-toggle': new Set(['themes-base', 'theme', 'themes']),
+  'velin-calendar': new Set(['value', 'min', 'max', 'label', 'class']),
+  'velin-file-dropzone': new Set(['accept', 'multiple', 'label', 'progress', 'class']),
+  'velin-code-block': new Set(['language', 'class']),
+};
+
+const WC_GLOBAL_ATTRS = new Set([
+  'id', 'class', 'slot', 'part', 'style', 'hidden', 'title', 'role', 'tabindex',
+  'aria-label', 'aria-labelledby', 'aria-describedby', 'aria-hidden', 'aria-expanded',
+  'aria-controls', 'aria-live', 'aria-atomic', 'dir', 'lang', 'data-velin-component',
+]);
+
+function lineNumberAt(content, index) {
+  return content.slice(0, Math.max(0, index)).split('\n').length;
+}
+
+function scanDuplicateIds(content, file) {
+  const issues = [];
+  const seen = new Map();
+  for (const m of content.matchAll(/\bid\s*=\s*["']([^"']+)["']/gi)) {
+    const id = m[1];
+    const ln = lineNumberAt(content, m.index);
+    if (seen.has(id)) {
+      issues.push({
+        file,
+        line: ln,
+        severity: 0,
+        rule: 'a11y/duplicate-id',
+        message: `Duplicate id="${id}" (also at line ${seen.get(id)}).`,
+        fixable: false,
+      });
+    } else {
+      seen.set(id, ln);
+    }
+  }
+  return issues;
+}
+
+function scanUnknownVelinClasses(content, file, knownClasses) {
+  const issues = [];
+  if (!knownClasses) return issues;
+  for (const m of content.matchAll(/\bclass\s*=\s*["']([^"']+)["']/gi)) {
+    const ln = lineNumberAt(content, m.index);
+    for (const token of m[1].split(/\s+/)) {
+      if (!token.startsWith('velin-')) continue;
+      if (!knownClasses.has(token)) {
+        issues.push({
+          file,
+          line: ln,
+          severity: 1,
+          rule: 'css/unknown-velin-class',
+          message: `Unknown VelinStyle class "${token}".`,
+          fixable: false,
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+function scanInvalidWcAttributes(content, file) {
+  const issues = [];
+  for (const m of content.matchAll(/<(velin-[a-z0-9-]+)\b([^>]*)>/gi)) {
+    const tag = m[1].toLowerCase();
+    const attrBlob = m[2] || '';
+    const allow = WC_ATTR_ALLOW[tag];
+    if (!allow) continue;
+    const ln = lineNumberAt(content, m.index);
+    for (const am of attrBlob.matchAll(/([:@]?[a-zA-Z_:][\w:.-]*)\s*=/g)) {
+      const name = am[1].toLowerCase();
+      if (name.startsWith('on')) continue;
+      if (name.startsWith('aria-') || name.startsWith('data-')) {
+        // data-velin-copy is wrong API for <velin-copy>; allow only data-* that we document via dataset.source → data-source
+        if (tag === 'velin-copy' && name !== 'data-source' && name.startsWith('data-')) {
+          issues.push({
+            file,
+            line: ln,
+            severity: 1,
+            rule: 'wc/invalid-attribute',
+            message: `<${tag}> does not use "${name}". Prefer value="…" or text="…".`,
+            fixable: false,
+          });
+        }
+        continue;
+      }
+      if (WC_GLOBAL_ATTRS.has(name) || allow.has(name)) continue;
+      issues.push({
+        file,
+        line: ln,
+        severity: 1,
+        rule: 'wc/invalid-attribute',
+        message: `<${tag}> does not observe attribute "${name}". Allowed: ${[...allow].join(', ') || '(none besides globals)'}.`,
+        fixable: false,
+      });
+    }
+  }
+  return issues;
+}
+
+function collectTinyTapClasses(content) {
+  const tiny = new Set();
+  for (const block of content.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) {
+    const css = block[1];
+    for (const rule of css.matchAll(/\.([a-zA-Z_-][\w-]*)\s*\{([^}]*)\}/g)) {
+      const body = rule[2];
+      const w = body.match(/(?:^|;)\s*(?:width|inline-size)\s*:\s*([\d.]+)px/i);
+      const h = body.match(/(?:^|;)\s*(?:height|block-size)\s*:\s*([\d.]+)px/i);
+      const wp = w ? Number(w[1]) : Infinity;
+      const hp = h ? Number(h[1]) : Infinity;
+      if (wp <= 24 || hp <= 24) tiny.add(rule[1]);
+    }
+  }
+  return tiny;
+}
+
+function scanTargetSizeMin(content, file) {
+  const issues = [];
+  const tinyClasses = collectTinyTapClasses(content);
+  const interactiveRe = /<(button|a|input|select|textarea|summary)\b([^>]*)>/gi;
+  for (const m of content.matchAll(interactiveRe)) {
+    const attrs = m[2] || '';
+    const ln = lineNumberAt(content, m.index);
+    let tiny = false;
+    const styleM = attrs.match(/\bstyle\s*=\s*["']([^"']*)["']/i);
+    if (styleM) {
+      const s = styleM[1];
+      for (const dim of s.matchAll(/(?:width|height|inline-size|block-size)\s*:\s*([\d.]+)px/gi)) {
+        if (Number(dim[1]) <= 24) tiny = true;
+      }
+    }
+    const classM = attrs.match(/\bclass\s*=\s*["']([^"']*)["']/i);
+    if (classM) {
+      for (const c of classM[1].split(/\s+/)) {
+        if (tinyClasses.has(c)) tiny = true;
+      }
+    }
+    if (tiny) {
+      issues.push({
+        file,
+        line: ln,
+        severity: 1,
+        rule: 'a11y/target-size-min',
+        message: `<${m[1]}> appears to have a hit target ≤24px (WCAG 2.5.8 heuristic).`,
+        fixable: false,
+      });
+    }
+  }
+  return issues;
+}
+
+function scanNestedInteractive(content, file) {
+  const issues = [];
+  const html = content
+    .replace(/<script\b[\s\S]*?<\/script>/gi, '')
+    .replace(/<style\b[\s\S]*?<\/style>/gi, '');
+
+  for (const m of html.matchAll(/<(button|a)\b([^>]*)>([\s\S]*?)<\/\1>/gi)) {
+    const outer = m[1].toLowerCase();
+    const innerHtml = m[3] || '';
+    const ln = lineNumberAt(content, m.index);
+    const nestedTag = innerHtml.match(/<(button|a)\b/i);
+    if (nestedTag) {
+      issues.push({
+        file,
+        line: ln,
+        severity: 0,
+        rule: 'a11y/nested-interactive',
+        message: `Nested interactive elements (<${outer}> contains <${nestedTag[1].toLowerCase()}>). Use a single control.`,
+        fixable: false,
+      });
+    }
+    if (/\brole\s*=\s*["'](button|link|menuitem)["']/i.test(innerHtml)) {
+      const role = innerHtml.match(/\brole\s*=\s*["'](button|link|menuitem)["']/i)[1];
+      issues.push({
+        file,
+        line: ln,
+        severity: 0,
+        rule: 'a11y/nested-interactive',
+        message: `<${outer}> contains an element with role="${role}" (nested interactive).`,
+        fixable: false,
+      });
+    }
+  }
+
+  // role=button wrapping another interactive
+  for (const m of html.matchAll(/<([a-z][\w-]*)\b([^>]*\brole\s*=\s*["']button["'][^>]*)>([\s\S]*?)<\/\1>/gi)) {
+    const innerHtml = m[3] || '';
+    if (/<(button|a)\b/i.test(innerHtml) || /\brole\s*=\s*["'](button|link)["']/i.test(innerHtml)) {
+      issues.push({
+        file,
+        line: lineNumberAt(content, m.index),
+        severity: 0,
+        rule: 'a11y/nested-interactive',
+        message: `role="button" host contains nested interactive content.`,
+        fixable: false,
+      });
+    }
+  }
+
+  return issues;
+}
+
+function scanContrastInline(content, file) {
+  const issues = [];
+  for (const m of content.matchAll(/<([a-z][\w-]*)\b([^>]*?\bstyle\s*=\s*["']([^"']*)["'][^>]*)>/gi)) {
+    const style = m[3];
+    const result = contrastFromInlineStyle(style);
+    if (!result) continue;
+    if (!result.pass) {
+      issues.push({
+        file,
+        line: lineNumberAt(content, m.index),
+        severity: 0,
+        rule: 'a11y/contrast-inline',
+        message: `Inline color contrast ${result.ratio.toFixed(2)}:1 fails WCAG AA (${result.min}:1). color=${result.fg} on ${result.bg}.`,
+        fixable: false,
+      });
+    }
+  }
+
+  // Authored <style> blocks: flag pairs of color + background-color in the same rule when both parse
+  for (const block of content.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) {
+    const css = block[1];
+    const blockStart = block.index ?? 0;
+    for (const rule of css.matchAll(/([^{]+)\{([^}]*)\}/g)) {
+      const body = rule[2];
+      const colorM = body.match(/(?:^|;)\s*color\s*:\s*([^;]+)/i);
+      const bgM = body.match(/(?:^|;)\s*(?:background-color|background)\s*:\s*([^;]+)/i);
+      if (!colorM || !bgM) continue;
+      const fg = parseColor(colorM[1].trim());
+      const bgRaw = bgM[1].trim();
+      if (/gradient|url\(/i.test(bgRaw)) continue;
+      const bg = parseColor(bgRaw.split(/\s+/)[0]);
+      if (!fg || !bg) continue;
+      const ratio = contrastRatio(relLuminance(fg), relLuminance(bg));
+      if (ratio < 4.5) {
+        issues.push({
+          file,
+          line: lineNumberAt(content, blockStart + (rule.index || 0)),
+          severity: 0,
+          rule: 'a11y/contrast-inline',
+          message: `Authored CSS contrast ${ratio.toFixed(2)}:1 fails WCAG AA (4.5:1) in rule "${rule[1].trim().slice(0, 40)}".`,
+          fixable: false,
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+const VELIN_WC_WITH_KEYBOARD = new Set([
+  'velin-popover', 'velin-collapse', 'velin-dropdown', 'velin-menubar', 'velin-command',
+  'velin-tabs', 'velin-accordion', 'velin-dialog', 'velin-modal', 'velin-drawer', 'velin-sheet',
+]);
+
+function scanRoleButtonContract(content, file) {
+  const issues = [];
+  for (const m of content.matchAll(/<([a-z][\w-]*)\b([^>]*\brole\s*=\s*["']button["'][^>]*)>/gi)) {
+    const tag = m[1].toLowerCase();
+    const attrs = m[2] || '';
+    const ln = lineNumberAt(content, m.index);
+    if (tag === 'button' || tag === 'summary') continue;
+    if (VELIN_WC_WITH_KEYBOARD.has(tag)) continue;
+
+    const hasTab = /\btabindex\s*=\s*["']?(?:0|-?\d+)/i.test(attrs);
+    const hasKeyHandler = /\bon(?:keydown|keyup|keypress)\s*=/i.test(attrs);
+    // Look ahead ~800 chars for a nearby script attaching keys (weak); prefer explicit warning
+    if (!hasTab) {
+      issues.push({
+        file,
+        line: ln,
+        severity: 1,
+        rule: 'a11y/role-button-contract',
+        message: `role="button" on <${tag}> without tabindex. Use <button> or add tabindex="0" and Enter/Space handlers.`,
+        fixable: false,
+      });
+      continue;
+    }
+    if (!hasKeyHandler) {
+      issues.push({
+        file,
+        line: ln,
+        severity: 1,
+        rule: 'a11y/role-button-contract',
+        message: `role="button" on <${tag}> lacks Enter/Space keyboard handling. Prefer <button> or handle keydown.`,
+        fixable: false,
+      });
+    }
+  }
+  return issues;
+}
+
 // ── Accessibility Scanner ────────────────────────────────────────────────────
 
 function scanA11yHTML(content, file) {
@@ -453,18 +778,26 @@ export function scan(targetPath, options = {}) {
     ? options.only.split(',').map((s) => s.trim().toLowerCase())
     : null;
 
-  const htmlFiles = walkFiles(targetPath, ['.html', '.htm'], ignore);
-  const cssFiles = walkFiles(targetPath, ['.css'], ignore);
-  const jsFiles = walkFiles(targetPath, ['.js', '.mjs'], ignore);
+  const htmlFiles = collectFiles(targetPath, ['.html', '.htm'], ignore);
+  const cssFiles = collectFiles(targetPath, ['.css'], ignore);
+  const jsFiles = collectFiles(targetPath, ['.js', '.mjs'], ignore);
 
   let allIssues = [];
 
   const fixEmailPlaceholder = options.fixEmailPlaceholder || 'user@example.com';
+  const knownClasses = htmlFiles.length ? loadKnownCssClasses({ includeDist: true }) : null;
 
   for (const file of htmlFiles) {
     const content = readFileSync(file, 'utf-8');
     allIssues.push(...scanSecurityHTML(content, file));
     allIssues.push(...scanA11yHTML(content, file));
+    allIssues.push(...scanDuplicateIds(content, file));
+    allIssues.push(...scanTargetSizeMin(content, file));
+    allIssues.push(...scanNestedInteractive(content, file));
+    allIssues.push(...scanContrastInline(content, file));
+    allIssues.push(...scanRoleButtonContract(content, file));
+    allIssues.push(...scanInvalidWcAttributes(content, file));
+    allIssues.push(...scanUnknownVelinClasses(content, file, knownClasses));
     allIssues.push(...scanPIIHTML(content, file, { fixEmailPlaceholder }));
   }
 
@@ -520,7 +853,27 @@ export function scan(targetPath, options = {}) {
         changedFiles: fixSummary.changedRelPaths,
       };
     }
+    if (options.returnData) {
+      return { exitCode: errors > 0 ? 1 : 0, ...payload };
+    }
     console.log(JSON.stringify(payload, null, 2));
+  } else if (options.returnData) {
+    return {
+      exitCode: errors > 0 ? 1 : 0,
+      total: allIssues.length,
+      errors,
+      warnings,
+      infos,
+      issues: allIssues.map((i) => ({
+        file: relative(targetPath, i.file),
+        line: i.line,
+        severity: SEVERITY_LABEL[i.severity],
+        category: issueCategory(i.rule),
+        rule: i.rule,
+        message: i.message,
+        fixable: !!i.fixable,
+      })),
+    };
   } else {
     console.log(`\n  ${C.bold('VelinStyle Scanner Report')}\n`);
     console.log(`  Scanned: ${htmlFiles.length} HTML, ${cssFiles.length} CSS, ${jsFiles.length} JS files\n`);