@kbach/react 0.6.49 → 0.6.51

package/README.md

@@ -38,7 +38,8 @@ That's the only setting needed — Vite, Next.js, and React Router all read it.
 |---|---|
 | Vite, React Router library mode, CRA, other Vite-based | **[Static CSS setup](#static-css-setup)** (recommended) — zero runtime cost, catches typos at build time. [Runtime setup](#runtime-setup) is there if you'd rather skip the plugin for now. |
 | React Router, framework mode | **[Static CSS setup](#static-css-setup)** — and skip `@vitejs/plugin-react`, see note in that section |
-| Next.js | **[Runtime setup](#runtime-setup)** — Static CSS doesn't apply (webpack/Turbopack, not Vite) |
+| Next.js | **[Next.js setup](#nextjs-setup)** — Runtime setup, plus one App Router-specific detail |
+| React Native, Expo | **[React Native / Expo setup](#react-native--expo-setup)** — different setup entirely (Babel preset, not the JSX runtime step above) |
 
 ## Static CSS setup
 
@@ -98,7 +99,7 @@ export default defineConfig({ plugins: [kbach(), reactRouter()] });
 
 ## Runtime setup
 
-Client-side CSS injection — works with any bundler (Vite, webpack, Turbopack, Metro-for-web, …), no build plugin. The right choice for Next.js (Static CSS doesn't apply there), or if you'd rather not wire up a Vite plugin yet. This is the whole setup:
+Client-side CSS injection — works with any bundler (Vite, webpack, Turbopack, Metro-for-web, …), no build plugin. Next.js always uses this (see [Next.js setup](#nextjs-setup) below for the one extra detail), or use it on Vite if you'd rather not wire up the plugin yet. This is the whole setup:
 
 ```jsx
 import { ThemeProvider, KbachReset } from '@kbach/react';
@@ -113,12 +114,115 @@ export default function Root() {
 }
 ```
 
-That's it — done. `<KbachReset />` renders the base reset (see [CSS resets](#css-resets)) as real markup instead of waiting on client JS — matters most for SSR, where it avoids a flash of unstyled browser defaults before hydration. `@kbach/react` ships its own `"use client"` directive, so this works in a Next.js Server Component tree with no wrapper needed — in Next.js, render it once in the root `layout.tsx`.
+That's it — done. `<KbachReset />` renders the base reset (see [CSS resets](#css-resets)) as real markup instead of waiting on client JS — matters most for SSR, where it avoids a flash of unstyled browser defaults before hydration.
 
 Using a custom `kbach.config.js`? Pass it to `ThemeProvider` too — see [Wiring the config in](#wiring-the-config-in--required-for-both-setups).
 
 Don't also set up Static CSS above in the same app — pick one.
 
+## Next.js setup
+
+Next.js is always [Runtime setup](#runtime-setup) above — Static CSS doesn't apply (webpack/Turbopack, not Vite). The `tsconfig.json` step from [Setup](#setup) applies as-is; SWC reads `jsxImportSource` the same way Vite does.
+
+The one Next.js-specific detail: render `<KbachReset />` once in the root App Router `layout.tsx` (inside `<head>`, or right after `<ThemeProvider>` opens) so the Server Component HTML has the base reset without waiting on hydration:
+
+```jsx
+// app/layout.tsx
+import { ThemeProvider, KbachReset } from '@kbach/react';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <ThemeProvider defaultMode="system">
+          <KbachReset />
+          {children}
+        </ThemeProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+Without `<KbachReset />` there, expect a flash of raw browser defaults (native button border, arrow-less `<select>`, etc.) on first paint until hydration completes. Utility classes beyond the base reset still wait on hydration either way — a known limitation of the runtime-only path (Static CSS isn't available for webpack/Turbopack), not a per-project bug.
+
+`@kbach/react`'s compiled output ships its own `"use client"` directive, so App Router Server Components can use `className`, `styled()`, hooks, `<ThemeProvider>`, and `<KbachReset>` directly — no manual `'use client'` wrapper needed anywhere in your own components.
+
+## React Native / Expo setup
+
+Same `npm install @kbach/react` — no separate package. Everything below (API, modifiers, color system) is the same import as web; only setup differs.
+
+**1. babel.config.js:**
+
+```js
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: [
+      'babel-preset-expo',
+      '@kbach/react/babel',
+    ],
+  };
+};
+```
+
+Or the one-liner helper: `const { createKbachConfig } = require('@kbach/react/native'); module.exports = createKbachConfig();` — identical result. Merging into an existing config: `withKbachBabel({ presets: [...] })`, also from `@kbach/react/native`. After changing this file, clear the Metro cache: `npx expo start --clear`.
+
+**2. Wrap your app:**
+
+```jsx
+import { ThemeProvider } from '@kbach/react/native';
+
+export default function App() {
+  return (
+    <ThemeProvider defaultMode="system">
+      <AppContent />
+    </ThemeProvider>
+  );
+}
+```
+
+This is a native-aware `ThemeProvider` — reads `useColorScheme()`/`useWindowDimensions()` automatically, no extra props needed. Import it from `@kbach/react/native`, not the plain `ThemeProvider` from `@kbach/react` — that one has no automatic RN wiring (colors scheme/window width would need to be passed in by hand).
+
+### Platform differences
+
+A handful of utilities are native-only or web-only:
+
+| | |
+|---|---|
+| Native-only | `tint-{color}` (Image/icon tinting), `perspective-{n}`, `backface-hidden`, `text-shadow`/`text-shadow-lg` |
+| Web-only, ignored on native (no warning) | `caret-*` `accent-*` `stroke-*` `fill-*` `touch-*` `float-*` `clear-*` `line-clamp-*` `scroll-*` `animate-*` `transition` `filter` `backdrop-filter` `print:` `before:` `after:` `selection:` `first-letter:` `first-line:` `marker:` `landscape:` `portrait:` `motion-reduce:` `motion-safe:` `contrast-more:` `contrast-less:` `rtl:` `ltr:` `grid` `grid-cols-*` `ring-offset-*` `outline-*` `cursor-*` `bg-gradient-*` |
+
+`ring`/`ring-{n}`/`ring-{color}` is a partial exception — RN has no box-shadow, so it falls back to `borderWidth`/`borderColor`, which *does* affect layout and shares properties with `border-*` (whichever class comes last wins if you combine both).
+
+CSS inheritance doesn't exist in React Native — apply font utilities to each `Text`, or define a styled component once: `const Body = styled(Text, 'font-sans text-gray-10 dark:text-white');`.
+
+### Expo Web / React Native Web
+
+In a browser (Expo Web, Metro web), `@kbach/react` switches to the same CSS-class strategy as plain web automatically:
+
+- RN components substitute to HTML: `View`/`ScrollView`→`div`, `Text`→`span`, `TextInput`→`input`/`textarea`, `Image`→`img`, `Pressable`/`TouchableOpacity`→`div[role=button]`
+- RN-only props (`onChangeText`, `source`, `secureTextEntry`, …) map to HTML equivalents
+- Register more: `registerWebElement(Animated.View, 'div')`
+- Recommended: use the Vite plugin same as [Static CSS setup](#static-css-setup) above — `import { kbach } from '@kbach/react/vite'` — and import `kbach.css` in your entry file, for zero runtime cost on the web target too
+- Not using the Vite plugin (the common case for Expo/Metro web, which has no Vite build step)? Render `<KbachReset />` once near your root — e.g. Expo Router's root `app/_layout.tsx`, inside `<ThemeProvider>`:
+
+  ```jsx
+  import { KbachReset } from '@kbach/react';
+  import { ThemeProvider } from '@kbach/react/native';
+
+  export default function RootLayout() {
+    return (
+      <ThemeProvider defaultMode="system">
+        <KbachReset />
+        <Slot />
+      </ThemeProvider>
+    );
+  }
+  ```
+
+  This ships the base reset as real markup instead of relying solely on the runtime injector.
+
 ## Dark mode
 
 `<ThemeProvider>` powers every `dark:` class — detects OS color scheme, persists the user's choice, re-renders on change.
@@ -135,7 +239,7 @@ Don't also set up Static CSS above in the same app — pick one.
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `defaultMode` | `'light' \| 'dark' \| 'system'` | `'system'` | Starting mode |
-| `disablePersistence` | `boolean` | `false` | Skip saving to `localStorage` |
+| `disablePersistence` | `boolean` | `false` | Skip saving to `localStorage` (web) / `AsyncStorage` (native) |
 | `config` | `FrameworkConfig` | global config | Scope a different config to this subtree |
 
 `darkMode` in `kbach.config.js` picks the matching strategy: `'attribute'` (default), `'class'`, or `'media'` (system-only). Toggle it with `useTheme()`'s `toggle()`/`setMode()` — see [API](#api).
@@ -364,6 +468,6 @@ Skipping the runtime one is an easy mistake under Static CSS setup specifically
 
 ## Full reference
 
-[kbach-react.md](./kbach-react.md) — complete utility list, every modifier, all config options.
+[kbach-react.md](./kbach-react.md) — complete utility list, every modifier, all config options, covers web and React Native/Expo.
 
-React Native / Expo: [`@kbach/native`](https://www.npmjs.com/package/@kbach/native).
+`@kbach/native` still exists on npm but is now just a deprecated compatibility shim re-exporting this package — install `@kbach/react` directly for new projects.

package/dist/core/index.d.ts

@@ -233,7 +233,7 @@ declare function expandModeAwareColorClasses(classString: string, colors: ThemeC
 /**
  * Generates the KbachCustomColors/KbachCustomSpacing module-augmentation
  * source for every color/spacing key `extend.theme` added beyond the built-in
- * defaults. Called by both the Vite plugin and @kbach/native's Babel plugin —
+ * defaults. Called by both the Vite plugin and the Babel plugin (@kbach/react/babel-plugin) —
  * kept here, shared, so "which colors count as custom" and "flat string vs.
  * ColorScale" can't drift between the two.
  *

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import React__default, { ReactNode, ComponentType, ForwardRefExoticComponent } from 'react';
+import React__default, { Context, ReactNode, ComponentType, ForwardRefExoticComponent } from 'react';
 import * as __core from './core';
 import { ThemeMode, ResolvedConfig, DefaultColorName, defaultColors, ThemeColors, DefaultSpacingKey, ThemeSpacing, FrameworkConfig, StyleValue, ResolvedStyle } from './core';
 export { DefaultColorName, DefaultSpacingKey, FrameworkConfig, ParsedClass, PluginAPI, ResolvedConfig, ResolvedStyle, StyleValue, ThemeConfig, ThemeMode, buildConfig, clearCache, defaultColors, defaultTheme, disableRuntimeCSS, flatten, generateKbachTypesDts, getConfig, initConfig, normalizeClassString, parseClass, parseClasses, resolve, setResolveTarget, splitClassTokens, updateConfig } from './core';
@@ -19,7 +19,10 @@ interface ThemeContextValue {
     /** The fully resolved framework config (theme values, darkMode strategy, etc.) */
     config: ResolvedConfig;
 }
-declare const ThemeContext: React.Context<ThemeContextValue | null>;
+declare global {
+    var __kbachThemeContext: Context<ThemeContextValue | null> | undefined;
+}
+declare const ThemeContext: Context<ThemeContextValue | null>;
 declare function useTheme(): ThemeContextValue;
 declare function useIsDark(): boolean;
 
@@ -134,7 +137,7 @@ interface ThemeProviderProps {
      * System color scheme for native `defaultMode="system"`.
      *
      * Pass the value of `useColorScheme()` from `react-native`. When importing
-     * `ThemeProvider` from `@kbach/native` this is handled automatically.
+     * `ThemeProvider` from `@kbach/react/native` this is handled automatically.
      *
      * @example
      * ```tsx
@@ -147,7 +150,7 @@ interface ThemeProviderProps {
     /**
      * Current window/screen width in pixels for responsive breakpoints.
      * On web this is read from `window.innerWidth` automatically.
-     * When importing `ThemeProvider` from `@kbach/native` this is provided
+     * When importing `ThemeProvider` from `@kbach/react/native` this is provided
      * automatically from `useWindowDimensions()`.
      */
     windowWidth?: number;

package/dist/index.js

@@ -71,7 +71,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/context.tsx
 var import_react = require("react");
-var ThemeContext = (0, import_react.createContext)(null);
+var ThemeContext = globalThis.__kbachThemeContext ?? (globalThis.__kbachThemeContext = (0, import_react.createContext)(null));
 function useTheme() {
   const ctx = (0, import_react.useContext)(ThemeContext);
   if (!ctx) {

package/dist/index.mjs

@@ -52,7 +52,7 @@ import {
 
 // src/context.tsx
 import { createContext, useContext } from "react";
-var ThemeContext = createContext(null);
+var ThemeContext = globalThis.__kbachThemeContext ?? (globalThis.__kbachThemeContext = createContext(null));
 function useTheme() {
   const ctx = useContext(ThemeContext);
   if (!ctx) {

package/dist/native.d.ts

@@ -0,0 +1,314 @@
+import React, { ReactNode } from 'react';
+
+/**
+ * Unified modifier registry — single source of truth for ALL modifier behavior.
+ *
+ * Adding a new modifier requires editing ONLY this file:
+ *   1. Add an entry to BUILTIN_MODIFIERS with its CSS and JS behavior.
+ *   2. Done — parser, resolver, CSS generator, and JSX runtime all derive
+ *      their behavior from this data automatically.
+ *
+ * Plugin authors can register custom modifiers via registerModifier().
+ */
+interface ModifierDef {
+    /**
+     * Cascade priority for CSS rule ORDER — NOT specificity. Two rules that
+     * differ only by modifier (e.g. `.hover\:bg-blue-6:hover` and
+     * `.focus\:bg-red-6:focus`) have equal CSS specificity, so when both
+     * conditions are true at once (hovering AND focused), the winner is
+     * whichever rule appears LATER in the stylesheet — CSS's normal same-
+     * specificity tiebreak. Without a fixed priority, "later" would depend on
+     * encounter order (whichever class the app happens to render/scan first),
+     * making the winner effectively random and inconsistent across reloads/
+     * builds. `order` fixes that: rules are emitted/injected sorted by this
+     * value (ascending — higher wins ties), regardless of source order, so
+     * e.g. `disabled:` always beats `hover:` on the same element no matter
+     * which one was written first in the className or rendered first in the
+     * app. Omit for the default (0). See getModifierOrder() below.
+     */
+    order?: number;
+    /** CSS pseudo-class or pseudo-element appended to the selector (e.g. ':hover', '::before') */
+    pseudo?: string;
+    /** Ancestor selector prefix INCLUDING trailing space (e.g. '.group:hover ', '.peer:focus ~ ') */
+    ancestorSelector?: string;
+    /** Directionality attribute selector prefix INCLUDING trailing space (e.g. '[dir="rtl"] ') */
+    dirSelector?: string;
+    /** @media query body WITHOUT the '@media ' prefix (e.g. 'print', '(orientation: landscape)') */
+    mediaQuery?: string;
+    /** Dark/light mode scheme — triggers the configured darkMode strategy in CSS output */
+    darkScheme?: 'dark' | 'light';
+    /** True for responsive modifiers — wraps in @media (min-width: theme.screens[name]) */
+    isResponsive?: boolean;
+    /**
+     * Forces !important on all declarations in the generated CSS rule.
+     * Applied automatically for structural / ancestor / media modifiers that must
+     * win over base inline styles.
+     */
+    forcesImportant?: boolean;
+    /**
+     * How the JSX runtime routes this modifier:
+     *   'interactive'  — managed by InteractiveWrapper (hover, focus, pressed, …)
+     *   'mode'         — managed by DarkWrapper (dark, light, not-dark, …)
+     *   'responsive'   — managed by DarkWrapper (sm, md, lg, xl, 2xl)
+     *   'css-only'     — CSS injection only; matchModifier always returns false
+     */
+    jsBehavior: 'interactive' | 'mode' | 'responsive' | 'css-only';
+    /**
+     * Evaluates whether this modifier's condition is met at runtime.
+     * Omit for 'css-only' modifiers — they never apply as inline styles.
+     */
+    jsMatch?: (isDark: boolean, state: Record<string, boolean | undefined>, breakpoints: Set<string>) => boolean;
+}
+
+type ThemeMode = 'light' | 'dark' | 'system';
+interface StyleValue {
+    [key: string]: string | number | undefined | null | StyleValue | StyleValue[];
+}
+/**
+ * A color value is either a plain string (hex/rgb/alias-to-another-color-name)
+ * or a mode-aware pair — resolved to `light` or `dark` per the active theme
+ * mode wherever it's actually used (className resolution, useColors()).
+ */
+type ColorValue = string | {
+    light: string;
+    dark: string;
+};
+type ColorShades = Record<string, ColorValue>;
+type ThemeColors = Record<string, ColorValue | ColorShades>;
+type ThemeSpacing = Record<string, number | string>;
+interface ThemeConfig {
+    colors: ThemeColors;
+    spacing: ThemeSpacing;
+    fontSize: Record<string, number | string>;
+    fontFamily: Record<string, string | string[]>;
+    fontWeight: Record<string, string | number>;
+    borderRadius: Record<string, number | string>;
+    borderWidth: Record<string, number>;
+    opacity: Record<string, number>;
+    lineHeight: Record<string, number | string>;
+    letterSpacing: Record<string, number | string>;
+    zIndex: Record<string, number | string>;
+    flex: Record<string, number | string>;
+    shadow: Record<string, StyleValue>;
+    screens: Record<string, string | number>;
+    /**
+     * Custom @keyframes, web only. Each key is a keyframe name, its value maps
+     * percentage/from/to selectors to a plain CSS declaration object (camelCase
+     * properties, same shape as an inline style object):
+     *   keyframes: { wiggle: { '0%, 100%': { transform: 'rotate(-3deg)' }, '50%': { transform: 'rotate(3deg)' } } }
+     * Referenced from `animation` below, or directly via animate-[wiggle_1s_ease-in-out].
+     */
+    keyframes: Record<string, Record<string, StyleValue>>;
+    /**
+     * Named animation shorthands built on `keyframes` above, referenced via
+     * animate-{name} (e.g. animate-wiggle):
+     *   animation: { wiggle: 'wiggle 1s ease-in-out infinite' }
+     * The first word must match a `keyframes` key so its @keyframes rule can be
+     * injected alongside the animation — a name with no matching keyframes entry
+     * still sets the `animation` CSS property, it just won't animate anything.
+     */
+    animation: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * 'class'     — toggles .dark class on <html>
+ * 'media'     — uses prefers-color-scheme media query
+ * 'attribute' — uses data-theme="dark" attribute on <html>
+ */
+type DarkMode = 'attribute' | 'class' | 'media';
+interface PluginAPI {
+    addUtility(name: string, styles: StyleValue): void;
+    /**
+     * Register a custom variant.
+     *
+     * Pass a CSS selector string for simple cases — it is automatically
+     * converted into a ModifierDef that generates correct CSS rules:
+     *   addVariant('hocus', ':hover, :focus')  // pseudo
+     *   addVariant('supports-grid', '@media (display: grid)')  // media
+     *   addVariant('dark-green', '.dark-green')  // ancestor selector
+     *
+     * Pass a full ModifierDef object for advanced control (e.g. JS-trackable
+     * interactive variants with custom jsMatch logic).
+     */
+    addVariant(name: string, selectorOrDef: string | ModifierDef): void;
+    theme(path: string, defaultValue?: unknown): unknown;
+    e(className: string): string;
+}
+interface FrameworkConfig {
+    darkMode?: DarkMode;
+    theme?: Partial<ThemeConfig>;
+    /** Additive theme extension — accepts either `extend.theme.X` or `extend.X` directly. */
+    extend?: {
+        theme?: Partial<ThemeConfig>;
+    } & Partial<ThemeConfig>;
+    plugins?: Array<(api: PluginAPI) => void>;
+    content?: string[];
+}
+
+interface ThemeProviderProps {
+    children: ReactNode;
+    /** Initial mode. Falls back to persisted value, then 'system'. */
+    defaultMode?: ThemeMode;
+    /**
+     * System color scheme for native `defaultMode="system"`.
+     *
+     * Pass the value of `useColorScheme()` from `react-native`. When importing
+     * `ThemeProvider` from `@kbach/react/native` this is handled automatically.
+     *
+     * @example
+     * ```tsx
+     * import { useColorScheme } from 'react-native';
+     * const colorScheme = useColorScheme();
+     * <ThemeProvider defaultMode="system" colorScheme={colorScheme}>…</ThemeProvider>
+     * ```
+     */
+    colorScheme?: 'light' | 'dark' | null;
+    /**
+     * Current window/screen width in pixels for responsive breakpoints.
+     * On web this is read from `window.innerWidth` automatically.
+     * When importing `ThemeProvider` from `@kbach/react/native` this is provided
+     * automatically from `useWindowDimensions()`.
+     */
+    windowWidth?: number;
+    /** Override the config (useful for per-tree config). Defaults to global getConfig(). */
+    config?: FrameworkConfig;
+    /** Disable persistence to localStorage */
+    disablePersistence?: boolean;
+}
+
+/**
+ * Native-aware ThemeProvider. Wraps the base ThemeProvider and automatically
+ * passes the system color scheme from React Native's useColorScheme() hook.
+ *
+ * This fixes Android startup dark mode detection: Appearance.getColorScheme()
+ * can cache null if the device was already dark at launch (the appearanceChanged
+ * event only fires on *changes*). useColorScheme() called here with a proper
+ * hook name ensures the React Compiler and all linters handle it correctly, and
+ * useSyncExternalStore inside the hook properly subscribes to Appearance events.
+ *
+ * Exported as `ThemeProvider` from @kbach/react/native — no API change for
+ * existing @kbach/native users (that package now re-exports this).
+ *
+ * `react-native` is required here lazily (inside the function body) rather
+ * than via a top-level `import`. native/index.ts bundles this file together
+ * with setup.ts's Node-only helpers (createKbachConfig, withKbach,
+ * withKbachBabel), which babel.config.js loads by calling
+ * `require('@kbach/react/native')` in a plain Node.js process — no Metro, no
+ * Babel/Flow transform for react-native's own source. A top-level import
+ * would make Node eagerly require the real `react-native` package just to
+ * read createKbachConfig off the module, which crashes immediately
+ * (react-native's entry point isn't valid plain-Node JS). A require() inside
+ * the function body only ever runs when NativeThemeProvider actually renders
+ * — i.e. inside the real Metro/Hermes runtime, where require() is always
+ * available and react-native loads fine.
+ *
+ * This is also why the "./native" export has no separate ESM entry: tsup/
+ * esbuild can't emit a real `require()` inside ESM output — it rewrites it to
+ * a `__require` shim (`typeof require !== "undefined" ? require : …`). That
+ * shim still resolves to Metro's real require function at runtime, but
+ * Metro's bundler only registers a module's dependencies by statically
+ * finding literal `require("name")` calls in its source — `__require(...)`
+ * doesn't match, so "react-native" is never added to the compiled module's
+ * dependency map and Metro throws "Requiring unknown module" at runtime. The
+ * CJS build's plain `require('react-native')` call doesn't have this
+ * problem, so both "import" and "require" conditions point at dist/native.js.
+ *
+ * '@kbach/react' itself is required the same lazy way, for a different
+ * reason: this file is bundled into its own dist/native.js (see
+ * tsup.config.ts), separate from dist/index.js/.mjs. A top-level `import`
+ * would make esbuild inline a SECOND, independent copy of
+ * ThemeProvider.tsx/context.tsx (its own createContext() call) into
+ * dist/native.js, splitting ThemeContext between "@kbach/react" and
+ * "@kbach/react/native" consumers — require('@kbach/react') instead resolves
+ * through Node/npm workspaces' self-reference and tsup's default of treating
+ * anything outside the entry's own source tree as external, reaching the
+ * exact same dist/index.js instance every other consumer gets (verified by
+ * building and grepping dist/native.js for a literal require("@kbach/react")
+ * rather than an inlined copy). `typeof import(...)` for the type would hit
+ * the same self-reference resolution tsup's DTS step can't handle during its
+ * own package's build (unlike esbuild's JS bundling, which resolves it
+ * fine) — so the type comes from the relative ThemeProviderProps import
+ * above instead, and ThemeProvider itself is cast to match.
+ */
+declare function NativeThemeProvider(props: ThemeProviderProps): React.JSX.Element;
+
+/**
+ * Metro and Babel setup helpers for React Native / Expo projects.
+ *
+ * All three functions are meant to be called from Node.js config files
+ * (metro.config.js, babel.config.js). They are safe to import in React
+ * Native bundles but will never execute there.
+ */
+interface KbachOptions {
+    /** Path to kbach.config.js, relative to project root. Default: 'kbach.config.js' */
+    configFile?: string;
+    /** JSX attribute names to transform at build time. Default: ['kb', 'className'] */
+    attributes?: string[];
+    /** Log transformed class strings to the Metro console. Default: false */
+    debug?: boolean;
+}
+/**
+ * Inject the Kbach Babel plugin into a Metro transformer config.
+ *
+ * metro.config.js (Expo):
+ * ```js
+ * const { getDefaultConfig } = require('expo/metro-config');
+ * const { withKbach } = require('@kbach/react/native');
+ * const config = getDefaultConfig(__dirname);
+ * module.exports = withKbach(config);
+ * ```
+ *
+ * metro.config.js (bare React Native):
+ * ```js
+ * const { getDefaultConfig } = require('@react-native/metro-config');
+ * const { withKbach } = require('@kbach/react/native');
+ * const config = getDefaultConfig(__dirname);
+ * module.exports = withKbach(config);
+ * ```
+ */
+declare function withKbach(metroConfig: Record<string, any>, _options?: KbachOptions): Record<string, any>;
+/**
+ * Add the Kbach preset to an existing Babel config.
+ * Use this when you have a custom babel.config.js and want to keep it.
+ *
+ * babel.config.js:
+ * ```js
+ * const { withKbachBabel } = require('@kbach/react/native');
+ * module.exports = withKbachBabel({
+ *   presets: ['babel-preset-expo'],
+ * });
+ * ```
+ */
+declare function withKbachBabel(babelConfig: Record<string, any>, options?: KbachOptions): Record<string, any>;
+/**
+ * Generate a complete Babel config for Expo projects.
+ * This is the recommended one-liner for new projects.
+ *
+ * babel.config.js:
+ * ```js
+ * const { createKbachConfig } = require('@kbach/react/native');
+ * module.exports = createKbachConfig();
+ * ```
+ *
+ * Or written manually (identical to NativeWind's config shape):
+ * ```js
+ * module.exports = function(api) {
+ *   api.cache(true);
+ *   return {
+ *     presets: [
+ *       'babel-preset-expo',
+ *       '@kbach/react/babel',
+ *     ],
+ *   };
+ * };
+ * ```
+ *
+ * Do NOT pass `jsxImportSource: '@kbach/react'` to babel-preset-expo here —
+ * that sets the default JSX pragma for every file Metro transforms, including
+ * node_modules and react-native's own internals, which breaks them. See the
+ * comment in withKbachBabel above for why the per-file pragma comment the
+ * Kbach babel plugin injects is the only place that should apply.
+ */
+declare function createKbachConfig(options?: KbachOptions): Record<string, unknown>;
+
+export { type KbachOptions, NativeThemeProvider as ThemeProvider, createKbachConfig, withKbach, withKbachBabel };

package/dist/native.js

@@ -0,0 +1,99 @@
+'use client';
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/native/index.ts
+var native_exports = {};
+__export(native_exports, {
+  ThemeProvider: () => NativeThemeProvider,
+  createKbachConfig: () => createKbachConfig,
+  withKbach: () => withKbach,
+  withKbachBabel: () => withKbachBabel
+});
+module.exports = __toCommonJS(native_exports);
+
+// src/native/NativeThemeProvider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function NativeThemeProvider(props) {
+  const { useColorScheme, useWindowDimensions } = require("react-native");
+  const { ThemeProvider } = require("@kbach/react");
+  const raw = useColorScheme();
+  const { width } = useWindowDimensions();
+  const systemColorScheme = raw === "dark" ? "dark" : raw === "light" ? "light" : null;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    ThemeProvider,
+    {
+      ...props,
+      colorScheme: props.colorScheme ?? systemColorScheme,
+      windowWidth: props.windowWidth ?? width
+    }
+  );
+}
+
+// src/native/setup.ts
+function warn(message) {
+  const proc = process;
+  const useColor = !!proc.stdout?.isTTY && !proc.env.NO_COLOR;
+  const paint = (code, s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
+  console.warn(`${paint("1", paint("35", "[kbach]"))} ${paint("33", message)}`);
+}
+function withKbach(metroConfig, _options = {}) {
+  return metroConfig;
+}
+function withKbachBabel(babelConfig, options = {}) {
+  const {
+    configFile = "kbach.config.js",
+    attributes = ["kb", "className"],
+    debug = false
+  } = options;
+  const presets = (babelConfig.presets ?? []).map((preset) => {
+    const [name, presetOpts = {}] = Array.isArray(preset) ? preset : [preset, {}];
+    if (typeof name === "string" && (name.includes("babel-preset-expo") || name.includes("preset-react"))) {
+      const opts = presetOpts;
+      if (opts.jsxRuntime === "classic") {
+        warn(`Forcing jsxRuntime "automatic" on ${name} (was "classic") \u2014 required for Kbach`);
+      }
+      return [name, { ...opts, jsxRuntime: "automatic" }];
+    }
+    return preset;
+  });
+  return {
+    ...babelConfig,
+    presets: [...presets, ["@kbach/react/babel", { configFile, attributes, debug }]]
+  };
+}
+function createKbachConfig(options = {}) {
+  return {
+    presets: [
+      "babel-preset-expo",
+      ["@kbach/react/babel", {
+        configFile: options.configFile ?? "kbach.config.js",
+        attributes: options.attributes ?? ["kb", "className"],
+        debug: options.debug ?? false
+      }]
+    ]
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ThemeProvider,
+  createKbachConfig,
+  withKbach,
+  withKbachBabel
+});