import { TokenColor, TokenRadius, TokenFontSize, TokenWeight } from '../index.js';

/** Re-alias of ui-tokens' TokenColor — the contrast pairs + ColorTokens key off this. */
type ColorTokenKey = TokenColor;
/**
 * Shape keys are NAMESPACED on purpose: bare scale names collide ('sm'/'lg'/'xl' are
 * both a radius AND a font-size), and EffectiveTokens flattens color+shape into one
 * record. Space is EXCLUDED — ui-tokens ships no `--mod-space-*` custom property.
 */
type ShapeTokenKey = `radius-${TokenRadius}` | `font-size-${TokenFontSize}` | `font-weight-${TokenWeight}`;
type ColorTokens = Record<ColorTokenKey, string>;
type ShapeTokens = Record<ShapeTokenKey, string>;
type ModePair<T> = {
    light: T;
    dark: T;
};
interface Palette {
    id: string;
    name: string;
    colors: ModePair<ColorTokens>;
}
/** Optional per-code decorative SVG markup for the ErrorState visual slot. Unvalidated, decorative. */
type ErrorArtMap = Record<string, string>;
interface PaletteSet {
    id: string;
    name: string;
    palettes: Palette[];
    defaultPaletteId: string;
    shape: ModePair<ShapeTokens>;
    meta?: {
        author?: string;
        version?: string;
        description?: string;
    };
    errorArt?: ErrorArtMap;
}
interface ActiveSelection {
    themeId: string;
    paletteId: string;
    mode: 'light' | 'dark' | 'system';
    overrides?: Partial<ColorTokens & ShapeTokens>;
}
type EffectiveTokens = ColorTokens & ShapeTokens;
type ContrastLevel = 'text' | 'ui';
interface ContrastPair {
    fg: ColorTokenKey;
    bg: ColorTokenKey;
    level: ContrastLevel;
}
/** A single-mode contrast failure (no palette/mode context — produced by validateContrastTokens). */
interface ContrastPairFailure {
    fg: ColorTokenKey;
    bg: ColorTokenKey;
    ratio: number;
    required: number;
}
/** A two-mode contrast failure — single-mode failure + its palette/mode coordinates. */
interface ContrastFailure extends ContrastPairFailure {
    paletteId: string;
    mode: 'light' | 'dark';
}
interface ContrastTokenReport {
    pass: boolean;
    failures: ContrastPairFailure[];
}
interface ContrastReport {
    pass: boolean;
    failures: ContrastFailure[];
}
/** Discriminated result — theme-engine defines its own (no shared Result type in the monorepo). */
type Result<T, E> = {
    ok: true;
    value: T;
} | {
    ok: false;
    error: E;
};

/** Frozen declared fg/bg set the design system renders together. validateContrast iterates THIS. */
declare const CONTRAST_PAIRS: readonly ContrastPair[];

declare class ThemeValidationError extends Error {
    readonly field: string;
    readonly detail: string;
    readonly name = "ThemeValidationError";
    readonly code: "THEME_VALIDATION";
    constructor(field: string, detail: string);
}
declare class ThemeColorFormatError extends Error {
    readonly field: string;
    readonly detail: string;
    readonly name = "ThemeColorFormatError";
    readonly code: "THEME_COLOR_FORMAT";
    constructor(field: string, detail: string);
}
declare class ThemeResolutionError extends Error {
    readonly detail: string;
    readonly name = "ThemeResolutionError";
    readonly code: "THEME_RESOLUTION";
    constructor(detail: string);
}
declare class ThemeOverrideError extends Error {
    readonly key: string;
    readonly name = "ThemeOverrideError";
    readonly code: "THEME_OVERRIDE";
    constructor(key: string);
}
type ThemeError = ThemeValidationError | ThemeColorFormatError | ThemeResolutionError | ThemeOverrideError;
/** Structural guard — matches any THEME_-coded error object. NEVER use `instanceof` across packages. */
declare function isThemeError(e: unknown): e is {
    code: string;
    message?: string;
};

declare function validatePaletteSet(pkg: unknown): Result<PaletteSet, ThemeError[]>;
/**
 * SINGLE-MODE Hard-floor checker — the shared impl + the override-persist seam.
 * Accepts any ColorTokens (an EffectiveTokens override result is a superset; extra shape keys ignored).
 */
declare function validateContrastTokens(colors: ColorTokens, pairs?: readonly ContrastPair[]): ContrastTokenReport;
declare function validateContrast(pkg: PaletteSet, pairs?: readonly ContrastPair[]): ContrastReport;

declare function resolveMode(pref: 'light' | 'dark' | 'system', systemPrefersDark: boolean): 'light' | 'dark';
/** Returns a NEW EffectiveTokens; throws ThemeOverrideError (typed) on an unknown override key. */
declare function mergeOverrides(base: EffectiveTokens, overrides?: Partial<EffectiveTokens>): EffectiveTokens;
declare function resolveActiveTheme(args: {
    themes: PaletteSet[];
    selection: ActiveSelection;
    systemPrefersDark: boolean;
}): Result<EffectiveTokens, ThemeError>;

/** Build-time static CSS for SSR/no-JS first paint. Palette-scoped; group 3 resolves system-mode with no flash. */
declare function themeToCss(pkg: PaletteSet): string;

type Rgb = [number, number, number];
/** Parse `#rgb` / `#rrggbb` (case-insensitive, trimmed) to [r,g,b] 0..255, or null. */
declare function parseHex(hex: string): Rgb | null;
/** WCAG-2.x relative luminance (sRGB). white -> 1, black -> 0. */
declare function relativeLuminance([r, g, b]: Rgb): number;
/** WCAG-2.x contrast ratio. Order-independent (auto lighter/darker). Range 1..21. */
declare function contrastRatio(a: Rgb, b: Rgb): number;

/** Apply resolved tokens to an element as inline custom properties + data attributes. Idempotent. */
declare function applyTheme(el: HTMLElement, tokens: EffectiveTokens, themeId: string, mode: 'light' | 'dark'): void;
/**
 * THE single owner of the `(prefers-color-scheme: dark)` media-query listener.
 * Returns an unsubscribe fn. No-ops + returns a noop unsubscribe under SSR (no matchMedia).
 */
declare function subscribeToSystemMode(cb: (prefersDark: boolean) => void): () => void;

export { type ActiveSelection, CONTRAST_PAIRS, type ColorTokenKey, type ColorTokens, type ContrastFailure, type ContrastLevel, type ContrastPair, type ContrastPairFailure, type ContrastReport, type ContrastTokenReport, type EffectiveTokens, type ErrorArtMap, type ModePair, type Palette, type PaletteSet, type Result, type Rgb, type ShapeTokenKey, type ShapeTokens, ThemeColorFormatError, type ThemeError, ThemeOverrideError, ThemeResolutionError, ThemeValidationError, applyTheme, contrastRatio, isThemeError, mergeOverrides, parseHex, relativeLuminance, resolveActiveTheme, resolveMode, subscribeToSystemMode, themeToCss, validateContrast, validateContrastTokens, validatePaletteSet };