@bereasoftware/nexa 1.4.1 → 1.5.0

package/README.en.md

@@ -2,13 +2,13 @@
   <img src="assets/Logo.png" alt="Nexa Logo" width="120" height="120" />
   <h1 align="center">@bereasoftware/nexa</h1>
   <p align="center">
-    A modern, type-safe HTTP client that combines the power of <code>fetch</code> with the convenience of <code>axios</code> — built on SOLID principles.
+    A modern, type-safe HTTP client that combines the power of <code>fetch</code> with the convenience of <code>axios</code>, and adds built-in development observability through <code>Dev Overlay</code>.
   </p>
 </p>
 
 <p align="center">
-  <a href="#tests"><img src="https://img.shields.io/badge/Tests-213_passing-brightgreen?style=for-the-badge" alt="Tests" /></a>
-  <a href="#test-coverage"><img src="https://img.shields.io/badge/Coverage-See_report-orange?style=for-the-badge" alt="Coverage" /></a>
+  <a href="#tests"><img src="https://img.shields.io/badge/Tests-219_passing-brightgreen?style=for-the-badge" alt="Tests" /></a>
+  <a href="#test-coverage"><img src="https://img.shields.io/badge/Coverage-See_report-orange?style=for-the-badge" alt="Coverage" /></a>
   <a href="https://www.npmjs.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/npm/v/@bereasoftware/nexa?style=for-the-badge" alt="NPM Version" /></a>
   <a href="https://bundlephobia.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/bundlephobia/minzip/@bereasoftware/nexa?label=Bundle&style=for-the-badge" alt="Bundle Size" /></a>
   <a href="https://www.npmjs.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/npm/dm/@bereasoftware/nexa?style=for-the-badge" alt="NPM Downloads" /></a>
@@ -37,6 +37,20 @@
 
 ---
 
+## Positioning
+
+Nexa is not trying to be just another `fetch` wrapper.
+
+The library is designed to combine three concerns in one package:
+
+- a type-safe HTTP API with zero runtime dependencies
+- real extensibility through retries, caching, middleware, and plugins
+- built-in development observability through `Dev Overlay`
+
+That makes it useful not only as an HTTP client, but also as a foundation for SDKs, internal tooling, and workflows where debugging experience matters.
+
+---
+
 ## Why Nexa?
 
 | Feature                         | `fetch` | `axios` | **Nexa** |
@@ -954,11 +968,11 @@ manager.register(rateLimitPlugin);
 
 ---
 
-## Dev Overlay
-
-Built-in visual development tool for debugging and monitoring HTTP requests in real-time.
-
-> API status: publicly available and intended for browser development flows. It is not designed for SSR or Node runtimes without a DOM.
+## Dev Overlay
+
+Built-in visual development tool for debugging and monitoring HTTP requests in real-time.
+
+> API status: publicly available and intended for browser development flows. It is not designed for SSR or Node runtimes without a DOM.
 
 ```typescript
 import { createHttpClient, createDevOverlay } from "@bereasoftware/nexa";
@@ -980,102 +994,106 @@ const client = createHttpClient({
 const result = await client.get("/users");
 ```
 
