/**
 * Tagged, leveled logging for every runtime - the one logger the whole
 * monorepo shares.
 *
 * Import this module instead of constructing package-local console wrappers so
 * log levels, tags, formatting, and browser behavior remain consistent.
 *
 * {@link logger} resolves a tagged {@link Logger} through a synchronous console
 * sink, then upgrades its server-side formatter when `node:util` resolves.
 * Keeping the sink dependency-free prevents browser bundlers from retaining an
 * optional bare import that downstream apps would still have to install.
 * {@link LogLevel} filtering runs through {@link shouldEmit} in per-level
 * wrappers around the platform console or stderr sink.
 *
 * The console fallback writes debug/info to `process.stdout` and warn/error to
 * `process.stderr` when available (Bun `inspect` per argument when
 * `LOG_BUN_CONSOLE_DISABLED` is unset, otherwise `node:util` inspection), or
 * delegates to global `console.*` when process streams are unavailable. Browser hosts omit
 * the `LEVEL` text prefix (devtools show severity) and keep only the `[name]`
 * tag.
 *
 * Env toggles: `LOG_LEVEL` (read per call) and `LOG_BUN_CONSOLE_DISABLED`
 * (read once during factory init).
 *
 * Browser-safe: `process` / `Bun` / `window` / `document` are all reached
 * through `globalThis` and guarded, and `node:util` is imported ONLY on a host
 * that has `process.stderr` - never in a browser, where the specifier is
 * unresolvable - so the module works in any runtime.
 *
 * @module
 */
import { type NameLike } from "./object.ts";
declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
/**
 * Supported severities, lowest to highest: `debug`, `info`, `warn`, `error`.
 * A call below the active threshold is discarded before any string work or
 * sink I/O.
 *
 * The threshold comes from `process.env.LOG_LEVEL` on every call
 * (case-insensitive, default `info` when unset, empty, or unknown) so test
 * runners and embedders can change verbosity after import without restarting
 * the process.
 */
export type LogLevel = (typeof LOG_LEVELS)[number];
/**
 * Dependency-free leveled logger. Standard methods honor `LOG_LEVEL`; `start`
 * and `success` are informational aliases with distinct presentation.
 */
export type Logger = {
    [K in LogLevel]: (...args: any[]) => void;
} & {
    /** Success message emitted at `info` level. */
    success: (...args: any[]) => void;
    /** Start / in-progress message emitted at `info` level. */
    start: (...args: any[]) => void;
};
/** Active threshold from `process.env.LOG_LEVEL`, default {@link DEFAULT_LEVEL}. */
export declare function activeLevel(): LogLevel;
/**
 * Whether a call at `level` would be emitted at the current
 * `process.env.LOG_LEVEL` threshold. Use before building expensive debug
 * payloads.
 *
 * @example
 * if (isLevelEnabled("debug")) {
 *   log.debug("mounts:resolver", { contribution: await heavySnapshot() });
 * }
 */
export declare function isLevelEnabled(level: LogLevel): boolean;
/**
 * Build a tagged logger for a plugin or module.
 *
 * The tag is `[name]` when `loggerName` is a non-empty string, a
 * {@link NameLike} with `name`, or a file / URL path (the basename without
 * extension is used). The console sink prepends `LEVEL [name]` on Node/Bun
 * hosts or `[name]` alone in browsers via {@link createFormatter}.
 *
 * Calls below `process.env.LOG_LEVEL` are dropped by {@link shouldEmit} before
 * the sink formats or writes the line.
 *
 * @example
 * import { log } from "@dbx-tools/shared-core";
 *
 * const logger = log.logger("genie/chat");
 * logger.info("starting");
 * logger.warn("missing optional config", { reason: "no env var" });
 * logger.error("request failed", { error: errorUtils.toError(cause) });
 */
export declare function logger(loggerName: NameLike | string | undefined): Logger;
export {};