@sugarcube-org/core 0.0.1-alpha.12 → 0.0.1-alpha.13

package/dist/index.d.ts

@@ -1,18 +1,14 @@
 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 = {
+    /** Token path pattern (e.g., "space.*", "color.primary.*"). */
     source: string;
+    /** Directional variants for spacing properties. */
     directions?: DirectionalVariant | DirectionalVariant[];
+    /** Custom prefix for generated classes. */
     prefix?: string;
+    /** Strip duplicate prefix (e.g., "text-text-quiet" → "text-quiet"). */
     stripDuplicates?: boolean;
 };
 
@@ -21,682 +17,401 @@ 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 for sugarcube.
+ * This is the shape of your config file (sugarcube.config.ts).
  *
- * Configuration uses the DTCG resolver format:
- * ```ts
- * export default {
+ * @example
+ * // sugarcube.config.ts
+ * import { defineConfig } from "@sugarcube-org/vite";
+ *
+ * export default defineConfig({
  *   resolver: "./tokens.resolver.json",
  *   output: { css: "src/styles" }
- * }
- * ```
+ * });
  */
-interface UserConfig {
+interface SugarcubeConfig {
     /**
-     * Path to the resolver.json file.
-     * Resolver defines all token sources, sets, and modifiers.
-     * Required for token processing, optional for validation-only scenarios.
+     * Path to the DTCG resolver document (.resolver.json).
+     * The resolver defines token sources, sets, and modifiers.
      */
     resolver?: string;
-    transforms?: UserTransformsConfig;
-    output?: UserOutputConfig;
+    /**
+     * Token transformation options.
+     */
+    transforms?: {
+        /**
+         * Viewport range for fluid typography calculations.
+         * Tokens with $type: "fluidDimension" will scale between min and max viewport widths.
+         */
+        fluid?: FluidConfig;
+        /**
+         * How to handle colors that can't be represented in sRGB.
+         * - "native": Use CSS color functions directly (modern browsers only)
+         * - "polyfill": Generate fallback values for older browsers
+         */
+        colorFallbackStrategy?: ColorFallbackStrategy;
+    };
+    /**
+     * Output configuration.
+     */
+    output?: {
+        /** Directory path where CSS files will be written. */
+        css?: string;
+        /** Directory path where component files will be written. */
+        components?: string;
+        /**
+         * HTML attribute used for theme selectors.
+         * @default "data-theme"
+         */
+        themeAttribute?: string;
+        /**
+         * Which context should use the :root selector.
+         * Other contexts will use [themeAttribute="contextName"] selectors.
+         * @default The resolver's default context
+         */
+        defaultContext?: string;
+    };
+    /**
+     * CSS utility class generation configuration.
+     * Maps CSS property names to token sources and options.
+     *
+     * @example
+     * utilities: {
+     *   "background-color": { source: "color.background.*" },
+     *   "padding": { source: "space.*", directions: ["x", "y", "all"] }
+     * }
+     */
     utilities?: UtilitiesConfig;
 }
 /**
- * Internal configuration type - what code uses (complete, required fields)
+ * Normalized configuration with all defaults applied.
+ * Used internally after processing SugarcubeConfig.
  */
 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
- */
+/** Reference to another token. String format: "{path.to.token}". */
 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.
- */
+/** Types that decompose into multiple CSS properties (e.g., typography → font-family, font-size, etc.). */
 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
- */
+/** CSS color string or W3C color object with colorSpace. */
 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.
- */
+/** Responsive dimension that scales between viewport sizes. */
 type FluidDimension = {
-    /** The minimum value at the smallest viewport size */
     min: Dimension;
-    /** The maximum value at the largest viewport size */
     max: Dimension;
 };
-/**
- * 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.
- */
+/** Bezier curve control points: [x1, y1, x2, y2]. */
 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";
-/**
- * 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">;
-    /** 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">;
-    /** 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[];
 
 /**
- * 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")
+ * Source information for a token, tracking where it came from.
+ * Used for error reporting and context-aware processing.
  */
 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"]`.
+     * The context name for modifier variations (e.g., "dark", "light").
+     * Aligns with DTCG Resolver Module 2025.10 terminology.
      */
     context?: string;
-    /** The path to the source file containing this token */
+    /** The file path where this token was defined. */
     sourcePath: string;
 };
 /**
- * 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")
+ * A loaded token file with its contents and source metadata.
+ * Represents a single token file after loading but before processing.
  */
 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.
