@saulwade/swl-ses 1.0.0

package/habilidades/mobile-flutter/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: mobile-flutter
+description: Flutter mejores prácticas. Cubre StatelessWidget/StatefulWidget/HookWidget, state management con Riverpod/BLoC/Provider, navegación con GoRouter y auto_route, platform channels, animaciones implícitas vs explícitas, performance con Impeller y const widgets, testing de widgets/integración/golden y anti-patrones críticos.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para React Native o Expo — Flutter usa Dart y tiene un modelo de renderizado completamente diferente; para React Native cargar `mobile-react-native`."
+  - "No cargar para apps nativas iOS (Swift/SwiftUI) o Android (Kotlin/Compose) — Flutter abstrae las plataformas con su propio motor; para iOS cargar `swift-experto`, para Android cargar `kotlin-experto`."
+  - "No cargar para errores de compilación Dart o configuración de Flutter SDK — para build errors usar las herramientas de diagnóstico de Flutter."
+  - "No cargar para diseño de UI web (CSS, Tailwind) — Flutter usa su propio sistema de widgets sin HTML/CSS."
+evolvable: true  # default para skill estandar
+---
+# Flutter Experto
+
+## Cuándo NO cargar
+
+- El proyecto es React Native o Expo — Flutter usa Dart con un motor de renderizado propio; para React Native cargar `mobile-react-native`.
+- El proyecto es nativo iOS (Swift/SwiftUI) o Android (Kotlin/Compose) — cargar `swift-experto` o `kotlin-experto` según corresponda.
+- Los errores son de compilación Dart, configuración del SDK o `pubspec.yaml` — usar las herramientas de diagnóstico de Flutter/Dart.
+- El diseño UI es para web con HTML/CSS — Flutter no usa HTML; sus widgets son completamente distintos.
+
+## Filosofía
+
+Flutter compila a código nativo ARM con su propio motor de renderizado (Skia/Impeller).
+No usa componentes nativos del OS — pinta cada pixel.
+
+**Regla fundamental**: Todo es un widget. Un widget no es mutable por sí solo —
+se reconstruye cuando su estado o el estado de su ancestro cambia.
+
+---
+
+## 1. Tipos de Widget — Cuándo Usar Cuál
+
+| Tipo | Cuándo |
+|------|--------|
+| **StatelessWidget** | Sin estado mutable, solo recibe props |
+| **StatefulWidget** | Estado local al widget (animaciones, controllers) |
+| **HookWidget** | Alternativa menos verbosa a StatefulWidget |
+| **ConsumerWidget** | Cuando se usa Riverpod |
+
+```dart
+// StatelessWidget — patrón base
+class TarjetaUsuario extends StatelessWidget {
+  const TarjetaUsuario({super.key, required this.usuario, this.onTap});
+  final Usuario usuario;
+  final VoidCallback? onTap;
+
+  @override
+  Widget build(BuildContext context) {
+    return Card(
+      child: ListTile(
+        title: Text(usuario.nombre),
+        subtitle: Text(usuario.email),
+        trailing: const Icon(Icons.chevron_right),
+        onTap: onTap,
+      ),
+    );
+  }
+}
+```
+
+---
+
+## 2. State Management — Riverpod (Recomendado)
+
+```dart
+@riverpod
+Future<List<Usuario>> listaUsuarios(ListaUsuariosRef ref) async {
+  final repo = ref.watch(usuarioRepositoryProvider);
+  return repo.obtenerTodos();
+}
+
+// Notifier con estado mutable
+@riverpod
+class CarritoNotifier extends _$CarritoNotifier {
+  @override
+  List<Producto> build() => [];
+
+  void agregar(Producto p) { state = [...state, p]; }
+  void eliminar(String id) { state = state.where((p) => p.id != id).toList(); }
+}
+
+// Uso con asyncValue.when()
+asyncUsuarios.when(
+  data: (usuarios) => ListView.builder(...),
+  loading: () => const CircularProgressIndicator(),
+  error: (e, st) => Text('Error: $e'),
+);
+```
+
+---
+
+## 3. Animaciones — Implícitas vs Explícitas
+
+**Preferir implícitas** para transiciones simples:
+
+```dart
+AnimatedContainer(
+  duration: const Duration(milliseconds: 300),
+  curve: Curves.easeInOut,
+  width: _expandido ? 200.0 : 100.0,
+  height: _expandido ? 200.0 : 100.0,
+)
+```
+
+Usar **explícitas** para animaciones complejas con `AnimationController`.
+SIEMPRE disponer controllers en `dispose()`.
+
+---
+
+## 4. Performance — Reglas Críticas
+
+- **`const` SIEMPRE que sea posible** — evita reconstrucción.
+- **RepaintBoundary** para aislar subárboles que cambian frecuentemente.
+- **`compute()`** para procesamiento pesado en isolate separado.
+- **Impeller** habilitado por defecto en iOS y Android 3.19+.
+- **Platform Views**: minimizar — tienen overhead significativo.
+
+```dart
+// BIEN: const evita reconstrucción
+child: const Padding(
+  padding: EdgeInsets.all(16),
+  child: Text('Título fijo'),
+)
+
+// CPU-intensivo: usar isolate
+final resultado = await compute(procesarJsonGrande, jsonString);
+```
+
+---
+
+## 5. Anti-patrones Críticos
+
+### BuildContext después de await
+
+```dart
+// MAL: context puede ser inválido
+Future<void> _guardar() async {
+  await servicio.guardar(datos);
+  Navigator.of(context).pop(); // puede crashear
+
+// BIEN: verificar mounted
+  if (!mounted) return;
+  Navigator.of(context).pop();
+}
+```
+
+### setState en subárboles grandes
+
+NUNCA `setState` en la raíz — reconstruye toda la pantalla.
+Aislar el estado al widget que lo necesita, o usar Riverpod/BLoC.
+
+### Dispose olvidado
+
+```dart
+// NUNCA olvidar:
+@override
+void dispose() {
+  _controller.dispose();       // AnimationController
+  _scrollController.dispose(); // ScrollController
+  _textController.dispose();   // TextEditingController
+  _focusNode.dispose();        // FocusNode
+  super.dispose();
+}
+```
+
+---
+
+## 6. Testing
+
+- **Widget tests**: `tester.pumpWidget()` + `find.text()` + `expect()`.
+- **Golden tests**: `matchesGoldenFile()` para comparación visual.
+- **Actualizar goldens**: `flutter test --update-goldens`.
+- **Modo perfil**: `flutter run --profile` para detectar jank.
+
+---
+
+## Checklist Flutter
+
+- [ ] Widgets const donde sea posible
+- [ ] Controllers dispuestos en `dispose()`
+- [ ] `mounted` verificado después de cada await
+- [ ] State management con Riverpod o BLoC (no setState global)
+- [ ] RepaintBoundary en animaciones frecuentes
+- [ ] Compute para CPU-intensivo
+- [ ] Widget tests para componentes clave
+- [ ] Golden tests para componentes visuales críticos
+
+Para implementaciones completas de BLoC, GoRouter, Platform Channels, animaciones explícitas y tests, ver [recursos/ejemplos-completos.md](recursos/ejemplos-completos.md).
+
+## Gotchas / Errores comunes no obvios
+
+**Usar `BuildContext` después de un `await` sin verificar `mounted` causa `setState() called after dispose()`**: si el widget se desmontó mientras la operación async estaba en progreso, `context` ya no es válido. Causa: Flutter no cancela automáticamente operaciones async cuando el widget se destruye. Fix: siempre verificar `if (!mounted) return;` inmediatamente después de cada `await` antes de usar `context`, `setState` o `Navigator`.
+
+**`const` en widgets con `GlobalKey` o con providers que cambian no previene reconstrucción**: `const TarjetaProducto(key: Key('prod-1'))` puede parecer que se cachea, pero si el `Provider` padre cambia y el widget consume datos del provider, se reconstruirá de todas formas. Causa: `const` en Flutter evita reconstrucción solo cuando el constructor recibe los mismos argumentos — no protege contra cambios en providers heredados. Fix: para aislar reconstrucciones costosas usar `Consumer` con un `builder` granular que solo consume el slice de estado necesario.
+
+**`Riverpod` con `ref.watch` dentro de un callback (como `onPressed`) lanza `ProviderException`**: `ref.watch` solo puede llamarse en el cuerpo del `build` o en `ConsumerWidget` — llamarlo en `onPressed`, `initState` o callbacks async lanza error en runtime. Causa: `ref.watch` registra una suscripción que necesita el contexto de build activo. Fix: usar `ref.read` dentro de callbacks y `ref.watch` solo en el cuerpo del `build`.
+
+**`AnimationController` sin `vsync: this` en un `StatefulWidget` que no implementa `TickerProviderStateMixin` causa error silencioso de rendimiento**: si se pasa `vsync: this` pero el widget solo implementa `SingleTickerProviderStateMixin` y luego se agregan más controllers, el segundo controller falla. Causa: `SingleTickerProviderStateMixin` solo soporta un ticker — el segundo lanza `FlutterError` en debug. Fix: implementar `TickerProviderStateMixin` (plural) cuando el widget necesita múltiples `AnimationController`.

