@kbach/react 0.6.51 → 1.0.0-beta.1

package/dist/chunk-FOQWQDF4.mjs

@@ -0,0 +1,446 @@
+// 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,
+    surface: { light: "#f9fafb", dark: "#111827" }
+  },
+  // 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.
+  spacing: {
+    "0": 0,
+    "px": 1,
+    "0.5": 2,
+    "1": 4,
+    "1.5": 6,
+    "2": 8,
+    "2.5": 10,
+    "3": 12,
+    "3.5": 14,
+    "4": 16,
+    "5": 20,
+    "6": 24,
+    "7": 28,
+    "8": 32,
+    "9": 36,
+    "10": 40,
+    "11": 44,
+    "12": 48,
+    "14": 56,
+    "16": 64,
+    "20": 80,
+    "24": 96,
+    "28": 112,
+    "32": 128,
+    "36": 144,
+    "40": 160,
+    "44": 176,
+    "48": 192,
+    "52": 208,
+    "56": 224,
+    "60": 240,
+    "64": 256,
+    "72": 288,
+    "80": 320,
+    "96": 384
+  },
+  screens: {
+    sm: 640,
+    md: 768,
+    lg: 1024,
+    xl: 1280,
+    "2xl": 1536
+  },
+  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/reset.ts
+var RESET_STYLE_ID = "kbach-reset";
+var RESET_RULES = [
+  // border-style: solid means border-N utilities show a visible border without an extra border-solid class.
+  // border-width: 0 keeps all elements borderless by default.
+  { css: "*, *::before, *::after { box-sizing: border-box; border-width: 0; border-style: solid; border-color: currentColor; }" },
+  { css: "body { margin: 0; padding: 0; }" },
+  { css: "h1, h2, h3, h4, h5, h6 { margin: 0; font-size: inherit; font-weight: inherit; }", tags: ["h1", "h2", "h3", "h4", "h5", "h6"] },
+  { css: "p { margin: 0; }", tags: ["p"] },
+  { css: "a { color: inherit; text-decoration: none; }", tags: ["a"] },
+  { css: "ul, ol { margin: 0; padding: 0; list-style: none; }", tags: ["ul", "ol"] },
+  // svg here only covers a literal <svg> tag in JSX — an icon imported as
+  // a component (e.g. `<ArrowIcon />`) never appears as the text "svg" in
+  // source, so this rule won't be pulled in by that usage alone. Same
+  // caveat applies to every tag-gated rule below: detection is a literal
+  // source-text scan (see vite-plugin/scan.ts's scanUsedTags), not a real
+  // DOM/type check.
+  { css: "img, video, svg { display: block; max-width: 100%; }", tags: ["img", "video", "svg"] },
+  // appearance: none is deliberately NOT applied to checkbox/radio/select below —
+  // stripping it hides their native checkmark/arrow with nothing rendered in its
+  // place, leaving an invisible checkbox or an arrow-less <select> that looks like
+  // plain text. Text-like inputs, textarea, and button don't have that problem
+  // (their native chrome is just a skin around content utilities can fully
+  // restyle), so they keep the blank-canvas treatment.
+  // :where() wraps the :not() exclusions so they contribute ZERO specificity
+  // (unlike a bare `input:not([type='checkbox']):not([type='radio'])`, whose
+  // two :not([attr]) clauses each add a class-level specificity point — (0,2,1)
+  // total, MORE than any single utility class (0,1,0)). Without :where(), this
+  // reset's `color: inherit` always won the cascade over a text-* color
+  // utility applied directly to a <input>/<textarea> regardless of source
+  // order, since author rules only override on a tie or higher specificity —
+  // confirmed on a real app: a TextInput's own text color utility resolved
+  // and injected correctly, class and all, but silently never painted.
+  {
+    css: "input:where(:not([type='checkbox']):not([type='radio'])), textarea { appearance: none; -webkit-appearance: none; background: transparent; padding: 0; margin: 0; font: inherit; color: inherit; line-height: inherit; }",
+    tags: ["input", "textarea"]
+  },
+  // Native checkbox/radio/range still get typography + spacing normalized, and
+  // accent-color re-themes their native indicator to the current text color
+  // instead of the browser/OS default blue, so they stay on-brand without
+  // needing to be rebuilt from scratch. Wrapped in :where() for the exact
+  // same reason as the input:not(...) exclusions above — a bare
+  // `input[type='range']` attribute selector has specificity (0,1,1),
+  // MORE than any single utility class (0,1,0), so an `accent-*` utility
+  // (Phase 23) applied directly to a checkbox/radio/range would resolve and
+  // inject correctly but silently never paint, losing the cascade to this
+  // reset regardless of source order — confirmed by hand via
+  // getComputedStyle on a real `accent-red-6` range input, which reported
+  // `currentColor`'s inherited value instead. `:where()` zeroes this
+  // selector's specificity contribution entirely, so any `accent-*`
+  // utility trivially wins once applied.
+  {
+    css: ":where(input[type='checkbox'], input[type='radio'], input[type='range']) { margin: 0; font: inherit; accent-color: currentColor; }",
+    tags: ["input"]
+  },
+  // select keeps its native chrome (border/background/arrow are all part of the
+  // same OS-drawn widget that appearance: none would blank out) — only typography
+  // and spacing are normalized so it still matches surrounding text.
+  { css: "select { margin: 0; font: inherit; color: inherit; line-height: inherit; }", tags: ["select"] },
+  { css: "button { appearance: none; -webkit-appearance: none; background: transparent; padding: 0; margin: 0; font: inherit; color: inherit; cursor: pointer; line-height: inherit; text-align: inherit; }", tags: ["button"] },
+  // Also covers any element opted into the button role (`role="button"` on
+  // a <div>/<span>) — but only when a literal <button> tag is ALSO
+  // somewhere in the scanned source, since detection here is purely
+  // tag-name-based; a project using role="button" exclusively, with no
+  // real <button> anywhere, won't pull this rule in. Acceptable tradeoff
+  // for this project's scope (rare pattern) — cheap enough that scanning
+  // for it separately isn't worth the added complexity.
+  { css: "button, [role='button'] { cursor: pointer; }", tags: ["button"] },
+  { css: ":disabled { cursor: default; }", tags: ["button", "input", "select", "textarea"] },
+  { css: "textarea { resize: vertical; }", tags: ["textarea"] },
+  // Firefox renders placeholders at ~54% opacity by default; every other browser uses 1 —
+  // normalize to 1 so placeholder color is consistent and fully controlled by the placeholder: modifier.
+  { css: "::placeholder { opacity: 1; }", tags: ["input", "textarea"] },
+  { css: "input[type='number']::-webkit-inner-spin-button, input[type='number']::-webkit-outer-spin-button { margin: 0; }", tags: ["input"] },
+  { css: "input[type='search']::-webkit-search-decoration, input[type='search']::-webkit-search-cancel-button { -webkit-appearance: none; }", tags: ["input"] },
+  { css: "fieldset { padding: 0; margin: 0; }", tags: ["fieldset"] },
+  { css: "table { border-collapse: collapse; border-spacing: 0; }", tags: ["table"] }
+];
+var BASE_RESET = RESET_RULES.map((r) => r.css).join("\n");
+function buildResetCSS(usedTags) {
+  if (!usedTags) return BASE_RESET;
+  return RESET_RULES.filter((r) => !r.tags || r.tags.some((t) => usedTags.has(t))).map((r) => r.css).join("\n");
+}
+
+export {
+  defaultTheme,
+  setTheme,
+  getTheme,
+  getThemeJson,
+  RESET_STYLE_ID,
+  BASE_RESET,
+  buildResetCSS
+};

