create-disposabl-app 0.0.4 → 0.1.1

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/js-lists-flatlist-flashlist.md

@@ -0,0 +1,223 @@
+---
+title: Higher-Order Lists
+impact: CRITICAL
+tags: lists, flatlist, flashlist, legend-list, scrollview, virtualization
+---
+
+# Skill: Higher-Order Lists
+
+Replace ScrollView with FlatList, FlashList, or Legend List for performant large list rendering.
+
+## Quick Pattern
+
+**Incorrect:**
+
+```jsx
+<ScrollView>
+  {items.map((item) => <Item key={item.id} {...item} />)}
+</ScrollView>
+```
+
+**Correct:**
+
+```jsx
+<FlashList
+  data={items}
+  keyExtractor={(item) => item.id}
+  renderItem={({ item }) => <Item {...item} />}
+  // FlashList v1 only: add estimatedItemSize.
+  // FlashList v2+: do not add estimated sizing props.
+/>
+```
+
+## When to Use
+
+- Rendering enough items that eager mounting affects FPS, memory, or startup
+- List scrolling is choppy or laggy
+- App freezes when loading list data
+- Memory usage spikes with long lists
+
+## Prerequisites
+
+- `@shopify/flash-list` for FlashList on React Native New Architecture
+- `@legendapp/list` for a JS/TypeScript list option without native dependencies
+- Understanding of list virtualization
+
+## Version Guardrail
+
+- FlashList v1: `estimatedItemSize` is part of the optimization guidance.
+- FlashList v2 and newer: `estimatedItemSize`, `estimatedListSize`, and `estimatedFirstItemOffset` are deprecated and no longer used. Do not flag them as missing.
+- Before suggesting a FlashList fix, confirm the installed major version and tailor the advice. See [FlashList v2 changes](https://shopify.github.io/flash-list/docs/v2-changes/).
+
+## Step-by-Step Instructions
+
+### 1. Identify the Problem
+
+![FPS Drop Graph](images/fps-drop-graph.png)
+
+```jsx
+// BAD: ScrollView renders ALL items at once
+const BadList = ({ items }) => (
+  <ScrollView>
+    {items.map((item) => (
+      <View key={item.id}>
+        <Text>{item.title}</Text>
+      </View>
+    ))}
+  </ScrollView>
+);
+```
+
+Large eager lists mount every row immediately, increasing JS work, native view count, and memory before the user can interact.
+
+### 2. Replace with FlatList
+
+```jsx
+import { FlatList } from 'react-native';
+
+const BetterList = ({ items }) => {
+  const renderItem = ({ item }) => (
+    <View>
+      <Text>{item.title}</Text>
+    </View>
+  );
+  
+  return (
+    <FlatList
+      data={items}
+      renderItem={renderItem}
+      keyExtractor={(item) => item.id}
+    />
+  );
+};
+```
+
+FlatList only renders visible items + buffer (windowing).
+
+### 3. Optimize FlatList with getItemLayout
+
+For fixed-height items, skip layout measurement:
+
+```jsx
+const ITEM_HEIGHT = 50;
+
+const OptimizedList = ({ items }) => {
+  const renderItem = ({ item }) => (
+    <View style={{ height: ITEM_HEIGHT }}>
+      <Text>{item.title}</Text>
+    </View>
+  );
+  
+  const getItemLayout = (_, index) => ({
+    length: ITEM_HEIGHT,
+    offset: ITEM_HEIGHT * index,
+    index,
+  });
+  
+  return (
+    <FlatList
+      data={items}
+      renderItem={renderItem}
+      keyExtractor={(item) => item.id}
+      getItemLayout={getItemLayout}
+    />
+  );
+};
+```
+
+### 4. Upgrade to FlashList
+
+```bash
+npm install @shopify/flash-list
+```
+
+```jsx
+import { FlashList } from '@shopify/flash-list';
+
+const BestList = ({ items }) => {
+  const renderItem = ({ item }) => (
+    <View style={{ height: 50 }}>
+      <Text>{item.title}</Text>
+    </View>
+  );
+  
+  return (
+    <FlashList
+      data={items}
+      renderItem={renderItem}
+      keyExtractor={(item) => item.id}
+    />
+  );
+};
+```
+
+For FlashList v1, add `estimatedItemSize` with a realistic average item height. FlashList v2 requires React Native New Architecture and no longer needs size estimates; it computes sizing automatically. For old architecture apps, use FlashList v1 docs or evaluate Legend List.
+
+**FlashList advantages:**
+- Recycles views instead of creating new ones
+- Often improves memory and scroll smoothness for large, complex lists
+- Supports item-type-aware recycling with `getItemType`
+
+### 5. Evaluate Legend List
+
+Legend List is a JS/TypeScript list alternative with no native dependency. It supports dynamic item sizes, bidirectional infinite scrolling, chat-friendly bottom alignment, and optional recycling.
+
+Enable `recycleItems` for long lists after confirming item components do not keep item-specific local state or side effects.
+
+## Code Examples
+
+### Mixed Item Types
+
+```jsx
+<FlashList
+  data={items}
+  renderItem={({ item }) => {
+    if (item.type === 'header') return <Header {...item} />;
+    if (item.type === 'product') return <Product {...item} />;
+    return <DefaultItem {...item} />;
+  }}
+  getItemType={(item) => item.type}  // Helps recycling
+/>
+```
+
+If the project is still on FlashList v1, keep `estimatedItemSize` alongside `getItemType`.
+
+### FlatList Optimizations (if not using FlashList)
+
+```jsx
+<FlatList
+  data={items}
+  renderItem={renderItem}
+  // Performance props
+  removeClippedSubviews={true}
+  maxToRenderPerBatch={10}
+  updateCellsBatchingPeriod={50}
+  initialNumToRender={10}
+  windowSize={5}
+  // Avoid re-renders
+  keyExtractor={(item) => item.id}
+  extraData={selectedId}  // Only when selection changes
+/>
+```
+
+## Decision Matrix
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Small static content | ScrollView OK |
+| Measured eager-mount or scroll cost | FlatList minimum |
+| Large or complex list | FlashList or Legend List |
+| Complex item layouts | FlashList with `getItemType`, or Legend List |
+| Fixed height items | FlatList: `getItemLayout`; FlashList v1: `estimatedItemSize`; FlashList v2+: stable item structure |
+
+## Common Pitfalls
+
+- **Inline renderItem functions**: Causes re-renders. Define outside or use `useCallback`.
+- **Missing keyExtractor**: Use unique IDs, not array index when possible.
+- **Assuming all FlashList versions need `estimatedItemSize`**: FlashList v2 ignores it. Check the installed version before suggesting it.
+- **Heavy item components**: Keep list items light. Move side effects out.
+
+## Related Skills
+
+- [js-profile-react.md](./js-profile-react.md) - Profile list rendering
+- [js-measure-fps.md](./js-measure-fps.md) - Measure scroll performance

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/js-measure-fps.md

@@ -0,0 +1,178 @@
+---
+title: Measure JS FPS
+impact: HIGH
+tags: fps, performance, monitoring, flashlight
+---
+
+# Skill: Measure JS FPS
+
+Monitor and measure JavaScript frame rate to quantify app smoothness and identify performance regressions.
+
+## Quick Command
+
+```bash
+# Method 1: Built-in Perf Monitor
+# Shake device → Dev Menu → "Perf Monitor"
+
+# Method 2: Flashlight (Android, detailed reports)
+# Install Flashlight from an official, verified release channel first.
+flashlight measure
+```
+
+## When to Use
+
+- Animations feel choppy or janky
+- Scrolling is not smooth
+- Need baseline FPS metrics before/after optimization
+- Want to compare performance across builds
+
+## Prerequisites
+
+- React Native app running on device/simulator
+- For Flashlight: Android device (iOS not supported)
+
+> **Note**: This skill involves visual output (FPS graphs, performance overlays). Use `agent-device` for runnable scenario evidence; install it through the environment's approved/trusted path or ask the user if verification needs it and it is missing. FPS graph interpretation may still require exported reports or human review. Record concrete FPS ranges, dropped-frame counts, device tier, and build type in text when asking an agent to reason about them.
+
+## Step-by-Step Instructions
+
+### Method 1: React Perf Monitor (Quick Check)
+
+1. Open Dev Menu:
+   - iOS Simulator: `Ctrl + Cmd + Z` or Device > Shake
+   - Android Emulator: `Cmd + M` (Mac) / `Ctrl + M` (Windows)
+
+2. Select **"Perf Monitor"**
+
+3. Observe the overlay showing:
+   - **UI (Main) thread FPS** - Native rendering
+   - **JS thread FPS** - JavaScript execution
+   - **RAM usage**
+
+4. Hide with "Hide Perf Monitor" from Dev Menu
+
+**Interpretation:**
+- **60 FPS** = Smooth (16.6ms per frame)
+- **< 60 FPS** = Dropping frames
+- **120 FPS** target for high refresh rate devices (8.3ms per frame)
+
+### Method 2: Flashlight (Automated Benchmarking)
+
+> Android only. Provides detailed reports and JSON export.
+
+![Flashlight FlatList vs FlashList Comparison](images/flashlight-flatlist-vs-flashlist.png)
+
+Flashlight shows comparative performance data:
+- **Score** (0-100): Overall performance rating (higher is better)
+- **Average FPS**: Target 60 FPS for smooth scrolling
+- **FPS Graph**: Real-time frame rate over test duration
+- **CPU/RAM metrics**: Resource consumption
+
+The image shows FlatList (score: 3) vs FlashList (score: 67) - a dramatic difference visible in both the score and FPS graph.
+
+**Installation:**
+
+Install Flashlight from the vendor's official release channel before using it. Prefer a package manager or a version-pinned binary with checksum/signature verification. Do not pipe a remote install script directly into a shell.
+
+**Usage:**
+
+```bash
+# Start measuring (app must be running on Android)
+flashlight measure
+```
+
+**Features:**
+- Real-time FPS graph
+- Average FPS calculation
+- CPU and RAM metrics
+- Overall performance score
+- JSON export for CI comparison
+
+### Important: Disable Dev Mode
+
+**Always disable development mode for accurate measurements:**
+
+**Android:**
+1. Open Dev Menu
+2. Settings > JS Dev Mode → **OFF**
+
+**iOS (React Native CLI):**
+```bash
+# Clear Metro cache if needed; this is not a production/release switch
+npx react-native start --reset-cache
+# Then run a Release scheme/build from Xcode or your CI
+```
+
+**Expo:**
+```bash
+# Start Metro without dev mode
+npx expo start --no-dev --minify
+# For accurate measurements, use EAS Build for release testing
+```
+
+## Code Examples
+
+### Identify FPS Drop Source
+
+If **UI FPS drops but JS FPS is fine:**
+- Native rendering issue
+- Too many views/complex layouts
+- Heavy native animations
+
+If **JS FPS drops but UI FPS is fine:**
+- JavaScript computation blocking
+- Expensive React re-renders
+- Look for `longRunningFunction` patterns
+
+If **Both drop:**
+- Mixed issue, start with JS profiling
+
+### Target Frame Budgets
+
+```javascript
+// 60 FPS = 16.6ms per frame
+const FRAME_BUDGET_60 = 16.6;
+
+// 120 FPS = 8.3ms per frame  
+const FRAME_BUDGET_120 = 8.3;
+
+// If your function takes longer, it will drop frames
+const longRunningFunction = () => {
+  let i = 0;
+  while (i < 1000000000) { // This blocks for seconds!
+    i++;
+  }
+};
+```
+
+## Interpreting Results
+
+| FPS Range | User Perception | Action |
+|-----------|-----------------|--------|
+| 55-60 | Smooth | Acceptable |
+| 45-55 | Slight stutter | Investigate |
+| 30-45 | Noticeable jank | Optimize required |
+| < 30 | Very choppy | Critical fix needed |
+
+## Flashlight CI Integration
+
+```bash
+# Export measurements to JSON
+flashlight measure --output results.json
+
+# Compare builds
+flashlight compare baseline.json current.json
+```
+
+## Common Pitfalls
+
+- **Measuring in dev mode**: Results will be artificially slow
+- **Not using real device**: Simulators don't reflect real performance
+- **Ignoring UI thread**: React Native has two threads - JS issues don't always show on UI thread
+- **Single measurement**: Run multiple times, FPS varies
+
+## Related Skills
+
+- [js-profile-react.md](./js-profile-react.md) - Find what's causing FPS drops
+- [js-animations-reanimated.md](./js-animations-reanimated.md) - Fix animation-related drops
+- [js-bottomsheet.md](./js-bottomsheet.md) - Measure bottom sheet gesture and snap performance
+- [js-lists-flatlist-flashlist.md](./js-lists-flatlist-flashlist.md) - Fix scroll-related drops

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/js-memory-leaks.md

@@ -0,0 +1,168 @@
+---
+title: Hunt JS Memory Leaks
+impact: MEDIUM
+tags: memory, leaks, profiling, cleanup
+---
+
+# Skill: Hunt JS Memory Leaks
+
+Find and fix JavaScript memory leaks using the React Native DevTools Memory tab, with `agent-device react-devtools` for related component context.
+
+## Quick Pattern
+
+**Incorrect (listener not cleaned up):**
+
+```jsx
+useEffect(() => {
+  const sub = EventEmitter.addListener('event', handler);
+  // Missing cleanup!
+}, []);
+```
+
+**Correct (proper cleanup):**
+
+```jsx
+useEffect(() => {
+  const sub = EventEmitter.addListener('event', handler);
+  return () => sub.remove();
+}, []);
+```
+
+## When to Use
+
+- App memory usage grows over time
+- App crashes after extended use
+- Navigating between screens increases memory
+- Suspecting event listeners or timers not cleaned up
+
+## Prerequisites
+
+- React Native DevTools Memory tab or exported memory profile available
+- `agent-device react-devtools` for related component ownership/render debugging
+- App running in development mode
+
+## Step-by-Step Instructions
+
+React Native DevTools supports heap snapshots, allocation instrumentation on timeline, and allocation sampling. Use allocation timeline to isolate leaks; use allocation sampling for lower-overhead long-running allocation profiling. Use `agent-device react-devtools` when you need token-efficient component tree, props, state, hooks, ownership, or render-cause context while investigating the leak.
+
+`agent-device react-devtools` does not replace the Memory tab. Use it only for related component context; heap snapshots and allocation timelines require the React Native DevTools Memory UI or an exported memory profile.
+
+### 1. Open Memory Profiler
+
+1. Open the React Native DevTools Memory tab or load an exported memory profile
+2. Select **"Allocation instrumentation on timeline"**
+
+### 2. Record Memory Allocations
+
+1. Click **"Start"** at the bottom
+2. Perform actions that might leak (navigate, trigger events, etc.)
+3. Wait 10-30 seconds
+4. Click **"Stop"**
+
+### 3. Analyze the Timeline
+
+**Key indicators:**
+- **Blue bars** = Memory allocated
+- **Gray bars** = Memory freed (garbage collected)
+- **Blue bars that stay blue** = Potential leak!
+
+### 4. Investigate Leaking Objects
+
+![Memory Heap Snapshot](images/memory-heap-snapshot.png)
+
+The Memory tab shows:
+- **Timeline** (top): Blue bars = allocations, select time range to filter
+- **Summary view** (bottom): Lists constructors with allocation counts
+
+**Key columns:**
+- **Constructor**: Object type (e.g., `JSObject`, `Function`, `(string)`)
+- **Count**: Number of instances
+- **Shallow Size**: Memory of the object itself
+- **Retained Size**: Memory freed if object is deleted (including references)
+
+**Red flag**: Large retained size % with small shallow size % = closures or references holding large objects.
+
+**To investigate:**
+1. Click on a blue spike in the timeline
+2. Look at the Constructor list below
+3. Check **Shallow size** vs **Retained size**
+4. Expand constructors to see individual allocations
+5. Click to see the exact source location
+
+### 5. Verify the Fix
+
+After fixing, re-profile the same flow. Memory should return to a stable baseline after GC and repeated interactions; some recent allocations can remain live legitimately.
+
+## Code Examples
+
+### Common Leak Patterns
+
+**1. Listeners Not Cleaned Up:**
+
+```jsx
+// BAD: Memory leak
+const BadEventComponent = () => {
+  useEffect(() => {
+    const subscription = EventEmitter.addListener('myEvent', handleEvent);
+    // Missing cleanup!
+  }, []);
+  
+  return <Text>Listening...</Text>;
+};
+
+// GOOD: Proper cleanup
+const GoodEventComponent = () => {
+  useEffect(() => {
+    const subscription = EventEmitter.addListener('myEvent', handleEvent);
+    return () => subscription.remove(); // Cleanup!
+  }, []);
+  
+  return <Text>Listening...</Text>;
+};
+```
+
+**2. Timers Not Cleared:**
+
+```jsx
+// BAD: Memory leak
+const BadTimerComponent = () => {
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setCount(prev => prev + 1);
+    }, 1000);
+    // Missing cleanup!
+  }, []);
+};
+
+// GOOD: Proper cleanup
+const GoodTimerComponent = () => {
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setCount(prev => prev + 1);
+    }, 1000);
+    return () => clearInterval(timer); // Cleanup!
+  }, []);
+};
+```
+
+Other common sources are closures that retain large objects and module-level arrays/maps that only grow. Confirm these through retained-size paths before refactoring them.
+
+## Memory Profiler Metrics
+
+| Metric | Meaning |
+|--------|---------|
+| **Shallow size** | Memory held by the object itself |
+| **Retained size** | Memory freed if object is deleted (includes references) |
+
+**Large retained size with small shallow size** = Object holding references to other large objects (common in closures).
+
+## Common Pitfalls
+
+- **Not forcing GC**: GC runs periodically. Allocate something else to trigger collection before concluding there's a leak.
+- **Over-reading allocation colors**: Persisting allocations are suspects, not proof. Confirm with retained objects and repeated flows.
+- **Missing useEffect cleanup**: Most common React Native leak source.
+
+## Related Skills
+
+- [native-memory-leaks.md](./native-memory-leaks.md) - Native-side memory leaks
+- [js-profile-react.md](./js-profile-react.md) - General profiling

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/js-profile-react.md

@@ -0,0 +1,138 @@
+---
+title: Profile React Performance
+impact: MEDIUM
+tags: profiling, devtools, re-renders, flamegraph
+---
+
+# Skill: Profile React Performance
+
+Identify unnecessary re-renders and performance bottlenecks in React Native apps using React Native DevTools through `agent-device react-devtools`.
+
+## Quick Command
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools wait --connected
+agent-device react-devtools profile start
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+agent-device react-devtools profile timeline --limit 20
+```
+
+Drive the target interaction with normal `agent-device` commands between `profile start` and `profile stop`. For targeted audits, profile the exact flow under review. Baseline output should include commit timeline, re-render counts, slow components, and a breakdown of the heaviest commit.
+
+## When to Use
+
+- App feels sluggish or janky during interactions
+- Need to identify which components re-render unnecessarily
+- Investigating slow list scrolling or form inputs
+- Before applying memoization or state management changes
+
+## Prerequisites
+
+- React Native DevTools connection available through `agent-device react-devtools`
+- App running in development mode
+- React DevTools version compatible with the app's React and React Native versions
+- For release-build profiling, [`@callstack/inspector`](https://github.com/callstackincubator/inspector#inspector) installed and connected first
+
+> **Note**: Prefer `agent-device react-devtools` over the visual DevTools UI for token-efficient React profiling and debugging. Use the visual UI or exported profiler JSON only when the CLI output is insufficient. Record concrete commit times, render counts, and component names.
+
+Manual fallback when `agent-device` is unavailable: open React Native DevTools from Metro (`j`) or the Dev Menu, use the Profiler tab, and record the same interaction. Keep this as fallback only; agent runs should prefer the CLI summaries above.
+
+## Step-by-Step Instructions
+
+### 1. Connect React Native DevTools
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools wait --connected
+```
+
+If `status` reports the helper is not running, start it first:
+
+```bash
+agent-device react-devtools start
+agent-device react-devtools wait --connected
+```
+
+#### Release Builds
+
+React Native release builds do not expose the same profiling path by default. Before using `agent-device react-devtools` against a release app, wire in `@callstack/inspector`:
+
+```bash
+npm install @callstack/inspector
+npx inspector start
+```
+
+Import `@callstack/inspector` as the first module in the app entrypoint, wrap Metro config with `withInspector(config, true)`, then build and run the app in release mode. For Expo, use a release build from prebuild/dev-client flow; Expo Go is not a release-build profiling target.
+
+### 2. Record a Profiling Session
+
+```bash
+agent-device react-devtools profile start
+agent-device react-devtools profile stop
+```
+
+Drive the exact interaction or navigation flow under review between those two commands.
+
+For AI-agent workflows, treat this as a required sequence:
+
+1. Run `agent-device react-devtools status`.
+2. Run `agent-device react-devtools wait --connected`.
+3. Start profiling immediately before the audited interaction.
+4. Drive the flow with normal `agent-device` commands.
+5. Stop profiling.
+6. Inspect slow components, re-render counts, and commit timing before proposing fixes.
+
+### 3. Analyze Results
+
+![React DevTools Flamegraph](images/devtools-flamegraph.png)
+
+Use bounded CLI summaries first:
+
+```bash
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+agent-device react-devtools profile timeline --limit 20
+```
+
+Then drill into a specific component:
+
+```bash
+agent-device react-devtools profile report @c5
+agent-device react-devtools get component @c5
+```
+
+Use the component ref printed by `profile slow`, `profile rerenders`, or `get tree`; `@c5` is only an example.
+
+Use the visual flame graph or exported profiler JSON only when the bounded CLI summaries do not answer the question.
+
+### 4. Profile JavaScript CPU
+
+For non-React CPU issues, use platform CPU profilers or `agent-device perf` instead of React DevTools render profiling.
+
+## Interpreting Results
+
+| Symptom | Likely Cause | Solution |
+|---------|--------------|----------|
+| Many yellow components | Cascading re-renders | Add memoization or use React Compiler |
+| "Props changed" on callbacks | Inline functions recreated | Use `useCallback` |
+| "Parent component rendered" | State too high in tree | Move state down or use atomic state |
+| Long JS thread block | Heavy computation | Move to background or use `useDeferredValue` |
+
+Only propose callback or dependency-array changes when the profiler or a reproducible bug shows they matter. Do not infer stale closures from a snippet alone.
+
+## Common Pitfalls
+
+- **Using one build type for every question**: Use `agent-device react-devtools` in development to identify render causes, commit patterns, and expensive components. Validate timing-sensitive FPS/CPU improvements in production or release-like builds.
+- **Not using production builds**: Some issues only appear with minified code
+- **Ignoring "Why did this render?"**: This tells you exactly what to fix
+- **Using component tree depth or count as the main baseline**: These are secondary context, not the core performance signal
+
+## Related Skills
+
+- [js-react-compiler.md](./js-react-compiler.md) - Automatic memoization
+- [js-atomic-state.md](./js-atomic-state.md) - Reduce re-renders with Jotai/Zustand
+- [js-bottomsheet.md](./js-bottomsheet.md) - Profile bottom sheet callback-driven re-renders
+- [js-measure-fps.md](./js-measure-fps.md) - Quantify frame rate impact