@kbach/react 1.0.0-beta.2 → 1.0.0-beta.20

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

@@ -348,7 +348,19 @@ var defaultTheme = {
     serif: 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
     mono: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace'
   },
-  darkMode: "attribute",
+  // Matches real Tailwind's own default (`darkMode: 'media'`): pure
+  // `@media (prefers-color-scheme: dark)`, works with zero JS — a project
+  // using only static `className` strings gets working `dark:` classes
+  // out of the box, with no runtime import required to write `data-theme`/
+  // `.dark` onto `<html>` (see darkModeStore.ts's `applyToDom`). The
+  // tradeoff: `'media'` can't be overridden by a manual light/dark toggle —
+  // `useTheme()`/`toggleGlobalDarkMode()` still track `isDark` correctly
+  // for JS consumers, but flipping it has no visible effect on `dark:`
+  // classes, since the browser's media query only ever reflects the real
+  // OS setting. Opt into `darkMode: 'class'` or `'attribute'` explicitly
+  // (via `kbach.config.js` or the `config`/`theme` plugin option) as soon
+  // as an app wants a real in-app toggle.
+  darkMode: "media",
   // Empty by default, matching real Tailwind's own defaults (no forced
   // centering/padding) — see `ContainerConfig`'s own doc comment.
   container: {}
@@ -365,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";
@@ -455,6 +474,7 @@ export {
   setTheme,
   getTheme,
   getThemeJson,
+  detectDarkModeStrategyFromDom,
   RESET_STYLE_ID,
   BASE_RESET,
   buildResetCSS

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

@@ -87,8 +87,28 @@ interface KbachConfig {
          * already-defined-above) is treated as a literal CSS value instead
          * (`accent: 'red'` — REAL CSS `red`, since there's no color named "red"
          * to alias), never an error either way.
+         *
+         * `dark` is a reserved key, not a color name — a SECOND way to write a
+         * mode-aware color, as a group instead of per-color: `{ surface:
+         * 'gray-2', card: 'white', dark: { surface: 'gray-11', card: 'gray-9' } }`
+         * makes `surface`/`card` mode-aware, while a name never mentioned under
+         * `dark` (like a hypothetical always-the-same `brand` here) stays a
+         * plain, mode-independent color. Equivalent to writing `surface: {
+         * light: 'gray-2', dark: 'gray-11' }` directly — pick whichever reads
+         * better for your config: per-color pairs when only a couple of colors
+         * are mode-aware, the grouped block when most of them are and writing
+         * "light"/"dark" twice per line would be repetitive. A name under
+         * `dark` with no matching top-level (light) entry is skipped — mode-
+         * aware colors need both sides written out. References inside `dark`
+         * resolve against the built-in palette and OTHER entries within `dark`
+         * itself (not the light-side custom colors, and not a light-side color
+         * already written as a `{ light, dark }` pair) — self-contained, the
+         * same way the light side already resolves independently of it.
          */
-        colors?: Record<string, ColorEntry | string>;
+        colors?: {
+            [colorName: string]: ColorEntry | string | Record<string, string> | undefined;
+            dark?: Record<string, string>;
+        };
         spacing?: Record<string, number>;
         screens?: Record<string, number>;
         /** Named font stacks, e.g. `{ display: '"Cal Sans", sans-serif' }` — adds to (or overrides one of) `defaultTheme.fontFamily`'s three names. */
@@ -99,7 +119,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-N74_lKa0.d.ts}

@@ -87,8 +87,28 @@ interface KbachConfig {
          * already-defined-above) is treated as a literal CSS value instead
          * (`accent: 'red'` — REAL CSS `red`, since there's no color named "red"
          * to alias), never an error either way.
+         *
+         * `dark` is a reserved key, not a color name — a SECOND way to write a
+         * mode-aware color, as a group instead of per-color: `{ surface:
+         * 'gray-2', card: 'white', dark: { surface: 'gray-11', card: 'gray-9' } }`
+         * makes `surface`/`card` mode-aware, while a name never mentioned under
+         * `dark` (like a hypothetical always-the-same `brand` here) stays a
+         * plain, mode-independent color. Equivalent to writing `surface: {
+         * light: 'gray-2', dark: 'gray-11' }` directly — pick whichever reads
+         * better for your config: per-color pairs when only a couple of colors
+         * are mode-aware, the grouped block when most of them are and writing
+         * "light"/"dark" twice per line would be repetitive. A name under
+         * `dark` with no matching top-level (light) entry is skipped — mode-
+         * aware colors need both sides written out. References inside `dark`
+         * resolve against the built-in palette and OTHER entries within `dark`
+         * itself (not the light-side custom colors, and not a light-side color
+         * already written as a `{ light, dark }` pair) — self-contained, the
+         * same way the light side already resolves independently of it.
          */
