# Configuração e manifestos

O que o shell configura, o que wu.json pode declarar e como a inicialização é validada no Framework 4.

Veja versões, mudanças e requisitos em [Framework 4.0 e CLI 1.2](/pt/docs/guides/releases/).


<span id="dos-documentos-con-distinta-autoridad"></span>

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

## Dois documentos com autoridades diferentes

A configuração de `wu.init()` pertence ao shell. `wu.json` pertence a uma aplicação e é baixado de `<url>/wu.json`. O manifesto solicita recursos; o shell concede a autoridade máxima. Nenhum campo do manifesto pode conceder permissões a si mesmo.

```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 um destino que `wu.app()` pode aproveitar. A chamada explícita `wu.mount('catalog', '#catalog-slot')` mantém visível o destino de cada montagem.

<span id="opciones-globales"></span>

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

## Opções globais

| Opção | Valor inicial / comportamento |
| --- | --- |
| `apps` | Lista de configurações com `name` e `url` |
| `sandbox` | `module`; também `strict` e `eval` |
| `strictFallback` | `false`; habilitar permite degradar um carregamento strict malsucedido para eval |
| `strictEvents` | Forçado a `true` na inicialização, salvo `false` explícito |
| `eventBus` | Ajustes do barramento; `strictEvents` tem precedência sobre `strictMode` |
| `manifestPolicy.imports` | `error`; também `warn` e `off` |
| `overrides` | Ajustes do sistema de substituição de URLs de desenvolvimento |
| `compatibility` | Perfil `strict` ou configuração explícita de migração |

`init` agrupa chamadas concorrentes, aguarda a instalação de plugins, registra apps e valida imports após o registro completo. Uma inicialização malsucedida reverte os registros criados nessa tentativa. Após uma inicialização bem-sucedida, outra chamada a `init` emite aviso e termina: não constitui uma API para substituir a configuração a quente.

`whenReady()` retorna uma promise com booleano. Se ninguém iniciou o WU, retorna `false`; se houver uma inicialização pendente, aguarda seu resultado. `mount()` já aguarda um `init` em andamento.

<span id="manifest-completo-y-válido"></span>

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

## Manifesto completo e 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"]
  }
}
```

Os campos superiores aceitos são `name`, `entry`, `wu`, `metadata`, `styleMode`, `version`, `folder` e `roles`. Dentro de `wu`, são reconhecidos `exports`, `imports`, `permissions`, `roles` e o nome histórico `routes`, embora rotas não vazias ali sejam rejeitadas na normalização do Framework 4. Use `metadata.routes` para informações descritivas.

`framework`, `sandbox`, `grants`, `domOwnership` e `keepAlive` pertencem à configuração do shell. Campos extras não são aceitos indiscriminadamente: guarde metadados próprios dentro de `metadata`.

<span id="reglas-de-carga-y-validación"></span>

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

## Regras de carregamento e validação

Um **404 real** permite gerar o manifesto padrão com `entry: 'index.js'` e permissões vazias. Um erro de rede, um 500, um JSON inválido ou uma página HTML retornada como manifesto produz erro. Isso evita que um servidor mal configurado seja interpretado como aplicação sem manifesto.

| Limite | Valor no código |
| --- | --- |
| Tamanho do manifesto | 100 KiB |
| Comprimento do nome | 50 caracteres |
| Comprimento da entrada | 200 caracteres |
| Exportações | 100 |
| Imports declarativos | 50 |
| Rotas descritivas | 100 |
| Solicitações / concessões | 50 declarações por lista |

A validação verifica se o nome baixado corresponde ao registrado. Inspeciona propriedades próprias, rejeita accessors e estruturas perigosas e entrega um snapshot congelado. Não use `manifest.wu.permissions.push(...)` para alterar a política após o registro.

<span id="permisos-sintaxis-exacta"></span>

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

## Permissões: sintaxe exata

Uma declaração de objeto exige `capability` e **`resource` explícito**. A forma string válida é, por exemplo, `store.read:catalog`. Use um objeto para declarar também `required`; use uma string quando precisar apenas de capacidade e 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` sozinho não é uma declaração válida para o parser. A declaração TypeScript de entrada permite alguns valores mais amplos, por isso é necessário preencher o recurso explicitamente mesmo quando o editor não exige.

`required` é `false` por padrão. Uma permissão opcional negada fica documentada nos diagnósticos e sua operação será rejeitada se for tentada. `required: true` faz o registro falhar quando o shell não cobre toda a solicitação.

<span id="estrategia-de-carga-layout-y-estilos"></span>

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

## Estratégia de carregamento, layout e estilos

`strategy` seleciona como antecipar o carregamento de uma aplicação; consulte [carregamento e pré-carregamento](/pt/docs/framework/loading/) para escolher entre carregar ao montar, importar de imediato ou antecipar recursos. `fullBleed` controla se a app ocupa a altura do host ou flui com o conteúdo. Ambos os campos são lidos na configuração da aplicação, embora não estejam listados em `WuAppConfig`.

Configure `styleMode` no manifesto. A montagem entrega `app.manifest.styleMode` ao sandbox; o campo de mesmo nome na configuração superior do host não o substitui. O [guia de sandbox e CSS](/pt/docs/framework/sandbox/) explica como combinar estilos próprios e compartilhados.

<span id="referencia-de-implementación"></span>

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

## Referência de implementação

Implementação: `src/core/wu-core.js`, `src/core/wu-core.js`, `src/core/wu-core.js`; parser e limites: `src/core/wu-manifest.js`, `src/core/wu-manifest.js`, `src/core/wu-manifest.js`; política: `src/core/wu-policy.js` e `src/core/wu-policy.js`. Testes: `tests/unit/manifest-policy.test.js`, `tests/unit/manifest-dependencies.test.js`, `tests/unit/init-race.test.js`.