@kbach/react-native 1.0.0-beta.0

package/README.md

@@ -0,0 +1,78 @@
+# @kbach/react-native
+
+Kbach's utility-class styling engine for React Native — the same class
+names as [`@kbach/react`](https://www.npmjs.com/package/@kbach/react),
+resolved to a real `StyleSheet`-ready style object instead of injected CSS.
+
+> **Beta, Android-only.** Resolution runs through a Kotlin/JNI TurboModule
+> calling the same Rust core `@kbach/react` uses, so class semantics stay
+> identical across web and native — but that TurboModule currently has to be
+> wired into your app's native Android project by hand (see
+> `apps/native-sandbox` in the [repo](https://github.com/semsakadanupol/kbach)
+> for a full working reference integration). There's no iOS bridge yet, and
+> no prebuilt native module distribution — expect to do real native-side
+> setup, not a drop-in `npm install`.
+
+## What this is
+
+- A JSX runtime (`@kbach/react-native/jsx-runtime`) that intercepts
+  `className`/`kb` props on every element and calls into the native bridge
+  to resolve them to a style object, synchronously, on every render.
+- A Babel plugin (`@kbach/react-native/babel-plugin`) that routes your
+  app's own files (never `node_modules`) through that JSX runtime via a
+  per-file `@jsxImportSource` pragma.
+- `setTheme()`/`getTheme()` for customizing the color palette and spacing
+  scale — the same `ThemeConfig` shape `@kbach/react` uses, kept as an
+  independent type here so a native-only project isn't forced to depend on
+  a web-oriented package.
+- `shadow-*` resolves to real native shadows — iOS's discrete
+  `shadowColor`/`shadowOffset`/`shadowOpacity`/`shadowRadius` and Android's
+  `elevation`, both derived from the same named tiers (`sm`/`DEFAULT`/`md`/
+  `lg`/`xl`/`2xl`) `@kbach/react`'s CSS `box-shadow` scale uses — one class
+  produces a real shadow on both platforms. `shadow-inner` and arbitrary
+  `shadow-[...]` values aren't supported — neither platform's native shadow
+  API can express an inset shadow, and an arbitrary value is a raw CSS
+  string with no mechanical translation into discrete native props.
+
+## Dark mode
+
+Works standalone, with zero provider — same architecture as `@kbach/react`:
+
+```tsx
+import { useGlobalDarkMode, toggleGlobalDarkMode } from '@kbach/react-native';
+
+function ThemeToggle() {
+  const isDark = useGlobalDarkMode();
+  return <Pressable onPress={toggleGlobalDarkMode}><Text>{isDark ? 'Dark' : 'Light'}</Text></Pressable>;
+}
+```
+
+Or the optional `<ThemeProvider>` / `useTheme()` pair, reading and writing
+the exact same global store:
+
+```tsx
+import { ThemeProvider, useTheme } from '@kbach/react-native';
+
+function Toggle() {
+  const { mode, isDark, setMode, toggle } = useTheme();
+  return <Pressable onPress={toggle}><Text>{mode}</Text></Pressable>;
+}
+
+<ThemeProvider defaultMode="system">
+  <Toggle />
+</ThemeProvider>;
+```
+
+By default the mode follows the OS `Appearance` setting live until you
+explicitly override it — and **isn't persisted across app launches**.
+There's no React-Native-builtin equivalent of `localStorage`, and adding
+one would mean forcing a real native dependency (e.g.
+`@react-native-async-storage/async-storage`) on every consumer, even ones
+that don't want it. If you want persistence, read your own storage at
+startup and call `setGlobalThemeMode()` with the result before your first
+render — the same "seed once" shape `<ThemeProvider defaultMode>` itself
+uses internally.
+
+## License
+
+MIT

package/dist/chunk-SVMYVXY6.mjs

@@ -0,0 +1,44 @@
+import {
+  resolveStyle
+} from "./chunk-YHF3QLRL.mjs";
+
+// src/jsx-runtime.tsx
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment } from "react";
+import { Pressable } from "react-native";
+function makeElement(isStaticChildren, type, props, key) {
+  return (isStaticChildren ? _jsxs : _jsx)(type, props, key);
+}
+function resolvedStyleFor(classStrRaw, userStyle, pressed) {
+  const resolved = resolveStyle(classStrRaw, pressed);
+  if (userStyle === void 0) {
+    return resolved;
+  }
+  if (typeof userStyle === "function") {
+    return [resolved, userStyle({ pressed })];
+  }
+  return [resolved, userStyle];
+}
+function processElement(type, rawProps, key, isStaticChildren) {
+  if (type === null || typeof type === "symbol" || !rawProps) {
+    return makeElement(isStaticChildren, type, rawProps ?? {}, key);
+  }
+  const { className: classStrRaw, style: userStyle, ...rest } = rawProps;
+  if (typeof classStrRaw !== "string") {
+    return makeElement(isStaticChildren, type, rawProps, key);
+  }
+  const finalStyle = type === Pressable ? (state) => resolvedStyleFor(classStrRaw, userStyle, state.pressed) : resolvedStyleFor(classStrRaw, userStyle, false);
+  return makeElement(isStaticChildren, type, { ...rest, style: finalStyle }, key);
+}
+function jsx(type, props, key) {
+  return processElement(type, props, key, false);
+}
+function jsxs(type, props, key) {
+  return processElement(type, props, key, true);
+}
+
+export {
+  Fragment,
+  jsx,
+  jsxs
+};

