@ranimontagna/agent-toolkit 0.3.5 → 0.3.7

package/skills/frontend/react-native/react-native-unistyles-v3/NOTICE.md

@@ -3,7 +3,7 @@
 This skill is copied from Jacek Pudysz's public `jpudysz/react-native-unistyles` repository.
 
 - Source: https://github.com/jpudysz/react-native-unistyles/tree/main/skills/react-native-unistyles-v3
-- Imported from commit: `8b5e9fd281a81bdfd87d4fe9e6a0b042c84c5c83`
+- Imported from commit: `eef411b37335010860ed80f69aa674572b90e1bf`
 - Upstream skill name: `react-native-unistyles-v3`
 - License: MIT, as declared by the upstream README and `packages/unistyles/package.json`
 - Copyright: Copyright (c) 2026 Jacek Pudysz

package/skills/frontend/react-native/react-native-unistyles-v3/SKILL.md

@@ -12,12 +12,13 @@ You are assisting with React Native Unistyles v3 styling. v3 is a zero-re-render
 
 ## Prerequisites
 
-- React Native 0.78+ with **New Architecture mandatory** (default from RN 0.83+)
+- React Native 0.81+ with **New Architecture mandatory** (enabled by default since RN 0.76, the only architecture since RN 0.82)
 - React 19+ (enforced at runtime)
-- `react-native-nitro-modules` (native bridge dependency)
-- `react-native-edge-to-edge` (required for Android edge-to-edge insets)
-- Expo SDK 53+ (if using Expo; **not compatible with Expo Go** — requires dev client or prebuild)
-- Xcode 16+ (iOS)
+- `react-native-nitro-modules` (native bridge dependency; pin an exact version — Unistyles 3.4.0+ needs `>= 0.37.1`)
+- iOS 15.1+, Android 7+
+- `react-native-edge-to-edge` is optional since v3.1.0 (set `edgeToEdgeEnabled=true` in `android/gradle.properties` instead; Expo SDK 54+ enables it automatically)
+- Expo SDK 54+ (if using Expo; **not compatible with Expo Go** — requires dev client or prebuild)
+- Xcode 16.4+ (iOS, required by Nitro Modules)
 
 ## Workflow
 
@@ -62,8 +63,8 @@ StyleSheet.configure({
   settings: {
     initialTheme: 'light',       // or: () => storage.getString('theme') ?? 'light'
     // adaptiveThemes: true,     // auto-switch light/dark based on OS (mutually exclusive with initialTheme)
-    // CSSVars: true,            // use CSS custom properties on web
-    // nativeBreakpointsMode: 'pixels' | 'points'
+    // CSSVars: true,            // web: themes as CSS variables (default: true)
+    // nativeBreakpointsMode: 'pixels' | 'points'  // default 'pixels' = compare against rt.screen (pt/dp)
   }
 })
 ```
@@ -90,12 +91,14 @@ const styles = StyleSheet.create(theme => ({
   }
 }))
 
-// In component — call useVariants BEFORE accessing styles
+// In component — call useVariants BEFORE accessing styles (always pass an object, `{}` for defaults)
 styles.useVariants({ size: 'large', color: 'primary' })
 return <View style={styles.button} />
 ```
 
-### withUnistyles — wrap third-party components (not React Native or Reanimated components)
+### withUnistyles — map theme/runtime to non-style props, or wrap views Unistyles can't bind to
+
+React Native / Reanimated views that only take `style` need no wrapping. Use `withUnistyles` for props like `color`/`trackColor`, for `contentContainerStyle`, or for third-party views that don't expose a native ref.
 
 ```tsx
 import { withUnistyles } from 'react-native-unistyles'
@@ -107,17 +110,19 @@ const UniButton = withUnistyles(Button, (theme, rt) => ({
 }))
 
 // Usage: <UniButton title="Press me" />
+// Per-instance mapping: <UniButton uniProps={theme => ({ color: isOn ? theme.colors.on : theme.colors.off })} />
 ```
 
 ## Critical Rules
 
 1. **NEVER spread styles** — `{...styles.x}` breaks C++ proxy binding. ALWAYS use array syntax: `[styles.x, styles.y]` or `[styles.x, { marginTop: 10 }]`