package/habilidades/mobile-flutter/recursos/ejemplos-completos.md

@@ -0,0 +1,319 @@
+# Flutter — Ejemplos Completos de Referencia
+
+Implementaciones completas de widgets, state management, navegación, animaciones y testing.
+
+---
+
+## StatefulWidget Completo con Animación
+
+```dart
+class ContadorAnimado extends StatefulWidget {
+  const ContadorAnimado({super.key, required this.inicial});
+  final int inicial;
+
+  @override
+  State<ContadorAnimado> createState() => _ContadorAnimadoState();
+}
+
+class _ContadorAnimadoState extends State<ContadorAnimado>
+    with SingleTickerProviderStateMixin {
+  late int _count;
+  late AnimationController _controller;
+
+  @override
+  void initState() {
+    super.initState();
+    _count = widget.inicial;
+    _controller = AnimationController(
+      vsync: this,
+      duration: const Duration(milliseconds: 300),
+    );
+  }
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    super.dispose();
+  }
+
+  void _incrementar() {
+    setState(() { _count++; });
+    _controller.forward(from: 0);
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      children: [
+        Text('$_count', style: const TextStyle(fontSize: 48)),
+        FloatingActionButton(onPressed: _incrementar, child: const Icon(Icons.add)),
+      ],
+    );
+  }
+}
+```
+
+---
+
+## HookWidget (flutter_hooks)
+
+```dart
+import 'package:flutter_hooks/flutter_hooks.dart';
+
+class BusquedaWidget extends HookWidget {
+  const BusquedaWidget({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    final controller = useTextEditingController();
+    final query = useListenableSelector(controller, () => controller.text);
+    final debouncedQuery = useDebounced(query, const Duration(milliseconds: 300));
+
+    useEffect(() {
+      return null;
+    }, [debouncedQuery]);
+
+    return TextField(
+      controller: controller,
+      decoration: const InputDecoration(
+        hintText: 'Buscar...',
+        prefixIcon: Icon(Icons.search),
+      ),
+    );
+  }
+}
+```
+
+---
+
+## BLoC — Implementación Completa
+
+```dart
+import 'package:flutter_bloc/flutter_bloc.dart';
+
+// Eventos
+sealed class AutenticacionEvento {}
+final class LoginSolicitado extends AutenticacionEvento {
+  const LoginSolicitado({required this.email, required this.password});
+  final String email, password;
+}
+final class CerrarSesion extends AutenticacionEvento {}
+
+// Estados
+sealed class AutenticacionEstado {}
+final class NoAutenticado extends AutenticacionEstado {}
+final class Cargando extends AutenticacionEstado {}
+final class Autenticado extends AutenticacionEstado {
+  const Autenticado(this.usuario);
+  final Usuario usuario;
+}
+final class ErrorAutenticacion extends AutenticacionEstado {
+  const ErrorAutenticacion(this.mensaje);
+  final String mensaje;
+}
+
+// BLoC
+class AutenticacionBloc extends Bloc<AutenticacionEvento, AutenticacionEstado> {
+  AutenticacionBloc(this._authRepo) : super(NoAutenticado()) {
+    on<LoginSolicitado>(_onLoginSolicitado);
+    on<CerrarSesion>((_, emit) => emit(NoAutenticado()));
+  }
+
+  final AuthRepository _authRepo;
+
+  Future<void> _onLoginSolicitado(
+    LoginSolicitado evento,
+    Emitter<AutenticacionEstado> emit,
+  ) async {
+    emit(Cargando());
+    try {
+      final usuario = await _authRepo.login(evento.email, evento.password);
+      emit(Autenticado(usuario));
+    } catch (e) {
+      emit(ErrorAutenticacion(e.toString()));
+    }
+  }
+}
+```
+
+---
+
+## Navegación con GoRouter
+
+```dart
+import 'package:go_router/go_router.dart';
+
+final appRouter = GoRouter(
+  initialLocation: '/',
+  redirect: (context, state) {
+    final autenticado = context.read<AuthBloc>().state is Autenticado;
+    final estaEnLogin = state.matchedLocation == '/login';
+    if (!autenticado && !estaEnLogin) return '/login';
+    if (autenticado && estaEnLogin) return '/';
+    return null;
+  },
+  routes: [
+    GoRoute(
+      path: '/',
+      builder: (context, state) => const HomeScreen(),
+      routes: [
+        GoRoute(
+          path: 'usuarios/:id',
+          builder: (context, state) => DetalleUsuarioScreen(
+            id: state.pathParameters['id']!,
+          ),
+        ),
+      ],
+    ),
+    GoRoute(
+      path: '/login',
+      builder: (context, state) => const LoginScreen(),
+    ),
+    ShellRoute(
+      builder: (context, state, child) => ScaffoldConNavBar(child: child),
+      routes: [
+        GoRoute(path: '/inicio', builder: (_, __) => const InicioTab()),
+        GoRoute(path: '/perfil', builder: (_, __) => const PerfilTab()),
+      ],
+    ),
+  ],
+);
+```
+
+---
+
+## Platform Channels
+
+```dart
+import 'package:flutter/services.dart';
+
+class BiometricoChannel {
+  static const _channel = MethodChannel('com.miapp/biometrico');
+
+  static Future<bool> autenticar(String motivo) async {
+    try {
+      final resultado = await _channel.invokeMethod<bool>(
+        'autenticar',
+        {'motivo': motivo},
+      );
+      return resultado ?? false;
+    } on PlatformException catch (e) {
+      throw BiometricoException(e.message ?? 'Error biométrico');
+    }
+  }
+}
+```
+
+```kotlin
+// android/app/src/main/kotlin/.../MainActivity.kt
+class MainActivity : FlutterActivity() {
+  override fun configureFlutterEngine(engine: FlutterEngine) {
+    super.configureFlutterEngine(engine)
+    MethodChannel(engine.dartExecutor.binaryMessenger, "com.miapp/biometrico")
+      .setMethodCallHandler { call, result ->
+        when (call.method) {
+          "autenticar" -> {
+            val motivo = call.argument<String>("motivo") ?: "Confirma tu identidad"
+            result.success(true)
+          }
+          else -> result.notImplemented()
+        }
+      }
+  }
+}
+```
+
+---
+
+## Animaciones Explícitas
+
+```dart
+class _LogoAnimadoState extends State<LogoAnimado>
+    with SingleTickerProviderStateMixin {
+  late AnimationController _controller;
+  late Animation<double> _escala;
+  late Animation<double> _rotacion;
+
+  @override
+  void initState() {
+    super.initState();
+    _controller = AnimationController(
+      vsync: this,
+      duration: const Duration(seconds: 2),
+    )..repeat(reverse: true);
+
+    _escala = Tween<double>(begin: 0.8, end: 1.2).animate(
+      CurvedAnimation(parent: _controller, curve: Curves.elasticInOut),
+    );
+    _rotacion = Tween<double>(begin: 0, end: 0.1).animate(
+      CurvedAnimation(parent: _controller, curve: Curves.easeInOut),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return AnimatedBuilder(
+      animation: _controller,
+      builder: (context, child) {
+        return Transform.scale(
+          scale: _escala.value,
+          child: Transform.rotate(angle: _rotacion.value, child: child),
+        );
+      },
+      child: const FlutterLogo(size: 100),
+    );
+  }
+}
+```
+
+---
+
+## Testing Completo
+
+### Widget Tests
+
+```dart
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  group('TarjetaUsuario', () {
+    final usuario = Usuario(id: '1', nombre: 'Ana López', email: 'ana@test.com');
+
+    testWidgets('muestra nombre y email', (tester) async {
+      await tester.pumpWidget(
+        MaterialApp(home: TarjetaUsuario(usuario: usuario)),
+      );
+      expect(find.text('Ana López'), findsOneWidget);
+      expect(find.text('ana@test.com'), findsOneWidget);
+    });
+
+    testWidgets('llama onTap al presionar', (tester) async {
+      var llamado = false;
+      await tester.pumpWidget(
+        MaterialApp(
+          home: TarjetaUsuario(usuario: usuario, onTap: () => llamado = true),
+        ),
+      );
+      await tester.tap(find.byType(ListTile));
+      expect(llamado, isTrue);
+    });
+  });
+}
+```
+
+### Golden Tests
+
+```dart
+testWidgets('TarjetaUsuario golden', (tester) async {
+  await tester.pumpWidget(
+    MaterialApp(home: TarjetaUsuario(usuario: usuario)),
+  );
+  await expectLater(
+    find.byType(TarjetaUsuario),
+    matchesGoldenFile('goldens/tarjeta_usuario.png'),
+  );
+});
+
+// Actualizar goldens:
+// flutter test --update-goldens
+```

