coding-os 0.3.2__py3-none-any.whl

core/skills/performance/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: performance
+tier: cross-cutting
+domain: [performance]
+description: Application performance for backend (Go+Fiber, Python+FastAPI), web frontends, and React Native mobile clients. Use when measuring or improving Web Vitals (LCP / INP / CLS), mobile FPS / TTI / memory, image/font/code-split optimization, profiling, or interpreting Lighthouse / Reanimated / Hermes / Flipper traces. Pairs with frontend-fundamentals + react-native-patterns + db-design.
+last_reviewed: "2026-05-11"
+
+---
+
+# Performance — Web + Backend + Mobile
+
+A practical playbook for measuring, profiling, and improving performance across the project's stack. Covers Web Vitals (Google's user-experience metrics), mobile perf budgets (FPS / TTI / memory), backend latency (P95 / P99 / saturation), with concrete tools per surface.
+
+## When to Use This Skill
+
+- Adding a perf budget to a new feature.
+- Investigating a Lighthouse / Web Vitals regression.
+- Mobile users report jank, slow app launch, battery drain.
+- Backend P95 latency exceeds SLO.
+- Bundle size jumped 30% after a release.
+- Lists scroll poorly; animations stutter.
+- Choosing between perf tools (when each pays off).
+
+## The Three Performance Surfaces
+
+| Surface | Primary metrics | Tools |
+|---|---|---|
+| **Backend** | P50 / P95 / P99 latency, throughput, error rate, saturation (CPU / mem / IO) | OpenTelemetry, Datadog APM, pprof (Go), py-spy (Python), pgbadger (Postgres) |
+| **Web frontend** | LCP, INP, CLS (Core Web Vitals), TTI, TBT, bundle size | Lighthouse, Chrome DevTools Performance, WebPageTest, web-vitals JS lib |
+| **Mobile** | FPS (60/120), TTI, memory, bundle size, native render time | Flipper, React DevTools Profiler, Hermes Sampling Profiler, Xcode Instruments, Android Profiler, FlashList Recorder |
+
+Each has its own measurement approach; conflate them at your peril.
+
+## Measurement First, Optimization Second
+
+The cardinal rule: don't optimize without numbers. The biggest performance regressions in the wild come from devs "fixing" something that wasn't slow.
+
+**Workflow**:
+
+1. Establish a budget (e.g., LCP < 2.5s P75, list scroll 60 FPS, P95 < 200ms).
+2. Measure on real conditions (real device, real network, real data volume).
+3. Identify the bottleneck via profiling.
+4. Fix the bottleneck.
+5. Re-measure to confirm improvement.
+6. Pin a regression test if possible (CI bundle-size gate, k6 load test).
+
+## Web Vitals (2026 — current Google ranking signals)
+
+| Metric | What it measures | Good | Needs improvement | Poor |
+|---|---|---|---|---|
+| **LCP** (Largest Contentful Paint) | Time until largest element renders | ≤ 2.5s | 2.5–4.0s | > 4.0s |
+| **INP** (Interaction to Next Paint) | Worst interaction latency in session — replaced FID March 2024 | ≤ 200ms | 200–500ms | > 500ms |
+| **CLS** (Cumulative Layout Shift) | Visual stability over the page lifetime | ≤ 0.1 | 0.1–0.25 | > 0.25 |
+| TTFB (Time to First Byte) | Server response start | ≤ 0.8s | 0.8–1.8s | > 1.8s |
+
+Measure on REAL devices via the `web-vitals` library; aggregate at P75 across users (Google's threshold).
+
+```html
+<script type="module">
+  import { onLCP, onINP, onCLS } from 'https://unpkg.com/web-vitals?module';
+  onLCP((metric) => sendToAnalytics('LCP', metric));
+  onINP((metric) => sendToAnalytics('INP', metric));
+  onCLS((metric) => sendToAnalytics('CLS', metric));
+</script>
+```
+
+For per-metric optimization tactics (image priorities for LCP, JS chunking for INP, reserved space for CLS), see [references/web-vitals.md](references/web-vitals.md).
+
+## Mobile Perf Budgets
+
+| Metric | Target | Hard fail |
+|---|---|---|
+| App cold start (TTI) | < 1.5s on mid-tier device | > 3s |
+| App warm start | < 500ms | > 1s |
+| Frame rate during scroll | 60 FPS (or 120 on ProMotion) | < 50 FPS |
+| Frame rate during animation | same | jank visible |
+| Memory after 5 min use | < 250MB | > 400MB |
+| JS bundle size | < 4MB uncompressed | > 8MB |
+| Native size (per platform) | < 50MB download | > 100MB |
+| Battery drain (1 hr active use) | < 5% | > 10% |
+
+Measure on a **mid-tier device** (Pixel 6a, iPhone 12 mini), not the top of the line. Real users have older phones.
+
+For RN-specific patterns (Hermes optimizations, FlashList, Reanimated worklets, native module trade-offs, bundle analysis), see [references/mobile-performance.md](references/mobile-performance.md).
+
+## Backend Perf Budgets
+
+| Metric | Target | Hard fail |
+|---|---|---|
+| P50 latency | < 100ms | > 300ms |
+| P95 latency | < 300ms | > 1s |
+| P99 latency | < 1s | > 3s |
+| Error rate | < 0.1% | > 1% |
+| CPU utilization | < 70% sustained | > 90% |
+| Memory utilization | < 70% sustained | > 90% |
+| DB connection pool usage | < 60% | > 90% |
+| Cache hit rate (where applicable) | > 90% | < 70% |
+
+P95 / P99 matter more than P50 — the slow tail is the user experience for the unlucky users.
+
+Per-language tools:
+
+- **Go**: `pprof` for CPU / heap / goroutine profiles. `runtime/trace` for execution traces. `httptrace` to dissect outbound calls.
+- **Python**: `py-spy` for sampling profiler. `cProfile` for deterministic. `tracemalloc` for memory leaks. `asyncio` debug mode for slow awaits.
+- **Node**: `--prof` + `--prof-process`. Clinic.js for flame graphs.
+
+## Image Optimization (Web + Mobile)
+
+The single biggest leverage in most apps. Modern formats + sizing rules:
+
+| Use case | Format | Notes |
+|---|---|---|
+| Photos (web) | AVIF (2026 default), WebP fallback | 30-50% smaller than JPEG |
+| Photos (RN) | WebP | iOS 14+ & Android natively |
+| Graphics / icons | SVG | Inline for critical above-fold |
+| Animation | WebP / animated AVIF | Avoid GIF (huge) |
+| Logos | SVG | Crisp at any density |
+| Charts | SVG (small) / Canvas (large) | DOM cost vs raster |
+
+**Sizing**:
+
+- Serve at the size the device displays. Don't serve a 4000px JPG to a 400px container.
+- Web: `<img srcset>` with multiple resolutions + `sizes` hint.
+- RN: `react-native-fast-image` with explicit `style={{ width, height }}` + remote CDN that supports `?w=` resize.
+
+**Loading**:
+
+- `loading="lazy"` on below-fold images (web).
+- `fetchpriority="high"` on the LCP image.
+- Preconnect to the image CDN: `<link rel="preconnect" href="https://cdn.app.com">`.
+
+**CDN**:
+
+- Cloudflare Images, ImageKit, Imgix, Cloudinary — auto-format + auto-resize.
+- Cache headers: `Cache-Control: public, max-age=31536000, immutable` for hashed asset URLs.
+
+## Code Splitting
+
+Web (Vite / Webpack / Next):
+
+```typescript
+// Lazy-load a route-scoped component
+const Settings = lazy(() => import('./Settings'));
+
+<Suspense fallback={<Spinner />}>
+  <Settings />
+</Suspense>
+```
+
+Rules:
+
+- Split per route at minimum.
+- Split large components (charts, rich-text editors, video players) on demand.
+- Don't split things smaller than ~30KB — overhead outweighs.
+- Preload the next likely route on hover / link visibility.
+
+RN: 0.76+ bundle is one file by default; use Hermes lazy parse + tree-shake aggressively.
+
+## Font Loading
+
+Fonts are render-blocking. Best practices:
+
+```css
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 400 700;             /* variable font, single file */
+  font-display: swap;                /* show fallback immediately, swap when ready */
+  src: url('/fonts/inter.woff2') format('woff2');
+}
+```
+
+```html
+<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preconnect" href="https://fonts.app.com">
+```
+
+- Variable fonts (one file, all weights) over multiple static fonts.
+- Subset fonts to characters you actually use (latin / latin-ext / etc.).
+- `font-display: swap` — never block on font.
+- Self-host critical fonts; don't depend on Google Fonts CDN for first paint.
+
+## JavaScript Cost (Web)
+
+The biggest INP / TTI killer. Defenses:
+
+- **Bundle budget**: < 200KB compressed JS for the initial page.
+- **Tree-shake aggressively**. `import { foo } from 'lib'` not `import * as lib`.
+- **Avoid large UI libraries**: a custom dropdown is 100x smaller than `react-select`.
+- **Defer non-critical scripts**: analytics, A/B testing, cookie banner load AFTER LCP.
+- **Web workers** for heavy computation (PDF parse, CSV processing).
+- **Streaming SSR** (React 19+) — TTFB drops, hydration starts earlier.
+
+Lint rule: `no-default-export` for UI lib modules — easier tree-shake.
+
+## Database Performance (cross-references db-design)
+
+Most backend slowness is the database. Default fixes:
+
+1. **Find the slow query** with `pg_stat_statements`:
+   ```sql
+   SELECT query, mean_exec_time, calls, total_exec_time
+   FROM pg_stat_statements
+   ORDER BY mean_exec_time DESC LIMIT 20;
+   ```
+2. **Run EXPLAIN (ANALYZE, BUFFERS)** on it.
+3. **Add the missing index** (per `db-design`).
+4. **N+1**: use eager loading or batch the lookup.
+5. **Connection pool sized correctly** (per `db-design`).
+6. **Add a cache layer** (Redis) for hot reads if DB is the bottleneck after indexing.
+
+For Postgres-specific perf tools, see `db-design::postgres-patterns.md`.
+
+## Caching Layers
+
+| Layer | Tool | Use case |
+|---|---|---|
+| HTTP / CDN | Cloudflare, Fastly | Public, cacheable responses (homepage, static) |
+| Reverse proxy | Nginx, Varnish | Same, on your edge |
+| Application | Redis, Memcached | Hot reads, session data, rate-limit counters |
+| Database query cache | (Postgres has no real query cache; use materialized views) | Aggregates that change infrequently |
+| Service worker | Browser | Offline-first PWAs |
+| Client-side | TanStack Query | Per-user request dedup + SWR |
+
+Rules:
+
+- **Cache invalidation is hard**. Pick TTL conservatively; explicit invalidate on writes.
+- **Cache headers** must be set deliberately on EVERY endpoint (`no-store` for sensitive).
+- **Edge cache** for anything that can be public.
+- **Don't cache PII** at the edge (CDN).
+
+## Profiling Workflow
+
+### Backend (Go example)
+
+```go
+import _ "net/http/pprof"
+go func() { _ = http.ListenAndServe("localhost:6060", nil) }()
+
+// Then:
+// go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30   (CPU)
+// go tool pprof http://localhost:6060/debug/pprof/heap                  (heap)
+// go tool pprof http://localhost:6060/debug/pprof/goroutine             (goroutine count)
+```
+
+### Web Frontend
+
+- Chrome DevTools → Performance tab → record while reproducing.
+- Look for: long tasks (> 50ms), layout shifts, render-blocking resources.
+- Lighthouse → Performance audit → "Diagnostics" + "Opportunities".
+
+### React Native
+
+- Flipper → React DevTools profiler (component re-renders).
+- Hermes Sampling Profiler (`hermes -enable-eval -sample-profiler`).
+- Xcode Instruments (iOS) → Time Profiler / Allocations.
+- Android Studio Profiler → CPU / Memory / Network.
+
+## Performance Regressions in CI
+
+Catch them before users do:
+
+- **Bundle size budget** in webpack/vite config; fails build if bundle grows > 5%.
+- **Lighthouse CI** (`@lhci/cli`) per PR on key pages; fails build on Performance score drop.
+- **k6 load tests** weekly against staging; alert on P95 regression.
+- **Detox / Maestro perf check** on mobile — startup time + first frame.
+
+```yaml
+# .github/workflows/perf.yml
+- run: npm run build
+- run: npx bundlesize    # fails if any chunk over budget
+- run: npx @lhci/cli autorun --collect.url=https://staging.app.com/
+```
+
+## Common Performance Mistakes
+
+1. **Optimizing without measuring** — guesswork; usually wrong.
+2. **Hand-rolled caching** when TanStack Query / SWR exists.
+3. **Re-renders ignored** — log re-render counts in dev; profile with React DevTools.
+4. **N+1 queries unnoticed** until prod — add `pg_stat_statements` early.
+5. **Big JPGs served everywhere** — modern formats + responsive `srcset`.
+6. **Synchronous render-blocking script** in `<head>` — defer/async or load late.
+7. **No `font-display: swap`** — invisible text until font loads.
+8. **CSS `@import`** — serial loading. Use `<link>` for parallel.
+9. **No connection pooling** to the DB — every request a new TCP handshake.
+10. **Memory leaks**: unsubscribed listeners, retained closures, big arrays in module scope.
+11. **Mobile: inline functions in render** of long lists — use `useCallback` + memoize rows.
+12. **Mobile: AsyncStorage on app start** for big data — use MMKV (synchronous, 30x faster).
+13. **Mobile: too many native module calls in render** — batch or move to lifecycle hooks.
+14. **Backend: blocking I/O in async runtime** — measure with the runtime's debug mode.
+15. **Backend: serialization-heavy responses** — Pydantic v2 is fast; v1 was a bottleneck.
+
+## Pre-Launch Performance Checklist
+
+See [assets/perf-checklist.md](assets/perf-checklist.md). Each item: a concrete metric or technique.
+
+## Source Material
+
+- *web.dev — Core Web Vitals*: <https://web.dev/articles/vitals>
+- *Web Performance — Brendan Gregg* (book + blog): <https://www.brendangregg.com/>
+- *Callstack — Ultimate Guide to React Native Optimization* (definitive RN perf reference).
+- *Addy Osmani — Image Optimization*: <https://images.guide/>
+- *Lighthouse Performance Scoring*: <https://developer.chrome.com/docs/lighthouse/performance/performance-scoring>
+- *PostgreSQL — Performance Tips*: <https://www.postgresql.org/docs/current/performance-tips.html>
+- *Go performance — uber-go/guide* and *cmd/pprof docs*.

core/skills/performance/assets/perf-checklist.md

@@ -0,0 +1,143 @@
+# Performance Pre-Launch Checklist
+
+Run before each release. Each item is a concrete metric or technique. Uncheck = fix or document waiver.
+
+## Web Vitals (web client)
+
+- [ ] **LCP** at P75 ≤ 2.5s on a real 4G mid-tier device.
+- [ ] **INP** at P75 ≤ 200ms.
+- [ ] **CLS** at P75 ≤ 0.1.
+- [ ] **TTFB** at P75 ≤ 800ms.
+- [ ] Lighthouse Performance score ≥ 90 on critical pages.
+- [ ] `web-vitals` JS lib reporting to RUM (real-user monitoring).
+
+## Image Optimization
+
+- [ ] Modern format (AVIF/WebP) for raster images.
+- [ ] Responsive `srcset` + `sizes` (web) OR CDN resize parameters (mobile).
+- [ ] Every `<img>` has explicit `width` + `height` (or `aspect-ratio`).
+- [ ] LCP image: `fetchpriority="high"` + `<link rel="preload">`.
+- [ ] Below-fold images: `loading="lazy"`.
+- [ ] CDN configured with `Cache-Control: public, max-age=31536000, immutable` for hashed URLs.
+
+## Fonts
+
+- [ ] Variable font (single file) over multi-weight static fonts.
+- [ ] `font-display: swap`.
+- [ ] Critical fonts preloaded (`<link rel="preload" as="font" crossorigin>`).
+- [ ] Font subset to actual character set (no full Unicode for Latin-only sites).
+- [ ] No render-blocking external font CSS (Google Fonts) for above-fold.
+
+## JavaScript
+
+- [ ] Initial JS bundle ≤ 200KB compressed.
+- [ ] Code-split per route (web).
+- [ ] Tree-shaking verified (named imports, ESM, no barrel re-exports).
+- [ ] Heavy dependencies replaced (Moment → date-fns, full Lodash → individual functions).
+- [ ] No render-blocking analytics / tag-manager script in `<head>`.
+- [ ] Long tasks (> 50ms) profiled; broken up if found in critical path.
+
+## Mobile (React Native)
+
+- [ ] Hermes enabled both platforms.
+- [ ] R8 / ProGuard enabled in Android release.
+- [ ] App cold-start time ≤ 1.5s on Pixel 6a / iPhone 12 mini.
+- [ ] App warm-start ≤ 500ms.
+- [ ] Scroll FPS ≥ 60 on long lists (FlashList used).
+- [ ] Animation FPS ≥ 60 (Reanimated worklets).
+- [ ] Memory after 5 minutes' use ≤ 250MB.
+- [ ] Bundle size: JS uncompressed ≤ 4MB.
+- [ ] Native size per platform ≤ 50MB download.
+- [ ] FastImage used for any image-heavy list.
+- [ ] No `console.*` in release bundle (`babel-plugin-transform-remove-console`).
+- [ ] Splash screen kept until first useful frame (`react-native-bootsplash`).
+- [ ] Non-critical init deferred via `InteractionManager.runAfterInteractions`.
+
+## Backend
+
+- [ ] P50 latency ≤ 100ms; P95 ≤ 300ms; P99 ≤ 1s.
+- [ ] Error rate ≤ 0.1% under normal load.
+- [ ] CPU < 70% sustained, memory < 70% sustained at peak.
+- [ ] DB connection pool < 60% utilization at peak.
+- [ ] No N+1 queries in hot paths (verified with `pg_stat_statements`).
+- [ ] All hot queries have appropriate indexes (verified with EXPLAIN ANALYZE).
+- [ ] Cache hit rate > 90% for cached endpoints.
+- [ ] APM / tracing wired up (OpenTelemetry → Datadog / Honeycomb / Tempo).
+
+## Database (cross-references db-design)
+
+- [ ] `pg_stat_statements` enabled and reviewed weekly.
+- [ ] `auto_explain` on with 500ms threshold; logs reviewed.
+- [ ] Connection pooling correct (per `db-design`).
+- [ ] No long-running idle transactions (`idle_in_transaction_session_timeout` set).
+- [ ] Backups verified by quarterly restore test.
+
+## Caching
+
+- [ ] CDN in front of static assets + cacheable endpoints.
+- [ ] Cache headers explicit on every endpoint (`no-store` for sensitive).
+- [ ] Application cache (Redis) for hot reads.
+- [ ] Cache invalidation strategy documented per cached resource.
+- [ ] No PII cached at edge (CDN).
+
+## Network
+
+- [ ] HTTP/2 or HTTP/3 enabled.
+- [ ] Gzip / Brotli compression for responses > 1KB.
+- [ ] `Connection: keep-alive` enabled.
+- [ ] Preconnect to critical third-party origins.
+- [ ] `<link rel="dns-prefetch">` for less-critical third-party origins.
+
+## CI Regression Gates
+
+- [ ] **Bundle-size budget** in CI; fails if any chunk > 5% larger.
+- [ ] **Lighthouse CI** per PR on key pages; fails on Performance score drop.
+- [ ] **k6 load test** weekly against staging; alerts on P95 regression.
+- [ ] **Mobile**: cold-start time tracked per release.
+- [ ] **APM**: p95 latency dashboards reviewed weekly; alerts on drift.
+
+## Observability
+
+- [ ] OpenTelemetry traces propagated end-to-end (RN client → backend → DB).
+- [ ] RUM collects Web Vitals + custom metrics.
+- [ ] Per-endpoint metrics: count, P50/P95/P99 latency, error rate.
+- [ ] Slow-query log threshold set (~500ms).
+- [ ] Per-screen mobile perf reported (cold-start, render time, error rate).
+
+## Common Anti-Patterns Audit
+
+- [ ] No optimization without measurement attached.
+- [ ] No hand-rolled caching when TanStack Query / SWR exists.
+- [ ] No re-renders ignored (React DevTools profiler reviewed for hot screens).
+- [ ] No N+1 queries unnoticed.
+- [ ] No giant JPEG hero images.
+- [ ] No synchronous render-blocking script in `<head>`.
+- [ ] No `font-display: block`.
+- [ ] No `@import` in CSS.
+- [ ] No connection-per-request to DB.
+
+## Pre-Launch Smoke
+
+- [ ] Cold-start measured on real mid-tier device (Pixel 6a / iPhone 12 mini).
+- [ ] Critical user flow timed end-to-end.
+- [ ] Network throttled to 4G slow → app still usable.
+- [ ] CPU throttled 4× → no jank.
+
+---
+
+If any box is unchecked, document the reason in a tracking issue with an ETA.
+
+## Per-Surface Quick Reference
+
+```
+Web:
+  LCP ≤ 2.5s   INP ≤ 200ms   CLS ≤ 0.1   TTFB ≤ 800ms
+
+Mobile (RN):
+  Cold start ≤ 1.5s   Scroll FPS = 60   Memory ≤ 250MB
+  JS bundle ≤ 4MB     Native size ≤ 50MB
+
+Backend:
+  P50 ≤ 100ms   P95 ≤ 300ms   P99 ≤ 1s   Errors ≤ 0.1%
+  CPU ≤ 70%     Memory ≤ 70%   Pool ≤ 60%
+```

core/skills/performance/references/mobile-performance.md

@@ -0,0 +1,249 @@
+# Mobile Performance — React Native Specific
+
+The actual playbook for keeping a React Native app fast on real devices. Pulls from Callstack's optimization guide + Hermes / FlashList / Reanimated documentation.
+
+## Three Categories of Slowness
+
+| Category | Symptom | Where to look |
+|---|---|---|
+| **Startup** | Cold launch > 2s | Hermes lazy parse, native init, Metro bundle, splash screen |
+| **Runtime jank** | Scroll < 60 FPS, animations stutter | JS thread blocks, heavy renders, bridge traffic |
+| **Memory / battery** | App killed in background, drains battery | Memory leaks, native modules, unsubscribed listeners |
+
+Each has different tools + fixes. Diagnose first.
+
+## Startup Time (TTI)
+
+### Measure
+
+- **iOS**: Xcode → Instruments → "App Launch" template. Or `xcrun simctl launch --console <bundle-id>` and time it.
+- **Android**: `adb shell am start -W com.app/.MainActivity` reports `TotalTime`.
+- **In-app**: log `Date.now()` in `index.js` first line and again in `App.tsx`'s first render — diff is JS startup.
+
+### Optimization
+
+1. **Hermes enabled** — required. Both platforms.
+2. **Pre-compiled bytecode** — Hermes ships `.hbc` files; Metro builds them in release mode automatically.
+3. **Lazy parsing** — Hermes parses functions on first call by default. Don't disable.
+4. **Reduce initial bundle**:
+   - `import` only what you need (tree-shake).
+   - Defer non-critical screens with React Navigation's lazy `getComponent`.
+   - Defer non-critical libraries: load analytics / push setup AFTER first render.
+5. **Defer native module init** that's not needed at launch.
+6. **Splash screen kept until first useful frame** (`react-native-bootsplash`). Better UX than launching to white.
+7. **InteractionManager.runAfterInteractions** for non-essential work after navigation.
+
+```typescript
+// In App.tsx
+useEffect(() => {
+  // Defer heavy init until after first paint.
+  InteractionManager.runAfterInteractions(() => {
+    initAnalytics();
+    setupPushHandlers();
+    prefetchNextScreens();
+  });
+}, []);
+```
+
+## Frame Rate (60 / 120 FPS)
+
+### Measure
+
+- **In-app**: enable React Native's perf monitor (Cmd+M / Cmd+D → Show Perf Monitor). Shows JS + UI thread FPS.
+- **Flipper**: React DevTools Profiler — see component re-renders.
+- **Hermes Sampling Profiler**: `hermes -enable-eval -sample-profiler`. Shows where JS time is spent.
+
+### Diagnose
+
+- Drops in **JS thread FPS** during scroll → JS work blocking (re-renders, sync I/O).
+- Drops in **UI thread FPS** during animation → native animation issue (rare with Reanimated worklets).
+- Stutter only on first scroll → cold native rendering; warm up via FlashList scroll-to-end on mount.
+
+### Optimization
+
+1. **FlashList for any list > 50 items** (per `react-native-patterns`). FlatList = old, slow. FlashList recycles row instances; 10–50× faster.
+2. **`useCallback` and `useMemo` aggressively** in row components.
+3. **`React.memo`** on row component, with custom equality if needed.
+4. **`useNativeDriver: true`** on legacy `Animated` (or use Reanimated, which is always native).
+5. **Reanimated 3 worklets** for any gesture-driven animation. Worklets run on UI thread; no bridge involvement.
+6. **Avoid `setState` in scroll handlers** without throttle / debounce.
+7. **`removeClippedSubviews={true}`** on long ScrollView (Android only; iOS is fine without).
+
+```typescript
+// Reanimated 3 worklet — runs on UI thread, 60 FPS guaranteed
+import Animated, { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';
+
+const scale = useSharedValue(1);
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: scale.value }],
+}));
+
+<Animated.View style={animatedStyle}>...</Animated.View>
+<Pressable
+  onPressIn={() => { scale.value = withSpring(0.95); }}
+  onPressOut={() => { scale.value = withSpring(1); }}>
+  ...
+</Pressable>
+```
+
+## JS Thread — Don't Block
+
+The JS thread runs all React work. Block it = drop frames.
+
+**Measure**: JS FPS drops during scroll / animation in the perf monitor.
+
+**Defenses**:
+
+- **No sync JSON parse > 100KB** in render. Move to `InteractionManager.runAfterInteractions` or a worker.
+- **Use `react-native-mmkv`** (synchronous, ~30x faster than AsyncStorage) for small data; AsyncStorage offloads to native thread but has overhead per call.
+- **Defer heavy computation**:
+  ```typescript
+  InteractionManager.runAfterInteractions(() => {
+    const result = heavyComputation();
+    setState(result);
+  });
+  ```
+- **`useDeferredValue`** in React 18+ for low-priority updates.
+- **Background thread** for crypto / image processing: `react-native-fast-tflite` etc. spawn off-thread.
+
+## Bundle Size
+
+### Measure
+
+```bash
+# Install:
+yarn add -D react-native-bundle-visualizer
+
+# Run:
+yarn react-native-bundle-visualizer
+# Opens the bundle in browser; click into chunks.
+```
+
+### Diagnose
+
+Common offenders:
+
+- **Moment.js** → swap for `date-fns` (tree-shakable) or native `Intl`.
+- **Lodash** → `import { debounce } from 'lodash-es'` (tree-shake) OR write your own.
+- **lottie-react-native + animations** → keep animation files small (Lottie JSON can balloon).
+- **All locale files of i18n libs** — only import the locales you ship.
+
+### Reduce
+
+1. **Tree-shaking**: ESM imports (`import { foo }`), not CJS (`require('lib')`).
+2. **Dead-code-elimination** via Metro's minifier.
+3. **Avoid barrel exports** (`index.ts` re-exports everything) — they defeat tree-shake.
+4. **Hermes pre-compile**: bytecode is smaller than minified JS in many cases.
+
+## Image Performance (RN)
+
+Images are usually the biggest perf cost on mobile.
+
+### Tools
+
+- **`react-native-fast-image`** — uses SDWebImage (iOS) / Glide (Android). Disk + memory cache. Faster decoding.
+- Always `style={{ width, height }}` — fixed dimensions.
+- **Resize on the server** (CDN) — never download a 4000px image to a 400px display.
+- **WebP** format on both platforms (native support since iOS 14 / Android API 14).
+
+```tsx
+import FastImage from 'react-native-fast-image';
+
+<FastImage
+  source={{ uri: `https://cdn.app.com/photos/${id}?w=600&fmt=webp`,
+            priority: FastImage.priority.normal,
+            cache: FastImage.cacheControl.immutable }}
+  style={{ width: 200, height: 200 }}
+  resizeMode={FastImage.resizeMode.cover}
+/>
+```
+
+### Image-Heavy Lists
+
+- Pre-fetch images for next-N rows: `FastImage.preload([{ uri: ... }])`.
+- Resize / thumbnail on the server; never client-resize a giant image.
+
+## Native Modules — Bridge Cost
+
+Every JS↔native call costs ~50-200µs in the legacy bridge. TurboModules (default in 0.76+ New Architecture) is much faster but still not free.
+
+**Defenses**:
+
+- **Batch calls** — `NativeModule.processMany(items)` instead of N calls.
+- **TurboModules** for sync calls when needed (legacy bridge is async-only).
+- **JSI** for hot paths — direct C++ binding, near-zero overhead. Use `react-native-mmkv`, `react-native-reanimated`, `react-native-fast-image` patterns.
+
+## Memory + Leaks
+
+### Measure
+
+- **Xcode Instruments → Allocations / Leaks**.
+- **Android Studio → Profiler → Memory**.
+- **React DevTools profiler** — see what's still mounted that shouldn't be.
+
+### Common Leak Sources
+
+1. **Subscriptions not cleaned up** in `useEffect` return.
+2. **Timers** not cleared.
+3. **Event listeners** not removed.
+4. **Module-scope arrays / maps** that grow forever.
+5. **Closures retaining big objects** — captured `data` lives as long as the closure.
+6. **Circular refs** in JS (rare; GC handles most).
+7. **Native side**: image cache too large, native module retaining buffers.
+
+### Fix
+
+```typescript
+useEffect(() => {
+  const sub = SomeAPI.subscribe(...);
+  const timer = setInterval(...);
+  const listener = AppState.addEventListener('change', ...);
+
+  return () => {
+    sub.remove();
+    clearInterval(timer);
+    listener.remove();
+  };
+}, [...stable deps]);
+```
+
+## Battery Drain
+
+The user-visible measure of inefficient code.
+
+**Common drains**:
+
+- Background polls / GPS / Bluetooth that don't pause when app backgrounded.
+- WebSocket reconnect storms.
+- Repeated wakeups by push notifications without coalescing.
+- Long video / audio playback without proper buffering.
+
+**Test**:
+
+- iOS: leave app open 30 min; check Battery section in Settings → Battery for your app's CPU%.
+- Android: Battery Historian (`adb bugreport`) or Settings → Battery → Battery usage.
+
+## Per-Phase Tactics
+
+### Pre-launch
+
+- Bundle analyzer run; nothing surprising.
+- Hermes + R8/ProGuard enabled.
+- FastImage configured.
+- Critical screens use FlashList.
+
+### Post-launch monitoring
+
+- Sentry / Crashlytics with performance monitoring (perf traces per screen).
+- Real-device cold-start time tracked.
+- Bundle size budgeted; CI fails on > 5% growth.
+
+## Source Material
+
+- Callstack — *Ultimate Guide to React Native Optimization*.
+- React Native — *Performance Overview*: <https://reactnative.dev/docs/performance>
+- Hermes docs — Sampling profiler usage.
+- Reanimated 3 docs — worklet patterns.
+- Shopify FlashList — internals + optimization guide.
+- Apple — *Energy Efficiency Guide for iOS*.
+- Android — *Battery and Memory Optimization*.