-2. **NEVER re-export StyleSheet from barrel files** — the Babel plugin detects `StyleSheet.create` by import source. Re-exporting breaks detection.
-3. **Babel plugin is REQUIRED** — add `['react-native-unistyles/plugin', { root: 'src' }]` to babel.config.js. Without it, styles won't be reactive.
+2. **NEVER re-export StyleSheet from barrel files** — import it directly from `react-native-unistyles`. Outside `root`, the Babel plugin only recognizes `StyleSheet.create` via that import (or `autoProcessImports`), so a re-export silently breaks detection.
+3. **Babel plugin is REQUIRED** — add `['react-native-unistyles/plugin', { root: 'src' }]` to babel.config.js (`root` is required; every file under it is processed). Re.Pack users use `RepackUnistylePlugin` from `react-native-unistyles/repack-plugin` instead. Without the plugin, styles won't be reactive.
 4. **Import StyleSheet from `react-native-unistyles` only** — it polyfills all RN StyleSheet APIs (`hairlineWidth`, `compose`, `flatten`, `absoluteFill`). Replace all `import { StyleSheet } from 'react-native'`.
-5. **`styles.useVariants()` must be called before accessing variant-dependent styles** — treat it like a React hook (top of component).
-6. **Prefer `StyleSheet.create(theme => ...)` over `useUnistyles()`** — theme functions cause zero re-renders; `useUnistyles()` re-renders on every theme/runtime change.
+5. **`styles.useVariants()` must be called before accessing variant-dependent styles** — treat it like a React hook (top of component). Always pass an object: `useVariants(undefined)` throws on native, use `{}` to select `default` variants.
+6. **Prefer `StyleSheet.create(theme => ...)` over `useUnistyles()`** — theme functions cause zero re-renders; `useUnistyles()` re-renders whenever a `theme`/`rt` value you *read* changes (never read `rt.insets.ime` there — it re-renders every keyboard frame).
 7. **`StyleSheet.configure()` must be called before any `StyleSheet.create()`** — typically in your app entry point, before any component renders.
+8. **Dynamic function arguments must be serializable** — Unistyles stores them in C++ and re-runs the function on theme/runtime changes. Functions are dropped; `Date`/`Map`/`Set`/class instances become plain objects. Pass primitives / plain objects (e.g. `date.getTime()`).
 
 ## Decision Trees
 
@@ -133,27 +138,31 @@ Need theme values as non-style props?
 └─ NO  → Pass Unistyles styles via style prop directly
 
 Need theme/runtime in component logic (not just styles)?
-├─ YES → useUnistyles() hook                        [causes re-renders]
+├─ YES → useUnistyles() hook                        [re-renders when read values change]
 └─ NO  → Use StyleSheet.create with theme function
 ```
 
 ### Third-party component integration
 
 ```
