theus-cli 0.2.82 → 0.2.84

package/vendor/theus-arsenal/skills/rendimiento-react/SKILL.md

@@ -1,567 +0,0 @@
----
-name: rendimiento-react
-description: Patrones de optimización de rendimiento para React y Next.js. Organiza más de 70 reglas en 8 categorías por prioridad — waterfalls, tamaño de bundle, lado servidor, fetching en cliente, re-renders, renderizado, micro-rendimiento de JS y patrones avanzados. Úsala al escribir, revisar o refactorizar código React/Next.js con foco en rendimiento.
----
-
-# Rendimiento en React
-
-Patrones de optimización de rendimiento para React 18/19 y Next.js. Esta skill organiza las reglas por prioridad y ofrece guía en forma de árbol de decisión para revisiones de código y refactorizaciones activas.
-
-## Cuándo activarla
-
-- Al escribir o revisar código React/Next.js con foco en rendimiento
-- Al diagnosticar cargas de página lentas, interacciones lentas o CPU alta en el cliente
-- Al auditar el tamaño del bundle o regresiones en las Core Web Vitals de Lighthouse
-- Al eliminar waterfalls en Server Components / rutas de API
-- Al reducir re-renders del lado del cliente
-- Al optimizar listas largas, animaciones o la hidratación
-- Al auditar decisiones de optimización en PRs que tocan `app/`, `pages/`, `components/` o capas de datos
-
-## Índice de prioridades
-
-| Prioridad | Categoría | Prefijo | Cuándo importa |
-|---|---|---|---|
-| 1 — CRÍTICA | Eliminación de waterfalls | `async-` | Siempre que un `await` va seguido de otro `await` independiente |
-| 2 — CRÍTICA | Optimización del tamaño de bundle | `bundle-` | JS de primera carga, imports por ruta, librerías de terceros |
-| 3 — ALTA | Rendimiento del lado servidor | `server-` | RSC, Server Actions, rutas de API, SSR |
-| 4 — MEDIA-ALTA | Fetching de datos en el cliente | `client-` | SWR / TanStack Query / `fetch` crudo en hooks |
-| 5 — MEDIA | Optimización de re-renders | `rerender-` | Actualizaciones de estado de alta frecuencia, propagación padre-hijo |
-| 6 — MEDIA | Rendimiento de renderizado | `rendering-` | Listas largas, animaciones, hidratación |
-| 7 — BAJA-MEDIA | Rendimiento de JavaScript | `js-` | Bucles calientes, asignaciones frecuentes |
-| 8 — BAJA | Patrones avanzados | `advanced-` | Integración de effect events, refs estables |
-
-## 1. Eliminación de waterfalls (CRÍTICA)
-
-> "Los waterfalls son el asesino de rendimiento #1" — cada `await` secuencial suma la latencia completa de la red.
-
-### Condiciones baratas antes del await
-
-Verifica condiciones síncronas (props, env, flags fijos) antes de esperar datos remotos.
-
-```ts
-// INCORRECTO
-async function Page({ id }: { id: string }) {
-  const flag = await getFlag("show-page");
-  if (!flag || !id) return null;
-  const data = await getData(id);
-  // ...
-}
-
-// CORRECTO — corta primero por la condición síncrona barata
-async function Page({ id }: { id: string }) {
-  if (!id) return null;
-  const flag = await getFlag("show-page");
-  if (!flag) return null;
-  const data = await getData(id);
-}
-```
-
-### Difiere los awaits hasta que se usen
-
-Mueve el `await` a la rama que usa el dato.
-
-```ts
-// INCORRECTO — espera antes de decidir si necesita el dato
-const user = await getUser(id);
-if (mode === "guest") return renderGuest();
-return renderUser(user);
-
-// CORRECTO
-if (mode === "guest") return renderGuest();
-const user = await getUser(id);
-return renderUser(user);
-```
-
-### Promise.all para trabajo independiente
-
-```ts
-// INCORRECTO — secuencial
-const user = await getUser(id);
-const posts = await getPosts(id);
-const followers = await getFollowers(id);
-
-// CORRECTO — en paralelo
-const [user, posts, followers] = await Promise.all([
-  getUser(id),
-  getPosts(id),
-  getFollowers(id),
-]);
-```
-
-### Dependencias parciales — arranca pronto, espera tarde
-
-```ts
-// CORRECTO — lanza todas las promesas y espera solo cuando cada resultado hace falta
-const userP = getUser(id);
-const postsP = getPosts(id);
-const profile = await getProfile(id);
-if (profile.private) return null;
-const [user, posts] = await Promise.all([userP, postsP]);
-```
-
-### Suspense para streaming
-
-Acerca los límites de `<Suspense>` a los datos para que la página pinte lo que pueda mientras los subárboles más lentos llegan por streaming. El costo: desplazamiento de layout cuando llega el contenido — reserva espacio (skeleton o `min-height`).
-
-### Server Components: paralelismo por composición
-
-```tsx
-// INCORRECTO — los awaits hermanos corren en secuencia dentro de un mismo componente
-export default async function Page() {
-  const user = await getUser();
-  const cart = await getCart();
-  return <View user={user} cart={cart} />;
-}
-
-// CORRECTO — divide en hijos; React los ejecuta en paralelo
-export default async function Page() {
-  return (
-    <View>
-      <UserSection />
-      <CartSection />
-    </View>
-  );
-}
-```
-
-## 2. Optimización del tamaño de bundle (CRÍTICA)
-
-### Imports directos, no barrels
-
-Los archivos barrel `index.ts` obligan al bundler a recorrer el grafo completo de módulos aunque el tree-shaking elimine la mayor parte. Los imports directos ahorran 200-800 ms de JS de primera carga en muchas apps reales.
-
-```ts
-// INCORRECTO
-import { Button, Card, Modal } from "@/components";
-
-// CORRECTO
-import { Button } from "@/components/Button";
-import { Card } from "@/components/Card";
-import { Modal } from "@/components/Modal";
-```
-
-Next.js 13.5+ incluye [Optimize Package Imports](https://nextjs.org/docs/app/api-reference/next-config-js/optimizePackageImports), que automatiza esto para los paquetes listados — úsalo; los imports directos manuales siguen siendo necesarios para las librerías no listadas.
-
-### Rutas analizables estáticamente
-
-```ts
-// INCORRECTO — anula el análisis del bundler y del trazado
-const mod = await import(`./pages/${name}`);
-
-// CORRECTO — explícito por rama
-const mod = name === "home" ? await import("./pages/home") : await import("./pages/about");
-```
-
-### Imports dinámicos para componentes pesados
-
-```tsx
-import dynamic from "next/dynamic";
-
-const HeavyChart = dynamic(() => import("./HeavyChart"), {
-  loading: () => <Skeleton />,
-  ssr: false, // cuando es solo-cliente
-});
-```
-
-### Difiere los scripts de terceros
-
-Carga analítica, logging y widgets de soporte DESPUÉS de la hidratación. Usa `next/script` con `strategy="afterInteractive"` (por defecto) o `"lazyOnload"`.
-
-### Carga condicional de módulos
-
-```tsx
-if (user.role === "admin") {
-  const { AdminPanel } = await import("./admin/AdminPanel");
-  // ...
-}
-```
-
-### Precarga en hover/focus
-
-Dispara `<link rel="preload">` o `import()` en hover para que el bundle ya esté en caché cuando el usuario haga clic.
-
-## 3. Rendimiento del lado servidor (ALTA)
-
-### Autentica las Server Actions como si fueran rutas de API
-
-Toda función `"use server"` es un endpoint público. Autentica Y autoriza dentro de la acción — nunca confíes en el control de acceso del Client Component que la invoca.
-
-```ts
-"use server";
-export async function deleteUser(formData: FormData) {
-  const session = await getSession();
-  if (!session?.user) throw new Error("No autorizado");
-  const targetId = String(formData.get("id"));
-  if (session.user.role !== "admin" && session.user.id !== targetId) {
-    throw new Error("Prohibido");
-  }
-  await db.user.delete({ where: { id: targetId } });
-}
-```
-
-### `React.cache()` para deduplicación por request
-
-```ts
-import { cache } from "react";
-
-export const getUser = cache(async (id: string) => {
-  return db.user.findUnique({ where: { id } });
-});
-```
-
-`React.cache` deduplica dentro de un mismo request. Llamar a `getUser("1")` desde tres Server Components en el mismo render = una sola consulta a la BD.
-
-### Caché LRU para datos entre requests
-
-Para datos que NO cambian por request (configuración, tablas de consulta), cachea fuera de React con una caché LRU o `unstable_cache`.
-
-### Evita la serialización duplicada en props de RSC
-
-Cuando un Server Component renderiza los mismos datos en varios Client Components, los datos se serializan una vez por consumidor. Sube el Client Component en el árbol y pasa children.
-
-### Eleva la E/S estática al ámbito de módulo
-
-```ts
-// CORRECTO — se ejecuta una vez al cargar el módulo
-const fontData = readFileSync(fontPath);
-
-export async function Page() {
-  return <Banner font={fontData} />;
-}
-```
-
-### Nada de estado mutable a nivel de módulo en RSC/SSR
-
-El estado de módulo en el servidor se comparte entre todos los requests — una condición de carrera entre usuarios. Usa almacenamiento con ámbito de request (`headers()`, `cookies()`, contexto asíncrono).
-
-### Minimiza los datos pasados a Client Components
-
-Serializa solo lo que el cliente necesita. Elimina campos, pagina y proyecta columnas en la capa de BD.
-
-### Paraleliza fetches anidados con Promise.all por elemento
-
-```ts
-const users = await getUsers();
-const enriched = await Promise.all(
-  users.map(async (u) => ({ ...u, posts: await getPostsFor(u.id) })),
-);
-```
-
-### Usa `after()` para trabajo no bloqueante
-
-El `after()` de Next.js 15 ejecuta trabajo después de enviar la respuesta — logging, calentamiento de caché, analítica.
-
-```ts
-import { after } from "next/server";
-export async function GET() {
-  const data = await getData();
-  after(() => logAnalytics(data));
-  return Response.json(data);
-}
-```
-
-## 4. Fetching de datos en el cliente (MEDIA-ALTA)
-
-### SWR / TanStack Query para deduplicación
-
-Varios componentes que llaman a `useUser(id)` deben compartir una sola petición de red y una sola entrada de caché. Usa SWR o TanStack Query — nunca improvises tu propio `useEffect` + `fetch` para datos compartidos.
-
-### Deduplica los listeners de eventos globales
-
-```tsx
-// INCORRECTO — cada componente añade el suyo
-useEffect(() => {
-  window.addEventListener("scroll", handler);
-  return () => window.removeEventListener("scroll", handler);
-}, []);
-
-// CORRECTO — un único listener compartido vía un hook + sujeto global
-const useScroll = createScrollHook(); // sujeto singleton por debajo
-```
-
-### Listeners pasivos para scroll
-
-```ts
-window.addEventListener("scroll", handler, { passive: true });
-```
-
-Mejora la fluidez del scroll; el listener no puede llamar a `preventDefault()`.
-
-### localStorage: versiona y minimiza
-
-- Guarda siempre un campo `version`; increméntalo al cambiar el esquema y migra o descarta los datos antiguos
-- Mantén los payloads pequeños — `localStorage` es síncrono y bloquea el hilo principal
-
-## 5. Optimización de re-renders (MEDIA)
-
-### No te suscribas a estado usado solo en callbacks
-
-```tsx
-// INCORRECTO — re-renderiza cada vez que cambia count
-const count = useStore((s) => s.count);
-const handler = () => doSomething(count);
-
-// CORRECTO — léelo una vez al invocar
-const handler = () => {
-  const count = useStore.getState().count;
-  doSomething(count);
-};
-```
-
-### Extrae el trabajo caro a componentes memoizados
-
-```tsx
-// CORRECTO — el hijo solo re-renderiza cuando cambia `items`
-const Heavy = memo(function Heavy({ items }: { items: Item[] }) {
-  return <Chart data={transform(items)} />;
-});
-```
-
-### Eleva las props por defecto no primitivas
-
-```tsx
-// INCORRECTO — un array nuevo en cada render rompe memo
-<List items={items ?? []} />
-
-// CORRECTO
-const EMPTY: Item[] = [];
-<List items={items ?? EMPTY} />
-```
-
-### Dependencias primitivas en efectos
-
-```tsx
-// INCORRECTO — identidad de objeto nueva en cada render
-useEffect(() => {}, [{ id, name }]);
-
-// CORRECTO — primitivas
-useEffect(() => {}, [id, name]);
-```
-
-### Suscríbete a booleanos derivados, no a valores crudos
-
-```tsx
-// INCORRECTO — re-renderiza ante cualquier cambio del carrito
-const cart = useStore((s) => s.cart);
-const hasItems = cart.length > 0;
-
-// CORRECTO — re-renderiza solo cuando cambia el estado de vacío
-const hasItems = useStore((s) => s.cart.length > 0);
-```
-
-### Deriva durante el render, nunca vía `useEffect`
-
-```tsx
-// INCORRECTO
-const [full, setFull] = useState("");
-useEffect(() => setFull(`${first} ${last}`), [first, last]);
-
-// CORRECTO
-const full = `${first} ${last}`;
-```
-
-### `setState` funcional para callbacks estables
-
-```tsx
-// CORRECTO
-const increment = useCallback(() => setCount((c) => c + 1), []);
-```
-
-### Inicializador perezoso de estado para valores caros
-
-```tsx
-const [tree] = useState(() => parseTree(largeInput));
-```
-
-### Evita memo para primitivas simples
-
-`useMemo(() => x + 1, [x])` es sobrecosto. Memo compensa cuando hay identidad de objeto o cómputo caro.
-
-### Divide los hooks con dependencias independientes
-
-```tsx
-// INCORRECTO — ambos selectores se recalculan si cambia cualquiera de las fuentes
-const { a, b } = useSomething(source1, source2);
-
-// CORRECTO
-const a = useA(source1);
-const b = useB(source2);
-```
-
-### Mueve la lógica de interacción a los manejadores de eventos
-
-Los manejadores de eventos corren solo con la acción del usuario — `useEffect` se re-ejecuta cada vez que cambian sus dependencias.
-
-### `startTransition` para actualizaciones no urgentes
-
-```tsx
-const [pending, startTransition] = useTransition();
-startTransition(() => setFilters(newFilters));
-```
-
-### `useDeferredValue` para renders caros
-
-```tsx
-const deferredQuery = useDeferredValue(query);
-const results = useMemo(() => expensiveSearch(deferredQuery), [deferredQuery]);
-```
-
-### `useRef` para valores transitorios frecuentes
-
-Para valores que cambian a menudo pero no deben disparar re-render (marcas de tiempo, última tecla, acumuladores).
-
-### No definas componentes dentro de componentes
-
-```tsx
-// INCORRECTO — Inner es un componente nuevo en cada render de Outer
-function Outer() {
-  const Inner = () => <span />;
-  return <Inner />;
-}
-```
-
-Cada render crea un tipo `Inner` nuevo, lo que anula la reconciliación y desmonta a los hijos.
-
-## 6. Rendimiento de renderizado (MEDIA)
-
-### Anima el contenedor, no el SVG
-
-Transformar un `<div>` contenedor alrededor de un SVG se acelera por GPU; transformar el propio SVG dispara paint.
-
-### `content-visibility: auto` para listas largas
-
-```css
-.row { content-visibility: auto; contain-intrinsic-size: auto 80px; }
-```
-
-El navegador omite el renderizado fuera de pantalla — una gran mejora en listas con cientos de filas.
-
-### Eleva el JSX estático
-
-```tsx
-const STATIC_HEADER = <h1>Título</h1>;
-function Page() {
-  return <>{STATIC_HEADER}<Body /></>;
-}
-```
-
-### SVG: reduce la precisión de coordenadas
-
-`d="M10.123456,20.654321"` → `d="M10.12,20.65"`. Cada dígito cuesta bytes; la diferencia visual es sub-píxel.
-
-### Hidratación sin parpadeo vía script inline
-
-Para valores necesarios antes de la hidratación (tema, locale), incrusta un `<script>` que fije `document.documentElement.dataset.*` antes de que React monte.
-
-### Suprime los desajustes de hidratación esperados de forma acotada
-
-```tsx
-<time suppressHydrationWarning>{new Date().toLocaleString()}</time>
-```
-
-Úsalo SOLO en nodos hoja con divergencia conocida — nunca en un árbol que contenga otros hijos.
-
-### `<Activity>` para mostrar/ocultar en lugar de montar/desmontar
-
-El `<Activity mode="visible|hidden">` de React 19 mantiene el estado del árbol y los efectos montados pero ocultos — más barato que desmontar/remontar para pestañas y acordeones.
-
-### Ternario en lugar de `&&` para render condicional
-
-```tsx
-// INCORRECTO — `0` se renderiza como nodo de texto
-{count && <Badge>{count}</Badge>}
-
-// CORRECTO
-{count > 0 ? <Badge>{count}</Badge> : null}
-```
-
-### `useTransition` para estados de carga
-
-Empareja `startTransition` con la acción; React muestra la UI anterior como `isPending` mientras se calcula el siguiente estado.
-
-### Resource hints de React DOM
-
-```tsx
-import { preload, preconnect } from "react-dom";
-preload("/api/critical", { as: "fetch" });
-preconnect("https://api.example.com");
-```
-
-### `defer` / `async` en etiquetas `<script>`
-
-`defer` para ejecución ordenada tras DOMContentLoaded; `async` para dispara-y-olvida.
-
-## 7. Rendimiento de JavaScript (BAJA-MEDIA)
-
-- **Agrupa los cambios de DOM/CSS** — aplícalos con un cambio de clase o `cssText`, no propiedad por propiedad
-- **`Map` para búsquedas repetidas** — `O(1)` frente al recorrido lineal `O(n)`
-- **Cachea el acceso a propiedades en bucles** — `const len = arr.length`
-- **Memoiza funciones puras** — `Map<clave, resultado>` a nivel de módulo
-- **Cachea las lecturas de `localStorage`** — API síncrona; una lectura por render
-- **Combina `filter().map()` en una sola pasada** — `flatMap` o un único `for`
-- **Comprueba primero la longitud del array** antes de comparaciones caras
-- **Retorno temprano** en las funciones
-- **Eleva las RegExp** fuera de los bucles — la compilación no es gratis
-- **Bucle para mín/máx** en lugar de `sort()` — `O(n)` frente a `O(n log n)`
-- **`Set`/`Map` para pertenencia** — `O(1)` frente a `Array.includes` `O(n)`
-- **`toSorted()` en lugar de mutación** cuando la inmutabilidad importa
-- **`flatMap` para mapear y filtrar en una sola pasada**
-- **`requestIdleCallback`** para trabajo no crítico
-
-## 8. Patrones avanzados (BAJA)
-
-### Dependencias de `useEffectEvent`
-
-Los valores de `useEffectEvent` son estables — NO los añadas a las dependencias del efecto.
-
-### Refs de manejadores de eventos
-
-Para callbacks estables pasados a hijos memoizados:
-
-```tsx
-const handlerRef = useRef(handler);
-useEffect(() => { handlerRef.current = handler; });
-const stable = useCallback((arg) => handlerRef.current(arg), []);
-```
-
-### Inicializa una sola vez por carga de la app
-
-Para singletons a nivel de módulo (telemetría, logger), protégelos con un flag en el ámbito del módulo — no con `useEffect`.
-
-### `useLatest` para refs de callbacks estables
-
-```tsx
-function useLatest<T>(value: T) {
-  const ref = useRef(value);
-  ref.current = value;
-  return ref;
-}
-```
-
-## Herramientas automatizadas
-
-Muchas de estas reglas ya están automatizadas:
-
-- **Optimize Package Imports de Next.js 13.5+** — optimización de imports barrel
-- **React Compiler** (RFC, en canary) — memoización automática
-- **Turbopack** — builds más rápidos, mejor tree-shaking
-- **Bundle Analyzer** (`@next/bundle-analyzer`) — visualiza el JS de primera carga
-
-Cuando el proyecto adopte React Compiler, degrada las reglas manuales de memoización `rerender-*` a "solo revisión" — el compilador las cubre. Los `useMemo`/`useCallback` manuales se convierten en ruido innecesario.
-
-## Correspondencia con Lighthouse / Web Vitals
-
-| Métrica | Categorías más relevantes |
-|---|---|
-| **LCP** (Largest Contentful Paint) | Waterfalls, Tamaño de bundle, Resource hints |
-| **INP** (Interaction to Next Paint) | Re-renders, Renderizado, JavaScript |
-| **CLS** (Cumulative Layout Shift) | Renderizado (ubicación de Suspense, dimensiones de imágenes) |
-| **TBT** (Total Blocking Time) | Tamaño de bundle, JavaScript, Diferir terceros |
-| **FID** (legado) | Tamaño de bundle, Hidratación |
-
-## Relacionado
-
-- Skills: [patrones-react](../patrones-react/SKILL.md), [testing-react](../testing-react/SKILL.md), [patrones-frontend](../patrones-frontend/SKILL.md), [accesibilidad](../accesibilidad/SKILL.md), [patrones-nextjs](../patrones-nextjs/SKILL.md)
-- Reglas: [rules/react/](../../rules/react/)
-- Agentes: `revisor-react` aplica estas reglas en la revisión de código; `resolutor-builds-react` atiende los fallos de build relacionados
-- Comandos: `/revisar-react`, `/build-react`, `/test-react`