/**
 * This file was automatically generated by xBuild.
 * DO NOT EDIT MANUALLY.
 */

/**
 * Formats a stack frame into a single display line.
 *
 * @param frame - Stack frame to format.
 * @returns Formatted stack trace line.
 *
 * @remarks
 * When `frame.fileName` is a URL, `#L<line>` is appended to improve linkability.
 * When both `line` and `column` are available, they are rendered as a `[line:column]` suffix.
 *
 * @since 5.0.0
 */
declare function formatStackLine(frame: StackFrameInterface): string;
/**
 * Creates a formatted stack entry enriched with source context and highlighted code.
 *
 * @param position - Resolved position and extracted code context for the frame.
 * @param frame - Stack frame to enrich.
 * @returns Formatted stack frame entry containing `format`, optional `code`, and the source snippet start line.
 *
 * @remarks
 * This function mutates `frame` with resolved `line`, `column`, `fileName`, and optionally `functionName`.
 * When `position.sourceRoot` is present and the source is not an HTTP URL, `frame.fileName` is prefixed with it.
 * It formats the stack line with {@link formatStackLine} and preserves the extracted code context for rendering.
 *
 * @see StackFrameInterface
 * @see PositionWithCodeInterface
 *
 * @since 5.0.0
 */
declare function stackSourceEntry(position: PositionWithCodeInterface, frame: StackFrameInterface): FormatStackFrameInterface;
/**
 * Converts a stack frame into a formatted entry, optionally enriched with source code context.
 *
 * @param frame - Stack frame to convert.
 * @param options - Resolver options controlling filtering and source lookups.
 * @returns Formatted stack frame entry, or `undefined` when filtered out.
 *
 * @remarks
 * Frames marked as native (`frame.native === true`) are excluded unless `options.withNativeFrames` is true.
 * If a source is available via `options.getSource`, the frame is enriched with a highlighted code snippet.
 *
 * @see ResolveOptionsInterface
 * @see FormatStackFrameInterface
 *
 * @since 5.0.0
 */
declare function stackEntry(frame: StackFrameInterface, options?: ResolveOptionsInterface): FormatStackFrameInterface | undefined;
/**
 * Resolves a parsed stack trace into structured metadata with formatted stack entries.
 *
 * @param error - Parsed stack trace to resolve.
 * @param options - Resolver options controlling filtering and source lookups.
 * @returns Resolved metadata containing `name`, `message`, and formatted `stack`.
 *
 * @remarks
 * Stack entries that are filtered out or cannot be enriched are omitted from the returned `stack`.
 *
 * @since 5.0.0
 */
declare function resolveError(error: ParsedStackTraceInterface, options?: ResolveOptionsInterface): ResolveMetadataInterface;
/**
 * Describes the origin of evaluated code referenced by a stack frame.
 *
 * @since 3.0.0
 */
interface EvalOriginInterface {
    /**
     * 1-based line number within the evaluated source, when available.
     * @since 3.0.0
     */
    line?: number;
    /**
     * 1-based column number within the evaluated source line, when available.
     * @since 3.0.0
     */
    column?: number;
    /**
     * File name associated with the evaluated source, when available.
     * @since 3.0.0
     */
    fileName?: string;
    /**
     * Function name associated with the evaluated source, when available.
     * @since 3.0.0
     */
    functionName?: string;
}
/**
 * Represents a stack frame in a stack trace.
 *
 * @remarks
 * This structure provides location and classification details about a single call site,
 * primarily used for diagnostics, stack analysis, and rendering stack traces in a structured form.
 *
 * @since 3.0.0
 */
interface StackFrameInterface {
    /**
     * The original frame text as provided by the runtime or parser.
     * @since 3.0.0
     */
    source: string;
    /**
     * 1-based line number within the source file, when available.
     * @since 3.0.0
     */
    line?: number;
    /**
     * 1-based column number within the source line, when available.
     * @since 3.0.0
     */
    column?: number;
    /**
     * File name for the call site, when available.
     * @since 3.0.0
     */
    fileName?: string;
    /**
     * Function name for the call site, when available.
     * @since 3.0.0
     */
    functionName?: string;
    /**
     * True when the frame originates from evaluated code (for example, `eval()`).
     * @since 3.0.0
     */
    eval: boolean;
    /**
     * True when the frame is part of an asynchronous call chain, when detectable.
     * @since 3.0.0
     */
    async: boolean;
    /**
     * True when the frame originates from native code execution.
     * @since 3.0.0
     */
    native: boolean;
    /**
     * True when the frame represents a constructor invocation.
     * @since 3.0.0
     */
    constructor: boolean;
    /**
     * Information about the evaluated code origin, when `eval` is true and the runtime provides it.
     * @see EvalOriginInterface
     * @since 3.0.0
     */
    evalOrigin?: EvalOriginInterface;
}
/**
 * Represents a fully parsed error stack trace with structured information.
 *
 * @remarks
 * `rawStack` preserves the original stack string for debugging and fallback rendering.
 *
 * @see StackFrameInterface
 * @since 2.1.0
 */
interface ParsedStackTraceInterface {
    /**
     * Error name (for example, `TypeError`).
     * @since 2.1.0
     */
    name: string;
    /**
     * Error message.
     * @since 2.1.0
     */
    message: string;
    /**
     * Parsed frames in call order.
     * @see StackFrameInterface
     * @since 2.1.0
     */
    stack: Array<StackFrameInterface>;
    /**
     * The raw stack string as received from the runtime.
     * @since 2.1.0
     */
    rawStack: string;
}
/**
 * Represents a source map structure used for mapping code within a file to its original source
 * @since 1.0.0
 */
interface SourceMapInterface {
    /**
     * The generated file's name that the source map is associated with
     * @since 1.0.0
     */
    file?: string | null;
    /**
     * An array of variable/function names present in the original source
     * @since 1.0.0
     */
    names?: Array<string>;
    /**
     * The version of the source map specification (standard is 3)
     * @since 1.0.0
     */
    version: number;
    /**
     * An array of URLs or paths to the original source files
     * @since 1.0.0
     */
    sources: Array<string>;
    /**
     * VLQ encoded string that maps generated code back to original source code
     * @since 1.0.0
     */
    mappings: string;
    /**
     * Root URL for resolving the sources
     * @since 1.0.0
     */
    sourceRoot?: string | null;
    /**
     * Array containing the content of the original source files
     * @since 1.0.0
     */
    sourcesContent?: Array<string>;
}
/**
 * Represents a position in source code with mapping information
 * @since 1.0.0
 */
interface PositionInterface {
    /**
     * Name of the identifier at this position
     * @since 1.0.0
     */
    name: string | null;
    /**
     * Line number in the original source
     * @since 1.0.0
     */
    line: number;
    /**
     * Column number in the original source
     * @since 1.0.0
     */
    column: number;
    /**
     * Path or URL to the original source file
     * @since 1.0.0
     */
    source: string;
    /**
     * Root URL for resolving the source
     * @since 1.0.0
     */
    sourceRoot: string | null;
    /**
     * Index of the source in the sources array
     * @since 1.0.0
     */
    sourceIndex: number;
    /**
     * Line number in the generated code
     * @since 1.0.0
     */
    generatedLine: number;
    /**
     * Column number in the generated code
     * @since 1.0.0
     */
    generatedColumn: number;
}
/**
 * Position in source code including the original source content
 *
 * @see PositionInterface
 * @since 1.0.0
 */
interface PositionWithContentInterface extends PositionInterface {
    /**
     * Content of the original source file
     * @since 1.0.0
     */
    sourcesContent: string;
}
/**
 * Position in source code including code fragment information
 *
 * @see PositionInterface
 * @since 1.0.0
 */
interface PositionWithCodeInterface extends PositionInterface {
    /**
     * Code fragment from the original source
     * @since 1.0.0
     */
    code: string;
    /**
     * Ending line number of the code fragment
     * @since 1.0.0
     */
    endLine: number;
    /**
     * Starting line number of the code fragment
     * @since 1.0.0
     */
    startLine: number;
}
/**
 * Options for retrieving source code context
 * @since 1.0.0
 */