package/dist/chunk-ROZXCQSM.mjs

@@ -0,0 +1,100 @@
+import {
+  BASE_RESET,
+  RESET_STYLE_ID,
+  getThemeJson
+} from "./chunk-FOQWQDF4.mjs";
+
+// src/wasmLoader.ts
+import init, { generate_css as wasmGenerateCss } from "@kbach/core-engine";
+var readyPromise = null;
+var ready = false;
+function initKbach() {
+  if (!readyPromise) {
+    readyPromise = init().then(() => {
+      ready = true;
+    });
+  }
+  return readyPromise;
+}
+function isKbachReady() {
+  return ready;
+}
+function generateCss(classString, themeJson) {
+  if (!ready) {
+    throw new Error(
+      "[kbach] generateCss() was called before initKbach() resolved. Call `await initKbach()` once at startup (e.g. before rendering your app) before using kb()."
+    );
+  }
+  return wasmGenerateCss(classString, themeJson);
+}
+
+// src/kb.ts
+var runtimeCSSDisabled = false;
+function disableRuntimeCSS() {
+  runtimeCSSDisabled = true;
+}
+function isRuntimeCSSDisabled() {
+  return runtimeCSSDisabled;
+}
+var styleEl = null;
+var sheetKeys = [];
+var ruleOrderByKey = /* @__PURE__ */ new Map();
+function getStyleEl() {
+  if (styleEl) return styleEl;
+  styleEl = document.createElement("style");
+  styleEl.setAttribute("data-kbach", "");
+  document.head.appendChild(styleEl);
+  return styleEl;
+}
+function findInsertionIndex(order) {
+  let lo = 0;
+  let hi = sheetKeys.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (ruleOrderByKey.get(sheetKeys[mid]) > order) hi = mid;
+    else lo = mid + 1;
+  }
+  return lo;
+}
+function injectRule(rule, order) {
+  if (ruleOrderByKey.has(rule)) return;
+  const sheet = getStyleEl().sheet;
+  if (!sheet) return;
+  const idx = findInsertionIndex(order);
+  try {
+    sheet.insertRule(rule, idx);
+  } catch {
+    return;
+  }
+  sheetKeys.splice(idx, 0, rule);
+  ruleOrderByKey.set(rule, order);
+}
+var resetChecked = false;
+function ensureResetInjected() {
+  if (resetChecked) return;
+  resetChecked = true;
+  if (document.getElementById(RESET_STYLE_ID)) return;
+  const el = document.createElement("style");
+  el.id = RESET_STYLE_ID;
+  el.textContent = BASE_RESET;
+  document.head.insertBefore(el, document.head.firstChild);
+}
+function kb(classString) {
+  const json = generateCss(classString, getThemeJson());
+  const { className, rules } = JSON.parse(json);
+  if (!runtimeCSSDisabled) {
+    ensureResetInjected();
+    for (const { rule, order } of rules) {
+      injectRule(rule, order);
+    }
+  }
+  return className;
+}
+
+export {
+  initKbach,
+  isKbachReady,
+  disableRuntimeCSS,
+  isRuntimeCSSDisabled,
+  kb
+};

