@kbach/react 1.0.0-beta.12 → 1.0.0-beta.14

package/README.md

@@ -199,31 +199,24 @@ imports anything from `@kbach/react`'s runtime:
 This default (`darkMode: 'media'`) can't be overridden by an in-app toggle —
 `@media (prefers-color-scheme)` only ever reflects the real OS setting. To
 add a manual light/dark switcher, opt into `darkMode: 'class'` or
-`'attribute'` (writes `.dark`/`data-theme` onto `<html>` instead) — this
-needs setting in **two places**, since they solve two different problems:
-
-1. **Build-time**, via `kbach.config.js` or the plugin's `config`/`theme`
-   option — controls which selector the generated CSS for `dark:` classes
-   compiles to (`[data-theme="dark"] .dark\:bg-neutral-12` vs
-   `.dark .dark\:bg-neutral-12` vs a plain `@media` query).
-2. **Runtime**, via `applyKbachConfig()` — controls what `useTheme()`'s
-   `toggle()`/`setMode()` actually write to the DOM. This is a *separate*
-   module from the build step above (it has to be: the plugin runs in
-   Node during your build, this runs in the browser) — setting only the
-   plugin option compiles the right CSS but leaves the toggle a silent
-   no-op, since the runtime still thinks the strategy is the `'media'`
-   default and has nothing to write to the DOM for it.
+`'attribute'` (writes `.dark`/`data-theme` onto `<html>` instead):
 
 ```js
-// kbach.config.js — build-time, read by the Vite/PostCSS plugin
+// kbach.config.js — a plain object, auto-discovered by the plugin at your
+// project root, no import needed in vite.config.ts/postcss.config.js
 export default { darkMode: 'attribute' };
 ```
 
-```tsx
-// app entry (e.g. root.tsx / main.tsx) — runtime, same value as above
-import { applyKbachConfig, useTheme } from '@kbach/react';
+```ts
+// vite.config.ts — no `config`/`theme` option needed
+import { kbach } from '@kbach/react/vite';
 
