Como o portal é construído

Estrutura do projeto

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

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

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.

Adicionar um capítulo

Crie um Markdown em src/content/docs/ com um frontmatter válido:

---
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

O guia Como executar os exemplos 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, 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 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, 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 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 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.

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.