interface SourceOptionsInterface {
    /**
     * Number of lines to include after the target line
     * @since 1.0.0
     */
    linesAfter?: number;
    /**
     * Number of lines to include before the target line
     * @since 1.0.0
     */
    linesBefore?: number;
}
/**
 * Options controlling stack trace resolution and source context extraction.
 *
 * @remarks
 * These options are consumed by the resolver to decide how to interpret positions,
 * how much code context to include, and whether to filter native frames.
 *
 * @since 5.0.0
 */
interface ResolveOptionsInterface {
    /**
     * Bias used when mapping line/column pairs to a source position.
     *
     * @remarks
     * Passed through to the underlying source resolver when extracting code context.
     *
     * @since 5.0.0
     */
    bias?: Bias;
    /**
     * 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 5.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 5.0.0
     */
    linesBefore?: number;
    /**
     * Line offset applied to resolved source positions.
     *
     * @remarks
     * This value is added to resolved line numbers before formatted stack entries are created.
     * It is useful when the source context comes from a shifted or combined source, where the
     * displayed line numbers need to be adjusted to match the original file.
     *
     * @since 5.1.0
     */
    lineOffset?: 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 5.0.0
     */
    withNativeFrames?: boolean;
    /**
     * Resolves a {@link SourceService} for the provided path.
     *
     * @param path - File path or URL to resolve.
     * @returns The source service when available, otherwise `null`/`undefined`.
     *
     * @remarks
     * When provided, the resolver uses this callback to enrich frames with highlighted code context.
     *
     * @since 5.0.0
     */
    getSource?(path: string): SourceService | null | undefined;
}
/**
 * Structured metadata produced by resolving a parsed stack trace.
 *
 * @since 5.0.0
 */
interface ResolveMetadataInterface {
    /**
     * Error name (for example, `TypeError`).
     * @since 5.0.0
     */
    name: string;
    /**
     * Error message.
     * @since 5.0.0
     */
    message: string;
    /**
     * Formatted stack frames.
     * @see FormatStackFrameInterface
     * @since 5.0.0
     */
    stack: Array<FormatStackFrameInterface>;
}
/**
 * A stack frame enriched with display formatting and optional source code context.
 *
 * @see StackFrameInterface
 * @since 5.0.0
 */
interface FormatStackFrameInterface extends StackFrameInterface {
    /**
     * Highlighted code context, when available.
     * @since 5.0.0
     */
    code?: string;
    /**
     * Formatted stack line representation.
     * @since 5.0.0
     */
    format: string;
    /**
     * Starting line number of the highlighted code fragment.
     *
     * @remarks
     * Used together with {@link code} to indicate the first line displayed
     * in the extracted source context.
     *
     * @since 5.0.1
     */
    stratLine?: number;
    /**
     * Root URL for resolving the source
     * @since 5.1.0
     */
    sourceRoot?: string | null;
}
/**
 * Service for loading, merging, and querying Source Map v3 data.
 *
 * @remarks
 * This service wraps a {@link MappingService} and enriches segment lookups with
 * source file paths, names, and optional source content/code context.
 *
 * @example
 * ```ts
 * const sourceMapJSON = '{"version": 3, "file": "bundle.js", "sources": ["foo.ts"], "names": [], "mappings": "AAAA"}';
 * const sourceService = new SourceService(sourceMapJSON);
 * console.log(sourceService.file); // 'bundle.js'
 * ```
 *
 * @since 5.0.0
 */
declare class SourceService {
    /**
     * Normalized generated file path associated with this source map.
     * @since 5.0.0
     */
    readonly file: string;
    /**
     * Identifier names referenced by mapped segments.
     * @since 5.0.0
     */
    readonly names: Array<string>;
    /**
     * Resolved source file paths used by the map.
     * @since 5.0.0
     */
    readonly sources: Array<string>;
    /**
     * Optional source root from the source map payload.
     * @since 5.0.0
     */
    readonly sourceRoot: string;
    /**
     * Inline source contents aligned with {@link sources} by index.
     * @since 5.0.0
     */
    readonly sourcesContent: Array<string>;
    /**
     * Internal mappings handler for encode/decode and lookups.
     * @since 5.0.0
     */
    readonly mappings: MappingService;
    /**
     * Creates an empty source service instance.
     *
     * @remarks
     * Useful when building mappings incrementally or as an accumulator target
     * for {@link assign}.
     *
     * @example
     * ```ts
     * const source = new SourceService();
     * ```
     *
     * @since 5.0.0
     */
    constructor();
    /**
     * Creates a source service with a generated line offset.
     *
     * @param source - Source map payload as object or JSON string
     * @param offset - Generated line offset applied during mapping decode
     *
     * @remarks
     * Use this overload when the source map file path is already embedded in
     * the source map payload and only line shifting is required.
     *
     * @example
     * ```ts
     * const source = new SourceService(rawMap, 20);
     * ```
     *
     * @since 5.0.0
     */
    constructor(source: SourceMapInterface | string, offset?: number);
    /**
     * Creates a source service with explicit file path and optional line offset.
     *
     * @param source - Source map payload as object or JSON string
     * @param file - Generated file path override
     * @param offset - Generated line offset applied during mapping decode
     *
     * @remarks
     * Prefer this overload when the source map payload omits `file` or when a
     * normalized file path override is required.
     *
     * @example
     * ```ts
     * const source = new SourceService(rawMap, 'dist/app.js', 5);
     * ```
     *
     * @since 5.0.0
     */
    constructor(source: SourceMapInterface | string, file?: string, offset?: number);
    /**
     * Concatenates multiple source maps into one service instance.
     *
     * @param sources - Source services to merge in order
     *
     * @returns A new service containing merged mappings, names, sources, and contents
     *
     * @throws Error - If no source services are provided
     *
     * @remarks
     * Name and source indices are offset during decode to preserve index
     * correctness across all merged source maps.
     *
     * @example
     * ```ts
     * const merged = SourceService.assign(sourceA, sourceB, ...);
     * ```
     *
     * @since 5.0.0
     */
    static assign(...sources: Array<SourceService>): SourceService;
    /**
     * Serializes current data to a Source Map v3 object.
     *
     * @returns A source map object with encoded mappings
     *
     * @remarks
     * Includes optional `file` and `sourceRoot` only when they are set.
     *
     * @example
     * ```ts
     * const map = source.getSourceObject();
     * ```
     *
     * @since 5.0.0
     */
    getSourceObject(): SourceMapInterface;
    /**
     * Resolves an original position from a generated position.
     *
     * @param line - 1-based generated line number
     * @param column - 1-based generated column number
     * @param bias - Search behavior when no exact match exists (default: {@link BOUND})
     *
     * @returns Position details, or `null` when no segment matches
     *
     * @remarks
     * The returned `name` can be `null` when the mapped segment has no
     * associated name index.
     *
     * @example
     * ```ts
     * const pos = source.getPosition(12, 8);
     * ```
     *
     * @since 5.0.0
     */
    getPosition(line: number, column: number, bias?: Bias): PositionInterface | null;
    /**
     * Resolves an original position and includes full source content for that file.
     *
     * @param line - 1-based generated line number
     * @param column - 1-based generated column number
     * @param bias - Search behavior when no exact match exists (default: {@link BOUND})
     *
     * @returns Position details with source content, or `null` when unavailable
     *
     * @remarks
     * Returns `null` if no mapped segment is found for the generated position.
     *
     * @example
     * ```ts
     * const pos = source.getPositionWithContent(12, 8);
     * ```
     *
     * @since 5.0.0
     */
    getPositionWithContent(line: number, column: number, bias?: Bias): PositionWithContentInterface | null;
    /**
     * Resolves an original position and includes surrounding code context.
     *
     * @param line - 1-based generated line number
     * @param column - 1-based generated column number
     * @param bias - Search behavior when no exact match exists (default: {@link BOUND})
     * @param options - Optional line window configuration
     *
     * @returns Position details with extracted code context, or `null` when unavailable
     *
     * @remarks
     * Default window uses `3` lines before and `4` lines after the target line.
     *
     * @example
     * ```ts
     * const pos = source.getPositionWithCode(12, 8, BOUND, {
     *   linesBefore: 2,
     *   linesAfter: 2
     * });
     * ```
     *
     * @since 5.0.0
     */
    getPositionWithCode(line: number, column: number, bias?: Bias, options?: SourceOptionsInterface): PositionWithCodeInterface | null;
    /**
     * Resolves a generated position from an original source position.
     *
     * @param line - 1-based original source line number
     * @param column - 1-based original source column number
     * @param sourceIndex - Source index or a partial source path to locate the index
     * @param bias - Search behavior when no exact match exists (default: {@link BOUND})
     *
     * @returns Position details, or `null` when no segment/source matches
     *
     * @remarks
     * String `sourceIndex` is matched using substring search against resolved
     * source paths in {@link sources}.
     *
     * @example
     * ```ts
     * const pos = source.getPositionByOriginal(40, 3, 'src/main.ts');
     * ```
     *
     * @since 5.0.0
     */
    getPositionByOriginal(line: number, column: number, sourceIndex: number | string, bias?: Bias): PositionInterface | null;
    /**
     * Serializes the current source map object as JSON.
     *
     * @returns JSON string representation of {@link getSourceObject}
     *
     * @remarks
     * Output is suitable for writing a `.map` file or transport over APIs.
     *
     * @example
     * ```ts
     * const json = source.toString();
     * ```
     *
     * @since 5.0.0
     */
    toString(): string;
    /**
     * Parses and validates Source Map v3 input.
     *
     * @param input - Source map object or JSON string
     *
     * @returns Parsed and validated source map object
     *
     * @throws Error - If source map version is not `3`
     * @throws Error - If required keys are missing
     *
     * @remarks
     * Accepts JSON input for convenience and validates required structural keys
     * before decode operations are attempted.
     *
     * @example
     * ```ts
     * const map = SourceService['parseSourceMap'](raw);
     * ```
     *
     * @since 5.0.0
     */
    private static parseSourceMap;
    /**
     * Checks whether a source path is an HTTP(S) URL.
     *
     * @param path - Path or URL candidate to evaluate
     *
     * @returns `true` when the value starts with `http` or `https`, otherwise `false`
     *
     * @remarks
     * This helper is used to preserve absolute URL sources and avoid filesystem
     * path normalization for remote resources.
     *
     * @example
     * ```ts
     * SourceService['isURL']('https://cdn.example.com/app.ts'); // true
     * SourceService['isURL']('src/app.ts'); // false
     * ```
     *
     * @since 5.0.0
     */
    private static isURL;
    /**
     * Resolves source paths relative to the current working directory.
     *
     * @param sources - Raw source entries from source map payload
     *
     * @returns Normalized relative source file paths
     *
     * @remarks
     * Each path is resolved from the generated file location, then converted to
     * a path relative to `process.cwd()`.
     *
     * @example
     * ```ts
     * // internal utility used during construction
     * ```
     *
     * @since 5.0.0
     */
    private resolveSources;
}
/**
 * Service for encoding, decoding, and querying Source Map v3 mappings.
 *
 * @remarks
 * This service manages the full lifecycle of source map operations:
 * - Decoding from VLQ-encoded strings or structured arrays
 * - Encoding to VLQ-encoded mapping strings
 * - Querying segments by generated or original positions
 * - Building position indices for efficient lookups
 *
 * The service maintains an internal offset state to support merging multiple
 * source maps and handles both 0-based VLQ wire format and 1-based public API.
 *
 * All line and column positions in the public API are 1-based, consistent
 * with how most editors and tools display positions.
 *
 * @example Basic decoding and encoding
 * ```ts
 * const service = new MappingService();
 * service.decode('AAAA;AACA,AADA;AAGA;');
 * const encoded = service.encode();
 * ```
 *
 * @example Querying segments
 * ```ts
 * const service = new MappingService();
 * service.decode(mappingArray);
 * const segment = service.getSegment(1, 5);
 * ```
 *
 * @since 5.0.0
 */