-applyKbachConfig({ darkMode: 'attribute' }); // call once, before first render
+export default defineConfig({ plugins: [kbach(), react()] });
+```
+
+```tsx
+// app entry — no applyKbachConfig() call needed either
+import { useTheme } from '@kbach/react';
 
 function ThemeToggle() {
   const { mode, isDark, setMode, toggle } = useTheme();
@@ -231,13 +224,34 @@ function ThemeToggle() {
 }
 ```
 
+That's the whole setup — one file, no runtime call. The generated CSS
+carries the strategy it was built with (as a `--kb-dark-mode` custom
+property), and `useTheme()`'s store reads it back from the DOM at startup,
+so build-time and runtime always agree automatically.
+
+If you're not using the static plugin at all (a pure runtime `kb()` setup,
+with no build step generating `dark:` CSS ahead of time), there's nothing
+for the runtime to auto-detect — call `applyKbachConfig({ darkMode: '...' })`
+yourself instead, once, before your first render:
+
+```tsx
+import { applyKbachConfig, useTheme } from '@kbach/react';
+
+applyKbachConfig({ darkMode: 'attribute' });
+```
+
+An explicit `applyKbachConfig()` call always overrides whatever was
+auto-detected, if you ever need one — e.g. switching strategy at runtime for
+some reason. Keep the value in one shared `kbach.config.js` and import it on
+both sides rather than typing the same literal twice, if you do reach for it.
+
 Works anywhere, no provider needed. `<ThemeProvider defaultMode="dark">` is
 optional, for seeding a startup default. Outside React (plain functions,
 event handlers), use `getGlobalDarkMode()`/`toggleGlobalDarkMode()` instead.
 Note: `useTheme()`/`toggleGlobalDarkMode()` still track `isDark` correctly
-under the default `'media'` strategy too (and even without ever calling
-`applyKbachConfig()`) — they just won't visibly affect `dark:` classes
-unless the runtime has also been told about `'class'`/`'attribute'`.
+under the default `'media'` strategy too (and even without any of the above)
+— they just won't visibly affect `dark:` classes unless the runtime has also
+learned about `'class'`/`'attribute'`, one way or another.
 
 ## Theming
 

package/dist/{chunk-L6B4DTLD.mjs → chunk-D7OC2AE7.mjs}

@@ -1,6 +1,6 @@
 import {
   kb
-} from "./chunk-ROKZPEHA.mjs";
+} from "./chunk-KJY3W4GF.mjs";
 
 // src/jsx-runtime.tsx
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";

package/dist/{chunk-ROKZPEHA.mjs → chunk-KJY3W4GF.mjs}

@@ -2,7 +2,7 @@ import {
   BASE_RESET,
   RESET_STYLE_ID,
   getThemeJson
-} from "./chunk-EOSN5CYG.mjs";
+} from "./chunk-OVKVZA7B.mjs";
 
 // src/wasmLoader.ts
 import init, { generate_css as wasmGenerateCss } from "@kbach/core-engine";
@@ -79,9 +79,23 @@ function ensureResetInjected() {
   el.textContent = BASE_RESET;
   document.head.insertBefore(el, document.head.firstChild);
 }
+var KB_CACHE_MAX = 500;
+var kbCache = /* @__PURE__ */ new Map();
+var cachedForThemeJson = null;
 function kb(classString) {
-  const json = generateCss(classString, getThemeJson());
-  const { className, rules } = JSON.parse(json);
+  const themeJson = getThemeJson();
+  if (themeJson !== cachedForThemeJson) {
+    kbCache.clear();
+    cachedForThemeJson = themeJson;
+  }
+  let result = kbCache.get(classString);
+  if (result === void 0) {
+    const json = generateCss(classString, themeJson);
+    result = JSON.parse(json);
+    if (kbCache.size >= KB_CACHE_MAX) kbCache.clear();
+    kbCache.set(classString, result);
+  }
+  const { className, rules } = result;
   if (!runtimeCSSDisabled) {
     ensureResetInjected();
     for (const { rule, order } of rules) {

package/dist/{chunk-EOSN5CYG.mjs → chunk-OVKVZA7B.mjs}

@@ -377,6 +377,13 @@ function getTheme() {
 function getThemeJson() {
   return activeThemeJson;
 }
+var DARK_MODE_STRATEGIES = /* @__PURE__ */ new Set(["attribute", "class", "media"]);
+function detectDarkModeStrategyFromDom() {
+  if (typeof document === "undefined") return;
+  const raw = getComputedStyle(document.documentElement).getPropertyValue("--kb-dark-mode").trim();
+  if (!DARK_MODE_STRATEGIES.has(raw) || raw === activeTheme.darkMode) return;
+  setTheme({ ...activeTheme, darkMode: raw });
+}
 
 // src/reset.ts
 var RESET_STYLE_ID = "kbach-reset";
@@ -467,6 +474,7 @@ export {
   setTheme,
   getTheme,
   getThemeJson,
+  detectDarkModeStrategyFromDom,
   RESET_STYLE_ID,
   BASE_RESET,
   buildResetCSS

package/dist/{chunk-4Y2QXNJY.mjs → chunk-OWWJ2PME.mjs}

@@ -1,7 +1,101 @@
 import {
   defaultTheme,
+  detectDarkModeStrategyFromDom,
+  getTheme,
   setTheme
-} from "./chunk-EOSN5CYG.mjs";
+} from "./chunk-OVKVZA7B.mjs";
+
+// src/darkModeStore.ts
+var STORAGE_KEY = "kbach-theme";
+var listeners = /* @__PURE__ */ new Set();
+function systemPrefersDark() {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+function storage() {
+  return typeof window === "undefined" ? null : window.localStorage;
+}
+function readPersistedMode() {
+  const ls = storage();
+  if (!ls) return null;
+  try {
+    const raw = ls.getItem(STORAGE_KEY);
+    return raw === "light" || raw === "dark" || raw === "system" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+function resolveIsDark(m) {
+  return m === "system" ? systemPrefersDark() : m === "dark";
+}
+function applyToDom(dark) {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  const strategy = getTheme().darkMode;
+  root.classList.toggle("dark", strategy === "class" && dark);
+  root.classList.toggle("light", strategy === "class" && !dark);
+  if (strategy === "attribute") {
+    root.setAttribute("data-theme", dark ? "dark" : "light");
+  } else {
+    root.removeAttribute("data-theme");
+  }
+}
+detectDarkModeStrategyFromDom();
+var persistedMode = readPersistedMode();
+var hadPersistedMode = persistedMode !== null;
+var mode = persistedMode ?? "system";
+var isDark = resolveIsDark(mode);
+applyToDom(isDark);
+if (typeof window !== "undefined" && window.matchMedia) {
+  const mq = window.matchMedia("(prefers-color-scheme: dark)");
+  const onSystemChange = (event) => {
+    if (mode !== "system") return;
+    isDark = event.matches;
+    applyToDom(isDark);
+    notify();
+  };
+  if (mq.addEventListener) mq.addEventListener("change", onSystemChange);
+  else mq.addListener(onSystemChange);
+}
+function notify() {
+  for (const listener of listeners) listener();
+}
+function resyncDomWithActiveTheme() {
+  applyToDom(isDark);
+}
+function getGlobalDarkMode() {
+  return isDark;
+}
+function getGlobalThemeMode() {
+  return mode;
+}
+function setGlobalThemeMode(nextMode) {
+  mode = nextMode;
+  isDark = resolveIsDark(nextMode);
+  applyToDom(isDark);
+  const ls = storage();
+  if (ls) {
+    try {
+      ls.setItem(STORAGE_KEY, nextMode);
+    } catch {
+    }
+  }
+  notify();
+}
+function toggleGlobalDarkMode() {
+  setGlobalThemeMode(isDark ? "light" : "dark");
+}
+function subscribeGlobalDarkMode(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+function seedDefaultMode(fallback) {
+  if (hadPersistedMode || mode === fallback) return;
+  mode = fallback;
+  isDark = resolveIsDark(fallback);
+  applyToDom(isDark);
+  notify();
+}
 
 // src/colorVariables.ts
 function parseHexRgb(hex) {
@@ -104,12 +198,19 @@ function resolveKbachConfig(config) {
 function applyKbachConfig(config) {
   const theme = resolveKbachConfig(config);
   setTheme(theme);
+  resyncDomWithActiveTheme();
   return theme;
 }
 
 export {
   parseHexRgb,
   ensureColorVariablesInjected,
+  getGlobalDarkMode,
+  getGlobalThemeMode,
+  setGlobalThemeMode,
+  toggleGlobalDarkMode,
+  subscribeGlobalDarkMode,
+  seedDefaultMode,
   resolveKbachConfig,
   applyKbachConfig
 };

package/dist/{chunk-J2M6QWJW.mjs → chunk-XV2ZLURB.mjs}

@@ -1,10 +1,10 @@
 import {
   resolveKbachConfig
-} from "./chunk-4Y2QXNJY.mjs";
+} from "./chunk-OWWJ2PME.mjs";
 import {
   buildResetCSS,
   defaultTheme
-} from "./chunk-EOSN5CYG.mjs";
+} from "./chunk-OVKVZA7B.mjs";
 
 // src/vite-plugin/index.ts
 import { readFileSync as readFileSync3, writeFileSync, mkdirSync, existsSync, statSync as statSync2 } from "fs";
@@ -181,11 +181,9 @@ function formatKbachCSS(tokenRules, theme, usedTags) {
   const spacingMap = buildSpacingVarMap(theme, compact);
   const { text, declarations } = applyVarMap(compact, colorMap, spacingMap);
   const lines = ["/* Generated by Kbach \u2014 do not edit */", "", buildResetCSS(usedTags)];
-  if (declarations.size > 0) {
-    lines.push("", ":root {");
-    for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
-    lines.push("}");
-  }
+  lines.push("", ":root {", `  --kb-dark-mode: ${theme.darkMode};`);
+  for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
+  lines.push("}");
   lines.push("", prettifyCSS(text));
   return lines.join("\n");
 }

package/dist/{config-BQ_b-qxF.d.mts → config-B00tH6vN.d.mts}

@@ -99,7 +99,18 @@ interface KbachConfig {
 }
 /** Merges a `KbachConfig` into `defaultTheme` — a pure function, no side effects. */
 declare function resolveKbachConfig(config: KbachConfig): ThemeConfig;
-/** `resolveKbachConfig()` + `setTheme()` in one call — the usual entry point from app code. Returns the resolved theme (e.g. to also hand to the Vite plugin's own `theme` option). */
+/**
+ * `resolveKbachConfig()` + `setTheme()` in one call — the usual entry point
+ * from app code. Returns the resolved theme (e.g. to also hand to the Vite
+ * plugin's own `theme` option).
+ *
+ * Also re-syncs the DOM to the CURRENT dark-mode state right after
+ * `setTheme()` — see `resyncDomWithActiveTheme`'s own doc comment for why
+ * this is required, not optional: without it, an app that configures
+ * `darkMode: 'attribute'`/`'class'` here can silently never apply its
+ * `dark:` classes on initial load (even though `useTheme().isDark` reads
+ * correctly) until some later, unrelated dark-mode event happens to fire.
+ */
 declare function applyKbachConfig(config: KbachConfig): ThemeConfig;
 
 export { type ColorEntry as C, type DarkModeStrategy as D, type KbachConfig as K, type ThemeConfig as T, type ContainerConfig as a, applyKbachConfig as b, defaultTheme as d, getTheme as g, resolveKbachConfig as r, setTheme as s };

package/dist/{config-BQ_b-qxF.d.ts → config-B00tH6vN.d.ts}

@@ -99,7 +99,18 @@ interface KbachConfig {
 }
 /** Merges a `KbachConfig` into `defaultTheme` — a pure function, no side effects. */
 declare function resolveKbachConfig(config: KbachConfig): ThemeConfig;
-/** `resolveKbachConfig()` + `setTheme()` in one call — the usual entry point from app code. Returns the resolved theme (e.g. to also hand to the Vite plugin's own `theme` option). */
+/**
+ * `resolveKbachConfig()` + `setTheme()` in one call — the usual entry point
+ * from app code. Returns the resolved theme (e.g. to also hand to the Vite
+ * plugin's own `theme` option).
+ *
+ * Also re-syncs the DOM to the CURRENT dark-mode state right after
+ * `setTheme()` — see `resyncDomWithActiveTheme`'s own doc comment for why
+ * this is required, not optional: without it, an app that configures
+ * `darkMode: 'attribute'`/`'class'` here can silently never apply its
+ * `dark:` classes on initial load (even though `useTheme().isDark` reads
+ * correctly) until some later, unrelated dark-mode event happens to fire.
+ */
 declare function applyKbachConfig(config: KbachConfig): ThemeConfig;
 
 export { type ColorEntry as C, type DarkModeStrategy as D, type KbachConfig as K, type ThemeConfig as T, type ContainerConfig as a, applyKbachConfig as b, defaultTheme as d, getTheme as g, resolveKbachConfig as r, setTheme as s };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-export { C as ColorEntry, a as ContainerConfig, D as DarkModeStrategy, K as KbachConfig, T as ThemeConfig, b as applyKbachConfig, d as defaultTheme, g as getTheme, r as resolveKbachConfig, s as setTheme } from './config-BQ_b-qxF.mjs';
+export { C as ColorEntry, a as ContainerConfig, D as DarkModeStrategy, K as KbachConfig, T as ThemeConfig, b as applyKbachConfig, d as defaultTheme, g as getTheme, r as resolveKbachConfig, s as setTheme } from './config-B00tH6vN.mjs';
 import * as react from 'react';
 import { ReactNode } from 'react';
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { C as ColorEntry, a as ContainerConfig, D as DarkModeStrategy, K as KbachConfig, T as ThemeConfig, b as applyKbachConfig, d as defaultTheme, g as getTheme, r as resolveKbachConfig, s as setTheme } from './config-BQ_b-qxF.js';
+export { C as ColorEntry, a as ContainerConfig, D as DarkModeStrategy, K as KbachConfig, T as ThemeConfig, b as applyKbachConfig, d as defaultTheme, g as getTheme, r as resolveKbachConfig, s as setTheme } from './config-B00tH6vN.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 

package/dist/index.js

@@ -455,6 +455,13 @@ function getTheme() {
 function getThemeJson() {
   return activeThemeJson;
 }
+var DARK_MODE_STRATEGIES = /* @__PURE__ */ new Set(["attribute", "class", "media"]);
+function detectDarkModeStrategyFromDom() {
+  if (typeof document === "undefined") return;
+  const raw = getComputedStyle(document.documentElement).getPropertyValue("--kb-dark-mode").trim();
+  if (!DARK_MODE_STRATEGIES.has(raw) || raw === activeTheme.darkMode) return;
+  setTheme({ ...activeTheme, darkMode: raw });
+}
 
 // src/reset.ts
 var RESET_STYLE_ID = "kbach-reset";
@@ -587,9 +594,23 @@ function ensureResetInjected() {
   el.textContent = BASE_RESET;
   document.head.insertBefore(el, document.head.firstChild);
 }
+var KB_CACHE_MAX = 500;
+var kbCache = /* @__PURE__ */ new Map();
+var cachedForThemeJson = null;
 function kb(classString) {
-  const json = generateCss(classString, getThemeJson());
-  const { className, rules } = JSON.parse(json);
+  const themeJson = getThemeJson();
+  if (themeJson !== cachedForThemeJson) {
+    kbCache.clear();
+    cachedForThemeJson = themeJson;
+  }
+  let result = kbCache.get(classString);
+  if (result === void 0) {
+    const json = generateCss(classString, themeJson);
+    result = JSON.parse(json);
+    if (kbCache.size >= KB_CACHE_MAX) kbCache.clear();
+    kbCache.set(classString, result);
+  }
+  const { className, rules } = result;
   if (!runtimeCSSDisabled) {
     ensureResetInjected();
     for (const { rule, order } of rules) {
@@ -656,63 +677,6 @@ function ensureColorVariablesInjected(theme) {
 ${wrapDarkDecls(theme.darkMode, darkDecls.join(" "))}`;
 }
 
