# Arquitetura poliglota

Diferencie a CLI, o host, o runtime, as aplicações e a biblioteca visual antes de conectar frameworks.

<span id="cinco-responsabilidades-distintas"></span>

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

## Cinco responsabilidades diferentes

Um **shell** é a página que reúne as aplicações; um **microfrontend** é cada aplicação que pode montar. O runtime WU conecta as duas partes. A CLI prepara os arquivos e as ferramentas com que você as desenvolve.

A tabela usa a arquitetura deste portal como exemplo. Você pode escolher outro shell e outros componentes visuais: Astro e Lit não são requisitos do runtime WU.

| Parte | O que possui | O que fornece |
| --- | --- | --- |
| WU CLI | Geração, desenvolvimento e compilação do workspace | Arquivos, configuração, processos e saída compilada |
| Shell Astro | URLs globais, navegação e composição da página | HTML da documentação e slots para aplicações |
| WU Framework | Registro, carregamento e ciclo de vida; serviços de comunicação | Um contrato comum para aplicações independentes |
| Microfrontend | Uma capacidade funcional e seus recursos | Implementação de mount/unmount e estado próprio |
| Biblioteca Lit | Controles e contratos visuais | Custom Elements utilizáveis por diferentes frameworks |

A CLI atua durante o desenvolvimento e a compilação. O runtime é executado no navegador. Astro pode produzir páginas sem JavaScript de framework; as partes interativas são carregadas por módulos cliente.

<span id="la-url-pertenece-al-shell"></span>

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

## A URL pertence ao shell

Um shell precisa decidir qual URL mostra qual conteúdo, como voltar e avançar funcionam e para onde o foco se move. O WU não inclui um roteador público que você possa invocar como `wu.router` ou `wu.routes`. Os metadados de rotas não implementam a navegação por si só.

Neste portal, Astro gera `/docs/.../`, `/labs/` e `/sources/`. São usados links HTML comuns. Uma mudança de documento descarrega a página anterior e cria um novo contexto de página. Não há uma SPA oculta nem promessa de manter o estado entre documentos.

Um produto com shell persistente pode usar a History API e um roteador próprio. Nesse caso, deve serializar as transições: desmontar a app anterior, montar a próxima, atualizar título e foco e tratar falhas. É uma responsabilidade adicional do host.

<span id="una-capacidad-por-microfrontend"></span>

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

## Uma capacidade por microfrontend

O laboratório contém duas capacidades deliberadamente pequenas:

- **Construtor de comandos**: transforma uma configuração escolhida pelo leitor em uma receita de CLI. React gerencia o estado e adapta eventos DOM.
- **Inspetor do runtime**: mostra e modifica o estado compartilhado, recebe eventos e permite observar a limpeza. Vue gerencia essa lógica.

Cada botão ou cartão não vira uma aplicação WU. Os botões, formulários e painéis ficam em componentes Lit; não precisam de implantação nem ciclo de vida próprio de MFE.

<span id="el-contrato-de-montaje"></span>

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

## O contrato de montagem

Um ciclo de vida explícito mostra quais recursos a app cria e quem os destrói:

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

wu.define('saludo', {
  mount(container) {
    const message = document.createElement('p');
    message.textContent = 'Aplicación montada por WU';
    container.append(message);
  },
  unmount(container) {
    container.replaceChildren();
  }
});
```

Isso define a implementação. O host deve inicializar o registro e a configuração da aplicação e chamar `mount`; uma definição não significa que ela já esteja visível. Consulte o manual do framework para o formato exato do manifesto e de `wu.init()`.

<span id="estado-local-dom-y-comunicación-entre-apps"></span>

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

## Estado local, DOM e comunicação entre apps

Use o mecanismo mais próximo da relação que deseja expressar:

| Relação | Mecanismo |
| --- | --- |
| Estado interno do React ou Vue | Estado do framework local |
| Dados de uma app para um controle Lit | Propriedades do Custom Element |
| Intenção de um controle para sua app | Evento DOM tipado |
| Fato que interessa a outras apps | Barramento de eventos WU |
| Dado compartilhado observável | Store WU |
| Serviço versionado entre provedores e consumidores | Contratos WU |

Não publique objetos mutáveis do store como API visual. Transmita dados e eventos e cancele as inscrições quando a app for desmontada.

<span id="aislamiento-y-confianza"></span>

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

## Isolamento e confiança

O portal usa `sandbox: 'module'`. Os módulos são executados no mesmo contexto JavaScript; isso não é uma barreira contra código hostil. Os componentes Lit têm Shadow DOM para seus estilos, mas Shadow DOM não impede o acesso ao contexto global.

As aplicações deste projeto são código local confiável. As capacidades da fachada limitam as operações feitas por ela; não tornam automaticamente seguro um módulo arbitrário. Os modos `strict`, `eval`, `proxy` e `none` têm contratos diferentes e são documentados com seus limites no manual.

<span id="una-interfaz-coherente"></span>

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

## Uma interface coerente

O sistema visual do portal usa fundo preto, texto em tom de osso, vermelho de sinalização, estados em verde-lima e divisões finas. As páginas de leitura mantêm tamanho de texto suficiente, foco visível e tabelas com rolagem.

A composição estática de documentos pertence ao Astro. Os controles interativos são implementados em Lit. React e Vue não introduzem uma segunda família de botões e formulários.

<span id="referencias"></span>

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

## Referências

- Código: `wu-framework/src/core/wu-core.js`, `wu-store.js`, `wu-event-bus.js`, `wu-contracts.js` e `src/index.js`.
- [Astro: scripts cliente e Custom Elements](https://v5.docs.astro.build/en/guides/client-side-scripts/).
- [Lit: ciclo de vida e limpeza de recursos](https://lit.dev/docs/components/lifecycle/).