package/dist/chunk-YHF3QLRL.mjs

@@ -0,0 +1,374 @@
+// src/generatedPalette.ts
+var PALETTE = {
+  "amber-1": "#fffbeb",
+  "amber-10": "#78350f",
+  "amber-11": "#451a03",
+  "amber-12": "#291002",
+  "amber-2": "#fef3c7",
+  "amber-3": "#fde68a",
+  "amber-4": "#fcd34d",
+  "amber-5": "#fbbf24",
+  "amber-6": "#f59e0b",
+  "amber-7": "#d97706",
+  "amber-8": "#b45309",
+  "amber-9": "#92400e",
+  "black": "#000000",
+  "blue-1": "#eff6ff",
+  "blue-10": "#1e3a8a",
+  "blue-11": "#172554",
+  "blue-12": "#0d1633",
+  "blue-2": "#dbeafe",
+  "blue-3": "#bfdbfe",
+  "blue-4": "#93c5fd",
+  "blue-5": "#60a5fa",
+  "blue-6": "#3b82f6",
+  "blue-7": "#2563eb",
+  "blue-8": "#1d4ed8",
+  "blue-9": "#1e40af",
+  "bronze": "#cd7f32",
+  "coal": "#1c1c1c",
+  "copper": "#b87333",
+  "current": "currentColor",
+  "cyan-1": "#ecfeff",
+  "cyan-10": "#164e63",
+  "cyan-11": "#083344",
+  "cyan-12": "#041e28",
+  "cyan-2": "#cffafe",
+  "cyan-3": "#a5f3fc",
+  "cyan-4": "#67e8f9",
+  "cyan-5": "#22d3ee",
+  "cyan-6": "#06b6d4",
+  "cyan-7": "#0891b2",
+  "cyan-8": "#0e7490",
+  "cyan-9": "#155e75",
+  "emerald-1": "#ecfdf5",
+  "emerald-10": "#064e3b",
+  "emerald-11": "#022c22",
+  "emerald-12": "#011a14",
+  "emerald-2": "#d1fae5",
+  "emerald-3": "#a7f3d0",
+  "emerald-4": "#6ee7b7",
+  "emerald-5": "#34d399",
+  "emerald-6": "#10b981",
+  "emerald-7": "#059669",
+  "emerald-8": "#047857",
+  "emerald-9": "#065f46",
+  "fuchsia-1": "#fdf4ff",
+  "fuchsia-10": "#701a75",
+  "fuchsia-11": "#4a044e",
+  "fuchsia-12": "#2d022f",
+  "fuchsia-2": "#fae8ff",
+  "fuchsia-3": "#f5d0fe",
+  "fuchsia-4": "#f0abfc",
+  "fuchsia-5": "#e879f9",
+  "fuchsia-6": "#d946ef",
+  "fuchsia-7": "#c026d3",
+  "fuchsia-8": "#a21caf",
+  "fuchsia-9": "#86198f",
+  "gold": "#d4af37",
+  "gray-1": "#f9fafb",
+  "gray-10": "#111827",
+  "gray-11": "#030712",
+  "gray-12": "#020409",
+  "gray-2": "#f3f4f6",
+  "gray-3": "#e5e7eb",
+  "gray-4": "#d1d5db",
+  "gray-5": "#9ca3af",
+  "gray-6": "#6b7280",
+  "gray-7": "#4b5563",
+  "gray-8": "#374151",
+  "gray-9": "#1f2937",
+  "green-1": "#f0fdf4",
+  "green-10": "#14532d",
+  "green-11": "#052e16",
+  "green-12": "#031b0d",
+  "green-2": "#dcfce7",
+  "green-3": "#bbf7d0",
+  "green-4": "#86efac",
+  "green-5": "#4ade80",
+  "green-6": "#22c55e",
+  "green-7": "#16a34a",
+  "green-8": "#15803d",
+  "green-9": "#166534",
+  "indigo-1": "#eef2ff",
+  "indigo-10": "#312e81",
+  "indigo-11": "#1e1b4b",
+  "indigo-12": "#12102d",
+  "indigo-2": "#e0e7ff",
+  "indigo-3": "#c7d2fe",
+  "indigo-4": "#a5b4fc",
+  "indigo-5": "#818cf8",
+  "indigo-6": "#6366f1",
+  "indigo-7": "#4f46e5",
+  "indigo-8": "#4338ca",
+  "indigo-9": "#3730a3",
+  "lime-1": "#f7fee7",
+  "lime-10": "#365314",
+  "lime-11": "#1a2e05",
+  "lime-12": "#0f1b03",
+  "lime-2": "#ecfccb",
+  "lime-3": "#d9f99d",
+  "lime-4": "#bef264",
+  "lime-5": "#a3e635",
+  "lime-6": "#84cc16",
+  "lime-7": "#65a30d",
+  "lime-8": "#4d7c0f",
+  "lime-9": "#3f6212",
+  "neutral-1": "#fafafa",
+  "neutral-10": "#171717",
+  "neutral-11": "#0a0a0a",
+  "neutral-12": "#050505",
+  "neutral-2": "#f5f5f5",
+  "neutral-3": "#e5e5e5",
+  "neutral-4": "#d4d4d4",
+  "neutral-5": "#a3a3a3",
+  "neutral-6": "#737373",
+  "neutral-7": "#525252",
+  "neutral-8": "#404040",
+  "neutral-9": "#262626",
+  "orange-1": "#fff7ed",
+  "orange-10": "#7c2d12",
+  "orange-11": "#431407",
+  "orange-12": "#270c04",
+  "orange-2": "#ffedd5",
+  "orange-3": "#fed7aa",
+  "orange-4": "#fdba74",
+  "orange-5": "#fb923c",
+  "orange-6": "#f97316",
+  "orange-7": "#ea580c",
+  "orange-8": "#c2410c",
+  "orange-9": "#9a3412",
+  "pink-1": "#fdf2f8",
+  "pink-10": "#831843",
+  "pink-11": "#500724",
+  "pink-12": "#300415",
+  "pink-2": "#fce7f3",
+  "pink-3": "#fbcfe8",
+  "pink-4": "#f9a8d4",
+  "pink-5": "#f472b6",
+  "pink-6": "#ec4899",
+  "pink-7": "#db2777",
+  "pink-8": "#be185d",
+  "pink-9": "#9d174d",
+  "purple-1": "#faf5ff",
+  "purple-10": "#581c87",
+  "purple-11": "#3b0764",
+  "purple-12": "#23043c",
+  "purple-2": "#f3e8ff",
+  "purple-3": "#e9d5ff",
+  "purple-4": "#d8b4fe",
+  "purple-5": "#c084fc",
+  "purple-6": "#a855f7",
+  "purple-7": "#9333ea",
+  "purple-8": "#7e22ce",
+  "purple-9": "#6b21a8",
+  "red-1": "#fef2f2",
+  "red-10": "#7f1d1d",
+  "red-11": "#450a0a",
+  "red-12": "#280606",
+  "red-2": "#fee2e2",
+  "red-3": "#fecaca",
+  "red-4": "#fca5a5",
+  "red-5": "#f87171",
+  "red-6": "#ef4444",
+  "red-7": "#dc2626",
+  "red-8": "#b91c1c",
+  "red-9": "#991b1b",
+  "rose-1": "#fff1f2",
+  "rose-10": "#881337",
+  "rose-11": "#4c0519",
+  "rose-12": "#2d030e",
+  "rose-2": "#ffe4e6",
+  "rose-3": "#fecdd3",
+  "rose-4": "#fda4af",
+  "rose-5": "#fb7185",
+  "rose-6": "#f43f5e",
+  "rose-7": "#e11d48",
+  "rose-8": "#be123c",
+  "rose-9": "#9f1239",
+  "silver": "#c0c0c0",
+  "sky-1": "#f0f9ff",
+  "sky-10": "#0c4a6e",
+  "sky-11": "#082f49",
+  "sky-12": "#041b2b",
+  "sky-2": "#e0f2fe",
+  "sky-3": "#bae6fd",
+  "sky-4": "#7dd3fc",
+  "sky-5": "#38bdf8",
+  "sky-6": "#0ea5e9",
+  "sky-7": "#0284c7",
+  "sky-8": "#0369a1",
+  "sky-9": "#075985",
+  "slate-1": "#f8fafc",
+  "slate-10": "#0f172a",
+  "slate-11": "#020617",
+  "slate-12": "#01020a",
+  "slate-2": "#f1f5f9",
+  "slate-3": "#e2e8f0",
+  "slate-4": "#cbd5e1",
+  "slate-5": "#94a3b8",
+  "slate-6": "#64748b",
+  "slate-7": "#475569",
+  "slate-8": "#334155",
+  "slate-9": "#1e293b",
+  "stone-1": "#fafaf9",
+  "stone-10": "#1c1917",
+  "stone-11": "#0c0a09",
+  "stone-12": "#070605",
+  "stone-2": "#f5f5f4",
+  "stone-3": "#e7e5e4",
+  "stone-4": "#d6d3d1",
+  "stone-5": "#a8a29e",
+  "stone-6": "#78716c",
+  "stone-7": "#57534e",
+  "stone-8": "#44403c",
+  "stone-9": "#292524",
+  "teal-1": "#f0fdfa",
+  "teal-10": "#134e4a",
+  "teal-11": "#042f2e",
+  "teal-12": "#021c1b",
+  "teal-2": "#ccfbf1",
+  "teal-3": "#99f6e4",
+  "teal-4": "#5eead4",
+  "teal-5": "#2dd4bf",
+  "teal-6": "#14b8a6",
+  "teal-7": "#0d9488",
+  "teal-8": "#0f766e",
+  "teal-9": "#115e59",
+  "transparent": "transparent",
+  "violet-1": "#f5f3ff",
+  "violet-10": "#4c1d95",
+  "violet-11": "#2e1065",
+  "violet-12": "#1c0a3d",
+  "violet-2": "#ede9fe",
+  "violet-3": "#ddd6fe",
+  "violet-4": "#c4b5fd",
+  "violet-5": "#a78bfa",
+  "violet-6": "#8b5cf6",
+  "violet-7": "#7c3aed",
+  "violet-8": "#6d28d9",
+  "violet-9": "#5b21b6",
+  "white": "#ffffff",
+  "yellow-1": "#fefce8",
+  "yellow-10": "#713f12",
+  "yellow-11": "#422006",
+  "yellow-12": "#271304",
+  "yellow-2": "#fef9c3",
+  "yellow-3": "#fef08a",
+  "yellow-4": "#fde047",
+  "yellow-5": "#facc15",
+  "yellow-6": "#eab308",
+  "yellow-7": "#ca8a04",
+  "yellow-8": "#a16207",
+  "yellow-9": "#854d0e",
+  "zinc-1": "#fafafa",
+  "zinc-10": "#18181b",
+  "zinc-11": "#09090b",
+  "zinc-12": "#050506",
+  "zinc-2": "#f4f4f5",
+  "zinc-3": "#e4e4e7",
+  "zinc-4": "#d4d4d8",
+  "zinc-5": "#a1a1aa",
+  "zinc-6": "#71717a",
+  "zinc-7": "#52525b",
+  "zinc-8": "#3f3f46",
+  "zinc-9": "#27272a"
+};
+
+// src/theme.ts
+var defaultTheme = {
+  colors: PALETTE,
+  spacing: {
+    // "0" is always a hardcoded zero in real Tailwind's own scale too,
+    // regardless of the base spacing unit — needed for `p-0`/`m-0`/etc.
+    // Mirrors the identical fix in @kbach/react's theme.ts.
+    "0": 0,
+    "1": 4,
+    "2": 8,
+    "4": 16,
+    "6": 24,
+    "8": 32
+  },
+  screens: {},
+  darkMode: "attribute"
+};
+var activeTheme = defaultTheme;
+var activeThemeJson = JSON.stringify(defaultTheme);
+function setTheme(theme) {
+  activeTheme = theme;
+  activeThemeJson = JSON.stringify(theme);
+}
+function getTheme() {
+  return activeTheme;
+}
+function getThemeJson() {
+  return activeThemeJson;
+}
+
+// src/darkModeStore.ts
+import { Appearance } from "react-native";
+var listeners = /* @__PURE__ */ new Set();
+function systemPrefersDark() {
+  return Appearance.getColorScheme() === "dark";
+}
+function resolveIsDark(m) {
+  return m === "system" ? systemPrefersDark() : m === "dark";
+}
+var mode = "system";
+var isDark = resolveIsDark(mode);
+var hasExplicitChoice = false;
+var subscription = Appearance.addChangeListener(({ colorScheme }) => {
+  if (mode !== "system") return;
+  isDark = colorScheme === "dark";
+  notify();
+});
+function notify() {
+  for (const listener of listeners) listener();
+}
+function getGlobalDarkMode() {
+  return isDark;
+}
+function getGlobalThemeMode() {
+  return mode;
+}
+function setGlobalThemeMode(nextMode) {
+  mode = nextMode;
+  isDark = resolveIsDark(nextMode);
+  hasExplicitChoice = true;
+  notify();
+}
+function toggleGlobalDarkMode() {
+  setGlobalThemeMode(isDark ? "light" : "dark");
+}
+function subscribeGlobalDarkMode(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+function seedDefaultMode(fallback) {
+  if (hasExplicitChoice || mode === fallback) return;
+  mode = fallback;
+  isDark = resolveIsDark(fallback);
+  notify();
+}
+
+// src/nativeBridge.ts
+import { TurboModuleRegistry } from "react-native";
+function resolveStyle(classString, pressed = false) {
+  const KbachModule = TurboModuleRegistry.getEnforcing("KbachModule");
+  const colorScheme = getGlobalDarkMode() ? "dark" : "light";
+  const json = KbachModule.resolveStyle(classString, getThemeJson(), colorScheme, pressed);
+  return JSON.parse(json);
+}
+
+export {
+  defaultTheme,
+  setTheme,
+  getTheme,
+  getGlobalDarkMode,
+  getGlobalThemeMode,
+  setGlobalThemeMode,
+  toggleGlobalDarkMode,
+  subscribeGlobalDarkMode,
+  seedDefaultMode,
+  resolveStyle
+};

package/dist/index.d.mts

@@ -0,0 +1,148 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface ThemeConfig {
+    /** Plain hex only, this pass — e.g. "blue-6" -> "#2563eb" */
+    colors: Record<string, string>;
+    spacing: Record<string, number>;
+    screens: Record<string, number>;
+    darkMode: 'attribute' | 'class' | 'media';
+}
+declare const defaultTheme: ThemeConfig;
+declare function setTheme(theme: ThemeConfig): void;
+declare function getTheme(): ThemeConfig;
+
+interface StyleObject {
+    [key: string]: string | number;
+}
+/**
+ * Calls the Rust engine via the KbachModule TurboModule (see
+ * apps/native-sandbox/android/.../KbachModule.kt and
+ * packages/core-engine/src/resolve_style.rs) and returns a plain style
+ * object ready for RN's `style` prop. Synchronous — no async init step,
+ * unlike the web/WASM path, since JSI-backed TurboModule methods are
+ * available as soon as the module is loaded.
+ *
+ * Reads `getGlobalDarkMode()` (darkModeStore.ts) fresh on every call (no
+ * caching) so `dark:` resolves correctly whenever this runs. That store —
+ * not a direct `Appearance.getColorScheme()` read, which this function
+ * used prior to `<ThemeProvider>` support — is what makes an explicit
+ * `setGlobalThemeMode('dark')`/`toggle()` override actually affect
+ * rendering; the store itself falls back to tracking `Appearance` live
+ * whenever the mode is `'system'` (its own default), so nothing regresses
+ * for apps that never touch the override API at all. This function itself
+ * has no subscription of its own, so nothing re-renders just because the
+ * store's value changed — call `useGlobalDarkMode()` (or consume
+ * `useTheme()`'s `isDark`) somewhere in the tree for that, NOT React
+ * Native's own `useColorScheme()`, which only reflects the raw OS setting
+ * and would miss an explicit override entirely.
+ *
+ * Phase 11 originally shipped with live in-place theme switching unverified
+ * (a `uiMode` toggle triggered a re-render but `Appearance.getColorScheme()`
+ * kept returning a stale value). Root-caused in Phase 12 while debugging an
+ * unrelated `active:` failure: `apps/native-sandbox` has its own separate
+ * `node_modules/react-native` (excluded from the npm workspace since Phase
+ * 5), while `packages/react-native` resolved `react-native` hierarchically
+ * up to a *different* copy at the repo root — two physical module
+ * instances, so a `useColorScheme()` subscription and an
+ * `Appearance.getColorScheme()` read were silently talking to two separate
+ * copies of the Appearance module. Fixed by forcing a single instance via
+ * `resolver.resolveRequest` in apps/native-sandbox/metro.config.js; live
+ * theme switching (and `active:`, the bug that surfaced this) both verified
+ * working after the fix — see Phase 12. Still relevant here: darkModeStore.ts
+ * itself calls `Appearance.addChangeListener`, so the same dual-instance
+ * failure mode would silently break the 'system' fallback path too if that
+ * metro.config.js fix ever regressed.
+ *
+ * `pressed` gates the `active:` modifier — unlike `colorScheme`, there's no
+ * system-level getter for "is this element currently pressed"; only RN's
+ * `Pressable` ever knows this, so it's passed in directly by the caller
+ * (jsx-runtime, from Pressable's own style-function callback) rather than
+ * queried here. Defaults to `false` for every other element type.
+ */
+declare function resolveStyle(classString: string, pressed?: boolean): StyleObject;
+
+/**
+ * Native port of @kbach/react's darkModeStore.ts — same architecture (a
+ * single module-level store is the real source of truth;
+ * ThemeProvider/useTheme are a thin, OPTIONAL wrapper around it; every
+ * function here works standalone with no provider mounted anywhere), with
+ * two real platform differences from the web version:
+ *
+ * 1. No persistence. There's no React-Native-builtin equivalent of
+ *    localStorage — adding one would mean forcing a real native dependency
+ *    (e.g. @react-native-async-storage/async-storage) on every consumer,
+ *    even ones that don't want it. The mode always starts at 'system' on a
+ *    fresh app launch. If you want persistence, read your own storage at
+ *    startup (before your first render) and call setGlobalThemeMode() with
+ *    the result — same "seed once, no built-in write-back" shape as
+ *    seedDefaultMode() below, just driven by your own storage instead of
+ *    one this package picks for you.
+ * 2. No DOM to "apply" the resolved mode to. On web, applyToDom() flips a
+ *    class/attribute the generated CSS's `dark:` selectors match against.
+ *    On native there's no CSS at all — nativeBridge.ts's resolveStyle()
+ *    reads getGlobalDarkMode() directly on every call instead of querying
+ *    Appearance.getColorScheme() itself, which is what actually makes an
+ *    explicit override affect rendering (previously that function always
+ *    read the raw OS setting, so it had no way to reflect a user choice —
+ *    see nativeBridge.ts's own comment on this for why that's the one
+ *    genuinely fixed bug this change introduces, not just a new feature).
+ */
+type ThemeMode = 'light' | 'dark' | 'system';
+declare function getGlobalDarkMode(): boolean;
+declare function getGlobalThemeMode(): ThemeMode;
+/** Explicit user choice — takes priority over any later `<ThemeProvider defaultMode>` seed (see `seedDefaultMode` below). Not persisted; see this module's own doc comment. */
+declare function setGlobalThemeMode(nextMode: ThemeMode): void;
+declare function toggleGlobalDarkMode(): void;
+declare function subscribeGlobalDarkMode(listener: () => void): () => 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. No server-snapshot argument (unlike
+ * @kbach/react's web version) — React Native has no SSR concept at all,
+ * so there's no third argument for `useSyncExternalStore` to need.
+ */
+declare function useGlobalDarkMode(): boolean;
+
+interface ThemeProviderProps {
+    children: ReactNode;
+    /**
+     * Applied once, on this provider's first mount, but ONLY if nothing has
+     * made an explicit mode choice yet (see
+     * `darkModeStore.ts::seedDefaultMode`) — an explicit prior choice always
+     * wins over a component's own default. Unlike @kbach/react's web
+     * version, there's no persisted value to check here — see
+     * darkModeStore.ts's own doc comment on why this package doesn't persist
+     * the mode across app launches.
+     */
+    defaultMode?: ThemeMode;
+}
+/**
+ * Native port of @kbach/react's `ThemeProvider` — a thin, OPTIONAL React
+ * Context wrapper around `darkModeStore.ts`'s single global store, not the
+ * source of truth itself. 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 the web version's
+ * identical guard.
+ */
+declare function ThemeProvider({ children, defaultMode }: ThemeProviderProps): react.JSX.Element;
+
+interface ThemeContextValue {
+    mode: ThemeMode;
+    isDark: boolean;
+    setMode: (mode: ThemeMode) => void;
+    toggle: () => void;
+}
+/**
+ * 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).
+ */
+declare function useTheme(): ThemeContextValue;
+
+export { type StyleObject, type ThemeConfig, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, defaultTheme, getGlobalDarkMode, getGlobalThemeMode, getTheme, resolveStyle, setGlobalThemeMode, setTheme, subscribeGlobalDarkMode, toggleGlobalDarkMode, useGlobalDarkMode, useTheme };