@sugarcube-org/core 0.0.1-alpha.0 → 0.0.1-alpha.10

package/dist/index.d.ts

@@ -1,230 +1,1435 @@
-type Color = string;
+import { z } from 'zod';
+
+/**
+ * Directional variants for utility properties
+ */
+type DirectionalVariant = "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all";
+/**
+ * Properties-first utility configuration
+ * This is the approach where users configure utilities by CSS property
+ * Made it separate in case we want other types of configs later
+ */
+type PropertyUtilityConfig = {
+    source: string;
+    directions?: DirectionalVariant | DirectionalVariant[];
+    prefix?: string;
+    stripDuplicates?: boolean;
+};
+
+type ColorFallbackStrategy = "native" | "polyfill";
+type FluidConfig = {
+    min: number;
+    max: number;
+};
+type UserTransformsConfig = {
+    fluid?: FluidConfig;
+    colorFallbackStrategy?: ColorFallbackStrategy;
+};
+/**
+ * Configuration for transforms applied to tokens during processing (internal config)
+ */
+type TransformsConfig = {
+    fluid: FluidConfig;
+    colorFallbackStrategy: ColorFallbackStrategy;
+};
+/**
+ * Configuration for output directories (user config - optional fields)
+ */
+type UserOutputConfig = {
+    /** Output directory for CSS files */
+    css?: string;
+    /** Output directory for component files */
+    components?: string;
+    /** Attribute name for theme selectors (default: "data-theme") */
+    themeAttribute?: string;
+    /**
+     * Which context should use :root selector (default: resolver's default).
+     * Other contexts use [data-theme="contextName"].
+     */
+    defaultContext?: string;
+};
+/**
+ * Configuration for output directories (internal config - required fields)
+ */
+type OutputConfig = {
+    css: string;
+    components?: string;
+    /** Attribute name for theme selectors */
+    themeAttribute: string;
+    /** Which context uses :root selector */
+    defaultContext?: string;
+};
+/**
+ * Utilities configuration
+ * This is the approach where users configure utilities by CSS property
+ * Can be a single configuration or an array of configurations
+ */
+type UtilitiesConfig = Record<string, PropertyUtilityConfig | PropertyUtilityConfig[]>;
+/**
+ * User configuration for Sugarcube.
+ *
+ * Configuration uses the DTCG resolver format:
+ * ```ts
+ * export default {
+ *   resolver: "./tokens.resolver.json",
+ *   output: { css: "src/styles" }
+ * }
+ * ```
+ */
+interface UserConfig {
+    /**
+     * Path to the resolver.json file.
+     * Resolver defines all token sources, sets, and modifiers.
+     * Required for token processing, optional for validation-only scenarios.
+     */
+    resolver?: string;
+    transforms?: UserTransformsConfig;
+    output?: UserOutputConfig;
+    utilities?: UtilitiesConfig;
+}
+/**
+ * Internal configuration type - what code uses (complete, required fields)
+ */
+interface InternalConfig {
+    /** Path to the resolver.json file (optional for validation-only scenarios) */
+    resolver?: string;
+    transforms: TransformsConfig;
+    output: OutputConfig;
+    utilities?: UtilitiesConfig;
+}
+
+/**
+ * Base error type that all other error types extend from.
+ * Used as the foundation for all error types in the system.
+ * Provides a consistent structure for error messages across the codebase.
+ */
+type BaseError = {
+    /** A human-readable error message describing what went wrong */
+    message: string;
+};
+
+/**
+ * A token value that can either be a raw value or a reference.
+ * This is the base type for all token values in the W3C Design Token Format.
+ * @template T - The type of token (e.g., "color", "dimension", etc.)
+ */
+type TokenValue<T extends TokenType> = RawTokenValue<T> | Reference<T>;
+/**
+ * The actual value of a token without references.
+ * This represents the concrete value that will be used in the final output.
+ * @template T - The type of token (e.g., "color", "dimension", etc.)
+ */
+type RawTokenValue<T extends TokenType> = T extends SimpleTokenType ? SimpleTokenValue<T> : T extends CompositeTokenType ? CompositeTokenValue<T> : never;
+/**
+ * A reference to another token, with optional type checking.
+ * References are strings that point to other tokens in the token tree.
+ * The phantom type parameter ensures type safety when resolving references.
+ * @template T - The type of token being referenced
+ */
+type Reference<T extends TokenType = TokenType> = string & {
+    /** Phantom type for type safety during reference resolution */
+    __tokenType?: T;
+};
+/**
+ * Metadata that can be attached to any node in the token tree.
+ * This includes descriptions and custom extensions as defined in the W3C spec.
+ */
+type NodeMetadata = {
+    /** Optional description of the token or group */
+    $description?: string;
+    /** Optional custom extensions as defined in the W3C spec */
+    $extensions?: {
+        [key: string]: unknown;
+    };
+};
+/**
+ * A single token with its value and metadata.
+ * This is the basic building block of the token system.
+ */
+type Token = NodeMetadata & {
+    /** The value of the token, which can be a raw value or a reference */
+    $value: TokenValue<TokenType>;
+    /** Optional type specification, can be inherited from parent groups */
+    $type?: TokenType;
+};
+/**
+ * A group of tokens that can be nested.
+ * The type allows for:
+ * - Regular token properties (non-$ prefixed) which must be Token | TokenGroup
+ * - Metadata properties from NodeMetadata (like $description, $extensions)
+ * - $type property for type inheritance as specified in the W3C spec
+ * - undefined to support optional metadata properties
+ */
+type TokenGroup = NodeMetadata & {
+    /** Optional type specification for the group, can be inherited by child tokens */
+    $type?: TokenType;
+    /** Dynamic properties that can be either tokens, token groups, or undefined */
+    [key: string]: Token | TokenGroup | TokenType | undefined;
+};
+/**
+ * All possible token types, either simple or composite.
+ * This is the union of all supported token types in the system.
+ */
+type TokenType = SimpleTokenType | CompositeTokenType;
+/**
+ * Token types that contain a single value.
+ * These are the basic building blocks of the token system.
+ */
+type SimpleTokenType = "color" | "dimension" | "fluidDimension" | "duration" | "cubicBezier" | "fontFamily" | "fontWeight" | "number";
+/**
+ * Values for simple token types.
+ * Maps each simple token type to its corresponding value type.
+ * @template T - The type of token (e.g., "color", "dimension", etc.)
+ */
+type SimpleTokenValue<T extends SimpleTokenType = SimpleTokenType> = T extends "color" ? Color : T extends "dimension" ? Dimension : T extends "fluidDimension" ? FluidDimension : T extends "duration" ? Duration : T extends "cubicBezier" ? CubicBezier : T extends "fontFamily" ? FontFamily : T extends "fontWeight" ? FontWeight : T extends "number" ? number : never;
+/**
+ * Token types that contain multiple values or are structurally complex.
+ * These types combine multiple simple types to create more complex tokens.
+ */
+type CompositeTokenType = AlwaysDecomposedType | "border" | "shadow" | "gradient" | "transition" | StructuralCompositeType;
+/**
+ * Token types that must always be broken down into their constituent parts.
+ * These types are never used directly in CSS output.
+ */
+type AlwaysDecomposedType = "typography";
+/**
+ * Token types that define structural patterns.
+ * These types are used to define reusable patterns in the token system.
+ */
+type StructuralCompositeType = "strokeStyle";
+/**
+ * Values for composite token types.
+ * Maps each composite token type to its corresponding value type.
+ * @template T - The type of token (e.g., "typography", "border", etc.)
+ */
+type CompositeTokenValue<T extends CompositeTokenType = CompositeTokenType> = T extends "typography" ? Typography : T extends "border" ? Border : T extends "shadow" ? Shadow : T extends "gradient" ? Gradient : T extends "transition" ? Transition : T extends "strokeStyle" ? StrokeStyle : never;
+/**
+ * A color value in any valid CSS color format.
+ * This can be either:
+ * - A string that is valid in CSS color contexts (legacy format)
+ * - A W3C color object with colorSpace, components, and optional alpha/hex
+ */
+type Color = string | {
+    /** The color space - supports "oklch" and "display-p3" */
+    colorSpace: "oklch" | "display-p3";
+    /** Array of 3 numbers representing the color components */
+    components: [number, number, number];
+    /** Optional alpha value between 0 and 1 (defaults to 1 if omitted) */
+    alpha?: number;
+    /** Optional hex fallback value for compatibility */
+    hex?: string;
+};
+/**
+ * A dimensional value with a numeric value and unit.
+ * Used for measurements like width, height, spacing, etc.
+ */
 type Dimension = {
+    /** The numeric value of the dimension */
     value: number;
+    /** The unit of measurement (px or rem) */
     unit: "px" | "rem";
 };
