@bcelep/capint 0.4.2 → 0.6.5

package/skills/react-native-best-practices/references/js-react-compiler.md

@@ -0,0 +1,368 @@
+---
+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
+
+- React 17+ (React 19 recommended for best compatibility)
+- Babel-based build system
+- Code follows [Rules of React](https://react.dev/reference/rules)
+
+## 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 Projects
+
+**SDK 54 and later** (simplified setup):
+
+```bash
+npx expo install babel-plugin-react-compiler
+```
+
+**SDK 52-53**:
+
+```bash
+npx expo install babel-plugin-react-compiler@beta react-compiler-runtime@beta
+```
+
+Then enable in your app config:
+
+```json
+// app.json
+{
+  "expo": {
+    "experiments": {
+      "reactCompiler": true
+    }
+  }
+}
+```
+
+#### React Native (without Expo)
+
+```bash
+npm install -D babel-plugin-react-compiler@latest
+```
+
+For React Native < 0.78 (React < 19), also install the runtime:
+
+```bash
+npm install react-compiler-runtime@beta
+```
+
+### Step 3: Configure Babel (React Native without Expo)
+
+For non-Expo React Native projects, configure Babel manually:
+
+```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], // Must run first!
+      // ... other plugins
+    ],
+  };
+};
+```
+
+> **Important**: React Compiler must run **first** in your Babel plugin pipeline. The compiler needs the original source information for proper analysis.
+
+### Step 4: Set Up ESLint (Recommended)
+
+The ESLint plugin helps identify code that can't be optimized and enforces the Rules of React.
+
+#### Expo Projects
+
+```bash
+npx expo lint  # Ensures ESLint is set up
+npx expo install eslint-plugin-react-compiler -- -D
+```
+
+Configure ESLint:
+
+```javascript
+// .eslintrc.js
+const { defineConfig } = require('eslint/config');
+const expoConfig = require('eslint-config-expo/flat');
+const reactCompiler = require('eslint-plugin-react-compiler');
+
+module.exports = defineConfig([
+  expoConfig,
+  reactCompiler.configs.recommended,
+  {
+    ignores: ['dist/*'],
+  },
+]);
+```
+
+#### React Native (without Expo)
+
+```bash
+npm install -D eslint-plugin-react-hooks@latest
+```
+
+The compiler rules are available in the `recommended-latest` preset. Follow the [eslint-plugin-react-hooks installation instructions](https://github.com/facebook/react/tree/main/packages/eslint-plugin-react-hooks).
+
+### Step 5: Verify Optimizations
+
+Open React DevTools. Optimized components show a `Memo ✨` badge.
+
+You can also verify by checking build output—compiled code includes automatic memoization:
+
+```javascript
+import { c as _c } from 'react/compiler-runtime';
+
+export default function MyApp() {
+  const $ = _c(1);
+  let t0;
+  if ($[0] === Symbol.for('react.memo_cache_sentinel')) {
+    t0 = <div>Hello World</div>;
+    $[0] = t0;
+  } else {
+    t0 = $[0];
+  }
+  return t0;
+}
+```
+
+**Note**: React Native 0.76+ includes DevTools with Memo badge support by default. For older versions or third-party debuggers with version mismatches, you may need to override `react-devtools-core` in `package.json`.
+
+## 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.js`, restart Metro with cache cleared:
+
+```bash
+# Expo
+npx expo start --clear
+
+# React Native CLI
+npx react-native start --reset-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.
+
+## How It Works
+
+The compiler transforms your code to automatically cache values:
+
+**Before (your code):**
+
+```jsx
+export default function MyApp() {
+  const [value, setValue] = useState('');
+  return (
+    <TextInput onChangeText={() => setValue(value)}>Hello World</TextInput>
+  );
+}
+```
+
+**After (compiled output):**
+
+```jsx
+import { c as _c } from 'react/compiler-runtime';
+
+export default function MyApp() {
+  const $ = _c(2); // Cache with 2 slots
+  const [value, setValue] = useState('');
+
+  let t0;
+  if ($[0] !== value) {
+    t0 = (
+      <TextInput onChangeText={() => setValue(value)}>Hello World</TextInput>
+    );
+    $[0] = value;
+    $[1] = t0;
+  } else {
+    t0 = $[1]; // Return cached JSX
+  }
+  return t0;
+}
+```
+
+## 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
+
+Testing on Expensify app showed:
+
+- **4.3% improvement** in Chat Finder TTI
+- Significant reduction in cascading re-renders
+- Most impact on apps without existing manual optimization
+
+Already heavily optimized apps may see marginal gains.
+
+## 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/skills/react-native-best-practices/references/js-uncontrolled-components.md

@@ -0,0 +1,216 @@
+---
+title: Uncontrolled Components
+impact: HIGH
+tags: textinput, forms, controlled, uncontrolled
+---
+
+# Skill: Uncontrolled Components
+
+Fix TextInput synchronization and flickering issues by using uncontrolled component pattern.
+
+## 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
+
+## 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.
+
+## 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/skills/react-native-best-practices/references/native-android-16kb-alignment.md

@@ -0,0 +1,113 @@
+---
+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 deadline   | November 1, 2025 for apps targeting Android 15+      |
+| React Native support   | Built-in since React Native 0.79                     |
+| 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 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 check to your release pipeline to catch issues before submission, example:
+
+```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 APK or AAB
+2. Run `zipalign` verification (see Quick Command)
+3. If misaligned libraries are found, trace them to source packages (see below)
+4. 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