-// src/config.ts
-function applyOpacityToHex(hex, opacityText) {
-  const rgb = parseHexRgb(hex);
-  if (!rgb) return hex;
-  const a = Number(opacityText) / 100;
-  const clamped = Number.isFinite(a) ? Math.min(1, Math.max(0, a)) : 1;
-  return `rgba(${rgb.join(",")},${clamped})`;
-}
-function resolveColorEntry(value, lookup) {
-  if (typeof value !== "string") return value;
-  const slash = value.indexOf("/");
-  const name = slash === -1 ? value : value.slice(0, slash);
-  const opacity = slash === -1 ? void 0 : value.slice(slash + 1);
-  const base = lookup(name);
-  if (base === void 0) return value;
-  if (opacity === void 0) return base;
-  return typeof base === "string" ? applyOpacityToHex(base, opacity) : { light: applyOpacityToHex(base.light, opacity), dark: applyOpacityToHex(base.dark, opacity) };
-}
-function resolveColors(extend, existing) {
-  const resolved = {};
-  const lookup = (name) => resolved[name] ?? existing[name];
-  for (const [name, value] of Object.entries(extend)) {
-    resolved[name] = resolveColorEntry(value, lookup);
-  }
-  return resolved;
-}
-function resolveKbachConfig(config) {
-  let theme = { ...defaultTheme, ...config.theme };
-  if (config.extend?.colors) {
-    theme = { ...theme, colors: { ...theme.colors, ...resolveColors(config.extend.colors, theme.colors) } };
-  }
-  if (config.extend?.spacing) {
-    theme = { ...theme, spacing: { ...theme.spacing, ...config.extend.spacing } };
-  }
-  if (config.extend?.screens) {
-    theme = { ...theme, screens: { ...theme.screens, ...config.extend.screens } };
-  }
-  if (config.extend?.fontFamily) {
-    theme = { ...theme, fontFamily: { ...theme.fontFamily, ...config.extend.fontFamily } };
-  }
-  if (config.extend?.container) {
-    theme = { ...theme, container: { ...theme.container, ...config.extend.container } };
-  }
-  if (config.darkMode) {
-    theme = { ...theme, darkMode: config.darkMode };
-  }
-  return theme;
-}
-function applyKbachConfig(config) {
-  const theme = resolveKbachConfig(config);
-  setTheme(theme);
-  return theme;
-}
-
-// src/useTheme.ts
-var import_react = require("react");
-
 // src/darkModeStore.ts
 var STORAGE_KEY = "kbach-theme";
 var listeners = /* @__PURE__ */ new Set();
