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

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

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

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

@@ -2,7 +2,7 @@ import {
   BASE_RESET,
   RESET_STYLE_ID,
   getThemeJson
-} from "./chunk-FOQWQDF4.mjs";
+} from "./chunk-EOSN5CYG.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 };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-export { T as ThemeConfig, d as defaultTheme, g as getTheme, s as setTheme } from './theme-BKAb78KP.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-BQ_b-qxF.mjs';
 import * as react from 'react';
 import { ReactNode } from 'react';
 
@@ -61,16 +61,23 @@ declare function setGlobalThemeMode(nextMode: ThemeMode): void;
 declare function toggleGlobalDarkMode(): void;
 declare function subscribeGlobalDarkMode(listener: () => void): () => void;
 
+interface ThemeState {
+    mode: ThemeMode;
+    isDark: boolean;
+    setMode: (mode: ThemeMode) => void;
+    toggle: () => void;
+}
 /**
- * Reactive read of the global dark-mode store — works with or without a
- * `<ThemeProvider>` mounted anywhere in the tree, since it subscribes to
- * `darkModeStore.ts` directly. `useSyncExternalStore`'s SSR snapshot always
- * returns `false` (light), matching `applyToDom`'s own server no-op — the
- * server and the client's very first render agree, so there's no
- * hydration-mismatch warning; the real value (if different) applies on the
- * client immediately after.
+ * The one hook for reading and writing Kbach's dark-mode state. Reads
+ * `darkModeStore.ts`'s global store directly via `useSyncExternalStore` —
+ * that module-level store, not React Context, is the actual source of
+ * truth (every provider used to just mirror it into a Context value), so
+ * this works from ANY component, with or without a `<ThemeProvider>`
+ * mounted anywhere in the tree. `<ThemeProvider>` still exists, but purely
+ * as an optional convenience for seeding an app's initial `defaultMode` —
+ * see its own doc comment.
  */
