Builders

Empieza por la distinción que lo gobierna todo: en Astro el código de un componente .astro se ejecuta en BUILD (en tu máquina o en CI), no en el navegador. El resultado es HTML plano. MOONKEY es exactamente esto: `astro.config.mjs` declara `i18n` con `fallbackType: 'rewrite'` y NO usa SSR. Cuando corres `npm run build`, Astro recorre `src/pages/`, ejecuta cada .astro una vez por locale y escribe HTML a `dist/`. No hay servidor en producción: Cloudflare Pages sirve archivos. Eso es lo que hace que `moonkeylab.pages.dev` cargue en milisegundos.

Crea el esqueleto desde cero para verlo sin magia: `npm create astro@latest mi-sitio -- --template minimal --no-install`, luego `cd mi-sitio && npm install && npm run dev`. Abre `http://localhost:4321`. Edita `src/pages/index.astro` y mira que un `const hoy = new Date()` impreso con `{hoy}` se congela en el momento del build cuando haces `npm run build`. Ese es el aha-moment: el JS del frontmatter (entre los `---`) corre una vez, no en cada visita.

Ahora el control fino: las islas. Por defecto un componente de framework (React/Svelte) en Astro se renderiza a HTML estático SIN su JS. Solo si le pones una directiva `client:*` se hidrata. `client:load` hidrata al cargar, `client:visible` cuando entra en viewport, `client:idle` cuando el hilo está libre. Regla de oficio: empieza SIN directiva. Solo añade `client:visible` cuando el componente NECESITA interactividad real. En MOONKEY el `IntersectionObserver` de reveal vive en `Layout.astro` como un `<script>` global, no como una isla por página — eso es la decisión correcta: un script de 15 líneas en vez de hidratar un framework entero.

Vite es el motor que está debajo de Astro y también el de Espejo (que es una SPA React pura: `vite.config.ts`, `@vitejs/plugin-react`). La diferencia: Espejo SÍ envía React al navegador porque necesita estado interactivo en vivo (lecturas de cámara con MediaPipe, navegación con react-router). Esa es la línea divisoria real del oficio: ¿el contenido es mayormente lectura (web de XNLAB, MOONKEY) o es una app con estado denso (Espejo)? Lo primero pide Astro/SSG; lo segundo, Vite+SPA. No mezcles religiones: no metas una SPA entera dentro de Astro cuando el 95% es contenido.

Mide, no opines. Corre `npm run build` y mira el tamaño de `dist/`. En MOONKEY un build de página de contenido debería tener ~0KB de JS de página (solo el script de reveal compartido). Abre DevTools → Network, recarga con caché vacía y filtra por JS: si ves un bundle de framework en una página que es solo texto, has metido una directiva `client:*` de más o un import que arrastra una librería pesada al cliente. El comando `npx astro build --verbose` te lista qué se prerenderiza.

Failure mode clásico: importar una librería de fecha/markdown/iconos en el frontmatter creyendo que es build-only, pero usarla dentro de un `<script>` cliente o pasarla a una isla — y de pronto va al bundle. Otra: olvidar que `import.meta.env` en Astro distingue `PUBLIC_*` (va al cliente) del resto (se queda en build). Si una variable que creías privada aparece en `dist/`, la prefijaste mal. Y la trampa de Vite: cualquier cosa bajo `public/` se copia verbatim sin procesar — no pongas ahí secretos ni esperes que Vite optimice esos assets.

Un design token es una variable con nombre semántico, no un valor crudo repetido. MOONKEY define los suyos en `src/styles/global.css`: `--surface-base: #f8fafc`, `--text-primary: #0f172a`, más la paleta emerald/violet/amber. La regla de oro: los componentes NUNCA usan el hex directo, usan el token. Así `--surface-base` aparece una vez; si cambia la paleta, cambia un sitio. El antipatrón es escribir `color: #0f172a` en cada card — has acoplado 30 archivos a un valor que debería tener nombre.