package/dist/index.d.mts

@@ -0,0 +1,117 @@
+export { T as ThemeConfig, d as defaultTheme, g as getTheme, s as setTheme } from './theme-BKAb78KP.mjs';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Loads and instantiates the Rust/WASM core engine. Call once at startup
+ * (e.g. before `ReactDOM.createRoot(...).render(...)`) and await it — every
+ * subsequent call returns the same memoized promise, so it's safe to call
+ * again from multiple entry points.
+ */
+declare function initKbach(): Promise<void>;
+declare function isKbachReady(): boolean;
+
+declare function disableRuntimeCSS(): void;
+declare function isRuntimeCSSDisabled(): boolean;
+/**
+ * Resolves a Kbach class string via the Rust/WASM engine, cascade-order-safe
+ * injects the resulting CSS rules into a single `<style data-kbach>` tag,
+ * and returns the class string unchanged for use as `className`.
+ *
+ * Must be called after `await initKbach()` resolves — see wasmLoader.ts.
+ */
+declare function kb(classString: string): string;
+
+/**
+ * Renders Kbach's base browser-default reset (borderless button/input,
+ * visible checkbox/radio, no arrow-less <select>, etc.) as a plain <style>
+ * tag so it's part of the page's initial HTML.
+ *
+ * Runtime-only setups (no Vite plugin / static kbach.css) otherwise only get
+ * this reset once kb()'s first call injects it — fine for a plain CSR app,
+ * but under SSR the server has no JS to run it, so the first paint ships
+ * with raw browser defaults (e.g. the native button border) until
+ * hydration catches up. Render this once, as high in <head> as your
+ * framework allows, to close that gap.
+ *
+ * Skips rendering entirely once disableRuntimeCSS() has fired — the Vite
+ * plugin calls it automatically wherever kbach.css gets imported (see
+ * vite-plugin/format.ts's own BASE_RESET inlining), and that static file
+ * already has this exact reset. No isNative check (unlike old-kbach's
+ * version of this component): @kbach/react is a web-only package now, so
+ * there's no cross-platform import path for this component to guard against.
+ */
+declare function KbachReset(): react.JSX.Element | null;
+
+/**
+ * Port of old-kbach's dark-mode architecture (`packages/ui/src/core/
+ * darkModeStore.ts` + `ThemeProvider.tsx`), simplified for this package's
+ * web-only scope: a single module-level store is the actual source of
+ * truth, and `<ThemeProvider>`/`useTheme()` (see `ThemeProvider.tsx`) are a
+ * thin, OPTIONAL React wrapper around it — every function here works
+ * standalone, with no provider mounted anywhere, which is the whole point:
+ * a plain script, an event handler, or a component that never wants
+ * Context can call `toggleGlobalDarkMode()` directly.
+ */
+type ThemeMode = 'light' | 'dark' | 'system';
+declare function getGlobalDarkMode(): boolean;
+declare function getGlobalThemeMode(): ThemeMode;
+/** Explicit user choice — persisted, and takes priority over any later `<ThemeProvider defaultMode>` seed (see `seedDefaultMode` below). */
+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. `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.
+ */
+declare function useGlobalDarkMode(): boolean;
+
+interface ThemeProviderProps {
+    children: ReactNode;
+    /**
+     * Applied once, on this provider's first mount, but ONLY if the user has
+     * no persisted preference already (see `darkModeStore.ts::seedDefaultMode`)
+     * — an explicit prior choice always wins over a component's own default.
+     */
+    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).
+ *
+ * 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.
+ */
+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 { KbachReset, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, disableRuntimeCSS, getGlobalDarkMode, getGlobalThemeMode, initKbach, isKbachReady, isRuntimeCSSDisabled, kb, setGlobalThemeMode, subscribeGlobalDarkMode, toggleGlobalDarkMode, useGlobalDarkMode, useTheme };