-Does the component accept a `style` prop?
-├─ YES → Pass Unistyles styles directly (Babel auto-processes standard RN views)
-│        If it's a custom native view → add to autoProcessPaths in Babel config
-├─ NO  → Does it accept theme-derived props (color, size, etc.)?
-│        ├─ YES → withUnistyles(Component, (theme, rt) => ({ prop: theme.value }))
-│        └─ NO  → useUnistyles() as fallback
-└─ Component from node_modules not processed?
-   → Add its path to autoProcessPaths or autoProcessImports in Babel plugin config
+Passing a Unistyles style to `contentContainerStyle` (ScrollView/FlatList)?
+├─ YES → withUnistyles(ScrollView) — auto-maps style + contentContainerStyle
+└─ NO  → react-native / react-native-reanimated view with a `style` prop?
+         ├─ YES → Pass Unistyles styles directly (Babel swaps in ref-borrowing factories)
+         └─ NO  → Third-party view built on RN components (in node_modules)?
+                  ├─ YES → Add its path to autoProcessPaths (e.g. 'some-lib/src/components')
+                  └─ Still not updating / needs theme-derived props (color, size, ...)?
+                     ├─ YES → withUnistyles(Component, (theme, rt) => ({ prop: theme.value }))
+                     └─ Last resort → useUnistyles() (re-renders the component)
+
+Your own files outside `root` (monorepo package) not updating?
+→ autoProcessImports: ['@my-org/styles']  (force-processes any file importing it)
 ```
 
 ## Reference Files
 
-- **Setup, installation, Babel plugin, TypeScript, testing, Expo Router**: read [references/setup-guide.md](references/setup-guide.md)
+- **Setup, installation, Babel plugin, Re.Pack, TypeScript, testing, Expo Router**: read [references/setup-guide.md](references/setup-guide.md)
 - **Complete API for every export**: read [references/api-reference.md](references/api-reference.md)
 - **Code patterns: themes, variants, breakpoints, web, SSR, Reanimated**: read [references/styling-patterns.md](references/styling-patterns.md)
-- **withUnistyles, autoProcessPaths, React Compiler, Reanimated, FlatList**: read [references/third-party-integration.md](references/third-party-integration.md)
+- **withUnistyles, autoProcessPaths/Imports, React Compiler, Reanimated, edge-to-edge, frozen screens, FlatList**: read [references/third-party-integration.md](references/third-party-integration.md)
 - **Troubleshooting from 150+ GitHub issues with solutions**: read [references/common-issues.md](references/common-issues.md)

package/skills/frontend/react-native/react-native-unistyles-v3/references/api-reference.md

@@ -52,6 +52,10 @@ const styles = StyleSheet.create(theme => ({
 <View style={styles.box(200, true)} />
 ```
 
+Arguments must be serializable (strings, numbers, booleans, `null`, `undefined`, plain arrays/objects): they're stored in C++ and the function is re-run natively on theme/runtime changes. Functions are dropped (shifting the remaining arguments); `Date`, `Map`, `Set` and class instances become plain objects.
+
+`boxShadow` and `filter: [{ dropShadow }]` also accept CSS-like strings (e.g. `boxShadow: '0 2px 4px rgba(0, 0, 0, 0.2)'`), parsed on iOS/Android.
+
 ### StyleSheet.configure(config)
 
 One-time initialization. Must be called before any `StyleSheet.create()`.
@@ -61,21 +65,23 @@ StyleSheet.configure({
   themes?: { [name: string]: ThemeObject },
   breakpoints?: { [name: string]: number },  // first must be 0
   settings?: {
-    initialTheme?: string | (() => string),
+    initialTheme?: string | (() => string),     // mutually exclusive with adaptiveThemes: true
     adaptiveThemes?: boolean,
-    CSSVars?: boolean,
-    nativeBreakpointsMode?: 'pixels' | 'points',
+    CSSVars?: boolean,                          // web only, default true
+    nativeBreakpointsMode?: 'pixels' | 'points', // default 'pixels'
   }
 })
 ```
 
+Unknown keys throw. `nativeBreakpointsMode: 'pixels'` compares breakpoints/`mq` against `UnistylesRuntime.screen` (points on iOS, dp on Android); `'points'` divides that by `pixelRatio` first.
+
 ### StyleSheet utilities
 
 | Property/Method | Description |
 |----------------|-------------|
-| `StyleSheet.hairlineWidth` | Thinnest visible line width (always `1` in v3) |
-| `StyleSheet.absoluteFill` | Shorthand for `{ position: 'absolute', left: 0, right: 0, top: 0, bottom: 0 }` |
-| `StyleSheet.absoluteFillObject` | Same object as `absoluteFill` |
+| `StyleSheet.hairlineWidth` | Thinnest line the device can draw (computed from `pixelRatio` on native; always `1` on web) |
+| `StyleSheet.absoluteFill` | Static `{ position: 'absolute', left: 0, right: 0, top: 0, bottom: 0 }` |
+| `StyleSheet.absoluteFillObject` | Same static object as `absoluteFill` |
 | `StyleSheet.compose(a, b)` | Compose two styles |
 | `StyleSheet.flatten(style)` | Flatten a style array into a single object |
 
@@ -84,8 +90,12 @@ StyleSheet.configure({
 Subscribe to Unistyles dependency changes:
 
 ```tsx
