@kbach/react-native 1.0.0-beta.4 → 1.0.0-beta.40

package/dist/clsx-BLLSnqAa.d.ts

@@ -0,0 +1,277 @@
+import { ThemeConfig, ContainerConfig } from './theme';
+import { ThemeMode } from './darkModeStore';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * A `kbach.config.js`-style theme customization — same shape as
+ * @kbach/react's `KbachConfig`, minus @kbach/react's own PER-COLOR
+ * `{ light, dark }` object form in `extend.colors` specifically (real
+ * mode-aware colors here are written via the grouped `dark` key instead —
+ * see `KbachConfig.extend.colors`'s own doc comment below): aliasing/
+ * opacity math on an individual color value here only ever operates on
+ * plain hex (`brand: 'blue-6'`, `brandSoft: 'brand/30'`), matching
+ * `jsEngine/resolvers/color.ts`'s `lookupHex`'s own Plain-only convention
+ * — a reference to an EXISTING color that happens to be mode-aware
+ * (`theme.colors` can hold those, for `useColors()`; see `theme.ts`'s own
+ * `ColorEntry` doc comment) just doesn't resolve as an alias, falling
+ * through to "literal CSS value" the same way an unknown name would. A
+ * config object goes in, a resolved `ThemeConfig` comes out, via one PURE
+ * function (`resolveKbachConfig`) — no plugins, no live-update store,
+ * nothing to keep "in sync."
+ */
+interface KbachConfig {
+    darkMode?: ThemeConfig['darkMode'];
+    /**
+     * REPLACES the named section of `defaultTheme` entirely — use `extend` to
+     * add instead of replace. `container` isn't here (only under `extend`
+     * below) — see @kbach/react's identical `KbachConfig.theme` doc comment
+     * for why.
+     */
+    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 hex color, 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'`), or a
+         * custom color defined EARLIER in this same object (`{ brand:
+         * '#ff6b35', brandSoft: 'brand/30' }` — `brandSoft` resolves to
+         * `brand`'s own value at 30% opacity). A string that doesn't match any
+         * known color name is treated as a literal CSS value instead.
+         *
+         * `dark` is a reserved key, not a color name: a parallel map of
+         * dark-mode overrides for any of the OTHER names in this same object —
+         * `{ surface: 'gray-2', card: 'white', dark: { surface: 'gray-11',
+         * card: 'gray-9' } }` makes `surface`/`card` mode-aware
+         * (`{ light, dark }` entries in the resolved theme), while `brand`
+         * (never mentioned under `dark`) stays a plain, mode-independent
+         * color. A name under `dark` with no matching top-level (light) entry
+         * is skipped — mode-aware colors need both sides written out, and
+         * inventing a "light" value out of nowhere would be worse than just
+         * not creating the entry at all. References inside `dark` resolve
+         * against the built-in palette and OTHER entries within `dark` itself
+         * (not against the light-side custom colors) — the same
+         * "self-contained, ordering-independent-of-the-other-side" resolution
+         * the light side already gets, just mirrored.
+         */
+        colors?: {
+            [colorName: string]: string | Record<string, string> | undefined;
+            dark?: Record<string, 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. Write it as a real web-shaped fallback stack even though this
+         * is the React Native package — native's own resolver strips it down
+         * to a single bare name at resolve time (RN's `fontFamily` prop can't
+         * take a fallback list), so the SAME config still works unmodified on
+         * Expo Web, which needs the full stack.
+         */
+        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. Also re-syncs the DOM (Expo Web only) to the CURRENT
+ * dark-mode state right after `setTheme()` — see
+ * `resyncDomWithActiveTheme`'s own doc comment for why this is required,
+ * not optional.
+ */
+declare function applyKbachConfig(config: KbachConfig): ThemeConfig;
+
+interface ThemeState {
+    mode: ThemeMode;
+    isDark: boolean;
+    setMode: (mode: ThemeMode) => void;
+    toggle: () => void;
+}
+/**
+ * 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. 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 useTheme(): ThemeState;
+
+/**
+ * The exact shape `@react-native-async-storage/async-storage`'s default
+ * export already has — pass it directly as `persist`. Any other async
+ * key-value store (MMKV, SecureStore, a custom backend, ...) works too, as
+ * long as it exposes these two methods with this signature. Kept minimal
+ * on purpose: `ThemeProvider` never imports a storage library itself (see
+ * `darkModeStore.ts`'s own doc comment on why this package forces no real
+ * native dependency on consumers who don't want persistence) — deliberately
+ * NOT a `boolean`-only option that reaches for AsyncStorage internally,
+ * since Metro resolves every `require()`/`import` target at BUNDLE time
+ * regardless of try/catch, so a library-internal "if installed, use it"
+ * check can't actually degrade gracefully when the package is absent — an
+ * injected adapter sidesteps that entirely.
+ */
+interface ThemeStorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+}
+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. If `persist` is also set and a
+     * persisted mode is found, the persisted mode wins over this fallback.
+     */
+    defaultMode?: ThemeMode;
+    /**
+     * Opt-in persistence across app launches — `false` by default (this
+     * package never persists on its own; see `darkModeStore.ts`'s doc
+     * comment). Pass a storage adapter to enable it:
+     * ```tsx
+     * import AsyncStorage from '@react-native-async-storage/async-storage';
+     * <ThemeProvider persist={AsyncStorage}>...
+     * ```
+     * The persisted value (if any) is read once on mount and applied via the
+     * same "don't clobber a real choice already in flight" guard
+     * `seedDefaultMode`/`defaultMode` uses; every later explicit mode change
+     * is written back automatically for as long as this provider stays
+     * mounted.
+     */
+    persist?: ThemeStorageAdapter | false;
+}
+/**
+ * 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 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, persist }: ThemeProviderProps): react.JSX.Element;
+
+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), ... */
+    readonly [name: string]: string | ColorScale;
+} & {
+    /** Applies an opacity (0–100) to any color string this hook can return. */
+    readonly alpha: (color: string, opacity?: number) => string;
+    /**
+     * Same lookup dot/bracket access does (`colors.get('brand')` ===
+     * `colors.brand`), typed as plain `string` instead of `string |
+     * ColorScale` — use this whenever the result goes somewhere that expects
+     * a real `string` (a native style prop, a chart library) and hits a type
+     * error otherwise. The wider union on every OTHER property here isn't a
+     * bug: a flat custom color (`brand`) and a shade-family prefix (`blue`)
+     * are served by the exact same object, and TypeScript has no way to
+     * statically know which one any given key names — `kbach.config.js`'s
+     * colors are plain runtime JS, not a type declaration this package could
+     * inspect ahead of time. A name with no matching theme entry falls back
+     * to the name itself, unresolved — the same "not a known color name ->
+     * literal value" convention `kbach.config.js`'s own color aliasing
+     * already uses (see `config.ts`'s `resolveColorEntry`), never an error.
+     */
+    readonly get: (name: string) => string;
+};
+/**
+ * Resolved theme colors as real values — for anywhere you need an actual
+ * color (a chart library prop, a raw SVG `fill`), not a `className`. Ported
+ * from old-kbach's `useColors()`, 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 —
+ * 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 on this platform specifically.
+ *
+ * ```ts
+ * const colors = useColors();
+ * colors.blue[6];        // "#2563eb" — static, same value in both modes
+ * colors.blue['6/50'];   // same, at 50% opacity
+ * colors.brand;          // resolves per isDark if defined as { light, dark }
+ * colors.get('brand');   // same value as colors.brand, typed as plain `string`
+ * ```
+ */
+declare function useColors(): ColorsAPI;
+
+/**
+ * Reads a dynamic token's CURRENT value reactively — the JS-value
+ * counterpart to using `var(--name)` directly in a `className` (see
+ * `jsxRuntimeCore.ts`'s own `substituteDynamicTokens`/`ReactiveElement` for
+ * how that path stays live). Useful when a component needs the raw value
+ * itself (e.g. to drive an Animated value, or a calculation), not just a
+ * resolved style. Subscribes to the store's shared version counter (same
+ * one every token change bumps — see `dynamicTokens.ts`'s own doc comment
+ * on why there's no per-token subscription), so this re-renders on ANY
+ * token change, then re-reads just the one name it was asked for.
+ */
+declare function useDynamicToken(name: string): string | undefined;
+
+/**
+ * A tiny class-name composer — combine strings, arrays, and objects (with
+ * boolean values) into one space-separated className, skipping anything
+ * falsy. Matches the widely-used `clsx` npm package's public API and
+ * behavior exactly (a from-scratch reimplementation, not a fork or a thin
+ * wrapper around it) — this package ships its own copy so using it adds
+ * zero runtime dependencies, and so it works identically whether or not
+ * `clsx`/`classnames` happens to already be installed.
+ *
+ * Kbach class strings never NEED this — a Kbach `className` is just a
+ * plain string, composable with plain JS (`"bg-" + color + "-6"`,
+ * `[base, active && "opacity-100"].join(" ")`, see this package's own
+ * README) with no special API required. This exists purely as an
+ * ergonomic convenience for the common "several conditional classes on one
+ * element" shape, for anyone who'd rather write it declaratively:
+ *
+ * ```ts
+ * clsx("px-4 py-2", isActive && "bg-blue-6", { "opacity-50": disabled });
+ * // "px-4 py-2 bg-blue-6" (when isActive is true and disabled is false)
+ * ```
+ *
+ * Identical to `@kbach/react`'s own `clsx.ts` — deliberately duplicated
+ * rather than factored into a shared package, since this is genuinely all
+ * there is to it and a whole extra published package for one ~20-line
+ * function would be more ceremony than the thing itself.
+ */
+/** Anything `clsx` accepts as one argument — recursively, for arrays. */
+type ClassValue = ClassArray | ClassDictionary | string | number | bigint | boolean | null | undefined;
+/** A key is kept (as a literal class name) only when its value is truthy — `{ "opacity-50": disabled }`. */
+interface ClassDictionary {
+    [className: string]: unknown;
+}
+type ClassArray = ClassValue[];
+/**
+ * Joins every truthy piece across all arguments with a single space,
+ * skipping falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`)
+ * entirely — they contribute nothing, not even an extra space. Arrays are
+ * flattened (recursively, to any depth); a plain object keeps only the
+ * keys whose value is truthy.
+ */
+declare function clsx(...inputs: ClassValue[]): string;
+
+export { type ClassArray as C, type KbachConfig as K, ThemeProvider as T, type ClassDictionary as a, type ClassValue as b, type ColorScale as c, type ColorsAPI as d, type ThemeProviderProps as e, type ThemeState as f, type ThemeStorageAdapter as g, applyKbachConfig as h, clsx as i, useDynamicToken as j, useTheme as k, resolveKbachConfig as r, useColors as u };

package/dist/darkModeStore.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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. `applyToDom` below IS needed here, unlike what an earlier version of
+ *    this file's own comment claimed ("no DOM to apply the resolved mode
+ *    to") — that reasoning only holds for real native (Android/iOS), where
+ *    nativeBridge.ts's resolveStyle() reads getGlobalDarkMode() directly on
+ *    every call, no DOM involved at all. This file is ALSO used by Expo
+ *    Web, though (no `.web.ts` sibling — Metro has nothing to swap in), and
+ *    Expo Web resolves `dark:` classes to REAL CSS with `[data-theme=
+ *    "dark"]`-style selectors (see nativeBridge.web.ts) that only ever
+ *    match if something writes that attribute to the DOM — nothing did,
+ *    which is exactly why toggling the mode changed `useTheme()`'s own
+ *    state (a consumer reading `mode`/`isDark` directly, e.g. for a label,
+ *    updated correctly) while every `dark:`-prefixed style silently never
+ *    applied. `typeof document === 'undefined'` is what makes one function
+ *    safe on both platforms: real native's Hermes has no `document` global
+ *    at all (not even `undefined` as a defined-but-empty value — genuinely
+ *    unset, which `typeof` can check without throwing), so this always
+ *    no-ops there, while Expo Web's react-native-web renders into a real
+ *    browser DOM where it's needed.
+ */
+type ThemeMode = 'light' | 'dark' | 'system';
+/**
+ * Re-applies the CURRENT `isDark` value to the DOM (Expo Web only — a
+ * genuine no-op on real native, same as `applyToDom` itself) under whatever
+ * `getTheme().darkMode` strategy is active right now, with no change to
+ * `mode`/`isDark` themselves, so it deliberately does NOT `notify()`.
+ * Mirrors @kbach/react's identical `resyncDomWithActiveTheme` — see that
+ * one's own doc comment for the full race it fixes: this module's initial
+ * `applyToDom(isDark)` call (above) runs at IMPORT time against whichever
+ * `darkMode` strategy `defaultTheme` had at that moment, which on Expo Web
+ * is BEFORE an app's own `applyKbachConfig({darkMode: 'attribute'})` call
+ * (in config.ts) has had a chance to switch it — without this, that config
+ * call would silently never get its `dark:` classes to apply on initial
+ * load, even though `useTheme().isDark` already reads correctly.
+ */
+declare function resyncDomWithActiveTheme(): void;
+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;
+/**
+ * Applies `fallback` as the initial mode, but ONLY if nothing has made an
+ * explicit choice yet — called once by `<ThemeProvider defaultMode>` on
+ * mount, never exported for direct use elsewhere. Unlike the web store,
+ * there's no persisted-value check here (nothing to check); the only
+ * thing that can beat a seed is a `setGlobalThemeMode()` call that
+ * happened first (e.g. your own storage-restore logic run before the
+ * provider mounts).
+ */
+declare function seedDefaultMode(fallback: ThemeMode): void;
+/** Exported for tests only — resets every module-level field back to its as-if-just-imported state. */
+declare function _resetForTests(): void;
+/** Exported for tests only — removes the Appearance change subscription so a test's mock doesn't leak into the next one. */
+declare function _unsubscribeForTests(): void;
+
+export { type ThemeMode, _resetForTests, _unsubscribeForTests, getGlobalDarkMode, getGlobalThemeMode, resyncDomWithActiveTheme, seedDefaultMode, setGlobalThemeMode, subscribeGlobalDarkMode, toggleGlobalDarkMode };

package/dist/darkModeStore.js

@@ -0,0 +1,118 @@
+"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/darkModeStore.ts
+var darkModeStore_exports = {};
+__export(darkModeStore_exports, {
+  _resetForTests: () => _resetForTests,
+  _unsubscribeForTests: () => _unsubscribeForTests,
+  getGlobalDarkMode: () => getGlobalDarkMode,
+  getGlobalThemeMode: () => getGlobalThemeMode,
+  resyncDomWithActiveTheme: () => resyncDomWithActiveTheme,
+  seedDefaultMode: () => seedDefaultMode,
+  setGlobalThemeMode: () => setGlobalThemeMode,
+  subscribeGlobalDarkMode: () => subscribeGlobalDarkMode,
+  toggleGlobalDarkMode: () => toggleGlobalDarkMode
+});
+module.exports = __toCommonJS(darkModeStore_exports);
+var import_react_native = require("react-native");
+var import_theme = require("./theme");
+var listeners = /* @__PURE__ */ new Set();
+function systemPrefersDark() {
+  return import_react_native.Appearance.getColorScheme() === "dark";
+}
+function resolveIsDark(m) {
+  return m === "system" ? systemPrefersDark() : m === "dark";
+}
+function applyToDom(dark) {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  const strategy = (0, import_theme.getTheme)().darkMode;
+  root.classList.toggle("dark", strategy === "class" && dark);
+  root.classList.toggle("light", strategy === "class" && !dark);
+  if (strategy === "attribute") {
+    root.setAttribute("data-theme", dark ? "dark" : "light");
+  } else {
+    root.removeAttribute("data-theme");
+  }
+}
+var mode = "system";
+var isDark = resolveIsDark(mode);
+applyToDom(isDark);
+var hasExplicitChoice = false;
+var subscription = import_react_native.Appearance.addChangeListener(({ colorScheme }) => {
+  if (mode !== "system") return;
+  isDark = colorScheme === "dark";
+  applyToDom(isDark);
+  notify();
+});
+function notify() {
+  for (const listener of listeners) listener();
+}
+function resyncDomWithActiveTheme() {
+  applyToDom(isDark);
+}
+function getGlobalDarkMode() {
+  return isDark;
+}
+function getGlobalThemeMode() {
+  return mode;
+}
+function setGlobalThemeMode(nextMode) {
+  mode = nextMode;
+  isDark = resolveIsDark(nextMode);
+  hasExplicitChoice = true;
+  applyToDom(isDark);
+  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);
+  applyToDom(isDark);
+  notify();
+}
+function _resetForTests() {
+  mode = "system";
+  isDark = resolveIsDark(mode);
+  hasExplicitChoice = false;
+  listeners.clear();
+}
+function _unsubscribeForTests() {
+  subscription.remove();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  _resetForTests,
+  _unsubscribeForTests,
+  getGlobalDarkMode,
+  getGlobalThemeMode,
+  resyncDomWithActiveTheme,
+  seedDefaultMode,
+  setGlobalThemeMode,
+  subscribeGlobalDarkMode,
+  toggleGlobalDarkMode
+});