-### Features
-
-- **Keyboard toggle** — Press `Ctrl+Shift+N` or `Cmd+Shift+N` to show/hide
-- **Request list** — Shows method, status, URL, duration and badges (cache, retries)
-- **Real-time metrics** — Total requests, average, throughput, success, failed
-- **Search and filter** — Filter by URL, method or status (`Ctrl+F`)
-- **Request detail** — Click any request to see headers, body and timing
-- **Quick retry** — Replays the selected URL with `fetch` for fast verification
-- **Keyboard shortcuts** — `Ctrl+Shift+N` / `Cmd+Shift+N` (toggle), `Escape` (close), `Ctrl+F` / `Cmd+F` (search)
+### Features
+
+- **Keyboard toggle** — Press `Ctrl+Shift+N` or `Cmd+Shift+N` to show/hide
+- **Request list** — Shows method, status, URL, duration and badges (cache, retries)
+- **Real-time metrics** — Total requests, average, throughput, success, failed
+- **Search and filter** — Filter by URL, method or status (`Ctrl+F`)
+- **Request detail** — Click any request to see headers, body and timing
+- **Quick retry** — Replays the selected URL with `fetch` for fast verification
+- **Keyboard shortcuts** — `Ctrl+Shift+N` / `Cmd+Shift+N` (toggle), `Escape` (close), `Ctrl+F` / `Cmd+F` (search)
 
 ### API
 
 ```typescript
-createDevOverlay(config?: DevOverlayConfig): { tracker: RequestTracker; ui: DevOverlayUI }
+createDevOverlay(config?: DevOverlayConfig): { tracker: RequestTracker; ui: DevOverlayUI; config: Required<DevOverlayConfig> }
+```
+
+**Configuration options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Tracker-level flag you can use to enable or disable the overlay flow in your app |
+| `position` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Overlay position |
+| `theme` | `'dark' \| 'light'` | `'dark'` | Typed visual theme; the current UI is optimized for dark mode |
+| `maxHistory` | `number` | `500` | Maximum requests in history |
+| `keyboardShortcut` | `string` | `'ctrl+shift+n'` | Keyboard shortcut |
+| `devOnly` | `boolean` | `true` | When true the UI mounts only in development environments (NODE_ENV=development or localhost) |
+| `floatingButtonSize` | `number` | `64` | Floating button width & height in pixels |
+| `floatingButtonOffset` | `number` | `24` | Offset from viewport edges in pixels |
+| `floatingButtonTheme` | `'inherit' \| 'dark' \| 'light'` | `'inherit'` | Floating button theme; `'inherit'` uses the overlay `theme` |
+
+**Behavior notes:**
+
+- `createDevOverlay()` is a singleton. Multiple calls reuse the same instance.
+- The overlay only mounts UI when a DOM is available. In SSR or Node you can import the module safely, but no panel is rendered.
+- `theme` is typed as `'dark' | 'light'`, but the current UI is primarily designed for dark mode.
+- The retry button uses direct `fetch()` for quick revalidation; it does not automatically replay interceptors or advanced `HttpClient` configuration.
+- `destroyDevOverlay()` clears the singleton instance, removes the panel, and unregisters the global listeners used by the overlay.
+
+**Note:** Advanced request options such as `transformRequest`, `credentials`, `withCredentials`, `debug`, `logger`, `transport`, `nodeOptions`, and `autoFormData` are already typed, but not all of them are fully wired into the main `HttpClient` pipeline in this release.
+
+**UI methods:**
+
+```typescript
+ui.show()   // Show overlay
+ui.hide()    // Hide overlay
+ui.toggle()  // Toggle visibility
+ui.destroy() // Remove the panel from the DOM
+
+tracker.clear()          // Clear history
+tracker.getHistory()      // Get all requests
+tracker.getMetrics()      // Get metrics
+tracker.getConfig()       // Get resolved config
+tracker.onChange((request) => {}) // Listen for new tracked requests
+```
+
+**Module methods:**
+
+```typescript
+getDevOverlay() // Get current { tracker, ui } or null if not created yet
+destroyDevOverlay() // Destroy the current singleton instance
 ```
 