+import { StyleSheet, UnistyleDependency } from 'react-native-unistyles'
+
 const unsubscribe = StyleSheet.addChangeListener((dependencies: UnistyleDependency[]) => {
-  // dependencies is an array of what changed (Theme, Breakpoints, Orientation, etc.)
+  if (dependencies.includes(UnistyleDependency.Theme)) {
+    // theme changed (or was updated with updateTheme)
+  }
 })
 
 // Later:
@@ -106,19 +116,19 @@ import { UnistylesRuntime } from 'react-native-unistyles'
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `colorScheme` | `'light' \| 'dark' \| 'unspecified'` | OS color scheme |
-| `themeName` | `string \| undefined` | Current active theme name |
+| `colorScheme` | `ColorScheme` (`'light' \| 'dark' \| 'unspecified'`) | OS color scheme |
+| `themeName` | `string \| undefined` | Current theme name (inside a `ScopedTheme` during render: the scoped name) |
 | `breakpoint` | `string \| undefined` | Current active breakpoint name |
 | `hasAdaptiveThemes` | `boolean` | Whether adaptive themes are enabled |
-| `screen` | `{ width: number, height: number }` | Screen dimensions |
-| `insets` | `{ top, bottom, left, right, ime: number }` | Safe area insets + keyboard (ime) |
-| `orientation` | `'portrait' \| 'landscape'` | Current orientation |
+| `screen` | `{ width: number, height: number }` | Screen dimensions (points on iOS, dp on Android; `window.innerWidth/innerHeight` on web) |
+| `insets` | `{ top, bottom, left, right, ime: number }` | Safe area insets + keyboard (ime); all `0` on web |
+| `orientation` | `Orientation` (`'portrait' \| 'landscape'`) | Current orientation |
 | `isPortrait` | `boolean` | Shorthand for portrait check |
 | `isLandscape` | `boolean` | Shorthand for landscape check |
 | `pixelRatio` | `number` | Device pixel ratio |
 | `fontScale` | `number` | User font scale preference |
-| `rtl` | `boolean` | Whether layout direction is RTL |
-| `contentSizeCategory` | `IOSContentSizeCategory \| AndroidContentSizeCategory` | Accessibility text size |
+| `rtl` | `boolean` | Whether layout direction is RTL. Updates at runtime on Android (`I18nManager.forceRTL` / locale change) and web (`dir` on `<html>`); on iOS read at startup (restart required) |
+| `contentSizeCategory` | `IOSContentSizeCategory \| AndroidContentSizeCategory \| WebContentSizeCategory` | Accessibility text size (`'web-unspecified'` on web) |
 | `breakpoints` | `UnistylesBreakpoints` | Registered breakpoints object |
 
 ### Sub-objects
@@ -126,18 +136,18 @@ import { UnistylesRuntime } from 'react-native-unistyles'
 | Property | Type | Description |
 |----------|------|-------------|
 | `statusBar` | `UnistylesStatusBar` | Status bar dimensions and controls |
-| `navigationBar` | `UnistylesNavigationBar` | Navigation bar dimensions and controls (Android) |
+| `navigationBar` | `UnistylesNavigationBar` | Navigation bar dimensions and controls (Android only; `0` on iOS/web) |
 
 ### Methods
 
 ```tsx
-// Switch theme
+// Switch theme (throws while adaptive themes are enabled)
 UnistylesRuntime.setTheme('dark')
 
-// Get theme object by name
+// Get theme object by name (current theme if omitted)
 const darkTheme = UnistylesRuntime.getTheme('dark')
 
-// Update theme values at runtime (triggers re-style of affected components)
+// Update theme values at runtime (re-styles affected views if it's the current theme)
 UnistylesRuntime.updateTheme('light', currentTheme => ({
   ...currentTheme,
   colors: { ...currentTheme.colors, primary: '#ff0000' }
@@ -146,10 +156,10 @@ UnistylesRuntime.updateTheme('light', currentTheme => ({
 // Enable/disable adaptive themes
 UnistylesRuntime.setAdaptiveThemes(true)
 
-// Set root view background color
+// Set root view background color (any RN color; omit to reset to transparent; sets <html> background on web)
 UnistylesRuntime.setRootViewBackgroundColor('#ffffff')
 
-// Enable immersive mode (hide status bar + navigation bar)
+// Immersive mode: Android hides status + navigation bars; iOS hides only the status bar (fade); no-op on web
 UnistylesRuntime.setImmersiveMode(true)
 ```
 
