@ranimontagna/agent-toolkit 0.3.5 → 0.3.7

package/skills/frontend/react-native/react-native-unistyles-v3/references/common-issues.md

@@ -6,18 +6,18 @@ Curated from 150+ GitHub issues. Organized by category with symptoms, causes, an
 
 ## 1. Setup & Initialization
 
-### "Unistyles was loaded but not configured" after hot reload
+### "Unistyles was loaded, but it's not configured" after hot reload
 
 **Symptoms:** Error appears after fast refresh / hot reload, not on cold start.
 **Cause:** `StyleSheet.configure()` runs in a module scope that doesn't re-execute on HMR.
 **Solution:** Ensure `StyleSheet.configure()` is imported in your entry point file. For Expo Router, follow the [Expo Router integration steps](setup-guide.md#expo-router-integration).
 **Ref:** [#1098](https://github.com/jpudysz/react-native-unistyles/issues/1098)
 
-### "Unistyles not initialized correctly"
+### "Unistyles was loaded, but it's not configured. Did you forget to call StyleSheet.configure?"
 
 **Symptoms:** Crash on app start.
 **Cause:** `StyleSheet.create()` is called before `StyleSheet.configure()`.
-**Solution:** Move `StyleSheet.configure()` to your app's entry point, before any component imports that use `StyleSheet.create`.
+**Solution:** Move `StyleSheet.configure()` to your app's entry point, before any component imports that use `StyleSheet.create`. With no themes/breakpoints, call `StyleSheet.configure({})`.
 **Ref:** [#1010](https://github.com/jpudysz/react-native-unistyles/issues/1010)
 
 ### StyleSheet.configure timing with Expo Router
@@ -26,17 +26,17 @@ Curated from 150+ GitHub issues. Organized by category with symptoms, causes, an
 **Cause:** Expo Router resolves routes before your config runs.
 **Solution:**
 1. Set `"main": "index.ts"` in package.json
-2. Create `index.ts` with:
+2. Create `index.ts` (or `index.js`) with:
    ```ts
-   import './unistyles'        // configure first
    import 'expo-router/entry'
+   import './unistyles'        // your StyleSheet.configure() file
    ```
 3. For static rendering, also import config in `app/+html.tsx`
 
 ### "Property value expected type of number but got null" for hasAdaptiveThemes
 
 **Symptoms:** Runtime error mentioning `hasAdaptiveThemes` property.
-**Cause:** `adaptiveThemes` set to `true` without both `light` and `dark` themes registered.
+**Cause:** `adaptiveThemes` set to `true` without both `light` and `dark` themes registered (current versions throw "You're trying to enable adaptiveThemes, but you didn't register both 'light' and 'dark' themes").
 **Solution:** Ensure themes object has keys named exactly `light` and `dark`:
 ```tsx
 StyleSheet.configure({
@@ -46,14 +46,23 @@ StyleSheet.configure({
 ```
 **Ref:** [#1040](https://github.com/jpudysz/react-native-unistyles/issues/1040)
 
+### setTheme throws / initialTheme + adaptiveThemes error
+
+**Cause:** `initialTheme` and `adaptiveThemes: true` are mutually exclusive, and `UnistylesRuntime.setTheme()` throws while adaptive themes are enabled.
+**Solution:** Use one of the two settings. To switch manually at runtime, call `UnistylesRuntime.setAdaptiveThemes(false)` before `setTheme()`.
+
+### Adaptive themes don't follow the OS
+
+**Solution:** Check that Expo `app.json` has `userInterfaceStyle: "automatic"` (bare: `Info.plist` doesn't hardcode `UIUserInterfaceStyle`), and that you haven't forced a scheme with `Appearance.setColorScheme('light' | 'dark')` (use `'unspecified'` to reset). Requires iOS 15+ / Android 10+.
+
 ---
 
 ## 2. Style Spreading (Most Common Issue)
 
-### "Style is not bound!" error
+### "Style is not bound!" error / "we detected style object with 2 unistyles styles" warning
 
-**Symptoms:** Runtime error "Style is not bound!" or styles not applying.
-**Cause:** Spreading Unistyles styles with `{...styles.x}`. v3 styles are C++ proxy objects — spreading breaks the native binding.
+**Symptoms:** Runtime error "Unistyles: Style is not bound!", a `__DEV__` warning about merged Unistyles styles, or styles that stop updating.
+**Cause:** Spreading/merging Unistyles styles with `{...styles.x}` (or altering the hidden `unistyles_*` key). Each style carries C++ state — merging two into one object keeps only the first binding.
 **Solution:** ALWAYS use array syntax:
 ```tsx
 // WRONG
@@ -85,7 +94,7 @@ const animStyle = useAnimatedStyle(() => ({ ...styles.box }))
 ### Re-exporting StyleSheet from barrel files
 
 **Symptoms:** Styles not reactive; theme changes have no effect.
-**Cause:** The Babel plugin detects `StyleSheet.create` by checking the import source is `react-native-unistyles`. Re-exporting through a barrel file (e.g., `export { StyleSheet } from 'react-native-unistyles'` in `utils/index.ts`) breaks detection.
+**Cause:** Outside `root`, the Babel plugin recognizes `StyleSheet.create` only when `StyleSheet` is imported from `react-native-unistyles` (or the file matches `autoProcessImports`). Re-exporting through a barrel file (e.g., `export { StyleSheet } from 'react-native-unistyles'` in `utils/index.ts`) breaks detection there. (Inside `root` a heuristic still catches stylesheet-shaped `.create()` calls, but don't rely on it.)
 **Solution:** Always import directly:
 ```tsx
 // WRONG
@@ -98,14 +107,14 @@ import { StyleSheet } from 'react-native-unistyles'
 ### Plugin interferes with other .create() calls
 
 **Symptoms:** Other libraries' `.create()` calls break (e.g., Zustand, custom factories).
-**Cause:** The Babel plugin processes any `StyleSheet.create()` it finds.
-**Solution:** The plugin only processes `StyleSheet.create()` when `StyleSheet` is imported from `react-native-unistyles`. If you have a different `StyleSheet` variable, rename it to avoid collision.
+**Cause:** In processed files (under `root`, matching `autoProcessImports`, or importing `react-native-unistyles`), the plugin treats any `something.create(arg)` that *looks like* a stylesheet as one: a single object argument whose values are objects, or an arrow function with ≤ 2 params returning a non-empty object.
+**Solution:** Change the call shape (e.g. pass an extra argument or a non-arrow factory), or move such factories to a file the plugin doesn't process. Use `debug: true` to see what the plugin detected.
 **Ref:** [#993](https://github.com/jpudysz/react-native-unistyles/issues/993)
 
 ### Wrong root directory
 
 **Symptoms:** Styles not reactive; Babel plugin appears to do nothing.
-**Cause:** The `root` option in Babel config resolves to the project root or an incorrect directory.
+**Cause:** The `root` option is missing (the plugin throws), resolves to the project root (throws — it would include `node_modules`), or points to the wrong directory. It's resolved relative to Babel's `root` (project directory by default).
 **Solution:** `root` must point to your **source code directory**, not the project root:
 ```js
 // WRONG — root resolves to project root
@@ -119,13 +128,14 @@ import { StyleSheet } from 'react-native-unistyles'
 
 ### Files outside root not processed
 
-**Symptoms:** Shared package styles not reactive.
-**Cause:** Only files inside `root` are processed by default.
-**Solution:** Add `autoProcessPaths` for additional directories:
+**Symptoms:** Shared package / library views not reactive.
+**Cause:** Files outside `root` are only processed if they import `react-native-unistyles` (and contain a stylesheet), match `autoProcessImports`, or match `autoProcessPaths`. `node_modules` is ignored unless listed in `autoProcessPaths`.
+**Solution:**
 ```js
 ['react-native-unistyles/plugin', {
   root: 'src',
-  autoProcessPaths: ['../packages/shared/src']
+  autoProcessImports: ['@my-org/styles'],        // your monorepo files importing this are processed
+  autoProcessPaths: ['external-library/components']  // substring of the absolute path, NOT '../relative'
 }]
 ```
 
@@ -133,6 +143,16 @@ import { StyleSheet } from 'react-native-unistyles'
 
 ## 4. Theme Updates Not Propagating
 
+### Frozen / hidden screens show stale styles
+
+**Symptoms:** After changing the theme (or rotating) while a screen is frozen (`freezeOnBlur`, react-navigation `inactiveBehavior` / `<Activity />`, `Suspense` fallback), the screen returns with old styles, or dynamic styles look wrong.
+**Cause:** Bugs in re-linking frozen views, fixed in **3.4.0**; also non-serializable dynamic function arguments (functions are dropped, `Date`/class instances become `{}` when the function is re-run natively).
+**Solution:** Upgrade to 3.4.0+, and pass only serializable values to dynamic functions. `useUnistyles`/`withUnistyles` components update only after the screen unfreezes (React blocks frozen trees).
+
+### Component not updating at all
+
+Check, in order: the file is processed by the Babel plugin (`debug: true`); the view is a React Native view (otherwise use `withUnistyles`); styles aren't spread; `contentContainerStyle` is passed through `withUnistyles`.
+
 ### Nested Text components + Reanimated conflict
 
 **Symptoms:** Nested `<Text>` components don't update color when theme changes while using Reanimated.
@@ -202,7 +222,7 @@ const UniButton = withUnistyles(Button, (theme) => ({
 ### Keyboard inset lag with react-native-keyboard-controller
 
 **Symptoms:** `rt.insets.ime` lags behind actual keyboard position.
-**Cause:** Conflict between Unistyles' IME tracking and react-native-keyboard-controller.
+**Cause:** Conflict between Unistyles' IME tracking and react-native-keyboard-controller. (Note: on Android, `ime` is the keyboard height minus the bottom inset and is only animated on Android 11+; Unistyles also guards `rt.insets.bottom` from being polluted by keyboard libraries.)
 **Solution:** Use only one keyboard tracking solution. Prefer `rt.insets.ime` and remove `react-native-keyboard-controller`, or vice versa.
 **Ref:** [#1065](https://github.com/jpudysz/react-native-unistyles/issues/1065)
 
@@ -234,15 +254,12 @@ npx react-native run-android
 ### SSR hydration mismatches
 
 **Symptoms:** React hydration warnings on page load with SSR.
-**Cause:** Server-rendered styles don't match client-side computed styles.
-**Solution:** Use the SSR utilities:
-```tsx
-// Server: inject styles
-const styles = useServerUnistyles()  // or getServerUnistyles()
-
-// Client: hydrate
-hydrateServerUnistyles()
-```
+**Cause:** Server-rendered styles don't match client-side state, or (without adaptive themes) Unistyles adds the theme class to `<html>`.
+**Solution:** Use the SSR utilities from `react-native-unistyles/server` (see [styling-patterns.md](styling-patterns.md#ssr-with-nextjs)):
+- App Router: `useServerUnistyles()` inside a `'use client'` component with `useServerInsertedHTML` (hydrates automatically on the client)
+- Pages Router: `getServerUnistyles()` + `resetServerUnistyles()` in `_document` `getInitialProps`, `hydrateServerUnistyles()` in a `useEffect` in `_app`
+- Add `suppressHydrationWarning` (or the theme class) to `<html>`
+- Styles leaking between requests (Pages Router) → you forgot `resetServerUnistyles()`
 
 ### Safari 16.3 and below not supported
 
@@ -255,7 +272,7 @@ hydrateServerUnistyles()
 
 **Symptoms:** Animated.View doesn't receive Unistyles styles on web platform.
 **Cause:** Reanimated's web implementation may not forward the style processing correctly.
-**Solution:** Use `getWebProps` or apply styles differently on web.
+**Solution:** Use `getWebProps` from `react-native-unistyles/web` (spread `{ className, ref }`) or apply styles differently on web.
 **Ref:** [#1014](https://github.com/jpudysz/react-native-unistyles/issues/1014)
 
 ### Gap polyfill incorrect margins on SmartTV
@@ -335,9 +352,9 @@ plugins: [
 
 ### useUnistyles causes re-renders
 
-**Symptoms:** Excessive re-renders, especially on theme/orientation changes.
-**Cause:** `useUnistyles()` subscribes to theme and runtime changes, triggering re-renders.
-**Solution:** Prefer `StyleSheet.create(theme => ...)` which uses zero-re-render C++ updates. Reserve `useUnistyles()` for cases where you need theme/runtime in JS logic.
+**Symptoms:** Excessive re-renders, especially on theme/orientation/keyboard changes.
+**Cause:** `useUnistyles()` re-renders the whole component when any value you **read** changes (subscriptions are created on property access, not destructuring). Reading `rt.insets.ime` re-renders on every keyboard animation frame.
+**Solution:** Prefer `StyleSheet.create(theme => ...)` which uses zero-re-render C++ updates. Reserve `useUnistyles()` for cases where you need theme/runtime in JS logic, and read only what you need.
 
 ### Variant memory in long lists
 

package/skills/frontend/react-native/react-native-unistyles-v3/references/setup-guide.md

@@ -3,11 +3,15 @@
 ## Installation
 
 ```bash
-npm install react-native-unistyles react-native-nitro-modules
+npm install react-native-unistyles react-native-nitro-modules@0.37.1
 # or
-yarn add react-native-unistyles react-native-nitro-modules
+yarn add react-native-unistyles react-native-nitro-modules@0.37.1
 ```
 
+Always pin an exact `react-native-nitro-modules` version that matches the compatibility table in the Unistyles README (Unistyles 3.4.0+ requires `>= 0.37.1`).
+
+On Android, `react-native-edge-to-edge` is optional (since v3.1.0). Set `edgeToEdgeEnabled=true` in `android/gradle.properties` (Expo SDK 54+ does it automatically).
+
 Then rebuild your native project:
 ```bash
 npx pod-install  # iOS
@@ -34,11 +38,13 @@ module.exports = {
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `root` | `string` | **Required.** Path to your source code root (relative to project root). Only files in this directory are processed. Must NOT resolve to the project root itself. |
-| `autoProcessPaths` | `string[]` | Additional directories outside `root` to process (e.g., shared packages in a monorepo). |
-| `autoProcessImports` | `string[]` | Additional package names whose imports trigger processing (e.g., `['@myorg/ui']`). |
-| `autoRemapImports` | `Record<string, Record<string, string>>` | Map exotic component imports to Unistyles component factories. |
-| `debug` | `boolean` | Enable debug logging to see which files are processed. Default: `false`. |
+| `root` | `string` | **Required** (the plugin throws without it). Folder resolved relative to Babel's `root` (your project directory by default). **Every file under it is processed**, no matter what it imports. Must NOT resolve to the project root itself (`'.'`), as that would include `node_modules`. |
+| `autoProcessImports` | `string[]` | Any file (outside `node_modules`) that imports one of these sources is processed like a `root` file (e.g., `['@my-org/styles']`). Use it for monorepo packages outside `root`. |
+| `autoProcessPaths` | `string[]` | Path fragments (matched as a substring of the absolute file path, e.g. `'external-library/components'`) whose `react-native` imports are replaced with Unistyles ref-borrowing factories. Meant for 3rd party code in `node_modules`. `react-native-reanimated/src/component` and `react-native-reanimated/lib/module/component` are always included; your paths are added. |
+| `autoRemapImports` | `Array<{ path: string, imports: Array<{ isDefault: boolean, name?: string, path: string, mapTo: string }> }>` | Advanced: remap non-standard imports (e.g. `react-native/Libraries/...`) in a `node_modules` library to Unistyles factories. |
+| `debug` | `boolean` | Log detected style dependencies per file/style. Default: `false`. |
+
+The plugin also throws on string refs (`ref="myView"`). Components swapped for ref-borrowing factories: `ActivityIndicator`, `View`, `Text`, `Image`, `ImageBackground`, `KeyboardAvoidingView`, `Pressable`, `ScrollView`, `FlatList`, `SectionList`, `Switch`, `TextInput`, `RefreshControl`, `TouchableHighlight`, `TouchableOpacity`, `VirtualizedList`, `Animated`, `SafeAreaView` (`Modal` and `TouchableWithoutFeedback` are not supported).
 
 ### Example: Monorepo with shared packages
 
@@ -48,13 +54,39 @@ module.exports = {
   plugins: [
     ['react-native-unistyles/plugin', {
       root: 'src',
-      autoProcessPaths: ['../shared-ui/src'],
-      autoProcessImports: ['@myorg/shared-ui']
+      // files outside `root` that import these sources are processed too
+      autoProcessImports: ['@my-org/styles', '@my-org/ui'],
+      // 3rd party components in node_modules built on react-native views
+      autoProcessPaths: ['external-library/components']
     }]
   ]
 }
 ```
 
+Note: `autoProcessPaths` is a substring match against the absolute file path — relative paths like `'../shared-ui/src'` never match.
+
+### Re.Pack
+
+With Re.Pack, don't add the plugin to `babel.config.js`; use the Rspack plugin instead (it runs the same Babel plugin through a loader):
+
+```js
+// rspack.config.mjs
+import * as Repack from '@callstack/repack'
+import { RepackUnistylePlugin } from 'react-native-unistyles/repack-plugin'
+
+export default {
+  plugins: [
+    new Repack.RepackPlugin(),
+    new RepackUnistylePlugin({
+      unistylesPluginOptions: { root: 'src' },  // same options as the Babel plugin, `root` required
+      // ruleExcludePaths: [...BASE_REPACK_EXCLUDE_PATHS, /my-lib/]  // optional RegExp[]
+    })
+  ]
+}
+```
+
+The loader needs `@babel/plugin-syntax-typescript` and `babel-plugin-syntax-hermes-parser` installed in your project.
+
 ### React Compiler ordering
 
 If using React Compiler, the Unistyles plugin **MUST come BEFORE** React Compiler:
@@ -100,10 +132,12 @@ StyleSheet.configure({
 
 | Setting | Type | Description |
 |---------|------|-------------|
-| `initialTheme` | `string \| () => string` | Theme to use on app start. Can be a function for lazy evaluation (e.g., reading from storage). Mutually exclusive with `adaptiveThemes`. |
-| `adaptiveThemes` | `boolean` | Auto-switch between `light` and `dark` themes based on OS color scheme. Requires themes named exactly `light` and `dark`. Mutually exclusive with `initialTheme`. |
-| `CSSVars` | `boolean` | Use CSS custom properties for theme values on web. Enables instant theme switching without style recalculation. Default: `false`. |
-| `nativeBreakpointsMode` | `'pixels' \| 'points'` | Whether breakpoint values are in physical pixels or logical points. Default: device-dependent. |
+| `initialTheme` | `string \| () => string` | Theme to use on app start. Can be a synchronous function (e.g., reading from storage). Mutually exclusive with `adaptiveThemes: true` (throws). With 2+ themes and no `adaptiveThemes`, set it — otherwise no theme is selected. A single registered theme is selected automatically. |
+| `adaptiveThemes` | `boolean` | Auto-switch between `light` and `dark` themes based on OS color scheme. Requires themes named exactly `light` and `dark`. While enabled, `UnistylesRuntime.setTheme()` throws — call `setAdaptiveThemes(false)` first. |
+| `CSSVars` | `boolean` | Web only. Converts theme strings to CSS variables, so theme switching only swaps the `html` class (or relies on `prefers-color-scheme` with adaptive themes). Default: `true`. Disable when themes differ in non-string values (numbers, functions). |
+| `nativeBreakpointsMode` | `'pixels' \| 'points'` | Default `'pixels'`: breakpoints are compared against `UnistylesRuntime.screen` (points on iOS, dp on Android). `'points'` additionally divides the screen size by `pixelRatio`. |
+
+Any other key in `settings` (or in the config object) throws an error.
 
 ### Minimal configuration (no themes, no breakpoints)
 
@@ -120,7 +154,7 @@ Augment the Unistyles module to get type-safe themes and breakpoints:
 ```tsx
 // unistyles.ts (or wherever you call StyleSheet.configure)
 import { StyleSheet } from 'react-native-unistyles'
-import { lightTheme } from './themes'
+import { lightTheme, darkTheme } from './themes'
 import { breakpoints } from './breakpoints'
 
 type AppThemes = {
@@ -160,11 +194,15 @@ Expo Router resolves routes before Unistyles can initialize. Extra steps are nee
 ### 2. Create index.ts
 
 ```ts
-// index.ts — import config BEFORE the router
-import './unistyles'        // your StyleSheet.configure() file
+// index.ts (or index.js)
 import 'expo-router/entry'
+import './unistyles'        // your StyleSheet.configure() file
 ```
 
+This is the order used by the official docs and the repo's Expo example app. The key point is that the config file is imported from the custom entry, not from a route file.
+
+Expo Router screens can be frozen when unfocused (`freezeOnBlur`) — Unistyles keeps their bindings and applies changes when they become visible again (fixes for stale styles landed in 3.4.0).
+
 ### 3. For static rendering (Expo SDK 52+)
 
 Import your Unistyles config in `app/+html.tsx`:
@@ -193,25 +231,29 @@ export default function Root({ children }: PropsWithChildren) {
 
 ## Testing / Mocks Setup
 
-The Babel plugin auto-disables in test environments (`NODE_ENV=test`). Import the mocks file in your Jest setup:
-
-```js
-// jest.setup.js
-require('react-native-unistyles/mocks')
-require('./unistyles')  // your StyleSheet.configure() call — provides theme data to mocks
-```
+The Babel plugin is a no-op when `NODE_ENV === 'test'` (Jest sets this by default). Add the mocks to Jest `setupFiles`, followed by your config file:
 
-```js
-// jest.config.js
-module.exports = {
-  setupFiles: ['./jest.setup.js'],
+```json
+// package.json
+{
+  "jest": {
+    "preset": "jest-expo",
+    "setupFiles": [
+      "react-native-unistyles/mocks",
+      "./unistyles.ts"
+    ]
+  }
 }
 ```
 
-The mock provides:
-- `StyleSheet.create` that resolves theme functions using the first registered theme
-- `StyleSheet.configure` that stores themes/breakpoints
-- `useUnistyles()` returning `{ theme, rt }` with mock runtime values
-- `withUnistyles` that applies mapper function
-- `mq`, `Display`, `Hide`, `ScopedTheme` as no-ops
-- `useAnimatedTheme` and `useAnimatedVariantColor` mocks (from `react-native-unistyles/reanimated`)
+The config file must come **after** the mocks (they stub `StyleSheet.configure`).
+
+Mock behavior and limitations:
+- `StyleSheet.create`, `useUnistyles` and `withUnistyles` always resolve with the **first** registered theme (`initialTheme` / `adaptiveThemes` are ignored)
+- runtime values (`screen`, `insets`, `statusBar`, `navigationBar`) are `0`
+- `variants` / `compoundVariants` are stripped and `useVariants` does nothing
+- `Display`, `Hide` and `ScopedTheme` render nothing (`null`)
+- `useAnimatedTheme` / `useAnimatedVariantColor` (from `react-native-unistyles/reanimated`) are mocked
+- `createUnistylesElement`, `UnistyleDependency` and the SSR helpers are **not** mocked (`undefined`)
+
+Don't unit-test how Unistyles resolves styles — use E2E tools (Maestro, Playwright) for that.