+     * The context name for modifier variations (e.g., "dark", "compact").
+     * Undefined for base/default tokens.
      */
     context?: string;
-    /** The actual token data following the W3C design tokens format */
+    /** The token data following the W3C Design Tokens format. */
     tokens: TokenGroup;
-    /** The path to the source file containing these tokens */
+    /** The file path where these tokens were loaded from. */
     sourcePath: string;
 };
 
 /**
- * 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.)
+ * A token with all references resolved to their final values.
+ * Contains both the original value (which may include references)
+ * and the fully resolved value.
  */
 type ResolvedToken<T extends TokenType = TokenType> = NodeMetadata & {
-    /** The type of the token */
+    /** The token type (e.g., "color", "dimension"). */
     $type: T;
-    /** The original value of the token, which may contain references */
+    /** The original value, which may contain references like "{color.primary}". */
     $value: RawTokenValue<T>;
-    /** The path to this token in the token tree */
+    /** The dot-separated path to this token (e.g., "color.primary"). */
     $path: string;
-    /** Information about where this token was loaded from */
+    /** Source information about where this token was defined. */
     $source: TokenSource;
-    /** The original path before any resolution */
+    /** The original path before any processing. */
     $originalPath: string;
-    /** The final resolved value after all references are resolved */
+    /** The final value after all references have been resolved. */
     $resolvedValue: RawTokenValue<T>;
 };
 /**
- * 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.
+ * A collection of resolved tokens keyed by their lookup path.
+ * Includes both tokens and group metadata nodes.
  */
 type ResolvedTokens = {
-    /** Token path as key, resolved token or metadata as value */
     [lookupKey: string]: ResolvedToken | NodeMetadata;
 };
-/**
- * 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;
 };
 
-/**
- * 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": { ... } }
- * }
+ * Tokens that have been converted to CSS properties, organized by context.
+ * Each context (e.g., "default", "dark") maps to its converted tokens.
  */
 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 */
+    /** Feature queries for progressive enhancement (e.g., P3 colors). */
     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;
 };
-/**
- * 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;
 };
-/**
- * CSS properties for shadow tokens.
- */
 type CSSShadowProperties = {
-    /** The shadow value */
     value: string;
 };
-/**
- * CSS properties for gradient tokens.
- */
 type CSSGradientProperties = {
-    /** The gradient value */
     value: string;
 };
-/**
- * CSS properties for transition tokens.
- */
 type CSSTransitionProperties = {
-    /** The transition value */
     value: string;
 };
 
 /**
- * Represents a single CSS file output with its path and content
+ * A generated CSS file with its output path and content.
  */
 type CSSFile = {
-    /** The path where the CSS file will be written */
+    /** The file path where the CSS will be written. */
     path: string;
-    /** The CSS content to write to the file */
+    /** The generated CSS content. */
     css: string;
 };
 /**
- * Represents multiple CSS file outputs
+ * Array of generated CSS files from the pipeline.
+ * Each file contains a path and the CSS content to write.
  */
 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;
 };
 
-/**
- * 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;
-};
-/**
- * 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")
- */
+/** In-memory token data keyed by file path. */
 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;
 };
 
