brandrail 0.3.2 → 0.4.0

package/dist/brandrail.mjs

@@ -701,13 +701,100 @@ function resolveConfig(config) {
     rules: config.rules ?? {},
     ignore: [...DEFAULT_IGNORE, ...config.ignore ?? []],
     forbiddenImports: config.forbiddenImports ?? DEFAULT_FORBIDDEN_IMPORTS,
-    colorTolerance: config.colorTolerance ?? 2.5
+    colorTolerance: config.colorTolerance ?? 2.5,
+    framework: config.framework
   };
 }
 
+// ../engine/src/frameworks.ts
+var FRAMEWORKS = ["react", "angular", "vue", "web-components", "html"];
+var FRAMEWORK_LABEL = {
+  react: "React",
+  angular: "Angular",
+  vue: "Vue",
+  "web-components": "Web Components",
+  html: "Plain HTML"
+};
+var LANG = { react: "tsx", angular: "html", vue: "vue", "web-components": "html", html: "html" };
+var isFramework = (x2) => typeof x2 === "string" && FRAMEWORKS.includes(x2);
+var kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/\./g, "-").toLowerCase();
+var prefixOf = (tag) => tag.includes("-") ? `${tag.split("-")[0]}-` : tag;
+function webComponentSetup(target, u, tag) {
+  const load = u.importPath ? `Load it once with \`import "${u.importPath}";\` at the app entry.` : "";
+  switch (target) {
+    case "angular":
+      return `Web component: add \`CUSTOM_ELEMENTS_SCHEMA\` to the component's \`schemas\`. ${load}`.trim();
+    case "vue":
+      return `Web component: set \`compilerOptions.isCustomElement = (tag) => tag.startsWith("${prefixOf(tag)}")\` in the Vue config. ${load}`.trim();
+    case "html":
+      return u.importPath ? `Web component: load \`${u.importPath}\` once (a bundler import or \`<script type="module">\`).` : void 0;
+    default:
+      return u.setup ?? (load || void 0);
+  }
+}
+function resolveUsage(c, framework) {
+  if (framework === "react") {
+    return {
+      framework,
+      importLine: `import { ${c.name} } from "${c.importPath}";`,
+      tag: c.name,
+      example: c.example,
+      lang: LANG.react,
+      props: c.props
+    };
+  }
+  const own = c.frameworks?.[framework];
+  if (own) return fromUsage(c, framework, framework, own);
+  const wc = c.frameworks?.["web-components"];
+  if (wc) {
+    const r = fromUsage(c, framework, "web-components", wc);
+    return { ...r, via: "web-components", setup: webComponentSetup(framework, wc, r.tag), importLine: framework === "html" ? void 0 : r.importLine };
+  }
+  return null;
+}
+function fromUsage(c, framework, kind, u) {
+  const path = u.importPath?.trim();
+  let tag = u.tag?.trim();
+  let importLine;
+  let setup = u.setup?.trim() || void 0;
+  switch (kind) {
+    case "angular":
+      tag ||= kebab(c.name);
+      if (path && u.importName) {
+        importLine = `import { ${u.importName} } from "${path}";`;
+        setup ??= `Add \`${u.importName}\` to the standalone component's \`imports\` (or the NgModule's).`;
+      }
+      break;
+    case "vue":
+      tag ||= u.importName || c.name;
+      if (path) importLine = `import { ${u.importName || tag} } from "${path}";`;
+      break;
+    case "web-components":
+      tag ||= kebab(c.name);
+      if (path) importLine = `import "${path}";`;
+      break;
+    case "html":
+      tag ||= c.replaces?.[0]?.replace(/\[.*$/, "") || "div";
+      if (path && !setup) setup = /\.css(\?|$)/.test(path) ? `Include \`<link rel="stylesheet" href="${path}">\` once.` : /\.m?js(\?|$)/.test(path) ? `Include \`<script type="module" src="${path}"></script>\` once.` : void 0;
+      break;
+  }
+  return { framework, importLine, tag, setup, example: u.example?.trim() || void 0, lang: LANG[kind], props: u.props?.length ? u.props : void 0 };
+}
+var markup = (u) => `<${u.tag}>`;
+function detectFramework(pkg) {
+  if (!pkg) return "html";
+  const deps = { ...pkg.peerDependencies, ...pkg.devDependencies, ...pkg.dependencies };
+  const has = (name) => name in deps;
+  if (has("@angular/core")) return "angular";
+  if (has("vue") || has("nuxt")) return "vue";
+  if (has("react") || has("next") || has("preact")) return "react";
+  if (has("svelte") || has("lit") || has("@stencil/core") || has("@sveltejs/kit")) return "web-components";
+  return "html";
+}
+
 // ../engine/src/rules.ts
-var MARKUP = ["jsx", "vue", "svelte", "html"];
-var ALL = ["jsx", "vue", "svelte", "html", "css"];
+var MARKUP = ["jsx", "vue", "svelte", "html", "template"];
+var ALL = ["jsx", "vue", "svelte", "html", "template", "css"];
 function* matches(re, text) {
   const g = new RegExp(re.source, re.flags.includes("g") ? re.flags : re.flags + "g");
   let m;
@@ -740,6 +827,38 @@ function pxValues(value) {
   }
   return out;
 }
+var kebab2 = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+function styleBindings(code) {
+  const out = [];
+  const withUnit = (v, unit) => unit && /^-?\d*\.?\d+$/.test(v.trim()) ? `${v.trim()}${unit === "%" ? "%" : unit}` : v;
+  for (const m of matches(/(['"])([a-zA-Z-]+)(?:\.(px|rem|em|%))?\1\s*:\s*(?:(['"`])([^'"`\n]*)\4|(-?\d*\.?\d+)(?![\w.]))/g, code)) {
+    const value = m[5] ?? m[6];
+    const offset = m.index + m[0].length - value.length - (m[5] !== void 0 ? 1 : 0);
+    out.push({ prop: kebab2(m[2]), value: withUnit(value, m[3]), offset });
+  }
+  for (const m of matches(/(?<![\w.'"-])((?:padding|margin)(?:Top|Right|Bottom|Left|Inline|Block)(?:Start|End)?|rowGap|columnGap|border(?:Top|Bottom)?(?:Left|Right)?Radius)\s*:\s*(['"`])([^'"`\n]*\d(?:px|rem)[^'"`\n]*)\2/g, code)) {
+    out.push({ prop: kebab2(m[1]), value: m[3], offset: m.index + m[0].length - m[3].length - 1 });
+  }
+  for (const m of matches(/\[style\.([a-zA-Z-]+)(?:\.(px|rem|em|%))?\]\s*=\s*(["'])([\s\S]*?)\3/g, code)) {
+    const inner = m[4].trim();
+    const lit = /^(['"`])(.*)\1$/.exec(inner)?.[2] ?? (/^-?\d*\.?\d+$/.test(inner) ? inner : null);
+    if (lit === null) continue;
+    out.push({ prop: kebab2(m[1]), value: withUnit(lit, m[2]), offset: m.index + m[0].length - 1 - m[4].length + m[4].indexOf(inner) });
+  }
+  return out;
+}
+function declValue(v, kind) {
+  if (kind === "css") return v;
+  const q = v[0];
+  if (q === '"' || q === "'" || q === "`") {
+    const end = v.indexOf(q, 1);
+    return end === -1 ? v : v.slice(0, end + 1);
+  }
+  const cut = v.search(/["'`>]/);
+  return cut === -1 ? v : v.slice(0, cut);
+}
+var SPACING_PROP = /^(?:(?:padding|margin)(?:-(?:top|right|bottom|left|inline|block)(?:-(?:start|end))?)?|gap|row-gap|column-gap)$/;
+var RADIUS_PROP = /^border(?:-(?:top|bottom|start|end)-(?:left|right|start|end))?-radius$/;
 var noHardcodedColor = {
   id: "no-hardcoded-color",
   title: "Hard-coded colour",
@@ -825,7 +944,7 @@ var spacingScale = {
     const ok = (n) => scale.some((s) => Math.abs(s - n) < 0.01);
     for (const m of matches(/(?<![\w-])(padding|margin|gap|row-gap|column-gap)(?:-(?:top|right|bottom|left|inline|block)(?:-(?:start|end))?)?\s*:\s*([^;{}\n]+)/g, code)) {
       const valueStart = m.index + m[0].length - m[2].length;
-      for (const v of pxValues(m[2])) {
+      for (const v of pxValues(declValue(m[2], kind))) {
         if (!ok(v.n)) out.push({ offset: valueStart + v.index, message: `${m[1]} ${fmt(v.n)} is off the spacing scale`, suggestion: `Use ${neighbours(scale, v.n)}` });
       }
     }
@@ -838,6 +957,12 @@ var spacingScale = {
         const n = Math.abs(parseFloat(m[2])) * (m[3] === "rem" ? 16 : 1);
         if (!ok(n)) out.push({ offset: m.index, message: `${m[0]} is off the spacing scale`, suggestion: `Use ${neighbours(scale, n)}` });
       }
+      for (const b of styleBindings(code)) {
+        if (!SPACING_PROP.test(b.prop)) continue;
+        for (const v of pxValues(b.value)) {
+          if (!ok(v.n)) out.push({ offset: b.offset + Math.min(v.index, b.value.length), message: `${b.prop} ${fmt(v.n)} is off the spacing scale`, suggestion: `Use ${neighbours(scale, v.n)}` });
+        }
+      }
     }
     return out;
   }
@@ -853,7 +978,7 @@ var radiusScale = {
     const ok = (n) => n >= 999 || config.radii.some((r) => Math.abs(r - n) < 0.01);
     for (const m of matches(/(?<![\w-])border(?:-(?:top|bottom|start|end)-(?:left|right|start|end))?-radius\s*:\s*([^;{}\n]+)/g, code)) {
       const valueStart = m.index + m[0].length - m[1].length;
-      for (const v of pxValues(m[1])) {
+      for (const v of pxValues(declValue(m[1], kind))) {
         if (!ok(v.n)) out.push({ offset: valueStart + v.index, message: `border-radius ${fmt(v.n)} is not a radius token`, suggestion: `Use ${neighbours(config.radii.filter((r) => r < 999), v.n)}` });
       }
     }
@@ -866,6 +991,12 @@ var radiusScale = {
         const n = parseFloat(m[1]);
         if (!ok(n)) out.push({ offset: m.index, message: `${m[0]} is not a radius token`, suggestion: `Use ${neighbours(config.radii.filter((r) => r < 999), n)}` });
       }
+      for (const b of styleBindings(code)) {
+        if (!RADIUS_PROP.test(b.prop)) continue;
+        for (const v of pxValues(b.value)) {
+          if (!ok(v.n)) out.push({ offset: b.offset, message: `${b.prop} ${fmt(v.n)} is not a radius token`, suggestion: `Use ${neighbours(config.radii.filter((r) => r < 999), v.n)}` });
+        }
+      }
     }
     return out;
   }
@@ -889,10 +1020,11 @@ var fontFamily = {
         suggestion: `Use var(--font-family-sans) (${allowed[0]})`
       });
     };
-    for (const m of matches(/(?<![\w-])font-family\s*:\s*([^;{}\n]+)/g, code)) test(m[1], m.index);
+    for (const m of matches(/(?<![\w-])font-family\s*:\s*([^;{}\n]+)/g, code)) test(declValue(m[1], kind), m.index);
     if (kind !== "css") {
       for (const m of matches(/(?<![\w-])fontFamily\s*:\s*(['"`])([^'"`]+)\1/g, code)) test(m[2], m.index);
       for (const m of matches(/(?<![\w-])font-\[([^\]]+)\]/g, code)) test(m[1].replace(/_/g, " "), m.index);
+      for (const b of styleBindings(code)) if (b.prop === "font-family") test(b.value, b.offset);
     }
     return out;
   }
@@ -904,7 +1036,7 @@ var preferOfficialComponent = {
   description: "Use the design system component instead of a raw HTML element.",
   defaultSeverity: "error",
   kinds: MARKUP,
-  check({ code, config }) {
+  check({ code, config, framework }) {
     if (config.replaces.size === 0) return [];
     const out = [];
     const baseTags = [...new Set([...config.replaces.keys()].map((k) => k.replace(/\[.*$/, "").replace(/[^a-z0-9-]/g, "")))].filter(Boolean);
@@ -919,16 +1051,28 @@ var preferOfficialComponent = {
         else if (tag === "input" && !TEXT_INPUT_TYPES.has(type)) comp = type === "submit" || type === "button" ? config.replaces.get("button") : void 0;
       }
       if (!comp) continue;
+      const usage = resolveUsage(comp, framework);
+      if (!usage) continue;
       if (new RegExp(`(?:function|const|class)\\s+${comp.name}\\b`).test(code)) continue;
+      if (framework !== "react" && implementsTag(code, usage.tag)) continue;
       out.push({
         offset: m.index,
         message: `Raw <${tag}${tag === "input" && /type=/.test(attrs) ? ` type="${attrs.match(/type\s*=\s*\{?\s*["'`]([\w-]+)/)?.[1]}"` : ""}> re-implements ${comp.name}`,
-        suggestion: `import { ${comp.name} } from "${comp.importPath}"`
+        suggestion: useSuggestion(comp, usage)
       });
     }
     return out;
   }
 };
+var escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+var implementsTag = (code, tag) => new RegExp(`selector\\s*:\\s*['"\`]${escapeRe(tag)}['"\`]|customElements\\.define\\(\\s*['"\`]${escapeRe(tag)}['"\`]|@customElement\\(\\s*['"\`]${escapeRe(tag)}['"\`]`).test(code);
+function useSuggestion(comp, u) {
+  if (u.framework === "react") return `import { ${comp.name} } from "${comp.importPath}"`;
+  const parts = [`Use <${u.tag}>`];
+  if (u.importLine) parts.push(`(${u.importLine})`);
+  if (u.setup && u.via) parts.push(`\u2014 ${u.setup}`);
+  return parts.join(" ");
+}
 var forbiddenImport = {
   id: "forbidden-import",
   title: "Other UI library",
@@ -1033,13 +1177,96 @@ function parseAttributes(code, start) {
   }
   return null;
 }
+function parseHtmlAttributes(code, start) {
+  const attrs = [];
+  let i2 = start;
+  while (i2 < code.length) {
+    while (/\s/.test(code[i2] ?? "")) i2++;
+    const c = code[i2];
+    if (c === void 0) return null;
+    if (c === ">" || c === "/" && code[i2 + 1] === ">") return { attrs, end: i2 };
+    if (c === "{" || c === "<" && code[i2 + 1] === "?") {
+      const close = c === "{" ? code[i2 + 1] === "%" ? "%}" : "}}" : "?>";
+      const e = code.indexOf(close, i2 + 2);
+      i2 = e === -1 ? code.length : e + close.length;
+      continue;
+    }
+    const name = /^[^\s=>/"'{]+/.exec(code.slice(i2, i2 + 120))?.[0];
+    if (!name) return null;
+    attrs.push({ name, offset: i2 });
+    i2 += name.length;
+    while (/\s/.test(code[i2] ?? "")) i2++;
+    if (code[i2] === "=") {
+      i2++;
+      while (/\s/.test(code[i2] ?? "")) i2++;
+      const q = code[i2];
+      if (q === '"' || q === "'") {
+        const e = code.indexOf(q, i2 + 1);
+        i2 = e === -1 ? code.length : e + 1;
+      } else while (i2 < code.length && !/[\s>]/.test(code[i2])) i2++;
+    }
+  }
+  return null;
+}
+var HTML_GLOBAL = /^(?:id|class|style|title|role|hidden|tabindex|lang|dir|slot|part|is|key|ref|name|for|form|aria-.+|data-.+)$/;
+function propName(raw) {
+  let n = raw;
+  if (/^(?:\(|@|on-|v-on:|\*|#|let-|ref-|v-(?!bind:|model:))/.test(n)) return null;
+  n = n.replace(/^v-bind:|^v-model:|^bind-|^:/, "").replace(/^\[\(?|\)?\]$/g, "");
+  if (/^(?:attr|class|style)\./.test(n) || /^ng[A-Z]/.test(n) || /^(?:formControl|formControlName|formGroup|routerLink|routerLinkActive)$/.test(n)) return null;
+  n = n.replace(/\.(?:px|rem|em|%)$/, "").replace(/\..*$/, "");
+  if (HTML_GLOBAL.test(n.toLowerCase())) return null;
+  return n;
+}
+var sameName = (a, b) => a.replace(/-/g, "").toLowerCase() === b.replace(/-/g, "").toLowerCase();
+function templateProps({ code, config, framework }) {
+  const tagged = [];
+  for (const comp of config.components) {
+    const u = resolveUsage(comp, framework);
+    const props = u?.props;
+    if (u && props?.length) tagged.push({ comp, tag: u.tag, props });
+  }
+  if (!tagged.length) return [];
+  const out = [];
+  const forms = /* @__PURE__ */ new Map();
+  for (const t of tagged) {
+    forms.set(t.tag, t);
+    if (framework === "vue") forms.set(t.tag.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase(), t);
+  }
+  const names = [...forms.keys()].sort((a, b) => b.length - a.length).map(escapeRe).join("|");
+  for (const m of matches(new RegExp(`<(${names})(?=[\\s/>])`, "g"), code)) {
+    const t = forms.get(m[1]);
+    const parsed = parseHtmlAttributes(code, m.index + m[0].length);
+    if (!parsed) continue;
+    const list = t.props.map((p) => p.required ? `${p.name} (required)` : p.name).join(", ");
+    const passed = [];
+    for (const a of parsed.attrs) {
+      const raw = a.name;
+      if (/^v-model$/.test(raw)) passed.push("modelValue", "value");
+      if (/^\[\(ngModel\)\]$/.test(raw)) passed.push("value");
+      const n = propName(raw);
+      if (!n) continue;
+      passed.push(n);
+      if (t.props.some((p) => sameName(p.name, n))) continue;
+      out.push({ offset: a.offset, message: `<${t.tag}> has no "${n}" input`, suggestion: `Remove it. ${t.comp.name} takes: ${list}` });
+    }
+    for (const p of t.props) {
+      if (!p.required || passed.some((n) => sameName(n, p.name))) continue;
+      if (p.name === "children" || p.name === "content") continue;
+      out.push({ offset: m.index, message: `<${t.tag}> is missing the required "${p.name}" input`, suggestion: `Add ${p.name}${p.type ? ` (${p.type})` : ""}` });
+    }
+  }
+  return out;
+}
 var componentProps = {
   id: "component-props",
   title: "Unknown or missing prop",
   description: "Design system components only accept their documented props, and required props must be passed.",
   defaultSeverity: "error",
-  kinds: ["jsx"],
-  check({ code, config }) {
+  kinds: MARKUP,
+  check(ctx) {
+    if (ctx.framework !== "react" || ctx.kind !== "jsx") return templateProps(ctx);
+    const { code, config } = ctx;
     if (!config.components.some((c) => c.props?.length)) return [];
     const imported = importedComponents(code, config.components);
     if (imported.size === 0) return [];
@@ -1089,8 +1316,10 @@ var RULES = [
 var RULE_IDS = RULES.map((r) => r.id);
 
 // ../engine/src/source.ts
+var TEMPLATE_EXTENSIONS = ["mustache", "hbs", "handlebars", "php", "phtml", "twig", "njk", "liquid"];
 function fileKind(path) {
   const ext = path.toLowerCase().split(".").pop() ?? "";
+  if (TEMPLATE_EXTENSIONS.includes(ext)) return "template";
   if (["tsx", "jsx", "ts", "js", "mjs", "cjs", "mdx"].includes(ext)) return "jsx";
   if (ext === "vue") return "vue";
   if (ext === "svelte") return "svelte";
@@ -1098,13 +1327,41 @@ function fileKind(path) {
   if (["css", "scss", "sass", "less", "pcss"].includes(ext)) return "css";
   return "other";
 }
-var SCANNABLE = /* @__PURE__ */ new Set(["jsx", "vue", "svelte", "html", "css"]);
+var SCANNABLE = /* @__PURE__ */ new Set(["jsx", "vue", "svelte", "html", "template", "css"]);
+var ANGULAR_COMPONENT = /@Component\s*\(\s*\{/;
+var ANGULAR_TEMPLATE = /\s(?:\[[\w.()-]+\]|\([\w.]+\)|\*ng[A-Z]\w*)\s*=|@(?:if|for|switch)\s*\(/;
+function fileFramework(path, kind, code, project) {
+  const p = path.toLowerCase();
+  switch (kind) {
+    case "vue":
+      return "vue";
+    case "svelte":
+      return "web-components";
+    case "template":
+      return "html";
+    case "css":
+      return project ?? "react";
+    case "html":
+      if (p.endsWith(".component.html") || project === "angular" || ANGULAR_TEMPLATE.test(code)) return "angular";
+      return project === "vue" || project === "web-components" ? project : "html";
+    case "jsx":
+      if (ANGULAR_COMPONENT.test(code)) return "angular";
+      if (/\.(tsx|jsx|mdx)$/.test(p)) return "react";
+      return project ?? "react";
+    default:
+      return project ?? "react";
+  }
+}
 var blank = (s) => s.replace(/[^\n]/g, " ");
 function stripComments(code, kind) {
   let out = code;
-  if (kind === "html" || kind === "vue" || kind === "svelte") {
+  if (kind === "html" || kind === "vue" || kind === "svelte" || kind === "template") {
     out = out.replace(/<!--[\s\S]*?-->/g, blank);
   }
+  if (kind === "template") {
+    out = out.replace(/\{\{!--[\s\S]*?--\}\}|\{\{![\s\S]*?\}\}|\{\{--[\s\S]*?--\}\}|\{#[\s\S]*?#\}|\{%-?\s*comment\s*-?%\}[\s\S]*?\{%-?\s*endcomment\s*-?%\}/g, blank).replace(/<\?(?:php|=)?[\s\S]*?(?:\?>|$)/g, (block) => block.replace(/\/\*[\s\S]*?\*\/|(?<![:"'])\/\/[^\n]*?(?=\?>|\n|$)|(?<=\s)#[^\n]*?(?=\?>|\n|$)/g, blank));
+    return out;
+  }
   if (kind === "css") {
     return out.replace(/\/\*[\s\S]*?\*\//g, blank).replace(/(^|[^:])\/\/[^\n]*/g, (m, p1) => p1 + blank(m.slice(p1.length)));
   }
@@ -1196,7 +1453,7 @@ function makeIgnore(globs) {
 }
 
 // ../engine/src/check.ts
-var ENGINE_VERSION = "0.3.2";
+var ENGINE_VERSION = "0.4.0";
 var WEIGHT = { error: 4, warning: 1.5, info: 0.25 };
 function computeScore(counts, lines) {
   const penalty = counts.error * WEIGHT.error + counts.warning * WEIGHT.warning + counts.info * WEIGHT.info;
@@ -1221,11 +1478,12 @@ function check(files, configInput, opts = {}) {
     const idx = new LineIndex(file.content);
     linesScanned += only ? only.size : file.content.split("\n").filter((l) => l.trim()).length;
     const code = stripComments(file.content, kind);
+    const framework = fileFramework(path, kind, code, config.framework);
     const seen = /* @__PURE__ */ new Set();
     for (const rule of RULES) {
       const setting = config.rules[rule.id];
       if (setting === "off" || !rule.kinds.includes(kind)) continue;
-      for (const f of rule.check({ path, kind, code, config })) {
+      for (const f of rule.check({ path, kind, code, config, framework })) {
         const { line, column } = idx.position(f.offset);
         if (only && !only.has(line)) continue;
         const key = `${rule.id}:${line}:${column}`;
@@ -1982,6 +2240,7 @@ var RULES_START = "<!-- brandrail:start -->";
 var RULES_END = "<!-- brandrail:end -->";
 function generateInstructions(config, opts = {}) {
   const r = resolveConfig(config);
+  const fw = opts.framework ?? config.framework ?? "react";
   const lines = [];
   lines.push(`# Design system rules${opts.org ? ` \u2014 ${opts.org}` : ""}`);
   lines.push("");
@@ -1989,7 +2248,7 @@ function generateInstructions(config, opts = {}) {
     `All UI in this repo must follow the Brand Kit${r.tokenVersion ? ` (v${r.tokenVersion})` : ""}. These rules are checked on every pull request by Brandrail.`
   );
   lines.push("");
-  const usesKit = r.components.some((c) => c.importPath === KIT_PACKAGE);
+  const usesKit = fw === "react" && r.components.some((c) => c.importPath === KIT_PACKAGE);
   if (opts.tokensCss || usesKit) {
     lines.push("## Setup");
     if (opts.tokensCss) {
@@ -2001,17 +2260,29 @@ function generateInstructions(config, opts = {}) {
     lines.push("");
   }
   if (r.components.length) {
+    const usable = r.components.map((c) => ({ c, u: resolveUsage(c, fw) }));
+    const here = usable.filter((x2) => x2.u);
+    const missing = usable.filter((x2) => !x2.u).map((x2) => x2.c.name);
     lines.push("## Components");
-    lines.push("Always use these components. Never re-create them with raw HTML elements:");
-    for (const c of r.components) {
+    if (fw !== "react") lines.push(`This is a${fw === "angular" ? "n" : ""} ${FRAMEWORK_LABEL[fw]} project: use the ${FRAMEWORK_LABEL[fw]} form of each component shown here.`);
+    if (here.length) lines.push("Always use these components. Never re-create them with raw HTML elements:");
+    for (const { c, u } of here) {
       const tags = [...r.replaces].filter(([, v]) => v === c).map(([t]) => `<${t}>`);
-      const props = c.props?.length ? ` \u2014 props: ${c.props.map((p) => p.required ? `${p.name}*` : p.name).join(", ")}` : "";
-      lines.push(`- \`${c.name}\` from \`${c.importPath}\`${tags.length ? ` (instead of ${tags.join(", ")})` : ""}${props}`);
-    }
-    if (r.components.some((c) => c.props?.length)) {
+      const props = u.props?.length ? ` \u2014 props: ${u.props.map((p) => p.required ? `${p.name}*` : p.name).join(", ")}` : "";
+      const how = fw === "react" ? `\`${c.name}\` from \`${c.importPath}\`` : `\`${markup(u)}\`${u.importLine ? ` (\`${u.importLine}\`)` : ""}`;
+      lines.push(`- ${how}${fw === "react" ? "" : ` \u2014 ${c.name}`}${tags.length ? ` (instead of ${tags.join(", ")})` : ""}${props}`);
+    }
+    const setups = [...new Set(here.map((x2) => x2.u.setup).filter(Boolean))];
+    if (setups.length && setups.length <= 3) for (const s of setups) lines.push(`- Setup: ${s}`);
+    else if (setups.length) lines.push("- Each component's setup is in its docs (MCP `get_component_docs`).");
+    if (here.some((x2) => x2.u.props?.length)) {
       lines.push("");
       lines.push("Pass only the props listed for each component (* = required). Any other prop is a type error and fails the check: if you need something a component doesn't take, look for a related component (often one with a longer name, like AvatarLabel next to Avatar) or compose it with design tokens.");
     }
+    if (missing.length) {
+      lines.push("");
+      lines.push(`No ${FRAMEWORK_LABEL[fw]} version yet: ${missing.join(", ")}. Build these with semantic HTML and the design tokens below; don't install another UI library.`);
+    }
     lines.push("");
   }
   if (r.colors.length) {
@@ -2073,7 +2344,7 @@ function mcpClientConfigs(url) {
       file: ".mcp.json",
       projectFile: true,
       content: json({ mcpServers: { brandrail: { type: "http", url, headers: { Authorization: "Bearer ${BRANDRAIL_KEY}" } } } }),
-      command: `claude mcp add --transport http brandrail ${url} --header "Authorization: Bearer $BRANDRAIL_KEY"`
+      command: `claude mcp add --transport http brandrail "${url}" --header "Authorization: Bearer $BRANDRAIL_KEY"`
     },
     {
       id: "codex",
@@ -2084,7 +2355,7 @@ function mcpClientConfigs(url) {
 url = "${url}"
 bearer_token_env_var = "BRANDRAIL_KEY"
 `,
-      command: `codex mcp add brandrail --url ${url} --bearer-token-env-var BRANDRAIL_KEY`
+      command: `codex mcp add brandrail --url "${url}" --bearer-token-env-var BRANDRAIL_KEY`
     },
     {
       id: "cursor",
@@ -2880,6 +3151,7 @@ Options for init
   --no-rules             Don't write AGENTS.md (Codex), CLAUDE.md, Cursor, Copilot, Windsurf, Gemini rule files
   --mcp                  Also add the Brandrail MCP server to .mcp.json, .cursor/mcp.json, .vscode/mcp.json
                          and print the Codex / Windsurf config
+  --framework <name>     react | angular | vue | web-components | html (default: detected from package.json)
   --tokens-css <file>    Where to write the CSS variables (default src/brandrail.tokens.css); --no-tokens-css to skip
   --force                Overwrite an existing brandrail.config.json
 
@@ -2910,7 +3182,7 @@ function parseArgs(argv) {
       const [k, v] = a.slice(2).split("=", 2);
       const next = rest[i2 + 1];
       if (v !== void 0) flags[k] = v;
-      else if (next !== void 0 && !next.startsWith("-") && ["config", "format", "fail-below", "changed", "pages", "storage-state", "wait", "width", "tokens-css"].includes(k)) {
+      else if (next !== void 0 && !next.startsWith("-") && ["config", "format", "fail-below", "changed", "pages", "storage-state", "wait", "width", "tokens-css", "framework"].includes(k)) {
         flags[k] = next;
         i2++;
       } else flags[k] = true;
@@ -3012,7 +3284,7 @@ function writeRuleFiles(root, config, org, tokensCss) {
     if (file.endsWith(".mdc")) {
       write(file, () => `---
 description: Design system rules from Brandrail
-globs: ["**/*.{tsx,jsx,vue,svelte,html,css,scss}"]
+globs: ["**/*.{tsx,jsx,ts,vue,svelte,html,css,scss,php,twig,hbs,mustache}"]
 alwaysApply: true
 ---
 
@@ -3032,8 +3304,8 @@ ${md}
   }
   return written;
 }
-function writeMcpConfigs(root) {
-  const url = `${apiBase()}/api/mcp`;
+function writeMcpConfigs(root, framework) {
+  const url = `${apiBase()}/api/mcp${framework === "react" ? "" : `?framework=${framework}`}`;
   for (const c of mcpClientConfigs(url)) {
     if (!c.projectFile) continue;
     const abs = join3(root, c.file);
@@ -3068,6 +3340,21 @@ ${c.content.replace(/^/gm, "  ")}`);
   }
   log("\nSet BRANDRAIL_KEY in your shell (an API key from Dashboard \u2192 Connect) before starting the AI tool.");
 }
+function projectFramework(cwd, config, flags) {
+  const asked = flags.framework;
+  if (typeof asked === "string") {
+    if (!isFramework(asked)) throw new Error(`Unknown --framework "${asked}". Use one of: ${FRAMEWORKS.join(", ")}.`);
+    return asked;
+  }
+  if (config.framework && isFramework(config.framework)) return config.framework;
+  const pkg = join3(cwd, "package.json");
+  if (!existsSync3(pkg)) return detectFramework(null);
+  try {
+    return detectFramework(JSON.parse(readFileSync2(pkg, "utf8")));
+  } catch {
+    return "react";
+  }
+}
 async function cmdInit(cwd, flags) {
   const target = join3(cwd, CONFIG_FILE);
   let config = starterConfig;
@@ -3092,13 +3379,20 @@ async function cmdInit(cwd, flags) {
 `);
     log(`\u2714 wrote ${CONFIG_FILE}${org ? ` from ${org}'s Brand Kit` : " (starter tokens \u2014 edit them or use --from-api)"}`);
   }
+  const framework = projectFramework(cwd, config, flags);
+  if (config.framework !== framework) {
+    config = { ...config, framework };
+    writeFileSync(target, `${JSON.stringify(config, null, 2)}
+`);
+  }
+  log(`\u2714 framework: ${FRAMEWORK_LABEL[framework]}${flags.framework ? "" : " (detected; change with --framework)"}`);
   const css = flags["tokens-css"] === false ? void 0 : tokensCssPath(cwd, config, flags);
   if (css) {
     const kit = writeTokensCss(cwd, css, config, org);
     log(`\u2714 wrote ${css}  (the Brand Kit as CSS variables${kit ? ", and @brandrail/kit themed from it" : ""} \u2014 import it once at your app entry)`);
   }
   if (flags.rules !== false) for (const f of writeRuleFiles(cwd, config, org, css)) log(`\u2714 updated ${f}`);
-  if (flags.mcp) writeMcpConfigs(cwd);
+  if (flags.mcp) writeMcpConfigs(cwd, framework);
   log("\nNext: npx brandrail check");
   return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brandrail",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Keep AI-generated UI on-brand: checks code and live pages against your design system, and wires your Brand Kit into Claude Code, Cursor, Copilot and Codex.",
   "keywords": [
     "design-system",