declare class MappingService {
    /**
     * The generated file this source map is associated with.
     *
     * @remarks
     * Optional field specifying the filename of the generated code that this
     * source map describes. This is typically a relative path.
     *
     * Can be `null` or omitted if the filename is not relevant or is provided
     * through other means (e.g., HTTP headers, file naming conventions).
     *
     * @example
     * ```ts
     * file: 'bundle.min.js'
     * ```
     *
     * @since 5.0.0
     */
    private lines;
    /**
     * List of identifier names referenced in the mappings.
     *
     * @remarks
     * Optional array containing all identifier names (variables, functions, etc.)
     * that are referenced by segments with a `nameIndex`. These names correspond
     * to their positions in the original source code.
     *
     * Segments can reference these names by index to indicate which identifier
     * in the original code corresponds to a position in the generated code.
     *
     * Omit this field if no names need to be tracked, or provide an empty array.
     *
     * @example
     * ```ts
     * names: ['myFunction', 'result', 'value']
     * ```
     *
     * @since 5.0.0
     */
    private readonly offsets;
    /**
     * Gets the current line offset used for coordinate adjustments.
     *
     * @returns The line offset value
     *
     * @remarks
     * This offset is applied when decoding mappings to shift generated line numbers.
     * Useful when merging multiple source maps where line numbers need adjustment.
     *
     * @since 5.0.0
     */
    get lineOffset(): number;
    /**
     * Gets the current name index offset used for coordinate adjustments.
     *
     * @returns The name index offset value
     *
     * @remarks
     * This offset is applied when decoding mappings to shift name indices.
     * Necessary when concatenating source maps with different name arrays.
     *
     * @since 5.0.0
     */
    get namesOffset(): number;
    /**
     * Gets the current source file index offset used for coordinate adjustments.
     *
     * @returns The source index offset value
     *
     * @remarks
     * This offset is applied when decoding mappings to shift source file indices.
     * Required when merging source maps with different source file arrays.
     *
     * @since 5.0.0
     */
    get sourcesOffset(): number;
    /**
     * Encodes all stored mappings to a Source Map v3 VLQ string.
     *
     * @returns A Base64 VLQ-encoded mappings string
     *
     * @remarks
     * Converts the internal 1-based segment representation to 0-based VLQ deltas
     * and encodes them as a semicolon-separated string where:
     * - Semicolons (`;`) separate lines
     * - Commas (`,`) separate segments within a line
     * - Empty frames are represented as empty strings between semicolons
     *
     * The encoding process:
     * 1. Resets column offset at each line boundary
     * 2. Computes deltas relative to a previous segment
     * 3. Encodes deltas using Base64 VLQ
     *
     * @example Encoding mappings
     * ```ts
     * const service = new MappingService();
     * service.decode(mappingArray);
     * const vlqString = service.encode();
     * // Returns: "AAAA;AACA,AADA;AAGA;"
     * ```
     *
     * @since 5.0.0
     */
    encode(): string;
    /**
     * Decodes and stores source map data from various input formats.
     *
     * @param mapping - Source map data (VLQ string, array, or MappingService instance)
     * @param namesOffset - Offset to apply to name indices (default: 0)
     * @param sourcesOffset - Offset to apply to source file indices (default: 0)
     * @param lineOffset - Offset to apply to generated line numbers (default: 0)
     *
     * @throws Error - If the mapping format is invalid or contains malformed data
     *
     * @remarks
     * Accepts three input formats:
     * - **VLQ string**: Standard Source Map v3 encoded mappings
     * - **Array**: Structured {@link SourceMappingType} with segments
     * - **MappingService**: Another service instance (copies its lines)
     *
     * Offsets are useful when merging multiple source maps, allowing index
     * adjustment to prevent conflicts in name and source arrays.
     *
     * The method appends to existing mappings, so calling it multiple times
     * will accumulate all decoded segments.
     *
     * @example Decoding from string
     * ```ts
     * const service = new MappingService();
     * service.decode('AAAA;AACA;AADA;');
     * ```
     *
     * @example Decoding with offsets
     * ```ts
     * const service = new MappingService();
     * service.decode(mappingArray, 5, 3, 10);
     * // All name indices += 5, source indices += 3, generated lines += 10
     * ```
     *
     * @example Decoding from another service
     * ```ts
     * const source = new MappingService();
     * source.decode('AAAA;');
     * const target = new MappingService();
     * target.decode(source);
     * ```
     *
     * @since 5.0.0
     */
    decode(mapping: MappingService | SourceMappingType | string, namesOffset?: number, sourcesOffset?: number, lineOffset?: number): void;
    /**
     * Finds a segment at the specified generated position using binary search.
     *
     * @param generatedLine - 1-based generated line number
     * @param generatedColumn - 1-based generated column number
     * @param bias - Search behavior when no exact match exists (default: {@link BOUND})
     *
     * @returns The matching segment, or `null` if no suitable segment exists
     *
     * @remarks
     * Uses binary search for O(log n) performance on sorted segment arrays.
     *
     * Bias behavior:
     * - **`BOUND`**: Returns exact matches only
     * - **`LOWER_BOUND`**: Returns the largest segment ≤ target column
     * - **`UPPER_BOUND`**: Returns the smallest segment ≥ target column
     *
     * The line index is adjusted by the current {@link lineOffset} to support
     * merged source maps with shifted line numbers.
     *
     * @example Finding exact segment
     * ```ts
     * const service = new MappingService();
     * service.decode(mappings);
     * const segment = service.getSegment(1, 5);
     * // Returns a segment at line 1, column 5, or null
     * ```
     *
     * @example Finding nearest lower bound
     * ```ts
     * const segment = service.getSegment(1, 7, LOWER_BOUND);
     * // Returns the closest segment at or before column 7
     * ```
     *
     * @see {@link Bias} for bias options
     * @see {@link getOriginalSegment} for reverse lookups
     *
     * @since 5.0.0
     */
    getSegment(generatedLine: number, generatedColumn: number, bias?: Bias): SegmentInterface | null;
    /**
     * Finds a segment at the specified original source position using linear search.
     *
     * @param sourceLine - 1-based original source line number
     * @param sourceColumn - 1-based original source column number
     * @param sourceIndex - Source file index
     * @param bias - Search behavior when no exact match exists (default: {@link BOUND})
     *
     * @returns The matching segment, or `null` if no suitable segment exists
     *
     * @remarks
     * Performs exhaustive linear search across all segments to find matches
     * by original position. For frequent lookups, consider building an index
     * first using {@link buildOriginalPositionIndex}.
     *
     * Returns immediately on the exact column match. For bias modes, tracks the
     * closest segment by computing column distance.
     *
     * Bias behavior:
     * - **`BOUND`**: Returns exact matches only
     * - **`LOWER_BOUND`**: Returns the closest segment with column ≤ target
     * - **`UPPER_BOUND`**: Returns the closest segment with column ≥ target
     *
     * @example Finding original segment
     * ```ts
     * const service = new MappingService();
     * service.decode(mappings);
     * const segment = service.getOriginalSegment(10, 25, 0);
     * // Returns segment mapping to source file 0, line 10, column 25
     * ```
     *
     * @example Finding the nearest original position
     * ```ts
     * const segment = service.getOriginalSegment(10, 25, 0, LOWER_BOUND);
     * // Returns the closest segment at or before column 25
     * ```
     *
     * @see {@link Bias} for bias options
     * @see {@link getSegment} for generated position lookups
     * @see {@link buildOriginalPositionIndex} for optimized repeated lookups
     *
     * @since 5.0.0
     */
    getOriginalSegment(sourceLine: number, sourceColumn: number, sourceIndex: number, bias?: Bias): SegmentInterface | null;
    /**
     * Builds an indexed map of segments grouped by original source position.
     *
     * @returns A map keyed by `"sourceIndex:line"` with sorted segment arrays
     *
     * @remarks
     * Creates a lookup structure for efficient reverse mapping from original
     * to generated positions. Each bucket contains all segments that map to
     * the same source file and line, sorted by column in ascending order.
     *
     * The index structure:
     * - **Keys**: Formatted as `"sourceIndex:line"` (e.g., `"0:1"`, `"2:15"`)
     * - **Values**: Arrays of {@link SegmentInterface} sorted by `column`
     *
     * This is useful when performing many original position lookups, as it
     * avoids the O(n) linear search of {@link getOriginalSegment}.
     *
     * Null/empty lines are safely skipped during index construction.
     *
     * @example Building and using index
     * ```ts
     * const service = new MappingService();
     * service.decode(mappings);
     * const index = service.buildOriginalPositionIndex();
     *
     * const segments = index.get('0:10');
     * // Returns all segments mapping to source file 0, line 10
     * ```
     *
     * @example Binary search on indexed bucket
     * ```ts
     * const index = service.buildOriginalPositionIndex();
     * const bucket = index.get('0:10') || [];
     * // Perform binary search on bucket for specific column
     * ```
     *
     * @see {@link getOriginalSegment} for single lookups
     *
     * @since 5.0.0
     */
    buildOriginalPositionIndex(): Map<string, Array<SegmentInterface>>;
    /**
     * Encodes a structured source mapping array to a VLQ string.
     *
     * @param sourceMapping - Array of segment lines to encode
     *
     * @returns A Base64 VLQ-encoded mappings string
     *
     * @remarks
     * Converts 1-based segment positions to 0-based VLQ deltas and encodes
     * them according to Source Map v3 specification.
     *
     * The encoding process:
     * 1. Pre-allocates arrays for optimal performance
     * 2. Resets `generatedColumn` offset to 0 at each line boundary
     * 3. Encodes each segment as deltas from the previous segment
     * 4. Joins segments with commas (`,`) and lines with semicolons (`;`)
     *
     * Null lines are encoded as empty strings (represented by consecutive
     * semicolons in the output).
     *
     * This method never reads the `generatedLine` field from segments, as
     * line boundaries are encoded structurally via semicolons.
     *
     * @example Internal encoding
     * ```ts
     * const encoded = this.encodeSourceMapping([
     *     [{ generatedColumn: 1, sourceIndex: 0, line: 1, column: 1, nameIndex: null, generatedLine: 1 }],
     *     null,
     *     [{ generatedColumn: 5, sourceIndex: 0, line: 2, column: 5, nameIndex: null, generatedLine: 3 }]
     * ]);
     * // Returns: "AAAA;;IAIA"
     * ```
     *
     * @see {@link encode} for public API
     * @see {@link encodeSegment} for single segment encoding
     *
     * @since 5.0.0
     */
    private encodeSourceMapping;
    /**
     * Validates that a string contains only valid VLQ characters.
     *
     * @param raw - String to validate
     *
     * @returns `true` if the string is valid, `false` otherwise
     *
     * @remarks
     * Checks that the input contains only characters from the Source Map v3
     * VLQ alphabet plus structural separators:
     * - Base64 VLQ characters: `A-Z`, `a-z`, `0-9`, `+`, `/`
     * - Separators: `,` (segments), `;` (lines)
     *
     * Empty strings are considered invalid.
     *
     * @example Valid mapping string
     * ```ts
     * this.validateSourceMappingString('AAAA;AACA,AADA;')
     * // Returns: true
     * ```
     *
     * @example Invalid mapping string
     * ```ts
     * this.validateSourceMappingString('AAAA;A#A;')
     * // Returns: false (contains '#')
     * ```
     *
     * @since 5.0.0
     */
    private validateSourceMappingString;
    /**
     * Decodes a structured source mapping array and appends segments to internal state.
     *
     * @param sourceMapping - Array of segment lines or null
     *
     * @throws Error - If the array structure is invalid or segments fail validation
     *
     * @remarks
     * Processes a pre-parsed {@link SourceMappingType} array, applying configured
     * offsets to all indices and positions.
     *
     * The decoding process:
     * 1. Validates that input is an array
     * 2. Pre-computes combined line shift for performance
     * 3. Validates each segment using {@link validateSegment}
     * 4. Applies name, source, and line offsets to all coordinates
     * 5. Appends decoded segments to an internal lines array
     *
     * Null lines are preserved as-is. Each segment is validated before the offset
     * application to ensure data integrity.
     *
     * Error messages include 1-based line numbers for easier debugging.
     *
     * @example Internal array decoding
     * ```ts
     * this.decodeSourceMappingArray([
     *     [{ line: 1, column: 1, nameIndex: null, sourceIndex: 0, generatedLine: 1, generatedColumn: 1 }],
     *     null,
     *     [{ line: 2, column: 5, nameIndex: 0, sourceIndex: 0, generatedLine: 3, generatedColumn: 3 }]
     * ]);
     * ```
     *
     * @see {@link decode} for public API
     * @see {@link validateSegment} for validation rules
     *
     * @since 5.0.0
     */
    private decodeSourceMappingArray;
    /**
     * Decodes a VLQ-encoded mapping string and appends segments to internal state.
     *
     * @param encodedMapping - Base64 VLQ-encoded mappings string
     *
     * @throws Error - If the string format is invalid or decoding fails
     *
     * @remarks
     * Parses a Source Map v3 VLQ string into structured segments with 1-based
     * positions, applying configured offsets.
     *
     * The decoding process:
     * 1. Validates a character set using {@link validateSourceMappingString}
     * 2. Splits string by semicolons (`;`) to separate lines
     * 3. Pre-computes offset flags to minimize branching in hot loop
     * 4. For each line:
     *    - Resets `generatedColumn` offset to 0
     *    - Splits by commas (`,`) to separate segments
     *    - Decodes VLQ deltas using {@link decodeVLQ}
     *    - Applies offsets (only allocating new objects when needed)
     * 5. Appends decoded segments to an internal lines array
     *
     * Empty lines (consecutive semicolons) are stored as `null`.
     *
     * Line offset is only applied when non-zero, avoiding unnecessary object
     * allocations for the common case.
     *
     * Error messages include 1-based line numbers for debugging.
     *
     * @example Internal string decoding
     * ```ts
     * this.decodeSourceMappingString('AAAA;AACA,AADA;AAGA;');
     * ```
     *
     * @see {@link decode} for public API
     * @see {@link decodeVLQ} for VLQ decoding
     * @see {@link decodeSegment} for delta application
     *
     * @since 5.0.0
     */
    private decodeSourceMappingString;
}
/**
 * Bias options for binary search operations on segment arrays.
 *
 * @remarks
 * Controls how the search behaves when an exact match is not found:
 * - `BOUND`: Returns the closest match
 * - `LOWER_BOUND`: Returns the largest element less than or equal to the target
 * - `UPPER_BOUND`: Returns the smallest element greater than or equal to the target
 *
 * @since 5.0.0
 */