-**Configuration options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enabled` | `boolean` | `true` | Tracker-level flag you can use to enable or disable the overlay flow in your app |
-| `position` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Overlay position |
-| `theme` | `'dark' \| 'light'` | `'dark'` | Typed visual theme; the current UI is optimized for dark mode |
-| `maxHistory` | `number` | `500` | Maximum requests in history |
-| `keyboardShortcut` | `string` | `'ctrl+shift+n'` | Keyboard shortcut |
-
-**Behavior notes:**
-
-- `createDevOverlay()` is a singleton. Multiple calls reuse the same instance.
-- The overlay only mounts UI when a DOM is available. In SSR or Node you can import the module safely, but no panel is rendered.
-- `theme` is typed as `'dark' | 'light'`, but the current UI is primarily designed for dark mode.
-- The retry button uses direct `fetch()` for quick revalidation; it does not automatically replay interceptors or advanced `HttpClient` configuration.
-- `destroyDevOverlay()` clears the singleton instance, removes the panel, and unregisters the global listeners used by the overlay.
-
-**Note:** Advanced request options such as `transformRequest`, `credentials`, `withCredentials`, `debug`, `logger`, `transport`, `nodeOptions`, and `autoFormData` are already typed, but not all of them are fully wired into the main `HttpClient` pipeline in this release.
-
-**UI methods:**
-
-```typescript
-ui.show()   // Show overlay
-ui.hide()    // Hide overlay
-ui.toggle()  // Toggle visibility
-ui.destroy() // Remove the panel from the DOM
-
-tracker.clear()          // Clear history
-tracker.getHistory()      // Get all requests
-tracker.getMetrics()      // Get metrics
-tracker.getConfig()       // Get resolved config
-tracker.onChange((request) => {}) // Listen for new tracked requests
-```
-
-**Module methods:**
-
-```typescript
-getDevOverlay() // Get current { tracker, ui } or null if not created yet
-destroyDevOverlay() // Destroy the current singleton instance
-```
-
-**When to use each export:**
-
-- `createDevOverlay()` creates or reuses the overlay and returns the `tracker` you pass into `createHttpClient({ devTracker })`.
-- `getDevOverlay()` lets you inspect the current instance without creating a new one.
-- `destroyDevOverlay()` is useful for full teardown during hot reloads, tests, or manual cleanup.
-- `RequestTracker` can be used on its own if you want request history and metrics without mounting the UI.
-
-**Exposed data shapes:**
-
-```typescript
-type TrackedRequest = {
-  id: string;
-  method: string;
-  url: string;
-  status?: number;
-  duration: number;
-  timestamp: number;
-  cached: boolean;
-  ok: boolean;
-  code?: string;
-  headers: Record<string, string>;
-  body?: unknown;
-  responseHeaders?: Record<string, string>;
-  retryCount: number;
-};
-
-type DevMetrics = {
-  totalRequests: number;
-  successfulRequests: number;
-  failedRequests: number;
-  cachedRequests: number;
-  avgDuration: number;
-  maxDuration: number;
-  minDuration: number;
-  requestsPerSecond: number;
-  slowestRequests: TrackedRequest[];
-};
-```
+**When to use each export:**
+
+- `createDevOverlay()` creates or reuses the overlay and returns the `tracker` you pass into `createHttpClient({ devTracker })`.
+- `getDevOverlay()` lets you inspect the current instance without creating a new one.
+- `destroyDevOverlay()` is useful for full teardown during hot reloads, tests, or manual cleanup.
+- `RequestTracker` can be used on its own if you want request history and metrics without mounting the UI.
+
+**Exposed data shapes:**
+
+```typescript
+type TrackedRequest = {
+  id: string;
+  method: string;
+  url: string;
+  status?: number;
+  duration: number;
+  timestamp: number;
+  cached: boolean;
+  ok: boolean;
+  code?: string;
+  headers: Record<string, string>;
+  body?: unknown;
+  responseHeaders?: Record<string, string>;
+  retryCount: number;
+};
+
+type DevMetrics = {
+  totalRequests: number;
+  successfulRequests: number;
+  failedRequests: number;
+  cachedRequests: number;
+  avgDuration: number;
+  maxDuration: number;
+  minDuration: number;
+  requestsPerSecond: number;
+  slowestRequests: TrackedRequest[];
+};
+```
 
 ---
 
@@ -1336,11 +1354,11 @@ Nexa ships in multiple module formats:
 
 ## Development
 
-### Tests
-
-```bash
-# Run all tests
-npm test
+### Tests
+
+```bash
+# Run all tests
+npm test
 
 # Watch mode
 npm run test:watch
@@ -1412,15 +1430,15 @@ See the `examples/` folder for usage examples with different frameworks:
 - `svelte-example.ts` — Usage with Svelte
 - `node-example.ts` — Usage with Node.js
 
-### Test Coverage
-
-Generate the latest report locally:
-
-```bash
-npm run test:coverage
-```
-
-Coverage changes as features evolve, so the generated report should be treated as the source of truth instead of hardcoded percentages in the README.
+### Test Coverage
+
+Generate the latest report locally:
+
+```bash
+npm run test:coverage
+```
+
+Coverage changes as features evolve, so the generated report should be treated as the source of truth instead of hardcoded percentages in the README.
 
 ---
 

package/README.md

@@ -2,13 +2,13 @@
   <img src="src/assets/Logo.png" alt="Nexa Logo" />
   <h1 align="center">@bereasoftware/nexa</h1>
   <p align="center">
-    Un cliente HTTP moderno y type-safe que combina el poder de <code>fetch</code> con la comodidad de <code>axios</code> — construido sobre principios SOLID.
+    Un cliente HTTP moderno y type-safe que combina el poder de <code>fetch</code> con la comodidad de <code>axios</code>, y añade observabilidad integrada para desarrollo con <code>Dev Overlay</code>.
   </p>
 </p>
 
 <p align="center">
-  <a href="#tests"><img src="https://img.shields.io/badge/Tests-213_pasando-brightgreen?style=for-the-badge" alt="Tests" /></a>
-  <a href="#test-coverage"><img src="https://img.shields.io/badge/Coverage-Ver_reporte-orange?style=for-the-badge" alt="Coverage" /></a>
+  <a href="#tests"><img src="https://img.shields.io/badge/Tests-219_pasando-brightgreen?style=for-the-badge" alt="Tests" /></a>
+  <a href="#test-coverage"><img src="https://img.shields.io/badge/Coverage-Ver_reporte-orange?style=for-the-badge" alt="Coverage" /></a>
   <a href="https://www.npmjs.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/npm/v/@bereasoftware/nexa?style=for-the-badge" alt="NPM Version" /></a>
   <a href="https://bundlephobia.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/bundlephobia/minzip/@bereasoftware/nexa?label=Bundle&style=for-the-badge" alt="Bundle Size" /></a>
   <a href="https://www.npmjs.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/npm/dm/@bereasoftware/nexa?style=for-the-badge" alt="NPM Downloads" /></a>
@@ -37,6 +37,20 @@
 
 ---
 
+## Posicionamiento
+
+Nexa no busca ser solo otro wrapper de `fetch`.
+
+La librería está diseñada para combinar tres cosas en un solo paquete:
+
+- una API HTTP type-safe y sin dependencias runtime
+- extensibilidad real con retries, caché, middlewares y plugins
+- observabilidad integrada para desarrollo con `Dev Overlay`
+
+Eso la hace útil no solo como cliente HTTP, sino también como base para SDKs, tooling interno y flujos donde la experiencia de depuración importa.
+
+---
+
 ## ¿Por qué Nexa?
 
 | Característica                             | `fetch` | `axios` | **Nexa** |
@@ -60,11 +74,11 @@
 | Validadores y transformadores              |   ❌    |   ❌    |    ✅    |
 | Tracking de duración de respuesta          |   ❌    |   ❌    |    ✅    |
 | Detección inteligente de tipo de respuesta |   ❌    |   ✅    |    ✅    |
-| WebSocket/SSE con reconexión automática    |   ❌    |   ❌    |    ✅    |
-| Rate limiting integrado                    |   ❌    |   ❌    |    ✅    |
-| Circuit breaker para fallos en cascada     |   ❌    |   ❌    |    ✅    |
-| Tree-shakeable                             |   ✅    |   ❌    |    ✅    |
-| Dev Overlay (herramientas de desarrollo)   |   ❌    |   ❌    |    ✅    |
+| WebSocket/SSE con reconexión automática    |   ❌    |   ❌    |    ✅    |
+| Rate limiting integrado                    |   ❌    |   ❌    |    ✅    |
+| Circuit breaker para fallos en cascada     |   ❌    |   ❌    |    ✅    |
+| Tree-shakeable                             |   ✅    |   ❌    |    ✅    |
+| Dev Overlay (herramientas de desarrollo)   |   ❌    |   ❌    |    ✅    |
 
 ---
 
@@ -231,12 +245,12 @@ const client = createHttpClient({
 | `maxConcurrent`       | `number`                      | `0` (ilimitado)                          | Máximo de peticiones concurrentes                            |
 | `defaultResponseType` | `ResponseType`                | `'auto'`                                 | Estrategia de parseo de respuesta por defecto                |
 | `defaultHooks`        | `RequestHooks`                | `{}`                                     | Hooks de ciclo de vida por defecto para todas las peticiones |
-| `debug`               | `boolean \| 'verbose'`        | `undefined`                              | Habilita logging de debug para requests/responses. `true` para logs básicos, `'verbose'` para logs detallados. |
-| `logger`              | `(message: string, data?: unknown) => void` | `undefined`                              | Función de logging personalizada. Si se proporciona, reemplaza el console.log por defecto con logging personalizado. |
-
-**Nota:** Las opciones avanzadas `transformRequest`, `credentials`, `withCredentials`, `debug`, `logger`, `transport`, `nodeOptions` y `autoFormData` ya están tipadas, pero no todas están completamente integradas en el pipeline principal de `HttpClient` en esta versión. Úsalas con validación manual hasta que se cierre esa integración.
-
----
+| `debug`               | `boolean \| 'verbose'`        | `undefined`                              | Habilita logging de debug para requests/responses. `true` para logs básicos, `'verbose'` para logs detallados. |
+| `logger`              | `(message: string, data?: unknown) => void` | `undefined`                              | Función de logging personalizada. Si se proporciona, reemplaza el console.log por defecto con logging personalizado. |
+
+**Nota:** Las opciones avanzadas `transformRequest`, `credentials`, `withCredentials`, `debug`, `logger`, `transport`, `nodeOptions` y `autoFormData` ya están tipadas, pero no todas están completamente integradas en el pipeline principal de `HttpClient` en esta versión. Úsalas con validación manual hasta que se cierre esa integración.
+
+---
 
 ## Métodos HTTP
 
@@ -370,7 +384,7 @@ await client.post('/api', data, { withCredentials: true });
 
 // Configuración global
 const client = createHttpClient({
-  credentials: 'same-origin',
+  credentials: 'same-origin',
   // o
   withCredentials: true, // Equivalente a credentials: 'include'
 });
@@ -604,7 +618,7 @@ await client.post('/api', data, {
 
 El logger recibe dos argumentos: el mensaje de log (con prefijo `[Nexa HTTP]`) y un objeto de datos opcional.
 
----
+---
 
 ## Estrategias de Reintentos
 
@@ -1291,11 +1305,11 @@ manager.register(rateLimitPlugin);
 
 ---
 
-## Dev Overlay
-
-Herramienta visual de desarrollo integrada para depurar y monitorear requests HTTP en tiempo real.
-
-> Estado de API: disponible públicamente y pensada para flujos de desarrollo en navegador. No está orientada a entornos SSR o Node sin DOM.
+## Dev Overlay
+
+Herramienta visual de desarrollo integrada para depurar y monitorear requests HTTP en tiempo real.
+
+> Estado de API: disponible públicamente y pensada para flujos de desarrollo en navegador. No está orientada a entornos SSR o Node sin DOM.
 
 ```typescript
 import { createHttpClient, createDevOverlay } from "@bereasoftware/nexa";