package/dist/dynamicTokens.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Cross-platform runtime-settable style values — the native counterpart to
+ * a real CSS custom property. Real `var(--sidebar-width)` already works on
+ * Expo Web today with ZERO code here (raw CSS text, resolved by the
+ * browser's own engine — see `jsxRuntimeCoreWeb.ts`, which does no
+ * className rewriting at all). Native has no such thing: RN's style system
+ * needs an actual JS-computed value at render time, so this module exists
+ * to give `var(--x)` an equivalent that works there too — same
+ * "module-level store is the real source of truth, no Context required"
+ * architecture as `darkModeStore.ts`, and `setDynamicToken` ALSO writes the
+ * real CSS custom property to the DOM when one exists (mirroring that
+ * file's own `applyToDom`), so a single call updates both platforms
+ * identically: instantly via native CSS reactivity on web, via this
+ * store's subscribers (see `jsxRuntimeCore.ts`'s `ReactiveElement`, which
+ * substitutes a registered token's current value into the className
+ * string before every resolve) on native.
+ *
+ * Deliberately ONE listener set shared by every token, not per-token
+ * subscriptions — same trade-off `darkModeStore.ts` already makes for
+ * "any relevant change re-renders every subscribed element" simplicity.
+ * An unrelated token's change still re-renders every subscribed element
+ * (there's no per-token filtering), but `substituteDynamicTokens` in
+ * `jsxRuntimeCore.ts` re-reads each token's CURRENT value fresh on every
+ * one of those re-renders, so the resolved style stays correct regardless
+ * — the redundant re-render is a cheap, accepted trade-off, not a bug.
+ */
+/** `name` is the bare token name, WITHOUT the leading `--` (matching how `getDynamicToken`/`var(--name)` substitution both address it). */
+declare function setDynamicToken(name: string, value: string): void;
+declare function getDynamicToken(name: string): string | undefined;
+declare function deleteDynamicToken(name: string): void;
+declare function subscribeDynamicTokens(listener: () => void): () => void;
+declare function getDynamicTokensVersion(): number;
+/** Exported for tests only — resets every module-level field back to its as-if-just-imported state. */
+declare function _resetForTests(): void;
+
+export { _resetForTests, deleteDynamicToken, getDynamicToken, getDynamicTokensVersion, setDynamicToken, subscribeDynamicTokens };

package/dist/dynamicTokens.js

@@ -0,0 +1,75 @@
+"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/dynamicTokens.ts
+var dynamicTokens_exports = {};
+__export(dynamicTokens_exports, {
+  _resetForTests: () => _resetForTests,
+  deleteDynamicToken: () => deleteDynamicToken,
+  getDynamicToken: () => getDynamicToken,
+  getDynamicTokensVersion: () => getDynamicTokensVersion,
+  setDynamicToken: () => setDynamicToken,
+  subscribeDynamicTokens: () => subscribeDynamicTokens
+});
+module.exports = __toCommonJS(dynamicTokens_exports);
+var tokens = /* @__PURE__ */ new Map();
+var listeners = /* @__PURE__ */ new Set();
+var version = 0;
+function applyToDom(name, value) {
+  if (typeof document === "undefined") return;
+  document.documentElement.style.setProperty(`--${name}`, value);
+}
+function notify() {
+  version++;
+  for (const listener of listeners) listener();
+}
+function setDynamicToken(name, value) {
+  tokens.set(name, value);
+  applyToDom(name, value);
+  notify();
+}
+function getDynamicToken(name) {
+  return tokens.get(name);
+}
+function deleteDynamicToken(name) {
+  if (!tokens.delete(name)) return;
+  if (typeof document !== "undefined") document.documentElement.style.removeProperty(`--${name}`);
+  notify();
+}
+function subscribeDynamicTokens(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+function getDynamicTokensVersion() {
+  return version;
+}
+function _resetForTests() {
+  tokens.clear();
+  listeners.clear();
+  version = 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  _resetForTests,
+  deleteDynamicToken,
+  getDynamicToken,
+  getDynamicTokensVersion,
+  setDynamicToken,
+  subscribeDynamicTokens
+});