declare const enum Bias {
    BOUND = 0,
    LOWER_BOUND = 1,
    UPPER_BOUND = 2
}
/**
 * Creates a new VLQ offset state initialized to zero-based positions.
 *
 * @param namesOffset - Initial name index offset
 * @param sourceOffset - Initial source file index offset
 *
 * @returns A new {@link VLQOffsetInterface} with all positional fields set to zero
 *
 * @remarks
 * This function initializes the mutable running state used by VLQ encoding/decoding
 * operations. The offset tracks cumulative deltas as segments are processed sequentially.
 *
 * All positional fields (line, column, generatedLine, generatedColumn) start at 0
 * because the Source Map v3 spec uses 0-based coordinates internally.
 *
 * @example Creating default offset
 * ```ts
 * const offset = createOffset();
 * // { line: 0, column: 0, generatedLine: 0, generatedColumn: 0, sourceIndex: 0, nameIndex: 0 }
 * ```
 *
 * @example Creating offset with initial indices
 * ```ts
 * const offset = createOffset(5, 2);
 * // { line: 0, column: 0, generatedLine: 0, generatedColumn: 0, sourceIndex: 2, nameIndex: 5 }
 * ```
 *
 * @since 5.0.0
 */
declare function createOffset(namesOffset?: number, sourceOffset?: number): VLQOffsetInterface;
/**
 * Apply a single array of decoded VLQ deltas to the running offset and return
 * a fully resolved, **1-based** {@link SegmentInterface}.
 *
 * @param offset - Mutable VLQ running state; **updated in-place**.
 * @param deltas - Raw integers from `decodeVLQ`: `[genCol, srcIdx, srcLine, srcCol, nameIdx?]`
 *
 * @returns A 1-based segment with all positions resolved
 *
 * @remarks
 * The Source Map v3 spec stores values as 0-based deltas from the previous segment.
 * This function advances the offset in-place and converts to 1-based output, so
 * callers never have to reason about the wire format.
 *
 * Delta array structure:
 * - `[0]`: Generated column delta (always present)
 * - `[1]`: Source file index delta (optional)
 * - `[2]`: Source line delta (optional)
 * - `[3]`: Source column delta (optional)
 * - `[4]`: Name index delta (optional, only when a segment references a name)
 *
 * The offset parameter is mutated to reflect the new accumulated state.
 *
 * @example Decoding segment with name
 * ```ts
 * const offset = createOffset();
 * const segment = decodeSegment(offset, [4, 0, 0, 5, 0]);
 * // { generatedLine: 1, generatedColumn: 5, line: 1, column: 6, sourceIndex: 0, nameIndex: 0 }
 * ```
 *
 * @example Decoding segment without name
 * ```ts
 * const offset = createOffset();
 * const segment = decodeSegment(offset, [10, 1, 2, 3]);
 * // { generatedLine: 1, generatedColumn: 11, line: 3, column: 4, sourceIndex: 1, nameIndex: null }
 * ```
 *
 * @see {@link SegmentInterface} for the resolved segment output
 * @see {@link VLQOffsetInterface} for more details on the running state
 *
 * @since 5.0.0
 */