El caso más instructivo del oficio está en Espejo, porque ahí los tokens son DINÁMICOS por tenant. Mira `src/brand/BrandProvider.tsx`: la función `applyTheme(brand)` hace `root.style.setProperty('--brand', brand.accent)` y deriva `--brand-soft`, `--brand-line`, `--brand-glow` con una función `withAlpha(hex, a)` que convierte el hex de marca en rgba con transparencia. Toda la UI pública de Espejo pinta con `var(--brand)`. Resultado: el mismo código sirve a Luna Rosa (rosa `#e58fb0`) y a cualquier influencer, cambiando UN campo `accent`. Eso es un design system que es también el motor del white-label.

Componente vs clase suelta: un componente encapsula estructura + tokens + comportamiento bajo un nombre. MOONKEY tiene `PromptBlock`, `AnimalIcon`, `MoonkeyLogo`, `FlowDiagram` en `src/components/`. La señal de que necesitas un componente: copias el mismo bloque de markup+clases una tercera vez. Hasta dos veces, duplica; a la tercera, extrae. No abstraigas antes — la abstracción prematura de un componente con 8 props 'por si acaso' es peor que la duplicación honesta.

Con Tailwind hay una trampa específica que MOONKEY documenta explícitamente: NUNCA interpoles clases como `bg-${theme}`. Tailwind hace tree-shaking escaneando el código en busca de strings de clase COMPLETOS en build; una clase construida en runtime no existe en el CSS generado y se renderiza sin estilo. Por eso `galaxy.ts` tiene un objeto `THEME` que mapea cada constelación a sus clases literales (`violet`, `amber`, `emerald`…) ya escritas. La lección: las clases dinámicas se resuelven con un MAPA de strings literales, no con interpolación.

Tipografía como token de sistema: MOONKEY fija `font-display` = Space Grotesk para h1–h3, Inter para body, JetBrains Mono para labels (`.label` = mono uppercase tracking-widest emerald-600). Eso no es decoración suelta: es una decisión codificada una vez que toda la app hereda. Si cada heading eligiera su propia fuente, no tendrías marca, tendrías ruido. El sistema vive en la capa de tokens/utilidades, no en cada `<h1>`.

Cómo verificar coherencia: haz un grep de valores crudos que NO deberían existir fuera del archivo de tokens. `grep -rn '#[0-9a-fA-F]\{6\}' src/components/` en MOONKEY debería devolver casi nada — si un hex aparece en un componente, es un token fugado que hay que reemplazar por `var(--token)`. Ese grep es tu linter de coherencia visual hecho a mano, y deberías correrlo antes de cada merge.

Multi-tenant significa: una instancia del software, muchos clientes (tenants) que la perciben como suya. White-label añade: cada tenant la ve con SU marca, sin rastro de la tuya. Espejo es el caso canónico — `src/brand/types.ts` lo dice en el comentario: 'cada influencer es un tenant con su marca'. El tenant se identifica por un `slug` en la URL (`/r/<slug>`) y todo —nombre, accent, glyph, voz, qué lecturas se ofrecen, el CTA de upsell— sale de un objeto `Brand`. La app pública entera se pinta a partir de ese objeto.

El corazón arquitectónico es el SEAM de datos. Mira `src/brand/store.ts`: define una `interface Store` con firmas async (`getBrand`, `listBrands`, `saveBrand`, `addSubscriber`, `listSubscribers`) y una implementación `LocalStore` sobre localStorage. El comentario lo deja explícito: 'Hoy: localStorage. Mañana: Supabase (mismas firmas). La UI nunca toca el almacenamiento directamente, solo este interfaz.' Esa interfaz es la costura: la UI depende de la ABSTRACCIÓN, no de la implementación. Cambiar de backend = escribir una nueva clase que implemente `Store`, sin tocar un solo componente.

Cómo el tenant llega a la UI: `BrandProvider.tsx` recibe el `slug`, llama `store.getBrand(slug)`, y si existe hace `applyTheme(brand)` y mete el brand en un Context React (`useBrand()`). Si no existe, marca `notFound`. Patrón limpio: un punto de entrada resuelve el tenant, aplica su tema, y lo provee a todo el árbol. Cualquier componente hace `const brand = useBrand()` y pinta lo suyo. Nadie más toca el storage ni decide el tema.