@@ -157,34 +167,43 @@ UnistylesRuntime.setImmersiveMode(true)
 
 ## StatusBar
 
+Accessed via `UnistylesRuntime.statusBar`.
+
 ```tsx
-import { StatusBar } from 'react-native-unistyles'
+UnistylesRuntime.statusBar
 ```
 
 | Property/Method | Type | Description |
 |----------------|------|-------------|
 | `width` | `number` | Status bar width |
 | `height` | `number` | Status bar height |
-| `setHidden(hidden, animation?)` | `(boolean, 'none' \| 'fade' \| 'slide') => void` | Show/hide status bar |
-| `setStyle(style, animated?)` | `('default' \| 'light' \| 'dark', boolean?) => void` | Set status bar style |
+| `setHidden(hidden, animation?)` | `(boolean, 'none' \| 'fade' \| 'slide') => void` | Show/hide status bar (`animation` used on iOS) |
+| `setStyle(style, animated?)` | `(StatusBarStyle, boolean?) => void` | Set content style: `StatusBarStyle.Default` / `.Light` / `.Dark` |
+
+```tsx
+import { UnistylesRuntime, StatusBarStyle } from 'react-native-unistyles'
 
-Also accessible via `UnistylesRuntime.statusBar`.
+UnistylesRuntime.statusBar.setStyle(StatusBarStyle.Light, true)
+UnistylesRuntime.statusBar.setHidden(true, 'slide')
+```
+
+On web, status/navigation bar dimensions are `0` and these setters do nothing.
 
 ---
 
 ## NavigationBar
 
+Accessed via `UnistylesRuntime.navigationBar`.
+
 ```tsx
-import { NavigationBar } from 'react-native-unistyles'
+UnistylesRuntime.navigationBar
 ```
 
 | Property/Method | Type | Description |
 |----------------|------|-------------|
-| `width` | `number` | Navigation bar width |
-| `height` | `number` | Navigation bar height |
-| `setHidden(hidden)` | `(boolean) => void` | Show/hide navigation bar (Android) |
-
-Also accessible via `UnistylesRuntime.navigationBar`.
+| `width` | `number` | Navigation bar width (Android only, `0` on iOS) |
+| `height` | `number` | Navigation bar height (Android only, `0` on iOS) |
+| `setHidden(hidden)` | `(boolean) => void` | Show/hide navigation bar (Android only) |
 
 ---
 
@@ -213,17 +232,19 @@ mq.height(min?, max?).and.width(min?, max?)   // returns symbol
 ```
 
 Parameters can be:
-- **Breakpoint names**: `'sm'`, `'md'`, `'lg'` (from registered breakpoints)
-- **Pixel values**: `320`, `768`, `1200`
-- **`null`/`undefined`**: unbounded (no min or no max)
+- **Breakpoint names**: `'sm'`, `'md'`, `'lg'` (resolved to their values when `mq` is called — `StyleSheet.configure` must run first; unknown names resolve to `0`)
+- **Numbers**: `320`, `768`, `1200` (same units as `UnistylesRuntime.screen`)
+- **`null`/`undefined` min** → `0`; omitted max → unbounded
+
+**Both bounds are inclusive.** Adjacent ranges like `(240, 380)` and `(380)` both match width `380`; on native the first matching query in the style object wins. Invalid ranges (`('xl', 'sm')`, `(500, 200)`) are ignored.
 
 ### Examples
 
 ```tsx
-mq.only.width('sm', 'md')           // width between sm and md breakpoints
-mq.only.width(320, 768)             // width between 320px and 768px
+mq.only.width('sm', 'md')           // sm <= width <= md
+mq.only.width(320, 768)             // 320 <= width <= 768
 mq.only.width('sm')                 // width >= sm (no max)