declare function decodeSegment(offset: VLQOffsetInterface, deltas: Array<number>): SegmentInterface;
/**
 * Decode a single raw VLQ segment string into a resolved, **1-based** {@link SegmentInterface}.
 *
 * @param offset - Mutable VLQ running state; **updated in-place**.
 * @param raw - A single VLQ-encoded segment string (e.g. `"AAAA"` or `"kBgB"`)
 *
 * @returns A 1-based segment with all positions resolved
 *
 * @remarks
 * Convenience wrapper around {@link decodeSegment} + {@link decodeVLQ}.
 * This function first decodes the Base64 VLQ string into an array of integers,
 * then processes those deltas to produce the final segment.
 *
 * The offset parameter is advanced to reflect the cumulative state.
 *
 * @example Decoding a raw segment
 * ```ts
 * const offset = createOffset();
 * const segment = decodeSegmentRaw(offset, "AAAA");
 * // Decodes and applies the VLQ-encoded deltas
 * ```
 *
 * @see {@link decodeVLQ} for Base64 VLQ decoding
 * @see {@link decodeSegment} for delta processing
 *
 * @since 5.0.0
 */
declare function decodeSegmentRaw(offset: VLQOffsetInterface, raw: string): SegmentInterface;
/**
 * Encode a **1-based** {@link SegmentInterface} into a VLQ delta string.
 *
 * @param offset - Mutable VLQ running state; **updated in-place**.
 * @param seg - The 1-based segment to encode
 *
 * @returns A Base64 VLQ-encoded string representing the deltas
 *
 * @remarks
 * The 1-based public values are converted back to 0-based VLQ deltas so the
 * wire format stays spec-compliant with Source Map v3.
 *
 * This function:
 * 1. Converts 1-based positions to 0-based coordinates
 * 2. Computes deltas from the running offset
 * 3. Encodes deltas as Base64 VLQ
 * 4. Updates the offset to reflect the new state
 *
 * The encoded string contains 4 or 5 values:
 * - Generated column delta (always present)
 * - Source file index delta
 * - Source line delta
 * - Source column delta
 * - Name index delta (only if segment has a name)
 *
 * @example Encoding a segment
 * ```ts
 * const offset = createOffset();
 * const encoded = encodeSegment(offset, {
 *     generatedLine: 1, generatedColumn: 5,
 *     line: 1, column: 6,
 *     sourceIndex: 0, nameIndex: 0
 * });
 * // Returns Base64 VLQ string like "IAAMA"
 * ```
 *
 * @see {@link encodeArrayVLQ} for Base64 VLQ encoding
 *
 * @since 5.0.0
 */
