# Cómo está construido el portal
Recorre el shell Astro, las recetas de APIs WU, la composición React/Vue y el ejemplo de servicios con contratos y RPC.
## Estructura del proyecto
```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
```
El `srcDir` de Astro apunta desde `shell/` a `../src`. Se conserva un shell identificable sin esconder el contenido documental dentro de una aplicación cliente.
## Desarrollo
```sh
npm ci
npm run dev
```
El lockfile fija WU Framework 4.0.0 de npm, tanto para `wu-framework` como para el alias `wu-framework-release`. Portada, laboratorios y descargas usan esa versión publicada. Composición y Servicios y RPC mantienen una URL CDN exacta y un paquete de respaldo de la misma versión.
`npm run dev` compila los laboratorios y arranca Astro. Los cambios en Markdown, componentes del host y estilos entran por el servidor de desarrollo. Después de modificar las apps o su UI compartida, ejecuta `npm run build:apps` y recarga el laboratorio.
## Build reproducible
```sh
npm run build
npm run preview
```
El primer paso empaqueta las aplicaciones, los runners y sus componentes Lit. Después Astro genera documentos, búsqueda, explorador de APIs y páginas de ejemplos. El servicio incluye sus artefactos de ejecución; el build normal no requiere Zig. Todo lo necesario para servir el portal queda en `dist/`.
Los scripts npm construyen este repositorio de documentación. Para un workspace creado con WU CLI, sigue las convenciones y la configuración de [wu build](/es/docs/cli/build/).
## Añadir un capítulo
Crea un Markdown bajo `src/content/docs/` con un frontmatter válido:
```yaml
---
title: Título del capítulo
description: Qué aprenderá el lector en esta página.
section: Framework
order: 20
---
```
Usa `##` para secciones navegables y `###` para subsecciones. Astro obtiene el índice lateral y los enlaces anterior/siguiente a partir de la colección. La ruta deriva del nombre del archivo: `framework/ejemplo.md` produce `/docs/framework/ejemplo/`.
El índice de búsqueda incluye título, descripción y cuerpo completo. No requiere un servicio de búsqueda ni envía consultas a terceros. La interfaz busca localmente después de cargar `/search.json`.
## Rutas de los ejemplos
| Ruta | Propósito |
| --- | --- |
| `/labs/` | Ocho recetas de APIs WU con comprobaciones y limpieza observables |
| `/labs/api/` | Acceso compatible al mismo laboratorio de recetas |
| `/labs/composition/` | Dos hosts WU: constructor React e inspector Vue |
| `/labs/backend/` | Servicios y RPC: cliente, contrato y proveedor |
La guía [Cómo ejecutar los ejemplos](/es/docs/guides/running-examples/) propone el recorrido de lectura y práctica. El explorador `/api/` es la referencia de firmas y contratos; cada ejemplo enlaza el capítulo pertinente.
## Composición y lifecycle reales
El shell importa el runtime en el cliente. Cada módulo expone `register(wu)` y define su lifecycle. El host inicializa la configuración con manifest y grants, y monta la app en un contenedor dedicado.
En [Composición](/es/labs/composition/), los controles de montar/desmontar llaman al lifecycle WU real. El constructor React y el inspector Vue comparten `docs.lab.counter`, `docs.lab.lastCommand` y eventos `docs:lab:*` durante la misma visita. Cada app recibe una facade scoped y libera sus listeners y su raíz de framework al desmontarse. Un cambio de documento reinicia el contexto; el ejemplo no tiene persistencia remota.
El [laboratorio de APIs](/es/labs/) ejecuta cada receta en una instancia propia de WU dentro del documento actual. Monta los fixtures directamente en Shadow DOM y libera sus recursos al terminar. Los registros de Composición permanecen independientes. El recibo distingue las comprobaciones, la limpieza confirmada y los recursos que siguen pendientes. Solo se ejecuta código fijo de la documentación.
En [Servicios y RPC](/es/labs/backend/) se montan dos aplicaciones con grants separados. El cliente consume un contrato versionado y solicita una respuesta al proveedor. La [guía del servicio](/es/docs/guides/browser-backend/) explica identidad, versiones, cancelación, respuestas y retirada del proveedor.
`apps/systems-lab/` conserva el ejecutor Worker, los invitados compilados y sus fixtures de pruebas. El servicio reutiliza esa infraestructura WASM/WASI para procesar datos en el navegador; no se monta una tercera app Systems Lab en la UI pública. Esta decisión de implementación no cambia el contrato WU que consume el cliente.
Los ejemplos de SSR, IA y MCP se incluyen en `examples/`. El build genera un ZIP portable en `/examples/wu-server-recipes.zip`, con su manifiesto npm y pruebas. El portal estático no inicia automáticamente un relay MCP.
## Lectura y accesibilidad
El contenido del manual se entrega como HTML estático. La navegación y el texto funcionan sin JavaScript. La búsqueda, los botones de copiar y el laboratorio necesitan JavaScript.
Hay un enlace para saltar al contenido, landmarks, estado de página activa, foco visible y reducción de movimiento. En pantallas estrechas, el índice de capítulos se convierte en una franja desplazable y la búsqueda permite llegar directamente a cualquier capítulo.
## Política editorial
Cada capítulo explica propósito, firma, configuración, ejemplos y límites. Una capacidad presente en tipos pero ausente del export público se señala. Los fragmentos deben utilizar APIs existentes y enlaces al contrato completo.
Los manuales del framework y CLI también viven junto a su código. Al cambiar un contrato, actualiza su referencia, ejemplos y pruebas, y vuelve a generar el portal. Consulta [versiones y distribución](/es/sources/) antes de cambiar la versión del runtime.
## Documentación en cuatro idiomas
El idioma principal del portal es inglés. El selector conserva el capítulo, los filtros y la sección actual al pasar a chino simplificado, portugués o español. Los enlaces de idioma funcionan también sin JavaScript; la búsqueda y los laboratorios requieren JavaScript.
| Idioma | Prefijo de las rutas |
| --- | --- |
| Inglés | `/` |
| Chino simplificado | `/zh-cn/` |
| Portugués | `/pt/` |
| Español | `/es/` |
Astro genera cada capítulo y su descarga Markdown para los cuatro idiomas. Cada página tiene su propio `lang`, URL canónica y enlaces `hreflang`; el sitemap relaciona sus versiones. El índice de búsqueda contiene los textos y enlaces del idioma activo.
Las traducciones de los manuales y las fichas de APIs están en `src/i18n/`. El generador combina esas traducciones con los bloques de código comunes y produce la colección `src/content/localized/`. Las plantillas compartidas de `src/views/` usan mensajes explícitos para sus controles y textos. El shell establece el idioma antes de cargar las aplicaciones React, Vue y Lit; el runner del laboratorio recibe también el idioma en su URL.
Las rutas de los módulos, los assets y los ZIP descargables se comparten entre idiomas. Los comandos, nombres de apps, canales, permisos y mensajes literales del código de ejemplo conservan su valor: traduce la explicación, pero mantén lo que el lector debe copiar o comprobar. Por eso las cuatro guías del contador descargan los mismos archivos ejecutables.
Para actualizar una traducción, ejecuta `npm run i18n:extract`, completa las claves pendientes y ejecuta `npm run i18n:build`. `npm run check:i18n` comprueba la cobertura y que las traducciones conserven código, enlaces, tablas y placeholders. `npm run test:i18n` comprueba las rutas y los recorridos interactivos con un servidor del portal activo. El build de producción falla si falta una traducción requerida.