-        colors?: Record<string, ColorEntry | string>;
+        colors?: {
+            [colorName: string]: ColorEntry | string | Record<string, string> | undefined;
+            dark?: Record<string, string>;
+        };
         spacing?: Record<string, number>;
         screens?: Record<string, number>;
         /** Named font stacks, e.g. `{ display: '"Cal Sans", sans-serif' }` — adds to (or overrides one of) `defaultTheme.fontFamily`'s three names. */
@@ -99,7 +119,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-N74_lKa0.mjs';
 import * as react from 'react';
 import { ReactNode } from 'react';
 
@@ -120,6 +120,22 @@ type ColorsAPI = {
      * `rgb(var(--kb-color-x))` mode-aware references.
      */
     readonly alpha: (color: string, opacity?: number) => string;
+    /**
+     * Same lookup dot/bracket access does (`colors.get('brand')` ===
+     * `colors.brand`), typed as plain `string` instead of `string |
+     * ColorScale` — use this whenever the result goes somewhere that expects
+     * a real `string` and hits a type error otherwise. The wider union on
+     * every OTHER property here isn't a bug: a flat custom color (`surface`)
+     * and a shade-family prefix (`blue`) are served by the exact same
+     * object, and TypeScript has no way to statically know which one any
+     * given key names — `kbach.config.js`'s colors are plain runtime JS, not
+     * a type declaration this package could inspect ahead of time. A name
+     * with no matching theme entry falls back to the name itself,
+     * unresolved — the same "not a known color name -> literal value"
+     * convention `kbach.config.js`'s own color aliasing already uses (see
+     * `config.ts`'s `resolveColorEntry`), never an error.
+     */
+    readonly get: (name: string) => string;
 };
 /**
  * Resolved theme colors as real values — for anywhere you need an actual
@@ -141,8 +157,57 @@ type ColorsAPI = {
  * colors.blue['6/50'];    // same, at 50% opacity
  * colors.surface;         // "rgb(var(--kb-color-surface))" if defined as { light, dark }
  * colors.alpha(colors.surface, 50); // "rgba(var(--kb-color-surface), 0.5)"
+ * colors.get('surface');  // same value as colors.surface, typed as plain `string`
  * ```
  */
 declare function useColors(): ColorsAPI;
 