declare function encodeSegment(offset: VLQOffsetInterface, seg: SegmentInterface): string;
/**
 * Validate all fields of a {@link SegmentInterface}.
 *
 * @param segment - The segment to validate
 *
 * @throws Error - on the first field that fails validation
 *
 * @remarks
 * Ensures all positional values are finite numbers and that every 1-based
 * position is ≥ 1. Throws on the first invalid field with a descriptive message.
 *
 * Validation rules:
 * - `line`, `column`, `generatedLine`, `generatedColumn`: Must be finite and ≥ 1
 * - `sourceIndex`: Must be a finite number (can be 0)
 * - `nameIndex`: Must be a finite number or `null`
 *
 * @example Valid segment
 * ```ts
 * validateSegment({
 *     line: 1, column: 5,
 *     generatedLine: 1, generatedColumn: 10,
 *     sourceIndex: 0, nameIndex: null
 * });
 * // No error thrown
 * ```
 *
 * @example Invalid segment (throws)
 * ```ts
 * validateSegment({
 *     line: 0, column: 5,
 *     generatedLine: 1, generatedColumn: 10,
 *     sourceIndex: 0, nameIndex: null
 * });
 * // Error: Invalid segment: 'line' must be a finite number ≥ 1, received 0
 * ```
 *
 * @see SegmentInterface
 *
 * @since 5.0.0
 */
declare function validateSegment(segment: SegmentInterface): void;
/**
 * A single decoded segment in a source map.
 *
 * @remarks
 * All line and column values are **1-based** for the public API.
 * This represents a mapping between a position in the generated (output) file
 * and the corresponding position in the original source file.
 *
 * Each segment can optionally reference a name from the source map's `names` array,
 * typically used for identifier mappings (e.g., minified variable names).
 *
 * @example Basic segment
 * ```ts
 * const segment: SegmentInterface = {
 *     generatedLine: 1,
 *     generatedColumn: 5,
 *     line: 10,
 *     column: 15,
 *     sourceIndex: 0,
 *     nameIndex: null
 * };
 * ```
 *
 * @example Segment with name reference
 * ```ts
 * const segment: SegmentInterface = {
 *     generatedLine: 1,
 *     generatedColumn: 10,
 *     line: 5,
 *     column: 20,
 *     sourceIndex: 0,
 *     nameIndex: 3  // References names[3] in the source map
 * };
 * ```
 *
 * @see {@link VLQOffsetInterface}
 *
 * @since 5.0.0
 */
interface SegmentInterface {
    /**
     * 1-based line in the original source file.
     *
     * @remarks
     * Corresponds to the original source position before transformation.
     * Always ≥ 1 for valid segments.
     *
     * @since 5.0.0
     */
    line: number;
    /**
     * 1-based column in the original source file.
     *
     * @remarks
     * Corresponds to the original source position before transformation.
     * Always ≥ 1 for valid segments.
     *
     * @since 5.0.0
     */
    column: number;
    /**
     * 1-based line in the generated (output) file.
     *
     * @remarks
     * Corresponds to the position in the transformed/compiled output.
     * Always ≥ 1 for valid segments.
     *
     * @since 5.0.0
     */
    generatedLine: number;
    /**
     * 1-based column in the generated (output) file.
     *
     * @remarks
     * Corresponds to the position in the transformed/compiled output.
     * Always ≥ 1 for valid segments.
     *
     * @since 5.0.0
     */
    generatedColumn: number;
    /**
     * Index into the source map's `sources` array.
     *
     * @remarks
     * This is 0-based and references which source file this segment maps to.
     * Must be a finite number ≥ 0.
     *
     * @since 5.0.0
     */
    sourceIndex: number;
    /**
     * Index into the source map's `names` array, or null when absent.
     *
     * @remarks
     * This is 0-based and references an identifier name (e.g., variable or function name)
     * in the source map. When `null`, this segment does not reference a name.
     *
     * Typically used for preserving original identifier names after minification.
     *
     * @since 5.0.0
     */
    nameIndex: number | null;
}
/**
 * Internal VLQ running-state used while incrementally encoding or decoding deltas.
 *
 * @remarks
 * All fields are **0-based** — the Source Map v3 wire format is 0-based throughout.
 * This type is an implementation detail; callers work with {@link SegmentInterface} instead.
 *
 * The offset is mutated in-place as segments are processed sequentially, accumulating
 * deltas from the VLQ-encoded mappings string. This avoids repeated conversions between
 * 0-based and 1-based coordinates.
 *
 * @example Creating initial offset
 * ```ts
 * const offset: VLQOffsetInterface = {
 *     line: 0,
 *     column: 0,
 *     generatedLine: 0,
 *     generatedColumn: 0,
 *     sourceIndex: 0,
 *     nameIndex: 0
 * };
 * ```
 *
 * @see {@link SegmentInterface}
 *
 * @since 5.0.0
 */
interface VLQOffsetInterface {
    /**
     * 0-based running source line.
     *
     * @remarks
     * Accumulates line deltas from decoded VLQ segments.
     * Internal representation only; converted to 1-based for public API.
     *
     * @since 5.0.0
     */
    line: number;
    /**
     * 0-based running source column.
     *
     * @remarks
     * Accumulates column deltas from decoded VLQ segments.
     * Internal representation only; converted to 1-based for public API.
     *
     * @since 5.0.0
     */
    column: number;
    /**
     * 0-based running generated line (frame index).
     *
     * @remarks
     * Tracks the current line in the generated output file.
     * Internal representation only; converted to 1-based for public API.
     *
     * @since 5.0.0
     */
    generatedLine: number;
    /**
     * 0-based running generated column — resets to 0 at the start of each line.
     *
     * @remarks
     * Accumulates column deltas within the current generated line.
     * Resets to 0 when moving to a new line in the mappings.
     * Internal representation only; converted to 1-based for public API.
     *
     * @since 5.0.0
     */
    generatedColumn: number;
    /**
     * 0-based running source index.
     *
     * @remarks
     * Accumulates source file index deltas from decoded VLQ segments.
     * References to the `sources` array in the source map.
     *
     * @since 5.0.0
     */
    sourceIndex: number;
    /**
     * 0-based running name index.
     *
     * @remarks
     * Accumulates name index deltas from decoded VLQ segments.
     * References the `names` array in the source map.
     *
     * @since 5.0.0
     */
    nameIndex: number;
}
/**
 * Offset values for adjusting segment indices and positions during decode operations.
 *
 * @remarks
 * This interface defines the offset state used by `MappingService` when
 * decoding and merging multiple source maps. Each offset is applied to its
 * corresponding segment field to shift indices and positions.
 *
 * Common use case: When concatenating multiple source maps, offsets prevent
 * index conflicts in shared arrays (names, sources) and adjust line numbers
 * to account for concatenated generated code.
 *
 * All offset values default to 0 when no adjustment is needed.
 *
 * @example Offset configuration for merged maps
 * ```ts
 * const offsets: SegmentsOffsetsInterface = {
 *     line: 100,      // Generated lines start at 101
 *     name: 5,        // a Name array starts at index 5
 *     sources: 3      // Source array starts at index 3
 * };
 * ```
 *
 * @since 5.0.0
 */
interface SegmentsOffsetsInterface {
    /**
     * Offset applied to generated line numbers.
     *
     * @remarks
     * Added to each segment's `generatedLine` field during decoding.
     * Used when merging source maps to shift line numbers for concatenated output.
     *
     * @since 5.0.0
     */
    line: number;
    /**
     * Offset applied to name indices.
     *
     * @remarks
     * Added to each segment's `nameIndex` field during decoding.
     * Necessary when merging source maps with different name arrays to prevent
     * index collisions.
     *
     * @since 5.0.0
     */
    name: number;
    /**
     * Offset applied to source file indices.
     *
     * @remarks
     * Added to each segment's `sourceIndex` field during decoding.
     * Required when merging source maps with different source file arrays to
     * maintain correct references.
     *
     * @since 5.0.0
     */
    sources: number;
}
/**
 * All segments for a single generated line, sorted by column position.
 *
 * @remarks
 * Represents a complete mapping line where all segments share the same
 * `generatedLine` value and are ordered by `generatedColumn` in ascending order.
 *
 * The sorted order enables efficient binary search operations when looking up
 * segments by generated column position. This ordering is maintained by both
 * encoding and decoding operations.
 *
 * An empty array indicates a generated line exists but has no source mappings.
 *
 * @example Single line with multiple segments
 * ```ts
 * const line: MappingLineType = [
 *     { generatedLine: 1, generatedColumn: 1, line: 1, column: 1, sourceIndex: 0, nameIndex: null },
 *     { generatedLine: 1, generatedColumn: 5, line: 1, column: 3, sourceIndex: 0, nameIndex: null },
 *     { generatedLine: 1, generatedColumn: 10, line: 1, column: 8, sourceIndex: 0, nameIndex: 0 }
 * ];
 * ```
 *
 * @see {@link SegmentInterface} for segment structure
 * @see {@link SourceMappingType} for the complete mapping structure
 *
 * @since 5.0.0
 */
