{user.name}
// uses 1 field
+}
+```
+
+**Correct: serializes only 1 field**
+
+```tsx
+async function Page() {
+ const user = await fetchUser()
+ return {name}
+}
+```
+
+### 3.6 Parallel Data Fetching with Component Composition
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect: Sidebar waits for Page's fetch to complete**
+
+```tsx
+export default async function Page() {
+ const header = await fetchHeader()
+ return (
+
+
+ )
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+```
+
+**Correct: both fetch simultaneously**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {header}
+ {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+
+export default function Page() {
+ return (
+
+
+ )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+
+function Layout({ children }: { children: ReactNode }) {
+ return (
+
+
+ )
+}
+
+export default function Page() {
+ return (
+ {fullName}
+} +``` + +**Correct: derive during render** + +```tsx +function Form() { + const [firstName, setFirstName] = useState('First') + const [lastName, setLastName] = useState('Last') + const fullName = firstName + ' ' + lastName + + return{fullName}
+} +``` + +Reference: [https://react.dev/learn/you-might-not-need-an-effect](https://react.dev/learn/you-might-not-need-an-effect) + +### 5.2 Defer State Reads to Usage Point + +**Impact: MEDIUM (avoids unnecessary subscriptions)** + +Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks. + +**Incorrect: subscribes to all searchParams changes** + +```tsx +function ShareButton({ chatId }: { chatId: string }) { + const searchParams = useSearchParams() + + const handleShare = () => { + const ref = searchParams.get('ref') + shareChat(chatId, { ref }) + } + + return +} +``` + +**Correct: reads on demand, no subscription** + +```tsx +function ShareButton({ chatId }: { chatId: string }) { + const handleShare = () => { + const params = new URLSearchParams(window.location.search) + const ref = params.get('ref') + shareChat(chatId, { ref }) + } + + return +} +``` + +### 5.3 Do not wrap a simple expression with a primitive result type in useMemo + +**Impact: LOW-MEDIUM (wasted computation on every render)** + +When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`. + +Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself. + +**Incorrect:** + +```tsx +function Header({ user, notifications }: Props) { + const isLoading = useMemo(() => { + return user.isLoading || notifications.isLoading + }, [user.isLoading, notifications.isLoading]) + + if (isLoading) return
+ {user.followers} followers
+ {user.posts} posts
+
+ )
+
+ return (
+
+
+ )
+}
+```
+
+Every time `UserProfile` renders, `Avatar` and `Stats` are new component types. React unmounts the old instances and mounts new ones, losing any internal state, running effects again, and recreating DOM nodes.
+
+**Correct: pass props instead**
+
+```tsx
+function Avatar({ src, theme }: { src: string; theme: string }) {
+ return (
+
+ {followers} followers
+ {posts} posts
+
+ )
+}
+
+function UserProfile({ user, theme }) {
+ return (
+
+
+ )
+}
+```
+
+**Symptoms of this bug:**
+
+- Input fields lose focus on every keystroke
+
+- Animations restart unexpectedly
+
+- `useEffect` cleanup/setup runs on every parent render
+
+- Scroll position resets inside the component
+
+### 5.5 Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+**Impact: MEDIUM (restores memoization by using a constant for default value)**
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect: `onClick` has different values on every rerender**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+ // ...
+})
+
+// Used without optional onClick
+{avatar}
+}
+```
+
+**Correct: skips computation when loading**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+ const id = useMemo(() => computeAvatarId(user), [user])
+ return
+
+ )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
+
+### 5.7 Narrow Effect Dependencies
+
+**Impact: LOW (minimizes effect re-runs)**
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect: re-runs on any user field change**
+
+```tsx
+useEffect(() => {
+ console.log(user.id)
+}, [user])
+```
+
+**Correct: re-runs only when id changes**
+
+```tsx
+useEffect(() => {
+ console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+ if (width < 768) {
+ enableMobileMode()
+ }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+ if (isMobile) {
+ enableMobileMode()
+ }
+}, [isMobile])
+```
+
+### 5.8 Put Interaction Logic in Event Handlers
+
+**Impact: MEDIUM (avoids effect re-runs and duplicate side effects)**
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect: event modeled as state + effect**
+
+```tsx
+function Form() {
+ const [submitted, setSubmitted] = useState(false)
+ const theme = useContext(ThemeContext)
+
+ useEffect(() => {
+ if (submitted) {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+ }, [submitted, theme])
+
+ return
+}
+```
+
+**Correct: do it in the handler**
+
+```tsx
+function Form() {
+ const theme = useContext(ThemeContext)
+
+ function handleSubmit() {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+
+ return
+}
+```
+
+Reference: [https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
+
+### 5.9 Subscribe to Derived State
+
+**Impact: MEDIUM (reduces re-render frequency)**
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect: re-renders on every pixel change**
+
+```tsx
+function Sidebar() {
+ const width = useWindowWidth() // updates continuously
+ const isMobile = width < 768
+ return
+}
+```
+
+**Correct: re-renders only when boolean changes**
+
+```tsx
+function Sidebar() {
+ const isMobile = useMediaQuery('(max-width: 767px)')
+ return
+}
+```
+
+### 5.10 Use Functional setState Updates
+
+**Impact: MEDIUM (prevents stale closures and unnecessary callback recreations)**
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect: requires state as dependency**
+
+```tsx
+function TodoList() {
+ const [items, setItems] = useState(initialItems)
+
+ // Callback must depend on items, recreated on every items change
+ const addItems = useCallback((newItems: Item[]) => {
+ setItems([...items, ...newItems])
+ }, [items]) // ❌ items dependency causes recreations
+
+ // Risk of stale closure if dependency is forgotten
+ const removeItem = useCallback((id: string) => {
+ setItems(items.filter(item => item.id !== id))
+ }, []) // ❌ Missing items dependency - will use stale items!
+
+ return ` and animate the wrapper instead.
+
+**Incorrect: animating SVG directly - no hardware acceleration**
+
+```tsx
+function LoadingSpinner() {
+ return (
+
+ )
+}
+```
+
+**Correct: animating wrapper div - hardware accelerated**
+
+```tsx
+function LoadingSpinner() {
+ return (
+ ` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+ return (
+
+
+ )
+}
+```
+
+Avoids expensive re-renders and state loss.
+
+### 6.8 Use defer or async on Script Tags
+
+**Impact: HIGH (eliminates render-blocking)**
+
+Script tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.
+
+- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order
+
+- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order
+
+Use `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.
+
+**Incorrect: blocks rendering**
+
+```tsx
+export default function Document() {
+ return (
+
+
+
+
+
+ {/* content */}
+
+ )
+}
+```
+
+**Correct: non-blocking**
+
+```tsx
+import Script from 'next/script'
+
+export default function Page() {
+ return (
+ <>
+
+
+
+ )
+}
+```
+
+**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:
+
+Reference: [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)
+
+### 6.9 Use Explicit Conditional Rendering
+
+**Impact: LOW (prevents rendering 0 or NaN)**
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect: renders "0" when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+ return (
+ {/* content */}
+}
+```
+
+**Example: preload critical fonts and styles**
+
+```tsx
+import { preload, preinit } from 'react-dom'
+
+export default function RootLayout({ children }) {
+ // Preload font file
+ preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })
+
+ // Fetch and apply critical stylesheet immediately
+ preinit('/styles/critical.css', { as: 'style' })
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+**Example: preload modules for code-split routes**
+
+```tsx
+import { preloadModule, preinitModule } from 'react-dom'
+
+function Navigation() {
+ const preloadDashboard = () => {
+ preloadModule('/dashboard.js', { as: 'script' })
+ }
+
+ return (
+
+ )
+}
+```
+
+**When to use each:**
+
+| API | Use case |
+
+|-----|----------|
+
+| `prefetchDNS` | Third-party domains you'll connect to later |
+
+| `preconnect` | APIs or CDNs you'll fetch from immediately |
+
+| `preload` | Critical resources needed for current page |
+
+| `preloadModule` | JS modules for likely next navigation |
+
+| `preinit` | Stylesheets/scripts that must execute early |
+
+| `preinitModule` | ES modules that must execute early |
+
+Reference: [https://react.dev/reference/react-dom#resource-preloading-apis](https://react.dev/reference/react-dom#resource-preloading-apis)
+
+### 6.11 Use useTransition Over Manual Loading States
+
+**Impact: LOW (reduces re-renders and improves code clarity)**
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect: manual loading state**
+
+```tsx
+function SearchResults() {
+ const [query, setQuery] = useState('')
+ const [results, setResults] = useState([])
+ const [isLoading, setIsLoading] = useState(false)
+
+ const handleSearch = async (value: string) => {
+ setIsLoading(true)
+ setQuery(value)
+ const data = await fetchResults(value)
+ setResults(data)
+ setIsLoading(false)
+ }
+
+ return (
+ <>
+ handleSearch(e.target.value)} />
+ {isLoading && (null)
+
+ useEffect(() => {
+ if (ref.current && isHighlighted) {
+ ref.current.style.width = '100px'
+ const width = ref.current.offsetWidth // Forces layout
+ ref.current.style.height = '200px'
+ }
+ }, [isHighlighted])
+
+ return ()
+
+function cachedSlugify(text: string): string {
+ if (slugifyCache.has(text)) {
+ return slugifyCache.get(text)!
+ }
+ const result = slugify(text)
+ slugifyCache.set(text, result)
+ return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+ return (
+ ()
+
+function getLocalStorage(key: string) {
+ if (!storageCache.has(key)) {
+ storageCache.set(key, localStorage.getItem(key))
+ }
+ return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+ localStorage.setItem(key, value)
+ storageCache.set(key, value) // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record | null = null
+
+function getCookie(name: string) {
+ if (!cookieCache) {
+ cookieCache = Object.fromEntries(
+ document.cookie.split('; ').map(c => c.split('='))
+ )
+ }
+ return cookieCache[name]
+}
+```
+
+**Important: invalidate on external changes**
+
+```typescript
+window.addEventListener('storage', (e) => {
+ if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+ if (document.visibilityState === 'visible') {
+ storageCache.clear()
+ }
+})
+```
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+### 7.6 Combine Multiple Array Iterations
+
+**Impact: LOW-MEDIUM (reduces iterations)**
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect: 3 iterations**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct: 1 iteration**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+ if (user.isAdmin) admins.push(user)
+ if (user.isTester) testers.push(user)
+ if (!user.isActive) inactive.push(user)
+}
+```
+
+### 7.7 Early Length Check for Array Comparisons
+
+**Impact: MEDIUM-HIGH (avoids expensive operations when lengths differ)**
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect: always runs expensive comparison**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+ // Always sorts and joins, even when lengths differ
+ return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+ // Early return if lengths differ
+ if (current.length !== original.length) {
+ return true
+ }
+ // Only sort when lengths match
+ const currentSorted = current.toSorted()
+ const originalSorted = original.toSorted()
+ for (let i = 0; i < currentSorted.length; i++) {
+ if (currentSorted[i] !== originalSorted[i]) {
+ return true
+ }
+ }
+ return false
+}
+```
+
+This new approach is more efficient because:
+
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+
+- It avoids mutating the original arrays
+
+- It returns early when a difference is found
+
+### 7.8 Early Return from Functions
+
+**Impact: LOW-MEDIUM (avoids unnecessary computation)**
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect: processes all items even after finding answer**
+
+```typescript
+function validateUsers(users: User[]) {
+ let hasError = false
+ let errorMessage = ''
+
+ for (const user of users) {
+ if (!user.email) {
+ hasError = true
+ errorMessage = 'Email required'
+ }
+ if (!user.name) {
+ hasError = true
+ errorMessage = 'Name required'
+ }
+ // Continues checking all users even after error found
+ }
+
+ return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct: returns immediately on first error**
+
+```typescript
+function validateUsers(users: User[]) {
+ for (const user of users) {
+ if (!user.email) {
+ return { valid: false, error: 'Email required' }
+ }
+ if (!user.name) {
+ return { valid: false, error: 'Name required' }
+ }
+ }
+
+ return { valid: true }
+}
+```
+
+### 7.9 Hoist RegExp Creation
+
+**Impact: LOW-MEDIUM (avoids recreation)**
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect: new RegExp every render**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+ const regex = new RegExp(`(${query})`, 'gi')
+ const parts = text.split(regex)
+ return <>{parts.map((part, i) => ...)}
+}
+```
+
+**Correct: memoize or hoist**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+ const regex = useMemo(
+ () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+ [query]
+ )
+ const parts = text.split(regex)
+ return <>{parts.map((part, i) => ...)}
+}
+```
+
+**Warning: global regex has mutable state**
+
+```typescript
+const regex = /foo/g
+regex.test('foo') // true, lastIndex = 3
+regex.test('foo') // false, lastIndex = 0
+```
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+### 7.10 Use flatMap to Map and Filter in One Pass
+
+**Impact: LOW-MEDIUM (eliminates intermediate array)**
+
+Chaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.
+
+**Incorrect: 2 iterations, intermediate array**
+
+```typescript
+const userNames = users
+ .map(user => user.isActive ? user.name : null)
+ .filter(Boolean)
+```
+
+**Correct: 1 iteration, no intermediate array**
+
+```typescript
+const userNames = users.flatMap(user =>
+ user.isActive ? [user.name] : []
+)
+```
+
+**More examples:**
+
+```typescript
+// Extract valid emails from responses
+// Before
+const emails = responses
+ .map(r => r.success ? r.data.email : null)
+ .filter(Boolean)
+
+// After
+const emails = responses.flatMap(r =>
+ r.success ? [r.data.email] : []
+)
+
+// Parse and filter valid numbers
+// Before
+const numbers = strings
+ .map(s => parseInt(s, 10))
+ .filter(n => !isNaN(n))
+
+// After
+const numbers = strings.flatMap(s => {
+ const n = parseInt(s, 10)
+ return isNaN(n) ? [] : [n]
+})
+```
+
+**When to use:**
+
+- Transforming items while filtering some out
+
+- Conditional mapping where some inputs produce no output
+
+- Parsing/validating where invalid inputs should be skipped
+
+### 7.11 Use Loop for Min/Max Instead of Sort
+
+**Impact: LOW (O(n) instead of O(n log n))**
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+ id: string
+ name: string
+ updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+ const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+ return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+ const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+ return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+ if (projects.length === 0) return null
+
+ let latest = projects[0]
+
+ for (let i = 1; i < projects.length; i++) {
+ if (projects[i].updatedAt > latest.updatedAt) {
+ latest = projects[i]
+ }
+ }
+
+ return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+ if (projects.length === 0) return { oldest: null, newest: null }
+
+ let oldest = projects[0]
+ let newest = projects[0]
+
+ for (let i = 1; i < projects.length; i++) {
+ if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+ if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+ }
+
+ return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative: Math.min/Math.max for small arrays**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
+
+### 7.12 Use Set/Map for O(1) Lookups
+
+**Impact: LOW-MEDIUM (O(n) to O(1))**
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
+
+### 7.13 Use toSorted() Instead of sort() for Immutability
+
+**Impact: MEDIUM-HIGH (prevents mutation bugs in React state)**
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect: mutates original array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+ // Mutates the users prop array!
+ const sorted = useMemo(
+ () => users.sort((a, b) => a.name.localeCompare(b.name)),
+ [users]
+ )
+ return
+```
+
+If the project is already linked (`.vercel/project.json` or `.vercel/repo.json` exists), the `orgId` in those files determines the team — no need to ask again. If there is only one team (or just a personal account), skip the prompt and use it directly.
+
+**About the `.vercel/` directory:** A linked project has either:
+- `.vercel/project.json` — created by `vercel link` (single project linking). Contains `projectId` and `orgId`.
+- `.vercel/repo.json` — created by `vercel link --repo` (repo-based linking). Contains `orgId`, `remoteName`, and a `projects` array mapping directories to Vercel project IDs.
+
+Either file means the project is linked. Check for both.
+
+**Do NOT** use `vercel project inspect`, `vercel ls`, or `vercel link` to detect state in an unlinked directory — without a `.vercel/` config, they will interactively prompt (or with `--yes`, silently link as a side-effect). Only `vercel whoami` is safe to run anywhere.
+
+## Step 2: Choose a Deploy Method
+
+### Linked (`.vercel/` exists) + has git remote → Git Push
+
+This is the ideal state. The project is linked and has git integration.
+
+1. **Ask the user before pushing.** Never push without explicit approval:
+ ```
+ This project is connected to Vercel via git. I can commit and push to
+ trigger a deployment. Want me to proceed?
+ ```
+
+2. **Commit and push:**
+ ```bash
+ git add .
+ git commit -m "deploy: "
+ git push
+ ```
+ Vercel automatically builds from the push. Non-production branches get preview deployments; the production branch (usually `main`) gets a production deployment.
+
+3. **Retrieve the preview URL.** If the CLI is authenticated:
+ ```bash
+ sleep 5
+ vercel ls --format json
+ ```
+ The JSON output has a `deployments` array. Find the latest entry — its `url` field is the preview URL.
+
+ If the CLI is not authenticated, tell the user to check the Vercel dashboard or the commit status checks on their git provider for the preview URL.
+
+---
+
+### Linked (`.vercel/` exists) + no git remote → `vercel deploy`
+
+The project is linked but there's no git repo. Deploy directly with the CLI.
+
+```bash
+vercel deploy [path] -y --no-wait
+```
+
+Use `--no-wait` so the CLI returns immediately with the deployment URL instead of blocking until the build finishes (builds can take a while). Then check on the deployment status with:
+
+```bash
+vercel inspect
+```
+
+For production deploys (only if user explicitly asks):
+```bash
+vercel deploy [path] --prod -y --no-wait
+```
+
+---
+
+### Not linked + CLI is authenticated → Link first, then deploy
+
+The CLI is working but the project isn't linked yet. This is the opportunity to get the user into the best state.
+
+1. **Ask the user which team to deploy to.** Present the team slugs from Step 1 as a bulleted list. If there's only one team (or just a personal account), skip this step.
+
+2. **Once a team is selected, proceed directly to linking.** Tell the user what will happen but do not ask for separate confirmation:
+ ```
+ Linking this project to on Vercel. This will create a Vercel
+ project to deploy to and enable automatic deployments on future git pushes.
+ ```
+
+3. **If a git remote exists**, use repo-based linking with the selected team scope:
+ ```bash
+ vercel link --repo --scope
+ ```
+ This reads the git remote URL and matches it to existing Vercel projects that deploy from that repo. It creates `.vercel/repo.json`. This is much more reliable than `vercel link` (without `--repo`), which tries to match by directory name and often fails when the local folder and Vercel project are named differently.
+
+ **If there is no git remote**, fall back to standard linking:
+ ```bash
+ vercel link --scope
+ ```
+ This prompts the user to select or create a project. It creates `.vercel/project.json`.
+
+4. **Then deploy using the best available method:**
+ - If a git remote exists → commit and push (see git push method above)
+ - If no git remote → `vercel deploy [path] -y --no-wait --scope `, then `vercel inspect ` to check status
+
+---
+
+### Not linked + CLI not authenticated → Install, auth, link, deploy
+
+The Vercel CLI isn't set up at all.
+
+1. **Install the CLI (if not already installed):**
+ ```bash
+ npm install -g vercel
+ ```
+
+2. **Authenticate:**
+ ```bash
+ vercel login
+ ```
+ The user completes auth in their browser. If running in a non-interactive environment where login is not possible, skip to the **no-auth fallback** below.
+
+3. **Ask which team to deploy to** — present team slugs from `vercel teams list --format json` as a bulleted list. If only one team / personal account, skip. Once selected, proceed immediately.
+
+4. **Link the project** with the selected team scope (use `--repo` if a git remote exists, plain `vercel link` otherwise):
+ ```bash
+ vercel link --repo --scope # if git remote exists
+ vercel link --scope # if no git remote
+ ```
+
+5. **Deploy** using the best available method (git push if remote exists, otherwise `vercel deploy -y --no-wait --scope `, then `vercel inspect ` to check status).
+
+---
+
+### No-Auth Fallback — claude.ai sandbox
+
+**When to use:** Last resort when the CLI can't be installed or authenticated in the claude.ai sandbox. This requires no authentication — it returns a **Preview URL** (live site) and a **Claim URL** (transfer to your Vercel account).
+
+```bash
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]
+```
+
+**Arguments:**
+- `path` - Directory to deploy, or a `.tgz` file (defaults to current directory)
+
+**Examples:**
+```bash
+# Deploy current directory
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
+
+# Deploy specific project
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
+
+# Deploy existing tarball
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz
+```
+
+The script auto-detects the framework from `package.json`, packages the project (excluding `node_modules`, `.git`, `.env`), uploads it, and waits for the build to complete.
+
+**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
+
+---
+
+### No-Auth Fallback — Codex sandbox
+
+**When to use:** In the Codex sandbox where the CLI may not be authenticated. Codex runs in a sandboxed environment by default — try the CLI first, and fall back to the deploy script if auth fails.
+
+1. **Check whether the Vercel CLI is installed** (no escalation needed for this check):
+ ```bash
+ command -v vercel
+ ```
+
+2. **If `vercel` is installed**, try deploying with the CLI:
+ ```bash
+ vercel deploy [path] -y --no-wait
+ ```
+
+3. **If `vercel` is not installed, or the CLI fails with "No existing credentials found"**, use the fallback script:
+ ```bash
+ skill_dir=""
+
+ # Deploy current directory
+ bash "$skill_dir/resources/deploy-codex.sh"
+
+ # Deploy specific project
+ bash "$skill_dir/resources/deploy-codex.sh" /path/to/project
+
+ # Deploy existing tarball
+ bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
+ ```
+
+The script handles framework detection, packaging, and deployment. It waits for the build to complete and returns JSON with `previewUrl` and `claimUrl`.
+
+**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
+
+**Escalated network access:** Only escalate the actual deploy command if sandboxing blocks the network call (`sandbox_permissions=require_escalated`). Do **not** escalate the `command -v vercel` check.
+
+---
+
+## Agent-Specific Notes
+
+### Claude Code / terminal-based agents
+
+You have full shell access. Do NOT use the `/mnt/skills/` path. Follow the decision flow above using the CLI directly.
+
+For the no-auth fallback, run the deploy script from the skill's installed location:
+```bash
+bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
+```
+The path may vary depending on where the user installed the skill.
+
+### Sandboxed environments (claude.ai)
+
+You likely cannot run `vercel login` or `git push`. Go directly to the **no-auth fallback — claude.ai sandbox**.
+
+### Codex
+
+Codex runs in a sandbox. Check if the CLI is available first, then fall back to the deploy script. Go to the **no-auth fallback — Codex sandbox**.
+
+---
+
+## Output
+
+Always show the user the deployment URL.
+
+- **Git push:** Use `vercel ls --format json` to find the preview URL. If the CLI isn't authenticated, tell the user to check the Vercel dashboard or commit status checks.
+- **CLI deploy:** Show the URL returned by `vercel deploy --no-wait`. Use `vercel inspect ` to check build status and report it to the user.
+- **No-auth fallback:** Show both the preview URL and the claim URL:
+ ```
+ Deployment successful!
+
+ Preview URL: https://my-app-abc123.vercel.app
+ Claim URL: https://vercel.com/claim-deployment?code=...
+
+ View your site at the Preview URL.
+ To transfer this deployment to your Vercel account, visit the Claim URL.
+ ```
+
+**Do not** curl or fetch the deployed URL to verify it works. Just return the link.
+
+---
+
+## Troubleshooting
+
+### Network Egress Error (claude.ai)
+
+If deployment fails due to network restrictions on claude.ai, tell the user:
+
+```
+Deployment failed due to network restrictions. To fix this:
+
+1. Go to https://claude.ai/settings/capabilities
+2. Add *.vercel.com to the allowed domains
+3. Try deploying again
+```
+
+### Escalated Network Access (Codex / sandboxed environments)
+
+If deployment fails due to network issues (timeouts, DNS errors, connection resets) in a sandboxed environment, rerun with escalated permissions (`sandbox_permissions=require_escalated`). Do not escalate the initial CLI availability check — only escalate the actual deploy command.
+
+Example guidance to the user:
+```
+The deploy needs escalated network access to deploy to Vercel. I can rerun
+the command with escalated permissions — want me to proceed?
+```
+
+### CLI Auth Failure
+
+If `vercel login` or `vercel deploy` fails with authentication errors, fall back to the no-auth deploy script (claude.ai or Codex variant, depending on the environment).
diff --git a/.agent/skills/deploy-to-vercel/resources/deploy-codex.sh b/.agent/skills/deploy-to-vercel/resources/deploy-codex.sh
new file mode 100644
index 00000000..af07d0fd
--- /dev/null
+++ b/.agent/skills/deploy-to-vercel/resources/deploy-codex.sh
@@ -0,0 +1,301 @@
+#!/bin/bash
+
+# Vercel Deployment Script for Codex (via claimable deploy endpoint)
+# Usage: ./deploy-codex.sh [project-path]
+# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
+
+set -euo pipefail
+
+DEPLOY_ENDPOINT="https://codex-deploy-skills.vercel.sh/api/deploy"
+
+# Detect framework from package.json
+detect_framework() {
+ local pkg_json="$1"
+
+ if [ ! -f "$pkg_json" ]; then
+ echo "null"
+ return
+ fi
+
+ local content=$(cat "$pkg_json")
+
+ # Helper to check if a package exists in dependencies or devDependencies.
+ # Use exact matching by default, with a separate prefix matcher for scoped
+ # package families like "@remix-run/".
+ has_dep_exact() {
+ echo "$content" | grep -q "\"$1\""
+ }
+
+ has_dep_prefix() {
+ echo "$content" | grep -q "\"$1"
+ }
+
+ # Order matters - check more specific frameworks first
+
+ # Blitz
+ if has_dep_exact "blitz"; then echo "blitzjs"; return; fi
+
+ # Next.js
+ if has_dep_exact "next"; then echo "nextjs"; return; fi
+
+ # Gatsby
+ if has_dep_exact "gatsby"; then echo "gatsby"; return; fi
+
+ # Remix
+ if has_dep_prefix "@remix-run/"; then echo "remix"; return; fi
+
+ # React Router (v7 framework mode)
+ if has_dep_prefix "@react-router/"; then echo "react-router"; return; fi
+
+ # TanStack Start
+ if has_dep_exact "@tanstack/start"; then echo "tanstack-start"; return; fi
+
+ # Astro
+ if has_dep_exact "astro"; then echo "astro"; return; fi
+
+ # Hydrogen (Shopify)
+ if has_dep_exact "@shopify/hydrogen"; then echo "hydrogen"; return; fi
+
+ # SvelteKit
+ if has_dep_exact "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
+
+ # Svelte (standalone)
+ if has_dep_exact "svelte"; then echo "svelte"; return; fi
+
+ # Nuxt
+ if has_dep_exact "nuxt"; then echo "nuxtjs"; return; fi
+
+ # Vue with Vitepress
+ if has_dep_exact "vitepress"; then echo "vitepress"; return; fi
+
+ # Vue with Vuepress
+ if has_dep_exact "vuepress"; then echo "vuepress"; return; fi
+
+ # Gridsome
+ if has_dep_exact "gridsome"; then echo "gridsome"; return; fi
+
+ # SolidStart
+ if has_dep_exact "@solidjs/start"; then echo "solidstart-1"; return; fi
+
+ # Docusaurus
+ if has_dep_exact "@docusaurus/core"; then echo "docusaurus-2"; return; fi
+
+ # RedwoodJS
+ if has_dep_prefix "@redwoodjs/"; then echo "redwoodjs"; return; fi
+
+ # Hexo
+ if has_dep_exact "hexo"; then echo "hexo"; return; fi
+
+ # Eleventy
+ if has_dep_exact "@11ty/eleventy"; then echo "eleventy"; return; fi
+
+ # Angular / Ionic Angular
+ if has_dep_exact "@ionic/angular"; then echo "ionic-angular"; return; fi
+ if has_dep_exact "@angular/core"; then echo "angular"; return; fi
+
+ # Ionic React
+ if has_dep_exact "@ionic/react"; then echo "ionic-react"; return; fi
+
+ # Create React App
+ if has_dep_exact "react-scripts"; then echo "create-react-app"; return; fi
+
+ # Ember
+ if has_dep_exact "ember-cli" || has_dep_exact "ember-source"; then echo "ember"; return; fi
+
+ # Dojo
+ if has_dep_exact "@dojo/framework"; then echo "dojo"; return; fi
+
+ # Polymer
+ if has_dep_prefix "@polymer/"; then echo "polymer"; return; fi
+
+ # Preact
+ if has_dep_exact "preact"; then echo "preact"; return; fi
+
+ # Stencil
+ if has_dep_exact "@stencil/core"; then echo "stencil"; return; fi
+
+ # UmiJS
+ if has_dep_exact "umi"; then echo "umijs"; return; fi
+
+ # Sapper (legacy Svelte)
+ if has_dep_exact "sapper"; then echo "sapper"; return; fi
+
+ # Saber
+ if has_dep_exact "saber"; then echo "saber"; return; fi
+
+ # Sanity
+ if has_dep_exact "sanity"; then echo "sanity-v3"; return; fi
+ if has_dep_prefix "@sanity/"; then echo "sanity"; return; fi
+
+ # Storybook
+ if has_dep_prefix "@storybook/"; then echo "storybook"; return; fi
+
+ # NestJS
+ if has_dep_exact "@nestjs/core"; then echo "nestjs"; return; fi
+
+ # Elysia
+ if has_dep_exact "elysia"; then echo "elysia"; return; fi
+
+ # Hono
+ if has_dep_exact "hono"; then echo "hono"; return; fi
+
+ # Fastify
+ if has_dep_exact "fastify"; then echo "fastify"; return; fi
+
+ # h3
+ if has_dep_exact "h3"; then echo "h3"; return; fi
+
+ # Nitro
+ if has_dep_exact "nitropack"; then echo "nitro"; return; fi
+
+ # Express
+ if has_dep_exact "express"; then echo "express"; return; fi
+
+ # Vite (generic - check last among JS frameworks)
+ if has_dep_exact "vite"; then echo "vite"; return; fi
+
+ # Parcel
+ if has_dep_exact "parcel"; then echo "parcel"; return; fi
+
+ # No framework detected
+ echo "null"
+}
+
+# Parse arguments
+INPUT_PATH="${1:-.}"
+
+# Create temp directory for packaging
+TEMP_DIR=$(mktemp -d)
+TARBALL="$TEMP_DIR/project.tgz"
+STAGING_DIR="$TEMP_DIR/staging"
+CLEANUP_TEMP=true
+
+cleanup() {
+ if [ "$CLEANUP_TEMP" = true ]; then
+ rm -rf "$TEMP_DIR"
+ fi
+}
+trap cleanup EXIT
+
+echo "Preparing deployment..." >&2
+
+# Check if input is a .tgz file or a directory
+FRAMEWORK="null"
+
+if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
+ # Input is already a tarball, use it directly
+ echo "Using provided tarball..." >&2
+ TARBALL="$INPUT_PATH"
+ CLEANUP_TEMP=false
+ # Can't detect framework from tarball, leave as null
+elif [ -d "$INPUT_PATH" ]; then
+ # Input is a directory, need to tar it
+ PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
+
+ # Detect framework from package.json
+ FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
+
+ # Stage files into a temporary directory to avoid mutating the source tree.
+ mkdir -p "$STAGING_DIR"
+ echo "Staging project files..." >&2
+ tar -C "$PROJECT_PATH" \
+ --exclude='node_modules' \
+ --exclude='.git' \
+ --exclude='.env' \
+ --exclude='.env.*' \
+ -cf - . | tar -C "$STAGING_DIR" -xf -
+
+ # Check if this is a static HTML project (no package.json)
+ if [ ! -f "$PROJECT_PATH/package.json" ]; then
+ # Find HTML files in root
+ HTML_FILES=$(find "$STAGING_DIR" -maxdepth 1 -name "*.html" -type f)
+ HTML_COUNT=$(printf '%s\n' "$HTML_FILES" | sed '/^$/d' | wc -l | tr -d '[:space:]')
+
+ # If there's exactly one HTML file and it's not index.html, rename it
+ if [ "$HTML_COUNT" -eq 1 ]; then
+ HTML_FILE=$(echo "$HTML_FILES" | head -1)
+ BASENAME=$(basename "$HTML_FILE")
+ if [ "$BASENAME" != "index.html" ]; then
+ echo "Renaming $BASENAME to index.html..." >&2
+ mv "$HTML_FILE" "$STAGING_DIR/index.html"
+ fi
+ fi
+ fi
+
+ # Create tarball from the staging directory
+ echo "Creating deployment package..." >&2
+ tar -czf "$TARBALL" -C "$STAGING_DIR" .
+else
+ echo "Error: Input must be a directory or a .tgz file" >&2
+ exit 1
+fi
+
+if [ "$FRAMEWORK" != "null" ]; then
+ echo "Detected framework: $FRAMEWORK" >&2
+fi
+
+# Deploy
+echo "Deploying..." >&2
+RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
+
+# Check for error in response
+if echo "$RESPONSE" | grep -q '"error"'; then
+ ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
+ echo "Error: $ERROR_MSG" >&2
+ exit 1
+fi
+
+# Extract URLs from response
+PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
+CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
+
+if [ -z "$PREVIEW_URL" ]; then
+ echo "Error: Could not extract preview URL from response" >&2
+ echo "$RESPONSE" >&2
+ exit 1
+fi
+
+echo "Deployment started. Waiting for build to complete..." >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+
+# Poll the preview URL until it returns a non-5xx response (5xx = still building)
+MAX_ATTEMPTS=60 # 5 minutes max (60 * 5 seconds)
+ATTEMPT=0
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+ HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL")
+
+ if [ "$HTTP_STATUS" -eq 200 ]; then
+ echo "" >&2
+ echo "Deployment ready!" >&2
+ break
+ elif [ "$HTTP_STATUS" -ge 500 ]; then
+ # 5xx means still building/deploying
+ echo "Building... (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" >&2
+ sleep 5
+ ATTEMPT=$((ATTEMPT + 1))
+ elif [ "$HTTP_STATUS" -ge 400 ] && [ "$HTTP_STATUS" -lt 500 ]; then
+ # 4xx might be an error or the app itself returns 4xx - it's responding
+ echo "" >&2
+ echo "Deployment ready (returned $HTTP_STATUS)!" >&2
+ break
+ else
+ # Any other status, assume it's ready
+ echo "" >&2
+ echo "Deployment ready!" >&2
+ break
+ fi
+done
+
+if [ $ATTEMPT -eq $MAX_ATTEMPTS ]; then
+ echo "" >&2
+ echo "Warning: Timed out waiting for deployment, but it may still be building." >&2
+fi
+
+echo "" >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+echo "Claim URL: $CLAIM_URL" >&2
+echo "" >&2
+
+# Output JSON for programmatic use
+echo "$RESPONSE"
diff --git a/.agent/skills/deploy-to-vercel/resources/deploy.sh b/.agent/skills/deploy-to-vercel/resources/deploy.sh
new file mode 100644
index 00000000..a458da63
--- /dev/null
+++ b/.agent/skills/deploy-to-vercel/resources/deploy.sh
@@ -0,0 +1,301 @@
+#!/bin/bash
+
+# Vercel Deployment Script (via claimable deploy endpoint)
+# Usage: ./deploy.sh [project-path]
+# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
+
+set -euo pipefail
+
+DEPLOY_ENDPOINT="https://claude-skills-deploy.vercel.com/api/deploy"
+
+# Detect framework from package.json
+detect_framework() {
+ local pkg_json="$1"
+
+ if [ ! -f "$pkg_json" ]; then
+ echo "null"
+ return
+ fi
+
+ local content=$(cat "$pkg_json")
+
+ # Helper to check if a package exists in dependencies or devDependencies.
+ # Use exact matching by default, with a separate prefix matcher for scoped
+ # package families like "@remix-run/".
+ has_dep_exact() {
+ echo "$content" | grep -q "\"$1\""
+ }
+
+ has_dep_prefix() {
+ echo "$content" | grep -q "\"$1"
+ }
+
+ # Order matters - check more specific frameworks first
+
+ # Blitz
+ if has_dep_exact "blitz"; then echo "blitzjs"; return; fi
+
+ # Next.js
+ if has_dep_exact "next"; then echo "nextjs"; return; fi
+
+ # Gatsby
+ if has_dep_exact "gatsby"; then echo "gatsby"; return; fi
+
+ # Remix
+ if has_dep_prefix "@remix-run/"; then echo "remix"; return; fi
+
+ # React Router (v7 framework mode)
+ if has_dep_prefix "@react-router/"; then echo "react-router"; return; fi
+
+ # TanStack Start
+ if has_dep_exact "@tanstack/start"; then echo "tanstack-start"; return; fi
+
+ # Astro
+ if has_dep_exact "astro"; then echo "astro"; return; fi
+
+ # Hydrogen (Shopify)
+ if has_dep_exact "@shopify/hydrogen"; then echo "hydrogen"; return; fi
+
+ # SvelteKit
+ if has_dep_exact "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
+
+ # Svelte (standalone)
+ if has_dep_exact "svelte"; then echo "svelte"; return; fi
+
+ # Nuxt
+ if has_dep_exact "nuxt"; then echo "nuxtjs"; return; fi
+
+ # Vue with Vitepress
+ if has_dep_exact "vitepress"; then echo "vitepress"; return; fi
+
+ # Vue with Vuepress
+ if has_dep_exact "vuepress"; then echo "vuepress"; return; fi
+
+ # Gridsome
+ if has_dep_exact "gridsome"; then echo "gridsome"; return; fi
+
+ # SolidStart
+ if has_dep_exact "@solidjs/start"; then echo "solidstart-1"; return; fi
+
+ # Docusaurus
+ if has_dep_exact "@docusaurus/core"; then echo "docusaurus-2"; return; fi
+
+ # RedwoodJS
+ if has_dep_prefix "@redwoodjs/"; then echo "redwoodjs"; return; fi
+
+ # Hexo
+ if has_dep_exact "hexo"; then echo "hexo"; return; fi
+
+ # Eleventy
+ if has_dep_exact "@11ty/eleventy"; then echo "eleventy"; return; fi
+
+ # Angular / Ionic Angular
+ if has_dep_exact "@ionic/angular"; then echo "ionic-angular"; return; fi
+ if has_dep_exact "@angular/core"; then echo "angular"; return; fi
+
+ # Ionic React
+ if has_dep_exact "@ionic/react"; then echo "ionic-react"; return; fi
+
+ # Create React App
+ if has_dep_exact "react-scripts"; then echo "create-react-app"; return; fi
+
+ # Ember
+ if has_dep_exact "ember-cli" || has_dep_exact "ember-source"; then echo "ember"; return; fi
+
+ # Dojo
+ if has_dep_exact "@dojo/framework"; then echo "dojo"; return; fi
+
+ # Polymer
+ if has_dep_prefix "@polymer/"; then echo "polymer"; return; fi
+
+ # Preact
+ if has_dep_exact "preact"; then echo "preact"; return; fi
+
+ # Stencil
+ if has_dep_exact "@stencil/core"; then echo "stencil"; return; fi
+
+ # UmiJS
+ if has_dep_exact "umi"; then echo "umijs"; return; fi
+
+ # Sapper (legacy Svelte)
+ if has_dep_exact "sapper"; then echo "sapper"; return; fi
+
+ # Saber
+ if has_dep_exact "saber"; then echo "saber"; return; fi
+
+ # Sanity
+ if has_dep_exact "sanity"; then echo "sanity-v3"; return; fi
+ if has_dep_prefix "@sanity/"; then echo "sanity"; return; fi
+
+ # Storybook
+ if has_dep_prefix "@storybook/"; then echo "storybook"; return; fi
+
+ # NestJS
+ if has_dep_exact "@nestjs/core"; then echo "nestjs"; return; fi
+
+ # Elysia
+ if has_dep_exact "elysia"; then echo "elysia"; return; fi
+
+ # Hono
+ if has_dep_exact "hono"; then echo "hono"; return; fi
+
+ # Fastify
+ if has_dep_exact "fastify"; then echo "fastify"; return; fi
+
+ # h3
+ if has_dep_exact "h3"; then echo "h3"; return; fi
+
+ # Nitro
+ if has_dep_exact "nitropack"; then echo "nitro"; return; fi
+
+ # Express
+ if has_dep_exact "express"; then echo "express"; return; fi
+
+ # Vite (generic - check last among JS frameworks)
+ if has_dep_exact "vite"; then echo "vite"; return; fi
+
+ # Parcel
+ if has_dep_exact "parcel"; then echo "parcel"; return; fi
+
+ # No framework detected
+ echo "null"
+}
+
+# Parse arguments
+INPUT_PATH="${1:-.}"
+
+# Create temp directory for packaging
+TEMP_DIR=$(mktemp -d)
+TARBALL="$TEMP_DIR/project.tgz"
+STAGING_DIR="$TEMP_DIR/staging"
+CLEANUP_TEMP=true
+
+cleanup() {
+ if [ "$CLEANUP_TEMP" = true ]; then
+ rm -rf "$TEMP_DIR"
+ fi
+}
+trap cleanup EXIT
+
+echo "Preparing deployment..." >&2
+
+# Check if input is a .tgz file or a directory
+FRAMEWORK="null"
+
+if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
+ # Input is already a tarball, use it directly
+ echo "Using provided tarball..." >&2
+ TARBALL="$INPUT_PATH"
+ CLEANUP_TEMP=false
+ # Can't detect framework from tarball, leave as null
+elif [ -d "$INPUT_PATH" ]; then
+ # Input is a directory, need to tar it
+ PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
+
+ # Detect framework from package.json
+ FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
+
+ # Stage files into a temporary directory to avoid mutating the source tree.
+ mkdir -p "$STAGING_DIR"
+ echo "Staging project files..." >&2
+ tar -C "$PROJECT_PATH" \
+ --exclude='node_modules' \
+ --exclude='.git' \
+ --exclude='.env' \
+ --exclude='.env.*' \
+ -cf - . | tar -C "$STAGING_DIR" -xf -
+
+ # Check if this is a static HTML project (no package.json)
+ if [ ! -f "$PROJECT_PATH/package.json" ]; then
+ # Find HTML files in root
+ HTML_FILES=$(find "$STAGING_DIR" -maxdepth 1 -name "*.html" -type f)
+ HTML_COUNT=$(printf '%s\n' "$HTML_FILES" | sed '/^$/d' | wc -l | tr -d '[:space:]')
+
+ # If there's exactly one HTML file and it's not index.html, rename it
+ if [ "$HTML_COUNT" -eq 1 ]; then
+ HTML_FILE=$(echo "$HTML_FILES" | head -1)
+ BASENAME=$(basename "$HTML_FILE")
+ if [ "$BASENAME" != "index.html" ]; then
+ echo "Renaming $BASENAME to index.html..." >&2
+ mv "$HTML_FILE" "$STAGING_DIR/index.html"
+ fi
+ fi
+ fi
+
+ # Create tarball from the staging directory
+ echo "Creating deployment package..." >&2
+ tar -czf "$TARBALL" -C "$STAGING_DIR" .
+else
+ echo "Error: Input must be a directory or a .tgz file" >&2
+ exit 1
+fi
+
+if [ "$FRAMEWORK" != "null" ]; then
+ echo "Detected framework: $FRAMEWORK" >&2
+fi
+
+# Deploy
+echo "Deploying..." >&2
+RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
+
+# Check for error in response
+if echo "$RESPONSE" | grep -q '"error"'; then
+ ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
+ echo "Error: $ERROR_MSG" >&2
+ exit 1
+fi
+
+# Extract URLs from response
+PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
+CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
+
+if [ -z "$PREVIEW_URL" ]; then
+ echo "Error: Could not extract preview URL from response" >&2
+ echo "$RESPONSE" >&2
+ exit 1
+fi
+
+echo "Deployment started. Waiting for build to complete..." >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+
+# Poll the preview URL until it returns a non-5xx response (5xx = still building)
+MAX_ATTEMPTS=60 # 5 minutes max (60 * 5 seconds)
+ATTEMPT=0
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+ HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL")
+
+ if [ "$HTTP_STATUS" -eq 200 ]; then
+ echo "" >&2
+ echo "Deployment ready!" >&2
+ break
+ elif [ "$HTTP_STATUS" -ge 500 ]; then
+ # 5xx means still building/deploying
+ echo "Building... (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" >&2
+ sleep 5
+ ATTEMPT=$((ATTEMPT + 1))
+ elif [ "$HTTP_STATUS" -ge 400 ] && [ "$HTTP_STATUS" -lt 500 ]; then
+ # 4xx might be an error or the app itself returns 4xx - it's responding
+ echo "" >&2
+ echo "Deployment ready (returned $HTTP_STATUS)!" >&2
+ break
+ else
+ # Any other status, assume it's ready
+ echo "" >&2
+ echo "Deployment ready!" >&2
+ break
+ fi
+done
+
+if [ $ATTEMPT -eq $MAX_ATTEMPTS ]; then
+ echo "" >&2
+ echo "Warning: Timed out waiting for deployment, but it may still be building." >&2
+fi
+
+echo "" >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+echo "Claim URL: $CLAIM_URL" >&2
+echo "" >&2
+
+# Output JSON for programmatic use
+echo "$RESPONSE"
diff --git a/.agent/skills/next-best-practices/SKILL.md b/.agent/skills/next-best-practices/SKILL.md
new file mode 100644
index 00000000..437896b4
--- /dev/null
+++ b/.agent/skills/next-best-practices/SKILL.md
@@ -0,0 +1,153 @@
+---
+name: next-best-practices
+description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
+user-invocable: false
+---
+
+# Next.js Best Practices
+
+Apply these rules when writing or reviewing Next.js code.
+
+## File Conventions
+
+See [file-conventions.md](./file-conventions.md) for:
+- Project structure and special files
+- Route segments (dynamic, catch-all, groups)
+- Parallel and intercepting routes
+- Middleware rename in v16 (middleware → proxy)
+
+## RSC Boundaries
+
+Detect invalid React Server Component patterns.
+
+See [rsc-boundaries.md](./rsc-boundaries.md) for:
+- Async client component detection (invalid)
+- Non-serializable props detection
+- Server Action exceptions
+
+## Async Patterns
+
+Next.js 15+ async API changes.
+
+See [async-patterns.md](./async-patterns.md) for:
+- Async `params` and `searchParams`
+- Async `cookies()` and `headers()`
+- Migration codemod
+
+## Runtime Selection
+
+See [runtime-selection.md](./runtime-selection.md) for:
+- Default to Node.js runtime
+- When Edge runtime is appropriate
+
+## Directives
+
+See [directives.md](./directives.md) for:
+- `'use client'`, `'use server'` (React)
+- `'use cache'` (Next.js)
+
+## Functions
+
+See [functions.md](./functions.md) for:
+- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
+- Server functions: `cookies`, `headers`, `draftMode`, `after`
+- Generate functions: `generateStaticParams`, `generateMetadata`
+
+## Error Handling
+
+See [error-handling.md](./error-handling.md) for:
+- `error.tsx`, `global-error.tsx`, `not-found.tsx`
+- `redirect`, `permanentRedirect`, `notFound`
+- `forbidden`, `unauthorized` (auth errors)
+- `unstable_rethrow` for catch blocks
+
+## Data Patterns
+
+See [data-patterns.md](./data-patterns.md) for:
+- Server Components vs Server Actions vs Route Handlers
+- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
+- Client component data fetching
+
+## Route Handlers
+
+See [route-handlers.md](./route-handlers.md) for:
+- `route.ts` basics
+- GET handler conflicts with `page.tsx`
+- Environment behavior (no React DOM)
+- When to use vs Server Actions
+
+## Metadata & OG Images
+
+See [metadata.md](./metadata.md) for:
+- Static and dynamic metadata
+- `generateMetadata` function
+- OG image generation with `next/og`
+- File-based metadata conventions
+
+## Image Optimization
+
+See [image.md](./image.md) for:
+- Always use `next/image` over `![]()
`
+- Remote images configuration
+- Responsive `sizes` attribute
+- Blur placeholders
+- Priority loading for LCP
+
+## Font Optimization
+
+See [font.md](./font.md) for:
+- `next/font` setup
+- Google Fonts, local fonts
+- Tailwind CSS integration
+- Preloading subsets
+
+## Bundling
+
+See [bundling.md](./bundling.md) for:
+- Server-incompatible packages
+- CSS imports (not link tags)
+- Polyfills (already included)
+- ESM/CommonJS issues
+- Bundle analysis
+
+## Scripts
+
+See [scripts.md](./scripts.md) for:
+- `next/script` vs native script tags
+- Inline scripts need `id`
+- Loading strategies
+- Google Analytics with `@next/third-parties`
+
+## Hydration Errors
+
+See [hydration-error.md](./hydration-error.md) for:
+- Common causes (browser APIs, dates, invalid HTML)
+- Debugging with error overlay
+- Fixes for each cause
+
+## Suspense Boundaries
+
+See [suspense-boundaries.md](./suspense-boundaries.md) for:
+- CSR bailout with `useSearchParams` and `usePathname`
+- Which hooks require Suspense boundaries
+
+## Parallel & Intercepting Routes
+
+See [parallel-routes.md](./parallel-routes.md) for:
+- Modal patterns with `@slot` and `(.)` interceptors
+- `default.tsx` for fallbacks
+- Closing modals correctly with `router.back()`
+
+## Self-Hosting
+
+See [self-hosting.md](./self-hosting.md) for:
+- `output: 'standalone'` for Docker
+- Cache handlers for multi-instance ISR
+- What works vs needs extra setup
+
+## Debug Tricks
+
+See [debug-tricks.md](./debug-tricks.md) for:
+- MCP endpoint for AI-assisted debugging
+- Rebuild specific routes with `--debug-build-paths`
+
diff --git a/.agent/skills/next-best-practices/async-patterns.md b/.agent/skills/next-best-practices/async-patterns.md
new file mode 100644
index 00000000..dce8d8cc
--- /dev/null
+++ b/.agent/skills/next-best-practices/async-patterns.md
@@ -0,0 +1,87 @@
+# Async Patterns
+
+In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.
+
+## Async Params and SearchParams
+
+Always type them as `Promise<...>` and await them.
+
+### Pages and Layouts
+
+```tsx
+type Props = { params: Promise<{ slug: string }> }
+
+export default async function Page({ params }: Props) {
+ const { slug } = await params
+}
+```
+
+### Route Handlers
+
+```tsx
+export async function GET(
+ request: Request,
+ { params }: { params: Promise<{ id: string }> }
+) {
+ const { id } = await params
+}
+```
+
+### SearchParams
+
+```tsx
+type Props = {
+ params: Promise<{ slug: string }>
+ searchParams: Promise<{ query?: string }>
+}
+
+export default async function Page({ params, searchParams }: Props) {
+ const { slug } = await params
+ const { query } = await searchParams
+}
+```
+
+### Synchronous Components
+
+Use `React.use()` for non-async components:
+
+```tsx
+import { use } from 'react'
+
+type Props = { params: Promise<{ slug: string }> }
+
+export default function Page({ params }: Props) {
+ const { slug } = use(params)
+}
+```
+
+### generateMetadata
+
+```tsx
+type Props = { params: Promise<{ slug: string }> }
+
+export async function generateMetadata({ params }: Props): Promise {
+ const { slug } = await params
+ return { title: slug }
+}
+```
+
+## Async Cookies and Headers
+
+```tsx
+import { cookies, headers } from 'next/headers'
+
+export default async function Page() {
+ const cookieStore = await cookies()
+ const headersList = await headers()
+
+ const theme = cookieStore.get('theme')
+ const userAgent = headersList.get('user-agent')
+}
+```
+
+## Migration Codemod
+
+```bash
+npx @next/codemod@latest next-async-request-api .
+```
diff --git a/.agent/skills/next-best-practices/bundling.md b/.agent/skills/next-best-practices/bundling.md
new file mode 100644
index 00000000..ac5e814c
--- /dev/null
+++ b/.agent/skills/next-best-practices/bundling.md
@@ -0,0 +1,180 @@
+# Bundling
+
+Fix common bundling issues with third-party packages.
+
+## Server-Incompatible Packages
+
+Some packages use browser APIs (`window`, `document`, `localStorage`) and fail in Server Components.
+
+### Error Signs
+
+```
+ReferenceError: window is not defined
+ReferenceError: document is not defined
+ReferenceError: localStorage is not defined
+Module not found: Can't resolve 'fs'
+```
+
+### Solution 1: Mark as Client-Only
+
+If the package is only needed on client:
+
+```tsx
+// Bad: Fails - package uses window
+import SomeChart from 'some-chart-library'
+
+export default function Page() {
+ return /_next/mcp \
+ -H "Content-Type: application/json" \
+ -H "Accept: application/json, text/event-stream" \
+ -d '{
+ "jsonrpc": "2.0",
+ "id": "1",
+ "method": "tools/call",
+ "params": {
+ "name": "",
+ "arguments": {}
+ }
+ }'
+```
+
+### Available Tools
+
+#### `get_errors`
+Get current errors from dev server (build errors, runtime errors with source-mapped stacks):
+```json
+{ "name": "get_errors", "arguments": {} }
+```
+
+#### `get_routes`
+Discover all routes by scanning filesystem:
+```json
+{ "name": "get_routes", "arguments": {} }
+// Optional: { "name": "get_routes", "arguments": { "routerType": "app" } }
+```
+Returns: `{ "appRouter": ["/", "/api/users/[id]", ...], "pagesRouter": [...] }`
+
+#### `get_project_metadata`
+Get project path and dev server URL:
+```json
+{ "name": "get_project_metadata", "arguments": {} }
+```
+Returns: `{ "projectPath": "/path/to/project", "devServerUrl": "http://localhost:3000" }`
+
+#### `get_page_metadata`
+Get runtime metadata about current page render (requires active browser session):
+```json
+{ "name": "get_page_metadata", "arguments": {} }
+```
+Returns segment trie data showing layouts, boundaries, and page components.
+
+#### `get_logs`
+Get path to Next.js development log file:
+```json
+{ "name": "get_logs", "arguments": {} }
+```
+Returns path to `/logs/next-development.log`
+
+#### `get_server_action_by_id`
+Locate a Server Action by ID:
+```json
+{ "name": "get_server_action_by_id", "arguments": { "actionId": "" } }
+```
+
+### Example: Get Errors
+
+```bash
+curl -X POST http://localhost:/_next/mcp \
+ -H "Content-Type: application/json" \
+ -H "Accept: application/json, text/event-stream" \
+ -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"get_errors","arguments":{}}}'
+```
+
+## Rebuild Specific Routes (Next.js 16+)
+
+Use `--debug-build-paths` to rebuild only specific routes instead of the entire app:
+
+```bash
+# Rebuild a specific route
+next build --debug-build-paths "/dashboard"
+
+# Rebuild routes matching a glob
+next build --debug-build-paths "/api/*"
+
+# Dynamic routes
+next build --debug-build-paths "/blog/[slug]"
+```
+
+Use this to:
+- Quickly verify a build fix without full rebuild
+- Debug static generation issues for specific pages
+- Iterate faster on build errors
diff --git a/.agent/skills/next-best-practices/directives.md b/.agent/skills/next-best-practices/directives.md
new file mode 100644
index 00000000..1ea1637d
--- /dev/null
+++ b/.agent/skills/next-best-practices/directives.md
@@ -0,0 +1,73 @@
+# Directives
+
+## React Directives
+
+These are React directives, not Next.js specific.
+
+### `'use client'`
+
+Marks a component as a Client Component. Required for:
+- React hooks (`useState`, `useEffect`, etc.)
+- Event handlers (`onClick`, `onChange`)
+- Browser APIs (`window`, `localStorage`)
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+
+export function Counter() {
+ const [count, setCount] = useState(0)
+ return
+}
+```
+
+Reference: https://react.dev/reference/rsc/use-client
+
+### `'use server'`
+
+Marks a function as a Server Action. Can be passed to Client Components.
+
+```tsx
+'use server'
+
+export async function submitForm(formData: FormData) {
+ // Runs on server
+}
+```
+
+Or inline within a Server Component:
+
+```tsx
+export default function Page() {
+ async function submit() {
+ 'use server'
+ // Runs on server
+ }
+ return
+}
+```
+
+Reference: https://react.dev/reference/rsc/use-server
+
+---
+
+## Next.js Directive
+
+### `'use cache'`
+
+Marks a function or component for caching. Part of Next.js Cache Components.
+
+```tsx
+'use cache'
+
+export async function getCachedData() {
+ return await fetchData()
+}
+```
+
+Requires `cacheComponents: true` in `next.config.ts`.
+
+For detailed usage including cache profiles, `cacheLife()`, `cacheTag()`, and `updateTag()`, see the `next-cache-components` skill.
+
+Reference: https://nextjs.org/docs/app/api-reference/directives/use-cache
diff --git a/.agent/skills/next-best-practices/error-handling.md b/.agent/skills/next-best-practices/error-handling.md
new file mode 100644
index 00000000..663e37b6
--- /dev/null
+++ b/.agent/skills/next-best-practices/error-handling.md
@@ -0,0 +1,227 @@
+# Error Handling
+
+Handle errors gracefully in Next.js applications.
+
+Reference: https://nextjs.org/docs/app/getting-started/error-handling
+
+## Error Boundaries
+
+### `error.tsx`
+
+Catches errors in a route segment and its children:
+
+```tsx
+'use client'
+
+export default function Error({
+ error,
+ reset,
+}: {
+ error: Error & { digest?: string }
+ reset: () => void
+}) {
+ return (
+ ()
+useEffect(() => setTime(new Date().toLocaleString()), [])
+```
+
+### Random Values or IDs
+
+```tsx
+// Bad: Random values differ between server and client
+
+
+
+ )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
+
+### 6.2 CSS content-visibility for Long Lists
+
+**Impact: HIGH (faster initial render)**
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+ content-visibility: auto;
+ contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+ return (
+
+ {messages.map(msg => (
+
+ )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
+
+### 6.3 Hoist Static JSX Elements
+
+**Impact: LOW (avoids re-creation)**
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect: recreates element every render**
+
+```tsx
+function LoadingSkeleton() {
+ return
+}
+
+function Container() {
+ return (
+
+
+ ))}
+ {msg.content}
+
+ {loading &&
+ )
+}
+```
+
+**Correct: reuses same element**
+
+```tsx
+const loadingSkeleton = (
+
+)
+
+function Container() {
+ return (
+
+ {loading && loadingSkeleton}
+
+ )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
+
+### 6.4 Optimize SVG Precision
+
+**Impact: LOW (reduces file size)**
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect: excessive precision**
+
+```svg
+
+ {children}
+
+ )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect: visual flickering**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ const [theme, setTheme] = useState('light')
+
+ useEffect(() => {
+ // Runs after hydration - causes visible flash
+ const stored = localStorage.getItem('theme')
+ if (stored) {
+ setTheme(stored)
+ }
+ }, [])
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct: no flicker, no hydration mismatch**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ return (
+ <>
+
+ {children}
+
+
+
+ )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
+
+### 6.6 Suppress Expected Hydration Mismatches
+
+**Impact: LOW-MEDIUM (avoids noisy hydration warnings for known differences)**
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect: known mismatch warnings**
+
+```tsx
+function Timestamp() {
+ return {new Date().toLocaleString()}
+}
+```
+
+**Correct: suppress expected mismatch only**
+
+```tsx
+function Timestamp() {
+ return (
+
+ {new Date().toLocaleString()}
+
+ )
+}
+```
+
+### 6.7 Use Activity Component for Show/Hide
+
+**Impact: MEDIUM (preserves state/DOM)**
+
+Use React's `
+ {count && {count}}
+
+ )
+}
+
+// When count = 0, renders: 0
+// When count = 5, renders: 5
+```
+
+**Correct: renders nothing when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+ return (
+
+ {count > 0 ? {count} : null}
+
+ )
+}
+
+// When count = 0, renders:
+// When count = 5, renders: 5
+```
+
+### 6.10 Use React DOM Resource Hints
+
+**Impact: HIGH (reduces load time for critical resources)**
+
+React DOM provides APIs to hint the browser about resources it will need. These are especially useful in server components to start loading resources before the client even receives the HTML.
+
+- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to
+
+- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server
+
+- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon
+
+- **`preloadModule(href)`**: Fetch an ES module you'll use soon
+
+- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script
+
+- **`preinitModule(href)`**: Fetch and evaluate an ES module
+
+**Example: preconnect to third-party APIs**
+
+```tsx
+import { preconnect, prefetchDNS } from 'react-dom'
+
+export default function App() {
+ prefetchDNS('https://analytics.example.com')
+ preconnect('https://api.example.com')
+
+ return Content
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+ return (
+
+ Content
+
+ )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
+
+### 7.2 Build Index Maps for Repeated Lookups
+
+**Impact: LOW-MEDIUM (1M ops to 2K ops)**
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+ return orders.map(order => ({
+ ...order,
+ user: users.find(u => u.id === order.userId)
+ }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+ const userById = new Map(users.map(u => [u.id, u]))
+
+ return orders.map(order => ({
+ ...order,
+ user: userById.get(order.userId)
+ }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+
+For 1000 orders × 1000 users: 1M ops → 2K ops.
+
+### 7.3 Cache Property Access in Loops
+
+**Impact: LOW-MEDIUM (reduces lookups)**
+
+Cache object property lookups in hot paths.
+
+**Incorrect: 3 lookups × N iterations**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+ process(obj.config.settings.value)
+}
+```
+
+**Correct: 1 lookup total**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+ process(value)
+}
+```
+
+### 7.4 Cache Repeated Function Calls
+
+**Impact: MEDIUM (avoid redundant computation)**
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect: redundant computation**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+ return (
+
+ {projects.map(project => {
+ // slugify() called 100+ times for same project names
+ const slug = slugify(project.name)
+
+ return
+ )
+}
+```
+
+**Correct: cached results**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map
+ {projects.map(project => {
+ // Computed only once per unique project name
+ const slug = cachedSlugify(project.name)
+
+ return
+ )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+ if (isLoggedInCache !== null) {
+ return isLoggedInCache
+ }
+
+ isLoggedInCache = document.cookie.includes('auth=')
+ return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+ isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
+
+### 7.5 Cache Storage API Calls
+
+**Impact: LOW-MEDIUM (reduces expensive I/O)**
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect: reads storage on every call**
+
+```typescript
+function getTheme() {
+ return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct: Map cache**
+
+```typescript
+const storageCache = new Map{sorted.map(renderUser)}
+}
+```
+
+**Correct: creates new array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+ // Creates new sorted array, original unchanged
+ const sorted = useMemo(
+ () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+ [users]
+ )
+ return {sorted.map(renderUser)}
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support: fallback for older browsers**
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+
+- `.toReversed()` - immutable reverse
+
+- `.toSpliced()` - immutable splice
+
+- `.with()` - immutable element replacement
+
+---
+
+## 8. Advanced Patterns
+
+**Impact: LOW**
+
+Advanced patterns for specific cases that require careful implementation.
+
+### 8.1 Initialize App Once, Not Per Mount
+
+**Impact: LOW-MEDIUM (avoids duplicate init in development)**
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect: runs twice in dev, re-runs on remount**
+
+```tsx
+function Comp() {
+ useEffect(() => {
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+**Correct: once per app load**
+
+```tsx
+let didInit = false
+
+function Comp() {
+ useEffect(() => {
+ if (didInit) return
+ didInit = true
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+Reference: [https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+### 8.2 Store Event Handlers in Refs
+
+**Impact: LOW (stable subscriptions)**
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect: re-subscribes on every render**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+ useEffect(() => {
+ window.addEventListener(event, handler)
+ return () => window.removeEventListener(event, handler)
+ }, [event, handler])
+}
+```
+
+**Correct: stable subscription**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+ const onEvent = useEffectEvent(handler)
+
+ useEffect(() => {
+ window.addEventListener(event, onEvent)
+ return () => window.removeEventListener(event, onEvent)
+ }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+### 8.3 useEffectEvent for Stable Callback Refs
+
+**Impact: LOW (prevents effect re-runs)**
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect: effect re-runs on every callback change**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+ const [query, setQuery] = useState('')
+
+ useEffect(() => {
+ const timeout = setTimeout(() => onSearch(query), 300)
+ return () => clearTimeout(timeout)
+ }, [query, onSearch])
+}
+```
+
+**Correct: using React's useEffectEvent**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+ const [query, setQuery] = useState('')
+ const onSearchEvent = useEffectEvent(onSearch)
+
+ useEffect(() => {
+ const timeout = setTimeout(() => onSearchEvent(query), 300)
+ return () => clearTimeout(timeout)
+ }, [query])
+}
+```
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://nextjs.org](https://nextjs.org)
+3. [https://swr.vercel.app](https://swr.vercel.app)
+4. [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+5. [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+6. [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+7. [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/.adal/skills/vercel-react-best-practices/SKILL.md b/.adal/skills/vercel-react-best-practices/SKILL.md
new file mode 100644
index 00000000..4417c6ae
--- /dev/null
+++ b/.adal/skills/vercel-react-best-practices/SKILL.md
@@ -0,0 +1,141 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+ author: vercel
+ version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 62 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-auth-actions` - Authenticate server actions like API routes
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-dedup-props` - Avoid duplicate serialization in RSC props
+- `server-hoist-static-io` - Hoist static I/O (fonts, logos) to module level
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+- `rerender-no-inline-components` - Don't define components inside components
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-hydration-suppress-warning` - Suppress expected mismatches
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Prefer useTransition for loading state
+- `rendering-resource-hints` - Use React DOM resource hints for preloading
+- `rendering-script-defer-async` - Use defer or async on script tags
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+- `js-flatmap-filter` - Use flatMap to map and filter in one pass
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/.agent/skills/deploy-to-vercel/Archive.zip b/.agent/skills/deploy-to-vercel/Archive.zip
new file mode 100644
index 00000000..2945baff
Binary files /dev/null and b/.agent/skills/deploy-to-vercel/Archive.zip differ
diff --git a/.agent/skills/deploy-to-vercel/SKILL.md b/.agent/skills/deploy-to-vercel/SKILL.md
new file mode 100644
index 00000000..a0251ce8
--- /dev/null
+++ b/.agent/skills/deploy-to-vercel/SKILL.md
@@ -0,0 +1,296 @@
+---
+name: deploy-to-vercel
+description: Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".
+metadata:
+ author: vercel
+ version: "3.0.0"
+---
+
+# Deploy to Vercel
+
+Deploy any project to Vercel. **Always deploy as preview** (not production) unless the user explicitly asks for production.
+
+The goal is to get the user into the best long-term setup: their project linked to Vercel with git-push deploys. Every method below tries to move the user closer to that state.
+
+## Step 1: Gather Project State
+
+Run all four checks before deciding which method to use:
+
+```bash
+# 1. Check for a git remote
+git remote get-url origin 2>/dev/null
+
+# 2. Check if locally linked to a Vercel project (either file means linked)
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+
+# 3. Check if the Vercel CLI is installed and authenticated
+vercel whoami 2>/dev/null
+
+# 4. List available teams (if authenticated)
+vercel teams list --format json 2>/dev/null
+```
+
+### Team selection
+
+If the user belongs to multiple teams, present all available team slugs as a bulleted list and ask which one to deploy to. Once the user picks a team, proceed immediately to the next step — do not ask for additional confirmation.
+
+Pass the team slug via `--scope` on all subsequent CLI commands (`vercel deploy`, `vercel link`, `vercel inspect`, etc.):
+
+```bash
+vercel deploy [path] -y --no-wait --scope -
+ {users.map(user =>
- {user.name} )} +
...
;
+}
+```
+
+### Solution 1: Parallel Fetching with Promise.all
+
+```tsx
+// Good: Parallel fetching
+async function Dashboard() {
+ const [user, posts, comments] = await Promise.all([
+ getUser(),
+ getPosts(),
+ getComments(),
+ ]);
+
+ return ...
;
+}
+```
+
+### Solution 2: Streaming with Suspense
+
+```tsx
+// Good: Show content progressively
+import { Suspense } from 'react';
+
+async function Dashboard() {
+ return (
+
+
+ );
+}
+
+async function UserSection() {
+ const user = await getUser(); // Fetches independently
+ return {user.name}
;
+}
+
+async function PostsSection() {
+ const posts = await getPosts(); // Fetches independently
+ return {user.name}
;
+}
+```
+
+## Client Component Data Fetching
+
+When Client Components need data:
+
+### Option 1: Pass from Server Component (Preferred)
+
+```tsx
+// Server Component
+async function Page() {
+ const data = await fetchData();
+ return {data.value}
;
+}
+```
+
+### Option 3: Server Action for Reads (Works But Not Ideal)
+
+Server Actions can be called from Client Components for reads, but this is not their intended purpose:
+
+```tsx
+'use client';
+import { getData } from './actions';
+import { useEffect, useState } from 'react';
+
+function ClientComponent() {
+ const [data, setData] = useState(null);
+
+ useEffect(() => {
+ getData().then(setData);
+ }, []);
+
+ return {data?.value}
;
+}
+```
+
+**Note**: Server Actions always use POST, so no HTTP caching. Prefer Route Handlers for cacheable reads.
+
+## Quick Reference
+
+| Pattern | Use Case | HTTP Method | Caching |
+|---------|----------|-------------|---------|
+| Server Component fetch | Internal reads | Any | Full Next.js caching |
+| Server Action | Mutations, form submissions | POST only | No |
+| Route Handler | External APIs, webhooks | Any | GET can be cached |
+| Client fetch to API | Client-side reads | Any | HTTP cache headers |
diff --git a/.agent/skills/next-best-practices/debug-tricks.md b/.agent/skills/next-best-practices/debug-tricks.md
new file mode 100644
index 00000000..9151ce66
--- /dev/null
+++ b/.agent/skills/next-best-practices/debug-tricks.md
@@ -0,0 +1,105 @@
+# Debug Tricks
+
+Tricks to speed up debugging Next.js applications.
+
+## MCP Endpoint (Dev Server)
+
+Next.js exposes a `/_next/mcp` endpoint in development for AI-assisted debugging via MCP (Model Context Protocol).
+
+- **Next.js 16+**: Enabled by default, use `next-devtools-mcp`
+- **Next.js < 16**: Requires `experimental.mcpServer: true` in next.config.js
+
+Reference: https://nextjs.org/docs/app/guides/mcp
+
+**Important**: Find the actual port of the running Next.js dev server (check terminal output or `package.json` scripts). Don't assume port 3000.
+
+### Request Format
+
+The endpoint uses JSON-RPC 2.0 over HTTP POST:
+
+```bash
+curl -X POST http://localhost:
+
+ )
+}
+```
+
+**Important:** `error.tsx` must be a Client Component.
+
+### `global-error.tsx`
+
+Catches errors in root layout:
+
+```tsx
+'use client'
+
+export default function GlobalError({
+ error,
+ reset,
+}: {
+ error: Error & { digest?: string }
+ reset: () => void
+}) {
+ return (
+
+
+ Something went wrong!
+ +Something went wrong!
+ + + + ) +} +``` + +**Important:** Must include `` and `` tags. + +## Server Actions: Navigation API Gotcha + +**Do NOT wrap navigation APIs in try-catch.** They throw special errors that Next.js handles internally. + +Reference: https://nextjs.org/docs/app/api-reference/functions/redirect#behavior + +```tsx +'use server' + +import { redirect } from 'next/navigation' +import { notFound } from 'next/navigation' + +// Bad: try-catch catches the navigation "error" +async function createPost(formData: FormData) { + try { + const post = await db.post.create({ ... }) + redirect(`/posts/${post.id}`) // This throws! + } catch (error) { + // redirect() throw is caught here - navigation fails! + return { error: 'Failed to create post' } + } +} + +// Good: Call navigation APIs outside try-catch +async function createPost(formData: FormData) { + let post + try { + post = await db.post.create({ ... }) + } catch (error) { + return { error: 'Failed to create post' } + } + redirect(`/posts/${post.id}`) // Outside try-catch +} + +// Good: Re-throw navigation errors +async function createPost(formData: FormData) { + try { + const post = await db.post.create({ ... }) + redirect(`/posts/${post.id}`) + } catch (error) { + if (error instanceof Error && error.message === 'NEXT_REDIRECT') { + throw error // Re-throw navigation errors + } + return { error: 'Failed to create post' } + } +} +``` + +Same applies to: +- `redirect()` - 307 temporary redirect +- `permanentRedirect()` - 308 permanent redirect +- `notFound()` - 404 not found +- `forbidden()` - 403 forbidden +- `unauthorized()` - 401 unauthorized + +Use `unstable_rethrow()` to re-throw these errors in catch blocks: + +```tsx +import { unstable_rethrow } from 'next/navigation' + +async function action() { + try { + // ... + redirect('/success') + } catch (error) { + unstable_rethrow(error) // Re-throws Next.js internal errors + return { error: 'Something went wrong' } + } +} +``` + +## Redirects + +```tsx +import { redirect, permanentRedirect } from 'next/navigation' + +// 307 Temporary - use for most cases +redirect('/new-path') + +// 308 Permanent - use for URL migrations (cached by browsers) +permanentRedirect('/new-url') +``` + +## Auth Errors + +Trigger auth-related error pages: + +```tsx +import { forbidden, unauthorized } from 'next/navigation' + +async function Page() { + const session = await getSession() + + if (!session) { + unauthorized() // Renders unauthorized.tsx (401) + } + + if (!session.hasAccess) { + forbidden() // Renders forbidden.tsx (403) + } + + returnYou don't have access to this resource
+}
+
+// app/unauthorized.tsx
+export default function Unauthorized() {
+ return Please log in to continue
+}
+```
+
+## Not Found
+
+### `not-found.tsx`
+
+Custom 404 page for a route segment:
+
+```tsx
+export default function NotFound() {
+ return (
+
+
+ )
+}
+```
+
+### Triggering Not Found
+
+```tsx
+import { notFound } from 'next/navigation'
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+ const { id } = await params
+ const post = await getPost(id)
+
+ if (!post) {
+ notFound() // Renders closest not-found.tsx
+ }
+
+ return Not Found
+Could not find the requested resource
+{post.title}
+}
+```
+
+## Error Hierarchy
+
+Errors bubble up to the nearest error boundary:
+
+```
+app/
+├── error.tsx # Catches errors from all children
+├── blog/
+│ ├── error.tsx # Catches errors in /blog/*
+│ └── [slug]/
+│ ├── error.tsx # Catches errors in /blog/[slug]
+│ └── page.tsx
+└── layout.tsx # Errors here go to global-error.tsx
+```
diff --git a/.agent/skills/next-best-practices/file-conventions.md b/.agent/skills/next-best-practices/file-conventions.md
new file mode 100644
index 00000000..c2b3b406
--- /dev/null
+++ b/.agent/skills/next-best-practices/file-conventions.md
@@ -0,0 +1,140 @@
+# File Conventions
+
+Next.js App Router uses file-based routing with special file conventions.
+
+## Project Structure
+
+Reference: https://nextjs.org/docs/app/getting-started/project-structure
+
+```
+app/
+├── layout.tsx # Root layout (required)
+├── page.tsx # Home page (/)
+├── loading.tsx # Loading UI
+├── error.tsx # Error UI
+├── not-found.tsx # 404 UI
+├── global-error.tsx # Global error UI
+├── route.ts # API endpoint
+├── template.tsx # Re-rendered layout
+├── default.tsx # Parallel route fallback
+├── blog/
+│ ├── page.tsx # /blog
+│ └── [slug]/
+│ └── page.tsx # /blog/:slug
+└── (group)/ # Route group (no URL impact)
+ └── page.tsx
+```
+
+## Special Files
+
+| File | Purpose |
+|------|---------|
+| `page.tsx` | UI for a route segment |
+| `layout.tsx` | Shared UI for segment and children |
+| `loading.tsx` | Loading UI (Suspense boundary) |
+| `error.tsx` | Error UI (Error boundary) |
+| `not-found.tsx` | 404 UI |
+| `route.ts` | API endpoint |
+| `template.tsx` | Like layout but re-renders on navigation |
+| `default.tsx` | Fallback for parallel routes |
+
+## Route Segments
+
+```
+app/
+├── blog/ # Static segment: /blog
+├── [slug]/ # Dynamic segment: /:slug
+├── [...slug]/ # Catch-all: /a/b/c
+├── [[...slug]]/ # Optional catch-all: / or /a/b/c
+└── (marketing)/ # Route group (ignored in URL)
+```
+
+## Parallel Routes
+
+```
+app/
+├── @analytics/
+│ └── page.tsx
+├── @sidebar/
+│ └── page.tsx
+└── layout.tsx # Receives { analytics, sidebar } as props
+```
+
+## Intercepting Routes
+
+```
+app/
+├── feed/
+│ └── page.tsx
+├── @modal/
+│ └── (.)photo/[id]/ # Intercepts /photo/[id] from /feed
+│ └── page.tsx
+└── photo/[id]/
+ └── page.tsx
+```
+
+Conventions:
+- `(.)` - same level
+- `(..)` - one level up
+- `(..)(..)` - two levels up
+- `(...)` - from root
+
+## Private Folders
+
+```
+app/
+├── _components/ # Private folder (not a route)
+│ └── Button.tsx
+└── page.tsx
+```
+
+Prefix with `_` to exclude from routing.
+
+## Middleware / Proxy
+
+### Next.js 14-15: `middleware.ts`
+
+```ts
+// middleware.ts (root of project)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+ // Auth, redirects, rewrites, etc.
+ return NextResponse.next();
+}
+
+export const config = {
+ matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+
+### Next.js 16+: `proxy.ts`
+
+Renamed for clarity - same capabilities, different names:
+
+```ts
+// proxy.ts (root of project)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function proxy(request: NextRequest) {
+ // Same logic as middleware
+ return NextResponse.next();
+}
+
+export const proxyConfig = {
+ matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+
+| Version | File | Export | Config |
+|---------|------|--------|--------|
+| v14-15 | `middleware.ts` | `middleware()` | `config` |
+| v16+ | `proxy.ts` | `proxy()` | `proxyConfig` |
+
+**Migration**: Run `npx @next/codemod@latest upgrade` to auto-rename.
+
+## File Conventions Reference
+
+Reference: https://nextjs.org/docs/app/api-reference/file-conventions
diff --git a/.agent/skills/next-best-practices/font.md b/.agent/skills/next-best-practices/font.md
new file mode 100644
index 00000000..7e526850
--- /dev/null
+++ b/.agent/skills/next-best-practices/font.md
@@ -0,0 +1,245 @@
+# Font Optimization
+
+Use `next/font` for automatic font optimization with zero layout shift.
+
+## Google Fonts
+
+```tsx
+// app/layout.tsx
+import { Inter } from 'next/font/google'
+
+const inter = Inter({ subsets: ['latin'] })
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ )
+}
+```
+
+## Multiple Fonts
+
+```tsx
+import { Inter, Roboto_Mono } from 'next/font/google'
+
+const inter = Inter({
+ subsets: ['latin'],
+ variable: '--font-inter',
+})
+
+const robotoMono = Roboto_Mono({
+ subsets: ['latin'],
+ variable: '--font-roboto-mono',
+})
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ )
+}
+```
+
+Use in CSS:
+```css
+body {
+ font-family: var(--font-inter);
+}
+
+code {
+ font-family: var(--font-roboto-mono);
+}
+```
+
+## Font Weights and Styles
+
+```tsx
+// Single weight
+const inter = Inter({
+ subsets: ['latin'],
+ weight: '400',
+})
+
+// Multiple weights
+const inter = Inter({
+ subsets: ['latin'],
+ weight: ['400', '500', '700'],
+})
+
+// Variable font (recommended) - includes all weights
+const inter = Inter({
+ subsets: ['latin'],
+ // No weight needed - variable fonts support all weights
+})
+
+// With italic
+const inter = Inter({
+ subsets: ['latin'],
+ style: ['normal', 'italic'],
+})
+```
+
+## Local Fonts
+
+```tsx
+import localFont from 'next/font/local'
+
+const myFont = localFont({
+ src: './fonts/MyFont.woff2',
+})
+
+// Multiple files for different weights
+const myFont = localFont({
+ src: [
+ {
+ path: './fonts/MyFont-Regular.woff2',
+ weight: '400',
+ style: 'normal',
+ },
+ {
+ path: './fonts/MyFont-Bold.woff2',
+ weight: '700',
+ style: 'normal',
+ },
+ ],
+})
+
+// Variable font
+const myFont = localFont({
+ src: './fonts/MyFont-Variable.woff2',
+ variable: '--font-my-font',
+})
+```
+
+## Tailwind CSS Integration
+
+```tsx
+// app/layout.tsx
+import { Inter } from 'next/font/google'
+
+const inter = Inter({
+ subsets: ['latin'],
+ variable: '--font-inter',
+})
+
+export default function RootLayout({ children }) {
+ return (
+
+ {children}
+
+ )
+}
+```
+
+```js
+// tailwind.config.js
+module.exports = {
+ theme: {
+ extend: {
+ fontFamily: {
+ sans: ['var(--font-inter)'],
+ },
+ },
+ },
+}
+```
+
+## Preloading Subsets
+
+Only load needed character subsets:
+
+```tsx
+// Latin only (most common)
+const inter = Inter({ subsets: ['latin'] })
+
+// Multiple subsets
+const inter = Inter({ subsets: ['latin', 'latin-ext', 'cyrillic'] })
+```
+
+## Display Strategy
+
+Control font loading behavior:
+
+```tsx
+const inter = Inter({
+ subsets: ['latin'],
+ display: 'swap', // Default - shows fallback, swaps when loaded
+})
+
+// Options:
+// 'auto' - browser decides
+// 'block' - short block period, then swap
+// 'swap' - immediate fallback, swap when ready (recommended)
+// 'fallback' - short block, short swap, then fallback
+// 'optional' - short block, no swap (use if font is optional)
+```
+
+## Don't Use Manual Font Links
+
+Always use `next/font` instead of `` tags for Google Fonts.
+
+```tsx
+// Bad: Manual link tag (blocks rendering, no optimization)
+
+
+// Bad: Missing display and preconnect
+
+
+// Good: Use next/font (self-hosted, zero layout shift)
+import { Inter } from 'next/font/google'
+
+const inter = Inter({ subsets: ['latin'] })
+```
+
+## Common Mistakes
+
+```tsx
+// Bad: Importing font in every component
+// components/Button.tsx
+import { Inter } from 'next/font/google'
+const inter = Inter({ subsets: ['latin'] }) // Creates new instance each time!
+
+// Good: Import once in layout, use CSS variable
+// app/layout.tsx
+const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
+
+// Bad: Using @import in CSS (blocks rendering)
+/* globals.css */
+@import url('https://fonts.googleapis.com/css2?family=Inter');
+
+// Good: Use next/font (self-hosted, no network request)
+import { Inter } from 'next/font/google'
+
+// Bad: Loading all weights when only using a few
+const inter = Inter({ subsets: ['latin'] }) // Loads all weights
+
+// Good: Specify only needed weights (for non-variable fonts)
+const inter = Inter({ subsets: ['latin'], weight: ['400', '700'] })
+
+// Bad: Missing subset - loads all characters
+const inter = Inter({})
+
+// Good: Always specify subset
+const inter = Inter({ subsets: ['latin'] })
+```
+
+## Font in Specific Components
+
+```tsx
+// For component-specific fonts, export from a shared file
+// lib/fonts.ts
+import { Inter, Playfair_Display } from 'next/font/google'
+
+export const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
+export const playfair = Playfair_Display({ subsets: ['latin'], variable: '--font-playfair' })
+
+// components/Heading.tsx
+import { playfair } from '@/lib/fonts'
+
+export function Heading({ children }) {
+ return {children}
+} +``` diff --git a/.agent/skills/next-best-practices/functions.md b/.agent/skills/next-best-practices/functions.md new file mode 100644 index 00000000..8f28a8b6 --- /dev/null +++ b/.agent/skills/next-best-practices/functions.md @@ -0,0 +1,108 @@ +# Functions + +Next.js function APIs. + +Reference: https://nextjs.org/docs/app/api-reference/functions + +## Navigation Hooks (Client) + +| Hook | Purpose | Reference | +|------|---------|-----------| +| `useRouter` | Programmatic navigation (`push`, `replace`, `back`, `refresh`) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-router) | +| `usePathname` | Get current pathname | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-pathname) | +| `useSearchParams` | Read URL search parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-search-params) | +| `useParams` | Access dynamic route parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-params) | +| `useSelectedLayoutSegment` | Active child segment (one level) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segment) | +| `useSelectedLayoutSegments` | All active segments below layout | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segments) | +| `useLinkStatus` | Check link prefetch status | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-link-status) | +| `useReportWebVitals` | Report Core Web Vitals metrics | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-report-web-vitals) | + +## Server Functions + +| Function | Purpose | Reference | +|----------|---------|-----------| +| `cookies` | Read/write cookies | [Docs](https://nextjs.org/docs/app/api-reference/functions/cookies) | +| `headers` | Read request headers | [Docs](https://nextjs.org/docs/app/api-reference/functions/headers) | +| `draftMode` | Enable preview of unpublished CMS content | [Docs](https://nextjs.org/docs/app/api-reference/functions/draft-mode) | +| `after` | Run code after response finishes streaming | [Docs](https://nextjs.org/docs/app/api-reference/functions/after) | +| `connection` | Wait for connection before dynamic rendering | [Docs](https://nextjs.org/docs/app/api-reference/functions/connection) | +| `userAgent` | Parse User-Agent header | [Docs](https://nextjs.org/docs/app/api-reference/functions/userAgent) | + +## Generate Functions + +| Function | Purpose | Reference | +|----------|---------|-----------| +| `generateStaticParams` | Pre-render dynamic routes at build time | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) | +| `generateMetadata` | Dynamic metadata | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) | +| `generateViewport` | Dynamic viewport config | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-viewport) | +| `generateSitemaps` | Multiple sitemaps for large sites | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-sitemaps) | +| `generateImageMetadata` | Multiple OG images per route | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-image-metadata) | + +## Request/Response + +| Function | Purpose | Reference | +|----------|---------|-----------| +| `NextRequest` | Extended Request with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-request) | +| `NextResponse` | Extended Response with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-response) | +| `ImageResponse` | Generate OG images | [Docs](https://nextjs.org/docs/app/api-reference/functions/image-response) | + +## Common Examples + +### Navigation + +Use `next/link` for internal navigation instead of `` tags. + +```tsx +// Bad: Plain anchor tag +About + +// Good: Next.js Link +import Link from 'next/link' + +About +``` + +Active link styling: + +```tsx +'use client' + +import Link from 'next/link' +import { usePathname } from 'next/navigation' + +export function NavLink({ href, children }) { + const pathname = usePathname() + + return ( + + {children} + + ) +} +``` + +### Static Generation + +```tsx +// app/blog/[slug]/page.tsx +export async function generateStaticParams() { + const posts = await getPosts() + return posts.map((post) => ({ slug: post.slug })) +} +``` + +### After Response + +```tsx +import { after } from 'next/server' + +export async function POST(request: Request) { + const data = await processRequest(request) + + after(async () => { + await logAnalytics(data) + }) + + return Response.json({ success: true }) +} +``` diff --git a/.agent/skills/next-best-practices/hydration-error.md b/.agent/skills/next-best-practices/hydration-error.md new file mode 100644 index 00000000..36d48295 --- /dev/null +++ b/.agent/skills/next-best-practices/hydration-error.md @@ -0,0 +1,91 @@ +# Hydration Errors + +Diagnose and fix React hydration mismatch errors. + +## Error Signs + +- "Hydration failed because the initial UI does not match" +- "Text content does not match server-rendered HTML" + +## Debugging + +In development, click the hydration error to see the server/client diff. + +## Common Causes and Fixes + +### Browser-only APIs + +```tsx +// Bad: Causes mismatch - window doesn't exist on server +{window.innerWidth}
+
+// Good: Use client component with mounted check
+'use client'
+import { useState, useEffect } from 'react'
+
+export function ClientOnly({ children }: { children: React.ReactNode }) {
+ const [mounted, setMounted] = useState(false)
+ useEffect(() => setMounted(true), [])
+ return mounted ? children : null
+}
+```
+
+### Date/Time Rendering
+
+Server and client may be in different timezones:
+
+```tsx
+// Bad: Causes mismatch
+{new Date().toLocaleString()}
+
+// Good: Render on client only
+'use client'
+const [time, setTime] = useState
+
+// Good: Use useId hook
+import { useId } from 'react'
+
+function Input() {
+ const id = useId()
+ return
+}
+```
+
+### Invalid HTML Nesting
+
+```tsx
+// Bad: Invalid - div inside p
+
+```
+
+### Third-party Scripts
+
+Scripts that modify DOM during hydration.
+
+```tsx
+// Good: Use next/script with afterInteractive
+import Script from 'next/script'
+
+export default function Page() {
+ return (
+
+ )
+}
+```
diff --git a/.agent/skills/next-best-practices/image.md b/.agent/skills/next-best-practices/image.md
new file mode 100644
index 00000000..aa9d28db
--- /dev/null
+++ b/.agent/skills/next-best-practices/image.md
@@ -0,0 +1,173 @@
+# Image Optimization
+
+Use `next/image` for automatic image optimization.
+
+## Always Use next/image
+
+```tsx
+// Bad: Avoid native img
+
+
+// Good: Use next/image
+import Image from 'next/image'
+ {
+ const { slug } = await params
+ const post = await getPost(slug)
+ return { title: post.title, description: post.description }
+}
+```
+
+## Avoid Duplicate Fetches
+
+Use React `cache()` when the same data is needed for both metadata and page:
+
+```tsx
+import { cache } from 'react'
+
+export const getPost = cache(async (slug: string) => {
+ return await db.posts.findFirst({ where: { slug } })
+})
+```
+
+## Viewport
+
+Separate from metadata for streaming support:
+
+```tsx
+import type { Viewport } from 'next'
+
+export const viewport: Viewport = {
+ width: 'device-width',
+ initialScale: 1,
+ themeColor: '#000000',
+}
+
+// Or dynamic
+export function generateViewport({ params }): Viewport {
+ return { themeColor: getThemeColor(params) }
+}
+```
+
+## Title Templates
+
+In root layout for consistent naming:
+
+```tsx
+export const metadata: Metadata = {
+ title: { default: 'Site Name', template: '%s | Site Name' },
+}
+```
+
+## Metadata File Conventions
+
+Reference: https://nextjs.org/docs/app/getting-started/project-structure#metadata-file-conventions
+
+Place these files in `app/` directory (or route segments):
+
+| File | Purpose |
+|------|---------|
+| `favicon.ico` | Favicon |
+| `icon.png` / `icon.svg` | App icon |
+| `apple-icon.png` | Apple app icon |
+| `opengraph-image.png` | OG image |
+| `twitter-image.png` | Twitter card image |
+| `sitemap.ts` / `sitemap.xml` | Sitemap (use `generateSitemaps` for multiple) |
+| `robots.ts` / `robots.txt` | Robots directives |
+| `manifest.ts` / `manifest.json` | Web app manifest |
+
+## SEO Best Practice: Static Files Are Often Enough
+
+For most sites, **static metadata files provide excellent SEO coverage**:
+
+```
+app/
+├── favicon.ico
+├── opengraph-image.png # Works for both OG and Twitter
+├── sitemap.ts
+├── robots.ts
+└── layout.tsx # With title/description metadata
+```
+
+**Tips:**
+- A single `opengraph-image.png` covers both Open Graph and Twitter (Twitter falls back to OG)
+- Static `title` and `description` in layout metadata is sufficient for most pages
+- Only use dynamic `generateMetadata` when content varies per page
+
+---
+
+# OG Image Generation
+
+Generate dynamic Open Graph images using `next/og`.
+
+## Important Rules
+
+1. **Use `next/og`** - not `@vercel/og` (it's built into Next.js)
+2. **No searchParams** - OG images can't access search params, use route params instead
+3. **Avoid Edge runtime** - Use default Node.js runtime
+
+```tsx
+// Good
+import { ImageResponse } from 'next/og'
+
+// Bad
+// import { ImageResponse } from '@vercel/og'
+// export const runtime = 'edge'
+```
+
+## Basic OG Image
+
+```tsx
+// app/opengraph-image.tsx
+import { ImageResponse } from 'next/og'
+
+export const alt = 'Site Name'
+export const size = { width: 1200, height: 630 }
+export const contentType = 'image/png'
+
+export default function Image() {
+ return new ImageResponse(
+ (
+ {
+ const start = id * 50000
+ const end = start + 50000
+ const products = await getProducts(start, end)
+
+ return products.map((product) => ({
+ url: `https://example.com/product/${product.id}`,
+ lastModified: product.updatedAt,
+ }))
+}
+```
+
+Generates `/sitemap/0.xml`, `/sitemap/1.xml`, etc.
diff --git a/.agent/skills/next-best-practices/parallel-routes.md b/.agent/skills/next-best-practices/parallel-routes.md
new file mode 100644
index 00000000..51e270d8
--- /dev/null
+++ b/.agent/skills/next-best-practices/parallel-routes.md
@@ -0,0 +1,287 @@
+# Parallel & Intercepting Routes
+
+Parallel routes render multiple pages in the same layout. Intercepting routes show a different UI when navigating from within your app vs direct URL access. Together they enable modal patterns.
+
+## File Structure
+
+```
+app/
+├── @modal/ # Parallel route slot
+│ ├── default.tsx # Required! Returns null
+│ ├── (.)photos/ # Intercepts /photos/*
+│ │ └── [id]/
+│ │ └── page.tsx # Modal content
+│ └── [...]catchall/ # Optional: catch unmatched
+│ └── page.tsx
+├── photos/
+│ └── [id]/
+│ └── page.tsx # Full page (direct access)
+├── layout.tsx # Renders both children and @modal
+└── page.tsx
+```
+
+## Step 1: Root Layout with Slot
+
+```tsx
+// app/layout.tsx
+export default function RootLayout({
+ children,
+ modal,
+}: {
+ children: React.ReactNode;
+ modal: React.ReactNode;
+}) {
+ return (
+
+
+ {children}
+ {modal}
+
+
+ );
+}
+```
+
+## Step 2: Default File (Critical!)
+
+**Every parallel route slot MUST have a `default.tsx`** to prevent 404s on hard navigation.
+
+```tsx
+// app/@modal/default.tsx
+export default function Default() {
+ return null;
+}
+```
+
+Without this file, refreshing any page will 404 because Next.js can't determine what to render in the `@modal` slot.
+
+## Step 3: Intercepting Route (Modal)
+
+The `(.)` prefix intercepts routes at the same level.
+
+```tsx
+// app/@modal/(.)photos/[id]/page.tsx
+import { Modal } from '@/components/modal';
+
+export default async function PhotoModal({
+ params
+}: {
+ params: Promise<{ id: string }>
+}) {
+ const { id } = await params;
+ const photo = await getPhoto(id);
+
+ return (
+
+ 
+
+ );
+}
+```
+
+## Step 4: Full Page (Direct Access)
+
+```tsx
+// app/photos/[id]/page.tsx
+export default async function PhotoPage({
+ params
+}: {
+ params: Promise<{ id: string }>
+}) {
+ const { id } = await params;
+ const photo = await getPhoto(id);
+
+ return (
+ (null);
+
+ // Close on escape key
+ useEffect(() => {
+ function onKeyDown(e: KeyboardEvent) {
+ if (e.key === 'Escape') {
+ router.back(); // Correct
+ }
+ }
+ document.addEventListener('keydown', onKeyDown);
+ return () => document.removeEventListener('keydown', onKeyDown);
+ }, [router]);
+
+ // Close on overlay click
+ const handleOverlayClick = useCallback((e: React.MouseEvent) => {
+ if (e.target === overlayRef.current) {
+ router.back(); // Correct
+ }
+ }, [router]);
+
+ return (
+
+
+
+ );
+}
+```
+
+## Common Gotchas
+
+### 1. Missing `default.tsx` → 404 on Refresh
+
+Every `@slot` folder needs a `default.tsx` that returns `null` (or appropriate content).
+
+### 2. Modal Persists After Navigation
+
+You're using `router.push()` instead of `router.back()`.
+
+### 3. Nested Parallel Routes Need Defaults Too
+
+If you have `@modal` inside a route group, each level needs its own `default.tsx`:
+
+```
+app/
+├── (marketing)/
+│ ├── @modal/
+│ │ └── default.tsx # Needed!
+│ └── layout.tsx
+└── layout.tsx
+```
+
+### 4. Intercepted Route Shows Wrong Content
+
+Check your matcher:
+- `(.)photos` intercepts `/photos` from the same route level
+- If your `@modal` is in `app/dashboard/@modal`, use `(.)photos` to intercept `/dashboard/photos`, not `/photos`
+
+### 5. TypeScript Errors with `params`
+
+In Next.js 15+, `params` is a Promise:
+
+```tsx
+// Correct
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+ const { id } = await params;
+}
+```
+
+## Complete Example: Photo Gallery Modal
+
+```
+app/
+├── @modal/
+│ ├── default.tsx
+│ └── (.)photos/
+│ └── [id]/
+│ └── page.tsx
+├── photos/
+│ ├── page.tsx # Gallery grid
+│ └── [id]/
+│ └── page.tsx # Full photo page
+├── layout.tsx
+└── page.tsx
+```
+
+Links in the gallery:
+
+```tsx
+// app/photos/page.tsx
+import Link from 'next/link';
+
+export default async function Gallery() {
+ const photos = await getPhotos();
+
+ return (
+ }) {
+ return
+}
+```
+
+## Quick Reference
+
+| Pattern | Valid? | Fix |
+|---------|--------|-----|
+| `'use client'` + `async function` | No | Fetch in server parent, pass data |
+| Pass `() => {}` to client | No | Define in client or use server action |
+| Pass `new Date()` to client | No | Use `.toISOString()` |
+| Pass `new Map()` to client | No | Convert to object/array |
+| Pass class instance to client | No | Pass plain object |
+| Pass server action to client | Yes | - |
+| Pass `string/number/boolean` | Yes | - |
+| Pass plain object/array | Yes | - |
diff --git a/.agent/skills/next-best-practices/runtime-selection.md b/.agent/skills/next-best-practices/runtime-selection.md
new file mode 100644
index 00000000..cec960d7
--- /dev/null
+++ b/.agent/skills/next-best-practices/runtime-selection.md
@@ -0,0 +1,39 @@
+# Runtime Selection
+
+## Use Node.js Runtime by Default
+
+Use the default Node.js runtime for new routes and pages. Only use Edge runtime if the project already uses it or there's a specific requirement.
+
+```tsx
+// Good: Default - no runtime config needed (uses Node.js)
+export default function Page() { ... }
+
+// Caution: Only if already used in project or specifically required
+export const runtime = 'edge'
+```
+
+## When to Use Each
+
+### Node.js Runtime (Default)
+
+- Full Node.js API support
+- File system access (`fs`)
+- Full `crypto` support
+- Database connections
+- Most npm packages work
+
+### Edge Runtime
+
+- Only for specific edge-location latency requirements
+- Limited API (no `fs`, limited `crypto`)
+- Smaller cold start
+- Geographic distribution needs
+
+## Detection
+
+**Before adding `runtime = 'edge'`**, check:
+1. Does the project already use Edge runtime?
+2. Is there a specific latency requirement?
+3. Are all dependencies Edge-compatible?
+
+If unsure, use Node.js runtime.
diff --git a/.agent/skills/next-best-practices/scripts.md b/.agent/skills/next-best-practices/scripts.md
new file mode 100644
index 00000000..4eeb744c
--- /dev/null
+++ b/.agent/skills/next-best-practices/scripts.md
@@ -0,0 +1,141 @@
+# Scripts
+
+Loading third-party scripts in Next.js.
+
+## Use next/script
+
+Always use `next/script` instead of native `
+
+// Good: Next.js Script component
+import Script from 'next/script'
+
+
+```
+
+## Inline Scripts Need ID
+
+Inline scripts require an `id` attribute for Next.js to track them.
+
+```tsx
+// Bad: Missing id
+
+
+// Good: Has id
+
+
+// Good: Inline with id
+
+```
+
+## Don't Put Script in Head
+
+`next/script` should not be placed inside `next/head`. It handles its own positioning.
+
+```tsx
+// Bad: Script inside Head
+import Head from 'next/head'
+import Script from 'next/script'
+
+
+
+
+
+// Good: Script outside Head
+
+ Page
+
+
+```
+
+## Loading Strategies
+
+```tsx
+// afterInteractive (default) - Load after page is interactive
+
+
+// lazyOnload - Load during idle time
+
+
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+
+
+// worker - Load in web worker (experimental)
+
+```
+
+## Google Analytics
+
+Use `@next/third-parties` instead of inline GA scripts.
+
+```tsx
+// Bad: Inline GA script
+
+
+
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Layout({ children }) {
+ return (
+
+ {children}
+ Page
+
+
+```
+
+## Loading Strategies
+
+```tsx
+// afterInteractive (default) - Load after page is interactive
+
+
+// lazyOnload - Load during idle time
+
+
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+
+
+// worker - Load in web worker (experimental)
+
+```
+
+## Google Analytics
+
+Use `@next/third-parties` instead of inline GA scripts.
+
+```tsx
+// Bad: Inline GA script
+
+
+
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Layout({ children }) {
+ return (
+
+ {children}
+ Page
+
+
+```
+
+## Loading Strategies
+
+```tsx
+// afterInteractive (default) - Load after page is interactive
+
+
+// lazyOnload - Load during idle time
+
+
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+
+
+// worker - Load in web worker (experimental)
+
+```
+
+## Google Analytics
+
+Use `@next/third-parties` instead of inline GA scripts.
+
+```tsx
+// Bad: Inline GA script
+
+
+
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Layout({ children }) {
+ return (
+
+ {children}
+ Page
+
+
+```
+
+## Loading Strategies
+
+```tsx
+// afterInteractive (default) - Load after page is interactive
+
+
+// lazyOnload - Load during idle time
+
+
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+
+
+// worker - Load in web worker (experimental)
+
+```
+
+## Google Analytics
+
+Use `@next/third-parties` instead of inline GA scripts.
+
+```tsx
+// Bad: Inline GA script
+
+
+
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Layout({ children }) {
+ return (
+
+ {children}
+ StormCom 1-Taka Challenge
+
+
+
+
+
+
+
+ 1-Taka Challenge - Mobile Story
+
+
+
+
+
+ 1-Taka Challenge - Clean & Modern
+
+
+
+
+
+ StormCom 1-Taka - Neubrutalist
+
+
+
+
+
+ StormCom vs Messenger Race
+
+
+
+
+
+ StormCom 1-Taka - Super Reel v2
+
+
+
+
+
+ StormCom vs Shopify Ad
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/marketing/videos/stormcom-1taka-bento.webm b/marketing/videos/stormcom-1taka-bento.webm
new file mode 100644
index 00000000..1e35357e
Binary files /dev/null and b/marketing/videos/stormcom-1taka-bento.webm differ
diff --git a/marketing/videos/stormcom-1taka-neubrutalist.webm b/marketing/videos/stormcom-1taka-neubrutalist.webm
new file mode 100644
index 00000000..bc14c999
Binary files /dev/null and b/marketing/videos/stormcom-1taka-neubrutalist.webm differ
diff --git a/marketing/videos/stormcom-1taka-race.webm b/marketing/videos/stormcom-1taka-race.webm
new file mode 100644
index 00000000..e45db3d0
Binary files /dev/null and b/marketing/videos/stormcom-1taka-race.webm differ
diff --git a/marketing/videos/stormcom-1taka-super-reel.webm b/marketing/videos/stormcom-1taka-super-reel.webm
new file mode 100644
index 00000000..282ce4b4
Binary files /dev/null and b/marketing/videos/stormcom-1taka-super-reel.webm differ
diff --git a/middleware.ts b/middleware.ts
index 0e8fb3ff..30e5ffa8 100644
--- a/middleware.ts
+++ b/middleware.ts
@@ -307,6 +307,7 @@ export default async function middleware(request: NextRequest) {
"/team",
"/projects",
"/products",
+ "/chat",
];
const isProtectedPath = protectedPaths.some((path) =>
diff --git a/package-lock.json b/package-lock.json
index 74f133af..61591296 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -65,6 +65,7 @@
"next-auth": "^4.24.13",
"next-themes": "^0.4.6",
"nodemailer": "^7.0.13",
+ "ollama": "^0.6.3",
"papaparse": "^5.5.3",
"pg": "^8.20.0",
"radix-ui": "^1.4.3",
@@ -17767,6 +17768,15 @@
"node": "^10.13.0 || >=12.0.0"
}
},
+ "node_modules/ollama": {
+ "version": "0.6.3",
+ "resolved": "https://registry.npmjs.org/ollama/-/ollama-0.6.3.tgz",
+ "integrity": "sha512-KEWEhIqE5wtfzEIZbDCLH51VFZ6Z3ZSa6sIOg/E/tBV8S51flyqBOXi+bRxlOYKDf8i327zG9eSTb8IJxvm3Zg==",
+ "license": "MIT",
+ "dependencies": {
+ "whatwg-fetch": "^3.6.20"
+ }
+ },
"node_modules/on-change": {
"version": "6.0.2",
"resolved": "https://registry.npmjs.org/on-change/-/on-change-6.0.2.tgz",
@@ -23128,6 +23138,12 @@
"license": "MIT",
"peer": true
},
+ "node_modules/whatwg-fetch": {
+ "version": "3.6.20",
+ "resolved": "https://registry.npmjs.org/whatwg-fetch/-/whatwg-fetch-3.6.20.tgz",
+ "integrity": "sha512-EqhiFU6daOA8kpjOWTL0olhVOF3i7OrFzSYiGsEMB8GcXS+RrzauAERX65xMeNWVqxA6HXH2m69Z9LaKKdisfg==",
+ "license": "MIT"
+ },
"node_modules/whatwg-mimetype": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz",
diff --git a/package.json b/package.json
index d8086e09..64c4f848 100644
--- a/package.json
+++ b/package.json
@@ -94,6 +94,7 @@
"next-auth": "^4.24.13",
"next-themes": "^0.4.6",
"nodemailer": "^7.0.13",
+ "ollama": "^0.6.3",
"papaparse": "^5.5.3",
"pg": "^8.20.0",
"radix-ui": "^1.4.3",
diff --git a/prisma/migrations/20260315000000_add_chat_messages/migration.sql b/prisma/migrations/20260315000000_add_chat_messages/migration.sql
new file mode 100644
index 00000000..4f7507f9
--- /dev/null
+++ b/prisma/migrations/20260315000000_add_chat_messages/migration.sql
@@ -0,0 +1,20 @@
+-- CreateEnum
+CREATE TYPE "ChatMessageRole" AS ENUM ('USER', 'ASSISTANT');
+
+-- CreateTable
+CREATE TABLE "chat_messages" (
+ "id" TEXT NOT NULL,
+ "userId" TEXT NOT NULL,
+ "role" "ChatMessageRole" NOT NULL,
+ "content" TEXT NOT NULL,
+ "model" TEXT,
+ "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+ CONSTRAINT "chat_messages_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "chat_messages_userId_createdAt_idx" ON "chat_messages"("userId", "createdAt");
+
+-- AddForeignKey
+ALTER TABLE "chat_messages" ADD CONSTRAINT "chat_messages_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
diff --git a/prisma/migrations/20260315001000_add_ollama_config/migration.sql b/prisma/migrations/20260315001000_add_ollama_config/migration.sql
new file mode 100644
index 00000000..5045910f
--- /dev/null
+++ b/prisma/migrations/20260315001000_add_ollama_config/migration.sql
@@ -0,0 +1,21 @@
+-- CreateTable
+CREATE TABLE "ollama_configs" (
+ "id" TEXT NOT NULL,
+ "userId" TEXT NOT NULL,
+ "host" TEXT NOT NULL DEFAULT 'https://ollama.com',
+ "apiKey" TEXT,
+ "model" TEXT NOT NULL DEFAULT 'llama3.2',
+ "systemPrompt" TEXT,
+ "temperature" DOUBLE PRECISION NOT NULL DEFAULT 0.7,
+ "isCloudMode" BOOLEAN NOT NULL DEFAULT true,
+ "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "updatedAt" TIMESTAMP(3) NOT NULL,
+
+ CONSTRAINT "ollama_configs_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ollama_configs_userId_key" ON "ollama_configs"("userId");
+
+-- AddForeignKey
+ALTER TABLE "ollama_configs" ADD CONSTRAINT "ollama_configs_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
diff --git a/prisma/migrations/20260316093000_add_chat_message_org_reasoning_metadata/migration.sql b/prisma/migrations/20260316093000_add_chat_message_org_reasoning_metadata/migration.sql
new file mode 100644
index 00000000..6a3bb396
--- /dev/null
+++ b/prisma/migrations/20260316093000_add_chat_message_org_reasoning_metadata/migration.sql
@@ -0,0 +1,31 @@
+-- AlterTable
+ALTER TABLE "chat_messages"
+ ADD COLUMN "organizationId" TEXT,
+ ADD COLUMN "thinking" TEXT,
+ ADD COLUMN "usage" JSONB;
+
+-- Backfill organizationId for users with exactly one membership
+WITH single_org_memberships AS (
+ SELECT
+ "userId",
+ MIN("organizationId") AS "organizationId"
+ FROM "Membership"
+ GROUP BY "userId"
+ HAVING COUNT(*) = 1
+)
+UPDATE "chat_messages" AS cm
+SET "organizationId" = som."organizationId"
+FROM single_org_memberships AS som
+WHERE cm."userId" = som."userId"
+ AND cm."organizationId" IS NULL;
+
+-- CreateIndex
+CREATE INDEX "chat_messages_userId_organizationId_createdAt_idx"
+ON "chat_messages"("userId", "organizationId", "createdAt");
+
+-- AddForeignKey
+ALTER TABLE "chat_messages"
+ADD CONSTRAINT "chat_messages_organizationId_fkey"
+FOREIGN KEY ("organizationId") REFERENCES "Organization"("id")
+ON DELETE SET NULL
+ON UPDATE CASCADE;
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index 12f7c1d3..5ffe07af 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -44,6 +44,8 @@ model User {
activitiesReceived PlatformActivity[] @relation("PlatformActivityTarget")
reviewedStoreRequests StoreRequest[] @relation("StoreRequestReviewer")
storeRequests StoreRequest[] @relation("UserStoreRequests")
+ chatMessages ChatMessage[]
+ ollamaConfig OllamaConfig?
}
model Account {
@@ -91,6 +93,7 @@ model Organization {
projects Project[]
store Store?
paymentConfigurations PaymentConfiguration[]
+ chatMessages ChatMessage[]
}
model Membership {
@@ -1846,6 +1849,53 @@ model LandingPage {
@@map("landing_pages")
}
+// ============================================================================
+// AI CHAT
+// ============================================================================
+
+enum ChatMessageRole {
+ USER
+ ASSISTANT
+}
+
+model ChatMessage {
+ id String @id @default(cuid())
+ userId String
+ organizationId String?
+ role ChatMessageRole
+ content String
+ thinking String?
+ model String?
+ usage Json?
+ createdAt DateTime @default(now())
+
+ user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+ organization Organization? @relation(fields: [organizationId], references: [id], onDelete: SetNull)
+
+ @@index([userId, createdAt])
+ @@index([userId, organizationId, createdAt])
+ @@map("chat_messages")
+}
+
+/// Stores Ollama Cloud / local configuration per user.
+/// Falls back to environment variables when no DB config exists.
+model OllamaConfig {
+ id String @id @default(cuid())
+ userId String @unique
+ host String @default("https://ollama.com")
+ apiKey String? /// AES-256-CBC encrypted
+ model String @default("llama3.2")
+ systemPrompt String?
+ temperature Float @default(0.7)
+ isCloudMode Boolean @default(true)
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+
+ user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+ @@map("ollama_configs")
+}
+
model LandingPageVersion {
id String @id @default(cuid())
pageId String
diff --git a/scripts/record-marketing-video.mjs b/scripts/record-marketing-video.mjs
new file mode 100644
index 00000000..8023e8be
--- /dev/null
+++ b/scripts/record-marketing-video.mjs
@@ -0,0 +1,43 @@
+import { chromium } from 'playwright';
+import path from 'path';
+import fs from 'fs';
+
+async function recordVideo(htmlRelativePath, outputDir) {
+ const htmlPath = path.resolve(htmlRelativePath);
+ console.log(`🚀 Starting video recording for: ${htmlPath}`);
+
+ if (!fs.existsSync(outputDir)) {
+ fs.mkdirSync(outputDir, { recursive: true });
+ }
+
+ const browser = await chromium.launch({ headless: true });
+ const context = await browser.newContext({
+ viewport: { width: 1080, height: 1920 }, // Vertical/Story format
+ recordVideo: {
+ dir: outputDir,
+ size: { width: 1080, height: 1920 },
+ }
+ });
+
+ const page = await context.newPage();
+
+ // Use file:// protocol for local HTML
+ const fileUrl = `file://${htmlPath}`;
+ await page.goto(fileUrl);
+
+ console.log('🎥 Recording for 15 seconds...');
+ await page.waitForTimeout(15000);
+
+ await browser.close();
+
+ console.log(`✅ Recording finished. Check the '${outputDir}' folder for the .webm video file.`);
+}
+
+// Target the race-reel ad
+const targetFile = 'marketing/ad-10-1taka/race-reel.html';
+const outDir = 'marketing/videos';
+
+recordVideo(targetFile, outDir).catch(err => {
+ console.error('❌ Error recording video:', err);
+ process.exit(1);
+});
diff --git a/skills/deploy-to-vercel/Archive.zip b/skills/deploy-to-vercel/Archive.zip
new file mode 100644
index 00000000..2945baff
Binary files /dev/null and b/skills/deploy-to-vercel/Archive.zip differ
diff --git a/skills/deploy-to-vercel/SKILL.md b/skills/deploy-to-vercel/SKILL.md
new file mode 100644
index 00000000..a0251ce8
--- /dev/null
+++ b/skills/deploy-to-vercel/SKILL.md
@@ -0,0 +1,296 @@
+---
+name: deploy-to-vercel
+description: Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".
+metadata:
+ author: vercel
+ version: "3.0.0"
+---
+
+# Deploy to Vercel
+
+Deploy any project to Vercel. **Always deploy as preview** (not production) unless the user explicitly asks for production.
+
+The goal is to get the user into the best long-term setup: their project linked to Vercel with git-push deploys. Every method below tries to move the user closer to that state.
+
+## Step 1: Gather Project State
+
+Run all four checks before deciding which method to use:
+
+```bash
+# 1. Check for a git remote
+git remote get-url origin 2>/dev/null
+
+# 2. Check if locally linked to a Vercel project (either file means linked)
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+
+# 3. Check if the Vercel CLI is installed and authenticated
+vercel whoami 2>/dev/null
+
+# 4. List available teams (if authenticated)
+vercel teams list --format json 2>/dev/null
+```
+
+### Team selection
+
+If the user belongs to multiple teams, present all available team slugs as a bulleted list and ask which one to deploy to. Once the user picks a team, proceed immediately to the next step — do not ask for additional confirmation.
+
+Pass the team slug via `--scope` on all subsequent CLI commands (`vercel deploy`, `vercel link`, `vercel inspect`, etc.):
+
+```bash
+vercel deploy [path] -y --no-wait --scope
+```
+
+If the project is already linked (`.vercel/project.json` or `.vercel/repo.json` exists), the `orgId` in those files determines the team — no need to ask again. If there is only one team (or just a personal account), skip the prompt and use it directly.
+
+**About the `.vercel/` directory:** A linked project has either:
+- `.vercel/project.json` — created by `vercel link` (single project linking). Contains `projectId` and `orgId`.
+- `.vercel/repo.json` — created by `vercel link --repo` (repo-based linking). Contains `orgId`, `remoteName`, and a `projects` array mapping directories to Vercel project IDs.
+
+Either file means the project is linked. Check for both.
+
+**Do NOT** use `vercel project inspect`, `vercel ls`, or `vercel link` to detect state in an unlinked directory — without a `.vercel/` config, they will interactively prompt (or with `--yes`, silently link as a side-effect). Only `vercel whoami` is safe to run anywhere.
+
+## Step 2: Choose a Deploy Method
+
+### Linked (`.vercel/` exists) + has git remote → Git Push
+
+This is the ideal state. The project is linked and has git integration.
+
+1. **Ask the user before pushing.** Never push without explicit approval:
+ ```
+ This project is connected to Vercel via git. I can commit and push to
+ trigger a deployment. Want me to proceed?
+ ```
+
+2. **Commit and push:**
+ ```bash
+ git add .
+ git commit -m "deploy: "
+ git push
+ ```
+ Vercel automatically builds from the push. Non-production branches get preview deployments; the production branch (usually `main`) gets a production deployment.
+
+3. **Retrieve the preview URL.** If the CLI is authenticated:
+ ```bash
+ sleep 5
+ vercel ls --format json
+ ```
+ The JSON output has a `deployments` array. Find the latest entry — its `url` field is the preview URL.
+
+ If the CLI is not authenticated, tell the user to check the Vercel dashboard or the commit status checks on their git provider for the preview URL.
+
+---
+
+### Linked (`.vercel/` exists) + no git remote → `vercel deploy`
+
+The project is linked but there's no git repo. Deploy directly with the CLI.
+
+```bash
+vercel deploy [path] -y --no-wait
+```
+
+Use `--no-wait` so the CLI returns immediately with the deployment URL instead of blocking until the build finishes (builds can take a while). Then check on the deployment status with:
+
+```bash
+vercel inspect
+```
+
+For production deploys (only if user explicitly asks):
+```bash
+vercel deploy [path] --prod -y --no-wait
+```
+
+---
+
+### Not linked + CLI is authenticated → Link first, then deploy
+
+The CLI is working but the project isn't linked yet. This is the opportunity to get the user into the best state.
+
+1. **Ask the user which team to deploy to.** Present the team slugs from Step 1 as a bulleted list. If there's only one team (or just a personal account), skip this step.
+
+2. **Once a team is selected, proceed directly to linking.** Tell the user what will happen but do not ask for separate confirmation:
+ ```
+ Linking this project to on Vercel. This will create a Vercel
+ project to deploy to and enable automatic deployments on future git pushes.
+ ```
+
+3. **If a git remote exists**, use repo-based linking with the selected team scope:
+ ```bash
+ vercel link --repo --scope
+ ```
+ This reads the git remote URL and matches it to existing Vercel projects that deploy from that repo. It creates `.vercel/repo.json`. This is much more reliable than `vercel link` (without `--repo`), which tries to match by directory name and often fails when the local folder and Vercel project are named differently.
+
+ **If there is no git remote**, fall back to standard linking:
+ ```bash
+ vercel link --scope
+ ```
+ This prompts the user to select or create a project. It creates `.vercel/project.json`.
+
+4. **Then deploy using the best available method:**
+ - If a git remote exists → commit and push (see git push method above)
+ - If no git remote → `vercel deploy [path] -y --no-wait --scope `, then `vercel inspect ` to check status
+
+---
+
+### Not linked + CLI not authenticated → Install, auth, link, deploy
+
+The Vercel CLI isn't set up at all.
+
+1. **Install the CLI (if not already installed):**
+ ```bash
+ npm install -g vercel
+ ```
+
+2. **Authenticate:**
+ ```bash
+ vercel login
+ ```
+ The user completes auth in their browser. If running in a non-interactive environment where login is not possible, skip to the **no-auth fallback** below.
+
+3. **Ask which team to deploy to** — present team slugs from `vercel teams list --format json` as a bulleted list. If only one team / personal account, skip. Once selected, proceed immediately.
+
+4. **Link the project** with the selected team scope (use `--repo` if a git remote exists, plain `vercel link` otherwise):
+ ```bash
+ vercel link --repo --scope # if git remote exists
+ vercel link --scope # if no git remote
+ ```
+
+5. **Deploy** using the best available method (git push if remote exists, otherwise `vercel deploy -y --no-wait --scope `, then `vercel inspect ` to check status).
+
+---
+
+### No-Auth Fallback — claude.ai sandbox
+
+**When to use:** Last resort when the CLI can't be installed or authenticated in the claude.ai sandbox. This requires no authentication — it returns a **Preview URL** (live site) and a **Claim URL** (transfer to your Vercel account).
+
+```bash
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]
+```
+
+**Arguments:**
+- `path` - Directory to deploy, or a `.tgz` file (defaults to current directory)
+
+**Examples:**
+```bash
+# Deploy current directory
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
+
+# Deploy specific project
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
+
+# Deploy existing tarball
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz
+```
+
+The script auto-detects the framework from `package.json`, packages the project (excluding `node_modules`, `.git`, `.env`), uploads it, and waits for the build to complete.
+
+**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
+
+---
+
+### No-Auth Fallback — Codex sandbox
+
+**When to use:** In the Codex sandbox where the CLI may not be authenticated. Codex runs in a sandboxed environment by default — try the CLI first, and fall back to the deploy script if auth fails.
+
+1. **Check whether the Vercel CLI is installed** (no escalation needed for this check):
+ ```bash
+ command -v vercel
+ ```
+
+2. **If `vercel` is installed**, try deploying with the CLI:
+ ```bash
+ vercel deploy [path] -y --no-wait
+ ```
+
+3. **If `vercel` is not installed, or the CLI fails with "No existing credentials found"**, use the fallback script:
+ ```bash
+ skill_dir=""
+
+ # Deploy current directory
+ bash "$skill_dir/resources/deploy-codex.sh"
+
+ # Deploy specific project
+ bash "$skill_dir/resources/deploy-codex.sh" /path/to/project
+
+ # Deploy existing tarball
+ bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
+ ```
+
+The script handles framework detection, packaging, and deployment. It waits for the build to complete and returns JSON with `previewUrl` and `claimUrl`.
+
+**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
+
+**Escalated network access:** Only escalate the actual deploy command if sandboxing blocks the network call (`sandbox_permissions=require_escalated`). Do **not** escalate the `command -v vercel` check.
+
+---
+
+## Agent-Specific Notes
+
+### Claude Code / terminal-based agents
+
+You have full shell access. Do NOT use the `/mnt/skills/` path. Follow the decision flow above using the CLI directly.
+
+For the no-auth fallback, run the deploy script from the skill's installed location:
+```bash
+bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
+```
+The path may vary depending on where the user installed the skill.
+
+### Sandboxed environments (claude.ai)
+
+You likely cannot run `vercel login` or `git push`. Go directly to the **no-auth fallback — claude.ai sandbox**.
+
+### Codex
+
+Codex runs in a sandbox. Check if the CLI is available first, then fall back to the deploy script. Go to the **no-auth fallback — Codex sandbox**.
+
+---
+
+## Output
+
+Always show the user the deployment URL.
+
+- **Git push:** Use `vercel ls --format json` to find the preview URL. If the CLI isn't authenticated, tell the user to check the Vercel dashboard or commit status checks.
+- **CLI deploy:** Show the URL returned by `vercel deploy --no-wait`. Use `vercel inspect ` to check build status and report it to the user.
+- **No-auth fallback:** Show both the preview URL and the claim URL:
+ ```
+ Deployment successful!
+
+ Preview URL: https://my-app-abc123.vercel.app
+ Claim URL: https://vercel.com/claim-deployment?code=...
+
+ View your site at the Preview URL.
+ To transfer this deployment to your Vercel account, visit the Claim URL.
+ ```
+
+**Do not** curl or fetch the deployed URL to verify it works. Just return the link.
+
+---
+
+## Troubleshooting
+
+### Network Egress Error (claude.ai)
+
+If deployment fails due to network restrictions on claude.ai, tell the user:
+
+```
+Deployment failed due to network restrictions. To fix this:
+
+1. Go to https://claude.ai/settings/capabilities
+2. Add *.vercel.com to the allowed domains
+3. Try deploying again
+```
+
+### Escalated Network Access (Codex / sandboxed environments)
+
+If deployment fails due to network issues (timeouts, DNS errors, connection resets) in a sandboxed environment, rerun with escalated permissions (`sandbox_permissions=require_escalated`). Do not escalate the initial CLI availability check — only escalate the actual deploy command.
+
+Example guidance to the user:
+```
+The deploy needs escalated network access to deploy to Vercel. I can rerun
+the command with escalated permissions — want me to proceed?
+```
+
+### CLI Auth Failure
+
+If `vercel login` or `vercel deploy` fails with authentication errors, fall back to the no-auth deploy script (claude.ai or Codex variant, depending on the environment).
diff --git a/skills/deploy-to-vercel/resources/deploy-codex.sh b/skills/deploy-to-vercel/resources/deploy-codex.sh
new file mode 100644
index 00000000..af07d0fd
--- /dev/null
+++ b/skills/deploy-to-vercel/resources/deploy-codex.sh
@@ -0,0 +1,301 @@
+#!/bin/bash
+
+# Vercel Deployment Script for Codex (via claimable deploy endpoint)
+# Usage: ./deploy-codex.sh [project-path]
+# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
+
+set -euo pipefail
+
+DEPLOY_ENDPOINT="https://codex-deploy-skills.vercel.sh/api/deploy"
+
+# Detect framework from package.json
+detect_framework() {
+ local pkg_json="$1"
+
+ if [ ! -f "$pkg_json" ]; then
+ echo "null"
+ return
+ fi
+
+ local content=$(cat "$pkg_json")
+
+ # Helper to check if a package exists in dependencies or devDependencies.
+ # Use exact matching by default, with a separate prefix matcher for scoped
+ # package families like "@remix-run/".
+ has_dep_exact() {
+ echo "$content" | grep -q "\"$1\""
+ }
+
+ has_dep_prefix() {
+ echo "$content" | grep -q "\"$1"
+ }
+
+ # Order matters - check more specific frameworks first
+
+ # Blitz
+ if has_dep_exact "blitz"; then echo "blitzjs"; return; fi
+
+ # Next.js
+ if has_dep_exact "next"; then echo "nextjs"; return; fi
+
+ # Gatsby
+ if has_dep_exact "gatsby"; then echo "gatsby"; return; fi
+
+ # Remix
+ if has_dep_prefix "@remix-run/"; then echo "remix"; return; fi
+
+ # React Router (v7 framework mode)
+ if has_dep_prefix "@react-router/"; then echo "react-router"; return; fi
+
+ # TanStack Start
+ if has_dep_exact "@tanstack/start"; then echo "tanstack-start"; return; fi
+
+ # Astro
+ if has_dep_exact "astro"; then echo "astro"; return; fi
+
+ # Hydrogen (Shopify)
+ if has_dep_exact "@shopify/hydrogen"; then echo "hydrogen"; return; fi
+
+ # SvelteKit
+ if has_dep_exact "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
+
+ # Svelte (standalone)
+ if has_dep_exact "svelte"; then echo "svelte"; return; fi
+
+ # Nuxt
+ if has_dep_exact "nuxt"; then echo "nuxtjs"; return; fi
+
+ # Vue with Vitepress
+ if has_dep_exact "vitepress"; then echo "vitepress"; return; fi
+
+ # Vue with Vuepress
+ if has_dep_exact "vuepress"; then echo "vuepress"; return; fi
+
+ # Gridsome
+ if has_dep_exact "gridsome"; then echo "gridsome"; return; fi
+
+ # SolidStart
+ if has_dep_exact "@solidjs/start"; then echo "solidstart-1"; return; fi
+
+ # Docusaurus
+ if has_dep_exact "@docusaurus/core"; then echo "docusaurus-2"; return; fi
+
+ # RedwoodJS
+ if has_dep_prefix "@redwoodjs/"; then echo "redwoodjs"; return; fi
+
+ # Hexo
+ if has_dep_exact "hexo"; then echo "hexo"; return; fi
+
+ # Eleventy
+ if has_dep_exact "@11ty/eleventy"; then echo "eleventy"; return; fi
+
+ # Angular / Ionic Angular
+ if has_dep_exact "@ionic/angular"; then echo "ionic-angular"; return; fi
+ if has_dep_exact "@angular/core"; then echo "angular"; return; fi
+
+ # Ionic React
+ if has_dep_exact "@ionic/react"; then echo "ionic-react"; return; fi
+
+ # Create React App
+ if has_dep_exact "react-scripts"; then echo "create-react-app"; return; fi
+
+ # Ember
+ if has_dep_exact "ember-cli" || has_dep_exact "ember-source"; then echo "ember"; return; fi
+
+ # Dojo
+ if has_dep_exact "@dojo/framework"; then echo "dojo"; return; fi
+
+ # Polymer
+ if has_dep_prefix "@polymer/"; then echo "polymer"; return; fi
+
+ # Preact
+ if has_dep_exact "preact"; then echo "preact"; return; fi
+
+ # Stencil
+ if has_dep_exact "@stencil/core"; then echo "stencil"; return; fi
+
+ # UmiJS
+ if has_dep_exact "umi"; then echo "umijs"; return; fi
+
+ # Sapper (legacy Svelte)
+ if has_dep_exact "sapper"; then echo "sapper"; return; fi
+
+ # Saber
+ if has_dep_exact "saber"; then echo "saber"; return; fi
+
+ # Sanity
+ if has_dep_exact "sanity"; then echo "sanity-v3"; return; fi
+ if has_dep_prefix "@sanity/"; then echo "sanity"; return; fi
+
+ # Storybook
+ if has_dep_prefix "@storybook/"; then echo "storybook"; return; fi
+
+ # NestJS
+ if has_dep_exact "@nestjs/core"; then echo "nestjs"; return; fi
+
+ # Elysia
+ if has_dep_exact "elysia"; then echo "elysia"; return; fi
+
+ # Hono
+ if has_dep_exact "hono"; then echo "hono"; return; fi
+
+ # Fastify
+ if has_dep_exact "fastify"; then echo "fastify"; return; fi
+
+ # h3
+ if has_dep_exact "h3"; then echo "h3"; return; fi
+
+ # Nitro
+ if has_dep_exact "nitropack"; then echo "nitro"; return; fi
+
+ # Express
+ if has_dep_exact "express"; then echo "express"; return; fi
+
+ # Vite (generic - check last among JS frameworks)
+ if has_dep_exact "vite"; then echo "vite"; return; fi
+
+ # Parcel
+ if has_dep_exact "parcel"; then echo "parcel"; return; fi
+
+ # No framework detected
+ echo "null"
+}
+
+# Parse arguments
+INPUT_PATH="${1:-.}"
+
+# Create temp directory for packaging
+TEMP_DIR=$(mktemp -d)
+TARBALL="$TEMP_DIR/project.tgz"
+STAGING_DIR="$TEMP_DIR/staging"
+CLEANUP_TEMP=true
+
+cleanup() {
+ if [ "$CLEANUP_TEMP" = true ]; then
+ rm -rf "$TEMP_DIR"
+ fi
+}
+trap cleanup EXIT
+
+echo "Preparing deployment..." >&2
+
+# Check if input is a .tgz file or a directory
+FRAMEWORK="null"
+
+if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
+ # Input is already a tarball, use it directly
+ echo "Using provided tarball..." >&2
+ TARBALL="$INPUT_PATH"
+ CLEANUP_TEMP=false
+ # Can't detect framework from tarball, leave as null
+elif [ -d "$INPUT_PATH" ]; then
+ # Input is a directory, need to tar it
+ PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
+
+ # Detect framework from package.json
+ FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
+
+ # Stage files into a temporary directory to avoid mutating the source tree.
+ mkdir -p "$STAGING_DIR"
+ echo "Staging project files..." >&2
+ tar -C "$PROJECT_PATH" \
+ --exclude='node_modules' \
+ --exclude='.git' \
+ --exclude='.env' \
+ --exclude='.env.*' \
+ -cf - . | tar -C "$STAGING_DIR" -xf -
+
+ # Check if this is a static HTML project (no package.json)
+ if [ ! -f "$PROJECT_PATH/package.json" ]; then
+ # Find HTML files in root
+ HTML_FILES=$(find "$STAGING_DIR" -maxdepth 1 -name "*.html" -type f)
+ HTML_COUNT=$(printf '%s\n' "$HTML_FILES" | sed '/^$/d' | wc -l | tr -d '[:space:]')
+
+ # If there's exactly one HTML file and it's not index.html, rename it
+ if [ "$HTML_COUNT" -eq 1 ]; then
+ HTML_FILE=$(echo "$HTML_FILES" | head -1)
+ BASENAME=$(basename "$HTML_FILE")
+ if [ "$BASENAME" != "index.html" ]; then
+ echo "Renaming $BASENAME to index.html..." >&2
+ mv "$HTML_FILE" "$STAGING_DIR/index.html"
+ fi
+ fi
+ fi
+
+ # Create tarball from the staging directory
+ echo "Creating deployment package..." >&2
+ tar -czf "$TARBALL" -C "$STAGING_DIR" .
+else
+ echo "Error: Input must be a directory or a .tgz file" >&2
+ exit 1
+fi
+
+if [ "$FRAMEWORK" != "null" ]; then
+ echo "Detected framework: $FRAMEWORK" >&2
+fi
+
+# Deploy
+echo "Deploying..." >&2
+RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
+
+# Check for error in response
+if echo "$RESPONSE" | grep -q '"error"'; then
+ ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
+ echo "Error: $ERROR_MSG" >&2
+ exit 1
+fi
+
+# Extract URLs from response
+PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
+CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
+
+if [ -z "$PREVIEW_URL" ]; then
+ echo "Error: Could not extract preview URL from response" >&2
+ echo "$RESPONSE" >&2
+ exit 1
+fi
+
+echo "Deployment started. Waiting for build to complete..." >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+
+# Poll the preview URL until it returns a non-5xx response (5xx = still building)
+MAX_ATTEMPTS=60 # 5 minutes max (60 * 5 seconds)
+ATTEMPT=0
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+ HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL")
+
+ if [ "$HTTP_STATUS" -eq 200 ]; then
+ echo "" >&2
+ echo "Deployment ready!" >&2
+ break
+ elif [ "$HTTP_STATUS" -ge 500 ]; then
+ # 5xx means still building/deploying
+ echo "Building... (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" >&2
+ sleep 5
+ ATTEMPT=$((ATTEMPT + 1))
+ elif [ "$HTTP_STATUS" -ge 400 ] && [ "$HTTP_STATUS" -lt 500 ]; then
+ # 4xx might be an error or the app itself returns 4xx - it's responding
+ echo "" >&2
+ echo "Deployment ready (returned $HTTP_STATUS)!" >&2
+ break
+ else
+ # Any other status, assume it's ready
+ echo "" >&2
+ echo "Deployment ready!" >&2
+ break
+ fi
+done
+
+if [ $ATTEMPT -eq $MAX_ATTEMPTS ]; then
+ echo "" >&2
+ echo "Warning: Timed out waiting for deployment, but it may still be building." >&2
+fi
+
+echo "" >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+echo "Claim URL: $CLAIM_URL" >&2
+echo "" >&2
+
+# Output JSON for programmatic use
+echo "$RESPONSE"
diff --git a/skills/deploy-to-vercel/resources/deploy.sh b/skills/deploy-to-vercel/resources/deploy.sh
new file mode 100644
index 00000000..a458da63
--- /dev/null
+++ b/skills/deploy-to-vercel/resources/deploy.sh
@@ -0,0 +1,301 @@
+#!/bin/bash
+
+# Vercel Deployment Script (via claimable deploy endpoint)
+# Usage: ./deploy.sh [project-path]
+# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
+
+set -euo pipefail
+
+DEPLOY_ENDPOINT="https://claude-skills-deploy.vercel.com/api/deploy"
+
+# Detect framework from package.json
+detect_framework() {
+ local pkg_json="$1"
+
+ if [ ! -f "$pkg_json" ]; then
+ echo "null"
+ return
+ fi
+
+ local content=$(cat "$pkg_json")
+
+ # Helper to check if a package exists in dependencies or devDependencies.
+ # Use exact matching by default, with a separate prefix matcher for scoped
+ # package families like "@remix-run/".
+ has_dep_exact() {
+ echo "$content" | grep -q "\"$1\""
+ }
+
+ has_dep_prefix() {
+ echo "$content" | grep -q "\"$1"
+ }
+
+ # Order matters - check more specific frameworks first
+
+ # Blitz
+ if has_dep_exact "blitz"; then echo "blitzjs"; return; fi
+
+ # Next.js
+ if has_dep_exact "next"; then echo "nextjs"; return; fi
+
+ # Gatsby
+ if has_dep_exact "gatsby"; then echo "gatsby"; return; fi
+
+ # Remix
+ if has_dep_prefix "@remix-run/"; then echo "remix"; return; fi
+
+ # React Router (v7 framework mode)
+ if has_dep_prefix "@react-router/"; then echo "react-router"; return; fi
+
+ # TanStack Start
+ if has_dep_exact "@tanstack/start"; then echo "tanstack-start"; return; fi
+
+ # Astro
+ if has_dep_exact "astro"; then echo "astro"; return; fi
+
+ # Hydrogen (Shopify)
+ if has_dep_exact "@shopify/hydrogen"; then echo "hydrogen"; return; fi
+
+ # SvelteKit
+ if has_dep_exact "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
+
+ # Svelte (standalone)
+ if has_dep_exact "svelte"; then echo "svelte"; return; fi
+
+ # Nuxt
+ if has_dep_exact "nuxt"; then echo "nuxtjs"; return; fi
+
+ # Vue with Vitepress
+ if has_dep_exact "vitepress"; then echo "vitepress"; return; fi
+
+ # Vue with Vuepress
+ if has_dep_exact "vuepress"; then echo "vuepress"; return; fi
+
+ # Gridsome
+ if has_dep_exact "gridsome"; then echo "gridsome"; return; fi
+
+ # SolidStart
+ if has_dep_exact "@solidjs/start"; then echo "solidstart-1"; return; fi
+
+ # Docusaurus
+ if has_dep_exact "@docusaurus/core"; then echo "docusaurus-2"; return; fi
+
+ # RedwoodJS
+ if has_dep_prefix "@redwoodjs/"; then echo "redwoodjs"; return; fi
+
+ # Hexo
+ if has_dep_exact "hexo"; then echo "hexo"; return; fi
+
+ # Eleventy
+ if has_dep_exact "@11ty/eleventy"; then echo "eleventy"; return; fi
+
+ # Angular / Ionic Angular
+ if has_dep_exact "@ionic/angular"; then echo "ionic-angular"; return; fi
+ if has_dep_exact "@angular/core"; then echo "angular"; return; fi
+
+ # Ionic React
+ if has_dep_exact "@ionic/react"; then echo "ionic-react"; return; fi
+
+ # Create React App
+ if has_dep_exact "react-scripts"; then echo "create-react-app"; return; fi
+
+ # Ember
+ if has_dep_exact "ember-cli" || has_dep_exact "ember-source"; then echo "ember"; return; fi
+
+ # Dojo
+ if has_dep_exact "@dojo/framework"; then echo "dojo"; return; fi
+
+ # Polymer
+ if has_dep_prefix "@polymer/"; then echo "polymer"; return; fi
+
+ # Preact
+ if has_dep_exact "preact"; then echo "preact"; return; fi
+
+ # Stencil
+ if has_dep_exact "@stencil/core"; then echo "stencil"; return; fi
+
+ # UmiJS
+ if has_dep_exact "umi"; then echo "umijs"; return; fi
+
+ # Sapper (legacy Svelte)
+ if has_dep_exact "sapper"; then echo "sapper"; return; fi
+
+ # Saber
+ if has_dep_exact "saber"; then echo "saber"; return; fi
+
+ # Sanity
+ if has_dep_exact "sanity"; then echo "sanity-v3"; return; fi
+ if has_dep_prefix "@sanity/"; then echo "sanity"; return; fi
+
+ # Storybook
+ if has_dep_prefix "@storybook/"; then echo "storybook"; return; fi
+
+ # NestJS
+ if has_dep_exact "@nestjs/core"; then echo "nestjs"; return; fi
+
+ # Elysia
+ if has_dep_exact "elysia"; then echo "elysia"; return; fi
+
+ # Hono
+ if has_dep_exact "hono"; then echo "hono"; return; fi
+
+ # Fastify
+ if has_dep_exact "fastify"; then echo "fastify"; return; fi
+
+ # h3
+ if has_dep_exact "h3"; then echo "h3"; return; fi
+
+ # Nitro
+ if has_dep_exact "nitropack"; then echo "nitro"; return; fi
+
+ # Express
+ if has_dep_exact "express"; then echo "express"; return; fi
+
+ # Vite (generic - check last among JS frameworks)
+ if has_dep_exact "vite"; then echo "vite"; return; fi
+
+ # Parcel
+ if has_dep_exact "parcel"; then echo "parcel"; return; fi
+
+ # No framework detected
+ echo "null"
+}
+
+# Parse arguments
+INPUT_PATH="${1:-.}"
+
+# Create temp directory for packaging
+TEMP_DIR=$(mktemp -d)
+TARBALL="$TEMP_DIR/project.tgz"
+STAGING_DIR="$TEMP_DIR/staging"
+CLEANUP_TEMP=true
+
+cleanup() {
+ if [ "$CLEANUP_TEMP" = true ]; then
+ rm -rf "$TEMP_DIR"
+ fi
+}
+trap cleanup EXIT
+
+echo "Preparing deployment..." >&2
+
+# Check if input is a .tgz file or a directory
+FRAMEWORK="null"
+
+if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
+ # Input is already a tarball, use it directly
+ echo "Using provided tarball..." >&2
+ TARBALL="$INPUT_PATH"
+ CLEANUP_TEMP=false
+ # Can't detect framework from tarball, leave as null
+elif [ -d "$INPUT_PATH" ]; then
+ # Input is a directory, need to tar it
+ PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
+
+ # Detect framework from package.json
+ FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
+
+ # Stage files into a temporary directory to avoid mutating the source tree.
+ mkdir -p "$STAGING_DIR"
+ echo "Staging project files..." >&2
+ tar -C "$PROJECT_PATH" \
+ --exclude='node_modules' \
+ --exclude='.git' \
+ --exclude='.env' \
+ --exclude='.env.*' \
+ -cf - . | tar -C "$STAGING_DIR" -xf -
+
+ # Check if this is a static HTML project (no package.json)
+ if [ ! -f "$PROJECT_PATH/package.json" ]; then
+ # Find HTML files in root
+ HTML_FILES=$(find "$STAGING_DIR" -maxdepth 1 -name "*.html" -type f)
+ HTML_COUNT=$(printf '%s\n' "$HTML_FILES" | sed '/^$/d' | wc -l | tr -d '[:space:]')
+
+ # If there's exactly one HTML file and it's not index.html, rename it
+ if [ "$HTML_COUNT" -eq 1 ]; then
+ HTML_FILE=$(echo "$HTML_FILES" | head -1)
+ BASENAME=$(basename "$HTML_FILE")
+ if [ "$BASENAME" != "index.html" ]; then
+ echo "Renaming $BASENAME to index.html..." >&2
+ mv "$HTML_FILE" "$STAGING_DIR/index.html"
+ fi
+ fi
+ fi
+
+ # Create tarball from the staging directory
+ echo "Creating deployment package..." >&2
+ tar -czf "$TARBALL" -C "$STAGING_DIR" .
+else
+ echo "Error: Input must be a directory or a .tgz file" >&2
+ exit 1
+fi
+
+if [ "$FRAMEWORK" != "null" ]; then
+ echo "Detected framework: $FRAMEWORK" >&2
+fi
+
+# Deploy
+echo "Deploying..." >&2
+RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
+
+# Check for error in response
+if echo "$RESPONSE" | grep -q '"error"'; then
+ ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
+ echo "Error: $ERROR_MSG" >&2
+ exit 1
+fi
+
+# Extract URLs from response
+PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
+CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
+
+if [ -z "$PREVIEW_URL" ]; then
+ echo "Error: Could not extract preview URL from response" >&2
+ echo "$RESPONSE" >&2
+ exit 1
+fi
+
+echo "Deployment started. Waiting for build to complete..." >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+
+# Poll the preview URL until it returns a non-5xx response (5xx = still building)
+MAX_ATTEMPTS=60 # 5 minutes max (60 * 5 seconds)
+ATTEMPT=0
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+ HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL")
+
+ if [ "$HTTP_STATUS" -eq 200 ]; then
+ echo "" >&2
+ echo "Deployment ready!" >&2
+ break
+ elif [ "$HTTP_STATUS" -ge 500 ]; then
+ # 5xx means still building/deploying
+ echo "Building... (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" >&2
+ sleep 5
+ ATTEMPT=$((ATTEMPT + 1))
+ elif [ "$HTTP_STATUS" -ge 400 ] && [ "$HTTP_STATUS" -lt 500 ]; then
+ # 4xx might be an error or the app itself returns 4xx - it's responding
+ echo "" >&2
+ echo "Deployment ready (returned $HTTP_STATUS)!" >&2
+ break
+ else
+ # Any other status, assume it's ready
+ echo "" >&2
+ echo "Deployment ready!" >&2
+ break
+ fi
+done
+
+if [ $ATTEMPT -eq $MAX_ATTEMPTS ]; then
+ echo "" >&2
+ echo "Warning: Timed out waiting for deployment, but it may still be building." >&2
+fi
+
+echo "" >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+echo "Claim URL: $CLAIM_URL" >&2
+echo "" >&2
+
+# Output JSON for programmatic use
+echo "$RESPONSE"
diff --git a/skills/vercel-composition-patterns/AGENTS.md b/skills/vercel-composition-patterns/AGENTS.md
new file mode 100644
index 00000000..558bf9aa
--- /dev/null
+++ b/skills/vercel-composition-patterns/AGENTS.md
@@ -0,0 +1,946 @@
+# React Composition Patterns
+
+**Version 1.0.0**
+Engineering
+January 2026
+
+> **Note:**
+> This document is mainly for agents and LLMs to follow when maintaining,
+> generating, or refactoring React codebases using composition. Humans
+> may also find it useful, but guidance here is optimized for automation
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.
+
+---
+
+## Table of Contents
+
+1. [Component Architecture](#1-component-architecture) — **HIGH**
+ - 1.1 [Avoid Boolean Prop Proliferation](#11-avoid-boolean-prop-proliferation)
+ - 1.2 [Use Compound Components](#12-use-compound-components)
+2. [State Management](#2-state-management) — **MEDIUM**
+ - 2.1 [Decouple State Management from UI](#21-decouple-state-management-from-ui)
+ - 2.2 [Define Generic Context Interfaces for Dependency Injection](#22-define-generic-context-interfaces-for-dependency-injection)
+ - 2.3 [Lift State into Provider Components](#23-lift-state-into-provider-components)
+3. [Implementation Patterns](#3-implementation-patterns) — **MEDIUM**
+ - 3.1 [Create Explicit Component Variants](#31-create-explicit-component-variants)
+ - 3.2 [Prefer Composing Children Over Render Props](#32-prefer-composing-children-over-render-props)
+4. [React 19 APIs](#4-react-19-apis) — **MEDIUM**
+ - 4.1 [React 19 API Changes](#41-react-19-api-changes)
+
+---
+
+## 1. Component Architecture
+
+**Impact: HIGH**
+
+Fundamental patterns for structuring components to avoid prop
+proliferation and enable flexible composition.
+
+### 1.1 Avoid Boolean Prop Proliferation
+
+**Impact: CRITICAL (prevents unmaintainable component variants)**
+
+Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
+
+component behavior. Each boolean doubles possible states and creates
+
+unmaintainable conditional logic. Use composition instead.
+
+**Incorrect: boolean props create exponential complexity**
+
+```tsx
+function Composer({
+ onSubmit,
+ isThread,
+ channelId,
+ isDMThread,
+ dmId,
+ isEditing,
+ isForwarding,
+}: Props) {
+ return (
+
+ )
+}
+```
+
+**Correct: composition eliminates conditionals**
+
+```tsx
+// Channel composer
+function ChannelComposer() {
+ return (
+
+
+
+
+ )
+}
+
+// Thread composer - adds "also send to channel" field
+function ThreadComposer({ channelId }: { channelId: string }) {
+ return (
+
+
+
+
+ )
+}
+
+// Edit composer - different footer actions
+function EditComposer() {
+ return (
+
+
+
+
+ )
+}
+```
+
+Each variant is explicit about what it renders. We can share internals without
+
+sharing a single monolithic parent.
+
+### 1.2 Use Compound Components
+
+**Impact: HIGH (enables flexible composition without prop drilling)**
+
+Structure complex components as compound components with a shared context. Each
+
+subcomponent accesses shared state via context, not props. Consumers compose the
+
+pieces they need.
+
+**Incorrect: monolithic component with render props**
+
+```tsx
+function Composer({
+ renderHeader,
+ renderFooter,
+ renderActions,
+ showAttachments,
+ showFormatting,
+ showEmojis,
+}: Props) {
+ return (
+
+ )
+}
+```
+
+**Correct: compound components with shared context**
+
+```tsx
+const ComposerContext = createContext(null)
+
+function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
+ return (
+
+ {children}
+
+ )
+}
+
+function ComposerFrame({ children }: { children: React.ReactNode }) {
+ return
+}
+
+function ComposerInput() {
+ const {
+ state,
+ actions: { update },
+ meta: { inputRef },
+ } = use(ComposerContext)
+ return (
+ update((s) => ({ ...s, input: text }))}
+ />
+ )
+}
+
+function ComposerSubmit() {
+ const {
+ actions: { submit },
+ } = use(ComposerContext)
+ return
+}
+
+// Export as compound component
+const Composer = {
+ Provider: ComposerProvider,
+ Frame: ComposerFrame,
+ Input: ComposerInput,
+ Submit: ComposerSubmit,
+ Header: ComposerHeader,
+ Footer: ComposerFooter,
+ Attachments: ComposerAttachments,
+ Formatting: ComposerFormatting,
+ Emojis: ComposerEmojis,
+}
+```
+
+**Usage:**
+
+```tsx
+
+
+
+
+
+
+```
+
+Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
+
+---
+
+## 2. State Management
+
+**Impact: MEDIUM**
+
+Patterns for lifting state and managing shared context across
+composed components.
+
+### 2.1 Decouple State Management from UI
+
+**Impact: MEDIUM (enables swapping state implementations without changing UI)**
+
+The provider component should be the only place that knows how state is managed.
+
+UI components consume the context interface—they don't know if state comes from
+
+useState, Zustand, or a server sync.
+
+**Incorrect: UI coupled to state implementation**
+
+```tsx
+function ChannelComposer({ channelId }: { channelId: string }) {
+ // UI component knows about global state implementation
+ const state = useGlobalChannelState(channelId)
+ const { submit, updateInput } = useChannelSync(channelId)
+
+ return (
+
+ sync.updateInput(text)}
+ />
+ sync.submit()} />
+
+ )
+}
+```
+
+**Correct: state management isolated in provider**
+
+```tsx
+// Provider handles all state management details
+function ChannelProvider({
+ channelId,
+ children,
+}: {
+ channelId: string
+ children: React.ReactNode
+}) {
+ const { state, update, submit } = useGlobalChannel(channelId)
+ const inputRef = useRef(null)
+
+ return (
+
+ {children}
+
+ )
+}
+
+// UI component only knows about the context interface
+function ChannelComposer() {
+ return (
+
+
+
+
+ )
+}
+
+// Usage
+function Channel({ channelId }: { channelId: string }) {
+ return (
+
+
+ )
+}
+```
+
+**Different providers, same UI:**
+
+```tsx
+// Local state for ephemeral forms
+function ForwardMessageProvider({ children }) {
+ const [state, setState] = useState(initialState)
+ const forwardMessage = useForwardMessage()
+
+ return (
+
+ {children}
+
+ )
+}
+
+// Global synced state for channels
+function ChannelProvider({ channelId, children }) {
+ const { state, update, submit } = useGlobalChannel(channelId)
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+The same `Composer.Input` component works with both providers because it only
+
+depends on the context interface, not the implementation.
+
+### 2.2 Define Generic Context Interfaces for Dependency Injection
+
+**Impact: HIGH (enables dependency-injectable state across use-cases)**
+
+Define a **generic interface** for your component context with three parts:
+
+`state`, `actions`, and `meta`. This interface is a contract that any provider
+
+can implement—enabling the same UI components to work with completely different
+
+state implementations.
+
+**Core principle:** Lift state, compose internals, make state
+
+dependency-injectable.
+
+**Incorrect: UI coupled to specific state implementation**
+
+```tsx
+function ComposerInput() {
+ // Tightly coupled to a specific hook
+ const { input, setInput } = useChannelComposerState()
+ return
+}
+
+interface ComposerContextValue {
+ state: ComposerState
+ actions: ComposerActions
+ meta: ComposerMeta
+}
+
+const ComposerContext = createContext(null)
+```
+
+**UI components consume the interface, not the implementation:**
+
+```tsx
+function ComposerInput() {
+ const {
+ state,
+ actions: { update },
+ meta,
+ } = use(ComposerContext)
+
+ // This component works with ANY provider that implements the interface
+ return (
+ update((s) => ({ ...s, input: text }))}
+ />
+ )
+}
+```
+
+**Different providers implement the same interface:**
+
+```tsx
+// Provider A: Local state for ephemeral forms
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+ const [state, setState] = useState(initialState)
+ const inputRef = useRef(null)
+ const submit = useForwardMessage()
+
+ return (
+
+ {children}
+
+ )
+}
+
+// Provider B: Global synced state for channels
+function ChannelProvider({ channelId, children }: Props) {
+ const { state, update, submit } = useGlobalChannel(channelId)
+ const inputRef = useRef(null)
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+**The same composed UI works with both:**
+
+```tsx
+// Works with ForwardMessageProvider (local state)
+
+
+
+
+
+// Works with ChannelProvider (global synced state)
+
+
+
+
+```
+
+**Custom UI outside the component can access state and actions:**
+
+```tsx
+function ForwardMessageDialog() {
+ return (
+
+
+
+ )
+}
+
+// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
+function ForwardButton() {
+ const {
+ actions: { submit },
+ } = use(ComposerContext)
+ return
+}
+
+// This preview lives OUTSIDE Composer.Frame but can read composer's state!
+function MessagePreview() {
+ const { state } = use(ComposerContext)
+ return
+
+ )
+}
+
+// Problem: How does this button access composer state?
+function ForwardMessageDialog() {
+ return (
+
+ )
+}
+```
+
+**Incorrect: useEffect to sync state up**
+
+```tsx
+function ForwardMessageDialog() {
+ const [input, setInput] = useState('')
+ return (
+
+ )
+}
+
+function ForwardMessageComposer({ onInputChange }) {
+ const [state, setState] = useState(initialState)
+ useEffect(() => {
+ onInputChange(state.input) // Sync on every change 😬
+ }, [state.input])
+}
+```
+
+**Incorrect: reading state from ref on submit**
+
+```tsx
+function ForwardMessageDialog() {
+ const stateRef = useRef(null)
+ return (
+
+ )
+}
+```
+
+**Correct: state lifted to provider**
+
+```tsx
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+ const [state, setState] = useState(initialState)
+ const forwardMessage = useForwardMessage()
+ const inputRef = useRef(null)
+
+ return (
+
+ {children}
+
+ )
+}
+
+function ForwardMessageDialog() {
+ return (
+
+
+
+ )
+}
+
+function ForwardButton() {
+ const { actions } = use(Composer.Context)
+ return
+}
+```
+
+The ForwardButton lives outside the Composer.Frame but still has access to the
+
+submit action because it's within the provider. Even though it's a one-off
+
+component, it can still access the composer's state and actions from outside the
+
+UI itself.
+
+**Key insight:** Components that need shared state don't have to be visually
+
+nested inside each other—they just need to be within the same provider.
+
+---
+
+## 3. Implementation Patterns
+
+**Impact: MEDIUM**
+
+Specific techniques for implementing compound components and
+context providers.
+
+### 3.1 Create Explicit Component Variants
+
+**Impact: MEDIUM (self-documenting code, no hidden conditionals)**
+
+Instead of one component with many boolean props, create explicit variant
+
+components. Each variant composes the pieces it needs. The code documents
+
+itself.
+
+**Incorrect: one component, many modes**
+
+```tsx
+// What does this component actually render?
+
+
+
+
+
+
+ )
+}
+
+function EditMessageComposer({ messageId }: { messageId: string }) {
+ return (
+
+
+
+
+
+
+ )
+}
+
+function ForwardMessageComposer({ messageId }: { messageId: string }) {
+ return (
+
+
+
+
+
+
+ )
+}
+```
+
+Each variant is explicit about:
+
+- What provider/state it uses
+
+- What UI elements it includes
+
+- What actions are available
+
+No boolean prop combinations to reason about. No impossible states.
+
+### 3.2 Prefer Composing Children Over Render Props
+
+**Impact: MEDIUM (cleaner composition, better readability)**
+
+Use `children` for composition instead of `renderX` props. Children are more
+
+readable, compose naturally, and don't require understanding callback
+
+signatures.
+
+**Incorrect: render props**
+
+```tsx
+function Composer({
+ renderHeader,
+ renderFooter,
+ renderActions,
+}: {
+ renderHeader?: () => React.ReactNode
+ renderFooter?: () => React.ReactNode
+ renderActions?: () => React.ReactNode
+}) {
+ return (
+
+ )
+}
+
+// Usage is awkward and inflexible
+return (
+
+
+
+
+)
+```
+
+**When render props are appropriate:**
+
+```tsx
+// Render props work well when you need to pass data back
+
Content
+
+// Bad: Invalid - p inside p
+Nested
+ +// Good: Valid nesting +Content
+
+// Good: Use next/image
+import Image from 'next/image'
+
+
+```
+
+## Remote Images Configuration
+
+Remote domains must be configured in `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+ images: {
+ remotePatterns: [
+ {
+ protocol: 'https',
+ hostname: 'example.com',
+ pathname: '/images/**',
+ },
+ {
+ protocol: 'https',
+ hostname: '*.cdn.com', // Wildcard subdomain
+ },
+ ],
+ },
+}
+```
+
+## Responsive Images
+
+Use `sizes` to tell the browser which size to download:
+
+```tsx
+// Full-width hero
+
+ Hello World
+
+ ),
+ { ...size }
+ )
+}
+```
+
+## Dynamic OG Image
+
+```tsx
+// app/blog/[slug]/opengraph-image.tsx
+import { ImageResponse } from 'next/og'
+
+export const alt = 'Blog Post'
+export const size = { width: 1200, height: 630 }
+export const contentType = 'image/png'
+
+type Props = { params: Promise<{ slug: string }> }
+
+export default async function Image({ params }: Props) {
+ const { slug } = await params
+ const post = await getPost(slug)
+
+ return new ImageResponse(
+ (
+
+
+ ),
+ { ...size }
+ )
+}
+```
+
+## Custom Fonts
+
+```tsx
+import { ImageResponse } from 'next/og'
+import { join } from 'path'
+import { readFile } from 'fs/promises'
+
+export default async function Image() {
+ const fontPath = join(process.cwd(), 'assets/fonts/Inter-Bold.ttf')
+ const fontData = await readFile(fontPath)
+
+ return new ImageResponse(
+ (
+ {post.title}
+ {post.description}
+
+ Custom Font Text
+
+ ),
+ {
+ width: 1200,
+ height: 630,
+ fonts: [{ name: 'Inter', data: fontData, style: 'normal' }],
+ }
+ )
+}
+```
+
+## File Naming
+
+- `opengraph-image.tsx` - Open Graph (Facebook, LinkedIn)
+- `twitter-image.tsx` - Twitter/X cards (optional, falls back to OG)
+
+## Styling Notes
+
+ImageResponse uses Flexbox layout:
+- Use `display: 'flex'`
+- No CSS Grid support
+- Styles must be inline objects
+
+## Multiple OG Images
+
+Use `generateImageMetadata` for multiple images per route:
+
+```tsx
+// app/blog/[slug]/opengraph-image.tsx
+import { ImageResponse } from 'next/og'
+
+export async function generateImageMetadata({ params }) {
+ const images = await getPostImages(params.slug)
+ return images.map((img, idx) => ({
+ id: idx,
+ alt: img.alt,
+ size: { width: 1200, height: 630 },
+ contentType: 'image/png',
+ }))
+}
+
+export default async function Image({ params, id }) {
+ const images = await getPostImages(params.slug)
+ const image = images[id]
+ return new ImageResponse(/* ... */)
+}
+```
+
+## Multiple Sitemaps
+
+Use `generateSitemaps` for large sites:
+
+```tsx
+// app/sitemap.ts
+import type { MetadataRoute } from 'next'
+
+export async function generateSitemaps() {
+ // Return array of sitemap IDs
+ return [{ id: 0 }, { id: 1 }, { id: 2 }]
+}
+
+export default async function sitemap({
+ id,
+}: {
+ id: number
+}): Promise
+
+
+ );
+}
+```
+
+## Step 5: Modal Component with Correct Closing
+
+**Critical: Use `router.back()` to close modals, NOT `router.push()` or ``.**
+
+```tsx
+// components/modal.tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { useCallback, useEffect, useRef } from 'react';
+
+export function Modal({ children }: { children: React.ReactNode }) {
+ const router = useRouter();
+ const overlayRef = useRef{photo.title}
+
+
+ );
+}
+```
+
+### Why NOT `router.push('/')` or ``?
+
+Using `push` or `Link` to "close" a modal:
+1. Adds a new history entry (back button shows modal again)
+2. Doesn't properly clear the intercepted route
+3. Can cause the modal to flash or persist unexpectedly
+
+`router.back()` correctly:
+1. Removes the intercepted route from history
+2. Returns to the previous page
+3. Properly unmounts the modal
+
+## Route Matcher Reference
+
+Matchers match **route segments**, not filesystem paths:
+
+| Matcher | Matches | Example |
+|---------|---------|---------|
+| `(.)` | Same level | `@modal/(.)photos` intercepts `/photos` |
+| `(..)` | One level up | `@modal/(..)settings` from `/dashboard/@modal` intercepts `/settings` |
+| `(..)(..)` | Two levels up | Rarely used |
+| `(...)` | From root | `@modal/(...)photos` intercepts `/photos` from anywhere |
+
+**Common mistake**: Thinking `(..)` means "parent folder" - it means "parent route segment".
+
+## Handling Hard Navigation
+
+When users directly visit `/photos/123` (bookmark, refresh, shared link):
+- The intercepting route is bypassed
+- The full `photos/[id]/page.tsx` renders
+- Modal doesn't appear (expected behavior)
+
+If you want the modal to appear on direct access too, you need additional logic:
+
+```tsx
+// app/photos/[id]/page.tsx
+import { Modal } from '@/components/modal';
+
+export default async function PhotoPage({ params }) {
+ const { id } = await params;
+ const photo = await getPhoto(id);
+
+ // Option: Render as modal on direct access too
+ return (
+
+
+ {children}
+
+
+ {photos.map(photo => (
+
+ 
+
+ ))}
+
+ );
+}
+```
+
+Clicking a photo → Modal opens (intercepted)
+Direct URL → Full page renders
+Refresh while modal open → Full page renders
diff --git a/.agent/skills/next-best-practices/route-handlers.md b/.agent/skills/next-best-practices/route-handlers.md
new file mode 100644
index 00000000..25e6f4d7
--- /dev/null
+++ b/.agent/skills/next-best-practices/route-handlers.md
@@ -0,0 +1,146 @@
+# Route Handlers
+
+Create API endpoints with `route.ts` files.
+
+## Basic Usage
+
+```tsx
+// app/api/users/route.ts
+export async function GET() {
+ const users = await getUsers()
+ return Response.json(users)
+}
+
+export async function POST(request: Request) {
+ const body = await request.json()
+ const user = await createUser(body)
+ return Response.json(user, { status: 201 })
+}
+```
+
+## Supported Methods
+
+`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
+
+## GET Handler Conflicts with page.tsx
+
+**A `route.ts` and `page.tsx` cannot coexist in the same folder.**
+
+```
+app/
+├── api/
+│ └── users/
+│ └── route.ts # /api/users
+└── users/
+ ├── page.tsx # /users (page)
+ └── route.ts # Warning: Conflicts with page.tsx!
+```
+
+If you need both a page and an API at the same path, use different paths:
+
+```
+app/
+├── users/
+│ └── page.tsx # /users (page)
+└── api/
+ └── users/
+ └── route.ts # /api/users (API)
+```
+
+## Environment Behavior
+
+Route handlers run in a **Server Component-like environment**:
+
+- Yes: Can use `async/await`
+- Yes: Can access `cookies()`, `headers()`
+- Yes: Can use Node.js APIs
+- No: Cannot use React hooks
+- No: Cannot use React DOM APIs
+- No: Cannot use browser APIs
+
+```tsx
+// Bad: This won't work - no React DOM in route handlers
+import { renderToString } from 'react-dom/server'
+
+export async function GET() {
+ const html = renderToString({user.name}
+}
+
+// Good: Remove async, fetch data in parent server component
+// page.tsx (server component - no 'use client')
+export default async function Page() {
+ const user = await getUser()
+ return {user.name}
+}
+```
+
+```tsx
+// Bad: async arrow function client component
+'use client'
+const Dashboard = async () => {
+ const data = await fetchDashboard()
+ return {data}
+}
+
+// Good: Fetch in server component, pass data down
+```
+
+### 2. Non-Serializable Props to Client Components
+
+Props passed from Server → Client must be JSON-serializable.
+
+**Detect:** Server component passes these to a client component:
+- Functions (except Server Actions with `'use server'`)
+- `Date` objects
+- `Map`, `Set`, `WeakMap`, `WeakSet`
+- Class instances
+- `Symbol` (unless globally registered)
+- Circular references
+
+```tsx
+// Bad: Function prop
+// page.tsx (server)
+export default function Page() {
+ const handleClick = () => console.log('clicked')
+ return
+
+
+
+
+
diff --git a/marketing/ad-10-1taka/index.html b/marketing/ad-10-1taka/index.html
new file mode 100644
index 00000000..ef35e892
--- /dev/null
+++ b/marketing/ad-10-1taka/index.html
@@ -0,0 +1,74 @@
+
+
+
+
+
+
+
+ ব্যবসা বাড়ান
+
+
+
+
+
+ LATEST TECH STACK
+ 🚀 New Launch Challenge
+
+ ব্যবসা বাড়ান
১ টাকার চ্যালেঞ্জে
+
+ + ফেসবুকের মেসেঞ্জার অর্ডার নিয়ে ক্লান্ত? প্রথম ১০০ জন লাকি মার্চেন্টকে ১ টাকায় সব সেটআপ করে দিচ্ছি। +
+
+
+
+
+ ৳১
+ Full Setup Fee
+ Save ৳5,000 in dev costs
+
+
+
+
+ 🚚
+
+
+ Pathao Auto-Booking
+ডেলিভারি বুকিং এখন হবে অটোমেটিক, মাত্র এক ক্লিকে।
+
+
+
+
+ 💳
+
+
+ bKash/Nagad Native
+সরাসরি বিকাশ ও নগদে পেমেন্ট নেওয়ার নিশ্চিন্ত সুবিধা।
+
+
+
+
+ Ready to dominate F-Commerce? Join the waitlist for first 100.
+
+
+
+
+
+
+
+
+
+
+ LIMITED TIME OFFER: FIRST 100 MERCHANTS
+
+
+
+
+
+
+
+
+ ৳১
+
+
+ Setup Fee!
+
+ ১ টাকায় ই-কমার্স ওয়েবসাইট!
++ আপনার ফেসবুক পেজের সব প্রোডাক্ট আমরাই StormCom-এ সেটআপ করে দিবো। কোনো ঝামেলা ছাড়াই নিজের ওয়েবসাইট চালু করুন। +
+ + +
+
+
+
+
+
+ 📦
+
+
+ 20 Products
+ Full Setup
+
+
+ 🚚
+
+
+ Pathao
+ Ready to Ship
+
+
+
+ Claim Offer Now
+
+ WWW.CODESTORMHUB.LIVE
+✨
+ ⚡
+
+
diff --git a/marketing/ad-10-1taka/mobile-story.html b/marketing/ad-10-1taka/mobile-story.html
new file mode 100644
index 00000000..f9d55998
--- /dev/null
+++ b/marketing/ad-10-1taka/mobile-story.html
@@ -0,0 +1,89 @@
+
+
+
+
+
+
+
+
+
+ ব্যবসা শুরু করুন
+
+
+
+
diff --git a/marketing/ad-10-1taka/modern-minimal.html b/marketing/ad-10-1taka/modern-minimal.html
new file mode 100644
index 00000000..e1117204
--- /dev/null
+++ b/marketing/ad-10-1taka/modern-minimal.html
@@ -0,0 +1,80 @@
+
+
+
+
+
+
+ NEW LAUNCH OFFER
+
+
+
+ ব্যবসা শুরু করুন
+ মাত্র ১ টাকায়!
+
+
+ 🪙
+
+
+
+
+
+
+
+ কেন StormCom?
+-
+
- ✨ ২০টি প্রোডাক্ট সেটআপ ফ্রি +
- ✨ অটোমেটিক পাঠাও বুকিং +
- ✨ সরাসরি বিকাশ পেমেন্ট +
+ LIMITED TO FIRST 100 MERCHANTS!
+
+
+
+
+
+ Claim Offer NOW
+
+
+ WWW.CODESTORMHUB.LIVE
+
+
+
+
+
diff --git a/marketing/ad-10-1taka/neubrutalist.html b/marketing/ad-10-1taka/neubrutalist.html
new file mode 100644
index 00000000..9a513ad3
--- /dev/null
+++ b/marketing/ad-10-1taka/neubrutalist.html
@@ -0,0 +1,78 @@
+
+
+
+
+
+
+
+
+
+
+ PROMO ID: SC2026
+
+
+
+ ৳১
+
+
+ আপনার ডিজিটাল বিজনেস শুরু হোক আজই!
+স্মার্ট বাংলাদেশে স্মার্ট ই-কমার্স।
+
+
+
+ Limited to first 100 people
+
+
+ + ১ টাকায় সবকিছু সেটআপ! +
+ +
+
+
+
+
+
+
+
+
+ ✅
+
+
+ ফুল প্রোডাক্ট আপলোড
+আপনার ২০টি প্রোডাক্ট আমরা নিজে হাতে সাজিয়ে দিবো।
+
+
+ ✅
+
+
+ পেমেন্ট গেটওয়ে কানেক্ট
+বিকাশ, নগদ এবং কার্ড পেমেন্ট এক্টিভেশন।
+
+
+ ✅
+
+
+ পাঠাও ইন্টিগ্রেশন
+অটোমেটিক ডেলিভারি বুকিং সুবিধা।
++ www.codestormhub.live +
+
+
+
+
+
diff --git a/marketing/ad-10-1taka/race-reel.html b/marketing/ad-10-1taka/race-reel.html
new file mode 100644
index 00000000..61d47f9a
--- /dev/null
+++ b/marketing/ad-10-1taka/race-reel.html
@@ -0,0 +1,189 @@
+
+
+
+
+
+
+
+
+
+ STORMCOM.
+ Limited 100 Spots / ১০০ জন মাত্র
+
+
+
+
+
+
+
+
+
+
+ ১ টাকার
+
+
+
+ ১ টাকার
চ্যালেঞ্জ
+
+ + আপনার ফেসবুক পেজকে প্রফেশনাল ওয়েবসাইটে রূপান্তর করুন। আমরাই সব করে দিচ্ছি! +
+
+
+
+
+ 🚚
+ Auto Pathao
+বুকিং হবে অটোমেটিক
+
+
+ 💰
+ Native bKash
+সরাসরি পেমেন্ট সুবিধা
+
+
+ ৳১
+ SETUP FEE
+
+ No hidden costs. No bullshit. Just 1 Taka.
+
+
+
+
+
+
+
+
+ SIGN UP NOW AT CODESTORMHUB.LIVE — NO CODING REQUIRED — PATHAO INTEGRATED — BKASH INTEGRATED — ONLY 1 TAKA SETUP — JOIN 100+ MERCHANTS — SIGN UP NOW AT CODESTORMHUB.LIVE — NO CODING REQUIRED — PATHAO INTEGRATED — BKASH INTEGRATED — ONLY 1 TAKA SETUP — JOIN 100+ MERCHANTS —
+
+
+
+
+
+
+
+
+
+ Manual Work
+ 00:00
+ Messenger Orders
+ +
+
+ "I want to order this shirt."
+ "Please send address & phone."
+
+
+ Typing into Pathao Panel...
+House 12, Road 5, Dhanmondi...
+ Still booking delivery...
+
+
+ StormCom Automation
+ 00:00
+ Auto-Pilot Sales
+ +
+
+
+ New Order #8921
+ PAID
+
+
+
+ 1-Click Booking
+
+ SYNC TO PATHAO
+
+
+
+ ✨
+ DONE!
Label Printed.
+ Label Printed.
STORMCOM WINS!
+
+
+
+
diff --git a/marketing/ad-10-1taka/super-reel.html b/marketing/ad-10-1taka/super-reel.html
new file mode 100644
index 00000000..1a10f9e4
--- /dev/null
+++ b/marketing/ad-10-1taka/super-reel.html
@@ -0,0 +1,176 @@
+
+
+
+
+
+
+
+
+
+ CODESTORMHUB.LIVE — NO CODING REQUIRED — PATHAO INTEGRATED — BKASH INTEGRATED — ONLY 1 TAKA SETUP — JOIN 100+ MERCHANTS — CODESTORMHUB.LIVE — NO CODING REQUIRED — PATHAO INTEGRATED —
+
+
+
+
+ Limited: 100 Slots Only
+
+
+ মেসেঞ্জারে
+ অর্ডার নেওয়া
+ বন্ধ করুন! +
+
+ + অর্ডার নেওয়া
+ বন্ধ করুন! +
+ ১ টাকার চ্যালেঞ্জে
+ নিজের ওয়েবসাইট শুরু করুন। +
+
+ + নিজের ওয়েবসাইট শুরু করুন। +
+
+
+
+ 🚚
+ Pathao Auto-Booking
+
+
+ 💰
+ Direct bKash Payment
+
+
+
+
+
+
+
diff --git a/marketing/ad-2/index.html b/marketing/ad-2/index.html
new file mode 100644
index 00000000..1e9004cd
--- /dev/null
+++ b/marketing/ad-2/index.html
@@ -0,0 +1,93 @@
+
+
+
+
+
+ SETUP
+ ৳১
+ CHALLENGE
+ - } +/> +``` + +Use render props when the parent needs to provide data or state to the child. + +Use children when composing static structure. + +--- + +## 4. React 19 APIs + +**Impact: MEDIUM** + +React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`. + +### 4.1 React 19 API Changes + +**Impact: MEDIUM (cleaner component definitions and context usage)** + +> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier. + +In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`. + +**Incorrect: forwardRef in React 19** + +```tsx +const ComposerInput = forwardRef
- } +/> +``` + +Use render props when the parent needs to provide data or state to the child. +Use children when composing static structure. diff --git a/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md b/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md new file mode 100644 index 00000000..56e32e8b --- /dev/null +++ b/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md @@ -0,0 +1,100 @@ +--- +title: Create Explicit Component Variants +impact: MEDIUM +impactDescription: self-documenting code, no hidden conditionals +tags: composition, variants, architecture +--- + +## Create Explicit Component Variants + +Instead of one component with many boolean props, create explicit variant +components. Each variant composes the pieces it needs. The code documents +itself. + +**Incorrect (one component, many modes):** + +```tsx +// What does this component actually render? +
- + }} + /> +) +``` + +**Correct: a single function instance passed to each item** + +```typescript +const onPress = useCallback(() => handlePress(item.id), [handlePress, item.id]) + +return ( +
- + )} + /> +) +``` + +Reference: [https://example.com](https://example.com) + +### 2.3 Keep List Items Lightweight + +**Impact: HIGH (reduces render time for visible items during scroll)** + +List items should be as inexpensive as possible to render. Minimize hooks, avoid + +queries, and limit React Context access. Virtualized lists render many items + +during scroll—expensive items cause jank. + +**Incorrect: heavy list item** + +```tsx +function ProductRow({ id }: { id: string }) { + // Bad: query inside list item + const { data: product } = useQuery(['product', id], () => fetchProduct(id)) + // Bad: multiple context accesses + const theme = useContext(ThemeContext) + const user = useContext(UserContext) + const cart = useContext(CartContext) + // Bad: expensive computation + const recommendations = useMemo( + () => computeRecommendations(product), + [product] + ) + + return
- + }} + /> +) +``` + +**Correct (a single function instance passed to each item):** + +```typescript +const onPress = useCallback(() => handlePress(item.id), [handlePress, item.id]) + +return ( +
- + )} + /> +) +``` + +Reference: [Link to documentation or resource](https://example.com) diff --git a/skills/vercel-react-native-skills/rules/list-performance-function-references.md b/skills/vercel-react-native-skills/rules/list-performance-function-references.md new file mode 100644 index 00000000..9721929b --- /dev/null +++ b/skills/vercel-react-native-skills/rules/list-performance-function-references.md @@ -0,0 +1,132 @@ +--- +title: Optimize List Performance with Stable Object References +impact: CRITICAL +impactDescription: virtualization relies on reference stability +tags: lists, performance, flatlist, virtualization +--- + +## Optimize List Performance with Stable Object References + +Don't map or filter data before passing to virtualized lists. Virtualization +relies on object reference stability to know what changed—new references cause +full re-renders of all visible items. Attempt to prevent frequent renders at the +list-parent level. + +Where needed, use context selectors within list items. + +**Incorrect (creates new object references on every keystroke):** + +```tsx +function DomainSearch() { + const { keyword, setKeyword } = useKeywordZustandState() + const { data: tlds } = useTlds() + + // Bad: creates new objects on every render, reparenting the entire list on every keystroke + const domains = tlds.map((tld) => ({ + domain: `${keyword}.${tld.name}`, + tld: tld.name, + price: tld.price, + })) + + return ( + <> +
+
+ )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct: wrapper shows immediately, data streams in**
+
+```tsx
+function Page() {
+ return (
+ Sidebar
+ Header
+
+
+ Footer
+
+
+ )
+}
+
+async function DataDisplay() {
+ const data = await fetchData() // Only blocks this component
+ return Sidebar
+ Header
+
+
+ Footer
+ {data.content}
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative: share promise across components**
+
+```tsx
+function Page() {
+ // Start fetch immediately, but don't await
+ const dataPromise = fetchData()
+
+ return (
+
+
+ )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise }) {
+ const data = use(dataPromise) // Unwraps the promise
+ return Sidebar
+ Header
+ Footer
+ {data.content}
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise }) {
+ const data = use(dataPromise) // Reuses the same promise
+ return {data.summary}
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+
+- SEO-critical content above the fold
+
+- Small, fast queries where suspense overhead isn't worth it
+
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
+
+---
+
+## 2. Bundle Size Optimization
+
+**Impact: CRITICAL**
+
+Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+### 2.1 Avoid Barrel File Imports
+
+**Impact: CRITICAL (200-800ms import cost, slow builds)**
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect: imports entire library**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct: imports only what you need**
+
+```tsx
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+// Loads only 3 modules (~2KB vs ~1MB)
+
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+**Alternative: Next.js 13.5+**
+
+```js
+// next.config.js - use optimizePackageImports
+module.exports = {
+ experimental: {
+ optimizePackageImports: ['lucide-react', '@mui/material']
+ }
+}
+
+// Then you can keep the ergonomic barrel imports:
+import { Check, X, Menu } from 'lucide-react'
+// Automatically transformed to direct imports at build time
+```
+
+Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+
+### 2.2 Conditional Module Loading
+
+**Impact: HIGH (loads large data only when needed)**
+
+Load large data or modules only when a feature is activated.
+
+**Example: lazy-load animation frames**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch{user.name}
// uses 1 field
+}
+```
+
+**Correct: serializes only 1 field**
+
+```tsx
+async function Page() {
+ const user = await fetchUser()
+ return {name}
+}
+```
+
+### 3.6 Parallel Data Fetching with Component Composition
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect: Sidebar waits for Page's fetch to complete**
+
+```tsx
+export default async function Page() {
+ const header = await fetchHeader()
+ return (
+
+
+ )
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+```
+
+**Correct: both fetch simultaneously**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {header}
+ {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+
+export default function Page() {
+ return (
+
+
+ )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+
+function Layout({ children }: { children: ReactNode }) {
+ return (
+
+
+ )
+}
+
+export default function Page() {
+ return (
+ {fullName}
+} +``` + +**Correct: derive during render** + +```tsx +function Form() { + const [firstName, setFirstName] = useState('First') + const [lastName, setLastName] = useState('Last') + const fullName = firstName + ' ' + lastName + + return{fullName}
+} +``` + +Reference: [https://react.dev/learn/you-might-not-need-an-effect](https://react.dev/learn/you-might-not-need-an-effect) + +### 5.2 Defer State Reads to Usage Point + +**Impact: MEDIUM (avoids unnecessary subscriptions)** + +Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks. + +**Incorrect: subscribes to all searchParams changes** + +```tsx +function ShareButton({ chatId }: { chatId: string }) { + const searchParams = useSearchParams() + + const handleShare = () => { + const ref = searchParams.get('ref') + shareChat(chatId, { ref }) + } + + return +} +``` + +**Correct: reads on demand, no subscription** + +```tsx +function ShareButton({ chatId }: { chatId: string }) { + const handleShare = () => { + const params = new URLSearchParams(window.location.search) + const ref = params.get('ref') + shareChat(chatId, { ref }) + } + + return +} +``` + +### 5.3 Do not wrap a simple expression with a primitive result type in useMemo + +**Impact: LOW-MEDIUM (wasted computation on every render)** + +When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`. + +Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself. + +**Incorrect:** + +```tsx +function Header({ user, notifications }: Props) { + const isLoading = useMemo(() => { + return user.isLoading || notifications.isLoading + }, [user.isLoading, notifications.isLoading]) + + if (isLoading) return
+ {user.followers} followers
+ {user.posts} posts
+
+ )
+
+ return (
+
+
+ )
+}
+```
+
+Every time `UserProfile` renders, `Avatar` and `Stats` are new component types. React unmounts the old instances and mounts new ones, losing any internal state, running effects again, and recreating DOM nodes.
+
+**Correct: pass props instead**
+
+```tsx
+function Avatar({ src, theme }: { src: string; theme: string }) {
+ return (
+
+ {followers} followers
+ {posts} posts
+
+ )
+}
+
+function UserProfile({ user, theme }) {
+ return (
+
+
+ )
+}
+```
+
+**Symptoms of this bug:**
+
+- Input fields lose focus on every keystroke
+
+- Animations restart unexpectedly
+
+- `useEffect` cleanup/setup runs on every parent render
+
+- Scroll position resets inside the component
+
+### 5.5 Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+**Impact: MEDIUM (restores memoization by using a constant for default value)**
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect: `onClick` has different values on every rerender**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+ // ...
+})
+
+// Used without optional onClick
+{avatar}
+}
+```
+
+**Correct: skips computation when loading**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+ const id = useMemo(() => computeAvatarId(user), [user])
+ return
+
+ )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
+
+### 5.7 Narrow Effect Dependencies
+
+**Impact: LOW (minimizes effect re-runs)**
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect: re-runs on any user field change**
+
+```tsx
+useEffect(() => {
+ console.log(user.id)
+}, [user])
+```
+
+**Correct: re-runs only when id changes**
+
+```tsx
+useEffect(() => {
+ console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+ if (width < 768) {
+ enableMobileMode()
+ }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+ if (isMobile) {
+ enableMobileMode()
+ }
+}, [isMobile])
+```
+
+### 5.8 Put Interaction Logic in Event Handlers
+
+**Impact: MEDIUM (avoids effect re-runs and duplicate side effects)**
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect: event modeled as state + effect**
+
+```tsx
+function Form() {
+ const [submitted, setSubmitted] = useState(false)
+ const theme = useContext(ThemeContext)
+
+ useEffect(() => {
+ if (submitted) {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+ }, [submitted, theme])
+
+ return
+}
+```
+
+**Correct: do it in the handler**
+
+```tsx
+function Form() {
+ const theme = useContext(ThemeContext)
+
+ function handleSubmit() {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+
+ return
+}
+```
+
+Reference: [https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
+
+### 5.9 Subscribe to Derived State
+
+**Impact: MEDIUM (reduces re-render frequency)**
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect: re-renders on every pixel change**
+
+```tsx
+function Sidebar() {
+ const width = useWindowWidth() // updates continuously
+ const isMobile = width < 768
+ return
+}
+```
+
+**Correct: re-renders only when boolean changes**
+
+```tsx
+function Sidebar() {
+ const isMobile = useMediaQuery('(max-width: 767px)')
+ return
+}
+```
+
+### 5.10 Use Functional setState Updates
+
+**Impact: MEDIUM (prevents stale closures and unnecessary callback recreations)**
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect: requires state as dependency**
+
+```tsx
+function TodoList() {
+ const [items, setItems] = useState(initialItems)
+
+ // Callback must depend on items, recreated on every items change
+ const addItems = useCallback((newItems: Item[]) => {
+ setItems([...items, ...newItems])
+ }, [items]) // ❌ items dependency causes recreations
+
+ // Risk of stale closure if dependency is forgotten
+ const removeItem = useCallback((id: string) => {
+ setItems(items.filter(item => item.id !== id))
+ }, []) // ❌ Missing items dependency - will use stale items!
+
+ return ` and animate the wrapper instead.
+
+**Incorrect: animating SVG directly - no hardware acceleration**
+
+```tsx
+function LoadingSpinner() {
+ return (
+
+ )
+}
+```
+
+**Correct: animating wrapper div - hardware accelerated**
+
+```tsx
+function LoadingSpinner() {
+ return (
+ ` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+ return (
+
+
+ )
+}
+```
+
+Avoids expensive re-renders and state loss.
+
+### 6.8 Use defer or async on Script Tags
+
+**Impact: HIGH (eliminates render-blocking)**
+
+Script tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.
+
+- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order
+
+- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order
+
+Use `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.
+
+**Incorrect: blocks rendering**
+
+```tsx
+export default function Document() {
+ return (
+
+
+
+
+
+ {/* content */}
+
+ )
+}
+```
+
+**Correct: non-blocking**
+
+```tsx
+import Script from 'next/script'
+
+export default function Page() {
+ return (
+ <>
+
+
+
+ )
+}
+```
+
+**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:
+
+Reference: [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)
+
+### 6.9 Use Explicit Conditional Rendering
+
+**Impact: LOW (prevents rendering 0 or NaN)**
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect: renders "0" when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+ return (
+ {/* content */}
+}
+```
+
+**Example: preload critical fonts and styles**
+
+```tsx
+import { preload, preinit } from 'react-dom'
+
+export default function RootLayout({ children }) {
+ // Preload font file
+ preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })
+
+ // Fetch and apply critical stylesheet immediately
+ preinit('/styles/critical.css', { as: 'style' })
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+**Example: preload modules for code-split routes**
+
+```tsx
+import { preloadModule, preinitModule } from 'react-dom'
+
+function Navigation() {
+ const preloadDashboard = () => {
+ preloadModule('/dashboard.js', { as: 'script' })
+ }
+
+ return (
+
+ )
+}
+```
+
+**When to use each:**
+
+| API | Use case |
+
+|-----|----------|
+
+| `prefetchDNS` | Third-party domains you'll connect to later |
+
+| `preconnect` | APIs or CDNs you'll fetch from immediately |
+
+| `preload` | Critical resources needed for current page |
+
+| `preloadModule` | JS modules for likely next navigation |
+
+| `preinit` | Stylesheets/scripts that must execute early |
+
+| `preinitModule` | ES modules that must execute early |
+
+Reference: [https://react.dev/reference/react-dom#resource-preloading-apis](https://react.dev/reference/react-dom#resource-preloading-apis)
+
+### 6.11 Use useTransition Over Manual Loading States
+
+**Impact: LOW (reduces re-renders and improves code clarity)**
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect: manual loading state**
+
+```tsx
+function SearchResults() {
+ const [query, setQuery] = useState('')
+ const [results, setResults] = useState([])
+ const [isLoading, setIsLoading] = useState(false)
+
+ const handleSearch = async (value: string) => {
+ setIsLoading(true)
+ setQuery(value)
+ const data = await fetchResults(value)
+ setResults(data)
+ setIsLoading(false)
+ }
+
+ return (
+ <>
+ handleSearch(e.target.value)} />
+ {isLoading && (null)
+
+ useEffect(() => {
+ if (ref.current && isHighlighted) {
+ ref.current.style.width = '100px'
+ const width = ref.current.offsetWidth // Forces layout
+ ref.current.style.height = '200px'
+ }
+ }, [isHighlighted])
+
+ return ()
+
+function cachedSlugify(text: string): string {
+ if (slugifyCache.has(text)) {
+ return slugifyCache.get(text)!
+ }
+ const result = slugify(text)
+ slugifyCache.set(text, result)
+ return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+ return (
+ ()
+
+function getLocalStorage(key: string) {
+ if (!storageCache.has(key)) {
+ storageCache.set(key, localStorage.getItem(key))
+ }
+ return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+ localStorage.setItem(key, value)
+ storageCache.set(key, value) // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record | null = null
+
+function getCookie(name: string) {
+ if (!cookieCache) {
+ cookieCache = Object.fromEntries(
+ document.cookie.split('; ').map(c => c.split('='))
+ )
+ }
+ return cookieCache[name]
+}
+```
+
+**Important: invalidate on external changes**
+
+```typescript
+window.addEventListener('storage', (e) => {
+ if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+ if (document.visibilityState === 'visible') {
+ storageCache.clear()
+ }
+})
+```
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+### 7.6 Combine Multiple Array Iterations
+
+**Impact: LOW-MEDIUM (reduces iterations)**
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect: 3 iterations**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct: 1 iteration**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+ if (user.isAdmin) admins.push(user)
+ if (user.isTester) testers.push(user)
+ if (!user.isActive) inactive.push(user)
+}
+```
+
+### 7.7 Early Length Check for Array Comparisons
+
+**Impact: MEDIUM-HIGH (avoids expensive operations when lengths differ)**
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect: always runs expensive comparison**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+ // Always sorts and joins, even when lengths differ
+ return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+ // Early return if lengths differ
+ if (current.length !== original.length) {
+ return true
+ }
+ // Only sort when lengths match
+ const currentSorted = current.toSorted()
+ const originalSorted = original.toSorted()
+ for (let i = 0; i < currentSorted.length; i++) {
+ if (currentSorted[i] !== originalSorted[i]) {
+ return true
+ }
+ }
+ return false
+}
+```
+
+This new approach is more efficient because:
+
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+
+- It avoids mutating the original arrays
+
+- It returns early when a difference is found
+
+### 7.8 Early Return from Functions
+
+**Impact: LOW-MEDIUM (avoids unnecessary computation)**
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect: processes all items even after finding answer**
+
+```typescript
+function validateUsers(users: User[]) {
+ let hasError = false
+ let errorMessage = ''
+
+ for (const user of users) {
+ if (!user.email) {
+ hasError = true
+ errorMessage = 'Email required'
+ }
+ if (!user.name) {
+ hasError = true
+ errorMessage = 'Name required'
+ }
+ // Continues checking all users even after error found
+ }
+
+ return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct: returns immediately on first error**
+
+```typescript
+function validateUsers(users: User[]) {
+ for (const user of users) {
+ if (!user.email) {
+ return { valid: false, error: 'Email required' }
+ }
+ if (!user.name) {
+ return { valid: false, error: 'Name required' }
+ }
+ }
+
+ return { valid: true }
+}
+```
+
+### 7.9 Hoist RegExp Creation
+
+**Impact: LOW-MEDIUM (avoids recreation)**
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect: new RegExp every render**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+ const regex = new RegExp(`(${query})`, 'gi')
+ const parts = text.split(regex)
+ return <>{parts.map((part, i) => ...)}
+}
+```
+
+**Correct: memoize or hoist**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+ const regex = useMemo(
+ () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+ [query]
+ )
+ const parts = text.split(regex)
+ return <>{parts.map((part, i) => ...)}
+}
+```
+
+**Warning: global regex has mutable state**
+
+```typescript
+const regex = /foo/g
+regex.test('foo') // true, lastIndex = 3
+regex.test('foo') // false, lastIndex = 0
+```
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+### 7.10 Use flatMap to Map and Filter in One Pass
+
+**Impact: LOW-MEDIUM (eliminates intermediate array)**
+
+Chaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.
+
+**Incorrect: 2 iterations, intermediate array**
+
+```typescript
+const userNames = users
+ .map(user => user.isActive ? user.name : null)
+ .filter(Boolean)
+```
+
+**Correct: 1 iteration, no intermediate array**
+
+```typescript
+const userNames = users.flatMap(user =>
+ user.isActive ? [user.name] : []
+)
+```
+
+**More examples:**
+
+```typescript
+// Extract valid emails from responses
+// Before
+const emails = responses
+ .map(r => r.success ? r.data.email : null)
+ .filter(Boolean)
+
+// After
+const emails = responses.flatMap(r =>
+ r.success ? [r.data.email] : []
+)
+
+// Parse and filter valid numbers
+// Before
+const numbers = strings
+ .map(s => parseInt(s, 10))
+ .filter(n => !isNaN(n))
+
+// After
+const numbers = strings.flatMap(s => {
+ const n = parseInt(s, 10)
+ return isNaN(n) ? [] : [n]
+})
+```
+
+**When to use:**
+
+- Transforming items while filtering some out
+
+- Conditional mapping where some inputs produce no output
+
+- Parsing/validating where invalid inputs should be skipped
+
+### 7.11 Use Loop for Min/Max Instead of Sort
+
+**Impact: LOW (O(n) instead of O(n log n))**
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+ id: string
+ name: string
+ updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+ const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+ return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+ const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+ return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+ if (projects.length === 0) return null
+
+ let latest = projects[0]
+
+ for (let i = 1; i < projects.length; i++) {
+ if (projects[i].updatedAt > latest.updatedAt) {
+ latest = projects[i]
+ }
+ }
+
+ return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+ if (projects.length === 0) return { oldest: null, newest: null }
+
+ let oldest = projects[0]
+ let newest = projects[0]
+
+ for (let i = 1; i < projects.length; i++) {
+ if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+ if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+ }
+
+ return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative: Math.min/Math.max for small arrays**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
+
+### 7.12 Use Set/Map for O(1) Lookups
+
+**Impact: LOW-MEDIUM (O(n) to O(1))**
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
+
+### 7.13 Use toSorted() Instead of sort() for Immutability
+
+**Impact: MEDIUM-HIGH (prevents mutation bugs in React state)**
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect: mutates original array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+ // Mutates the users prop array!
+ const sorted = useMemo(
+ () => users.sort((a, b) => a.name.localeCompare(b.name)),
+ [users]
+ )
+ return > }) {
+ const [frames, setFrames] = useState(null)
+
+ useEffect(() => {
+ if (enabled && !frames && typeof window !== 'undefined') {
+ import('./animation-frames.js')
+ .then(mod => setFrames(mod.frames))
+ .catch(() => setEnabled(false))
+ }
+ }, [enabled, frames, setEnabled])
+
+ if (!frames) return
+ {children}
+
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
diff --git a/skills/vercel-react-best-practices/rules/client-event-listeners.md b/skills/vercel-react-best-practices/rules/client-event-listeners.md
new file mode 100644
index 00000000..aad4ae91
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/client-event-listeners.md
@@ -0,0 +1,74 @@
+---
+title: Deduplicate Global Event Listeners
+impact: LOW
+impactDescription: single listener for N components
+tags: client, swr, event-listeners, subscription
+---
+
+## Deduplicate Global Event Listeners
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+ useEffect(() => {
+ const handler = (e: KeyboardEvent) => {
+ if (e.metaKey && e.key === key) {
+ callback()
+ }
+ }
+ window.addEventListener('keydown', handler)
+ return () => window.removeEventListener('keydown', handler)
+ }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+ // Register this callback in the Map
+ useEffect(() => {
+ if (!keyCallbacks.has(key)) {
+ keyCallbacks.set(key, new Set())
+ }
+ keyCallbacks.get(key)!.add(callback)
+
+ return () => {
+ const set = keyCallbacks.get(key)
+ if (set) {
+ set.delete(callback)
+ if (set.size === 0) {
+ keyCallbacks.delete(key)
+ }
+ }
+ }
+ }, [key, callback])
+
+ useSWRSubscription('global-keydown', () => {
+ const handler = (e: KeyboardEvent) => {
+ if (e.metaKey && keyCallbacks.has(e.key)) {
+ keyCallbacks.get(e.key)!.forEach(cb => cb())
+ }
+ }
+ window.addEventListener('keydown', handler)
+ return () => window.removeEventListener('keydown', handler)
+ })
+}
+
+function Profile() {
+ // Multiple shortcuts will share the same listener
+ useKeyboardShortcut('p', () => { /* ... */ })
+ useKeyboardShortcut('k', () => { /* ... */ })
+ // ...
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/client-localstorage-schema.md b/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
new file mode 100644
index 00000000..d30a1a7d
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
@@ -0,0 +1,71 @@
+---
+title: Version and Minimize localStorage Data
+impact: MEDIUM
+impactDescription: prevents schema conflicts, reduces storage size
+tags: client, localStorage, storage, versioning, data-minimization
+---
+
+## Version and Minimize localStorage Data
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+ try {
+ localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+ } catch {
+ // Throws in incognito/private browsing, quota exceeded, or disabled
+ }
+}
+
+function loadConfig() {
+ try {
+ const data = localStorage.getItem(`userConfig:${VERSION}`)
+ return data ? JSON.parse(data) : null
+ } catch {
+ return null
+ }
+}
+
+// Migration from v1 to v2
+function migrate() {
+ try {
+ const v1 = localStorage.getItem('userConfig:v1')
+ if (v1) {
+ const old = JSON.parse(v1)
+ saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+ localStorage.removeItem('userConfig:v1')
+ }
+ } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+ try {
+ localStorage.setItem('prefs:v1', JSON.stringify({
+ theme: user.preferences.theme,
+ notifications: user.preferences.notifications
+ }))
+ } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
diff --git a/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md b/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
new file mode 100644
index 00000000..ce39a889
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
@@ -0,0 +1,48 @@
+---
+title: Use Passive Event Listeners for Scrolling Performance
+impact: MEDIUM
+impactDescription: eliminates scroll delay caused by event listeners
+tags: client, event-listeners, scrolling, performance, touch, wheel
+---
+
+## Use Passive Event Listeners for Scrolling Performance
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+ const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+ const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+
+ document.addEventListener('touchstart', handleTouch)
+ document.addEventListener('wheel', handleWheel)
+
+ return () => {
+ document.removeEventListener('touchstart', handleTouch)
+ document.removeEventListener('wheel', handleWheel)
+ }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+ const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+ const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+
+ document.addEventListener('touchstart', handleTouch, { passive: true })
+ document.addEventListener('wheel', handleWheel, { passive: true })
+
+ return () => {
+ document.removeEventListener('touchstart', handleTouch)
+ document.removeEventListener('wheel', handleWheel)
+ }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
diff --git a/skills/vercel-react-best-practices/rules/client-swr-dedup.md b/skills/vercel-react-best-practices/rules/client-swr-dedup.md
new file mode 100644
index 00000000..2a430f27
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/client-swr-dedup.md
@@ -0,0 +1,56 @@
+---
+title: Use SWR for Automatic Deduplication
+impact: MEDIUM-HIGH
+impactDescription: automatic deduplication
+tags: client, swr, deduplication, data-fetching
+---
+
+## Use SWR for Automatic Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect (no deduplication, each instance fetches):**
+
+```tsx
+function UserList() {
+ const [users, setUsers] = useState([])
+ useEffect(() => {
+ fetch('/api/users')
+ .then(r => r.json())
+ .then(setUsers)
+ }, [])
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+ const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+ const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+ const { trigger } = useSWRMutation('/api/user', updateUser)
+ return
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)
diff --git a/skills/vercel-react-best-practices/rules/js-batch-dom-css.md b/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
new file mode 100644
index 00000000..a62d84ed
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
@@ -0,0 +1,107 @@
+---
+title: Avoid Layout Thrashing
+impact: MEDIUM
+impactDescription: prevents forced synchronous layouts and reduces performance bottlenecks
+tags: javascript, dom, css, performance, reflow, layout-thrashing
+---
+
+## Avoid Layout Thrashing
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**This is OK (browser batches style changes):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+ // Each line invalidates style, but browser batches the recalculation
+ element.style.width = '100px'
+ element.style.height = '200px'
+ element.style.backgroundColor = 'blue'
+ element.style.border = '1px solid black'
+}
+```
+
+**Incorrect (interleaved reads and writes force reflows):**
+```typescript
+function layoutThrashing(element: HTMLElement) {
+ element.style.width = '100px'
+ const width = element.offsetWidth // Forces reflow
+ element.style.height = '200px'
+ const height = element.offsetHeight // Forces another reflow
+}
+```
+
+**Correct (batch writes, then read once):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+ // Batch all writes together
+ element.style.width = '100px'
+ element.style.height = '200px'
+ element.style.backgroundColor = 'blue'
+ element.style.border = '1px solid black'
+
+ // Read after all writes are done (single reflow)
+ const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Correct (batch reads, then writes):**
+```typescript
+function avoidThrashing(element: HTMLElement) {
+ // Read phase - all layout queries first
+ const rect1 = element.getBoundingClientRect()
+ const offsetWidth = element.offsetWidth
+ const offsetHeight = element.offsetHeight
+
+ // Write phase - all style changes after
+ element.style.width = '100px'
+ element.style.height = '200px'
+}
+```
+
+**Better: use CSS classes**
+```css
+.highlighted-box {
+ width: 100px;
+ height: 200px;
+ background-color: blue;
+ border: 1px solid black;
+}
+```
+```typescript
+function updateElementStyles(element: HTMLElement) {
+ element.classList.add('highlighted-box')
+
+ const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**React example:**
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+ const ref = useRef(null)
+
+ useEffect(() => {
+ if (ref.current && isHighlighted) {
+ ref.current.style.width = '100px'
+ const width = ref.current.offsetWidth // Forces layout
+ ref.current.style.height = '200px'
+ }
+ }, [isHighlighted])
+
+ return ()
+
+function cachedSlugify(text: string): string {
+ if (slugifyCache.has(text)) {
+ return slugifyCache.get(text)!
+ }
+ const result = slugify(text)
+ slugifyCache.set(text, result)
+ return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+ return (
+ ()
+
+function getLocalStorage(key: string) {
+ if (!storageCache.has(key)) {
+ storageCache.set(key, localStorage.getItem(key))
+ }
+ return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+ localStorage.setItem(key, value)
+ storageCache.set(key, value) // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record | null = null
+
+function getCookie(name: string) {
+ if (!cookieCache) {
+ cookieCache = Object.fromEntries(
+ document.cookie.split('; ').map(c => c.split('='))
+ )
+ }
+ return cookieCache[name]
+}
+```
+
+**Important (invalidate on external changes):**
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+```typescript
+window.addEventListener('storage', (e) => {
+ if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+ if (document.visibilityState === 'visible') {
+ storageCache.clear()
+ }
+})
+```
diff --git a/skills/vercel-react-best-practices/rules/js-combine-iterations.md b/skills/vercel-react-best-practices/rules/js-combine-iterations.md
new file mode 100644
index 00000000..044d017e
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-combine-iterations.md
@@ -0,0 +1,32 @@
+---
+title: Combine Multiple Array Iterations
+impact: LOW-MEDIUM
+impactDescription: reduces iterations
+tags: javascript, arrays, loops, performance
+---
+
+## Combine Multiple Array Iterations
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect (3 iterations):**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct (1 iteration):**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+ if (user.isAdmin) admins.push(user)
+ if (user.isTester) testers.push(user)
+ if (!user.isActive) inactive.push(user)
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/js-early-exit.md b/skills/vercel-react-best-practices/rules/js-early-exit.md
new file mode 100644
index 00000000..f46cb89c
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-early-exit.md
@@ -0,0 +1,50 @@
+---
+title: Early Return from Functions
+impact: LOW-MEDIUM
+impactDescription: avoids unnecessary computation
+tags: javascript, functions, optimization, early-return
+---
+
+## Early Return from Functions
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect (processes all items even after finding answer):**
+
+```typescript
+function validateUsers(users: User[]) {
+ let hasError = false
+ let errorMessage = ''
+
+ for (const user of users) {
+ if (!user.email) {
+ hasError = true
+ errorMessage = 'Email required'
+ }
+ if (!user.name) {
+ hasError = true
+ errorMessage = 'Name required'
+ }
+ // Continues checking all users even after error found
+ }
+
+ return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct (returns immediately on first error):**
+
+```typescript
+function validateUsers(users: User[]) {
+ for (const user of users) {
+ if (!user.email) {
+ return { valid: false, error: 'Email required' }
+ }
+ if (!user.name) {
+ return { valid: false, error: 'Name required' }
+ }
+ }
+
+ return { valid: true }
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/js-flatmap-filter.md b/skills/vercel-react-best-practices/rules/js-flatmap-filter.md
new file mode 100644
index 00000000..ee0edf0d
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-flatmap-filter.md
@@ -0,0 +1,60 @@
+---
+title: Use flatMap to Map and Filter in One Pass
+impact: LOW-MEDIUM
+impactDescription: eliminates intermediate array
+tags: javascript, arrays, flatMap, filter, performance
+---
+
+## Use flatMap to Map and Filter in One Pass
+
+**Impact: LOW-MEDIUM (eliminates intermediate array)**
+
+Chaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.
+
+**Incorrect (2 iterations, intermediate array):**
+
+```typescript
+const userNames = users
+ .map(user => user.isActive ? user.name : null)
+ .filter(Boolean)
+```
+
+**Correct (1 iteration, no intermediate array):**
+
+```typescript
+const userNames = users.flatMap(user =>
+ user.isActive ? [user.name] : []
+)
+```
+
+**More examples:**
+
+```typescript
+// Extract valid emails from responses
+// Before
+const emails = responses
+ .map(r => r.success ? r.data.email : null)
+ .filter(Boolean)
+
+// After
+const emails = responses.flatMap(r =>
+ r.success ? [r.data.email] : []
+)
+
+// Parse and filter valid numbers
+// Before
+const numbers = strings
+ .map(s => parseInt(s, 10))
+ .filter(n => !isNaN(n))
+
+// After
+const numbers = strings.flatMap(s => {
+ const n = parseInt(s, 10)
+ return isNaN(n) ? [] : [n]
+})
+```
+
+**When to use:**
+- Transforming items while filtering some out
+- Conditional mapping where some inputs produce no output
+- Parsing/validating where invalid inputs should be skipped
diff --git a/skills/vercel-react-best-practices/rules/js-hoist-regexp.md b/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
new file mode 100644
index 00000000..dae3fefd
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
@@ -0,0 +1,45 @@
+---
+title: Hoist RegExp Creation
+impact: LOW-MEDIUM
+impactDescription: avoids recreation
+tags: javascript, regexp, optimization, memoization
+---
+
+## Hoist RegExp Creation
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect (new RegExp every render):**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+ const regex = new RegExp(`(${query})`, 'gi')
+ const parts = text.split(regex)
+ return <>{parts.map((part, i) => ...)}
+}
+```
+
+**Correct (memoize or hoist):**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+ const regex = useMemo(
+ () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+ [query]
+ )
+ const parts = text.split(regex)
+ return <>{parts.map((part, i) => ...)}
+}
+```
+
+**Warning (global regex has mutable state):**
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+```typescript
+const regex = /foo/g
+regex.test('foo') // true, lastIndex = 3
+regex.test('foo') // false, lastIndex = 0
+```
diff --git a/skills/vercel-react-best-practices/rules/js-index-maps.md b/skills/vercel-react-best-practices/rules/js-index-maps.md
new file mode 100644
index 00000000..9d357a00
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-index-maps.md
@@ -0,0 +1,37 @@
+---
+title: Build Index Maps for Repeated Lookups
+impact: LOW-MEDIUM
+impactDescription: 1M ops to 2K ops
+tags: javascript, map, indexing, optimization, performance
+---
+
+## Build Index Maps for Repeated Lookups
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+ return orders.map(order => ({
+ ...order,
+ user: users.find(u => u.id === order.userId)
+ }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+ const userById = new Map(users.map(u => [u.id, u]))
+
+ return orders.map(order => ({
+ ...order,
+ user: userById.get(order.userId)
+ }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+For 1000 orders × 1000 users: 1M ops → 2K ops.
diff --git a/skills/vercel-react-best-practices/rules/js-length-check-first.md b/skills/vercel-react-best-practices/rules/js-length-check-first.md
new file mode 100644
index 00000000..8b895736
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-length-check-first.md
@@ -0,0 +1,49 @@
+---
+title: Early Length Check for Array Comparisons
+impact: MEDIUM-HIGH
+impactDescription: avoids expensive operations when lengths differ
+tags: javascript, arrays, performance, optimization, comparison
+---
+
+## Early Length Check for Array Comparisons
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect (always runs expensive comparison):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+ // Always sorts and joins, even when lengths differ
+ return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+ // Early return if lengths differ
+ if (current.length !== original.length) {
+ return true
+ }
+ // Only sort when lengths match
+ const currentSorted = current.toSorted()
+ const originalSorted = original.toSorted()
+ for (let i = 0; i < currentSorted.length; i++) {
+ if (currentSorted[i] !== originalSorted[i]) {
+ return true
+ }
+ }
+ return false
+}
+```
+
+This new approach is more efficient because:
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+- It avoids mutating the original arrays
+- It returns early when a difference is found
diff --git a/skills/vercel-react-best-practices/rules/js-min-max-loop.md b/skills/vercel-react-best-practices/rules/js-min-max-loop.md
new file mode 100644
index 00000000..4b6656e9
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-min-max-loop.md
@@ -0,0 +1,82 @@
+---
+title: Use Loop for Min/Max Instead of Sort
+impact: LOW
+impactDescription: O(n) instead of O(n log n)
+tags: javascript, arrays, performance, sorting, algorithms
+---
+
+## Use Loop for Min/Max Instead of Sort
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+ id: string
+ name: string
+ updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+ const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+ return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+ const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+ return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+ if (projects.length === 0) return null
+
+ let latest = projects[0]
+
+ for (let i = 1; i < projects.length; i++) {
+ if (projects[i].updatedAt > latest.updatedAt) {
+ latest = projects[i]
+ }
+ }
+
+ return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+ if (projects.length === 0) return { oldest: null, newest: null }
+
+ let oldest = projects[0]
+ let newest = projects[0]
+
+ for (let i = 1; i < projects.length; i++) {
+ if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+ if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+ }
+
+ return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative (Math.min/Math.max for small arrays):**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
diff --git a/skills/vercel-react-best-practices/rules/js-set-map-lookups.md b/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
new file mode 100644
index 00000000..680a4892
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
@@ -0,0 +1,24 @@
+---
+title: Use Set/Map for O(1) Lookups
+impact: LOW-MEDIUM
+impactDescription: O(n) to O(1)
+tags: javascript, set, map, data-structures, performance
+---
+
+## Use Set/Map for O(1) Lookups
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
diff --git a/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md b/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
new file mode 100644
index 00000000..eae8b3f8
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
@@ -0,0 +1,57 @@
+---
+title: Use toSorted() Instead of sort() for Immutability
+impact: MEDIUM-HIGH
+impactDescription: prevents mutation bugs in React state
+tags: javascript, arrays, immutability, react, state, mutation
+---
+
+## Use toSorted() Instead of sort() for Immutability
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect (mutates original array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+ // Mutates the users prop array!
+ const sorted = useMemo(
+ () => users.sort((a, b) => a.name.localeCompare(b.name)),
+ [users]
+ )
+ return ` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+ return (
+
+
+ )
+}
+```
+
+Avoids expensive re-renders and state loss.
diff --git a/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md b/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
new file mode 100644
index 00000000..646744cb
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
@@ -0,0 +1,47 @@
+---
+title: Animate SVG Wrapper Instead of SVG Element
+impact: LOW
+impactDescription: enables hardware acceleration
+tags: rendering, svg, css, animation, performance
+---
+
+## Animate SVG Wrapper Instead of SVG Element
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `
+
+
+ )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
+
+### 6.2 CSS content-visibility for Long Lists
+
+**Impact: HIGH (faster initial render)**
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+ content-visibility: auto;
+ contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+ return (
+
+ {messages.map(msg => (
+
+ )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
+
+### 6.3 Hoist Static JSX Elements
+
+**Impact: LOW (avoids re-creation)**
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect: recreates element every render**
+
+```tsx
+function LoadingSkeleton() {
+ return
+}
+
+function Container() {
+ return (
+
+
+ ))}
+ {msg.content}
+
+ {loading &&
+ )
+}
+```
+
+**Correct: reuses same element**
+
+```tsx
+const loadingSkeleton = (
+
+)
+
+function Container() {
+ return (
+
+ {loading && loadingSkeleton}
+
+ )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
+
+### 6.4 Optimize SVG Precision
+
+**Impact: LOW (reduces file size)**
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect: excessive precision**
+
+```svg
+
+ {children}
+
+ )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect: visual flickering**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ const [theme, setTheme] = useState('light')
+
+ useEffect(() => {
+ // Runs after hydration - causes visible flash
+ const stored = localStorage.getItem('theme')
+ if (stored) {
+ setTheme(stored)
+ }
+ }, [])
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct: no flicker, no hydration mismatch**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ return (
+ <>
+
+ {children}
+
+
+
+ )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
+
+### 6.6 Suppress Expected Hydration Mismatches
+
+**Impact: LOW-MEDIUM (avoids noisy hydration warnings for known differences)**
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect: known mismatch warnings**
+
+```tsx
+function Timestamp() {
+ return {new Date().toLocaleString()}
+}
+```
+
+**Correct: suppress expected mismatch only**
+
+```tsx
+function Timestamp() {
+ return (
+
+ {new Date().toLocaleString()}
+
+ )
+}
+```
+
+### 6.7 Use Activity Component for Show/Hide
+
+**Impact: MEDIUM (preserves state/DOM)**
+
+Use React's `
+ {count && {count}}
+
+ )
+}
+
+// When count = 0, renders: 0
+// When count = 5, renders: 5
+```
+
+**Correct: renders nothing when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+ return (
+
+ {count > 0 ? {count} : null}
+
+ )
+}
+
+// When count = 0, renders:
+// When count = 5, renders: 5
+```
+
+### 6.10 Use React DOM Resource Hints
+
+**Impact: HIGH (reduces load time for critical resources)**
+
+React DOM provides APIs to hint the browser about resources it will need. These are especially useful in server components to start loading resources before the client even receives the HTML.
+
+- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to
+
+- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server
+
+- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon
+
+- **`preloadModule(href)`**: Fetch an ES module you'll use soon
+
+- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script
+
+- **`preinitModule(href)`**: Fetch and evaluate an ES module
+
+**Example: preconnect to third-party APIs**
+
+```tsx
+import { preconnect, prefetchDNS } from 'react-dom'
+
+export default function App() {
+ prefetchDNS('https://analytics.example.com')
+ preconnect('https://api.example.com')
+
+ return Content
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+ return (
+
+ Content
+
+ )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
+
+### 7.2 Build Index Maps for Repeated Lookups
+
+**Impact: LOW-MEDIUM (1M ops to 2K ops)**
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+ return orders.map(order => ({
+ ...order,
+ user: users.find(u => u.id === order.userId)
+ }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+ const userById = new Map(users.map(u => [u.id, u]))
+
+ return orders.map(order => ({
+ ...order,
+ user: userById.get(order.userId)
+ }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+
+For 1000 orders × 1000 users: 1M ops → 2K ops.
+
+### 7.3 Cache Property Access in Loops
+
+**Impact: LOW-MEDIUM (reduces lookups)**
+
+Cache object property lookups in hot paths.
+
+**Incorrect: 3 lookups × N iterations**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+ process(obj.config.settings.value)
+}
+```
+
+**Correct: 1 lookup total**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+ process(value)
+}
+```
+
+### 7.4 Cache Repeated Function Calls
+
+**Impact: MEDIUM (avoid redundant computation)**
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect: redundant computation**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+ return (
+
+ {projects.map(project => {
+ // slugify() called 100+ times for same project names
+ const slug = slugify(project.name)
+
+ return
+ )
+}
+```
+
+**Correct: cached results**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map
+ {projects.map(project => {
+ // Computed only once per unique project name
+ const slug = cachedSlugify(project.name)
+
+ return
+ )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+ if (isLoggedInCache !== null) {
+ return isLoggedInCache
+ }
+
+ isLoggedInCache = document.cookie.includes('auth=')
+ return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+ isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
+
+### 7.5 Cache Storage API Calls
+
+**Impact: LOW-MEDIUM (reduces expensive I/O)**
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect: reads storage on every call**
+
+```typescript
+function getTheme() {
+ return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct: Map cache**
+
+```typescript
+const storageCache = new Map{sorted.map(renderUser)}
+}
+```
+
+**Correct: creates new array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+ // Creates new sorted array, original unchanged
+ const sorted = useMemo(
+ () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+ [users]
+ )
+ return {sorted.map(renderUser)}
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support: fallback for older browsers**
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+
+- `.toReversed()` - immutable reverse
+
+- `.toSpliced()` - immutable splice
+
+- `.with()` - immutable element replacement
+
+---
+
+## 8. Advanced Patterns
+
+**Impact: LOW**
+
+Advanced patterns for specific cases that require careful implementation.
+
+### 8.1 Initialize App Once, Not Per Mount
+
+**Impact: LOW-MEDIUM (avoids duplicate init in development)**
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect: runs twice in dev, re-runs on remount**
+
+```tsx
+function Comp() {
+ useEffect(() => {
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+**Correct: once per app load**
+
+```tsx
+let didInit = false
+
+function Comp() {
+ useEffect(() => {
+ if (didInit) return
+ didInit = true
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+Reference: [https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+### 8.2 Store Event Handlers in Refs
+
+**Impact: LOW (stable subscriptions)**
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect: re-subscribes on every render**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+ useEffect(() => {
+ window.addEventListener(event, handler)
+ return () => window.removeEventListener(event, handler)
+ }, [event, handler])
+}
+```
+
+**Correct: stable subscription**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+ const onEvent = useEffectEvent(handler)
+
+ useEffect(() => {
+ window.addEventListener(event, onEvent)
+ return () => window.removeEventListener(event, onEvent)
+ }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+### 8.3 useEffectEvent for Stable Callback Refs
+
+**Impact: LOW (prevents effect re-runs)**
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect: effect re-runs on every callback change**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+ const [query, setQuery] = useState('')
+
+ useEffect(() => {
+ const timeout = setTimeout(() => onSearch(query), 300)
+ return () => clearTimeout(timeout)
+ }, [query, onSearch])
+}
+```
+
+**Correct: using React's useEffectEvent**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+ const [query, setQuery] = useState('')
+ const onSearchEvent = useEffectEvent(onSearch)
+
+ useEffect(() => {
+ const timeout = setTimeout(() => onSearchEvent(query), 300)
+ return () => clearTimeout(timeout)
+ }, [query])
+}
+```
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://nextjs.org](https://nextjs.org)
+3. [https://swr.vercel.app](https://swr.vercel.app)
+4. [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+5. [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+6. [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+7. [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/skills/vercel-react-best-practices/README.md b/skills/vercel-react-best-practices/README.md
new file mode 100644
index 00000000..f283e1c0
--- /dev/null
+++ b/skills/vercel-react-best-practices/README.md
@@ -0,0 +1,123 @@
+# React Best Practices
+
+A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+ - `_sections.md` - Section metadata (titles, impacts, descriptions)
+ - `_template.md` - Template for creating new rules
+ - `area-description.md` - Individual rule files
+- `src/` - Build scripts and utilities
+- `metadata.json` - Document metadata (version, organization, abstract)
+- __`AGENTS.md`__ - Compiled output (generated)
+- __`test-cases.json`__ - Test cases for LLM evaluation (generated)
+
+## Getting Started
+
+1. Install dependencies:
+ ```bash
+ pnpm install
+ ```
+
+2. Build AGENTS.md from rules:
+ ```bash
+ pnpm build
+ ```
+
+3. Validate rule files:
+ ```bash
+ pnpm validate
+ ```
+
+4. Extract test cases:
+ ```bash
+ pnpm extract-tests
+ ```
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+ - `async-` for Eliminating Waterfalls (Section 1)
+ - `bundle-` for Bundle Size Optimization (Section 2)
+ - `server-` for Server-Side Performance (Section 3)
+ - `client-` for Client-Side Data Fetching (Section 4)
+ - `rerender-` for Re-render Optimization (Section 5)
+ - `rendering-` for Rendering Performance (Section 6)
+ - `js-` for JavaScript Performance (Section 7)
+ - `advanced-` for Advanced Patterns (Section 8)
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+
+## Rule File Structure
+
+Each rule file should follow this structure:
+
+```markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example
+```
+
+Optional explanatory text after examples.
+
+Reference: [Link](https://example.com)
+
+## File Naming Convention
+
+- Files starting with `_` are special (excluded from build)
+- Rule files: `area-description.md` (e.g., `async-parallel.md`)
+- Section is automatically inferred from filename prefix
+- Rules are sorted alphabetically by title within each section
+- IDs (e.g., 1.1, 1.2) are auto-generated during build
+
+## Impact Levels
+
+- `CRITICAL` - Highest priority, major performance gains
+- `HIGH` - Significant performance improvements
+- `MEDIUM-HIGH` - Moderate-high gains
+- `MEDIUM` - Moderate performance improvements
+- `LOW-MEDIUM` - Low-medium gains
+- `LOW` - Incremental improvements
+
+## Scripts
+
+- `pnpm build` - Compile rules into AGENTS.md
+- `pnpm validate` - Validate all rule files
+- `pnpm extract-tests` - Extract test cases for LLM evaluation
+- `pnpm dev` - Build and validate
+
+## Contributing
+
+When adding or modifying rules:
+
+1. Use the correct filename prefix for your section
+2. Follow the `_template.md` structure
+3. Include clear bad/good examples with explanations
+4. Add appropriate tags
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+6. Rules are automatically sorted by title - no need to manage numbers!
+
+## Acknowledgments
+
+Originally created by [@shuding](https://x.com/shuding) at [Vercel](https://vercel.com).
diff --git a/skills/vercel-react-best-practices/SKILL.md b/skills/vercel-react-best-practices/SKILL.md
new file mode 100644
index 00000000..4417c6ae
--- /dev/null
+++ b/skills/vercel-react-best-practices/SKILL.md
@@ -0,0 +1,141 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+ author: vercel
+ version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 62 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-auth-actions` - Authenticate server actions like API routes
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-dedup-props` - Avoid duplicate serialization in RSC props
+- `server-hoist-static-io` - Hoist static I/O (fonts, logos) to module level
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+- `rerender-no-inline-components` - Don't define components inside components
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-hydration-suppress-warning` - Suppress expected mismatches
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Prefer useTransition for loading state
+- `rendering-resource-hints` - Use React DOM resource hints for preloading
+- `rendering-script-defer-async` - Use defer or async on script tags
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+- `js-flatmap-filter` - Use flatMap to map and filter in one pass
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/skills/vercel-react-best-practices/rules/_sections.md b/skills/vercel-react-best-practices/rules/_sections.md
new file mode 100644
index 00000000..4d20c144
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/_sections.md
@@ -0,0 +1,46 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Eliminating Waterfalls (async)
+
+**Impact:** CRITICAL
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+## 2. Bundle Size Optimization (bundle)
+
+**Impact:** CRITICAL
+**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+## 3. Server-Side Performance (server)
+
+**Impact:** HIGH
+**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+## 4. Client-Side Data Fetching (client)
+
+**Impact:** MEDIUM-HIGH
+**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+## 5. Re-render Optimization (rerender)
+
+**Impact:** MEDIUM
+**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+## 6. Rendering Performance (rendering)
+
+**Impact:** MEDIUM
+**Description:** Optimizing the rendering process reduces the work the browser needs to do.
+
+## 7. JavaScript Performance (js)
+
+**Impact:** LOW-MEDIUM
+**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.
+
+## 8. Advanced Patterns (advanced)
+
+**Impact:** LOW
+**Description:** Advanced patterns for specific cases that require careful implementation.
diff --git a/skills/vercel-react-best-practices/rules/_template.md b/skills/vercel-react-best-practices/rules/_template.md
new file mode 100644
index 00000000..1e9e7070
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/_template.md
@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
diff --git a/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md b/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
new file mode 100644
index 00000000..97e7ade2
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+ useEffect(() => {
+ window.addEventListener(event, handler)
+ return () => window.removeEventListener(event, handler)
+ }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+ const handlerRef = useRef(handler)
+ useEffect(() => {
+ handlerRef.current = handler
+ }, [handler])
+
+ useEffect(() => {
+ const listener = (e) => handlerRef.current(e)
+ window.addEventListener(event, listener)
+ return () => window.removeEventListener(event, listener)
+ }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+ const onEvent = useEffectEvent(handler)
+
+ useEffect(() => {
+ window.addEventListener(event, onEvent)
+ return () => window.removeEventListener(event, onEvent)
+ }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
diff --git a/skills/vercel-react-best-practices/rules/advanced-init-once.md b/skills/vercel-react-best-practices/rules/advanced-init-once.md
new file mode 100644
index 00000000..73ee38e5
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/advanced-init-once.md
@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+ useEffect(() => {
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+ useEffect(() => {
+ if (didInit) return
+ didInit = true
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
diff --git a/skills/vercel-react-best-practices/rules/advanced-use-latest.md b/skills/vercel-react-best-practices/rules/advanced-use-latest.md
new file mode 100644
index 00000000..9c7cb501
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/advanced-use-latest.md
@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+ const [query, setQuery] = useState('')
+
+ useEffect(() => {
+ const timeout = setTimeout(() => onSearch(query), 300)
+ return () => clearTimeout(timeout)
+ }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+ const [query, setQuery] = useState('')
+ const onSearchEvent = useEffectEvent(onSearch)
+
+ useEffect(() => {
+ const timeout = setTimeout(() => onSearchEvent(query), 300)
+ return () => clearTimeout(timeout)
+ }, [query])
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/async-api-routes.md b/skills/vercel-react-best-practices/rules/async-api-routes.md
new file mode 100644
index 00000000..6feda1ef
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/async-api-routes.md
@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+ const session = await auth()
+ const config = await fetchConfig()
+ const data = await fetchData(session.user.id)
+ return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+ const sessionPromise = auth()
+ const configPromise = fetchConfig()
+ const session = await sessionPromise
+ const [config, data] = await Promise.all([
+ configPromise,
+ fetchData(session.user.id)
+ ])
+ return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
diff --git a/skills/vercel-react-best-practices/rules/async-defer-await.md b/skills/vercel-react-best-practices/rules/async-defer-await.md
new file mode 100644
index 00000000..ea7082a3
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/async-defer-await.md
@@ -0,0 +1,80 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+ const userData = await fetchUserData(userId)
+
+ if (skipProcessing) {
+ // Returns immediately but still waited for userData
+ return { skipped: true }
+ }
+
+ // Only this branch uses userData
+ return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+ if (skipProcessing) {
+ // Returns immediately without waiting
+ return { skipped: true }
+ }
+
+ // Fetch only when needed
+ const userData = await fetchUserData(userId)
+ return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+ const permissions = await fetchPermissions(userId)
+ const resource = await getResource(resourceId)
+
+ if (!resource) {
+ return { error: 'Not found' }
+ }
+
+ if (!permissions.canEdit) {
+ return { error: 'Forbidden' }
+ }
+
+ return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+ const resource = await getResource(resourceId)
+
+ if (!resource) {
+ return { error: 'Not found' }
+ }
+
+ const permissions = await fetchPermissions(userId)
+
+ if (!permissions.canEdit) {
+ return { error: 'Forbidden' }
+ }
+
+ return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
diff --git a/skills/vercel-react-best-practices/rules/async-dependencies.md b/skills/vercel-react-best-practices/rules/async-dependencies.md
new file mode 100644
index 00000000..0484ebab
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/async-dependencies.md
@@ -0,0 +1,51 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+ fetchUser(),
+ fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+ async user() { return fetchUser() },
+ async config() { return fetchConfig() },
+ async profile() {
+ return fetchProfile((await this.$.user).id)
+ }
+})
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+ userPromise,
+ fetchConfig(),
+ profilePromise
+])
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
diff --git a/skills/vercel-react-best-practices/rules/async-parallel.md b/skills/vercel-react-best-practices/rules/async-parallel.md
new file mode 100644
index 00000000..64133f6c
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/async-parallel.md
@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+ fetchUser(),
+ fetchPosts(),
+ fetchComments()
+])
+```
diff --git a/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md b/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
new file mode 100644
index 00000000..1fbc05b0
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
@@ -0,0 +1,99 @@
+---
+title: Strategic Suspense Boundaries
+impact: HIGH
+impactDescription: faster initial paint
+tags: async, suspense, streaming, layout-shift
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+ const data = await fetchData() // Blocks entire page
+
+ return (
+
+
+ )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct (wrapper shows immediately, data streams in):**
+
+```tsx
+function Page() {
+ return (
+ Sidebar
+ Header
+
+
+ Footer
+
+
+ )
+}
+
+async function DataDisplay() {
+ const data = await fetchData() // Only blocks this component
+ return Sidebar
+ Header
+
+
+ Footer
+ {data.content}
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative (share promise across components):**
+
+```tsx
+function Page() {
+ // Start fetch immediately, but don't await
+ const dataPromise = fetchData()
+
+ return (
+
+
+ )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise }) {
+ const data = use(dataPromise) // Unwraps the promise
+ return Sidebar
+ Header
+ Footer
+ {data.content}
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise }) {
+ const data = use(dataPromise) // Reuses the same promise
+ return {data.summary}
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
diff --git a/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md b/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
new file mode 100644
index 00000000..ee48f327
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
@@ -0,0 +1,59 @@
+---
+title: Avoid Barrel File Imports
+impact: CRITICAL
+impactDescription: 200-800ms import cost, slow builds
+tags: bundle, imports, tree-shaking, barrel-files, performance
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct (imports only what you need):**
+
+```tsx
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+// Loads only 3 modules (~2KB vs ~1MB)
+
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+**Alternative (Next.js 13.5+):**
+
+```js
+// next.config.js - use optimizePackageImports
+module.exports = {
+ experimental: {
+ optimizePackageImports: ['lucide-react', '@mui/material']
+ }
+}
+
+// Then you can keep the ergonomic barrel imports:
+import { Check, X, Menu } from 'lucide-react'
+// Automatically transformed to direct imports at build time
+```
+
+Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
diff --git a/skills/vercel-react-best-practices/rules/bundle-conditional.md b/skills/vercel-react-best-practices/rules/bundle-conditional.md
new file mode 100644
index 00000000..99d6fc90
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/bundle-conditional.md
@@ -0,0 +1,31 @@
+---
+title: Conditional Module Loading
+impact: HIGH
+impactDescription: loads large data only when needed
+tags: bundle, conditional-loading, lazy-loading
+---
+
+## Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+**Example (lazy-load animation frames):**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.DispatchContent
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+ return (
+
+ Content
+
+ )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
diff --git a/skills/vercel-react-best-practices/rules/js-cache-function-results.md b/skills/vercel-react-best-practices/rules/js-cache-function-results.md
new file mode 100644
index 00000000..180f8ac8
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-cache-function-results.md
@@ -0,0 +1,80 @@
+---
+title: Cache Repeated Function Calls
+impact: MEDIUM
+impactDescription: avoid redundant computation
+tags: javascript, cache, memoization, performance
+---
+
+## Cache Repeated Function Calls
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect (redundant computation):**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+ return (
+
+ {projects.map(project => {
+ // slugify() called 100+ times for same project names
+ const slug = slugify(project.name)
+
+ return
+ )
+}
+```
+
+**Correct (cached results):**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map
+ {projects.map(project => {
+ // Computed only once per unique project name
+ const slug = cachedSlugify(project.name)
+
+ return
+ )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+ if (isLoggedInCache !== null) {
+ return isLoggedInCache
+ }
+
+ isLoggedInCache = document.cookie.includes('auth=')
+ return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+ isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/skills/vercel-react-best-practices/rules/js-cache-property-access.md b/skills/vercel-react-best-practices/rules/js-cache-property-access.md
new file mode 100644
index 00000000..39eec906
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-cache-property-access.md
@@ -0,0 +1,28 @@
+---
+title: Cache Property Access in Loops
+impact: LOW-MEDIUM
+impactDescription: reduces lookups
+tags: javascript, loops, optimization, caching
+---
+
+## Cache Property Access in Loops
+
+Cache object property lookups in hot paths.
+
+**Incorrect (3 lookups × N iterations):**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+ process(obj.config.settings.value)
+}
+```
+
+**Correct (1 lookup total):**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+ process(value)
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/js-cache-storage.md b/skills/vercel-react-best-practices/rules/js-cache-storage.md
new file mode 100644
index 00000000..aa4a30c0
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-cache-storage.md
@@ -0,0 +1,70 @@
+---
+title: Cache Storage API Calls
+impact: LOW-MEDIUM
+impactDescription: reduces expensive I/O
+tags: javascript, localStorage, storage, caching, performance
+---
+
+## Cache Storage API Calls
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect (reads storage on every call):**
+
+```typescript
+function getTheme() {
+ return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct (Map cache):**
+
+```typescript
+const storageCache = new Map{sorted.map(renderUser)}
+}
+```
+
+**Correct (creates new array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+ // Creates new sorted array, original unchanged
+ const sorted = useMemo(
+ () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+ [users]
+ )
+ return {sorted.map(renderUser)}
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support (fallback for older browsers):**
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+- `.toReversed()` - immutable reverse
+- `.toSpliced()` - immutable splice
+- `.with()` - immutable element replacement
diff --git a/skills/vercel-react-best-practices/rules/rendering-activity.md b/skills/vercel-react-best-practices/rules/rendering-activity.md
new file mode 100644
index 00000000..c957a490
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-activity.md
@@ -0,0 +1,26 @@
+---
+title: Use Activity Component for Show/Hide
+impact: MEDIUM
+impactDescription: preserves state/DOM
+tags: rendering, activity, visibility, state-preservation
+---
+
+## Use Activity Component for Show/Hide
+
+Use React's `` and animate the wrapper instead.
+
+**Incorrect (animating SVG directly - no hardware acceleration):**
+
+```tsx
+function LoadingSpinner() {
+ return (
+
+ )
+}
+```
+
+**Correct (animating wrapper div - hardware accelerated):**
+
+```tsx
+function LoadingSpinner() {
+ return (
+ {/* content */}
+}
+```
+
+**Example (preload critical fonts and styles):**
+
+```tsx
+import { preload, preinit } from 'react-dom'
+
+export default function RootLayout({ children }) {
+ // Preload font file
+ preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })
+
+ // Fetch and apply critical stylesheet immediately
+ preinit('/styles/critical.css', { as: 'style' })
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+**Example (preload modules for code-split routes):**
+
+```tsx
+import { preloadModule, preinitModule } from 'react-dom'
+
+function Navigation() {
+ const preloadDashboard = () => {
+ preloadModule('/dashboard.js', { as: 'script' })
+ }
+
+ return (
+
+ )
+}
+```
+
+**When to use each:**
+
+| API | Use case |
+|-----|----------|
+| `prefetchDNS` | Third-party domains you'll connect to later |
+| `preconnect` | APIs or CDNs you'll fetch from immediately |
+| `preload` | Critical resources needed for current page |
+| `preloadModule` | JS modules for likely next navigation |
+| `preinit` | Stylesheets/scripts that must execute early |
+| `preinitModule` | ES modules that must execute early |
+
+Reference: [React DOM Resource Preloading APIs](https://react.dev/reference/react-dom#resource-preloading-apis)
diff --git a/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md b/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
new file mode 100644
index 00000000..ee275ed1
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
@@ -0,0 +1,68 @@
+---
+title: Use defer or async on Script Tags
+impact: HIGH
+impactDescription: eliminates render-blocking
+tags: rendering, script, defer, async, performance
+---
+
+## Use defer or async on Script Tags
+
+**Impact: HIGH (eliminates render-blocking)**
+
+Script tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.
+
+- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order
+- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order
+
+Use `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.
+
+**Incorrect (blocks rendering):**
+
+```tsx
+export default function Document() {
+ return (
+
+
+
+
+
+ {/* content */}
+
+ )
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+export default function Document() {
+ return (
+
+
+ {/* Independent script - use async */}
+
+ {/* DOM-dependent script - use defer */}
+
+
+ {/* content */}
+
+ )
+}
+```
+
+**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:
+
+```tsx
+import Script from 'next/script'
+
+export default function Page() {
+ return (
+ <>
+
+
+
+ )
+}
+```
+
+Reference: [MDN - Script element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)
diff --git a/skills/vercel-react-best-practices/rules/rendering-svg-precision.md b/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
new file mode 100644
index 00000000..6d771286
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
@@ -0,0 +1,28 @@
+---
+title: Optimize SVG Precision
+impact: LOW
+impactDescription: reduces file size
+tags: rendering, svg, optimization, svgo
+---
+
+## Optimize SVG Precision
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect (excessive precision):**
+
+```svg
+
+ )
+
+ // Defined inside to access `user` - BAD
+ const Stats = () => (
+ 
+ )
+}
+
+function Stats({ followers, posts }: { followers: number; posts: number }) {
+ return (
+ (null)
+
+ useEffect(() => {
+ const onMove = (e: MouseEvent) => {
+ lastXRef.current = e.clientX
+ const node = dotRef.current
+ if (node) {
+ node.style.transform = `translateX(${e.clientX}px)`
+ }
+ }
+ window.addEventListener('mousemove', onMove)
+ return () => window.removeEventListener('mousemove', onMove)
+ }, [])
+
+ return (
+
+ )
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/server-after-nonblocking.md b/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
new file mode 100644
index 00000000..e8f5b260
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+ // Perform mutation
+ await updateDatabase(request)
+
+ // Logging blocks the response
+ const userAgent = request.headers.get('user-agent') || 'unknown'
+ await logUserAction({ userAgent })
+
+ return new Response(JSON.stringify({ status: 'success' }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' }
+ })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+ // Perform mutation
+ await updateDatabase(request)
+
+ // Log after response is sent
+ after(async () => {
+ const userAgent = (await headers()).get('user-agent') || 'unknown'
+ const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+
+ logUserAction({ sessionCookie, userAgent })
+ })
+
+ return new Response(JSON.stringify({ status: 'success' }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' }
+ })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
diff --git a/skills/vercel-react-best-practices/rules/server-auth-actions.md b/skills/vercel-react-best-practices/rules/server-auth-actions.md
new file mode 100644
index 00000000..ee82c044
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-auth-actions.md
@@ -0,0 +1,96 @@
+---
+title: Authenticate Server Actions Like API Routes
+impact: CRITICAL
+impactDescription: prevents unauthorized access to server mutations
+tags: server, server-actions, authentication, security, authorization
+---
+
+## Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect (no authentication check):**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+ // Anyone can call this! No auth check
+ await db.user.delete({ where: { id: userId } })
+ return { success: true }
+}
+```
+
+**Correct (authentication inside the action):**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+ // Always check auth inside the action
+ const session = await verifySession()
+
+ if (!session) {
+ throw unauthorized('Must be logged in')
+ }
+
+ // Check authorization too
+ if (session.user.role !== 'admin' && session.user.id !== userId) {
+ throw unauthorized('Cannot delete other users')
+ }
+
+ await db.user.delete({ where: { id: userId } })
+ return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+ userId: z.string().uuid(),
+ name: z.string().min(1).max(100),
+ email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+ // Validate input first
+ const validated = updateProfileSchema.parse(data)
+
+ // Then authenticate
+ const session = await verifySession()
+ if (!session) {
+ throw new Error('Unauthorized')
+ }
+
+ // Then authorize
+ if (session.user.id !== validated.userId) {
+ throw new Error('Can only update own profile')
+ }
+
+ // Finally perform the mutation
+ await db.user.update({
+ where: { id: validated.userId },
+ data: {
+ name: validated.name,
+ email: validated.email
+ }
+ })
+
+ return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
diff --git a/skills/vercel-react-best-practices/rules/server-cache-lru.md b/skills/vercel-react-best-practices/rules/server-cache-lru.md
new file mode 100644
index 00000000..ef6938aa
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-cache-lru.md
@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache({
+ max: 1000,
+ ttl: 5 * 60 * 1000 // 5 minutes
+})
+
+export async function getUser(id: string) {
+ const cached = cache.get(id)
+ if (cached) return cached
+
+ const user = await db.user.findUnique({ where: { id } })
+ cache.set(id, user)
+ return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
diff --git a/skills/vercel-react-best-practices/rules/server-cache-react.md b/skills/vercel-react-best-practices/rules/server-cache-react.md
new file mode 100644
index 00000000..87c9ca33
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-cache-react.md
@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+ const session = await auth()
+ if (!session?.user?.id) return null
+ return await db.user.findUnique({
+ where: { id: session.user.id }
+ })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+ return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 }) // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+ return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1) // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params) // Query runs
+getUser(params) // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)
diff --git a/skills/vercel-react-best-practices/rules/server-dedup-props.md b/skills/vercel-react-best-practices/rules/server-dedup-props.md
new file mode 100644
index 00000000..fb24a256
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-dedup-props.md
@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+ u.active)} />
+
+
+ )
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/server-serialization.md b/skills/vercel-react-best-practices/rules/server-serialization.md
new file mode 100644
index 00000000..39c5c416
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-serialization.md
@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+ const user = await fetchUser() // 50 fields
+ return ` component, causing a hard crash in production.
+
+**Incorrect: crashes if count is 0 or name is ""**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+ return (
+
+ {name && {name} }
+ {count && {count} items }
+
+ )
+}
+// If name="" or count=0, renders the falsy value → crash
+```
+
+**Correct: ternary with null**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+ return (
+
+ {name ? {name} : null}
+ {count ? {count} items : null}
+
+ )
+}
+```
+
+**Correct: explicit boolean coercion**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+ return (
+
+ {!!name && {name} }
+ {!!count && {count} items }
+
+ )
+}
+```
+
+**Best: early return**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+ if (!name) return null
+
+ return (
+
+ {name}
+ {count > 0 ? {count} items : null}
+
+ )
+}
+```
+
+Early returns are clearest. When using conditionals inline, prefer ternary or
+
+explicit boolean checks.
+
+**Lint rule:** Enable `react/jsx-no-leaked-render` from
+
+[eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-leaked-render.md)
+
+to catch this automatically.
+
+### 1.2 Wrap Strings in Text Components
+
+**Impact: CRITICAL (prevents runtime crash)**
+
+Strings must be rendered inside ``. React Native crashes if a string is a
+
+direct child of ``.
+
+**Incorrect: crashes**
+
+```tsx
+import { View } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+ return Hello, {name}!
+}
+// Error: Text strings must be rendered within a component.
+```
+
+**Correct:**
+
+```tsx
+import { View, Text } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+ return (
+
+ Hello, {name}!
+
+ )
+}
+```
+
+---
+
+## 2. List Performance
+
+**Impact: HIGH**
+
+Optimizing virtualized lists (FlatList, LegendList, FlashList)
+for smooth scrolling and fast updates.
+
+### 2.1 Avoid Inline Objects in renderItem
+
+**Impact: HIGH (prevents unnecessary re-renders of memoized list items)**
+
+Don't create new objects inside `renderItem` to pass as props. Inline objects
+
+create new references on every render, breaking memoization. Pass primitive
+
+values directly from `item` instead.
+
+**Incorrect: inline object breaks memoization**
+
+```tsx
+function UserList({ users }: { users: User[] }) {
+ return (
+ (
+ (
+ // Good: pass the item directly
+ {/* ... */}
+})
+```
+
+**Correct: hoist static styles in module scope**
+
+```tsx
+const activeStyle = { backgroundColor: 'green' }
+const inactiveStyle = { backgroundColor: 'gray' }
+
+renderItem={({ item }) => (
+ {
+ // bad: creates a new callback on each render
+ const onPress = () => handlePress(item.id)
+ return (
+ {/* ... */}
+}
+```
+
+**Correct: lightweight list item**
+
+```tsx
+function ProductRow({ name, price, imageUrl }: Props) {
+ // Good: receives only primitives, minimal hooks
+ return (
+
+ {name}
+ {price}
+
+ )
+}
+```
+
+**Move data fetching to parent:**
+
+```tsx
+// Parent fetches all data once
+function ProductList() {
+ const { data: products } = useQuery(['products'], fetchProducts)
+
+ return (
+ (
+ {domain}
+}
+```
+
+**Updating parent array reference:**
+
+```tsx
+// good: creates a new array instance without mutating the inner objects
+// good: parent array reference is unaffected by typing and updating "keyword"
+const sortedTlds = tlds.toSorted((a, b) => a.name.localeCompare(b.name))
+
+return {user.name}
+})
+
+renderItem={({ item }) => {name}
+})
+
+renderItem={({ item }) => (
+ handlePress(item.id)} />
+
+// Correct: pass ID, handle in child
+{name}
+ {items.map((item) => (
+
+ )
+}
+// 50 items = 50 components mounted, even if only 10 visible
+```
+
+**Correct: virtualizer renders only visible items**
+
+```tsx
+import { LegendList } from '@legendapp/list'
+
+function Feed({ items }: { items: Item[] }) {
+ return (
+
+ {/* 4000x3000 image loaded for a 100x100 thumbnail */}
+ {product.name}
+
+ )
+}
+```
+
+**Correct: request appropriately-sized image**
+
+```tsx
+function ProductItem({ product }: { product: Product }) {
+ // Request a 200x200 image (2x for retina)
+ const thumbnailUrl = `${product.imageUrl}?w=200&h=200&fit=cover`
+
+ return (
+
+ {product.name}
+
+ )
+}
+```
+
+Use an optimized image component with built-in caching and placeholder support,
+
+such as `expo-image` or `SolitoImage` (which uses `expo-image` under the hood).
+
+Request images at 2x the display size for retina screens.
+
+### 2.8 Use Item Types for Heterogeneous Lists
+
+**Impact: HIGH (efficient recycling, less layout thrashing)**
+
+When a list has different item layouts (messages, images, headers, etc.), use a
+
+`type` field on each item and provide `getItemType` to the list. This puts items
+
+into separate recycling pools so a message component never gets recycled into an
+
+image component.
+
+[LegendList getItemType](https://legendapp.com/open-source/list/api/props/#getitemtype-v2)
+
+**Incorrect: single component with conditionals**
+
+```tsx
+type Item = { id: string; text?: string; imageUrl?: string; isHeader?: boolean }
+
+function ListItem({ item }: { item: Item }) {
+ if (item.isHeader) {
+ return item.id}
+ getItemType={(item) => item.type}
+ renderItem={({ item }) => {
+ switch (item.type) {
+ case 'header':
+ return item.id}
+ getItemType={(item) => item.type}
+ getEstimatedItemSize={(index, item, itemType) => {
+ switch (itemType) {
+ case 'header':
+ return 48
+ case 'message':
+ return 72
+ case 'image':
+ return 300
+ default:
+ return 72
+ }
+ }}
+ renderItem={({ item }) => {
+ /* ... */
+ }}
+ recycleItems
+/>
+```
+
+- **Recycling efficiency**: Items with the same type share a recycling pool
+
+- **No layout thrashing**: A header never recycles into an image cell
+
+- **Type safety**: TypeScript can narrow the item type in each branch
+
+- **Better size estimation**: Use `getEstimatedItemSize` with `itemType` for
+
+ accurate estimates per type
+
+---
+
+## 3. Animation
+
+**Impact: HIGH**
+
+GPU-accelerated animations, Reanimated patterns, and avoiding
+render thrashing during gestures.
+
+### 3.1 Animate Transform and Opacity Instead of Layout Properties
+
+**Impact: HIGH (GPU-accelerated animations, no layout recalculation)**
+
+Avoid animating `width`, `height`, `top`, `left`, `margin`, or `padding`. These trigger layout recalculation on every frame. Instead, use `transform` (scale, translate) and `opacity` which run on the GPU without triggering layout.
+
+**Incorrect: animates height, triggers layout every frame**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+ const animatedStyle = useAnimatedStyle(() => ({
+ height: withTiming(expanded ? 200 : 0), // triggers layout on every frame
+ overflow: 'hidden',
+ }))
+
+ return {children}
+}
+```
+
+**Correct: animates scaleY, GPU-accelerated**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+ const animatedStyle = useAnimatedStyle(() => ({
+ transform: [
+ { scaleY: withTiming(expanded ? 1 : 0) },
+ ],
+ opacity: withTiming(expanded ? 1 : 0),
+ }))
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+**Correct: animates translateY for slide animations**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function SlideIn({ visible }: { visible: boolean }) {
+ const animatedStyle = useAnimatedStyle(() => ({
+ transform: [
+ { translateY: withTiming(visible ? 0 : 100) },
+ ],
+ opacity: withTiming(visible ? 1 : 0),
+ }))
+
+ return {children}
+}
+```
+
+GPU-accelerated properties: `transform` (translate, scale, rotate), `opacity`. Everything else triggers layout.
+
+### 3.2 Prefer useDerivedValue Over useAnimatedReaction
+
+**Impact: MEDIUM (cleaner code, automatic dependency tracking)**
+
+When deriving a shared value from another, use `useDerivedValue` instead of
+
+`useAnimatedReaction`. Derived values are declarative, automatically track
+
+dependencies, and return a value you can use directly. Animated reactions are
+
+for side effects, not derivations.
+
+[Reanimated useDerivedValue](https://docs.swmansion.com/react-native-reanimated/docs/core/useDerivedValue)
+
+**Incorrect: useAnimatedReaction for derivation**
+
+```tsx
+import { useSharedValue, useAnimatedReaction } from 'react-native-reanimated'
+
+function MyComponent() {
+ const progress = useSharedValue(0)
+ const opacity = useSharedValue(1)
+
+ useAnimatedReaction(
+ () => progress.value,
+ (current) => {
+ opacity.value = 1 - current
+ }
+ )
+
+ // ...
+}
+```
+
+**Correct: useDerivedValue**
+
+```tsx
+import { useSharedValue, useDerivedValue } from 'react-native-reanimated'
+
+function MyComponent() {
+ const progress = useSharedValue(0)
+
+ const opacity = useDerivedValue(() => 1 - progress.get())
+
+ // ...
+}
+```
+
+Use `useAnimatedReaction` only for side effects that don't produce a value
+
+(e.g., triggering haptics, logging, calling `runOnJS`).
+
+### 3.3 Use GestureDetector for Animated Press States
+
+**Impact: MEDIUM (UI thread animations, smoother press feedback)**
+
+For animated press states (scale, opacity on press), use `GestureDetector` with
+
+`Gesture.Tap()` and shared values instead of Pressable's
+
+`onPressIn`/`onPressOut`. Gesture callbacks run on the UI thread as worklets—no
+
+JS thread round-trip for press animations.
+
+[Gesture Handler Tap Gesture](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture)
+
+**Incorrect: Pressable with JS thread callbacks**
+
+```tsx
+import { Pressable } from 'react-native'
+import Animated, {
+ useSharedValue,
+ useAnimatedStyle,
+ withTiming,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+ const scale = useSharedValue(1)
+
+ const animatedStyle = useAnimatedStyle(() => ({
+ transform: [{ scale: scale.value }],
+ }))
+
+ return (
+ (scale.value = withTiming(0.95))}
+ onPressOut={() => (scale.value = withTiming(1))}
+ >
+
+ Press me
+
+
+ )
+}
+```
+
+**Correct: GestureDetector with UI thread worklets**
+
+```tsx
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import Animated, {
+ useSharedValue,
+ useAnimatedStyle,
+ withTiming,
+ interpolate,
+ runOnJS,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+ // Store the press STATE (0 = not pressed, 1 = pressed)
+ const pressed = useSharedValue(0)
+
+ const tap = Gesture.Tap()
+ .onBegin(() => {
+ pressed.set(withTiming(1))
+ })
+ .onFinalize(() => {
+ pressed.set(withTiming(0))
+ })
+ .onEnd(() => {
+ runOnJS(onPress)()
+ })
+
+ // Derive visual values from the state
+ const animatedStyle = useAnimatedStyle(() => ({
+ transform: [
+ { scale: interpolate(withTiming(pressed.get()), [0, 1], [1, 0.95]) },
+ ],
+ }))
+
+ return (
+
+
+ Press me
+
+
+ )
+}
+```
+
+Store the press **state** (0 or 1), then derive the scale via `interpolate`.
+
+This keeps the shared value as ground truth. Use `runOnJS` to call JS functions
+
+from worklets. Use `.set()` and `.get()` for React Compiler compatibility.
+
+---
+
+## 4. Scroll Performance
+
+**Impact: HIGH**
+
+Tracking scroll position without causing render thrashing.
+
+### 4.1 Never Track Scroll Position in useState
+
+**Impact: HIGH (prevents render thrashing during scroll)**
+
+Never store scroll position in `useState`. Scroll events fire rapidly—state
+
+updates cause render thrashing and dropped frames. Use a Reanimated shared value
+
+for animations or a ref for non-reactive tracking.
+
+**Incorrect: useState causes jank**
+
+```tsx
+import { useState } from 'react'
+import {
+ ScrollView,
+ NativeSyntheticEvent,
+ NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+ const [scrollY, setScrollY] = useState(0)
+
+ const onScroll = (e: NativeSyntheticEvent) => {
+ setScrollY(e.nativeEvent.contentOffset.y) // re-renders on every frame
+ }
+
+ return ) => {
+ scrollY.current = e.nativeEvent.contentOffset.y // no re-render
+ }
+
+ return
+
+ )
+}
+```
+
+**Correct: native stack with react-navigation**
+
+```tsx
+import { createNativeStackNavigator } from '@react-navigation/native-stack'
+
+const Stack = createNativeStackNavigator()
+
+function App() {
+ return (
+
+
+ )
+}
+```
+
+**Correct: expo-router uses native stack by default**
+
+```tsx
+// app/_layout.tsx
+import { Stack } from 'expo-router'
+
+export default function Layout() {
+ return
+
+ )
+}
+```
+
+**Correct: native bottom tabs with react-navigation**
+
+```tsx
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'
+
+const Tab = createNativeBottomTabNavigator()
+
+function App() {
+ return (
+
+ ({ sfSymbol: 'house' }),
+ }}
+ />
+ ({ sfSymbol: 'gear' }),
+ }}
+ />
+
+ )
+}
+```
+
+**Correct: expo-router native tabs**
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { NativeTabs } from 'expo-router/unstable-native-tabs'
+
+export default function TabLayout() {
+ return (
+
+
+ Home
+
+
+ Settings
+
+
+ )
+}
+```
+
+On iOS, native tabs automatically enable `contentInsetAdjustmentBehavior` on the
+
+first `ScrollView` at the root of each tab screen, so content scrolls correctly
+
+behind the translucent tab bar. If you need to disable this, use
+
+`disableAutomaticContentInsets` on the trigger.
+
+**Incorrect: custom header component**
+
+```tsx
+
+ {itemCount} items
+ Total: ${total}
+
+ )
+}
+```
+
+**Correct: derived values**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+ const total = items.reduce((sum, item) => sum + item.price, 0)
+ const itemCount = items.length
+
+ return (
+
+ {itemCount} items
+ Total: ${total}
+
+ )
+}
+```
+
+**Another example:**
+
+```tsx
+// Incorrect: storing both firstName, lastName, AND fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const [fullName, setFullName] = useState('')
+
+// Correct: derive fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const fullName = `${firstName} ${lastName}`
+```
+
+State should be the minimal source of truth. Everything else is derived.
+
+Reference: [https://react.dev/learn/choosing-the-state-structure](https://react.dev/learn/choosing-the-state-structure)
+
+### 6.2 Use fallback state instead of initialState
+
+**Impact: MEDIUM (reactive fallbacks without syncing)**
+
+Use `undefined` as initial state and nullish coalescing (`??`) to fall back to
+
+parent or server values. State represents user intent only—`undefined` means
+
+"user hasn't chosen yet." This enables reactive fallbacks that update when the
+
+source changes, not just on initial render.
+
+**Incorrect: syncs state, loses reactivity**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+ const [enabled, setEnabled] = useState(defaultEnabled)
+ // If fallbackEnabled changes, state is stale
+ // State mixes user intent with default value
+
+ return (undefined)
+ const enabled = _enabled ?? defaultEnabled
+ // undefined = user hasn't touched it, falls back to prop
+ // If defaultEnabled changes, component reflects it
+ // Once user interacts, their choice persists
+
+ return (undefined)
+ const theme = _theme ?? data.theme
+ // Shows server value until user overrides
+ // Server refetch updates the fallback automatically
+
+ return (undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+ const { width, height } = e.nativeEvent.layout
+ // size may be stale in this closure
+ if (size?.width !== width || size?.height !== height) {
+ setSize({ width, height })
+ }
+}
+```
+
+**Correct: dispatch updater**
+
+```tsx
+const [size, setSize] = useState(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+ const { width, height } = e.nativeEvent.layout
+ setSize((prev) => {
+ if (prev?.width === width && prev?.height === height) return prev
+ return { width, height }
+ })
+}
+```
+
+Returning the previous value from the updater skips the re-render.
+
+For primitive states, you don't need to compare values before firing a
+
+re-render.
+
+**Incorrect: unnecessary comparison for primitive state**
+
+```tsx
+const [size, setSize] = useState(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+ const { width, height } = e.nativeEvent.layout
+ setSize((prev) => (prev === width ? prev : width))
+}
+```
+
+**Correct: sets primitive state directly**
+
+```tsx
+const [size, setSize] = useState(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+ const { width, height } = e.nativeEvent.layout
+ setSize(width)
+}
+```
+
+However, if the next state depends on the current state, you should still use a
+
+dispatch updater.
+
+**Incorrect: reads state directly from the callback**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+ setCount(count + 1)
+}
+```
+
+**Correct: dispatch updater**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+ setCount((prev) => prev + 1)
+}
+```
+
+---
+
+## 7. State Architecture
+
+**Impact: MEDIUM**
+
+Ground truth principles for state variables and derived values.
+
+### 7.1 State Must Represent Ground Truth
+
+**Impact: HIGH (cleaner logic, easier debugging, single source of truth)**
+
+State variables—both React `useState` and Reanimated shared values—should
+
+represent the actual state of something (e.g., `pressed`, `progress`, `isOpen`),
+
+not derived visual values (e.g., `scale`, `opacity`, `translateY`). Derive
+
+visual values from state using computation or interpolation.
+
+**Incorrect: storing the visual output**
+
+```tsx
+const scale = useSharedValue(1)
+
+const tap = Gesture.Tap()
+ .onBegin(() => {
+ scale.set(withTiming(0.95))
+ })
+ .onFinalize(() => {
+ scale.set(withTiming(1))
+ })
+
+const animatedStyle = useAnimatedStyle(() => ({
+ transform: [{ scale: scale.get() }],
+}))
+```
+
+**Correct: storing the state, deriving the visual**
+
+```tsx
+const pressed = useSharedValue(0) // 0 = not pressed, 1 = pressed
+
+const tap = Gesture.Tap()
+ .onBegin(() => {
+ pressed.set(withTiming(1))
+ })
+ .onFinalize(() => {
+ pressed.set(withTiming(0))
+ })
+
+const animatedStyle = useAnimatedStyle(() => ({
+ transform: [{ scale: interpolate(pressed.get(), [0, 1], [1, 0.95]) }],
+}))
+```
+
+**Why this matters:**
+
+State variables should represent real "state", not necessarily a desired end
+
+result.
+
+1. **Single source of truth** — The state (`pressed`) describes what's
+
+ happening; visuals are derived
+
+2. **Easier to extend** — Adding opacity, rotation, or other effects just
+
+ requires more interpolations from the same state
+
+3. **Debugging** — Inspecting `pressed = 1` is clearer than `scale = 0.95`
+
+4. **Reusable logic** — The same `pressed` value can drive multiple visual
+
+ properties
+
+**Same principle for React state:**
+
+```tsx
+// Incorrect: storing derived values
+const [isExpanded, setIsExpanded] = useState(false)
+const [height, setHeight] = useState(0)
+
+useEffect(() => {
+ setHeight(isExpanded ? 200 : 0)
+}, [isExpanded])
+
+// Correct: derive from state
+const [isExpanded, setIsExpanded] = useState(false)
+const height = isExpanded ? 200 : 0
+```
+
+State is the minimal truth. Everything else is derived.
+
+---
+
+## 8. React Compiler
+
+**Impact: MEDIUM**
+
+Compatibility patterns for React Compiler with React Native and
+Reanimated.
+
+### 8.1 Destructure Functions Early in Render (React Compiler)
+
+**Impact: HIGH (stable references, fewer re-renders)**
+
+This rule is only applicable if you are using the React Compiler.
+
+Destructure functions from hooks at the top of render scope. Never dot into
+
+objects to call functions. Destructured functions are stable references; dotting
+
+creates new references and breaks memoization.
+
+**Incorrect: dotting into object**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton(props) {
+ const router = useRouter()
+
+ // bad: react-compiler will key the cache on "props" and "router", which are objects that change each render
+ const handlePress = () => {
+ props.onSave()
+ router.push('/success') // unstable reference
+ }
+
+ return
+}
+```
+
+**Correct: destructure early**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton({ onSave }) {
+ const { push } = useRouter()
+
+ // good: react-compiler will key on push and onSave
+ const handlePress = () => {
+ onSave()
+ push('/success') // stable reference
+ }
+
+ return
+}
+```
+
+### 8.2 Use .get() and .set() for Reanimated Shared Values (not .value)
+
+**Impact: LOW (required for React Compiler compatibility)**
+
+With React Compiler enabled, use `.get()` and `.set()` instead of reading or
+
+writing `.value` directly on Reanimated shared values. The compiler can't track
+
+property access—explicit methods ensure correct behavior.
+
+**Incorrect: breaks with React Compiler**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+ const count = useSharedValue(0)
+
+ const increment = () => {
+ count.value = count.value + 1 // opts out of react compiler
+ }
+
+ return
+}
+```
+
+**Correct: React Compiler compatible**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+ const count = useSharedValue(0)
+
+ const increment = () => {
+ count.set(count.get() + 1)
+ }
+
+ return
+}
+```
+
+See the
+
+[Reanimated docs](https://docs.swmansion.com/react-native-reanimated/docs/core/useSharedValue/#react-compiler-support)
+
+for more.
+
+---
+
+## 9. User Interface
+
+**Impact: MEDIUM**
+
+Native UI patterns for images, menus, modals, styling, and
+platform-consistent interfaces.
+
+### 9.1 Measuring View Dimensions
+
+**Impact: MEDIUM (synchronous measurement, avoid unnecessary re-renders)**
+
+Use both `useLayoutEffect` (synchronous) and `onLayout` (for updates). The sync
+
+measurement gives you the initial size immediately; `onLayout` keeps it current
+
+when the view changes. For non-primitive states, use a dispatch updater to
+
+compare values and avoid unnecessary re-renders.
+
+**Height only:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+ const ref = useRef(null)
+ const [height, setHeight] = useState(undefined)
+
+ useLayoutEffect(() => {
+ // Sync measurement on mount (RN 0.82+)
+ const rect = ref.current?.getBoundingClientRect()
+ if (rect) setHeight(rect.height)
+ // Pre-0.82: ref.current?.measure((x, y, w, h) => setHeight(h))
+ }, [])
+
+ const onLayout = (e: LayoutChangeEvent) => {
+ setHeight(e.nativeEvent.layout.height)
+ }
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+**Both dimensions:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+type Size = { width: number; height: number }
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+ const ref = useRef(null)
+ const [size, setSize] = useState(undefined)
+
+ useLayoutEffect(() => {
+ const rect = ref.current?.getBoundingClientRect()
+ if (rect) setSize({ width: rect.width, height: rect.height })
+ }, [])
+
+ const onLayout = (e: LayoutChangeEvent) => {
+ const { width, height } = e.nativeEvent.layout
+ setSize((prev) => {
+ // for non-primitive states, compare values before firing a re-render
+ if (prev?.width === width && prev?.height === height) return prev
+ return { width, height }
+ })
+ }
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+Use functional setState to compare—don't read state directly in the callback.
+
+### 9.2 Modern React Native Styling Patterns
+
+**Impact: MEDIUM (consistent design, smoother borders, cleaner layouts)**
+
+Follow these styling patterns for cleaner, more consistent React Native code.
+
+**Always use `borderCurve: 'continuous'` with `borderRadius`:**
+
+**Use `gap` instead of margin for spacing between elements:**
+
+```tsx
+// Incorrect – margin on children
+
+ Title
+ Subtitle
+
+
+// Correct – gap on parent
+
+ Title
+ Subtitle
+
+```
+
+**Use `padding` for space within, `gap` for space between:**
+
+```tsx
+
+ First
+ Second
+
+```
+
+**Use `experimental_backgroundImage` for linear gradients:**
+
+```tsx
+// Incorrect – third-party gradient library
+Title
+Subtitle
+Caption
+
+// Correct – consistent size, vary weight and color
+Title
+Subtitle
+Caption
+```
+
+Limiting font sizes creates visual consistency. Use `fontWeight` (bold/semibold)
+
+and grayscale colors for hierarchy instead.
+
+### 9.3 Use contentInset for Dynamic ScrollView Spacing
+
+**Impact: LOW (smoother updates, no layout recalculation)**
+
+When adding space to the top or bottom of a ScrollView that may change
+
+(keyboard, toolbars, dynamic content), use `contentInset` instead of padding.
+
+Changing `contentInset` doesn't trigger layout recalculation—it adjusts the
+
+scroll area without re-rendering content.
+
+**Incorrect: padding causes layout recalculation**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+ return (
+
+ {children}
+
+ )
+}
+// Changing bottomOffset triggers full layout recalculation
+```
+
+**Correct: contentInset for dynamic spacing**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+ return (
+
+ {children}
+
+ )
+}
+// Changing bottomOffset only adjusts scroll bounds
+```
+
+Use `scrollIndicatorInsets` alongside `contentInset` to keep the scroll
+
+indicator aligned. For static spacing that never changes, padding is fine.
+
+### 9.4 Use contentInsetAdjustmentBehavior for Safe Areas
+
+**Impact: MEDIUM (native safe area handling, no layout shifts)**
+
+Use `contentInsetAdjustmentBehavior="automatic"` on the root ScrollView instead of wrapping content in SafeAreaView or manual padding. This lets iOS handle safe area insets natively with proper scroll behavior.
+
+**Incorrect: SafeAreaView wrapper**
+
+```tsx
+import { SafeAreaView, ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+ return (
+
+
+
+ Content
+
+
+
+ )
+}
+```
+
+**Incorrect: manual safe area padding**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+
+function MyScreen() {
+ const insets = useSafeAreaInsets()
+
+ return (
+
+
+ Content
+
+
+ )
+}
+```
+
+**Correct: native content inset adjustment**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+ return (
+
+
+ Content
+
+
+ )
+}
+```
+
+The native approach handles dynamic safe areas (keyboard, toolbars) and allows content to scroll behind the status bar naturally.
+
+### 9.5 Use expo-image for Optimized Images
+
+**Impact: HIGH (memory efficiency, caching, blurhash placeholders, progressive loading)**
+
+Use `expo-image` instead of React Native's `Image`. It provides memory-efficient caching, blurhash placeholders, progressive loading, and better performance for lists.
+
+**Incorrect: React Native Image**
+
+```tsx
+import { Image } from 'react-native'
+
+function Avatar({ url }: { url: string }) {
+ return (null)
+
+ return (
+ <>
+ {urls.map((url) => (
+ setSelected(url)}>
+
+ ))}
+ setSelected(null)}>
+
+
+ )
+}
+```
+
+**Correct: Galeria with expo-image**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function ImageGallery({ urls }: { urls: string[] }) {
+ return (
+
+ {urls.map((url, index) => (
+
+
+ ))}
+
+ )
+}
+```
+
+**Single image:**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+ return (
+
+
+
+
+ )
+}
+```
+
+**With low-res thumbnails and high-res fullscreen:**
+
+```tsx
+
+ {lowResUrls.map((url, index) => (
+
+
+ ))}
+
+```
+
+**With FlashList:**
+
+```tsx
+
+ (
+
+
+ )}
+ numColumns={3}
+ estimatedItemSize={100}
+ />
+
+```
+
+Works with `expo-image`, `SolitoImage`, `react-native` Image, or any image
+
+component.
+
+Reference: [https://github.com/nandorojo/galeria](https://github.com/nandorojo/galeria)
+
+### 9.7 Use Native Menus for Dropdowns and Context Menus
+
+**Impact: HIGH (native accessibility, platform-consistent UX)**
+
+Use native platform menus instead of custom JS implementations. Native menus
+
+provide built-in accessibility, consistent platform UX, and better performance.
+
+Use [zeego](https://zeego.dev) for cross-platform native menus.
+
+**Incorrect: custom JS menu**
+
+```tsx
+import { useState } from 'react'
+import { View, Pressable, Text } from 'react-native'
+
+function MyMenu() {
+ const [open, setOpen] = useState(false)
+
+ return (
+
+ setOpen(!open)}>
+ Open Menu
+
+ {open && (
+
+ console.log('edit')}>
+ Edit
+
+ console.log('delete')}>
+ Delete
+
+
+ )}
+
+ )
+}
+```
+
+**Correct: native menu with zeego**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MyMenu() {
+ return (
+
+
+
+ Open Menu
+
+
+
+
+ console.log('edit')}>
+ Edit
+
+
+ console.log('delete')}
+ >
+ Delete
+
+
+
+ )
+}
+```
+
+**Context menu: long-press**
+
+```tsx
+import * as ContextMenu from 'zeego/context-menu'
+
+function MyContextMenu() {
+ return (
+
+
+
+ Long press me
+
+
+
+
+ console.log('copy')}>
+ Copy
+
+
+ console.log('paste')}>
+ Paste
+
+
+
+ )
+}
+```
+
+**Checkbox items:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function SettingsMenu() {
+ const [notifications, setNotifications] = useState(true)
+
+ return (
+
+
+
+ Settings
+
+
+
+
+ setNotifications((prev) => !prev)}
+ >
+ Notifications
+
+
+
+ )
+}
+```
+
+**Submenus:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MenuWithSubmenu() {
+ return (
+
+
+
+ Options
+
+
+
+
+ console.log('home')}>
+ Home
+
+
+
+
+ More Options
+
+
+
+
+ Settings
+
+
+
+ Help
+
+
+
+
+
+ )
+}
+```
+
+Reference: [https://zeego.dev/components/dropdown-menu](https://zeego.dev/components/dropdown-menu)
+
+### 9.8 Use Native Modals Over JS-Based Bottom Sheets
+
+**Impact: HIGH (native performance, gestures, accessibility)**
+
+Use native `` with `presentationStyle="formSheet"` or React Navigation
+
+v7's native form sheet instead of JS-based bottom sheet libraries. Native modals
+
+have built-in gestures, accessibility, and better performance. Rely on native UI
+
+for low-level primitives.
+
+**Incorrect: JS-based bottom sheet**
+
+```tsx
+import BottomSheet from 'custom-js-bottom-sheet'
+
+function MyScreen() {
+ const sheetRef = useRef(null)
+
+ return (
+
+
+ )
+}
+```
+
+**Correct: native Modal with formSheet**
+
+```tsx
+import { Modal, View, Text, Button } from 'react-native'
+
+function MyScreen() {
+ const [visible, setVisible] = useState(false)
+
+ return (
+
+
+ )
+}
+```
+
+**Correct: React Navigation v7 native form sheet**
+
+```tsx
+// In your navigator
+
+ Press me
+
+ )
+}
+```
+
+**Correct: Pressable**
+
+```tsx
+import { Pressable } from 'react-native'
+
+function MyButton({ onPress }: { onPress: () => void }) {
+ return (
+
+ Press me
+
+ )
+}
+```
+
+**Correct: Pressable from gesture handler for lists**
+
+```tsx
+import { Pressable } from 'react-native-gesture-handler'
+
+function ListItem({ onPress }: { onPress: () => void }) {
+ return (
+
+ Item
+
+ )
+}
+```
+
+Use `react-native-gesture-handler` Pressable inside scrollable lists for better
+
+gesture coordination, as long as you are using the ScrollView from
+
+`react-native-gesture-handler` as well.
+
+**For animated press states (scale, opacity changes):** Use `GestureDetector`
+
+with Reanimated shared values instead of Pressable's style callback. See the
+
+`animation-gesture-detector-press` rule.
+
+---
+
+## 10. Design System
+
+**Impact: MEDIUM**
+
+Architecture patterns for building maintainable component
+libraries.
+
+### 10.1 Use Compound Components Over Polymorphic Children
+
+**Impact: MEDIUM (flexible composition, clearer API)**
+
+Don't create components that can accept a string if they aren't a text node. If
+
+a component can receive a string child, it must be a dedicated `*Text`
+
+component. For components like buttons, which can have both a View (or
+
+Pressable) together with text, use compound components, such a `Button`,
+
+`ButtonText`, and `ButtonIcon`.
+
+**Incorrect: polymorphic children**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+type ButtonProps = {
+ children: string | React.ReactNode
+ icon?: React.ReactNode
+}
+
+function Button({ children, icon }: ButtonProps) {
+ return (
+
+ {icon}
+ {typeof children === 'string' ? {children} : children}
+
+ )
+}
+
+// Usage is ambiguous
+}>Save
+
+```
+
+**Correct: compound components**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+function Button({ children }: { children: React.ReactNode }) {
+ return {children}
+}
+
+function ButtonText({ children }: { children: React.ReactNode }) {
+ return {children}
+}
+
+function ButtonIcon({ children }: { children: React.ReactNode }) {
+ return <>{children}
+}
+
+// Usage is explicit and composable
+
+
+
+```
+
+---
+
+## 11. Monorepo
+
+**Impact: LOW**
+
+Dependency management and native module configuration in
+monorepos.
+
+### 11.1 Install Native Dependencies in App Directory
+
+**Impact: CRITICAL (required for autolinking to work)**
+
+In a monorepo, packages with native code must be installed in the native app's
+
+directory directly. Autolinking only scans the app's `node_modules`—it won't
+
+find native dependencies installed in other packages.
+
+**Incorrect: native dep in shared package only**
+
+```typescript
+packages/
+ ui/
+ package.json # has react-native-reanimated
+ app/
+ package.json # missing react-native-reanimated
+```
+
+Autolinking fails—native code not linked.
+
+**Correct: native dep in app directory**
+
+```json
+// packages/app/package.json
+{
+ "dependencies": {
+ "react-native-reanimated": "3.16.1"
+ }
+}
+```
+
+Even if the shared package uses the native dependency, the app must also list it
+
+for autolinking to detect and link the native code.
+
+### 11.2 Use Single Dependency Versions Across Monorepo
+
+**Impact: MEDIUM (avoids duplicate bundles, version conflicts)**
+
+Use a single version of each dependency across all packages in your monorepo.
+
+Prefer exact versions over ranges. Multiple versions cause duplicate code in
+
+bundles, runtime conflicts, and inconsistent behavior across packages.
+
+Use a tool like syncpack to enforce this. As a last resort, use yarn resolutions
+
+or npm overrides.
+
+**Incorrect: version ranges, multiple versions**
+
+```json
+// packages/app/package.json
+{
+ "dependencies": {
+ "react-native-reanimated": "^3.0.0"
+ }
+}
+
+// packages/ui/package.json
+{
+ "dependencies": {
+ "react-native-reanimated": "^3.5.0"
+ }
+}
+```
+
+**Correct: exact versions, single source of truth**
+
+```json
+// package.json (root)
+{
+ "pnpm": {
+ "overrides": {
+ "react-native-reanimated": "3.16.1"
+ }
+ }
+}
+
+// packages/app/package.json
+{
+ "dependencies": {
+ "react-native-reanimated": "3.16.1"
+ }
+}
+
+// packages/ui/package.json
+{
+ "dependencies": {
+ "react-native-reanimated": "3.16.1"
+ }
+}
+```
+
+Use your package manager's override/resolution feature to enforce versions at
+
+the root. When adding dependencies, specify exact versions without `^` or `~`.
+
+---
+
+## 12. Third-Party Dependencies
+
+**Impact: LOW**
+
+Wrapping and re-exporting third-party dependencies for
+maintainability.
+
+### 12.1 Import from Design System Folder
+
+**Impact: LOW (enables global changes and easy refactoring)**
+
+Re-export dependencies from a design system folder. App code imports from there,
+
+not directly from packages. This enables global changes and easy refactoring.
+
+**Incorrect: imports directly from package**
+
+```tsx
+import { View, Text } from 'react-native'
+import { Button } from '@ui/button'
+
+function Profile() {
+ return (
+
+ Hello
+
+
+ )
+}
+```
+
+**Correct: imports from design system**
+
+```tsx
+import { View } from '@/components/view'
+import { Text } from '@/components/text'
+import { Button } from '@/components/button'
+
+function Profile() {
+ return (
+
+ Hello
+
+
+ )
+}
+```
+
+Start by simply re-exporting. Customize later without changing app code.
+
+---
+
+## 13. JavaScript
+
+**Impact: LOW**
+
+Micro-optimizations like hoisting expensive object creation.
+
+### 13.1 Hoist Intl Formatter Creation
+
+**Impact: LOW-MEDIUM (avoids expensive object recreation)**
+
+Don't create `Intl.DateTimeFormat`, `Intl.NumberFormat`, or
+
+`Intl.RelativeTimeFormat` inside render or loops. These are expensive to
+
+instantiate. Hoist to module scope when the locale/options are static.
+
+**Incorrect: new formatter every render**
+
+```tsx
+function Price({ amount }: { amount: number }) {
+ const formatter = new Intl.NumberFormat('en-US', {
+ style: 'currency',
+ currency: 'USD',
+ })
+ return {formatter.format(amount)}
+}
+```
+
+**Correct: hoisted to module scope**
+
+```tsx
+const currencyFormatter = new Intl.NumberFormat('en-US', {
+ style: 'currency',
+ currency: 'USD',
+})
+
+function Price({ amount }: { amount: number }) {
+ return {currencyFormatter.format(amount)}
+}
+```
+
+**For dynamic locales, memoize:**
+
+```tsx
+const dateFormatter = useMemo(
+ () => new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }),
+ [locale]
+)
+```
+
+**Common formatters to hoist:**
+
+```tsx
+// Module-level formatters
+const dateFormatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' })
+const timeFormatter = new Intl.DateTimeFormat('en-US', { timeStyle: 'short' })
+const percentFormatter = new Intl.NumberFormat('en-US', { style: 'percent' })
+const relativeFormatter = new Intl.RelativeTimeFormat('en-US', {
+ numeric: 'auto',
+})
+```
+
+Creating `Intl` objects is significantly more expensive than `RegExp` or plain
+
+objects—each instantiation parses locale data and builds internal lookup tables.
+
+---
+
+## 14. Fonts
+
+**Impact: LOW**
+
+Native font loading for improved performance.
+
+### 14.1 Load fonts natively at build time
+
+**Impact: LOW (fonts available at launch, no async loading)**
+
+Use the `expo-font` config plugin to embed fonts at build time instead of
+
+`useFonts` or `Font.loadAsync`. Embedded fonts are more efficient.
+
+[Expo Font Documentation](https://docs.expo.dev/versions/latest/sdk/font/)
+
+**Incorrect: async font loading**
+
+```tsx
+import { useFonts } from 'expo-font'
+import { Text, View } from 'react-native'
+
+function App() {
+ const [fontsLoaded] = useFonts({
+ 'Geist-Bold': require('./assets/fonts/Geist-Bold.otf'),
+ })
+
+ if (!fontsLoaded) {
+ return null
+ }
+
+ return (
+
+ Hello
+
+ )
+}
+```
+
+**Correct: config plugin, fonts embedded at build**
+
+```tsx
+import { Text, View } from 'react-native'
+
+function App() {
+ // No loading state needed—font is already available
+ return (
+
+ Hello
+
+ )
+}
+```
+
+After adding fonts to the config plugin, run `npx expo prebuild` and rebuild the
+
+native app.
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://reactnative.dev](https://reactnative.dev)
+3. [https://docs.swmansion.com/react-native-reanimated](https://docs.swmansion.com/react-native-reanimated)
+4. [https://docs.swmansion.com/react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler)
+5. [https://docs.expo.dev](https://docs.expo.dev)
+6. [https://legendapp.com/open-source/legend-list](https://legendapp.com/open-source/legend-list)
+7. [https://github.com/nandorojo/galeria](https://github.com/nandorojo/galeria)
+8. [https://zeego.dev](https://zeego.dev)
diff --git a/skills/vercel-react-native-skills/README.md b/skills/vercel-react-native-skills/README.md
new file mode 100644
index 00000000..854db9f5
--- /dev/null
+++ b/skills/vercel-react-native-skills/README.md
@@ -0,0 +1,165 @@
+# React Native Guidelines
+
+A structured repository for creating and maintaining React Native Best Practices
+optimized for agents and LLMs.
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+ - `_sections.md` - Section metadata (titles, impacts, descriptions)
+ - `_template.md` - Template for creating new rules
+ - `area-description.md` - Individual rule files
+- `metadata.json` - Document metadata (version, organization, abstract)
+- **`AGENTS.md`** - Compiled output (generated)
+
+## Rules
+
+### Core Rendering (CRITICAL)
+
+- `rendering-text-in-text-component.md` - Wrap strings in Text components
+- `rendering-no-falsy-and.md` - Avoid falsy && operator in JSX
+
+### List Performance (HIGH)
+
+- `list-performance-virtualize.md` - Use virtualized lists (LegendList,
+ FlashList)
+- `list-performance-function-references.md` - Keep stable object references
+- `list-performance-callbacks.md` - Hoist callbacks to list root
+- `list-performance-inline-objects.md` - Avoid inline objects in renderItem
+- `list-performance-item-memo.md` - Pass primitives for memoization
+- `list-performance-item-expensive.md` - Keep list items lightweight
+- `list-performance-images.md` - Use compressed images in lists
+- `list-performance-item-types.md` - Use item types for heterogeneous lists
+
+### Animation (HIGH)
+
+- `animation-gpu-properties.md` - Animate transform/opacity instead of layout
+- `animation-gesture-detector-press.md` - Use GestureDetector for press
+ animations
+- `animation-derived-value.md` - Prefer useDerivedValue over useAnimatedReaction
+
+### Scroll Performance (HIGH)
+
+- `scroll-position-no-state.md` - Never track scroll in useState
+
+### Navigation (HIGH)
+
+- `navigation-native-navigators.md` - Use native stack and native tabs
+
+### React State (MEDIUM)
+
+- `react-state-dispatcher.md` - Use functional setState updates
+- `react-state-fallback.md` - State should represent user intent only
+- `react-state-minimize.md` - Minimize state variables, derive values
+
+### State Architecture (MEDIUM)
+
+- `state-ground-truth.md` - State must represent ground truth
+
+### React Compiler (MEDIUM)
+
+- `react-compiler-destructure-functions.md` - Destructure functions early
+- `react-compiler-reanimated-shared-values.md` - Use .get()/.set() for shared
+ values
+
+### User Interface (MEDIUM)
+
+- `ui-expo-image.md` - Use expo-image for optimized images
+- `ui-image-gallery.md` - Use Galeria for lightbox/galleries
+- `ui-menus.md` - Native dropdown and context menus with Zeego
+- `ui-native-modals.md` - Use native Modal with formSheet
+- `ui-pressable.md` - Use Pressable instead of TouchableOpacity
+- `ui-measure-views.md` - Measuring view dimensions
+- `ui-safe-area-scroll.md` - Use contentInsetAdjustmentBehavior
+- `ui-scrollview-content-inset.md` - Use contentInset for dynamic spacing
+- `ui-styling.md` - Modern styling patterns (gap, boxShadow, gradients)
+
+### Design System (MEDIUM)
+
+- `design-system-compound-components.md` - Use compound components
+
+### Monorepo (LOW)
+
+- `monorepo-native-deps-in-app.md` - Install native deps in app directory
+- `monorepo-single-dependency-versions.md` - Single dependency versions
+
+### Third-Party Dependencies (LOW)
+
+- `imports-design-system-folder.md` - Import from design system folder
+
+### JavaScript (LOW)
+
+- `js-hoist-intl.md` - Hoist Intl formatter creation
+
+### Fonts (LOW)
+
+- `fonts-config-plugin.md` - Load fonts natively at build time
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+ - `rendering-` for Core Rendering
+ - `list-performance-` for List Performance
+ - `animation-` for Animation
+ - `scroll-` for Scroll Performance
+ - `navigation-` for Navigation
+ - `react-state-` for React State
+ - `state-` for State Architecture
+ - `react-compiler-` for React Compiler
+ - `ui-` for User Interface
+ - `design-system-` for Design System
+ - `monorepo-` for Monorepo
+ - `imports-` for Third-Party Dependencies
+ - `js-` for JavaScript
+ - `fonts-` for Fonts
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+
+## Rule File Structure
+
+Each rule file should follow this structure:
+
+````markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description of what's wrong):**
+
+```tsx
+// Bad code example
+```
+````
+
+**Correct (description of what's right):**
+
+```tsx
+// Good code example
+```
+
+Reference: [Link](https://example.com)
+
+```
+
+## File Naming Convention
+
+- Files starting with `_` are special (excluded from build)
+- Rule files: `area-description.md` (e.g., `animation-gpu-properties.md`)
+- Section is automatically inferred from filename prefix
+- Rules are sorted alphabetically by title within each section
+
+## Impact Levels
+
+- `CRITICAL` - Highest priority, causes crashes or broken UI
+- `HIGH` - Significant performance improvements
+- `MEDIUM` - Moderate performance improvements
+- `LOW` - Incremental improvements
+```
diff --git a/skills/vercel-react-native-skills/SKILL.md b/skills/vercel-react-native-skills/SKILL.md
new file mode 100644
index 00000000..73401865
--- /dev/null
+++ b/skills/vercel-react-native-skills/SKILL.md
@@ -0,0 +1,121 @@
+---
+name: vercel-react-native-skills
+description:
+ React Native and Expo best practices for building performant mobile apps. Use
+ when building React Native components, optimizing list performance,
+ implementing animations, or working with native modules. Triggers on tasks
+ involving React Native, Expo, mobile performance, or native platform APIs.
+license: MIT
+metadata:
+ author: vercel
+ version: '1.0.0'
+---
+
+# React Native Skills
+
+Comprehensive best practices for React Native and Expo applications. Contains
+rules across multiple categories covering performance, animations, UI patterns,
+and platform-specific optimizations.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Building React Native or Expo apps
+- Optimizing list and scroll performance
+- Implementing animations with Reanimated
+- Working with images and media
+- Configuring native modules or fonts
+- Structuring monorepo projects with native dependencies
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+| -------- | ---------------- | -------- | -------------------- |
+| 1 | List Performance | CRITICAL | `list-performance-` |
+| 2 | Animation | HIGH | `animation-` |
+| 3 | Navigation | HIGH | `navigation-` |
+| 4 | UI Patterns | HIGH | `ui-` |
+| 5 | State Management | MEDIUM | `react-state-` |
+| 6 | Rendering | MEDIUM | `rendering-` |
+| 7 | Monorepo | MEDIUM | `monorepo-` |
+| 8 | Configuration | LOW | `fonts-`, `imports-` |
+
+## Quick Reference
+
+### 1. List Performance (CRITICAL)
+
+- `list-performance-virtualize` - Use FlashList for large lists
+- `list-performance-item-memo` - Memoize list item components
+- `list-performance-callbacks` - Stabilize callback references
+- `list-performance-inline-objects` - Avoid inline style objects
+- `list-performance-function-references` - Extract functions outside render
+- `list-performance-images` - Optimize images in lists
+- `list-performance-item-expensive` - Move expensive work outside items
+- `list-performance-item-types` - Use item types for heterogeneous lists
+
+### 2. Animation (HIGH)
+
+- `animation-gpu-properties` - Animate only transform and opacity
+- `animation-derived-value` - Use useDerivedValue for computed animations
+- `animation-gesture-detector-press` - Use Gesture.Tap instead of Pressable
+
+### 3. Navigation (HIGH)
+
+- `navigation-native-navigators` - Use native stack and native tabs over JS navigators
+
+### 4. UI Patterns (HIGH)
+
+- `ui-expo-image` - Use expo-image for all images
+- `ui-image-gallery` - Use Galeria for image lightboxes
+- `ui-pressable` - Use Pressable over TouchableOpacity
+- `ui-safe-area-scroll` - Handle safe areas in ScrollViews
+- `ui-scrollview-content-inset` - Use contentInset for headers
+- `ui-menus` - Use native context menus
+- `ui-native-modals` - Use native modals when possible
+- `ui-measure-views` - Use onLayout, not measure()
+- `ui-styling` - Use StyleSheet.create or Nativewind
+
+### 5. State Management (MEDIUM)
+
+- `react-state-minimize` - Minimize state subscriptions
+- `react-state-dispatcher` - Use dispatcher pattern for callbacks
+- `react-state-fallback` - Show fallback on first render
+- `react-compiler-destructure-functions` - Destructure for React Compiler
+- `react-compiler-reanimated-shared-values` - Handle shared values with compiler
+
+### 6. Rendering (MEDIUM)
+
+- `rendering-text-in-text-component` - Wrap text in Text components
+- `rendering-no-falsy-and` - Avoid falsy && for conditional rendering
+
+### 7. Monorepo (MEDIUM)
+
+- `monorepo-native-deps-in-app` - Keep native dependencies in app package
+- `monorepo-single-dependency-versions` - Use single versions across packages
+
+### 8. Configuration (LOW)
+
+- `fonts-config-plugin` - Use config plugins for custom fonts
+- `imports-design-system-folder` - Organize design system imports
+- `js-hoist-intl` - Hoist Intl object creation
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/list-performance-virtualize.md
+rules/animation-gpu-properties.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/skills/vercel-react-native-skills/rules/_sections.md b/skills/vercel-react-native-skills/rules/_sections.md
new file mode 100644
index 00000000..0519cf23
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/_sections.md
@@ -0,0 +1,86 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Core Rendering (rendering)
+
+**Impact:** CRITICAL
+**Description:** Fundamental React Native rendering rules. Violations cause
+runtime crashes or broken UI.
+
+## 2. List Performance (list-performance)
+
+**Impact:** HIGH
+**Description:** Optimizing virtualized lists (FlatList, LegendList, FlashList)
+for smooth scrolling and fast updates.
+
+## 3. Animation (animation)
+
+**Impact:** HIGH
+**Description:** GPU-accelerated animations, Reanimated patterns, and avoiding
+render thrashing during gestures.
+
+## 4. Scroll Performance (scroll)
+
+**Impact:** HIGH
+**Description:** Tracking scroll position without causing render thrashing.
+
+## 5. Navigation (navigation)
+
+**Impact:** HIGH
+**Description:** Using native navigators for stack and tab navigation instead of
+JS-based alternatives.
+
+## 6. React State (react-state)
+
+**Impact:** MEDIUM
+**Description:** Patterns for managing React state to avoid stale closures and
+unnecessary re-renders.
+
+## 7. State Architecture (state)
+
+**Impact:** MEDIUM
+**Description:** Ground truth principles for state variables and derived values.
+
+## 8. React Compiler (react-compiler)
+
+**Impact:** MEDIUM
+**Description:** Compatibility patterns for React Compiler with React Native and
+Reanimated.
+
+## 9. User Interface (ui)
+
+**Impact:** MEDIUM
+**Description:** Native UI patterns for images, menus, modals, styling, and
+platform-consistent interfaces.
+
+## 10. Design System (design-system)
+
+**Impact:** MEDIUM
+**Description:** Architecture patterns for building maintainable component
+libraries.
+
+## 11. Monorepo (monorepo)
+
+**Impact:** LOW
+**Description:** Dependency management and native module configuration in
+monorepos.
+
+## 12. Third-Party Dependencies (imports)
+
+**Impact:** LOW
+**Description:** Wrapping and re-exporting third-party dependencies for
+maintainability.
+
+## 13. JavaScript (js)
+
+**Impact:** LOW
+**Description:** Micro-optimizations like hoisting expensive object creation.
+
+## 14. Fonts (fonts)
+
+**Impact:** LOW
+**Description:** Native font loading for improved performance.
diff --git a/skills/vercel-react-native-skills/rules/_template.md b/skills/vercel-react-native-skills/rules/_template.md
new file mode 100644
index 00000000..1e9e7070
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/_template.md
@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
diff --git a/skills/vercel-react-native-skills/rules/animation-derived-value.md b/skills/vercel-react-native-skills/rules/animation-derived-value.md
new file mode 100644
index 00000000..310928a9
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/animation-derived-value.md
@@ -0,0 +1,53 @@
+---
+title: Prefer useDerivedValue Over useAnimatedReaction
+impact: MEDIUM
+impactDescription: cleaner code, automatic dependency tracking
+tags: animation, reanimated, derived-value
+---
+
+## Prefer useDerivedValue Over useAnimatedReaction
+
+When deriving a shared value from another, use `useDerivedValue` instead of
+`useAnimatedReaction`. Derived values are declarative, automatically track
+dependencies, and return a value you can use directly. Animated reactions are
+for side effects, not derivations.
+
+**Incorrect (useAnimatedReaction for derivation):**
+
+```tsx
+import { useSharedValue, useAnimatedReaction } from 'react-native-reanimated'
+
+function MyComponent() {
+ const progress = useSharedValue(0)
+ const opacity = useSharedValue(1)
+
+ useAnimatedReaction(
+ () => progress.value,
+ (current) => {
+ opacity.value = 1 - current
+ }
+ )
+
+ // ...
+}
+```
+
+**Correct (useDerivedValue):**
+
+```tsx
+import { useSharedValue, useDerivedValue } from 'react-native-reanimated'
+
+function MyComponent() {
+ const progress = useSharedValue(0)
+
+ const opacity = useDerivedValue(() => 1 - progress.get())
+
+ // ...
+}
+```
+
+Use `useAnimatedReaction` only for side effects that don't produce a value
+(e.g., triggering haptics, logging, calling `runOnJS`).
+
+Reference:
+[Reanimated useDerivedValue](https://docs.swmansion.com/react-native-reanimated/docs/core/useDerivedValue)
diff --git a/skills/vercel-react-native-skills/rules/animation-gesture-detector-press.md b/skills/vercel-react-native-skills/rules/animation-gesture-detector-press.md
new file mode 100644
index 00000000..87c67827
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/animation-gesture-detector-press.md
@@ -0,0 +1,95 @@
+---
+title: Use GestureDetector for Animated Press States
+impact: MEDIUM
+impactDescription: UI thread animations, smoother press feedback
+tags: animation, gestures, press, reanimated
+---
+
+## Use GestureDetector for Animated Press States
+
+For animated press states (scale, opacity on press), use `GestureDetector` with
+`Gesture.Tap()` and shared values instead of Pressable's
+`onPressIn`/`onPressOut`. Gesture callbacks run on the UI thread as worklets—no
+JS thread round-trip for press animations.
+
+**Incorrect (Pressable with JS thread callbacks):**
+
+```tsx
+import { Pressable } from 'react-native'
+import Animated, {
+ useSharedValue,
+ useAnimatedStyle,
+ withTiming,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+ const scale = useSharedValue(1)
+
+ const animatedStyle = useAnimatedStyle(() => ({
+ transform: [{ scale: scale.value }],
+ }))
+
+ return (
+ (scale.value = withTiming(0.95))}
+ onPressOut={() => (scale.value = withTiming(1))}
+ >
+
+ Press me
+
+
+ )
+}
+```
+
+**Correct (GestureDetector with UI thread worklets):**
+
+```tsx
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import Animated, {
+ useSharedValue,
+ useAnimatedStyle,
+ withTiming,
+ interpolate,
+ runOnJS,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+ // Store the press STATE (0 = not pressed, 1 = pressed)
+ const pressed = useSharedValue(0)
+
+ const tap = Gesture.Tap()
+ .onBegin(() => {
+ pressed.set(withTiming(1))
+ })
+ .onFinalize(() => {
+ pressed.set(withTiming(0))
+ })
+ .onEnd(() => {
+ runOnJS(onPress)()
+ })
+
+ // Derive visual values from the state
+ const animatedStyle = useAnimatedStyle(() => ({
+ transform: [
+ { scale: interpolate(withTiming(pressed.get()), [0, 1], [1, 0.95]) },
+ ],
+ }))
+
+ return (
+
+
+ Press me
+
+
+ )
+}
+```
+
+Store the press **state** (0 or 1), then derive the scale via `interpolate`.
+This keeps the shared value as ground truth. Use `runOnJS` to call JS functions
+from worklets. Use `.set()` and `.get()` for React Compiler compatibility.
+
+Reference:
+[Gesture Handler Tap Gesture](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture)
diff --git a/skills/vercel-react-native-skills/rules/animation-gpu-properties.md b/skills/vercel-react-native-skills/rules/animation-gpu-properties.md
new file mode 100644
index 00000000..5fda0955
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/animation-gpu-properties.md
@@ -0,0 +1,65 @@
+---
+title: Animate Transform and Opacity Instead of Layout Properties
+impact: HIGH
+impactDescription: GPU-accelerated animations, no layout recalculation
+tags: animation, performance, reanimated, transform, opacity
+---
+
+## Animate Transform and Opacity Instead of Layout Properties
+
+Avoid animating `width`, `height`, `top`, `left`, `margin`, or `padding`. These trigger layout recalculation on every frame. Instead, use `transform` (scale, translate) and `opacity` which run on the GPU without triggering layout.
+
+**Incorrect (animates height, triggers layout every frame):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+ const animatedStyle = useAnimatedStyle(() => ({
+ height: withTiming(expanded ? 200 : 0), // triggers layout on every frame
+ overflow: 'hidden',
+ }))
+
+ return {children}
+}
+```
+
+**Correct (animates scaleY, GPU-accelerated):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+ const animatedStyle = useAnimatedStyle(() => ({
+ transform: [
+ { scaleY: withTiming(expanded ? 1 : 0) },
+ ],
+ opacity: withTiming(expanded ? 1 : 0),
+ }))
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+**Correct (animates translateY for slide animations):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function SlideIn({ visible }: { visible: boolean }) {
+ const animatedStyle = useAnimatedStyle(() => ({
+ transform: [
+ { translateY: withTiming(visible ? 0 : 100) },
+ ],
+ opacity: withTiming(visible ? 1 : 0),
+ }))
+
+ return {children}
+}
+```
+
+GPU-accelerated properties: `transform` (translate, scale, rotate), `opacity`. Everything else triggers layout.
diff --git a/skills/vercel-react-native-skills/rules/design-system-compound-components.md b/skills/vercel-react-native-skills/rules/design-system-compound-components.md
new file mode 100644
index 00000000..d8239ee1
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/design-system-compound-components.md
@@ -0,0 +1,66 @@
+---
+title: Use Compound Components Over Polymorphic Children
+impact: MEDIUM
+impactDescription: flexible composition, clearer API
+tags: design-system, components, composition
+---
+
+## Use Compound Components Over Polymorphic Children
+
+Don't create components that can accept a string if they aren't a text node. If
+a component can receive a string child, it must be a dedicated `*Text`
+component. For components like buttons, which can have both a View (or
+Pressable) together with text, use compound components, such a `Button`,
+`ButtonText`, and `ButtonIcon`.
+
+**Incorrect (polymorphic children):**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+type ButtonProps = {
+ children: string | React.ReactNode
+ icon?: React.ReactNode
+}
+
+function Button({ children, icon }: ButtonProps) {
+ return (
+
+ {icon}
+ {typeof children === 'string' ? {children} : children}
+
+ )
+}
+
+// Usage is ambiguous
+}>Save
+
+```
+
+**Correct (compound components):**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+function Button({ children }: { children: React.ReactNode }) {
+ return {children}
+}
+
+function ButtonText({ children }: { children: React.ReactNode }) {
+ return {children}
+}
+
+function ButtonIcon({ children }: { children: React.ReactNode }) {
+ return <>{children}
+}
+
+// Usage is explicit and composable
+
+
+
+```
diff --git a/skills/vercel-react-native-skills/rules/fonts-config-plugin.md b/skills/vercel-react-native-skills/rules/fonts-config-plugin.md
new file mode 100644
index 00000000..39aa0147
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/fonts-config-plugin.md
@@ -0,0 +1,71 @@
+---
+title: Load fonts natively at build time
+impact: LOW
+impactDescription: fonts available at launch, no async loading
+tags: fonts, expo, performance, config-plugin
+---
+
+## Use Expo Config Plugin for Font Loading
+
+Use the `expo-font` config plugin to embed fonts at build time instead of
+`useFonts` or `Font.loadAsync`. Embedded fonts are more efficient.
+
+**Incorrect (async font loading):**
+
+```tsx
+import { useFonts } from 'expo-font'
+import { Text, View } from 'react-native'
+
+function App() {
+ const [fontsLoaded] = useFonts({
+ 'Geist-Bold': require('./assets/fonts/Geist-Bold.otf'),
+ })
+
+ if (!fontsLoaded) {
+ return null
+ }
+
+ return (
+
+ Hello
+
+ )
+}
+```
+
+**Correct (config plugin, fonts embedded at build):**
+
+```json
+// app.json
+{
+ "expo": {
+ "plugins": [
+ [
+ "expo-font",
+ {
+ "fonts": ["./assets/fonts/Geist-Bold.otf"]
+ }
+ ]
+ ]
+ }
+}
+```
+
+```tsx
+import { Text, View } from 'react-native'
+
+function App() {
+ // No loading state needed—font is already available
+ return (
+
+ Hello
+
+ )
+}
+```
+
+After adding fonts to the config plugin, run `npx expo prebuild` and rebuild the
+native app.
+
+Reference:
+[Expo Font Documentation](https://docs.expo.dev/versions/latest/sdk/font/)
diff --git a/skills/vercel-react-native-skills/rules/imports-design-system-folder.md b/skills/vercel-react-native-skills/rules/imports-design-system-folder.md
new file mode 100644
index 00000000..8466dcb2
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/imports-design-system-folder.md
@@ -0,0 +1,68 @@
+---
+title: Import from Design System Folder
+impact: LOW
+impactDescription: enables global changes and easy refactoring
+tags: imports, architecture, design-system
+---
+
+## Import from Design System Folder
+
+Re-export dependencies from a design system folder. App code imports from there,
+not directly from packages. This enables global changes and easy refactoring.
+
+**Incorrect (imports directly from package):**
+
+```tsx
+import { View, Text } from 'react-native'
+import { Button } from '@ui/button'
+
+function Profile() {
+ return (
+
+ Hello
+
+
+ )
+}
+```
+
+**Correct (imports from design system):**
+
+```tsx
+// components/view.tsx
+import { View as RNView } from 'react-native'
+
+// ideal: pick the props you will actually use to control implementation
+export function View(
+ props: Pick, 'style' | 'children'>
+) {
+ return
+ Hello
+
+
+ )
+}
+```
+
+Start by simply re-exporting. Customize later without changing app code.
diff --git a/skills/vercel-react-native-skills/rules/js-hoist-intl.md b/skills/vercel-react-native-skills/rules/js-hoist-intl.md
new file mode 100644
index 00000000..9af1c354
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/js-hoist-intl.md
@@ -0,0 +1,61 @@
+---
+title: Hoist Intl Formatter Creation
+impact: LOW-MEDIUM
+impactDescription: avoids expensive object recreation
+tags: javascript, intl, optimization, memoization
+---
+
+## Hoist Intl Formatter Creation
+
+Don't create `Intl.DateTimeFormat`, `Intl.NumberFormat`, or
+`Intl.RelativeTimeFormat` inside render or loops. These are expensive to
+instantiate. Hoist to module scope when the locale/options are static.
+
+**Incorrect (new formatter every render):**
+
+```tsx
+function Price({ amount }: { amount: number }) {
+ const formatter = new Intl.NumberFormat('en-US', {
+ style: 'currency',
+ currency: 'USD',
+ })
+ return {formatter.format(amount)}
+}
+```
+
+**Correct (hoisted to module scope):**
+
+```tsx
+const currencyFormatter = new Intl.NumberFormat('en-US', {
+ style: 'currency',
+ currency: 'USD',
+})
+
+function Price({ amount }: { amount: number }) {
+ return {currencyFormatter.format(amount)}
+}
+```
+
+**For dynamic locales, memoize:**
+
+```tsx
+const dateFormatter = useMemo(
+ () => new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }),
+ [locale]
+)
+```
+
+**Common formatters to hoist:**
+
+```tsx
+// Module-level formatters
+const dateFormatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' })
+const timeFormatter = new Intl.DateTimeFormat('en-US', { timeStyle: 'short' })
+const percentFormatter = new Intl.NumberFormat('en-US', { style: 'percent' })
+const relativeFormatter = new Intl.RelativeTimeFormat('en-US', {
+ numeric: 'auto',
+})
+```
+
+Creating `Intl` objects is significantly more expensive than `RegExp` or plain
+objects—each instantiation parses locale data and builds internal lookup tables.
diff --git a/skills/vercel-react-native-skills/rules/list-performance-callbacks.md b/skills/vercel-react-native-skills/rules/list-performance-callbacks.md
new file mode 100644
index 00000000..a0b3913f
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/list-performance-callbacks.md
@@ -0,0 +1,44 @@
+---
+title: Hoist callbacks to the root of lists
+impact: MEDIUM
+impactDescription: Fewer re-renders and faster lists
+tags: tag1, tag2
+---
+
+## List performance callbacks
+
+**Impact: HIGH (Fewer re-renders and faster lists)**
+
+When passing callback functions to list items, create a single instance of the
+callback at the root of the list. Items should then call it with a unique
+identifier.
+
+**Incorrect (creates a new callback on each render):**
+
+```typescript
+return (
+ {
+ // bad: creates a new callback on each render
+ const onPress = () => handlePress(item.id)
+ return (
+ {domain}
+}
+```
+
+**Updating parent array reference:**
+
+Creating a new array instance can be okay, as long as its inner object
+references are stable. For instance, if you sort a list of objects:
+
+```tsx
+// good: creates a new array instance without mutating the inner objects
+// good: parent array reference is unaffected by typing and updating "keyword"
+const sortedTlds = tlds.toSorted((a, b) => a.name.localeCompare(b.name))
+
+return {domain}
+}
+```
+
+Virtualization can now skip items that haven't changed when typing. Only visible
+items (~20) re-render on keystroke, rather than the parent.
+
+**Deriving state within list items based on parent data (avoids parent
+re-renders):**
+
+For components where the data is conditional based on the parent state, this
+pattern is even more important. For example, if you are checking if an item is
+favorited, toggling favorites only re-renders one component if the item itself
+is in charge of accessing the state rather than the parent:
+
+```tsx
+function DomainItemFavoriteButton({ tld }: { tld: Tld }) {
+ const isFavorited = useFavoritesStore((s) => s.favorites.has(tld.id))
+ return
+ {/* 4000x3000 image loaded for a 100x100 thumbnail */}
+ {product.name}
+
+ )
+}
+```
+
+**Correct (request appropriately-sized image):**
+
+```tsx
+function ProductItem({ product }: { product: Product }) {
+ // Request a 200x200 image (2x for retina)
+ const thumbnailUrl = `${product.imageUrl}?w=200&h=200&fit=cover`
+
+ return (
+
+ {product.name}
+
+ )
+}
+```
+
+Use an optimized image component with built-in caching and placeholder support,
+such as `expo-image` or `SolitoImage` (which uses `expo-image` under the hood).
+Request images at 2x the display size for retina screens.
diff --git a/skills/vercel-react-native-skills/rules/list-performance-inline-objects.md b/skills/vercel-react-native-skills/rules/list-performance-inline-objects.md
new file mode 100644
index 00000000..d5b6514a
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/list-performance-inline-objects.md
@@ -0,0 +1,97 @@
+---
+title: Avoid Inline Objects in renderItem
+impact: HIGH
+impactDescription: prevents unnecessary re-renders of memoized list items
+tags: lists, performance, flatlist, virtualization, memo
+---
+
+## Avoid Inline Objects in renderItem
+
+Don't create new objects inside `renderItem` to pass as props. Inline objects
+create new references on every render, breaking memoization. Pass primitive
+values directly from `item` instead.
+
+**Incorrect (inline object breaks memoization):**
+
+```tsx
+function UserList({ users }: { users: User[] }) {
+ return (
+ (
+ (
+ // Good: pass the item directly
+ {/* ... */}
+})
+```
+
+**Correct (hoist static styles in module scope):**
+
+```tsx
+const activeStyle = { backgroundColor: 'green' }
+const inactiveStyle = { backgroundColor: 'gray' }
+
+renderItem={({ item }) => (
+ {/* ... */}
+}
+```
+
+**Correct (lightweight list item):**
+
+```tsx
+function ProductRow({ name, price, imageUrl }: Props) {
+ // Good: receives only primitives, minimal hooks
+ return (
+
+ {name}
+ {price}
+
+ )
+}
+```
+
+**Move data fetching to parent:**
+
+```tsx
+// Parent fetches all data once
+function ProductList() {
+ const { data: products } = useQuery(['products'], fetchProducts)
+
+ return (
+ (
+ {user.name}
+})
+
+renderItem={({ item }) => {name}
+})
+
+renderItem={({ item }) => (
+ handlePress(item.id)} />
+
+// Correct: pass ID, handle in child
+{name} item.id}
+ getItemType={(item) => item.type}
+ renderItem={({ item }) => {
+ switch (item.type) {
+ case 'header':
+ return item.id}
+ getItemType={(item) => item.type}
+ getEstimatedItemSize={(index, item, itemType) => {
+ switch (itemType) {
+ case 'header':
+ return 48
+ case 'message':
+ return 72
+ case 'image':
+ return 300
+ default:
+ return 72
+ }
+ }}
+ renderItem={({ item }) => {
+ /* ... */
+ }}
+ recycleItems
+/>
+```
+
+Reference:
+[LegendList getItemType](https://legendapp.com/open-source/list/api/props/#getitemtype-v2)
diff --git a/skills/vercel-react-native-skills/rules/list-performance-virtualize.md b/skills/vercel-react-native-skills/rules/list-performance-virtualize.md
new file mode 100644
index 00000000..8a393ba1
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/list-performance-virtualize.md
@@ -0,0 +1,67 @@
+---
+title: Use a List Virtualizer for Any List
+impact: HIGH
+impactDescription: reduced memory, faster mounts
+tags: lists, performance, virtualization, scrollview
+---
+
+## Use a List Virtualizer for Any List
+
+Use a list virtualizer like LegendList or FlashList instead of ScrollView with
+mapped children—even for short lists. Virtualizers only render visible items,
+reducing memory usage and mount time. ScrollView renders all children upfront,
+which gets expensive quickly.
+
+**Incorrect (ScrollView renders all items at once):**
+
+```tsx
+function Feed({ items }: { items: Item[] }) {
+ return (
+
+ {items.map((item) => (
+
+ )
+}
+// 50 items = 50 components mounted, even if only 10 visible
+```
+
+**Correct (virtualizer renders only visible items):**
+
+```tsx
+import { LegendList } from '@legendapp/list'
+
+function Feed({ items }: { items: Item[] }) {
+ return (
+
+
+ )
+}
+```
+
+**Correct (native stack with react-navigation):**
+
+```tsx
+import { createNativeStackNavigator } from '@react-navigation/native-stack'
+
+const Stack = createNativeStackNavigator()
+
+function App() {
+ return (
+
+
+ )
+}
+```
+
+**Correct (expo-router uses native stack by default):**
+
+```tsx
+// app/_layout.tsx
+import { Stack } from 'expo-router'
+
+export default function Layout() {
+ return
+
+ )
+}
+```
+
+**Correct (native bottom tabs with react-navigation):**
+
+```tsx
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'
+
+const Tab = createNativeBottomTabNavigator()
+
+function App() {
+ return (
+
+ ({ sfSymbol: 'house' }),
+ }}
+ />
+ ({ sfSymbol: 'gear' }),
+ }}
+ />
+
+ )
+}
+```
+
+**Correct (expo-router native tabs):**
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { NativeTabs } from 'expo-router/unstable-native-tabs'
+
+export default function TabLayout() {
+ return (
+
+
+ Home
+
+
+ Settings
+
+
+ )
+}
+```
+
+On iOS, native tabs automatically enable `contentInsetAdjustmentBehavior` on the
+first `ScrollView` at the root of each tab screen, so content scrolls correctly
+behind the translucent tab bar. If you need to disable this, use
+`disableAutomaticContentInsets` on the trigger.
+
+### Prefer Native Header Options Over Custom Components
+
+**Incorrect (custom header component):**
+
+```tsx
+ (undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+ const { width, height } = e.nativeEvent.layout
+ // size may be stale in this closure
+ if (size?.width !== width || size?.height !== height) {
+ setSize({ width, height })
+ }
+}
+```
+
+**Correct (dispatch updater):**
+
+```tsx
+const [size, setSize] = useState(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+ const { width, height } = e.nativeEvent.layout
+ setSize((prev) => {
+ if (prev?.width === width && prev?.height === height) return prev
+ return { width, height }
+ })
+}
+```
+
+Returning the previous value from the updater skips the re-render.
+
+For primitive states, you don't need to compare values before firing a
+re-render.
+
+**Incorrect (unnecessary comparison for primitive state):**
+
+```tsx
+const [size, setSize] = useState(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+ const { width, height } = e.nativeEvent.layout
+ setSize((prev) => (prev === width ? prev : width))
+}
+```
+
+**Correct (sets primitive state directly):**
+
+```tsx
+const [size, setSize] = useState(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+ const { width, height } = e.nativeEvent.layout
+ setSize(width)
+}
+```
+
+However, if the next state depends on the current state, you should still use a
+dispatch updater.
+
+**Incorrect (reads state directly from the callback):**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+ setCount(count + 1)
+}
+```
+
+**Correct (dispatch updater):**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+ setCount((prev) => prev + 1)
+}
+```
diff --git a/skills/vercel-react-native-skills/rules/react-state-fallback.md b/skills/vercel-react-native-skills/rules/react-state-fallback.md
new file mode 100644
index 00000000..204f3466
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/react-state-fallback.md
@@ -0,0 +1,56 @@
+---
+title: Use fallback state instead of initialState
+impact: MEDIUM
+impactDescription: reactive fallbacks without syncing
+tags: state, hooks, derived-state, props, initialState
+---
+
+## Use fallback state instead of initialState
+
+Use `undefined` as initial state and nullish coalescing (`??`) to fall back to
+parent or server values. State represents user intent only—`undefined` means
+"user hasn't chosen yet." This enables reactive fallbacks that update when the
+source changes, not just on initial render.
+
+**Incorrect (syncs state, loses reactivity):**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+ const [enabled, setEnabled] = useState(defaultEnabled)
+ // If fallbackEnabled changes, state is stale
+ // State mixes user intent with default value
+
+ return (undefined)
+ const enabled = _enabled ?? defaultEnabled
+ // undefined = user hasn't touched it, falls back to prop
+ // If defaultEnabled changes, component reflects it
+ // Once user interacts, their choice persists
+
+ return (undefined)
+ const theme = _theme ?? data.theme
+ // Shows server value until user overrides
+ // Server refetch updates the fallback automatically
+
+ return
+ {itemCount} items
+ Total: ${total}
+
+ )
+}
+```
+
+**Correct (derived values):**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+ const total = items.reduce((sum, item) => sum + item.price, 0)
+ const itemCount = items.length
+
+ return (
+
+ {itemCount} items
+ Total: ${total}
+
+ )
+}
+```
+
+**Another example:**
+
+```tsx
+// Incorrect: storing both firstName, lastName, AND fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const [fullName, setFullName] = useState('')
+
+// Correct: derive fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const fullName = `${firstName} ${lastName}`
+```
+
+State should be the minimal source of truth. Everything else is derived.
+
+Reference: [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure)
diff --git a/skills/vercel-react-native-skills/rules/rendering-no-falsy-and.md b/skills/vercel-react-native-skills/rules/rendering-no-falsy-and.md
new file mode 100644
index 00000000..30f05d3f
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/rendering-no-falsy-and.md
@@ -0,0 +1,74 @@
+---
+title: Never Use && with Potentially Falsy Values
+impact: CRITICAL
+impactDescription: prevents production crash
+tags: rendering, conditional, jsx, crash
+---
+
+## Never Use && with Potentially Falsy Values
+
+Never use `{value && ` component, causing a hard crash in production.
+
+**Incorrect (crashes if count is 0 or name is ""):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+ return (
+
+ {name && {name} }
+ {count && {count} items }
+
+ )
+}
+// If name="" or count=0, renders the falsy value → crash
+```
+
+**Correct (ternary with null):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+ return (
+
+ {name ? {name} : null}
+ {count ? {count} items : null}
+
+ )
+}
+```
+
+**Correct (explicit boolean coercion):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+ return (
+
+ {!!name && {name} }
+ {!!count && {count} items }
+
+ )
+}
+```
+
+**Best (early return):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+ if (!name) return null
+
+ return (
+
+ {name}
+ {count > 0 ? {count} items : null}
+
+ )
+}
+```
+
+Early returns are clearest. When using conditionals inline, prefer ternary or
+explicit boolean checks.
+
+**Lint rule:** Enable `react/jsx-no-leaked-render` from
+[eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-leaked-render.md)
+to catch this automatically.
diff --git a/skills/vercel-react-native-skills/rules/rendering-text-in-text-component.md b/skills/vercel-react-native-skills/rules/rendering-text-in-text-component.md
new file mode 100644
index 00000000..fd1b9f40
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/rendering-text-in-text-component.md
@@ -0,0 +1,36 @@
+---
+title: Wrap Strings in Text Components
+impact: CRITICAL
+impactDescription: prevents runtime crash
+tags: rendering, text, core
+---
+
+## Wrap Strings in Text Components
+
+Strings must be rendered inside ``. React Native crashes if a string is a
+direct child of ``.
+
+**Incorrect (crashes):**
+
+```tsx
+import { View } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+ return Hello, {name}!
+}
+// Error: Text strings must be rendered within a component.
+```
+
+**Correct:**
+
+```tsx
+import { View, Text } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+ return (
+
+ Hello, {name}!
+
+ )
+}
+```
diff --git a/skills/vercel-react-native-skills/rules/scroll-position-no-state.md b/skills/vercel-react-native-skills/rules/scroll-position-no-state.md
new file mode 100644
index 00000000..a5760cd2
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/scroll-position-no-state.md
@@ -0,0 +1,82 @@
+---
+title: Never Track Scroll Position in useState
+impact: HIGH
+impactDescription: prevents render thrashing during scroll
+tags: scroll, performance, reanimated, useRef
+---
+
+## Never Track Scroll Position in useState
+
+Never store scroll position in `useState`. Scroll events fire rapidly—state
+updates cause render thrashing and dropped frames. Use a Reanimated shared value
+for animations or a ref for non-reactive tracking.
+
+**Incorrect (useState causes jank):**
+
+```tsx
+import { useState } from 'react'
+import {
+ ScrollView,
+ NativeSyntheticEvent,
+ NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+ const [scrollY, setScrollY] = useState(0)
+
+ const onScroll = (e: NativeSyntheticEvent) => {
+ setScrollY(e.nativeEvent.contentOffset.y) // re-renders on every frame
+ }
+
+ return ) => {
+ scrollY.current = e.nativeEvent.contentOffset.y // no re-render
+ }
+
+ return (null)
+
+ return (
+ <>
+ {urls.map((url) => (
+ setSelected(url)}>
+
+ ))}
+ setSelected(null)}>
+
+
+ )
+}
+```
+
+**Correct (Galeria with expo-image):**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function ImageGallery({ urls }: { urls: string[] }) {
+ return (
+
+ {urls.map((url, index) => (
+
+
+ ))}
+
+ )
+}
+```
+
+**Single image:**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+ return (
+
+
+
+
+ )
+}
+```
+
+**With low-res thumbnails and high-res fullscreen:**
+
+```tsx
+
+ {lowResUrls.map((url, index) => (
+
+
+ ))}
+
+```
+
+**With FlashList:**
+
+```tsx
+
+ (
+
+
+ )}
+ numColumns={3}
+ estimatedItemSize={100}
+ />
+
+```
+
+Works with `expo-image`, `SolitoImage`, `react-native` Image, or any image
+component.
+
+Reference: [Galeria](https://github.com/nandorojo/galeria)
diff --git a/skills/vercel-react-native-skills/rules/ui-measure-views.md b/skills/vercel-react-native-skills/rules/ui-measure-views.md
new file mode 100644
index 00000000..8b783fee
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-measure-views.md
@@ -0,0 +1,78 @@
+---
+title: Measuring View Dimensions
+impact: MEDIUM
+impactDescription: synchronous measurement, avoid unnecessary re-renders
+tags: layout, measurement, onLayout, useLayoutEffect
+---
+
+## Measuring View Dimensions
+
+Use both `useLayoutEffect` (synchronous) and `onLayout` (for updates). The sync
+measurement gives you the initial size immediately; `onLayout` keeps it current
+when the view changes. For non-primitive states, use a dispatch updater to
+compare values and avoid unnecessary re-renders.
+
+**Height only:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+ const ref = useRef(null)
+ const [height, setHeight] = useState(undefined)
+
+ useLayoutEffect(() => {
+ // Sync measurement on mount (RN 0.82+)
+ const rect = ref.current?.getBoundingClientRect()
+ if (rect) setHeight(rect.height)
+ // Pre-0.82: ref.current?.measure((x, y, w, h) => setHeight(h))
+ }, [])
+
+ const onLayout = (e: LayoutChangeEvent) => {
+ setHeight(e.nativeEvent.layout.height)
+ }
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+**Both dimensions:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+type Size = { width: number; height: number }
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+ const ref = useRef(null)
+ const [size, setSize] = useState(undefined)
+
+ useLayoutEffect(() => {
+ const rect = ref.current?.getBoundingClientRect()
+ if (rect) setSize({ width: rect.width, height: rect.height })
+ }, [])
+
+ const onLayout = (e: LayoutChangeEvent) => {
+ const { width, height } = e.nativeEvent.layout
+ setSize((prev) => {
+ // for non-primitive states, compare values before firing a re-render
+ if (prev?.width === width && prev?.height === height) return prev
+ return { width, height }
+ })
+ }
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+Use functional setState to compare—don't read state directly in the callback.
diff --git a/skills/vercel-react-native-skills/rules/ui-menus.md b/skills/vercel-react-native-skills/rules/ui-menus.md
new file mode 100644
index 00000000..5168bc20
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-menus.md
@@ -0,0 +1,174 @@
+---
+title: Use Native Menus for Dropdowns and Context Menus
+impact: HIGH
+impactDescription: native accessibility, platform-consistent UX
+tags: user-interface, menus, context-menus, zeego, accessibility
+---
+
+## Use Native Menus for Dropdowns and Context Menus
+
+Use native platform menus instead of custom JS implementations. Native menus
+provide built-in accessibility, consistent platform UX, and better performance.
+Use [zeego](https://zeego.dev) for cross-platform native menus.
+
+**Incorrect (custom JS menu):**
+
+```tsx
+import { useState } from 'react'
+import { View, Pressable, Text } from 'react-native'
+
+function MyMenu() {
+ const [open, setOpen] = useState(false)
+
+ return (
+
+ setOpen(!open)}>
+ Open Menu
+
+ {open && (
+
+ console.log('edit')}>
+ Edit
+
+ console.log('delete')}>
+ Delete
+
+
+ )}
+
+ )
+}
+```
+
+**Correct (native menu with zeego):**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MyMenu() {
+ return (
+
+
+
+ Open Menu
+
+
+
+
+ console.log('edit')}>
+ Edit
+
+
+ console.log('delete')}
+ >
+ Delete
+
+
+
+ )
+}
+```
+
+**Context menu (long-press):**
+
+```tsx
+import * as ContextMenu from 'zeego/context-menu'
+
+function MyContextMenu() {
+ return (
+
+
+
+ Long press me
+
+
+
+
+ console.log('copy')}>
+ Copy
+
+
+ console.log('paste')}>
+ Paste
+
+
+
+ )
+}
+```
+
+**Checkbox items:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function SettingsMenu() {
+ const [notifications, setNotifications] = useState(true)
+
+ return (
+
+
+
+ Settings
+
+
+
+
+ setNotifications((prev) => !prev)}
+ >
+ Notifications
+
+
+
+ )
+}
+```
+
+**Submenus:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MenuWithSubmenu() {
+ return (
+
+
+
+ Options
+
+
+
+
+ console.log('home')}>
+ Home
+
+
+
+
+ More Options
+
+
+
+
+ Settings
+
+
+
+ Help
+
+
+
+
+
+ )
+}
+```
+
+Reference: [Zeego Documentation](https://zeego.dev/components/dropdown-menu)
diff --git a/skills/vercel-react-native-skills/rules/ui-native-modals.md b/skills/vercel-react-native-skills/rules/ui-native-modals.md
new file mode 100644
index 00000000..f560e11e
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-native-modals.md
@@ -0,0 +1,77 @@
+---
+title: Use Native Modals Over JS-Based Bottom Sheets
+impact: HIGH
+impactDescription: native performance, gestures, accessibility
+tags: modals, bottom-sheet, native, react-navigation
+---
+
+## Use Native Modals Over JS-Based Bottom Sheets
+
+Use native `` with `presentationStyle="formSheet"` or React Navigation
+v7's native form sheet instead of JS-based bottom sheet libraries. Native modals
+have built-in gestures, accessibility, and better performance. Rely on native UI
+for low-level primitives.
+
+**Incorrect (JS-based bottom sheet):**
+
+```tsx
+import BottomSheet from 'custom-js-bottom-sheet'
+
+function MyScreen() {
+ const sheetRef = useRef(null)
+
+ return (
+
+
+ )
+}
+```
+
+**Correct (native Modal with formSheet):**
+
+```tsx
+import { Modal, View, Text, Button } from 'react-native'
+
+function MyScreen() {
+ const [visible, setVisible] = useState(false)
+
+ return (
+
+
+ )
+}
+```
+
+**Correct (React Navigation v7 native form sheet):**
+
+```tsx
+// In your navigator
+
+ Press me
+
+ )
+}
+```
+
+**Correct (Pressable):**
+
+```tsx
+import { Pressable } from 'react-native'
+
+function MyButton({ onPress }: { onPress: () => void }) {
+ return (
+
+ Press me
+
+ )
+}
+```
+
+**Correct (Pressable from gesture handler for lists):**
+
+```tsx
+import { Pressable } from 'react-native-gesture-handler'
+
+function ListItem({ onPress }: { onPress: () => void }) {
+ return (
+
+ Item
+
+ )
+}
+```
+
+Use `react-native-gesture-handler` Pressable inside scrollable lists for better
+gesture coordination, as long as you are using the ScrollView from
+`react-native-gesture-handler` as well.
+
+**For animated press states (scale, opacity changes):** Use `GestureDetector`
+with Reanimated shared values instead of Pressable's style callback. See the
+`animation-gesture-detector-press` rule.
diff --git a/skills/vercel-react-native-skills/rules/ui-safe-area-scroll.md b/skills/vercel-react-native-skills/rules/ui-safe-area-scroll.md
new file mode 100644
index 00000000..79812bc9
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-safe-area-scroll.md
@@ -0,0 +1,65 @@
+---
+title: Use contentInsetAdjustmentBehavior for Safe Areas
+impact: MEDIUM
+impactDescription: native safe area handling, no layout shifts
+tags: safe-area, scrollview, layout
+---
+
+## Use contentInsetAdjustmentBehavior for Safe Areas
+
+Use `contentInsetAdjustmentBehavior="automatic"` on the root ScrollView instead of wrapping content in SafeAreaView or manual padding. This lets iOS handle safe area insets natively with proper scroll behavior.
+
+**Incorrect (SafeAreaView wrapper):**
+
+```tsx
+import { SafeAreaView, ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+ return (
+
+
+
+ Content
+
+
+
+ )
+}
+```
+
+**Incorrect (manual safe area padding):**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+
+function MyScreen() {
+ const insets = useSafeAreaInsets()
+
+ return (
+
+
+ Content
+
+
+ )
+}
+```
+
+**Correct (native content inset adjustment):**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+ return (
+
+
+ Content
+
+
+ )
+}
+```
+
+The native approach handles dynamic safe areas (keyboard, toolbars) and allows content to scroll behind the status bar naturally.
diff --git a/skills/vercel-react-native-skills/rules/ui-scrollview-content-inset.md b/skills/vercel-react-native-skills/rules/ui-scrollview-content-inset.md
new file mode 100644
index 00000000..bbebc3b8
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-scrollview-content-inset.md
@@ -0,0 +1,45 @@
+---
+title: Use contentInset for Dynamic ScrollView Spacing
+impact: LOW
+impactDescription: smoother updates, no layout recalculation
+tags: scrollview, layout, contentInset, performance
+---
+
+## Use contentInset for Dynamic ScrollView Spacing
+
+When adding space to the top or bottom of a ScrollView that may change
+(keyboard, toolbars, dynamic content), use `contentInset` instead of padding.
+Changing `contentInset` doesn't trigger layout recalculation—it adjusts the
+scroll area without re-rendering content.
+
+**Incorrect (padding causes layout recalculation):**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+ return (
+
+ {children}
+
+ )
+}
+// Changing bottomOffset triggers full layout recalculation
+```
+
+**Correct (contentInset for dynamic spacing):**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+ return (
+
+ {children}
+
+ )
+}
+// Changing bottomOffset only adjusts scroll bounds
+```
+
+Use `scrollIndicatorInsets` alongside `contentInset` to keep the scroll
+indicator aligned. For static spacing that never changes, padding is fine.
diff --git a/skills/vercel-react-native-skills/rules/ui-styling.md b/skills/vercel-react-native-skills/rules/ui-styling.md
new file mode 100644
index 00000000..3908de3c
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-styling.md
@@ -0,0 +1,87 @@
+---
+title: Modern React Native Styling Patterns
+impact: MEDIUM
+impactDescription: consistent design, smoother borders, cleaner layouts
+tags: styling, css, layout, shadows, gradients
+---
+
+## Modern React Native Styling Patterns
+
+Follow these styling patterns for cleaner, more consistent React Native code.
+
+**Always use `borderCurve: 'continuous'` with `borderRadius`:**
+
+```tsx
+// Incorrect
+{ borderRadius: 12 }
+
+// Correct – smoother iOS-style corners
+{ borderRadius: 12, borderCurve: 'continuous' }
+```
+
+**Use `gap` instead of margin for spacing between elements:**
+
+```tsx
+// Incorrect – margin on children
+
+ Title
+ Subtitle
+
+
+// Correct – gap on parent
+
+ Title
+ Subtitle
+
+```
+
+**Use `padding` for space within, `gap` for space between:**
+
+```tsx
+
+ First
+ Second
+
+```
+
+**Use `experimental_backgroundImage` for linear gradients:**
+
+```tsx
+// Incorrect – third-party gradient library
+Title
+Subtitle
+Caption
+
+// Correct – consistent size, vary weight and color
+Title
+Subtitle
+Caption
+```
+
+Limiting font sizes creates visual consistency. Use `fontWeight` (bold/semibold)
+and grayscale colors for hierarchy instead.
diff --git a/skills/web-design-guidelines/SKILL.md b/skills/web-design-guidelines/SKILL.md
new file mode 100644
index 00000000..ceae92ab
--- /dev/null
+++ b/skills/web-design-guidelines/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+metadata:
+ author: vercel
+ version: "1.0.0"
+ argument-hint:
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.
diff --git a/src/app/api/chat/actions/parse/route.ts b/src/app/api/chat/actions/parse/route.ts
new file mode 100644
index 00000000..a9996b09
--- /dev/null
+++ b/src/app/api/chat/actions/parse/route.ts
@@ -0,0 +1,213 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth";
+import { z } from "zod";
+import { authOptions } from "@/lib/auth";
+import { getOllamaClientForUser } from "@/lib/ollama";
+import { resolveChatTenantContext } from "@/lib/chat-tenant-context";
+
+const requestSchema = z.object({
+ message: z.string().min(1).max(4000),
+ model: z.string().min(1).optional(),
+ storeId: z.string().cuid().optional(),
+});
+
+const parsedActionSchema = z.object({
+ actionType: z.enum([
+ "direct_answer",
+ "search_products",
+ "get_order_status",
+ "get_customer_info",
+ "apply_coupon",
+ "check_inventory",
+ "unknown",
+ ]),
+ confidence: z.number().min(0).max(1),
+ toolName: z
+ .enum([
+ "search_products",
+ "get_order_status",
+ "get_customer_info",
+ "apply_coupon",
+ "check_inventory",
+ ])
+ .optional(),
+ toolArgs: z.record(z.string(), z.unknown()).optional(),
+ rationale: z.string().optional(),
+});
+
+const relaxedParsedActionSchema = z.object({
+ actionType: z.string().optional(),
+ confidence: z.union([z.number(), z.string()]).optional(),
+ toolName: z.string().optional(),
+ toolArgs: z.record(z.string(), z.unknown()).optional(),
+ rationale: z.string().optional(),
+});
+
+const allowedActionTypes = new Set([
+ "direct_answer",
+ "search_products",
+ "get_order_status",
+ "get_customer_info",
+ "apply_coupon",
+ "check_inventory",
+ "unknown",
+]);
+
+function normalizeParsedAction(raw: unknown): z.infer | null {
+ const parsed = relaxedParsedActionSchema.safeParse(raw);
+ if (!parsed.success) return null;
+
+ const actionType = String(parsed.data.actionType ?? "unknown").trim().toLowerCase();
+ const confidenceRaw = parsed.data.confidence;
+ const confidenceNumeric =
+ typeof confidenceRaw === "number"
+ ? confidenceRaw
+ : Number.isFinite(Number(confidenceRaw))
+ ? Number(confidenceRaw)
+ : 0.5;
+
+ const normalized = {
+ actionType: allowedActionTypes.has(actionType) ? actionType : "unknown",
+ confidence: Math.max(0, Math.min(1, confidenceNumeric)),
+ toolName: parsed.data.toolName,
+ toolArgs: parsed.data.toolArgs,
+ rationale: parsed.data.rationale,
+ };
+
+ const strictResult = parsedActionSchema.safeParse(normalized);
+ return strictResult.success ? strictResult.data : null;
+}
+
+const outputFormat = {
+ type: "object",
+ required: ["actionType", "confidence"],
+ properties: {
+ actionType: {
+ type: "string",
+ enum: [
+ "direct_answer",
+ "search_products",
+ "get_order_status",
+ "get_customer_info",
+ "apply_coupon",
+ "check_inventory",
+ "unknown",
+ ],
+ },
+ confidence: { type: "number" },
+ toolName: {
+ type: "string",
+ enum: [
+ "search_products",
+ "get_order_status",
+ "get_customer_info",
+ "apply_coupon",
+ "check_inventory",
+ ],
+ },
+ toolArgs: {
+ type: "object",
+ additionalProperties: true,
+ },
+ rationale: {
+ type: "string",
+ },
+ },
+};
+
+function parseJsonFromModel(output: string): unknown {
+ const trimmed = output.trim();
+
+ try {
+ return JSON.parse(trimmed);
+ } catch {
+ const start = trimmed.indexOf("{");
+ const end = trimmed.lastIndexOf("}");
+ if (start >= 0 && end > start) {
+ return JSON.parse(trimmed.slice(start, end + 1));
+ }
+ throw new Error("Model response did not contain valid JSON");
+ }
+}
+
+export async function POST(request: NextRequest) {
+ if (process.env.AI_ACTIONS_ENABLED === "false") {
+ return NextResponse.json({ error: "Action parsing is disabled by configuration" }, { status: 403 });
+ }
+
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ let body: z.infer;
+ try {
+ body = requestSchema.parse(await request.json());
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ return NextResponse.json({ error: "Invalid request body", details: error.issues }, { status: 400 });
+ }
+ return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+ }
+
+ try {
+ const tenant = await resolveChatTenantContext(session, body.storeId);
+ const { client, config } = await getOllamaClientForUser(session.user.id);
+ const activeModel = body.model?.trim() || config.model;
+
+ const prompt = [
+ "You are an action parser for an e-commerce SaaS assistant.",
+ "Return ONLY strict JSON matching the provided schema.",
+ "Choose actionType=direct_answer when no clear business tool intent exists.",
+ `Current organizationId: ${tenant.organizationId}`,
+ `Current storeId: ${tenant.storeId}`,
+ `User message: ${body.message}`,
+ ].join("\n");
+
+ const result = await client.generate({
+ model: activeModel,
+ prompt,
+ stream: false,
+ format: outputFormat,
+ options: {
+ temperature: 0,
+ },
+ });
+
+ let parsedAction: z.infer;
+ try {
+ const rawParsed = parseJsonFromModel(result.response || "");
+ parsedAction =
+ parsedActionSchema.safeParse(rawParsed).success
+ ? parsedActionSchema.parse(rawParsed)
+ :
+ normalizeParsedAction(rawParsed) ?? {
+ actionType: "direct_answer",
+ confidence: 0.35,
+ rationale: "Fallback: model output required normalization",
+ };
+ } catch {
+ parsedAction = {
+ actionType: "direct_answer",
+ confidence: 0.25,
+ rationale: "Fallback: structured parse validation failed",
+ };
+ }
+
+ return NextResponse.json({
+ data: parsedAction,
+ meta: {
+ model: result.model || activeModel,
+ storeId: tenant.storeId,
+ organizationId: tenant.organizationId,
+ },
+ });
+ } catch (error) {
+ const message = error instanceof Error ? error.message : "Failed to parse action";
+ console.error("[chat/actions/parse] Error:", message);
+ return NextResponse.json(
+ { error: "Failed to parse action", details: message },
+ { status: 502 },
+ );
+ }
+}
diff --git a/src/app/api/chat/assistant/route.ts b/src/app/api/chat/assistant/route.ts
new file mode 100644
index 00000000..99a417c1
--- /dev/null
+++ b/src/app/api/chat/assistant/route.ts
@@ -0,0 +1,224 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth";
+import { z } from "zod";
+import type { Message } from "ollama";
+import { authOptions } from "@/lib/auth";
+import { getOllamaClientForUser } from "@/lib/ollama";
+import { resolveChatTenantContext } from "@/lib/chat-tenant-context";
+import {
+ assertPublicHttpsUrl,
+ executeCommerceTool,
+ getCommerceToolDefinitions,
+} from "@/lib/chat-tools";
+
+const requestSchema = z.object({
+ message: z.string().min(1).max(4000),
+ model: z.string().min(1).optional(),
+ storeId: z.string().cuid().optional(),
+ includeWebTools: z.boolean().optional().default(false),
+ maxToolCalls: z.number().int().min(1).max(5).optional().default(3),
+});
+
+export async function POST(request: NextRequest) {
+ if (process.env.AI_TOOLS_ENABLED === "false") {
+ return NextResponse.json({ error: "AI tools are disabled by configuration" }, { status: 403 });
+ }
+
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ let body: z.infer;
+ try {
+ body = requestSchema.parse(await request.json());
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ return NextResponse.json({ error: "Invalid request body", details: error.issues }, { status: 400 });
+ }
+ return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+ }
+
+ try {
+ const tenant = await resolveChatTenantContext(session, body.storeId);
+ const { client, config } = await getOllamaClientForUser(session.user.id);
+ const activeModel = body.model?.trim() || config.model;
+
+ const tools = getCommerceToolDefinitions({
+ includeWebSearch: body.includeWebTools,
+ includeWebFetch: body.includeWebTools,
+ });
+
+ const messages: Message[] = [
+ {
+ role: "system",
+ content: [
+ config.systemPrompt,
+ "You can call tools for store-specific information when needed.",
+ `Current storeId: ${tenant.storeId}`,
+ `Current organizationId: ${tenant.organizationId}`,
+ "Currency context: use Bangladeshi Taka (BDT, symbol ৳) for monetary values.",
+ "Never invent product/order/customer data when a tool can provide it.",
+ ].join("\n"),
+ },
+ {
+ role: "user",
+ content: body.message,
+ },
+ ];
+
+ const conversation: Message[] = [...messages];
+
+ let current = await client.chat({
+ model: activeModel,
+ messages: conversation,
+ stream: false,
+ tools,
+ options: {
+ temperature: config.temperature,
+ },
+ });
+
+ const executedToolCalls: NonNullable["tool_calls"]> = [];
+ const toolResults: Array<{ name: string; arguments: Record; result: unknown }> = [];
+
+ let remainingToolCalls = body.maxToolCalls;
+
+ while (remainingToolCalls > 0) {
+ const toolCalls = current.message?.tool_calls ?? [];
+ if (toolCalls.length === 0) {
+ break;
+ }
+
+ const callsToExecute = toolCalls.slice(0, remainingToolCalls);
+ remainingToolCalls -= callsToExecute.length;
+
+ if (current.message) {
+ conversation.push(current.message);
+ }
+
+ const toolMessages: Message[] = [];
+ for (const call of callsToExecute) {
+ const toolName = call.function?.name;
+ const toolArgs = call.function?.arguments ?? {};
+
+ if (!toolName) continue;
+ executedToolCalls.push(call);
+
+ let result: unknown;
+ if (toolName === "web_search") {
+ if (!body.includeWebTools) {
+ result = { ok: false, error: "Web tools are disabled for this request" };
+ } else {
+ const query = String(toolArgs.query ?? "").trim();
+ if (!query) {
+ result = { ok: false, error: "query is required" };
+ } else {
+ const maxResults = Math.min(10, Math.max(1, Number(toolArgs.maxResults ?? 5)));
+ const searchResult = await client.webSearch({ query, maxResults });
+ result = {
+ ok: true,
+ query,
+ results: searchResult.results,
+ };
+ }
+ }
+ } else if (toolName === "web_fetch") {
+ if (!body.includeWebTools) {
+ result = { ok: false, error: "Web tools are disabled for this request" };
+ } else {
+ const rawUrl = String(toolArgs.url ?? "").trim();
+ const maxChars = Math.min(30000, Math.max(500, Number(toolArgs.maxChars ?? 8000)));
+ const safeUrl = assertPublicHttpsUrl(rawUrl);
+ const fetchResult = await client.webFetch({ url: safeUrl.toString() });
+
+ result = {
+ ok: true,
+ title: fetchResult.title,
+ url: fetchResult.url,
+ content: fetchResult.content.slice(0, maxChars),
+ links: fetchResult.links.slice(0, 20),
+ };
+ }
+ } else {
+ result = await executeCommerceTool(session, tenant, toolName, toolArgs);
+ }
+
+ toolResults.push({
+ name: toolName,
+ arguments: toolArgs,
+ result,
+ });
+
+ toolMessages.push({
+ role: "tool",
+ tool_name: toolName,
+ content: JSON.stringify(result),
+ });
+ }
+
+ conversation.push(...toolMessages);
+
+ current = await client.chat({
+ model: activeModel,
+ messages: conversation,
+ stream: false,
+ tools,
+ options: {
+ temperature: config.temperature,
+ },
+ });
+ }
+
+ let finalResponse = current.message?.content?.trim() ?? "";
+ let finalThinking = current.message?.thinking ?? null;
+
+ if (!finalResponse && toolResults.length > 0) {
+ const fallback = await client.chat({
+ model: activeModel,
+ messages: [
+ ...conversation,
+ {
+ role: "user",
+ content:
+ "Provide a concise user-facing answer using the completed tool results above. Do not call more tools.",
+ },
+ ],
+ stream: false,
+ options: {
+ temperature: 0.2,
+ },
+ });
+
+ finalResponse = fallback.message?.content?.trim() ?? "";
+ finalThinking = fallback.message?.thinking ?? finalThinking;
+ current = fallback;
+ }
+
+ if (!finalResponse) {
+ finalResponse =
+ toolResults.length > 0
+ ? "I completed tool calls but could not generate a final natural-language answer."
+ : "I could not generate a response for this request.";
+ }
+
+ return NextResponse.json({
+ data: {
+ response: finalResponse,
+ thinking: finalThinking,
+ model: current.model || activeModel,
+ toolCalls: executedToolCalls,
+ toolResults,
+ },
+ });
+ } catch (error) {
+ const message = error instanceof Error ? error.message : "Failed to generate assistant response";
+ const status = message.startsWith("Access denied") ? 403 : 502;
+
+ console.error("[chat/assistant] Error:", message);
+ return NextResponse.json(
+ { error: "Failed to generate assistant response", details: message },
+ { status },
+ );
+ }
+}
diff --git a/src/app/api/chat/embed/route.ts b/src/app/api/chat/embed/route.ts
new file mode 100644
index 00000000..00736430
--- /dev/null
+++ b/src/app/api/chat/embed/route.ts
@@ -0,0 +1,108 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth";
+import { z } from "zod";
+import { authOptions } from "@/lib/auth";
+import { getOllamaClientForUser } from "@/lib/ollama";
+import { resolveChatTenantContext } from "@/lib/chat-tenant-context";
+
+const requestSchema = z.object({
+ input: z.union([z.string().min(1), z.array(z.string().min(1)).min(1).max(64)]),
+ model: z.string().min(1).optional(),
+ storeId: z.string().cuid().optional(),
+});
+
+const DEFAULT_EMBEDDING_MODELS = ["embeddinggemma", "qwen3-embedding", "nomic-embed-text", "all-minilm"];
+
+function buildEmbeddingModelCandidates(...models: Array): string[] {
+ const unique = new Set();
+
+ for (const raw of models) {
+ const model = raw?.trim();
+ if (!model) continue;
+ unique.add(model);
+ }
+
+ for (const fallback of DEFAULT_EMBEDDING_MODELS) {
+ unique.add(fallback);
+ }
+
+ return Array.from(unique);
+}
+
+export async function POST(request: NextRequest) {
+ if (process.env.AI_EMBEDDINGS_ENABLED === "false") {
+ return NextResponse.json({ error: "Embeddings are disabled by configuration" }, { status: 403 });
+ }
+
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ let body: z.infer;
+ try {
+ body = requestSchema.parse(await request.json());
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ return NextResponse.json({ error: "Invalid request body", details: error.issues }, { status: 400 });
+ }
+ return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+ }
+
+ try {
+ const tenant = await resolveChatTenantContext(session, body.storeId);
+ const { client, config } = await getOllamaClientForUser(session.user.id);
+ const candidateModels = buildEmbeddingModelCandidates(
+ body.model,
+ process.env.OLLAMA_EMBED_MODEL,
+ config.model,
+ );
+
+ let embeddings: number[][] | null = null;
+ let modelUsed: string | null = null;
+ let lastEmbeddingError: unknown = null;
+
+ for (const model of candidateModels) {
+ try {
+ const result = await client.embed({
+ model,
+ input: body.input,
+ });
+
+ embeddings = result.embeddings;
+ modelUsed = result.model || model;
+ break;
+ } catch (embeddingError) {
+ lastEmbeddingError = embeddingError;
+ }
+ }
+
+ if (!embeddings || !modelUsed) {
+ throw new Error(
+ `Embedding generation failed for models: ${candidateModels.join(", ")}. Last error: ${lastEmbeddingError instanceof Error ? lastEmbeddingError.message : String(lastEmbeddingError)}`,
+ );
+ }
+
+ return NextResponse.json({
+ data: {
+ embeddings,
+ },
+ meta: {
+ model: modelUsed,
+ strategy: "embedding",
+ dimensions: embeddings[0]?.length ?? 0,
+ total: embeddings.length,
+ attemptedModels: candidateModels,
+ storeId: tenant.storeId,
+ organizationId: tenant.organizationId,
+ },
+ });
+ } catch (error) {
+ const message = error instanceof Error ? error.message : "Failed to generate embeddings";
+ console.error("[chat/embed] Error:", message);
+ return NextResponse.json(
+ { error: "Failed to generate embeddings", details: message },
+ { status: 502 },
+ );
+ }
+}
diff --git a/src/app/api/chat/generate/route.ts b/src/app/api/chat/generate/route.ts
new file mode 100644
index 00000000..7f781b2f
--- /dev/null
+++ b/src/app/api/chat/generate/route.ts
@@ -0,0 +1,182 @@
+/**
+ * POST /api/chat/generate
+ *
+ * Single-turn generation endpoint built on Ollama's generate API.
+ * Useful for prompt completions and structured output scenarios.
+ */
+
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth/next";
+import { authOptions } from "@/lib/auth";
+import { getOllamaClientForUser } from "@/lib/ollama";
+import type {
+ ChatGenerateRequest,
+ ChatGenerateResponse,
+ ChatOutputFormat,
+ ChatThinkLevel,
+ ChatUsageMetrics,
+} from "@/lib/chat-types";
+
+const MAX_PROMPT_LENGTH = 8000;
+const THINK_LEVELS = ["low", "medium", "high"] as const;
+
+function sanitiseInput(text: string): string {
+ let result = text;
+ const tagPattern = /<[^>]*>/g;
+ let previous: string;
+ do {
+ previous = result;
+ result = result.replace(tagPattern, "");
+ } while (result !== previous);
+
+ return result
+ .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, "")
+ .trim();
+}
+
+function parseThinkValue(value: unknown, model: string): ChatThinkLevel | undefined {
+ if (value === undefined) return undefined;
+
+ const isGptOssModel = model.toLowerCase().startsWith("gpt-oss");
+
+ if (typeof value === "boolean") {
+ if (value && isGptOssModel) {
+ return "medium";
+ }
+ return value;
+ }
+
+ if (typeof value === "string" && THINK_LEVELS.includes(value as (typeof THINK_LEVELS)[number])) {
+ if (!isGptOssModel) {
+ return true;
+ }
+ return value as (typeof THINK_LEVELS)[number];
+ }
+
+ throw new Error("Invalid think value. Use boolean or one of: low, medium, high.");
+}
+
+function parseKeepAlive(value: unknown): string | number | undefined {
+ if (value === undefined) return undefined;
+
+ if (typeof value === "number") {
+ if (!Number.isFinite(value) || value < 0) {
+ throw new Error("Invalid keepAlive value. Number must be non-negative.");
+ }
+ return value;
+ }
+
+ if (typeof value === "string") {
+ const trimmed = value.trim();
+ if (trimmed.length === 0) {
+ throw new Error("Invalid keepAlive value. String must not be empty.");
+ }
+ return trimmed;
+ }
+
+ throw new Error("Invalid keepAlive value. Use string or number.");
+}
+
+function parseFormat(value: unknown): ChatOutputFormat | undefined {
+ if (value === undefined) return undefined;
+ if (value === "json") return "json";
+
+ if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+ return value as Record;
+ }
+
+ throw new Error("Invalid format value. Use 'json' or a JSON schema object.");
+}
+
+function extractUsage(payload: {
+ done_reason?: string;
+ total_duration?: number;
+ load_duration?: number;
+ prompt_eval_count?: number;
+ prompt_eval_duration?: number;
+ eval_count?: number;
+ eval_duration?: number;
+}): ChatUsageMetrics {
+ return {
+ doneReason: payload.done_reason,
+ totalDuration: payload.total_duration,
+ loadDuration: payload.load_duration,
+ promptEvalCount: payload.prompt_eval_count,
+ promptEvalDuration: payload.prompt_eval_duration,
+ evalCount: payload.eval_count,
+ evalDuration: payload.eval_duration,
+ };
+}
+
+export async function POST(request: NextRequest) {
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ let body: ChatGenerateRequest;
+ try {
+ body = await request.json();
+ } catch {
+ return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+ }
+
+ if (!body.prompt || typeof body.prompt !== "string") {
+ return NextResponse.json({ error: "Prompt is required" }, { status: 400 });
+ }
+
+ if (body.model !== undefined && (typeof body.model !== "string" || body.model.trim().length === 0)) {
+ return NextResponse.json({ error: "Model must be a non-empty string when provided" }, { status: 400 });
+ }
+
+ const prompt = sanitiseInput(body.prompt);
+ if (!prompt) {
+ return NextResponse.json({ error: "Prompt cannot be empty" }, { status: 400 });
+ }
+
+ if (prompt.length > MAX_PROMPT_LENGTH) {
+ return NextResponse.json(
+ { error: `Prompt exceeds maximum length of ${MAX_PROMPT_LENGTH} characters` },
+ { status: 400 },
+ );
+ }
+
+ try {
+ const { client, config } = await getOllamaClientForUser(session.user.id);
+ const activeModel = body.model?.trim() || config.model;
+
+ const think = parseThinkValue(body.think, activeModel);
+ const keepAlive = parseKeepAlive(body.keepAlive);
+ const format = parseFormat(body.format);
+
+ const response = await client.generate({
+ model: activeModel,
+ prompt,
+ stream: false,
+ system: body.system?.trim() || config.systemPrompt,
+ options: {
+ temperature: config.temperature,
+ },
+ ...(think !== undefined ? { think } : {}),
+ ...(keepAlive !== undefined ? { keep_alive: keepAlive } : {}),
+ ...(format !== undefined ? { format } : {}),
+ });
+
+ const result: ChatGenerateResponse = {
+ response: response.response ?? "",
+ thinking: response.thinking ?? null,
+ model: response.model || activeModel,
+ doneReason: response.done_reason,
+ usage: extractUsage(response),
+ };
+
+ return NextResponse.json(result);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : "Failed to generate response";
+ console.error("[chat/generate] Error:", message);
+ return NextResponse.json(
+ { error: "Failed to generate response", details: message },
+ { status: 502 },
+ );
+ }
+}
diff --git a/src/app/api/chat/history/route.ts b/src/app/api/chat/history/route.ts
new file mode 100644
index 00000000..3e9e20f1
--- /dev/null
+++ b/src/app/api/chat/history/route.ts
@@ -0,0 +1,62 @@
+/**
+ * GET /api/chat/history – Fetch authenticated user's chat history
+ * DELETE /api/chat/history – Clear authenticated user's chat history
+ */
+
+import { NextResponse } from "next/server";
+import { getServerSession } from "next-auth/next";
+import { authOptions } from "@/lib/auth";
+import { prisma } from "@/lib/prisma";
+
+/** Maximum messages returned per request */
+const MAX_HISTORY = 100;
+
+export async function GET() {
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ const organizationId = session.user.organizationId ?? null;
+
+ const newestMessages = await prisma.chatMessage.findMany({
+ where: {
+ userId: session.user.id,
+ organizationId,
+ },
+ orderBy: { createdAt: "desc" },
+ take: MAX_HISTORY,
+ select: {
+ id: true,
+ role: true,
+ content: true,
+ thinking: true,
+ model: true,
+ organizationId: true,
+ usage: true,
+ createdAt: true,
+ },
+ });
+
+ const messages = newestMessages.reverse();
+
+ return NextResponse.json({ messages });
+}
+
+export async function DELETE() {
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ const organizationId = session.user.organizationId ?? null;
+
+ await prisma.chatMessage.deleteMany({
+ where: {
+ userId: session.user.id,
+ organizationId,
+ },
+ });
+
+ return NextResponse.json({ success: true });
+}
diff --git a/src/app/api/chat/models/[name]/route.ts b/src/app/api/chat/models/[name]/route.ts
new file mode 100644
index 00000000..fd3d5e85
--- /dev/null
+++ b/src/app/api/chat/models/[name]/route.ts
@@ -0,0 +1,78 @@
+/**
+ * GET /api/chat/models/[name]
+ *
+ * Returns detailed information about a specific model from the user's
+ * configured Ollama instance using the SDK's show() method.
+ */
+
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth/next";
+import { authOptions } from "@/lib/auth";
+import { getOllamaClientForUser } from "@/lib/ollama";
+
+export async function GET(
+ _request: NextRequest,
+ { params }: { params: Promise<{ name: string }> },
+) {
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ const { name } = await params;
+ if (!name) {
+ return NextResponse.json({ error: "Model name is required" }, { status: 400 });
+ }
+
+ try {
+ const { client } = await getOllamaClientForUser(session.user.id);
+ const info = await client.show({ model: decodeURIComponent(name) });
+ const modelInfoRaw = info.model_info as unknown;
+ const modelInfo =
+ modelInfoRaw &&
+ typeof modelInfoRaw === "object" &&
+ "entries" in (modelInfoRaw as Record) &&
+ typeof (modelInfoRaw as { entries?: unknown }).entries === "function"
+ ? Object.fromEntries((modelInfoRaw as Map).entries())
+ : modelInfoRaw && typeof modelInfoRaw === "object"
+ ? (modelInfoRaw as Record)
+ : {};
+
+ return NextResponse.json({
+ name: decodeURIComponent(name),
+ modelfile: info.modelfile ?? "",
+ parameters: info.parameters ?? "",
+ template: info.template ?? "",
+ system: info.system ?? "",
+ license: info.license ?? "",
+ capabilities: info.capabilities ?? [],
+ modelInfo,
+ details: {
+ parentModel: info.details?.parent_model ?? "",
+ format: info.details?.format ?? "",
+ family: info.details?.family ?? "",
+ families: info.details?.families ?? [],
+ parameterSize: info.details?.parameter_size ?? "",
+ quantizationLevel: info.details?.quantization_level ?? "",
+ },
+ });
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+
+ if (/not found/i.test(message)) {
+ return NextResponse.json(
+ {
+ error: "Model not found on the currently configured Ollama host",
+ details: message,
+ },
+ { status: 404 },
+ );
+ }
+
+ console.error(`[chat/models/${name}] Error:`, message);
+ return NextResponse.json(
+ { error: "Failed to fetch model details", details: message },
+ { status: 502 },
+ );
+ }
+}
diff --git a/src/app/api/chat/models/manage/route.ts b/src/app/api/chat/models/manage/route.ts
new file mode 100644
index 00000000..cec15f55
--- /dev/null
+++ b/src/app/api/chat/models/manage/route.ts
@@ -0,0 +1,119 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth/next";
+import { z } from "zod";
+import { authOptions } from "@/lib/auth";
+import { getOllamaClientForUser } from "@/lib/ollama";
+
+const requestSchema = z
+ .object({
+ action: z.enum(["pull", "copy", "delete"]),
+ model: z.string().min(1).optional(),
+ source: z.string().min(1).optional(),
+ destination: z.string().min(1).optional(),
+ })
+ .superRefine((value, ctx) => {
+ if (value.action === "pull" || value.action === "delete") {
+ if (!value.model?.trim()) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "model is required",
+ path: ["model"],
+ });
+ }
+ }
+
+ if (value.action === "copy") {
+ if (!value.source?.trim()) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "source is required for copy action",
+ path: ["source"],
+ });
+ }
+
+ if (!value.destination?.trim()) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "destination is required for copy action",
+ path: ["destination"],
+ });
+ }
+ }
+ });
+
+export async function POST(request: NextRequest) {
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ let body: z.infer;
+ try {
+ body = requestSchema.parse(await request.json());
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ return NextResponse.json({ error: "Invalid request body", details: error.issues }, { status: 400 });
+ }
+ return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+ }
+
+ try {
+ const { client } = await getOllamaClientForUser(session.user.id);
+
+ switch (body.action) {
+ case "pull": {
+ const model = body.model!.trim();
+ const pullResult = await client.pull({ model, stream: false });
+ return NextResponse.json({
+ data: {
+ action: "pull",
+ model,
+ result: pullResult,
+ },
+ });
+ }
+
+ case "copy": {
+ const source = body.source!.trim();
+ const destination = body.destination!.trim();
+ await client.copy({ source, destination });
+
+ return NextResponse.json({
+ data: {
+ action: "copy",
+ source,
+ destination,
+ message: "Model copied successfully",
+ },
+ });
+ }
+
+ case "delete": {
+ const model = body.model!.trim();
+ await client.delete({ model });
+
+ return NextResponse.json({
+ data: {
+ action: "delete",
+ model,
+ message: "Model deleted successfully",
+ },
+ });
+ }
+
+ default:
+ return NextResponse.json({ error: "Unsupported action" }, { status: 400 });
+ }
+ } catch (error) {
+ const message = error instanceof Error ? error.message : "Model management action failed";
+ console.error("[chat/models/manage] Error:", message);
+
+ return NextResponse.json(
+ {
+ error: "Failed to manage model",
+ details: message,
+ },
+ { status: 502 },
+ );
+ }
+}
diff --git a/src/app/api/chat/models/route.ts b/src/app/api/chat/models/route.ts
new file mode 100644
index 00000000..932e0f11
--- /dev/null
+++ b/src/app/api/chat/models/route.ts
@@ -0,0 +1,48 @@
+/**
+ * GET /api/chat/models
+ *
+ * Returns the list of available models from the user's configured Ollama
+ * instance (Cloud or local). Requires authentication.
+ */
+
+import { NextResponse } from "next/server";
+import { getServerSession } from "next-auth/next";
+import { authOptions } from "@/lib/auth";
+import { getOllamaClientForUser } from "@/lib/ollama";
+import type { OllamaModelInfo } from "@/lib/chat-types";
+
+export async function GET() {
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ try {
+ const { client, config } = await getOllamaClientForUser(session.user.id);
+ const listResponse = await client.list();
+
+ const models: OllamaModelInfo[] = (listResponse.models ?? []).map((m) => ({
+ name: m.name,
+ model: m.model,
+ size: m.size,
+ digest: m.digest,
+ modifiedAt: m.modified_at.toString(),
+ }));
+
+ return NextResponse.json({
+ models,
+ currentModel: config.model,
+ isCloudMode: config.isCloudMode,
+ });
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ console.error("[chat/models] Error listing models:", message);
+ return NextResponse.json(
+ {
+ error: "Failed to fetch models. Check your Ollama configuration.",
+ details: message,
+ },
+ { status: 502 },
+ );
+ }
+}
diff --git a/src/app/api/chat/ollama/route.ts b/src/app/api/chat/ollama/route.ts
new file mode 100644
index 00000000..de12886e
--- /dev/null
+++ b/src/app/api/chat/ollama/route.ts
@@ -0,0 +1,997 @@
+/**
+ * POST /api/chat/ollama
+ *
+ * Authenticated API route that sends chat messages to a configured Ollama
+ * instance (Cloud or local) via the official `ollama` SDK. Streams the LLM
+ * response back to the client and persists both user and assistant messages
+ * in the database.
+ *
+ * Configuration priority: DB (OllamaConfig per user) → env vars → defaults.
+ */
+
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth/next";
+import type { ChatResponse, Message } from "ollama";
+import { Prisma } from "@prisma/client";
+import { authOptions } from "@/lib/auth";
+import { prisma } from "@/lib/prisma";
+import { getOllamaClientForUser } from "@/lib/ollama";
+import { resolveChatTenantContext } from "@/lib/chat-tenant-context";
+import { executeCommerceTool, getCommerceToolDefinitions } from "@/lib/chat-tools";
+import type {
+ ChatAttachmentData,
+ ChatOutputFormat,
+ ChatRequestExtended,
+ ChatThinkLevel,
+ ChatUsageMetrics,
+} from "@/lib/chat-types";
+
+/** Maximum allowed message length (characters) */
+const MAX_MESSAGE_LENGTH = 4000;
+
+/** Number of recent messages to include as conversation context */
+const CONTEXT_MESSAGE_COUNT = 20;
+
+const THINK_LEVELS = ["low", "medium", "high"] as const;
+
+const MAX_ATTACHMENTS = 8;
+const MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024;
+const MAX_TOTAL_ATTACHMENT_BYTES = 24 * 1024 * 1024;
+const MAX_ATTACHMENT_TEXT_CHARS_PER_FILE = 6000;
+const MAX_ATTACHMENT_TEXT_CHARS_TOTAL = 20000;
+
+const MAX_TOOL_CALLS = 4;
+const STORE_DATA_INTENT_PATTERN =
+ /\b(my store|our store|inventory|stock|order\s*(status|number|id)?|customer|coupon|discount|sku|product\s*(id|inventory|stock)?|in this store)\b/i;
+
+const TEXT_MIME_PREFIXES = ["text/"];
+const TEXT_MIME_TYPES = new Set([
+ "application/json",
+ "application/xml",
+ "application/x-yaml",
+ "application/yaml",
+ "application/javascript",
+ "application/typescript",
+]);
+const TEXT_FILE_EXTENSIONS = [
+ ".txt",
+ ".md",
+ ".markdown",
+ ".csv",
+ ".json",
+ ".xml",
+ ".html",
+ ".htm",
+ ".yaml",
+ ".yml",
+ ".log",
+ ".ts",
+ ".tsx",
+ ".js",
+ ".jsx",
+ ".py",
+ ".sql",
+];
+
+interface ParsedAttachment {
+ metadata: ChatAttachmentData;
+ imageBase64?: string;
+ textExtract?: string;
+}
+
+interface ParsedChatPayload {
+ message: string;
+ model?: string;
+ think?: unknown;
+ keepAlive?: unknown;
+ format?: unknown;
+ attachments: ParsedAttachment[];
+}
+
+/**
+ * Strip HTML tags and dangerous patterns from user input.
+ * Applies the tag-stripping regex repeatedly to eliminate nested / split tags
+ * (e.g. `ipt>`) that a single pass would miss.
+ */
+function sanitiseInput(text: string): string {
+ let result = text;
+ const tagPattern = /<[^>]*>/g;
+ // Repeat until no more tags can be found (handles nested fragments)
+ let previous: string;
+ do {
+ previous = result;
+ result = result.replace(tagPattern, "");
+ } while (result !== previous);
+
+ return result
+ .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, "") // strip control chars
+ .trim();
+}
+
+function parseThinkValue(value: unknown, model: string): ChatThinkLevel | undefined {
+ if (value === undefined) return undefined;
+
+ const isGptOssModel = model.toLowerCase().startsWith("gpt-oss");
+
+ if (typeof value === "boolean") {
+ // gpt-oss uses level-based thinking; map boolean true to medium by default
+ if (value && isGptOssModel) {
+ return "medium";
+ }
+ return value;
+ }
+
+ if (typeof value === "string" && THINK_LEVELS.includes(value as (typeof THINK_LEVELS)[number])) {
+ if (!isGptOssModel) {
+ return true;
+ }
+ return value as (typeof THINK_LEVELS)[number];
+ }
+
+ throw new Error("Invalid think value. Use boolean or one of: low, medium, high.");
+}
+
+function parseKeepAlive(value: unknown): string | number | undefined {
+ if (value === undefined) return undefined;
+
+ if (typeof value === "number") {
+ if (!Number.isFinite(value) || value < 0) {
+ throw new Error("Invalid keepAlive value. Number must be non-negative.");
+ }
+ return value;
+ }
+
+ if (typeof value === "string") {
+ const trimmed = value.trim();
+ if (trimmed.length === 0) {
+ throw new Error("Invalid keepAlive value. String must not be empty.");
+ }
+ return trimmed;
+ }
+
+ throw new Error("Invalid keepAlive value. Use string or number.");
+}
+
+function parseFormat(value: unknown): ChatOutputFormat | undefined {
+ if (value === undefined) return undefined;
+ if (value === "json") return "json";
+
+ if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+ return value as Record;
+ }
+
+ throw new Error("Invalid format value. Use 'json' or a JSON schema object.");
+}
+
+function parseBooleanLike(value: unknown): boolean | undefined {
+ if (typeof value === "boolean") return value;
+ if (typeof value !== "string") return undefined;
+
+ const normalized = value.trim().toLowerCase();
+ if (normalized === "true") return true;
+ if (normalized === "false") return false;
+
+ return undefined;
+}
+
+function parseKeepAliveValue(value: unknown): string | number | undefined {
+ if (typeof value === "number") return value;
+ if (typeof value !== "string") return undefined;
+
+ const trimmed = value.trim();
+ if (!trimmed) return undefined;
+
+ const asNumber = Number(trimmed);
+ if (Number.isFinite(asNumber) && String(asNumber) === trimmed) {
+ return asNumber;
+ }
+
+ return trimmed;
+}
+
+function parseFormatString(value: string): ChatOutputFormat | undefined {
+ const trimmed = value.trim();
+ if (!trimmed) return undefined;
+ if (trimmed === "json") return "json";
+
+ try {
+ const parsed = JSON.parse(trimmed);
+ if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+ return parsed as Record;
+ }
+ } catch {
+ // ignore invalid JSON and fallback to undefined
+ }
+
+ return undefined;
+}
+
+function sanitizeFilename(name: string): string {
+ const normalized = name.replace(/\s+/g, " ").trim();
+ return normalized.replace(/[^\w .@()\-\[\]]/g, "_").slice(0, 120) || "attachment";
+}
+
+function isTextLikeFile(file: File): boolean {
+ const mime = (file.type || "").toLowerCase();
+ if (TEXT_MIME_TYPES.has(mime)) return true;
+ if (TEXT_MIME_PREFIXES.some((prefix) => mime.startsWith(prefix))) return true;
+
+ const lowerName = file.name.toLowerCase();
+ return TEXT_FILE_EXTENSIONS.some((extension) => lowerName.endsWith(extension));
+}
+
+async function parseUploadedAttachments(formData: FormData): Promise {
+ const files = formData
+ .getAll("files")
+ .filter((value): value is File => value instanceof File);
+
+ if (files.length === 0) return [];
+
+ if (files.length > MAX_ATTACHMENTS) {
+ throw new Error(`A maximum of ${MAX_ATTACHMENTS} files can be uploaded at once.`);
+ }
+
+ let totalBytes = 0;
+ let totalExtractedChars = 0;
+ const attachments: ParsedAttachment[] = [];
+
+ for (const file of files) {
+ const safeName = sanitizeFilename(file.name);
+ const type = file.type || "application/octet-stream";
+ const isImage = type.startsWith("image/");
+
+ if (file.size <= 0) {
+ continue;
+ }
+
+ if (file.size > MAX_ATTACHMENT_BYTES) {
+ throw new Error(`File too large: ${safeName}. Max allowed is ${MAX_ATTACHMENT_BYTES / (1024 * 1024)}MB.`);
+ }
+
+ totalBytes += file.size;
+ if (totalBytes > MAX_TOTAL_ATTACHMENT_BYTES) {
+ throw new Error(
+ `Total uploaded file size exceeds ${MAX_TOTAL_ATTACHMENT_BYTES / (1024 * 1024)}MB.`,
+ );
+ }
+
+ const metadata: ChatAttachmentData = {
+ id: `att-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
+ name: safeName,
+ size: file.size,
+ type,
+ isImage,
+ source: "upload",
+ };
+
+ const attachment: ParsedAttachment = { metadata };
+
+ if (isImage) {
+ const bytes = Buffer.from(await file.arrayBuffer());
+ attachment.imageBase64 = bytes.toString("base64");
+ } else if (isTextLikeFile(file)) {
+ const rawText = await file.text();
+ if (rawText.trim().length > 0 && totalExtractedChars < MAX_ATTACHMENT_TEXT_CHARS_TOTAL) {
+ const remaining = MAX_ATTACHMENT_TEXT_CHARS_TOTAL - totalExtractedChars;
+ const extract = sanitiseInput(rawText)
+ .slice(0, Math.min(MAX_ATTACHMENT_TEXT_CHARS_PER_FILE, remaining))
+ .trim();
+
+ if (extract) {
+ attachment.textExtract = extract;
+ totalExtractedChars += extract.length;
+ }
+ }
+ }
+
+ attachments.push(attachment);
+ }
+
+ return attachments;
+}
+
+function buildStorageMessageContent(message: string, attachments: ParsedAttachment[]): string {
+ const base = message.trim() || "(Sent attachments for analysis)";
+ if (attachments.length === 0) return base;
+
+ const summary = attachments
+ .map((attachment) => `${attachment.metadata.name} (${attachment.metadata.type}, ${attachment.metadata.size} bytes)`)
+ .join(", ");
+
+ return `${base}\n\n[Attachments: ${summary}]`;
+}
+
+function buildModelAttachmentContext(attachments: ParsedAttachment[]): string {
+ if (attachments.length === 0) return "";
+
+ const lines: string[] = [
+ "Attached file context (use this for grounded responses):",
+ ...attachments.map((attachment) => {
+ const { name, type, size, isImage } = attachment.metadata;
+ return `- ${name} (${type}, ${size} bytes${isImage ? ", image" : ""})`;
+ }),
+ ];
+
+ const textAttachments = attachments.filter((attachment) => attachment.textExtract);
+ if (textAttachments.length > 0) {
+ lines.push("", "Extracted text snippets from uploaded files:");
+ for (const attachment of textAttachments) {
+ lines.push(`\n[${attachment.metadata.name}]\n${attachment.textExtract}`);
+ }
+ }
+
+ const unsupported = attachments.filter(
+ (attachment) => !attachment.metadata.isImage && !attachment.textExtract,
+ );
+ if (unsupported.length > 0) {
+ lines.push(
+ "",
+ "Some files are non-text and were included as metadata only. If needed, ask the user to provide text extracts.",
+ );
+ }
+
+ return lines.join("\n").trim();
+}
+
+async function parseIncomingPayload(request: NextRequest): Promise {
+ const contentType = request.headers.get("content-type") || "";
+
+ if (contentType.includes("multipart/form-data")) {
+ const formData = await request.formData();
+ const attachments = await parseUploadedAttachments(formData);
+
+ const message = String(formData.get("message") || "");
+ const model = typeof formData.get("model") === "string" ? String(formData.get("model")) : undefined;
+ const thinkRaw = typeof formData.get("think") === "string" ? String(formData.get("think")) : undefined;
+ const keepAliveRaw =
+ typeof formData.get("keepAlive") === "string" ? String(formData.get("keepAlive")) : undefined;
+ const formatRaw =
+ typeof formData.get("format") === "string" ? String(formData.get("format")) : undefined;
+
+ return {
+ message,
+ model,
+ think: parseBooleanLike(thinkRaw) ?? thinkRaw,
+ keepAlive: parseKeepAliveValue(keepAliveRaw),
+ format: formatRaw ? parseFormatString(formatRaw) : undefined,
+ attachments,
+ };
+ }
+
+ const jsonBody = (await request.json()) as ChatRequestExtended;
+ return {
+ ...jsonBody,
+ message: String(jsonBody.message || ""),
+ attachments: [],
+ };
+}
+
+function extractUsage(part: ChatResponse): ChatUsageMetrics {
+ return {
+ doneReason: part.done_reason,
+ totalDuration: part.total_duration,
+ loadDuration: part.load_duration,
+ promptEvalCount: part.prompt_eval_count,
+ promptEvalDuration: part.prompt_eval_duration,
+ evalCount: part.eval_count,
+ evalDuration: part.eval_duration,
+ };
+}
+
+function tryParseJsonObject(text: string): Record | null {
+ const trimmed = text.trim();
+ if (!trimmed) return null;
+
+ const candidates = [trimmed];
+ const fenceMatch = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+ if (fenceMatch?.[1]) {
+ candidates.push(fenceMatch[1].trim());
+ }
+
+ for (const candidate of candidates) {
+ try {
+ const parsed = JSON.parse(candidate);
+ if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+ return parsed as Record;
+ }
+ } catch {
+ // continue trying candidates
+ }
+ }
+
+ return null;
+}
+
+function getSchemaRequiredKeys(format: ChatOutputFormat): string[] {
+ if (format === "json") return [];
+
+ const maybeRequired = format.required;
+ if (!Array.isArray(maybeRequired)) return [];
+
+ return maybeRequired.filter((key): key is string => typeof key === "string");
+}
+
+function ensureRequiredKeys(params: {
+ parsed: Record;
+ requiredKeys: string[];
+ rawContent: string;
+}): Record {
+ if (params.requiredKeys.length === 0) return params.parsed;
+
+ const enriched: Record = { ...params.parsed };
+ for (const key of params.requiredKeys) {
+ if (enriched[key] !== undefined) continue;
+
+ if (key === "answer") {
+ enriched[key] =
+ typeof params.parsed.title === "string"
+ ? params.parsed.title
+ : params.rawContent.slice(0, 300) || "No answer provided.";
+ continue;
+ }
+
+ if (key === "confidence") {
+ enriched[key] =
+ typeof params.parsed.score === "number"
+ ? params.parsed.score
+ : typeof params.parsed.confidence === "number"
+ ? params.parsed.confidence
+ : 0.5;
+ continue;
+ }
+
+ enriched[key] = null;
+ }
+
+ return enriched;
+}
+
+async function ensureStructuredContent(params: {
+ ollamaClient: Awaited>["client"];
+ model: string;
+ format: ChatOutputFormat;
+ content: string;
+}): Promise {
+ const requiredKeys = getSchemaRequiredKeys(params.format);
+
+ const parsedInitial = tryParseJsonObject(params.content);
+ if (parsedInitial) {
+ const withRequired = ensureRequiredKeys({
+ parsed: parsedInitial,
+ requiredKeys,
+ rawContent: params.content,
+ });
+ return JSON.stringify(withRequired, null, 2);
+ }
+
+ try {
+ const repairResponse = await params.ollamaClient.chat({
+ model: params.model,
+ stream: false,
+ messages: [
+ {
+ role: "system",
+ content:
+ "You are a JSON formatter. Return ONLY valid JSON with no markdown fences, no prose, and no extra keys unless required by schema.",
+ },
+ {
+ role: "user",
+ content:
+ params.format === "json"
+ ? `Convert the following content into a valid JSON object:\n\n${params.content}`
+ : `Convert the following content into JSON that conforms to this schema:\n${JSON.stringify(params.format)}\n\nContent:\n${params.content}`,
+ },
+ ],
+ options: {
+ temperature: 0,
+ },
+ ...(params.format === "json" ? { format: "json" as const } : { format: params.format }),
+ });
+
+ const repairedText = repairResponse.message?.content ?? params.content;
+ const parsedRepaired = tryParseJsonObject(repairedText);
+ if (parsedRepaired) {
+ const withRequired = ensureRequiredKeys({
+ parsed: parsedRepaired,
+ requiredKeys,
+ rawContent: params.content,
+ });
+ return JSON.stringify(withRequired, null, 2);
+ }
+ } catch {
+ // fall through to raw content
+ }
+
+ return params.content;
+}
+
+function shouldUseToolAssistance(message: string, hasAttachments: boolean): boolean {
+ if (hasAttachments) return false;
+ if (process.env.AI_TOOLS_ENABLED === "false") return false;
+ return STORE_DATA_INTENT_PATTERN.test(message);
+}
+
+function splitIntoStreamChunks(text: string, maxChunkLength = 120): string[] {
+ if (text.length <= maxChunkLength) return [text];
+
+ const words = text.split(/(\s+)/);
+ const chunks: string[] = [];
+ let current = "";
+
+ for (const piece of words) {
+ if (!piece) continue;
+
+ if ((current + piece).length > maxChunkLength && current.length > 0) {
+ chunks.push(current);
+ current = piece;
+ } else {
+ current += piece;
+ }
+ }
+
+ if (current) chunks.push(current);
+ return chunks;
+}
+
+const VISION_MODEL_HINTS = [
+ "gemma3",
+ "llava",
+ "bakllava",
+ "moondream",
+ "qwen3-vl",
+ "minicpm-v",
+ "vision",
+];
+
+function isLikelyVisionModel(modelName: string): boolean {
+ const normalized = modelName.toLowerCase();
+ return VISION_MODEL_HINTS.some((hint) => normalized.includes(hint));
+}
+
+async function resolveVisionCapableModel(params: {
+ ollamaClient: Awaited>["client"];
+ preferredModel: string;
+}): Promise {
+ if (isLikelyVisionModel(params.preferredModel)) {
+ return params.preferredModel;
+ }
+
+ try {
+ const listed = await params.ollamaClient.list();
+ const available = listed.models ?? [];
+
+ const candidate = available.find((model) => {
+ const byName = typeof model.name === "string" ? model.name : "";
+ const byModel = typeof model.model === "string" ? model.model : "";
+ return isLikelyVisionModel(byName) || isLikelyVisionModel(byModel);
+ });
+
+ return candidate?.name || candidate?.model || params.preferredModel;
+ } catch {
+ return params.preferredModel;
+ }
+}
+
+async function generateToolAssistedResponse(params: {
+ ollamaClient: Awaited>["client"];
+ session: Parameters[0];
+ tenant: { storeId: string; organizationId: string };
+ activeModel: string;
+ temperature: number;
+ messages: Message[];
+}): Promise<{ response: string; thinking: string; usage: ChatUsageMetrics | null }> {
+ const tools = getCommerceToolDefinitions({ includeWebSearch: false, includeWebFetch: false });
+
+ const conversation: Message[] = [
+ {
+ role: "system",
+ content: [
+ "You have access to secure commerce tools scoped to the active tenant.",
+ `Current storeId: ${params.tenant.storeId}`,
+ `Current organizationId: ${params.tenant.organizationId}`,
+ "For store-specific data requests (orders, products, inventory, customers, coupons), call tools.",
+ "Currency context: use Bangladeshi Taka (BDT, symbol ৳) for monetary values.",
+ "Never claim you cannot access data when a relevant tool can be used.",
+ ].join("\n"),
+ },
+ ...params.messages,
+ ];
+
+ let current = await params.ollamaClient.chat({
+ model: params.activeModel,
+ messages: conversation,
+ stream: false,
+ tools,
+ options: {
+ temperature: params.temperature,
+ },
+ });
+
+ let remainingToolCalls = MAX_TOOL_CALLS;
+ let finalUsage = extractUsage(current);
+
+ while (remainingToolCalls > 0) {
+ const toolCalls = current.message?.tool_calls ?? [];
+ if (toolCalls.length === 0) break;
+
+ const callsToExecute = toolCalls.slice(0, remainingToolCalls);
+ remainingToolCalls -= callsToExecute.length;
+
+ if (current.message) {
+ conversation.push(current.message);
+ }
+
+ const toolMessages: Message[] = [];
+ for (const call of callsToExecute) {
+ const toolName = call.function?.name;
+ const toolArgs =
+ call.function?.arguments && typeof call.function.arguments === "object"
+ ? (call.function.arguments as Record)
+ : {};
+
+ if (!toolName) continue;
+
+ let result: Record;
+ try {
+ result = await executeCommerceTool(params.session, params.tenant, toolName, toolArgs);
+ } catch (toolError) {
+ result = {
+ ok: false,
+ error: toolError instanceof Error ? toolError.message : "Tool execution failed",
+ };
+ }
+
+ toolMessages.push({
+ role: "tool",
+ tool_name: toolName,
+ content: JSON.stringify(result),
+ });
+ }
+
+ if (toolMessages.length === 0) break;
+ conversation.push(...toolMessages);
+
+ current = await params.ollamaClient.chat({
+ model: params.activeModel,
+ messages: conversation,
+ stream: false,
+ tools,
+ options: {
+ temperature: params.temperature,
+ },
+ });
+ finalUsage = extractUsage(current);
+ }
+
+ let finalResponse = current.message?.content?.trim() ?? "";
+ let finalThinking = current.message?.thinking ?? "";
+
+ if (!finalResponse) {
+ const fallback = await params.ollamaClient.chat({
+ model: params.activeModel,
+ messages: [
+ ...conversation,
+ {
+ role: "user",
+ content: "Provide a concise final answer for the user using available tool results. Do not call more tools.",
+ },
+ ],
+ stream: false,
+ options: {
+ temperature: 0.2,
+ },
+ });
+
+ finalResponse = fallback.message?.content?.trim() ?? "";
+ finalThinking = fallback.message?.thinking ?? finalThinking;
+ finalUsage = extractUsage(fallback);
+ }
+
+ if (!finalResponse) {
+ finalResponse = "I could not produce a response for this request.";
+ }
+
+ return {
+ response: finalResponse,
+ thinking: finalThinking,
+ usage: finalUsage,
+ };
+}
+
+export async function POST(request: NextRequest) {
+ // ── Auth ──────────────────────────────────────────────────────────────
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+ const userId = session.user.id;
+
+ // ── Parse & validate ──────────────────────────────────────────────────
+ let body: ParsedChatPayload;
+ try {
+ body = await parseIncomingPayload(request);
+ } catch (error) {
+ return NextResponse.json(
+ {
+ error: "Invalid request body",
+ details: error instanceof Error ? error.message : "Unsupported payload",
+ },
+ { status: 400 },
+ );
+ }
+
+ if (body.model !== undefined && (typeof body.model !== "string" || body.model.trim().length === 0)) {
+ return NextResponse.json(
+ { error: "Model must be a non-empty string when provided" },
+ { status: 400 },
+ );
+ }
+
+ if (body.message === undefined || typeof body.message !== "string") {
+ return NextResponse.json({ error: "Message is required" }, { status: 400 });
+ }
+
+ const userMessage = sanitiseInput(body.message);
+ const hasAttachments = body.attachments.length > 0;
+
+ if (userMessage.length === 0 && !hasAttachments) {
+ return NextResponse.json({ error: "Message cannot be empty" }, { status: 400 });
+ }
+
+ if (userMessage.length > MAX_MESSAGE_LENGTH) {
+ return NextResponse.json(
+ { error: `Message exceeds maximum length of ${MAX_MESSAGE_LENGTH} characters` },
+ { status: 400 },
+ );
+ }
+
+ // ── Resolve Ollama config (DB → env → defaults) ──────────────────────
+ let ollamaClient;
+ let ollamaConfig;
+ try {
+ const resolved = await getOllamaClientForUser(userId);
+ ollamaClient = resolved.client;
+ ollamaConfig = resolved.config;
+ } catch (err) {
+ console.error("[chat/ollama] Config resolution error:", err);
+ return NextResponse.json(
+ { error: "Failed to load AI configuration. Check your settings." },
+ { status: 500 },
+ );
+ }
+
+ const imageAttachments = body.attachments
+ .filter((attachment) => attachment.metadata.isImage && attachment.imageBase64)
+ .map((attachment) => attachment.imageBase64 as string);
+
+ // Allow per-message model override from the request body
+ let activeModel = body.model?.trim() || ollamaConfig.model;
+ if (imageAttachments.length > 0) {
+ activeModel = await resolveVisionCapableModel({
+ ollamaClient,
+ preferredModel: activeModel,
+ });
+ }
+
+ const organizationId = session.user.organizationId ?? null;
+ const wantsToolAssistance = shouldUseToolAssistance(userMessage, hasAttachments);
+
+ let toolTenantContext: { storeId: string; organizationId: string } | null = null;
+ if (wantsToolAssistance) {
+ try {
+ const resolvedTenant = await resolveChatTenantContext(session);
+ toolTenantContext = {
+ storeId: resolvedTenant.storeId,
+ organizationId: resolvedTenant.organizationId,
+ };
+ } catch (toolContextError) {
+ console.warn(
+ "[chat/ollama] Could not resolve tenant context for tool-assisted response, falling back to standard chat:",
+ toolContextError instanceof Error ? toolContextError.message : String(toolContextError),
+ );
+ }
+ }
+
+ let think: ChatThinkLevel | undefined;
+ let keepAlive: string | number | undefined;
+ let format: ChatOutputFormat | undefined;
+
+ try {
+ think = parseThinkValue(body.think, activeModel);
+ keepAlive = parseKeepAlive(body.keepAlive);
+ format = parseFormat(body.format);
+ } catch (err) {
+ return NextResponse.json(
+ { error: err instanceof Error ? err.message : "Invalid request options" },
+ { status: 400 },
+ );
+ }
+
+ // ── Build conversation context ────────────────────────────────────────
+ const recentMessages = await prisma.chatMessage.findMany({
+ where: { userId, organizationId },
+ orderBy: { createdAt: "desc" },
+ take: CONTEXT_MESSAGE_COUNT,
+ select: { role: true, content: true },
+ });
+
+ const storageMessage = buildStorageMessageContent(userMessage, body.attachments);
+ const attachmentContext = buildModelAttachmentContext(body.attachments);
+ const modelUserMessage =
+ attachmentContext.length > 0
+ ? `${userMessage.trim() || "Analyze the attached files."}\n\n${attachmentContext}`
+ : userMessage;
+
+ // ── Persist current user message ─────────────────────────────────────
+ await prisma.chatMessage.create({
+ data: {
+ userId,
+ organizationId,
+ role: "USER",
+ content: storageMessage,
+ model: activeModel,
+ },
+ });
+
+ const messages: Message[] = [
+ { role: "system", content: ollamaConfig.systemPrompt },
+ ...recentMessages.reverse().map((m) => ({
+ role: (m.role === "USER" ? "user" : "assistant") as "user" | "assistant",
+ content: m.content,
+ })),
+ {
+ role: "user",
+ content: modelUserMessage,
+ ...(imageAttachments.length > 0 ? { images: imageAttachments } : {}),
+ },
+ ];
+
+ // ── Call Ollama via SDK (streaming) ───────────────────────────────────
+ let fullAssistantResponse = "";
+ let fullAssistantThinking = "";
+ let usageMetrics: ChatUsageMetrics | null = null;
+
+ const stream = new ReadableStream({
+ async start(controller) {
+ const encoder = new TextEncoder();
+ const writeEvent = (event: Record) => {
+ controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
+ };
+
+ try {
+ if (toolTenantContext) {
+ const toolAssisted = await generateToolAssistedResponse({
+ ollamaClient,
+ session: session as Parameters[0],
+ tenant: toolTenantContext,
+ activeModel,
+ temperature: ollamaConfig.temperature,
+ messages,
+ });
+
+ fullAssistantResponse = toolAssisted.response;
+ fullAssistantThinking = toolAssisted.thinking;
+ usageMetrics = toolAssisted.usage;
+
+ if (fullAssistantThinking) {
+ for (const token of splitIntoStreamChunks(fullAssistantThinking, 180)) {
+ writeEvent({ type: "thinking", token });
+ }
+ }
+
+ for (const token of splitIntoStreamChunks(fullAssistantResponse)) {
+ writeEvent({ type: "content", token });
+ }
+
+ writeEvent({ type: "done", usage: usageMetrics });
+ return;
+ }
+
+ if (format !== undefined) {
+ const structuredResponse = await ollamaClient.chat({
+ model: activeModel,
+ messages,
+ stream: false,
+ options: {
+ temperature: ollamaConfig.temperature,
+ },
+ ...(think !== undefined ? { think } : {}),
+ ...(keepAlive !== undefined ? { keep_alive: keepAlive } : {}),
+ ...(format !== undefined ? { format } : {}),
+ });
+
+ fullAssistantThinking = structuredResponse.message?.thinking ?? "";
+ fullAssistantResponse = structuredResponse.message?.content ?? "";
+ fullAssistantResponse = await ensureStructuredContent({
+ ollamaClient,
+ model: activeModel,
+ format,
+ content: fullAssistantResponse,
+ });
+ usageMetrics = extractUsage(structuredResponse);
+
+ if (fullAssistantThinking) {
+ for (const token of splitIntoStreamChunks(fullAssistantThinking, 180)) {
+ writeEvent({ type: "thinking", token });
+ }
+ }
+
+ for (const token of splitIntoStreamChunks(fullAssistantResponse)) {
+ writeEvent({ type: "content", token });
+ }
+
+ writeEvent({ type: "done", usage: usageMetrics });
+ return;
+ }
+
+ const chatRequest = {
+ model: activeModel,
+ messages,
+ stream: true as const,
+ options: {
+ temperature: ollamaConfig.temperature,
+ },
+ ...(think !== undefined ? { think } : {}),
+ ...(keepAlive !== undefined ? { keep_alive: keepAlive } : {}),
+ ...(format !== undefined ? { format } : {}),
+ };
+
+ const response = await ollamaClient.chat(chatRequest);
+
+ for await (const part of response as AsyncIterable) {
+ const thinkingToken = part.message?.thinking ?? "";
+ if (thinkingToken) {
+ fullAssistantThinking += thinkingToken;
+ writeEvent({ type: "thinking", token: thinkingToken });
+ }
+
+ const token = part.message?.content ?? "";
+ if (token) {
+ fullAssistantResponse += token;
+ writeEvent({ type: "content", token });
+ }
+
+ if (part.done) {
+ usageMetrics = extractUsage(part);
+ writeEvent({ type: "done", usage: usageMetrics });
+ }
+ }
+ } catch (err) {
+ const errMsg = err instanceof Error ? err.message : String(err);
+ console.error("[chat/ollama] SDK streaming error:", errMsg);
+ writeEvent({
+ type: "error",
+ message: "Failed to get response from AI service. Please check your configuration.",
+ });
+ } finally {
+ // Persist assistant response
+ if (fullAssistantResponse.trim().length > 0 || fullAssistantThinking.trim().length > 0) {
+ try {
+ await prisma.chatMessage.create({
+ data: {
+ userId,
+ organizationId,
+ role: "ASSISTANT",
+ content: fullAssistantResponse,
+ thinking: fullAssistantThinking || null,
+ model: activeModel,
+ usage: usageMetrics ? (usageMetrics as Prisma.InputJsonValue) : undefined,
+ },
+ });
+ } catch (dbErr) {
+ console.error("[chat/ollama] Failed to persist assistant message:", dbErr);
+ }
+ }
+ controller.close();
+ }
+ },
+ });
+
+ return new Response(stream, {
+ headers: {
+ "Content-Type": "application/x-ndjson; charset=utf-8",
+ "Cache-Control": "no-cache, no-transform",
+ "X-Accel-Buffering": "no",
+ },
+ });
+}
diff --git a/src/app/api/chat/semantic-search/products/route.ts b/src/app/api/chat/semantic-search/products/route.ts
new file mode 100644
index 00000000..1e8b75a5
--- /dev/null
+++ b/src/app/api/chat/semantic-search/products/route.ts
@@ -0,0 +1,312 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth";
+import { z } from "zod";
+import { authOptions } from "@/lib/auth";
+import { getOllamaClientForUser } from "@/lib/ollama";
+import { resolveChatTenantContext } from "@/lib/chat-tenant-context";
+import { prisma } from "@/lib/prisma";
+import { Role } from "@prisma/client";
+
+const requestSchema = z.object({
+ query: z.string().min(1).max(1000),
+ storeId: z.string().cuid().optional(),
+ model: z.string().min(1).optional(),
+ topK: z.number().int().min(1).max(20).optional().default(8),
+ candidateLimit: z.number().int().min(10).max(120).optional().default(50),
+});
+
+const DEFAULT_EMBEDDING_MODELS = ["embeddinggemma", "qwen3-embedding", "nomic-embed-text", "all-minilm"];
+
+function buildEmbeddingModelCandidates(...models: Array): string[] {
+ const unique = new Set();
+
+ for (const raw of models) {
+ const model = raw?.trim();
+ if (!model) continue;
+ unique.add(model);
+ }
+
+ for (const fallback of DEFAULT_EMBEDDING_MODELS) {
+ unique.add(fallback);
+ }
+
+ return Array.from(unique);
+}
+
+function magnitude(values: number[]): number {
+ return Math.sqrt(values.reduce((sum, value) => sum + value * value, 0));
+}
+
+function cosineSimilarity(a: number[], b: number[]): number {
+ if (a.length !== b.length || a.length === 0) return 0;
+
+ const dot = a.reduce((sum, value, index) => sum + value * b[index], 0);
+ const magA = magnitude(a);
+ const magB = magnitude(b);
+
+ if (magA === 0 || magB === 0) return 0;
+ return dot / (magA * magB);
+}
+
+function buildProductSemanticText(product: {
+ name: string;
+ description: string | null;
+ shortDescription: string | null;
+ sku: string;
+ category: { name: string } | null;
+ brand: { name: string } | null;
+}): string {
+ return [
+ product.name,
+ product.shortDescription ?? "",
+ product.description ?? "",
+ product.sku,
+ product.category?.name ?? "",
+ product.brand?.name ?? "",
+ ]
+ .filter(Boolean)
+ .join(" \n ");
+}
+
+function lexicalSimilarity(query: string, text: string): number {
+ const q = query.toLowerCase().trim();
+ const t = text.toLowerCase();
+ if (!q || !t) return 0;
+
+ const terms = q.split(/\s+/).filter((term) => term.length > 1);
+ if (terms.length === 0) return 0;
+
+ const matches = terms.reduce((count, term) => (t.includes(term) ? count + 1 : count), 0);
+ return matches / terms.length;
+}
+
+export async function POST(request: NextRequest) {
+ if (process.env.AI_EMBEDDINGS_ENABLED === "false") {
+ return NextResponse.json({ error: "Semantic search is disabled by configuration" }, { status: 403 });
+ }
+
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ let body: z.infer;
+ try {
+ body = requestSchema.parse(await request.json());
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ return NextResponse.json({ error: "Invalid request body", details: error.issues }, { status: 400 });
+ }
+ return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+ }
+
+ try {
+ const tenant = await resolveChatTenantContext(session, body.storeId);
+
+ const elevatedMembership = await prisma.membership.findFirst({
+ where: {
+ userId: session.user.id,
+ organizationId: tenant.organizationId,
+ role: {
+ in: [
+ Role.OWNER,
+ Role.ADMIN,
+ Role.STORE_ADMIN,
+ Role.SALES_MANAGER,
+ Role.INVENTORY_MANAGER,
+ ],
+ },
+ },
+ select: { id: true },
+ });
+
+ const canReadProducts =
+ session.user.isSuperAdmin ||
+ Boolean(session.user.permissions?.includes("products:read")) ||
+ Boolean(elevatedMembership);
+
+ if (!canReadProducts) {
+ return NextResponse.json(
+ { error: "Access denied. You do not have permission to search products." },
+ { status: 403 },
+ );
+ }
+
+ const { client, config } = await getOllamaClientForUser(session.user.id);
+ const candidateModels = buildEmbeddingModelCandidates(
+ body.model,
+ process.env.OLLAMA_EMBED_MODEL,
+ config.model,
+ );
+ const activeModel = candidateModels[0] ?? config.model;
+
+ const candidates = await prisma.product.findMany({
+ where: {
+ storeId: tenant.storeId,
+ deletedAt: null,
+ },
+ orderBy: { updatedAt: "desc" },
+ take: body.candidateLimit,
+ select: {
+ id: true,
+ name: true,
+ slug: true,
+ sku: true,
+ price: true,
+ inventoryQty: true,
+ inventoryStatus: true,
+ status: true,
+ description: true,
+ shortDescription: true,
+ category: {
+ select: {
+ name: true,
+ },
+ },
+ brand: {
+ select: {
+ name: true,
+ },
+ },
+ },
+ });
+
+ if (candidates.length === 0) {
+ return NextResponse.json({
+ data: [],
+ meta: {
+ model: activeModel,
+ storeId: tenant.storeId,
+ organizationId: tenant.organizationId,
+ candidateCount: 0,
+ },
+ });
+ }
+
+ const candidateTexts = candidates.map(buildProductSemanticText);
+ const embeddingPayload = [body.query, ...candidateTexts];
+
+ let scored: Array<{
+ id: string;
+ name: string;
+ slug: string;
+ sku: string;
+ priceMinor: number;
+ price: number;
+ inventoryQty: number;
+ inventoryStatus: string;
+ status: string;
+ score: number;
+ category: string | null;
+ brand: string | null;
+ }> = [];
+ let strategy: "embedding" | "lexical-fallback" = "embedding";
+ let modelUsed = activeModel;
+
+ try {
+ let embeddingResult: Awaited> | null = null;
+ let selectedModel = activeModel;
+ let lastEmbeddingError: unknown = null;
+
+ for (const candidateModel of candidateModels) {
+ try {
+ embeddingResult = await client.embed({
+ model: candidateModel,
+ input: embeddingPayload,
+ });
+ selectedModel = candidateModel;
+ break;
+ } catch (embeddingError) {
+ lastEmbeddingError = embeddingError;
+ }
+ }
+
+ if (!embeddingResult) {
+ throw new Error(
+ `Embedding generation failed for models: ${candidateModels.join(", ")}. Last error: ${lastEmbeddingError instanceof Error ? lastEmbeddingError.message : String(lastEmbeddingError)}`,
+ );
+ }
+
+ const [queryEmbedding, ...productEmbeddings] = embeddingResult.embeddings;
+ if (!queryEmbedding || productEmbeddings.length !== candidates.length) {
+ throw new Error("Embedding generation did not return expected vectors.");
+ }
+
+ scored = candidates
+ .map((product, index) => ({
+ product,
+ score: cosineSimilarity(queryEmbedding, productEmbeddings[index] || []),
+ }))
+ .sort((a, b) => b.score - a.score)
+ .slice(0, body.topK)
+ .map(({ product, score }) => ({
+ id: product.id,
+ name: product.name,
+ slug: product.slug,
+ sku: product.sku,
+ priceMinor: product.price,
+ price: Number((product.price / 100).toFixed(2)),
+ inventoryQty: product.inventoryQty,
+ inventoryStatus: product.inventoryStatus,
+ status: product.status,
+ score: Number(score.toFixed(6)),
+ category: product.category?.name ?? null,
+ brand: product.brand?.name ?? null,
+ }));
+
+ modelUsed = embeddingResult.model || selectedModel;
+ } catch (embeddingError) {
+ strategy = "lexical-fallback";
+ console.warn(
+ "[chat/semantic-search/products] Embedding unavailable, using lexical fallback:",
+ embeddingError instanceof Error ? embeddingError.message : String(embeddingError),
+ );
+
+ scored = candidates
+ .map((product) => {
+ const text = buildProductSemanticText(product);
+ return {
+ product,
+ score: lexicalSimilarity(body.query, text),
+ };
+ })
+ .sort((a, b) => b.score - a.score)
+ .slice(0, body.topK)
+ .map(({ product, score }) => ({
+ id: product.id,
+ name: product.name,
+ slug: product.slug,
+ sku: product.sku,
+ priceMinor: product.price,
+ price: Number((product.price / 100).toFixed(2)),
+ inventoryQty: product.inventoryQty,
+ inventoryStatus: product.inventoryStatus,
+ status: product.status,
+ score: Number(score.toFixed(6)),
+ category: product.category?.name ?? null,
+ brand: product.brand?.name ?? null,
+ }));
+ }
+
+ return NextResponse.json({
+ data: scored,
+ meta: {
+ model: modelUsed,
+ strategy,
+ attemptedModels: candidateModels,
+ storeId: tenant.storeId,
+ organizationId: tenant.organizationId,
+ candidateCount: candidates.length,
+ returned: scored.length,
+ },
+ });
+ } catch (error) {
+ const message = error instanceof Error ? error.message : "Failed to run semantic product search";
+ console.error("[chat/semantic-search/products] Error:", message);
+
+ return NextResponse.json(
+ { error: "Failed to run semantic product search", details: message },
+ { status: 502 },
+ );
+ }
+}
diff --git a/src/app/api/chat/tools/execute/route.ts b/src/app/api/chat/tools/execute/route.ts
new file mode 100644
index 00000000..54bb10be
--- /dev/null
+++ b/src/app/api/chat/tools/execute/route.ts
@@ -0,0 +1,66 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth";
+import { z } from "zod";
+import { authOptions } from "@/lib/auth";
+import { resolveChatTenantContext } from "@/lib/chat-tenant-context";
+import { CHAT_TOOL_NAMES, executeCommerceTool } from "@/lib/chat-tools";
+
+const requestSchema = z.object({
+ toolName: z.enum(CHAT_TOOL_NAMES),
+ toolArgs: z.record(z.string(), z.unknown()).optional(),
+ arguments: z.record(z.string(), z.unknown()).optional(),
+ storeId: z.string().cuid().optional(),
+}).transform((payload) => ({
+ ...payload,
+ toolArgs: payload.toolArgs ?? payload.arguments,
+}));
+
+export async function POST(request: NextRequest) {
+ if (process.env.AI_TOOLS_ENABLED === "false") {
+ return NextResponse.json({ error: "AI tools are disabled by configuration" }, { status: 403 });
+ }
+
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ let body: z.infer;
+ try {
+ body = requestSchema.parse(await request.json());
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ return NextResponse.json({ error: "Invalid request body", details: error.issues }, { status: 400 });
+ }
+ return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+ }
+
+ try {
+ const tenant = await resolveChatTenantContext(session, body.storeId);
+
+ const result = await executeCommerceTool(
+ session,
+ tenant,
+ body.toolName,
+ body.toolArgs,
+ );
+
+ return NextResponse.json({
+ data: result,
+ meta: {
+ toolName: body.toolName,
+ storeId: tenant.storeId,
+ organizationId: tenant.organizationId,
+ },
+ });
+ } catch (error) {
+ const message = error instanceof Error ? error.message : "Failed to execute tool";
+ const status = message.startsWith("Access denied") ? 403 : 502;
+
+ console.error("[chat/tools/execute] Error:", message);
+ return NextResponse.json(
+ { error: "Failed to execute tool", details: message },
+ { status },
+ );
+ }
+}
diff --git a/src/app/api/chat/webfetch/route.ts b/src/app/api/chat/webfetch/route.ts
new file mode 100644
index 00000000..dfe65c8e
--- /dev/null
+++ b/src/app/api/chat/webfetch/route.ts
@@ -0,0 +1,68 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth";
+import { z } from "zod";
+import { authOptions } from "@/lib/auth";
+import { getOllamaClientForUser } from "@/lib/ollama";
+import { resolveChatTenantContext } from "@/lib/chat-tenant-context";
+import { assertPublicHttpsUrl } from "@/lib/chat-tools";
+
+const requestSchema = z.object({
+ url: z.string().url(),
+ maxChars: z.number().int().min(500).max(30000).optional().default(8000),
+ storeId: z.string().cuid().optional(),
+});
+
+export async function POST(request: NextRequest) {
+ if (process.env.AI_WEB_ENABLED === "false") {
+ return NextResponse.json({ error: "Web fetch is disabled by configuration" }, { status: 403 });
+ }
+
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ let body: z.infer;
+ try {
+ body = requestSchema.parse(await request.json());
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ return NextResponse.json({ error: "Invalid request body", details: error.issues }, { status: 400 });
+ }
+ return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+ }
+
+ try {
+ const safeUrl = assertPublicHttpsUrl(body.url);
+ const tenant = await resolveChatTenantContext(session, body.storeId);
+ const { client } = await getOllamaClientForUser(session.user.id);
+
+ const result = await client.webFetch({
+ url: safeUrl.toString(),
+ });
+
+ return NextResponse.json({
+ data: {
+ title: result.title,
+ url: result.url,
+ content: result.content.slice(0, body.maxChars),
+ links: result.links.slice(0, 30),
+ },
+ meta: {
+ maxChars: body.maxChars,
+ storeId: tenant.storeId,
+ organizationId: tenant.organizationId,
+ },
+ });
+ } catch (error) {
+ const message = error instanceof Error ? error.message : "Failed to fetch web content";
+ const status = message.includes("not allowed") || message.includes("Only HTTPS") ? 400 : 502;
+
+ console.error("[chat/webfetch] Error:", message);
+
+ return NextResponse.json(
+ { error: "Failed to fetch web content", details: message },
+ { status },
+ );
+ }
+}
diff --git a/src/app/api/chat/websearch/route.ts b/src/app/api/chat/websearch/route.ts
new file mode 100644
index 00000000..2b484498
--- /dev/null
+++ b/src/app/api/chat/websearch/route.ts
@@ -0,0 +1,63 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth";
+import { z } from "zod";
+import { authOptions } from "@/lib/auth";
+import { getOllamaClientForUser } from "@/lib/ollama";
+import { resolveChatTenantContext } from "@/lib/chat-tenant-context";
+
+const requestSchema = z.object({
+ query: z.string().min(1).max(500),
+ maxResults: z.number().int().min(1).max(10).optional().default(5),
+ storeId: z.string().cuid().optional(),
+});
+
+export async function POST(request: NextRequest) {
+ if (process.env.AI_WEB_ENABLED === "false") {
+ return NextResponse.json({ error: "Web search is disabled by configuration" }, { status: 403 });
+ }
+
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ let body: z.infer;
+ try {
+ body = requestSchema.parse(await request.json());
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ return NextResponse.json({ error: "Invalid request body", details: error.issues }, { status: 400 });
+ }
+ return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+ }
+
+ try {
+ const tenant = await resolveChatTenantContext(session, body.storeId);
+ const { client } = await getOllamaClientForUser(session.user.id);
+
+ const result = await client.webSearch({
+ query: body.query,
+ maxResults: body.maxResults,
+ });
+
+ return NextResponse.json({
+ data: {
+ results: result.results,
+ },
+ meta: {
+ query: body.query,
+ maxResults: body.maxResults,
+ storeId: tenant.storeId,
+ organizationId: tenant.organizationId,
+ },
+ });
+ } catch (error) {
+ const message = error instanceof Error ? error.message : "Failed to run web search";
+ console.error("[chat/websearch] Error:", message);
+
+ return NextResponse.json(
+ { error: "Failed to run web search", details: message },
+ { status: 502 },
+ );
+ }
+}
diff --git a/src/app/api/settings/ai/route.ts b/src/app/api/settings/ai/route.ts
new file mode 100644
index 00000000..1272dcf4
--- /dev/null
+++ b/src/app/api/settings/ai/route.ts
@@ -0,0 +1,147 @@
+/**
+ * GET /api/settings/ai — read the authenticated user's Ollama config
+ * PUT /api/settings/ai — create or update the config
+ *
+ * The API key is always encrypted before persistence and never returned
+ * in plain text — the client only receives a `hasApiKey` boolean.
+ */
+
+import { NextRequest, NextResponse } from "next/server";
+import { getServerSession } from "next-auth/next";
+import { authOptions } from "@/lib/auth";
+import { prisma } from "@/lib/prisma";
+import { encryptCredential } from "@/lib/encryption";
+import type { OllamaConfigData, OllamaConfigUpdate } from "@/lib/chat-types";
+
+// ── GET ─────────────────────────────────────────────────────────────────────
+export async function GET() {
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ const config = await prisma.ollamaConfig.findUnique({
+ where: { userId: session.user.id },
+ });
+
+ if (!config) {
+ // Return defaults derived from env / hard-coded values
+ const envHost = process.env.OLLAMA_API_URL || "http://localhost:11434";
+ const envModel = process.env.OLLAMA_MODEL || "llama3.2";
+ const envApiKey = process.env.OLLAMA_API_KEY;
+
+ const data: OllamaConfigData = {
+ host: envHost,
+ model: envModel,
+ systemPrompt:
+ "You are a helpful AI assistant. Answer questions clearly and concisely. Use Markdown for formatting when appropriate.",
+ temperature: 0.7,
+ isCloudMode: envHost.includes("ollama.com") || Boolean(envApiKey),
+ hasApiKey: Boolean(envApiKey),
+ };
+ return NextResponse.json(data);
+ }
+
+ const data: OllamaConfigData = {
+ host: config.host,
+ model: config.model,
+ systemPrompt:
+ config.systemPrompt ??
+ "You are a helpful AI assistant. Answer questions clearly and concisely. Use Markdown for formatting when appropriate.",
+ temperature: config.temperature,
+ isCloudMode: config.isCloudMode,
+ hasApiKey: Boolean(config.apiKey),
+ };
+ return NextResponse.json(data);
+}
+
+// ── PUT ─────────────────────────────────────────────────────────────────────
+export async function PUT(request: NextRequest) {
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ let body: OllamaConfigUpdate;
+ try {
+ body = await request.json();
+ } catch {
+ return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+ }
+
+ // Validate host URL when provided
+ if (body.host !== undefined) {
+ try {
+ new URL(body.host);
+ } catch {
+ return NextResponse.json(
+ { error: "Invalid host URL" },
+ { status: 400 },
+ );
+ }
+ }
+
+ // Validate temperature range
+ if (
+ body.temperature !== undefined &&
+ (body.temperature < 0 || body.temperature > 2)
+ ) {
+ return NextResponse.json(
+ { error: "Temperature must be between 0 and 2" },
+ { status: 400 },
+ );
+ }
+
+ // Encrypt API key before storing
+ let encryptedApiKey: string | undefined;
+ if (body.apiKey !== undefined && body.apiKey.trim().length > 0) {
+ try {
+ encryptedApiKey = encryptCredential(body.apiKey);
+ } catch (err) {
+ console.error("[settings/ai] Encryption error:", err);
+ return NextResponse.json(
+ { error: "Failed to encrypt API key. Please check server configuration." },
+ { status: 500 },
+ );
+ }
+ }
+
+ // Upsert config
+ const upsertData: Record = {};
+ if (body.host !== undefined) upsertData.host = body.host;
+ if (body.model !== undefined) upsertData.model = body.model;
+ if (body.systemPrompt !== undefined) upsertData.systemPrompt = body.systemPrompt;
+ if (body.temperature !== undefined) upsertData.temperature = body.temperature;
+ if (body.isCloudMode !== undefined) upsertData.isCloudMode = body.isCloudMode;
+ if (encryptedApiKey !== undefined) upsertData.apiKey = encryptedApiKey;
+ // Allow explicitly clearing the API key
+ if (body.apiKey !== undefined && body.apiKey.trim().length === 0) {
+ upsertData.apiKey = null;
+ }
+
+ const config = await prisma.ollamaConfig.upsert({
+ where: { userId: session.user.id },
+ create: {
+ userId: session.user.id,
+ host: (body.host as string) ?? "https://ollama.com",
+ model: (body.model as string) ?? "llama3.2",
+ systemPrompt: body.systemPrompt as string | undefined,
+ temperature: (body.temperature as number) ?? 0.7,
+ isCloudMode: (body.isCloudMode as boolean) ?? true,
+ apiKey: encryptedApiKey ?? null,
+ },
+ update: upsertData,
+ });
+
+ const data: OllamaConfigData = {
+ host: config.host,
+ model: config.model,
+ systemPrompt:
+ config.systemPrompt ??
+ "You are a helpful AI assistant. Answer questions clearly and concisely. Use Markdown for formatting when appropriate.",
+ temperature: config.temperature,
+ isCloudMode: config.isCloudMode,
+ hasApiKey: Boolean(config.apiKey),
+ };
+ return NextResponse.json(data);
+}
diff --git a/src/app/api/settings/ai/test/route.ts b/src/app/api/settings/ai/test/route.ts
new file mode 100644
index 00000000..5efd11d8
--- /dev/null
+++ b/src/app/api/settings/ai/test/route.ts
@@ -0,0 +1,48 @@
+/**
+ * POST /api/settings/ai/test
+ *
+ * Tests connectivity to the user's configured Ollama instance.
+ * Returns success/failure, available models, and round-trip latency.
+ */
+
+import { NextResponse } from "next/server";
+import { getServerSession } from "next-auth/next";
+import { authOptions } from "@/lib/auth";
+import { getOllamaClientForUser } from "@/lib/ollama";
+import type { ConnectionTestResult } from "@/lib/chat-types";
+
+export async function POST() {
+ const session = await getServerSession(authOptions);
+ if (!session?.user?.id) {
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ const start = Date.now();
+
+ try {
+ const { client } = await getOllamaClientForUser(session.user.id);
+ const listResponse = await client.list();
+ const latencyMs = Date.now() - start;
+
+ const modelNames = (listResponse.models ?? []).map((m) => m.name);
+
+ const result: ConnectionTestResult = {
+ success: true,
+ message: `Connected successfully. Found ${modelNames.length} model(s).`,
+ models: modelNames,
+ latencyMs,
+ };
+ return NextResponse.json(result);
+ } catch (err) {
+ const latencyMs = Date.now() - start;
+ const message = err instanceof Error ? err.message : String(err);
+ console.error("[settings/ai/test] Connection test failed:", message);
+
+ const result: ConnectionTestResult = {
+ success: false,
+ message: `Connection failed: ${message}`,
+ latencyMs,
+ };
+ return NextResponse.json(result, { status: 200 }); // 200 so client can read body
+ }
+}
diff --git a/src/app/chat/loading.tsx b/src/app/chat/loading.tsx
new file mode 100644
index 00000000..e1cec8c5
--- /dev/null
+++ b/src/app/chat/loading.tsx
@@ -0,0 +1,25 @@
+import { Skeleton } from "@/components/ui/skeleton";
+import { Card, CardContent, CardFooter, CardHeader } from "@/components/ui/card";
+
+export default function ChatLoading() {
+ return (
+
+
+
+
+ );
+}
diff --git a/src/app/settings/ai/page.tsx b/src/app/settings/ai/page.tsx
new file mode 100644
index 00000000..53782e53
--- /dev/null
+++ b/src/app/settings/ai/page.tsx
@@ -0,0 +1,56 @@
+import { getServerSession } from "next-auth";
+import { authOptions } from "@/lib/auth";
+import { redirect } from "next/navigation";
+import { AppSidebar } from "@/components/app-sidebar";
+import { SiteHeader } from "@/components/site-header";
+import {
+ SidebarInset,
+ SidebarProvider,
+} from "@/components/ui/sidebar";
+import { AiSettingsForm } from "@/components/ai-settings-form";
+
+export const metadata = {
+ title: "AI Settings",
+ description: "Configure your Ollama AI chat integration",
+};
+
+export default async function AiSettingsPage() {
+ const session = await getServerSession(authOptions);
+ if (!session?.user) {
+ redirect("/login");
+ }
+
+ return (
+
+
+
+
+ );
+}
diff --git a/src/components/ai-settings-form.tsx b/src/components/ai-settings-form.tsx
new file mode 100644
index 00000000..9e75b21e
--- /dev/null
+++ b/src/components/ai-settings-form.tsx
@@ -0,0 +1,755 @@
+"use client";
+
+import * as React from "react";
+import {
+ IconCheck,
+ IconLoader2,
+ IconRefresh,
+ IconTrash,
+ IconPlugConnected,
+ IconInfoCircle,
+} from "@tabler/icons-react";
+
+import { Button } from "@/components/ui/button";
+import {
+ Card,
+ CardContent,
+ CardDescription,
+ CardHeader,
+ CardTitle,
+} from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from "@/components/ui/select";
+import { Slider } from "@/components/ui/slider";
+import { Switch } from "@/components/ui/switch";
+import { Textarea } from "@/components/ui/textarea";
+import { Badge } from "@/components/ui/badge";
+import { Separator } from "@/components/ui/separator";
+import type {
+ OllamaConfigData,
+ OllamaModelInfo,
+ ConnectionTestResult,
+ OllamaModelDetails,
+} from "@/lib/chat-types";
+
+export function AiSettingsForm() {
+ const [config, setConfig] = React.useState(null);
+ const [models, setModels] = React.useState([]);
+ const [loading, setLoading] = React.useState(true);
+ const [saving, setSaving] = React.useState(false);
+ const [modelsLoading, setModelsLoading] = React.useState(false);
+ const [modelDetailsLoading, setModelDetailsLoading] = React.useState(false);
+ const [saved, setSaved] = React.useState(false);
+ const [error, setError] = React.useState(null);
+ const [modelDetailsError, setModelDetailsError] = React.useState(null);
+ const [testing, setTesting] = React.useState(false);
+ const [testResult, setTestResult] = React.useState(null);
+ const [modelDetails, setModelDetails] = React.useState(null);
+ const [modelActionLoading, setModelActionLoading] = React.useState(false);
+ const [modelActionError, setModelActionError] = React.useState(null);
+ const [modelActionMessage, setModelActionMessage] = React.useState(null);
+ const [pullModelName, setPullModelName] = React.useState("");
+ const [copySourceModel, setCopySourceModel] = React.useState("");
+ const [copyDestinationModel, setCopyDestinationModel] = React.useState("");
+
+ // Form state
+ const [host, setHost] = React.useState("https://ollama.com");
+ const [apiKey, setApiKey] = React.useState("");
+ const [model, setModel] = React.useState("llama3.2");
+ const [systemPrompt, setSystemPrompt] = React.useState("");
+ const [temperature, setTemperature] = React.useState(0.7);
+ const [isCloudMode, setIsCloudMode] = React.useState(true);
+ const [clearSavedApiKey, setClearSavedApiKey] = React.useState(false);
+
+ // Load config on mount
+ React.useEffect(() => {
+ async function load() {
+ try {
+ const res = await fetch("/api/settings/ai");
+ if (!res.ok) throw new Error("Failed to load AI settings");
+ const data: OllamaConfigData = await res.json();
+ setConfig(data);
+ setHost(data.host);
+ setModel(data.model);
+ setPullModelName(data.model);
+ setCopySourceModel(data.model);
+ setSystemPrompt(data.systemPrompt);
+ setTemperature(data.temperature);
+ setIsCloudMode(data.isCloudMode);
+ } catch (err) {
+ setError(err instanceof Error ? err.message : "Failed to load settings");
+ } finally {
+ setLoading(false);
+ }
+ }
+ load();
+ }, []);
+
+ // Fetch models
+ const fetchModels = React.useCallback(async () => {
+ setModelsLoading(true);
+ try {
+ const res = await fetch("/api/chat/models");
+ if (!res.ok) {
+ const data = await res.json();
+ throw new Error(data.error || "Failed to fetch models");
+ }
+ const data = await res.json();
+ setModels(data.models ?? []);
+ } catch (err) {
+ console.error("Model fetch error:", err);
+ setModels([]);
+ } finally {
+ setModelsLoading(false);
+ }
+ }, []);
+
+ const fetchModelDetails = React.useCallback(async (modelName: string) => {
+ if (!modelName.trim()) {
+ setModelDetails(null);
+ setModelDetailsError(null);
+ return;
+ }
+
+ setModelDetailsLoading(true);
+ setModelDetailsError(null);
+
+ try {
+ const res = await fetch(`/api/chat/models/${encodeURIComponent(modelName)}`);
+ if (res.status === 404) {
+ setModelDetails(null);
+ setModelDetailsError(null);
+ return;
+ }
+
+ if (!res.ok) {
+ const data = await res.json().catch(() => ({}));
+ throw new Error(data.error || "Failed to fetch model details");
+ }
+
+ const details = (await res.json()) as OllamaModelDetails;
+ setModelDetails(details);
+ } catch (err) {
+ setModelDetails(null);
+ setModelDetailsError(err instanceof Error ? err.message : "Failed to fetch model details");
+ } finally {
+ setModelDetailsLoading(false);
+ }
+ }, []);
+
+ React.useEffect(() => {
+ if (!model.trim()) {
+ setModelDetails(null);
+ setModelDetailsError(null);
+ return;
+ }
+
+ const timeoutId = window.setTimeout(() => {
+ fetchModelDetails(model);
+ }, 350);
+
+ return () => window.clearTimeout(timeoutId);
+ }, [fetchModelDetails, model]);
+
+ React.useEffect(() => {
+ if (!pullModelName) {
+ setPullModelName(model);
+ }
+
+ if (!copySourceModel) {
+ setCopySourceModel(model);
+ }
+ }, [copySourceModel, model, pullModelName]);
+
+ // Test connection
+ const testConnection = React.useCallback(async () => {
+ setTesting(true);
+ setTestResult(null);
+ try {
+ const res = await fetch("/api/settings/ai/test", { method: "POST" });
+ const data: ConnectionTestResult = await res.json();
+ setTestResult(data);
+ // If test returns models, update the models list
+ if (data.success && data.models && data.models.length > 0) {
+ setModels(data.models.map((name) => ({ name, size: 0, modifiedAt: "" })));
+ }
+ } catch (err) {
+ setTestResult({
+ success: false,
+ message: err instanceof Error ? err.message : "Test failed",
+ });
+ } finally {
+ setTesting(false);
+ }
+ }, []);
+
+ const runModelAction = React.useCallback(
+ async (payload: Record, successMessage: string) => {
+ setModelActionLoading(true);
+ setModelActionError(null);
+ setModelActionMessage(null);
+
+ try {
+ const res = await fetch("/api/chat/models/manage", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(payload),
+ });
+
+ const data = await res.json().catch(() => ({}));
+ if (!res.ok) {
+ const details = [data.error, data.details].filter(Boolean).join(": ");
+ throw new Error(details || "Model action failed");
+ }
+
+ setModelActionMessage(successMessage);
+ await fetchModels();
+ } catch (err) {
+ setModelActionError(err instanceof Error ? err.message : "Model action failed");
+ } finally {
+ setModelActionLoading(false);
+ }
+ },
+ [fetchModels],
+ );
+
+ // Save config
+ async function handleSave() {
+ setSaving(true);
+ setError(null);
+ setSaved(false);
+ try {
+ const body: Record = {
+ host,
+ model,
+ systemPrompt,
+ temperature,
+ isCloudMode,
+ };
+ // Explicit API key clearing takes precedence
+ if (clearSavedApiKey) {
+ body.apiKey = "";
+ } else if (apiKey.trim().length > 0) {
+ // Only send apiKey when user typed one
+ body.apiKey = apiKey;
+ }
+
+ const res = await fetch("/api/settings/ai", {
+ method: "PUT",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(body),
+ });
+
+ if (!res.ok) {
+ const data = await res.json();
+ throw new Error(data.error || "Failed to save settings");
+ }
+
+ const data: OllamaConfigData = await res.json();
+ setConfig(data);
+ setApiKey(""); // clear input after successful save
+ setClearSavedApiKey(false);
+ setSaved(true);
+ setTimeout(() => setSaved(false), 3000);
+ } catch (err) {
+ setError(err instanceof Error ? err.message : "Save failed");
+ } finally {
+ setSaving(false);
+ }
+ }
+
+ // Toggle cloud mode changes host automatically
+ function handleCloudToggle(checked: boolean) {
+ setIsCloudMode(checked);
+ if (checked) {
+ setHost("https://ollama.com");
+ } else {
+ setHost("http://localhost:11434");
+ }
+ }
+
+ if (loading) {
+ return (
+
+
+
+ )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
diff --git a/skills/vercel-react-best-practices/rules/rendering-conditional-render.md b/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
new file mode 100644
index 00000000..7e866f58
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
@@ -0,0 +1,40 @@
+---
+title: Use Explicit Conditional Rendering
+impact: LOW
+impactDescription: prevents rendering 0 or NaN
+tags: rendering, conditional, jsx, falsy-values
+---
+
+## Use Explicit Conditional Rendering
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect (renders "0" when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+ return (
+
+ {count && {count}}
+
+ )
+}
+
+// When count = 0, renders: 0
+// When count = 5, renders: 5
+```
+
+**Correct (renders nothing when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+ return (
+
+ {count > 0 ? {count} : null}
+
+ )
+}
+
+// When count = 0, renders:
+// When count = 5, renders: 5
+```
diff --git a/skills/vercel-react-best-practices/rules/rendering-content-visibility.md b/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
new file mode 100644
index 00000000..aa665636
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
@@ -0,0 +1,38 @@
+---
+title: CSS content-visibility for Long Lists
+impact: HIGH
+impactDescription: faster initial render
+tags: rendering, css, content-visibility, long-lists
+---
+
+## CSS content-visibility for Long Lists
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+ content-visibility: auto;
+ contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+ return (
+
+ {messages.map(msg => (
+
+ )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
diff --git a/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md b/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
new file mode 100644
index 00000000..32d2f3fc
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
@@ -0,0 +1,46 @@
+---
+title: Hoist Static JSX Elements
+impact: LOW
+impactDescription: avoids re-creation
+tags: rendering, jsx, static, optimization
+---
+
+## Hoist Static JSX Elements
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect (recreates element every render):**
+
+```tsx
+function LoadingSkeleton() {
+ return
+}
+
+function Container() {
+ return (
+
+
+ ))}
+ {msg.content}
+
+ {loading &&
+ )
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = (
+
+)
+
+function Container() {
+ return (
+
+ {loading && loadingSkeleton}
+
+ )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
diff --git a/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md b/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
new file mode 100644
index 00000000..5cf0e79b
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
@@ -0,0 +1,82 @@
+---
+title: Prevent Hydration Mismatch Without Flickering
+impact: MEDIUM
+impactDescription: avoids visual flicker and hydration errors
+tags: rendering, ssr, hydration, localStorage, flicker
+---
+
+## Prevent Hydration Mismatch Without Flickering
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect (breaks SSR):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ // localStorage is not available on server - throws error
+ const theme = localStorage.getItem('theme') || 'light'
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect (visual flickering):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ const [theme, setTheme] = useState('light')
+
+ useEffect(() => {
+ // Runs after hydration - causes visible flash
+ const stored = localStorage.getItem('theme')
+ if (stored) {
+ setTheme(stored)
+ }
+ }, [])
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct (no flicker, no hydration mismatch):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ return (
+ <>
+
+ {children}
+
+
+
+ )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
diff --git a/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md b/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
new file mode 100644
index 00000000..24ba2513
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
@@ -0,0 +1,30 @@
+---
+title: Suppress Expected Hydration Mismatches
+impact: LOW-MEDIUM
+impactDescription: avoids noisy hydration warnings for known differences
+tags: rendering, hydration, ssr, nextjs
+---
+
+## Suppress Expected Hydration Mismatches
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect (known mismatch warnings):**
+
+```tsx
+function Timestamp() {
+ return {new Date().toLocaleString()}
+}
+```
+
+**Correct (suppress expected mismatch only):**
+
+```tsx
+function Timestamp() {
+ return (
+
+ {new Date().toLocaleString()}
+
+ )
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/rendering-resource-hints.md b/skills/vercel-react-best-practices/rules/rendering-resource-hints.md
new file mode 100644
index 00000000..1290bef0
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-resource-hints.md
@@ -0,0 +1,85 @@
+---
+title: Use React DOM Resource Hints
+impact: HIGH
+impactDescription: reduces load time for critical resources
+tags: rendering, preload, preconnect, prefetch, resource-hints
+---
+
+## Use React DOM Resource Hints
+
+**Impact: HIGH (reduces load time for critical resources)**
+
+React DOM provides APIs to hint the browser about resources it will need. These are especially useful in server components to start loading resources before the client even receives the HTML.
+
+- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to
+- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server
+- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon
+- **`preloadModule(href)`**: Fetch an ES module you'll use soon
+- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script
+- **`preinitModule(href)`**: Fetch and evaluate an ES module
+
+**Example (preconnect to third-party APIs):**
+
+```tsx
+import { preconnect, prefetchDNS } from 'react-dom'
+
+export default function App() {
+ prefetchDNS('https://analytics.example.com')
+ preconnect('https://api.example.com')
+
+ return {fullName}
+} +``` + +**Correct (derive during render):** + +```tsx +function Form() { + const [firstName, setFirstName] = useState('First') + const [lastName, setLastName] = useState('Last') + const fullName = firstName + ' ' + lastName + + return{fullName}
+} +``` + +References: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) diff --git a/skills/vercel-react-best-practices/rules/rerender-derived-state.md b/skills/vercel-react-best-practices/rules/rerender-derived-state.md new file mode 100644 index 00000000..e5c899f6 --- /dev/null +++ b/skills/vercel-react-best-practices/rules/rerender-derived-state.md @@ -0,0 +1,29 @@ +--- +title: Subscribe to Derived State +impact: MEDIUM +impactDescription: reduces re-render frequency +tags: rerender, derived-state, media-query, optimization +--- + +## Subscribe to Derived State + +Subscribe to derived boolean state instead of continuous values to reduce re-render frequency. + +**Incorrect (re-renders on every pixel change):** + +```tsx +function Sidebar() { + const width = useWindowWidth() // updates continuously + const isMobile = width < 768 + return +} +``` + +**Correct (re-renders only when boolean changes):** + +```tsx +function Sidebar() { + const isMobile = useMediaQuery('(max-width: 767px)') + return +} +``` diff --git a/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md b/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md new file mode 100644 index 00000000..b004ef45 --- /dev/null +++ b/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md @@ -0,0 +1,74 @@ +--- +title: Use Functional setState Updates +impact: MEDIUM +impactDescription: prevents stale closures and unnecessary callback recreations +tags: react, hooks, useState, useCallback, callbacks, closures +--- + +## Use Functional setState Updates + +When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references. + +**Incorrect (requires state as dependency):** + +```tsx +function TodoList() { + const [items, setItems] = useState(initialItems) + + // Callback must depend on items, recreated on every items change + const addItems = useCallback((newItems: Item[]) => { + setItems([...items, ...newItems]) + }, [items]) // ❌ items dependency causes recreations + + // Risk of stale closure if dependency is forgotten + const removeItem = useCallback((id: string) => { + setItems(items.filter(item => item.id !== id)) + }, []) // ❌ Missing items dependency - will use stale items! + + return{avatar}
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+ const id = useMemo(() => computeAvatarId(user), [user])
+ return
+
+ )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
diff --git a/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md b/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
new file mode 100644
index 00000000..dd58a1af
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
@@ -0,0 +1,45 @@
+---
+title: Put Interaction Logic in Event Handlers
+impact: MEDIUM
+impactDescription: avoids effect re-runs and duplicate side effects
+tags: rerender, useEffect, events, side-effects, dependencies
+---
+
+## Put Interaction Logic in Event Handlers
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect (event modeled as state + effect):**
+
+```tsx
+function Form() {
+ const [submitted, setSubmitted] = useState(false)
+ const theme = useContext(ThemeContext)
+
+ useEffect(() => {
+ if (submitted) {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+ }, [submitted, theme])
+
+ return
+}
+```
+
+**Correct (do it in the handler):**
+
+```tsx
+function Form() {
+ const theme = useContext(ThemeContext)
+
+ function handleSubmit() {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+
+ return
+}
+```
+
+Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
diff --git a/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md b/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md
new file mode 100644
index 00000000..d97592ac
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md
@@ -0,0 +1,82 @@
+---
+title: Don't Define Components Inside Components
+impact: HIGH
+impactDescription: prevents remount on every render
+tags: rerender, components, remount, performance
+---
+
+## Don't Define Components Inside Components
+
+**Impact: HIGH (prevents remount on every render)**
+
+Defining a component inside another component creates a new component type on every render. React sees a different component each time and fully remounts it, destroying all state and DOM.
+
+A common reason developers do this is to access parent variables without passing props. Always pass props instead.
+
+**Incorrect (remounts on every render):**
+
+```tsx
+function UserProfile({ user, theme }) {
+ // Defined inside to access `theme` - BAD
+ const Avatar = () => (
+
+ {user.followers} followers
+ {user.posts} posts
+
+ )
+
+ return (
+
+
+ )
+}
+```
+
+Every time `UserProfile` renders, `Avatar` and `Stats` are new component types. React unmounts the old instances and mounts new ones, losing any internal state, running effects again, and recreating DOM nodes.
+
+**Correct (pass props instead):**
+
+```tsx
+function Avatar({ src, theme }: { src: string; theme: string }) {
+ return (
+
+ {followers} followers
+ {posts} posts
+
+ )
+}
+
+function UserProfile({ user, theme }) {
+ return (
+
+
+ )
+}
+```
+
+**Symptoms of this bug:**
+- Input fields lose focus on every keystroke
+- Animations restart unexpectedly
+- `useEffect` cleanup/setup runs on every parent render
+- Scroll position resets inside the component
diff --git a/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md b/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
new file mode 100644
index 00000000..59dfab0f
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
@@ -0,0 +1,35 @@
+---
+title: Do not wrap a simple expression with a primitive result type in useMemo
+impact: LOW-MEDIUM
+impactDescription: wasted computation on every render
+tags: rerender, useMemo, optimization
+---
+
+## Do not wrap a simple expression with a primitive result type in useMemo
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+ const isLoading = useMemo(() => {
+ return user.isLoading || notifications.isLoading
+ }, [user.isLoading, notifications.isLoading])
+
+ if (isLoading) return
+ 
+ Hello World
+
,
+ { fonts: [{ name: 'Inter', data: fontData }] }
+ )
+}
+```
+
+**Correct: loads once at module initialization**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+// Module-level: runs ONCE when module is first imported
+const fontData = fetch(
+ new URL('./fonts/Inter.ttf', import.meta.url)
+).then(res => res.arrayBuffer())
+
+const logoData = fetch(
+ new URL('./images/logo.png', import.meta.url)
+).then(res => res.arrayBuffer())
+
+export async function GET(request: Request) {
+ // Await the already-started promises
+ const [font, logo] = await Promise.all([fontData, logoData])
+
+ return new ImageResponse(
+
+ 
+ Hello World
+
,
+ { fonts: [{ name: 'Inter', data: font }] }
+ )
+}
+```
+
+**Alternative: synchronous file reads with Node.js fs**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Synchronous read at module level - blocks only during module init
+const fontData = readFileSync(
+ join(process.cwd(), 'public/fonts/Inter.ttf')
+)
+
+const logoData = readFileSync(
+ join(process.cwd(), 'public/images/logo.png')
+)
+
+export async function GET(request: Request) {
+ return new ImageResponse(
+
+
+ Hello World
+
,
+ { fonts: [{ name: 'Inter', data: fontData }] }
+ )
+}
+```
+
+**General Node.js example: loading config or templates**
+
+```typescript
+// Incorrect: reads config on every call
+export async function processRequest(data: Data) {
+ const config = JSON.parse(
+ await fs.readFile('./config.json', 'utf-8')
+ )
+ const template = await fs.readFile('./template.html', 'utf-8')
+
+ return render(template, data, config)
+}
+
+// Correct: loads once at module level
+const configPromise = fs.readFile('./config.json', 'utf-8')
+ .then(JSON.parse)
+const templatePromise = fs.readFile('./template.html', 'utf-8')
+
+export async function processRequest(data: Data) {
+ const [config, template] = await Promise.all([
+ configPromise,
+ templatePromise
+ ])
+
+ return render(template, data, config)
+}
+```
+
+**When to use this pattern:**
+
+- Loading fonts for OG image generation
+- Loading static logos, icons, or watermarks
+- Reading configuration files that don't change at runtime
+- Loading email templates or other static templates
+- Any static asset that's the same across all requests
+
+**When NOT to use this pattern:**
+
+- Assets that vary per request or user
+- Files that may change during runtime (use caching with TTL instead)
+- Large files that would consume too much memory if kept loaded
+- Sensitive data that shouldn't persist in memory
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** Module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
+
+**In traditional serverless:** Each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.
diff --git a/skills/vercel-react-best-practices/rules/server-parallel-fetching.md b/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
new file mode 100644
index 00000000..1affc835
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+ const header = await fetchHeader()
+ return (
+
+
+ )
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {header}
+ {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+
+export default function Page() {
+ return (
+
+
+ )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+
+function Layout({ children }: { children: ReactNode }) {
+ return (
+
+
+ )
+}
+
+export default function Page() {
+ return (
+ {user.name}
// uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+ const user = await fetchUser()
+ return {name}
+}
+```
diff --git a/skills/vercel-react-native-skills/AGENTS.md b/skills/vercel-react-native-skills/AGENTS.md
new file mode 100644
index 00000000..d263eb9c
--- /dev/null
+++ b/skills/vercel-react-native-skills/AGENTS.md
@@ -0,0 +1,2897 @@
+# React Native Skills
+
+**Version 1.0.0**
+Engineering
+January 2026
+
+> **Note:**
+> This document is mainly for agents and LLMs to follow when maintaining,
+> generating, or refactoring React Native codebases. Humans
+> may also find it useful, but guidance here is optimized for automation
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive performance optimization guide for React Native applications, designed for AI agents and LLMs. Contains 35+ rules across 13 categories, prioritized by impact from critical (core rendering, list performance) to incremental (fonts, imports). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+
+---
+
+## Table of Contents
+
+1. [Core Rendering](#1-core-rendering) — **CRITICAL**
+ - 1.1 [Never Use && with Potentially Falsy Values](#11-never-use--with-potentially-falsy-values)
+ - 1.2 [Wrap Strings in Text Components](#12-wrap-strings-in-text-components)
+2. [List Performance](#2-list-performance) — **HIGH**
+ - 2.1 [Avoid Inline Objects in renderItem](#21-avoid-inline-objects-in-renderitem)
+ - 2.2 [Hoist callbacks to the root of lists](#22-hoist-callbacks-to-the-root-of-lists)
+ - 2.3 [Keep List Items Lightweight](#23-keep-list-items-lightweight)
+ - 2.4 [Optimize List Performance with Stable Object References](#24-optimize-list-performance-with-stable-object-references)
+ - 2.5 [Pass Primitives to List Items for Memoization](#25-pass-primitives-to-list-items-for-memoization)
+ - 2.6 [Use a List Virtualizer for Any List](#26-use-a-list-virtualizer-for-any-list)
+ - 2.7 [Use Compressed Images in Lists](#27-use-compressed-images-in-lists)
+ - 2.8 [Use Item Types for Heterogeneous Lists](#28-use-item-types-for-heterogeneous-lists)
+3. [Animation](#3-animation) — **HIGH**
+ - 3.1 [Animate Transform and Opacity Instead of Layout Properties](#31-animate-transform-and-opacity-instead-of-layout-properties)
+ - 3.2 [Prefer useDerivedValue Over useAnimatedReaction](#32-prefer-usederivedvalue-over-useanimatedreaction)
+ - 3.3 [Use GestureDetector for Animated Press States](#33-use-gesturedetector-for-animated-press-states)
+4. [Scroll Performance](#4-scroll-performance) — **HIGH**
+ - 4.1 [Never Track Scroll Position in useState](#41-never-track-scroll-position-in-usestate)
+5. [Navigation](#5-navigation) — **HIGH**
+ - 5.1 [Use Native Navigators for Navigation](#51-use-native-navigators-for-navigation)
+6. [React State](#6-react-state) — **MEDIUM**
+ - 6.1 [Minimize State Variables and Derive Values](#61-minimize-state-variables-and-derive-values)
+ - 6.2 [Use fallback state instead of initialState](#62-use-fallback-state-instead-of-initialstate)
+ - 6.3 [useState Dispatch updaters for State That Depends on Current Value](#63-usestate-dispatch-updaters-for-state-that-depends-on-current-value)
+7. [State Architecture](#7-state-architecture) — **MEDIUM**
+ - 7.1 [State Must Represent Ground Truth](#71-state-must-represent-ground-truth)
+8. [React Compiler](#8-react-compiler) — **MEDIUM**
+ - 8.1 [Destructure Functions Early in Render (React Compiler)](#81-destructure-functions-early-in-render-react-compiler)
+ - 8.2 [Use .get() and .set() for Reanimated Shared Values (not .value)](#82-use-get-and-set-for-reanimated-shared-values-not-value)
+9. [User Interface](#9-user-interface) — **MEDIUM**
+ - 9.1 [Measuring View Dimensions](#91-measuring-view-dimensions)
+ - 9.2 [Modern React Native Styling Patterns](#92-modern-react-native-styling-patterns)
+ - 9.3 [Use contentInset for Dynamic ScrollView Spacing](#93-use-contentinset-for-dynamic-scrollview-spacing)
+ - 9.4 [Use contentInsetAdjustmentBehavior for Safe Areas](#94-use-contentinsetadjustmentbehavior-for-safe-areas)
+ - 9.5 [Use expo-image for Optimized Images](#95-use-expo-image-for-optimized-images)
+ - 9.6 [Use Galeria for Image Galleries and Lightbox](#96-use-galeria-for-image-galleries-and-lightbox)
+ - 9.7 [Use Native Menus for Dropdowns and Context Menus](#97-use-native-menus-for-dropdowns-and-context-menus)
+ - 9.8 [Use Native Modals Over JS-Based Bottom Sheets](#98-use-native-modals-over-js-based-bottom-sheets)
+ - 9.9 [Use Pressable Instead of Touchable Components](#99-use-pressable-instead-of-touchable-components)
+10. [Design System](#10-design-system) — **MEDIUM**
+ - 10.1 [Use Compound Components Over Polymorphic Children](#101-use-compound-components-over-polymorphic-children)
+11. [Monorepo](#11-monorepo) — **LOW**
+ - 11.1 [Install Native Dependencies in App Directory](#111-install-native-dependencies-in-app-directory)
+ - 11.2 [Use Single Dependency Versions Across Monorepo](#112-use-single-dependency-versions-across-monorepo)
+12. [Third-Party Dependencies](#12-third-party-dependencies) — **LOW**
+ - 12.1 [Import from Design System Folder](#121-import-from-design-system-folder)
+13. [JavaScript](#13-javascript) — **LOW**
+ - 13.1 [Hoist Intl Formatter Creation](#131-hoist-intl-formatter-creation)
+14. [Fonts](#14-fonts) — **LOW**
+ - 14.1 [Load fonts natively at build time](#141-load-fonts-natively-at-build-time)
+
+---
+
+## 1. Core Rendering
+
+**Impact: CRITICAL**
+
+Fundamental React Native rendering rules. Violations cause
+runtime crashes or broken UI.
+
+### 1.1 Never Use && with Potentially Falsy Values
+
+**Impact: CRITICAL (prevents production crash)**
+
+Never use `{value &&
+
+
+
+
+ {Array.from({ length: 4 }).map((_, i) => (
+
+
+
+
+
+ );
+}
diff --git a/src/app/chat/page.tsx b/src/app/chat/page.tsx
new file mode 100644
index 00000000..669bdc9a
--- /dev/null
+++ b/src/app/chat/page.tsx
@@ -0,0 +1,44 @@
+import { AppSidebar } from "@/components/app-sidebar";
+import { ChatInterface } from "@/components/chat/chat-interface";
+import { SiteHeader } from "@/components/site-header";
+import {
+ SidebarInset,
+ SidebarProvider,
+} from "@/components/ui/sidebar";
+import { getServerSession } from "next-auth";
+import { authOptions } from "@/lib/auth";
+import { redirect } from "next/navigation";
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+ title: "AI Chat",
+ description: "Chat with an AI assistant powered by Ollama",
+};
+
+export default async function ChatPage() {
+ const session = await getServerSession(authOptions);
+ if (!session?.user) {
+ redirect("/login");
+ }
+
+ return (
+
+
+ ))}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + AI Settings +
++ Configure your Ollama connection, model, and chat behavior. + Settings are saved per-user and encrypted at rest. +
+
+
+ );
+ }
+
+ return (
+
+ {/* Connection Settings */}
+
+
+ Connection
+
+ Configure how StormCom connects to your Ollama instance. For Ollama
+ Cloud, create an API key at{" "}
+
+ ollama.com/settings/keys
+
+ .
+
+
+
+ {/* Cloud toggle */}
+
+
+
+
+
+
+ {models.length > 0 ? (
+
+
+
+ {/* Behavior Settings */}
+
+
+ Behavior
+
+ Fine-tune how the AI assistant responds
+
+
+
+ {/* System Prompt */}
+
+
+
+
+
+
+ + Use Ollama's cloud API for larger models +
+
+
+ setHost(e.target.value)}
+ placeholder={isCloudMode ? "https://ollama.com" : "http://localhost:11434"}
+ />
+
+
+ {/* API Key (Cloud only) */}
+ {isCloudMode && (
+ + {isCloudMode + ? "The Ollama Cloud API endpoint" + : "Your local Ollama server address"} +
+
+
+ )}
+
+
+
+ {config?.hasApiKey && (
+
+
+ )}
+
+ {
+ setApiKey(e.target.value);
+ if (e.target.value.trim().length > 0) {
+ setClearSavedApiKey(false);
+ }
+ }}
+ placeholder={
+ config?.hasApiKey
+ ? "•••••••• (leave blank to keep current key)"
+ : "Enter your Ollama API key"
+ }
+ />
+ {config?.hasApiKey && (
+
+
+ )}
+ + {clearSavedApiKey + ? "Saved API key will be removed when you click Save Settings." + : "A key is already stored. You can keep, replace, or remove it."} +
+ ++ Your API key is encrypted before storage and never exposed to the browser. +
+
+
+ {testResult && (
+
+
+
+ )}
+ {testResult.message}
+ {testResult.latencyMs !== undefined && ( ++ Latency: {testResult.latencyMs}ms +
+ )} + {testResult.models && testResult.models.length > 0 && ( ++ Models: {testResult.models.join(", ")} +
+ )} +
+
+
+ Model
+
+ Choose the AI model used for chat responses
+
+
+
+
+
+
+
+ ) : (
+
+
+ setModel(e.target.value)}
+ placeholder="llama3.2"
+ />
+
+ )}
+
+ + Click "Refresh Models" to see available models, or type a model name + manually. +
+
+
+
+
+
+ {modelDetailsLoading && (
+
+
+
+ {modelDetailsError ? (
+ {modelDetailsError}
+ ) : null} + + {modelDetails ? ( +
+
+ ) : (
+
+
+
+ {modelDetails.capabilities && modelDetails.capabilities.length > 0 ? (
+ + Family:{" "} + {modelDetails.details.family || "Unknown"} +
++ Parameters:{" "} + {modelDetails.details.parameterSize || "Unknown"} +
++ Format:{" "} + {modelDetails.details.format || "Unknown"} +
++ Quantization:{" "} + {modelDetails.details.quantizationLevel || "Unknown"} +
+
+
+ ) : (
+ Capabilities
+
+ {modelDetails.capabilities.map((capability) => (
+
+ {capability}
+
+ ))}
+
+ No capabilities metadata reported by Ollama for this model.
+ )} +Select or type a model name to view metadata and capabilities.
+ )} +
+
+
+
+
+
+ + Manage models on the configured Ollama host (pull, alias/copy, delete). +
+
+
+
+
+
+
+
+ setPullModelName(event.target.value)}
+ placeholder="e.g. qwen3:8b"
+ disabled={modelActionLoading}
+ />
+
+
+
+
+
+
+
+ setCopySourceModel(event.target.value)}
+ placeholder="Existing model name"
+ disabled={modelActionLoading}
+ />
+
+
+
+ setCopyDestinationModel(event.target.value)}
+ placeholder="New alias/model name"
+ disabled={modelActionLoading}
+ />
+
+
+
+
+
+
+
+ {modelActionError ? (
+ {modelActionError}
+ ) : null} + {modelActionMessage ? ( +{modelActionMessage}
+ ) : null} +
+
+
+
+
+