@remotex-labs/xbuild 2.3.2 → 2.4.1

package/dist/index.d.ts

@@ -3,8 +3,8 @@
  * DO NOT EDIT MANUALLY.
  */
 
-import ts, { CompilerOptions, DiagnosticCategory, IScriptSnapshot, LanguageService, ParsedCommandLine, ResolvedModuleWithFailedLookupLocations, SourceFile } from 'typescript';
 import { BuildOptions, BuildResult, Loader, Message, OnEndResult, OnLoadArgs, OnLoadResult, OnResolveArgs, OnResolveResult, OnStartResult, PartialMessage, Platform, PluginBuild } from 'esbuild';
+import ts, { CompilerOptions, DiagnosticCategory, IScriptSnapshot, LanguageService, ParsedCommandLine, ResolvedModuleWithFailedLookupLocations, SourceFile } from 'typescript';
 import { IncomingMessage, ServerResponse } from 'http';
 import { ResolveMetadataInterface as xMapResolveMetadataInterface, ResolveOptionsInterface } from '@remotex-labs/xmap';
 import { Options } from 'yargs';
@@ -348,27 +348,36 @@ declare class BuildService {
      */
     typeChack(): Promise<Record<string, DiagnosticInterface[]>>;
     /**
-     * Executes the build process for all or specific variants.
+     * Executes the build process for all or specific variants,
+     * respecting `dependOn` ordering and running independent variants in parallel.
      *
      * @param names - Optional array of variant names to build (builds all if omitted)
      *
      * @returns Promise resolving to a map of variant names to their enhanced build results
      *
+     * @throws xBuildError - When a circular dependency is detected before any build starts
      * @throws AggregateError - When any variant build fails, containing all error details
      *
      * @remarks
      * The build process:
-     * 1. Filters variants if specific names are provided
-     * 2. Builds all variants in parallel
-     * 3. Collects results and errors from each variant
-     * 4. Enhances build results with additional metadata
-     * 5. Aggregates errors if any builds failed
-     * 6. Throws AggregateError if errors occurred
+     * 1. Validates the dependency graph — throws immediately on circular deps
+     * 2. Launches all requested variants concurrently
+     * 3. Each variant awaits its `dependOn` dependencies before running
+     * 4. Collects results and errors from each variant without stopping others
+     * 5. Enhances build results with additional metadata
+     * 6. Throws AggregateError if any builds failed
+     *
+     * **Dependency resolution**:
+     * - `dependOn` variants always finish before the dependent variant starts
+     * - A shared dependency (e.g. two variants both depending on `types`) builds
+     *   only once — subsequent dependents await the same running promise
+     * - Independent variants run fully in parallel
      *
      * **Error handling**:
      * - Build failures don't stop other variants from building
-     * - All errors are collected and thrown together after all builds are complete
-     * - Supports both esbuild errors and generic JavaScript errors
+     * - All errors are collected into {@link BuildTreeInterface.errors} and thrown
+     *   together after all builds complete
+     * - Supports both esbuild-specific errors and generic JavaScript errors
      *
      * **Result enhancement**:
      * Build results are processed by {@link enhancedBuildResult} to provide
@@ -392,22 +401,21 @@ declare class BuildService {
      * // Only production and staging variants are built
      * ```
      *
-     * @example Handle individual variant errors
+     * @example With dependency ordering
      * ```ts
-     * try {
-     *   await buildService.build();
-     * } catch (error) {
-     *   if (error instanceof AggregateError) {
-     *     console.error(`${error.errors.length} variants failed`);
-     *   }
-     * }
+     * // Given: main dependOn shared, shared dependOn types
+     * // Build order: types → shared → main (dependencies first)
+     * const results = await buildService.build();
      * ```
      *
+     * @see {@link buildVariant} for per-variant execution and caching logic
+     * @see {@link BuildTreeInterface}
      * @see {@link enhancedBuildResult}
      * @see {@link BuildResultInterface}
      * @see {@link VariantService.build}
+     * @see {@link validateDependencies} for circular dependency detection
      *
-     * @since 2.0.0
+     * @since 2.4.0
      */
     build(names?: Array<string>): Promise<Record<string, BuildResultInterface>>;
     /**
@@ -504,778 +512,1167 @@ declare class BuildService {
      * @since 2.0.0
      */
     private parseVariants;
-}
-/**
- * Represents a cached TypeScript language service instance with reference counting for shared resource management.
- * Enables multiple consumers to share the same language service while tracking active usage through reference counts.
- *
- * @remarks
- * This interface is used internally by {@link TypescriptService} to implement a caching strategy that prevents
- * duplicate language service instances for the same configuration file. The lifecycle follows these rules:
- * - When a new service is created, `refCount` starts at 1
- * - Each additional consumer increments `refCount`
- * - Calling dispose decrements `refCount`
- * - When `refCount` reaches 0, the service is disposed and removed from cache
- *
- * The cached data includes all components needed to maintain a fully functional TypeScript compiler instance:
- * compiled configuration, language service host, and the language service itself.
- *
- * @example
- * ```ts
- * const cached: CachedServiceInterface = {
- *   config: parsedConfig,
- *   host: languageHost,
- *   service: tsLanguageService,
- *   refCount: 1
- * };
- *
- * // Another consumer acquires the same service
- * cached.refCount++; // Now 2
- *
- * // Consumers finish and dispose
- * cached.refCount--; // Now 1
- * cached.refCount--; // Now 0, triggers cleanup
- * ```
- *
- * @see {@link TypescriptService}
- * @see {@link LanguageHostService}
- *
- * @since 2.0.0
- */
-interface CachedServiceInterface {
     /**
-     * Number of active consumers currently using this cached language service instance.
+     * Returns the normalized `dependOn` list for a variant.
      *
-     * @remarks
-     * This counter tracks how many TypeScript service instances are sharing this cached language service.
-     * When it reaches zero, the service can be safely disposed of and removed from the cache.
+     * @param variantName - The variant to look up
      *
-     * @since 2.0.0
-     */
-    refCount: number;
-    /**
-     * Language service host managing file system operations and compiler options for this instance.
-     * @since 2.0.0
-     */
-    host: LanguageHostService;
-    /**
-     * TypeScript language service providing type checking, analysis, and compilation capabilities.
-     * @since 2.0.0
-     */
-    service: LanguageService;
-    /**
-     * Parsed TypeScript configuration including compiler options, file names, and project references.
+     * @returns Array of dependency variant names, empty if none defined
      *
      * @remarks
-     * This configuration is reloaded when the `tsconfig.json` file changes, ensuring the cached
-     * service stays synchronized with the project's compilation settings.
+     * Normalizes the `dependOn` field from the variant configuration into
+     * a consistent array form, since the field accepts either a single
+     * string or an array of strings.
      *
-     * @since 2.0.0
+     * @see {@link buildVariant}
+     * @see {@link validateDependencies}
+     *
+     * @since 2.4.0
      */
-    config: ParsedCommandLine;
-}
-/**
- * Represents formatted diagnostic information from TypeScript compilation, including errors, warnings, and suggestions.
- * Provides a simplified interface for displaying compiler messages with optional source location details.
- *
- * @remarks
- * This interface normalizes TypeScript's diagnostic format into a structure suitable for display in logs,
- * editor integrations, or build output. All location information (file, line, column) is optional because
- * some diagnostics apply globally or lack specific source positions.
- *
- * Line and column numbers are 1-indexed to match standard editor conventions, even though TypeScript
- * internally uses 0-indexed positions.
- *
- * @example
- * ```ts
- * const diagnostic: DiagnosticInterface = {
- *   file: 'src/index.ts',
- *   line: 42,
- *   column: 15,
- *   code: 2304,
- *   message: "Cannot find name 'unknownVariable'."
- * };
- *
- * console.log(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column}`);
- * console.log(`TS${diagnostic.code}: ${diagnostic.message}`);
- * ```
- *
- * @see {@link TypescriptService.check}
- * @see {@link TypescriptService.formatDiagnostic}
- *
- * @since 2.0.0
- */
-interface DiagnosticInterface {
+    private getDependOn;
     /**
-     * File path where the diagnostic occurred.
+     * Validates the dependency graph for all or specific variants before building starts.
      *
-     * @remarks
-     * Optional because some diagnostics are configuration-level errors that don't relate to a specific file.
+     * @param names - Optional subset of variant names to validate (validates all if omitted)
      *
-     * @since 2.0.0
-     */
-    file?: string;
-    /**
-     * Line number where the diagnostic occurred, 1-indexed.
+     * @throws xBuildError - When a circular dependency is detected, with the full cycle
+     * path included in the message (e.g. `Circular dependency detected: main → shared → main`)
      *
      * @remarks
-     * Optional because diagnostics without source location (like config errors) won't have line information.
-     * When present, this value is 1-indexed to match standard editor conventions.
+     * Performs a depth-first traversal of the dependency graph using two sets:
+     * - `visited` — variants fully processed, skipped on revisit
+     * - `inStack` — variants in the current traversal path, used to detect cycles
      *
-     * @since 2.0.0
+     * Dependencies that exist in `dependOn` but have no matching variant instance
+     * in {@link variants} are silently skipped.
+     *
+     * Called by {@link build} before any variant starts, ensuring the entire
+     * graph is valid before any work begins.
+     *
+     * @see {@link build}
+     * @see {@link getDependOn}
+     *
+     * @since 2.4.0
      */
-    line?: number;
+    private validateDependencies;
     /**
-     * Column number where the diagnostic occurred, 1-indexed.
+     * Executes the build for a single variant after all its dependencies resolve.
+     *
+     * @param name - Variant name to build
+     * @param ctx - Isolated build context for this {@link build} invocation
      *
      * @remarks
-     * Optional because diagnostics without source location won't have column information.
-     * When present, this value is 1-indexed to match standard editor conventions.
+     * Called exclusively by {@link buildVariant} after the promise is registered
+     * in {@link BuildTreeInterface.cache}, preventing re-entry.
      *
-     * @since 2.0.0
+     * Awaits all `dependOn` dependencies concurrently via `Promise.all` before
+     * running the variant. Dependencies missing from {@link variants} are silently skipped.
+     *
+     * Errors are pushed into {@link BuildTreeInterface.errors} rather than thrown,
+     * so all variants attempt to build even if a sibling fails. Handles both
+     * esbuild-specific errors via {@link isBuildResultError} and generic JavaScript errors.
+     *
+     * @see {@link buildVariant}
+     * @see {@link getDependOn}
+     * @see {@link isBuildResultError}
+     * @see {@link BuildTreeInterface}
+     * @see {@link enhancedBuildResult}
+     *
+     * @since 2.4.0
      */
-    column?: number;
+    private executeBuild;
     /**
-     * TypeScript diagnostic code identifying the specific error or warning type.
+     * Builds a single variant, first awaiting any `dependOn` dependencies.
+     *
+     * @param name - Variant name to build
+     * @param ctx - Isolated build context for this {@link build} invocation,
+     * carrying the promise cache, error list, and results map
+     *
+     * @returns Promise that resolves when the variant and all its dependencies finish
      *
      * @remarks
-     * Optional because not all diagnostics have associated error codes. When present, this can be used
-     * to look up detailed documentation or implement diagnostic-specific handling.
+     * Stores its promise in {@link BuildTreeInterface.cache} on first call so any
+     * subsequent caller depending on the same variant awaits the already-running
+     * promise rather than triggering a duplicate build.
      *
-     * @example
-     * Common codes include 2304 (cannot find name), 2322 (type not assignable), 2307 (cannot find module).
+     * Delegates actual execution to {@link executeBuild} after registering the promise,
+     * ensuring the cache is populated before any async work begins.
      *
-     * @since 2.0.0
+     * @see {@link build}
+     * @see {@link executeBuild}
+     * @see {@link BuildTreeInterface}
+     *
+     * @since 2.4.0
      */
-    code?: number;
+    private buildVariant;
+}
+/**
+ * Options used to reload the build service configuration.
+ *
+ * @remarks
+ * These options control how configuration reload behaves:
+ * - `config` replaces the current build configuration
+ * - `clearCache` clears cached file and TypeScript language service state before reloading
+ *
+ * @since 2.3.0
+ */
+interface ReloadOptionsInterface {
     /**
-     * Human-readable diagnostic message describing the error, warning, or suggestion.
+     * Optional new configuration to replace the current one.
      *
      * @remarks
-     * This message is flattened from TypeScript's potentially nested diagnostic message structure
-     * using newline separators for multi-line messages.
+     * When provided, the build service reloads using this configuration
+     * before recalculating variants.
      *
-     * @since 2.0.0
+     * @since 2.3.0
      */
-    message: string;
+    config?: PartialBuildConfigType;
     /**
-     * Category of the diagnostic indicating its severity level.
+     * Whether to clear cached files and TypeScript language service state before reloading.
      *
      * @remarks
-     * Determines how the diagnostic should be treated and displayed. TypeScript uses this to distinguish
-     * between different severity levels:
-     * - `DiagnosticCategory.Error` (1): Compilation-blocking errors
-     * - `DiagnosticCategory.Warning` (0): Non-blocking warnings
-     * - `DiagnosticCategory.Suggestion` (2): Code improvement suggestions
-     * - `DiagnosticCategory.Message` (3): Informational messages
-     *
-     * This property is essential for filtering diagnostics by severity and determining whether
-     * a build should fail or continue.
-     *
-     * @example
-     * ```ts
-     * if (diagnostic.category === DiagnosticCategory.Error) {
-     *   console.error(`Error: ${diagnostic.message}`);
-     *   process.exit(1);
-     * }
-     * ```
+     * When enabled, cached file tracking and language service state are reset
+     * before the configuration is reloaded.
      *
-     * @since 2.0.0
+     * @since 2.3.0
      */
-    category: DiagnosticCategory;
+    clearCache?: boolean;
 }
 /**
- * Implements a TypeScript Language Service host with file snapshot caching and module resolution.
+ * Isolated state container for a single {@link BuildService.build} invocation.
  *
  * @remarks
- * The `LanguageHostService` implements the {@link ts.LanguageServiceHost} interface to provide
- * TypeScript's language service with file system access, file snapshots, and compiler configuration.
- *
- * @example
- * ```ts
- * // Initialize with compiler options
- * const host = new LanguageHostService({
- *   target: ts.ScriptTarget.ES2020,
- *   module: ts.ModuleKind.ESNext,
- *   paths: {
- *     '@utils/*': ['src/utils/*'],
- *     '@components/*': ['src/components/*']
- *   }
- * });
- *
- * // Track files for analysis
- * host.touchFile('src/index.ts');
- * host.touchFiles(['src/utils.ts', 'src/types.ts']);
- *
- * // Get file snapshots for language service
- * const snapshot = host.getScriptSnapshot('src/index.ts');
+ * Created fresh on every `build()` call to ensure concurrent watch-mode
+ * rebuilds cannot share or overwrite each other's state.
  *
- * // Resolve module imports
- * const resolved = host.resolveModuleName('@utils/helpers', 'src/index.ts');
- *
- * // Check for path aliases
- * const hasAliases = host.aliasRegex !== undefined;
- *
- * // Update configuration
- * host.options = { target: ts.ScriptTarget.ES2022 };
- * ```
+ * Passed through {@link BuildService.buildVariant} to carry the promise
+ * cache, accumulated errors, and collected results across the full
+ * dependency graph traversal.
  *
- * @see {@link ts.LanguageServiceHost} for the implemented interface specification
- * @see {@link FilesModel} for file snapshot caching implementation
+ * @see {@link BuildService.build}
+ * @see {@link BuildService.buildVariant}
  *
- * @since 2.0.0
+ * @since 2.4.0
  */