type MappingLineType = Array<SegmentInterface>;
/**
 * Complete source map represented as an array of mapping lines.
 *
 * @remarks
 * The decoded representation of a Source Map v3 mappings field, structured as
 * an array where each index corresponds to a 0-based generated line number.
 *
 * Each entry is either:
 * - **`MappingLineType`**: An array of segments for that generated line
 * - **`null`**: Indicates the generated line has no source mappings
 *
 * The array index directly corresponds to generated line numbers (0-based),
 * so `SourceMappingType[0]` contains mappings for generated line 1.
 *
 * Null entries are common for:
 * - Empty lines in generated code
 * - Lines without corresponding source positions
 * - Structural spacing preserved in the encoding
 *
 * This structure optimizes for O(1) line lookups and maintains the natural
 * ordering of generated code.
 *
 * @example Complete mapping with null line
 * ```ts
 * const mapping: SourceMappingType = [
 *     [{ generatedLine: 1, generatedColumn: 1, line: 1, column: 1, sourceIndex: 0, nameIndex: null }],
 *     null,  // Generated line 2 has no mappings
 *     [{ generatedLine: 3, generatedColumn: 1, line: 2, column: 1, sourceIndex: 0, nameIndex: null }]
 * ];
 * ```
 *
 * @example Empty mapping
 * ```ts
 * const mapping: SourceMappingType = [];
 * ```
 *
 * @see {@link MappingLineType} for line structure
 * @see {@link SegmentInterface} for segment details
 *
 * @since 5.0.0
 */
type SourceMappingType = Array<MappingLineType | null>;
/**
 * Encodes a signed integer into Base64 VLQ (Variable-Length Quantity) format.
 *
 * @param value - The signed integer to encode (can be negative)
 *
 * @returns The Base64-encoded VLQ string representation
 *
 * @remarks
 * This function implements VLQ encoding with Base64 character mapping:
 * 1. Converts the value to unsigned format (negative numbers get sign bit)
 * 2. Splits the value into 5-bit chunks
 * 3. Sets continuation bit on all chunks except the last
 * 4. Encodes each chunk as a Base64 character
 *
 * VLQ format:
 * - Sign bit: Least significant bit of the first chunk (1 for negative, 0 for positive)
 * - Data bits: Remaining bits store the absolute value
 * - Continuation bit: 6th bit indicates if more chunks follow
 *
 * This encoding is commonly used in source maps for efficient delta encoding.
 *
 * @example Encoding positive number
 * ```ts
 * const encoded = encodeVLQ(123);
 * // '6H' (VLQ representation)
 * ```
 *
 * @example Encoding negative number
 * ```ts
 * const encoded = encodeVLQ(-456);
 * // 'twB' (VLQ representation with sign bit)
 * ```
 *
 * @example Encoding zero
 * ```ts
 * const encoded = encodeVLQ(0);
 * // 'A'
 * ```
 *
 * @see {@link decodeVLQ} for decoding VLQ strings
 * @see {@link encodeArrayVLQ} for encoding multiple values
 *
 * @since 1.0.0
 */
declare function encodeVLQ(value: number): string;
/**
 * Encodes an array of signed integers into a single Base64 VLQ string.
 *
 * @param values - Array of signed integers to encode
 *
 * @returns Concatenated Base64 VLQ string representing all values
 *
 * @remarks
 * This function encodes multiple values by applying {@link encodeVLQ} to each element
 * and concatenating the results. The encoded values are not separated by delimiters;
 * the VLQ format's continuation bits allow the decoder to determine value boundaries.
 *
 * This is commonly used in source maps to encode segment data efficiently.
 *
 * @example Encoding multiple values
 * ```ts
 * const encoded = encodeArrayVLQ([0, 5, -10, 100]);
 * // 'AKAS6H' (concatenated VLQ encoding)
 * ```
 *
 * @example Encoding empty array
 * ```ts
 * const encoded = encodeArrayVLQ([]);
 * // ''
 * ```
 *
 * @example Encoding single value
 * ```ts
 * const encoded = encodeArrayVLQ([42]);
 * // 'U' (equivalent to encodeVLQ(42))
 * ```
 *
 * @see {@link encodeVLQ} for single value encoding
 * @see {@link decodeVLQ} for decoding the result
 *
 * @since 1.0.0
 */
declare function encodeArrayVLQ(values: Array<number>): string;
/**
 * Decodes a Base64 VLQ (Variable-Length Quantity) string into an array of signed integers.
 *
 * @param data - The Base64 VLQ-encoded string to decode
 *
 * @returns Array of decoded signed integers
 *
 * @throws {@link Error}
 * Thrown when encountering an invalid Base64 character or incomplete VLQ sequence
 *
 * @remarks
 * This function implements VLQ decoding with Base64 character mapping:
 * 1. Reads Base64 characters and converts them to 6-bit values
 * 2. Extracts 5-bit data chunks and checks continuation bits
 * 3. Accumulates chunks until a terminal chunk is found
 * 4. Converts accumulated value back to signed integer using the sign bit
 *
 * The function validates:
 * - All characters are valid Base64 characters
 * - VLQ sequences are properly terminated (no incomplete sequences)
 *
 * Error conditions:
 * - Invalid Base64 character: Reports the character and its position
 * - Incomplete sequence: Reports when the string ends mid-value
 *
 * @example Decoding single value
 * ```ts
 * const values = decodeVLQ('6H');
 * // [123]
 * ```
 *
 * @example Decoding multiple values
 * ```ts
 * const values = decodeVLQ('AKAS6H');
 * // [0, 5, -10, 100]
 * ```
 *
 * @example Handling errors - invalid character
 * ```ts
 * try {
 *   decodeVLQ('AB@C');
 * } catch (err) {
 *   console.error(err.message);
 *   // "Invalid Base64 character: '@' at index 2"
 * }
 * ```
 *
 * @example Handling errors - incomplete sequence
 * ```ts
 * try {
 *   decodeVLQ('g');
 * } catch (err) {
 *   console.error(err.message);
 *   // "Unexpected end of VLQ input: incomplete sequence"
 * }
 * ```
 *
 * @see {@link encodeVLQ} for encoding values
 * @see {@link encodeArrayVLQ} for encoding arrays
 *
 * @since 1.0.0
 */
declare function decodeVLQ(data: string): Array<number>;
/**
 * Converts a file path to POSIX format by normalizing backslashes and duplicate slashes.
 *
 * @param input - The file path to convert (can be null or undefined)
 *
 * @returns The path in POSIX format with forward slashes, or an empty string if input is falsy
 *
 * @remarks
 * This function performs the following transformations:
 * 1. Converts all backslashes (`\`) to forward slashes (`/`)
 * 2. Collapses consecutive forward slashes into a single slash
 * 3. Returns an empty string for null, undefined, or empty input
 *
 * This is useful for normalizing Windows-style paths to POSIX-style paths for
 * cross-platform compatibility in build tools and file processing.
 *
 * @example Converting Windows path
 * ```ts
 * const windowsPath = 'C:\\Users\\Documents\\file.txt';
 * const posixPath = toPosix(windowsPath);
 * // 'C:/Users/Documents/file.txt'
 * ```
 *
 * @example Normalizing duplicate slashes
 * ```ts
 * const messyPath = 'src//components///Button.tsx';
 * const cleanPath = toPosix(messyPath);
 * // 'src/components/Button.tsx'
 * ```
 *
 * @example Handling falsy values
 * ```ts
 * toPosix(null);      // ''
 * toPosix(undefined); // ''
 * toPosix('');        // ''
 * ```
 *
 * @since 4.1.0
 */