+/**
+ * A fluid dimension that scales between min and max values.
+ * Used for responsive design tokens that need to scale with viewport size.
+ */
 type FluidDimension = {
+    /** The minimum value at the smallest viewport size */
     min: Dimension;
+    /** The maximum value at the largest viewport size */
     max: Dimension;
 };
-type Duration = string;
+/**
+ * A duration value with a numeric value and time unit.
+ * Used for animations, transitions, and other time-based values.
+ */
+type Duration = {
+    /** The numeric value of the duration */
+    value: number;
+    /** The unit of time (milliseconds or seconds) */
+    unit: "ms" | "s";
+};
+/**
+ * A cubic bezier curve defined by four control points.
+ * Used for defining custom easing functions in animations and transitions.
+ * The four numbers represent the x,y coordinates of the two control points.
+ */
 type CubicBezier = [number, number, number, number];
+/**
+ * A font family name or list of fallback fonts.
+ * Can be a single font name or an array of fonts in order of preference.
+ */
 type FontFamily = string | string[];
+/**
+ * A font weight value as either a number or semantic string.
+ * Numbers range from 100-900, strings are semantic names for common weights.
+ */
 type FontWeight = number | FontWeightString;
+/**
+ * Semantic font weight names.
+ * These are standardized names for common font weights.
+ */
 type FontWeightString = "thin" | "hairline" | "extra-light" | "ultra-light" | "light" | "normal" | "regular" | "book" | "medium" | "semi-bold" | "demi-bold" | "bold" | "extra-bold" | "ultra-bold" | "black" | "heavy" | "extra-black" | "ultra-black";
+/**
+ * Line cap style for strokes.
+ * Defines how the end of a stroke should be rendered.
+ */
 type LineCap = "round" | "butt" | "square";
-type TokenType = SimpleTokenType | CompositeTokenType;
-type SimpleTokenType = "color" | "dimension" | "fluidDimension" | "duration" | "cubicBezier" | "fontFamily" | "fontWeight" | "number";
-type CompositeTokenType = AlwaysDecomposedType | OptionallyDecomposedType | StructuralCompositeType;
-type AlwaysDecomposedType = "typography";
-type OptionallyDecomposedType = "border" | "shadow" | "gradient" | "transition";
-type StructuralCompositeType = "strokeStyle";
-type Reference<T extends TokenType = TokenType> = string & {
-    __tokenType?: T;
-};
-type TokenValue<T extends TokenType> = RawTokenValue<T> | Reference<T>;
-type RawTokenValue<T extends TokenType> = T extends SimpleTokenType ? SimpleTokenValue<T> : T extends CompositeTokenType ? CompositeTokenValue<T> : never;
-type SimpleTokenValue<T extends SimpleTokenType = SimpleTokenType> = T extends "color" ? Color : T extends "dimension" ? Dimension : T extends "fluidDimension" ? FluidDimension : T extends "duration" ? Duration : T extends "cubicBezier" ? CubicBezier : T extends "fontFamily" ? FontFamily : T extends "fontWeight" ? FontWeight : T extends "number" ? number : never;
-type CompositeTokenValue<T extends CompositeTokenType = CompositeTokenType> = T extends "typography" ? Typography : T extends "border" ? Border : T extends "shadow" ? Shadow : T extends "gradient" ? Gradient : T extends "transition" ? Transition : T extends "strokeStyle" ? StrokeStyle : never;
+/**
+ * Typography token combining font properties.
+ * This is a composite type that combines multiple font-related properties.
+ */
 type Typography = {
+    /** The font family to use */
     fontFamily: TokenValue<"fontFamily">;
+    /** The size of the font */
     fontSize: TokenValue<"dimension">;
+    /** Optional font weight */
     fontWeight?: TokenValue<"fontWeight">;
+    /** Optional letter spacing */
     letterSpacing?: TokenValue<"dimension">;
+    /** Optional line height as a multiplier */
     lineHeight?: TokenValue<"number">;
 };
+/**
+ * Transition token defining animation properties.
+ * Used to define how properties should animate between states.
+ */
 type Transition = {
+    /** How long the transition should take */
     duration: TokenValue<"duration">;
+    /** Optional delay before the transition starts */
     delay?: TokenValue<"duration">;
+    /** The easing function to use for the transition */
     timingFunction: TokenValue<"cubicBezier">;
 };
+/**
+ * Predefined stroke style keywords.
+ * These are the standard stroke styles available in CSS.
+ */
 type StrokeStyleKeyword = "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "outset" | "inset";
+/**
+ * Custom stroke style definition.
+ * Used when the predefined stroke styles are not sufficient.
+ */
 type StrokeStyleCustom = {
+    /** Array of dimensions defining the dash pattern */
     dashArray: Array<TokenValue<"dimension">>;
+    /** How the ends of the stroke should be rendered */
     lineCap: LineCap;
 };
+/**
+ * A stroke style can be either a predefined keyword or a custom definition.
+ * This allows for both simple and complex stroke styles.
+ */
 type StrokeStyle = StrokeStyleKeyword | StrokeStyleCustom;
+/**
+ * Border token combining color, width, and style.
+ * This is a composite type that defines a complete border.
+ */
 type Border = {
+    /** The color of the border */
     color: TokenValue<"color">;
+    /** The width of the border */
     width: TokenValue<"dimension">;
-    style: StrokeStyle;
+    /** The style of the border, either a stroke style or a reference to one */
+    style: StrokeStyle | Reference<"strokeStyle">;
 };
+/**
+ * A single shadow definition.
+ * This is the basic building block for shadow tokens.
+ */
 type ShadowObject = {
+    /** The color of the shadow */
     color: TokenValue<"color">;
+    /** Horizontal offset of the shadow */
     offsetX: TokenValue<"dimension">;
+    /** Vertical offset of the shadow */
     offsetY: TokenValue<"dimension">;
+    /** How much the shadow should blur */
     blur: TokenValue<"dimension">;
+    /** How much the shadow should spread */
     spread: TokenValue<"dimension">;
+    /** Whether the shadow should be inset */
     inset?: boolean;
 };
