@kbach/react 1.0.0-beta.1 → 1.0.0-beta.3

package/README.md

@@ -1,32 +1,11 @@
 # @kbach/react
 
-A utility-first styling engine for React, powered by a real Rust/WASM core.
-Kbach aims for full [Tailwind CSS v4](https://tailwindcss.com) feature
-parity — grid, transforms, filters, gradients, animations, container
-queries, arbitrary values, and a parameterized variant system (`has-*`,
-`data-*`, `aria-*`, `not-*`, generalized `group-*`/`peer-*`, and more) — with
-its own 22-family + metals color palette as the one deliberate difference.
-
-> **Beta.** The API is close to stable but may still change before `1.0.0`.
-> Feedback and issues are very welcome.
-
-## Why Kbach
-
-- **A real engine, not a lookup table.** Every class is resolved by the same
-  Rust/WASM core at build time (via the Vite plugin) and at runtime (via
-  `kb()`), so build-time and runtime output can never drift apart.
-- **Static by default.** The Vite plugin scans your source and writes a real,
-  plain `kbach.css` file — no runtime style injection needed, no
-  flash-of-unstyled-content, no client-side CSS-in-JS overhead.
-- **Dark mode that works without a provider.** Toggle/set/subscribe to dark
-  mode from anywhere — a plain function, an event handler, a component that
-  never wants React Context — with an optional `<ThemeProvider>` as a thin
-  wrapper around the exact same store.
-- **Composable by nature.** Utility class strings are just strings — combine
-  them with plain arrays, ternaries, or template literals. No bespoke
-  composition API required.
-
-## Installation
+A utility-first styling engine for React, powered by a Rust/WASM core.
+Tailwind CSS v4 feature parity, plus Kbach's own color palette.
+
+> Beta — API may still change before 1.0.0.
+
+## Install
 
 ```sh
 npm install @kbach/react
@@ -34,9 +13,6 @@ npm install @kbach/react
 
 ## Quick start
 
-Add the Vite plugin so your utility classes are resolved to real CSS at
-build time:
-
 ```ts
 // vite.config.ts
 import { defineConfig } from 'vite';
@@ -48,9 +24,6 @@ export default defineConfig({
 });
 ```
 
-Create `src/kbach.css` with the markers the plugin writes between, and
-import it once:
-
 ```css
 /* src/kbach.css */
 /* kbach:start */
@@ -69,8 +42,6 @@ initKbach().then(() => {
 });
 ```
 
-Then just use utility classes:
-
 ```tsx
 <div className="flex items-center gap-4 bg-blue-6 text-white p-4 rounded-lg">
   Hello Kbach
@@ -79,40 +50,20 @@ Then just use utility classes:
 
 ## Dark mode
 
-Works standalone, with zero provider:
-
 ```tsx
-import { useGlobalDarkMode, toggleGlobalDarkMode } from '@kbach/react';
+import { useTheme } from '@kbach/react';
 
 function ThemeToggle() {
-  const isDark = useGlobalDarkMode();
-  return <button onClick={toggleGlobalDarkMode}>{isDark ? 'Dark' : 'Light'}</button>;
-}
-```
-
-Or opt into the optional `<ThemeProvider>` / `useTheme()` pair — both read
-and write the exact same global store, so they always stay in sync with the
-standalone functions above:
-
-```tsx
-import { ThemeProvider, useTheme } from '@kbach/react';
-
-function Toggle() {
   const { mode, isDark, setMode, toggle } = useTheme();
   return <button onClick={toggle}>{mode}</button>;
 }
-
-<ThemeProvider defaultMode="system">
-  <Toggle />
-</ThemeProvider>;
 ```
 
-## Theming
+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.
 
-Customize the color palette, spacing scale, breakpoints, and dark-mode
-strategy via `setTheme()` (call once, before your first render) — the same
-theme object is used by both the runtime and the Vite plugin, so the two
-never fall out of sync:
+## Theming
 
 ```ts
 import { setTheme, defaultTheme } from '@kbach/react';
@@ -123,12 +74,10 @@ setTheme({
 });
 ```
 
-## Runtime & dynamic classes
+## Dynamic classes
 
-Every class name that appears literally in your source is resolved at build
-time. For a class name assembled from truly dynamic data (e.g. user input)
-with no static occurrence anywhere in your source, call `kb()` — it resolves
-and injects the CSS at runtime and returns the class name unchanged:
+Classes that appear literally in your source are resolved at build time.
+For classes assembled from truly dynamic data, use `kb()`:
 
 ```ts
 import { kb } from '@kbach/react';
@@ -136,9 +85,37 @@ import { kb } from '@kbach/react';
 const className = kb(`bg-${userColor}-6`);
 ```
 
-If you're using the static build (the default with the Vite plugin), prefer
-a `safelist` entry in the plugin config for known-but-dynamic values instead
-— it keeps everything static with zero runtime cost.
+Prefer a `safelist` entry in the plugin config when the possible values are
+known ahead of time — keeps everything static.
+
+## Reading colors as values
+
+For anywhere you need a real color, not a `className` (an SVG `fill`, a
+chart library prop):
+
+```tsx
+import { useColors } from '@kbach/react';
+
+const colors = useColors();
+colors.blue[6];       // '#2563eb' — static, same value in both modes
+colors.blue['6/50'];  // same, at 50% opacity
+colors.surface;       // 'rgb(var(--kb-color-surface))' if defined as light/dark
+```
+
+Any color — a shade-family entry like `blue-6` or a standalone name like
+`surface` — can be defined in the theme as a plain string (static) or a
+`{ light, dark }` pair, fully manual:
+
+```ts
+setTheme({
+  ...defaultTheme,
+  colors: { ...defaultTheme.colors, surface: { light: '#f9fafb', dark: '#111827' } },
+});
+```
+
+A plain color always resolves to its literal value. A `{ light, dark }`
+color resolves to a live CSS variable instead of a fixed hex — it stays
+correct across theme changes with zero re-render.
 
 ## License
 

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

@@ -284,14 +284,15 @@ var defaultTheme = {
   // Real Tailwind's default spacing scale in full — every step is exactly
   // `n * 4px` (Tailwind's base spacing unit), including the fractional
   // `.5` steps (`1.5` -> 6px, `2.5` -> 10px, `3.5` -> 14px) and the "px"
-  // literal (a bare 1px, for `p-px`-style hairline spacing). Previously
-  // this only had {0,1,2,4,6,8} — a handful of spot-checked values, not
-  // the real scale — so anything else (`p-3`, `w-5`, `border-2`, `gap-10`,
-  // ...) silently failed to resolve (an unknown spacing key returns `None`
-  // the same way an unknown class does, with no error). "0" itself is
-  // still needed explicitly (not derivable as "any number * 4") for the
-  // same reason it always was: `sticky top-0` needs an actual "0" key to
-  // resolve at all, not just fall through as unresolvable.
+  // literal (a bare 1px, for `p-px`-style hairline spacing). This table is
+  // only the "usual stops", though — the Rust/JS engines' shared
+  // `spacing_px`/`spacingPx` helper falls back to Tailwind v4's own live
+  // `n * 4px` formula for any bare numeric step NOT listed here (`p-0.25`,
+  // `gap-1.75`, `w-13`, ...), so this table exists to name the common
+  // values and give a theme customization something to override, not to
+  // enumerate every resolvable step. "px" is the one exception that must
+  // stay listed explicitly — it isn't a number, so the formula can't
+  // derive it.
   spacing: {
     "0": 0,
     "px": 1,
@@ -336,7 +337,21 @@ var defaultTheme = {
     xl: 1280,
     "2xl": 1536
   },
-  darkMode: "attribute"
+  // Byte-for-byte the same three stacks
+  // packages/core-engine/src/resolvers/typography.rs's `font_family_value`
+  // falls back to — kept here too (rather than leaving this empty and
+  // relying purely on the Rust-side fallback) so `defaultTheme.fontFamily.sans`
+  // is a real, readable value for anything that wants to extend rather
+  // than replace it (see `KbachConfig.extend.fontFamily` in config.ts).
+  fontFamily: {
+    sans: 'ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+    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",
+  // Empty by default, matching real Tailwind's own defaults (no forced
+  // centering/padding) — see `ContainerConfig`'s own doc comment.
+  container: {}
 };
 var activeTheme = defaultTheme;
 var activeThemeJson = JSON.stringify(defaultTheme);

package/dist/chunk-NKR3PSWO.mjs

@@ -0,0 +1,115 @@
+import {
+  defaultTheme,
+  setTheme
+} from "./chunk-N5HCQIBB.mjs";
+
+// src/colorVariables.ts
+function parseHexRgb(hex) {
+  const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim());
+  if (!m) return null;
+  let h = m[1];
+  if (h.length === 3) h = h.split("").map((c) => c + c).join("");
+  const n = parseInt(h, 16);
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+function wrapDarkDecls(strategy, decls) {
+  switch (strategy) {
+    case "class":
+      return `.dark { ${decls} }`;
+    case "media":
+      return `@media (prefers-color-scheme: dark) { :root { ${decls} } }`;
+    case "attribute":
+    default:
+      return `[data-theme="dark"] { ${decls} }`;
+  }
+}
+var STYLE_ID = "kbach-colors";
+var injectedForTheme = null;
+function ensureColorVariablesInjected(theme) {
+  if (typeof document === "undefined") return;
+  if (injectedForTheme === theme) return;
+  injectedForTheme = theme;
+  const lightDecls = [];
+  const darkDecls = [];
+  for (const [name, value] of Object.entries(theme.colors)) {
+    if (typeof value === "string") continue;
+    const light = parseHexRgb(value.light);
+    const dark = parseHexRgb(value.dark);
+    if (!light || !dark) continue;
+    lightDecls.push(`--kb-color-${name}: ${light.join(",")};`);
+    darkDecls.push(`--kb-color-${name}: ${dark.join(",")};`);
+  }
+  let el = document.getElementById(STYLE_ID);
+  if (lightDecls.length === 0) {
+    el?.remove();
+    return;
+  }
+  if (!el) {
+    el = document.createElement("style");
+    el.id = STYLE_ID;
+    document.head.insertBefore(el, document.head.firstChild);
+  }
+  el.textContent = `:root { ${lightDecls.join(" ")} }
+${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;
+}
+
+export {
+  parseHexRgb,
+  ensureColorVariablesInjected,
+  resolveKbachConfig,
+  applyKbachConfig
+};

package/dist/{chunk-AD3G6RHY.mjs → chunk-PAJ6KHDB.mjs}

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

package/dist/{chunk-ROZXCQSM.mjs → chunk-ZQJKL2MV.mjs}

@@ -2,7 +2,7 @@ import {
   BASE_RESET,
   RESET_STYLE_ID,
   getThemeJson
-} from "./chunk-FOQWQDF4.mjs";
+} from "./chunk-N5HCQIBB.mjs";
 
 // src/wasmLoader.ts
 import init, { generate_css as wasmGenerateCss } from "@kbach/core-engine";

package/dist/config-BQ_b-qxF.d.mts

@@ -0,0 +1,105 @@
+/** A plain hex color, or a mode-aware pair auto-expanded into a light/dark class pair by the Rust engine. */
+type ColorEntry = string | {
+    light: string;
+    dark: string;
+};
+type DarkModeStrategy = 'attribute' | 'class' | 'media';
+/**
+ * Real Tailwind's `theme.container` config, mirroring
+ * `packages/core-engine/src/theme.rs`'s `ContainerConfig` exactly (same
+ * field names, `camelCase` on both sides via serde). `padding` is one
+ * uniform value applied at every breakpoint (including below the smallest
+ * one) rather than real Tailwind's optional per-breakpoint object form —
+ * the common case in practice, and simpler to reason about; a
+ * per-breakpoint padding map is a natural follow-up if ever needed.
+ */
+interface ContainerConfig {
+    center?: boolean;
+    padding?: string;
+}
+interface ThemeConfig {
+    /** e.g. "blue-6" -> "#2563eb", or "surface" -> { light, dark } */
+    colors: Record<string, ColorEntry>;
+    /** e.g. "4" -> 16 (px) */
+    spacing: Record<string, number>;
+    /** e.g. "sm" -> 640 (min-width px) */
+    screens: Record<string, number>;
+    /**
+     * e.g. "sans" -> "ui-sans-serif, system-ui, ...". Optional — the Rust
+     * engine's own `font_family_value` already carries a hardcoded fallback
+     * for "sans"/"serif"/"mono" (see its own doc comment) for when a theme
+     * omits this field (or a name within it) entirely, matching this field's
+     * `#[serde(default)]` on the Rust side. `defaultTheme` below still
+     * populates all three explicitly, matching the Rust fallback strings
+     * byte-for-byte, so a caller reading `defaultTheme.fontFamily.sans`
+     * (e.g. to extend rather than replace it) gets the real value rather
+     * than needing to already know the Rust-side fallback text.
+     */
+    fontFamily?: Record<string, string>;
+    darkMode: DarkModeStrategy;
+    /** Optional, matching `ContainerConfig`'s own `#[serde(default)]` on the Rust side — an omitted theme.container behaves exactly like `{}`. */
+    container?: ContainerConfig;
+}
+declare const defaultTheme: ThemeConfig;
+declare function setTheme(theme: ThemeConfig): void;
+declare function getTheme(): ThemeConfig;
+
+/**
+ * A `kbach.config.js`-style theme customization, in one plain object — same
+ * `theme`/`extend`/`darkMode` shape real Tailwind's own config file uses,
+ * simplified from old-kbach's version (no plugins, no color alias chains
+ * with cycle detection, no live-update-listener store): a config object
+ * goes in, a resolved `ThemeConfig` comes out, via one PURE function
+ * (`resolveKbachConfig`) — same input always produces the same output, so
+ * nothing needs to stay "in sync" the way old-kbach's Babel-injected config
+ * singleton did. Call it identically from a Node.js build script
+ * (`vite.config.ts`) and from browser/app code (`applyKbachConfig`) and
+ * both get the exact same theme, no synchronization mechanism required.
+ */
+interface KbachConfig {
+    /** Applied on top of `defaultTheme`; `undefined` means "keep the default". */
+    darkMode?: DarkModeStrategy;
+    /**
+     * REPLACES the named section of `defaultTheme` entirely (e.g. supplying
+     * `theme.colors` drops the rest of the default palette) — use `extend`
+     * instead to add to the defaults rather than replace them. `container`
+     * isn't here (only under `extend` below) — it has no "defaults to
+     * replace" the way colors/spacing/screens/fontFamily do, since real
+     * Tailwind's own container config is inherently additive (center/padding
+     * on top of the always-present breakpoint ladder), so there's no
+     * meaningful distinction between "replace" and "extend" for it.
+     */
+    theme?: Partial<Pick<ThemeConfig, 'colors' | 'spacing' | 'screens' | 'fontFamily'>>;
+    /** Merges INTO `defaultTheme` (or `theme` above, if also supplied) — the common case. */
+    extend?: {
+        /**
+         * A value is either a literal color (a hex string, or `{ light, dark }`
+         * — same mode-aware shape `useColors()`/`useTheme()` already support)
+         * or a REFERENCE to another color name, optionally with an opacity
+         * suffix. Two things can be referenced:
+         * - A BUILT-IN palette color, always available regardless of ordering
+         *   (`accent: 'orange-5'`, `accentSoft: 'orange-5/50'`).
+         * - A custom color defined EARLIER in this same object
+         *   (`{ brand: '#ff6b35', brandSoft: 'brand/30' }` — `brandSoft`
+         *   resolves to `brand`'s own value at 30% opacity, computed once here
+         *   rather than needing a `colors.alpha()` call at every use site).
+         * A string that doesn't match any known color name (built-in or
+         * 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.
+         */
+        colors?: Record<string, ColorEntry | 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. */
+        fontFamily?: Record<string, string>;
+        /** `{ center: true, padding: '2rem' }` — see `ContainerConfig`'s own doc comment. */
+        container?: ContainerConfig;
+    };
+}
+/** 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). */
+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

@@ -0,0 +1,105 @@
+/** A plain hex color, or a mode-aware pair auto-expanded into a light/dark class pair by the Rust engine. */
+type ColorEntry = string | {
+    light: string;
+    dark: string;
+};
+type DarkModeStrategy = 'attribute' | 'class' | 'media';
+/**
+ * Real Tailwind's `theme.container` config, mirroring
+ * `packages/core-engine/src/theme.rs`'s `ContainerConfig` exactly (same
+ * field names, `camelCase` on both sides via serde). `padding` is one
+ * uniform value applied at every breakpoint (including below the smallest
+ * one) rather than real Tailwind's optional per-breakpoint object form —
+ * the common case in practice, and simpler to reason about; a
+ * per-breakpoint padding map is a natural follow-up if ever needed.
+ */
+interface ContainerConfig {
+    center?: boolean;
+    padding?: string;
+}
+interface ThemeConfig {
+    /** e.g. "blue-6" -> "#2563eb", or "surface" -> { light, dark } */
+    colors: Record<string, ColorEntry>;
+    /** e.g. "4" -> 16 (px) */
+    spacing: Record<string, number>;
+    /** e.g. "sm" -> 640 (min-width px) */
+    screens: Record<string, number>;
+    /**
+     * e.g. "sans" -> "ui-sans-serif, system-ui, ...". Optional — the Rust
+     * engine's own `font_family_value` already carries a hardcoded fallback
+     * for "sans"/"serif"/"mono" (see its own doc comment) for when a theme
+     * omits this field (or a name within it) entirely, matching this field's
+     * `#[serde(default)]` on the Rust side. `defaultTheme` below still
+     * populates all three explicitly, matching the Rust fallback strings
+     * byte-for-byte, so a caller reading `defaultTheme.fontFamily.sans`
+     * (e.g. to extend rather than replace it) gets the real value rather
+     * than needing to already know the Rust-side fallback text.
+     */
+    fontFamily?: Record<string, string>;
+    darkMode: DarkModeStrategy;
+    /** Optional, matching `ContainerConfig`'s own `#[serde(default)]` on the Rust side — an omitted theme.container behaves exactly like `{}`. */
+    container?: ContainerConfig;
+}
+declare const defaultTheme: ThemeConfig;
+declare function setTheme(theme: ThemeConfig): void;
+declare function getTheme(): ThemeConfig;
+
+/**
+ * A `kbach.config.js`-style theme customization, in one plain object — same
+ * `theme`/`extend`/`darkMode` shape real Tailwind's own config file uses,
+ * simplified from old-kbach's version (no plugins, no color alias chains
+ * with cycle detection, no live-update-listener store): a config object
+ * goes in, a resolved `ThemeConfig` comes out, via one PURE function
+ * (`resolveKbachConfig`) — same input always produces the same output, so
+ * nothing needs to stay "in sync" the way old-kbach's Babel-injected config
+ * singleton did. Call it identically from a Node.js build script
+ * (`vite.config.ts`) and from browser/app code (`applyKbachConfig`) and
+ * both get the exact same theme, no synchronization mechanism required.
+ */
+interface KbachConfig {
+    /** Applied on top of `defaultTheme`; `undefined` means "keep the default". */
+    darkMode?: DarkModeStrategy;
+    /**
+     * REPLACES the named section of `defaultTheme` entirely (e.g. supplying
+     * `theme.colors` drops the rest of the default palette) — use `extend`
+     * instead to add to the defaults rather than replace them. `container`
+     * isn't here (only under `extend` below) — it has no "defaults to
+     * replace" the way colors/spacing/screens/fontFamily do, since real
+     * Tailwind's own container config is inherently additive (center/padding
+     * on top of the always-present breakpoint ladder), so there's no
+     * meaningful distinction between "replace" and "extend" for it.
+     */
+    theme?: Partial<Pick<ThemeConfig, 'colors' | 'spacing' | 'screens' | 'fontFamily'>>;
+    /** Merges INTO `defaultTheme` (or `theme` above, if also supplied) — the common case. */
+    extend?: {
+        /**
+         * A value is either a literal color (a hex string, or `{ light, dark }`
+         * — same mode-aware shape `useColors()`/`useTheme()` already support)
+         * or a REFERENCE to another color name, optionally with an opacity
+         * suffix. Two things can be referenced:
+         * - A BUILT-IN palette color, always available regardless of ordering
+         *   (`accent: 'orange-5'`, `accentSoft: 'orange-5/50'`).
+         * - A custom color defined EARLIER in this same object
+         *   (`{ brand: '#ff6b35', brandSoft: 'brand/30' }` — `brandSoft`
+         *   resolves to `brand`'s own value at 30% opacity, computed once here
+         *   rather than needing a `colors.alpha()` call at every use site).
+         * A string that doesn't match any known color name (built-in or
+         * 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.
+         */
+        colors?: Record<string, ColorEntry | 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. */
+        fontFamily?: Record<string, string>;
+        /** `{ center: true, padding: '2rem' }` — see `ContainerConfig`'s own doc comment. */
+        container?: ContainerConfig;
+    };
+}
+/** 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). */
+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 };