@kbach/react 0.6.5 → 0.6.7

package/README.md

@@ -73,6 +73,8 @@ export default defineConfig({
 });
 ```
 
+Adding the plugin also declares `@kbach/react` in Vite's `optimizeDeps.include` upfront, so Vite pre-bundles it during its initial dependency scan instead of discovering it lazily on the first page that imports it — avoiding a forced full-reload mid-render, which is what a rare "Invalid hook call"-style crash on first load (but never again after) usually turns out to be.
+
 Then create an empty `kbach.css` anywhere in your project and import it once in your app entry:
 
 ```css
@@ -88,7 +90,7 @@ import './kbach.css';
 
 The plugin scans your source files and writes generated CSS between the `/* kbach:start */`/`/* kbach:end */` markers. Importing `kbach.css` automatically disables runtime injection — all styles come from the file instead. On HMR, only the changed file is rescanned; unchanged tokens reuse cached CSS.
 
-While it's scanning, the plugin also indexes every `.css`/`.scss`/`.sass`/`.less` file under the same directories and warns in the terminal (not the browser console) for any class that's neither a real Kbach utility nor defined anywhere in those stylesheets — likely a typo. A class you've defined yourself elsewhere (CSS Modules, styled-components, a third-party component's class) is recognized as soon as something in the project literally has a `.that-class-name` rule, so it won't get flagged just because Kbach itself doesn't know it.
+While it's scanning, the plugin also indexes every `.css`/`.scss`/`.sass`/`.less` file under the same directories and warns in the terminal (not the browser console) for any class that's neither a real Kbach utility nor defined anywhere in those stylesheets — likely a typo. A class you've defined yourself elsewhere (CSS Modules, styled-components, a third-party component's class) is recognized as soon as something in the project literally has a `.that-class-name` rule, so it won't get flagged just because Kbach itself doesn't know it. Each warning includes a `file:line:column` location that most terminals (VS Code's integrated terminal included) turn into a clickable link straight to that class.
 
 ## Next.js
 

package/dist/{chunk-FXDK5Z6V.mjs → chunk-5YN6PIXQ.mjs}

@@ -23,7 +23,7 @@ import {
   transformToWebProps,
   useConditionalWidth,
   useGlobalDarkMode
-} from "./chunk-BAUO36PM.mjs";
+} from "./chunk-LXOMVLQI.mjs";
 
 // src/jsx-runtime.tsx
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";

package/dist/{chunk-BAUO36PM.mjs → chunk-LXOMVLQI.mjs}

