agent-skill-kit 3.9.135

package/.agent/skills/react-pro/rules/hooks-custom.md

@@ -0,0 +1,61 @@
+---
+title: "Custom Hooks Patterns"
+impact: MEDIUM
+impactDescription: "Reusable hooks reduce duplication and improve testability"
+tags: hooks, useDebounce, useLocalStorage, custom
+---
+
+# Custom Hooks Patterns
+
+> Reusable hooks for common patterns: debounce, localStorage, and more.
+
+---
+
+## useDebounce
+
+```tsx
+function useDebounce<T>(value: T, delay = 300): T {
+  const [debounced, setDebounced] = useState(value)
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay)
+    return () => clearTimeout(timer)
+  }, [value, delay])
+  return debounced
+}
+```
+
+## useLocalStorage
+
+```tsx
+function useLocalStorage<T>(key: string, initial: T) {
+  const [value, setValue] = useState<T>(() => {
+    try {
+      const stored = localStorage.getItem(key)
+      return stored ? JSON.parse(stored) : initial
+    } catch {
+      return initial
+    }
+  })
+
+  useEffect(() => {
+    localStorage.setItem(key, JSON.stringify(value))
+  }, [key, value])
+
+  return [value, setValue] as const
+}
+```
+
+## Usage
+
+```tsx
+function SearchPage() {
+  const [query, setQuery] = useState('')
+  const debouncedQuery = useDebounce(query, 500)
+  const [theme, setTheme] = useLocalStorage('theme', 'dark')
+  // ...
+}
+```
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/mui-styling.md

@@ -0,0 +1,138 @@
+---
+name: mui-styling
+description: MUI v7 styling — sx prop, Grid size syntax, inline vs separate files, theme access
+title: "MUI v7 Styling"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: mui, styling
+---
+
+# MUI v7 Styling
+
+> sx prop for styling, Grid with size prop, inline vs separate files.
+
+---
+
+## sx Prop Pattern
+
+```typescript
+import { Box, Paper } from '@mui/material';
+import type { SxProps, Theme } from '@mui/material';
+
+// Define styles object
+const styles: Record<string, SxProps<Theme>> = {
+  container: {
+    p: 2,
+    bgcolor: 'background.paper',
+    borderRadius: 2,
+  },
+  header: {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    mb: 3,
+  },
+  content: {
+    p: 3,
+    minHeight: 200,
+  },
+};
+
+// Apply in component
+<Box sx={styles.container}>
+  <Box sx={styles.header}>Header</Box>
+  <Paper sx={styles.content}>Content</Paper>
+</Box>
+```
+
+---
+
+## MUI v7 Grid (Breaking Change!)
+
+```typescript
+import { Grid } from '@mui/material';
+
+// ✅ MUI v7 syntax
+<Grid container spacing={2}>
+  <Grid size={{ xs: 12, md: 6, lg: 4 }}>
+    <Paper>Item 1</Paper>
+  </Grid>
+  <Grid size={{ xs: 12, md: 6, lg: 4 }}>
+    <Paper>Item 2</Paper>
+  </Grid>
+</Grid>
+
+// ❌ OLD syntax (wrong in v7)
+<Grid xs={12} md={6}>  // DON'T USE
+```
+
+---
+
+## Inline vs Separate Styles
+
+| Lines | Location |
+|-------|----------|
+| <100 | Inline in component file |
+| >100 | Separate `.styles.ts` file |
+
+```typescript
+// MyComponent.styles.ts (for >100 lines)
+import type { SxProps, Theme } from '@mui/material';
+
+export const styles: Record<string, SxProps<Theme>> = {
+  container: { ... },
+  header: { ... },
+  // ... many more styles
+};
+```
+
+```typescript
+// MyComponent.tsx
+import { styles } from './MyComponent.styles';
+
+<Box sx={styles.container}>
+```
+
+---
+
+## Theme Access
+
+```typescript
+// Access theme in sx
+sx={{
+  bgcolor: 'primary.main',
+  color: 'text.secondary',
+  p: theme => theme.spacing(2),
+  
+  // Responsive
+  width: { xs: '100%', md: '50%' },
+}}
+```
+
+---
+
+## Common sx Properties
+
+| Short | CSS Property |
+|-------|--------------|
+| `p` | padding |
+| `m` | margin |
+| `px`, `py` | padding x/y |
+| `mx`, `my` | margin x/y |
+| `bgcolor` | backgroundColor |
+| `display` | display |
+| `gap` | gap |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [component-patterns.md](component-patterns.md) | Component structure with MUI |
+| [performance.md](performance.md) | Lazy load heavy MUI components |
+| [../SKILL.md](../SKILL.md) | MUI v7 Grid breaking change |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/patterns.md