declare function toPosix(input: string | null | undefined): string;
/**
 * Normalizes a file path to POSIX format and resolves `.` and `..` segments.
 *
 * @param path - The file path to normalize
 *
 * @returns The normalized POSIX path with resolved relative segments
 *
 * @remarks
 * This function:
 * 1. Converts the path to POSIX format using {@link toPosix}
 * 2. Applies `path.posix.normalize()` to resolve `.` and `..` segments
 * 3. Removes trailing slashes (except for root `/`)
 *
 * @example Resolving relative segments
 * ```ts
 * const path = 'src/components/../utils/./helper.ts';
 * const normalized = normalize(path);
 * // 'src/utils/helper.ts'
 * ```
 *
 * @example Normalizing Windows path
 * ```ts
 * const windowsPath = 'C:\\Users\\..\\Documents\\file.txt';
 * const normalized = normalize(windowsPath);
 * // 'C:/Documents/file.txt'
 * ```
 *
 * @see {@link toPosix} for path conversion
 *
 * @since 4.1.0
 */
declare function normalize(path: string): string;
/**
 * Joins multiple path segments into a single POSIX path.
 *
 * @param paths - Path segments to join
 *
 * @returns The joined path in POSIX format with normalized separators
 *
 * @remarks
 * This function:
 * 1. Converts each path segment to POSIX format using {@link toPosix}
 * 2. Joins them using `path.posix.join()`
 * 3. Normalizes the result (resolves `.` and `..`, removes duplicate slashes)
 *
 * @example Joining path segments
 * ```ts
 * const fullPath = join('src', 'components', 'Button.tsx');
 * // 'src/components/Button.tsx'
 * ```
 *
 * @example Joining mixed-format paths
 * ```ts
 * const fullPath = join('C:\\Users', 'Documents', '../Pictures/photo.jpg');
 * // 'C:/Users/Pictures/photo.jpg'
 * ```
 *
 * @example Joining with empty segments
 * ```ts
 * const fullPath = join('src', '', 'utils');
 * // 'src/utils'
 * ```
 *
 * @see {@link toPosix} for path conversion
 *
 * @since 4.1.0
 */
declare function join(...paths: Array<string>): string;
/**
 * Resolves a sequence of paths into an absolute POSIX path.
 *
 * @param paths - Path segments to resolve (processed right-to-left until an absolute path is found)
 *
 * @returns The resolved absolute path in POSIX format
 *
 * @remarks
 * This function:
 * 1. Uses Node.js `path.resolve()` to compute the absolute path
 * 2. Converts the result to POSIX format using {@link toPosix}
 * 3. Processes paths right-to-left, stopping at the first absolute path
 *
 * The resolution process:
 * - If no absolute path is found, prepends the current working directory
 * - Relative segments (`.` and `..`) are resolved
 * - The result is always an absolute path
 *
 * @example Resolving relative paths
 * ```ts
 * // Current directory: /home/user/project
 * const absolutePath = resolve('src', 'components', 'Button.tsx');
 * // '/home/user/project/src/components/Button.tsx'
 * ```
 *
 * @example Resolving with an absolute path
 * ```ts
 * const absolutePath = resolve('/var/www', 'html', 'index.html');
 * // '/var/www/html/index.html'
 * ```
 *
 * @example Resolving on Windows
 * ```ts
 * // Current directory: C:\Users\project
 * const absolutePath = resolve('src\\utils', '../components/Button.tsx');
 * // 'C:/Users/project/src/components/Button.tsx'
 * ```
 *
 * @see {@link toPosix} for path conversion
 *
 * @since 4.1.0
 */
declare function resolve(...paths: Array<string>): string;
/**
 * Returns the directory name of a path in POSIX format.
 *
 * @param p - The file path
 *
 * @returns The directory portion of the path, or `.` for paths without a directory component
 *
 * @remarks
 * This function:
 * 1. Converts the path to POSIX format using {@link toPosix}
 * 2. Extracts the directory portion using `path.posix.dirname()`
 * 3. Removes the last segment (file or final directory name)
 *
 * @example Getting directory name
 * ```ts
 * const dir = dirname('/home/user/file.txt');
 * // '/home/user'
 * ```
 *
 * @example Windows path
 * ```ts
 * const dir = dirname('C:\\Users\\Documents\\file.txt');
 * // 'C:/Users/Documents'
 * ```
 *
 * @example Path without directory
 * ```ts
 * const dir = dirname('file.txt');
 * // '.'
 * ```
 *
 * @example Root path
 * ```ts
 * const dir = dirname('/file.txt');
 * // '/'
 * ```
 *
 * @see {@link toPosix} for path conversion
 *
 * @since 4.1.0
 */
declare function dirname(p: string): string;
/**
 * Calculates the relative path from one location to another in POSIX format.
 *
 * @param from - The source path (starting point)
 * @param to - The destination path (target)
 *
 * @returns The relative path from `from` to `to`, or `.` if paths are identical
 *
 * @remarks
 * This function:
 * 1. Converts both paths to POSIX format using {@link toPosix}
 * 2. Computes the relative path using `path.posix.relative()`
 * 3. Returns `.` when the result is empty (indicating the same location)
 *
 * The relative path uses `..` to navigate up directories and includes only
 * the necessary segments to reach the destination from the source.
 *
 * @example Basic relative path
 * ```ts
 * const rel = relative('/home/user/project', '/home/user/docs/file.txt');
 * // '../docs/file.txt'
 * ```
 *
 * @example Same directory
 * ```ts
 * const rel = relative('/home/user', '/home/user');
 * // '.'
 * ```
 *
 * @example Windows paths
 * ```ts
 * const rel = relative('C:\\Users\\project\\src', 'C:\\Users\\project\\dist\\bundle.js');
 * // '../dist/bundle.js'
 * ```
 *
 * @example Sibling directories
 * ```ts
 * const rel = relative('/app/src/components', '/app/src/utils');
 * // '../utils'
 * ```
 *
 * @see {@link toPosix} for path conversion
 *
 * @since 4.1.0
 */
declare function relative(from: string, to: string): string;
/**
 * Returns the last portion of a path (filename or directory name) in POSIX format.
 *
 * @param p - The file path
 * @param suffix - Optional file extension to remove from the result
 *
 * @returns The base name of the path, optionally with the suffix removed
 *
 * @remarks
 * This function:
 * 1. Converts the path to POSIX format using {@link toPosix}
 * 2. Extracts the final segment using `path.posix.basename()`
 * 3. Optionally removes the specified suffix if it matches the end of the basename
 *
 * The suffix parameter is useful for extracting filenames without extensions.
 *
 * @example Getting filename
 * ```ts
 * const name = basename('/home/user/documents/report.pdf');
 * // 'report.pdf'
 * ```
 *
 * @example Removing extension
 * ```ts
 * const name = basename('/home/user/documents/report.pdf', '.pdf');
 * // 'report'
 * ```
 *
 * @example Windows path
 * ```ts
 * const name = basename('C:\\Users\\Documents\\file.txt');
 * // 'file.txt'
 * ```
 *
 * @example Directory name
 * ```ts
 * const name = basename('/home/user/documents/');
 * // 'documents'
 * ```
 *
 * @example Suffix doesn't match
 * ```ts
 * const name = basename('file.txt', '.md');
 * // 'file.txt'
 * ```
 *
 * @see {@link toPosix} for path conversion
 *
 * @since 4.1.0
 */
declare function basename(p: string, suffix?: string): string;

export {
	Bias,
	FormatStackFrameInterface,
	PositionInterface,
	PositionWithCodeInterface,
	PositionWithContentInterface,
	ResolveMetadataInterface,
	ResolveOptionsInterface,
	SegmentInterface,
	SourceMapInterface,
	SourceOptionsInterface,
	SourceService,
	VLQOffsetInterface,
	basename,
	createOffset,
	decodeSegment,
	decodeSegmentRaw,
	decodeVLQ,
	dirname,
	encodeArrayVLQ,
	encodeSegment,
	encodeVLQ,
	formatStackLine,
	join,
	normalize,
	relative,
	resolve,
	resolveError,
	stackEntry,
	stackSourceEntry,
	toPosix,
	validateSegment
};