-mq.only.width(null, 600)            // width <= 600px
+mq.only.width(null, 600)            // 0 <= width <= 600
 mq.width('sm', 'lg').and.height(400, 800)  // combined width + height
 ```
 
@@ -250,19 +271,29 @@ const UniButton = withUnistyles(Button, (theme, rt) => ({
 }))
 ```
 
-### With uniProps — dynamic mappings from component props
-
-The wrapped component receives additional `uniProps` that map to theme-derived values:
+### uniProps — per-instance mappings that can use component state
 
 ```tsx
-const UniIcon = withUnistyles(Icon, (theme) => ({
-  // These become available as props on UniIcon
-}))
+const UniSwitch = withUnistyles(Switch)
 
-// The style and contentContainerStyle props are auto-processed
-<UniIcon style={styles.icon} />
+const MyComponent = ({ isDisabled }) => (
+  <UniSwitch
+    uniProps={(theme, rt) => ({
+      trackColor: { true: isDisabled ? theme.colors.disabled : theme.colors.primary }
+    })}
+  />
+)
 ```
 
+Priority: mappings < `uniProps` < inline props. Both mappings and `uniProps` may return a `key` (used as the React `key` to remount the component, `uniProps` wins). They can't return `style`/`contentContainerStyle` — pass those as regular props; they're auto-mapped:
+
+```tsx
+const UniScrollView = withUnistyles(ScrollView)
+<UniScrollView style={styles.scroll} contentContainerStyle={styles.content} />
+```
+
+Re-renders: only when the dependencies it reads change — but on iOS/Android a wrapped component is always subscribed to theme changes. Reading `rt.insets.ime` re-renders on every keyboard animation frame. On web the component is wrapped in a `display: contents` `<div>`.
+
 ### Ref forwarding
 
 `withUnistyles` forwards refs automatically:
@@ -280,7 +311,7 @@ const ref = useRef<TextInput>(null)
 
 ## useUnistyles
 
-Hook that returns the current theme and mini runtime. **Causes re-renders** when theme or runtime values change.
+Hook that returns the current theme and mini runtime. **Causes re-renders** of the whole component. Subscriptions are created on **property access**, not destructuring: reading any `theme.*` subscribes to theme changes, reading `rt.screen.width` subscribes to dimensions, `rt.insets.top` to insets, `rt.insets.ime` only to the keyboard (re-renders every animation frame — prefer `StyleSheet`). Respects the parent `ScopedTheme`.
 
 ```tsx
 import { useUnistyles } from 'react-native-unistyles'
@@ -310,12 +341,14 @@ import { Display, Hide, mq } from 'react-native-unistyles'
   <SidePanel />
 </Display>
 
-// Hide children when width < 768
-<Hide mq={mq.only.width(null, 768)}>
+// Hide children when width <= 767 (bounds are inclusive)
+<Hide mq={mq.only.width(null, 767)}>
   <MobileNav />
 </Hide>
 ```
 
+These are plain conditional renders (no wrapper view); only `Display`/`Hide` re-renders when the query result changes.
+
 ---
 
 ## ScopedTheme
@@ -331,7 +364,7 @@ Props are **mutually exclusive** — use only one:
 | Prop | Type | Description |
 |------|------|-------------|
 | `name` | `keyof UnistylesThemes` | Force a specific theme |
-| `invertedAdaptive` | `boolean` | Use the opposite adaptive theme |
+| `invertedAdaptive` | `boolean` | Use the opposite adaptive theme (no-op if adaptive themes are disabled) |
 | `reset` | `boolean` | Reset to the global theme (undo parent ScopedTheme) |
 
 ```tsx
@@ -351,6 +384,8 @@ Props are **mutually exclusive** — use only one:
 </ScopedTheme>
 ```
 
+The scoped theme is only known during render (no React Context): `UnistylesRuntime.themeName`, `useUnistyles`, `withUnistyles` and `useAnimatedTheme` respect it inside the subtree. With `Suspense`, put `ScopedTheme` inside the suspending component.
+
 ---
 
 ## Types