-declare class LanguageHostService implements ts.LanguageServiceHost {
-    private compilerOptions;
+interface BuildTreeInterface {
     /**
-     * Reference to TypeScript's system interface for file operations.
+     * Promise cache keyed by variant name.
      *
      * @remarks
-     * Static reference to `ts.sys` that provides abstracted file system operations
-     * (read, write, directory traversal) compatible with different environments (Node.js, browsers, etc.).
-     * Used for all file I/O operations in this service to maintain platform independence.
-     *
-     * @see {@link ts.sys}
+     * Ensures each variant builds exactly once per `build()` call.
+     * Subsequent callers depending on the same variant await the
+     * already-running promise instead of triggering a duplicate build.
      *
-     * @since 2.0.0
+     * @since 2.4.0
      */
-    private static readonly sys;
+    cache: Map<string, Promise<void>>;
     /**
-     * Cached regular expression for matching import/export statements with path aliases.
+     * Accumulated build errors across all variants.
      *
      * @remarks
-     * Compiled from `compilerOptions.paths` to efficiently detect imports using path aliases.
-     * Regenerated when compiler options change. Undefined if no path aliases are configured.
-     *
-     * Used by tools that need to identify which import statements use aliases for proper
-     * handling during transformation or bundling.
+     * Errors are pushed here rather than thrown immediately, so all
+     * variants attempt to build even if a sibling fails. Thrown together
+     * as an `AggregateError` after all builds complete.
      *
-     * @see {@link generateAliasRegex} for pattern generation
-     *
-     * @since 2.0.0
+     * @since 2.4.0
      */
-    private alias;
+    errors: Array<Error>;
     /**
-     * Cache for resolved module specifiers.
+     * Collected build results keyed by variant name.
      *
      * @remarks
-     * Stores the absolute resolved file path for each module name so repeated lookups
-     * do not trigger TypeScript module resolution again. A value of `undefined` means
-     * the module could not be resolved and that result is cached too.
-     *
-     * This cache is keyed by the raw import specifier, so it is only safe when the
-     * same specifier is resolved in a compatible context.
+     * Populated by {@link BuildService.buildVariant} as each variant
+     * finishes. Only contains results for variants that built successfully.
      *
-     * @since 2.3.0
+     * @since 2.4.0
      */
-    private aliasCache;
-    /**
-     * Cache for TypeScript module resolution results.
-     *
-     * @remarks
-     * TypeScript's internal module resolution cache that stores resolution results to avoid
-     * redundant lookups. Improves performance significantly when resolving many imports,
-     * especially in large projects with complex path mappings.
+    results: Record<string, BuildResultInterface>;
+}
+/**
+ * Extended build result interface with normalized error and warning arrays.
+ *
+ * @remarks
+ * This interface extends esbuild's {@link BuildResult} while replacing the `errors` and `warnings`
+ * properties with normalized Error instances instead of esbuild's Message objects. This normalization
+ * provides consistent error handling throughout the xBuild system with proper stack traces, formatting,
+ * and error classification.
+ *
+ * **Key differences from esbuild's BuildResult**:
+ * - `errors`: Changed from `Message[]` to `Error[]` with normalized error types
+ * - `warnings`: Changed from `Message[]` to `Error[]` with normalized error types
+ * - All other properties (metafile, outputFiles, mangleCache) are preserved unchanged
+ *
+ * **Benefits of normalization**:
+ * - Consistent error handling across different error sources (esbuild, TypeScript, VM runtime)
+ * - Proper error inheritance and type checking
+ * - Rich stack trace information with source mapping
+ * - Formatted error output with syntax highlighting
+ * - Integration with xBuild's custom error classes
+ *
+ * The normalized errors may include:
+ * - {@link TypesError} for TypeScript type checking failures
+ * - {@link xBuildError} for text errors during build hooks
+ * - {@link esBuildError} for esbuild compilation errors with location information
+ * - {@link VMRuntimeError} for runtime errors during build hooks
+ * - {@link xBuildBaseError} for custom build system errors
+ *
+ * @example
+ * ```ts
+ * const result: BuildResultInterface = {
+ *   errors: [
+ *     new esBuildError(esbuildMessage),
+ *     new TypesError('Type checking failed', diagnostics)
+ *   ],
+ *   warnings: [
+ *     new xBuildError('Deprecation warning')
+ *   ],
+ *   metafile: { ... },
+ *   outputFiles: [ ... ],
+ *   mangleCache: { ... }
+ * };
+ * ```
+ *
+ * @see {@link BuildResult} from esbuild for the base interface
+ *
+ * @since 2.0.0
+ */
+interface BuildResultInterface extends Omit<BuildResult, 'errors' | 'warnings'> {
+    /**
+     * Array of normalized error instances encountered during the build.
      *
-     * Recreated when compiler options change (since different options may affect resolution).
+     * @remarks
+     * Contains Error instances converted from esbuild messages and other error sources.
+     * Unlike esbuild's native error array which contains Message objects, this array
+     * contains fully normalized Error instances with proper stack traces and formatting.
      *
-     * @see {@link ts.createModuleResolutionCache}
+     * Errors in this array may originate from:
+     * - Compilation errors (syntax, resolution failures)
+     * - Type checking failures
+     * - Build hook execution errors
+     * - Plugin errors
+     *
+     * @example
+     * ```ts
+     * if (result.errors.length > 0) {
+     *   console.error(`Build failed with ${result.errors.length} errors`);
+     *   result.errors.forEach(err => console.error(err.stack));
+     * }
+     * ```
      *
      * @since 2.0.0
      */
-    private moduleResolutionCache;
+    errors: Array<Error>;
     /**
-     * A set containing the file paths of all actively tracked script files.
+     * Array of normalized warning instances encountered during the build.
      *
      * @remarks
-     * This set ensures that files are tracked for later operations, such as retrieving script versions
-     * or snapshots. Files are added to this set when they are first processed or read by the service.
+     * Contains Error instances converted from esbuild warning messages and other warning sources.
+     * Unlike esbuild's native warning array which contains Message objects, this array
+     * contains fully normalized Error instances with proper stack traces and formatting.
+     *
+     * Warnings indicate non-fatal issues that don't prevent build completion but may
+     * require attention, such as:
+     * - Deprecated API usage
+     * - Type checking warnings
+     * - Performance concerns
+     * - Potential runtime issues
      *
      * @example
      * ```ts
-     * trackFiles.add('/src/main.ts');
-     * console.log(trackFiles.has('/src/main.ts')); // true
+     * if (result.warnings.length > 0) {
+     *   console.warn(`Build completed with ${result.warnings.length} warnings`);
+     *   result.warnings.forEach(warn => console.warn(warn.message));
+     * }
      * ```
      *
-     * @see {@link getScriptFileNames} - Retrieves all tracked files.
+     * @since 2.0.0
+     */
+    warnings: Array<Error>;
+}
+/**
+ * Recursively makes all properties of a type optional.
+ *
+ * @remarks
+ * This utility type behaves like TypeScript’s built-in {@link Partial} type,
+ * but applies recursively to all nested object properties.
+ *
+ * It is commonly used for:
+ * - Partial configuration overrides
+ * - Patch / update objects
+ * - Programmatic configuration merging
+ * - Build variant and preset definitions
+ *
+ * This type only affects compile-time type checking and has no runtime impact.
+ *
+ * ⚠️ **Important limitations**:
+ * - Arrays and functions are treated as objects and will also be recursively
+ *   transformed. If this is undesirable, a more specialized deep-partial
+ *   implementation should be used.
+ * - Intended for configuration and data-shaping use cases, not strict domain models.
+ *
+ * @example
+ * ```ts
+ * interface Config {
+ *   server: {
+ *     host: string;
+ *     port: number;
+ *   };
+ *   features: {
+ *     experimental: boolean;
+ *   };
+ * }
+ *
+ * const override: DeepPartialType<Config> = {
+ *   server: {
+ *     port: 8080
+ *   }
+ * };
+ * ```
+ *
+ * @template T - The type to recursively make optional.
+ *
+ * @since 2.0.0
+ */
+type DeepPartialType<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartialType<T[K]> : T[K];
+};
+/**
+ * Represents code that can be injected into build output as a banner or footer.
+ * Can be a static string or a function that generates code dynamically based on build context.
+ *
+ * @remarks
+ * This type provides flexibility for injecting code at the top (banner) or bottom (footer) of
+ * bundled output files. The function form receives the plugin name and command-line arguments,
+ * allowing for context-aware code generation.
+ *
+ * Common use cases:
+ * - Static banners: Copyright notices, license headers, version information
+ * - Dynamic banners: Build timestamps, environment-specific code, conditional imports
+ * - Footer code: Analytics snippets, polyfills, initialization scripts
+ *
+ * When using the function form, the generated string is cached per build variant to avoid
+ * regenerating the same code multiple times.
+ *
+ * @example
+ * ```ts
+ * // Static banner
+ * const banner: InjectableCodeType = '\/* Copyright 2024 *\/';
+ *
+ * // Dynamic banner
+ * const banner: InjectableCodeType = (name, argv) => {
+ *   const version = argv.version || '1.0.0';
+ *   return `\/* Built by ${name} v${version} at ${new Date().toISOString()} *\/`;
+ * };
+ * ```
+ *
+ * @see {@link BaseBuildDefinitionInterface.banner}
+ * @see {@link BaseBuildDefinitionInterface.footer}
+ *
+ * @since 2.0.0
+ */
+type InjectableCodeType = string | ((name: string, argv: Record<string, unknown>) => string);
+/**
+ * Defines lifecycle hook handlers for build process stages.
+ * Allows registration of custom logic during resolution, loading, build start, build end, and success.
+ *
+ * @remarks
+ * This interface groups all available lifecycle hooks in a single configuration object.
+ * All hooks are optional, allowing selective registration of only necessary handlers.
+ *
+ * Hook execution order during a build:
+ * 1. `onStart` - Before any file processing
+ * 2. `onResolve` - During import path resolution
+ * 3. `onLoad` - When loading file contents
+ * 4. `onEnd` - After build completes (success or failure)
+ * 5. `onSuccess` - After a build completes successfully
+ *
+ * Each hook receives a specialized context object appropriate for its lifecycle stage, providing
+ * access to build configuration, variant information, and cross-hook communication through the
+ * shared stage object.
+ *
+ * @example
+ * ```ts
+ * const hooks: LifecycleHooksInterface = {
+ *   onStart: async (context) => {
+ *     console.log(`${context.variantName} build starting...`);
+ *   },
+ *   onLoad: async (context) => {
+ *     if (context.args.path.endsWith('.custom')) {
+ *       return { contents: transform(context.contents), loader: 'ts' };
+ *     }
+ *   },
+ *   onSuccess: async (context) => {
+ *     console.log(`Build succeeded in ${context.duration}ms!`);
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link OnEndType}
+ * @see {@link OnLoadType}
+ * @see {@link OnStartType}
+ * @see {@link OnResolveType}
+ *
+ * @since 2.0.0
+ */
+interface LifecycleHooksInterface {
+    /**
+     * Hook handler executed when the build completes, regardless of success or failure.
+     *
+     * @remarks
+     * Called after all build operations finish with a result context containing the build result,
+     * calculated duration, variant name, arguments, and stage state. Useful for cleanup, logging,
+     * reporting, and post-processing.
+     *
+     * The handler receives `ResultContextInterface` providing access to:
+     * - `buildResult`: Final build outcome with errors and warnings
+     * - `duration`: Build duration in milliseconds
+     * - `variantName`: Build variant identifier
+     * - `argv`: Command-line arguments and configuration
+     * - `stage`: Shared state object for cross-hook communication
+     *
+     * @example
+     * ```ts
+     * onEnd: async (context) => {
+     *   const { buildResult, duration, variantName } = context;
+     *   console.log(`${variantName} completed in ${duration}ms`);
+     *   if (buildResult.errors.length > 0) {
+     *     // Handle errors
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link ResultContextInterface}
      *
      * @since 2.0.0
      */
-    private readonly trackFiles;
+    onEnd?: OnEndType;
     /**
-     * Model for managing file snapshots and version tracking.
+     * Hook handler executed when loading file contents during module processing.
      *
      * @remarks
-     * Delegates file snapshot management to {@link FilesModel} for centralized
-     * caching and change detection. Snapshots are tracked by modification time
-     * to detect file changes efficiently.
+     * Called for each file being processed with a load context containing the current file contents
+     * (potentially transformed by previous hooks), loader type, load arguments, variant name, and
+     * stage state. Can transform contents and change the loader type. Multiple handlers execute in
+     * a pipeline pattern where each receives the output of previous hooks.
      *
-     * @see {@link FilesModel}
+     * The handler receives `LoadContextInterface` providing access to:
+     * - `contents`: Current file contents (string or binary)
+     * - `loader`: Current loader type (e.g., 'ts', 'js', 'json')
+     * - `args`: Load arguments including file path and namespace
+     * - `variantName`: Build variant identifier
+     * - `argv`: Command-line arguments and configuration
+     * - `stage`: Shared state object for cross-hook communication
+     *
+     * @example
+     * ```ts
+     * onLoad: async (context) => {
+     *   const { contents, args, variantName } = context;
+     *   if (args.path.endsWith('.custom')) {
+     *     return {
+     *       contents: transform(contents.toString()),
+     *       loader: 'ts'
+     *     };
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link LoadContextInterface}
      *
      * @since 2.0.0
      */
-    private readonly filesCache;
+    onLoad?: OnLoadType;
     /**
-     * Initializes a new {@link LanguageHostService} instance.
+     * Hook handler executed when the build process begins.
      *
-     * @param compilerOptions - Optional TypeScript compiler options (defaults to an empty object)
+     * @remarks
+     * Called before any file processing starts with a build context containing the esbuild build object,
+     * variant name, arguments, and stage state. Useful for initialization, validation, and setup tasks.
+     *
+     * The handler receives `BuildContextInterface` providing access to:
+     * - `build`: esbuild plugin build object with configuration and utilities
+     * - `variantName`: Build variant identifier
+     * - `argv`: Command-line arguments and configuration
+     * - `stage`: Shared state object for cross-hook communication
+     *
+     * @example
+     * ```ts
+     * onStart: async (context) => {
+     *   const { build, variantName, stage } = context;
+     *   console.log(`Starting ${variantName} build`);
+     *   stage.startTime = new Date();
+     *
+     *   // Validate configuration
+     *   if (!build.initialOptions.outdir) {
+     *     return { errors: [{ text: 'Output directory required' }] };
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link BuildContextInterface}
+     *
+     * @since 2.0.0
+     */
+    onStart?: OnStartType;
+    /**
+     * Hook handler executed when the build completes successfully without errors.
      *
      * @remarks
-     * Performs initialization including:
-     * 1. Stores compiler options for later use
-     * 2. Generates path alias regex from options if configured
-     * 3. Creates module resolution cache with appropriate settings
+     * Only called when `buildResult.errors.length === 0`, after all regular end hooks have completed.
+     * Receives the same result context as end hooks, containing build result, duration, variant name,
+     * arguments, and stage state. Useful for deployment, success notifications, and success-only operations.
      *
-     * The module resolution cache is necessary for efficient resolution of imports in large projects.
-     * Path alias regex is generated up-front and cached for performance.
+     * The handler receives `ResultContextInterface` providing access to:
+     * - `buildResult`: Final build outcome (guaranteed to have zero errors)
+     * - `duration`: Build duration in milliseconds
+     * - `variantName`: Build variant identifier
+     * - `argv`: Command-line arguments and configuration
+     * - `stage`: Shared state object for cross-hook communication
      *
      * @example
      * ```ts
-     * // Create host with default options
-     * const host = new LanguageHostService();
+     * onSuccess: async (context) => {
+     *   const { buildResult, duration, variantName } = context;
+     *   console.log(`${variantName} succeeded in ${duration}ms!`);
+     *   await deploy(buildResult.metafile);
+     * }
+     * ```
      *
-     * // Create host with specific compiler options
-     * const host = new LanguageHostService({
-     *   target: ts.ScriptTarget.ES2020,
-     *   module: ts.ModuleKind.ESNext,
-     *   paths: {
-     *     '@utils/*': ['src/utils/*']
+     * @see {@link ResultContextInterface}
+     *
+     * @since 2.0.0
+     */
+    onSuccess?: OnEndType;
+    /**
+     * Hook handler executed during module path resolution.
+     *
+     * @remarks
+     * Called when resolving import paths to file system locations with a resolve context containing
+     * the resolution arguments, variant name, and stage state. Can redirect imports, mark modules as
+     * external, or implement custom resolution logic. Multiple handlers execute, and their results are
+     * merged, with later hooks able to override earlier ones.
+     *
+     * The handler receives `ResolveContextInterface` providing access to:
+     * - `args`: Resolution arguments including import path and importer info
+     * - `variantName`: Build variant identifier
+     * - `argv`: Command-line arguments and configuration
+     * - `stage`: Shared state object for cross-hook communication
+     *
+     * @example
+     * ```ts
+     * onResolve: async (context) => {
+     *   const { args, variantName } = context;
+     *
+     *   // Redirect '@/' imports to 'src/'
+     *   if (args.path.startsWith('@/')) {
+     *     return {
+     *       path: resolve('src', args.path.slice(2)),
+     *       namespace: 'file'
+     *     };
      *   }
-     * });
+     *
+     *   // Mark as external in production
+     *   if (variantName === 'production' && args.path.includes('node_modules')) {
+     *     return { path: args.path, external: true };
+     *   }
+     * }
      * ```
      *
+     * @see {@link ResolveContextInterface}
+     *
      * @since 2.0.0
      */
-    constructor(compilerOptions?: CompilerOptions);
+    onResolve?: OnResolveType;
+}
+/**
+ * Configuration options for TypeScript declaration file generation.
+ *
+ * @remarks
+ * Controls how and where TypeScript declaration files (`.d.ts`) are generated during the build.
+ * These options work in conjunction with the TypeScript compiler to produce type definitions
+ * for bundled code.
+ *
+ * When `bundle` is true, declarations from multiple source files are combined into a single
+ * declaration file per entry point. When false, individual declaration files are generated
+ * for each source file.
+ *
+ * @example
+ * ```ts
+ * // Generate bundled declarations in custom directory
+ * const options: DeclarationOptionsInterface = {
+ *   outDir: 'types',
+ *   bundle: true
+ * };
+ * ```
+ *
+ * @see {@link BaseBuildDefinitionInterface.declaration}
+ *
+ * @since 2.0.0
+ */
+interface DeclarationOptionsInterface {
+    /**
+     * Output directory for generated declaration files.
+     *
+     * @remarks
+     * Specifies where `.d.ts` files should be written. If not provided, uses the TypeScript
+     * compiler's `declarationDir` or `outDir` from `tsconfig.json`.
+     *
+     * @example
+     * ```ts
+     * outDir: 'dist/types'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    outDir?: string;
+    /**
+     * Whether to bundle declarations into a single file per entry point.
+     *
+     * @remarks
+     * When true, combines all declarations from imported modules into a single `.d.ts` file.
+     * When false, generates individual declaration files mirroring the source structure.
+     *
+     * Bundling is useful for library distribution as it provides a single type definition file
+     * that consumers can reference.
+     *
+     * @example
+     * ```ts
+     * bundle: true  // Produces single bundled .d.ts
+     * bundle: false // Produces multiple .d.ts files
+     * ```
+     *
+     * @since 2.0.0
+     */
+    bundle?: boolean;
+}
+/**
+ * Configuration options for TypeScript type checking during builds.
+ *
+ * @remarks
+ * Controls how TypeScript type checking is performed and whether type errors should fail the build.
+ * Type checking runs in parallel with the esbuild compilation process for better performance.
+ *
+ * @example
+ * ```ts
+ * // Fail build on type errors
+ * const options: TypeCheckOptionsInterface = {
+ *   failOnError: true
+ * };
+ * ```
+ *
+ * @see {@link BaseBuildDefinitionInterface.types}
+ *
+ * @since 2.0.0
+ */
+interface TypeCheckOptionsInterface {
     /**
-     * Regular expression that matches import/export statements using path aliases (if `paths` is configured).
+     * Whether to fail the build when TypeScript errors are detected.
      *
      * @remarks
-     * Used mainly for advanced refactoring or rewrite tools that need to identify aliased imports.
+     * When true, any TypeScript errors will cause the build to fail with a non-zero exit code.
+     * When false, errors are logged, but the build continues and succeeds.
      *
-     * @since 2.0.0
-     */
-    get aliasRegex(): RegExp | undefined;
-    /**
-     * Replaces current compiler options and regenerates derived state (alias regex, module cache).
+     * Useful in CI/CD pipelines where type safety must be enforced before deployment.
      *
-     * @param options - new compiler configuration
+     * @example
+     * ```ts
+     * failOnError: true  // Build fails on type errors
+     * failOnError: false // Type errors logged, but build continues
+     * ```
      *
      * @since 2.0.0
      */
-    set options(options: CompilerOptions);
+    failOnError?: boolean;
+}
+/**
+ * Base configuration shared across all build definitions, including common and variant builds.
+ * Provides common settings for hooks, type checking, code injection, and declaration generation.
+ *
+ * @remarks
+ * This interface defines the foundation for build configuration that applies to both common
+ * settings and individual build variants. Properties defined here can be overridden at the
+ * variant level for customization.
+ *
+ * Configuration inheritance:
+ * - Common build settings apply to all variants
+ * - Variant settings override common settings
+ * - Objects like `define` are merged (variant takes precedence)
+ * - Arrays and primitives replace common values
+ *
+ * @example
+ * ```ts
+ * const base: BaseBuildDefinitionInterface = {
+ *   types: { failOnError: true },
+ *   declaration: { bundle: true, outDir: 'types' },
+ *   define: { 'process.env.NODE_ENV': '"production"' },
+ *   banner: 'const x = "test"',
+ *   hooks: {
+ *     onSuccess: async () => console.log('Build complete!')
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link CommonBuildInterface}
+ * @see {@link VariantBuildInterface}
+ * @see {@link BuildConfigInterface}
+ *
+ * @since 2.0.0
+ */
+interface BaseBuildDefinitionInterface {
     /**
-     * Reloads all tracked file snapshots in the shared {@link FilesModel} cache.
+     * Lifecycle hook handlers for build process stages.
      *
      * @remarks
-     * This method iterates over every currently tracked file path and touches each file again so
-     * the cache can refresh its stored modification time, version, and content snapshot when needed.
-     * It is useful in watch-mode or manual refresh scenarios where the underlying files may have changed
-     * and dependent services need to observe the updated state.
-     *
-     * @since 2.3.0
-     */
-    static reload(): void;
-    /**
-     * Updates file snapshot in the cache and returns the current state.
+     * Registers custom handlers for various build lifecycle events including start, resolve,
+     * load, end, and success stages. All hooks are optional.
      *
-     * @param path - file path (relative or absolute)
-     * @returns current snapshot data (version, mtime, content snapshot)
+     * @see {@link LifecycleHooksInterface}
      *
-     * @see {@link FilesModel#touchFile}
      * @since 2.0.0
      */
-    touchFile(path: string): FileSnapshotInterface;
+    lifecycle?: LifecycleHooksInterface;
     /**
-     * Ensures multiple files are tracked and their snapshots are up to date.
+     * TypeScript type checking configuration.
      *
-     * @param filesPath - list of file paths to touch
+     * @remarks
+     * Controls whether and how TypeScript type checking is performed during builds.
+     * - `true`: Enable type checking with default options
+     * - `false` or omitted: Disable type checking
+     * - Object: Enable with specific options like `failOnError`
      *
-     * @since 2.0.0
-     */
-    touchFiles(filesPath: Array<string>): void;
-    /**
-     * Returns current compiler options used by this host.
+     * @example
+     * ```ts
+     * types: true                      // Enable with default
+     * types: { failOnError: true }     // Enable and fail on errors
+     * types: false                     // Disable
+     * ```
      *
-     * @returns active TypeScript compiler configuration
+     * @see {@link TypeCheckOptionsInterface}
      *
      * @since 2.0.0
      */
-    getCompilationSettings(): CompilerOptions;
+    types?: boolean | TypeCheckOptionsInterface;
     /**
-     * Checks whether a file exists on disk.
+     * Global constants to replace during bundling.
      *
-     * @param path - absolute path
-     * @returns `true` if file exists
+     * @remarks
+     * Defines key-value pairs for constant replacement during the build. Keys are identifiers
+     * or property access expressions, values are JSON-stringified replacements.
      *
-     * @since 2.0.0
-     */
-    fileExists(path: string): boolean;
-    /**
-     * Reads file content from disk.
+     * Commonly used for environment variables, feature flags, and build-time constants.
      *
-     * @param path - absolute path
-     * @param encoding - optional encoding (defaults to UTF-8)
-     * @returns file content or `undefined` if read fails
+     * @example
+     * ```ts
+     * define: {
+     *   'process.env.NODE_ENV': '"production"',
+     *   'DEBUG': 'false',
+     *   'VERSION': '"1.2.3"'
+     * }
+     * ```
      *
      * @since 2.0.0
      */
-    readFile(path: string, encoding?: string): string | undefined;
+    define?: Record<string, unknown>;
     /**
-     * Lists files and/or directories matching criteria.
+     * Code to inject at the beginning of each output file.
      *
-     * @param path - starting directory
-     * @param extensions - allowed file extensions
-     * @param exclude - glob exclude patterns
-     * @param include - glob include patterns
-     * @param depth - max recursion depth
-     * @returns matching file paths
+     * @remarks
+     * Can be a static string or a function that generates code based on build context.
+     * Commonly used for copyright notices, license headers, or polyfill imports.
      *
-     * @since 2.0.0
-     */
-    readDirectory(path: string, extensions?: Array<string>, exclude?: Array<string>, include?: Array<string>, depth?: number): Array<string>;
-    /**
-     * Returns immediate subdirectories of a given path.
+     * @example
+     * ```ts
+     * banner: 'const x = "test"'
+     * banner: (name, argv) => `const x = "Built: ${new Date().toISOString()}"`
+     * ```
      *
-     * @param path - directory to list
-     * @returns subdirectory names
+     * @see {@link InjectableCodeType}
      *
      * @since 2.0.0
      */
-    getDirectories(path: string): Array<string>;
+    banner?: {
+        [key: string]: InjectableCodeType;
+    };
     /**
-     * Checks whether a directory exists.
+     * Code to inject at the end of each output file.
      *
-     * @param path - absolute path
-     * @returns `true` if directory exists
+     * @remarks
+     * Can be a static string or a function that generates code based on build context.
+     * Commonly used for initialization code, analytics, or polyfills.
      *
-     * @since 2.0.0
-     */
-    directoryExists(path: string): boolean;
-    /**
-     * Returns the current working directory used as resolution base.
+     * @example
+     * ```ts
+     * footer: '// End of bundle'
+     * footer: (name, argv) => `console.log('Loaded ${name}');`
+     * ```
      *
-     * @returns absolute path of cwd
+     * @see {@link InjectableCodeType}
      *
      * @since 2.0.0
      */
-    getCurrentDirectory(): string;
+    footer?: {
+        [key: string]: InjectableCodeType;
+    };
     /**
-     * Returns names of all known script files tracked by this host.
-     *
-     * @returns array of resolved absolute paths
+     * TypeScript declaration file generation configuration.
      *
      * @remarks
-     * Only includes files previously requested via `getScriptSnapshot` or explicitly `touchFile`/`touchFiles`.
-     *
-     * @since 2.0.0
-     */
-    getScriptFileNames(): Array<string>;
-    /**
-     * Returns a path to a default lib `.d.ts` file matching the given target.
-     *
-     * @param options - compiler options (mainly `target`)
-     * @returns absolute path to lib.d.ts / lib.esxxxx.d.ts
-     *
-     * @since 2.0.0
-     */
-    getDefaultLibFileName(options: CompilerOptions): string;
-    /**
-     * Returns string version identifier for the given file.
+     * Controls whether and how TypeScript declaration files are generated.
+     * - `true`: Generate declarations with default options
+     * - `false` or omitted: Do not generate declarations
+     * - Object: Generate with specific options like `outDir` and `bundle`
      *
-     * @param path - file path
-     * @returns version as string (usually `"0"`, `"1"`, `"2"`, …)
+     * @example
+     * ```ts
+     * declaration: true                              // Generate with default
+     * declaration: { outDir: 'types', bundle: true } // Generate bundled in custom dir
+     * declaration: false                             // Disable
+     * ```
      *
-     * @remarks
-     * Tracks file in `trackFiles` set as a side effect so it appears in `getScriptFileNames()`.
+     * @see {@link DeclarationOptionsInterface}
      *
      * @since 2.0.0
      */
-    getScriptVersion(path: string): string;
+    declaration?: boolean | DeclarationOptionsInterface;
+}
+/**
+ * Build configuration for a specific build variant including esbuild settings and entry points.
+ * Extends base configuration with variant-specific esbuild options and required entry points.
+ *
+ * @remarks
+ * A variant represents a distinct build target with its own entry points and esbuild configuration.
+ * Variants inherit settings from the common configuration but can override any property.
+ *
+ * The `esbuild` property excludes fields that are managed by the build system:
+ * - `plugins`: Managed by the hook provider
+ * - `define`, `banner`, `footer`: Managed by base configuration
+ * - `entryPoints`: Required at variant level (non-nullable)
+ *
+ * Multiple variants enable building different outputs from the same codebase, such as
+ * - Different module formats (ESM, CJS)
+ * - Different targets (Node.js, browser)
+ * - Different bundles (main, worker, tests)
+ *
+ * @example
+ * ```ts
+ * const variant: VariantBuildInterface = {
+ *   esbuild: {
+ *     entryPoints: ['src/index.ts'],
+ *     outdir: 'dist/esm',
+ *     format: 'esm',
+ *     target: 'es2020'
+ *   },
+ *   types: true,
+ *   declaration: { bundle: true, outDir: 'dist/types' }
+ * };
+ * ```
+ *
+ * @see {@link VariantsType}
+ * @see {@link CommonBuildInterface}
+ * @see {@link BaseBuildDefinitionInterface}
+ *
+ * @since 2.0.0
+ */
+interface VariantBuildInterface extends BaseBuildDefinitionInterface {
     /**
-     * Checks whether a file is actively tracked (has been requested before).
+     * Esbuild-specific configuration for this variant including entry points.
      *
-     * @param path - file path
-     * @returns `true` if the file is known to this host
+     * @remarks
+     * Contains all esbuild options except those managed by the build system.
+     * The `entryPoints` field is required and must be non-empty to define what to build.
+     *
+     * Common options include:
+     * - `format`: Output format (esm, cjs, iife)
+     * - `outdir` or `outfile`: Output location
+     * - `target`: ECMAScript target version
+     * - `platform`: Target platform (browser, node, neutral)
+     * - `minify`: Whether to minify output
+     * - `sourcemap`: Whether to generate source maps
+     *
+     * @example
+     * ```ts
+     * esbuild: {
+     *   entryPoints: ['src/index.ts', 'src/worker.ts'],
+     *   outdir: 'dist',
+     *   format: 'esm',
+     *   target: 'es2020',
+     *   minify: true,
+     *   sourcemap: true
+     * }
+     * ```
      *
      * @since 2.0.0
      */
-    hasScriptSnapshot(path: string): boolean;
+    esbuild: Omit<BuildOptions, 'plugins' | 'define' | 'banner' | 'footer'>;
     /**
-     * Returns an up-to-date script snapshot for the file.
-     *
-     * @param path - file path
-     * @returns `IScriptSnapshot` or `undefined` if a file is missing/empty
+     * Variants that must finish building before this variant starts.
      *
      * @remarks
-     * Automatically touches the file (reads disk if needed) when no snapshot exists yet.
+     * Use this field to express build ordering between variants when one output
+     * depends on another being completed first.
      *
-     * @since 2.0.0
-     */
-    getScriptSnapshot(path: string): IScriptSnapshot | undefined;
-    /**
-     * Resolves module import using current compiler options and cache.
+     * You can provide:
+     * - a single variant name
+     * - an array of variant names
      *
-     * @param moduleName - module specifier
-     * @param containingFile - path of a file containing the import
-     * @returns resolution result (success and failed lookups)
+     * The build system should resolve these dependencies before running the current
+     * variant and should also detect circular dependencies to avoid infinite loops.
      *
-     * @since 2.0.0
-     */
-    resolveModuleName(moduleName: string, containingFile: string): ResolvedModuleWithFailedLookupLocations;
-    /**
-     * Resolves a module specifier to its absolute file path using the host.
+     * @example
+     * ```ts
+     * dependOn: 'types'
+     * ```
      *
-     * @param moduleName - import/export specifier (e.g. "lodash", "./utils")
-     * @param containingFile - path of a file containing the import
-     * @returns resolved absolute path or `undefined` if resolution fails
+     * @example
+     * ```ts
+     * dependOn: ['types', 'shared']
+     * ```
      *
-     * @since 2.0.0
+     * @see {@link VariantsType}
+     * @since 2.4.0
      */
-    resolveModuleFileName(moduleName: string, containingFile: string): string | undefined;
+    dependOn?: string | Array<string>;
+}
+/**
+ * Shared configuration applied to all build variants.
+ * Extends base configuration with esbuild settings but without entry points.
+ *
+ * @remarks
+ * Common configuration provides default settings that apply to all variants unless overridden.
+ * This reduces duplication when multiple variants share similar settings.
+ *
+ * The `esbuild` property excludes managed fields and `entryPoints` (which must be variant-specific).
+ * Settings defined here are merged with variant-specific settings, with variants taking precedence.
+ *
+ * Typical use cases:
+ * - Shared compiler options (target, platform)
+ * - Common minification and sourcemap settings
+ * - Shared external dependencies
+ * - Default output configuration
+ *
+ * @example
+ * ```ts
+ * const common: CommonBuildInterface = {
+ *   esbuild: {
+ *     target: 'es2020',
+ *     platform: 'node',
+ *     sourcemap: true,
+ *     external: ['react', 'react-dom']
+ *   },
+ *   types: { failOnError: true },
+ *   declaration: true
+ * };
+ * ```
+ *
+ * @see {@link BaseBuildDefinitionInterface}
+ * @see {@link VariantBuildInterface}
+ * @see {@link BuildConfigInterface}
+ *
+ * @since 2.0.0
+ */
+interface CommonBuildInterface extends BaseBuildDefinitionInterface {
     /**
-     * Rewrites path aliases in declaration content to relative paths.
-     *
-     * @param content - raw declaration text
-     * @param fileName - source file name
-     * @param type - file extension to append to resolved paths (e.g., `'.d.ts'`, `'.js'`), defaults to empty string
-     * @returns content with aliases replaced by relative paths
+     * Shared esbuild configuration for all variants.
      *
      * @remarks
-     * Ensures emitted files use portable relative imports instead of aliases.
-     * The `type` parameter allows flexible transformation of resolved TypeScript source file extensions
-     * (`.ts`, `.tsx`) to any target extension.
+     * Contains esbuild options that apply to all variants by default. Variants can override
+     * any of these settings with their own specific values.
      *
-     * **Common use cases**:
-     * - Pass `'.d.ts'` for declaration file generation
-     * - Pass `'.js'` for JavaScript output paths
-     * - Pass `''` (default) to preserve the resolved file extension
+     * Excludes managed fields and `entryPoints` since entry points must be variant-specific.
      *
      * @example
      * ```ts
-     * // For regular source files (preserve extension)
-     * const code = host.resolveAliases(content, 'src/index.ts');
-     *
-     * // For declaration files
-     * const dts = host.resolveAliases(content, 'src/index.ts', '.d.ts');
-     * // '@utils/helpers' -> './utils/helpers.d.ts'
-     *
-     * // For JavaScript output
-     * const js = host.resolveAliases(content, 'src/index.ts', '.js');
-     * // '@utils/helpers' -> './utils/helpers.js'
+     * esbuild: {
+     *   platform: 'node',
+     *   target: 'node18',
+     *   external: ['typescript']
+     * }
      * ```
      *
      * @since 2.0.0
      */
-    resolveAliases(content: string, fileName: string, type?: string): string;
-    /**
-     * Builds regex that matches import/export declarations using any configured path alias.
-     *
-     * @param config - compiler options containing `paths`
-     * @returns regex or `undefined` if no `paths` configured
-     *
-     * @since 2.0.0
-     */
-    private static generateAliasRegex;
+    esbuild?: Omit<BuildOptions, 'plugins' | 'define' | 'banner' | 'footer'>;
 }
 /**
- * Extended TypeScript script snapshot that includes direct access to the underlying text content.
+ * Maps variant names to their build configurations.
+ * Allows defining multiple build targets with different entry points and settings.
  *
  * @remarks
- * This type augments TypeScript's standard `IScriptSnapshot` interface with a `text` property,
- * providing direct access to the original source text without requiring method calls.
- *
- * TypeScript's native `IScriptSnapshot` only exposes text through the `getText()` method.
- * This extended type adds a `text` property for more convenient access to the full content,
- * particularly useful in caching scenarios where the source text is frequently referenced.
+ * This type represents a collection of named build variants. Each key is a user-defined
+ * variant name (e.g., 'esm', 'cjs', 'browser'), and each value is the complete build
+ * configuration for that variant.
  *
- * Primarily used by {@link FilesModel} to store file content snapshots in an efficient,
- * readily accessible format for incremental compilation and language service operations.
+ * Variant names are used for:
+ * - CLI targeting specific builds
+ * - Build output organization
+ * - Logging and error reporting
+ * - Parallel build coordination
  *
  * @example
  * ```ts
- * const snapshot: ScriptSnapshotType = {
- *   ...ts.ScriptSnapshot.fromString(content),
- *   text: content
+ * const variants: VariantsType = {
+ *   esm: {
+ *     esbuild: {
+ *       entryPoints: ['src/index.ts'],
+ *       format: 'esm',
+ *       outdir: 'dist/esm'
+ *     }
+ *   },
+ *   cjs: {
+ *     esbuild: {
+ *       entryPoints: ['src/index.ts'],
+ *       format: 'cjs',
+ *       outdir: 'dist/cjs'
+ *     }
+ *   }
  * };
- *
- * // Direct text access (convenient)
- * console.log(snapshot.text);
- *
- * // Method-based access (standard IScriptSnapshot)
- * console.log(snapshot.getText(0, snapshot.getLength()));
  * ```
  *
- * @see {@link IScriptSnapshot}
- * @see {@link FilesModel.touchFile}
- * @see {@link FileSnapshotInterface}
+ * @see {@link VariantBuildInterface}
+ * @see {@link BuildConfigInterface}
  *
  * @since 2.0.0
  */
-type ScriptSnapshotType = IScriptSnapshot & {
-    text: string;
+type VariantsType = {
+    [variantName: string]: VariantBuildInterface;
 };
 /**
- * Represents the cached state of a single file for incremental TypeScript processing.
+ * Complete build configuration including common settings, variants, and CLI options.
+ * Serves as the root configuration object for the entire build system.
  *
- * Stores the modification timestamp, a version counter that increments on every meaningful change,
- * and an optional TypeScript `ScriptSnapshot` containing the file content in a memory-efficient form.
+ * @remarks
+ * This interface defines the complete structure of the build configuration file. It includes:
+ * - Optional common settings shared across all variants
+ * - Required variants mapping defining all build targets
+ * - Optional verbose logging flag
+ * - Optional custom command-line argument definitions
  *
- * Used by language services and build tools to quickly determine whether a file needs to be reparsed.
+ * The configuration is typically exported from a `build.config.ts` or similar file and
+ * loaded by the build system at startup.
+ *
+ * Configuration resolution:
+ * 1. Load the configuration file
+ * 2. Parse command-line arguments using `userArgv` definitions
+ * 3. Merge common settings with each variant
+ * 4. Execute builds for all or selected variants
+ *
+ * @example
+ * ```ts
+ * const config: BuildConfigInterface = {
+ *   verbose: true,
+ *   common: {
+ *     esbuild: {
+ *       platform: 'node',
+ *       target: 'node18'
+ *     },
+ *     types: true
+ *   },
+ *   variants: {
+ *     esm: {
+ *       esbuild: {
+ *         entryPoints: ['src/index.ts'],
+ *         format: 'esm',
+ *         outdir: 'dist/esm'
+ *       }
+ *     },
+ *     cjs: {
+ *       esbuild: {
+ *         entryPoints: ['src/index.ts'],
+ *         format: 'cjs',
+ *         outdir: 'dist/cjs'
+ *       }
+ *     }
+ *   },
+ *   userArgv: {
+ *     watch: { type: 'boolean', description: 'Watch for changes' }
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link VariantsType}
+ * @see {@link CommonBuildInterface}
+ * @see {@link PartialBuildConfigType}
  *
  * @since 2.0.0
  */
-interface FileSnapshotInterface {
+interface BuildConfigInterface {
     /**
-     * Last known modification time of the file in milliseconds since epoch.
-     *
-     * Set to `0` when the file no longer exists or cannot be accessed.
+     * Shared configuration applied to all build variants.
      *
      * @remarks
-     * Compared directly against `fs.stat().mtimeMs` to detect changes without reading content.
+     * Optional common settings that are merged with each variant's configuration.
+     * Variants can override these settings with their own specific values.
+     *
+     * @see {@link CommonBuildInterface}
      *
      * @since 2.0.0
      */
-    mtimeMs: number;
+    common?: CommonBuildInterface;
     /**
-     * Monotonically increasing integer that changes whenever the file content or accessibility status changes.
-     *
-     * Used by TypeScript language services as the script version identifier.
+     * Enable verbose logging output during builds.
      *
      * @remarks
-     * - Incremented on every successful content read with changed mtime
-     * - Incremented when a file becomes unreadable (if it previously had content or version bigger than 0)
-     * - Not incremented on no-op accesses (unchanged mtime)
+     * When true, outputs detailed build information including file processing,
+     * hook execution, and timing information. Useful for debugging build issues.
      *
      * @example
      * ```ts
-     * // Typical usage in LanguageServiceHost
-     * getScriptVersion(fileName: string): string {
-     *   const snapshot = cache.touchFile(fileName);
-     *   return String(snapshot.version);
-     * }
+     * verbose: true  // Detailed output
+     * verbose: false // Minimal output
      * ```
      *
      * @since 2.0.0
      */
-    version: number;
+    verbose?: boolean;
     /**
-     * TypeScript script snapshot containing the file's source text, or `undefined` if the file is missing,
-     * empty, or inaccessible.
+     * Build variant definitions mapping names to configurations.
      *
      * @remarks
-     * - Created via `ts.ScriptSnapshot.fromString(content)`
-     * - Kept `undefined` for zero-length or non-readable files to save memory
-     * - Consumers should check existence before calling methods like `getText()`
+     * Required field defining all build targets. At least one variant must be defined.
+     * Each variant specifies its own entry points and can override common settings.
      *
-     * @see ScriptSnapshotType
-     * @see {@link https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API#script-snapshot | TypeScript Compiler API – Script Snapshots}
+     * @see {@link VariantsType}
      *
      * @since 2.0.0
      */
-    contentSnapshot: ScriptSnapshotType | undefined;
+    variants: VariantsType;
 }
 /**
- * Extended build result interface with normalized error and warning arrays.
+ * Partial build configuration for incremental or programmatic configuration building.
+ * Allows omitting variants and userArgv while making other fields optional.
  *
  * @remarks
- * This interface extends esbuild's {@link BuildResult} while replacing the `errors` and `warnings`
- * properties with normalized Error instances instead of esbuild's Message objects. This normalization
- * provides consistent error handling throughout the xBuild system with proper stack traces, formatting,
- * and error classification.
- *
- * **Key differences from esbuild's BuildResult**:
- * - `errors`: Changed from `Message[]` to `Error[]` with normalized error types
- * - `warnings`: Changed from `Message[]` to `Error[]` with normalized error types
- * - All other properties (metafile, outputFiles, mangleCache) are preserved unchanged
- *
- * **Benefits of normalization**:
- * - Consistent error handling across different error sources (esbuild, TypeScript, VM runtime)
- * - Proper error inheritance and type checking
- * - Rich stack trace information with source mapping
- * - Formatted error output with syntax highlighting
- * - Integration with xBuild's custom error classes
+ * This type is useful when building configuration programmatically or when providing
+ * configuration fragments that will be merged with a base configuration. It makes
+ * all properties optional except `variants` and `userArgv` which are completely omitted.
  *
- * The normalized errors may include:
- * - {@link TypesError} for TypeScript type checking failures
- * - {@link xBuildError} for text errors during build hooks
- * - {@link esBuildError} for esbuild compilation errors with location information
- * - {@link VMRuntimeError} for runtime errors during build hooks
- * - {@link xBuildBaseError} for custom build system errors
+ * Common use cases:
+ * - Configuration presets or templates
+ * - Programmatic configuration generation
+ * - Configuration merging utilities
+ * - Partial overrides in build scripts
  *
  * @example
  * ```ts
- * const result: BuildResultInterface = {
- *   errors: [
- *     new esBuildError(esbuildMessage),
- *     new TypesError('Type checking failed', diagnostics)
- *   ],
- *   warnings: [
- *     new xBuildError('Deprecation warning')
- *   ],
- *   metafile: { ... },
- *   outputFiles: [ ... ],
- *   mangleCache: { ... }
+ * const preset: PartialBuildConfigType = {
+ *   verbose: true,
+ *   common: {
+ *     types: { failOnError: true },
+ *     declaration: true
+ *   }
+ * };
+ *
+ * // Merge with full config
+ * const fullConfig: BuildConfigInterface = {
+ *   ...preset,
+ *   variants: { ... }
  * };
  * ```
  *
- * @see {@link BuildResult} from esbuild for the base interface
+ * @see {@link BuildConfigInterface}
  *
  * @since 2.0.0
  */
-interface BuildResultInterface extends Omit<BuildResult, 'errors' | 'warnings'> {
-    /**
-     * Array of normalized error instances encountered during the build.
-     *
-     * @remarks
-     * Contains Error instances converted from esbuild messages and other error sources.
-     * Unlike esbuild's native error array which contains Message objects, this array
-     * contains fully normalized Error instances with proper stack traces and formatting.
-     *
-     * Errors in this array may originate from:
-     * - Compilation errors (syntax, resolution failures)
-     * - Type checking failures
-     * - Build hook execution errors
-     * - Plugin errors
-     *
-     * @example
-     * ```ts
-     * if (result.errors.length > 0) {
-     *   console.error(`Build failed with ${result.errors.length} errors`);
-     *   result.errors.forEach(err => console.error(err.stack));
-     * }
-     * ```
-     *
-     * @since 2.0.0
-     */
-    errors: Array<Error>;
-    /**
-     * Array of normalized warning instances encountered during the build.
-     *
-     * @remarks
-     * Contains Error instances converted from esbuild warning messages and other warning sources.
-     * Unlike esbuild's native warning array which contains Message objects, this array
-     * contains fully normalized Error instances with proper stack traces and formatting.
-     *
-     * Warnings indicate non-fatal issues that don't prevent build completion but may
-     * require attention, such as:
-     * - Deprecated API usage
-     * - Type checking warnings
-     * - Performance concerns
-     * - Potential runtime issues
-     *
-     * @example
-     * ```ts
-     * if (result.warnings.length > 0) {
-     *   console.warn(`Build completed with ${result.warnings.length} warnings`);
-     *   result.warnings.forEach(warn => console.warn(warn.message));
-     * }
-     * ```
-     *
-     * @since 2.0.0
-     */
-    warnings: Array<Error>;
-}
+type PartialBuildConfigType = Partial<BuildConfigInterface>;
 /**
  * Represents a value that may be synchronous, asynchronous, void, null, or the specified type.
  *
@@ -2004,889 +2401,675 @@ type OnResolveType = (context: ResolveContextInterface) => MaybeUndefinedPromise
  */
 type OnLoadType = (context: LoadContextInterface) => MaybeUndefinedPromiseType<OnLoadResult>;
 /**
- * Options used to reload the build service configuration.
- *
- * @remarks
- * These options control how configuration reload behaves:
- * - `config` replaces the current build configuration
- * - `clearCache` clears cached file and TypeScript language service state before reloading
- *
- * @since 2.3.0
- */
-interface ReloadOptionsInterface {
-    /**
-     * Optional new configuration to replace the current one.
-     *
-     * @remarks
-     * When provided, the build service reloads using this configuration
-     * before recalculating variants.
-     */
-    config?: PartialBuildConfigType;
-    /**
-     * Whether to clear cached files and TypeScript language service state before reloading.
-     *
-     * @remarks
-     * When enabled, cached file tracking and language service state are reset
-     * before the configuration is reloaded.
-     */
-    clearCache?: boolean;
-}
-/**
- * Recursively makes all properties of a type optional.
- *
- * @remarks
- * This utility type behaves like TypeScript’s built-in {@link Partial} type,
- * but applies recursively to all nested object properties.
- *
- * It is commonly used for:
- * - Partial configuration overrides
- * - Patch / update objects
- * - Programmatic configuration merging
- * - Build variant and preset definitions
- *
- * This type only affects compile-time type checking and has no runtime impact.
- *
- * ⚠️ **Important limitations**:
- * - Arrays and functions are treated as objects and will also be recursively
- *   transformed. If this is undesirable, a more specialized deep-partial
- *   implementation should be used.
- * - Intended for configuration and data-shaping use cases, not strict domain models.
- *
- * @example
- * ```ts
- * interface Config {
- *   server: {
- *     host: string;
- *     port: number;
- *   };
- *   features: {
- *     experimental: boolean;
- *   };
- * }
- *
- * const override: DeepPartialType<Config> = {
- *   server: {
- *     port: 8080
- *   }
- * };
- * ```
- *
- * @template T - The type to recursively make optional.
- *
- * @since 2.0.0
- */
-type DeepPartialType<T> = {
-    [K in keyof T]?: T[K] extends object ? DeepPartialType<T[K]> : T[K];
-};
-/**
- * Represents code that can be injected into build output as a banner or footer.
- * Can be a static string or a function that generates code dynamically based on build context.
+ * Represents a cached TypeScript language service instance with reference counting for shared resource management.
+ * Enables multiple consumers to share the same language service while tracking active usage through reference counts.
  *
  * @remarks
- * This type provides flexibility for injecting code at the top (banner) or bottom (footer) of
- * bundled output files. The function form receives the plugin name and command-line arguments,
- * allowing for context-aware code generation.
- *
- * Common use cases:
- * - Static banners: Copyright notices, license headers, version information
- * - Dynamic banners: Build timestamps, environment-specific code, conditional imports
- * - Footer code: Analytics snippets, polyfills, initialization scripts
+ * This interface is used internally by {@link TypescriptService} to implement a caching strategy that prevents
+ * duplicate language service instances for the same configuration file. The lifecycle follows these rules:
+ * - When a new service is created, `refCount` starts at 1
+ * - Each additional consumer increments `refCount`
+ * - Calling dispose decrements `refCount`
+ * - When `refCount` reaches 0, the service is disposed and removed from cache
  *
- * When using the function form, the generated string is cached per build variant to avoid
- * regenerating the same code multiple times.
+ * The cached data includes all components needed to maintain a fully functional TypeScript compiler instance:
+ * compiled configuration, language service host, and the language service itself.
  *
  * @example
  * ```ts
- * // Static banner
- * const banner: InjectableCodeType = '\/* Copyright 2024 *\/';
- *
- * // Dynamic banner
- * const banner: InjectableCodeType = (name, argv) => {
- *   const version = argv.version || '1.0.0';
- *   return `\/* Built by ${name} v${version} at ${new Date().toISOString()} *\/`;
+ * const cached: CachedServiceInterface = {
+ *   config: parsedConfig,
+ *   host: languageHost,
+ *   service: tsLanguageService,
+ *   refCount: 1
  * };
+ *
+ * // Another consumer acquires the same service
+ * cached.refCount++; // Now 2
+ *
+ * // Consumers finish and dispose
+ * cached.refCount--; // Now 1
+ * cached.refCount--; // Now 0, triggers cleanup
  * ```
  *
- * @see {@link BaseBuildDefinitionInterface.banner}
- * @see {@link BaseBuildDefinitionInterface.footer}
+ * @see {@link TypescriptService}
+ * @see {@link LanguageHostService}
  *
  * @since 2.0.0
  */
-type InjectableCodeType = string | ((name: string, argv: Record<string, unknown>) => string);
+interface CachedServiceInterface {
+    /**
+     * Number of active consumers currently using this cached language service instance.
+     *
+     * @remarks
+     * This counter tracks how many TypeScript service instances are sharing this cached language service.
+     * When it reaches zero, the service can be safely disposed of and removed from the cache.
+     *
+     * @since 2.0.0
+     */
+    refCount: number;
+    /**
+     * Language service host managing file system operations and compiler options for this instance.
+     * @since 2.0.0
+     */
+    host: LanguageHostService;
+    /**
+     * TypeScript language service providing type checking, analysis, and compilation capabilities.
+     * @since 2.0.0
+     */
+    service: LanguageService;
+    /**
+     * Parsed TypeScript configuration including compiler options, file names, and project references.
+     *
+     * @remarks
+     * This configuration is reloaded when the `tsconfig.json` file changes, ensuring the cached
+     * service stays synchronized with the project's compilation settings.
+     *
+     * @since 2.0.0
+     */
+    config: ParsedCommandLine;
+}
 /**
- * Defines lifecycle hook handlers for build process stages.
- * Allows registration of custom logic during resolution, loading, build start, build end, and success.
+ * Represents formatted diagnostic information from TypeScript compilation, including errors, warnings, and suggestions.
+ * Provides a simplified interface for displaying compiler messages with optional source location details.
  *
  * @remarks
- * This interface groups all available lifecycle hooks in a single configuration object.
- * All hooks are optional, allowing selective registration of only necessary handlers.
- *
- * Hook execution order during a build:
- * 1. `onStart` - Before any file processing
- * 2. `onResolve` - During import path resolution
- * 3. `onLoad` - When loading file contents
- * 4. `onEnd` - After build completes (success or failure)
- * 5. `onSuccess` - After a build completes successfully
+ * This interface normalizes TypeScript's diagnostic format into a structure suitable for display in logs,
+ * editor integrations, or build output. All location information (file, line, column) is optional because
+ * some diagnostics apply globally or lack specific source positions.
  *
- * Each hook receives a specialized context object appropriate for its lifecycle stage, providing
- * access to build configuration, variant information, and cross-hook communication through the
- * shared stage object.
+ * Line and column numbers are 1-indexed to match standard editor conventions, even though TypeScript
+ * internally uses 0-indexed positions.
  *
  * @example
  * ```ts
- * const hooks: LifecycleHooksInterface = {
- *   onStart: async (context) => {
- *     console.log(`${context.variantName} build starting...`);
- *   },
- *   onLoad: async (context) => {
- *     if (context.args.path.endsWith('.custom')) {
- *       return { contents: transform(context.contents), loader: 'ts' };
- *     }
- *   },
- *   onSuccess: async (context) => {
- *     console.log(`Build succeeded in ${context.duration}ms!`);
- *   }
+ * const diagnostic: DiagnosticInterface = {
+ *   file: 'src/index.ts',
+ *   line: 42,
+ *   column: 15,
+ *   code: 2304,
+ *   message: "Cannot find name 'unknownVariable'."
  * };
+ *
+ * console.log(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column}`);
+ * console.log(`TS${diagnostic.code}: ${diagnostic.message}`);
  * ```
  *
- * @see {@link OnEndType}
- * @see {@link OnLoadType}
- * @see {@link OnStartType}
- * @see {@link OnResolveType}
+ * @see {@link TypescriptService.check}
+ * @see {@link TypescriptService.formatDiagnostic}
  *
  * @since 2.0.0
  */
-interface LifecycleHooksInterface {
+interface DiagnosticInterface {
     /**
-     * Hook handler executed when the build completes, regardless of success or failure.
+     * File path where the diagnostic occurred.
      *
      * @remarks
-     * Called after all build operations finish with a result context containing the build result,
-     * calculated duration, variant name, arguments, and stage state. Useful for cleanup, logging,
-     * reporting, and post-processing.
-     *
-     * The handler receives `ResultContextInterface` providing access to:
-     * - `buildResult`: Final build outcome with errors and warnings
-     * - `duration`: Build duration in milliseconds
-     * - `variantName`: Build variant identifier
-     * - `argv`: Command-line arguments and configuration
-     * - `stage`: Shared state object for cross-hook communication
+     * Optional because some diagnostics are configuration-level errors that don't relate to a specific file.
      *
-     * @example
-     * ```ts
-     * onEnd: async (context) => {
-     *   const { buildResult, duration, variantName } = context;
-     *   console.log(`${variantName} completed in ${duration}ms`);
-     *   if (buildResult.errors.length > 0) {
-     *     // Handle errors
-     *   }
-     * }
-     * ```
+     * @since 2.0.0
+     */
+    file?: string;
+    /**
+     * Line number where the diagnostic occurred, 1-indexed.
      *
-     * @see {@link ResultContextInterface}
+     * @remarks
+     * Optional because diagnostics without source location (like config errors) won't have line information.
+     * When present, this value is 1-indexed to match standard editor conventions.
      *
      * @since 2.0.0
      */
-    onEnd?: OnEndType;
+    line?: number;
     /**
-     * Hook handler executed when loading file contents during module processing.
+     * Column number where the diagnostic occurred, 1-indexed.
      *
      * @remarks
-     * Called for each file being processed with a load context containing the current file contents
-     * (potentially transformed by previous hooks), loader type, load arguments, variant name, and
-     * stage state. Can transform contents and change the loader type. Multiple handlers execute in
-     * a pipeline pattern where each receives the output of previous hooks.
+     * Optional because diagnostics without source location won't have column information.
+     * When present, this value is 1-indexed to match standard editor conventions.
      *
-     * The handler receives `LoadContextInterface` providing access to:
-     * - `contents`: Current file contents (string or binary)
-     * - `loader`: Current loader type (e.g., 'ts', 'js', 'json')
-     * - `args`: Load arguments including file path and namespace
-     * - `variantName`: Build variant identifier
-     * - `argv`: Command-line arguments and configuration
-     * - `stage`: Shared state object for cross-hook communication
+     * @since 2.0.0
+     */
+    column?: number;
+    /**
+     * TypeScript diagnostic code identifying the specific error or warning type.
+     *
+     * @remarks
+     * Optional because not all diagnostics have associated error codes. When present, this can be used
+     * to look up detailed documentation or implement diagnostic-specific handling.
      *
      * @example
-     * ```ts
-     * onLoad: async (context) => {
-     *   const { contents, args, variantName } = context;
-     *   if (args.path.endsWith('.custom')) {
-     *     return {
-     *       contents: transform(contents.toString()),
-     *       loader: 'ts'
-     *     };
-     *   }
-     * }
-     * ```
+     * Common codes include 2304 (cannot find name), 2322 (type not assignable), 2307 (cannot find module).
      *
-     * @see {@link LoadContextInterface}
+     * @since 2.0.0
+     */
+    code?: number;
+    /**
+     * Human-readable diagnostic message describing the error, warning, or suggestion.
+     *
+     * @remarks
+     * This message is flattened from TypeScript's potentially nested diagnostic message structure
+     * using newline separators for multi-line messages.
      *
      * @since 2.0.0
      */
-    onLoad?: OnLoadType;
+    message: string;
     /**
-     * Hook handler executed when the build process begins.
+     * Category of the diagnostic indicating its severity level.
      *
      * @remarks
-     * Called before any file processing starts with a build context containing the esbuild build object,
-     * variant name, arguments, and stage state. Useful for initialization, validation, and setup tasks.
+     * Determines how the diagnostic should be treated and displayed. TypeScript uses this to distinguish
+     * between different severity levels:
+     * - `DiagnosticCategory.Error` (1): Compilation-blocking errors
+     * - `DiagnosticCategory.Warning` (0): Non-blocking warnings
+     * - `DiagnosticCategory.Suggestion` (2): Code improvement suggestions
+     * - `DiagnosticCategory.Message` (3): Informational messages
      *
-     * The handler receives `BuildContextInterface` providing access to:
-     * - `build`: esbuild plugin build object with configuration and utilities
-     * - `variantName`: Build variant identifier
-     * - `argv`: Command-line arguments and configuration
-     * - `stage`: Shared state object for cross-hook communication
+     * This property is essential for filtering diagnostics by severity and determining whether
+     * a build should fail or continue.
      *
      * @example
      * ```ts
-     * onStart: async (context) => {
-     *   const { build, variantName, stage } = context;
-     *   console.log(`Starting ${variantName} build`);
-     *   stage.startTime = new Date();
-     *
-     *   // Validate configuration
-     *   if (!build.initialOptions.outdir) {
-     *     return { errors: [{ text: 'Output directory required' }] };
-     *   }
+     * if (diagnostic.category === DiagnosticCategory.Error) {
+     *   console.error(`Error: ${diagnostic.message}`);
+     *   process.exit(1);
      * }
      * ```
      *
-     * @see {@link BuildContextInterface}
+     * @since 2.0.0
+     */
+    category: DiagnosticCategory;
+}
+/**
+ * Implements a TypeScript Language Service host with file snapshot caching and module resolution.
+ *
+ * @remarks
+ * The `LanguageHostService` implements the {@link ts.LanguageServiceHost} interface to provide
+ * TypeScript's language service with file system access, file snapshots, and compiler configuration.
+ *
+ * @example
+ * ```ts
+ * // Initialize with compiler options
+ * const host = new LanguageHostService({
+ *   target: ts.ScriptTarget.ES2020,
+ *   module: ts.ModuleKind.ESNext,
+ *   paths: {
+ *     '@utils/*': ['src/utils/*'],
+ *     '@components/*': ['src/components/*']
+ *   }
+ * });
+ *
+ * // Track files for analysis
+ * host.touchFile('src/index.ts');
+ * host.touchFiles(['src/utils.ts', 'src/types.ts']);
+ *
+ * // Get file snapshots for language service
+ * const snapshot = host.getScriptSnapshot('src/index.ts');
+ *
+ * // Resolve module imports
+ * const resolved = host.resolveModuleName('@utils/helpers', 'src/index.ts');
+ *
+ * // Check for path aliases
+ * const hasAliases = host.aliasRegex !== undefined;
+ *
+ * // Update configuration
+ * host.options = { target: ts.ScriptTarget.ES2022 };
+ * ```
+ *
+ * @see {@link ts.LanguageServiceHost} for the implemented interface specification
+ * @see {@link FilesModel} for file snapshot caching implementation
+ *
+ * @since 2.0.0
+ */
+declare class LanguageHostService implements ts.LanguageServiceHost {
+    private compilerOptions;
+    /**
+     * Reference to TypeScript's system interface for file operations.
+     *
+     * @remarks
+     * Static reference to `ts.sys` that provides abstracted file system operations
+     * (read, write, directory traversal) compatible with different environments (Node.js, browsers, etc.).
+     * Used for all file I/O operations in this service to maintain platform independence.
+     *
+     * @see {@link ts.sys}
      *
      * @since 2.0.0
      */
-    onStart?: OnStartType;
+    private static readonly sys;
     /**
-     * Hook handler executed when the build completes successfully without errors.
+     * Cached regular expression for matching import/export statements with path aliases.
      *
      * @remarks
-     * Only called when `buildResult.errors.length === 0`, after all regular end hooks have completed.
-     * Receives the same result context as end hooks, containing build result, duration, variant name,
-     * arguments, and stage state. Useful for deployment, success notifications, and success-only operations.
-     *
-     * The handler receives `ResultContextInterface` providing access to:
-     * - `buildResult`: Final build outcome (guaranteed to have zero errors)
-     * - `duration`: Build duration in milliseconds
-     * - `variantName`: Build variant identifier
-     * - `argv`: Command-line arguments and configuration
-     * - `stage`: Shared state object for cross-hook communication
+     * Compiled from `compilerOptions.paths` to efficiently detect imports using path aliases.
+     * Regenerated when compiler options change. Undefined if no path aliases are configured.
      *
-     * @example
-     * ```ts
-     * onSuccess: async (context) => {
-     *   const { buildResult, duration, variantName } = context;
-     *   console.log(`${variantName} succeeded in ${duration}ms!`);
-     *   await deploy(buildResult.metafile);
-     * }
-     * ```
+     * Used by tools that need to identify which import statements use aliases for proper
+     * handling during transformation or bundling.
      *
-     * @see {@link ResultContextInterface}
+     * @see {@link generateAliasRegex} for pattern generation
      *
      * @since 2.0.0
      */
-    onSuccess?: OnEndType;
+    private alias;
     /**
-     * Hook handler executed during module path resolution.
+     * Cache for resolved module specifiers.
      *
      * @remarks
-     * Called when resolving import paths to file system locations with a resolve context containing
-     * the resolution arguments, variant name, and stage state. Can redirect imports, mark modules as
-     * external, or implement custom resolution logic. Multiple handlers execute, and their results are
-     * merged, with later hooks able to override earlier ones.
+     * Stores the absolute resolved file path for each module name so repeated lookups
+     * do not trigger TypeScript module resolution again. A value of `undefined` means
+     * the module could not be resolved and that result is cached too.
      *
-     * The handler receives `ResolveContextInterface` providing access to:
-     * - `args`: Resolution arguments including import path and importer info
-     * - `variantName`: Build variant identifier
-     * - `argv`: Command-line arguments and configuration
-     * - `stage`: Shared state object for cross-hook communication
+     * This cache is keyed by the raw import specifier, so it is only safe when the
+     * same specifier is resolved in a compatible context.
      *
-     * @example
-     * ```ts
-     * onResolve: async (context) => {
-     *   const { args, variantName } = context;
+     * @since 2.3.0
+     */
+    private aliasCache;
+    /**
+     * Cache for TypeScript module resolution results.
      *
-     *   // Redirect '@/' imports to 'src/'
-     *   if (args.path.startsWith('@/')) {
-     *     return {
-     *       path: resolve('src', args.path.slice(2)),
-     *       namespace: 'file'
-     *     };
-     *   }
+     * @remarks
+     * TypeScript's internal module resolution cache that stores resolution results to avoid
+     * redundant lookups. Improves performance significantly when resolving many imports,
+     * especially in large projects with complex path mappings.
      *
-     *   // Mark as external in production
-     *   if (variantName === 'production' && args.path.includes('node_modules')) {
-     *     return { path: args.path, external: true };
-     *   }
-     * }
-     * ```
+     * Recreated when compiler options change (since different options may affect resolution).
      *
-     * @see {@link ResolveContextInterface}
+     * @see {@link ts.createModuleResolutionCache}
      *
      * @since 2.0.0
      */
-    onResolve?: OnResolveType;
-}
-/**
- * Configuration options for TypeScript declaration file generation.
- *
- * @remarks
- * Controls how and where TypeScript declaration files (`.d.ts`) are generated during the build.
- * These options work in conjunction with the TypeScript compiler to produce type definitions
- * for bundled code.
- *
- * When `bundle` is true, declarations from multiple source files are combined into a single
- * declaration file per entry point. When false, individual declaration files are generated
- * for each source file.
- *
- * @example
- * ```ts
- * // Generate bundled declarations in custom directory
- * const options: DeclarationOptionsInterface = {
- *   outDir: 'types',
- *   bundle: true
- * };
- * ```
- *
- * @see {@link BaseBuildDefinitionInterface.declaration}
- *
- * @since 2.0.0
- */
-interface DeclarationOptionsInterface {
+    private moduleResolutionCache;
     /**
-     * Output directory for generated declaration files.
+     * A set containing the file paths of all actively tracked script files.
      *
      * @remarks
-     * Specifies where `.d.ts` files should be written. If not provided, uses the TypeScript
-     * compiler's `declarationDir` or `outDir` from `tsconfig.json`.
+     * This set ensures that files are tracked for later operations, such as retrieving script versions
+     * or snapshots. Files are added to this set when they are first processed or read by the service.
      *
      * @example
      * ```ts
-     * outDir: 'dist/types'
+     * trackFiles.add('/src/main.ts');
+     * console.log(trackFiles.has('/src/main.ts')); // true
      * ```
      *
+     * @see {@link getScriptFileNames} - Retrieves all tracked files.
+     *
      * @since 2.0.0
      */
-    outDir?: string;
+    private readonly trackFiles;
     /**
-     * Whether to bundle declarations into a single file per entry point.
+     * Model for managing file snapshots and version tracking.
      *
      * @remarks
-     * When true, combines all declarations from imported modules into a single `.d.ts` file.
-     * When false, generates individual declaration files mirroring the source structure.
+     * Delegates file snapshot management to {@link FilesModel} for centralized
+     * caching and change detection. Snapshots are tracked by modification time
+     * to detect file changes efficiently.
      *
-     * Bundling is useful for library distribution as it provides a single type definition file
-     * that consumers can reference.
+     * @see {@link FilesModel}
+     *
+     * @since 2.0.0
+     */
+    private readonly filesCache;
+    /**
+     * Initializes a new {@link LanguageHostService} instance.
+     *
+     * @param compilerOptions - Optional TypeScript compiler options (defaults to an empty object)
+     *
+     * @remarks
+     * Performs initialization including:
+     * 1. Stores compiler options for later use
+     * 2. Generates path alias regex from options if configured
+     * 3. Creates module resolution cache with appropriate settings
+     *
+     * The module resolution cache is necessary for efficient resolution of imports in large projects.
+     * Path alias regex is generated up-front and cached for performance.
      *
      * @example
      * ```ts
-     * bundle: true  // Produces single bundled .d.ts
-     * bundle: false // Produces multiple .d.ts files
+     * // Create host with default options
+     * const host = new LanguageHostService();
+     *
+     * // Create host with specific compiler options
+     * const host = new LanguageHostService({
+     *   target: ts.ScriptTarget.ES2020,
+     *   module: ts.ModuleKind.ESNext,
+     *   paths: {
+     *     '@utils/*': ['src/utils/*']
+     *   }
+     * });
      * ```
      *
      * @since 2.0.0
      */
-    bundle?: boolean;
-}
-/**
- * Configuration options for TypeScript type checking during builds.
- *
- * @remarks
- * Controls how TypeScript type checking is performed and whether type errors should fail the build.
- * Type checking runs in parallel with the esbuild compilation process for better performance.
- *
- * @example
- * ```ts
- * // Fail build on type errors
- * const options: TypeCheckOptionsInterface = {
- *   failOnError: true
- * };
- * ```
- *
- * @see {@link BaseBuildDefinitionInterface.types}
- *
- * @since 2.0.0
- */
-interface TypeCheckOptionsInterface {
+    constructor(compilerOptions?: CompilerOptions);
     /**
-     * Whether to fail the build when TypeScript errors are detected.
+     * Regular expression that matches import/export statements using path aliases (if `paths` is configured).
      *
      * @remarks
-     * When true, any TypeScript errors will cause the build to fail with a non-zero exit code.
-     * When false, errors are logged, but the build continues and succeeds.
+     * Used mainly for advanced refactoring or rewrite tools that need to identify aliased imports.
      *
-     * Useful in CI/CD pipelines where type safety must be enforced before deployment.
+     * @since 2.0.0
+     */
+    get aliasRegex(): RegExp | undefined;
+    /**
+     * Replaces current compiler options and regenerates derived state (alias regex, module cache).
      *
-     * @example
-     * ```ts
-     * failOnError: true  // Build fails on type errors
-     * failOnError: false // Type errors logged, but build continues
-     * ```
+     * @param options - new compiler configuration
      *
      * @since 2.0.0
      */
-    failOnError?: boolean;
-}
-/**
- * Base configuration shared across all build definitions, including common and variant builds.
- * Provides common settings for hooks, type checking, code injection, and declaration generation.
- *
- * @remarks
- * This interface defines the foundation for build configuration that applies to both common
- * settings and individual build variants. Properties defined here can be overridden at the
- * variant level for customization.
- *
- * Configuration inheritance:
- * - Common build settings apply to all variants
- * - Variant settings override common settings
- * - Objects like `define` are merged (variant takes precedence)
- * - Arrays and primitives replace common values
- *
- * @example
- * ```ts
- * const base: BaseBuildDefinitionInterface = {
- *   types: { failOnError: true },
- *   declaration: { bundle: true, outDir: 'types' },
- *   define: { 'process.env.NODE_ENV': '"production"' },
- *   banner: 'const x = "test"',
- *   hooks: {
- *     onSuccess: async () => console.log('Build complete!')
- *   }
- * };
- * ```
- *
- * @see {@link CommonBuildInterface}
- * @see {@link VariantBuildInterface}
- * @see {@link BuildConfigInterface}
- *
- * @since 2.0.0
- */
-interface BaseBuildDefinitionInterface {
+    set options(options: CompilerOptions);
     /**
-     * Lifecycle hook handlers for build process stages.
+     * Reloads all tracked file snapshots in the shared {@link FilesModel} cache.
      *
      * @remarks
-     * Registers custom handlers for various build lifecycle events including start, resolve,
-     * load, end, and success stages. All hooks are optional.
+     * This method iterates over every currently tracked file path and touches each file again so
+     * the cache can refresh its stored modification time, version, and content snapshot when needed.
+     * It is useful in watch-mode or manual refresh scenarios where the underlying files may have changed
+     * and dependent services need to observe the updated state.
+     *
+     * @since 2.3.0
+     */
+    static reload(): void;
+    /**
+     * Updates file snapshot in the cache and returns the current state.
      *
-     * @see {@link LifecycleHooksInterface}
+     * @param path - file path (relative or absolute)
+     * @returns current snapshot data (version, mtime, content snapshot)
      *
+     * @see {@link FilesModel#touchFile}
      * @since 2.0.0
      */
-    lifecycle?: LifecycleHooksInterface;
+    touchFile(path: string): FileSnapshotInterface;
     /**
-     * TypeScript type checking configuration.
+     * Ensures multiple files are tracked and their snapshots are up to date.
      *
-     * @remarks
-     * Controls whether and how TypeScript type checking is performed during builds.
-     * - `true`: Enable type checking with default options
-     * - `false` or omitted: Disable type checking
-     * - Object: Enable with specific options like `failOnError`
+     * @param filesPath - list of file paths to touch
      *
-     * @example
-     * ```ts
-     * types: true                      // Enable with default
-     * types: { failOnError: true }     // Enable and fail on errors
-     * types: false                     // Disable
-     * ```
+     * @since 2.0.0
+     */
+    touchFiles(filesPath: Array<string>): void;
+    /**
+     * Returns current compiler options used by this host.
      *
-     * @see {@link TypeCheckOptionsInterface}
+     * @returns active TypeScript compiler configuration
      *
      * @since 2.0.0
      */
-    types?: boolean | TypeCheckOptionsInterface;
+    getCompilationSettings(): CompilerOptions;
     /**
-     * Global constants to replace during bundling.
+     * Checks whether a file exists on disk.
      *
-     * @remarks
-     * Defines key-value pairs for constant replacement during the build. Keys are identifiers
-     * or property access expressions, values are JSON-stringified replacements.
+     * @param path - absolute path
+     * @returns `true` if file exists
      *
-     * Commonly used for environment variables, feature flags, and build-time constants.
+     * @since 2.0.0
+     */
+    fileExists(path: string): boolean;
+    /**
+     * Reads file content from disk.
      *
-     * @example
-     * ```ts
-     * define: {
-     *   'process.env.NODE_ENV': '"production"',
-     *   'DEBUG': 'false',
-     *   'VERSION': '"1.2.3"'
-     * }
-     * ```
+     * @param path - absolute path
+     * @param encoding - optional encoding (defaults to UTF-8)
+     * @returns file content or `undefined` if read fails
      *
      * @since 2.0.0
      */
-    define?: Record<string, unknown>;
+    readFile(path: string, encoding?: string): string | undefined;
     /**
-     * Code to inject at the beginning of each output file.
+     * Lists files and/or directories matching criteria.
      *
-     * @remarks
-     * Can be a static string or a function that generates code based on build context.
-     * Commonly used for copyright notices, license headers, or polyfill imports.
+     * @param path - starting directory
+     * @param extensions - allowed file extensions
+     * @param exclude - glob exclude patterns
+     * @param include - glob include patterns
+     * @param depth - max recursion depth
+     * @returns matching file paths
      *
-     * @example
-     * ```ts
-     * banner: 'const x = "test"'
-     * banner: (name, argv) => `const x = "Built: ${new Date().toISOString()}"`
-     * ```
+     * @since 2.0.0
+     */
+    readDirectory(path: string, extensions?: Array<string>, exclude?: Array<string>, include?: Array<string>, depth?: number): Array<string>;
+    /**
+     * Returns immediate subdirectories of a given path.
      *
-     * @see {@link InjectableCodeType}
+     * @param path - directory to list
+     * @returns subdirectory names
      *
      * @since 2.0.0
      */
-    banner?: {
-        [key: string]: InjectableCodeType;
-    };
+    getDirectories(path: string): Array<string>;
     /**
-     * Code to inject at the end of each output file.
+     * Checks whether a directory exists.
      *
-     * @remarks
-     * Can be a static string or a function that generates code based on build context.
-     * Commonly used for initialization code, analytics, or polyfills.
+     * @param path - absolute path
+     * @returns `true` if directory exists
      *
-     * @example
-     * ```ts
-     * footer: '// End of bundle'
-     * footer: (name, argv) => `console.log('Loaded ${name}');`
-     * ```
+     * @since 2.0.0
+     */
+    directoryExists(path: string): boolean;
+    /**
+     * Returns the current working directory used as resolution base.
      *
-     * @see {@link InjectableCodeType}
+     * @returns absolute path of cwd
      *
      * @since 2.0.0
      */
-    footer?: {
-        [key: string]: InjectableCodeType;
-    };
+    getCurrentDirectory(): string;
     /**
-     * TypeScript declaration file generation configuration.
+     * Returns names of all known script files tracked by this host.
+     *
+     * @returns array of resolved absolute paths
      *
      * @remarks
-     * Controls whether and how TypeScript declaration files are generated.
-     * - `true`: Generate declarations with default options
-     * - `false` or omitted: Do not generate declarations
-     * - Object: Generate with specific options like `outDir` and `bundle`
+     * Only includes files previously requested via `getScriptSnapshot` or explicitly `touchFile`/`touchFiles`.
      *
-     * @example
-     * ```ts
-     * declaration: true                              // Generate with default
-     * declaration: { outDir: 'types', bundle: true } // Generate bundled in custom dir
-     * declaration: false                             // Disable
-     * ```
+     * @since 2.0.0
+     */
+    getScriptFileNames(): Array<string>;
+    /**
+     * Returns a path to a default lib `.d.ts` file matching the given target.
      *
-     * @see {@link DeclarationOptionsInterface}
+     * @param options - compiler options (mainly `target`)
+     * @returns absolute path to lib.d.ts / lib.esxxxx.d.ts
      *
      * @since 2.0.0
      */
-    declaration?: boolean | DeclarationOptionsInterface;
-}
-/**
- * Build configuration for a specific build variant including esbuild settings and entry points.
- * Extends base configuration with variant-specific esbuild options and required entry points.
- *
- * @remarks
- * A variant represents a distinct build target with its own entry points and esbuild configuration.
- * Variants inherit settings from the common configuration but can override any property.
- *
- * The `esbuild` property excludes fields that are managed by the build system:
- * - `plugins`: Managed by the hook provider
- * - `define`, `banner`, `footer`: Managed by base configuration
- * - `entryPoints`: Required at variant level (non-nullable)
- *
- * Multiple variants enable building different outputs from the same codebase, such as
- * - Different module formats (ESM, CJS)
- * - Different targets (Node.js, browser)
- * - Different bundles (main, worker, tests)
- *
- * @example
- * ```ts
- * const variant: VariantBuildInterface = {
- *   esbuild: {
- *     entryPoints: ['src/index.ts'],
- *     outdir: 'dist/esm',
- *     format: 'esm',
- *     target: 'es2020'
- *   },
- *   types: true,
- *   declaration: { bundle: true, outDir: 'dist/types' }
- * };
- * ```
- *
- * @see {@link VariantsType}
- * @see {@link CommonBuildInterface}
- * @see {@link BaseBuildDefinitionInterface}
- *
- * @since 2.0.0
- */
-interface VariantBuildInterface extends BaseBuildDefinitionInterface {
+    getDefaultLibFileName(options: CompilerOptions): string;
     /**
-     * Esbuild-specific configuration for this variant including entry points.
+     * Returns string version identifier for the given file.
+     *
+     * @param path - file path
+     * @returns version as string (usually `"0"`, `"1"`, `"2"`, …)
      *
      * @remarks
-     * Contains all esbuild options except those managed by the build system.
-     * The `entryPoints` field is required and must be non-empty to define what to build.
+     * Tracks file in `trackFiles` set as a side effect so it appears in `getScriptFileNames()`.
      *
-     * Common options include:
-     * - `format`: Output format (esm, cjs, iife)
-     * - `outdir` or `outfile`: Output location
-     * - `target`: ECMAScript target version
-     * - `platform`: Target platform (browser, node, neutral)
-     * - `minify`: Whether to minify output
-     * - `sourcemap`: Whether to generate source maps
+     * @since 2.0.0
+     */
+    getScriptVersion(path: string): string;
+    /**
+     * Checks whether a file is actively tracked (has been requested before).
      *
-     * @example
-     * ```ts
-     * esbuild: {
-     *   entryPoints: ['src/index.ts', 'src/worker.ts'],
-     *   outdir: 'dist',
-     *   format: 'esm',
-     *   target: 'es2020',
-     *   minify: true,
-     *   sourcemap: true
-     * }
-     * ```
+     * @param path - file path
+     * @returns `true` if the file is known to this host
      *
      * @since 2.0.0
      */
-    esbuild: Omit<BuildOptions, 'plugins' | 'define' | 'banner' | 'footer'>;
-}
-/**
- * Shared configuration applied to all build variants.
- * Extends base configuration with esbuild settings but without entry points.
- *
- * @remarks
- * Common configuration provides default settings that apply to all variants unless overridden.
- * This reduces duplication when multiple variants share similar settings.
- *
- * The `esbuild` property excludes managed fields and `entryPoints` (which must be variant-specific).
- * Settings defined here are merged with variant-specific settings, with variants taking precedence.
- *
- * Typical use cases:
- * - Shared compiler options (target, platform)
- * - Common minification and sourcemap settings
- * - Shared external dependencies
- * - Default output configuration
- *
- * @example
- * ```ts
- * const common: CommonBuildInterface = {
- *   esbuild: {
- *     target: 'es2020',
- *     platform: 'node',
- *     sourcemap: true,
- *     external: ['react', 'react-dom']
- *   },
- *   types: { failOnError: true },
- *   declaration: true
- * };
- * ```
- *
- * @see {@link BaseBuildDefinitionInterface}
- * @see {@link VariantBuildInterface}
- * @see {@link BuildConfigInterface}
- *
- * @since 2.0.0
- */
-interface CommonBuildInterface extends BaseBuildDefinitionInterface {
+    hasScriptSnapshot(path: string): boolean;
+    /**
+     * Returns an up-to-date script snapshot for the file.
+     *
+     * @param path - file path
+     * @returns `IScriptSnapshot` or `undefined` if a file is missing/empty
+     *
+     * @remarks
+     * Automatically touches the file (reads disk if needed) when no snapshot exists yet.
+     *
+     * @since 2.0.0
+     */
+    getScriptSnapshot(path: string): IScriptSnapshot | undefined;
     /**
-     * Shared esbuild configuration for all variants.
+     * Resolves module import using current compiler options and cache.
+     *
+     * @param moduleName - module specifier
+     * @param containingFile - path of a file containing the import
+     * @returns resolution result (success and failed lookups)
+     *
+     * @since 2.0.0
+     */
+    resolveModuleName(moduleName: string, containingFile: string): ResolvedModuleWithFailedLookupLocations;
+    /**
+     * Resolves a module specifier to its absolute file path using the host.
+     *
+     * @param moduleName - import/export specifier (e.g. "lodash", "./utils")
+     * @param containingFile - path of a file containing the import
+     * @returns resolved absolute path or `undefined` if resolution fails
+     *
+     * @since 2.0.0
+     */
+    resolveModuleFileName(moduleName: string, containingFile: string): string | undefined;
+    /**
+     * Rewrites path aliases in declaration content to relative paths.
+     *
+     * @param content - raw declaration text
+     * @param fileName - source file name
+     * @param type - file extension to append to resolved paths (e.g., `'.d.ts'`, `'.js'`), defaults to empty string
+     * @returns content with aliases replaced by relative paths
      *
      * @remarks
-     * Contains esbuild options that apply to all variants by default. Variants can override
-     * any of these settings with their own specific values.
+     * Ensures emitted files use portable relative imports instead of aliases.
+     * The `type` parameter allows flexible transformation of resolved TypeScript source file extensions
+     * (`.ts`, `.tsx`) to any target extension.
      *
-     * Excludes managed fields and `entryPoints` since entry points must be variant-specific.
+     * **Common use cases**:
+     * - Pass `'.d.ts'` for declaration file generation
+     * - Pass `'.js'` for JavaScript output paths
+     * - Pass `''` (default) to preserve the resolved file extension
      *
      * @example
      * ```ts
-     * esbuild: {
-     *   platform: 'node',
-     *   target: 'node18',
-     *   external: ['typescript']
-     * }
+     * // For regular source files (preserve extension)
+     * const code = host.resolveAliases(content, 'src/index.ts');
+     *
+     * // For declaration files
+     * const dts = host.resolveAliases(content, 'src/index.ts', '.d.ts');
+     * // '@utils/helpers' -> './utils/helpers.d.ts'
+     *
+     * // For JavaScript output
+     * const js = host.resolveAliases(content, 'src/index.ts', '.js');
+     * // '@utils/helpers' -> './utils/helpers.js'
      * ```
      *
      * @since 2.0.0
      */
-    esbuild?: Omit<BuildOptions, 'plugins' | 'define' | 'banner' | 'footer'>;
+    resolveAliases(content: string, fileName: string, type?: string): string;
+    /**
+     * Builds regex that matches import/export declarations using any configured path alias.
+     *
+     * @param config - compiler options containing `paths`
+     * @returns regex or `undefined` if no `paths` configured
+     *
+     * @since 2.0.0
+     */
+    private static generateAliasRegex;
 }
 /**
- * Maps variant names to their build configurations.
- * Allows defining multiple build targets with different entry points and settings.
+ * Extended TypeScript script snapshot that includes direct access to the underlying text content.
  *
  * @remarks
- * This type represents a collection of named build variants. Each key is a user-defined
- * variant name (e.g., 'esm', 'cjs', 'browser'), and each value is the complete build
- * configuration for that variant.
+ * This type augments TypeScript's standard `IScriptSnapshot` interface with a `text` property,
+ * providing direct access to the original source text without requiring method calls.
  *
- * Variant names are used for:
- * - CLI targeting specific builds
- * - Build output organization
- * - Logging and error reporting
- * - Parallel build coordination
+ * TypeScript's native `IScriptSnapshot` only exposes text through the `getText()` method.
+ * This extended type adds a `text` property for more convenient access to the full content,
+ * particularly useful in caching scenarios where the source text is frequently referenced.
+ *
+ * Primarily used by {@link FilesModel} to store file content snapshots in an efficient,
+ * readily accessible format for incremental compilation and language service operations.
  *
  * @example
  * ```ts
- * const variants: VariantsType = {
- *   esm: {
- *     esbuild: {
- *       entryPoints: ['src/index.ts'],
- *       format: 'esm',
- *       outdir: 'dist/esm'
- *     }
- *   },
- *   cjs: {
- *     esbuild: {
- *       entryPoints: ['src/index.ts'],
- *       format: 'cjs',
- *       outdir: 'dist/cjs'
- *     }
- *   }
+ * const snapshot: ScriptSnapshotType = {
+ *   ...ts.ScriptSnapshot.fromString(content),
+ *   text: content
  * };
+ *
+ * // Direct text access (convenient)
+ * console.log(snapshot.text);
+ *
+ * // Method-based access (standard IScriptSnapshot)
+ * console.log(snapshot.getText(0, snapshot.getLength()));
  * ```
  *
- * @see {@link VariantBuildInterface}
- * @see {@link BuildConfigInterface}
+ * @see {@link IScriptSnapshot}
+ * @see {@link FilesModel.touchFile}
+ * @see {@link FileSnapshotInterface}
  *
  * @since 2.0.0
  */
-type VariantsType = {
-    [variantName: string]: VariantBuildInterface;
+type ScriptSnapshotType = IScriptSnapshot & {
+    text: string;
 };
 /**
- * Complete build configuration including common settings, variants, and CLI options.
- * Serves as the root configuration object for the entire build system.
- *
- * @remarks
- * This interface defines the complete structure of the build configuration file. It includes:
- * - Optional common settings shared across all variants
- * - Required variants mapping defining all build targets
- * - Optional verbose logging flag
- * - Optional custom command-line argument definitions
- *
- * The configuration is typically exported from a `build.config.ts` or similar file and
- * loaded by the build system at startup.
- *
- * Configuration resolution:
- * 1. Load the configuration file
- * 2. Parse command-line arguments using `userArgv` definitions
- * 3. Merge common settings with each variant
- * 4. Execute builds for all or selected variants
+ * Represents the cached state of a single file for incremental TypeScript processing.
  *
- * @example
- * ```ts
- * const config: BuildConfigInterface = {
- *   verbose: true,
- *   common: {
- *     esbuild: {
- *       platform: 'node',
- *       target: 'node18'
- *     },
- *     types: true
- *   },
- *   variants: {
- *     esm: {
- *       esbuild: {
- *         entryPoints: ['src/index.ts'],
- *         format: 'esm',
- *         outdir: 'dist/esm'
- *       }
- *     },
- *     cjs: {
- *       esbuild: {
- *         entryPoints: ['src/index.ts'],
- *         format: 'cjs',
- *         outdir: 'dist/cjs'
- *       }
- *     }
- *   },
- *   userArgv: {
- *     watch: { type: 'boolean', description: 'Watch for changes' }
- *   }
- * };
- * ```
+ * Stores the modification timestamp, a version counter that increments on every meaningful change,
+ * and an optional TypeScript `ScriptSnapshot` containing the file content in a memory-efficient form.
  *
- * @see {@link VariantsType}
- * @see {@link CommonBuildInterface}
- * @see {@link PartialBuildConfigType}
+ * Used by language services and build tools to quickly determine whether a file needs to be reparsed.
  *
  * @since 2.0.0
  */
-interface BuildConfigInterface {
+interface FileSnapshotInterface {
     /**
-     * Shared configuration applied to all build variants.
+     * Last known modification time of the file in milliseconds since epoch.
      *
-     * @remarks
-     * Optional common settings that are merged with each variant's configuration.
-     * Variants can override these settings with their own specific values.
+     * Set to `0` when the file no longer exists or cannot be accessed.
      *
-     * @see {@link CommonBuildInterface}
+     * @remarks
+     * Compared directly against `fs.stat().mtimeMs` to detect changes without reading content.
      *
      * @since 2.0.0
      */
-    common?: CommonBuildInterface;
+    mtimeMs: number;
     /**
-     * Enable verbose logging output during builds.
+     * Monotonically increasing integer that changes whenever the file content or accessibility status changes.
+     *
+     * Used by TypeScript language services as the script version identifier.
      *
      * @remarks
-     * When true, outputs detailed build information including file processing,
-     * hook execution, and timing information. Useful for debugging build issues.
+     * - Incremented on every successful content read with changed mtime
+     * - Incremented when a file becomes unreadable (if it previously had content or version bigger than 0)
+     * - Not incremented on no-op accesses (unchanged mtime)
      *
      * @example
      * ```ts
-     * verbose: true  // Detailed output
-     * verbose: false // Minimal output
+     * // Typical usage in LanguageServiceHost
+     * getScriptVersion(fileName: string): string {
+     *   const snapshot = cache.touchFile(fileName);
+     *   return String(snapshot.version);
+     * }
      * ```
      *
      * @since 2.0.0
      */
-    verbose?: boolean;
+    version: number;
     /**
-     * Build variant definitions mapping names to configurations.
+     * TypeScript script snapshot containing the file's source text, or `undefined` if the file is missing,
+     * empty, or inaccessible.
      *
      * @remarks
-     * Required field defining all build targets. At least one variant must be defined.
-     * Each variant specifies its own entry points and can override common settings.
+     * - Created via `ts.ScriptSnapshot.fromString(content)`
+     * - Kept `undefined` for zero-length or non-readable files to save memory
+     * - Consumers should check existence before calling methods like `getText()`
      *
-     * @see {@link VariantsType}
+     * @see ScriptSnapshotType
+     * @see {@link https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API#script-snapshot | TypeScript Compiler API – Script Snapshots}
      *
      * @since 2.0.0
      */
-    variants: VariantsType;
+    contentSnapshot: ScriptSnapshotType | undefined;
 }
-/**
- * Partial build configuration for incremental or programmatic configuration building.
- * Allows omitting variants and userArgv while making other fields optional.
- *
- * @remarks
- * This type is useful when building configuration programmatically or when providing
- * configuration fragments that will be merged with a base configuration. It makes
- * all properties optional except `variants` and `userArgv` which are completely omitted.
- *
- * Common use cases:
- * - Configuration presets or templates
- * - Programmatic configuration generation
- * - Configuration merging utilities
- * - Partial overrides in build scripts
- *
- * @example
- * ```ts
- * const preset: PartialBuildConfigType = {
- *   verbose: true,
- *   common: {
- *     types: { failOnError: true },
- *     declaration: true
- *   }
- * };
- *
- * // Merge with full config
- * const fullConfig: BuildConfigInterface = {
- *   ...preset,
- *   variants: { ... }
- * };
- * ```
- *
- * @see {@link BuildConfigInterface}
- *
- * @since 2.0.0
- */
-type PartialBuildConfigType = Partial<BuildConfigInterface>;
 /**
  * Provides a file-watching service that tracks changes in the framework's root directory.
  *