El aislamiento entre tenants es la línea roja del white-label, y aquí está el riesgo real: `listSubscribers(slug)` filtra por `brandSlug`. En localStorage eso es trivial pero FRÁGIL — todo vive en el mismo navegador, no hay frontera de seguridad real. El momento crítico es la migración a Supabase: ahí el aislamiento DEBE moverse a Postgres RLS (una fila de subscriber solo es visible para su tenant), exactamente la disciplina que MOONKEY aplica con `is_admin()` y políticas self-or-admin. En multi-tenant real, el filtro `WHERE slug = ...` en el cliente NO es seguridad; la seguridad es RLS en la base.

Configuración por tenant sin ramas de código: fíjate que Espejo no tiene `if (tenant === 'lunarosa')` en ningún sitio. La variación es DATOS (`Brand.readings`, `Brand.voice`, `Brand.offer`), no lógica condicional. Esa es la regla del white-label sano: las diferencias entre clientes viven en configuración (datos), nunca en bifurcaciones de código. En cuanto escribes el primer `if (cliente X)` has empezado a forkear el producto y a perder la economía del modelo.

Hay un guardarraíl ético específico en Espejo que no es opcional: la memoria del proyecto marca que NO se construye sifón encubierto de leads ni venta de datos personales/biométricos — solo datos consentidos de primera parte y agregados anónimos. En un producto multi-tenant que maneja datos de los usuarios finales de tus clientes, el modelo de consentimiento (`types.ts` tiene versión del texto de consentimiento aceptado y `Brand.legal.responsible`) es parte de la arquitectura, no un añadido legal posterior. El responsable del tratamiento es el influencer-tenant, y eso debe estar modelado en los datos.

MOONKEY corre 6 locales — `['es','en','th','fr','it','ch']` (config en `src/i18n/config.ts`). ES vive en la raíz; el resto bajo prefijo (`/en/`, `/th/`, `/fr/`, `/it/`, `/ch/`). La pieza que evita duplicar páginas es Astro i18n con `fallbackType: 'rewrite'` en `astro.config.mjs`: durante el build, Astro REESCRIBE cada página con el contexto de cada locale, así que un único `index.astro` genera 6 HTML traducidos. No hay `pages/en/index.astro`, `pages/fr/index.astro`… hay UNO. Esa es la regla central: una plantilla, N salidas.

El fallback es lo que hace el sistema robusto sin traducirlo todo de golpe: `astro.config.mjs` declara `fallback: { en:'es', th:'es', fr:'es', it:'es', ch:'es' }`, y la función `useTranslations` en `src/i18n/utils.ts` implementa la misma cadena: `dict[key] ?? base[key] ?? key`. Es decir: si falta una clave en francés, cae a español; si tampoco está, devuelve la clave misma (visible, fácil de cazar). Esto te deja LANZAR con traducciones parciales sin romper nada — el francés muestra español donde aún no tradujiste, no una página rota.

MOONKEY usa TRES patrones de i18n y CLAUDE.md avisa de la inconsistencia, lo cual es una lección de oficio en sí: (1) diccionario `src/i18n/ui.ts` con `t('key')` para chrome/nav corto (~240 keys); (2) objetos de contenido inline con `cLocale = (es|th) ? locale : 'en'` que colapsa FR/IT/CH a EN, para contenido pesado como el currículum; (3) páginas `src/pages/en/*.astro` que sobreescriben SOLO en inglés. El patrón 3 es deuda: hay 5 páginas raíz hardcodeadas en español, así que `/th/fr/it/ch` muestran ES en ellas. Lección: elige UN patrón dominante (el diccionario con fallback) y trata los otros como deuda a pagar, no como variedad sana.