+/**
+ * A shadow can be either a single shadow or multiple shadows.
+ * Multiple shadows are rendered in order, with later shadows appearing on top.
+ */
 type Shadow = ShadowObject | ShadowObject[];
+/**
+ * A single stop in a gradient.
+ * Defines the color and position of a point in the gradient.
+ */
 type GradientStop = {
+    /** The color at this point in the gradient */
     color: TokenValue<"color">;
-    position: number;
+    /** The position of this point in the gradient (0-1) */
+    position: number | Reference<"number">;
 };
+/**
+ * A gradient is defined by a series of stops.
+ * The stops define how the gradient transitions between colors.
+ */
 type Gradient = GradientStop[];
-type TokenMetadata = {
-    $description?: string;
-    $extensions?: SugarcubeExtensions;
+
+/**
+ * Source information for a token, tracking its context and origin.
+ * This metadata helps with error reporting and token organization.
+ *
+ * Terminology aligns with DTCG Resolver Module 2025.10:
+ * - "context" = a resolved variation from a modifier (e.g., "light", "dark")
+ */
+type TokenSource = {
+    /**
+     * Optional context name for modifier variations (e.g., "dark", "light", "compact").
+     *
+     * TODO: Future enhancement - support multiple orthogonal modifiers.
+     * The DTCG spec supports multiple modifiers (e.g., theme + density), which would
+     * require changing this to: `context?: string | Record<string, string>`
+     * For example: `{ theme: "dark", density: "compact" }`
+     * This would also require updating CSS generation to produce combined selectors
+     * like `[data-theme="dark"][data-density="compact"]`.
+     */
+    context?: string;
+    /** The path to the source file containing this token */
+    sourcePath: string;
 };
-type SugarcubeExtensions = {
-    "com.sugarcube": {
-        color?: ColorMetadata;
-        fluid?: FluidMetadata;
-    };
+/**
+ * A complete token tree with context information.
+ * This represents a single token file's contents with its metadata.
+ *
+ * Terminology aligns with DTCG Resolver Module 2025.10:
+ * - "context" = a resolved variation from a modifier (e.g., "light", "dark")
+ */
+type TokenTree = {
+    /**
+     * Optional context name for modifier variations (e.g., "dark", "light", "compact").
+     *
+     * TODO: Future enhancement - support multiple orthogonal modifiers.
+     * See TokenSource.context for details.
+     */
+    context?: string;
+    /** The actual token data following the W3C design tokens format */
+    tokens: TokenGroup;
+    /** The path to the source file containing these tokens */
+    sourcePath: string;
 };
-type ColorMetadata = {
-    format: ColorFormatName;
+
+/**
+ * A resolved token with its final value.
+ * Contains both the original token data and its resolved value after reference resolution.
+ * @template T - The type of token (e.g., "color", "dimension", etc.)
+ */
+type ResolvedToken<T extends TokenType = TokenType> = NodeMetadata & {
+    /** The type of the token */
+    $type: T;
+    /** The original value of the token, which may contain references */
+    $value: RawTokenValue<T>;
+    /** The path to this token in the token tree */
+    $path: string;
+    /** Information about where this token was loaded from */
+    $source: TokenSource;
+    /** The original path before any resolution */
+    $originalPath: string;
+    /** The final resolved value after all references are resolved */
+    $resolvedValue: RawTokenValue<T>;
 };
-type FluidMetadata = {
-    viewports: {
-        min: Dimension;
-        max: Dimension;
-    };
+/**
+ * A map of resolved tokens by their lookup path.
+ * Used to store the final resolved state of all tokens in a collection.
+ * Keys are token paths, values are either resolved tokens or node metadata.
+ */
+type ResolvedTokens = {
+    /** Token path as key, resolved token or metadata as value */
+    [lookupKey: string]: ResolvedToken | NodeMetadata;
 };
-type ColorFormatName = "hex" | "rgb" | "hsl" | "p3";
-type MetadataMap = {
-    root: TokenMetadata;
-    groups: Record<string, TokenMetadata>;
-    tokens: Record<string, TokenMetadata>;
+/**
+ * Type of resolution error that occurred.
+ * - "circular": A circular reference was detected
+ * - "missing": A referenced token could not be found
+ * - "type-mismatch": A referenced token's type doesn't match the expected type
+ */
+type ResolutionErrorType = "circular" | "missing" | "type-mismatch";
+/**
+ * An error that occurred during token resolution.
+ * Extends the base error type with resolution-specific information.
+ */
+type ResolutionError = BaseError & {
+    /** The type of resolution error that occurred */
+    type: ResolutionErrorType;
+    /** The path to the token that failed resolution */
+    path: string;
+    /** Source information about where the token was loaded from */
+    source: TokenSource;
 };
-type CSSProperties<T extends TokenType> = T extends SimpleTokenType ? SimpleCSSProperties : T extends AlwaysDecomposedType ? AlwaysDecomposedProperties : T extends OptionallyDecomposedType ? OptionallyDecomposedProperties<T> : T extends StructuralCompositeType ? SimpleCSSProperties : never;
+
+/**
+ * A token that has been converted to CSS properties.
+ * Extends ResolvedToken with CSS-specific properties.
+ * @template T The type of token
+ */
+type ConvertedToken<T extends TokenType = TokenType> = ResolvedToken<T> & {
+    /** The CSS properties generated from the token */
+    $cssProperties: CSSProperties<T>;
+};
+/**
+ * A collection of converted tokens.
+ * Maps token paths to their converted values or metadata nodes.
+ */
+type ConvertedTokens = {
+    [lookupKey: string]: ConvertedToken | NodeMetadata;
+};
+/**
+ * A collection of converted tokens organized by context.
+ * Structure: context → tokens
+ *
+ * Example:
+ * {
+ *   default: { "color.primary": { ... } },
+ *   dark: { "color.primary": { ... } },
+ *   ocean: { "color.primary": { ... } }
+ * }
+ */
+type NormalizedConvertedTokens = {
+    [context: string]: ConvertedTokens;
+};
+/**
+ * CSS property types for different token types.
+ * Maps token types to their corresponding CSS property structures.
+ * @template T The type of token
+ */
+type CSSProperties<T extends TokenType> = T extends SimpleTokenType ? SimpleCSSProperties : T extends AlwaysDecomposedType ? AlwaysDecomposedProperties : T extends "border" ? CSSBorderProperties : T extends "shadow" ? CSSShadowProperties : T extends "gradient" ? CSSGradientProperties : T extends "transition" ? CSSTransitionProperties : T extends StructuralCompositeType ? SimpleCSSProperties : never;
+/**
+ * Simple CSS properties with a single value.
+ * Used for tokens that map to a single CSS property.
+ */
 type SimpleCSSProperties = {
+    /** The CSS value */
     value: string | number;
+    /** Optional feature queries for responsive values */
     featureValues?: Array<{
         query: string;
         value: string;
     }>;
 };
+/**
+ * CSS properties that are always broken down into multiple properties.
+ * Currently only used for typography tokens.
+ */
 type AlwaysDecomposedProperties = CSSTypographyProperties;
+/**
+ * CSS properties specific to typography tokens.
+ * Maps typography tokens to their corresponding CSS properties.
+ */
 type CSSTypographyProperties = {
+    /** The font family to use */
     "font-family": string;
+    /** The font size */
     "font-size": string;
+    /** The font weight */
     "font-weight"?: number | string;
+    /** The letter spacing */
     "letter-spacing"?: string;
+    /** The line height */
     "line-height"?: number | string;
 };
-type OptionallyDecomposedProperties<T extends OptionallyDecomposedType> = T extends "border" ? CSSBorderProperties : T extends "shadow" ? CSSShadowProperties : T extends "gradient" ? CSSGradientProperties : T extends "transition" ? CSSTransitionProperties : never;
+/**
+ * CSS properties for specific token types.
+ * These types represent tokens that map to single CSS properties.
+ */
+/**
+ * CSS properties for border tokens.
+ */
 type CSSBorderProperties = {
+    /** The border value */
     value: string;
-    split?: {
-        width: string;
-        style: string;
-        color: string;
-    };
 };
+/**
+ * CSS properties for shadow tokens.
+ */
 type CSSShadowProperties = {
+    /** The shadow value */
     value: string;
-    split?: CSSShadowSplitProperties | CSSShadowSplitProperties[];
-};
-type CSSShadowSplitProperties = {
-    "offset-x": string;
-    "offset-y": string;
-    "blur": string;
-    "spread": string;
-    "color": string;
-    "inset"?: "inset";
 };
+/**
+ * CSS properties for gradient tokens.
+ */
 type CSSGradientProperties = {
+    /** The gradient value */
     value: string;
-    split?: {
-        stops: Array<{
-            color: string;
-            position: string;
-        }>;
-    };
 };
+/**
+ * CSS properties for transition tokens.
+ */
 type CSSTransitionProperties = {
+    /** The transition value */
     value: string;
-    split?: {
-        "duration": string;
-        "timing-function": string;
-        "delay"?: string;
-    };
 };
-type BaseToken = TokenMetadata & {
-    $value: TokenValue<TokenType>;
+
+/**
+ * Represents a single CSS file output with its path and content
+ */
+type CSSFile = {
+    /** The path where the CSS file will be written */
+    path: string;
+    /** The CSS content to write to the file */
+    css: string;
 };
-type SelfTypedToken<T extends TokenType = TokenType> = BaseToken & {
-    $type: T;
+/**
+ * Represents multiple CSS file outputs
+ */
+type CSSFileOutput = CSSFile[];
+
+/**
+ * An error that occurred during token flattening.
+ * Extends the base error type with flattening-specific information.
+ */
+type FlattenError = BaseError & {
+    /** The path to the token that failed flattening */
+    path: string;
+    /** Source information about where the token was loaded from */
+    source: TokenSource;
 };
-type InheritedTypeToken = BaseToken;
-type Token<T extends TokenType = TokenType> = SelfTypedToken<T> | InheritedTypeToken;
-type UnresolvedToken<T extends TokenType = TokenType> = (SelfTypedToken<T> & {
-    $path: string;
-}) | (InheritedTypeToken & {
-    $path: string;
-});
-type ResolvedToken<T extends TokenType = TokenType> = UnresolvedToken<T> & {
-    $resolvedValue: RawTokenValue<T>;
+
+/**
+ * Result of loading a Sugarcube configuration file
+ */
+type LoadedConfig = {
+    /** The validated configuration */
+    config: InternalConfig;
+    /** The path to the config file that was loaded */
+    configPath: string;
 };
-type ConvertedToken<T extends TokenType = TokenType> = ResolvedToken<T> & {
-    $type: T;
-    cssProperties: CSSProperties<T>;
+/**
+ * Data structure for loading tokens from memory.
+ * Maps file paths to their token content and metadata.
+ * Used for programmatic token loading.
+ *
+ * Terminology aligns with DTCG Resolver Module 2025.10:
+ * - "context" = a resolved variation from a modifier (e.g., "light", "dark")
+ */
+type TokenMemoryData = Record<string, {
+    /**
+     * Optional context name for modifier variations (e.g., "dark", "light").
+     * See TokenSource.context for future enhancement notes.
+     */
+    context?: string;
+    /** The raw token content as a string */
+    content: string;
+}>;
+/**
+ * An error that occurred during token loading.
+ * Extends the base error type with file-specific information.
+ */
+type LoadError = BaseError & {
+    /** The file path where the error occurred */
+    file: string;
 };
-type DesignTokens = TokenGroup;
-type TokenGroup = {
-    [key: string]: Token | TokenGroup | string | undefined;
-} & TokenMetadata;
-type FlattenedTokens = {
-    [path: string]: UnresolvedToken;
+
+/**
+ * An error that occurred during token validation.
+ * Extends the base error type with token-specific information.
+ */
+type ValidationError = BaseError & {
+    /** The path to the token that failed validation */
+    path: string;
+    /** Source information about where the token was loaded from */
+    source: TokenSource;
 };
-type ResolvedTokens = {
-    [path: string]: ResolvedToken;
+
+/**
+ * Modifier metadata for CSS generation.
+ * Used to build selectors like [data-theme="dark"].
+ */
+type ModifierMeta$1 = {
+    /** The modifier name (e.g., "theme", "density") */
+    name: string;
+    /** Auto-derived CSS attribute (e.g., "data-theme", "data-density") */
+    attribute: string;
+    /** The default context name */
+    defaultContext: string;
+    /** Available non-default context names */
+    contexts: string[];
 };
-type ConvertedTokens = {
-    [path: string]: ConvertedToken;
+/**
+ * Result of running any pipeline.
+ * Contains the generated output, token trees, and any errors.
+ */
+type PipelineResult = {
+    /** The generated output (e.g. CSS files) */
+    output: CSSFileOutput;
+    /** The loaded token trees */
+    trees: TokenTree[];
+    /** Modifier metadata for CSS selector generation */
+    modifiers?: ModifierMeta$1[];
+    /** Any errors that occurred during pipeline execution */
+    errors: PipelineErrors;
 };
-type ValidationError = {
-    path: string;
-    message: string;
+/**
+ * Common error types that can occur during pipeline execution.
+ * Organizes errors by the pipeline stage where they occurred.
+ */
+type PipelineErrors = {
+    /** Errors that occurred during token loading */
+    load: LoadError[];
+    /** Errors that occurred during token flattening */
+    flatten: FlattenError[];
+    /** Errors that occurred during token validation */
+    validation: ValidationError[];
+    /** Errors that occurred during token resolution */
+    resolution: ResolutionError[];
 };
-type ResolutionError = {
-    type: "circular" | "missing" | "type-mismatch";
-    path: string;
-    message: string;
+/**
+ * Defines how tokens should be loaded and processed.
+ * - "resolver": Load from a DTCG resolver document (primary method)
+ * - "memory": Load from in-memory data (for testing/programmatic use)
+ */
+type TokenPipelineSource = {
+    type: "resolver";
+    /** Path to the .resolver.json file */
+    resolverPath: string;
+    /** Configuration for output and transforms */
+    config: InternalConfig;
+} | {
+    type: "memory";
+    /** In-memory token data */
+    data: TokenMemoryData;
+    /** Configuration for output and transforms */
+    config: InternalConfig;
 };
 
-declare function flatten(tree: DesignTokens): {
-    tokens: FlattenedTokens;
-    errors: ValidationError[];
-};
+/**
+ * Generate CSS variable files from converted tokens.
+ *
+ * @param convertedTokens - The normalized and converted tokens
+ * @param config - The configuration object
+ * @param modifiers - Optional modifier metadata for generating per-modifier attribute selectors
+ * @returns Array of CSS file outputs
+ */
+declare function generateCSSVariables(convertedTokens: NormalizedConvertedTokens, config: InternalConfig, modifiers?: ModifierMeta$1[]): Promise<CSSFileOutput>;
+
+/**
+ * Core token processing pipeline.
+ *
+ * Loads tokens from a resolver document, flattens, validates, and resolves references.
+ * Returns processed tokens ready for CSS generation.
+ */
 
-declare function resolve(tokens: FlattenedTokens): {
+/**
+ * Result of loading and resolving tokens.
+ */
+type LoadAndResolveResult = {
+    /** The loaded token trees */
+    trees: TokenTree[];
+    /** Resolved tokens after reference resolution */
     resolved: ResolvedTokens;
-    errors: ResolutionError[];
+    /** Modifier metadata for CSS selector generation */
+    modifiers: ModifierMeta$1[];
+    /** Any errors that occurred */
+    errors: PipelineResult["errors"];
+};
+/**
+ * Core token processing pipeline that handles loading, validation, and resolution.
+ *
+ * This pipeline:
+ * 1. Loads token trees from resolver document or memory
+ * 2. Flattens trees into a single structure
+ * 3. Validates tokens for correctness
+ * 4. Resolves all token references
+ *
+ * For resolver sources, loads ALL contexts (not just default) and returns
+ * modifier metadata needed for CSS selector generation.
+ *
+ * @param source - The source of tokens to process (resolver or memory)
+ * @returns Processed tokens with modifier metadata and any errors
+ *
+ * @example
+ * const result = await loadAndResolveTokens({
+ *   type: "resolver",
+ *   resolverPath: "tokens.resolver.json",
+ *   config
+ * });
+ * // result.trees - all token trees (base + modifier contexts)
+ * // result.modifiers - metadata for CSS selectors
+ */
+declare function loadAndResolveTokens(source: TokenPipelineSource): Promise<LoadAndResolveResult>;
+
+/**
+ * Normalized tokens organized by context.
+ * Structure: context → tokens
+ *
+ * This is the structure for resolver-based configs where sets merge
+ * and modifiers define contexts (light, dark, ocean, etc.).
+ *
+ * Example:
+ * {
+ *   light: { "color.primary": { $value: "#3b82f6" } },
+ *   dark: { "color.primary": { $value: "#60a5fa" } },
+ *   ocean: { "color.primary": { $value: "#0ea5e9" } }
+ * }
+ */
+type NormalizedTokens = Record<string, ResolvedTokens>;
+/**
+ * Result of the normalization process.
+ */
+type NormalizeResult = {
+    /** The normalized tokens organized by context */
+    tokens: NormalizedTokens;
+    /** The default context name */
+    defaultContext?: string;
+};
+
+type NamedUtilityValue = {
+    kind: "named";
+    value: string;
+    fraction: string | null;
+};
+type ArbitraryUtilityValue = {
+    kind: "arbitrary";
+    value: string;
 };
+type UtilityValue = NamedUtilityValue | ArbitraryUtilityValue;
+type StaticVariant = {
+    kind: "static";
+    root: string;
+};
+type FunctionalVariant = {
+    kind: "functional";
+    root: string;
+    value: UtilityValue;
+};
+type Variant = StaticVariant | FunctionalVariant;
+type StaticCandidate = {
+    kind: "static";
+    root: string;
+    variants: Variant[];
+    raw: string;
+};
+type FunctionalCandidate = {
+    kind: "functional";
+    root: string;
+    value: UtilityValue | null;
+    variants: Variant[];
+    raw: string;
+};
+type Candidate = StaticCandidate | FunctionalCandidate;
+interface StaticUtilityPattern {
+    properties: string[];
+    validator: (candidate: Candidate) => boolean;
+    generator: (candidate: Candidate) => string;
+}
 
 /**
- * Converts a set of resolved tokens to CSS-ready converted tokens
- * @param tokens - The resolved tokens to convert
- * @param metadataMap - Metadata for the token conversion process
- * @returns A record of converted tokens with kebab-case keys
- * @throws If any token has an unsupported type or is missing required properties
+ * Processes and converts token trees into CSS-ready format.
+ * This pipeline:
+ * 1. Processes trees with resolved tokens to create a unified structure
+ * 2. Normalizes tokens into a context-based organization
+ * 3. Converts tokens to their CSS representations with properties
+ *
+ *
+ * @param trees - The token trees to process
+ * @param resolved - The resolved tokens for processing
+ * @param config - The sugarcube configuration
+ * @param validationErrors - Optional array of validation errors. Tokens with validation errors will be filtered out before conversion.
+ * @returns The processed and converted tokens ready for CSS generation
+ *
+ * @example
+ * const convertedTokens = await processAndConvertTokens(trees, resolved, config);
+ * // convertedTokens = { "default": { "token.path": { $cssProperties: {...} } }, "dark": {...} }
  */
-declare function convert(tokens: ResolvedTokens, metadataMap: MetadataMap): ConvertedTokens;
+declare function processAndConvertTokens(trees: TokenTree[], resolved: ResolvedTokens, config: InternalConfig, validationErrors?: ValidationError[]): Promise<NormalizedConvertedTokens>;
 
-declare function generateCSS(tokens: ConvertedTokens, options?: {
-    splitTypes?: OptionallyDecomposedType[];
-}): Promise<string>;
+/**
+ * Resolver-based token loading for DTCG Resolver Module 2025.10
+ * https://www.designtokens.org/TR/2025.10/resolver/
+ *
+ * This module loads tokens from a resolver document, producing TokenTree[]
+ * for pipeline compatibility plus modifier metadata for CSS generation.
+ */
 
-type MetadataResult = {
-    metadata: MetadataMap;
-    errors: ValidationError[];
+/**
+ * Modifier metadata for CSS generation.
+ * Used to build selectors like [data-theme="dark"].
+ */
+type ModifierMeta = {
+    /** The modifier name (e.g., "theme", "density") */
+    name: string;
+    /** Auto-derived CSS attribute (e.g., "data-theme", "data-density") */
+    attribute: string;
+    /** The default context name */
+    defaultContext: string;
+    /** Available non-default context names */
+    contexts: string[];
+};
+/**
+ * Result of loading tokens from a resolver document.
+ */
+type ResolverLoadResult = {
+    /** Token trees for pipeline processing (base + all modifier contexts) */
+    trees: TokenTree[];
+    /** Modifier metadata for CSS selector generation */
+    modifiers: ModifierMeta[];
+    /** Any errors encountered during loading */
+    errors: LoadError[];
 };
-declare function collectMetadata(tree: DesignTokens): MetadataResult;
+/**
+ * Load tokens from a resolver document.
+ *
+ * This function:
+ * 1. Parses the resolver document
+ * 2. Processes all sets and modifier contexts
+ * 3. Returns TokenTree[] with context info for the pipeline
+ * 4. Returns modifier metadata for CSS selector generation
+ *
+ * Token trees use compound context keys for non-default modifier contexts:
+ * - Base tokens: context = undefined (maps to :root)
+ * - Modifier contexts: context = "modifierName:contextName" (e.g., "theme:dark")
+ *
+ * @param resolverPath - Path to the .resolver.json file
+ * @returns ResolverLoadResult with trees, modifier metadata, and errors
+ *
+ * @example
+ * const result = await loadFromResolver("tokens.resolver.json");
+ * // result.trees -> TokenTree[] for flatten/validate/resolve
+ * // result.modifiers -> metadata for CSS selector generation
+ */
+declare function loadFromResolver(resolverPath: string): Promise<ResolverLoadResult>;
+
+declare function generateIndex(stylesDir: string, config: InternalConfig): Promise<string>;
+declare function shouldRegenerateIndex(stylesDir: string, config: InternalConfig): Promise<boolean>;
+
+/**
+ * Writes CSS files to disk, creating directories as needed.
+ *
+ * This function:
+ * 1. Creates any missing directories in the file path
+ * 2. Adds a warning banner to prevent direct edits
+ * 3. Only writes files if the content has changed
+ * 4. Handles both single and multiple CSS file outputs
+ *
+ * @param output - Array of CSS file outputs to write
+ * @returns The original output array
+ * @throws Error if file writing fails
+ *
+ * @example
+ * await writeCSSFilesToDisk([
+ *   { path: "styles/tokens.css", css: "body { color: red; }" }
+ * ]);
+ */
+declare function writeCSSVariablesToDisk(output: CSSFileOutput): Promise<CSSFileOutput>;
+/**
+ * Writes utility CSS files to disk, creating directories as needed.
+ *
+ * This function:
+ * 1. Creates any missing directories in the file path
+ * 2. Adds a warning banner specific to utility classes
+ * 3. Only writes files if the content has changed
+ *
+ * @param output - The CSS file output to write
+ * @param config - The sugarcube configuration
+ * @returns The CSS file output that was written
+ * @throws Error if file writing fails
+ *
+ * @example
+ * await writeCSSUtilitiesToDisk(
+ *   [{ path: "src/styles/utilities/utilities.css", css: ".p-4 { padding: var(--spacing-4); }" }],
+ *   config
+ * );
+ */
+declare function writeCSSUtilitiesToDisk(output: CSSFileOutput): Promise<CSSFileOutput>;
+
+declare function findConfigFile(basePath?: string): string | null;
+declare function configFileExists(basePath?: string): boolean;
+declare function loadTSConfig(configPath: string): Promise<unknown>;
+declare function loadUserConfig(configPath?: string): Promise<{
+    config: UserConfig;
+    configPath: string;
+}>;
+declare function loadInternalConfig(configPath?: string): Promise<LoadedConfig>;
+
+/**
+ * Validates a user configuration object against the user schema.
+ *
+ * @param config - The user configuration object to validate
+ * @returns The validated user configuration
+ * @throws Error if the configuration is invalid
+ */
+declare function validateUserConfig(config: Partial<UserConfig>): UserConfig;
+/**
+ * Validates an internal configuration object against the internal schema.
+ *
+ * @param config - The internal configuration object to validate
+ * @returns The validated internal configuration
+ * @throws Error if the configuration is invalid
+ */
+declare function validateInternalConfig(config: InternalConfig): InternalConfig;
+/**
+ * Validates a user configuration object against the schema and fills in defaults.
+ *
+ * This function:
+ * 1. Validates the configuration structure using the user schema
+ * 2. Fills in default values
+ * 3. Validates the complete configuration using the internal schema
+ * 4. Returns the validated configuration with defaults filled in
+ *
+ * @param config - The user configuration object to validate
+ * @returns The validated configuration with defaults filled in
+ * @throws Error if the configuration is invalid
+ *
+ * @example
+ * const config = { resolver: "./tokens.resolver.json" };
+ * const validatedConfig = validateConfig(config);
+ */
+declare function validateConfig(config: Partial<UserConfig>): InternalConfig;
+/**
+ * Parses and validates a JSON configuration string.
+ *
+ * This function:
+ * 1. Parses the JSON string into a configuration object
+ * 2. Validates and normalizes the configuration using validateConfig
+ * 3. Returns the validated and normalized configuration
+ *
+ * @param configString - The JSON configuration string to parse and validate
+ * @returns The validated and normalized configuration
+ * @throws Error if the JSON is invalid or the configuration is invalid
+ */
+declare function parseAndValidateConfig(configString: string): InternalConfig;
 
 /**
- * This function takes a JSON string representation of a token tree and converts it
- * into a DesignTokens object.
+ * Fills in default values for any omitted fields in a user configuration.
+ *
+ * This function takes a user config (with optional fields) and
+ * returns a complete internal config (with all required fields filled in).
+ *
+ * @param userConfig - The user configuration with optional fields
+ * @returns A complete configuration with all defaults filled in
  *
- * @param {string} json - A JSON string representing a token tree structure.
- * @returns {DesignTokens} A DesignTokens object representing the parsed token structure.
- * @throws {SyntaxError} If the provided JSON string is not valid JSON.
- * @throws {TypeError} If the JSON structure doesn't match the expected DesignTokens format.
+ * @example
+ * const userConfig = {
+ *   resolver: "./tokens.resolver.json"
+ * };
+ * const completeConfig = fillDefaults(userConfig);
+ * // completeConfig.output.css === "src/styles"
  */
-declare function parseJson(json: string): DesignTokens;
+declare function fillDefaults(userConfig: UserConfig): InternalConfig;
+
+interface CSSImport {
+    path: string;
+    layer: string;
+    relativePath: string;
+}
+declare function discoverAllFiles(stylesDir: string, config: InternalConfig): Promise<CSSImport[]>;
+
+declare function generateIndexContent(files: CSSImport[]): string;
+
+declare class Instrumentation implements Disposable {
+    #private;
+    private defaultFlush;
+    constructor(defaultFlush?: (message: string) => undefined);
+    hit(label: string): void;
+    start(label: string): void;
+    end(label: string): void;
+    report(flush?: (message: string) => undefined): void;
+    [Symbol.dispose](): void;
+}
+
+type CSSObject = Record<string, string | number | undefined>;
+declare function convertConfigToUnoRules(utilitiesConfig: UtilitiesConfig, tokens: NormalizedConvertedTokens): Array<[RegExp, (m: RegExpMatchArray) => CSSObject]>;
+
+declare const SUGARCUBE_FILE = "_sugarcube.css";
+declare const GLOBAL_DIR = "global";
+declare const UTILITIES_DIR = "utilities";
+declare const VARIABLES_FILE_SUFFIX = ".variables.gen.css";
+declare const DEFAULT_VARIABLES_FILENAME = "tokens";
+declare const DEFAULT_UTILITIES_FILENAME = "utilities.gen.css";
+declare const DEFAULT_STYLES_PATH = "src/styles";
+declare const DEFAULT_DESIGN_TOKENS_PATH = "src/design-tokens";
+declare const SUGARCUBE_CONFIG_FILE = "sugarcube.config.ts";
+
+declare const DEFAULT_CONFIG: {
+    readonly output: {
+        readonly css: "src/styles";
+        readonly components: "src/components/ui";
+        readonly themeAttribute: "data-theme";
+    };
+    readonly transforms: {
+        readonly fluid: {
+            readonly min: 320;
+            readonly max: 1200;
+        };
+        readonly colorFallbackStrategy: "native";
+    };
+};
+
+declare const DEFAULT_COLLECTION = "default";
+declare const DEFAULT_CONTEXT = "default";
+
+declare const ErrorMessages: {
+    readonly LOAD: {
+        readonly NO_FILES_FOUND: (pattern: string) => string;
+        readonly INVALID_JSON: (path: string, message: string) => string;
+        readonly GLOB_ERROR: (pattern: string, error: string) => string;
+    };
+    readonly FLATTEN: {
+        readonly INVALID_TOKEN_NAME: (name: string) => string;
+        readonly MISSING_DOLLAR_PREFIX: (path: string) => string;
+        readonly INVALID_TOKEN_NESTING: (path: string) => string;
+        readonly COMPOSITE_TOKEN_MISSING_TYPE: (path: string) => string;
+        readonly CONFLICT_TOKEN_VS_GROUP: (path: string) => string;
+        readonly CONFLICT_INCOMPATIBLE_TYPES: (expected: string, received: string, path: string) => string;
+    };
+    readonly METADATA: {
+        readonly COLLECTION_ERROR: (message: string) => string;
+        readonly INVALID_EXTENSIONS: (path: string) => string;
+        readonly INVALID_DESCRIPTION: (path: string) => string;
+    };
+    readonly VALIDATE: {
+        readonly MISSING_TYPE: (path: string) => string;
+        readonly UNKNOWN_TOKEN_TYPE: (type: string, path: string) => string;
+        readonly INVALID_COLOR: (value: unknown, path: string) => string;
+        readonly INVALID_DIMENSION: (value: unknown, path: string) => string;
+        readonly INVALID_DIMENSION_UNIT: (unit: unknown, path: string) => string;
+        readonly INVALID_FONT_FAMILY: (value: unknown, path: string) => string;
+        readonly INVALID_FONT_WEIGHT: (value: unknown, path: string) => string;
+        readonly INVALID_DURATION: (value: unknown, path: string) => string;
+        readonly INVALID_DURATION_UNIT: (unit: unknown, path: string) => string;
+        readonly INVALID_CUBIC_BEZIER: (value: unknown, path: string) => string;
+        readonly INVALID_STROKE_STYLE: (value: unknown, path: string) => string;
+        readonly INVALID_STROKE_LINE_CAP: (value: unknown, path: string) => string;
+        readonly INVALID_BORDER: (value: unknown, path: string) => string;
+        readonly INVALID_SHADOW: (value: unknown, path: string) => string;
+        readonly INVALID_SHADOW_INSET: (value: unknown, path: string) => string;
+        readonly INVALID_TRANSITION: (value: unknown, path: string) => string;
+        readonly INVALID_GRADIENT: (value: unknown, path: string) => string;
+        readonly INVALID_GRADIENT_STOP_POSITION: (value: unknown, path: string) => string;
+        readonly INVALID_TYPOGRAPHY: (value: unknown, path: string) => string;
+        readonly MISSING_REQUIRED_PROPERTY: (prop: string, path: string) => string;
+        readonly INVALID_NUMBER: (value: unknown, path: string) => string;
+        readonly INVALID_ARRAY: (value: unknown, path: string) => string;
+        readonly MISSING_FLUID_CONFIG: (path: string) => string;
+        readonly INVALID_FLUID_DIMENSION: (value: unknown, path: string) => string;
+        readonly INVALID_VIEWPORT_CONFIG: (value: unknown, path: string) => string;
+        readonly MISMATCHED_UNITS: (unit1: unknown, unit2: unknown, path: string) => string;
+        readonly INVALID_FLUID_VALUE_RANGE: (path: string) => string;
+        readonly INVALID_TOKEN_TYPE: (expected: string, received: string, path: string) => string;
+        readonly INVALID_TYPE: (expected: string, value: unknown, path: string) => string;
+        readonly INVALID_ENUM_VALUE: (enumValues: unknown[], value: unknown, path: string) => string;
+    };
+    readonly RESOLVE: {
+        readonly CIRCULAR_REFERENCE: (path: string, ref: string) => string;
+        readonly REFERENCE_NOT_FOUND: (ref: string, path: string) => string;
+        readonly TYPE_MISMATCH: (path: string) => string;
+    };
+    readonly GENERATE: {
+        readonly INVALID_CSS_VALUE: (key: string, value: unknown) => string;
+        readonly INVALID_VARIABLE_NAME: (path: string, name: string) => string;
+    };
+    readonly CONFIG: {
+        readonly INVALID_JSON: (error: string) => string;
+        readonly INVALID_CONFIG: (path: string, message: string) => string;
+        readonly DUPLICATE_FILENAMES: (filename: string, paths: string[]) => string;
+        readonly FILE_NOT_FOUND: (path: string) => string;
+    };
+    readonly UTILITIES: {
+        readonly RESERVED_PREFIX: (prefix: string, tokenType: string) => string;
+        readonly DUPLICATE_CLASS_NAME: (className: string, paths: string[]) => string;
+        readonly INVALID_PROPERTY_MAPPING: (tokenType: string) => string;
+        readonly DUPLICATE_PREFIX: (prefix: string, tokenType: string) => string;
+        readonly MISSING_SOURCE: (property: string) => string;
+        readonly INVALID_SOURCE_PATTERN: (property: string, source: string) => string;
+        readonly INVALID_DIRECTIONS: (property: string) => string;
+        readonly INVALID_CONFIG_OBJECT: "utilitiesConfig must be an object";
+        readonly INVALID_TOKENS_OBJECT: "tokens must be an object";
+    };
+    readonly RESOLVER: {
+        readonly FILE_NOT_FOUND: (path: string) => string;
+        readonly INVALID_JSON: (message: string) => string;
+        readonly INVALID_REFERENCE: (ref: string) => string;
+        readonly INVALID_SOURCE_REFERENCE: (ref: string) => string;
+        readonly UNDEFINED_SET: (name: string) => string;
+        readonly UNDEFINED_MODIFIER: (name: string) => string;
+        readonly CIRCULAR_REFERENCE: (ref: string) => string;
+        readonly EXTERNAL_FILE_NOT_FOUND: (path: string) => string;
+        readonly EXTERNAL_FILE_ERROR: (path: string, message: string) => string;
+        readonly INVALID_JSON_POINTER: (pointer: string, reason: string) => string;
+        readonly DUPLICATE_NAME: (name: string) => string;
+        readonly MODIFIER_NEEDS_CONTEXTS: "Modifier must have at least one context defined.";
+        readonly MODIFIER_SINGLE_CONTEXT: "Modifier has only one context. Consider using a set instead, or add more contexts.";
+        readonly INVALID_DEFAULT: (name: string, contexts: string[]) => string;
+        readonly UNKNOWN_MODIFIER: (name: string) => string;
+        readonly INVALID_CONTEXT: (context: string, modifier: string, valid: string[]) => string;
+        readonly MISSING_REQUIRED_INPUT: (name: string) => string;
+        readonly INVALID_INPUT_TYPE: (name: string) => string;
+        readonly MALFORMED_REFERENCE: (key: string, value: string) => string;
+        readonly RESOLVER_AS_TOKEN_SOURCE: (path: string) => string;
+    };
+};
+
+/**
+ * User Config Schema - what users write (minimal, optional fields)
+ * Uses DTCG resolver format exclusively.
+ */
+declare const userConfigSchema: z.ZodObject<{
+    resolver: z.ZodOptional<z.ZodString>;
+    transforms: z.ZodOptional<z.ZodObject<{
+        fluid: z.ZodOptional<z.ZodObject<{
+            min: z.ZodNumber;
+            max: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            min: number;
+            max: number;
+        }, {
+            min: number;
+            max: number;
+        }>>;
+        colorFallbackStrategy: z.ZodOptional<z.ZodEnum<["native", "polyfill"]>>;
+    }, "strip", z.ZodTypeAny, {
+        fluid?: {
+            min: number;
+            max: number;
+        } | undefined;
+        colorFallbackStrategy?: "native" | "polyfill" | undefined;
+    }, {
+        fluid?: {
+            min: number;
+            max: number;
+        } | undefined;
+        colorFallbackStrategy?: "native" | "polyfill" | undefined;
+    }>>;
+    output: z.ZodOptional<z.ZodObject<{
+        css: z.ZodOptional<z.ZodString>;
+        components: z.ZodOptional<z.ZodString>;
+        themeAttribute: z.ZodOptional<z.ZodString>;
+        defaultContext: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        css?: string | undefined;
+        components?: string | undefined;
+        themeAttribute?: string | undefined;
+        defaultContext?: string | undefined;
+    }, {
+        css?: string | undefined;
+        components?: string | undefined;
+        themeAttribute?: string | undefined;
+        defaultContext?: string | undefined;
+    }>>;
+    utilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+        source: z.ZodString;
+        directions: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, z.ZodArray<z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, "many">]>>;
+        prefix: z.ZodOptional<z.ZodString>;
+        stripDuplicates: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }>, z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        directions: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, z.ZodArray<z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, "many">]>>;
+        prefix: z.ZodOptional<z.ZodString>;
+        stripDuplicates: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }>, "many">]>>>;
+}, "strip", z.ZodTypeAny, {
+    resolver?: string | undefined;
+    transforms?: {
+        fluid?: {
+            min: number;
+            max: number;
+        } | undefined;
+        colorFallbackStrategy?: "native" | "polyfill" | undefined;
+    } | undefined;
+    output?: {
+        css?: string | undefined;
+        components?: string | undefined;
+        themeAttribute?: string | undefined;
+        defaultContext?: string | undefined;
+    } | undefined;
+    utilities?: Record<string, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    } | {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }[]> | undefined;
+}, {
+    resolver?: string | undefined;
+    transforms?: {
+        fluid?: {
+            min: number;
+            max: number;
+        } | undefined;
+        colorFallbackStrategy?: "native" | "polyfill" | undefined;
+    } | undefined;
+    output?: {
+        css?: string | undefined;
+        components?: string | undefined;
+        themeAttribute?: string | undefined;
+        defaultContext?: string | undefined;
+    } | undefined;
+    utilities?: Record<string, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    } | {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }[]> | undefined;
+}>;
+/**
+ * Internal Config Schema - what code uses (complete, required fields)
+ */
+declare const internalConfigSchema: z.ZodObject<{
+    resolver: z.ZodOptional<z.ZodString>;
+    transforms: z.ZodObject<{
+        fluid: z.ZodObject<{
+            min: z.ZodNumber;
+            max: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            min: number;
+            max: number;
+        }, {
+            min: number;
+            max: number;
+        }>;
+        colorFallbackStrategy: z.ZodEnum<["native", "polyfill"]>;
+    }, "strip", z.ZodTypeAny, {
+        fluid: {
+            min: number;
+            max: number;
+        };
+        colorFallbackStrategy: "native" | "polyfill";
+    }, {
+        fluid: {
+            min: number;
+            max: number;
+        };
+        colorFallbackStrategy: "native" | "polyfill";
+    }>;
+    output: z.ZodObject<{
+        css: z.ZodString;
+        components: z.ZodOptional<z.ZodString>;
+        themeAttribute: z.ZodString;
+        defaultContext: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        css: string;
+        themeAttribute: string;
+        components?: string | undefined;
+        defaultContext?: string | undefined;
+    }, {
+        css: string;
+        themeAttribute: string;
+        components?: string | undefined;
+        defaultContext?: string | undefined;
+    }>;
+    utilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+        source: z.ZodString;
+        directions: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, z.ZodArray<z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, "many">]>>;
+        prefix: z.ZodOptional<z.ZodString>;
+        stripDuplicates: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }>, z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        directions: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, z.ZodArray<z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, "many">]>>;
+        prefix: z.ZodOptional<z.ZodString>;
+        stripDuplicates: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }>, "many">]>>>;
+}, "strip", z.ZodTypeAny, {
+    output: {
+        css: string;
+        themeAttribute: string;
+        components?: string | undefined;
+        defaultContext?: string | undefined;
+    };
+    transforms: {
+        fluid: {
+            min: number;
+            max: number;
+        };
+        colorFallbackStrategy: "native" | "polyfill";
+    };
+    resolver?: string | undefined;
+    utilities?: Record<string, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    } | {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }[]> | undefined;
+}, {
+    output: {
+        css: string;
+        themeAttribute: string;
+        components?: string | undefined;
+        defaultContext?: string | undefined;
+    };
+    transforms: {
+        fluid: {
+            min: number;
+            max: number;
+        };
+        colorFallbackStrategy: "native" | "polyfill";
+    };
+    resolver?: string | undefined;
+    utilities?: Record<string, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    } | {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+    }[]> | undefined;
+}>;
 
-declare function validate(tokens: FlattenedTokens, metadata: MetadataMap): ValidationError[];
+declare function isResolvedToken(token: unknown): token is ResolvedToken;
+declare function isResolvedTokenOfType<T extends TokenType>(token: unknown, type: T): token is ResolvedToken<T>;
 
-export { type MetadataMap, type OptionallyDecomposedType, type ResolutionError, type ResolvedTokens, type ValidationError, collectMetadata, convert, flatten, generateCSS, parseJson, resolve, validate };
+export { type ArbitraryUtilityValue, type CSSFileOutput, type Candidate, DEFAULT_COLLECTION, DEFAULT_CONFIG, DEFAULT_CONTEXT, DEFAULT_DESIGN_TOKENS_PATH, DEFAULT_STYLES_PATH, DEFAULT_UTILITIES_FILENAME, DEFAULT_VARIABLES_FILENAME, ErrorMessages, type FunctionalCandidate, type FunctionalVariant, GLOBAL_DIR, Instrumentation, type InternalConfig, type LoadAndResolveResult, type LoadedConfig, type ModifierMeta, type NamedUtilityValue, type NormalizeResult, type NormalizedConvertedTokens, type NormalizedTokens, type OutputConfig, type ModifierMeta$1 as PipelineModifierMeta, type PipelineResult, type ResolvedToken, type ResolvedTokens, type ResolverLoadResult, SUGARCUBE_CONFIG_FILE, SUGARCUBE_FILE, type StaticCandidate, type StaticUtilityPattern, type StaticVariant, type TokenPipelineSource, type TokenTree, UTILITIES_DIR, type UserConfig, type UserOutputConfig, type UtilitiesConfig, type UtilityValue, VARIABLES_FILE_SUFFIX, type Variant, configFileExists, convertConfigToUnoRules, discoverAllFiles, fillDefaults, findConfigFile, generateCSSVariables, generateIndex, generateIndexContent, internalConfigSchema, isResolvedToken, isResolvedTokenOfType, loadAndResolveTokens, loadFromResolver, loadInternalConfig, loadTSConfig, loadUserConfig, parseAndValidateConfig, processAndConvertTokens, shouldRegenerateIndex, userConfigSchema, validateConfig, validateInternalConfig, validateUserConfig, writeCSSUtilitiesToDisk, writeCSSVariablesToDisk };