/**
 * @file The `Logger` class + the shared-default `getDefaultLogger()` accessor —
 *   the public class surface for `logger/*`. Owns the per-instance state
 *   (parent, bound stream, indent buffers, theme), the symbol-prefixed semantic
 *   methods (`success`, `fail`, `info`, ...), the chainable wrappers around the
 *   underlying `Console` methods, AND the module-singleton accessor for the
 *   shared default instance. Console construction is deliberately lazy: the
 *   constructor only stashes its args in `_internal.privateConstructorArgs`;
 *   the actual `node:console` instance is built on first call to
 *   `#getConsole()`. This lets the logger be imported during early Node.js
 *   bootstrap before stdout is ready, avoiding `ERR_CONSOLE_WRITABLE_STREAM`.
 *   Free helpers live in sibling leaves (per `socket-lib`'s
 *   export-top-level-functions rule):
 *
 *   - color helpers — `./colors` (`applyColor`, `getYoctocolors`)
 *   - log symbols + symbol getters — `./symbols`
 *   - lazy console init + prototype mirror — `./console-init`
 *   - shared private state — `./_internal`
 */
import { incLogCallCountSymbol, lastWasBlankSymbol } from './symbols';
import type { Task } from './types';
/**
 * Enhanced console logger with indentation, colored symbols, and stream
 * management.
 */