-/**
- * 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;
 };
 
 /**
- * Modifier metadata for CSS generation.
- * Used to build selectors like [data-theme="dark"].
+ * Metadata about a modifier (e.g., theme, density) for CSS generation.
+ * Used to build attribute selectors like [data-theme="dark"].
  */
 type ModifierMeta$1 = {
-    /** The modifier name (e.g., "theme", "density") */
+    /** The modifier name (e.g., "theme", "density"). */
     name: string;
-    /** Auto-derived CSS attribute (e.g., "data-theme", "data-density") */
+    /** The HTML attribute name (e.g., "data-theme", "data-density"). */
     attribute: string;
-    /** The default context name */
+    /** The default context that uses :root selector. */
     defaultContext: string;
-    /** Available non-default context names */
+    /** Available non-default context names. */
     contexts: string[];
 };
 /**
- * Result of running any pipeline.
- * Contains the generated output, token trees, and any errors.
+ * Result of running the token processing pipeline.
+ * Contains generated CSS output, processed tokens, and any errors encountered.
  */
 type PipelineResult = {
-    /** The generated output (e.g. CSS files) */
+    /** The generated CSS files ready to be written to disk. */
     output: CSSFileOutput;
-    /** The loaded token trees */
+    /** The loaded and processed token trees. */
     trees: TokenTree[];
-    /** Modifier metadata for CSS selector generation */
+    /** Modifier metadata for CSS selector generation. */
     modifiers?: ModifierMeta$1[];
-    /** Any errors that occurred during pipeline execution */
+    /** Any errors that occurred during pipeline execution. */
     errors: PipelineErrors;
 };
 /**
- * Common error types that can occur during pipeline execution.
- * Organizes errors by the pipeline stage where they occurred.
+ * Errors organized by the pipeline stage where they occurred.
  */
 type PipelineErrors = {
-    /** Errors that occurred during token loading */
+    /** Errors from loading token files. */
     load: LoadError[];
-    /** Errors that occurred during token flattening */
+    /** Errors from flattening token trees. */
     flatten: FlattenError[];
-    /** Errors that occurred during token validation */
+    /** Errors from validating token values. */
     validation: ValidationError[];
-    /** Errors that occurred during token resolution */
+    /** Errors from resolving token references. */
     resolution: ResolutionError[];
 };
 /**
- * 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)
+ * Defines the source of tokens for the pipeline.
+ *
+ * @example
+ * // Load from a DTCG resolver document
+ * const source: TokenPipelineSource = {
+ *   type: "resolver",
+ *   resolverPath: "./tokens.resolver.json",
+ *   config: internalConfig
+ * };
+ *
+ * @example
+ * // Load from in-memory data (for testing)
+ * const source: TokenPipelineSource = {
+ *   type: "memory",
+ *   data: { "tokens.json": { content: '{"color": {...}}' } },
+ *   config: internalConfig
+ * };
  */
 type TokenPipelineSource = {
     type: "resolver";
-    /** Path to the .resolver.json file */
+    /** Path to the DTCG resolver document (.resolver.json). */
     resolverPath: string;
-    /** Configuration for output and transforms */
+    /** Pipeline configuration. */
     config: InternalConfig;
 } | {
     type: "memory";
-    /** In-memory token data */
+    /** In-memory token data keyed by file path. */
     data: TokenMemoryData;
-    /** Configuration for output and transforms */
+    /** Pipeline configuration. */
     config: InternalConfig;
 };
 