El bug más caro de i18n con prefijos es el href crudo. Si escribes `<a href='/cuenta'>` desde una página bajo `/fr/`, mandas al usuario fuera de su idioma. Por eso MOONKEY tiene `localizedPath(pathname, target)` en `utils.ts`: quita el prefijo de locale actual, reconstruye la ruta y le antepone el target (`/fr/cuenta`), dejando ES en raíz. CLAUDE.md lo marca como obligatorio: 'usa `localizedPath('/ruta', locale)`, nunca `/ruta` crudo'. Internaliza esto: en un sitio con prefijos de idioma, CADA enlace pasa por la función de localización, sin excepción.

Detectar el locale activo tiene una sutileza que `utils.ts` resuelve: `resolveLocale(currentLocale, pathname)` prefiere `Astro.currentLocale` sobre la detección por URL, porque durante un rewrite de fallback la URL puede haber perdido el prefijo y solo el contexto de Astro sabe el locale real. Si detectas locale solo por `pathname.split('/')` te equivocas justo en las páginas que usan fallback. Regla: confía en el contexto del framework primero, en la URL como respaldo.

El selector de idioma necesita dos diccionarios separados: `LOCALE_LABELS` (ES, EN, TH…) para el switcher compacto y `LOCALE_NAMES` (Español, ไทย, Italiano…) para el dropdown completo. Y ojo a los casos raros: 'ch' aquí es Deutsch (CH), suizo-alemán, no chino — un comentario en `config.ts` lo aclara. Esa clase de ambigüedad (un código que parece otro idioma) es exactamente lo que documentas en el código para que nadie traduzca al idioma equivocado seis meses después.

MOONKEY se despliega en Cloudflare Pages (`moonkeylab.pages.dev`) desde el repo `garciafradepablo-pixel/xop`. El flujo base: conectas el repo de GitHub a Cloudflare Pages, defines el build command (`npm run build`) y el output directory (`dist/` en Astro). Cada push a main dispara un build en CI y publica. No subes archivos a mano: el deploy es una consecuencia de git push. Eso te da reproducibilidad — lo que está en producción es exactamente lo que está en el commit.

Para una SSG pura como MOONKEY, Cloudflare solo sirve los HTML estáticos del build; no hay runtime de servidor. Esto es clave para el modelo de seguridad (lo verás en Ops): como no hay handler server-side, el único env que importa en producción es el que se inyectó EN BUILD. Si tu app necesita lógica server (no es el caso de MOONKEY ni XNLAB de contenido), ahí entran Cloudflare Functions/Workers — pero no las metas si no las necesitas.

La frontera de los secretos es LA lección de este módulo. En Astro/Vite, las variables `PUBLIC_*` (Astro) o `VITE_*` (Vite puro como Espejo) se inyectan en el bundle del cliente — son VISIBLES para cualquiera que abra DevTools. Todo lo demás se queda en build. MOONKEY pone la Supabase anon key como pública a propósito: CLAUDE.md dice 'solo anon key' en `src/lib/supabase.ts`, porque la anon key está DISEÑADA para ser pública (su poder lo limita RLS, no el secreto). La regla absoluta: la `service_role` key NUNCA lleva prefijo público, NUNCA va a un sitio estático. Si la pones, está en el bundle, y es game over.

En Cloudflare configuras las env vars en el dashboard (Settings → Environment variables), separando Production de Preview. Las que tu build necesita exponer al cliente llevan el prefijo correcto; las que solo usa el proceso de build (tokens de API de terceros para generar contenido) no lo llevan y no acaban en `dist/`. Verificación obligatoria post-deploy: descarga tu JS de producción y haz `grep -ri 'service_role\|secret\|sk_'` sobre `dist/`. Si algo aparece, tienes una fuga que rotar inmediatamente.

Dominio propio: en Cloudflare Pages, Custom domains → añades tu dominio, Cloudflare crea los registros DNS (si el dominio está en Cloudflare es automático; si no, añades un CNAME al `*.pages.dev`). HTTPS es automático. El `.pages.dev` sigue funcionando como URL de respaldo. Para previews, cada PR/rama genera su propia URL efímera — úsalas para revisar cambios antes de mergear a main, sin tocar producción.