@@ -373,6 +408,7 @@ const styles = StyleSheet.create(theme => ({
 
 type ButtonVariants = UnistylesVariants<typeof styles>
 // { size?: 'small' | 'large'; color?: 'primary' | 'secondary' }
+// Options of the same group are merged across styles; boolean groups infer `boolean`
 
 type Props = { title: string } & ButtonVariants
 
@@ -386,16 +422,34 @@ const Button = ({ title, ...variants }: Props) => {
 
 The type of individual style entries in a Unistyles stylesheet.
 
-### IOSContentSizeCategory / AndroidContentSizeCategory
+### UnistylesMiniRuntime
+
+Type of the `rt` argument (in `StyleSheet.create`, `useUnistyles`, `withUnistyles`): `themeName`, `breakpoint`, `hasAdaptiveThemes`, `colorScheme`, `screen`, `contentSizeCategory`, `insets`, `pixelRatio`, `fontScale`, `rtl`, `statusBar`, `navigationBar`, `isPortrait`, `isLandscape`.
+
+```tsx
+import type { UnistylesMiniRuntime } from 'react-native-unistyles'
+
+const getHeaderHeight = (rt: UnistylesMiniRuntime) => rt.insets.top + 56
+```
+
+### Value enums: ColorScheme, Orientation, StatusBarStyle, content size categories
 
-Enums for accessibility text size categories:
+These are **runtime values** (TS enums), not just types:
 
 ```tsx
-import type { IOSContentSizeCategory, AndroidContentSizeCategory } from 'react-native-unistyles'
+import {
+  ColorScheme,                // Light 'light', Dark 'dark', Unspecified 'unspecified'
+  Orientation,                // Portrait 'portrait', Landscape 'landscape'
+  StatusBarStyle,             // Default 'default', Light 'light', Dark 'dark'
+  IOSContentSizeCategory,     // AccessibilityExtraExtraExtraLarge … AccessibilityMedium,
+                              // ExtraExtraExtraLarge 'xxxLarge', ExtraExtraLarge 'xxLarge', ExtraLarge 'xLarge',
+                              // Large, Medium, Small, ExtraSmall 'xSmall', Unspecified 'unspecified'
+  AndroidContentSizeCategory, // Small, Default, Large, ExtraLarge, Huge, ExtraHuge, ExtraExtraHuge
+  WebContentSizeCategory,     // Unspecified 'web-unspecified'
+  UnistylesRuntime,
+} from 'react-native-unistyles'
 
-// iOS values: 'accessibilityExtraExtraExtraLarge', 'xxxLarge', 'xxLarge', 'xLarge',
-//             'Large', 'Medium', 'Small', 'xSmall', 'unspecified'
-// Android values: 'Small', 'Default', 'Large', 'ExtraLarge', 'Huge', 'ExtraHuge', 'ExtraExtraHuge'
+const isDark = UnistylesRuntime.colorScheme === ColorScheme.Dark
 ```
 
 ### UnistyleDependency
@@ -405,9 +459,11 @@ Enum for change listener dependencies:
 ```tsx
 import { UnistyleDependency } from 'react-native-unistyles'
 
-// Values: Theme, ThemeName, Breakpoints, ColorScheme, ContentSizeCategory,
-//         Orientation, Insets, Ime, PixelRatio, FontScale, Rtl,
-//         NavigationBar, StatusBar, Dimensions, AdaptiveThemes
+// Values: Theme, ThemeName, AdaptiveThemes, Breakpoints, Variants, ColorScheme,
+//         Dimensions, Orientation, ContentSizeCategory, Insets, PixelRatio,
+//         FontScale, StatusBar, NavigationBar, Ime, Rtl
+// Web emits only: Theme, ThemeName, AdaptiveThemes, Breakpoints, ColorScheme,
+//                 Dimensions, Orientation, Rtl
 ```
 
 ---
@@ -415,16 +471,16 @@ import { UnistyleDependency } from 'react-native-unistyles'
 ## Web-Only Exports
 
 ```tsx
-import { getWebProps } from 'react-native-unistyles/web-only'
+import { getWebProps } from 'react-native-unistyles/web'
 ```
 
-### getWebProps(style)
+### getWebProps(style, forwardedRef?)
 
-For custom web components that don't support Unistyles' auto-processing:
+For custom web (DOM) components. Returns `{ className, ref }` — spread both onto the element (the `ref` keeps the styles reactive; pass your forwarded ref as the 2nd argument to merge it). `className` includes any `_classNames`:
 
 ```tsx
-const { className, style: webStyle } = getWebProps(styles.container)
-return <div className={className} style={webStyle}>...</div>
+const webProps = getWebProps([styles.container, customStyle], forwardedRef)
+return <div {...webProps}>...</div>
 ```
 
 ---
@@ -437,7 +493,7 @@ import { useAnimatedTheme, useAnimatedVariantColor } from 'react-native-unistyle
 
 ### useAnimatedTheme()
 
-Returns a `SharedValue<Theme>` for use inside Reanimated worklets:
+Returns a `SharedValue<Theme>` for use inside Reanimated worklets (no re-renders; follows the parent `ScopedTheme`):
 
 ```tsx
 const animatedTheme = useAnimatedTheme()
@@ -449,17 +505,20 @@ const animatedStyle = useAnimatedStyle(() => ({
 
 ### useAnimatedVariantColor(style, colorKey)
 
-Animate color transitions when variants change:
+Returns a derived `SharedValue<string>` with the variant's current color (`colorKey` must contain `color`/`Color`; the style must have `variants`, otherwise it throws). Use it inside `useAnimatedStyle`:
 
 ```tsx
-const animatedColor = useAnimatedVariantColor(styles.button, 'backgroundColor')
+const color = useAnimatedVariantColor(styles.button, 'backgroundColor')
+const animatedStyle = useAnimatedStyle(() => ({
+  backgroundColor: withTiming(color.value, { duration: 500 }),
+}))
 ```
 
 ---
 
 ## SSR Exports
 
-For server-side rendering with Next.js:
+For server-side rendering with Next.js (also re-exported from the root, docs use the subpath):
 
 ```tsx
 import {
@@ -467,29 +526,27 @@ import {
   getServerUnistyles,
   hydrateServerUnistyles,
   resetServerUnistyles
-} from 'react-native-unistyles'
+} from 'react-native-unistyles/server'
 ```
 
 | Function | Description |
 |----------|-------------|
-| `useServerUnistyles(settings?)` | React hook returning style elements for SSR (App Router) |
-| `getServerUnistyles(settings?)` | Returns React element with styles for SSR (Pages Router) |
-| `hydrateServerUnistyles()` | Call on client to hydrate server-rendered styles |
-| `resetServerUnistyles()` | Reset server styles between requests |
+| `useServerUnistyles(settings?)` | App Router, in a `'use client'` component with `useServerInsertedHTML`. Returns the styles once per request on the server and resets the registry; on the client it hydrates automatically |
+| `getServerUnistyles(settings?)` | Pages Router (`_document` `getInitialProps`). Returns `<style>`/`<script>` elements; throws on the client |
+| `hydrateServerUnistyles()` | Pages Router: call on the client (in `useEffect`); throws on the server |
+| `resetServerUnistyles()` | Pages Router: call after **every** request (clears CSS, cached stylesheets, listeners) |
 
-Settings: `{ includeRNWStyles?: boolean }`
+Settings: `{ includeRNWStyles?: boolean }` (default `true`)
 
 ---
 
-## Native Components
+## Native Components (Babel factories)
 
-Pre-styled components that work with Unistyles out of the box:
+The Babel plugin rewrites `react-native` imports in processed files to ref-borrowing factories (no extra views, no styling of their own) so C++ can update the native views:
 
 ```tsx
+// what the plugin generates — you don't write this yourself
 import { View } from 'react-native-unistyles/components/native/View'
-import { Text } from 'react-native-unistyles/components/native/Text'
-import { Pressable } from 'react-native-unistyles/components/native/Pressable'
-// etc.
 ```
 
-These are automatically created by the Babel plugin — you typically don't import them directly. They exist for edge cases where the plugin can't detect a component.
+They are built with `createUnistylesElement(Component)` (exported from the root). On native, only the `style` prop is bound — use `withUnistyles` for `contentContainerStyle`.