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

package/dist/index.cjs

@@ -2,24 +2,64 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_core = require("./chunks/core-Dzz7agGa.cjs");
-const require_transports = require("./chunks/transports-COPWmlF1.cjs");
-const require_utils = require("./chunks/utils-BqlFYocD.cjs");
-const require_styling = require("./chunks/styling-Cg5saQ46.cjs");
-const require_environment_detector = require("./chunks/environment-detector-Cnn6wr6O.cjs");
-const require_spinner = require("./chunks/spinner-DNvxbM9a.cjs");
-const require_LogContext = require("./chunks/LogContext-L7HzynFw.cjs");
-const require_HookBridge = require("./chunks/HookBridge-CiRfR67f.cjs");
-const require_SerializerBridge = require("./chunks/SerializerBridge-BaOQOb8q.cjs");
-const require_server_fallback = require("./chunks/server-fallback-BUKjdLS7.cjs");
-const require_StyleManager = require("./chunks/StyleManager-CIpd6wbO.cjs");
+const require_core = require("./chunks/core-CqS_UBzJ.cjs");
+const require_transports = require("./chunks/transports-BZ-Mc2IT.cjs");
+const require_utils = require("./chunks/utils-W_cxqriN.cjs");
+const require_styling = require("./chunks/styling-Cel2wPRy.cjs");
+const require_environment_detector = require("./chunks/environment-detector-D-tHkKWA.cjs");
+const require_spinner = require("./chunks/spinner-BHyYEXsM.cjs");
+const require_LogContext = require("./chunks/LogContext-DZasm_P5.cjs");
+const require_HookBridge = require("./chunks/HookBridge-C-AvXmPD.cjs");
+const require_SerializerBridge = require("./chunks/SerializerBridge-C4a9Z37F.cjs");
+const require_server_fallback = require("./chunks/server-fallback-CaCPjWby.cjs");
+const require_StyleManager = require("./chunks/StyleManager-DQ6UNRB-.cjs");
 //#region src/ScopedLogger.ts
