Cómo está construido el portal

Estructura del proyecto

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

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

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.

Añadir un capítulo

Crea un Markdown bajo src/content/docs/ con un frontmatter válido:

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

La guía Cómo ejecutar los ejemplos 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, 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 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 se montan dos aplicaciones con grants separados. El cliente consume un contrato versionado y solicita una respuesta al proveedor. La guía del servicio 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 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.

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.