@@ -710,13 +425,6 @@ type TokenPipelineSource = {
  */
 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.
- */
-
 /**
  * Result of loading and resolving tokens.
  */
@@ -757,69 +465,40 @@ type LoadAndResolveResult = {
 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" } }
- * }
+ * Resolved tokens organized by context name.
+ * Each key is a context (e.g., "default", "dark", "light")
+ * and the value is the resolved tokens for that context.
  */
 type NormalizedTokens = Record<string, ResolvedTokens>;
 /**
  * Result of the normalization process.
+ * Contains tokens organized by context and the default context name.
  */
 type NormalizeResult = {
-    /** The normalized tokens organized by context */
+    /** Tokens organized by context name. */
     tokens: NormalizedTokens;
-    /** The default context name */
+    /** The context that should use :root selector in CSS output. */
     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;
+/**
+ * Result of loading a sugarcube configuration file.
+ * Contains the validated, normalized configuration and its source path.
+ */
+type LoadedConfig = {
+    /** The validated and normalized configuration with defaults applied. */
+    config: InternalConfig;
+    /** The absolute path to the config file that was loaded. */
+    configPath: string;
 };
-type Candidate = StaticCandidate | FunctionalCandidate;
-interface StaticUtilityPattern {
-    properties: string[];
-    validator: (candidate: Candidate) => boolean;
-    generator: (candidate: Candidate) => string;
-}
+declare function findConfigFile(basePath?: string): string | null;
+declare function configFileExists(basePath?: string): boolean;
+declare function loadTSConfig(configPath: string): Promise<unknown>;
+declare function loadSugarcubeConfig(configPath?: string): Promise<{
+    config: SugarcubeConfig;
+    configPath: string;
+}>;
+declare function loadInternalConfig(configPath?: string): Promise<LoadedConfig>;
 
 /**
  * Processes and converts token trees into CSS-ready format.
@@ -841,14 +520,6 @@ interface StaticUtilityPattern {
  */
 declare function processAndConvertTokens(trees: TokenTree[], resolved: ResolvedTokens, config: InternalConfig, validationErrors?: ValidationError[]): Promise<NormalizedConvertedTokens>;
 
-/**
- * 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.
- */
-
 /**
  * Modifier metadata for CSS generation.
  * Used to build selectors like [data-theme="dark"].
@@ -877,29 +548,12 @@ type ResolverLoadResult = {
 /**
  * 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:
+ * Returns TokenTree[] with compound context keys for 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.
  *
@@ -940,15 +594,6 @@ declare function writeCSSVariablesToDisk(output: CSSFileOutput): Promise<CSSFile
  */
 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.
  *
@@ -956,7 +601,7 @@ declare function loadInternalConfig(configPath?: string): Promise<LoadedConfig>;
  * @returns The validated user configuration
  * @throws Error if the configuration is invalid
  */
-declare function validateUserConfig(config: Partial<UserConfig>): UserConfig;
+declare function validateSugarcubeConfig(config: Partial<SugarcubeConfig>): SugarcubeConfig;
 /**
  * Validates an internal configuration object against the internal schema.
  *
@@ -968,12 +613,6 @@ 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
@@ -982,15 +621,10 @@ declare function validateInternalConfig(config: InternalConfig): InternalConfig;
  * const config = { resolver: "./tokens.resolver.json" };
  * const validatedConfig = validateConfig(config);
  */
-declare function validateConfig(config: Partial<UserConfig>): InternalConfig;
+declare function validateConfig(config: Partial<SugarcubeConfig>): 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
@@ -1013,7 +647,7 @@ declare function parseAndValidateConfig(configString: string): InternalConfig;
  * const completeConfig = fillDefaults(userConfig);
  * // completeConfig.output.css === "src/styles"
  */
-declare function fillDefaults(userConfig: UserConfig): InternalConfig;
+declare function fillDefaults(userConfig: SugarcubeConfig): InternalConfig;
 
 interface CSSImport {
     path: string;
@@ -1035,15 +669,6 @@ declare class Instrumentation implements Disposable {
     [Symbol.dispose](): void;
 }
 
-/**
- * Performance monitor for debugging Vite dev server performance.
- * Enable with: SUGARCUBE_PERF=1 pnpm dev
- *
- * Tracks:
- * - File watcher activity and frequency
- * - Memory usage changes over time
- * - Module graph size during operations
- */
 declare class PerfMonitor implements Disposable {
     #private;
     private defaultFlush;
@@ -1190,10 +815,6 @@ declare const ErrorMessages: {
     };
 };
 
-/**
- * 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<{
@@ -1321,9 +942,6 @@ declare const userConfigSchema: z.ZodObject<{
         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<{
@@ -1452,7 +1070,625 @@ declare const internalConfigSchema: z.ZodObject<{
     }[]> | undefined;
 }>;
 
+/**
+ * Name schema for sets, modifiers, and contexts.
+ * Names MUST NOT:
+ * - Start with '$' (reserved prefix per DTCG spec)
+ * - Contain '{' or '}' (used in reference syntax)
+ * - Contain '.' (used as path separator in references)
+ */
+declare const nameSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
+/**
+ * Reference object schema.
+ * The $ref property uses JSON Pointer syntax for same-document references
+ * or file paths for external references.
+ */
+declare const referenceObjectSchema: z.ZodObject<{
+    $ref: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    $ref: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    $ref: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+/**
+ * Source schema - either a reference or inline token group.
+ * We use z.unknown() for inline tokens since we don't need to validate
+ * token structure at the resolver level.
+ */
+declare const sourceSchema: z.ZodUnion<[z.ZodObject<{
+    $ref: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    $ref: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    $ref: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+/**
+ * Set definition schema for root-level sets map.
+ */
+declare const setDefinitionSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    sources: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        $ref: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    sources: (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+    description?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    sources: (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+    description?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>;
+/**
+ * Modifier contexts schema.
+ * Each key is a context name, value is an array of sources.
+ */
+declare const modifierContextsSchema: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodObject<{
+    $ref: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    $ref: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    $ref: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">>;
+/**
+ * Modifier definition schema for root-level modifiers map.
+ */
+declare const modifierDefinitionSchema: z.ZodEffects<z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    contexts: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        $ref: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">>;
+    default: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    contexts: Record<string, (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    contexts: Record<string, (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>, {
+    contexts: Record<string, (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    contexts: Record<string, (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>;
+/**
+ * Inline set schema for resolutionOrder.
+ */
+declare const inlineSetSchema: z.ZodObject<{
+    type: z.ZodLiteral<"set">;
+    name: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
+    sources: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        $ref: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">;
+    description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "set";
+    sources: (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+    description?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    name: string;
+    type: "set";
+    sources: (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+    description?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>;
+/**
+ * Inline modifier schema for resolutionOrder.
+ */
+declare const inlineModifierSchema: z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"modifier">;
+    name: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
+    contexts: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        $ref: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">>;
+    description: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "modifier";
+    contexts: Record<string, (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    name: string;
+    type: "modifier";
+    contexts: Record<string, (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>, {
+    name: string;
+    type: "modifier";
+    contexts: Record<string, (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    name: string;
+    type: "modifier";
+    contexts: Record<string, (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>;
+/**
+ * Resolution order item schema.
+ * Can be a reference, inline set, or inline modifier.
+ */
+declare const resolutionOrderItemSchema: z.ZodUnion<[z.ZodObject<{
+    $ref: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    $ref: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    $ref: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
+    type: z.ZodLiteral<"set">;
+    name: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
+    sources: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        $ref: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">;
+    description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "set";
+    sources: (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+    description?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    name: string;
+    type: "set";
+    sources: (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+    description?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>, z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"modifier">;
+    name: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
+    contexts: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        $ref: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">>;
+    description: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "modifier";
+    contexts: Record<string, (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    name: string;
+    type: "modifier";
+    contexts: Record<string, (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>, {
+    name: string;
+    type: "modifier";
+    contexts: Record<string, (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    name: string;
+    type: "modifier";
+    contexts: Record<string, (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>]>;
+/**
+ * Root-level sets map schema.
+ */
+declare const setsMapSchema: z.ZodRecord<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>, z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    sources: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        $ref: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    sources: (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+    description?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    sources: (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+    description?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>>;
+/**
+ * Root-level modifiers map schema.
+ */
+declare const modifiersMapSchema: z.ZodRecord<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>, z.ZodEffects<z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    contexts: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        $ref: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">>;
+    default: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    contexts: Record<string, (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    contexts: Record<string, (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>, {
+    contexts: Record<string, (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}, {
+    contexts: Record<string, (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+    description?: string | undefined;
+    default?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+}>>;
+declare const resolverDocumentSchema: z.ZodObject<{
+    version: z.ZodLiteral<"2025.10">;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    sets: z.ZodOptional<z.ZodRecord<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        sources: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+            $ref: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">;
+        $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        sources: (z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+        description?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }, {
+        sources: (z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+        description?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }>>>;
+    modifiers: z.ZodOptional<z.ZodRecord<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>, z.ZodEffects<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        contexts: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodObject<{
+            $ref: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">>;
+        default: z.ZodOptional<z.ZodString>;
+        $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        contexts: Record<string, (z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }, {
+        contexts: Record<string, (z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }>, {
+        contexts: Record<string, (z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }, {
+        contexts: Record<string, (z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }>>>;
+    resolutionOrder: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        $ref: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
+        type: z.ZodLiteral<"set">;
+        name: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
+        sources: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+            $ref: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">;
+        description: z.ZodOptional<z.ZodString>;
+        $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        type: "set";
+        sources: (z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+        description?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }, {
+        name: string;
+        type: "set";
+        sources: (z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+        description?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }>, z.ZodEffects<z.ZodObject<{
+        type: z.ZodLiteral<"modifier">;
+        name: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
+        contexts: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodObject<{
+            $ref: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">>;
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodString>;
+        $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        type: "modifier";
+        contexts: Record<string, (z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }, {
+        name: string;
+        type: "modifier";
+        contexts: Record<string, (z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }>, {
+        name: string;
+        type: "modifier";
+        contexts: Record<string, (z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }, {
+        name: string;
+        type: "modifier";
+        contexts: Record<string, (z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }>]>, "many">;
+    $schema: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    $defs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    version: "2025.10";
+    resolutionOrder: (z.objectOutputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | {
+        name: string;
+        type: "set";
+        sources: (z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+        description?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    } | {
+        name: string;
+        type: "modifier";
+        contexts: Record<string, (z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    })[];
+    name?: string | undefined;
+    description?: string | undefined;
+    sets?: Record<string, {
+        sources: (z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+        description?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }> | undefined;
+    modifiers?: Record<string, {
+        contexts: Record<string, (z.objectOutputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }> | undefined;
+    $schema?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+    $defs?: Record<string, unknown> | undefined;
+}, {
+    version: "2025.10";
+    resolutionOrder: (z.objectInputType<{
+        $ref: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | {
+        name: string;
+        type: "set";
+        sources: (z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+        description?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    } | {
+        name: string;
+        type: "modifier";
+        contexts: Record<string, (z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    })[];
+    name?: string | undefined;
+    description?: string | undefined;
+    sets?: Record<string, {
+        sources: (z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[];
+        description?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }> | undefined;
+    modifiers?: Record<string, {
+        contexts: Record<string, (z.objectInputType<{
+            $ref: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | Record<string, unknown>)[]>;
+        description?: string | undefined;
+        default?: string | undefined;
+        $extensions?: Record<string, unknown> | undefined;
+    }> | undefined;
+    $schema?: string | undefined;
+    $extensions?: Record<string, unknown> | undefined;
+    $defs?: Record<string, unknown> | undefined;
+}>;
+
 declare function isResolvedToken(token: unknown): token is ResolvedToken;
 declare function isResolvedTokenOfType<T extends TokenType>(token: unknown, type: T): token is ResolvedToken<T>;
 
-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, PerfMonitor, 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, clearMatchCache, 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 };
+/**
+ * Check if an object is a reference (has $ref property).
+ */
+declare function isReference(value: unknown): value is {
+    $ref: string;
+};
+/**
+ * Type guard for inline set in resolutionOrder.
+ */
+declare function isInlineSet(item: unknown): item is {
+    type: "set";
+    name: string;
+    sources: unknown[];
+};
+/**
+ * Type guard for inline modifier in resolutionOrder.
+ */
+declare function isInlineModifier(item: unknown): item is {
+    type: "modifier";
+    name: string;
+    contexts: Record<string, unknown[]>;
+    default?: string;
+};
+
+export { type CSSFileOutput, DEFAULT_COLLECTION, DEFAULT_CONFIG, DEFAULT_CONTEXT, DEFAULT_DESIGN_TOKENS_PATH, DEFAULT_STYLES_PATH, DEFAULT_UTILITIES_FILENAME, DEFAULT_VARIABLES_FILENAME, ErrorMessages, GLOBAL_DIR, Instrumentation, type InternalConfig, type LoadAndResolveResult, type LoadedConfig, type ModifierMeta, type NormalizeResult, type NormalizedConvertedTokens, type NormalizedTokens, type OutputConfig, PerfMonitor, type ModifierMeta$1 as PipelineModifierMeta, type PipelineResult, type ResolvedToken, type ResolvedTokens, type ResolverLoadResult, SUGARCUBE_CONFIG_FILE, SUGARCUBE_FILE, type SugarcubeConfig, type TokenPipelineSource, type TokenTree, UTILITIES_DIR, type UtilitiesConfig, VARIABLES_FILE_SUFFIX, clearMatchCache, configFileExists, convertConfigToUnoRules, discoverAllFiles, fillDefaults, findConfigFile, generateCSSVariables, generateIndexContent, inlineModifierSchema, inlineSetSchema, internalConfigSchema, isInlineModifier, isInlineSet, isReference, isResolvedToken, isResolvedTokenOfType, loadAndResolveTokens, loadFromResolver, loadInternalConfig, loadSugarcubeConfig, loadTSConfig, modifierContextsSchema, modifierDefinitionSchema, modifiersMapSchema, nameSchema, parseAndValidateConfig, processAndConvertTokens, referenceObjectSchema, resolutionOrderItemSchema, resolverDocumentSchema, setDefinitionSchema, setsMapSchema, sourceSchema, userConfigSchema, validateConfig, validateInternalConfig, validateSugarcubeConfig, writeCSSUtilitiesToDisk, writeCSSVariablesToDisk };