package/habilidades/mobile-react-native/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: mobile-react-native
+description: React Native + Expo mejores prácticas. Cubre navegación con React Navigation y Expo Router, state management (Zustand, Redux Toolkit), native modules y Turbo Modules, animaciones con Reanimated, styling con StyleSheet y NativeWind, performance con Hermes y FlashList, testing con Detox y Jest Testing Library.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para Flutter (Dart, Riverpod, GoRouter, widgets) — React Native usa JavaScript/TypeScript con un puente nativo diferente; para Flutter cargar `mobile-flutter`."
+  - "No cargar para React web (Next.js, Server Components, CSS) — React Native no tiene DOM, no usa HTML/CSS y las APIs de navegación son distintas; para web cargar `react-experto`."
+  - "No cargar para errores de compilación de módulos nativos, Xcode o Gradle en React Native — para build errors nativos usar las herramientas de diagnóstico de la plataforma."
+  - "No cargar para apps iOS nativas (Swift) o Android nativas (Kotlin) — React Native y los SDKs nativos tienen modelos de ciclo de vida completamente distintos."
+evolvable: true  # default para skill estandar
+---
+# React Native + Expo Experto
+
+## Cuándo NO cargar
+
+- El proyecto es Flutter (Dart) — React Native usa JavaScript con puente nativo; para Flutter cargar `mobile-flutter`.
+- El contexto es React para web (Next.js, Server Components, DOM) — React Native no tiene DOM ni HTML/CSS; para web cargar `react-experto`.
+- Los errores son de compilación nativa: Xcode build failures, Gradle errors, módulos nativos no encontrados — usar las herramientas de diagnóstico de iOS/Android.
+- El proyecto es una app nativa pura en Swift o Kotlin — cargar `swift-experto` o `kotlin-experto`.
+
+## Filosofía
+
+React Native comparte la lógica de JavaScript con React web, pero el modelo
+de renderizado es completamente nativo. El puente JS-nativo tiene costo;
+la arquitectura moderna (Nueva Arquitectura / Fabric) lo reduce con JSI,
+pero las reglas de rendimiento siguen siendo críticas.
+
+---
+
+## 1. Navegación — Expo Router (recomendado para proyectos nuevos)
+
+Expo Router usa el sistema de archivos como router, similar a Next.js App Router:
+
+```
+app/
+├── _layout.tsx           # Root layout (Stack/Tabs)
+├── index.tsx             # / (pantalla home)
+├── (tabs)/
+│   ├── _layout.tsx       # Tabs layout
+│   ├── inicio.tsx        # /inicio
+│   └── perfil.tsx        # /perfil
+├── usuarios/
+│   ├── index.tsx         # /usuarios
+│   └── [id].tsx          # /usuarios/:id
+└── modal.tsx             # Pantalla modal
+```
+
+```tsx
+// app/_layout.tsx — Root layout con Stack
+import { Stack } from 'expo-router';
+
+export default function RootLayout() {
+  return (
+    <Stack screenOptions={{ headerStyle: { backgroundColor: '#f8fafc' } }}>
+      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
+      <Stack.Screen name="modal" options={{ presentation: 'modal' }} />
+    </Stack>
+  );
+}
+
+// Navegación programática
+import { router } from 'expo-router';
+router.push('/usuarios/123');
+router.replace('/login');
+router.back();
+```
+
+---
+
+## 2. State Management — Zustand (recomendado)
+
+```typescript
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+interface SesionStore {
+  usuario: Usuario | null;
+  token: string | null;
+  login: (usuario: Usuario, token: string) => void;
+  logout: () => void;
+}
+
+export const useSesionStore = create<SesionStore>()(
+  persist(
+    (set) => ({
+      usuario: null,
+      token: null,
+      login: (usuario, token) => set({ usuario, token }),
+      logout: () => set({ usuario: null, token: null }),
+    }),
+    { name: 'sesion-storage', storage: createJSONStorage(() => AsyncStorage) }
+  )
+);
+```
+
+---
+
+## 3. Animaciones con Reanimated
+
+```tsx
+import Animated, { useSharedValue, useAnimatedStyle, withSpring, withTiming } from 'react-native-reanimated';
+
+function TarjetaAnimada() {
+  const escala = useSharedValue(1);
+
+  const estiloAnimado = useAnimatedStyle(() => ({
+    transform: [{ scale: escala.value }],
+  }));
+
+  return (
+    <Animated.View style={[styles.tarjeta, estiloAnimado]}>
+      <Pressable
+        onPressIn={() => { escala.value = withSpring(0.95); }}
+        onPressOut={() => { escala.value = withSpring(1); }}
+      >
+        <Text>Presiona</Text>
+      </Pressable>
+    </Animated.View>
+  );
+}
+```
+
+---
+
+## 4. Styling: StyleSheet (enfoque nativo)
+
+```tsx
+// Crear estilos fuera del componente (procesados UNA vez, no en cada render)
+const styles = StyleSheet.create({
+  contenedor: { flex: 1, backgroundColor: '#f8fafc', padding: 16 },
+  tarjeta: {
+    backgroundColor: '#ffffff', borderRadius: 12, padding: 16, marginBottom: 12,
+    shadowColor: '#000', shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.05, shadowRadius: 4, elevation: 2,
+  },
+});
+```
+
+---
+
+## 5. Performance
+
+- Hermes habilitado por defecto en Expo SDK 48+: `"jsEngine": "hermes"`
+- Usar `FlashList` de `@shopify/flash-list` en lugar de `FlatList` para listas grandes
+- SIEMPRE pasar `estimatedItemSize` a FlashList
+- SIEMPRE memorizar `renderItem` con `useCallback` y componentes de lista con `React.memo`
+
+---
+
+## 6. Anti-patrones Críticos
+
+- **Bridge overhead**: usar `useWindowDimensions()` hook en vez de `Dimensions.get('window')` en cada render
+- **Bloquear hilo JS**: usar librerías nativas para procesamiento pesado (ImageManipulator, etc.)
+- **Estilos inline en listas**: NUNCA `style={{ ... }}` en componentes de lista, usar `StyleSheet.create` fuera
+- **setInterval sin cleanup**: SIEMPRE retornar cleanup en `useEffect`
+
+---
+
+## Ejemplos Completos
+
+Para implementaciones de React Navigation tipada, Redux Toolkit, Turbo Modules,
+Expo Modules API, Gesture Handler + Reanimated, NativeWind v4, y testing con
+Jest/RNTL y Detox, ver
+[recursos/ejemplos-completos.md](recursos/ejemplos-completos.md).
+
+## Gotchas / Errores comunes no obvios
+
+**`useEffect` con `async` function directa no maneja el cleanup correctamente y puede causar memory leaks**: `useEffect(async () => { await fetch(...); }, [])` no puede retornar una función de cleanup desde una función async (retorna una Promise, no una función). Causa: `useEffect` espera que el callback retorne una función de cleanup o `undefined` — retornar una Promise hace que React ignore el cleanup. Fix: declarar la función async dentro del efecto y llamarla: `useEffect(() => { const fn = async () => { ... }; fn(); return () => { /* cleanup */ }; }, [])`.
+
+**Reanimated `useAnimatedStyle` que accede a valores de estado React (no shared values) no actualiza en el UI thread**: `useAnimatedStyle(() => ({ opacity: someReactState }))` no reacciona cuando `someReactState` cambia porque los animated styles se ejecutan en el UI thread y no tienen acceso al estado React del JS thread. Causa: la separación de threads de Reanimated 2/3. Fix: convertir el valor a `useSharedValue` y actualizarlo con `useEffect` cuando cambie el estado React: `useEffect(() => { sharedVal.value = someReactState; }, [someReactState])`.
+
+**`FlashList` con items de altura variable sin `overrideItemLayout` tiene scroll jumpy**: `FlashList` usa `estimatedItemSize` para todos los items por defecto — si los items tienen altura muy variable (ej: mensajes de chat), el scroll puede saltar al navegar de vuelta a items ya renderizados. Causa: la estimación de tamaño acumula error en listas con alta variabilidad. Fix: implementar `overrideItemLayout` que retorna el tamaño real de cada item conocido, o medir los items con `onLayout` y almacenar sus tamaños para retornarlos en la función.
+
+**`Zustand` con `persist` en AsyncStorage puede devolver `null` en el primer render antes de que se rehidrate**: `useSesionStore(s => s.usuario)` puede retornar `null` el primer frame aunque haya datos persistidos, porque la rehidratación de AsyncStorage es asíncrona. Causa: AsyncStorage es asíncrono — el store se inicializa con el estado por defecto y luego se rehidrata. Fix: verificar el estado de hidratación con `useStore(s => s._hasHydrated)` (habilitando el `onRehydrateStorage` callback) o usar `zustand/middleware/persist` con la opción `skipHydration: true` y disparar la hidratación manualmente en el splash screen.