@stackwright/themes 0.4.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Per Aspera Sapientia LLC
+
+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/dist/index.d.mts

@@ -0,0 +1,331 @@
+import { z } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode } from 'react';
+
+declare const componentStyleSchema: z.ZodObject<{
+    base: z.ZodOptional<z.ZodString>;
+    primary: z.ZodOptional<z.ZodString>;
+    secondary: z.ZodOptional<z.ZodString>;
+    outline: z.ZodOptional<z.ZodString>;
+    shadow: z.ZodOptional<z.ZodString>;
+    nav: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodOptional<z.ZodString>>>;
+declare const colorsSchema: z.ZodObject<{
+    primary: z.ZodString;
+    secondary: z.ZodString;
+    accent: z.ZodString;
+    background: z.ZodString;
+    surface: z.ZodString;
+    text: z.ZodString;
+    textSecondary: z.ZodString;
+}, z.core.$strip>;
+type ThemeColors = z.infer<typeof colorsSchema>;
+type ColorMode = 'light' | 'dark' | 'system';
+declare const themeConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    colors: z.ZodObject<{
+        primary: z.ZodString;
+        secondary: z.ZodString;
+        accent: z.ZodString;
+        background: z.ZodString;
+        surface: z.ZodString;
+        text: z.ZodString;
+        textSecondary: z.ZodString;
+    }, z.core.$strip>;
+    darkColors: z.ZodOptional<z.ZodObject<{
+        primary: z.ZodString;
+        secondary: z.ZodString;
+        accent: z.ZodString;
+        background: z.ZodString;
+        surface: z.ZodString;
+        text: z.ZodString;
+        textSecondary: z.ZodString;
+    }, z.core.$strip>>;
+    backgroundImage: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        repeat: z.ZodOptional<z.ZodEnum<{
+            repeat: "repeat";
+            "repeat-x": "repeat-x";
+            "repeat-y": "repeat-y";
+            "no-repeat": "no-repeat";
+        }>>;
+        size: z.ZodOptional<z.ZodString>;
+        position: z.ZodOptional<z.ZodString>;
+        attachment: z.ZodOptional<z.ZodEnum<{
+            scroll: "scroll";
+            fixed: "fixed";
+            local: "local";
+        }>>;
+        scale: z.ZodOptional<z.ZodNumber>;
+        animation: z.ZodOptional<z.ZodEnum<{
+            drift: "drift";
+            float: "float";
+            shimmer: "shimmer";
+            "shimmer-float": "shimmer-float";
+            none: "none";
+        }>>;
+        customAnimation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    typography: z.ZodObject<{
+        fontFamily: z.ZodObject<{
+            primary: z.ZodString;
+            secondary: z.ZodString;
+        }, z.core.$strip>;
+        scale: z.ZodObject<{
+            xs: z.ZodString;
+            sm: z.ZodString;
+            base: z.ZodString;
+            lg: z.ZodString;
+            xl: z.ZodString;
+            '2xl': z.ZodString;
+            '3xl': z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    spacing: z.ZodObject<{
+        xs: z.ZodString;
+        sm: z.ZodString;
+        md: z.ZodString;
+        lg: z.ZodString;
+        xl: z.ZodString;
+        '2xl': z.ZodString;
+    }, z.core.$strip>;
+    components: z.ZodOptional<z.ZodObject<{
+        button: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        card: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        header: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        footer: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const themeSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    colors: z.ZodObject<{
+        primary: z.ZodString;
+        secondary: z.ZodString;
+        accent: z.ZodString;
+        background: z.ZodString;
+        surface: z.ZodString;
+        text: z.ZodString;
+        textSecondary: z.ZodString;
+    }, z.core.$strip>;
+    darkColors: z.ZodOptional<z.ZodObject<{
+        primary: z.ZodString;
+        secondary: z.ZodString;
+        accent: z.ZodString;
+        background: z.ZodString;
+        surface: z.ZodString;
+        text: z.ZodString;
+        textSecondary: z.ZodString;
+    }, z.core.$strip>>;
+    backgroundImage: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        repeat: z.ZodOptional<z.ZodEnum<{
+            repeat: "repeat";
+            "repeat-x": "repeat-x";
+            "repeat-y": "repeat-y";
+            "no-repeat": "no-repeat";
+        }>>;
+        size: z.ZodOptional<z.ZodString>;
+        position: z.ZodOptional<z.ZodString>;
+        attachment: z.ZodOptional<z.ZodEnum<{
+            scroll: "scroll";
+            fixed: "fixed";
+            local: "local";
+        }>>;
+        scale: z.ZodOptional<z.ZodNumber>;
+        animation: z.ZodOptional<z.ZodEnum<{
+            drift: "drift";
+            float: "float";
+            shimmer: "shimmer";
+            "shimmer-float": "shimmer-float";
+            none: "none";
+        }>>;
+        customAnimation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    typography: z.ZodObject<{
+        fontFamily: z.ZodObject<{
+            primary: z.ZodString;
+            secondary: z.ZodString;
+        }, z.core.$strip>;
+        scale: z.ZodObject<{
+            xs: z.ZodString;
+            sm: z.ZodString;
+            base: z.ZodString;
+            lg: z.ZodString;
+            xl: z.ZodString;
+            '2xl': z.ZodString;
+            '3xl': z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    spacing: z.ZodObject<{
+        xs: z.ZodString;
+        sm: z.ZodString;
+        md: z.ZodString;
+        lg: z.ZodString;
+        xl: z.ZodString;
+        '2xl': z.ZodString;
+    }, z.core.$strip>;
+    components: z.ZodOptional<z.ZodObject<{
+        button: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        card: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        header: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        footer: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ThemeConfig = z.infer<typeof themeConfigSchema>;
+type ComponentStyle = z.infer<typeof componentStyleSchema>;
+interface Theme extends ThemeConfig {
+}
+
+interface ThemeContextType {
+    /** The resolved theme — `colors` reflects the active color mode. */
+    theme: Theme;
+    /** The original theme with both `colors` and `darkColors` intact. */
+    rawTheme: Theme;
+    setTheme: (theme: Theme) => void;
+    /** Current color mode setting (`'light'`, `'dark'`, or `'system'`). */
+    colorMode: ColorMode;
+    /** Switch the color mode. */
+    setColorMode: (mode: ColorMode) => void;
+    /** The actually active mode after resolving `'system'`. */
+    resolvedColorMode: 'light' | 'dark';
+}
+interface ThemeProviderProps {
+    theme: Theme;
+    children: ReactNode;
+    /** Initial color mode. Defaults to `'system'`. */
+    initialColorMode?: ColorMode;
+}
+declare const ThemeProvider: React.FC<ThemeProviderProps>;
+/**
+ * Access the current theme and color mode controls.
+ * Must be called inside a `<ThemeProvider>`.
+ */
+declare const useTheme: () => ThemeContextType;
+/**
+ * Like `useTheme`, but returns `undefined` instead of throwing when
+ * no `ThemeProvider` is present. Useful for optional-context components
+ * like `ThemeStyleInjector`.
+ */
+declare const useThemeOptional: () => ThemeContextType | undefined;
+/**
+ * Converts a Stackwright Theme to CSS custom properties.
+ * Inject these via ThemeStyleInjector or a `<style>` tag.
+ */
+declare function themeToCSSVars(theme: Theme): Record<string, string>;
+interface ThemeStyleInjectorProps {
+    /**
+     * Explicit theme override. When omitted the resolved theme from the
+     * nearest `ThemeProvider` is used automatically — this is the
+     * recommended approach so CSS vars stay in sync with color mode changes.
+     */
+    theme?: Theme;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * Wraps children in a div that injects Stackwright CSS custom properties.
+ * Place this inside a `<ThemeProvider>` and it will track color mode
+ * changes automatically.
+ */
+declare function ThemeStyleInjector({ theme: themeProp, children, className, }: ThemeStyleInjectorProps): react_jsx_runtime.JSX.Element;
+
+declare class ThemeLoader {
+    private static themes;
+    static loadThemeFromYaml(yamlContent: string): Theme;
+    static loadThemeFromFile(themeName: string): Theme;
+    static getTheme(name: string): Theme | undefined;
+    static getAllThemes(): Theme[];
+    static registerCustomTheme(theme: Theme): void;
+    static loadCustomTheme(theme: Theme): Theme;
+    private static getEmbeddedTheme;
+}
+
+/**
+ * Blocking script that reads the `sw-color-mode` cookie and applies the
+ * correct color mode attribute to `<html>` before React hydrates.
+ *
+ * Place this in `_document.tsx` `<Head>` (Pages Router) or in a `<script>`
+ * tag in `layout.tsx` (App Router). It must execute before the body is
+ * painted — intentionally render-blocking.
+ *
+ * The `data-sw-color-mode` attribute set by this script is read by
+ * `ThemeProvider`'s `systemPreference` initialiser, ensuring the first
+ * React render matches the visible state — no hydration mismatch.
+ *
+ * For return visitors (cookie exists): correct theme on first paint, zero flash.
+ * For first-time visitors with OS dark mode: one-frame flash (same as next-themes v0.2).
+ */
+declare function ColorModeScript({ fallback }: {
+    fallback?: ColorMode;
+}): react_jsx_runtime.JSX.Element;
+
+export { type ColorMode, ColorModeScript, type ComponentStyle, type Theme, type ThemeColors, type ThemeColors as ThemeColorsType, type ThemeConfig, ThemeLoader, ThemeProvider, ThemeStyleInjector, colorsSchema, componentStyleSchema, themeConfigSchema, themeSchema, themeToCSSVars, useTheme, useThemeOptional };

package/dist/index.d.ts

@@ -1,5 +1,331 @@
-export * from './types';
-export * from './ThemeProvider';
-export * from './themeLoader';
-export type { ThemeConfig, Theme, ComponentStyle } from './types';
-//# sourceMappingURL=index.d.ts.map
+import { z } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode } from 'react';
+
+declare const componentStyleSchema: z.ZodObject<{
+    base: z.ZodOptional<z.ZodString>;
+    primary: z.ZodOptional<z.ZodString>;
+    secondary: z.ZodOptional<z.ZodString>;
+    outline: z.ZodOptional<z.ZodString>;
+    shadow: z.ZodOptional<z.ZodString>;
+    nav: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodOptional<z.ZodString>>>;
+declare const colorsSchema: z.ZodObject<{
+    primary: z.ZodString;
+    secondary: z.ZodString;
+    accent: z.ZodString;
+    background: z.ZodString;
+    surface: z.ZodString;
+    text: z.ZodString;
+    textSecondary: z.ZodString;
+}, z.core.$strip>;
+type ThemeColors = z.infer<typeof colorsSchema>;
+type ColorMode = 'light' | 'dark' | 'system';
+declare const themeConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    colors: z.ZodObject<{
+        primary: z.ZodString;
+        secondary: z.ZodString;
+        accent: z.ZodString;
+        background: z.ZodString;
+        surface: z.ZodString;
+        text: z.ZodString;
+        textSecondary: z.ZodString;
+    }, z.core.$strip>;
+    darkColors: z.ZodOptional<z.ZodObject<{
+        primary: z.ZodString;
+        secondary: z.ZodString;
+        accent: z.ZodString;
+        background: z.ZodString;
+        surface: z.ZodString;
+        text: z.ZodString;
+        textSecondary: z.ZodString;
+    }, z.core.$strip>>;
+    backgroundImage: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        repeat: z.ZodOptional<z.ZodEnum<{
+            repeat: "repeat";
+            "repeat-x": "repeat-x";
+            "repeat-y": "repeat-y";
+            "no-repeat": "no-repeat";
+        }>>;
+        size: z.ZodOptional<z.ZodString>;
+        position: z.ZodOptional<z.ZodString>;
+        attachment: z.ZodOptional<z.ZodEnum<{
+            scroll: "scroll";
+            fixed: "fixed";
+            local: "local";
+        }>>;
+        scale: z.ZodOptional<z.ZodNumber>;
+        animation: z.ZodOptional<z.ZodEnum<{
+            drift: "drift";
+            float: "float";
+            shimmer: "shimmer";
+            "shimmer-float": "shimmer-float";
+            none: "none";
+        }>>;
+        customAnimation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    typography: z.ZodObject<{
+        fontFamily: z.ZodObject<{
+            primary: z.ZodString;
+            secondary: z.ZodString;
+        }, z.core.$strip>;
+        scale: z.ZodObject<{
+            xs: z.ZodString;
+            sm: z.ZodString;
+            base: z.ZodString;
+            lg: z.ZodString;
+            xl: z.ZodString;
+            '2xl': z.ZodString;
+            '3xl': z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    spacing: z.ZodObject<{
+        xs: z.ZodString;
+        sm: z.ZodString;
+        md: z.ZodString;
+        lg: z.ZodString;
+        xl: z.ZodString;
+        '2xl': z.ZodString;
+    }, z.core.$strip>;
+    components: z.ZodOptional<z.ZodObject<{
+        button: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        card: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        header: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        footer: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const themeSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    colors: z.ZodObject<{
+        primary: z.ZodString;
+        secondary: z.ZodString;
+        accent: z.ZodString;
+        background: z.ZodString;
+        surface: z.ZodString;
+        text: z.ZodString;
+        textSecondary: z.ZodString;
+    }, z.core.$strip>;
+    darkColors: z.ZodOptional<z.ZodObject<{
+        primary: z.ZodString;
+        secondary: z.ZodString;
+        accent: z.ZodString;
+        background: z.ZodString;
+        surface: z.ZodString;
+        text: z.ZodString;
+        textSecondary: z.ZodString;
+    }, z.core.$strip>>;
+    backgroundImage: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        repeat: z.ZodOptional<z.ZodEnum<{
+            repeat: "repeat";
+            "repeat-x": "repeat-x";
+            "repeat-y": "repeat-y";
+            "no-repeat": "no-repeat";
+        }>>;
+        size: z.ZodOptional<z.ZodString>;
+        position: z.ZodOptional<z.ZodString>;
+        attachment: z.ZodOptional<z.ZodEnum<{
+            scroll: "scroll";
+            fixed: "fixed";
+            local: "local";
+        }>>;
+        scale: z.ZodOptional<z.ZodNumber>;
+        animation: z.ZodOptional<z.ZodEnum<{
+            drift: "drift";
+            float: "float";
+            shimmer: "shimmer";
+            "shimmer-float": "shimmer-float";
+            none: "none";
+        }>>;
+        customAnimation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    typography: z.ZodObject<{
+        fontFamily: z.ZodObject<{
+            primary: z.ZodString;
+            secondary: z.ZodString;
+        }, z.core.$strip>;
+        scale: z.ZodObject<{
+            xs: z.ZodString;
+            sm: z.ZodString;
+            base: z.ZodString;
+            lg: z.ZodString;
+            xl: z.ZodString;
+            '2xl': z.ZodString;
+            '3xl': z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    spacing: z.ZodObject<{
+        xs: z.ZodString;
+        sm: z.ZodString;
+        md: z.ZodString;
+        lg: z.ZodString;
+        xl: z.ZodString;
+        '2xl': z.ZodString;
+    }, z.core.$strip>;
+    components: z.ZodOptional<z.ZodObject<{
+        button: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        card: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        header: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+        footer: z.ZodOptional<z.ZodObject<{
+            base: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            secondary: z.ZodOptional<z.ZodString>;
+            outline: z.ZodOptional<z.ZodString>;
+            shadow: z.ZodOptional<z.ZodString>;
+            nav: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodOptional<z.ZodString>>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ThemeConfig = z.infer<typeof themeConfigSchema>;
+type ComponentStyle = z.infer<typeof componentStyleSchema>;
+interface Theme extends ThemeConfig {
+}
+
+interface ThemeContextType {
+    /** The resolved theme — `colors` reflects the active color mode. */
+    theme: Theme;
+    /** The original theme with both `colors` and `darkColors` intact. */
+    rawTheme: Theme;
+    setTheme: (theme: Theme) => void;
+    /** Current color mode setting (`'light'`, `'dark'`, or `'system'`). */
+    colorMode: ColorMode;
+    /** Switch the color mode. */
+    setColorMode: (mode: ColorMode) => void;
+    /** The actually active mode after resolving `'system'`. */
+    resolvedColorMode: 'light' | 'dark';
+}
+interface ThemeProviderProps {
+    theme: Theme;
+    children: ReactNode;
+    /** Initial color mode. Defaults to `'system'`. */
+    initialColorMode?: ColorMode;
+}
+declare const ThemeProvider: React.FC<ThemeProviderProps>;
+/**
+ * Access the current theme and color mode controls.
+ * Must be called inside a `<ThemeProvider>`.
+ */
+declare const useTheme: () => ThemeContextType;
+/**
+ * Like `useTheme`, but returns `undefined` instead of throwing when
+ * no `ThemeProvider` is present. Useful for optional-context components
+ * like `ThemeStyleInjector`.
+ */
+declare const useThemeOptional: () => ThemeContextType | undefined;
+/**
+ * Converts a Stackwright Theme to CSS custom properties.
+ * Inject these via ThemeStyleInjector or a `<style>` tag.
+ */
+declare function themeToCSSVars(theme: Theme): Record<string, string>;
+interface ThemeStyleInjectorProps {
+    /**
+     * Explicit theme override. When omitted the resolved theme from the
+     * nearest `ThemeProvider` is used automatically — this is the
+     * recommended approach so CSS vars stay in sync with color mode changes.
+     */
+    theme?: Theme;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * Wraps children in a div that injects Stackwright CSS custom properties.
+ * Place this inside a `<ThemeProvider>` and it will track color mode
+ * changes automatically.
+ */
+declare function ThemeStyleInjector({ theme: themeProp, children, className, }: ThemeStyleInjectorProps): react_jsx_runtime.JSX.Element;
+
+declare class ThemeLoader {
+    private static themes;
+    static loadThemeFromYaml(yamlContent: string): Theme;
+    static loadThemeFromFile(themeName: string): Theme;
+    static getTheme(name: string): Theme | undefined;
+    static getAllThemes(): Theme[];
+    static registerCustomTheme(theme: Theme): void;
+    static loadCustomTheme(theme: Theme): Theme;
+    private static getEmbeddedTheme;
+}
+
+/**
+ * Blocking script that reads the `sw-color-mode` cookie and applies the
+ * correct color mode attribute to `<html>` before React hydrates.
+ *
+ * Place this in `_document.tsx` `<Head>` (Pages Router) or in a `<script>`
+ * tag in `layout.tsx` (App Router). It must execute before the body is
+ * painted — intentionally render-blocking.
+ *
+ * The `data-sw-color-mode` attribute set by this script is read by
+ * `ThemeProvider`'s `systemPreference` initialiser, ensuring the first
+ * React render matches the visible state — no hydration mismatch.
+ *
+ * For return visitors (cookie exists): correct theme on first paint, zero flash.
+ * For first-time visitors with OS dark mode: one-frame flash (same as next-themes v0.2).
+ */
+declare function ColorModeScript({ fallback }: {
+    fallback?: ColorMode;
+}): react_jsx_runtime.JSX.Element;
+
+export { type ColorMode, ColorModeScript, type ComponentStyle, type Theme, type ThemeColors, type ThemeColors as ThemeColorsType, type ThemeConfig, ThemeLoader, ThemeProvider, ThemeStyleInjector, colorsSchema, componentStyleSchema, themeConfigSchema, themeSchema, themeToCSSVars, useTheme, useThemeOptional };