@@ -1319,98 +1333,115 @@ const result = await client.get("/users");
 
 ### Características
 
-- **Toggle con teclado** — Presiona `Ctrl+Shift+N` o `Cmd+Shift+N` para mostrar/ocultar
-- **Lista de requests** — Muestra método, status, URL, duración y badges (cache, retries)
-- **Métricas en tiempo real** — Total requests, promedio, throughput, éxitos y fallos
-- **Búsqueda y filtro** — Filtra por URL, método o status (`Ctrl+F`)
-- **Detalle de request** — Click en cualquier request para ver headers, body y timing
-- **Retry rápido** — Reejecuta la URL seleccionada con `fetch` para una verificación rápida
-- **Keyboard shortcuts** — `Ctrl+Shift+N` / `Cmd+Shift+N` (toggle), `Escape` (cerrar), `Ctrl+F` / `Cmd+F` (buscar)
+- **Toggle con teclado** — Presiona `Ctrl+Shift+N` o `Cmd+Shift+N` para mostrar/ocultar
+- **Lista de requests** — Muestra método, status, URL, duración y badges (cache, retries)
+- **Métricas en tiempo real** — Total requests, promedio, throughput, éxitos y fallos
+- **Búsqueda y filtro** — Filtra por URL, método o status (`Ctrl+F`)
+- **Detalle de request** — Click en cualquier request para ver headers, body y timing
+
+### Persistencia de configuración
+
+El `Dev Overlay` persiste la configuración del usuario (posición, tema, tamaño del botón flotante, etc.) en `localStorage` bajo la clave `nexa.devOverlay.config`.
+
+
+Al llamar a `createDevOverlay()` la configuración que se aplica sigue el orden de preferencia (los valores persistidos en `localStorage` tienen prioridad por diseño):
+
+- Valores por defecto ← (`defaultDevOverlayConfig`)
+- Opciones pasadas a `createDevOverlay()` (argumento `config`)
+- Valores persistidos en `localStorage` (sobrescriben los anteriores)
+
+En entornos sin DOM (por ejemplo, durante tests en Node) el componente visual no se monta, pero el `tracker` sigue inicializándose y respeta la carga y persistencia de la configuración.
+- **Retry rápido** — Reejecuta la URL seleccionada con `fetch` para una verificación rápida
+- **Keyboard shortcuts** — `Ctrl+Shift+N` / `Cmd+Shift+N` (toggle), `Escape` (cerrar), `Ctrl+F` / `Cmd+F` (buscar)
 
 ### API
 
 ```typescript
-createDevOverlay(config?: DevOverlayConfig): { tracker: RequestTracker; ui: DevOverlayUI }
-```
-
-**Opciones de configuración:**
-
-| Opción | Tipo | Por defecto | Descripción |
-|--------|------|-------------|-------------|
-| `enabled` | `boolean` | `true` | Flag de configuración almacenado por el tracker para habilitar o deshabilitar el overlay desde tu flujo |
-| `position` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Posición del overlay |
-| `theme` | `'dark' \| 'light'` | `'dark'` | Tema visual tipado; la UI actual está optimizada para el tema oscuro |
-| `maxHistory` | `number` | `500` |Máximo de requests en historial |
-| `keyboardShortcut` | `string` | `'ctrl+shift+n'` | Atajo de teclado |
-
-**Notas de comportamiento:**
-
-- `createDevOverlay()` es singleton. Si lo llamas varias veces, reutiliza la misma instancia.
-- El overlay solo monta UI cuando hay DOM disponible. En SSR o Node puedes importar el módulo sin romper el proceso, pero no se renderiza panel.
-- `theme` está tipado como `'dark' | 'light'`, pero la UI actual está diseñada principalmente para tema oscuro.
-- El botón de retry del panel usa `fetch()` directo para revalidación rápida; no reaplica automáticamente interceptores ni configuración avanzada del `HttpClient`.
-- `destroyDevOverlay()` limpia la instancia singleton, desmonta el panel y remueve listeners globales registrados por el overlay.
-
-**Métodos del UI:**
-
-```typescript
-ui.show()   // Mostrar overlay
-ui.hide()   // Ocultar overlay
-ui.toggle() // Alternar visibilidad
-ui.destroy() // Desmontar el panel del DOM
-
-tracker.clear() // Limpiar historial
-tracker.getHistory() // Obtener todos los requests
-tracker.getMetrics() // Obtener métricas
-tracker.getConfig() // Obtener configuración resuelta
-tracker.onChange((request) => {}) // Escuchar nuevos requests
-```
-
-**Métodos del módulo:**
-
-```typescript
-getDevOverlay() // Obtener { tracker, ui } actuales o null si no existen
-destroyDevOverlay() // Destruir la instancia singleton actual
-```
-
-**Cuándo usar cada export:**
-
-- `createDevOverlay()` crea o reutiliza el overlay y devuelve el `tracker` que debes pasar a `createHttpClient({ devTracker })`.
-- `getDevOverlay()` te permite consultar la instancia actual sin crear una nueva.
-- `destroyDevOverlay()` sirve para cerrar completamente la herramienta en hot reloads, tests o limpieza manual.
-- `RequestTracker` puede usarse por separado si quieres recolectar historial y métricas sin montar la UI.
-
-**Estructuras expuestas:**
-
-```typescript
-type TrackedRequest = {
-  id: string;
-  method: string;
-  url: string;
-  status?: number;
-  duration: number;
-  timestamp: number;
-  cached: boolean;
-  ok: boolean;
-  code?: string;
-  headers: Record<string, string>;
-  body?: unknown;
-  responseHeaders?: Record<string, string>;
-  retryCount: number;
-};
-
-type DevMetrics = {
-  totalRequests: number;
-  successfulRequests: number;
-  failedRequests: number;
-  cachedRequests: number;
-  avgDuration: number;
-  maxDuration: number;
-  minDuration: number;
-  requestsPerSecond: number;
-  slowestRequests: TrackedRequest[];
-};
-```
+createDevOverlay(config?: DevOverlayConfig): { tracker: RequestTracker; ui: DevOverlayUI; config: Required<DevOverlayConfig> }
+```
+
+**Opciones de configuración:**
+
+| Opción | Tipo | Por defecto | Descripción |
+|--------|------|-------------|-------------|
+| `enabled` | `boolean` | `true` | Flag de configuración almacenado por el tracker para habilitar o deshabilitar el overlay desde tu flujo |
+| `position` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Posición del overlay |
+| `theme` | `'dark' \| 'light'` | `'dark'` | Tema visual tipado; la UI actual está optimizada para el tema oscuro |
+| `maxHistory` | `number` | `500` |Máximo de requests en historial |
+| `keyboardShortcut` | `string` | `'ctrl+shift+n'` | Atajo de teclado |
+| `devOnly` | `boolean` | `true` | Cuando es true, la UI solo se monta en entornos de desarrollo (NODE_ENV=development o localhost) |
+| `floatingButtonSize` | `number` | `64` | Tamaño (ancho & alto) del botón flotante en píxeles |
+| `floatingButtonOffset` | `number` | `24` | Offset desde los bordes de la ventana en píxeles |
+| `floatingButtonTheme` | `'inherit' \| 'dark' \| 'light'` | `'inherit'` | Tema del botón flotante; `'inherit'` usa el `theme` del overlay |
+
+**Notas de comportamiento:**
+
+- `createDevOverlay()` es singleton. Si lo llamas varias veces, reutiliza la misma instancia.
+- El overlay solo monta UI cuando hay DOM disponible. En SSR o Node puedes importar el módulo sin romper el proceso, pero no se renderiza panel.
+- `theme` está tipado como `'dark' | 'light'`, pero la UI actual está diseñada principalmente para tema oscuro.
+- El botón de retry del panel usa `fetch()` directo para revalidación rápida; no reaplica automáticamente interceptores ni configuración avanzada del `HttpClient`.
+- `destroyDevOverlay()` limpia la instancia singleton, desmonta el panel y remueve listeners globales registrados por el overlay.
+
+**Métodos del UI:**
+
+```typescript
+ui.show()   // Mostrar overlay
+ui.hide()   // Ocultar overlay
+ui.toggle() // Alternar visibilidad
+ui.destroy() // Desmontar el panel del DOM
+
+tracker.clear() // Limpiar historial
+tracker.getHistory() // Obtener todos los requests
+tracker.getMetrics() // Obtener métricas
+tracker.getConfig() // Obtener configuración resuelta
+tracker.onChange((request) => {}) // Escuchar nuevos requests
+```
+
+**Métodos del módulo:**
+
+```typescript
+getDevOverlay() // Obtener { tracker, ui } actuales o null si no existen
+destroyDevOverlay() // Destruir la instancia singleton actual
+```
+
+**Cuándo usar cada export:**
+
+- `createDevOverlay()` crea o reutiliza el overlay y devuelve el `tracker` que debes pasar a `createHttpClient({ devTracker })`.
+- `getDevOverlay()` te permite consultar la instancia actual sin crear una nueva.
+- `destroyDevOverlay()` sirve para cerrar completamente la herramienta en hot reloads, tests o limpieza manual.
+- `RequestTracker` puede usarse por separado si quieres recolectar historial y métricas sin montar la UI.
+
+**Estructuras expuestas:**
+
+```typescript
+type TrackedRequest = {
+  id: string;
+  method: string;
+  url: string;
+  status?: number;
+  duration: number;
+  timestamp: number;
+  cached: boolean;
+  ok: boolean;
+  code?: string;
+  headers: Record<string, string>;
+  body?: unknown;
+  responseHeaders?: Record<string, string>;
+  retryCount: number;
+};
+
+type DevMetrics = {
+  totalRequests: number;
+  successfulRequests: number;
+  failedRequests: number;
+  cachedRequests: number;
+  avgDuration: number;
+  maxDuration: number;
+  minDuration: number;
+  requestsPerSecond: number;
+  slowestRequests: TrackedRequest[];
+};
+```
 
 ---
 
@@ -1564,7 +1595,7 @@ deferred.reject(new Error("falló"));
 
 ### Contexto de Error Enriquecido
 
-`HttpErrorDetails` incluye campos opcionales para `request`, `response` y `config`, pero en esta versión no todos los caminos de error los rellenan de forma consistente. Úsalos como metadatos opcionales, no como garantía fuerte.
+`HttpErrorDetails` incluye campos opcionales para `request`, `response` y `config`, pero en esta versión no todos los caminos de error los rellenan de forma consistente. Úsalos como metadatos opcionales, no como garantía fuerte.
 
 ```typescript
 const result = await client.get('/api');
@@ -1576,7 +1607,7 @@ if (!result.ok) {
 }
 ```
 
-Si necesitas ese contexto en todos los errores, conviene complementarlo temporalmente con hooks o interceptores propios.
+Si necesitas ese contexto en todos los errores, conviene complementarlo temporalmente con hooks o interceptores propios.
 
 ### Clase HttpError