@react-native-rethemed/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 manato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @react-native-rethemed/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Type-safe design tokens for React Native style props — no wrapper components. Light/dark aware, with text presets and a `themed` style API. Part of [react-native-rethemed](https://github.com/manakuro/react-native-rethemed).
+
+## Installation
+
+```sh
+npm install @react-native-rethemed/core
+npm install --save-dev @react-native-rethemed/cli
+```
+
+`react` and `react-native` are peer dependencies.
+
+## Usage
+
+Define a theme:
+
+```ts
+// src/theme/theme.ts
+import { defineTheme } from '@react-native-rethemed/core';
+
+export const themeConfig = defineTheme({
+  tokens: {
+    radii: { md: 6, full: 9999 },
+    spacing: { 1: 4, 2: 8, 4: 16 },
+    fontSizes: { sm: 14, md: 16 },
+    fontWeights: { normal: '400', semibold: '600' },
+    lineHeights: { moderate: 1.5 },
+  },
+  semanticTokens: {
+    colors: {
+      bg: { default: { light: '#ffffff', dark: '#111111' } },
+      fg: { default: { light: '#111111', dark: '#fafafa' } },
+    },
+    text: {
+      title: { fontSize: 'md', lineHeight: 'moderate', fontWeight: 'semibold' },
+    },
+  },
+  defaults: { fontSize: 'md' },
+});
+```
+
+Generate the typed bindings with [`@react-native-rethemed/cli`](https://github.com/manakuro/react-native-rethemed/tree/main/packages/react-native-rethemed/cli):
+
+```sh
+npx @react-native-rethemed/cli codegen src/theme/theme.ts --docs docs/themed.md
+```
+
+Then wrap the app and style with tokens:
+
+```tsx
+import { Text, View } from 'react-native';
+import { ThemedProvider, useThemed } from './theme/themed.gen';
+
+export default function App() {
+  return (
+    <ThemedProvider>
+      <Card />
+    </ThemedProvider>
+  );
+}
+
+function Card() {
+  const { themed } = useThemed();
+  return (
+    <View style={themed.view({ backgroundColor: 'bg.default', padding: 4, borderRadius: 'md' })}>
+      <Text style={themed.text.title({ color: 'fg.default' })}>Hello</Text>
+    </View>
+  );
+}
+```
+
+Start from a design system with a token package (`@react-native-rethemed/chakra-ui-tokens`, `material-ui-tokens`, `material-design-tokens`, `panda-css-tokens`, `tailwind-css-tokens`, `shadcn-ui-tokens`, `radix-ui-tokens`) and `extendTheme`.
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@react-native-rethemed/core` | Everything: `defineTheme`, `extendTheme`, `createThemed`, `createThemedStyles` and the types |
+| `@react-native-rethemed/core/config` | The React / React Native-free part (`defineTheme`, `extendTheme`, token helpers), for theme files and tooling |
+
+See the [main README](https://github.com/manakuro/react-native-rethemed#readme) for color mode, `extendTheme` merge rules and the full API.
+
+## License
+
+MIT

package/dist/cjs/color-mode-store.d.ts

@@ -0,0 +1,32 @@
+export type ColorMode = 'light' | 'dark' | 'system';
+/**
+ * Structural subset of `expo-secure-store` / `AsyncStorage`, so either can be
+ * passed as-is without an adapter.
+ */
+export type ColorModeStorage = {
+    getItem: (key: string) => string | null | Promise<string | null>;
+    setItem: (key: string, value: string) => void | Promise<void>;
+};
+export declare const isColorMode: (value: unknown) => value is ColorMode;
+/**
+ * External store holding the uncontrolled color mode. One is created per
+ * `createThemed()` call (never at module level) so independent instances
+ * don't share state.
+ */
+export declare function createColorModeStore(): {
+    /**
+     * Seeds the mode on first use only. Called during render so the very
+     * first render already sees `defaultMode`; later calls (e.g. a changed
+     * `defaultColorMode` prop) are ignored rather than overwriting the
+     * current mode.
+     */
+    init(defaultMode: ColorMode): void;
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): ColorMode;
+    setMode(next: ColorMode): void;
+    /** Returns `false` if rehydration already ran for this store. */
+    beginHydration(): boolean;
+    /** Applies a stored value unless it's malformed or the user already chose. */
+    hydrate(saved: unknown): void;
+};
+export type ColorModeStore = ReturnType<typeof createColorModeStore>;

package/dist/cjs/color-mode-store.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isColorMode = void 0;
+exports.createColorModeStore = createColorModeStore;
+const isColorMode = (value) => value === 'light' || value === 'dark' || value === 'system';
+exports.isColorMode = isColorMode;
+/**
+ * External store holding the uncontrolled color mode. One is created per
+ * `createThemed()` call (never at module level) so independent instances
+ * don't share state.
+ */
+function createColorModeStore() {
+    let mode = null;
+    // Set once the user picks a mode, so a late rehydration can't override it.
+    let userSet = false;
+    let hydrationStarted = false;
+    const listeners = new Set();
+    const emit = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    return {
+        /**
+         * Seeds the mode on first use only. Called during render so the very
+         * first render already sees `defaultMode`; later calls (e.g. a changed
+         * `defaultColorMode` prop) are ignored rather than overwriting the
+         * current mode.
+         */
+        init(defaultMode) {
+            if (mode === null)
+                mode = defaultMode;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getSnapshot() {
+            return mode ?? 'system';
+        },
+        setMode(next) {
+            userSet = true;
+            if (next === mode)
+                return;
+            mode = next;
+            emit();
+        },
+        /** Returns `false` if rehydration already ran for this store. */
+        beginHydration() {
+            if (hydrationStarted)
+                return false;
+            hydrationStarted = true;
+            return true;
+        },
+        /** Applies a stored value unless it's malformed or the user already chose. */
+        hydrate(saved) {
+            if (userSet || !(0, exports.isColorMode)(saved) || saved === mode)
+                return;
+            mode = saved;
+            emit();
+        },
+    };
+}

package/dist/cjs/config.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@react-native-rethemed/core/config` — the React/RN-free part of core.
+ *
+ * Apps can import everything from the package root: the CLI stubs
+ * `react-native` when it evaluates a theme file. Core's own token packages
+ * still import from here so they never depend on that stub.
+ */
+export { defineTheme } from './define-theme';
+export { extendTheme } from './extend-theme';
+export { RN_DEFAULT_FONT_SIZE, resolveBaseFontSize, } from './resolvers/line-height-resolver';
+export { isSchemeColor, walkSemanticColors } from './semantic-colors';
+export { COLOR_KEYS, FONT_SIZE_KEYS, FONT_WEIGHT_KEYS, LETTER_SPACING_KEYS, LINE_HEIGHT_KEYS, RADIUS_KEYS, SHADOW_STYLE_PROPS, SPACING_KEYS, Z_INDEX_KEYS, } from './style-props';
+export { isTextPreset, resolveTextColor, TEXT_TOKEN_FIELDS, walkTextPresets, } from './text-tree';
+export type { LooseSchema, SchemeColor, SemanticColors, ShadowToken, TextColor, TextToken, TextTokenTree, ThemeConfig, ThemedSchema, ThemedStyles, TokenizeStyle, } from './types';

package/dist/cjs/config.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.walkTextPresets = exports.TEXT_TOKEN_FIELDS = exports.resolveTextColor = exports.isTextPreset = exports.Z_INDEX_KEYS = exports.SPACING_KEYS = exports.SHADOW_STYLE_PROPS = exports.RADIUS_KEYS = exports.LINE_HEIGHT_KEYS = exports.LETTER_SPACING_KEYS = exports.FONT_WEIGHT_KEYS = exports.FONT_SIZE_KEYS = exports.COLOR_KEYS = exports.walkSemanticColors = exports.isSchemeColor = exports.resolveBaseFontSize = exports.RN_DEFAULT_FONT_SIZE = exports.extendTheme = exports.defineTheme = void 0;
+/**
+ * `@react-native-rethemed/core/config` — the React/RN-free part of core.
+ *
+ * Apps can import everything from the package root: the CLI stubs
+ * `react-native` when it evaluates a theme file. Core's own token packages
+ * still import from here so they never depend on that stub.
+ */
+var define_theme_1 = require("./define-theme");
+Object.defineProperty(exports, "defineTheme", { enumerable: true, get: function () { return define_theme_1.defineTheme; } });
+var extend_theme_1 = require("./extend-theme");
+Object.defineProperty(exports, "extendTheme", { enumerable: true, get: function () { return extend_theme_1.extendTheme; } });
+var line_height_resolver_1 = require("./resolvers/line-height-resolver");
+Object.defineProperty(exports, "RN_DEFAULT_FONT_SIZE", { enumerable: true, get: function () { return line_height_resolver_1.RN_DEFAULT_FONT_SIZE; } });
+Object.defineProperty(exports, "resolveBaseFontSize", { enumerable: true, get: function () { return line_height_resolver_1.resolveBaseFontSize; } });
+var semantic_colors_1 = require("./semantic-colors");
+Object.defineProperty(exports, "isSchemeColor", { enumerable: true, get: function () { return semantic_colors_1.isSchemeColor; } });
+Object.defineProperty(exports, "walkSemanticColors", { enumerable: true, get: function () { return semantic_colors_1.walkSemanticColors; } });
+var style_props_1 = require("./style-props");
+Object.defineProperty(exports, "COLOR_KEYS", { enumerable: true, get: function () { return style_props_1.COLOR_KEYS; } });
+Object.defineProperty(exports, "FONT_SIZE_KEYS", { enumerable: true, get: function () { return style_props_1.FONT_SIZE_KEYS; } });
+Object.defineProperty(exports, "FONT_WEIGHT_KEYS", { enumerable: true, get: function () { return style_props_1.FONT_WEIGHT_KEYS; } });
+Object.defineProperty(exports, "LETTER_SPACING_KEYS", { enumerable: true, get: function () { return style_props_1.LETTER_SPACING_KEYS; } });
+Object.defineProperty(exports, "LINE_HEIGHT_KEYS", { enumerable: true, get: function () { return style_props_1.LINE_HEIGHT_KEYS; } });
+Object.defineProperty(exports, "RADIUS_KEYS", { enumerable: true, get: function () { return style_props_1.RADIUS_KEYS; } });
+Object.defineProperty(exports, "SHADOW_STYLE_PROPS", { enumerable: true, get: function () { return style_props_1.SHADOW_STYLE_PROPS; } });
+Object.defineProperty(exports, "SPACING_KEYS", { enumerable: true, get: function () { return style_props_1.SPACING_KEYS; } });
+Object.defineProperty(exports, "Z_INDEX_KEYS", { enumerable: true, get: function () { return style_props_1.Z_INDEX_KEYS; } });
+var text_tree_1 = require("./text-tree");
+Object.defineProperty(exports, "isTextPreset", { enumerable: true, get: function () { return text_tree_1.isTextPreset; } });
+Object.defineProperty(exports, "resolveTextColor", { enumerable: true, get: function () { return text_tree_1.resolveTextColor; } });
+Object.defineProperty(exports, "TEXT_TOKEN_FIELDS", { enumerable: true, get: function () { return text_tree_1.TEXT_TOKEN_FIELDS; } });
+Object.defineProperty(exports, "walkTextPresets", { enumerable: true, get: function () { return text_tree_1.walkTextPresets; } });

package/dist/cjs/create-themed-styles.d.ts

@@ -0,0 +1,13 @@
+import type { ColorScheme } from './resolvers/color-resolver';
+import type { LooseSchema, ThemeConfig, ThemedSchema, ThemedStyles } from './types';
+/**
+ * Builds `{ view, text, image }` from a fully resolved `ThemeConfig` for one
+ * fixed color scheme. No React here — plain data in, plain functions out.
+ * `createThemed` calls this once per scheme and hands the result out through
+ * `useThemed()`, so components re-render (and pick up new colors) when the
+ * scheme changes.
+ *
+ * `S` comes from the generated `themed.gen.ts`; without it every token
+ * prop is loosely typed (`LooseSchema`).
+ */
+export declare function createThemedStyles<S extends ThemedSchema = LooseSchema>(config: ThemeConfig, scheme: ColorScheme): ThemedStyles<S>;

package/dist/cjs/create-themed-styles.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createThemedStyles = createThemedStyles;
+const style_resolver_1 = require("./resolvers/style-resolver");
+const text_tree_1 = require("./text-tree");
+const text_variants_1 = require("./text-variants");
+/**
+ * Builds `{ view, text, image }` from a fully resolved `ThemeConfig` for one
+ * fixed color scheme. No React here — plain data in, plain functions out.
+ * `createThemed` calls this once per scheme and hands the result out through
+ * `useThemed()`, so components re-render (and pick up new colors) when the
+ * scheme changes.
+ *
+ * `S` comes from the generated `themed.gen.ts`; without it every token
+ * prop is loosely typed (`LooseSchema`).
+ */
+function createThemedStyles(config, scheme) {
+    // One pass over the input's keys per call; see `createStyleResolver`.
+    const resolveStyle = (0, style_resolver_1.createStyleResolver)(config, scheme);
+    const text = (input = {}) => resolveStyle(input);
+    // Preset colors (`{ light, dark }`) are picked for this scheme up front.
+    const variants = (0, text_variants_1.createTextVariants)((0, text_tree_1.resolveTextTree)(config.semanticTokens?.text, scheme), (input) => resolveStyle(input));
+    // `Object.assign` would throw for roles that collide with non-writable
+    // function properties (`name`, `length`); defineProperty overrides them.
+    for (const [role, sizes] of Object.entries(variants)) {
+        Object.defineProperty(text, role, {
+            value: sizes,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    return {
+        view: resolveStyle,
+        image: resolveStyle,
+        text,
+    };
+}

package/dist/cjs/create-themed.d.ts

@@ -0,0 +1,46 @@
+import { type ReactNode } from 'react';
+import { type ColorMode, type ColorModeStorage } from './color-mode-store';
+import { type ColorScheme } from './resolvers/color-resolver';
+import type { LooseSchema, ThemeConfig, ThemedSchema, ThemedStyles } from './types';
+export type { ColorMode, ColorModeStorage, ColorScheme };
+export type ThemedProviderProps = {
+    children?: ReactNode;
+    /**
+     * Controlled mode: the app owns the scheme and this value is used as-is.
+     * When set, `defaultColorMode`/`storage`/`storageKey` are ignored.
+     */
+    colorScheme?: ColorScheme;
+    /** Uncontrolled initial mode. Only read the first time the store is used. */
+    defaultColorMode?: ColorMode;
+    /** Uncontrolled persistence, e.g. `expo-secure-store` or `AsyncStorage`. */
+    storage?: ColorModeStorage;
+    storageKey?: string;
+};
+export type UseThemedResult<S extends ThemedSchema = LooseSchema> = {
+    themed: ThemedStyles<S>;
+    /** Primitive, scheme-independent tokens exactly as in the config. */
+    tokens: S['tokens'];
+    /**
+     * Semantic tokens with colors (including text preset colors) resolved for
+     * the current scheme.
+     */
+    semanticTokens: S['semanticTokens'];
+    colorScheme: ColorScheme;
+};
+export type UseColorModeResult = {
+    mode: ColorMode;
+    setMode: (mode: ColorMode) => void;
+};
+/**
+ * Binds a theme config to React: returns a provider plus hooks that read
+ * the current scheme from it. Everything (store, contexts, precomputed
+ * themes) is scoped to this call, so several instances can coexist.
+ *
+ * `S` is supplied by the generated `themed.gen.ts`
+ * (`@react-native-rethemed/cli codegen`); without it tokens are loosely typed.
+ */
+export declare function createThemed<S extends ThemedSchema = LooseSchema>(config: ThemeConfig): {
+    ThemedProvider: ({ children, colorScheme, defaultColorMode, storage, storageKey, }: ThemedProviderProps) => import("react").FunctionComponentElement<import("react").ProviderProps<ColorScheme | null>>;
+    useThemed: () => UseThemedResult<S>;
+    useColorMode: () => UseColorModeResult;
+};

package/dist/cjs/create-themed.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createThemed = createThemed;
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const color_mode_store_1 = require("./color-mode-store");
+const create_themed_styles_1 = require("./create-themed-styles");
+const color_resolver_1 = require("./resolvers/color-resolver");
+const text_tree_1 = require("./text-tree");
+const DEFAULT_STORAGE_KEY = 'react-native-rethemed.color-mode';
+/** RN 0.86 reports `'unspecified'` (and may report `null`); the theme is binary. */
+function toColorScheme(value) {
+    return value === 'dark' ? 'dark' : 'light';
+}
+/** `Appearance.setColorScheme` is RN 0.73+ only and absent on react-native-web. */
+function syncNativeAppearance(mode) {
+    if (typeof react_native_1.Appearance?.setColorScheme !== 'function')
+        return;
+    react_native_1.Appearance.setColorScheme(mode === 'system' ? 'unspecified' : mode);
+}
+const warnControlledSetMode = () => {
+    if (__DEV__) {
+        console.warn('[react-native-rethemed] setMode() was called while <ThemedProvider> is ' +
+            'controlled via the `colorScheme` prop. Update that prop instead.');
+    }
+};
+/**
+ * Binds a theme config to React: returns a provider plus hooks that read
+ * the current scheme from it. Everything (store, contexts, precomputed
+ * themes) is scoped to this call, so several instances can coexist.
+ *
+ * `S` is supplied by the generated `themed.gen.ts`
+ * (`@react-native-rethemed/cli codegen`); without it tokens are loosely typed.
+ */
+function createThemed(config) {
+    // Precomputed once per scheme so `useThemed()` returns referentially
+    // stable objects until the scheme actually changes.
+    const build = (colorScheme) => ({
+        themed: (0, create_themed_styles_1.createThemedStyles)(config, colorScheme),
+        tokens: config.tokens ?? {},
+        semanticTokens: {
+            colors: (0, color_resolver_1.resolveSemanticColors)(config, colorScheme),
+            text: (0, text_tree_1.resolveTextTree)(config.semanticTokens?.text, colorScheme),
+        },
+        colorScheme,
+    });
+    const themes = {
+        light: build('light'),
+        dark: build('dark'),
+    };
+    const store = (0, color_mode_store_1.createColorModeStore)();
+    // Split so a mode change that keeps the same scheme (e.g. 'system' ->
+    // 'light' while the OS is light) doesn't re-render `useThemed` consumers.
+    const SchemeContext = (0, react_1.createContext)(null);
+    const ModeContext = (0, react_1.createContext)(null);
+    function ThemedProvider({ children, colorScheme, defaultColorMode = 'system', storage, storageKey = DEFAULT_STORAGE_KEY, }) {
+        const isControlled = colorScheme !== undefined;
+        // Hooks run unconditionally so switching between controlled and
+        // uncontrolled never changes hook order or remounts children.
+        store.init(defaultColorMode);
+        const storedMode = (0, react_1.useSyncExternalStore)(store.subscribe, store.getSnapshot, store.getSnapshot);
+        const systemScheme = toColorScheme((0, react_native_1.useColorScheme)());
+        (0, react_1.useEffect)(() => {
+            if (isControlled || !storage || !store.beginHydration())
+                return;
+            // The store outlives this provider, so the result is applied even if
+            // it resolves after unmount; `hydrate` drops it if the user already
+            // picked a mode. `Promise.resolve().then` also catches a sync throw.
+            Promise.resolve()
+                .then(() => storage.getItem(storageKey))
+                .then((saved) => store.hydrate(saved))
+                .catch(() => { });
+        }, [isControlled, storage, storageKey]);
+        (0, react_1.useEffect)(() => {
+            if (!isControlled)
+                syncNativeAppearance(storedMode);
+        }, [isControlled, storedMode]);
+        const setUncontrolledMode = (0, react_1.useCallback)((next) => {
+            // Sync first: when returning to 'system', RN's `useColorScheme()`
+            // keeps reporting the old override until it's reset.
+            syncNativeAppearance(next);
+            store.setMode(next);
+            if (storage) {
+                Promise.resolve()
+                    .then(() => storage.setItem(storageKey, next))
+                    .catch(() => { });
+            }
+        }, [storage, storageKey]);
+        const scheme = isControlled
+            ? colorScheme
+            : storedMode === 'system'
+                ? systemScheme
+                : storedMode;
+        const mode = isControlled ? colorScheme : storedMode;
+        const setMode = isControlled ? warnControlledSetMode : setUncontrolledMode;
+        const modeValue = (0, react_1.useMemo)(() => ({ mode, setMode }), [mode, setMode]);
+        // `createElement` instead of JSX so consumers type-checking this source
+        // (it ships as `.ts`) don't need a `jsx` compiler option.
+        return (0, react_1.createElement)(SchemeContext, { value: scheme }, (0, react_1.createElement)(ModeContext, { value: modeValue }, children));
+    }
+    function useThemed() {
+        const scheme = (0, react_1.useContext)(SchemeContext);
+        if (scheme === null) {
+            throw new Error('useThemed() must be used within a <ThemedProvider> returned by the ' +
+                'same createThemed() call.');
+        }
+        return themes[scheme];
+    }
+    function useColorMode() {
+        const value = (0, react_1.useContext)(ModeContext);
+        if (value === null) {
+            throw new Error('useColorMode() must be used within a <ThemedProvider> returned by ' +
+                'the same createThemed() call.');
+        }
+        return value;
+    }
+    return { ThemedProvider, useThemed, useColorMode };
+}

package/dist/cjs/define-theme.d.ts

@@ -0,0 +1,11 @@
+import type { ThemeConfig } from './types';
+/**
+ * Identity function used purely as a type gate: checks `config` against
+ * `ThemeConfig` (object literals get the usual excess-property check, so a
+ * misspelled `radius` or `semanticToken` fails to compile).
+ *
+ * The return type is deliberately the plain `ThemeConfig` — exact token
+ * names come from the generated `themed.gen.ts`, not from literal-type
+ * inference here.
+ */
+export declare function defineTheme(config: ThemeConfig): ThemeConfig;

package/dist/cjs/define-theme.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTheme = defineTheme;
+/**
+ * Identity function used purely as a type gate: checks `config` against
+ * `ThemeConfig` (object literals get the usual excess-property check, so a
+ * misspelled `radius` or `semanticToken` fails to compile).
+ *
+ * The return type is deliberately the plain `ThemeConfig` — exact token
+ * names come from the generated `themed.gen.ts`, not from literal-type
+ * inference here.
+ */
+function defineTheme(config) {
+    return config;
+}

package/dist/cjs/extend-theme.d.ts

@@ -0,0 +1,14 @@
+import type { ThemeConfig } from './types';
+/**
+ * Merges N `ThemeConfig`s, folding left-to-right so later themes override
+ * earlier ones per key:
+ *
+ * ```ts
+ * const config = extendTheme(materialDesignTheme, chakraUiTheme, {
+ *   semanticTokens: {
+ *     text: { display: { lg: { fontSize: 60, lineHeight: 68 } } },
+ *   },
+ * });
+ * ```
+ */
+export declare function extendTheme(...themes: [ThemeConfig, ...ThemeConfig[]]): ThemeConfig;

package/dist/cjs/extend-theme.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extendTheme = extendTheme;
+const semantic_colors_1 = require("./semantic-colors");
+const text_tree_1 = require("./text-tree");
+/**
+ * Flat `tokens` categories: a one-level merge (`{ ...a, ...b }`, `b` wins per
+ * key) is enough. `semanticTokens.colors` holds groups (merged one level
+ * deeper) and top-level colors (replaced whole); `semanticTokens.text` is a tree of any depth — see
+ * `mergeTextTree`.
+ *
+ * Merging is runtime-only: the result is typed as the plain `ThemeConfig`,
+ * and exact token names come from the generated `themed.gen.ts`.
+ */
+const FLAT_CATEGORY_KEYS = [
+    'colors',
+    'radii',
+    'spacing',
+    'fontSizes',
+    'fontWeights',
+    'lineHeights',
+    'letterSpacings',
+    'zIndices',
+    'shadows',
+];
+function mergeFlat(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return { ...a, ...b };
+}
+/**
+ * `semanticTokens.colors`: groups are merged, colors replaced whole, so
+ * overriding `bg.default` keeps `bg.subtle` and every other group. A
+ * top-level color (`primary`) is replaced like a token; when a name is a
+ * color on one side and a group on the other, the later side replaces it.
+ */
+function mergeSemanticColors(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const result = { ...a };
+    for (const [key, next] of Object.entries(b)) {
+        const prev = result[key];
+        result[key] =
+            prev && !(0, semantic_colors_1.isSchemeColor)(prev) && !(0, semantic_colors_1.isSchemeColor)(next)
+                ? { ...prev, ...next }
+                : next;
+    }
+    return result;
+}
+/**
+ * `semanticTokens.text`: groups merge recursively, presets (leaves) are
+ * replaced whole. So overriding `display.lg` keeps `display.md` and every
+ * other group, at any depth. When a key is a preset on one side and a group
+ * on the other, the later side replaces it.
+ */
+function mergeTextTree(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const result = { ...a };
+    for (const [key, next] of Object.entries(b)) {
+        const prev = result[key];
+        result[key] =
+            prev && !(0, text_tree_1.isTextPreset)(prev) && !(0, text_tree_1.isTextPreset)(next)
+                ? (mergeTextTree(prev, next) ?? next)
+                : next;
+    }
+    return result;
+}
+function mergeTokens(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const merged = {};
+    for (const key of FLAT_CATEGORY_KEYS) {
+        const value = mergeFlat(a[key], b[key]);
+        if (value)
+            merged[key] = value;
+    }
+    return merged;
+}
+function mergeSemanticTokens(a, b) {
+    const colors = mergeSemanticColors(a?.colors, b?.colors);
+    const text = mergeTextTree(a?.text, b?.text);
+    return {
+        ...(colors ? { colors } : {}),
+        ...(text ? { text } : {}),
+    };
+}
+function mergeThemeConfig(a, b) {
+    const defaults = mergeFlat(a.defaults, b.defaults);
+    return {
+        tokens: mergeTokens(a.tokens, b.tokens),
+        semanticTokens: mergeSemanticTokens(a.semanticTokens, b.semanticTokens),
+        ...(defaults ? { defaults } : {}),
+    };
+}
+/**
+ * Merges N `ThemeConfig`s, folding left-to-right so later themes override
+ * earlier ones per key:
+ *
+ * ```ts
+ * const config = extendTheme(materialDesignTheme, chakraUiTheme, {
+ *   semanticTokens: {
+ *     text: { display: { lg: { fontSize: 60, lineHeight: 68 } } },
+ *   },
+ * });
+ * ```
+ */
+function extendTheme(...themes) {
+    return themes.reduce(mergeThemeConfig);
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,4 @@
+export * from './config';
+export type { ColorMode, ColorModeStorage, ColorScheme, ThemedProviderProps, UseColorModeResult, UseThemedResult, } from './create-themed';
+export { createThemed } from './create-themed';
+export { createThemedStyles } from './create-themed-styles';