-export { type ColorScale, type ColorsAPI, KbachReset, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeState, disableRuntimeCSS, getGlobalDarkMode, getGlobalThemeMode, initKbach, isKbachReady, isRuntimeCSSDisabled, kb, setGlobalThemeMode, subscribeGlobalDarkMode, toggleGlobalDarkMode, useColors, useTheme };
+/**
+ * A tiny class-name composer — combine strings, arrays, and objects (with
+ * boolean values) into one space-separated className, skipping anything
+ * falsy. Matches the widely-used `clsx` npm package's public API and
+ * behavior exactly (a from-scratch reimplementation, not a fork or a thin
+ * wrapper around it) — this package ships its own copy so using it adds
+ * zero runtime dependencies, and so it works identically whether or not
+ * `clsx`/`classnames` happens to already be installed.
+ *
+ * Kbach class strings never NEED this — a Kbach `className` is just a
+ * plain string, composable with plain JS (`"bg-" + color + "-6"`,
+ * `[base, active && "opacity-100"].join(" ")`, see this package's own
+ * README) with no special API required. This exists purely as an
+ * ergonomic convenience for the common "several conditional classes on one
+ * element" shape, for anyone who'd rather write it declaratively:
+ *
+ * ```ts
+ * clsx("px-4 py-2", isActive && "bg-blue-6", { "opacity-50": disabled });
+ * // "px-4 py-2 bg-blue-6" (when isActive is true and disabled is false)
+ * ```
+ *
+ * The static build-time scanner (vite-plugin/postcss-plugin) already
+ * recognizes `clsx(...)` call sites (alongside `cn`/`classnames`/`cx`/
+ * `kb`) and extracts every string literal inside them on its own — using
+ * this function needs no extra plugin configuration to keep working with
+ * the static CSS build.
+ *
+ * Identical to `@kbach/react-native`'s own `clsx.ts` — deliberately
+ * duplicated rather than factored into a shared package, since this is
+ * genuinely all there is to it and a whole extra published package for one
+ * ~20-line function would be more ceremony than the thing itself.
+ */
+/** Anything `clsx` accepts as one argument — recursively, for arrays. */
+type ClassValue = ClassArray | ClassDictionary | string | number | bigint | boolean | null | undefined;
+/** A key is kept (as a literal class name) only when its value is truthy — `{ "opacity-50": disabled }`. */
+interface ClassDictionary {
+    [className: string]: unknown;
+}
+type ClassArray = ClassValue[];
+/**
+ * Joins every truthy piece across all arguments with a single space,
+ * skipping falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`)
+ * entirely — they contribute nothing, not even an extra space. Arrays are
+ * flattened (recursively, to any depth); a plain object keeps only the
+ * keys whose value is truthy.
+ */
+declare function clsx(...inputs: ClassValue[]): string;
+
+export { type ClassArray, type ClassDictionary, type ClassValue, type ColorScale, type ColorsAPI, KbachReset, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeState, clsx, disableRuntimeCSS, getGlobalDarkMode, getGlobalThemeMode, initKbach, isKbachReady, isRuntimeCSSDisabled, kb, setGlobalThemeMode, subscribeGlobalDarkMode, toggleGlobalDarkMode, useColors, useTheme };

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-N74_lKa0.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 
@@ -120,6 +120,22 @@ type ColorsAPI = {
      * `rgb(var(--kb-color-x))` mode-aware references.
      */
     readonly alpha: (color: string, opacity?: number) => string;
+    /**
+     * Same lookup dot/bracket access does (`colors.get('brand')` ===
+     * `colors.brand`), typed as plain `string` instead of `string |
+     * ColorScale` — use this whenever the result goes somewhere that expects
+     * a real `string` and hits a type error otherwise. The wider union on
+     * every OTHER property here isn't a bug: a flat custom color (`surface`)
+     * and a shade-family prefix (`blue`) are served by the exact same
+     * object, and TypeScript has no way to statically know which one any
+     * given key names — `kbach.config.js`'s colors are plain runtime JS, not
+     * a type declaration this package could inspect ahead of time. A name
+     * with no matching theme entry falls back to the name itself,
+     * unresolved — the same "not a known color name -> literal value"
+     * convention `kbach.config.js`'s own color aliasing already uses (see
+     * `config.ts`'s `resolveColorEntry`), never an error.
+     */
+    readonly get: (name: string) => string;
 };
 /**
  * Resolved theme colors as real values — for anywhere you need an actual
@@ -141,8 +157,57 @@ type ColorsAPI = {
  * colors.blue['6/50'];    // same, at 50% opacity
  * colors.surface;         // "rgb(var(--kb-color-surface))" if defined as { light, dark }
  * colors.alpha(colors.surface, 50); // "rgba(var(--kb-color-surface), 0.5)"
+ * colors.get('surface');  // same value as colors.surface, typed as plain `string`
  * ```
  */
 declare function useColors(): ColorsAPI;
 
