@remotex-labs/xbuild 2.2.3 → 2.3.0

package/dist/index.d.ts

@@ -6,7 +6,7 @@
 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 { IncomingMessage, ServerResponse } from 'http';
-import { PositionInterface, SourceService } from '@remotex-labs/xmap';
+import { ResolveMetadataInterface as xMapResolveMetadataInterface, ResolveOptionsInterface } from '@remotex-labs/xmap';
 import { Options } from 'yargs';
 
 /**
@@ -224,31 +224,43 @@ declare class BuildService {
      * Reloads the build configuration and updates variants accordingly.
      *
      * @param config - Optional new configuration to replace the current one
+     * @param clearCache - Whether to clear cached files and TypeScript language service state before reloading
      *
      * @remarks
      * The reload process:
-     * 1. Replaces configuration if provided
-     * 2. Compares new variant names with existing ones
-     * 3. Disposes variants no longer in configuration
-     * 4. Creates new variants from the updated configuration
-     * 5. Existing variants with matching names continue unchanged
+     * 1. Optionally clears cached file state and TypeScript language service data
+     * 2. Replaces configuration if provided
+     * 3. Compares new variant names with existing ones
+     * 4. Disposes variants no longer in configuration
+     * 5. Creates new variants from the updated configuration
+     * 6. Existing variants with matching names continue unchanged
      *
      * This is useful for hot-reloading configuration files without restarting the build process.
      *
      * @example
      * ```ts
-     * // Add a new staging variant
+     * // Reload with a new staging variant
      * buildService.reload({
-     *   variants: {
-     *     ...buildService.config.variants,
-     *     staging: { esbuild: { minify: true } }
+     *   config: {
+     *     variants: {
+     *       ...buildService.config.variants,
+     *       staging: { esbuild: { minify: true } }
+     *     }
      *   }
      * });
      * ```
      *
-     * @since 2.0.0
+     * @example
+     * ```ts
+     * // Reload and clear cached file/type-checking state first
+     * buildService.reload({
+     *   clearCache: true
+     * });
+     * ```
+     *
+     * @since 2.3.0
      */
-    reload(config?: PartialBuildConfigType): void;
+    reload({ config, clearCache }?: ReloadOptionsInterface): void;
     /**
      * Notifies all variants that specific files have been modified.
      *
@@ -743,6 +755,19 @@ declare class LanguageHostService implements ts.LanguageServiceHost {
      * @since 2.0.0
      */
     private alias;
+    /**
+     * Cache for resolved module specifiers.
+     *
+     * @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.
+     *
+     * @since 2.3.0
+     */
     private aliasCache;
     /**
      * Cache for TypeScript module resolution results.
@@ -839,6 +864,18 @@ declare class LanguageHostService implements ts.LanguageServiceHost {
      * @since 2.0.0
      */
     set options(options: CompilerOptions);
+    /**
+     * Reloads all tracked file snapshots in the shared {@link FilesModel} cache.
+     *
+     * @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.
      *
@@ -1139,1689 +1176,1717 @@ interface FileSnapshotInterface {
     contentSnapshot: ScriptSnapshotType | undefined;
 }
 /**
- * Recursively makes all properties of a type optional.
+ * Extended build result interface with normalized error and warning arrays.
  *
  * @remarks
- * This utility type behaves like TypeScript’s built-in {@link Partial} type,
- * but applies recursively to all nested object properties.
+ * 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.
  *
- * It is commonly used for:
- * - Partial configuration overrides
- * - Patch / update objects
- * - Programmatic configuration merging
- * - Build variant and preset definitions
+ * **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
  *
- * This type only affects compile-time type checking and has no runtime impact.
+ * **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
  *
- * ⚠️ **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.
+ * 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
- * interface Config {
- *   server: {
- *     host: string;
- *     port: number;
- *   };
- *   features: {
- *     experimental: boolean;
- *   };
- * }
- *
- * const override: DeepPartialType<Config> = {
- *   server: {
- *     port: 8080
- *   }
+ * const result: BuildResultInterface = {
+ *   errors: [
+ *     new esBuildError(esbuildMessage),
+ *     new TypesError('Type checking failed', diagnostics)
+ *   ],
+ *   warnings: [
+ *     new xBuildError('Deprecation warning')
+ *   ],
+ *   metafile: { ... },
+ *   outputFiles: [ ... ],
+ *   mangleCache: { ... }
  * };
  * ```
  *
- * @template T - The type to recursively make optional.
+ * @see {@link BuildResult} from esbuild for the base interface
  *
  * @since 2.0.0
  */
-type DeepPartialType<T> = {
-    [K in keyof T]?: T[K] extends object ? DeepPartialType<T[K]> : T[K];
-};
+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>;
+}
 /**
- * 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 value that may be synchronous, asynchronous, void, null, or the specified type.
  *
- * @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.
+ * @template T - The actual value type when present
  *
- * 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
+ * @remarks
+ * This utility type is used for hook handlers that may return values in multiple forms:
+ * - Synchronous return: `T`, `void`, or `null`
+ * - Asynchronous return: `Promise<T>`, `Promise<void>`, or `Promise<null>`
  *
- * When using the function form, the generated string is cached per build variant to avoid
- * regenerating the same code multiple times.
+ * This flexibility allows hooks to be implemented as sync or async functions and to optionally
+ * return results. Handlers that don't need to return data can return `void` or `null`.
  *
  * @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()} *\/`;
- * };
+ * // All valid implementations
+ * const sync: MaybeVoidPromiseType<string> = 'result';
+ * const voidSync: MaybeVoidPromiseType<string> = null;
+ * const async: MaybeVoidPromiseType<string> = Promise.resolve('result');
+ * const voidAsync: MaybeVoidPromiseType<string> = Promise.resolve(null);
  * ```
  *
- * @see {@link BaseBuildDefinitionInterface.banner}
- * @see {@link BaseBuildDefinitionInterface.footer}
+ * @see {@link OnEndType}
+ * @see {@link OnStartType}
  *
  * @since 2.0.0
  */
-type InjectableCodeType = string | ((name: string, argv: Record<string, unknown>) => string);
+type MaybeVoidPromiseType<T> = void | null | T | Promise<void | null | T>;
 /**
- * Defines lifecycle hook handlers for build process stages.
- * Allows registration of custom logic during resolution, loading, build start, build end, and success.
+ * Represents a value that may be synchronous, asynchronous, undefined, null, or the specified type.
  *
- * @remarks
- * This interface groups all available lifecycle hooks in a single configuration object.
- * All hooks are optional, allowing selective registration of only necessary handlers.
+ * @template T - The actual value type when present
  *
- * 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
+ * @remarks
+ * This utility type is used for hook handlers that may return values in multiple forms:
+ * - Synchronous return: `T`, `undefined`, or `null`
+ * - Asynchronous return: `Promise<T>`, `Promise<undefined>`, or `Promise<null>`
  *
- * 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.
+ * Similar to {@link MaybeVoidPromiseType} but uses `undefined` instead of `void`, allowing handlers
+ * to explicitly return nothing or optionally return results. This distinction is important for
+ * hooks where the absence of a return value has semantic meaning (like allowing default behavior).
  *
  * @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!`);
- *   }
- * };
+ * // All valid implementations
+ * const sync: MaybeUndefinedPromiseType<object> = { path: '/file.ts' };
+ * const undefinedSync: MaybeUndefinedPromiseType<object> = undefined;
+ * const async: MaybeUndefinedPromiseType<object> = Promise.resolve({ path: '/file.ts' });
+ * const undefinedAsync: MaybeUndefinedPromiseType<object> = Promise.resolve(undefined);
  * ```
  *
- * @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
-     */
-    onEnd?: OnEndType;
-    /**
-     * Hook handler executed when loading file contents during module processing.
-     *
-     * @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.
+type MaybeUndefinedPromiseType<T> = undefined | null | T | Promise<undefined | null | T>;
+/**
+ * Represents a transient build stage state shared across hook handlers during a single build.
+ *
+ * @remarks
+ * This interface provides a flexible container for storing temporary data during the build lifecycle.
+ * It's reset at the start of each build and is available to all hooks through the plugin context.
+ *
+ * The `startTime` property is always present and set when the build begins, allowing hooks to
+ * calculate durations and timing information. Additional properties can be added dynamically
+ * using the index signature to facilitate cross-handler communication.
+ *
+ * Common use cases:
+ * - Storing build start time for duration calculations
+ * - Passing data between different hook handlers
+ * - Accumulating statistics during the build
+ * - Caching computed values for reuse across hooks
+ *
+ * @example
+ * ```ts
+ * // In onStart hook
+ * context.stage.startTime = new Date();
+ * context.stage.fileCount = 0;
+ *
+ * // In onLoad hook
+ * context.stage.fileCount++;
+ *
+ * // In onEnd hook
+ * const duration = Date.now() - context.stage.startTime.getTime();
+ * console.log(`Processed ${context.stage.fileCount} files in ${duration}ms`);
+ * ```
+ *
+ * @see {@link LifecycleContextInterface}
+ *
+ * @since 2.0.0
+ */
+interface LifecycleStageInterface {
+    /**
+     * Timestamp when the build process started.
      *
-     * 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
+     * @remarks
+     * Set during the first `onStart` hook execution and available throughout the build lifecycle.
+     * Used to calculate build duration and timing information.
      *
-     * @example
-     * ```ts
-     * onLoad: async (context) => {
-     *   const { contents, args, variantName } = context;
-     *   if (args.path.endsWith('.custom')) {
-     *     return {
-     *       contents: transform(contents.toString()),
-     *       loader: 'ts'
-     *     };
-     *   }
-     * }
-     * ```
+     * @since 2.0.0
+     */
+    startTime: Date;
+    /**
+     * Additional dynamic properties for cross-handler communication.
      *
-     * @see {@link LoadContextInterface}
+     * @remarks
+     * Handlers can store arbitrary data in the stage object using any string key.
+     * This allows passing information between hooks during a single build.
      *
      * @since 2.0.0
      */
-    onLoad?: OnLoadType;
+    [key: string]: unknown;
+}
+/**
+ * Base context interface shared by all lifecycle hook handlers.
+ * Provides access to plugin configuration, command-line arguments, and transient build state.
+ *
+ * @remarks
+ * This context is initialized during the `onStart` phase and remains available throughout the
+ * entire build lifecycle. All hook handlers receive a variant of this context, enabling:
+ * - Access to command-line arguments and configuration
+ * - Cross-handler communication through the stage object
+ * - Consistent variant identification across hooks
+ *
+ * The context is immutable at the top level (variantName and argv don't change during a build),
+ * but the stage object is mutable and reset between builds.
+ *
+ * @example
+ * ```ts
+ * // In onStart hook
+ * const handler: OnStartType = async (context) => {
+ *   console.log(`Variant ${context.variantName} starting`);
+ *   context.stage.customData = { processed: 0 };
+ * };
+ * ```
+ *
+ * @see {@link LoadContextInterface}
+ * @see {@link BuildContextInterface}
+ * @see {@link ResultContextInterface}
+ * @see {@link ResolveContextInterface}
+ * @see {@link LifecycleStageInterface}
+ *
+ * @since 2.0.0
+ */
+interface LifecycleContextInterface {
     /**
-     * Hook handler executed when the build process begins.
+     * Command-line arguments and configuration options passed to the provider.
      *
      * @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
+     * Contains all CLI options and flags passed when the provider was created.
+     * Available to all handlers for accessing build-specific configuration like
+     * debug flags, output paths, or custom settings.
      *
      * @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' }] };
-     *   }
-     * }
+     * context.argv; // { debug: true, verbose: false, outdir: 'dist' }
      * ```
      *
-     * @see {@link BuildContextInterface}
-     *
      * @since 2.0.0
      */
-    onStart?: OnStartType;
+    argv: Record<string, unknown>;
     /**
-     * Hook handler executed when the build completes successfully without errors.
+     * Transient state object for cross-handler communication during a single build.
      *
      * @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.
+     * Reset to contain only `startTime` at the beginning of each build. Handlers can store
+     * and retrieve temporary data during the build lifecycle through this object.
      *
-     * 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
+     * Common patterns:
+     * - Accumulating statistics across multiple hooks
+     * - Passing processed data between different hook types
+     * - Caching expensive computations for reuse
      *
      * @example
      * ```ts
-     * onSuccess: async (context) => {
-     *   const { buildResult, duration, variantName } = context;
-     *   console.log(`${variantName} succeeded in ${duration}ms!`);
-     *   await deploy(buildResult.metafile);
-     * }
+     * // Store data in onLoad
+     * context.stage.transformedFiles = [];
+     *
+     * // Access in onEnd
+     * console.log(`Transformed ${context.stage.transformedFiles.length} files`);
      * ```
      *
-     * @see {@link ResultContextInterface}
+     * @see {@link LifecycleStageInterface}
      *
      * @since 2.0.0
      */
-    onSuccess?: OnEndType;
+    stage: LifecycleStageInterface;
     /**
-     * Hook handler executed during module path resolution.
+     * Identifier for the build variant or plugin instance.
      *
      * @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
+     * Used for identification and logging. Same as the variant name passed to
+     * the HooksProvider constructor or build configuration.
      *
      * @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 };
-     *   }
-     * }
+     * context.variantName; // 'production' or 'development'
      * ```
      *
-     * @see {@link ResolveContextInterface}
-     *
      * @since 2.0.0
      */
-    onResolve?: OnResolveType;
+    variantName: string;
+    /**
+     * esbuild configuration options used for this lifecycle execution.
+     *
+     * @remarks
+     * These options represent the active build configuration for the provider and
+     * are intended to be read by lifecycle handlers when build behavior depends on
+     * entry points, output settings, plugins, or other esbuild flags.
+     *
+     * @since 2.2.0
+     */
+    options: BuildOptions;
 }
 /**
- * Configuration options for TypeScript declaration file generation.
+ * Context interface for `onStart` hooks, providing access to the esbuild plugin build object.
  *
  * @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.
+ * This specialized context extends the base lifecycle context with the esbuild `PluginBuild`
+ * object, giving start hooks access to build configuration, utilities, and the ability to
+ * register additional esbuild hooks dynamically.
  *
- * 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.
+ * Start hooks are the only lifecycle phase that receives the build object, as they execute
+ * before file processing begins and may need to configure or inspect build settings.
  *
  * @example
  * ```ts
- * // Generate bundled declarations in custom directory
- * const options: DeclarationOptionsInterface = {
- *   outDir: 'types',
- *   bundle: true
+ * const handler: OnStartType = async (context) => {
+ *   const { build, variantName, argv } = context;
+ *   console.log(`Starting ${variantName} build`);
+ *
+ *   // Access build configuration
+ *   console.log(`Platform: ${build.initialOptions.platform}`);
+ *
+ *   return { errors: [], warnings: [] };
  * };
  * ```
  *
- * @see {@link BaseBuildDefinitionInterface.declaration}
+ * @see {@link OnStartType}
+ * @see {@link LifecycleContextInterface}
  *
  * @since 2.0.0
  */
