# Referencia pública

Consulta imports, parámetros, retornos y ejemplos de las APIs de composición, comunicación, estado y extensiones.

Consulta las versiones, cambios y requisitos en [Framework 4.0 y CLI 1.2](/es/docs/guides/releases/).


<span class="section-anchor" id="section-1"></span>

## Import principal

```js
import { wu } from 'wu-framework';
// Equivalente para el singleton:
// import wu from 'wu-framework';
```

El paquete define entrypoints ESM, CommonJS y UMD. Los subpaths de adapters, integraciones, servidor, sandbox e IA están declarados en `package.json`. Importar una ruta interna no exportada no forma parte del contrato de distribución.

<span class="section-anchor" id="section-2"></span>

## Core y lifecycle

| API | Entrada / retorno | Uso |
| --- | --- | --- |
| `wu.init(config)` | Objeto con `apps`; `Promise<void>` | Inicialización una vez |
| `wu.whenReady()` | `Promise<boolean>` | Esperar un init en vuelo |
| `wu.define(name, lifecycle)` | `mount` obligatorio | Registrar implementación |
| `wu.mount(name, selector)` | Selector string; promesa | Montar en un nodo accesible por `document.querySelector` |
| `wu.unmount(name, options?)` | `{ force?, keepAlive? }`; promesa | Liberar u ocultar |
| `wu.update(name, props)` | Record; `Promise<boolean>` | Props vivas |
| `wu.hide(name)` / `show(name)` | Promesas | Preservar/reactivar una app |
| `wu.isHidden(name)` | Booleano | Estado keep-alive |
| `wu.destroy()` | Promesa | Liberar todo el runtime |
| `wu.app(name, config)` | `WuApp` | Identidad y configuración reutilizables; registra al montar |

El helper exportado `init(apps)` **recibe el array**, mientras `wu.init({ apps })` recibe el objeto. No son intercambiables sintácticamente. Los helpers exportados `mount`, `unmount`, `define`, `app`, `hide`, `show`, `isHidden` y `destroy` delegan al singleton.

<span class="section-anchor" id="section-3"></span>

### Inicialización tipada

```ts
import { wu, type WuAppConfig } from 'wu-framework';

const catalog: WuAppConfig = {
  name: 'catalog',
  url: '/apps/catalog',
  grants: [{ capability: 'store.read', resource: 'catalog' }],
};

await wu.init({ apps: [catalog], sandbox: 'module' });
await wu.mount(catalog.name, '#catalog-slot');
// Al retirar este consumidor del shell:
await wu.unmount(catalog.name);
```

El slot debe existir antes de `mount`; el manifest debe declarar la misma identidad y solicitar los recursos que utilizará la app. `unmount` libera una referencia y aplica las reglas de keep-alive; `{ force: true }` solicita el desmontaje completo.

<span class="section-anchor" id="section-4"></span>

## Comunicación

| API del singleton/facade | Retorno |
| --- | --- |
| `emit(event, data, opts?)` | Booleano de aceptación |
| `on(event, callback)` | Función unsubscribe |
| `once(event, callback)` | Función unsubscribe |
| `off(event, callback)` | Booleano del bus |
| `request(channel, data, opts?)` | Promesa de respuesta |
| `handle(channel, handler)` | Función de liberación; opciones en eventBus/facade |
| `provide(name, impl, opts?)` | Handle con `revoke()` |
| `consume(name, range?, opts?)` | Proxy; promesa si `wait: true` |

`WuEvent` contiene `name`, `data`, `timestamp`, `appName`, `meta`, `verified`. `WuRpcOptions` admite `timeout`, `signal`, `version` y `range`; `WuRpcHandleOptions` admite `version`, `allow` y `replace`.

`request` y `handle` son métodos de `wu`, `wu.eventBus` y la facade; no se exportan como funciones sueltas del paquete principal. `emit`, `on`, `once`, `off`, `provide` y `consume` también existen como helpers exportados.

`wu.handle(channel, handler, options)` conserva `version`, `allow` y `replace`. Dentro del lifecycle, `context.wu.handle` añade además la identidad y los grants de la app; utiliza esa facade para handlers de una microapp.

<span class="section-anchor" id="section-5"></span>

### Elegir evento o petición

```js
const unsubscribe = wu.on('catalog:selected', (event) => {
  console.log(event.data.productId);
});
wu.emit('catalog:selected', { productId: 'p-42' });

const stopLookup = wu.handle('catalog:lookup', ({ productId }) => {
  return { productId, available: true };
});
const result = await wu.request('catalog:lookup', { productId: 'p-42' });
console.log(result.available);

unsubscribe();
stopLookup();
```

El callback de evento recibe un envelope `WuEvent`; el handler RPC recibe directamente el payload de la petición. Conserva las funciones de baja en el lifecycle que instaló cada listener/proveedor. Dentro de una aplicación usa `context.wu` con los grants correspondientes.

<span class="section-anchor" id="section-6"></span>

## Store

| Método | Retorno / observación |
| --- | --- |
| `get(path?)` / `getSnapshot(path?)` | Snapshot separado; sin identidad estable de objetos entre lecturas |
| `set(path, value)` | Número de secuencia |
| `update(path, updater)` | Número; updater síncrono |
| `on(pattern, callback)` | Cleanup; payload distinto en wildcard |
| `batch(record)` | Array de secuencias; preflight de todas las entradas |
| `tap(fn)` | Cleanup; observa commits síncronos |
| `hydrate(state, options?)` | Sustituye estado con opciones de notificación |
| `sync(options?)` | Handle con `ready`, `stop`, `status` |
| `getMetrics()` | Contadores del store |
| `reset()` / `dispose()` / `clear()` | Operaciones de ciclo del store; no API de persistencia |