@@ -740,13 +704,15 @@ function applyToDom(dark) {
   if (typeof document === "undefined") return;
   const root = document.documentElement;
   const strategy = getTheme().darkMode;
-  if (strategy === "class") {
-    root.classList.toggle("dark", dark);
-    root.classList.toggle("light", !dark);
-  } else if (strategy === "attribute") {
+  root.classList.toggle("dark", strategy === "class" && dark);
+  root.classList.toggle("light", strategy === "class" && !dark);
+  if (strategy === "attribute") {
     root.setAttribute("data-theme", dark ? "dark" : "light");
+  } else {
+    root.removeAttribute("data-theme");
   }
 }
+detectDarkModeStrategyFromDom();
 var persistedMode = readPersistedMode();
 var hadPersistedMode = persistedMode !== null;
 var mode = persistedMode ?? "system";
@@ -766,6 +732,9 @@ if (typeof window !== "undefined" && window.matchMedia) {
 function notify() {
   for (const listener of listeners) listener();
 }
+function resyncDomWithActiveTheme() {
+  applyToDom(isDark);
+}
 function getGlobalDarkMode() {
   return isDark;
 }
@@ -800,7 +769,63 @@ function seedDefaultMode(fallback) {
   notify();
 }
 
+// src/config.ts
+function applyOpacityToHex(hex, opacityText) {
+  const rgb = parseHexRgb(hex);
+  if (!rgb) return hex;
+  const a = Number(opacityText) / 100;
+  const clamped = Number.isFinite(a) ? Math.min(1, Math.max(0, a)) : 1;
+  return `rgba(${rgb.join(",")},${clamped})`;
+}
+function resolveColorEntry(value, lookup) {
+  if (typeof value !== "string") return value;
+  const slash = value.indexOf("/");
+  const name = slash === -1 ? value : value.slice(0, slash);
+  const opacity = slash === -1 ? void 0 : value.slice(slash + 1);
+  const base = lookup(name);
+  if (base === void 0) return value;
+  if (opacity === void 0) return base;
+  return typeof base === "string" ? applyOpacityToHex(base, opacity) : { light: applyOpacityToHex(base.light, opacity), dark: applyOpacityToHex(base.dark, opacity) };
+}
+function resolveColors(extend, existing) {
+  const resolved = {};
+  const lookup = (name) => resolved[name] ?? existing[name];
+  for (const [name, value] of Object.entries(extend)) {
+    resolved[name] = resolveColorEntry(value, lookup);
+  }
+  return resolved;
+}
+function resolveKbachConfig(config) {
+  let theme = { ...defaultTheme, ...config.theme };
+  if (config.extend?.colors) {
+    theme = { ...theme, colors: { ...theme.colors, ...resolveColors(config.extend.colors, theme.colors) } };
+  }
+  if (config.extend?.spacing) {
+    theme = { ...theme, spacing: { ...theme.spacing, ...config.extend.spacing } };
+  }
+  if (config.extend?.screens) {
+    theme = { ...theme, screens: { ...theme.screens, ...config.extend.screens } };
+  }
+  if (config.extend?.fontFamily) {
+    theme = { ...theme, fontFamily: { ...theme.fontFamily, ...config.extend.fontFamily } };
+  }
+  if (config.extend?.container) {
+    theme = { ...theme, container: { ...theme.container, ...config.extend.container } };
+  }
+  if (config.darkMode) {
+    theme = { ...theme, darkMode: config.darkMode };
+  }
+  return theme;
+}
+function applyKbachConfig(config) {
+  const theme = resolveKbachConfig(config);
+  setTheme(theme);
+  resyncDomWithActiveTheme();
+  return theme;
+}
+
 // src/useTheme.ts
+var import_react = require("react");
 function useTheme() {
   const isDark2 = (0, import_react.useSyncExternalStore)(subscribeGlobalDarkMode, getGlobalDarkMode, () => false);
   const mode2 = (0, import_react.useSyncExternalStore)(subscribeGlobalDarkMode, getGlobalThemeMode, () => "system");
@@ -838,6 +863,7 @@ function ThemeProvider({ children, defaultMode = "system" }) {
 }
 
 // src/useColors.ts
+var import_react3 = require("react");
 function applyOpacity(color, opacity) {
   const a = Math.max(0, Math.min(1, opacity / 100));
   const varMatch = /^rgb\(var\((--[\w-]+)\)\)$/.exec(color);
@@ -898,7 +924,7 @@ function useColors() {
   const { isDark: isDark2 } = useTheme();
   const theme = getTheme();
   ensureColorVariablesInjected(theme);
-  return makeColorsProxy(theme, isDark2);
+  return (0, import_react3.useMemo)(() => makeColorsProxy(theme, isDark2), [theme, isDark2]);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -4,20 +4,26 @@ import {
   isKbachReady,
   isRuntimeCSSDisabled,
   kb
-} from "./chunk-ROKZPEHA.mjs";
+} from "./chunk-KJY3W4GF.mjs";
 import {
   applyKbachConfig,
   ensureColorVariablesInjected,
+  getGlobalDarkMode,
+  getGlobalThemeMode,
   parseHexRgb,
-  resolveKbachConfig
-} from "./chunk-4Y2QXNJY.mjs";
+  resolveKbachConfig,
+  seedDefaultMode,
+  setGlobalThemeMode,
+  subscribeGlobalDarkMode,
+  toggleGlobalDarkMode
+} from "./chunk-OWWJ2PME.mjs";
 import {
   BASE_RESET,
   RESET_STYLE_ID,
   defaultTheme,
   getTheme,
   setTheme
-} from "./chunk-EOSN5CYG.mjs";
+} from "./chunk-OVKVZA7B.mjs";
 
 // src/KbachReset.tsx
 import { jsx } from "react/jsx-runtime";
@@ -28,101 +34,12 @@ function KbachReset() {
 
 // src/useTheme.ts
 import { useMemo, useSyncExternalStore } from "react";
-
-// src/darkModeStore.ts
-var STORAGE_KEY = "kbach-theme";
-var listeners = /* @__PURE__ */ new Set();
-function systemPrefersDark() {
-  if (typeof window === "undefined" || !window.matchMedia) return false;
-  return window.matchMedia("(prefers-color-scheme: dark)").matches;
-}
-function storage() {
-  return typeof window === "undefined" ? null : window.localStorage;
-}
-function readPersistedMode() {
-  const ls = storage();
-  if (!ls) return null;
-  try {
-    const raw = ls.getItem(STORAGE_KEY);
-    return raw === "light" || raw === "dark" || raw === "system" ? raw : null;
-  } catch {
-    return null;
-  }
-}
-function resolveIsDark(m) {
-  return m === "system" ? systemPrefersDark() : m === "dark";
-}
-function applyToDom(dark) {
-  if (typeof document === "undefined") return;
-  const root = document.documentElement;
-  const strategy = getTheme().darkMode;
-  if (strategy === "class") {
-    root.classList.toggle("dark", dark);
-    root.classList.toggle("light", !dark);
-  } else if (strategy === "attribute") {
-    root.setAttribute("data-theme", dark ? "dark" : "light");
-  }
-}
-var persistedMode = readPersistedMode();
-var hadPersistedMode = persistedMode !== null;
-var mode = persistedMode ?? "system";
-var isDark = resolveIsDark(mode);
-applyToDom(isDark);
-if (typeof window !== "undefined" && window.matchMedia) {
-  const mq = window.matchMedia("(prefers-color-scheme: dark)");
-  const onSystemChange = (event) => {
-    if (mode !== "system") return;
-    isDark = event.matches;
-    applyToDom(isDark);
-    notify();
-  };
-  if (mq.addEventListener) mq.addEventListener("change", onSystemChange);
-  else mq.addListener(onSystemChange);
-}
-function notify() {
-  for (const listener of listeners) listener();
-}
-function getGlobalDarkMode() {
-  return isDark;
-}
-function getGlobalThemeMode() {
-  return mode;
-}
-function setGlobalThemeMode(nextMode) {
-  mode = nextMode;
-  isDark = resolveIsDark(nextMode);
-  applyToDom(isDark);
-  const ls = storage();
-  if (ls) {
-    try {
-      ls.setItem(STORAGE_KEY, nextMode);
-    } catch {
-    }
-  }
-  notify();
-}
-function toggleGlobalDarkMode() {
-  setGlobalThemeMode(isDark ? "light" : "dark");
-}
-function subscribeGlobalDarkMode(listener) {
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-}
-function seedDefaultMode(fallback) {
-  if (hadPersistedMode || mode === fallback) return;
-  mode = fallback;
-  isDark = resolveIsDark(fallback);
-  applyToDom(isDark);
-  notify();
-}
-
-// src/useTheme.ts
 function useTheme() {
-  const isDark2 = useSyncExternalStore(subscribeGlobalDarkMode, getGlobalDarkMode, () => false);
-  const mode2 = useSyncExternalStore(subscribeGlobalDarkMode, getGlobalThemeMode, () => "system");
+  const isDark = useSyncExternalStore(subscribeGlobalDarkMode, getGlobalDarkMode, () => false);
+  const mode = useSyncExternalStore(subscribeGlobalDarkMode, getGlobalThemeMode, () => "system");
   return useMemo(
-    () => ({ mode: mode2, isDark: isDark2, setMode: setGlobalThemeMode, toggle: toggleGlobalDarkMode }),
-    [mode2, isDark2]
+    () => ({ mode, isDark, setMode: setGlobalThemeMode, toggle: toggleGlobalDarkMode }),
+    [mode, isDark]
   );
 }
 
@@ -154,6 +71,7 @@ function ThemeProvider({ children, defaultMode = "system" }) {
 }
 
 // src/useColors.ts
+import { useMemo as useMemo2 } from "react";
 function applyOpacity(color, opacity) {
   const a = Math.max(0, Math.min(1, opacity / 100));
   const varMatch = /^rgb\(var\((--[\w-]+)\)\)$/.exec(color);
@@ -166,14 +84,14 @@ function applyOpacity(color, opacity) {
   if (color.startsWith("rgba(")) return color.replace(/,\s*[\d.]+\)$/, `,${a})`);
   return color;
 }
-function resolveEntry(name, entry, isDark2) {
+function resolveEntry(name, entry, isDark) {
   if (typeof entry === "string") return entry;
   const light = parseHexRgb(entry.light);
   const dark = parseHexRgb(entry.dark);
   if (light && dark) return `rgb(var(--kb-color-${name}))`;
-  return isDark2 ? entry.dark : entry.light;
+  return isDark ? entry.dark : entry.light;
 }
-function makeColorsProxy(theme, isDark2) {
+function makeColorsProxy(theme, isDark) {
   const alpha = (color, opacity) => opacity === void 0 ? color : applyOpacity(color, opacity);
   const cache = /* @__PURE__ */ new Map();
   function resolveNamed(key) {
@@ -186,7 +104,7 @@ function makeColorsProxy(theme, isDark2) {
     }
     const entry = theme.colors[name];
     if (entry === void 0) return void 0;
-    const value = resolveEntry(name, entry, isDark2);
+    const value = resolveEntry(name, entry, isDark);
     return opacity === void 0 ? value : applyOpacity(value, opacity);
   }
   function makeFamilyProxy(family) {
@@ -211,10 +129,10 @@ function makeColorsProxy(theme, isDark2) {
   });
 }
 function useColors() {
-  const { isDark: isDark2 } = useTheme();
+  const { isDark } = useTheme();
   const theme = getTheme();
   ensureColorVariablesInjected(theme);
-  return makeColorsProxy(theme, isDark2);
+  return useMemo2(() => makeColorsProxy(theme, isDark), [theme, isDark]);
 }
 export {
   KbachReset,

package/dist/jsx-dev-runtime.js

@@ -548,9 +548,23 @@ function ensureResetInjected() {
   el.textContent = BASE_RESET;
   document.head.insertBefore(el, document.head.firstChild);
 }
+var KB_CACHE_MAX = 500;
+var kbCache = /* @__PURE__ */ new Map();
+var cachedForThemeJson = null;
 function kb(classString) {
-  const json = generateCss(classString, getThemeJson());
-  const { className, rules } = JSON.parse(json);
+  const themeJson = getThemeJson();
+  if (themeJson !== cachedForThemeJson) {
+    kbCache.clear();
+    cachedForThemeJson = themeJson;
+  }
+  let result = kbCache.get(classString);
+  if (result === void 0) {
+    const json = generateCss(classString, themeJson);
+    result = JSON.parse(json);
+    if (kbCache.size >= KB_CACHE_MAX) kbCache.clear();
+    kbCache.set(classString, result);
+  }
+  const { className, rules } = result;
   if (!runtimeCSSDisabled) {
     ensureResetInjected();
     for (const { rule, order } of rules) {

package/dist/jsx-dev-runtime.mjs

@@ -2,9 +2,9 @@ import {
   Fragment,
   jsx,
   jsxs
-} from "./chunk-L6B4DTLD.mjs";
-import "./chunk-ROKZPEHA.mjs";
-import "./chunk-EOSN5CYG.mjs";
+} from "./chunk-D7OC2AE7.mjs";
+import "./chunk-KJY3W4GF.mjs";
+import "./chunk-OVKVZA7B.mjs";
 
 // src/jsx-dev-runtime.tsx
 function jsxDEV(type, props, key, isStaticChildren, source, self) {

package/dist/jsx-runtime.js

@@ -547,9 +547,23 @@ function ensureResetInjected() {
   el.textContent = BASE_RESET;
   document.head.insertBefore(el, document.head.firstChild);
 }
+var KB_CACHE_MAX = 500;
+var kbCache = /* @__PURE__ */ new Map();
+var cachedForThemeJson = null;
 function kb(classString) {
-  const json = generateCss(classString, getThemeJson());
-  const { className, rules } = JSON.parse(json);
+  const themeJson = getThemeJson();
+  if (themeJson !== cachedForThemeJson) {
+    kbCache.clear();
+    cachedForThemeJson = themeJson;
+  }
+  let result = kbCache.get(classString);
+  if (result === void 0) {
+    const json = generateCss(classString, themeJson);
+    result = JSON.parse(json);
+    if (kbCache.size >= KB_CACHE_MAX) kbCache.clear();
+    kbCache.set(classString, result);
+  }
+  const { className, rules } = result;
   if (!runtimeCSSDisabled) {
     ensureResetInjected();
     for (const { rule, order } of rules) {

package/dist/jsx-runtime.mjs

@@ -2,9 +2,9 @@ import {
   Fragment,
   jsx,
   jsxs
-} from "./chunk-L6B4DTLD.mjs";
-import "./chunk-ROKZPEHA.mjs";
-import "./chunk-EOSN5CYG.mjs";
+} from "./chunk-D7OC2AE7.mjs";
+import "./chunk-KJY3W4GF.mjs";
+import "./chunk-OVKVZA7B.mjs";
 export {
   Fragment,
   jsx,

package/dist/postcss-plugin.d.mts

@@ -1,5 +1,5 @@
 import { Plugin } from 'postcss';
-import { T as ThemeConfig, K as KbachConfig } from './config-BQ_b-qxF.mjs';
+import { T as ThemeConfig, K as KbachConfig } from './config-B00tH6vN.mjs';
 
 interface KbachPostcssPluginOptions {
     /**

package/dist/postcss-plugin.d.ts

@@ -1,5 +1,5 @@
 import { Plugin } from 'postcss';
-import { T as ThemeConfig, K as KbachConfig } from './config-BQ_b-qxF.js';
+import { T as ThemeConfig, K as KbachConfig } from './config-B00tH6vN.js';
 
 interface KbachPostcssPluginOptions {
     /**

package/dist/postcss-plugin.js

@@ -476,11 +476,9 @@ function formatKbachCSS(tokenRules, theme, usedTags) {
   const spacingMap = buildSpacingVarMap(theme, compact);
   const { text, declarations } = applyVarMap(compact, colorMap, spacingMap);
   const lines = ["/* Generated by Kbach \u2014 do not edit */", "", buildResetCSS(usedTags)];
-  if (declarations.size > 0) {
-    lines.push("", ":root {");
-    for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
-    lines.push("}");
-  }
+  lines.push("", ":root {", `  --kb-dark-mode: ${theme.darkMode};`);
+  for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
+  lines.push("}");
   lines.push("", prettifyCSS(text));
   return lines.join("\n");
 }
@@ -988,7 +986,22 @@ var defaultTheme = {
   // centering/padding) — see `ContainerConfig`'s own doc comment.
   container: {}
 };
+var activeTheme = defaultTheme;
 var activeThemeJson = JSON.stringify(defaultTheme);
+function setTheme(theme) {
+  activeTheme = theme;
+  activeThemeJson = JSON.stringify(theme);
+}
+function getTheme() {
+  return activeTheme;
+}
+var DARK_MODE_STRATEGIES = /* @__PURE__ */ new Set(["attribute", "class", "media"]);
+function detectDarkModeStrategyFromDom() {
+  if (typeof document === "undefined") return;
+  const raw = getComputedStyle(document.documentElement).getPropertyValue("--kb-dark-mode").trim();
+  if (!DARK_MODE_STRATEGIES.has(raw) || raw === activeTheme.darkMode) return;
+  setTheme({ ...activeTheme, darkMode: raw });
+}
 
 // src/colorVariables.ts
 function parseHexRgb(hex) {
@@ -1000,6 +1013,61 @@ function parseHexRgb(hex) {
   return [n >> 16 & 255, n >> 8 & 255, n & 255];
 }
 
+// src/darkModeStore.ts
+var STORAGE_KEY = "kbach-theme";
+var listeners = /* @__PURE__ */ new Set();
+function systemPrefersDark() {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+function storage() {
+  return typeof window === "undefined" ? null : window.localStorage;
+}
+function readPersistedMode() {
+  const ls = storage();
+  if (!ls) return null;
+  try {
+    const raw = ls.getItem(STORAGE_KEY);
+    return raw === "light" || raw === "dark" || raw === "system" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+function resolveIsDark(m) {
+  return m === "system" ? systemPrefersDark() : m === "dark";
+}
+function applyToDom(dark) {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  const strategy = getTheme().darkMode;
+  root.classList.toggle("dark", strategy === "class" && dark);
+  root.classList.toggle("light", strategy === "class" && !dark);
+  if (strategy === "attribute") {
+    root.setAttribute("data-theme", dark ? "dark" : "light");
+  } else {
+    root.removeAttribute("data-theme");
+  }
+}
+detectDarkModeStrategyFromDom();
+var persistedMode = readPersistedMode();
+var mode = persistedMode ?? "system";
+var isDark = resolveIsDark(mode);
+applyToDom(isDark);
+if (typeof window !== "undefined" && window.matchMedia) {
+  const mq = window.matchMedia("(prefers-color-scheme: dark)");
+  const onSystemChange = (event) => {
+    if (mode !== "system") return;
+    isDark = event.matches;
+    applyToDom(isDark);
+    notify();
+  };
+  if (mq.addEventListener) mq.addEventListener("change", onSystemChange);
+  else mq.addListener(onSystemChange);
+}
+function notify() {
+  for (const listener of listeners) listener();
+}
+
 // src/config.ts
 function applyOpacityToHex(hex, opacityText) {
   const rgb = parseHexRgb(hex);

package/dist/postcss-plugin.mjs

@@ -2,9 +2,9 @@ import {
   DEFAULT_SCAN_DIRS,
   createKbachStaticCssEngine,
   resolveEffectiveTheme
-} from "./chunk-J2M6QWJW.mjs";
-import "./chunk-4Y2QXNJY.mjs";
-import "./chunk-EOSN5CYG.mjs";
+} from "./chunk-XV2ZLURB.mjs";
+import "./chunk-OWWJ2PME.mjs";
+import "./chunk-OVKVZA7B.mjs";
 
 // src/postcss-plugin/index.ts
 import postcss from "postcss";

package/dist/vite-plugin.d.mts

@@ -1,5 +1,5 @@
 import { Plugin } from 'vite';
-import { T as ThemeConfig, K as KbachConfig } from './config-BQ_b-qxF.mjs';
+import { T as ThemeConfig, K as KbachConfig } from './config-B00tH6vN.mjs';
 
 interface KbachPluginOptions {
     /** Defaults to the same defaultTheme the runtime uses — pass your own to keep both in sync. */

package/dist/vite-plugin.d.ts

@@ -1,5 +1,5 @@
 import { Plugin } from 'vite';
-import { T as ThemeConfig, K as KbachConfig } from './config-BQ_b-qxF.js';
+import { T as ThemeConfig, K as KbachConfig } from './config-B00tH6vN.js';
 
 interface KbachPluginOptions {
     /** Defaults to the same defaultTheme the runtime uses — pass your own to keep both in sync. */

package/dist/vite-plugin.js

@@ -285,11 +285,9 @@ function formatKbachCSS(tokenRules, theme, usedTags) {
   const spacingMap = buildSpacingVarMap(theme, compact);
   const { text, declarations } = applyVarMap(compact, colorMap, spacingMap);
   const lines = ["/* Generated by Kbach \u2014 do not edit */", "", buildResetCSS(usedTags)];
-  if (declarations.size > 0) {
-    lines.push("", ":root {");
-    for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
-    lines.push("}");
-  }
+  lines.push("", ":root {", `  --kb-dark-mode: ${theme.darkMode};`);
+  for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
+  lines.push("}");
   lines.push("", prettifyCSS(text));
   return lines.join("\n");
 }
@@ -1382,7 +1380,22 @@ var defaultTheme = {
   // centering/padding) — see `ContainerConfig`'s own doc comment.
   container: {}
 };
+var activeTheme = defaultTheme;
 var activeThemeJson = JSON.stringify(defaultTheme);
+function setTheme(theme) {
+  activeTheme = theme;
+  activeThemeJson = JSON.stringify(theme);
+}
+function getTheme() {
+  return activeTheme;
+}
+var DARK_MODE_STRATEGIES = /* @__PURE__ */ new Set(["attribute", "class", "media"]);
+function detectDarkModeStrategyFromDom() {
+  if (typeof document === "undefined") return;
+  const raw = getComputedStyle(document.documentElement).getPropertyValue("--kb-dark-mode").trim();
+  if (!DARK_MODE_STRATEGIES.has(raw) || raw === activeTheme.darkMode) return;
+  setTheme({ ...activeTheme, darkMode: raw });
+}
 
 // src/colorVariables.ts
 function parseHexRgb(hex) {
@@ -1394,6 +1407,61 @@ function parseHexRgb(hex) {
   return [n >> 16 & 255, n >> 8 & 255, n & 255];
 }
 
+// src/darkModeStore.ts
+var STORAGE_KEY = "kbach-theme";
+var listeners = /* @__PURE__ */ new Set();
+function systemPrefersDark() {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+function storage() {
+  return typeof window === "undefined" ? null : window.localStorage;
+}
+function readPersistedMode() {
+  const ls = storage();
+  if (!ls) return null;
+  try {
+    const raw = ls.getItem(STORAGE_KEY);
+    return raw === "light" || raw === "dark" || raw === "system" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+function resolveIsDark(m) {
+  return m === "system" ? systemPrefersDark() : m === "dark";
+}
+function applyToDom(dark) {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  const strategy = getTheme().darkMode;
+  root.classList.toggle("dark", strategy === "class" && dark);
+  root.classList.toggle("light", strategy === "class" && !dark);
+  if (strategy === "attribute") {
+    root.setAttribute("data-theme", dark ? "dark" : "light");
+  } else {
+    root.removeAttribute("data-theme");
+  }
+}
+detectDarkModeStrategyFromDom();
+var persistedMode = readPersistedMode();
+var mode = persistedMode ?? "system";
+var isDark = resolveIsDark(mode);
+applyToDom(isDark);
+if (typeof window !== "undefined" && window.matchMedia) {
+  const mq = window.matchMedia("(prefers-color-scheme: dark)");
+  const onSystemChange = (event) => {
+    if (mode !== "system") return;
+    isDark = event.matches;
+    applyToDom(isDark);
+    notify();
+  };
+  if (mq.addEventListener) mq.addEventListener("change", onSystemChange);
+  else mq.addListener(onSystemChange);
+}
+function notify() {
+  for (const listener of listeners) listener();
+}
+
 // src/config.ts
 function applyOpacityToHex(hex, opacityText) {
   const rgb = parseHexRgb(hex);

package/dist/vite-plugin.mjs

@@ -5,9 +5,9 @@ import {
   kbach,
   loadConfigFile,
   resolveEffectiveTheme
-} from "./chunk-J2M6QWJW.mjs";
-import "./chunk-4Y2QXNJY.mjs";
-import "./chunk-EOSN5CYG.mjs";
+} from "./chunk-XV2ZLURB.mjs";
+import "./chunk-OWWJ2PME.mjs";
+import "./chunk-OVKVZA7B.mjs";
 export {
   CSS_SYNC_DEBOUNCE_MS,
   DEFAULT_SCAN_DIRS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbach/react",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.14",
   "description": "A utility-first styling engine for React, powered by a real Rust/WASM core — Tailwind CSS v4 feature parity with Kbach's own color palette.",
   "keywords": ["css", "react", "tailwind", "utility-first", "wasm", "styling"],
   "license": "MIT",
@@ -62,7 +62,7 @@
     "generate:colors": "node ../core-engine/scripts/generate-palette.mjs src/generatedPalette.ts"
   },
   "dependencies": {
-    "@kbach/core-engine": "1.0.0-beta.7"
+    "@kbach/core-engine": "1.0.0-beta.8"
   },
   "devDependencies": {
     "@types/react": "^19.2.0",