-interface DeclarationOptionsInterface {
+interface BuildContextInterface extends LifecycleContextInterface {
     /**
-     * Output directory for generated declaration files.
+     * The esbuild plugin build object providing build configuration and utilities.
      *
      * @remarks
-     * Specifies where `.d.ts` files should be written. If not provided, uses the TypeScript
-     * compiler's `declarationDir` or `outDir` from `tsconfig.json`.
+     * Provides access to:
+     * - `initialOptions`: Build configuration options
+     * - `resolve`: Path resolution utilities
+     * - Dynamic hook registration methods
+     * - Build environment information
+     *
+     * Available only in `onStart` hooks, as later phases don't require build-level access.
      *
      * @example
      * ```ts
-     * outDir: 'dist/types'
+     * // Access initial options
+     * const outdir = context.build.initialOptions.outdir;
+     *
+     * // Resolve a path
+     * const resolved = await context.build.resolve('./module', {
+     *   resolveDir: '/src'
+     * });
      * ```
      *
      * @since 2.0.0
      */
-    outDir?: string;
+    build: PluginBuild;
+}
+/**
+ * Context interface for `onEnd` and `onSuccess` hooks, providing access to build results and duration.
+ *
+ * @remarks
+ * This specialized context extends the base lifecycle context with the final build result
+ * and calculated build duration, giving end hooks access to a build outcome, errors, warnings,
+ * and metadata.
+ *
+ * The duration is automatically calculated from the start time in the stage object, providing
+ * a convenient way to measure build performance without manual timestamp calculations.
+ *
+ * @example
+ * ```ts
+ * const handler: OnEndType = async (context) => {
+ *   const { buildResult, duration, variantName } = context;
+ *
+ *   console.log(`${variantName} build completed in ${duration}ms`);
+ *
+ *   if (buildResult.errors.length > 0) {
+ *     console.error(`Build failed with ${buildResult.errors.length} errors`);
+ *   }
+ *
+ *   // Access metafile for dependency analysis
+ *   if (buildResult.metafile) {
+ *     console.log('Outputs:', Object.keys(buildResult.metafile.outputs));
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link OnEndType}
+ * @see {@link LifecycleContextInterface}
+ *
+ * @since 2.0.0
+ */
+interface ResultContextInterface extends LifecycleContextInterface {
     /**
-     * Whether to bundle declarations into a single file per entry point.
+     * Build duration in milliseconds.
      *
      * @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.
+     * Automatically calculated as the time elapsed from `context.stage.startTime` to
+     * when the build completed. Useful for performance monitoring and reporting.
      *
-     * Bundling is useful for library distribution as it provides a single type definition file
-     * that consumers can reference.
+     * @example
+     * ```ts
+     * console.log(`Build took ${context.duration}ms`);
+     * ```
+     *
+     * @since 2.0.0
+     */
+    duration: number;
+    /**
+     * The final build result from esbuild containing errors, warnings, and metadata.
+     *
+     * @remarks
+     * Provides access to:
+     * - `errors`: Array of build errors
+     * - `warnings`: Array of build warnings
+     * - `metafile`: Build metadata including inputs, outputs, and dependencies
+     * - `outputFiles`: Generated file contents (if `write: false`)
      *
      * @example
      * ```ts
-     * bundle: true  // Produces single bundled .d.ts
-     * bundle: false // Produces multiple .d.ts files
+     * // Check for errors
+     * if (context.buildResult.errors.length > 0) {
+     *   // Handle build failure
+     * }
+     *
+     * // Analyze dependencies
+     * const inputs = context.buildResult.metafile?.inputs;
      * ```
      *
      * @since 2.0.0
      */
-    bundle?: boolean;
+    buildResult: BuildResult;
 }
 /**
- * Configuration options for TypeScript type checking during builds.
+ * Context interface for `onResolve` hooks, providing access to resolution arguments.
  *
  * @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.
+ * This specialized context extends the base lifecycle context with esbuild's resolution
+ * arguments, giving resolve hooks access to the import path, importer information, and
+ * resolution context needed to implement custom module resolution logic.
+ *
+ * Resolve hooks use this context to determine how to resolve import paths, redirect imports,
+ * or mark modules as external based on the resolution arguments.
  *
  * @example
  * ```ts
- * // Fail build on type errors
- * const options: TypeCheckOptionsInterface = {
- *   failOnError: true
+ * const handler: OnResolveType = 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 node_modules as external in development
+ *   if (variantName === 'development' && args.path.includes('node_modules')) {
+ *     return { path: args.path, external: true };
+ *   }
+ *
+ *   return undefined; // Use default resolution
  * };
  * ```
  *
- * @see {@link BaseBuildDefinitionInterface.types}
+ * @see {@link OnResolveType}
+ * @see {@link LifecycleContextInterface}
  *
  * @since 2.0.0
  */
-interface TypeCheckOptionsInterface {
+interface ResolveContextInterface extends LifecycleContextInterface {
     /**
-     * Whether to fail the build when TypeScript errors are detected.
+     * Resolution arguments from esbuild containing the import path and resolution context.
      *
      * @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.
-     *
-     * Useful in CI/CD pipelines where type safety must be enforced before deployment.
+     * Provides access to:
+     * - `path`: The import path to resolve (e.g., './module', '\@/utils')
+     * - `importer`: The file that contains this import
+     * - `namespace`: The namespace of the importer
+     * - `resolveDir`: The directory to resolve relative imports from
+     * - `kind`: The kind of import (e.g., 'import-statement', 'require-call')
+     * - `pluginData`: Data passed from previous plugins
      *
      * @example
      * ```ts
-     * failOnError: true  // Build fails on type errors
-     * failOnError: false // Type errors logged, but build continues
+     * console.log(`Resolving ${context.args.path} from ${context.args.importer}`);
+     *
+     * if (context.args.kind === 'dynamic-import') {
+     *   // Handle dynamic imports specially
+     * }
      * ```
      *
      * @since 2.0.0
      */
-    failOnError?: boolean;
+    args: OnResolveArgs;
 }
 /**
- * Base configuration shared across all build definitions, including common and variant builds.
- * Provides common settings for hooks, type checking, code injection, and declaration generation.
+ * Context interface for `onLoad` hooks, providing access to load arguments, current contents, and loader.
  *
  * @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.
+ * This specialized context extends the base lifecycle context with esbuild's load arguments,
+ * the current file contents (potentially transformed by previous hooks), and the current loader
+ * type. This enables load hooks to implement content transformations in a pipeline pattern.
  *
- * 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
+ * Load hooks receive the output of previous hooks through `contents` and `loader`, allowing
+ * sequential transformations where each hook builds on the work of previous hooks.
  *
  * @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!')
+ * const handler: OnLoadType = async (context) => {
+ *   const { contents, loader, args, variantName } = context;
+ *
+ *   // Transform .custom files to TypeScript
+ *   if (args.path.endsWith('.custom')) {
+ *     return {
+ *       contents: transformCustomSyntax(contents.toString()),
+ *       loader: 'ts'
+ *     };
+ *   }
+ *
+ *   // Add debugging in development
+ *   if (variantName === 'development' && loader === 'ts') {
+ *     return {
+ *       contents: `console.log('Loading: ${args.path}');\n${contents}`,
+ *       loader
+ *     };
  *   }
+ *
+ *   return undefined; // Pass through unchanged
  * };
  * ```
  *
- * @see {@link CommonBuildInterface}
- * @see {@link VariantBuildInterface}
- * @see {@link BuildConfigInterface}
+ * @see {@link OnLoadType}
+ * @see {@link LifecycleContextInterface}
  *
  * @since 2.0.0
  */
-interface BaseBuildDefinitionInterface {
+interface LoadContextInterface extends LifecycleContextInterface {
     /**
-     * Lifecycle hook handlers for build process stages.
+     * Load arguments from esbuild containing file path and namespace.
      *
      * @remarks
-     * Registers custom handlers for various build lifecycle events including start, resolve,
-     * load, end, and success stages. All hooks are optional.
+     * Provides access to:
+     * - `path`: The absolute path to the file being loaded
+     * - `namespace`: The namespace for this module
+     * - `suffix`: Optional suffix for special handling
+     * - `pluginData`: Data passed from resolve hooks or previous plugins
      *
-     * @see {@link LifecycleHooksInterface}
+     * @example
+     * ```ts
+     * console.log(`Loading ${context.args.path}`);
+     *
+     * if (context.args.namespace === 'virtual') {
+     *   // Handle virtual modules
+     * }
+     * ```
      *
      * @since 2.0.0
      */
-    lifecycle?: LifecycleHooksInterface;
+    args: OnLoadArgs;
     /**
-     * TypeScript type checking configuration.
+     * The current loader type for this file.
      *
      * @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`
+     * Reflects any loader changes made by previous hooks in the pipeline. Can be:
+     * - `'js'`, `'ts'`, `'jsx'`, `'tsx'`: JavaScript/TypeScript variants
+     * - `'json'`, `'css'`, `'text'`: Special content types
+     * - `'base64'`, `'binary'`, `'dataurl'`: Binary content encodings
+     * - `'default'`: Let esbuild determine the loader
+     * - `undefined`: No loader has been set yet
+     *
+     * Hooks can change the loader to affect how esbuild processes the contents.
      *
      * @example
      * ```ts
-     * types: true                      // Enable with default
-     * types: { failOnError: true }     // Enable and fail on errors
-     * types: false                     // Disable
+     * if (context.loader === 'json') {
+     *   // Transform JSON before esbuild processes it
+     * }
      * ```
      *
-     * @see {@link TypeCheckOptionsInterface}
-     *
      * @since 2.0.0
      */
-    types?: boolean | TypeCheckOptionsInterface;
+    loader: Loader | undefined;
     /**
-     * Global constants to replace during bundling.
+     * The current file contents as string or binary data.
      *
      * @remarks
-     * Defines key-value pairs for constant replacement during the build. Keys are identifiers
-     * or property access expressions, values are JSON-stringified replacements.
+     * Contains the output of previous load hooks in the pipeline, or the initial file
+     * contents if this is the first hook. Hooks can transform this content and return
+     * new contents for further hooks to process.
      *
-     * Commonly used for environment variables, feature flags, and build-time constants.
+     * Content can be:
+     * - `string`: Text content (source code, JSON, CSS, etc.)
+     * - `Uint8Array`: Binary content (images, fonts, etc.)
      *
      * @example
      * ```ts
-     * define: {
-     *   'process.env.NODE_ENV': '"production"',
-     *   'DEBUG': 'false',
-     *   'VERSION': '"1.2.3"'
+     * // Transform string contents
+     * const transformed = context.contents.toString().replace(/old/g, 'new');
+     *
+     * // Check content type
+     * if (typeof context.contents === 'string') {
+     *   // Handle text
+     * } else {
+     *   // Handle binary
      * }
      * ```
      *
      * @since 2.0.0
      */
-    define?: Record<string, unknown>;
-    /**
-     * Code to inject at the beginning of each output file.
-     *
-     * @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.
-     *
-     * @example
-     * ```ts
-     * banner: 'const x = "test"'
-     * banner: (name, argv) => `const x = "Built: ${new Date().toISOString()}"`
-     * ```
-     *
-     * @see {@link InjectableCodeType}
-     *
-     * @since 2.0.0
-     */
-    banner?: {
-        [key: string]: InjectableCodeType;
-    };
-    /**
-     * Code to inject at the end of each output file.
-     *
-     * @remarks
-     * Can be a static string or a function that generates code based on build context.
-     * Commonly used for initialization code, analytics, or polyfills.
-     *
-     * @example
-     * ```ts
-     * footer: '// End of bundle'
-     * footer: (name, argv) => `console.log('Loaded ${name}');`
-     * ```
-     *
-     * @see {@link InjectableCodeType}
-     *
-     * @since 2.0.0
-     */
-    footer?: {
-        [key: string]: InjectableCodeType;
-    };
-    /**
-     * TypeScript declaration file generation configuration.
-     *
-     * @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`
-     *
-     * @example
-     * ```ts
-     * declaration: true                              // Generate with default
-     * declaration: { outDir: 'types', bundle: true } // Generate bundled in custom dir
-     * declaration: false                             // Disable
-     * ```
-     *
-     * @see {@link DeclarationOptionsInterface}
-     *
-     * @since 2.0.0
-     */
-    declaration?: boolean | DeclarationOptionsInterface;
+    contents: string | Uint8Array;
 }
 /**
- * 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.
+ * Handler function signature for `onStart` hooks executed when a build begins.
  *
- * @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.
+ * @param context - Build context containing the esbuild build object, arguments, and stage state
  *
- * 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)
+ * @returns Optional result containing errors and warnings to report, or void/null if none
  *
- * 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)
+ * @remarks
+ * Start hooks are executed before any file processing occurs and receive a build context
+ * with access to the esbuild `PluginBuild` object. They can perform initialization tasks
+ * and return errors or warnings that will be aggregated with results from other start hooks.
+ *
+ * Return value semantics:
+ * - Return `void` or `null` if the hook has nothing to report
+ * - Return `OnStartResult` with errors/warnings arrays to report issues
+ * - Can be synchronous or asynchronous (return a Promise)
  *
  * @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' }
+ * const onStart: OnStartType = async (context) => {
+ *   console.log(`Starting ${context.variantName} build`);
+ *   context.stage.startTime = new Date();
+ *
+ *   // Validate build configuration
+ *   if (!context.build.initialOptions.outdir) {
+ *     return {
+ *       errors: [{
+ *         text: 'Output directory not specified',
+ *         location: null
+ *       }]
+ *     };
+ *   }
+ *
+ *   return { errors: [], warnings: [] };
  * };
  * ```
  *
- * @see {@link VariantsType}
- * @see {@link CommonBuildInterface}
- * @see {@link BaseBuildDefinitionInterface}
+ * @see {@link MaybeVoidPromiseType}
+ * @see {@link BuildContextInterface}
+ * @see {@link LifecycleProvider.onStart}
  *
  * @since 2.0.0
  */
-interface VariantBuildInterface extends BaseBuildDefinitionInterface {
-    /**
-     * Esbuild-specific configuration for this variant including entry points.
-     *
-     * @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
-     */
-    esbuild: Omit<BuildOptions, 'plugins' | 'define' | 'banner' | 'footer'>;
-}
+type OnStartType = (context: BuildContextInterface) => MaybeVoidPromiseType<OnStartResult>;
 /**
- * Shared configuration applied to all build variants.
- * Extends base configuration with esbuild settings but without entry points.
+ * Handler function signature for `onEnd` and `onSuccess` hooks executed when a build completes.
+ *
+ * @param context - Result context containing the build result, duration, arguments, and stage state
+ *
+ * @returns Optional result containing additional errors and warnings to report, or void/null if none
  *
  * @remarks
- * Common configuration provides default settings that apply to all variants unless overridden.
- * This reduces duplication when multiple variants share similar settings.
+ * End hooks are executed after all build operations are complete, regardless of success or failure.
+ * They receive a result context with the final build outcome, calculated duration, and can perform
+ * cleanup, logging, or post-processing tasks.
  *
- * 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.
+ * Success hooks use the same signature but only execute when `context.buildResult.errors.length === 0`,
+ * making them suitable for deployment or success-only operations.
  *
- * Typical use cases:
- * - Shared compiler options (target, platform)
- * - Common minification and sourcemap settings
- * - Shared external dependencies
- * - Default output configuration
+ * Return value semantics:
+ * - Return `void` or `null` if the hook has nothing to report
+ * - Return `OnEndResult` with errors/warnings arrays to add to build output
+ * - Can be synchronous or asynchronous (return a Promise)
  *
  * @example
  * ```ts
- * const common: CommonBuildInterface = {
- *   esbuild: {
- *     target: 'es2020',
- *     platform: 'node',
- *     sourcemap: true,
- *     external: ['react', 'react-dom']
- *   },
- *   types: { failOnError: true },
- *   declaration: true
+ * const onEnd: OnEndType = async (context) => {
+ *   console.log(`${context.variantName} build completed in ${context.duration}ms`);
+ *
+ *   if (context.buildResult.errors.length > 0) {
+ *     console.error(`Build failed with ${context.buildResult.errors.length} errors`);
+ *   } else {
+ *     console.log('Build succeeded!');
+ *   }
+ *
+ *   // Clean up temporary files
+ *   await cleanupTempFiles(context.stage.tempDir);
  * };
  * ```
  *
- * @see {@link BaseBuildDefinitionInterface}
- * @see {@link VariantBuildInterface}
- * @see {@link BuildConfigInterface}
+ * @example
+ * ```ts
+ * const onSuccess: OnEndType = async (context) => {
+ *   console.log('Deploying build artifacts...');
+ *   await deploy(context.buildResult.metafile);
+ * };
+ * ```
+ *
+ * @see {@link MaybeVoidPromiseType}
+ * @see {@link ResultContextInterface}
+ * @see {@link LifecycleProvider.onEnd}
+ * @see {@link LifecycleProvider.onSuccess}
  *
  * @since 2.0.0
  */
-interface CommonBuildInterface extends BaseBuildDefinitionInterface {
-    /**
-     * Shared esbuild configuration for all variants.
-     *
-     * @remarks
-     * Contains esbuild options that apply to all variants by default. Variants can override
-     * any of these settings with their own specific values.
-     *
-     * Excludes managed fields and `entryPoints` since entry points must be variant-specific.
-     *
-     * @example
-     * ```ts
-     * esbuild: {
-     *   platform: 'node',
-     *   target: 'node18',
-     *   external: ['typescript']
-     * }
-     * ```
-     *
-     * @since 2.0.0
-     */
-    esbuild?: Omit<BuildOptions, 'plugins' | 'define' | 'banner' | 'footer'>;
-}
+type OnEndType = (context: ResultContextInterface) => MaybeVoidPromiseType<OnEndResult>;
 /**
- * Maps variant names to their build configurations.
- * Allows defining multiple build targets with different entry points and settings.
+ * Handler function signature for `onResolve` hooks executed during module path resolution.
+ *
+ * @param context - Resolve context containing resolution arguments, variant name, and stage state
+ *
+ * @returns Optional resolution result to override default resolution, or undefined/null for default behavior
  *
  * @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.
+ * Resolve hooks are executed when esbuild needs to resolve import paths to file system locations.
+ * They receive a resolve context with the import path, importer information, and can redirect imports,
+ * implement custom resolution algorithms, or provide virtual modules.
  *
- * Variant names are used for:
- * - CLI targeting specific builds
- * - Build output organization
- * - Logging and error reporting
- * - Parallel build coordination
+ * Return value semantics:
+ * - Return `undefined` or `null` to allow default esbuild resolution
+ * - Return `OnResolveResult` to override with custom resolution (path, namespace, external flag, etc.)
+ * - Can be synchronous or asynchronous (return a Promise)
  *
- * @example
+ * Multiple resolve hooks can execute, and their results are merged, with later hooks able to
+ * override properties set by earlier hooks.
+ *
+ * @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 onResolve: OnResolveType = 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 dependencies as external in production
+ *   if (variantName === 'production' && args.path.startsWith('lodash')) {
+ *     return { path: args.path, external: true };
  *   }
+ *
+ *   // Allow default resolution
+ *   return undefined;
  * };
  * ```
  *
- * @see {@link VariantBuildInterface}
- * @see {@link BuildConfigInterface}
+ * @see {@link ResolveContextInterface}
+ * @see {@link MaybeUndefinedPromiseType}
+ * @see {@link LifecycleProvider.onResolve}
  *
  * @since 2.0.0
  */
-type VariantsType = {
-    [variantName: string]: VariantBuildInterface;
-};
+type OnResolveType = (context: ResolveContextInterface) => MaybeUndefinedPromiseType<OnResolveResult>;
 /**
- * Complete build configuration including common settings, variants, and CLI options.
- * Serves as the root configuration object for the entire build system.
+ * Handler function signature for `onLoad` hooks executed when loading file contents.
+ *
+ * @param context - Load context containing current contents, loader, load arguments, and stage state
+ *
+ * @returns Optional load result to transform contents or change loader, or undefined/null for no changes
  *
  * @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
+ * Load hooks are executed when esbuild loads file contents and can transform the contents,
+ * change the loader type, or inject additional code. Multiple load hooks execute in a pipeline
+ * pattern where each hook receives the transformed output of previous hooks through the context.
  *
- * The configuration is typically exported from a `build.config.ts` or similar file and
- * loaded by the build system at startup.
+ * Return value semantics:
+ * - Return `undefined` or `null` to pass contents unchanged to the next hook
+ * - Return `OnLoadResult` with `contents` to transform file contents
+ * - Return `OnLoadResult` with `loader` to change the loader type
+ * - Can be synchronous or asynchronous (return a Promise)
  *
- * 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
+ * The `context.contents` property receives the output of previous hooks, and `context.loader`
+ * reflects any loader changes made by previous hooks.
  *
  * @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' }
+ * const onLoad: OnLoadType = async (context) => {
+ *   const { contents, loader, args, variantName } = context;
+ *
+ *   // Transform .custom files to TypeScript
+ *   if (args.path.endsWith('.custom')) {
+ *     return {
+ *       contents: transformCustomSyntax(contents.toString()),
+ *       loader: 'ts'
+ *     };
+ *   }
+ *
+ *   // Inject environment variables in development
+ *   if (variantName === 'development' && loader === 'js') {
+ *     return {
+ *       contents: `const ENV = '${variantName}';\n${contents}`,
+ *       loader
+ *     };
  *   }
+ *
+ *   // Pass through unchanged
+ *   return undefined;
  * };
  * ```
  *
- * @see {@link VariantsType}
- * @see {@link CommonBuildInterface}
- * @see {@link PartialBuildConfigType}
+ * @see {@link LoadContextInterface}
+ * @see {@link LifecycleProvider.onLoad}
+ * @see {@link MaybeUndefinedPromiseType}
  *
  * @since 2.0.0
  */
-interface BuildConfigInterface {
-    /**
-     * Shared configuration applied to all build variants.
-     *
-     * @remarks
-     * 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
-     */
-    common?: CommonBuildInterface;
+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 {
     /**
-     * Enable verbose logging output during builds.
+     * Optional new configuration to replace the current one.
      *
      * @remarks
-     * When true, outputs detailed build information including file processing,
-     * hook execution, and timing information. Useful for debugging build issues.
-     *
-     * @example
-     * ```ts
-     * verbose: true  // Detailed output
-     * verbose: false // Minimal output
-     * ```
-     *
-     * @since 2.0.0
+     * When provided, the build service reloads using this configuration
+     * before recalculating variants.
      */
-    verbose?: boolean;
+    config?: PartialBuildConfigType;
     /**
-     * Build variant definitions mapping names to configurations.
+     * Whether to clear cached files and TypeScript language service state before reloading.
      *
      * @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.
-     *
-     * @see {@link VariantsType}
-     *
-     * @since 2.0.0
+     * When enabled, cached file tracking and language service state are reset
+     * before the configuration is reloaded.
      */
-    variants: VariantsType;
+    clearCache?: boolean;
 }
 /**
- * Partial build configuration for incremental or programmatic configuration building.
- * Allows omitting variants and userArgv while making other fields optional.
+ * Recursively makes all properties of a type 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.
+ * This utility type behaves like TypeScript’s built-in {@link Partial} type,
+ * but applies recursively to all nested object properties.
  *
- * Common use cases:
- * - Configuration presets or templates
- * - Programmatic configuration generation
- * - Configuration merging utilities
- * - Partial overrides in build scripts
+ * 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
- * const preset: PartialBuildConfigType = {
- *   verbose: true,
- *   common: {
- *     types: { failOnError: true },
- *     declaration: true
- *   }
- * };
+ * interface Config {
+ *   server: {
+ *     host: string;
+ *     port: number;
+ *   };
+ *   features: {
+ *     experimental: boolean;
+ *   };
+ * }
  *
- * // Merge with full config
- * const fullConfig: BuildConfigInterface = {
- *   ...preset,
- *   variants: { ... }
+ * const override: DeepPartialType<Config> = {
+ *   server: {
+ *     port: 8080
+ *   }
  * };
  * ```
  *
- * @see {@link BuildConfigInterface}
+ * @template T - The type to recursively make optional.
  *
  * @since 2.0.0
  */
-type PartialBuildConfigType = Partial<BuildConfigInterface>;
+type DeepPartialType<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartialType<T[K]> : T[K];
+};
 /**
- * Represents a value that may be synchronous, asynchronous, void, null, or the specified type.
- *
- * @template T - The actual value type when present
+ * 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 utility type is used for hook handlers that may return values in multiple forms:
- * - Synchronous return: `T`, `void`, or `null`
- * - Asynchronous return: `Promise<T>`, `Promise<void>`, or `Promise<null>`
+ * 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.
  *
- * This flexibility allows hooks to be implemented as sync or async functions and to optionally
- * return results. Handlers that don't need to return data can return `void` or `null`.
+ * 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
- * // All valid implementations
- * const sync: MaybeVoidPromiseType<string> = 'result';
- * const voidSync: MaybeVoidPromiseType<string> = null;
- * const async: MaybeVoidPromiseType<string> = Promise.resolve('result');
- * const voidAsync: MaybeVoidPromiseType<string> = Promise.resolve(null);
+ * // 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 OnEndType}
- * @see {@link OnStartType}
+ * @see {@link BaseBuildDefinitionInterface.banner}
+ * @see {@link BaseBuildDefinitionInterface.footer}
  *
  * @since 2.0.0
  */
-type MaybeVoidPromiseType<T> = void | null | T | Promise<void | null | T>;
+type InjectableCodeType = string | ((name: string, argv: Record<string, unknown>) => string);
 /**
- * Represents a value that may be synchronous, asynchronous, undefined, null, or the specified type.
- *
- * @template T - The actual value type when present
+ * Defines lifecycle hook handlers for build process stages.
+ * Allows registration of custom logic during resolution, loading, build start, build end, and success.
  *
  * @remarks
- * This utility type is used for hook handlers that may return values in multiple forms:
- * - Synchronous return: `T`, `undefined`, or `null`
- * - Asynchronous return: `Promise<T>`, `Promise<undefined>`, or `Promise<null>`
+ * This interface groups all available lifecycle hooks in a single configuration object.
+ * All hooks are optional, allowing selective registration of only necessary handlers.
  *
- * Similar to {@link MaybeVoidPromiseType} but uses `undefined` instead of `void`, allowing handlers
- * to explicitly return nothing or optionally return results. This distinction is important for
- * hooks where the absence of a return value has semantic meaning (like allowing default behavior).
+ * 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
- * // All valid implementations
- * const sync: MaybeUndefinedPromiseType<object> = { path: '/file.ts' };
- * const undefinedSync: MaybeUndefinedPromiseType<object> = undefined;
- * const async: MaybeUndefinedPromiseType<object> = Promise.resolve({ path: '/file.ts' });
- * const undefinedAsync: MaybeUndefinedPromiseType<object> = Promise.resolve(undefined);
+ * 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
  */
-type MaybeUndefinedPromiseType<T> = undefined | null | T | Promise<undefined | null | T>;
-/**
- * Represents a transient build stage state shared across hook handlers during a single build.
- *
- * @remarks
- * This interface provides a flexible container for storing temporary data during the build lifecycle.
- * It's reset at the start of each build and is available to all hooks through the plugin context.
- *
- * The `startTime` property is always present and set when the build begins, allowing hooks to
- * calculate durations and timing information. Additional properties can be added dynamically
- * using the index signature to facilitate cross-handler communication.
- *
- * Common use cases:
- * - Storing build start time for duration calculations
- * - Passing data between different hook handlers
- * - Accumulating statistics during the build
- * - Caching computed values for reuse across hooks
- *
- * @example
- * ```ts
- * // In onStart hook
- * context.stage.startTime = new Date();
- * context.stage.fileCount = 0;
- *
- * // In onLoad hook
- * context.stage.fileCount++;
- *
- * // In onEnd hook
- * const duration = Date.now() - context.stage.startTime.getTime();
- * console.log(`Processed ${context.stage.fileCount} files in ${duration}ms`);
- * ```
- *
- * @see {@link LifecycleContextInterface}
- *
- * @since 2.0.0
- */
-interface LifecycleStageInterface {
+interface LifecycleHooksInterface {
     /**
-     * Timestamp when the build process started.
+     * Hook handler executed when the build completes, regardless of success or failure.
      *
      * @remarks
-     * Set during the first `onStart` hook execution and available throughout the build lifecycle.
-     * Used to calculate build duration and timing information.
+     * 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.
      *
-     * @since 2.0.0
-     */
-    startTime: Date;
-    /**
-     * Additional dynamic properties for cross-handler communication.
+     * 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
      *
-     * @remarks
-     * Handlers can store arbitrary data in the stage object using any string key.
-     * This allows passing information between hooks during a single build.
+     * @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
      */
-    [key: string]: unknown;
-}
-/**
- * Base context interface shared by all lifecycle hook handlers.
- * Provides access to plugin configuration, command-line arguments, and transient build state.
- *
- * @remarks
- * This context is initialized during the `onStart` phase and remains available throughout the
- * entire build lifecycle. All hook handlers receive a variant of this context, enabling:
- * - Access to command-line arguments and configuration
- * - Cross-handler communication through the stage object
- * - Consistent variant identification across hooks
- *
- * The context is immutable at the top level (variantName and argv don't change during a build),
- * but the stage object is mutable and reset between builds.
- *
- * @example
- * ```ts
- * // In onStart hook
- * const handler: OnStartType = async (context) => {
- *   console.log(`Variant ${context.variantName} starting`);
- *   context.stage.customData = { processed: 0 };
- * };
- * ```
- *
- * @see {@link LoadContextInterface}
- * @see {@link BuildContextInterface}
- * @see {@link ResultContextInterface}
- * @see {@link ResolveContextInterface}
- * @see {@link LifecycleStageInterface}
- *
- * @since 2.0.0
- */
-interface LifecycleContextInterface {
+    onEnd?: OnEndType;
     /**
-     * Command-line arguments and configuration options passed to the provider.
+     * Hook handler executed when loading file contents during module processing.
      *
      * @remarks
-     * Contains all CLI options and flags passed when the provider was created.
-     * Available to all handlers for accessing build-specific configuration like
-     * debug flags, output paths, or custom settings.
+     * 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.
+     *
+     * 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
-     * context.argv; // { debug: true, verbose: false, outdir: 'dist' }
+     * 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
      */
-    argv: Record<string, unknown>;
+    onLoad?: OnLoadType;
     /**
-     * Transient state object for cross-handler communication during a single build.
+     * Hook handler executed when the build process begins.
      *
      * @remarks
-     * Reset to contain only `startTime` at the beginning of each build. Handlers can store
-     * and retrieve temporary data during the build lifecycle through this object.
+     * 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.
      *
-     * Common patterns:
-     * - Accumulating statistics across multiple hooks
-     * - Passing processed data between different hook types
-     * - Caching expensive computations for reuse
+     * 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
-     * // Store data in onLoad
-     * context.stage.transformedFiles = [];
+     * onStart: async (context) => {
+     *   const { build, variantName, stage } = context;
+     *   console.log(`Starting ${variantName} build`);
+     *   stage.startTime = new Date();
      *
-     * // Access in onEnd
-     * console.log(`Transformed ${context.stage.transformedFiles.length} files`);
+     *   // Validate configuration
+     *   if (!build.initialOptions.outdir) {
+     *     return { errors: [{ text: 'Output directory required' }] };
+     *   }
+     * }
      * ```
      *
-     * @see {@link LifecycleStageInterface}
+     * @see {@link BuildContextInterface}
      *
      * @since 2.0.0
      */
-    stage: LifecycleStageInterface;
+    onStart?: OnStartType;
     /**
-     * Identifier for the build variant or plugin instance.
+     * Hook handler executed when the build completes successfully without errors.
      *
      * @remarks
-     * Used for identification and logging. Same as the variant name passed to
-     * the HooksProvider constructor or build configuration.
+     * 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
      *
      * @example
      * ```ts
-     * context.variantName; // 'production' or 'development'
+     * onSuccess: async (context) => {
+     *   const { buildResult, duration, variantName } = context;
+     *   console.log(`${variantName} succeeded in ${duration}ms!`);
+     *   await deploy(buildResult.metafile);
+     * }
      * ```
      *
+     * @see {@link ResultContextInterface}
+     *
      * @since 2.0.0
      */
-    variantName: string;
+    onSuccess?: OnEndType;
     /**
-     * esbuild configuration options used for this lifecycle execution.
+     * Hook handler executed during module path resolution.
      *
      * @remarks
-     * These options represent the active build configuration for the provider and
-     * are intended to be read by lifecycle handlers when build behavior depends on
-     * entry points, output settings, plugins, or other esbuild flags.
+     * 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.
      *
-     * @since 2.2.0
-     */
-    options: BuildOptions;
-}
-/**
- * Context interface for `onStart` hooks, providing access to the esbuild plugin build object.
- *
- * @remarks
- * This specialized context extends the base lifecycle context with the esbuild `PluginBuild`
- * object, giving start hooks access to build configuration, utilities, and the ability to
- * register additional esbuild hooks dynamically.
- *
- * Start hooks are the only lifecycle phase that receives the build object, as they execute
- * before file processing begins and may need to configure or inspect build settings.
- *
- * @example
- * ```ts
- * const handler: OnStartType = async (context) => {
- *   const { build, variantName, argv } = context;
- *   console.log(`Starting ${variantName} build`);
- *
- *   // Access build configuration
- *   console.log(`Platform: ${build.initialOptions.platform}`);
- *
- *   return { errors: [], warnings: [] };
- * };
- * ```
- *
- * @see {@link OnStartType}
- * @see {@link LifecycleContextInterface}
- *
- * @since 2.0.0
- */
-interface BuildContextInterface extends LifecycleContextInterface {
-    /**
-     * The esbuild plugin build object providing build configuration and utilities.
-     *
-     * @remarks
-     * Provides access to:
-     * - `initialOptions`: Build configuration options
-     * - `resolve`: Path resolution utilities
-     * - Dynamic hook registration methods
-     * - Build environment information
-     *
-     * Available only in `onStart` hooks, as later phases don't require build-level access.
+     * 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
-     * // Access initial options
-     * const outdir = context.build.initialOptions.outdir;
+     * onResolve: async (context) => {
+     *   const { args, variantName } = context;
      *
-     * // Resolve a path
-     * const resolved = await context.build.resolve('./module', {
-     *   resolveDir: '/src'
-     * });
+     *   // 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
      */
-    build: PluginBuild;
+    onResolve?: OnResolveType;
 }
 /**
- * Context interface for `onEnd` and `onSuccess` hooks, providing access to build results and duration.
+ * Configuration options for TypeScript declaration file generation.
  *
  * @remarks
- * This specialized context extends the base lifecycle context with the final build result
- * and calculated build duration, giving end hooks access to a build outcome, errors, warnings,
- * and metadata.
+ * 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.
  *
- * The duration is automatically calculated from the start time in the stage object, providing
- * a convenient way to measure build performance without manual timestamp calculations.
+ * 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
- * const handler: OnEndType = async (context) => {
- *   const { buildResult, duration, variantName } = context;
- *
- *   console.log(`${variantName} build completed in ${duration}ms`);
- *
- *   if (buildResult.errors.length > 0) {
- *     console.error(`Build failed with ${buildResult.errors.length} errors`);
- *   }
- *
- *   // Access metafile for dependency analysis
- *   if (buildResult.metafile) {
- *     console.log('Outputs:', Object.keys(buildResult.metafile.outputs));
- *   }
+ * // Generate bundled declarations in custom directory
+ * const options: DeclarationOptionsInterface = {
+ *   outDir: 'types',
+ *   bundle: true
  * };
  * ```
  *
- * @see {@link OnEndType}
- * @see {@link LifecycleContextInterface}
+ * @see {@link BaseBuildDefinitionInterface.declaration}
  *
  * @since 2.0.0
  */
-interface ResultContextInterface extends LifecycleContextInterface {
+interface DeclarationOptionsInterface {
     /**
-     * Build duration in milliseconds.
+     * Output directory for generated declaration files.
      *
      * @remarks
-     * Automatically calculated as the time elapsed from `context.stage.startTime` to
-     * when the build completed. Useful for performance monitoring and reporting.
+     * Specifies where `.d.ts` files should be written. If not provided, uses the TypeScript
+     * compiler's `declarationDir` or `outDir` from `tsconfig.json`.
      *
      * @example
      * ```ts
-     * console.log(`Build took ${context.duration}ms`);
+     * outDir: 'dist/types'
      * ```
      *
      * @since 2.0.0
      */
-    duration: number;
+    outDir?: string;
     /**
-     * The final build result from esbuild containing errors, warnings, and metadata.
+     * Whether to bundle declarations into a single file per entry point.
      *
      * @remarks
-     * Provides access to:
-     * - `errors`: Array of build errors
-     * - `warnings`: Array of build warnings
-     * - `metafile`: Build metadata including inputs, outputs, and dependencies
-     * - `outputFiles`: Generated file contents (if `write: false`)
+     * 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
-     * // Check for errors
-     * if (context.buildResult.errors.length > 0) {
-     *   // Handle build failure
-     * }
-     *
-     * // Analyze dependencies
-     * const inputs = context.buildResult.metafile?.inputs;
+     * bundle: true  // Produces single bundled .d.ts
+     * bundle: false // Produces multiple .d.ts files
      * ```
      *
      * @since 2.0.0
      */
-    buildResult: BuildResult;
+    bundle?: boolean;
 }
 /**
- * Context interface for `onResolve` hooks, providing access to resolution arguments.
+ * Configuration options for TypeScript type checking during builds.
  *
  * @remarks
- * This specialized context extends the base lifecycle context with esbuild's resolution
- * arguments, giving resolve hooks access to the import path, importer information, and
- * resolution context needed to implement custom module resolution logic.
- *
- * Resolve hooks use this context to determine how to resolve import paths, redirect imports,
- * or mark modules as external based on the resolution arguments.
+ * 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
- * const handler: OnResolveType = 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 node_modules as external in development
- *   if (variantName === 'development' && args.path.includes('node_modules')) {
- *     return { path: args.path, external: true };
- *   }
- *
- *   return undefined; // Use default resolution
+ * // Fail build on type errors
+ * const options: TypeCheckOptionsInterface = {
+ *   failOnError: true
  * };
  * ```
  *
- * @see {@link OnResolveType}
- * @see {@link LifecycleContextInterface}
+ * @see {@link BaseBuildDefinitionInterface.types}
  *
  * @since 2.0.0
  */
-interface ResolveContextInterface extends LifecycleContextInterface {
+interface TypeCheckOptionsInterface {
     /**
-     * Resolution arguments from esbuild containing the import path and resolution context.
+     * Whether to fail the build when TypeScript errors are detected.
      *
      * @remarks
-     * Provides access to:
-     * - `path`: The import path to resolve (e.g., './module', '\@/utils')
-     * - `importer`: The file that contains this import
-     * - `namespace`: The namespace of the importer
-     * - `resolveDir`: The directory to resolve relative imports from
-     * - `kind`: The kind of import (e.g., 'import-statement', 'require-call')
-     * - `pluginData`: Data passed from previous plugins
+     * 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.
+     *
+     * Useful in CI/CD pipelines where type safety must be enforced before deployment.
      *
      * @example
      * ```ts
-     * console.log(`Resolving ${context.args.path} from ${context.args.importer}`);
-     *
-     * if (context.args.kind === 'dynamic-import') {
-     *   // Handle dynamic imports specially
-     * }
+     * failOnError: true  // Build fails on type errors
+     * failOnError: false // Type errors logged, but build continues
      * ```
      *
      * @since 2.0.0
      */
-    args: OnResolveArgs;
+    failOnError?: boolean;
 }
 /**
- * Context interface for `onLoad` hooks, providing access to load arguments, current contents, and loader.
+ * 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 specialized context extends the base lifecycle context with esbuild's load arguments,
- * the current file contents (potentially transformed by previous hooks), and the current loader
- * type. This enables load hooks to implement content transformations in a pipeline pattern.
+ * 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.
  *
- * Load hooks receive the output of previous hooks through `contents` and `loader`, allowing
- * sequential transformations where each hook builds on the work of previous hooks.
+ * 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 handler: OnLoadType = async (context) => {
- *   const { contents, loader, args, variantName } = context;
- *
- *   // Transform .custom files to TypeScript
- *   if (args.path.endsWith('.custom')) {
- *     return {
- *       contents: transformCustomSyntax(contents.toString()),
- *       loader: 'ts'
- *     };
- *   }
- *
- *   // Add debugging in development
- *   if (variantName === 'development' && loader === 'ts') {
- *     return {
- *       contents: `console.log('Loading: ${args.path}');\n${contents}`,
- *       loader
- *     };
+ * 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!')
  *   }
- *
- *   return undefined; // Pass through unchanged
  * };
  * ```
  *
- * @see {@link OnLoadType}
- * @see {@link LifecycleContextInterface}
+ * @see {@link CommonBuildInterface}
+ * @see {@link VariantBuildInterface}
+ * @see {@link BuildConfigInterface}
  *
  * @since 2.0.0
  */
-interface LoadContextInterface extends LifecycleContextInterface {
+interface BaseBuildDefinitionInterface {
     /**
-     * Load arguments from esbuild containing file path and namespace.
+     * Lifecycle hook handlers for build process stages.
      *
      * @remarks
-     * Provides access to:
-     * - `path`: The absolute path to the file being loaded
-     * - `namespace`: The namespace for this module
-     * - `suffix`: Optional suffix for special handling
-     * - `pluginData`: Data passed from resolve hooks or previous plugins
+     * Registers custom handlers for various build lifecycle events including start, resolve,
+     * load, end, and success stages. All hooks are optional.
      *
-     * @example
-     * ```ts
-     * console.log(`Loading ${context.args.path}`);
+     * @see {@link LifecycleHooksInterface}
      *
-     * if (context.args.namespace === 'virtual') {
-     *   // Handle virtual modules
-     * }
+     * @since 2.0.0
+     */
+    lifecycle?: LifecycleHooksInterface;
+    /**
+     * TypeScript type checking configuration.
+     *
+     * @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`
+     *
+     * @example
+     * ```ts
+     * types: true                      // Enable with default
+     * types: { failOnError: true }     // Enable and fail on errors
+     * types: false                     // Disable
      * ```
      *
+     * @see {@link TypeCheckOptionsInterface}
+     *
      * @since 2.0.0
      */
-    args: OnLoadArgs;
+    types?: boolean | TypeCheckOptionsInterface;
     /**
-     * The current loader type for this file.
+     * Global constants to replace during bundling.
      *
      * @remarks
-     * Reflects any loader changes made by previous hooks in the pipeline. Can be:
-     * - `'js'`, `'ts'`, `'jsx'`, `'tsx'`: JavaScript/TypeScript variants
-     * - `'json'`, `'css'`, `'text'`: Special content types
-     * - `'base64'`, `'binary'`, `'dataurl'`: Binary content encodings
-     * - `'default'`: Let esbuild determine the loader
-     * - `undefined`: No loader has been set yet
+     * Defines key-value pairs for constant replacement during the build. Keys are identifiers
+     * or property access expressions, values are JSON-stringified replacements.
      *
-     * Hooks can change the loader to affect how esbuild processes the contents.
+     * Commonly used for environment variables, feature flags, and build-time constants.
      *
      * @example
      * ```ts
-     * if (context.loader === 'json') {
-     *   // Transform JSON before esbuild processes it
+     * define: {
+     *   'process.env.NODE_ENV': '"production"',
+     *   'DEBUG': 'false',
+     *   'VERSION': '"1.2.3"'
      * }
      * ```
      *
      * @since 2.0.0
      */
-    loader: Loader | undefined;
+    define?: Record<string, unknown>;
     /**
-     * The current file contents as string or binary data.
+     * Code to inject at the beginning of each output file.
      *
      * @remarks
-     * Contains the output of previous load hooks in the pipeline, or the initial file
-     * contents if this is the first hook. Hooks can transform this content and return
-     * new contents for further hooks to process.
+     * 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.
      *
-     * Content can be:
-     * - `string`: Text content (source code, JSON, CSS, etc.)
-     * - `Uint8Array`: Binary content (images, fonts, etc.)
+     * @example
+     * ```ts
+     * banner: 'const x = "test"'
+     * banner: (name, argv) => `const x = "Built: ${new Date().toISOString()}"`
+     * ```
+     *
+     * @see {@link InjectableCodeType}
+     *
+     * @since 2.0.0
+     */
+    banner?: {
+        [key: string]: InjectableCodeType;
+    };
+    /**
+     * Code to inject at the end of each output file.
+     *
+     * @remarks
+     * Can be a static string or a function that generates code based on build context.
+     * Commonly used for initialization code, analytics, or polyfills.
      *
      * @example
      * ```ts
-     * // Transform string contents
-     * const transformed = context.contents.toString().replace(/old/g, 'new');
+     * footer: '// End of bundle'
+     * footer: (name, argv) => `console.log('Loaded ${name}');`
+     * ```
      *
-     * // Check content type
-     * if (typeof context.contents === 'string') {
-     *   // Handle text
-     * } else {
-     *   // Handle binary
-     * }
+     * @see {@link InjectableCodeType}
+     *
+     * @since 2.0.0
+     */
+    footer?: {
+        [key: string]: InjectableCodeType;
+    };
+    /**
+     * TypeScript declaration file generation configuration.
+     *
+     * @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`
+     *
+     * @example
+     * ```ts
+     * declaration: true                              // Generate with default
+     * declaration: { outDir: 'types', bundle: true } // Generate bundled in custom dir
+     * declaration: false                             // Disable
      * ```
      *
+     * @see {@link DeclarationOptionsInterface}
+     *
      * @since 2.0.0
      */
-    contents: string | Uint8Array;
+    declaration?: boolean | DeclarationOptionsInterface;
 }
 /**
- * Handler function signature for `onStart` hooks executed when a build begins.
- *
- * @param context - Build context containing the esbuild build object, arguments, and stage state
- *
- * @returns Optional result containing errors and warnings to report, or void/null if none
+ * 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
- * Start hooks are executed before any file processing occurs and receive a build context
- * with access to the esbuild `PluginBuild` object. They can perform initialization tasks
- * and return errors or warnings that will be aggregated with results from other start hooks.
+ * 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.
  *
- * Return value semantics:
- * - Return `void` or `null` if the hook has nothing to report
- * - Return `OnStartResult` with errors/warnings arrays to report issues
- * - Can be synchronous or asynchronous (return a Promise)
+ * 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 onStart: OnStartType = async (context) => {
- *   console.log(`Starting ${context.variantName} build`);
- *   context.stage.startTime = new Date();
- *
- *   // Validate build configuration
- *   if (!context.build.initialOptions.outdir) {
- *     return {
- *       errors: [{
- *         text: 'Output directory not specified',
- *         location: null
- *       }]
- *     };
- *   }
- *
- *   return { errors: [], warnings: [] };
+ * 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 MaybeVoidPromiseType}
- * @see {@link BuildContextInterface}
- * @see {@link LifecycleProvider.onStart}
+ * @see {@link VariantsType}
+ * @see {@link CommonBuildInterface}
+ * @see {@link BaseBuildDefinitionInterface}
  *
  * @since 2.0.0
  */
-type OnStartType = (context: BuildContextInterface) => MaybeVoidPromiseType<OnStartResult>;
+interface VariantBuildInterface extends BaseBuildDefinitionInterface {
+    /**
+     * Esbuild-specific configuration for this variant including entry points.
+     *
+     * @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
+     */
+    esbuild: Omit<BuildOptions, 'plugins' | 'define' | 'banner' | 'footer'>;
+}
 /**
- * Handler function signature for `onEnd` and `onSuccess` hooks executed when a build completes.
- *
- * @param context - Result context containing the build result, duration, arguments, and stage state
- *
- * @returns Optional result containing additional errors and warnings to report, or void/null if none
+ * Shared configuration applied to all build variants.
+ * Extends base configuration with esbuild settings but without entry points.
  *
  * @remarks
- * End hooks are executed after all build operations are complete, regardless of success or failure.
- * They receive a result context with the final build outcome, calculated duration, and can perform
- * cleanup, logging, or post-processing tasks.
- *
- * Success hooks use the same signature but only execute when `context.buildResult.errors.length === 0`,
- * making them suitable for deployment or success-only operations.
- *
- * Return value semantics:
- * - Return `void` or `null` if the hook has nothing to report
- * - Return `OnEndResult` with errors/warnings arrays to add to build output
- * - Can be synchronous or asynchronous (return a Promise)
- *
- * @example
- * ```ts
- * const onEnd: OnEndType = async (context) => {
- *   console.log(`${context.variantName} build completed in ${context.duration}ms`);
+ * Common configuration provides default settings that apply to all variants unless overridden.
+ * This reduces duplication when multiple variants share similar settings.
  *
- *   if (context.buildResult.errors.length > 0) {
- *     console.error(`Build failed with ${context.buildResult.errors.length} errors`);
- *   } else {
- *     console.log('Build succeeded!');
- *   }
+ * 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.
  *
- *   // Clean up temporary files
- *   await cleanupTempFiles(context.stage.tempDir);
- * };
- * ```
+ * Typical use cases:
+ * - Shared compiler options (target, platform)
+ * - Common minification and sourcemap settings
+ * - Shared external dependencies
+ * - Default output configuration
  *
  * @example
  * ```ts
- * const onSuccess: OnEndType = async (context) => {
- *   console.log('Deploying build artifacts...');
- *   await deploy(context.buildResult.metafile);
+ * const common: CommonBuildInterface = {
+ *   esbuild: {
+ *     target: 'es2020',
+ *     platform: 'node',
+ *     sourcemap: true,
+ *     external: ['react', 'react-dom']
+ *   },
+ *   types: { failOnError: true },
+ *   declaration: true
  * };
  * ```
  *
- * @see {@link MaybeVoidPromiseType}
- * @see {@link ResultContextInterface}
- * @see {@link LifecycleProvider.onEnd}
- * @see {@link LifecycleProvider.onSuccess}
+ * @see {@link BaseBuildDefinitionInterface}
+ * @see {@link VariantBuildInterface}
+ * @see {@link BuildConfigInterface}
  *
  * @since 2.0.0
  */
-type OnEndType = (context: ResultContextInterface) => MaybeVoidPromiseType<OnEndResult>;
+interface CommonBuildInterface extends BaseBuildDefinitionInterface {
+    /**
+     * Shared esbuild configuration for all variants.
+     *
+     * @remarks
+     * Contains esbuild options that apply to all variants by default. Variants can override
+     * any of these settings with their own specific values.
+     *
+     * Excludes managed fields and `entryPoints` since entry points must be variant-specific.
+     *
+     * @example
+     * ```ts
+     * esbuild: {
+     *   platform: 'node',
+     *   target: 'node18',
+     *   external: ['typescript']
+     * }
+     * ```
+     *
+     * @since 2.0.0
+     */
+    esbuild?: Omit<BuildOptions, 'plugins' | 'define' | 'banner' | 'footer'>;
+}
 /**
- * Handler function signature for `onResolve` hooks executed during module path resolution.
- *
- * @param context - Resolve context containing resolution arguments, variant name, and stage state
- *
- * @returns Optional resolution result to override default resolution, or undefined/null for default behavior
+ * Maps variant names to their build configurations.
+ * Allows defining multiple build targets with different entry points and settings.
  *
  * @remarks
- * Resolve hooks are executed when esbuild needs to resolve import paths to file system locations.
- * They receive a resolve context with the import path, importer information, and can redirect imports,
- * implement custom resolution algorithms, or provide virtual modules.
- *
- * Return value semantics:
- * - Return `undefined` or `null` to allow default esbuild resolution
- * - Return `OnResolveResult` to override with custom resolution (path, namespace, external flag, etc.)
- * - Can be synchronous or asynchronous (return a Promise)
+ * 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.
  *
- * Multiple resolve hooks can execute, and their results are merged, with later hooks able to
- * override properties set by earlier hooks.
+ * Variant names are used for:
+ * - CLI targeting specific builds
+ * - Build output organization
+ * - Logging and error reporting
+ * - Parallel build coordination
  *
  * @example
  * ```ts
- * const onResolve: OnResolveType = 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 dependencies as external in production
- *   if (variantName === 'production' && args.path.startsWith('lodash')) {
- *     return { path: args.path, external: true };
+ * 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'
+ *     }
  *   }
- *
- *   // Allow default resolution
- *   return undefined;
  * };
  * ```
  *
- * @see {@link ResolveContextInterface}
- * @see {@link MaybeUndefinedPromiseType}
- * @see {@link LifecycleProvider.onResolve}
+ * @see {@link VariantBuildInterface}
+ * @see {@link BuildConfigInterface}
  *
  * @since 2.0.0
  */
-type OnResolveType = (context: ResolveContextInterface) => MaybeUndefinedPromiseType<OnResolveResult>;
+type VariantsType = {
+    [variantName: string]: VariantBuildInterface;
+};
 /**
- * Handler function signature for `onLoad` hooks executed when loading file contents.
- *
- * @param context - Load context containing current contents, loader, load arguments, and stage state
- *
- * @returns Optional load result to transform contents or change loader, or undefined/null for no changes
+ * Complete build configuration including common settings, variants, and CLI options.
+ * Serves as the root configuration object for the entire build system.
  *
  * @remarks
- * Load hooks are executed when esbuild loads file contents and can transform the contents,
- * change the loader type, or inject additional code. Multiple load hooks execute in a pipeline
- * pattern where each hook receives the transformed output of previous hooks through the context.
+ * 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
  *
- * Return value semantics:
- * - Return `undefined` or `null` to pass contents unchanged to the next hook
- * - Return `OnLoadResult` with `contents` to transform file contents
- * - Return `OnLoadResult` with `loader` to change the loader type
- * - Can be synchronous or asynchronous (return a Promise)
+ * The configuration is typically exported from a `build.config.ts` or similar file and
+ * loaded by the build system at startup.
  *
- * The `context.contents` property receives the output of previous hooks, and `context.loader`
- * reflects any loader changes made by previous hooks.
+ * 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 onLoad: OnLoadType = async (context) => {
- *   const { contents, loader, args, variantName } = context;
- *
- *   // Transform .custom files to TypeScript
- *   if (args.path.endsWith('.custom')) {
- *     return {
- *       contents: transformCustomSyntax(contents.toString()),
- *       loader: 'ts'
- *     };
- *   }
- *
- *   // Inject environment variables in development
- *   if (variantName === 'development' && loader === 'js') {
- *     return {
- *       contents: `const ENV = '${variantName}';\n${contents}`,
- *       loader
- *     };
+ * 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' }
  *   }
- *
- *   // Pass through unchanged
- *   return undefined;
- * };
- * ```
- *
- * @see {@link LoadContextInterface}
- * @see {@link LifecycleProvider.onLoad}
- * @see {@link MaybeUndefinedPromiseType}
- *
- * @since 2.0.0
- */
-type OnLoadType = (context: LoadContextInterface) => MaybeUndefinedPromiseType<OnLoadResult>;
-/**
- * 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
+ * @see {@link VariantsType}
+ * @see {@link CommonBuildInterface}
+ * @see {@link PartialBuildConfigType}
  *
  * @since 2.0.0
  */
-interface BuildResultInterface extends Omit<BuildResult, 'errors' | 'warnings'> {
+interface BuildConfigInterface {
     /**
-     * Array of normalized error instances encountered during the build.
+     * Shared configuration applied to all build variants.
      *
      * @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.
+     * Optional common settings that are merged with each variant's configuration.
+     * Variants can override these settings with their own specific values.
      *
-     * Errors in this array may originate from:
-     * - Compilation errors (syntax, resolution failures)
-     * - Type checking failures
-     * - Build hook execution errors
-     * - Plugin errors
+     * @see {@link CommonBuildInterface}
+     *
+     * @since 2.0.0
+     */
+    common?: CommonBuildInterface;
+    /**
+     * Enable verbose logging output during builds.
+     *
+     * @remarks
+     * When true, outputs detailed build information including file processing,
+     * hook execution, and timing information. Useful for debugging build issues.
      *
      * @example
      * ```ts
-     * if (result.errors.length > 0) {
-     *   console.error(`Build failed with ${result.errors.length} errors`);
-     *   result.errors.forEach(err => console.error(err.stack));
-     * }
+     * verbose: true  // Detailed output
+     * verbose: false // Minimal output
      * ```
      *
      * @since 2.0.0
      */
-    errors: Array<Error>;
+    verbose?: boolean;
     /**
-     * Array of normalized warning instances encountered during the build.
+     * Build variant definitions mapping names to configurations.
      *
      * @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
+     * 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.
      *
-     * @example
-     * ```ts
-     * if (result.warnings.length > 0) {
-     *   console.warn(`Build completed with ${result.warnings.length} warnings`);
-     *   result.warnings.forEach(warn => console.warn(warn.message));
-     * }
-     * ```
+     * @see {@link VariantsType}
      *
      * @since 2.0.0
      */
-    warnings: Array<Error>;
+    variants: VariantsType;
 }
+/**
+ * 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.
  *
@@ -3667,793 +3732,273 @@ declare function isBuildResultError(error: unknown): error is BuildResult;
  * console.error(error.stack);
  * ```
  *
- * @see {@link xBuildBaseError}
- * @see {@link getErrorMetadata}
- * @see {@link formatStack}
- *
- * @since 2.0.0
- */
-declare class esBuildError extends xBuildBaseError {
-    /**
-     * Optional esbuild diagnostic identifier copied from `PartialMessage.id`.
-     *
-     * @remarks
-     * This value is useful for categorizing diagnostics by producer (for example,
-     * plugin- or phase-specific IDs). When absent in the source message, it defaults
-     * to an empty string.
-     *
-     * @since 2.0.0
-     */
-    readonly id: string;
-    /**
-     * Creates a new esbuild error with formatted output and metadata.
-     *
-     * @param message - The esbuild {@link PartialMessage} containing diagnostic details
-     * @param options - Optional stack parsing/formatting options used when deriving metadata
-     *
-     * @remarks
-     * The constructor:
-     * 1. Initializes the base error with `message.text ?? ''`
-     * 2. Persists `message.id ?? ''` on {@link id}
-     * 3. If `message.detail` is an `Error`, uses its `message` and `stack` as runtime values
-     * 4. Builds structured metadata from either the original message or `detail` error
-     * 5. Produces formatted output (stack replacement for message-based diagnostics, or
-     *    formatted inspector output for `detail`-based diagnostics)
-     *
-     * The error name is always set to `'esBuildError'`. Formatted output includes:
-     * - Error name and message with color coding
-     * - Any diagnostic notes from esbuild
-     * - Highlighted code snippet showing the error location
-     * - Enhanced stack trace with file path and position
-     *
-     * @see {@link getErrorMetadata} for formatting logic
-     * @see {@link PartialMessage} for esbuild message structure
-     *
-     * @since 2.0.0
-     */
-    constructor(message: PartialMessage, options?: StackTraceInterface);
-}
-/**
- * A base class for custom errors with enhanced stack trace formatting and source code information.
- *
- * @remarks
- * The `xBuildBaseError` class extends the native `Error` class, adding functionality to:
- * - Parse and store structured stack trace metadata via {@link StackInterface}
- * - Format stack traces with syntax highlighting and source mapping
- * - Provide enhanced console output through custom Node.js inspection
- *
- * This is particularly useful for debugging errors in compiled or transpiled code by providing
- * clearer information about the original source of the error, including
- * - Original source file paths (from source maps)
- * - Highlighted code snippets showing the error location
- * - Enhanced stack frame formatting with proper indentation
- *
- * @example
- * ```ts
- * class ValidationError extends xBuildBaseError {
- *   constructor(message: string, field: string) {
- *     super(message, 'ValidationError');
- *     this.reformatStack(this, { withFrameworkFrames: false });
- *   }
- * }
- *
- * throw new ValidationError('Invalid email format', 'email');
- * ```
- *
- * @see {@link formatStack} for stack formatting
- * @see {@link getErrorMetadata} for stack parsing
- * @see {@link StackInterface} for the metadata structure
- * @see {@link StackTraceInterface} for formatting options
- *
- * @since 2.0.0
- */
-declare abstract class xBuildBaseError extends Error {
-    /**
-     * Structured metadata from the parsed stack trace.
-     *
-     * @remarks
-     * Contains the parsed stack information including
-     * - Original source code snippet
-     * - Line and column numbers
-     * - Source file path (from source maps)
-     * - Formatted stack frames
-     * - Syntax-highlighted code
-     *
-     * This property is populated by calling {@link reformatStack}.
-     *
-     * @since 2.0.0
-     */
-    protected errorMetadata: StackInterface | undefined;
-    /**
-     * Pre-formatted stack trace string ready for display.
-     *
-     * @remarks
-     * Contains the complete formatted output including
-     * - Error name and message
-     * - Syntax-highlighted code snippet (if available)
-     * - Enhanced stack trace with proper indentation
-     *
-     * This is generated by {@link formatStack} and used by the custom
-     * Node.js inspector for console output.
-     *
-     * @since 2.0.0
-     */
-    protected formattedStack: string | undefined;
-    /**
-     * Creates a new instance of the base error class.
-     *
-     * @param message - The error message describing the problem
-     * @param name - The error type name; defaults to `'xBuildBaseError'`
-     *
-     * @remarks
-     * This constructor:
-     * - Properly sets up the prototype chain to ensure `instanceof` checks work for derived classes
-     * - Captures the stack trace if supported by the runtime environment
-     * - Sets the error name for identification
-     *
-     * **Important:** This is a protected constructor and should only be called by derived classes.
-     * Subclasses should call {@link reformatStack} after construction to enable enhanced formatting.
-     *
-     * @example
-     * ```ts
-     * class DatabaseError extends xBuildBaseError {
-     *   constructor(message: string, public readonly query: string) {
-     *     super(message, 'DatabaseError');
-     *     this.reformatStack(this);
-     *   }
-     * }
-     * ```
-     *
-     * @since 2.0.0
-     */
-    protected constructor(message: string, name?: string);
-    /**
-     * Gets the structured stack trace metadata.
-     *
-     * @returns The parsed stack metadata, or `undefined` if {@link reformatStack} has not been called
-     *
-     * @remarks
-     * Provides read-only access to the error's structured stack information,
-     * which can be used for:
-     * - Custom error logging
-     * - Error reporting services
-     * - Debugging tools
-     * - Stack analysis
-     *
-     * @example
-     * ```ts
-     * try {
-     *   throw new ValidationError('Invalid input');
-     * } catch (error) {
-     *   if (error instanceof xBuildBaseError) {
-     *     const meta = error.metadata;
-     *     console.log(`Error at ${meta?.source}:${meta?.line}:${meta?.column}`);
-     *   }
-     * }
-     * ```
-     *
-     * @since 2.0.0
-     */
-    get metadata(): StackInterface | undefined;
-    /**
-     * Parses the error stack trace and generates enhanced formatting with metadata.
-     *
-     * @param error - The error object to parse and format
-     * @param options - Optional configuration for stack trace parsing and formatting
-     *
-     * @remarks
-     * This method performs two operations:
-     * 1. Parses the error's stack trace using {@link getErrorMetadata} to extract structured metadata
-     * 2. Formats the metadata using {@link formatStack} to create a styled, human-readable output
-     *
-     * The parsed metadata is stored in {@link errorMetadata} and the formatted string in {@link formattedStack}.
-     *
-     * **Typical usage:** Call this method in the constructor of derived error classes to enable
-     * enhanced stack trace formatting.
-     *
-     * @example
-     * ```ts
-     * class NetworkError extends xBuildBaseError {
-     *   constructor(message: string, public readonly statusCode: number) {
-     *     super(message, 'NetworkError');
-     *     // Enable enhanced formatting without framework frames
-     *     this.reformatStack(this, {
-     *       withFrameworkFrames: false,
-     *       withNativeFrames: true
-     *     });
-     *   }
-     * }
-     * ```
-     *
-     * @example
-     * ```ts
-     * class CustomError extends xBuildBaseError {
-     *   constructor(message: string) {
-     *     super(message, 'CustomError');
-     *     // Use default options
-     *     this.reformatStack(this);
-     *   }
-     * }
-     * ```
-     *
-     * @see {@link formatStack} for formatting logic
-     * @see {@link getErrorMetadata} for parsing logic
-     * @see {@link StackTraceInterface} for available options
-     *
-     * @since 2.0.0
-     */
-    protected reformatStack(error: Error, options?: StackTraceInterface): void;
-}
-/**
- * Structured result of a parsed and formatted stack trace.
- *
- * @remarks
- * This interface represents the finalized output from stack trace parsing and formatting,
- * containing both the raw code context and fully formatted stack frames ready for display.
- * Used as the return type for {@link getErrorMetadata}.
- *
- * @see getErrorMetadata
- * @since 2.0.0
- */
-interface StackInterface {
-    /**
-     * Extracted source code snippet surrounding the error location.
-     *
-     * @remarks
-     * Contains multiple lines of code context (before and after the error line)
-     * as determined by the {@link StackTraceInterface.linesBefore} and
-     * {@link StackTraceInterface.linesAfter} options.
-     *
-     * @since 2.0.0
-     */
-    code: string;
-    /**
-     * Line number of the error within the source file.
-     *
-     * @remarks
-     * This line number reflects the original source position after source map resolution,
-     * with any {@link StackContextInterface.lineOffset} applied.
-     *
-     * @since 2.0.0
-     */
-    line: number;
-    /**
-     * Column number of the error within the source file.
-     *
-     * @remarks
-     * This column number reflects the original source position after source map resolution.
-     *
-     * @since 2.0.0
-     */
-    column: number;
-    /**
-     * Original source file path, if available.
-     *
-     * @remarks
-     * This is the resolved source file path from source maps or the original file name.
-     * May be undefined if no source information is available.
-     *
-     * @since 2.0.0
-     */
-    source?: string;
-    /**
-     * Array of formatted stack trace entries ready for display.
-     *
-     * @remarks
-     * Each string represents a single formatted stack frame, complete with
-     * function names, file paths, line/column numbers, and color formatting.
-     * Empty strings from filtered frames (native or framework) are excluded.
-     *
-     * @since 2.0.0
-     */
-    stacks: Array<string>;
-    /**
-     * Syntax-highlighted and formatted version of the source code snippet.
-     *
-     * @remarks
-     * Contains the {@link code} with applied syntax highlighting and error formatting,
-     * including line numbers and a marker indicating the exact error position.
-     * Generated by {@link highlightPositionCode} and cached during frame processing.
-     *
-     * @see highlightPositionCode
-     * @since 2.0.0
-     */
-    formatCode: string;
-}
-/**
- * Configuration options for parsing and formatting stack traces.
- *
- * @remarks
- * These options control how stack traces are parsed, what frames are included,
- * and how much source code context is displayed. Used by {@link getErrorMetadata}
- * and {@link stackEntry} to customize stack trace output.
- *
- * @see stackEntry
- * @see getErrorMetadata
- *
- * @since 2.0.0
- */
-interface StackTraceInterface {
-    /**
-     * Number of lines of source code to include after the error line.
-     *
-     * @defaultValue 3
-     *
-     * @remarks
-     * Defaults to 3 if not specified. Used when extracting code context
-     * from source files or snapshots.
-     *
-     * @since 2.0.0
-     */
-    linesAfter?: number;
-    /**
-     * Number of lines of source code to include before the error line.
-     *
-     * @defaultValue 3
-     *
-     * @remarks
-     * Defaults to 3 if not specified. Used when extracting code context
-     * from source files or snapshots.
-     *
-     * @since 2.0.0
-     */
-    linesBefore?: number;
-    /**
-     * Whether to include native (built-in) stack frames in the output.
-     *
-     * @defaultValue Based on `ConfigurationService.verbose` setting
-     *
-     * @remarks
-     * Native frames are those marked with `frame.native === true`, typically
-     * representing Node.js internal functions. When false, these frames are
-     * filtered out during processing. Automatically set based on the `verbose`
-     * configuration setting if not explicitly provided.
-     *
-     * @since 2.0.0
-     */
-    withNativeFrames?: boolean;
-    /**
-     * Whether to include framework-internal stack frames in the output.
-     *
-     * @defaultValue Based on `ConfigurationService.verbose` setting
-     *
-     * @remarks
-     * Framework frames are identified by {@link isFrameworkFile}.
-     * When false, these frames are filtered out to reduce noise in stack traces.
-     * Automatically set based on the `verbose` configuration setting if not
-     * explicitly provided.
-     *
-     * @see isFrameworkFile
-     * @since 2.0.0
-     */
-    withFrameworkFrames?: boolean;
-}
-/**
- * Internal runtime context used during stack trace parsing and formatting.
- *
- * @remarks
- * This context extends {@link StackTraceInterface} with additional runtime state
- * and service dependencies required during stack trace processing. It maintains
- * mutable state as frames are processed, including the first encountered code snippet,
- * line/column positions, and formatted output. Used internally by {@link stackEntry},
- * {@link formatFrameWithPosition}, and related functions.
- *
- * @see stackEntry
- * @see getErrorMetadata
- * @see StackTraceInterface
- *
- * @since 2.0.0
- */
-interface StackContextInterface extends StackTraceInterface {
-    /**
-     * Cached source code snippet from the first processed frame with code context.
-     *
-     * @remarks
-     * Populated by {@link formatFrameWithPosition} on the first frame that has
-     * available code. Subsequent frames do not overwrite this value, ensuring
-     * the code displayed corresponds to the most relevant stack frame.
-     *
-     * @see formatFrameWithPosition
-     *
-     * @since 2.0.0
-     */
-    code: string;
-    /**
-     * Reference to the {@link FilesModel} service for accessing file snapshots.
-     *
-     * @remarks
-     * Used by {@link getSource} to retrieve file content when source maps are
-     * not available. Injected during context initialization in {@link getErrorMetadata}.
-     *
-     * @see getSource
-     * @see FilesModel
-     *
-     * @since 2.0.0
-     */
-    files: FilesModel;
-    /**
-     * Cached original source file path from the first processed frame.
-     *
-     * @remarks
-     * Populated by {@link formatFrameWithPosition} on the first frame that has
-     * a resolved source position. Corresponds to the file containing the {@link code}.
-     *
-     * @see formatFrameWithPosition
-     * @since 2.0.0
-     */
-    source: string;
-    /**
-     * Reference to the {@link FrameworkService} for resolving source maps and framework files.
-     *
-     * @remarks
-     * Used throughout stack processing to:
-     * - Retrieve source maps via {@link getSourceMap}
-     * - Identify framework files via {@link isFrameworkFile}
-     * - Resolve relative paths using {@link rootPath}
-     *
-     * Injected during context initialization in {@link getErrorMetadata}.
-     *
-     * @see getSource
-     * @see stackEntry
-     * @see FrameworkService
-     *
-     * @since 2.0.0
-     */
-    framework: FrameworkService;
-    /**
-     * Resolved line number from the most recently processed stack frame.
-     *
-     * @remarks
-     * Updated by {@link stackEntry} after resolving source positions.
-     * Includes any {@link lineOffset} adjustments. Used to populate the
-     * final {@link StackInterface.line} value.
-     *
-     * @see stackEntry
-     * @since 2.0.0
-     */
-    line: number;
+ * @see {@link xBuildBaseError}
+ * @see {@link getErrorMetadata}
+ * @see {@link formatStack}
+ *
+ * @since 2.0.0
+ */
+declare class esBuildError extends xBuildBaseError {
     /**
-     * Resolved column number from the most recently processed stack frame.
+     * Optional esbuild diagnostic identifier copied from `PartialMessage.id`.
      *
      * @remarks
-     * Updated by {@link stackEntry} after resolving source positions.
-     * Used to populate the final {@link StackInterface.column} value.
+     * This value is useful for categorizing diagnostics by producer (for example,
+     * plugin- or phase-specific IDs). When absent in the source message, it defaults
+     * to an empty string.
      *
-     * @see stackEntry
      * @since 2.0.0
      */
-    column: number;
+    readonly id: string;
     /**
-     * Line number offset to apply to all resolved positions.
+     * Creates a new esbuild error with formatted output and metadata.
      *
-     * @defaultValue 0
+     * @param message - The esbuild {@link PartialMessage} containing diagnostic details
+     * @param options - Optional stack parsing/formatting options used when deriving metadata
      *
      * @remarks
-     * Applied to `position.line`, `position.startLine`, and `position.endLine`
-     * in {@link stackEntry}. Useful for aligning stack trace line numbers with
-     * external systems or editors that use different line numbering schemes.
-     *
-     * @see stackEntry
-     * @since 2.0.0
-     */
-    lineOffset: number;
-    /**
-     * Cached syntax-highlighted code snippet from the first processed frame.
+     * The constructor:
+     * 1. Initializes the base error with `message.text ?? ''`
+     * 2. Persists `message.id ?? ''` on {@link id}
+     * 3. If `message.detail` is an `Error`, uses its `message` and `stack` as runtime values
+     * 4. Builds structured metadata from either the original message or `detail` error
+     * 5. Produces formatted output (stack replacement for message-based diagnostics, or
+     *    formatted inspector output for `detail`-based diagnostics)
      *
-     * @remarks
-     * Generated by {@link highlightPositionCode} and stored by {@link formatFrameWithPosition}
-     * on the first frame that has code context. This is the display-ready version of {@link code}
-     * with syntax highlighting, line numbers, and error position markers applied.
+     * The error name is always set to `'esBuildError'`. Formatted output includes:
+     * - Error name and message with color coding
+     * - Any diagnostic notes from esbuild
+     * - Highlighted code snippet showing the error location
+     * - Enhanced stack trace with file path and position
      *
-     * @see highlightPositionCode
-     * @see formatFrameWithPosition
+     * @see {@link getErrorMetadata} for formatting logic
+     * @see {@link PartialMessage} for esbuild message structure
      *
      * @since 2.0.0
      */
-    formatCode: string;
+    constructor(message: PartialMessage, options?: StackTraceInterface);
 }
 /**
- * Provides access to the framework's file paths and associated source maps.
+ * A base class for custom errors with enhanced stack trace formatting and source code information.
  *
  * @remarks
- * This service manages the framework's source map files, including the main framework
- * file and any additional source files. It caches initialized {@link SourceService}
- * instances for performance.
+ * The `xBuildBaseError` class extends the native `Error` class, adding functionality to:
+ * - Parse and store structured stack trace metadata via {@link ResolveMetadataInterface}
+ * - Format stack traces with syntax highlighting and source mapping
+ * - Provide enhanced console output through custom Node.js inspection
+ *
+ * This is particularly useful for debugging errors in compiled or transpiled code by providing
+ * clearer information about the original source of the error, including
+ * - Original source file paths (from source maps)
+ * - Highlighted code snippets showing the error location
+ * - Enhanced stack frame formatting with proper indentation
  *
  * @example
  * ```ts
- * const frameworkService = new FrameworkService();
- * console.log(frameworkService.rootPath);
- * const sourceMap = frameworkService.sourceMap(frameworkService.filePath);
+ * class ValidationError extends xBuildBaseError {
+ *   constructor(message: string, field: string) {
+ *     super(message, 'ValidationError');
+ *     this.reformatStack(this, { withFrameworkFrames: false });
+ *   }
+ * }
+ *
+ * throw new ValidationError('Invalid email format', 'email');
  * ```
  *
+ * @see {@link formatStack} for stack formatting
+ * @see {@link getErrorMetadata} for stack parsing
+ * @see {@link StackTraceInterface} for formatting options
+ * @see {@link ResolveMetadataInterface} for the metadata structure
+ *
  * @since 2.0.0
  */
-declare class FrameworkService {
-    /**
-     * Absolute path to the current file.
-     *
-     * @readonly
-     * @since 2.0.0
-     */
-    readonly filePath: string;
-    /**
-     * Absolute path to the distribution directory.
-     *
-     * @readonly
-     * @since 2.0.0
-     */
-    readonly distPath: string;
-    /**
-     * Absolute path to the project root directory.
-     *
-     * @readonly
-     * @since 2.0.0
-     */
-    readonly rootPath: string;
-    /**
-     * Cached {@link SourceService} instances for additional source files.
-     * @since 2.0.0
-     */
-    private readonly sourceMaps;
-    /**
-     * Initializes a new {@link FrameworkService} instance.
-     *
-     * @remarks
-     * Sets up the main framework source map, as well as root and distribution paths.
-     *
-     * @since 2.0.0
-     */
-    constructor();
-    /**
-     * Determines whether a given {@link PositionInterface} refers to a framework file.
-     *
-     * @param position - The position information to check
-     * @returns `true` if the position is from the framework (contains "xJet"), otherwise `false`
-     *
-     * @see PositionInterface
-     * @since 1.0.0
-     */
-    isFrameworkFile(position: PositionInterface): boolean;
+declare abstract class xBuildBaseError extends Error {
     /**
-     * Retrieves a cached {@link SourceService} for a given file path.
-     *
-     * @param path - Absolute path to the file
-     * @returns A {@link SourceService} instance if found, otherwise `undefined`
+     * Structured metadata from the parsed stack trace.
      *
      * @remarks
-     * Paths are normalized before lookup. Only previously initialized source maps
-     * (via {@link setSource} or {@link setSourceFile}) are available in the cache.
-     *
-     * @see SourceService
-     * @since 2.0.0
-     */
-    getSourceMap(path: string): SourceService | undefined;
-    /**
-     * Registers and initializes a new {@link SourceService} for a provided source map string.
-     *
-     * @param source - The raw source map content
-     * @param path - Absolute file path associated with the source map
-     * @returns A new or cached {@link SourceService} instance
-     *
-     * @throws Error if initialization fails
+     * Contains the parsed stack information including
+     * - Original source code snippet
+     * - Line and column numbers
+     * - Source file path (from source maps)
+     * - Formatted stack frames
+     * - Syntax-highlighted code
      *
-     * @remarks
-     * If a source map for the given path is already cached, the cached instance is returned.
+     * This property is populated by calling {@link reformatStack}.
      *
-     * @see SourceService
      * @since 2.0.0
      */
-    setSource(source: string, path: string): void;
+    protected errorMetadata: ResolveMetadataInterface | undefined;
     /**
-     * Loads and initializes a {@link SourceService} for a file and its `.map` companion.
-     *
-     * @param path - Absolute path to the file
-     * @returns A new or cached {@link SourceService} instance
-     *
-     * @throws Error if the `.map` file cannot be read or parsed
+     * Pre-formatted stack trace string ready for display.
      *
      * @remarks
-     * This method attempts to read the `.map` file located next to the provided file.
-     * If already cached, returns the existing {@link SourceService}.
-     *
-     * @see SourceService
-     * @since 2.0.0
-     */
-    setSourceFile(path: string): void;
-    /**
-     * Retrieves the project root directory.
-     * @returns Absolute path to the project root
+     * Contains the complete formatted output including
+     * - Error name and message
+     * - Syntax-highlighted code snippet (if available)
+     * - Enhanced stack trace with proper indentation
      *
-     * @since 2.0.0
-     */
-    private getRootDir;
-    /**
-     * Retrieves the distribution directory.
-     * @returns Absolute path to the distribution folder
+     * This is generated by {@link formatStack} and used by the custom
+     * Node.js inspector for console output.
      *
      * @since 2.0.0
      */
-    private getDistDir;
+    protected formattedStack: string | undefined;
     /**
-     * Creates and caches a new {@link SourceService} instance for a given source map.
+     * Creates a new instance of the base error class.
      *
-     * @param source - Raw source map content
-     * @param path - Normalized file path used as the cache key
-     * @returns The newly created {@link SourceService} instance
+     * @param message - The error message describing the problem
+     * @param name - The error type name; defaults to `'xBuildBaseError'`
      *
      * @remarks
-     * This method is only used internally by {@link setSource} and {@link setSourceFile}.
-     * The instance is cached in {@link sourceMaps} for reuse.
+     * This constructor:
+     * - Properly sets up the prototype chain to ensure `instanceof` checks work for derived classes
+     * - Captures the stack trace if supported by the runtime environment
+     * - Sets the error name for identification
      *
-     * @see SourceService
-     * @since 2.0.0
-     */
-    private initializeSourceMap;
-}
-/**
- * In-memory cache that maintains lightweight snapshots of file contents (as TypeScript `IScriptSnapshot`)
- * together with modification time and version counters.
- *
- * Primarily used by language servers, transpiler, and incremental build systems to avoid unnecessary
- * file system reads and snapshot recreation when files have not changed.
- *
- * @since 2.0.0
- */
-declare class FilesModel {
-    /**
-     * Cache that maps original (possibly relative) paths → normalized absolute paths with forward slashes
-     * @since 2.0.0
-     */
-    private readonly resolvedPathCache;
-    /**
-     * Main storage: resolved absolute path → current file snapshot state
-     * @since 2.0.0
-     */
-    private readonly snapshotsByPath;
-    /**
-     * Removes all cached paths and snapshots.
-     * @since 2.0.0
-     */
-    clear(): void;
-    /**
-     * Returns the current known snapshot state for the given file path, or `undefined`
-     * if the file has never been touched/observed by this cache.
+     * **Important:** This is a protected constructor and should only be called by derived classes.
+     * Subclasses should call {@link reformatStack} after construction to enable enhanced formatting.
      *
-     * @param path - filesystem path (relative or absolute)
-     * @returns current snapshot data or `undefined` if not tracked yet
+     * @example
+     * ```ts
+     * class DatabaseError extends xBuildBaseError {
+     *   constructor(message: string, public readonly query: string) {
+     *     super(message, 'DatabaseError');
+     *     this.reformatStack(this);
+     *   }
+     * }
+     * ```
      *
      * @since 2.0.0
      */
-    getSnapshot(path: string): FileSnapshotInterface | undefined;
+    protected constructor(message: string, name?: string);
     /**
-     * Returns an existing snapshot entry for the given file path, or creates/updates it if not tracked yet.
+     * Gets the structured stack trace metadata.
      *
-     * @param path - Filesystem path (relative or absolute).
-     * @returns The current snapshot entry for the file (existing or newly created).
+     * @returns The parsed stack metadata, or `undefined` if {@link reformatStack} has not been called
      *
      * @remarks
-     * This is a convenience method combining:
-     * - {@link getSnapshot} (fast path when already tracked), and
-     * - {@link touchFile} (tracks the file, reads content if needed, updates version/mtime).
-     *
-     * Use this when you need a snapshot entry and don't want to handle the `undefined` case.
-     *
-     * @see {@link touchFile}
-     * @see {@link getSnapshot}
-     *
-     * @since 2.0.0
-     */
-    getOrTouchFile(path: string): FileSnapshotInterface;
-    /**
-     * Returns array containing all currently tracked resolved absolute paths.
+     * Provides read-only access to the error's structured stack information,
+     * which can be used for:
+     * - Custom error logging
+     * - Error reporting services
+     * - Debugging tools
+     * - Stack analysis
      *
-     * @returns list of normalized absolute paths (using forward slashes)
+     * @example
+     * ```ts
+     * try {
+     *   throw new ValidationError('Invalid input');
+     * } catch (error) {
+     *   if (error instanceof xBuildBaseError) {
+     *     const meta = error.metadata;
+     *     console.log(`Error at ${meta?.source}:${meta?.line}:${meta?.column}`);
+     *   }
+     * }
+     * ```
      *
      * @since 2.0.0
      */
-    getTrackedFilePaths(): Array<string>;
+    get metadata(): ResolveMetadataInterface | undefined;
     /**
-     * Ensures the file is tracked and returns an up-to-date snapshot state.
+     * Parses the error stack trace and generates enhanced formatting with metadata.
      *
-     * @param path - Filesystem path (relative or absolute)
-     * @returns Shallow copy of the current (possibly just updated) snapshot entry
+     * @param error - The error object to parse and format
+     * @param options - Optional configuration for stack trace parsing and formatting
      *
      * @remarks
-     * This method implements incremental file tracking with three possible outcomes:
-     *
-     * **Fast path (no changes):**
-     * - mtime hasn't changed → returns existing state without I/O
-     *
-     * **Update path (file changed):**
-     * - mtime changed or file is new → reads content and creates fresh `ScriptSnapshot`
-     * - Increments version number for TypeScript language service invalidation
-     *
-     * **Error path (file unavailable):**
-     * - File cannot be read (deleted/permission denied) → clears snapshot and bumps version
-     * - Version increment only occurs if there was previous content (prevents silent no-ops)
+     * This method performs two operations:
+     * 1. Parses the error's stack trace using {@link getErrorMetadata} to extract structured metadata
+     * 2. Formats the metadata using {@link formatStack} to create a styled, human-readable output
      *
-     * Always returns a shallow copy to prevent accidental mutation of internal state.
+     * The parsed metadata is stored in {@link errorMetadata} and the formatted string in {@link formattedStack}.
      *
-     * Typically used in watch mode to notify TypeScript of file changes without full rebuilds.
+     * **Typical usage:** Call this method in the constructor of derived error classes to enable
+     * enhanced stack trace formatting.
      *
      * @example
      * ```ts
-     * const snapshot = filesModel.touchFile('./src/index.ts');
-     *
-     * if (snapshot.contentSnapshot) {
-     *   languageServiceHost.getScriptSnapshot = () => snapshot.contentSnapshot;
-     *   languageServiceHost.getScriptVersion = () => String(snapshot.version);
+     * class NetworkError extends xBuildBaseError {
+     *   constructor(message: string, public readonly statusCode: number) {
+     *     super(message, 'NetworkError');
+     *     // Enable enhanced formatting without framework frames
+     *     this.reformatStack(this, {
+     *       withFrameworkFrames: false,
+     *       withNativeFrames: true
+     *     });
+     *   }
      * }
      * ```
      *
-     * @see {@link getSnapshot}
-     * @see {@link FileSnapshotInterface}
-     *
-     * @since 2.0.0
-     */
-    touchFile(path: string): FileSnapshotInterface;
-    /**
-     * Normalizes the given path to an absolute path using forward slashes.
-     * Results are cached to avoid repeated `path.resolve` + replace calls.
+     * @example
+     * ```ts
+     * class CustomError extends xBuildBaseError {
+     *   constructor(message: string) {
+     *     super(message, 'CustomError');
+     *     // Use default options
+     *     this.reformatStack(this);
+     *   }
+     * }
+     * ```
      *
-     * @param path - any filesystem path
-     * @returns normalized absolute path (always `/` separators)
+     * @see {@link formatStack} for formatting logic
+     * @see {@link getErrorMetadata} for parsing logic
+     * @see {@link StackTraceInterface} for available options
      *
      * @since 2.0.0
      */
-    resolve(path: string): string;
+    protected reformatStack(error: Error, options?: StackTraceInterface): void;
+}
+/**
+ * Configuration options for parsing and formatting stack traces.
+ *
+ * @remarks
+ * These options control how stack traces are parsed, what frames are included,
+ * and how much source code context is displayed. Used by {@link getErrorMetadata}
+ * to customize stack trace output.
+ *
+ * @see stackEntry
+ * @see getErrorMetadata
+ *
+ * @since 2.0.0
+ */
+interface StackTraceInterface extends Omit<ResolveOptionsInterface, 'getSource'> {
     /**
-     * Creates a new snapshot entry for a resolved file path and registers it in the cache.
+     * Whether to include framework-internal stack frames in the output.
      *
-     * @param resolvedPath - Normalized absolute file path
-     * @returns A new {@link FileSnapshotInterface} with initial state (version 0, no content)
+     * @defaultValue Based on `ConfigurationService.verbose` setting
      *
      * @remarks
-     * This method initializes a new file tracking entry with default values:
-     * - `version`: 0 (will increment on first read)
-     * - `mtimeMs`: 0 (will update on first sync)
-     * - `contentSnapshot`: undefined (will populate on first sync)
-     *
-     * The entry is immediately added to {@link snapshotsByPath} to prevent duplicate creation.
-     *
-     * Called internally by {@link touchFile} when encountering a previously unseen file path.
+     * Framework frames are identified by {@link FrameworkService.isFrameworkFile}.
+     * When false, these frames are filtered out to reduce noise in stack traces.
+     * Automatically set based on the `verbose` configuration setting if not
+     * explicitly provided.
      *
-     * @since 2.1.5
+     * @see FrameworkService.isFrameworkFile
+     * @since 2.0.0
      */
-    private createEntry;
+    withFrameworkFrames?: boolean;
+}
+/**
+ * Additional metadata used when resolving and formatting source output.
+ *
+ * @remarks
+ * Extends the base xMap resolution metadata with optional formatted code text
+ * that can be attached to the resolution result.
+ *
+ * @since 2.2.5
+ */
+interface ResolveMetadataInterface extends xMapResolveMetadataInterface {
     /**
-     * Synchronizes a snapshot entry with the current file system state.
-     *
-     * @param resolvedPath - Normalized absolute path to the file
-     * @param entry - The snapshot entry to update
+     * Formatted source code associated with the resolved item.
      *
      * @remarks
-     * This method performs efficient incremental updates:
-     *
-     * **Optimization check:**
-     * - Compares current mtime with cached mtime
-     * - Returns immediately if file hasn't changed (fast path)
-     *
-     * **Update logic:**
-     * - Reads file content only when mtime differs
-     * - Increments version for TypeScript invalidation
-     * - Updates mtime to current value
-     * - Creates TypeScript `ScriptSnapshot` from content
-     *
-     * **File descriptor handling:**
-     * - Opens file in read mode (`'r'`)
-     * - Ensures file descriptor closure via `finally` block
-     * - Throws on read errors (handled by caller)
-     *
-     * Empty file content results in `undefined` snapshot rather than empty snapshot,
-     * signaling that the file has no compilable content.
-     *
-     * @throws Will propagate file system errors (ENOENT, EACCES, etc.) to caller
+     * Typically used when a resolved file needs to preserve or expose its
+     * transformed code representation for later processing or display.
      *
-     * @since 2.1.5
+     * @since 2.2.5
      */
-    private syncEntry;
+    formatCode?: string;
 }
 /**
  * Separates glob patterns into include and exclude arrays.