@mks2508/better-logger 0.18.2-alpha.1 → 0.18.3

package/dist/Logger.d.ts

@@ -4,7 +4,7 @@
  * Sistema de logging profesional con estilos CSS avanzados, temas adaptativos,
  * badges automáticos, contextos temporales y exportación de datos.
  */
-import type { LogLevel, LogTag, Verbosity, ThemeVariant, BannerType, LoggerConfig, ILogHandler, StyleOptions, Bindings, SerializerFn, HookEvent, HookCallback, MiddlewareFn, TransportTarget, TransportRecord, ILogResourceRef, StackInfo } from './types/index.js';
+import type { LogLevel, LogTag, Verbosity, ThemeVariant, BannerType, LoggerConfig, ILogHandler, StyleOptions, Bindings, SerializerFn, HookEvent, HookCallback, MiddlewareFn, TransportTarget, TransportRecord, ILogResourceRef, StackInfo, Span, SpanAttributes } from './types/index.js';
 import { SerializerRegistry } from './serializers/index.js';
 import { HookManager } from './hooks/index.js';
 import { TransportManager } from './transports/index.js';
@@ -49,37 +49,38 @@ export declare class Logger {
     private hookBridge;
     private logContext;
     private transportBridge;
-    /** Set during success() so log() skips its own dispatch (N2 fix). */
+    /** Fijado por `success()` para que `log()` salte su propio dispatch. */
     private _successTagDispatched;
     private styleManager;
-    /** Whether CLI primitives (step, box, header, etc.) should be shown*/
+    /** Controla si las CLI primitives (step, box, header, ...) deben renderizarse. */
     private _showPrimitives;
     private terminalBridge;
     /**
-     * Active smart-preset reference (set by `preset()`). Typed as `unknown`
-     * to keep the public surface clean; consumed by `createStyledOutput`.
+     * Referencia activa al smart-preset (fijada por `preset()`). Tipada como
+     * `unknown` para mantener limpia la surface pública; la consume
+     * `createStyledOutput`.
      */
     private _activePreset?;
     /**
-     * Name of the active smart-preset. Stored separately so theme-change
-     * detection can re-render without re-running the preset body.
+     * Nombre del smart-preset activo. Se guarda aparte para que la detección
+     * de cambio de tema pueda re-renderizar sin re-ejecutar el body del preset.
      */
     private _activePresetName?;
     /**
-     * Last-applied `customize()` overrides. Stored for later read by
-     * `createStyledOutput`.
+     * Overrides aplicados por el último `customize()`. Se conservan para que
+     * `createStyledOutput` los lea después.
      */
     private _customization?;
     /**
-     * This logger's own context bindings (from child() calls).
-     * Single source of truth for this logger's contribution to the context chain.
+     * Bindings propios de este logger (provenientes de llamadas a `child()`).
+     * Source of truth única de la contribución de este logger a la cadena de contexto.
      * @private
      */
     private _bindings;
     /**
-     * Reference to the parent's merged context record at the time this logger
-     * was created. Together with _bindings, forms the context chain.
-     * Undefined for the root logger.
+     * Referencia al record de contexto mergueado del parent en el momento en
+     * que se creó este logger. Junto con `_bindings`, forma la cadena de
+     * contexto. `undefined` para el logger raíz.
      * @private
      */
     private _parentContextRecord;
@@ -178,86 +179,87 @@ export declare class Logger {
      */
     setBannerType(bannerType: BannerType): void;
     /**
-     * Runs `fn` within an AsyncLocalStorage scope where `bindings` are
-     * merged into the context for all log calls inside `fn`.
+     * Ejecuta `fn` dentro de un scope AsyncLocalStorage donde `bindings` se
+     * merguean al contexto para todas las llamadas de log dentro de `fn`.
      *
-     * Without `fn` (the old setter shape): no-op for backwards compatibility.
-     * Prefer `child()` for persistent bindings or `withContextAsync()` for
-     * async callbacks.
+     * Sin `fn` (el shape legacy de setter): no-op por backwards compatibility.
+     * Preferir `child()` para bindings persistentes o `withContextAsync()`
+     * para callbacks async.
      *
-     * @param bindings - Key-value pairs to attach for the duration of `fn`
-     * @param fn - Optional synchronous function to run with scoped bindings
-     * @returns The return value of `fn`, or undefined if no fn provided
+     * @param bindings - Pares key-value a adjuntar durante la ejecución de `fn`
+     * @param fn - Función sincrónica opcional a ejecutar con los bindings en scope
+     * @returns El valor de retorno de `fn`, o `undefined` si no se pasa `fn`
      *
      * @example
-     * // Scoped synchronous callback
+     * // Callback sincrónico scoped
      * logger.withContext({ requestId: 'r-42' }, () => {
-     *   doWork(); // logs inside see requestId in attributes
+     *   doWork(); // los logs de aquí ven requestId en attributes
      * });
      *
      * @example
-     * // Persistent binding: use child()
+     * // Binding persistente: usar child()
      * const reqLog = logger.child({ requestId: 'r-42' });
-     * reqLog.info('handling request'); // attributes include requestId
+     * reqLog.info('handling request'); // attributes incluye requestId
      *
-     * @see {@link child} for an immutable copy with the merged context
-     * @see {@link withContextAsync} for async callback variant
+     * @see {@link child} para una copia inmutable con el contexto mergueado
+     * @see {@link withContextAsync} para la variante con callback async
      */
     withContext<R>(bindings: Record<string, unknown>, fn?: () => R): R | undefined;
     /**
-     * Async variant of `withContext`. Runs `fn` within an AsyncLocalStorage
-     * scope so bindings are available to all async log calls inside `fn`.
+     * Variante async de `withContext`. Ejecuta `fn` dentro de un scope
+     * AsyncLocalStorage para que los bindings estén disponibles a todas las
+     * llamadas de log async dentro de `fn`.
      *
-     * @param bindings - Key-value pairs to attach for the duration of `fn`
-     * @param fn - Async function to run with the scoped bindings
-     * @returns The return value of `fn`
+     * @param bindings - Pares key-value a adjuntar durante la ejecución de `fn`
+     * @param fn - Función async a ejecutar con los bindings en scope
+     * @returns El valor de retorno de `fn`
      *
      * @example
      * await logger.withContextAsync({ requestId: 'r-42' }, async () => {
-     *   await fetchData(); // logs inside see requestId in attributes
+     *   await fetchData(); // los logs de aquí ven requestId en attributes
      * });
      *
-     * @see {@link child} for a persistent child logger
-     * @see {@link withContext} for synchronous callback variant
+     * @see {@link child} para un child logger persistente
+     * @see {@link withContext} para la variante con callback sincrónico
      */
     withContextAsync<R>(bindings: Record<string, unknown>, fn: () => Promise<R>): Promise<R>;
     /**
-     * Returns an immutable copy of this logger with the extra context bound.
-     * Future calls on the child emit with the merged context, without
-     * mutating the parent — the canonical MDC pattern.
+     * Devuelve una copia inmutable de este logger con el contexto extra bound.
+     * Las llamadas futuras sobre el child emiten con el contexto mergueado,
+     * sin mutar al parent — el patrón canónico de MDC.
      *
-     * @param extra - Key-value pairs to attach (requestId, userId, ...)
-     * @returns A new Logger with merged context
+     * @param extra - Pares key-value a adjuntar (requestId, userId, ...)
+     * @returns Un nuevo Logger con el contexto mergueado
      *
      * @example
      * const reqLog = logger.child({ requestId: req.id });
-     * reqLog.info('start');     // emits attributes: { requestId }
-     * logger.info('unrelated'); // NOT affected — parent's context untouched
+     * reqLog.info('start');     // emite attributes: { requestId }
+     * logger.info('unrelated'); // NO afectado — el contexto del parent queda intacto
      *
      */
     child(extra: Record<string, unknown>): Logger;
     /**
-     * Drops every key from the bound context. After this call, emitted
-     * records no longer carry `attributes` until {@link withContext} or
-     * {@link child} re-establish one.
+     * Descarta todas las keys del contexto bound. Tras esta llamada, los
+     * records emitidos dejan de llevar `attributes` hasta que
+     * {@link withContext} o {@link child} restablezcan uno.
      *
-     * @returns The same logger instance, now context-free
+     * @returns La misma instancia del logger, ahora sin contexto
      */
     clearContext(): this;
     /**
-     * Snapshot of the bound context. Returned object is a shallow copy:
-     * mutating it does NOT affect what subsequent log calls emit.
+     * Snapshot del contexto bound. El objeto devuelto es una shallow copy:
+     * mutarlo NO afecta lo que emiten las llamadas de log posteriores.
      *
-     * @returns A read-only snapshot of the current context
+     * @returns Un snapshot read-only del contexto actual
      */
     getContext(): Readonly<Record<string, unknown>>;
     /**
-     * Updates the default OTel resource (service.name, version, env).
-     * Persisted into every emitted record's `resource` field unless the
-     * record itself overrides it.
+     * Actualiza el resource OTel por defecto (service.name, version, env).
+     * Se persiste en el campo `resource` de cada record emitido, salvo que
+     * el propio record lo override.
      *
-     * @param resource - Partial OTel resource to merge into the current one
-     * @returns The same logger instance, for chaining
+     * @param resource - Resource OTel parcial a merguear con el actual
+     * @returns La misma instancia del logger, para chaining
      *
      * @example
      * logger.setResource({ 'service.name': 'api', 'service.version': '1.2.3' });
@@ -274,20 +276,15 @@ export declare class Logger {
      */
     resetConfig(): void;
     /**
-     * Método de limpieza para eliminar listeners y liberar recursos
+     * Método de limpieza para eliminar listeners y liberar recursos.
      *
-     * @example
-     * // Antes de cerrar la aplicación
-     * logger.cleanup();
-     *
-     */
-    /**
-     * Tears down every resource held by this Logger. Safe to call multiple
-     * times. Fixed in 5.1.0 to fully drain transports + clear timers +
-     * drop the legacy handler list + reset group depth + clear context.
+     * Vacía los transports (drain), limpia timers, suelta la lista de
+     * handlers legacy, resetea el group depth y limpia el context.
+     * Seguro de invocar múltiples veces.
      *
      * @example
-     * await logger.cleanup(); // before process exit / hot reload
+     * // Antes de cerrar la aplicación
+     * await logger.cleanup();
      *
      */
     cleanup(): Promise<void>;
@@ -303,7 +300,7 @@ export declare class Logger {
      * logger.preset('glassmorphism'); // Efectos de blur modernos
      * logger.preset('minimal');       // Minimalista y elegante
      * logger.preset('debug');         // Modo desarrollo detallado
-     * logger.preset('production');    // Optimizado para producción
+     * logger.preset('production');    // Enfocado en producción
      *
      */
     preset(name: string): void;
@@ -407,8 +404,59 @@ export declare class Logger {
      *
      */
     clearBadges(): this;
+    /**
+     * Crea un logger scoped para un componente o módulo del dominio.
+     *
+     * El `ComponentLogger` resultante prepends un badge `[name]` a cada
+     * mensaje y comparte configuración, transports y hooks con el logger
+     * padre. Útil para trazar el origen de los logs en apps con muchos
+     * módulos (Auth, DB, Cache, ...).
+     *
+     * @param {string} name - Nombre del componente que aparecerá como badge
+     * @returns {ComponentLogger} Logger scoped para el componente
+     *
+     * @example
+     * const auth = logger.component('Auth');
+     * auth.info('Validando token');   // [Auth] Validando token
+     * auth.success('Token válido');
+     *
+     * @see {@link api} para loggers de endpoints REST/GraphQL
+     * @see {@link scope} para un scope genérico sin badge de componente
+     */
     component(name: string): ComponentLogger;
+    /**
+     * Crea un logger scoped para un endpoint o surface de API.
+     *
+     * Como `component()` pero con styling orientado a APIs (badge `[API]`
+     * por defecto más el nombre del sub-scope). Útil para distinguir
+     * tráfico REST vs GraphQL vs WebSocket en los logs.
+     *
+     * @param {string} name - Nombre de la API o surface (p.ej. `'REST'`, `'GraphQL'`)
+     * @returns {APILogger} Logger scoped para la API
+     *
+     * @example
+     * const rest = logger.api('REST');
+     * rest.info('GET /users/42');     // [API] [REST] GET /users/42
+     *
+     * @see {@link component} para loggers de componentes de dominio
+     */
     api(name: string): APILogger;
+    /**
+     * Crea un logger scoped genérico con un prefijo.
+     *
+     * Variante minimal de `component()` / `api()`: solo aplica un prefijo
+     * de scope sin badges ni styling especial. Útil para sub-módulos que
+     * no encajan en las categorías de `component`/`api`.
+     *
+     * @param {string} name - Texto del prefijo de scope
+     * @returns {ScopedLogger} Logger con el scope aplicado
+     *
+     * @example
+     * const db = logger.scope('db');
+     * db.info('Pool conectado');      // [db] Pool conectado
+     *
+     * @see {@link component} y {@link api} para variantes con badges
+     */
     scope(name: string): ScopedLogger;
     /**
      * Personalización simple con configuración mínima
@@ -600,14 +648,18 @@ export declare class Logger {
      */
     removeTransport(id: string): boolean;
     /**
-     * Fuerza el flush de todos los transports
+     * Fuerza el flush de todos los transports. Antes de flushear, cierra los
+     * spans aún abiertos (`incomplete: true`) y los encola para export — un
+     * span abierto nunca se tira en un flush.
      *
      * @returns Promise que resuelve cuando todos los buffers están vaciados
      *
      */
     flushTransports(): Promise<void>;
     /**
-     * Cierra todos los transports
+     * Cierra todos los transports. Como en {@link flushTransports}, primero
+     * fuerza el cierre de los spans abiertos para que viajen en el flush
+     * final del close.
      *
      * @returns Promise que resuelve cuando todos están cerrados
      *
@@ -627,37 +679,48 @@ export declare class Logger {
      */
     private shouldLog;
     /**
-     * Builds and dispatches a `TransportRecord` to the {@link TransportManager}
-     * (no-op if no transports are registered). Shared by every log path —
-     * `log()`, `success()`, and visual methods like `table()` / `group()` /
-     * `time()` — so all emissions hit the same transport pipeline.
+     * Tag pendiente de inyectar en el siguiente `TransportRecord` emitido
+     * por `log()`. Lo fijan `success()` y `logWithBindingsAndTag()` antes
+     * de delegar; `log()` lo consume y lo resetea a `undefined`.
      *
-     * @param level - The canonical log level (trace/debug/info/warn/error/critical)
-     * @param message - Final, post-hook message text
-     * @param prefix - Effective prefix (global + scope)
-     * @param stackInfo - Optional caller location
-     * @param extra - Optional fields to merge into the record (e.g. `{ tag: 'success' }`)
+     * @internal
      */
     protected _dispatchTag: string | undefined;
     /**
-     * Computes the fully-merged context for this logger.
+     * Computa el contexto completamente mergueado para este logger.
      *
-     * The context chain is built at child-creation time: each child stores
-     * its parent's fully-merged context (at that moment) as _parentContextRecord.
-     * This means _parentContextRecord already contains all ancestors' bindings
-     * in the correct precedence order (root first, nearest child last).
+     * La cadena de contexto se construye en el momento de crear el child:
+     * cada child almacena el contexto fully-merged de su parent (en ese
+     * instante) como `_parentContextRecord`. Esto implica que
+     * `_parentContextRecord` ya contiene los bindings de todos los ancestros
+     * en el orden de precedencia correcto (root primero, child más cercano al final).
      *
-     * Merge order (later wins):
-     *   1. _parentContextRecord — parent's merged context snapshot at creation time
-     *   2. _bindings            — this logger's own bindings (child() calls)
-     *   3. ALS store            — withContext/withContextAsync scope (highest priority)
+     * Orden de merge (gana el último):
+     *   1. _parentContextRecord — snapshot del contexto mergueado del parent en la creación
+     *   2. _bindings            — bindings propios de este logger (llamadas a `child()`)
+     *   3. ALS store            — scope de `withContext`/`withContextAsync` (prioridad máxima)
      *
      * @internal
-     * @returns The merged context record
+     * @returns El record de contexto mergueado
      */
     private _getMergedContext;
-    /** @internal Exposes base merged context (no ALS) to LogContext child factory closure. */
+    /** @internal Expone el contexto base mergueado (sin ALS) a la closure de la child factory de LogContext. */
     _captureMergedContext(): Record<string, unknown>;
+    /**
+     * Construye y despacha un `TransportRecord` al {@link TransportManager}
+     * (no-op si no hay transports registrados). Lo comparten todos los
+     * caminos de log — `log()`, `success()` y los métodos visuales como
+     * `table()` / `group()` / `time()` — para que toda emisión atraviese
+     * el mismo pipeline de transports.
+     *
+     * @protected
+     * @param {LogLevel} level - Nivel canónico (trace/debug/info/warn/error/critical)
+     * @param {string} message - Mensaje final, post-hook
+     * @param {string | undefined} prefix - Prefijo efectivo (global + scope)
+     * @param {StackInfo | null} stackInfo - Ubicación del caller, opcional
+     * @param {Partial<TransportRecord>} [extra] - Campos extra a mergear en el record
+     *        (p.ej. `{ tag: 'success' }` o `attributes` adicionales)
+     */
     protected dispatchToTransports(level: LogLevel, message: string, prefix: string | undefined, stackInfo: StackInfo | null, extra?: Partial<TransportRecord>): void;
     /**
      * Obtiene el prefijo efectivo (global + scope)
@@ -666,50 +729,78 @@ export declare class Logger {
      */
     private getEffectivePrefix;
     /**
-     * Método central de logging. Awaits the `beforeLog` hook pipeline
-     * synchronously (so redactions / enrichments are reflected in the
-     * emitted message before console + transport dispatch).
+     * Método central de logging. Espera el hook pipeline `beforeLog`
+     * antes de despachar a consola y transports, para que redacciones
+     * o enriquecimientos (PII, correlation IDs) se reflejen en el
+     * mensaje emitido.
+     *
+     * Los callers fire-and-forget (p.ej. `logger.info(...)` sin `await`)
+     * siguen funcionando: el `Promise<void>` resultante se descarta.
+     * Se recomienda `await` cuando los hooks `beforeLog` mutan `message`.
      *
-     * Fire-and-forget callers (e.g. `logger.info(...)` without `await`)
-     * still work — the resulting `Promise<void>` is dropped on the floor.
-     * Awaiting is recommended when `beforeLog` hooks mutate `message`
-     * (e.g. PII redaction, correlation IDs).
+     * El tag opcional (`TransportRecord.tag`) NO se pasa como argumento:
+     * se establece vía `_dispatchTag` (ver `success()` y
+     * {@link logWithBindingsAndTag}) antes de invocar este método.
      *
      * @protected
-     * @param level - Nivel del log
-     * @param args - Argumentos a loggear
-     * @returns Promise that resolves once the record has been dispatched
+     * @param {LogLevel} level - Nivel del log
+     * @param {unknown[]} args - Argumentos a loggear (mensaje + datos)
+     * @returns {Promise<void>} Promesa que resuelve al completar el dispatch
      *
      */
+    protected log(level: LogLevel, ...args: unknown[]): Promise<void>;
     /**
-     * Protected logging method. Awaits the `beforeLog` hook pipeline
-     * synchronously (so redactions / enrichments are reflected in the
-     * emitted message before console + transport dispatch).
+     * Emite un log aplicando bindings (badges, scope) al prefijo del
+     * mensaje antes de delegar en {@link Logger.log}.
      *
-     * Fire-and-forget callers (e.g. `logger.info(...)` without `await`)
-     * still work — the resulting `Promise<void>` is dropped on the floor.
-     * Awaiting is recommended when `beforeLog` hooks mutate `message`
-     * (e.g. PII redaction, correlation IDs).
+     * No es API pública de consumo: existe para que `ScopedLogger`
+     * (`component()` / `api()` / `scope()`) pueda reutilizar el pipeline
+     * central de `log()` sin duplicar la lógica de styling/badges.
      *
-     * @protected
-     * @param level - Nivel del log
-     * @param args - Argumentos a loggear
-     * @param tag - Optional tag forwarded to `dispatchToTransports` as
-     *              `TransportRecord.tag` (e.g. `'success'` for success records).
-     * @returns Promise that resolves once the record has been dispatched
+     * @internal
+     * @param {Bindings} bindings - Bindings de scope (badges, scope name, ...)
+     * @param {LogLevel} level - Nivel de log
+     * @param {unknown[]} args - Argumentos a loggear
+     * @returns {Promise<void>} Promesa del dispatch
      *
+     * @see {@link logWithBindingsAndTag} para la variante con `tag`
      */
-    protected log(level: LogLevel, ...args: unknown[]): Promise<void>;
     logWithBindings(bindings: Bindings, level: LogLevel, ...args: unknown[]): Promise<void>;
     /**
-     * Like `logWithBindings()` but sets _dispatchTag first so that
-     * `log()` dispatches with the tag. Used by ScopedLogger.success()
-     * to propagate tag:'success' through the normal log() pipeline.
+     * Como {@link logWithBindings} pero fija `_dispatchTag` antes de
+     * delegar, para que `log()` despache el `TransportRecord` con el
+     * tag indicado. Lo usa `ScopedLogger.success()` para propagar
+     * `tag: 'success'` a través del pipeline normal de `log()`.
+     *
+     * @internal
+     * @param {Bindings} bindings - Bindings de scope (badges, scope name, ...)
+     * @param {LogLevel} level - Nivel de log
+     * @param {LogTag} tag - Tag a inyectar en el `TransportRecord`
+     * @param {unknown[]} args - Argumentos a loggear
+     * @returns {Promise<void>} Promesa del dispatch
      */
     logWithBindingsAndTag(bindings: Bindings, level: LogLevel, tag: LogTag, ...args: unknown[]): Promise<void>;
+    /**
+     * Registra mensajes de debug (nivel más verboso junto a `trace`).
+     * Pensado para diagnóstico de desarrollo: valores intermedios, flags
+     * de control flow, estado interno. Devuelve `Promise<void>`.
+     *
+     * Filtrado por defecto cuando `verbosity > 'debug'` (ver `setVerbosity`).
+     *
+     * @param {unknown[]} args - Mensaje + datos a inspeccionar
+     * @returns {Promise<void>} Promesa del dispatch
+     *
+     * @example
+     * logger.debug('Estado interno:', { conn, queueSize });
+     * logger.debug('Entrando en branch X');
+     *
+     * @see {@link trace} para diagnósticos aún más granulares
+     * @see {@link setVerbosity} para controlar el nivel mínimo visible
+     */
     debug(...args: unknown[]): Promise<void>;
     /**
-     * Registra mensajes informativos. Devuelve `Promise<void>` desde 5.1.0.
+     * Registra mensajes informativos. El `await` retorna cuando el hook
+     * `beforeLog` y el dispatch a transports han terminado.
      *
      * @param args - Mensajes y datos informativos
      *
@@ -720,14 +811,14 @@ export declare class Logger {
      */
     info(...args: unknown[]): Promise<void>;
     /**
-     * Registra mensajes de advertencia. Devuelve `Promise<void>` desde 5.1.0.
+     * Registra mensajes de advertencia.
      *
      * @param args - Mensajes de advertencia
      *
      */
     warn(...args: unknown[]): Promise<void>;
     /**
-     * Registra mensajes de error. Devuelve `Promise<void>` desde 5.1.0.
+     * Registra mensajes de error.
      *
      * @param args - Mensaje de error y stack traces
      *
@@ -760,7 +851,7 @@ export declare class Logger {
      */
     trace(...args: unknown[]): void;
     /**
-     * Registra errores críticos (prioridad más alta). Devuelve `Promise<void>` desde 5.1.0.
+     * Registra errores críticos (prioridad más alta).
      *
      * @param args - Errores críticos del sistema
      *
@@ -769,6 +860,98 @@ export declare class Logger {
      *
      */
     critical(...args: unknown[]): Promise<void>;
+    /**
+     * Emite un **point-span**: un span con `start = end` para completion
+     * signals y eventos puntuales (una operación instantánea, un hito).
+     * No registra contexto activo ni puede leakear — se exporta de inmediato.
+     *
+     * El nombre `event` (y no `trace`) es deliberado: `trace` es un log level
+     * (el -1) y está reservado.
+     *
+     * @param {string} name - Nombre del evento (`job.completed`, `cache.flushed`, ...).
+     * @param {SpanAttributes} [attributes] - Attributes del span.
+     *
+     * @example
+     * logger.event('build.finished', { status: 'ok', durationMs: 4200 });
+     *
+     * @see {@link span} para intervalos con work-block
+     * @see {@link startSpan} para intervalos externally-ended
+     */
+    event(name: string, attributes?: SpanAttributes): void;
+    /**
+     * Ejecuta `fn` dentro de un span de intervalo. El span queda **activo en
+     * el AsyncLocalStorage del módulo** mientras `fn` corre: los logs emitidos
+     * dentro heredan su `traceId`/`spanId`, y los spans hijos lo toman como
+     * `parentSpanId`.
+     *
+     * Al retornar `fn` el span se cierra automáticamente; si `fn` lanza, se
+     * marca `status {code: 2}` con el mensaje del error (`fail`) y la
+     * excepción se relanza intacta.
+     *
+     * @typeParam T - Tipo resuelto por `fn`.
+     * @param {string} name - Nombre de la operación.
+     * @param {(s: Span) => T | Promise<T>} fn - Work-block a medir.
+     * @returns {Promise<T>} Lo que resuelve `fn`.
+     * @throws {unknown} Relanza cualquier error de `fn` tras marcar el span fallido.
+     *
+     * @example
+     * await logger.span('db.migrate', { target: 'v2' }, async (s) => {
+     *   await runMigrations();
+     *   s.set('tables', 14);
+     * });
+     *
+     * @see {@link event} para point-spans
+     * @see {@link startSpan} para spans externally-ended (poll/callback)
+     */
+    span<T>(name: string, fn: (s: Span) => T | Promise<T>): Promise<T>;
+    span<T>(name: string, attributes: SpanAttributes, fn: (s: Span) => T | Promise<T>): Promise<T>;
+    /**
+     * Inicia un span de intervalo **externally-ended**: devuelve el handle y
+     * NO fija contexto ALS (el cierre ocurre fuera del bloque léxico — p.ej.
+     * un `cli.spawn` que se cierra desde un poll o callback externo).
+     *
+     * Si el span no se cierra antes de `flushTransports()` / shutdown, el
+     * flush lo fuerza a cerrar con `incomplete: true` y lo exporta — nunca
+     * se tira.
+     *
+     * @param {string} name - Nombre de la operación.
+     * @param {SpanAttributes} [attributes] - Attributes iniciales.
+     * @returns {Span} Handle con `set`/`end`/`fail` y los ids del span.
+     *
+     * @example
+     * const s = logger.startSpan('spawn.build', { cmd: 'make' });
+     * proc.on('exit', code => {
+     *   if (code === 0) s.end({ exitCode: code });
+     *   else s.fail(new Error(`exit ${code}`));
+     * });
+     *
+     * @see {@link span} para el caso con work-block
+     */
+    startSpan(name: string, attributes?: SpanAttributes): Span;
+    /**
+     * Scope por defecto de los spans emitidos por este logger (el
+     * `globalPrefix`, o `'root'`).
+     * @internal
+     */
+    _spanScopeName(): string;
+    /**
+     * Emite un point-span con scope explícito. Lo consume
+     * {@link ScopedLogger.event}, que pasa su scope compuesto.
+     * @internal
+     */
+    _emitSpanEvent(name: string, attributes: SpanAttributes | undefined, scope: string): void;
+    /**
+     * Crea un span externally-ended con scope explícito. Lo consume
+     * {@link ScopedLogger.startSpan}.
+     * @internal
+     */
+    _startSpan(name: string, attributes: SpanAttributes | undefined, scope: string): Span;
+    /**
+     * Corre `fn` dentro de un span activo en el ALS con scope explícito.
+     * Lo consume {@link ScopedLogger.span}.
+     * @internal
+     */
+    _runSpan<T>(name: string, attributes: SpanAttributes | undefined, scope: string, fn: (s: Span) => T | Promise<T>): Promise<T>;
     /**
      * Muestra datos en formato de tabla. Pasa por la pipeline completa
      * (outputMode-respecting writeOutput + transports + hooks).
@@ -824,7 +1007,7 @@ export declare class Logger {
      * Finaliza un temporizador y muestra el tiempo transcurrido
      *
      * @param {string} label - Etiqueta del temporizador a finalizar
-     * @returns {number} Elapsed milliseconds, or -1 if timer not found
+     * @returns {number} Milisegundos transcurridos, o `-1` si no se encuentra el timer
      *
      * @example
      * logger.time('consulta-db');
@@ -877,11 +1060,11 @@ export declare class Logger {
      */
     logAnimated(message: string, duration?: number): void;
     /**
-     * Displays a step progress indicator in the terminal
+     * Muestra un indicador de progreso de pasos en la terminal
      *
-     * @param {number} current - Current step number
-     * @param {number} total - Total number of steps
-     * @param {string} message - Step description
+     * @param {number} current - Número de paso actual
+     * @param {number} total - Número total de pasos
+     * @param {string} message - Descripción del paso
      *
      * @example
      * logger.step(1, 5, 'Analyzing repository...');
@@ -890,10 +1073,10 @@ export declare class Logger {
      */
     step(current: number, total: number, message: string): void;
     /**
-     * Displays a styled header with optional subtitle
+     * Muestra un header con estilo y subtítulo opcional
      *
-     * @param {string} title - Main title text
-     * @param {string} subtitle - Optional subtitle (rendered dimmed)
+     * @param {string} title - Texto del título principal
+     * @param {string} subtitle - Subtítulo opcional (se renderiza atenuado)
      *
      * @example
      * logger.header('Commit Wizard', 'v2.0.0');
@@ -901,7 +1084,7 @@ export declare class Logger {
      */
     header(title: string, subtitle?: string): void;
     /**
-     * Displays a horizontal divider line
+     * Muestra una línea divisoria horizontal
      *
      * @example
      * logger.divider();
@@ -909,7 +1092,7 @@ export declare class Logger {
      */
     divider(): void;
     /**
-     * Outputs a blank line
+     * Emite una línea en blanco
      *
      * @example
      * logger.blank();
@@ -917,10 +1100,10 @@ export declare class Logger {
      */
     blank(): void;
     /**
-     * Renders content inside a bordered box
+     * Renderiza contenido dentro de un box con borde
      *
-     * @param {string} content - Content string (may contain newlines)
-     * @param {IBoxOptions} options - Box rendering options
+     * @param {string} content - String de contenido (puede contener newlines)
+     * @param {IBoxOptions} options - Opciones de renderizado del box
      *
      * @example
      * logger.box('3 commits generated\nProvider: Groq', { title: 'Done', borderColor: '#00ff00' });
@@ -928,11 +1111,11 @@ export declare class Logger {
      */
     box(content: string, options?: IBoxOptions): void;
     /**
-     * Renders an array of objects as a formatted ASCII table.
-     * Note: This is distinct from the existing table() method which uses console.table.
+     * Renderiza un array de objetos como una tabla ASCII formateada.
+     * Distinto del método `table()` existente, que usa `console.table`.
      *
-     * @param {Record<string, unknown>[]} rows - Array of row objects
-     * @param {ITableOptions} options - Table rendering options
+     * @param {Record<string, unknown>[]} rows - Array de objetos fila
+     * @param {ITableOptions} options - Opciones de renderizado de la tabla
      *
      * @example
      * logger.cliTable([
@@ -943,11 +1126,11 @@ export declare class Logger {
      */
     cliTable(rows: Record<string, unknown>[], options?: ITableOptions): void;
     /**
-     * Creates a spinner handle for showing progress during async operations.
-     * Returns a NoopSpinner in non-TTY environments.
+     * Crea un handle de spinner para mostrar progreso durante operaciones async.
+     * Devuelve un `NoopSpinner` en entornos non-TTY.
      *
-     * @param {string} message - Initial spinner text
-     * @returns {ISpinnerHandle} Spinner controller
+     * @param {string} message - Texto inicial del spinner
+     * @returns {ISpinnerHandle} Controller del spinner
      *
      * @example
      * const s = logger.spinner('Analyzing repository...');
@@ -958,30 +1141,31 @@ export declare class Logger {
      */
     spinner(message: string): ISpinnerHandle;
     /**
-     * Sets the CLI verbosity level, controlling both log verbosity and primitive visibility
+     * Fija el nivel de verbosidad del CLI, controlando a la vez la verbosidad
+     * de logs y la visibilidad de las primitives
      *
-     * @param {CLILogLevel} level - CLI log level
+     * @param {CLILogLevel} level - Nivel de log del CLI
      *
      * @example
-     * logger.setCLILevel('quiet');   // Only errors, no CLI primitives
-     * logger.setCLILevel('verbose'); // Debug logs + all CLI primitives
+     * logger.setCLILevel('quiet');   // Solo errors, sin CLI primitives
+     * logger.setCLILevel('verbose'); // Debug logs + todas las CLI primitives
      *
      */
     setCLILevel(level: CLILogLevel): void;
     /**
-     * Returns the current CLI log level
-     * @returns {CLILogLevel} Current CLI log level
+     * Devuelve el nivel de log del CLI actual
+     * @returns {CLILogLevel} Nivel de log del CLI actual
      */
     get cliLevel(): CLILogLevel;
     /**
-     * Writes formatted output to the configured destination.
-     * Respects outputMode configuration for console, silent, or custom output.
+     * Escribe output formateado al destino configurado.
+     * Respeta la configuración `outputMode` para output a consola, silencioso o custom.
      *
      * @private
-     * @param {string} message - Formatted log message
-     * @param {LogLevel} level - Log level
-     * @param {string[]} styles - CSS styles for browser console
-     * @param {unknown[]} additionalArgs - Additional arguments to log
+     * @param {string} message - Mensaje de log formateado
+     * @param {LogLevel} level - Nivel de log
+     * @param {string[]} styles - Estilos CSS para la consola del navegador
+     * @param {unknown[]} additionalArgs - Argumentos adicionales a loggear
      */
     private writeOutput;
     /**
@@ -1005,15 +1189,16 @@ export declare class Logger {
     cli(command: string): Promise<void>;
 }
 /**
- * Resets the default singleton. Clears the cached instance so the next call
- * to `getDefaultLogger()` rebuilds it from defaults. Useful for tests and
- * hot reload scenarios.
+ * Resetea el singleton por defecto. Limpia la instancia cacheada para que la
+ * próxima llamada a `getDefaultLogger()` la reconstruya desde defaults. Útil
+ * para tests y escenarios de hot reload.
  *
  */
 export declare function resetDefaultLogger(): void;
 /**
  * Lazy default export — every property access defers to `getDefaultLogger()`.
- * Side-effect-free at module import (BUG-N11).
+ * Sin side-effects al importar el módulo (la primera llamada al singleton
+ * se produce en el primer acceso a una propiedad, no en el `import`).
  *
  * @example
  * import logger from 'better-logger';
@@ -1021,6 +1206,16 @@ export declare function resetDefaultLogger(): void;
  */
 declare const loggerProxy: Logger;
 export default loggerProxy;
+/**
+ * Resuelve los argumentos del overload `span(name, fn?)` /
+ * `span(name, attributes, fn)` a `{ attributes, fn }`.
+ *
+ * @internal Compartido con `ScopedLogger.span`; no es API pública.
+ */
+export declare function resolveSpanArgs<T>(fnOrAttributes: ((s: Span) => T | Promise<T>) | SpanAttributes, maybeFn?: (s: Span) => T | Promise<T>): {
+    attributes: SpanAttributes | undefined;
+    fn: (s: Span) => T | Promise<T>;
+};
 /**
  * Métodos individuales exportados para conveniencia
  * @description Todos los métodos están correctamente enlazados al singleton lazy
@@ -1037,6 +1232,10 @@ export declare const group: (label: string, collapsed?: boolean) => void;
 export declare const groupEnd: () => void;
 export declare const time: (label: string) => void;
 export declare const timeEnd: (label: string) => number;
+export declare const event: (name: string, attributes?: SpanAttributes) => void;
+export declare const startSpan: (name: string, attributes?: SpanAttributes) => Span;
+export declare function span<T>(name: string, fn: (s: Span) => T | Promise<T>): Promise<T>;
+export declare function span<T>(name: string, attributes: SpanAttributes, fn: (s: Span) => T | Promise<T>): Promise<T>;
 export declare const setGlobalPrefix: (prefix: string) => void;
 export declare const setVerbosity: (level: Verbosity) => void;
 export declare const addHandler: (handler: ILogHandler) => void;