-export { type ColorScale, type ColorsAPI, KbachReset, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeState, disableRuntimeCSS, getGlobalDarkMode, getGlobalThemeMode, initKbach, isKbachReady, isRuntimeCSSDisabled, kb, setGlobalThemeMode, subscribeGlobalDarkMode, toggleGlobalDarkMode, useColors, useTheme };
+/**
+ * A tiny class-name composer — combine strings, arrays, and objects (with
+ * boolean values) into one space-separated className, skipping anything
+ * falsy. Matches the widely-used `clsx` npm package's public API and
+ * behavior exactly (a from-scratch reimplementation, not a fork or a thin
+ * wrapper around it) — this package ships its own copy so using it adds
+ * zero runtime dependencies, and so it works identically whether or not
+ * `clsx`/`classnames` happens to already be installed.
+ *
+ * Kbach class strings never NEED this — a Kbach `className` is just a
+ * plain string, composable with plain JS (`"bg-" + color + "-6"`,
+ * `[base, active && "opacity-100"].join(" ")`, see this package's own
+ * README) with no special API required. This exists purely as an
+ * ergonomic convenience for the common "several conditional classes on one
+ * element" shape, for anyone who'd rather write it declaratively:
+ *
+ * ```ts
+ * clsx("px-4 py-2", isActive && "bg-blue-6", { "opacity-50": disabled });
+ * // "px-4 py-2 bg-blue-6" (when isActive is true and disabled is false)
+ * ```
+ *
+ * The static build-time scanner (vite-plugin/postcss-plugin) already
+ * recognizes `clsx(...)` call sites (alongside `cn`/`classnames`/`cx`/
+ * `kb`) and extracts every string literal inside them on its own — using
+ * this function needs no extra plugin configuration to keep working with
+ * the static CSS build.
+ *
+ * Identical to `@kbach/react-native`'s own `clsx.ts` — deliberately
+ * duplicated rather than factored into a shared package, since this is
+ * genuinely all there is to it and a whole extra published package for one
+ * ~20-line function would be more ceremony than the thing itself.
+ */
+/** Anything `clsx` accepts as one argument — recursively, for arrays. */
+type ClassValue = ClassArray | ClassDictionary | string | number | bigint | boolean | null | undefined;
+/** A key is kept (as a literal class name) only when its value is truthy — `{ "opacity-50": disabled }`. */
+interface ClassDictionary {
+    [className: string]: unknown;
+}
+type ClassArray = ClassValue[];
+/**
+ * Joins every truthy piece across all arguments with a single space,
+ * skipping falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`)
+ * entirely — they contribute nothing, not even an extra space. Arrays are
+ * flattened (recursively, to any depth); a plain object keeps only the
+ * keys whose value is truthy.
+ */
+declare function clsx(...inputs: ClassValue[]): string;
+
+export { type ClassArray, type ClassDictionary, type ClassValue, type ColorScale, type ColorsAPI, KbachReset, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeState, clsx, disableRuntimeCSS, getGlobalDarkMode, getGlobalThemeMode, initKbach, isKbachReady, isRuntimeCSSDisabled, kb, setGlobalThemeMode, subscribeGlobalDarkMode, toggleGlobalDarkMode, useColors, useTheme };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(src_exports, {
   KbachReset: () => KbachReset,
   ThemeProvider: () => ThemeProvider,
   applyKbachConfig: () => applyKbachConfig,
+  clsx: () => clsx,
   defaultTheme: () => defaultTheme,
   disableRuntimeCSS: () => disableRuntimeCSS,
   getGlobalDarkMode: () => getGlobalDarkMode,
@@ -70,7 +71,7 @@ function isKbachReady() {
 function generateCss(classString, themeJson) {
   if (!ready) {
     throw new Error(
-      "[kbach] generateCss() was called before initKbach() resolved. Call `await initKbach()` once at startup (e.g. before rendering your app) before using kb()."
+      "[Kbach] generateCss() was called before initKbach() resolved. Call `await initKbach()` once at startup (e.g. before rendering your app) before using kb()."
     );
   }
   return (0, import_core_engine.generate_css)(classString, themeJson);
@@ -426,7 +427,19 @@ var defaultTheme = {
     serif: 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
     mono: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace'
   },
-  darkMode: "attribute",
+  // Matches real Tailwind's own default (`darkMode: 'media'`): pure
+  // `@media (prefers-color-scheme: dark)`, works with zero JS — a project
+  // using only static `className` strings gets working `dark:` classes
+  // out of the box, with no runtime import required to write `data-theme`/
+  // `.dark` onto `<html>` (see darkModeStore.ts's `applyToDom`). The
+  // tradeoff: `'media'` can't be overridden by a manual light/dark toggle —
+  // `useTheme()`/`toggleGlobalDarkMode()` still track `isDark` correctly
+  // for JS consumers, but flipping it has no visible effect on `dark:`
+  // classes, since the browser's media query only ever reflects the real
+  // OS setting. Opt into `darkMode: 'class'` or `'attribute'` explicitly
+  // (via `kbach.config.js` or the `config`/`theme` plugin option) as soon
+  // as an app wants a real in-app toggle.
+  darkMode: "media",
   // Empty by default, matching real Tailwind's own defaults (no forced
   // centering/padding) — see `ContainerConfig`'s own doc comment.
   container: {}
@@ -443,6 +456,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";
@@ -575,9 +595,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) {
@@ -644,63 +678,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();
@@ -728,13 +705,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";
@@ -754,6 +733,9 @@ if (typeof window !== "undefined" && window.matchMedia) {
 function notify() {
   for (const listener of listeners) listener();
 }
+function resyncDomWithActiveTheme() {
+  applyToDom(isDark);
+}
 function getGlobalDarkMode() {
   return isDark;
 }
@@ -788,7 +770,81 @@ 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 { dark: darkExtend, ...lightExtend } = extend;
+  const resolved = {};
+  const lookup = (name) => resolved[name] ?? existing[name];
+  for (const [name, value] of Object.entries(lightExtend)) {
+    if (typeof value === "object" && value !== null && !("light" in value) && !("dark" in value)) continue;
+    resolved[name] = resolveColorEntry(value, lookup);
+  }
+  if (darkExtend) {
+    const resolvedDark = {};
+    const lookupDark = (name) => {
+      const found = resolvedDark[name] ?? existing[name];
+      return typeof found === "string" ? found : void 0;
+    };
+    for (const [name, value] of Object.entries(darkExtend)) {
+      const entry = resolveColorEntry(value, lookupDark);
+      resolvedDark[name] = typeof entry === "string" ? entry : entry.dark;
+    }
+    for (const [name, darkValue] of Object.entries(resolvedDark)) {
+      const lightEntry = resolved[name];
+      if (lightEntry === void 0 || typeof lightEntry !== "string") continue;
+      resolved[name] = { light: lightEntry, dark: darkValue };
+    }
+  }
+  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");
@@ -806,10 +862,12 @@ var warnedMultipleProviders = false;
 function ThemeProvider({ children, defaultMode = "system" }) {
   (0, import_react2.useEffect)(() => {
     mountedProviderCount++;
-    if (mountedProviderCount > 1 && !warnedMultipleProviders) {
+    if (mountedProviderCount > 1 && !warnedMultipleProviders && process.env.NODE_ENV !== "production") {
       warnedMultipleProviders = true;
       console.warn(
-        "[kbach] Multiple <ThemeProvider> instances are mounted at once. Dark-mode state is one global store useTheme() reads everywhere, not scoped per-provider, so their defaultMode seeds will fight over the same state."
+        "%c[Kbach]%c Multiple <ThemeProvider> instances are mounted at once.\nDark mode is one global store \u2014 useTheme() reads it everywhere, not scoped per provider \u2014 so their defaultMode seeds will fight over the same state.\nMount exactly one <ThemeProvider>, as high in the tree as convenient.",
+        "background:#7c3aed;color:#fff;font-weight:600;padding:1px 6px;border-radius:3px",
+        "font-weight:400"
       );
     }
     return () => {
@@ -826,6 +884,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);
@@ -870,11 +929,13 @@ function makeColorsProxy(theme, isDark2) {
       }
     });
   }
-  return new Proxy({ alpha }, {
+  const get = (name) => resolveNamed(name) ?? name;
+  return new Proxy({ alpha, get }, {
     get(_, prop) {
       const key = String(prop);
       if (key === "then") return void 0;
       if (key === "alpha") return alpha;
+      if (key === "get") return get;
       const direct = resolveNamed(key);
       if (direct !== void 0) return direct;
       if (!cache.has(key)) cache.set(key, makeFamilyProxy(key));
@@ -886,13 +947,40 @@ 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]);
+}
+
+// src/clsx.ts
+function clsx(...inputs) {
+  let out = "";
+  for (const input of inputs) {
+    const piece = resolveClassValue(input);
+    if (piece) out = out ? `${out} ${piece}` : piece;
+  }
+  return out;
+}
+function resolveClassValue(value) {
+  if (!value) return "";
+  const type = typeof value;
+  if (type === "string" || type === "number" || type === "bigint") return String(value);
+  if (Array.isArray(value)) return clsx(...value);
+  if (type === "object") {
+    let out = "";
+    for (const key in value) {
+      if (Object.prototype.hasOwnProperty.call(value, key) && value[key]) {
+        out = out ? `${out} ${key}` : key;
+      }
+    }
+    return out;
+  }
+  return "";
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   KbachReset,
   ThemeProvider,
   applyKbachConfig,
+  clsx,
   defaultTheme,
   disableRuntimeCSS,
   getGlobalDarkMode,