-declare function useGlobalDarkMode(): boolean;
+declare function useTheme(): ThemeState;
 
 interface ThemeProviderProps {
     children: ReactNode;
@@ -82,36 +89,60 @@ interface ThemeProviderProps {
     defaultMode?: ThemeMode;
 }
 /**
- * Optional React Context wrapper around `darkModeStore.ts`'s single global
- * store — port of old-kbach's `ThemeProvider` (`packages/ui/src/
- * ThemeProvider.tsx`), same "provider is a thin wrapper around a global
- * store, not the source of truth itself" shape, simplified to this
- * package's web-only scope (no native `useColorScheme()`/`windowWidth`
- * branch, no `disablePersistence` prop — persistence is always on, since
- * `darkModeStore.ts` already guards every `localStorage` access for
- * environments where it's unavailable).
+ * Optional — `useTheme()` reads `darkModeStore.ts`'s global store directly
+ * and works anywhere without this mounted at all. The only thing this
+ * component does is seed that store's initial `defaultMode` once, for apps
+ * that want to declare a startup default in JSX rather than calling
+ * `setGlobalThemeMode()` imperatively before their first render. It
+ * renders `children` as-is — no Context.Provider, since there's no value
+ * left to distribute; `useTheme()` never reads from Context.
  *
- * Because the store is global, MULTIPLE mounted providers share the exact
- * same `mode`/`isDark` state rather than each getting their own scoped
- * value — mounting more than one is very likely a mistake (each fighting
- * over the same state via a different `defaultMode`), so this warns once
- * in dev, matching old-kbach's identical guard.
+ * Because the store is global, MULTIPLE mounted providers would each try
+ * to seed the exact same store rather than getting their own scoped
+ * state — mounting more than one is very likely a mistake, so this warns
+ * once in dev.
  */
 declare function ThemeProvider({ children, defaultMode }: ThemeProviderProps): react.JSX.Element;
 
-interface ThemeContextValue {
-    mode: ThemeMode;
-    isDark: boolean;
-    setMode: (mode: ThemeMode) => void;
-    toggle: () => void;
+interface ColorScale {
+    /** `colors.blue[6]` -> raw value */
+    readonly [shade: number]: string;
+    /** `colors.blue['6/50']` -> shade 6 at 50% opacity */
+    readonly [key: string]: string;
 }
+type ColorsAPI = {
+    /** `colors.white`, `colors.blue` (a shade family), `colors.surface`, ... */
+    readonly [name: string]: string | ColorScale;
+} & {
+    /**
+     * Applies an opacity (0–100) to any color string this hook can return —
+     * a hex, `rgb()`/`rgba()`, or one of this hook's own
+     * `rgb(var(--kb-color-x))` mode-aware references.
+     */
+    readonly alpha: (color: string, opacity?: number) => string;
+};
 /**
- * Requires a `<ThemeProvider>` ancestor — throws otherwise, since a
- * component that destructures `{ mode, setMode }` genuinely needs Context
- * (unlike a component that just wants the dark/light boolean, which should
- * reach for `useGlobalDarkMode()` instead and never needs a provider at
- * all).
+ * Resolved theme colors as real values — for anywhere you need an actual
+ * color (an SVG `fill`, a canvas context, a chart library prop), not a
+ * `className`. Ported from old-kbach's `useColors()`
+ * (`old-kbach/packages/ui/src/useColors.ts`), adapted to this engine's flat
+ * `"blue-6"`-keyed palette (`colors.blue[6]` looks up `"blue-6"`).
+ *
+ * Any color — a shade-family entry like `"blue-6"` or a standalone name
+ * like `"surface"` — can be defined in the theme as either a plain string
+ * (static, same in both modes) or a `{ light, dark }` pair — fully manual,
+ * no automatic shade-shifting or other assumption about what a "dark
+ * variant" should be; see `resolveEntry`'s own doc comment for how a
+ * `{ light, dark }` entry resolves.
+ *
+ * ```ts
+ * const colors = useColors();
+ * colors.blue[6];         // "#3b82f6" — 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 }
+ * colors.alpha(colors.surface, 50); // "rgba(var(--kb-color-surface), 0.5)"
+ * ```
  */
-declare function useTheme(): ThemeContextValue;
+declare function useColors(): ColorsAPI;
 
-export { KbachReset, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, disableRuntimeCSS, getGlobalDarkMode, getGlobalThemeMode, initKbach, isKbachReady, isRuntimeCSSDisabled, kb, setGlobalThemeMode, subscribeGlobalDarkMode, toggleGlobalDarkMode, useGlobalDarkMode, useTheme };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { T as ThemeConfig, d as defaultTheme, g as getTheme, s as setTheme } from './theme-BKAb78KP.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-BQ_b-qxF.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 
@@ -61,16 +61,23 @@ declare function setGlobalThemeMode(nextMode: ThemeMode): void;
 declare function toggleGlobalDarkMode(): void;
 declare function subscribeGlobalDarkMode(listener: () => void): () => void;
 
+interface ThemeState {
+    mode: ThemeMode;
+    isDark: boolean;
+    setMode: (mode: ThemeMode) => void;
+    toggle: () => void;
+}
 /**
- * Reactive read of the global dark-mode store — works with or without a
- * `<ThemeProvider>` mounted anywhere in the tree, since it subscribes to
- * `darkModeStore.ts` directly. `useSyncExternalStore`'s SSR snapshot always
- * returns `false` (light), matching `applyToDom`'s own server no-op — the
- * server and the client's very first render agree, so there's no
- * hydration-mismatch warning; the real value (if different) applies on the
- * client immediately after.
+ * The one hook for reading and writing Kbach's dark-mode state. Reads
+ * `darkModeStore.ts`'s global store directly via `useSyncExternalStore` —
+ * that module-level store, not React Context, is the actual source of
+ * truth (every provider used to just mirror it into a Context value), so
+ * this works from ANY component, with or without a `<ThemeProvider>`
+ * mounted anywhere in the tree. `<ThemeProvider>` still exists, but purely
+ * as an optional convenience for seeding an app's initial `defaultMode` —
+ * see its own doc comment.
  */
-declare function useGlobalDarkMode(): boolean;
+declare function useTheme(): ThemeState;
 
 interface ThemeProviderProps {
     children: ReactNode;
@@ -82,36 +89,60 @@ interface ThemeProviderProps {
     defaultMode?: ThemeMode;
 }
 /**
- * Optional React Context wrapper around `darkModeStore.ts`'s single global
- * store — port of old-kbach's `ThemeProvider` (`packages/ui/src/
- * ThemeProvider.tsx`), same "provider is a thin wrapper around a global
- * store, not the source of truth itself" shape, simplified to this
- * package's web-only scope (no native `useColorScheme()`/`windowWidth`
- * branch, no `disablePersistence` prop — persistence is always on, since
- * `darkModeStore.ts` already guards every `localStorage` access for
- * environments where it's unavailable).
+ * Optional — `useTheme()` reads `darkModeStore.ts`'s global store directly
+ * and works anywhere without this mounted at all. The only thing this
+ * component does is seed that store's initial `defaultMode` once, for apps
+ * that want to declare a startup default in JSX rather than calling
+ * `setGlobalThemeMode()` imperatively before their first render. It
+ * renders `children` as-is — no Context.Provider, since there's no value
+ * left to distribute; `useTheme()` never reads from Context.
  *
- * Because the store is global, MULTIPLE mounted providers share the exact
- * same `mode`/`isDark` state rather than each getting their own scoped
- * value — mounting more than one is very likely a mistake (each fighting
- * over the same state via a different `defaultMode`), so this warns once
- * in dev, matching old-kbach's identical guard.
+ * Because the store is global, MULTIPLE mounted providers would each try
+ * to seed the exact same store rather than getting their own scoped
+ * state — mounting more than one is very likely a mistake, so this warns
+ * once in dev.
  */
 declare function ThemeProvider({ children, defaultMode }: ThemeProviderProps): react.JSX.Element;
 
-interface ThemeContextValue {
-    mode: ThemeMode;
-    isDark: boolean;
-    setMode: (mode: ThemeMode) => void;
-    toggle: () => void;
+interface ColorScale {
+    /** `colors.blue[6]` -> raw value */
+    readonly [shade: number]: string;
+    /** `colors.blue['6/50']` -> shade 6 at 50% opacity */
+    readonly [key: string]: string;
 }
+type ColorsAPI = {
+    /** `colors.white`, `colors.blue` (a shade family), `colors.surface`, ... */
+    readonly [name: string]: string | ColorScale;
+} & {
+    /**
+     * Applies an opacity (0–100) to any color string this hook can return —
+     * a hex, `rgb()`/`rgba()`, or one of this hook's own
+     * `rgb(var(--kb-color-x))` mode-aware references.
+     */
+    readonly alpha: (color: string, opacity?: number) => string;
+};
 /**
- * Requires a `<ThemeProvider>` ancestor — throws otherwise, since a
- * component that destructures `{ mode, setMode }` genuinely needs Context
- * (unlike a component that just wants the dark/light boolean, which should
- * reach for `useGlobalDarkMode()` instead and never needs a provider at
- * all).
+ * Resolved theme colors as real values — for anywhere you need an actual
+ * color (an SVG `fill`, a canvas context, a chart library prop), not a
+ * `className`. Ported from old-kbach's `useColors()`
+ * (`old-kbach/packages/ui/src/useColors.ts`), adapted to this engine's flat
+ * `"blue-6"`-keyed palette (`colors.blue[6]` looks up `"blue-6"`).
+ *
+ * Any color — a shade-family entry like `"blue-6"` or a standalone name
+ * like `"surface"` — can be defined in the theme as either a plain string
+ * (static, same in both modes) or a `{ light, dark }` pair — fully manual,
+ * no automatic shade-shifting or other assumption about what a "dark
+ * variant" should be; see `resolveEntry`'s own doc comment for how a
+ * `{ light, dark }` entry resolves.
+ *
+ * ```ts
+ * const colors = useColors();
+ * colors.blue[6];         // "#3b82f6" — 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 }
+ * colors.alpha(colors.surface, 50); // "rgba(var(--kb-color-surface), 0.5)"
+ * ```
  */
-declare function useTheme(): ThemeContextValue;
+declare function useColors(): ColorsAPI;
 
-export { KbachReset, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, disableRuntimeCSS, getGlobalDarkMode, getGlobalThemeMode, initKbach, isKbachReady, isRuntimeCSSDisabled, kb, setGlobalThemeMode, subscribeGlobalDarkMode, toggleGlobalDarkMode, useGlobalDarkMode, useTheme };
+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 };