# Configuración y manifests

Qué configura el shell, qué puede declarar wu.json y cómo se valida el arranque en Framework 4.

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>

## Dos documentos con distinta autoridad

La configuración de `wu.init()` pertenece al shell. `wu.json` pertenece a una aplicación y se descarga de `<url>/wu.json`. El manifest solicita recursos; el shell concede la autoridad máxima. Ningún campo del manifest puede concederse permisos a sí mismo.

```js
import { wu } from 'wu-framework';

await wu.init({
  sandbox: 'module',
  strictEvents: true,
  strictFallback: false,
  manifestPolicy: { imports: 'error' },
  apps: [{
    name: 'catalog',
    url: '/apps/catalog',
    framework: 'react',
    container: '#catalog-slot',
    keepAlive: false,
    grants: [
      { capability: 'store.read', resource: 'catalog' },
      { capability: 'events.emit', resource: 'catalog:selected' },
    ],
  }],
});
```

`container` configura un destino que puede aprovechar `wu.app()`. La llamada explícita `wu.mount('catalog', '#catalog-slot')` mantiene visible el destino de cada montaje.

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

## Opciones globales

| Opción | Valor inicial / comportamiento |
| --- | --- |
| `apps` | Lista de configuraciones con `name` y `url` |
| `sandbox` | `module`; también `strict` y `eval` |
| `strictFallback` | `false`; habilitarlo permite degradar una carga strict fallida a eval |
| `strictEvents` | Se fuerza `true` al inicializar salvo `false` explícito |
| `eventBus` | Ajustes del bus; `strictEvents` gana respecto de `strictMode` |
| `manifestPolicy.imports` | `error`; también `warn` y `off` |
| `overrides` | Ajustes del sistema de sustitución de URLs de desarrollo |
| `compatibility` | Perfil `strict` o configuración explícita de migración |

`init` agrupa llamadas concurrentes, espera instalación de plugins, registra apps y valida imports después del registro completo. Una inicialización fallida revierte los registros creados en ese intento. Tras una inicialización exitosa, otra llamada a `init` advierte y termina: no constituye una API para reemplazar la configuración en caliente.

`whenReady()` devuelve una promesa con booleano. Si nadie inició WU devuelve `false`; si hay un arranque pendiente espera su resultado. `mount()` ya espera un `init` en vuelo.

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

## Manifest completo y válido

```json
{
  "name": "catalog",
  "version": "1.2.0",
  "entry": "assets/catalog.js",
  "styleMode": "own-only",
  "wu": {
    "exports": { "ProductCard": "components/product-card.js" },
    "imports": [],
    "permissions": [
      { "capability": "store.read", "resource": "catalog", "required": true },
      { "capability": "events.emit", "resource": "catalog:selected" }
    ],
    "roles": ["catalog-reader"]
  },
  "metadata": {
    "description": "Explorador del catálogo",
    "routes": ["/catalog", "/catalog/:id"]
  }
}
```

Los campos superiores admitidos son `name`, `entry`, `wu`, `metadata`, `styleMode`, `version`, `folder` y `roles`. Dentro de `wu` se reconocen `exports`, `imports`, `permissions`, `roles` y el nombre histórico `routes`, aunque rutas no vacías allí se rechazan en la normalización de Framework 4. Usa `metadata.routes` para información descriptiva.

`framework`, `sandbox`, `grants`, `domOwnership` y `keepAlive` pertenecen a la configuración del shell. Los campos extra no se aceptan indiscriminadamente: guarda metadatos propios dentro de `metadata`.

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

## Reglas de carga y validación

Un **404 real** permite generar el manifest por defecto con `entry: 'index.js'` y permisos vacíos. Un error de red, un 500, un JSON inválido o una página HTML devuelta como manifest produce error. Esto evita que un servidor mal configurado se interprete como aplicación sin manifest.

| Límite | Valor en código |
| --- | --- |
| Tamaño del manifest | 100 KiB |
| Longitud del nombre | 50 caracteres |
| Longitud del entry | 200 caracteres |
| Exportaciones | 100 |
| Imports declarativos | 50 |
| Rutas descriptivas | 100 |
| Solicitudes / grants | 50 declaraciones por lista |

La validación comprueba que el nombre descargado coincide con el registrado. Inspecciona propiedades propias, rechaza accessors y estructuras peligrosas y entrega un snapshot congelado. No uses `manifest.wu.permissions.push(...)` para cambiar política después del registro.

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

## Permisos: sintaxis exacta

Una declaración objeto exige `capability` y **`resource` explícito**. La forma string válida es, por ejemplo, `store.read:catalog`. Usa un objeto para declarar también `required`; usa un string cuando solo necesites capacidad y recurso.

```js
// Solicitud de la aplicación:
const permission = {
  capability: 'store.read',
  resource: 'catalog',
  required: true,
};

// Dos formas equivalentes de conceder esa lectura desde el host:
const objectGrant = { capability: 'store.read', resource: 'catalog' };
const stringGrant = 'store.read:catalog';
```

`store.read` a solas no es una declaración válida para el parser. La declaración TypeScript de entrada permite algunos valores más amplios, por lo que completar el recurso explícitamente es necesario incluso cuando el editor no lo exige.

`required` es `false` por defecto. Un permiso opcional denegado queda documentado en los diagnósticos y su operación será rechazada si se intenta. `required: true` hace fallar el registro cuando el shell no cubre toda la solicitud.

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

## Estrategia de carga, layout y estilos

`strategy` selecciona cómo anticipar la carga de una aplicación; consulta [carga y precarga](/es/docs/framework/loading/) para elegir entre cargar al montar, importar de inmediato o anticipar recursos. `fullBleed` controla si la app ocupa el alto del host o fluye con el contenido. Ambos campos se leen en la configuración de la aplicación, aunque no están enumerados en `WuAppConfig`.

Configura `styleMode` en el manifest. El montaje entrega `app.manifest.styleMode` al sandbox; el campo del mismo nombre en la configuración superior del host no lo sustituye. La [guía de sandbox y CSS](/es/docs/framework/sandbox/) explica cómo combinar estilos propios y compartidos.

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

## Referencia de implementación

Implementación: `src/core/wu-core.js`, `src/core/wu-core.js`, `src/core/wu-core.js`; parser y límites: `src/core/wu-manifest.js`, `src/core/wu-manifest.js`, `src/core/wu-manifest.js`; política: `src/core/wu-policy.js` y `src/core/wu-policy.js`. Pruebas: `tests/unit/manifest-policy.test.js`, `tests/unit/manifest-dependencies.test.js`, `tests/unit/init-race.test.js`.