# Como o portal é construído Percorra o shell Astro, as receitas de APIs WU, a composição React/Vue e o exemplo de serviços com contratos e RPC. ## Estrutura do projeto ```text wu-docs/ ├── shell/astro.config.mjs # Astro: configuración del host ├── src/content/docs/ # Manuales del framework y CLI │ ├── guides/ │ ├── framework/ │ └── cli/ ├── src/layouts/ # Composición del documento ├── src/components/ # Controles Lit del portal ├── src/pages/ # Rutas y generación estática ├── apps/command-lab/ # Microfrontend React ├── apps/runtime-lab/ # Microfrontend Vue ├── apps/systems-lab/ # Ejecutor e infraestructura del servicio ├── apps/api-lab/ # WU recipes with owned instances in the host document ├── apps/backend-lab/ # Implementación del proveedor RPC ├── examples/ # SSR, IA local y relay MCP ├── packages/lab-ui/ # Controles Lit de los laboratorios ├── scripts/build-apps.mjs # Empaquetado de los módulos ESM ├── public/microfrontends/ # Salida generada de las apps ├── packages/backend-ui/ # Cliente e interfaz de Servicios y RPC └── dist/ # Sitio estático compilado ``` O `srcDir` do Astro aponta de `shell/` para `../src`. Um shell identificável é mantido sem esconder o conteúdo documental dentro de uma aplicação cliente. ## Desenvolvimento ```sh npm ci npm run dev ``` O lockfile fixa WU Framework 4.0.0 publicado no npm para `wu-framework` e o alias `wu-framework-release`. Página inicial, laboratórios e downloads usam essa versão. Composição e Serviços e RPC mantêm uma URL CDN exata e um pacote de fallback da mesma versão. `npm run dev` compila os laboratórios e inicia Astro. As alterações em Markdown, componentes do host e estilos entram pelo servidor de desenvolvimento. Após modificar as apps ou sua UI compartilhada, execute `npm run build:apps` e recarregue o laboratório. ## Build reproduzível ```sh npm run build npm run preview ``` A primeira etapa empacota as aplicações, os runners e seus componentes Lit. Depois, Astro gera documentos, busca, explorador de APIs e páginas de exemplos. O serviço inclui seus artefatos de execução; o build normal não requer Zig. Tudo de que você precisa para servir o portal fica em `dist/`. Os scripts npm fazem o build deste repositório de documentação. Para um workspace criado com WU CLI, siga as convenções e a configuração de [wu build](/pt/docs/cli/build/). ## Adicionar um capítulo Crie um Markdown em `src/content/docs/` com um frontmatter válido: ```yaml --- title: Título del capítulo description: Qué aprenderá el lector en esta página. section: Framework order: 20 --- ``` Use `##` para seções navegáveis e `###` para subseções. Astro obtém o índice lateral e os links anterior/próximo a partir da coleção. A rota deriva do nome do arquivo: `framework/ejemplo.md` produz `/docs/framework/ejemplo/`. O índice de busca inclui título, descrição e corpo completo. Não requer um serviço de busca nem envia consultas a terceiros. A interface busca localmente após carregar `/search.json`. ## Rotas dos exemplos | Rota | Finalidade | | --- | --- | | `/labs/` | Oito receitas de APIs WU com verificações e limpeza observáveis | | `/labs/api/` | Acesso compatível ao mesmo laboratório de receitas | | `/labs/composition/` | Dois hosts WU: construtor React e inspetor Vue | | `/labs/backend/` | Serviços e RPC: cliente, contrato e provedor | O guia [Como executar os exemplos](/pt/docs/guides/running-examples/) propõe o percurso de leitura e prática. O explorador `/api/` é a referência de assinaturas e contratos; cada exemplo vincula o capítulo pertinente. ## Composição e ciclo de vida reais O shell importa o runtime no cliente. Cada módulo expõe `register(wu)` e define seu ciclo de vida. O host inicializa a configuração com manifesto e concessões e monta a app em um contêiner dedicado. Em [Composição](/pt/labs/composition/), os controles de montar/desmontar chamam o ciclo de vida WU real. O construtor React e o inspetor Vue compartilham `docs.lab.counter`, `docs.lab.lastCommand` e eventos `docs:lab:*` durante a mesma visita. Cada app recebe uma fachada com escopo e libera seus listeners e a raiz do framework ao ser desmontada. Uma mudança de documento reinicia o contexto; o exemplo não tem persistência remota. O [laboratório de APIs](/pt/labs/) executa cada receita em sua própria instância WU no documento atual. Os fixtures são montados diretamente em Shadow DOM e seus recursos são liberados ao terminar. Os registros de Composição permanecem independentes. O recibo distingue asserções, limpeza confirmada e recursos ainda pendentes. Apenas o código fixo da documentação é executado. Em [Serviços e RPC](/pt/labs/backend/), duas aplicações são montadas com concessões separadas. O cliente consome um contrato versionado e solicita uma resposta ao provedor. O [guia do serviço](/pt/docs/guides/browser-backend/) explica identidade, versões, cancelamento, respostas e remoção do provedor. `apps/systems-lab/` mantém o executor Worker, os convidados compilados e suas fixtures de teste. O serviço reutiliza essa infraestrutura WASM/WASI para processar dados no navegador; uma terceira app Systems Lab não é montada na UI pública. Essa decisão de implementação não muda o contrato WU consumido pelo cliente. Os exemplos de SSR, IA e MCP estão incluídos em `examples/`. O build gera um ZIP portátil em `/examples/wu-server-recipes.zip`, com seu manifesto npm e testes. O portal estático não inicia automaticamente um relay MCP. ## Leitura e acessibilidade O conteúdo do manual é entregue como HTML estático. A navegação e o texto funcionam sem JavaScript. A busca, os botões de copiar e o laboratório precisam de JavaScript. Há um link para pular para o conteúdo, landmarks, estado de página ativa, foco visível e redução de movimento. Em telas estreitas, o índice de capítulos vira uma faixa com rolagem e a busca permite chegar diretamente a qualquer capítulo. ## Política editorial Cada capítulo explica finalidade, assinatura, configuração, exemplos e limites. Uma capacidade presente nos tipos, mas ausente da exportação pública, é sinalizada. Os fragmentos devem usar APIs existentes e links para o contrato completo. Os manuais do framework e da CLI também ficam junto ao código. Ao mudar um contrato, atualize sua referência, exemplos e testes e gere o portal novamente. Consulte [versões e distribuição](/pt/sources/) antes de mudar a versão do runtime. ## Documentação em quatro idiomas O idioma principal do portal é inglês. O seletor mantém o capítulo, os filtros e a seção atual ao mudar para chinês simplificado, português ou espanhol. Os links de idioma também funcionam sem JavaScript; a busca e os laboratórios requerem JavaScript. | Idioma | Prefixo das rotas | | --- | --- | | Inglês | `/` | | Chinês simplificado | `/zh-cn/` | | Português | `/pt/` | | Espanhol | `/es/` | Astro gera cada capítulo e seu download Markdown nos quatro idiomas. Cada página tem seu próprio `lang`, URL canônica e links `hreflang`; o sitemap relaciona suas versões. O índice de busca contém os textos e links do idioma ativo. As traduções dos manuais e das fichas de APIs ficam em `src/i18n/`. O gerador combina essas traduções com os blocos de código comuns e produz a coleção `src/content/localized/`. Os templates compartilhados de `src/views/` usam mensagens explícitas para seus controles e textos. O shell define o idioma antes de carregar as aplicações React, Vue e Lit; o runner do laboratório também recebe o idioma em sua URL. As rotas dos módulos, os assets e os ZIPs para download são compartilhados entre idiomas. Os comandos, nomes de apps, canais, permissões e mensagens literais do código de exemplo mantêm seu valor: traduza a explicação, mas mantenha o que o leitor precisa copiar ou verificar. Por isso, os quatro guias do contador baixam os mesmos arquivos executáveis. Para atualizar uma tradução, execute `npm run i18n:extract`, complete as chaves pendentes e execute `npm run i18n:build`. `npm run check:i18n` verifica a cobertura e se as traduções mantêm código, links, tabelas e placeholders. `npm run test:i18n` verifica as rotas e os percursos interativos com um servidor do portal ativo. O build de produção falha se faltar uma tradução obrigatória.