create-disposabl-app 0.0.4 → 0.1.1

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

@@ -0,0 +1,261 @@
+---
+title: React Compiler
+impact: HIGH
+tags: memoization, react-compiler, memo, useMemo, useCallback
+---
+
+# Skill: React Compiler
+
+Set up React Compiler to automatically memoize components and eliminate unnecessary re-renders.
+
+## Quick Pattern
+
+**Before (manual memoization):**
+
+```jsx
+const MemoizedButton = memo(({ onPress }) => <Pressable onPress={onPress} />);
+const handler = useCallback(() => doSomething(), []);
+```
+
+**After (automatic with React Compiler):**
+
+```jsx
+// No memo/useCallback needed - compiler handles it
+const Button = ({ onPress }) => <Pressable onPress={onPress} />;
+const handler = () => doSomething();
+```
+
+## When to Use
+
+- Want automatic performance optimization without manual `memo`/`useMemo`/`useCallback`
+- Codebase follows Rules of React
+- React Native 0.76+ or Expo SDK 52+
+- Ready to remove boilerplate memoization code
+
+## Prerequisites
+
+- Babel-based build system
+- Code follows [Rules of React](https://react.dev/reference/rules)
+- Check current React Native, Expo, and React Compiler release notes before copying version-specific setup
+
+## Step-by-Step Instructions
+
+### Step 1: Check Compatibility
+
+Before enabling the compiler, verify your project is compatible:
+
+```bash
+npx react-compiler-healthcheck@latest
+```
+
+This checks if your app follows the Rules of React and identifies potential issues.
+
+### Step 2: Install React Compiler
+
+#### Expo
+
+Use Expo's SDK-specific path:
+
+```bash
+# SDK 54 and later: Babel is auto-configured
+npx expo install babel-plugin-react-compiler@beta
+
+# SDK 53: install runtime too
+npx expo install babel-plugin-react-compiler@beta react-compiler-runtime@beta
+```
+
+Then enable the experiment in app config:
+
+```json
+{
+  "expo": {
+    "experiments": {
+      "reactCompiler": true
+    }
+  }
+}
+```
+
+#### React Native without Expo
+
+```bash
+npm install -D babel-plugin-react-compiler@latest
+```
+
+For React 17 or 18 targets, also install the compiler runtime:
+
+```bash
+npm install react-compiler-runtime@latest
+```
+
+Prefer the setup path documented for the app's exact Expo SDK, React Native, and React versions.
+
+### Step 3: Configure Babel (React Native without Expo)
+
+For non-Expo React Native projects, configure Babel manually and keep the compiler first in the plugin pipeline:
+
+```javascript
+// babel.config.js
+const ReactCompilerConfig = {
+  target: '19', // Use '18' for React Native < 0.78
+};
+
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['module:@react-native/babel-preset'],
+    plugins: [
+      ['babel-plugin-react-compiler', ReactCompilerConfig],
+      // ... other plugins
+    ],
+  };
+};
+```
+
+### Step 4: Set Up ESLint (Recommended)
+
+Use the React Hooks/Compiler lint rules that match the app's React version. For Expo, SDK 55+ includes React Compiler lint rules through `eslint-config-expo`; SDK 54 and earlier need `eslint-plugin-react-compiler`. Fix rule violations before treating a component as compiler-optimized; skipped components are safe but do not get the intended memoization.
+
+### Step 5: Verify Optimizations
+
+Verify with `agent-device react-devtools` before/after render measurements. For release-build verification, connect [`@callstack/inspector`](https://github.com/callstackincubator/inspector#inspector) first so React DevTools can attach. Some visual DevTools versions show compiler memoization badges, but profiler evidence is the stable signal.
+
+## Incremental Adoption
+
+You can incrementally adopt React Compiler using two strategies:
+
+### Strategy 1: Limit to Specific Directories
+
+Configure the Babel plugin to only run on specific files, e.g. `src/path/to/dir` in the following examples:
+
+**Expo** (create `babel.config.js` with `npx expo customize babel.config.js`):
+
+```javascript
+// babel.config.js
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: [
+      [
+        'babel-preset-expo',
+        {
+          'react-compiler': {
+            sources: (filename) => {
+              return filename.includes('src/path/to/dir');
+            },
+          },
+        },
+      ],
+    ],
+  };
+};
+```
+
+**React Native (without Expo)**:
+
+```javascript
+// babel.config.js
+const ReactCompilerConfig = {
+  target: '19',
+  sources: (filename) => {
+    return filename.includes('src/path/to/dir');
+  },
+};
+
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['module:@react-native/babel-preset'],
+    plugins: [['babel-plugin-react-compiler', ReactCompilerConfig]],
+  };
+};
+```
+
+After changing Babel config, restart Metro with a cleared cache.
+
+### Strategy 2: Opt Out Specific Components
+
+Use the `"use no memo"` directive to skip optimization for specific components or files:
+
+```jsx
+function ProblematicComponent() {
+  'use no memo';
+
+  return <Text>Will not be optimized</Text>;
+}
+```
+
+This is useful for temporarily opting out components that cause issues. Fix the underlying problem and remove the directive once resolved.
+
+## Code Examples
+
+### React Compiler Playground
+
+Test transformations at [React Playground](https://playground.react.dev/).
+
+### What Gets Optimized
+
+```jsx
+// Components - auto-memoized
+const Button = ({ onPress, label }) => (
+  <Pressable onPress={onPress}>
+    <Text>{label}</Text>
+  </Pressable>
+);
+
+// Callbacks - auto-cached (no useCallback needed)
+const handlePress = () => {
+  console.log('pressed');
+};
+
+// Expensive computations - auto-cached (no useMemo needed)
+const filtered = items.filter((item) => item.active);
+```
+
+### What Breaks Compilation
+
+```jsx
+// BAD: Mutating props
+const BadComponent = ({ items }) => {
+  items.push('new item'); // Mutation!
+  return <List data={items} />;
+};
+
+// BAD: Mutating during render
+const BadMutation = () => {
+  const [items, setItems] = useState([]);
+  items.push('new'); // Mutation during render!
+  return <List data={items} />;
+};
+
+// BAD: Non-idempotent render
+let counter = 0;
+const BadRender = () => {
+  counter++; // Side effect during render!
+  return <Text>{counter}</Text>;
+};
+```
+
+## Should You Remove Manual Memoization?
+
+Improvements are primarily automatic. You can remove instances of `useCallback`, `useMemo`, and `React.memo` in favor of automatic memoization once the compiler is working correctly in your project.
+
+**Note**: Class components will not be optimized. Migrate to function components for full benefits.
+
+Expo's implementation only runs on application code (not node_modules), and only when bundling for the client (disabled in server rendering).
+
+## Expected Performance Improvements
+
+Expect the largest wins in components that currently rely on manual memoization discipline or have cascading re-renders. Already well-memoized code may show little change; keep the compiler only when profiling or maintenance cost justifies it.
+
+## Common Pitfalls
+
+- **Not fixing ESLint errors first**: When ESLint reports an error, the compiler skips that component—this is safe but means you miss optimization
+- **Expecting it to fix bad patterns**: Compiler optimizes good code, doesn't fix bad code
+- **Forgetting shallow comparison**: Like `memo`, compiler uses shallow comparison for objects/arrays
+- **Not running healthcheck**: Always run `npx react-compiler-healthcheck@latest` before enabling
+
+## Related Skills
+
+- [js-profile-react.md](./js-profile-react.md) - Verify optimization impact
+- [js-atomic-state.md](./js-atomic-state.md) - Alternative for state-related re-renders

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

@@ -0,0 +1,219 @@
+---
+title: Uncontrolled Components
+impact: HIGH
+tags: textinput, forms, controlled, uncontrolled
+---
+
+# Skill: Uncontrolled Components
+
+Fix TextInput synchronization and flickering issues by using the uncontrolled component pattern where React does not need to own every keystroke.
+
+## Quick Pattern
+
+**Before (controlled - may flicker on legacy arch):**
+
+```jsx
+<TextInput value={text} onChangeText={setText} />
+```
+
+**After (uncontrolled - native owns state):**
+
+```jsx
+<TextInput defaultValue={text} onChangeText={setText} />
+```
+
+## When to Use
+
+- TextInput flickers or shows wrong characters during fast typing
+- Text input lags behind user input on low-end devices
+- Using legacy (non-New Architecture) React Native
+- Need maximum input responsiveness
+- React does not need to transform, mask, validate, or own the value on every keystroke
+
+## Prerequisites
+
+- Understanding of React controlled vs uncontrolled components
+- TextInput component in use
+
+## Problem Description
+
+![Controlled TextInput Ping-Pong Communication](images/controlled-textinput-pingpong.png)
+
+The diagram shows what happens when typing "TEST" with a controlled `TextInput`:
+
+1. User types "T" → `onChangeText('T')` fires
+2. React calls `setValue('T')` → native updates to "T"
+3. User types "E" → `onChangeText('TE')` fires
+4. React calls `setValue('TE')` → native updates to "TE"
+5. ...continues for each character
+
+**The problem**: Each character requires a round-trip between native and JavaScript. On legacy architecture, if React state update is slow, native may show intermediate states (flicker).
+
+**New Architecture note:** This issue is largely resolved in New Architecture, but uncontrolled pattern still provides best performance.
+
+Use uncontrolled TextInput primarily as a responsiveness or legacy-architecture escape hatch. Keep controlled inputs when React must transform, mask, validate, or own the value on every keystroke.
+
+## Step-by-Step Instructions
+
+### 1. Identify Controlled TextInput
+
+```jsx
+// Controlled - value prop syncs state to native
+const ControlledInput = () => {
+  const [value, setValue] = useState('');
+  
+  return (
+    <TextInput
+      value={value}           // This causes sync issues
+      onChangeText={setValue}
+    />
+  );
+};
+```
+
+### 2. Convert to Uncontrolled
+
+Remove the `value` prop to make it uncontrolled:
+
+```jsx
+// Uncontrolled - native owns the state
+const UncontrolledInput = () => {
+  const [value, setValue] = useState('');
+  
+  return (
+    <TextInput
+      defaultValue={value}     // Only sets initial value
+      onChangeText={setValue}  // Still updates React state
+    />
+  );
+};
+```
+
+### 3. Use Ref for Programmatic Control
+
+If you need to read/set value programmatically:
+
+```jsx
+const UncontrolledWithRef = () => {
+  const inputRef = useRef(null);
+  
+  const clearInput = () => {
+    inputRef.current?.clear();
+  };
+  
+  const getValue = () => {
+    // Use onChangeText to track value, or native methods
+  };
+  
+  return (
+    <TextInput
+      ref={inputRef}
+      defaultValue=""
+      onChangeText={(text) => console.log('Current:', text)}
+    />
+  );
+};
+```
+
+## Code Examples
+
+### Full Migration Example
+
+**Before (Controlled):**
+
+```jsx
+const SearchInput = () => {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState([]);
+  
+  const handleChange = (text) => {
+    setQuery(text);
+    fetchResults(text).then(setResults);
+  };
+  
+  return (
+    <View>
+      <TextInput
+        value={query}              // Remove this
+        onChangeText={handleChange}
+        placeholder="Search..."
+      />
+      <ResultsList data={results} />
+    </View>
+  );
+};
+```
+
+**After (Uncontrolled):**
+
+```jsx
+const SearchInput = () => {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState([]);
+  
+  const handleChange = (text) => {
+    setQuery(text);
+    fetchResults(text).then(setResults);
+  };
+  
+  return (
+    <View>
+      <TextInput
+        defaultValue=""           // Initial value only
+        onChangeText={handleChange}
+        placeholder="Search..."
+      />
+      <ResultsList data={results} />
+    </View>
+  );
+};
+```
+
+### When You Need Value Control
+
+For input masking or validation that modifies input:
+
+```jsx
+// Option 1: Accept the controlled behavior (may flicker)
+const MaskedInput = () => {
+  const [value, setValue] = useState('');
+  
+  const handleChange = (text) => {
+    // Phone mask: (123) 456-7890
+    const masked = maskPhone(text);
+    setValue(masked);
+  };
+  
+  return (
+    <TextInput
+      value={value}  // Necessary for masking
+      onChangeText={handleChange}
+    />
+  );
+};
+
+// Option 2: Use a native masked input library
+// react-native-masked-text handles this natively
+```
+
+## Decision Matrix
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Simple text input | Uncontrolled |
+| Search/filter input | Uncontrolled |
+| Form with validation on submit | Uncontrolled |
+| Input masking (phone, credit card) | Controlled or native library |
+| Character-by-character validation | Controlled |
+| New Architecture app | Either works well |
+
+## Common Pitfalls
+
+- **Forgetting `defaultValue`**: Without it, input starts empty
+- **Trying to clear with state**: Use `ref.current.clear()` instead
+- **Mixing patterns**: Don't use both `value` and `defaultValue`
+
+## Related Skills
+
+- [js-profile-react.md](./js-profile-react.md) - Profile input performance
+- [js-concurrent-react.md](./js-concurrent-react.md) - Defer expensive search operations

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/native-android-16kb-alignment.md

@@ -0,0 +1,114 @@
+---
+title: Android 16 KB Page Size Alignment
+impact: CRITICAL
+tags: android, native, 16kb, alignment, page-size, google-play, third-party
+---
+
+# Android 16 KB page size alignment
+
+---
+
+## Quick Reference
+
+| Item                   | Details                                              |
+| ---------------------- | ---------------------------------------------------- |
+| Google Play requirement | Apps and updates targeting Android 15+ must support 16 KB page sizes on 64-bit devices |
+| React Native support   | RN 0.79+ includes aligned RN-provided native binaries; still verify third-party `.so` files |
+| What to check          | Third-party native libraries (`.so` files)           |
+| Official documentation | [developer.android.com/guide/practices/page-sizes][] |
+
+[developer.android.com/guide/practices/page-sizes]: https://developer.android.com/guide/practices/page-sizes
+
+---
+
+## Quick Command
+
+Verify generated APK alignment using Android's official `zipalign` tool:
+
+```bash
+zipalign -c -P 16 -v 4 app-release.apk
+```
+
+If any 64-bit libraries (`arm64-v8a`, `x86_64`) show misalignment, they need updating.
+
+For deeper ELF-level inspection, use Android's [check_elf_alignment.sh][] script.
+
+[check_elf_alignment.sh]: https://cs.android.com/android/platform/superproject/main/+/main:system/extras/tools/check_elf_alignment.sh
+
+---
+
+## When to Check
+
+React Native 0.79+ builds core binaries with correct alignment. However, **third-party
+native libraries** may still be misaligned. Check alignment when:
+
+* Adding or updating SDKs with native code
+* Preparing a release for Google Play
+* Investigating crashes on Android 15+ devices with 16 KB page size
+
+---
+
+## CI Integration
+
+Add alignment checks to your release pipeline after producing release APKs. If you ship AABs, generate device APKs with your normal release tooling or `bundletool`, then run `zipalign` on those APKs:
+
+```bash
+zipalign -c -P 16 -v 4 app-release.apk 2>&1 | tee alignment.log
+if grep -q "Verification FAILED" alignment.log; then exit 1; fi
+```
+
+## Step-by-Step
+
+1. Build your release artifact
+2. Generate or locate the release APK(s)
+3. Run `zipalign` verification (see Quick Command)
+4. If misaligned libraries are found, trace them to source packages (see below)
+5. Update, replace, or remove the affected dependencies
+
+For runtime testing, use the [16KB Android Emulator image][] or enable
+"Boot with 16KB page size" on Pixel 8/8a/9 devices.
+
+[16KB Android Emulator image]: https://developer.android.com/guide/practices/page-sizes#set-up-the-android-emulator-with-a-16-kb-based-system-image
+
+---
+
+## Tracing Misaligned Libraries
+
+When `zipalign` reports a misaligned library like `libfoo.so`, find its source package:
+
+```bash
+# Find the .so file in node_modules
+find node_modules -name "libfoo.so" 2>/dev/null
+
+# Or search gradle files for references
+grep -r "foo" node_modules/*/android --include="*.gradle" 2>/dev/null
+```
+
+Once identified, update the dependency or contact the vendor for a 16KB-compatible build.
+
+---
+
+## Common Pitfalls
+
+* Waiting for Play Store rejection instead of checking in CI
+* Assuming a React Native upgrade rebuilds third-party native binaries
+* Only checking 32-bit ABIs (`armeabi-v7a`, `x86`) — these are not affected
+* Using `zipalign` without the `-P 16` flag (checks 4 KB, not 16 KB)
+* Validating only debug builds
+
+---
+
+## Fixing Alignment Issues
+
+Alignment issues require **rebuilding** the native library with a compatible toolchain.
+Repackaging alone does not fix them.
+
+See [official remediation steps][] for detailed guidance.
+
+[official remediation steps]: https://developer.android.com/guide/practices/page-sizes#build-app-16kb
+
+---
+
+## Related Skills
+
+* [native-profiling.md](./native-profiling.md) — Native debugging tools