export declare class Logger {
    #private;
    /**
     * Static reference to log symbols for convenience.
     */
    static LOG_SYMBOLS: Record<string, string>;
    /**
     * Creates a new Logger instance.
     *
     * When called without arguments, creates a logger using the default
     * `process.stdout` and `process.stderr` streams. Can accept custom console
     * constructor arguments for advanced use cases.
     *
     * @param args - Optional console constructor arguments.
     */
    constructor(...args: unknown[]);
    /**
     * Gets a logger instance bound exclusively to stderr.
     *
     * All logging operations on this instance will write to stderr only.
     * Indentation is tracked separately from stdout. The instance is cached and
     * reused on subsequent accesses.
     *
     * @returns A logger instance bound to stderr
     */
    get stderr(): Logger;
    /**
     * Gets a logger instance bound exclusively to stdout.
     *
     * All logging operations on this instance will write to stdout only.
     * Indentation is tracked separately from stderr. The instance is cached and
     * reused on subsequent accesses.
     *
     * @returns A logger instance bound to stdout
     */
    get stdout(): Logger;
    /**
     * Gets the total number of log calls made on this logger instance.
     *
     * Tracks all logging method calls including `log()`, `error()`, `warn()`,
     * `success()`, `fail()`, etc. Useful for testing and monitoring logging
     * activity.
     *
     * @returns The number of times logging methods have been called
     */
    get logCallCount(): number;
    /**
     * Increments the internal log call counter.
     *
     * This is called automatically by logging methods and should not be called
     * directly in normal usage.
     */
    [incLogCallCountSymbol](): this;
    /**
     * Sets whether the last logged line was blank.
     *
     * Used internally to track blank lines and prevent duplicate spacing. This is
     * called automatically by logging methods.
     *
     * @param value - Whether the last line was blank.
     * @param stream - Optional stream to update (defaults to both streams if not
     *   bound, or target stream if bound)
     */
    [lastWasBlankSymbol](value: unknown, stream?: 'stderr' | 'stdout'): this;
    /**
     * Logs an assertion failure message if the value is falsy.
     *
     * Works like `console.assert()` but returns the logger for chaining. If the
     * value is truthy, nothing is logged. If falsy, logs an error message with an
     * assertion failure.
     *
     * @param value - The value to test.
     * @param message - Optional message and additional arguments to log.
     */
    assert(value: unknown, ...message: unknown[]): this;
    /**
     * Clears the current line in the terminal.
     *
     * Moves the cursor to the beginning of the line and clears all content. Works
     * in both TTY and non-TTY environments. Useful for clearing progress
     * indicators created with `progress()`.
     *
     * The stream to clear (stderr or stdout) depends on whether the logger is
     * stream-bound.
     */
    clearLine(): this;
    /**
     * Clears the visible terminal screen.
     *
     * Only available on the main logger instance, not on stream-bound instances
     * (`.stderr` or `.stdout`). Resets the log call count and blank line tracking
     * if the output is a TTY.
     *
     * @throws {Error} If called on a stream-bound logger instance
     */
    clearVisible(): this;
    /**
     * Increments and logs a counter for the given label.
     *
     * Each unique label maintains its own counter. Works like `console.count()`.
     *
     * @default 'default'
     *
     * @param label - Optional label for the counter.
     */
    count(label?: string | undefined): this;
    /**
     * Creates a task that logs start and completion messages automatically.
     *
     * Returns a task object with a `run()` method that executes the provided
     * function and logs "Starting task: {name}" before execution and "Completed
     * task: {name}" after completion.
     *
     * @param name - The name of the task.
     *
     * @returns A task object with a `run()` method
     */
    createTask(name: string): Task;
    /**
     * Decreases the indentation level by removing spaces from the prefix.
     *
     * When called on the main logger, affects both stderr and stdout indentation.
     * When called on a stream-bound logger (`.stderr` or `.stdout`), affects only
     * that stream's indentation.
     *
     * @default 2
     */
    dedent(spaces?: number): this;
    /**
     * Displays an object's properties in a formatted way.
     *
     * Works like `console.dir()` with customizable options for depth, colors,
     * etc. Useful for inspecting complex objects.
     *
     * @param obj - The object to display.
     * @param options - Optional formatting options (Node.js inspect options)
     */
    dir(obj: unknown, options?: unknown | undefined): this;
    /**
     * Displays data as XML/HTML in a formatted way.
     *
     * Works like `console.dirxml()`. In Node.js, behaves the same as `dir()`.
     *
     * @param data - The data to display.
     */
    dirxml(...data: unknown[]): this;
    /**
     * Logs a completion message with a success symbol (alias for `success()`).
     *
     * Provides semantic clarity when marking something as "done". Does NOT
     * automatically clear the current line - call `clearLine()` first if needed
     * after using `progress()`.
     */
    done(...args: unknown[]): this;
    /**
     * Logs an error message to stderr.
     *
     * Automatically applies current indentation. All arguments are formatted and
     * logged like `console.error()`.
     */
    error(...args: unknown[]): this;
    /**
     * Logs a newline to stderr only if the last line wasn't already blank.
     *
     * Prevents multiple consecutive blank lines. Useful for adding spacing
     * between sections without creating excessive whitespace.
     */
    errorNewline(): this;
    /**
     * Logs a failure message with a red colored fail symbol.
     *
     * Automatically prefixes the message with `LOG_SYMBOLS.fail` (red ✖). Always
     * outputs to stderr. If the message starts with an existing symbol, it will
     * be stripped and replaced.
     */
    fail(...args: unknown[]): this;
    /**
     * Starts a new indented log group.
     *
     * If a label is provided, it's logged before increasing indentation. Groups
     * can be nested. Each group increases indentation by the `kGroupIndentWidth`
     * (default 2 spaces). Call `groupEnd()` to close.
     *
     * @param label - Optional label to display before the group.
     */
    group(...label: unknown[]): this;
    /**
     * Starts a new collapsed log group (alias for `group()`).
     *
     * In browser consoles, this creates a collapsed group. In Node.js, it behaves
     * identically to `group()`.
     *
     * @param label - Optional label to display before the group.
     */
    groupCollapsed(...label: unknown[]): this;
    /**
     * Ends the current log group and decreases indentation.
     *
     * Must be called once for each `group()` or `groupCollapsed()` call to
     * properly close the group and restore indentation.
     */
    groupEnd(): this;
    /**
     * Increases the indentation level by adding spaces to the prefix.
     *
     * When called on the main logger, affects both stderr and stdout indentation.
     * When called on a stream-bound logger (`.stderr` or `.stdout`), affects only
     * that stream's indentation. Maximum indentation is 1000 spaces.
     *
     * @default 2
     */
    indent(spaces?: number): this;
    /**
     * Logs an informational message with a blue colored info symbol.
     *
     * Automatically prefixes the message with `LOG_SYMBOLS.info` (blue ℹ). Always
     * outputs to stderr. If the message starts with an existing symbol, it will
     * be stripped and replaced.
     */
    info(...args: unknown[]): this;
    /**
     * Logs a message to stdout.
     *
     * Automatically applies current indentation. All arguments are formatted and
     * logged like `console.log()`. This is the primary method for standard
     * output.
     */
    log(...args: unknown[]): this;
    /**
     * Logs a newline to stdout only if the last line wasn't already blank.
     *
     * Prevents multiple consecutive blank lines. Useful for adding spacing
     * between sections without creating excessive whitespace.
     */
    logNewline(): this;
    /**
     * Shows a progress indicator that can be cleared with `clearLine()`.
     *
     * Displays a simple status message with a '∴' prefix. Does not include
     * animation or spinner. Intended to be cleared once the operation completes.
     * The output stream (stderr or stdout) depends on whether the logger is
     * stream-bound.
     *
     * @param text - The progress message to display.
     */
    progress(text: string): this;
    /**
     * Resets all indentation to zero.
     *
     * When called on the main logger, resets both stderr and stdout indentation.
     * When called on a stream-bound logger (`.stderr` or `.stdout`), resets only
     * that stream's indentation.
     */
    resetIndent(): this;
    /**
     * Logs a skip message with a cyan colored skip symbol.
     *
     * Automatically prefixes the message with `LOG_SYMBOLS.skip` (cyan ↻). Always
     * outputs to stderr. If the message starts with an existing symbol, it will
     * be stripped and replaced.
     */
    skip(...args: unknown[]): this;
    /**
     * Logs a main step message with a cyan arrow symbol and blank line before it.
     *
     * Automatically prefixes the message with `LOG_SYMBOLS.step` (cyan →) and
     * adds a blank line before the message unless the last line was already
     * blank. Useful for marking major steps in a process with clear visual
     * separation. Always outputs to stdout. If the message starts with an
     * existing symbol, it will be stripped and replaced.
     *
     * @param msg - The step message to log.
     * @param extras - Additional arguments to log.
     */
    step(msg: string, ...extras: unknown[]): this;
    /**
     * Logs an indented substep message (stateless).
     *
     * Adds a 2-space indent to the message without affecting the logger's
     * indentation state. Useful for showing sub-items under a main step.
     *
     * @param msg - The substep message to log.
     * @param extras - Additional arguments to log.
     */
    substep(msg: string, ...extras: unknown[]): this;
    /**
     * Logs a success message with a green colored success symbol.
     *
     * Automatically prefixes the message with `LOG_SYMBOLS.success` (green ✔).
     * Always outputs to stderr. If the message starts with an existing symbol, it
     * will be stripped and replaced.
     */
    success(...args: unknown[]): this;
    /**
     * Displays data in a table format.
     *
     * Works like `console.table()`. Accepts arrays of objects or objects with
     * nested objects. Optionally specify which properties to include in the
     * table.
     *
     * @param tabularData - The data to display as a table.
     * @param properties - Optional array of property names to include.
     */
    table(tabularData: unknown, properties?: readonly string[] | undefined): this;
    /**
     * Starts a timer for measuring elapsed time.
     *
     * Creates a timer with the given label. Use `timeEnd()` with the same label
     * to stop the timer and log the elapsed time, or use `timeLog()` to check the
     * time without stopping the timer.
     *
     * @default 'default'
     *
     * @param label - Optional label for the timer.
     */
    time(label?: string | undefined): this;
    /**
     * Ends a timer and logs the elapsed time.
     *
     * Logs the duration since `console.time()` or `logger.time()` was called with
     * the same label. The timer is stopped and removed.
     *
     * @default 'default'
     *
     * @param label - Optional label for the timer.
     */
    timeEnd(label?: string | undefined): this;
    /**
     * Logs the current value of a timer without stopping it.
     *
     * Logs the duration since `console.time()` was called with the same label,
     * but keeps the timer running. Can include additional data to log alongside
     * the time.
     *
     * @default 'default'
     *
     * @param label - Optional label for the timer.
     * @param data - Additional data to log with the time.
     */
    timeLog(label?: string | undefined, ...data: unknown[]): this;
    /**
     * Logs a stack trace to the console.
     *
     * Works like `console.trace()`. Shows the call stack leading to where this
     * method was called. Useful for debugging.
     *
     * @param message - Optional message to display with the trace.
     * @param args - Additional arguments to log.
     */
    trace(message?: unknown | undefined, ...args: unknown[]): this;
    /**
     * Logs a warning message with a yellow colored warning symbol.
     *
     * Automatically prefixes the message with `LOG_SYMBOLS.warn` (yellow ⚠).
     * Always outputs to stderr. If the message starts with an existing symbol, it
     * will be stripped and replaced.
     */
    warn(...args: unknown[]): this;
    /**
     * Writes text directly to stdout without a newline or indentation.
     *
     * Useful for progress indicators or custom formatting where you need
     * low-level control. Does not apply any indentation or formatting.
     *
     * @param text - The text to write.
     */
    write(text: string): this;
}
/**
 * Get the default logger instance. Lazily creates the logger to avoid circular
 * dependencies during module initialization. Reuses the same instance across
 * calls.
 *
 * Construction is lazy so that importing this module during early Node.js
 * bootstrap doesn't try to resolve `node:console` before stdout is ready
 * (mirrors the lazy `Console` init inside `Logger` itself).
 *
 * @returns Shared default logger instance
 */
export declare function getDefaultLogger(): Logger;