@@ -565,6 +565,15 @@ function escapeCSSSelector(cls) {
   return cls.replace(/[ !"#$%&'()*+,./:;<=>?@[\\\]^`{|}~]/g, "\\$&");
 }
 
+// src/core/devWarn.ts
+function kbachWarn(message) {
+  console.warn(
+    "%c[kbach]%c " + message,
+    "color:#8b5cf6;font-weight:700",
+    "color:inherit;font-weight:400"
+  );
+}
+
 // src/core/registry.ts
 var BUILTIN_MODIFIERS = {
   // ── Mode ─────────────────────────────────────────────────────────────────
@@ -640,7 +649,7 @@ function _invalidate() {
 }
 function registerModifier(name, def) {
   if (process.env.NODE_ENV !== "production" && name in BUILTIN_MODIFIERS) {
-    console.warn(`[kbach] registerModifier: "${name}" is a built-in modifier and cannot be overridden. Use a different name.`);
+    kbachWarn(`"${name}" is built-in \u2014 pick another modifier name`);
     return;
   }
   _pluginModifiers[name] = def;
@@ -2434,7 +2443,7 @@ function parseClass(className) {
   }
   if (remaining.endsWith("]") && bracketStart === -1) {
     if (process.env.NODE_ENV !== "production") {
-      console.warn(`[kbach] Malformed class string: "${trimmed}" \u2014 unbalanced brackets`);
+      kbachWarn(`Unbalanced brackets: "${trimmed}"`);
     }
   }
   if (remaining.startsWith("[") && remaining.endsWith("]")) {
@@ -2901,7 +2910,7 @@ function resolve(classString, theme, darkMode = "attribute") {
     const styles = resolveUtility(parsed, theme);
     if (!styles) {
       if (process.env.NODE_ENV !== "production" && !parsed.isArbitrary && !isKnownUtility(parsed.utility) && !parsed.original.startsWith("__")) {
-        console.warn(`[kbach] Unknown utility "${parsed.utility}" in class "${parsed.original}"`);
+        kbachWarn(`Unknown class "${parsed.original}"`);
       }
       continue;
     }
@@ -3056,7 +3065,7 @@ function buildConfig(userConfig) {
       for (const [key, value] of Object.entries(ext)) {
         if (typeof value !== "object" || value === null || Array.isArray(value)) {
           if (process.env.NODE_ENV !== "production") {
-            console.warn(`[kbach] config.extend.${key} must be a plain object, got ${typeof value}. Skipping.`);
+            kbachWarn(`extend.${key} should be an object, got ${typeof value} \u2014 skipped`);
           }
           continue;
         }

package/dist/index.js

@@ -690,6 +690,15 @@ function escapeCSSSelector(cls) {
   return cls.replace(/[ !"#$%&'()*+,./:;<=>?@[\\\]^`{|}~]/g, "\\$&");
 }
 
+// src/core/devWarn.ts
+function kbachWarn(message) {
+  console.warn(
+    "%c[kbach]%c " + message,
+    "color:#8b5cf6;font-weight:700",
+    "color:inherit;font-weight:400"
+  );
+}
+
 // src/core/registry.ts
 var BUILTIN_MODIFIERS = {
   // ── Mode ─────────────────────────────────────────────────────────────────
@@ -765,7 +774,7 @@ function _invalidate() {
 }
 function registerModifier(name, def) {
   if (process.env.NODE_ENV !== "production" && name in BUILTIN_MODIFIERS) {
-    console.warn(`[kbach] registerModifier: "${name}" is a built-in modifier and cannot be overridden. Use a different name.`);
+    kbachWarn(`"${name}" is built-in \u2014 pick another modifier name`);
     return;
   }
   _pluginModifiers[name] = def;
@@ -2553,7 +2562,7 @@ function parseClass(className) {
   }
   if (remaining.endsWith("]") && bracketStart === -1) {
     if (process.env.NODE_ENV !== "production") {
-      console.warn(`[kbach] Malformed class string: "${trimmed}" \u2014 unbalanced brackets`);
+      kbachWarn(`Unbalanced brackets: "${trimmed}"`);
     }
   }
   if (remaining.startsWith("[") && remaining.endsWith("]")) {
@@ -2979,7 +2988,7 @@ function resolve(classString, theme, darkMode = "attribute") {
     const styles = resolveUtility(parsed, theme);
     if (!styles) {
       if (process.env.NODE_ENV !== "production" && !parsed.isArbitrary && !isKnownUtility(parsed.utility) && !parsed.original.startsWith("__")) {
-        console.warn(`[kbach] Unknown utility "${parsed.utility}" in class "${parsed.original}"`);
+        kbachWarn(`Unknown class "${parsed.original}"`);
       }
       continue;
     }
@@ -3134,7 +3143,7 @@ function buildConfig(userConfig) {
       for (const [key, value] of Object.entries(ext)) {
         if (typeof value !== "object" || value === null || Array.isArray(value)) {
           if (process.env.NODE_ENV !== "production") {
-            console.warn(`[kbach] config.extend.${key} must be a plain object, got ${typeof value}. Skipping.`);
+            kbachWarn(`extend.${key} should be an object, got ${typeof value} \u2014 skipped`);
           }
           continue;
         }

package/dist/index.mjs

@@ -36,7 +36,7 @@ import {
   useGlobalDarkMode,
   useGlobalWidth,
   useSyncExternalStore
-} from "./chunk-BAUO36PM.mjs";
+} from "./chunk-LXOMVLQI.mjs";
 
 // src/context.tsx
 import { createContext, useContext } from "react";

package/dist/jsx-dev-runtime.js

@@ -643,6 +643,15 @@ function escapeCSSSelector(cls) {
   return cls.replace(/[ !"#$%&'()*+,./:;<=>?@[\\\]^`{|}~]/g, "\\$&");
 }
 
+// src/core/devWarn.ts
+function kbachWarn(message) {
+  console.warn(
+    "%c[kbach]%c " + message,
+    "color:#8b5cf6;font-weight:700",
+    "color:inherit;font-weight:400"
+  );
+}
+
 // src/core/registry.ts
 var BUILTIN_MODIFIERS = {
   // ── Mode ─────────────────────────────────────────────────────────────────
@@ -718,7 +727,7 @@ function _invalidate() {
 }
 function registerModifier(name, def) {
   if (process.env.NODE_ENV !== "production" && name in BUILTIN_MODIFIERS) {
-    console.warn(`[kbach] registerModifier: "${name}" is a built-in modifier and cannot be overridden. Use a different name.`);
+    kbachWarn(`"${name}" is built-in \u2014 pick another modifier name`);
     return;
   }
   _pluginModifiers[name] = def;
@@ -2512,7 +2521,7 @@ function parseClass(className) {
   }
   if (remaining.endsWith("]") && bracketStart === -1) {
     if (process.env.NODE_ENV !== "production") {
-      console.warn(`[kbach] Malformed class string: "${trimmed}" \u2014 unbalanced brackets`);
+      kbachWarn(`Unbalanced brackets: "${trimmed}"`);
     }
   }
   if (remaining.startsWith("[") && remaining.endsWith("]")) {
@@ -2923,7 +2932,7 @@ function resolve(classString, theme, darkMode = "attribute") {
     const styles = resolveUtility(parsed, theme);
     if (!styles) {
       if (process.env.NODE_ENV !== "production" && !parsed.isArbitrary && !isKnownUtility(parsed.utility) && !parsed.original.startsWith("__")) {
-        console.warn(`[kbach] Unknown utility "${parsed.utility}" in class "${parsed.original}"`);
+        kbachWarn(`Unknown class "${parsed.original}"`);
       }
       continue;
     }
@@ -3067,7 +3076,7 @@ function buildConfig(userConfig) {
       for (const [key, value] of Object.entries(ext)) {
         if (typeof value !== "object" || value === null || Array.isArray(value)) {
           if (process.env.NODE_ENV !== "production") {
-            console.warn(`[kbach] config.extend.${key} must be a plain object, got ${typeof value}. Skipping.`);
+            kbachWarn(`extend.${key} should be an object, got ${typeof value} \u2014 skipped`);
           }
           continue;
         }

package/dist/jsx-dev-runtime.mjs

@@ -3,8 +3,8 @@ import {
   Fragment,
   jsx,
   jsxs
-} from "./chunk-FXDK5Z6V.mjs";
-import "./chunk-BAUO36PM.mjs";
+} from "./chunk-5YN6PIXQ.mjs";
+import "./chunk-LXOMVLQI.mjs";
 
 // src/jsx-dev-runtime.tsx
 function jsxDEV(type, props, key, isStaticChildren, source, self) {

package/dist/jsx-runtime.js

@@ -644,6 +644,15 @@ function escapeCSSSelector(cls) {
   return cls.replace(/[ !"#$%&'()*+,./:;<=>?@[\\\]^`{|}~]/g, "\\$&");
 }
 
+// src/core/devWarn.ts
+function kbachWarn(message) {
+  console.warn(
+    "%c[kbach]%c " + message,
+    "color:#8b5cf6;font-weight:700",
+    "color:inherit;font-weight:400"
+  );
+}
+
 // src/core/registry.ts
 var BUILTIN_MODIFIERS = {
   // ── Mode ─────────────────────────────────────────────────────────────────
@@ -719,7 +728,7 @@ function _invalidate() {
 }
 function registerModifier(name, def) {
   if (process.env.NODE_ENV !== "production" && name in BUILTIN_MODIFIERS) {
-    console.warn(`[kbach] registerModifier: "${name}" is a built-in modifier and cannot be overridden. Use a different name.`);
+    kbachWarn(`"${name}" is built-in \u2014 pick another modifier name`);
     return;
   }
   _pluginModifiers[name] = def;
@@ -2513,7 +2522,7 @@ function parseClass(className) {
   }
   if (remaining.endsWith("]") && bracketStart === -1) {
     if (process.env.NODE_ENV !== "production") {
-      console.warn(`[kbach] Malformed class string: "${trimmed}" \u2014 unbalanced brackets`);
+      kbachWarn(`Unbalanced brackets: "${trimmed}"`);
     }
   }
   if (remaining.startsWith("[") && remaining.endsWith("]")) {
@@ -2924,7 +2933,7 @@ function resolve(classString, theme, darkMode = "attribute") {
     const styles = resolveUtility(parsed, theme);
     if (!styles) {
       if (process.env.NODE_ENV !== "production" && !parsed.isArbitrary && !isKnownUtility(parsed.utility) && !parsed.original.startsWith("__")) {
-        console.warn(`[kbach] Unknown utility "${parsed.utility}" in class "${parsed.original}"`);
+        kbachWarn(`Unknown class "${parsed.original}"`);
       }
       continue;
     }
@@ -3068,7 +3077,7 @@ function buildConfig(userConfig) {
       for (const [key, value] of Object.entries(ext)) {
         if (typeof value !== "object" || value === null || Array.isArray(value)) {
           if (process.env.NODE_ENV !== "production") {
-            console.warn(`[kbach] config.extend.${key} must be a plain object, got ${typeof value}. Skipping.`);
+            kbachWarn(`extend.${key} should be an object, got ${typeof value} \u2014 skipped`);
           }
           continue;
         }

package/dist/jsx-runtime.mjs

@@ -4,10 +4,10 @@ import {
   _invalidateDefaultFontCache,
   jsx,
   jsxs
-} from "./chunk-FXDK5Z6V.mjs";
+} from "./chunk-5YN6PIXQ.mjs";
 import {
   registerWebElement
-} from "./chunk-BAUO36PM.mjs";
+} from "./chunk-LXOMVLQI.mjs";
 export {
   Fragment,
   _invalidateDefaultFontCache,

package/dist/vite-plugin.js

@@ -2307,6 +2307,15 @@ function getBuiltinStandaloneNames() {
   return _standaloneNames;
 }
 
+// src/core/devWarn.ts
+function kbachWarn(message) {
+  console.warn(
+    "%c[kbach]%c " + message,
+    "color:#8b5cf6;font-weight:700",
+    "color:inherit;font-weight:400"
+  );
+}
+
 // src/core/registry.ts
 var BUILTIN_MODIFIERS = {
   // ── Mode ─────────────────────────────────────────────────────────────────
@@ -2382,7 +2391,7 @@ function _invalidate() {
 }
 function registerModifier(name, def) {
   if (process.env.NODE_ENV !== "production" && name in BUILTIN_MODIFIERS) {
-    console.warn(`[kbach] registerModifier: "${name}" is a built-in modifier and cannot be overridden. Use a different name.`);
+    kbachWarn(`"${name}" is built-in \u2014 pick another modifier name`);
     return;
   }
   _pluginModifiers[name] = def;
@@ -2461,7 +2470,7 @@ function parseClass(className) {
   }
   if (remaining.endsWith("]") && bracketStart === -1) {
     if (process.env.NODE_ENV !== "production") {
-      console.warn(`[kbach] Malformed class string: "${trimmed}" \u2014 unbalanced brackets`);
+      kbachWarn(`Unbalanced brackets: "${trimmed}"`);
     }
   }
   if (remaining.startsWith("[") && remaining.endsWith("]")) {
@@ -2897,7 +2906,7 @@ function buildConfig(userConfig) {
       for (const [key, value] of Object.entries(ext)) {
         if (typeof value !== "object" || value === null || Array.isArray(value)) {
           if (process.env.NODE_ENV !== "production") {
-            console.warn(`[kbach] config.extend.${key} must be a plain object, got ${typeof value}. Skipping.`);
+            kbachWarn(`extend.${key} should be an object, got ${typeof value} \u2014 skipped`);
           }
           continue;
         }
@@ -2996,6 +3005,39 @@ function normPath(p) {
   return process2.platform === "win32" ? fwd.toLowerCase() : fwd;
 }
 setCSSGenMode(true);
+var useColor = !!process2.stdout?.isTTY && !process2.env.NO_COLOR;
+var paint = (code, s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
+var purple = (s) => paint("35", s);
+var yellow = (s) => paint("33", s);
+var dim = (s) => paint("2", s);
+var bold = (s) => paint("1", s);
+var TAG = () => `${bold(purple("[kbach]"))}`;
+function warn(message) {
+  console.warn(`${TAG()} ${yellow(message)}`);
+}
+function warnBlock(header, ...lines) {
+  console.warn([`${TAG()} ${yellow(header)}`, ...lines].join("\n"));
+}
+function findLineCol(code, needle) {
+  const index = code.indexOf(needle);
+  if (index === -1) return null;
+  let line = 1;
+  let lastNewline = -1;
+  for (let i = 0; i < index; i++) {
+    if (code.charCodeAt(i) === 10) {
+      line++;
+      lastNewline = i;
+    }
+  }
+  return { line, column: index - lastNewline };
+}
+function warnAt(message, root, filePath, code, needle) {
+  const pos = findLineCol(code, needle);
+  const relPath = (0, import_path.relative)(root, filePath).replace(/\\/g, "/");
+  const location = pos ? `${relPath}:${pos.line}:${pos.column}` : relPath;
+  console.warn(`${TAG()} ${yellow(message)}
+  ${dim("at")} ${location}`);
+}
 var KBACH_START = "/* kbach:start */";
 var KBACH_END = "/* kbach:end */";
 var GROUPS = [
@@ -3118,8 +3160,9 @@ function findKbachCSS(root) {
   if (found.length === 0) return null;
   found.sort((a, b) => a.split(/[\\/]/g).length - b.split(/[\\/]/g).length);
   if (found.length > 1) {
-    console.warn(
-      "[kbach] Multiple kbach.css files found \u2014 only the shallowest will receive generated styles.\n        Remove duplicates to avoid confusion:\n" + found.map((f) => `          ${f}`).join("\n")
+    warnBlock(
+      `Multiple kbach.css found, using the shallowest \u2014 remove the rest:`,
+      ...found.map((f) => dim(`  ${f}`))
     );
   }
   return found[0];
@@ -3208,7 +3251,7 @@ function scanDir(dir, onFile) {
     entries = (0, import_fs.readdirSync)(dir);
   } catch (err) {
     if (err.code !== "ENOENT") {
-      console.warn(`[kbach] Cannot read directory ${dir}:`, err.message);
+      warn(`Can't read ${dir}: ${err.message}`);
     }
     return;
   }
@@ -3220,7 +3263,7 @@ function scanDir(dir, onFile) {
       if (st.isDirectory()) scanDir(full, onFile);
       else if (/\.(tsx?|jsx?)$/.test(entry)) onFile(full, (0, import_fs.readFileSync)(full, "utf-8"));
     } catch (err) {
-      console.warn(`[kbach] Cannot process ${full}:`, err.message);
+      warn(`Can't process ${full}: ${err.message}`);
     }
   }
 }
@@ -3272,16 +3315,14 @@ function kbach(userConfigOrOptions) {
   const tokenCSS = /* @__PURE__ */ new Map();
   const projectCssClasses = /* @__PURE__ */ new Set();
   const warnedTokens = /* @__PURE__ */ new Set();
-  function checkUnknownToken(tok) {
+  function checkUnknownToken(tok, filePath, code) {
     if (process2.env.NODE_ENV === "production" || warnedTokens.has(tok) || tok.startsWith("__")) return;
     const parsed = parseClass(tok);
     if (parsed && resolveUtility(parsed, cfg.theme) !== null) return;
     const base = stripModifierPrefix(tok);
     if (!base || projectCssClasses.has(base)) return;
     warnedTokens.add(tok);
-    console.warn(
-      `[kbach] "${tok}" isn't a Kbach utility and no matching CSS rule was found anywhere in the project (checked .css/.scss/.sass/.less files) \u2014 possible typo? If this is intentional (a third-party class, one defined via CSS-in-JS, etc.), this warning is safe to ignore.`
-    );
+    warnAt(`Unknown class "${tok}" \u2014 no Kbach utility or project CSS rule matches it. Typo?`, root, filePath, code, tok);
   }
   function processFile(filePath, code) {
     const key = normPath(filePath);
@@ -3291,7 +3332,7 @@ function kbach(userConfigOrOptions) {
       if (!tokenCSS.has(tok)) {
         tokenCSS.set(tok, generateClassCSS(tok, cfg.theme, cfg.darkMode, screens));
       }
-      checkUnknownToken(tok);
+      checkUnknownToken(tok, filePath, code);
     }
     fileTokens.set(key, tokens);
   }
@@ -3319,12 +3360,29 @@ function kbach(userConfigOrOptions) {
   return {
     name: "kbach",
     enforce: "pre",
+    // Without this, Vite only discovers @kbach/react needs pre-bundling once it
+    // actually crawls into an import of it — typically the FIRST page load — and
+    // has to stop, optimize it, and force a full reload mid-render. That reload
+    // can land in the middle of a render pass (React hooks resolving against a
+    // module graph that's being swapped out from under it), which is what an
+    // "Invalid hook call" / hook-related crash on first load only usually is.
+    // Declaring it here upfront means Vite pre-bundles it during its initial
+    // dependency scan, before any page ever requests it — no mid-render reload.
+    config() {
+      return {
+        optimizeDeps: {
+          include: ["@kbach/react", "@kbach/react/jsx-runtime", "@kbach/react/jsx-dev-runtime"]
+        }
+      };
+    },
     configResolved(resolved) {
       root = resolved.root;
       const names = new Set(resolved.plugins.map((p) => p.name));
       if (names.has("react-router") && names.has("vite:react-refresh")) {
-        console.warn(
-          `[kbach] Detected both @vitejs/plugin-react and @react-router/dev's reactRouter() plugin active together. reactRouter() already includes its own JSX transform and Fast Refresh integration \u2014 having both crashes the page at runtime with "Identifier 'RefreshRuntime' has already been declared" before React hydrates, which looks like every class silently failing to style. Remove the react() plugin from vite.config.ts; jsxImportSource in tsconfig.json is enough on its own.`
+        warnBlock(
+          "@vitejs/plugin-react + reactRouter() conflict \u2014 page will crash before styles apply.",
+          dim('  Both inject Fast Refresh ("RefreshRuntime already declared").'),
+          dim("  Fix: remove react() from vite.config.ts \u2014 tsconfig jsxImportSource is enough.")
         );
       }
     },

package/dist/vite-plugin.mjs

@@ -1,6 +1,6 @@
 // src/vite-plugin.ts
 import { readFileSync, writeFileSync, readdirSync, statSync } from "fs";
-import { join } from "path";
+import { join, relative } from "path";
 import processImport from "process";
 
 // src/core/platform.ts
@@ -2273,6 +2273,15 @@ function getBuiltinStandaloneNames() {
   return _standaloneNames;
 }
 
+// src/core/devWarn.ts
+function kbachWarn(message) {
+  console.warn(
+    "%c[kbach]%c " + message,
+    "color:#8b5cf6;font-weight:700",
+    "color:inherit;font-weight:400"
+  );
+}
+
 // src/core/registry.ts
 var BUILTIN_MODIFIERS = {
   // ── Mode ─────────────────────────────────────────────────────────────────
@@ -2348,7 +2357,7 @@ function _invalidate() {
 }
 function registerModifier(name, def) {
   if (process.env.NODE_ENV !== "production" && name in BUILTIN_MODIFIERS) {
-    console.warn(`[kbach] registerModifier: "${name}" is a built-in modifier and cannot be overridden. Use a different name.`);
+    kbachWarn(`"${name}" is built-in \u2014 pick another modifier name`);
     return;
   }
   _pluginModifiers[name] = def;
@@ -2427,7 +2436,7 @@ function parseClass(className) {
   }
   if (remaining.endsWith("]") && bracketStart === -1) {
     if (process.env.NODE_ENV !== "production") {
-      console.warn(`[kbach] Malformed class string: "${trimmed}" \u2014 unbalanced brackets`);
+      kbachWarn(`Unbalanced brackets: "${trimmed}"`);
     }
   }
   if (remaining.startsWith("[") && remaining.endsWith("]")) {
@@ -2863,7 +2872,7 @@ function buildConfig(userConfig) {
       for (const [key, value] of Object.entries(ext)) {
         if (typeof value !== "object" || value === null || Array.isArray(value)) {
           if (process.env.NODE_ENV !== "production") {
-            console.warn(`[kbach] config.extend.${key} must be a plain object, got ${typeof value}. Skipping.`);
+            kbachWarn(`extend.${key} should be an object, got ${typeof value} \u2014 skipped`);
           }
           continue;
         }
@@ -2962,6 +2971,39 @@ function normPath(p) {
   return process2.platform === "win32" ? fwd.toLowerCase() : fwd;
 }
 setCSSGenMode(true);
+var useColor = !!process2.stdout?.isTTY && !process2.env.NO_COLOR;
+var paint = (code, s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
+var purple = (s) => paint("35", s);
+var yellow = (s) => paint("33", s);
+var dim = (s) => paint("2", s);
+var bold = (s) => paint("1", s);
+var TAG = () => `${bold(purple("[kbach]"))}`;
+function warn(message) {
+  console.warn(`${TAG()} ${yellow(message)}`);
+}
+function warnBlock(header, ...lines) {
+  console.warn([`${TAG()} ${yellow(header)}`, ...lines].join("\n"));
+}
+function findLineCol(code, needle) {
+  const index = code.indexOf(needle);
+  if (index === -1) return null;
+  let line = 1;
+  let lastNewline = -1;
+  for (let i = 0; i < index; i++) {
+    if (code.charCodeAt(i) === 10) {
+      line++;
+      lastNewline = i;
+    }
+  }
+  return { line, column: index - lastNewline };
+}
+function warnAt(message, root, filePath, code, needle) {
+  const pos = findLineCol(code, needle);
+  const relPath = relative(root, filePath).replace(/\\/g, "/");
+  const location = pos ? `${relPath}:${pos.line}:${pos.column}` : relPath;
+  console.warn(`${TAG()} ${yellow(message)}
+  ${dim("at")} ${location}`);
+}
 var KBACH_START = "/* kbach:start */";
 var KBACH_END = "/* kbach:end */";
 var GROUPS = [
@@ -3084,8 +3126,9 @@ function findKbachCSS(root) {
   if (found.length === 0) return null;
   found.sort((a, b) => a.split(/[\\/]/g).length - b.split(/[\\/]/g).length);
   if (found.length > 1) {
-    console.warn(
-      "[kbach] Multiple kbach.css files found \u2014 only the shallowest will receive generated styles.\n        Remove duplicates to avoid confusion:\n" + found.map((f) => `          ${f}`).join("\n")
+    warnBlock(
+      `Multiple kbach.css found, using the shallowest \u2014 remove the rest:`,
+      ...found.map((f) => dim(`  ${f}`))
     );
   }
   return found[0];
@@ -3174,7 +3217,7 @@ function scanDir(dir, onFile) {
     entries = readdirSync(dir);
   } catch (err) {
     if (err.code !== "ENOENT") {
-      console.warn(`[kbach] Cannot read directory ${dir}:`, err.message);
+      warn(`Can't read ${dir}: ${err.message}`);
     }
     return;
   }
@@ -3186,7 +3229,7 @@ function scanDir(dir, onFile) {
       if (st.isDirectory()) scanDir(full, onFile);
       else if (/\.(tsx?|jsx?)$/.test(entry)) onFile(full, readFileSync(full, "utf-8"));
     } catch (err) {
-      console.warn(`[kbach] Cannot process ${full}:`, err.message);
+      warn(`Can't process ${full}: ${err.message}`);
     }
   }
 }
@@ -3238,16 +3281,14 @@ function kbach(userConfigOrOptions) {
   const tokenCSS = /* @__PURE__ */ new Map();
   const projectCssClasses = /* @__PURE__ */ new Set();
   const warnedTokens = /* @__PURE__ */ new Set();
-  function checkUnknownToken(tok) {
+  function checkUnknownToken(tok, filePath, code) {
     if (process2.env.NODE_ENV === "production" || warnedTokens.has(tok) || tok.startsWith("__")) return;
     const parsed = parseClass(tok);
     if (parsed && resolveUtility(parsed, cfg.theme) !== null) return;
     const base = stripModifierPrefix(tok);
     if (!base || projectCssClasses.has(base)) return;
     warnedTokens.add(tok);
-    console.warn(
-      `[kbach] "${tok}" isn't a Kbach utility and no matching CSS rule was found anywhere in the project (checked .css/.scss/.sass/.less files) \u2014 possible typo? If this is intentional (a third-party class, one defined via CSS-in-JS, etc.), this warning is safe to ignore.`
-    );
+    warnAt(`Unknown class "${tok}" \u2014 no Kbach utility or project CSS rule matches it. Typo?`, root, filePath, code, tok);
   }
   function processFile(filePath, code) {
     const key = normPath(filePath);
@@ -3257,7 +3298,7 @@ function kbach(userConfigOrOptions) {
       if (!tokenCSS.has(tok)) {
         tokenCSS.set(tok, generateClassCSS(tok, cfg.theme, cfg.darkMode, screens));
       }
-      checkUnknownToken(tok);
+      checkUnknownToken(tok, filePath, code);
     }
     fileTokens.set(key, tokens);
   }
@@ -3285,12 +3326,29 @@ function kbach(userConfigOrOptions) {
   return {
     name: "kbach",
     enforce: "pre",
+    // Without this, Vite only discovers @kbach/react needs pre-bundling once it
+    // actually crawls into an import of it — typically the FIRST page load — and
+    // has to stop, optimize it, and force a full reload mid-render. That reload
+    // can land in the middle of a render pass (React hooks resolving against a
+    // module graph that's being swapped out from under it), which is what an
+    // "Invalid hook call" / hook-related crash on first load only usually is.
+    // Declaring it here upfront means Vite pre-bundles it during its initial
+    // dependency scan, before any page ever requests it — no mid-render reload.
+    config() {
+      return {
+        optimizeDeps: {
+          include: ["@kbach/react", "@kbach/react/jsx-runtime", "@kbach/react/jsx-dev-runtime"]
+        }
+      };
+    },
     configResolved(resolved) {
       root = resolved.root;
       const names = new Set(resolved.plugins.map((p) => p.name));
       if (names.has("react-router") && names.has("vite:react-refresh")) {
-        console.warn(
-          `[kbach] Detected both @vitejs/plugin-react and @react-router/dev's reactRouter() plugin active together. reactRouter() already includes its own JSX transform and Fast Refresh integration \u2014 having both crashes the page at runtime with "Identifier 'RefreshRuntime' has already been declared" before React hydrates, which looks like every class silently failing to style. Remove the react() plugin from vite.config.ts; jsxImportSource in tsconfig.json is enough on its own.`
+        warnBlock(
+          "@vitejs/plugin-react + reactRouter() conflict \u2014 page will crash before styles apply.",
+          dim('  Both inject Fast Refresh ("RefreshRuntime already declared").'),
+          dim("  Fix: remove react() from vite.config.ts \u2014 tsconfig jsxImportSource is enough.")
         );
       }
     },

package/kbach-react.md

@@ -67,7 +67,7 @@ The `kbach()` Vite plugin scans your source files and writes generated CSS betwe
 - Runs on `buildStart` (initial load) and on every HMR file change
 - Stateless: rescans all files fresh every time — removed classes are immediately evicted
 - Output is grouped by category with CSS custom properties for theme colors
-- Also indexes every `.css`/`.scss`/`.sass`/`.less` file the same `include` dirs cover, and warns (`console.warn`, dev-server terminal, not the browser) for any class that's neither a real Kbach utility NOR defined anywhere in those stylesheets — a likely typo. Classes intentionally handled elsewhere (CSS Modules, styled-components, a third-party component's own class) are recognized once anything in the project literally defines `.that-class-name` and stay silent.
+- Also indexes every `.css`/`.scss`/`.sass`/`.less` file the same `include` dirs cover, and warns (`console.warn`, dev-server terminal, not the browser) for any class that's neither a real Kbach utility NOR defined anywhere in those stylesheets — a likely typo. Classes intentionally handled elsewhere (CSS Modules, styled-components, a third-party component's own class) are recognized once anything in the project literally defines `.that-class-name` and stay silent. Each warning prints a `file:line:column` location that terminals with clickable-link support (VS Code's included) turn into a jump-to-that-class link.
 
 ```ts
 // vite.config.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbach/react",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "React / React Native components and hooks for the Kbach framework",
   "source": "./src/index.ts",
   "main": "./dist/index.js",