+/**
+* Logger prefijado por un scope nominal. Mantiene su propio stack de badges
+* y contextos y delega el envío de mensajes al {@link Logger} padre a través
+* de bindings (`{ scope, badges }`).
+*
+* Es la base de la jerarquía temática: {@link APILogger} y
+* {@link ComponentLogger} extienden de ella, y {@link ContextLogger} la
+* consume para apilar/subdesapilar sub-prefijos en el scope.
+*
+* No se construye directamente: se obtiene con `logger.scope('name')`.
+*
+* @example
+* // El factory method del Logger raíz devuelve un ScopedLogger
+* import logger from '@mks2508/better-logger';
+*
+* const http = logger.scope('HTTP');
+* http.badge('OUTBOUND').info('Request enviada');
+* // salida: [HTTP] [OUTBOUND] Request enviada
+*
+* @example
+* // Anidar contextos dentro de un scope (el prefijo se compone con ':')
+* const retry = http.context('retry');
+* retry.run(() => http.warn('Reintentando petición'));
+* // salida: [HTTP:retry] Reintentando petición
+*
+* @see {@link Logger.scope}
+* @see {@link APILogger}
+* @see {@link ComponentLogger}
+* @see {@link ContextLogger}
+*/
 var ScopedLogger = class {
 	parent;
 	scopeName;
 	badgeList = [];
 	contextStack = [];
 	_timers;
+	/**
+	* Construye un ScopedLogger vinculado a un {@link Logger} padre.
+	*
+	* Los clientes no deben llamar a este constructor directamente: usen
+	* `logger.scope(name)`, que configura correctamente la instancia.
+	*
+	* @param {Logger} parent - Logger raíz al que se delegan los mensajes.
+	* @param {string} scopeName - Etiqueta del scope; se renderiza como
+	*   prefijo `[scopeName]` en cada línea.
+	*/
 	constructor(parent, scopeName) {
 		this.parent = parent;
 		this.scopeName = scopeName;
@@ -38,31 +78,125 @@ var ScopedLogger = class {
 		if (this.contextStack.length === 0) return this.scopeName;
 		return [this.scopeName, ...this.contextStack].join(":");
 	}
+	/**
+	* Reemplaza la lista actual de badges por la pasada y la aplica a todos
+	* los mensajes posteriores de este scope.
+	*
+	* @param {string[]} badges - Etiquetas a mostrar como badges adyacentes
+	*   al prefijo (p. ej. `['OUTBOUND', 'CACHED']`).
+	* @returns {this} La misma instancia, para encadenar llamadas.
+	*
+	* @example
+	* logger.scope('HTTP').badges(['OUTBOUND', 'CACHED']).info('Cache hit');
+	* // salida: [HTTP] [OUTBOUND] [CACHED] Cache hit
+	*
+	* @see {@link badge} para añadir sin reemplazar los existentes.
+	* @see {@link clearBadges} para vaciar la lista.
+	*/
 	badges(badges) {
 		this.badgeList = [...badges];
 		return this;
 	}
+	/**
+	* Añade un badge al scope de forma idempotente (no lo duplica si ya existe).
+	*
+	* @param {string} badge - Etiqueta a añadir a la lista de badges.
+	* @returns {this} La misma instancia, para encadenar llamadas.
+	*
+	* @example
+	* logger.scope('API')
+	*   .badge('OUTBOUND')
+	*   .badge('RETRY')
+	*   .warn('Reintentando');
+	* // salida: [API] [OUTBOUND] [RETRY] Reintentando
+	*/
 	badge(badge) {
 		if (!this.badgeList.includes(badge)) this.badgeList.push(badge);
 		return this;
 	}
+	/**
+	* Vacía la lista de badges del scope.
+	*
+	* @returns {this} La misma instancia, para encadenar llamadas.
+	*
+	* @example
+	* const http = logger.scope('HTTP');
+	* http.badge('OUTBOUND').info('uno');
+	* http.clearBadges().info('dos');
+	* // [HTTP] [OUTBOUND] uno   /   [HTTP] dos
+	*/
 	clearBadges() {
 		this.badgeList = [];
 		return this;
 	}
+	/**
+	* Aplica un theme preset al logger padre. El preset afecta a toda la
+	* instancia raíz (no solo a este scope) porque el style es compartido.
+	*
+	* @param {string} presetName - Nombre del preset registrado en el StyleManager.
+	* @returns {this} La misma instancia, para encadenar llamadas.
+	*
+	* @example
+	* logger.scope('UI').style('cyberpunk').info('neon');
+	* @see {@link Logger.setTheme}
+	*/
 	style(presetName) {
 		this.parent.setTheme(presetName);
 		return this;
 	}
+	/**
+	* Crea un {@link ContextLogger} vinculado a este scope. Los contextos se
+	* apilan en el prefijo separados por `:`, permitiendo agrupar bloques de
+	* logs relacionados (reintentos, sub-etapas, etc.) sin `console.group`.
+	*
+	* @param {string} contextName - Nombre del contexto a apilar.
+	* @returns {ContextLogger} Handler con `run`, `runAsync`, `start`/`end`.
+	*
+	* @example
+	* const retry = logger.scope('HTTP').context('retry');
+	* retry.run(() => logger.warn('Reintentando'));
+	* // salida: [HTTP:retry] Reintentando
+	* @see {@link ContextLogger}
+	*/
 	context(contextName) {
 		return new ContextLogger(this, contextName);
 	}
+	/**
+	* Inicia un timer etiquetado bajo el namespace `<scopeName>:<label>`.
+	* El label es local a este scope, así que dos scopes pueden reutilizar el
+	* mismo nombre sin colisión.
+	*
+	* @param {string} label - Identificador del timer.
+	*
+	* @example
+	* const http = logger.scope('HTTP');
+	* http.time('request');
+	* // ... trabajo ...
+	* http.timeEnd('request'); // imprime "Timer: request - 12.34ms"
+	* @see {@link timeEnd}
+	*/
 	time(label) {
 		this.timers.set(label, {
 			label: `${this.scopeName}:${label}`,
 			startTime: performance.now()
 		});
 	}
+	/**
+	* Detiene un timer previamente iniciado con {@link time} y registra la
+	* duración con nivel `success`. Si el label no existe, emite un `warn`
+	* y devuelve `undefined`.
+	*
+	* @param {string} label - Mismo label pasado a {@link time}.
+	* @returns {number | undefined} Milisegundos transcurridos, o `undefined`
+	*   si el timer no estaba registrado.
+	*
+	* @example
+	* const http = logger.scope('HTTP');
+	* http.time('fetch');
+	* await fetch(url);
+	* const ms = http.timeEnd('fetch');
+	* if (ms && ms > 1000) http.warn('Latencia alta');
+	*/
 	timeEnd(label) {
 		const timer = this.timers.get(label);
 		if (!timer) {
@@ -74,118 +208,447 @@ var ScopedLogger = class {
 		this.success(`Timer: ${label} - ${elapsed.toFixed(2)}ms`);
 		return elapsed;
 	}
+	/**
+	* Emite un mensaje a nivel `debug` con los bindings actuales del scope.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales (objetos,
+	*   errores, etc.) serializados igual que en el logger raíz.
+	*
+	* @example
+	* logger.scope('DB').debug('query', { sql, params });
+	*/
 	debug(...args) {
 		this.parent.logWithBindings(this.getBindings(), "debug", ...args);
 	}
+	/**
+	* Emite un mensaje a nivel `info` con los bindings actuales del scope.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales.
+	*
+	* @example
+	* logger.scope('AUTH').info('Login exitoso', { userId });
+	*/
 	info(...args) {
 		this.parent.logWithBindings(this.getBindings(), "info", ...args);
 	}
+	/**
+	* Emite un mensaje a nivel `warn` con los bindings actuales del scope.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales.
+	*
+	* @example
+	* logger.scope('CACHE').warn('Cache miss', { key });
+	*/
 	warn(...args) {
 		this.parent.logWithBindings(this.getBindings(), "warn", ...args);
 	}
+	/**
+	* Emite un mensaje a nivel `error` con los bindings actuales del scope.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales (típicamente
+	*   un `Error` o contexto del fallo).
+	*
+	* @example
+	* logger.scope('DB').error('Conexión rechazada', err);
+	*/
 	error(...args) {
 		this.parent.logWithBindings(this.getBindings(), "error", ...args);
 	}
+	/**
+	* Emite un mensaje con badge visual `SUCCESS` a nivel `info`. Úselo para
+	* hitos positivos dentro del scope (conexión establecida, sync completo,
+	* commit aplicado).
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales.
+	*
+	* @example
+	* logger.scope('SYNC').success('Sincronización completa', { count: 42 });
+	*/
 	success(...args) {
 		const bindings = this.getBindings();
 		this.parent.logWithBindingsAndTag(bindings, "info", "success", ...args);
 	}
+	/**
+	* Emite un mensaje a nivel `critical` con los bindings actuales del scope.
+	* Reservado para fallos que detienen el flujo de la aplicación.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales.
+	*
+	* @example
+	* logger.scope('PAY').critical('Pasarela inaccesible', err);
+	*/
 	critical(...args) {
 		this.parent.logWithBindings(this.getBindings(), "critical", ...args);
 	}
+	/**
+	* Emite un mensaje a nivel `trace` (verbosidad máxima) con los bindings
+	* actuales del scope. Solo aparece si la verbosity global lo permite.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales.
+	*
+	* @example
+	* logger.scope('NET').trace('packet', { bytes });
+	*/
 	trace(...args) {
 		this.parent.logWithBindings(this.getBindings(), "trace", ...args);
 	}
-	/** @see Logger.step */
+	/**
+	* Emite un point-span con el scope de este logger como
+	* `SpanRecord.scope`. Ver {@link Logger.event}.
+	*
+	* @param {string} name - Nombre del evento.
+	* @param {SpanAttributes} [attributes] - Attributes del span.
+	*
+	* @example
+	* logger.scope('BUILD').event('step.done', { step: 'compile' });
+	*/
+	event(name, attributes) {
+		this.parent._emitSpanEvent(name, attributes, this.getScopePrefix());
+	}
+	span(name, fnOrAttributes, maybeFn) {
+		const { attributes, fn } = resolveSpanArgs(fnOrAttributes, maybeFn);
+		return this.parent._runSpan(name, attributes, this.getScopePrefix(), fn);
+	}
+	/**
+	* Inicia un span externally-ended etiquetado con el scope de este
+	* logger. Ver {@link Logger.startSpan}.
+	*
+	* @param {string} name - Nombre de la operación.
+	* @param {SpanAttributes} [attributes] - Attributes iniciales.
+	* @returns {Span} Handle con `set`/`end`/`fail`.
+	*/
+	startSpan(name, attributes) {
+		return this.parent._startSpan(name, attributes, this.getScopePrefix());
+	}
+	/**
+	* Delegación a {@link Logger.step}: dibuja una barra de progreso discreta
+	* `current/total` para este scope.
+	*
+	* @param {number} current - Paso actual (1-indexed).
+	* @param {number} total - Total de pasos.
+	* @param {string} message - Texto mostrado junto al contador.
+	* @see {@link Logger.step}
+	*/
 	step(current, total, message) {
 		this.parent.step(current, total, message);
 	}
-	/** @see Logger.header */
+	/**
+	* Delegación a {@link Logger.header}: imprime un título con separadores visuales.
+	*
+	* @param {string} title - Texto del título.
+	* @param {string} [subtitle] - Subtítulo opcional bajo el título.
+	* @see {@link Logger.header}
+	*/
 	header(title, subtitle) {
 		this.parent.header(title, subtitle);
 	}
-	/** @see Logger.divider */
+	/**
+	* Delegación a {@link Logger.divider}: imprime una línea separadora horizontal.
+	* @see {@link Logger.divider}
+	*/
 	divider() {
 		this.parent.divider();
 	}
-	/** @see Logger.blank */
+	/**
+	* Delegación a {@link Logger.blank}: inserta una línea en blanco.
+	* @see {@link Logger.blank}
+	*/
 	blank() {
 		this.parent.blank();
 	}
-	/** @see Logger.box */
+	/**
+	* Delegación a {@link Logger.box}: dibuja un recuadro ANSI alrededor de `content`.
+	*
+	* @param {string} content - Texto a enmarcar.
+	* @param {IBoxOptions} [options] - Opciones de estilo del box.
+	* @see {@link Logger.box}
+	*/
 	box(content, options) {
 		this.parent.box(content, options);
 	}
-	/** @see Logger.cliTable */
+	/**
+	* Delegación a {@link Logger.cliTable}: renderiza `rows` como tabla ASCII.
+	*
+	* @param {Record<string, unknown>[]} rows - Filas a mostrar.
+	* @param {ITableOptions} [options] - Opciones de columnas y estilo.
+	* @see {@link Logger.cliTable}
+	*/
 	cliTable(rows, options) {
 		this.parent.cliTable(rows, options);
 	}
-	/** @see Logger.spinner */
+	/**
+	* Delegación a {@link Logger.spinner}: arranca un spinner con `message`.
+	*
+	* @param {string} message - Texto a mostrar al lado del spinner.
+	* @returns {ISpinnerHandle} Handle para detener/actualizar el spinner.
+	* @see {@link Logger.spinner}
+	*/
 	spinner(message) {
 		return this.parent.spinner(message);
 	}
-	/** @see Logger.setCLILevel */
+	/**
+	* Delegación a {@link Logger.setCLILevel}: ajusta el nivel mínimo de las
+	* primitivas CLI visibles.
+	*
+	* @param {CLILogLevel} level - Nivel CLI (`silent` … `verbose`).
+	* @see {@link Logger.setCLILevel}
+	*/
 	setCLILevel(level) {
 		this.parent.setCLILevel(level);
 	}
+	/**
+	* Apila un contexto en el prefijo del scope. Invocado por
+	* {@link ContextLogger}; los clientes no deben llamarlo directamente.
+	*
+	* @param {string} context - Nombre del contexto a apilar.
+	* @internal
+	*/
 	_pushContext(context) {
 		this.contextStack.push(context);
 	}
+	/**
+	* Desapila el último contexto del prefijo del scope. Invocado por
+	* {@link ContextLogger}; los clientes no deben llamarlo directamente.
+	*
+	* @internal
+	*/
 	_popContext() {
 		this.contextStack.pop();
 	}
 };
+/**
+* Logger especializado para llamadas a APIs y servicios externos.
+*
+* Extiende {@link ScopedLogger} pre-seteando el badge `API` y exponiendo
+* atajos para eventos típicos de integración: llamadas lentas ({@link slow}),
+* rate limiting ({@link rateLimit}), fallos de autenticación ({@link auth}) y
+* APIs deprecadas ({@link deprecated}).
+*
+* Se obtiene con `logger.api(name)` y no se construye directamente.
+*
+* @example
+* import logger from '@mks2508/better-logger';
+*
+* const stripe = logger.api('Stripe');
+* stripe.info('Consultando customer', { id });
+* // salida: [API:Stripe] [API] Consultando customer
+*
+* stripe.slow('customer.retrieve', 1250);
+* // salida: [API:Stripe] [API] [SLOW] customer.retrieve (1250ms)
+*
+* @see {@link Logger.api}
+* @see {@link ScopedLogger}
+*/
 var APILogger = class extends ScopedLogger {
+	/**
+	* Construye un APILogger con scope `API:<apiName>` y badge `API` ya aplicado.
+	*
+	* Los clientes deben usar `logger.api(name)`.
+	*
+	* @param {Logger} parent - Logger raíz al que se delegan los mensajes.
+	* @param {string} apiName - Nombre del servicio/API (se prefija con `API:`).
+	*/
 	constructor(parent, apiName) {
 		super(parent, `API:${apiName}`);
 		this.badge("API");
 	}
+	/**
+	* Registra una llamada lenta con badge `SLOW` a nivel `warn`.
+	*
+	* @param {string} message - Descripción de la operación lenta.
+	* @param {number} [duration] - Duración medida en ms; si se pasa, se
+	*   anexa al mensaje como `(Nms)`.
+	*
+	* @example
+	* const t0 = performance.now();
+	* await stripe.customers.retrieve(id);
+	* logger.api('Stripe').slow('retrieve', performance.now() - t0);
+	*/
 	slow(message, duration) {
 		this.badge("SLOW");
 		const msg = duration ? `${message} (${duration}ms)` : message;
 		this.warn(msg);
 	}
+	/**
+	* Registra un evento de rate limiting (HTTP 429) con badge `RATE_LIMIT`.
+	*
+	* @param {string} message - Detalle del límite golpeado.
+	*
+	* @example
+	* logger.api('GitHub').rateLimit('Secondary rate limit on /search');
+	*/
 	rateLimit(message) {
 		this.badge("RATE_LIMIT");
 		this.warn(message);
 	}
+	/**
+	* Registra un fallo de autenticación (401/403) con badge `AUTH` a nivel
+	* `error`.
+	*
+	* @param {string} message - Detalle del fallo de credenciales/token.
+	*
+	* @example
+	* logger.api('OAuth').auth('Token expirado');
+	*/
 	auth(message) {
 		this.badge("AUTH");
 		this.error(message);
 	}
+	/**
+	* Marca una API como deprecada con badge `DEPRECATED` a nivel `warn`.
+	*
+	* @param {string} message - Mensaje guiando a la migración (endpoint
+	*   alternativo, versión retirada, etc.).
+	*
+	* @example
+	* logger.api('Legacy').deprecated('Usar v3; v2 se retira en Q4');
+	*/
 	deprecated(message) {
 		this.badge("DEPRECATED");
 		this.warn(message);
 	}
 };
+/**
+* Logger para componentes UI, módulos o cualquier unidad con ciclo de vida.
+*
+* Extiende {@link ScopedLogger} pre-seteando el badge `COMPONENT` y exponiendo
+* atajos para eventos típicos: {@link lifecycle}, {@link stateChange} y
+* {@link propsChange}.
+*
+* Se obtiene con `logger.component(name)` y no se construye directamente.
+*
+* @example
+* import logger from '@mks2508/better-logger';
+*
+* const cart = logger.component('Cart');
+* cart.lifecycle('mount');
+* // salida: [Cart] [COMPONENT] [LIFECYCLE] mount
+*
+* cart.stateChange('empty', 'has-items', { count: 3 });
+* // salida: [Cart] [COMPONENT] [STATE] empty → has-items { count: 3 }
+*
+* @see {@link Logger.component}
+* @see {@link ScopedLogger}
+*/
 var ComponentLogger = class extends ScopedLogger {
+	/**
+	* Construye un ComponentLogger con badge `COMPONENT` ya aplicado.
+	*
+	* Los clientes deben usar `logger.component(name)`.
+	*
+	* @param {Logger} parent - Logger raíz al que se delegan los mensajes.
+	* @param {string} componentName - Nombre del componente (scope label).
+	*/
 	constructor(parent, componentName) {
 		super(parent, componentName);
 		this.badge("COMPONENT");
 	}
+	/**
+	* Registra un evento de ciclo de vida con badge `LIFECYCLE` a nivel `info`.
+	*
+	* @param {string} event - Nombre del evento (`mount`, `unmount`,
+	*   `update`, ...).
+	* @param {string} [message] - Detalle opcional; si se omite, solo se
+	*   registra el nombre del evento.
+	*
+	* @example
+	* logger.component('Cart').lifecycle('mount', 'Modal abierto');
+	*/
 	lifecycle(event, message) {
 		this.badge("LIFECYCLE");
 		const msg = message ? `${event}: ${message}` : event;
 		this.info(msg);
 	}
+	/**
+	* Registra una transición de estado con badge `STATE` a nivel `info`.
+	*
+	* @param {string} from - Estado previo.
+	* @param {string} to - Estado nuevo.
+	* @param {unknown} [data] - Payload opcional asociado a la transición.
+	*
+	* @example
+	* const fsm = logger.component('FSM');
+	* fsm.stateChange('idle', 'loading');
+	* fsm.stateChange('loading', 'success', { items: 3 });
+	*/
 	stateChange(from, to, data) {
 		this.badge("STATE");
 		const msg = `${from} → ${to}`;
 		if (data) this.info(msg, data);
 		else this.info(msg);
 	}
+	/**
+	* Registra cambios de props/debug del componente con badge `PROPS` a nivel
+	* `debug`.
+	*
+	* @param {Record<string, unknown>} changes - Mapa prop → valor (típicamente
+	*   el diff de props entre renders).
+	*
+	* @example
+	* logger.component('Cart').propsChange({ itemCount: 5, currency: 'EUR' });
+	*/
 	propsChange(changes) {
 		this.badge("PROPS");
 		this.debug("Props changed:", changes);
 	}
 };
+/**
+* Handler de contexto apilable sobre un {@link ScopedLogger}.
+*
+* Permite agrupar bloques de logs bajo un sub-prefijo separado por `:`,
+* manteniendo la correlación visual sin necesidad de `console.group`. El
+* prefijo compuesto se forma como `<scopeName>:<contextName>`.
+*
+* Se crea con `scopedLogger.context(name)`. El patrón idiomático es
+* {@link run}/{@link runAsync} (auto push/pop con try/finally); {@link start}
+* y {@link end} permiten control manual cuando el bloque no cierra
+* léxicamente (event handlers distribuidos, promesas de larga duración).
+*
+* @example
+* import logger from '@mks2508/better-logger';
+*
+* const http = logger.scope('HTTP');
+*
+* // Bloque síncrono auto-cerrado
+* http.context('retry').run(() => {
+*   http.warn('Reintentando petición');
+* });
+* // salida: [HTTP:retry] Reintentando petición
+*
+* // Bloque async auto-cerrado
+* await http.context('refresh').runAsync(async () => {
+*   await refreshToken();
+*   http.info('Token refrescado');
+* });
+*
+* @see {@link ScopedLogger.context}
+*/
 var ContextLogger = class {
 	parentLogger;
 	contextName;
+	/**
+	* @param {ScopedLogger} parentLogger - Scope sobre el que se apila el contexto.
+	* @param {string} contextName - Sub-prefijo a apilar en el scope padre.
+	*/
 	constructor(parentLogger, contextName) {
 		this.parentLogger = parentLogger;
 		this.contextName = contextName;
 	}
+	/**
+	* Ejecuta `fn` síncrona dentro del contexto, garantizando el pop del
+	* prefijo incluso si `fn` lanza. El contexto solo está activo durante la
+	* ejecución de `fn`.
+	*
+	* @typeParam T - Tipo de retorno de `fn`.
+	* @param {() => T} fn - Función a ejecutar bajo el contexto.
+	* @returns {T} Lo que devuelva `fn`.
+	* @throws {unknown} Relanza cualquier excepción de `fn` tras desapilar.
+	*
+	* @example
+	* logger.scope('HTTP').context('warmup').run(() => {
+	*   logger.info('Pre-cargando caché');
+	* });
+	*/
 	run(fn) {
 		this.parentLogger._pushContext(this.contextName);
 		try {
@@ -194,6 +657,21 @@ var ContextLogger = class {
 			this.parentLogger._popContext();
 		}
 	}
+	/**
+	* Variante async de {@link run}: mantiene el contexto activo mientras se
+	* awaiting la promesa de `fn`, incluyendo awaits internos.
+	*
+	* @typeParam T - Tipo resuelto por la promesa de `fn`.
+	* @param {() => Promise<T>} fn - Función async a ejecutar bajo el contexto.
+	* @returns {Promise<T>} Promesa que resuelve al valor de `fn`.
+	* @throws {unknown} Relanza cualquier rechazo de `fn` tras desapilar.
+	*
+	* @example
+	* await logger.scope('HTTP').context('fetch').runAsync(async () => {
+	*   const r = await fetch(url);
+	*   logger.info('Recibido', { status: r.status });
+	* });
+	*/
 	async runAsync(fn) {
 		this.parentLogger._pushContext(this.contextName);
 		try {
@@ -202,27 +680,80 @@ var ContextLogger = class {
 			this.parentLogger._popContext();
 		}
 	}
+	/**
+	* Apila el contexto manualmente. Útil cuando el bloque que lo consume no
+	* cierra léxicamente (event handlers, timeouts, streams). Debe emparejarse
+	* con un {@link end} posterior; olvidarlo deja el prefijo contaminado para
+	* los logs siguientes del scope.
+	*
+	* @example
+	* const ctx = logger.scope('WS').context('subscribe');
+	* socket.onopen  = () => { ctx.start(); ctx.info('connected'); };
+	* socket.onclose = () => { ctx.info('disconnected'); ctx.end(); };
+	* @see {@link end}
+	*/
 	start() {
 		this.parentLogger._pushContext(this.contextName);
 	}
+	/**
+	* Desapila el último contexto abierto con {@link start}.
+	*
+	* @see {@link start}
+	*/
 	end() {
 		this.parentLogger._popContext();
 	}
+	/**
+	* Atajo a `scopedLogger.debug(...)`. El contexto se aplica al prefijo del
+	* scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales.
+	*/
 	debug(...args) {
 		this.parentLogger.debug(...args);
 	}
+	/**
+	* Atajo a `scopedLogger.info(...)`. El contexto se aplica al prefijo del
+	* scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales.
+	*/
 	info(...args) {
 		this.parentLogger.info(...args);
 	}
+	/**
+	* Atajo a `scopedLogger.warn(...)`. El contexto se aplica al prefijo del
+	* scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales.
+	*/
 	warn(...args) {
 		this.parentLogger.warn(...args);
 	}
+	/**
+	* Atajo a `scopedLogger.error(...)`. El contexto se aplica al prefijo del
+	* scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales.
+	*/
 	error(...args) {
 		this.parentLogger.error(...args);
 	}
+	/**
+	* Atajo a `scopedLogger.success(...)`. El contexto se aplica al prefijo del
+	* scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales.
+	*/
 	success(...args) {
 		this.parentLogger.success(...args);
 	}
+	/**
+	* Atajo a `scopedLogger.critical(...)`. El contexto se aplica al prefijo
+	* del scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+	*
+	* @param {...unknown[]} args - Mensaje y argumentos adicionales.
+	*/
 	critical(...args) {
 		this.parentLogger.critical(...args);
 	}
@@ -230,7 +761,34 @@ var ContextLogger = class {
 //#endregion
 //#region src/cli/CommandProcessor.ts
 /**
-* CLI command processor
+* Procesador central del CLI del logger. Resuelve nombres de comando (con
+* aliases), despacha ejecución, mantiene historial acotado (max 100 entradas)
+* y soporta un sistema de plugins para extensión de terceros.
+*
+* No es un binario standalone: se invoca desde la consola del navegador vía
+* `window.cli("<command>")` (modo interactivo habilitado por
+* {@link enterInteractiveMode}) o desde código vía `logger.cli()`. El
+* constructor no registra ningún comando por defecto — usar
+* {@link createDefaultCLI} para obtener una instancia con los 8 comandos
+* estándar ya cargados.
+*
+* @example
+* ```ts
+* const cli = createDefaultCLI();
+* await cli.processCommand('/themes', logger);
+* await cli.processCommand('/config theme=neon', logger);
+* ```
+*
+* @example
+* ```ts
+* // Modo interactivo: expone `window.cli` en el navegador
+* cli.enterInteractiveMode(logger);
+* // Desde la devtools: cli('help')  →  procesa '/help'
+* ```
+*
+* @see {@link createDefaultCLI}
+* @see {@link ICommand}
+* @see {@link ICLIPlugin}
 */
 var CommandProcessor = class {
 	commands = /* @__PURE__ */ new Map();
@@ -240,14 +798,26 @@ var CommandProcessor = class {
 	maxHistorySize = 100;
 	isInteractiveMode = false;
 	/**
-	* Register a command
+	* Registra un comando. Si el comando declara `aliases`, también se indexan
+	* para resolución. Un comando con el mismo `name` sobreescribe al previo.
+	*
+	* @param {ICommand} command - Comando a registrar.
+	* @see {@link ICommand}
 	*/
 	registerCommand(command) {
 		this.commands.set(command.name, command);
 		if (command.aliases) for (const alias of command.aliases) this.aliases.set(alias, command.name);
 	}
 	/**
-	* Register a plugin
+	* Registra un plugin: indexa todos sus commands y, si el plugin define
+	* `initialize`, lo invoca con el processor y el logger. Los comandos del
+	* plugin se registran vía {@link registerCommand} y sus aliases quedan
+	* resolvibles igual que los directos.
+	*
+	* @param {ICLIPlugin} plugin - Plugin a registrar.
+	* @param {Logger} [logger] - Logger activo; requerido solo si el plugin define `initialize`.
+	* @throws {Error} Si ya existe un plugin registrado con el mismo `name`.
+	* @see {@link unregisterPlugin}
 	*/
 	registerPlugin(plugin, logger) {
 		if (this.plugins.has(plugin.name)) throw new Error(`Plugin ${plugin.name} is already registered`);
@@ -256,7 +826,12 @@ var CommandProcessor = class {
 		if (plugin.initialize && logger) plugin.initialize(this, logger);
 	}
 	/**
-	* Unregister a plugin
+	* Desregistra un plugin por nombre: elimina todos sus commands (y los
+	* aliases que aportasen), invoca su hook `cleanup` si existe y lo quita
+	* del registry. No-op si el nombre no existe.
+	*
+	* @param {string} pluginName - Nombre del plugin a desregistrar.
+	* @see {@link registerPlugin}
 	*/
 	unregisterPlugin(pluginName) {
 		const plugin = this.plugins.get(pluginName);
@@ -269,13 +844,20 @@ var CommandProcessor = class {
 		this.plugins.delete(pluginName);
 	}
 	/**
-	* Get all registered commands
+	* Lista todos los commands registrados (directamente o vía plugins).
+	* No incluye aliases.
+	*
+	* @returns {ICommand[]} Snapshot array de los commands registrados.
 	*/
 	getCommands() {
 		return Array.from(this.commands.values());
 	}
 	/**
-	* Get a specific command
+	* Resuelve un comando por nombre canónico o alias. Devuelve `undefined`
+	* si no existe ninguno que matchee.
+	*
+	* @param {string} name - Nombre canónico o alias del comando.
+	* @returns {ICommand | undefined} El comando resuelto, o `undefined`.
 	*/
 	getCommand(name) {
 		let command = this.commands.get(name);
@@ -284,25 +866,38 @@ var CommandProcessor = class {
 		if (aliasTarget) return this.commands.get(aliasTarget);
 	}
 	/**
-	* Get command history
+	* Devuelve una copia del historial de comandos ejecutados (más recientes
+	* primero). Acotado a 100 entradas por {@link maxHistorySize}; las más
+	* viejas se descartan al insertar nuevas.
+	*
+	* @returns {HistoryEntry[]} Snapshot del historial; mutar el array devuelto
+	*   no afecta al estado interno del processor.
 	*/
 	getHistory() {
 		return [...this.history];
 	}
 	/**
-	* Clear command history
+	* Vacía el historial de comandos en memoria.
 	*/
 	clearHistory() {
 		this.history = [];
 	}
 	/**
-	* Get registered plugins
+	* Lista los plugins actualmente registrados.
+	*
+	* @returns {ICLIPlugin[]} Snapshot array de plugins activos.
 	*/
 	getPlugins() {
 		return Array.from(this.plugins.values());
 	}
 	/**
-	* Enter interactive mode
+	* Activa el modo interactivo. Marca el flag interno y, si se ejecuta en
+	* navegador, expone `window.cli(command)` para invocar comandos desde la
+	* devtools sin prefijo `/` (se añade automáticamente al input).
+	*
+	* @param {Logger} logger - Logger activo (emite el mensaje de bienvenida
+	*   con hint sobre `cli(...)` en browser).
+	* @see {@link exitInteractiveMode}
 	*/
 	enterInteractiveMode(logger) {
 		this.isInteractiveMode = true;
@@ -310,13 +905,22 @@ var CommandProcessor = class {
 		if (typeof window !== "undefined") this.setupBrowserInteractiveMode(logger);
 	}
 	/**
-	* Exit interactive mode
+	* Desactiva el flag de modo interactivo. Nota: no elimina el `window.cli`
+	* que {@link enterInteractiveMode} haya expuesto en el navegador — el
+	* handler global sigue vivo hasta reload.
+	*
+	* @see {@link enterInteractiveMode}
 	*/
 	exitInteractiveMode() {
 		this.isInteractiveMode = false;
 	}
 	/**
-	* Setup browser interactive mode
+	* Instala `window.cli(command)` como wrapper delgado alrededor de
+	* {@link processCommand}, prefijando `/` automáticamente. Solo se invoca
+	* desde {@link enterInteractiveMode} cuando `window` está disponible.
+	*
+	* @internal
+	* @param logger - Logger activo, reenviado a cada invocación.
 	*/
 	setupBrowserInteractiveMode(logger) {
 		window.cli = (commandString) => {
@@ -325,7 +929,20 @@ var CommandProcessor = class {
 		logger.info("💡 Use cli(\"command\") to execute CLI commands in browser console.");
 	}
 	/**
-	* Process a CLI command
+	* Parsea y ejecuta un comando. El formato esperado es `/name args...`:
+	* split por espacios, primer token = nombre del comando, resto = args
+	* (re-joined con espacios). Si el comando no existe, loguea el error y
+	* sugiere similares vía {@link getSuggestions} ("Did you mean: ...?").
+	*
+	* Toda invocación (válida o no) se registra en el historial con flag de
+	* éxito/fallo según si `execute` resolvió o throweó.
+	*
+	* @param {string} commandString - Comando completo, debe empezar con `/`.
+	* @param {Logger} logger - Logger activo para output y errores.
+	* @returns {Promise<void>} Resuelve cuando el comando termina (sync o async).
+	*   Nunca rechaza: los errores de `execute` se capturan y se loguean.
+	* @see {@link ICommand.execute}
+	* @see {@link getSuggestions}
 	*/
 	async processCommand(commandString, logger) {
 		if (!commandString.startsWith("/")) {
@@ -353,7 +970,12 @@ var CommandProcessor = class {
 		}
 	}
 	/**
-	* Add command to history
+	* Inserta una entrada al frente del historial y trunca a
+	* {@link maxHistorySize} (100) si hace falta.
+	*
+	* @internal
+	* @param command - String crudo del comando ejecutado.
+	* @param success - Si la ejecución tuvo éxito.
 	*/
 	addToHistory(command, success) {
 		this.history.unshift({
@@ -364,7 +986,12 @@ var CommandProcessor = class {
 		if (this.history.length > this.maxHistorySize) this.history = this.history.slice(0, this.maxHistorySize);
 	}
 	/**
-	* Get command suggestions for partial matches
+	* Devuelve nombres de comando que empiezan con el prefijo dado. Alimente
+	* el hint "Did you mean" de {@link processCommand} cuando un comando no
+	* se encuentra. Match por `startsWith` (no fuzzy).
+	*
+	* @param {string} partial - Prefijo parcial tipeado por el usuario.
+	* @returns {string[]} Nombres canónicos que matchean; aliases excluidos.
 	*/
 	getSuggestions(partial) {
 		return Array.from(this.commands.keys()).filter((name) => name.startsWith(partial));
@@ -373,12 +1000,47 @@ var CommandProcessor = class {
 //#endregion
 //#region src/cli/commands/ConfigCommand.ts
 /**
-* Configuration command handler
+* Comando `/config` del CLI runtime del {@link Logger}. Inspecciona o muta
+* la configuración del logger en vivo desde la DevTools console.
+*
+* Acepta tres modos de invocación:
+* - Sin argumentos: vuelca el estado actual como tabla agrupada.
+* - JSON completo (empieza con `{`): aplica un objeto de configuración parcial.
+* - Pares `key=value` separados por coma: atajo para mutaciones puntuales.
+*
+* Solo se aplican las keys de la whitelist interna (`theme`, `verbosity`,
+* `enableColors`, `enableTimestamps`, `enableStackTrace`, `globalPrefix`,
+* `bannerType`); cualquier otra key se rechaza con un `warn` y se ignora.
+*
+* @example
+* // Sin argumentos: ver estado actual
+* // > /config
+*
+* @example
+* // Objeto JSON completo
+* // > /config {"theme":"neon","verbosity":"debug"}
+*
+* @example
+* // Atajo key=value (múltiples pares separados por coma)
+* // > /config theme=neon,verbosity=debug,globalPrefix=MiApp
+*
+* @see {@link ICommand} para el contrato que implementa este comando.
+* @see {@link Logger.setTheme}, {@link Logger.setVerbosity},
+*      {@link Logger.setBannerType}, {@link Logger.setGlobalPrefix}
+*      para los setters subyacentes.
 */
 var ConfigCommand = class {
 	name = "config";
 	description = "Show or update logger configuration";
 	usage = "/config [json|key=value,...]";
+	/**
+	* Ejecuta el comando `/config` contra el logger dado.
+	*
+	* @param args - Argumentos crudos del usuario. Vacío = status; con `{`
+	*               inicial = parse JSON; resto = pares `key=value` separados
+	*               por coma.
+	* @param logger - Instancia destino cuyos setters se invocan.
+	*/
 	execute(args, logger) {
 		if (!args) {
 			this.showStatus(logger);
@@ -452,12 +1114,30 @@ var ConfigCommand = class {
 //#endregion
 //#region src/cli/commands/ThemeCommand.ts
 /**
-* Themes command - show available themes
+* Comando `/themes` del CLI runtime del {@link Logger}. Lista los presets
+* temáticos disponibles en {@link THEME_PRESETS}, renderizando una preview
+* con los colores reales de cada tema (background, foreground, border).
+*
+* Es de solo lectura: no muta el logger. Útil para descubrir qué tema
+* aplicar antes de correr `/config theme=<name>`.
+*
+* @example
+* // Listar todos los temas con preview coloreada
+* // > /themes
+*
+* @see {@link THEME_PRESETS} para el catálogo completo de temas.
+* @see {@link ConfigCommand} para aplicar un tema vía `/config theme=...`.
 */
 var ThemesCommand = class {
 	name = "themes";
 	description = "Show available theme presets";
 	usage = "/themes";
+	/**
+	* Ejecuta el comando `/themes` contra el logger dado.
+	*
+	* @param _args - Ignorado (comando sin parámetros).
+	* @param logger - Instancia usada para abrir/cerrar el `group` de salida.
+	*/
 	execute(_args, logger) {
 		logger.group("🎨 Available Themes");
 		Object.keys(require_styling.THEME_PRESETS).forEach((themeName) => {
@@ -469,12 +1149,30 @@ var ThemesCommand = class {
 	}
 };
 /**
-* Banners command - show available banner types
+* Comando `/banners` del CLI runtime del {@link Logger}. Enumera los tipos
+* de banner disponibles en {@link BANNER_VARIANTS} (`simple`, `ascii`,
+* `unicode`, ...) con una mini-preview de cada uno para inspección visual.
+*
+* Es de solo lectura: no muta el logger. Para cambiar el banner activo
+* usar {@link BannerCommand}.
+*
+* @example
+* // Listar todas las variantes de banner con preview
+* // > /banners
+*
+* @see {@link BANNER_VARIANTS} para el catálogo completo de variantes.
+* @see {@link BannerCommand} para aplicar un tipo concreto.
 */
 var BannersCommand = class {
 	name = "banners";
 	description = "Show available banner types";
 	usage = "/banners";
+	/**
+	* Ejecuta el comando `/banners` contra el logger dado.
+	*
+	* @param _args - Ignorado (comando sin parámetros).
+	* @param logger - Instancia usada para abrir/cerrar el `group` de salida.
+	*/
 	execute(_args, logger) {
 		logger.group("🖼️ Available Banner Types");
 		Object.keys(require_styling.BANNER_VARIANTS).forEach((bannerName) => {
@@ -490,12 +1188,35 @@ var BannersCommand = class {
 	}
 };
 /**
-* Banner command - change/show banner type
+* Comando `/banner [type]` del CLI runtime del {@link Logger}.
+*
+* - Sin argumentos: re-renderiza el banner actualmente activo.
+* - Con un tipo válido: lo aplica vía {@link Logger.setBannerType} y lo
+*   muestra inmediatamente.
+* - Con un tipo inválido: loguea un `error` listando las opciones válidas.
+*
+* @example
+* // Mostrar el banner actual
+* // > /banner
+*
+* @example
+* // Cambiar a un tipo concreto
+* // > /banner ascii
+*
+* @see {@link BANNER_VARIANTS} para los tipos aceptados.
+* @see {@link Logger.setBannerType} y {@link Logger.showBanner} para los
+*      métodos subyacentes.
 */
 var BannerCommand = class {
 	name = "banner";
 	description = "Change or show current banner type";
 	usage = "/banner [type]";
+	/**
+	* Ejecuta el comando `/banner` contra el logger dado.
+	*
+	* @param args - Tipo de banner solicitado. Vacío = mostrar banner actual.
+	* @param logger - Instancia destino cuyo banner se actualiza/muestra.
+	*/
 	execute(args, logger) {
 		if (!args) {
 			logger.showBanner();
@@ -510,12 +1231,27 @@ var BannerCommand = class {
 //#endregion
 //#region src/cli/commands/ExportCommand.ts
 /**
-* Status command - show logger configuration and statistics
+* Comando `/status` del CLI runtime del {@link Logger}. Vuelca la
+* configuración vigente y algunas estadísticas (theme, verbosity, flags
+* de features, handler count, bufferSize) en una tabla agrupada dentro
+* de la consola. Es de solo lectura: no muta el logger.
+*
+* @example
+* // Inspeccionar el estado actual del logger
+* // > /status
+*
+* @see {@link Logger.getConfig} fuente de los datos mostrados.
 */
 var StatusCommand = class {
 	name = "status";
 	description = "Show current logger status and configuration";
 	usage = "/status";
+	/**
+	* Ejecuta el comando `/status` contra el logger dado.
+	*
+	* @param _args - Ignorado (comando sin parámetros).
+	* @param logger - Instancia de la que se lee la configuración.
+	*/
 	execute(_args, logger) {
 		const config = logger.getConfig();
 		const statusData = {
@@ -535,23 +1271,54 @@ var StatusCommand = class {
 	}
 };
 /**
-* Reset command - reset logger to defaults
+* Comando `/reset` del CLI runtime del {@link Logger}. Restaura la
+* configuración a sus defaults de fábrica vía {@link Logger.resetConfig}.
+* No resetea handlers ni transports registrados — solo config.
+*
+* @example
+* // Volver a la configuración por defecto
+* // > /reset
+*
+* @see {@link Logger.resetConfig} para el método subyacente.
 */
 var ResetCommand = class {
 	name = "reset";
 	description = "Reset logger configuration to defaults";
 	usage = "/reset";
+	/**
+	* Ejecuta el comando `/reset` contra el logger dado.
+	*
+	* @param _args - Ignorado (comando sin parámetros).
+	* @param logger - Instancia cuya configuración se resetea.
+	*/
 	execute(_args, logger) {
 		logger.resetConfig();
 	}
 };
 /**
-* Demo command - show logger feature demonstration
+* Comando `/demo` del CLI runtime del {@link Logger}. Ejecuta una
+* demostración integral de las capacidades del logger: todos los niveles
+* de log (debug → critical), tablas, timers (`time`/`timeEnd`), SVG inline
+* y mensajes animados. Útil para validar que el styling funciona en un
+* entorno nuevo o tras un cambio de tema.
+*
+* @example
+* // Lanzar la demo completa
+* // > /demo
+*
+* @see {@link Logger} para cada feature individual (`table`, `time`,
+*      `logWithSVG`, `logAnimated`, ...).
 */
 var DemoCommand = class {
 	name = "demo";
 	description = "Show comprehensive feature demonstration";
 	usage = "/demo";
+	/**
+	* Ejecuta el comando `/demo` contra el logger dado.
+	*
+	* @param _args - Ignorado (comando sin parámetros).
+	* @param logger - Instancia sobre la que se ejecutan los ejemplos.
+	*/
 	execute(_args, logger) {
 		logger.group("🎪 Advanced Logger Demo");
 		logger.debug("Debug message with detailed information");
@@ -597,12 +1364,38 @@ var DemoCommand = class {
 //#endregion
 //#region src/cli/help.ts
 /**
-* Help command - show comprehensive CLI help
+* Comando `/help`: renderiza en consola el panel de ayuda del CLI con todos
+* los comandos disponibles, opciones de configuración, filtros de export y
+* ejemplos. El panel usa un gradient claro con {@link StyleBuilder} y los
+* quick tips se agrupan vía `logger.group`.
+*
+* Registrado por defecto por {@link createDefaultCLI}.
+*
+* @example
+* ```ts
+* const cli = createDefaultCLI();
+* await cli.processCommand('/help', logger);
+* // Imprime el panel ASCII con gradient + grupo "Quick Tips".
+* ```
+*
+* @see {@link ICommand}
+* @see {@link createDefaultCLI}
 */
 var HelpCommand = class {
 	name = "help";
 	description = "Show CLI help and available commands";
 	usage = "/help [command]";
+	/**
+	* Renderiza el panel de ayuda completo. Actualmente ignora `_args`: el
+	* `usage` declara `/help [command]` (sub-comando opcional) pero la
+	* implementación siempre muestra el panel global.
+	*
+	* @param {string} _args - Argumentos opcionales (reservado para ayuda por
+	*   sub-comando; sin uso actual).
+	* @param {Logger} logger - Logger activo; se usa solo para `group`/`info`
+	*   de los quick tips.
+	* @returns {void}
+	*/
 	execute(_args, logger) {
 		const helpStyle = new require_styling.StyleBuilder().bg("linear-gradient(135deg, #f8f9fa 0%, #e9ecef 100%)").color("#495057").padding("15px 20px").rounded("8px").border("1px solid #dee2e6").font("Monaco, Consolas, monospace").size("13px").build();
 		console.log(`%c
@@ -702,7 +1495,30 @@ var HelpCommand = class {
 //#endregion
 //#region src/cli/index.ts
 /**
-* Create and configure default CLI processor
+* Crea un {@link CommandProcessor} con los 8 comandos estándar ya registrados:
+* `help`, `config`, `themes`, `banners`, `banner`, `status`, `reset` y
+* `demo`. Es el factory canónico — los consumidores normalmente no construyen
+* un `CommandProcessor` vacío a mano, ya que este no trae comandos cargados.
+*
+* @returns {CommandProcessor} Processor listo para usar, sin modo interactivo activo.
+*
+* @example
+* ```ts
+* const cli = createDefaultCLI();
+* await cli.processCommand('/help', logger);
+* await cli.processCommand('/config theme=neon', logger);
+* ```
+*
+* @example
+* ```ts
+* // Modo interactivo en el navegador: expone `window.cli`
+* const cli = createDefaultCLI();
+* cli.enterInteractiveMode(logger);
+* // desde devtools: cli('themes')  →  procesa '/themes'
+* ```
+*
+* @see {@link CommandProcessor}
+* @see {@link HelpCommand}
 */
 function createDefaultCLI() {
 	const processor = new CommandProcessor();
@@ -719,7 +1535,9 @@ function createDefaultCLI() {
 //#endregion
 //#region src/transports/TransportBridge.ts
 /**
-* Creates a TransportBridge instance.
+* Crea una instancia de {@link TransportBridge}.
+*
+* @internal
 */
 function createTransportBridge() {
 	let transportManager;
@@ -747,9 +1565,170 @@ function createTransportBridge() {
 	};
 }
 //#endregion
+//#region src/transports/SpanRuntime.ts
+/** ALS singleton del módulo — compartido por todas las instancias de Logger.
+*
+* Resolución por capas (global → `process.getBuiltinModule` → `require`,
+* undefined en browser) delegada al helper compartido
+* {@link resolveAsyncLocalStorage} — ver su doc para el detalle de capas.
+* `context/LogContext.ts` usa el mismo helper para su ALS de MDC. */
+const activeSpanStore = require_LogContext.resolveAsyncLocalStorage();
+/**
+* Span activo en el call stack corriente (dentro de `span(fn)`), si lo hay.
+* Lo consumen la correlación log→span (`TransportRecord.traceId/spanId`) y la
+* resolución de `parentSpanId` en spans hijos.
+*/
+function getActiveSpan() {
+	return activeSpanStore?.getStore();
+}
+/**
+* Ejecuta `fn` con `record` como span activo. Sin ALS disponible (browser),
+* ejecuta `fn` directamente — sin correlación pero funcional.
+*/
+function runWithActiveSpan(record, fn) {
+	return activeSpanStore ? activeSpanStore.run(record, fn) : fn();
+}
+/** Nanosegundos Unix actuales como string decimal (formato OTLP). */
+function nowUnixNano() {
+	return String(BigInt(Date.now()) * 1000000n);
+}
+/**
+* Hex aleatorio de `bytes` bytes. Usa `crypto.getRandomValues`; sin
+* `crypto` (runtimes exóticos) degrada a `Math.random` — suficiente para ids
+* de correlación, no para secrets.
+*/
+function randomHex(bytes) {
+	const cryptoObj = globalThis.crypto;
+	if (cryptoObj?.getRandomValues) {
+		const buf = new Uint8Array(bytes);
+		cryptoObj.getRandomValues(buf);
+		let out = "";
+		for (const b of buf) out += b.toString(16).padStart(2, "0");
+		return out;
+	}
+	let out = "";
+	for (let i = 0; i < bytes * 2; i++) out += Math.floor(Math.random() * 16).toString(16);
+	return out;
+}
+/** Trace id W3C: 16 bytes → 32 chars hex. */
+function generateTraceId() {
+	return randomHex(16);
+}
+/** Span id W3C: 8 bytes → 16 chars hex. */
+function generateSpanId() {
+	return randomHex(8);
+}
+/**
+* Registry de spans abiertos (leak-safety). Cubre tanto los de `startSpan()`
+* (externally-ended, el caso del handoff) como los de `span(fn)` en curso:
+* si un flush llega mid-flight, es mejor exportar el span incompleto que
+* tirarlo. El doble-`end()` es no-op, así que el cierre natural posterior no
+* duplica el export.
+*/
+const openSpans = /* @__PURE__ */ new Map();
+/**
+* Crea el record de span y su {@link Span} handle. El handle registra el
+* span en el registry de abiertos; `onEnd` se invoca una única vez, con el
+* record final (duración real o `incomplete: true`), para su export al
+* pipeline de transports.
+*
+* `end()` solo fija `endTimeUnixNano` si no se fijó antes — así los
+* point-spans (`event()`) pueden fijar `end = start` exacto.
+*
+* @param name - Nombre de la operación.
+* @param attributes - Attributes iniciales (copia propia del record).
+* @param scope - Scope del logger emisor.
+* @param onEnd - Callback de export; recibe el record cerrado.
+* @returns El record (para el ALS store) y el handle del span.
+*/
+function createSpan(name, attributes, scope, onEnd) {
+	const parent = getActiveSpan();
+	const record = {
+		kind: "span",
+		traceId: parent?.traceId ?? generateTraceId(),
+		spanId: generateSpanId(),
+		parentSpanId: parent?.spanId,
+		name,
+		spanKind: 1,
+		startTimeUnixNano: nowUnixNano(),
+		endTimeUnixNano: "0",
+		attributes: { ...attributes ?? {} },
+		scope
+	};
+	let ended = false;
+	const finish = () => {
+		if (ended) return;
+		ended = true;
+		openSpans.delete(record);
+		onEnd(record);
+	};
+	openSpans.set(record, {
+		record,
+		end: finish,
+		forceEnd: () => {
+			if (ended) return;
+			record.incomplete = true;
+			if (record.endTimeUnixNano === "0") record.endTimeUnixNano = nowUnixNano();
+			finish();
+		}
+	});
+	const handle = {
+		traceId: record.traceId,
+		spanId: record.spanId,
+		set(key, value) {
+			record.attributes[key] = value;
+			return handle;
+		},
+		end(attributes) {
+			if (attributes) Object.assign(record.attributes, attributes);
+			if (ended) return;
+			if (record.endTimeUnixNano === "0") record.endTimeUnixNano = nowUnixNano();
+			finish();
+		},
+		fail(err) {
+			if (ended) return;
+			record.status = {
+				code: 2,
+				message: err instanceof Error ? err.message : String(err)
+			};
+			this.end();
+		}
+	};
+	return {
+		record,
+		span: handle
+	};
+}
+/**
+* Emite un point-span (`event()`): start = end exactamente, sin registro en
+* abiertos tras el cierre — no hay leak posible. El `parentSpanId` se resuelve
+* contra el span activo si existe, pero NO fija contexto ALS.
+*/
+function emitEventSpan(name, attributes, scope, onEnd) {
+	const { record, span } = createSpan(name, attributes, scope, onEnd);
+	record.endTimeUnixNano = record.startTimeUnixNano;
+	span.end();
+}
+/**
+* Fuerza el cierre de todos los spans abiertos (`incomplete: true`) y los
+* exporta vía el `onEnd` de cada uno. Lo invocan `flushTransports()` /
+* `closeTransports()` / `cleanup()` ANTES del flush real — un span abierto
+* nunca se tira en shutdown.
+*
+* @returns Los records forzados a cerrar (para diagnóstico/tests).
+*/
+function forceCloseOpenSpans() {
+	const snapshot = [...openSpans.values()];
+	for (const entry of snapshot) entry.forceEnd();
+	return snapshot.map((entry) => entry.record);
+}
+//#endregion
 //#region src/playground/TerminalBridge.ts
 /**
-* Creates a TerminalBridge using a getter to avoid circular reference at construction.
+* Crea un {@link TerminalBridge} usando un getter para evitar referencias
+* circulares en la construcción.
+*
+* @internal
 */
 function createTerminalBridge(options) {
 	let _showPrimitives = true;
@@ -874,37 +1853,38 @@ var Logger = class Logger {
 	hookBridge;
 	logContext;
 	transportBridge;
-	/** Set during success() so log() skips its own dispatch (N2 fix). */
+	/** Fijado por `success()` para que `log()` salte su propio dispatch. */
 	_successTagDispatched = false;
 	styleManager;
-	/** Whether CLI primitives (step, box, header, etc.) should be shown*/
+	/** Controla si las CLI primitives (step, box, header, ...) deben renderizarse. */
 	_showPrimitives = true;
 	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`.
 	*/
 	_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.
 	*/
 	_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.
 	*/
 	_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
 	*/
 	_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
 	*/
 	_parentContextRecord;
@@ -1072,65 +2052,66 @@ var Logger = class Logger {
 		this.success(`Banner type changed to: ${bannerType}`);
 	}
 	/**
-	* 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(bindings, fn) {
 		return this.logContext.withContext(bindings, fn);
 	}
 	/**
-	* 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(bindings, fn) {
 		return this.logContext.withContextAsync(bindings, fn);
 	}
 	/**
-	* 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) {
@@ -1140,21 +2121,21 @@ var Logger = class Logger {
 		return childLogger;
 	}
 	/**
-	* 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.logContext.clearContext();
 		return 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() {
 		let merged = this._parentContextRecord ?? {};
@@ -1165,12 +2146,12 @@ var Logger = class Logger {
 		return merged;
 	}
 	/**
-	* 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' });
@@ -1199,20 +2180,15 @@ var Logger = class Logger {
 		this.success("Logger configuration reset to defaults");
 	}
 	/**
-	* 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.
+	* Método de limpieza para eliminar listeners y liberar recursos.
+	*
+	* 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();
 	*
 	*/
 	async cleanup() {
@@ -1222,6 +2198,7 @@ var Logger = class Logger {
 			} catch {}
 			this.themeChangeListener = null;
 		}
+		forceCloseOpenSpans();
 		await this.transportBridge.closeTransports();
 		this.handlers.length = 0;
 		this.timers.clear();
@@ -1241,7 +2218,7 @@ var Logger = 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) {
@@ -1387,12 +2364,63 @@ var Logger = class Logger {
 		this.badgeList = [];
 		return 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) {
 		return new ComponentLogger(this, name);
 	}
+	/**
+	* 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) {
 		return new APILogger(this, name);
 	}
+	/**
+	* 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) {
 		return new ScopedLogger(this, name);
 	}
@@ -1593,21 +2621,27 @@ var Logger = class Logger {
 		return this.transportBridge.removeTransport(id);
 	}
 	/**
-	* 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
 	*
 	*/
 	async flushTransports() {
+		forceCloseOpenSpans();
 		await this.transportBridge.flushTransports();
 	}
 	/**
-	* 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
 	*
 	*/
 	async closeTransports() {
+		forceCloseOpenSpans();
 		await this.transportBridge.closeTransports();
 	}
 	/**
@@ -1629,33 +2663,29 @@ var Logger = class Logger {
 		return require_core.LOG_LEVELS[level] >= require_core.LOG_LEVELS[this.config.verbosity];
 	}
 	/**
-	* 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
 	*/
 	_dispatchTag;
 	/**
-	* 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
 	*/
 	_getMergedContext() {
 		let merged = this._parentContextRecord ?? {};
@@ -1670,7 +2700,7 @@ var Logger = class Logger {
 		};
 		return merged;
 	}
-	/** @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() {
 		let merged = this._parentContextRecord ?? {};
 		if (this._bindings && Object.keys(this._bindings).length > 0) merged = {
@@ -1679,6 +2709,21 @@ var Logger = class Logger {
 		};
 		return merged;
 	}
+	/**
+	* 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)
+	*/
 	dispatchToTransports(level, message, prefix, stackInfo, extra) {
 		const record = {
 			level,
@@ -1698,6 +2743,11 @@ var Logger = class Logger {
 			resource: this.logContext._getResource() ? { ...this.logContext._getResource() } : void 0,
 			...extra
 		};
+		const activeSpan = getActiveSpan();
+		if (activeSpan && !record.traceId) {
+			record.traceId = activeSpan.traceId;
+			record.spanId = activeSpan.spanId;
+		}
 		this.transportBridge.writeRecord(record);
 	}
 	/**
@@ -1710,37 +2760,23 @@ var Logger = class Logger {
 		return parts.length > 0 ? parts.join(":") : void 0;
 	}
 	/**
-	* Método central de logging. Awaits the `beforeLog` hook pipeline
-	* synchronously (so redactions / enrichments are reflected in the
-	* emitted message before console + transport dispatch).
-	*
-	* 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).
-	*
-	* @protected
-	* @param level - Nivel del log
-	* @param args - Argumentos a loggear
-	* @returns Promise that resolves once the record has been dispatched
+	* 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.
 	*
-	*/
-	/**
-	* Protected logging method. Awaits the `beforeLog` hook pipeline
-	* synchronously (so redactions / enrichments are reflected in the
-	* emitted message before console + transport dispatch).
+	* 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
-	* @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
+	* @param {LogLevel} level - Nivel del log
+	* @param {unknown[]} args - Argumentos a loggear (mensaje + datos)
+	* @returns {Promise<void>} Promesa que resuelve al completar el dispatch
 	*
 	*/
 	async log(level, ...args) {
@@ -1790,6 +2826,22 @@ var Logger = class Logger {
 		else this.dispatchToTransports(level, message, prefix, stackInfo);
 		this.hookBridge.getHookManager().emit("afterLog", processed).catch(() => {});
 	}
+	/**
+	* Emite un log aplicando bindings (badges, scope) al prefijo del
+	* mensaje antes de delegar en {@link Logger.log}.
+	*
+	* 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.
+	*
+	* @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`
+	*/
 	logWithBindings(bindings, level, ...args) {
 		if (!this.shouldLog(level)) return Promise.resolve();
 		let prefix = "";
@@ -1800,19 +2852,45 @@ var Logger = class Logger {
 		return this.log(level, ...args);
 	}
 	/**
-	* 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, level, tag, ...args) {
 		this._dispatchTag = tag;
 		return this.logWithBindings(bindings, level, ...args);
 	}
+	/**
+	* 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) {
 		return this.log("debug", ...args);
 	}
 	/**
-	* 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
 	*
@@ -1825,7 +2903,7 @@ var Logger = class Logger {
 		return this.log("info", ...args);
 	}
 	/**
-	* Registra mensajes de advertencia. Devuelve `Promise<void>` desde 5.1.0.
+	* Registra mensajes de advertencia.
 	*
 	* @param args - Mensajes de advertencia
 	*
@@ -1834,7 +2912,7 @@ var Logger = class Logger {
 		return this.log("warn", ...args);
 	}
 	/**
-	* Registra mensajes de error. Devuelve `Promise<void>` desde 5.1.0.
+	* Registra mensajes de error.
 	*
 	* @param args - Mensaje de error y stack traces
 	*
@@ -1914,7 +2992,7 @@ var Logger = class Logger {
 		this.log("trace", ...args);
 	}
 	/**
-	* 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
 	*
@@ -1926,6 +3004,104 @@ var Logger = class Logger {
 		return this.log("critical", ...args);
 	}
 	/**
+	* 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, attributes) {
+		emitEventSpan(name, attributes, this._spanScopeName(), (record) => {
+			this.transportBridge.writeRecord(record);
+		});
+	}
+	span(name, fnOrAttributes, maybeFn) {
+		const { attributes, fn } = resolveSpanArgs(fnOrAttributes, maybeFn);
+		return this._runSpan(name, attributes, this._spanScopeName(), fn);
+	}
+	/**
+	* 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, attributes) {
+		return this._startSpan(name, attributes, this._spanScopeName());
+	}
+	/**
+	* Scope por defecto de los spans emitidos por este logger (el
+	* `globalPrefix`, o `'root'`).
+	* @internal
+	*/
+	_spanScopeName() {
+		return this.config.globalPrefix || "root";
+	}
+	/**
+	* Emite un point-span con scope explícito. Lo consume
+	* {@link ScopedLogger.event}, que pasa su scope compuesto.
+	* @internal
+	*/
+	_emitSpanEvent(name, attributes, scope) {
+		emitEventSpan(name, attributes, scope, (record) => {
+			this.transportBridge.writeRecord(record);
+		});
+	}
+	/**
+	* Crea un span externally-ended con scope explícito. Lo consume
+	* {@link ScopedLogger.startSpan}.
+	* @internal
+	*/
+	_startSpan(name, attributes, scope) {
+		const { span } = createSpan(name, attributes, scope, (record) => {
+			this.transportBridge.writeRecord(record);
+		});
+		return span;
+	}
+	/**
+	* Corre `fn` dentro de un span activo en el ALS con scope explícito.
+	* Lo consume {@link ScopedLogger.span}.
+	* @internal
+	*/
+	async _runSpan(name, attributes, scope, fn) {
+		const { record, span } = createSpan(name, attributes, scope, (r) => {
+			this.transportBridge.writeRecord(r);
+		});
+		try {
+			const result = await runWithActiveSpan(record, () => fn(span));
+			span.end();
+			return result;
+		} catch (error) {
+			span.fail(error);
+			throw error;
+		}
+	}
+	/**
 	* Muestra datos en formato de tabla. Pasa por la pipeline completa
 	* (outputMode-respecting writeOutput + transports + hooks).
 	*
@@ -2034,7 +3210,7 @@ var Logger = 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');
@@ -2156,11 +3332,11 @@ var Logger = class Logger {
 		} });
 	}
 	/**
-	* 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...');
@@ -2171,10 +3347,10 @@ var Logger = class Logger {
 		this.terminalBridge.step(current, total, message);
 	}
 	/**
-	* 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');
@@ -2184,7 +3360,7 @@ var Logger = class Logger {
 		this.terminalBridge.header(title, subtitle);
 	}
 	/**
-	* Displays a horizontal divider line
+	* Muestra una línea divisoria horizontal
 	*
 	* @example
 	* logger.divider();
@@ -2194,7 +3370,7 @@ var Logger = class Logger {
 		this.terminalBridge.divider();
 	}
 	/**
-	* Outputs a blank line
+	* Emite una línea en blanco
 	*
 	* @example
 	* logger.blank();
@@ -2204,10 +3380,10 @@ var Logger = class Logger {
 		this.terminalBridge.blank();
 	}
 	/**
-	* 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' });
@@ -2217,11 +3393,11 @@ var Logger = class Logger {
 		this.terminalBridge.box(content, options);
 	}
 	/**
-	* 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([
@@ -2234,11 +3410,11 @@ var Logger = class Logger {
 		this.terminalBridge.cliTable(rows, options);
 	}
 	/**
-	* 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...');
@@ -2251,13 +3427,14 @@ var Logger = class Logger {
 		return this.terminalBridge.spinner(message);
 	}
 	/**
-	* 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) {
@@ -2267,21 +3444,21 @@ var Logger = class Logger {
 		this.config.cliLevel = level;
 	}
 	/**
-	* 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() {
 		return this.config.cliLevel ?? "normal";
 	}
 	/**
-	* 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
 	*/
 	writeOutput(message, level, styles, additionalArgs) {
 		const mode = this.config.outputMode ?? "console";
@@ -2321,21 +3498,20 @@ var Logger = class Logger {
 	}
 };
 /**
-/**
-* Lazy singleton instance — initialised on first call to {@link getDefaultLogger},
-* not on module import. Fixes BUG-N11 (eager side-effect at import time).
+* Instancia singleton lazy — se inicializa en la primera llamada a
+* {@link getDefaultLogger}, no al importar el módulo.
 *
 * @private
 */
 let _defaultLogger = null;
 /**
-* Lazily creates the default Logger singleton.
+* Crea el singleton del Logger por defecto de forma lazy.
 *
-* The singleton is only built on first call, so importing the module
-* never executes `new Logger(...)` or `displayInitBanner()`. This keeps
-* module imports side-effect free.
+* El singleton se construye solo en la primera llamada, de modo que
+* importar el módulo nunca ejecuta `new Logger(...)` ni
+* `displayInitBanner()`. Así los imports del módulo quedan side-effect free.
 *
-* @returns The shared Logger instance
+* @returns La instancia compartida de Logger
 */
 function getDefaultLogger() {
 	if (!_defaultLogger) {
@@ -2358,12 +3534,12 @@ new Proxy({}, { get(_target, prop, receiver) {
 	return typeof value === "function" ? value.bind(instance) : value;
 } });
 /**
-* Narrow a free-form `Record<string, unknown>` context into a typed
-* `ILogAttributes` bag. Unknown shapes fall back to JSON-encoded strings,
-* which keeps the OTLP transport happy (every value lands in a typed slot).
+* Estrecha un contexto free-form `Record<string, unknown>` a un bag tipado
+* `ILogAttributes`. Los shapes desconocidos caen a strings JSON-encoded,
+* lo que mantiene conforme al transport OTLP (cada valor cae en un slot tipado).
 *
-* @param input - The user-supplied context (typically `Logger.context`).
-* @returns A new attribute bag matching `ILogAttributes`.
+* @param input - Contexto suministrado por el usuario (típicamente `Logger.context`).
+* @returns Un nuevo bag de attributes que satisface `ILogAttributes`.
 */
 function toLogAttributes(input) {
 	const out = {};
@@ -2390,6 +3566,23 @@ function toAttributeValue(value) {
 		return;
 	}
 }
+/**
+* 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.
+*/
+function resolveSpanArgs(fnOrAttributes, maybeFn) {
+	if (typeof fnOrAttributes === "function") return {
+		attributes: void 0,
+		fn: fnOrAttributes
+	};
+	if (typeof maybeFn === "function") return {
+		attributes: fnOrAttributes,
+		fn: maybeFn
+	};
+	throw new TypeError("span(name, …): se requiere una función fn");
+}
 //#endregion
 //#region src/index.ts
 /**
@@ -2422,6 +3615,11 @@ const group = (label, collapsed) => getLogger().group(label, collapsed);
 const groupEnd = () => getLogger().groupEnd();
 const time = (label) => getLogger().time(label);
 const timeEnd = (label) => getLogger().timeEnd(label);
+const event = (name, attributes) => getLogger().event(name, attributes);
+const startSpan = (name, attributes) => getLogger().startSpan(name, attributes);
+function span(name, fnOrAttributes, maybeFn) {
+	return getLogger().span(name, fnOrAttributes, maybeFn);
+}
 const setGlobalPrefix = (prefix) => getLogger().setGlobalPrefix(prefix);
 const scope = (name) => getLogger().scope(name);
 const component = (name) => getLogger().component(name);
@@ -2480,6 +3678,7 @@ exports.critical = critical;
 exports.debug = debug;
 exports.default = src_default;
 exports.error = error;
+exports.event = event;
 exports.flushTransports = flushTransports;
 exports.formatLogLevelANSI = require_utils.formatLogLevelANSI;
 exports.formatSuccessANSI = require_utils.formatSuccessANSI;
@@ -2510,6 +3709,8 @@ exports.setGlobalPrefix = setGlobalPrefix;
 exports.setTheme = setTheme;
 exports.setVerbosity = setVerbosity;
 exports.showBanner = showBanner;
+exports.span = span;
+exports.startSpan = startSpan;
 exports.success = success;
 exports.supportsANSI = require_environment_detector.supportsANSI;
 exports.table = table;