# Referencia de carga, caché y diagnóstico
Carga dinámica, prioridades, overrides, caché, estilos y observación del runtime.
## Elegir el nivel de carga
Usa `wu.mount` para el ciclo de vida completo. `wu.prefetch` anticipa recursos de aplicaciones registradas y `wu.use` carga componentes publicados mediante exports. `WuLoader` es un cargador independiente: no sustituye el catálogo, el sandbox ni los grants del core.
Los overrides y las herramientas de inspección pertenecen al host. Una métrica mide un tramo observado; no garantiza que el navegador haya terminado de pintar. Consulta [carga de aplicaciones](/es/docs/framework/loading/) y [diagnóstico](/es/docs/framework/troubleshooting/) para el flujo completo.
## wu.use
Carga una exportación de componente declarada por otra aplicación.
`wu.use("app.component"): Promise`
- **Parámetros:** Nombre exacto app.component; el manifest proveedor debe declarar wu.exports.
- **Retorno:** default export cuando existe, o namespace del módulo.
- **Errores:** App/export ausentes, traversal, URL inválida o import fallido rechazan.
- **Permisos:** Host; un componente cargado ejecuta código en el realm del consumidor.
- **Limpieza:** La instancia del renderer que use el componente administra su cleanup.
```js
const ProductCard = await wu.use('catalog.ProductCard');
```
Método presente en runtime pero ausente de la declaración WuCore. No convierte componentes entre frameworks.
Referencia: `src/core/wu-core.js`.
## wu.prefetchAll
Solicita precarga para todas las aplicaciones registradas.
`wu.prefetchAll(options?): Promise | (() => void)`
- **Parámetros:** Mismas opciones de disparador que prefetch.
- **Retorno:** Promesa inmediata o cleanup de disparadores diferidos.
- **Errores:** La precarga es una solicitud al navegador; no confirma que un renderer pueda montar.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** Conserva el cleanup si eliges un disparador diferido.
```js
await wu.prefetchAll({ on: 'immediate' });
```
Referencia: `src/core/wu-prefetch.js`.
## new WuLoader
Crea un loader de código y componentes con caché y deduplicación en vuelo.
`new WuLoader({ maxCacheSize?, cacheTTL? }?): WuLoader`
- **Parámetros:** maxCacheSize limita el número de entradas (50 por defecto); cacheTTL expresa milisegundos (1800000 por defecto).
- **Retorno:** Instancia con loadApp, loadComponent, preload, isAvailable y clearCache.
- **Errores:** No registra apps ni ejecuta el lifecycle por construirlo.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** loader.clearCache() libera sus entradas cacheadas.
```js
import { WuLoader } from 'wu-framework';
const loader = new WuLoader({ maxCacheSize: 20, cacheTTL: 60000 });
```
Referencia: `src/core/wu-loader.js`.
## WuLoader.loadApp
Descarga texto de código de un entry para el pipeline de carga.
`loader.loadApp(appUrl, manifest?): Promise`
- **Parámetros:** Base URL y manifest con entry opcional.
- **Retorno:** String con código; no ejecuta mount ni registra la app.
- **Errores:** Fetch fallido, respuesta no válida o resolución de entry fallida rechazan.
- **Permisos:** Host; sujeto a acceso de red del entorno.
- **Limpieza:** clearCache(base) descarta lecturas futuras cacheadas.
```js
const code = await loader.loadApp('/apps/catalog', { entry: 'entry.js' });
```
Referencia: `src/core/wu-loader.js`.
## WuLoader.loadComponent
Importa un componente confinado a la base de una app.
`loader.loadComponent(appUrl, componentPath): Promise`
- **Parámetros:** Base y ruta relativa de componente; no URLs absolutas ni traversal.
- **Retorno:** default export o namespace importado.
- **Errores:** Ruta fuera de base o import fallido rechaza.
- **Permisos:** El módulo ejecuta código del mismo contexto; no es RPC scoped.
- **Limpieza:** El import nativo conserva su caché de módulos.
```js
const card = await loader.loadComponent('/apps/catalog', 'components/card.js');
```
Referencia: `src/core/wu-loader.js`.
## WuLoader.preload
Anticipa la descarga de código para una lista de aplicaciones.
`loader.preload(appConfigs: WuAppConfig[]): Promise`
- **Parámetros:** Array de configuraciones con name y url.
- **Retorno:** Promesa de finalización del recorrido de precarga.
- **Errores:** La precarga captura fallos por app; inspecciona la disponibilidad antes del montaje.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No monta renderers; clearCache libera texto cacheado.
```js
await loader.preload([{ name: 'catalog', url: '/apps/catalog' }]);
```
Referencia: `src/core/wu-loader.js`.
## WuLoader.isAvailable
Consulta si una URL responde correctamente a HEAD.
`loader.isAvailable(url): Promise`
- **Parámetros:** URL a comprobar.
- **Retorno:** Booleano; errores de red se convierten en false.
- **Errores:** Un servidor que rechaza HEAD puede devolver false aunque GET funcione.
- **Permisos:** Acceso de red del host.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
const available = await loader.isAvailable('/apps/catalog/entry.js');
```
Referencia: `src/core/wu-loader.js`.
## WuLoader.clearCache
Descarta el texto y registros cacheados del loader.
`loader.clearCache(pattern?): void`
- **Parámetros:** Patrón opcional; sin patrón vacía la caché del loader.
- **Retorno:** void.
- **Errores:** No invalida el caché ESM del navegador.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
loader.clearCache('catalog');
```
Referencia: `src/core/wu-loader.js`.
## WuLoader.getStats
Consulta caché e imports en vuelo del loader.
`loader.getStats(): object`
- **Parámetros:** Sin argumentos.
- **Retorno:** Objeto de métricas.
- **Errores:** No representa el estado montado de apps.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
console.log(loader.getStats());
```
Referencia: `src/core/wu-loader.js`.
## wu.override
Configura una sustitución de URL para desarrollo.
`wu.override(name, url, options?): void`
- **Parámetros:** name y URL autorizada; options.maxAge/path configuran persistencia del override.
- **Retorno:** void
- **Errores:** El sistema valida dominios y configuración; el override no es un remount automático.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** Retira overrides de desarrollo antes de compartir una sesión.
```js
wu.override('catalog', 'http://localhost:4101');
```
Referencia: `src/core/wu-overrides.js`.
## wu.removeOverride
Retira una sustitución de URL.
`wu.removeOverride(name): void`
- **Parámetros:** Nombre exacto de app.
- **Retorno:** void
- **Errores:** El sistema valida dominios y configuración; el override no es un remount automático.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** Retira overrides de desarrollo antes de compartir una sesión.
```js
wu.removeOverride('catalog');
```
Referencia: `src/core/wu-overrides.js`.
## wu.getOverrides
Consulta las sustituciones de URL activas.
`wu.getOverrides(): Record`
- **Parámetros:** Sin argumentos.
- **Retorno:** Record
- **Errores:** El sistema valida dominios y configuración; el override no es un remount automático.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** Retira overrides de desarrollo antes de compartir una sesión.
```js
console.log(wu.getOverrides());
```
Referencia: `src/core/wu-overrides.js`.
## wu.clearOverrides
Retira todas las sustituciones activas.
`wu.clearOverrides(): void`
- **Parámetros:** Sin argumentos.
- **Retorno:** void
- **Errores:** El sistema valida dominios y configuración; el override no es un remount automático.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** Retira overrides de desarrollo antes de compartir una sesión.
```js
wu.clearOverrides();
```
Referencia: `src/core/wu-overrides.js`.
## normalizeStyleMode
Normaliza los alias de configuración de estilos.
`normalizeStyleMode(mode): string | undefined`
- **Parámetros:** String de modo o undefined.
- **Retorno:** none→isolated; own-only→fully-isolated; otros valores pasan sin validar.
- **Errores:** No valida por sí solo que el modo sea admitido por el manifest.
- **Permisos:** Función pura; no concede permisos.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
import { normalizeStyleMode } from 'wu-framework';
console.log(normalizeStyleMode('own-only'));
```
Referencia: `src/core/wu-sandbox.js`.
## resolveDomOwnership
Resuelve ownership explícito y aliases nativeShadow/framework.
`resolveDomOwnership(options?): "wu" | "app" | "light"`
- **Parámetros:** domOwnership gana; luego nativeShadow; Lit selecciona app por defecto.
- **Retorno:** Ownership efectivo.
- **Errores:** No crea Shadow DOM ni valida que un renderer implemente su límite.
- **Permisos:** Función de configuración; no es control de seguridad.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
import { resolveDomOwnership } from 'wu-framework';
console.log(resolveDomOwnership({ framework: 'lit' }));
```
Referencia: `src/core/wu-sandbox.js`.
## wu.tagStyleAsApp
Atribuye una hoja style/link a una aplicación para el bridge CSS.
`wu.tagStyleAsApp(element, appName): void`
- **Parámetros:** Elemento style/link y nombre de app.
- **Retorno:** void.
- **Errores:** La atribución no sustituye styleMode del manifest.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** Retira la hoja cuando termine su propietario.
```js
const style = document.createElement('style');
style.textContent = ':host { color: var(--accent); }';
wu.tagStyleAsApp(style, 'catalog');
document.head.append(style);
```
Referencia: `src/core/wu-core.js`.
## new WuCache
Crea una caché LRU con TTL y almacenamiento opcional.
`new WuCache(options?): WuCache`
- **Parámetros:** maxSize en MB; maxItems; TTL en ms; persistent y storage memory/localStorage/sessionStorage.
- **Retorno:** Instancia de caché.
- **Errores:** Una entrada demasiado grande o un límite de operaciones puede impedir almacenamiento.
- **Permisos:** Host; no uses almacenamiento persistente como autorización.
- **Limpieza:** cache.clear() libera entradas y su namespace persistente.
```js
import { WuCache } from 'wu-framework';
const cache = new WuCache({ maxSize: 2, maxItems: 20, defaultTTL: 60000, storage: 'memory' });
```
Referencia: `src/core/wu-cache.js`.
## WuCache.get
Lee una entrada no expirada y actualiza su orden LRU.
`cache.get(key): unknown | null`
- **Parámetros:** Clave de la entrada.
- **Retorno:** Valor guardado o null por ausencia, expiración o rate limit.
- **Errores:** null no distingue miss, expiración y cooldown; consulta métricas.
- **Permisos:** Acceso a la caché propietaria; no aplica grants de store.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
const result = cache.get('catalog-result');
```
La lectura en memoria devuelve la referencia guardada; no es un snapshot separado como WuStore.
Referencia: `src/core/wu-cache.js`.
## WuCache.set
Guarda un valor y aplica límites de espacio y expiración.
`cache.set(key, value, ttl?): boolean`
- **Parámetros:** Clave, valor y TTL en ms; ttl=0 usa defaultTTL por la selección con ||.
- **Retorno:** true si se almacena; false por tamaño, error o rate limit.
- **Errores:** Captura fallos y devuelve false; la cuota de storage puede limitar persistencia.
- **Permisos:** Host; valida qué datos guardas de forma persistente.
- **Limpieza:** delete(key) retira una entrada; clear() retira todas.
```js
const cached = cache.set('catalog-result', { count: 12 }, 30000);
```
Referencia: `src/core/wu-cache.js`.
## WuCache.delete
Elimina una entrada de memoria y del backing configurado.
`cache.delete(key): void`
- **Parámetros:** Clave exacta.
- **Retorno:** void
- **Errores:** La persistencia depende de disponibilidad y cuota del storage.
- **Permisos:** Autoridad del propietario de la caché.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
cache.delete('catalog-result');
```
Referencia: `src/core/wu-cache.js`.
## WuCache.clear
Vacía la caché de esta instancia y su almacenamiento configurado.
`cache.clear(): void`
- **Parámetros:** Sin argumentos.
- **Retorno:** void
- **Errores:** La persistencia depende de disponibilidad y cuota del storage.
- **Permisos:** Autoridad del propietario de la caché.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
cache.clear();
```
Referencia: `src/core/wu-cache.js`.
## WuCache.getStats
Consulta hits, misses, expulsiones, tamaños y rate limiting.
`cache.getStats(): object`
- **Parámetros:** Sin argumentos.
- **Retorno:** object
- **Errores:** La persistencia depende de disponibilidad y cuota del storage.
- **Permisos:** Autoridad del propietario de la caché.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
console.log(cache.getStats());
```
Referencia: `src/core/wu-cache.js`.
## WuCache.getRateLimitStatus
Consulta si las operaciones están en cooldown y su cuota.
`cache.getRateLimitStatus(): object`
- **Parámetros:** Sin argumentos.
- **Retorno:** object
- **Errores:** La persistencia depende de disponibilidad y cuota del storage.
- **Permisos:** Autoridad del propietario de la caché.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
console.log(cache.getRateLimitStatus());
```
Referencia: `src/core/wu-cache.js`.
## wu.getStats
Resume estado y métricas de los subsistemas del core.
`wu.getStats(): object`
- **Parámetros:** Sin argumentos.
- **Retorno:** Objeto de diagnóstico.
- **Errores:** No sustituye una prueba de montaje ni una comprobación HTTP.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
console.log(wu.getStats());
```
Referencia: `src/core/wu-core.js`.
## wu.getManifestDiagnostics
Lee errores de dependencias declarativas entre apps.
`wu.getManifestDiagnostics(): WuManifestImportDiagnostic[]`
- **Parámetros:** Sin argumentos; depende del preflight de imports.
- **Retorno:** Lista de diagnósticos por consumidor/import/proveedor.
- **Errores:** No comprueba automáticamente todos los imports transitivos de un bundle.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
console.table(wu.getManifestDiagnostics());
```
Referencia: `src/core/wu-core.js`.
## wu.showInspector
Abre el inspector visual cargado bajo demanda.
`wu.showInspector(): Promise<{ close(): void } | null>`
- **Parámetros:** Sin argumentos.
- **Retorno:** Handle close o null cuando no se abre.
- **Errores:** La carga del chunk o el entorno DOM pueden impedir la apertura.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** close() o wu.hideInspector() retira el overlay.
```js
const inspector = await wu.showInspector();
// Al cerrar tu herramienta:
inspector?.close();
```
Referencia: `src/core/wu-core.js`.
## wu.hideInspector
Cierra el overlay de inspección si existe.
`wu.hideInspector(): Promise`
- **Parámetros:** Sin argumentos.
- **Retorno:** Promesa de cierre.
- **Errores:** No elimina apps ni datos del store.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** Retira la interfaz de diagnóstico.
```js
await wu.hideInspector();
```
Referencia: `src/core/wu-core.js`.
## wu.performance.startMeasure
Marca el inicio de una duración asociada a app o global.
`wu.performance.startMeasure(name, appName?): void`
- **Parámetros:** Nombre de medida; appName por defecto global.
- **Retorno:** void.
- **Errores:** Una configuración disabled omite el registro.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** Termina con endMeasure usando el mismo par nombre/app.
```js
wu.performance.startMeasure('load-catalog', 'catalog');
```
Referencia: `src/core/wu-performance.js`.
## wu.performance.endMeasure
Cierra una duración y la publica en métricas/User Timing cuando está habilitado.
`wu.performance.endMeasure(name, appName?): number`
- **Parámetros:** Mismo nombre/app que startMeasure.
- **Retorno:** Milisegundos; 0 si no hay marca inicial.
- **Errores:** Ausencia de marca devuelve 0 y no inventa una duración.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** Retira la marca inicial de esta medición.
```js
const ms = wu.performance.endMeasure('load-catalog', 'catalog');
```
Referencia: `src/core/wu-performance.js`.
## wu.performance.generateReport
Agrupa estadísticas de rendimiento de la instancia.
`wu.performance.generateReport(): object`
- **Parámetros:** Sin argumentos.
- **Retorno:** object
- **Errores:** La disponibilidad de User Timing depende del entorno.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
console.log(wu.performance.generateReport());
```
Referencia: `src/core/wu-performance.js`.
## wu.performance.getMetrics
Lee métricas de una app concreta.
`wu.performance.getMetrics(appName): object | null`
- **Parámetros:** Nombre exacto; null si no hay mediciones.
- **Retorno:** object | null
- **Errores:** La disponibilidad de User Timing depende del entorno.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
console.log(wu.performance.getMetrics('catalog'));
```
Referencia: `src/core/wu-performance.js`.
## wu.performance.getAllMetrics
Lee métricas de todas las apps registradas en el medidor.
`wu.performance.getAllMetrics(): object`
- **Parámetros:** Sin argumentos.
- **Retorno:** object
- **Errores:** La disponibilidad de User Timing depende del entorno.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
console.log(wu.performance.getAllMetrics());
```
Referencia: `src/core/wu-performance.js`.
## wu.performance.clearMetrics
Limpia mediciones de una app o todas.
`wu.performance.clearMetrics(appName?): void`
- **Parámetros:** Nombre opcional.
- **Retorno:** void
- **Errores:** La disponibilidad de User Timing depende del entorno.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
wu.performance.clearMetrics('catalog');
```
Referencia: `src/core/wu-performance.js`.
## wu.performance.getDevToolsEntries
Lee entradas User Timing emitidas por WU.
`wu.performance.getDevToolsEntries(options?): PerformanceEntry[]`
- **Parámetros:** type: mark, measure o all; appName opcional.
- **Retorno:** PerformanceEntry[]
- **Errores:** La disponibilidad de User Timing depende del entorno.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
console.table(wu.performance.getDevToolsEntries({ type: 'measure', appName: 'catalog' }));
```
Referencia: `src/core/wu-performance.js`.
## wu.performance.observe
Escucha nuevas entradas User Timing de WU mediante PerformanceObserver.
`wu.performance.observe(callback, { type? }?): () => void`
- **Parámetros:** Callback de PerformanceEntry; type por defecto measure.
- **Retorno:** Cleanup; si el observer no está disponible devuelve uno vacío.
- **Errores:** La falta de PerformanceObserver no lanza; los fallos de callback se registran.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** stop() desconecta el observer.
```js
const stop = wu.performance.observe(entry => console.log(entry.duration), { type: 'measure' });
```
Referencia: `src/core/wu-performance.js`.
## wu.performance.configure
Configura medición, límite de historial, User Timing y umbrales.
`wu.performance.configure(options): void`
- **Parámetros:** enabled, maxMeasurements, devtoolsTimeline y thresholds por nombre.
- **Retorno:** void.
- **Errores:** Un umbral superado genera advertencia; no cancela una operación.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No crea suscripciones ni procesos persistentes.
```js
wu.performance.configure({ enabled: true, maxMeasurements: 100, devtoolsTimeline: true });
```
Referencia: `src/core/wu-performance.js`.
## wu.errorBoundary.register
Añade un handler de clasificación y recuperación de fallos.
`wu.errorBoundary.register(handler): void`
- **Parámetros:** name, canHandle(error) y handle(error,context).
- **Retorno:** void.
- **Errores:** Lanza si falta uno de esos miembros; los handlers se recorren por orden.
- **Permisos:** API de host; no está expuesta por la facade scoped.
- **Limpieza:** No devuelve unsubscribe; administra estas extensiones durante el lifecycle del host.
```js
wu.errorBoundary.register({ name: 'catalog-error', canHandle: error => error.name === 'CatalogError', async handle(error) { return { recovered: false, action: 'none', message: error.message }; } });
```
El fallback genérico por defecto puede preceder a handlers agregados después. Comprueba el orden antes de depender de este registro.
Referencia: `src/core/wu-error-boundary.js`.
## wu.errorBoundary.handle
Clasifica un fallo y obtiene una decisión de recuperación.
`wu.errorBoundary.handle(error, context?): Promise