Biblioshare

PWA para llevar el registro de tus hobbies de consumo cultural — libros, películas y series — en un solo sitio. Un Goodreads + Letterboxd + tracker de series unificado, con estética centrada en portadas, perfiles públicos, clubes de lectura y sagas.

Next.js 16 (App Router) + React 19 + Supabase + Tailwind, desplegado en Vercel, con wrapper Android vía Capacitor.

Arranque

Node 22.22.2+ de la línea 22, 24.15.0+ de la 24 o 26+ (^22.22.2 || ^24.15.0 || >=26.0.0). .nvmrc fija 22.23.1 y la CI usa esa línea, ambas compatibles; Node 23 queda fuera del rango de jsdom. El shell suele arrancar en otra versión, así que fnm use antes de nada.

npm install
cp .env.example .env.local   # y rellenar (ver «Entornos»)
npm run dev                  # http://localhost:3000

Script	Qué hace
npm run dev	Servidor de desarrollo
npm run build / start	Build de producción y arranque
npm run lint	ESLint
npm test	Vitest (unidad) — requiere una versión admitida de Node
npm run test:e2e	Playwright (e2e) — necesita un servidor levantado; reutiliza el que haya

Documentación

Cada documento tiene un solo trabajo y una cabecera de frescura que dice si puedes fiarte de él. La regla general: donde un doc canónico contradiga a otro, mira la tabla de gobernanza de abajo para saber cuál manda.

Doc	Manda para	Tipo
Arquitectura	Rutas, capas, flujo de datos, mapa de módulos	Canónico · vs código
Modelo de datos	Esquema: tablas, RLS, enums, migraciones	Canónico · vs prod
Trampas conocidas	Lo que ya ha costado horas. Léelo antes de depurar algo raro	Canónico
Proyecto	Qué existe hoy (mapa de features por dominio)	Canónico
Seguridad	Modelo de permisos: RLS, roles, grants, excepciones	Canónico
Guía de UI	Patrones de UI y principios de diseño (derivados de la auditoría 2026-08)	Canónico
Glosario de UI	Cómo se llama cada concepto de cara al usuario. Se consulta ANTES de escribir copy	Canónico
Sistema de diseño	Los tokens: color, tipografía, forma, elevación, layout y los primitivos, con el porqué de cada uno. Formato DESIGN.md, legible por agentes

docs/superpowers/plans/ y specs/ son registro histórico: uno por feature, fechado y congelado. Explican por qué algo es como es, no cómo está hoy. Si contradicen a los docs de la tabla, mandan estos.

Los tres docs de diseño no compiten: se reparten la pantalla. DESIGN.md manda sobre los tokens (qué color, qué tamaño, qué radio, qué sombra, y el porqué medido de cada uno); docs/UI-GUIA.md manda sobre los patrones (cuántas columnas, dónde vive lo destructivo, qué es tab y qué es pill); docs/REFERENCIA-VISUAL.md guarda las capturas y el flujo de prototipado. Un valor de color o de tipografía se cambia en globals.css y se refleja en DESIGN.md; una regla de composición se discute en UI-GUIA.md. PRODUCT.md, en la raíz, es la verdad de producto (usuarios, plataforma, restricciones, accesibilidad) y no contiene nada visual.

Gobernanza documental (cómo NO desincronizarse)

Cuatro reglas, para que la doc no vuelva a divergir del proyecto:

1. Una fuente de verdad: el repo (git). El Proyecto de Claude refleja el subconjunto canónico (arquitectura, modelo de datos, visión, backlog), no lo origina.
2. Un trabajo por documento. La verdad actual (arriba) va en docs pequeños y verificables; la historia va en specs//plans/ y en decisiones.md (append-only, nunca se reescribe → no puede desincronizarse).
3. Contrato de frescura en cada doc. Canónico → [Canónico · verificado contra {prod|código} el AAAA-MM-DD]. Histórico → [Histórico · congelado el AAAA-MM-DD].
4. El esquema se verifica contra prod, no se mantiene a ciegas. Cuando dudes, corre el chequeo de deriva.

Entornos (Supabase)

Dos proyectos remotos separados y un entorno local desechable para pruebas:

• Producción — lo usa el deploy de Vercel (variables configuradas allí).

• Dev — lo usa el desarrollo local; .env.local apunta aquí. Todo lo que hagas con npm run dev (búsquedas que cachean catálogo, usuarios de prueba, imports) escribe solo en dev.

• Local desechable — Docker + Supabase CLI 2.116.0 + Node 22. El esquema completo se reconstruye desde cero sin acceder a los proyectos remotos. Receta y limpieza en Pruebas con Supabase local.

El desarrollo habitual sigue apuntando a dev remoto; sus latencias condicionan los timeouts (ver Trampas). El entorno desechable usa variables de proceso locales y no necesita sobrescribir .env.local.

Regla de migraciones: primero en dev, se verifica, y después en producción. Añadir cada SQL a supabase/bootstrap/manifest.json en orden de dependencias y ejecutar npm run db:baseline. El generador rechaza migraciones omitidas o duplicadas. schema-baseline.sql es una entrada generada para psql, con inclusiones relativas, no un bloque pegable en el SQL editor. Solo sirve para una base Supabase vacía; nunca para actualizar un proyecto existente.

Android (Capacitor)

El wrapper carga server.url apuntando a la URL de producción, así que las sesiones nativas se mezclan con las de web en las métricas. El escáner de ISBN (ML Kit) solo existe en nativo — en el navegador ese control no se pinta.