@@ -0,0 +1,24 @@
+---
+title: "React Advanced Patterns (Deprecated)"
+impact: MEDIUM
+impactDescription: "This file has been split into focused rule files"
+tags: deprecated, redirect
+---
+
+# React Advanced Patterns — DEPRECATED
+
+> This file has been split into focused rule files. Read the individual files instead.
+
+| Old Section | New File |
+|-------------|----------|
+| React 19 Patterns | [react19-hooks.md](react19-hooks.md) |
+| Composition Patterns | [composition-compound.md](composition-compound.md) |
+| State Management | [state-management.md](state-management.md) |
+| Error Boundary | [error-boundary.md](error-boundary.md) |
+| Custom Hooks | [hooks-custom.md](hooks-custom.md) |
+| Performance | [performance-optimization.md](performance-optimization.md) |
+| Testing | [testing-patterns.md](testing-patterns.md) |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/performance-optimization.md

@@ -0,0 +1,65 @@
+---
+title: "React Performance Optimization"
+impact: HIGH
+impactDescription: "2-10× improvement in rendering with proper optimization"
+tags: performance, virtual, memo, lazy, bundle
+---
+
+# React Performance Optimization
+
+> Priority-based performance optimization: waterfalls → bundle → re-renders → lists.
+
+---
+
+## Priority Matrix
+
+| Priority | Category | Action |
+|:--------:|----------|--------|
+| 1 | Eliminate waterfalls | `Promise.all()`, parallel fetch, Suspense streaming |
+| 2 | Bundle size | Direct imports (no barrels), `dynamic()`, lazy load |
+| 3 | Re-renders | React Compiler (19), then `useMemo`/`useCallback` |
+| 4 | Large lists | Virtualize with `@tanstack/react-virtual` |
+
+## Virtualized List (10K+ items)
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual'
+
+function VirtualList({ items }: { items: Item[] }) {
+  const parentRef = useRef<HTMLDivElement>(null)
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 50,
+  })
+
+  return (
+    <div ref={parentRef} style={{ height: 400, overflow: 'auto' }}>
+      <div style={{ height: virtualizer.getTotalSize() }}>
+        {virtualizer.getVirtualItems().map(row => (
+          <div key={row.key} style={{
+            position: 'absolute',
+            top: row.start,
+            height: row.size,
+            width: '100%',
+          }}>
+            {items[row.index].name}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+```
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Premature `useMemo`/`useCallback` | Profile first (React Compiler handles most) |
+| Barrel file re-exports | Direct imports for smaller bundles |
+| God components (> 300 lines) | Split at 150 lines |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/performance.md

@@ -0,0 +1,137 @@
+---
+name: performance
+description: React performance — lazy loading, React.memo, useMemo, useCallback, bundle analysis
+title: "Performance Optimization"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: performance
+---
+
+# Performance Optimization
+
+> Lazy load heavy components, memoize expensive computations.
+
+---
+
+## Lazy Loading
+
+```typescript
+import React, { lazy } from 'react';
+import { SuspenseLoader } from '~components/SuspenseLoader';
+
+// Lazy load heavy components
+const DataGrid = lazy(() => 
+  import('@mui/x-data-grid').then(m => ({ default: m.DataGrid }))
+);
+const RichTextEditor = lazy(() => import('./RichTextEditor'));
+const ChartComponent = lazy(() => import('./Chart'));
+
+// Usage with SuspenseLoader
+<SuspenseLoader>
+  <DataGrid rows={data} columns={columns} />
+</SuspenseLoader>
+```
+
+---
+
+## What to Lazy Load
+
+| Component Type | Lazy Load? |
+|----------------|------------|
+| DataGrid, Tables | ✅ Yes |
+| Charts (Recharts, Chart.js) | ✅ Yes |
+| Rich Text Editors | ✅ Yes |
+| Code Editors (Monaco) | ✅ Yes |
+| Map Components | ✅ Yes |
+| Dialog/Modal content | ✅ Yes |
+| Simple buttons, inputs | ❌ No |
+| Layout components | ❌ No |
+
+---
+
+## useMemo
+
+```typescript
+import { useMemo } from 'react';
+
+// ✅ Expensive computation
+const filteredData = useMemo(() => {
+  return data
+    .filter(item => item.status === filter)
+    .sort((a, b) => b.date - a.date)
+    .map(item => ({ ...item, computed: heavyFn(item) }));
+}, [data, filter]);
+
+// ❌ Don't memoize simple values
+const label = `Hello ${name}`; // No useMemo needed
+```
+
+---
+
+## useCallback
+
+```typescript
+import { useCallback } from 'react';
+
+// ✅ Handler passed to children
+const handleClick = useCallback(() => {
+  console.log('clicked');
+}, []);
+
+<MemoizedChild onClick={handleClick} />
+
+// ❌ Inline handler (no memoization needed)
+<button onClick={() => setOpen(true)}>
+```
+
+---
+
+## React.memo
+
+```typescript
+import React from 'react';
+
+// For expensive pure components
+const ExpensiveList = React.memo(({ items }) => {
+  return items.map(item => <ExpensiveItem key={item.id} item={item} />);
+});
+
+// With custom comparison
+const OptimizedComponent = React.memo(
+  ({ data }) => <div>{data.value}</div>,
+  (prevProps, nextProps) => prevProps.data.id === nextProps.data.id
+);
+```
+
+---
+
+## Bundle Analysis
+
+```bash
+# Vite bundle analyzer
+npm install -D rollup-plugin-visualizer
+
+# In vite.config.ts
+import { visualizer } from 'rollup-plugin-visualizer';
+
+plugins: [
+  visualizer({ open: true })
+]
+
+# Build and analyze
+npm run build
+```
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [component-patterns.md](component-patterns.md) | useCallback rules for components |
+| [data-fetching.md](data-fetching.md) | Query caching for performance |
+| [../SKILL.md](../SKILL.md) | Lazy load heavy components rule |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/react19-hooks.md

@@ -0,0 +1,85 @@
+---
+title: "React 19 Patterns"
+impact: HIGH
+impactDescription: "React 19 introduces useActionState and useOptimistic for modern form handling"
+tags: react19, useActionState, useOptimistic, forms
+---
+
+# React 19 Patterns
+
+> Modern React 19 hooks for form submissions and optimistic UI updates.
+
+---
+
+## useActionState (Form Submissions)
+
+```tsx
+import { useActionState } from 'react'
+
+async function createUser(prev: State, formData: FormData) {
+  const name = formData.get('name') as string
+  const res = await fetch('/api/users', {
+    method: 'POST',
+    body: JSON.stringify({ name }),
+    headers: { 'Content-Type': 'application/json' },
+  })
+  if (!res.ok) return { error: 'Failed to create user' }
+  return { error: null, success: true }
+}
+
+type State = { error: string | null; success?: boolean }
+
+function CreateUserForm() {
+  const [state, action, isPending] = useActionState(createUser, { error: null })
+
+  return (
+    <form action={action}>
+      <input name="name" required disabled={isPending} />
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create User'}
+      </button>
+      {state.error && <p className="error">{state.error}</p>}
+      {state.success && <p className="success">User created!</p>}
+    </form>
+  )
+}
+```
+
+## useOptimistic (Instant UI Updates)
+
+```tsx
+import { useOptimistic } from 'react'
+
+function TodoList({ todos }: { todos: Todo[] }) {
+  const [optimisticTodos, addOptimistic] = useOptimistic(
+    todos,
+    (current, newTodo: Todo) => [...current, newTodo]
+  )
+
+  async function handleAdd(formData: FormData) {
+    const title = formData.get('title') as string
+    const tempTodo = { id: crypto.randomUUID(), title, completed: false }
+
+    addOptimistic(tempTodo)  // Instant UI update
+    await createTodo(title)  // Server call (may fail → reverts automatically)
+  }
+
+  return (
+    <div>
+      <form action={handleAdd}>
+        <input name="title" required />
+        <button type="submit">Add</button>
+      </form>
+      <ul>
+        {optimisticTodos.map(todo => (
+          <li key={todo.id}>{todo.title}</li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/state-management.md

@@ -0,0 +1,90 @@
+---
+title: "Zustand & React Query State Management"
+impact: HIGH
+impactDescription: "Proper state management prevents prop drilling and ensures data consistency"
+tags: zustand, react-query, tanstack, state, global
+---
+
+# State Management Patterns
+
+> Zustand for global client state, React Query for server state.
+
+---
+
+## Zustand (Global State)
+
+```tsx
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+
+interface AuthStore {
+  user: User | null
+  token: string | null
+  login: (email: string, password: string) => Promise<void>
+  logout: () => void
+}
+
+const useAuthStore = create<AuthStore>()(
+  persist(
+    (set) => ({
+      user: null,
+      token: null,
+      login: async (email, password) => {
+        const res = await fetch('/api/auth/login', {
+          method: 'POST',
+          body: JSON.stringify({ email, password }),
+          headers: { 'Content-Type': 'application/json' },
+        })
+        const { user, token } = await res.json()
+        set({ user, token })
+      },
+      logout: () => set({ user: null, token: null }),
+    }),
+    { name: 'auth-storage' }
+  )
+)
+
+// Usage — auto re-renders on change
+function NavBar() {
+  const { user, logout } = useAuthStore()
+  if (!user) return <LoginButton />
+  return <button onClick={logout}>{user.name}</button>
+}
+```
+
+## React Query (Server State)
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+
+function UserList() {
+  const { data: users, isLoading, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: () => fetch('/api/users').then(r => r.json()),
+    staleTime: 5 * 60 * 1000, // 5 min cache
+  })
+
+  const queryClient = useQueryClient()
+  const createUser = useMutation({
+    mutationFn: (data: UserCreate) =>
+      fetch('/api/users', { method: 'POST', body: JSON.stringify(data) }).then(r => r.json()),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+  })
+
+  if (isLoading) return <Skeleton />
+  if (error) return <ErrorMessage error={error} />
+
+  return (
+    <div>
+      {users.map((u: User) => <UserCard key={u.id} user={u} />)}
+      <button onClick={() => createUser.mutate({ name: 'New User' })}>
+        {createUser.isPending ? 'Creating...' : 'Add User'}
+      </button>
+    </div>
+  )
+}
+```
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/testing-patterns.md

@@ -0,0 +1,52 @@
+---
+title: "React Testing Patterns"
+impact: MEDIUM
+impactDescription: "Proper testing ensures component correctness and prevents regressions"
+tags: testing, react-testing-library, userEvent, AAA
+---
+
+# React Testing Patterns
+
+> AAA pattern (Arrange-Act-Assert) with React Testing Library and userEvent.
+
+---
+
+## Component Testing
+
+```tsx
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+test('creates user on form submit', async () => {
+  const user = userEvent.setup()
+  render(<CreateUserForm />)
+
+  await user.type(screen.getByRole('textbox', { name: /name/i }), 'John')
+  await user.click(screen.getByRole('button', { name: /create/i }))
+
+  expect(await screen.findByText(/user created/i)).toBeInTheDocument()
+})
+
+test('shows error on failed submission', async () => {
+  server.use(http.post('/api/users', () => HttpResponse.json({}, { status: 500 })))
+  const user = userEvent.setup()
+  render(<CreateUserForm />)
+
+  await user.type(screen.getByRole('textbox', { name: /name/i }), 'John')
+  await user.click(screen.getByRole('button', { name: /create/i }))
+
+  expect(await screen.findByText(/failed/i)).toBeInTheDocument()
+})
+```
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| `useEffect` for data fetching | React Query / use() / Server Components |
+| Index as key in dynamic lists | Stable unique ID |
+| Prop drill > 3 levels | Compound components or Zustand |
+
+---
+
+⚡ PikaKit v3.9.134