Failure modes de deploy reales: (1) el build pasa en local pero falla en CI porque una dependencia estaba en `node_modules` local pero no en `package.json` — corre `npm ci` (no `install`) en limpio para reproducir CI. (2) Variables que existen en local (`.env`) pero no configuraste en el dashboard → build pasa pero la app falla en runtime con undefined. (3) El warning cosmético de Astro sobre `Astro.request.headers` en builds estáticos con i18n rewrite — `astro.config.mjs` lo documenta como inofensivo, el build pasa. No persigas warnings que la config ya marcó como esperados.

Recupera el seam de BD-03: en Espejo `src/brand/store.ts` define `interface Store` con firmas async y `LocalStore` la implementa sobre localStorage. El comentario es la tesis entera del módulo: 'Hoy: localStorage. Mañana: Supabase (mismas firmas).' Porque la interfaz YA es async (`Promise<Brand | null>`), la UI no nota la diferencia entre leer de memoria o de la red — el `await` ya está ahí. Una API síncrona habría hecho la migración imposible sin tocar cada llamada. Diseñar la costura async desde el día uno es la decisión que paga aquí.

El swap concreto: escribes una clase `SupabaseStore implements Store`. `getBrand(slug)` pasa de leer localStorage a `await supabase.from('brands').select().eq('slug', slug).single()`. `addSubscriber` pasa de `write()` a `.insert()`. Las firmas son IDÉNTICAS. Al final, una línea cambia el mundo: `export const store: Store = new SupabaseStore()` en vez de `new LocalStore()`. Cero componentes tocados. Eso es lo que significa 'cambiar la capa de datos sin reescribir la app': el resto del código depende de `Store`, no de localStorage.

Pero migrar el almacenamiento es la mitad fácil. La mitad seria es la SEGURIDAD, y aquí cambia el modelo entero. En localStorage no hay fronteras: todo vive en el navegador del usuario. En Supabase, como el cliente solo lleva la anon key (MOONKEY: `src/lib/supabase.ts`, 'solo anon key'), la autoridad NO es el cliente — es Postgres RLS. MOONKEY lo formula sin ambigüedad: 'autoridad = RLS, no el cliente'. Cuando Espejo migre los subscribers, el filtro `WHERE brandSlug = slug` que hoy hace en JS DEBE convertirse en una política RLS que garantice que un tenant solo lee SUS subscribers. El filtro de cliente era conveniencia; RLS es seguridad.

Patrón de referencia de RLS en MOONKEY: las tablas `profiles/progress/feedback/proofs` tienen SELECT 'self-or-admin' vía `is_admin()` (función SECURITY DEFINER), verificado por impersonación — un no-admin no puede leer filas ajenas. `proofs` INSERT exige sesión y liga `user_id = auth.uid()` (política `proofs_insert_self`). Columnas sensibles (`role`, `founder_badge`) son inmutables para no-admins vía trigger guard, así que nadie se auto-escala. Esa es la plantilla mental para cualquier migración: cada operación (SELECT/INSERT/UPDATE) necesita una política que se cumpla AUNQUE el atacante controle el cliente.

Higiene de migración de datos: necesitas un esquema (tabla `brands`, tabla `subscribers` con `brand_slug`), aplicado como MIGRACIÓN versionada (no SQL suelto en la consola — MOONKEY: 'cambios de RLS/seguridad: migración versionada + `get_advisors` después'). Luego un script de una sola vez que lea el localStorage existente y haga `insert` masivo al backend, idempotente (que puedas re-correr sin duplicar). Y un periodo de doble escritura opcional si no puedes parar la app: escribes a ambos hasta confirmar paridad, luego cortas localStorage.

Ojo a la frontera ética que arrastra Espejo: la memoria del proyecto prohíbe sifón encubierto de datos personales/biométricos; solo datos consentidos de primera parte y agregados anónimos. Migrar a backend AUMENTA el poder de los datos (ahora persisten, se cruzan, se exportan), así que el modelo de consentimiento que en localStorage era casi teórico se vuelve real y auditable. La migración técnica y la responsabilidad sobre los datos suben juntas — no migres el almacenamiento sin migrar también las garantías de privacidad.