`store` exportado por la raíz apunta a `wu.store`. Los helpers `getState`, `setState`, `onStateChange` y `syncStore` usan esa misma instancia. `new WuCore()` crea por defecto su propio store; el constructor permite inyectar otro para composición intencional.

<span class="section-anchor" id="section-7"></span>

## Inspección, rendimiento y extensiones

| API | Función |
| --- | --- |
| `wu.inspect({ events? })` | Snapshot de apps, estado y diagnósticos |
| `wu.getAppInfo(name)` | Información de app registrada |
| `wu.getSandboxInfo(name)` | Modo pedido/real y ownership |
| `wu.getManifestDiagnostics()` | Dependencias declarativas inválidas |
| `wu.getStats()` | Resumen operativo |
| `wu.showInspector()` / `hideInspector()` | UI de inspección cargada bajo demanda |
| `wu.performance.startMeasure(name, app?)` | Iniciar medida |
| `wu.performance.endMeasure(name, app?)` | Terminar y devolver duración |
| `wu.performance.generateReport()` | Reporte de medidas |
| `wu.prefetch` / `prefetchAll` | Anticipar recursos |
| `wu.use('app.component')` | Cargar default export o namespace declarado en `wu.exports`; consulta la nota de tipos |
| `wu.override` / `removeOverride` / `getOverrides` / `clearOverrides` | Sustitución de URLs |
| `wu.pluginSystem.use(plugin, options)` | Instalación asíncrona |
| `wu.hooks.use(phase, middleware, options?)` | Middleware de lifecycle |
| `wu.aiReady()` / `timelineReady()` | Cargar subsistema diferido |

Las clases exportadas incluyen `WuCore`, `WuCompatibility`, `WuLoader`, `WuSandbox`, `WuManifest`, `WuStore`, `WuApp`, `WuStyleBridge`, `WuCache`, `WuEventBus`, `WuPerformance`, `WuProxySandbox`, `WuPluginSystem`, `WuLoadingStrategy`, `WuPrefetch`, `WuOverrides`, `WuErrorBoundary`, `WuContracts` y `WuLifecycleHooks`. Usar directamente una clase de bajo nivel exige configurar sus garantías: `new WuEventBus()` empieza permissive; `wu.init()` activa strict para el bus del core.

<span class="section-anchor" id="section-8"></span>

## Tipos que conviene conocer

`WuAppConfig` describe configuración host. `WuLifecycle` y `WuAppLifecycleContext` describen el montaje. `WuAppFacade`/`WuScopedStore` describen autoridad app. `WuPermissionRequest`, `WuCapabilityGrant` y `WuCompiledPolicy` describen política. `WuSyncHandle`, `WuTimelineFacade` y `WuInspectSnapshot` describen subsistemas opcionales.

<span class="section-anchor" id="section-9"></span>

### Compatibilidad de las declaraciones TypeScript

Las siguientes precisiones permiten escribir entradas válidas y consumir correctamente los retornos, incluso donde la declaración de tipos no expresa todo el contrato:

- `resource?` en requests/grants está tipado opcional, pero el parser exige la propiedad.
- El union de input permite capacidad sola; el parser string exige `capability:resource`.
- `strategy` y `fullBleed` se leen en runtime pero faltan en `WuAppConfig`.
- `wu.use` existe en el core, pero falta en la declaración pública de `WuCore`.
- `WuLifecycleHooks.use` aparece con retorno `void`, aunque implementación devuelve cleanup.
- La firma genérica del store no expresa correctamente el envelope wildcard.
- El tipo host ofrece `styleMode`; configura el valor efectivo en el manifest.

<span class="section-anchor" id="section-10"></span>

## Referencia de implementación

Exports efectivos: `src/index.js`; helpers: `src/index.js`; tipos públicos: `src/index.d.ts`, `src/index.d.ts`, `src/index.d.ts`, `src/index.d.ts`; subpaths: `package.json`. Pruebas: `tests/unit/package-exports.test.js`, `tests/unit/adapter-conformance.test.js`, `tests/unit/store-subscription-semantics.test.js`.

<span class="section-anchor" id="section-11"></span>

## APIs de la versión 3.2

El catálogo incluye manifests declarados, foco, transiciones, ventanas, drag and drop, shadow deployment, puertos y apps instalables. Los [recorridos de actualización](/es/docs/guides/releases/) enlazan contratos completos, imports opcionales y manejo de errores. Las APIs anteriores de estado, eventos, IA y lifecycle siguen en sus referencias correspondientes.

Consulta [supervisión, recuperación y replay](/es/docs/framework/runtime-reliability/) para `superviseApp`, `createReplaySession` y los métodos scoped `reportError`, `now` y `random`.

Las entradas opcionales `ai`, `timeline`, `devtools`, `mcp`, `store-sync`, `shadow`, `windows`, `dnd`, `ports`, `wuapp`, `sandbox/iframe` y `sandbox/html-parser` tienen declaraciones públicas. `typesVersions` también las resuelve con `moduleResolution: "node10"`. Importa tipos desde los subpaths publicados, no desde archivos internos.