@yuaone/core 0.3.3 → 0.4.0

package/plugins/react/patterns/anti-patterns.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://yuaone.com/schemas/patterns.json",
+  "name": "React Anti-Patterns",
+  "version": "1.0.0",
+  "description": "Common React anti-patterns to detect and warn about",
+  "patterns": [
+    {
+      "id": "index-as-key",
+      "name": "Array Index as Key",
+      "description": "Using array index as key in lists causes bugs when items are reordered, inserted, or deleted.",
+      "detect": "\\.map\\s*\\(\\s*\\([^,)]+,\\s*(\\w+)\\)\\s*=>.*key\\s*=\\s*\\{\\s*\\1\\s*\\}",
+      "action": "warn",
+      "template": "// BAD: key={index}\nitems.map((item, index) => <Item key={index} />)\n\n// GOOD: key={item.id}\nitems.map(item => <Item key={item.id} />)\n\n// If no ID, generate one at creation time:\nconst newItem = { id: crypto.randomUUID(), ...data };"
+    },
+    {
+      "id": "use-effect-no-deps",
+      "name": "useEffect Without Dependency Array",
+      "description": "useEffect without dependency array runs on EVERY render. Usually a bug.",
+      "detect": "useEffect\\(\\s*\\(\\)\\s*=>\\s*\\{[^}]+\\}\\s*\\)\\s*;",
+      "action": "warn",
+      "template": "// BAD: runs every render\nuseEffect(() => { fetchData(); });\n\n// GOOD: runs once on mount\nuseEffect(() => { fetchData(); }, []);\n\n// GOOD: runs when dependency changes\nuseEffect(() => { fetchData(id); }, [id]);"
+    },
+    {
+      "id": "props-in-state",
+      "name": "Copying Props into State",
+      "description": "Copying props into state creates a stale data source. Compute derived values directly from props.",
+      "detect": "useState\\(\\s*props\\.|const\\s*\\[\\w+,\\s*set\\w+\\]\\s*=\\s*useState\\(\\w+\\)",
+      "action": "warn",
+      "template": "// BAD: derived state from props\nfunction UserGreeting({ user }) {\n  const [name, setName] = useState(user.name); // Stale!\n  return <h1>{name}</h1>;\n}\n\n// GOOD: compute directly from props\nfunction UserGreeting({ user }) {\n  const displayName = user.name.toUpperCase(); // Always fresh\n  return <h1>{displayName}</h1>;\n}\n\n// Exception: only use state for props as initial values\nfunction EditableField({ initialValue }) {\n  const [value, setValue] = useState(initialValue);\n  // User edits diverge from initial value intentionally\n}"
+    },
+    {
+      "id": "direct-dom-manipulation",
+      "name": "Direct DOM Manipulation",
+      "description": "Avoid direct DOM manipulation (querySelector, getElementById, innerHTML). Use refs and React state.",
+      "detect": "document\\.(querySelector|getElementById|getElementsBy|createElement)|innerHTML\\s*=",
+      "action": "warn",
+      "template": "// BAD: direct DOM manipulation\ndocument.getElementById('title').textContent = 'Hello';\ndocument.querySelector('.list').innerHTML = '<li>item</li>';\n\n// GOOD: use React state and refs\nconst [title, setTitle] = useState('Hello');\nconst listRef = useRef<HTMLUListElement>(null);\nreturn (\n  <>\n    <h1>{title}</h1>\n    <ul ref={listRef}>{items.map(i => <li key={i.id}>{i.name}</li>)}</ul>\n  </>\n);"
+    },
+    {
+      "id": "dangerous-inner-html",
+      "name": "dangerouslySetInnerHTML Without Sanitization",
+      "description": "Using dangerouslySetInnerHTML without sanitization exposes XSS vulnerabilities.",
+      "detect": "dangerouslySetInnerHTML\\s*=\\s*\\{\\s*\\{\\s*__html",
+      "action": "warn",
+      "template": "// BAD: unsanitized HTML\n<div dangerouslySetInnerHTML={{ __html: userInput }} />\n\n// GOOD: sanitize with DOMPurify\nimport DOMPurify from 'dompurify';\n<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userInput) }} />\n\n// BETTER: use a markdown renderer or structured content\nimport ReactMarkdown from 'react-markdown';\n<ReactMarkdown>{userContent}</ReactMarkdown>"
+    },
+    {
+      "id": "prop-drilling-deep",
+      "name": "Deep Prop Drilling",
+      "description": "Passing props through 3+ levels of components that don't use them. Use context or composition.",
+      "detect": "\\{\\s*\\.{3}props\\s*\\}|\\{\\s*\\.{3}rest\\s*\\}",
+      "action": "warn",
+      "template": "// BAD: prop drilling through intermediate components\n<App theme={theme}>\n  <Layout theme={theme}>\n    <Sidebar theme={theme}>\n      <NavItem theme={theme} /> {/* Only NavItem needs theme */}\n    </Sidebar>\n  </Layout>\n</App>\n\n// GOOD: use context\nconst ThemeContext = createContext<Theme>(defaultTheme);\n\n// Provider at top:\n<ThemeContext.Provider value={theme}><App /></ThemeContext.Provider>\n\n// Consumer where needed:\nfunction NavItem() {\n  const theme = useContext(ThemeContext);\n}\n\n// ALSO GOOD: composition\n<Layout sidebar={<Sidebar><NavItem theme={theme} /></Sidebar>} />"
+    },
+    {
+      "id": "use-effect-in-render",
+      "name": "Side Effect in Render Body",
+      "description": "Side effects (API calls, subscriptions, mutations) should be in useEffect, not in the render body.",
+      "detect": "function\\s+\\w+.*\\{[^}]*(fetch\\(|axios\\.|console\\.log|document\\.|window\\.addEventListener)",
+      "action": "warn",
+      "template": "// BAD: side effect during render\nfunction UserProfile({ id }) {\n  fetch(`/api/users/${id}`); // Runs EVERY render!\n  const data = localStorage.getItem('user'); // SSR unsafe!\n}\n\n// GOOD: side effect in useEffect\nfunction UserProfile({ id }) {\n  const [data, setData] = useState(null);\n  useEffect(() => {\n    fetch(`/api/users/${id}`).then(r => r.json()).then(setData);\n  }, [id]);\n}"
+    },
+    {
+      "id": "conditional-hook",
+      "name": "Conditional Hook Call",
+      "description": "Hooks must not be called conditionally, inside loops, or after early returns. React relies on call order.",
+      "detect": "if\\s*\\([^)]*\\)\\s*\\{[^}]*(useState|useEffect|useCallback|useMemo|useRef|useContext|useReducer)",
+      "action": "warn",
+      "template": "// BAD: hook inside condition\nif (isLoggedIn) {\n  const [user, setUser] = useState(null); // Breaks Rules of Hooks!\n}\n\n// GOOD: always call, conditionally use\nconst [user, setUser] = useState<User | null>(null);\nuseEffect(() => {\n  if (isLoggedIn) fetchUser().then(setUser);\n}, [isLoggedIn]);\n\n// ALSO GOOD: split into a separate component\n{isLoggedIn && <AuthenticatedSection />}"
+    },
+    {
+      "id": "new-object-in-jsx",
+      "name": "New Object/Array Literal in JSX Props",
+      "description": "Creating objects or arrays inline in JSX causes unnecessary re-renders of child components.",
+      "detect": "<\\w+[^>]*\\b(style|className|options|data|config)\\s*=\\s*\\{\\s*(\\{|\\[)",
+      "action": "warn",
+      "template": "// BAD: new object every render\n<Avatar style={{ width: 50, height: 50 }} />\n<Select options={[{ value: 'a' }, { value: 'b' }]} />\n\n// GOOD: hoist to module scope (static values)\nconst avatarStyle = { width: 50, height: 50 } as const;\nconst options = [{ value: 'a' }, { value: 'b' }] as const;\n\n// GOOD: useMemo for dynamic values\nconst style = useMemo(() => ({ width: size, height: size }), [size]);"
+    },
+    {
+      "id": "missing-error-boundary",
+      "name": "Missing Error Boundary",
+      "description": "Components that fetch data or render dynamic content should be wrapped in an error boundary.",
+      "detect": "throw\\s+new\\s+Error|Promise\\.reject|catch\\s*\\(.*\\{\\s*throw",
+      "action": "warn",
+      "template": "// BAD: unhandled error crashes entire app\n<App>\n  <DataComponent /> {/* If this throws, entire app crashes */}\n</App>\n\n// GOOD: error boundary around risky components\n<App>\n  <ErrorBoundary fallback={<ErrorFallback />}>\n    <DataComponent />\n  </ErrorBoundary>\n</App>\n\n// In Next.js App Router, use error.tsx for route-level error boundaries"
+    }
+  ]
+}

package/plugins/react/patterns/components.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://yuaone.com/schemas/patterns.json",
+  "name": "React Component Patterns",
+  "version": "1.0.0",
+  "description": "Common React component patterns for detection and suggestion",
+  "patterns": [
+    {
+      "id": "compound-component",
+      "name": "Compound Component",
+      "description": "Parent provides context, children consume it. Great for Select, Tabs, Accordion, Menu.",
+      "detect": "(createContext|useContext).*\\.(Provider|Consumer)",
+      "action": "suggest",
+      "template": "const {Name}Context = createContext<{Name}ContextType | null>(null);\n\nfunction use{Name}Context() {\n  const ctx = useContext({Name}Context);\n  if (!ctx) throw new Error('{Name} compound components must be used within <{Name}>');\n  return ctx;\n}\n\nfunction {Name}({ children }: { children: React.ReactNode }) {\n  const [state, setState] = useState(initialState);\n  return (\n    <{Name}Context.Provider value={{ state, setState }}>\n      {children}\n    </{Name}Context.Provider>\n  );\n}\n\n{Name}.Item = function {Name}Item({ value }: { value: string }) {\n  const { state, setState } = use{Name}Context();\n  return <div onClick={() => setState(value)}>{value}</div>;\n};\n\nexport { {Name} };"
+    },
+    {
+      "id": "hoc-pattern",
+      "name": "Higher-Order Component",
+      "description": "Wrap a component to inject props or behavior. Use sparingly -- prefer hooks for most cases.",
+      "detect": "function\\s+with[A-Z]\\w+\\s*\\(|const\\s+with[A-Z]\\w+\\s*=",
+      "action": "suggest",
+      "template": "function with{Behavior}<P extends object>(\n  WrappedComponent: React.ComponentType<P & {Injected}Props>\n) {\n  function Enhanced(props: P) {\n    const injected = use{Behavior}();\n    return <WrappedComponent {...props} {...injected} />;\n  }\n  Enhanced.displayName = `with{Behavior}(${WrappedComponent.displayName || WrappedComponent.name})`;\n  return Enhanced;\n}"
+    },
+    {
+      "id": "render-props",
+      "name": "Render Props / Children as Function",
+      "description": "Component accepts a render function as children or prop. Useful for headless behavior injection.",
+      "detect": "children\\s*\\(|render\\s*=\\s*\\{\\s*\\(",
+      "action": "suggest",
+      "template": "interface {Name}Props<T> {\n  children: (state: { data: T; loading: boolean; error: Error | null }) => React.ReactNode;\n}\n\nfunction {Name}<T>({ children }: {Name}Props<T>) {\n  const { data, loading, error } = use{DataSource}<T>();\n  return <>{children({ data, loading, error })}</>;\n}"
+    },
+    {
+      "id": "forward-ref",
+      "name": "forwardRef Component",
+      "description": "Component that forwards ref to an inner DOM element. Required for ref-based integrations.",
+      "detect": "React\\.forwardRef|forwardRef\\s*<",
+      "action": "suggest",
+      "template": "interface {Name}Props extends React.HTMLAttributes<HTMLDivElement> {\n  variant?: 'primary' | 'secondary';\n}\n\nconst {Name} = React.forwardRef<HTMLDivElement, {Name}Props>(\n  ({ variant = 'primary', className, children, ...props }, ref) => {\n    return (\n      <div ref={ref} className={cn(styles[variant], className)} {...props}>\n        {children}\n      </div>\n    );\n  }\n);\n\n{Name}.displayName = '{Name}';\nexport { {Name} };"
+    },
+    {
+      "id": "generic-component",
+      "name": "Generic TypeScript Component",
+      "description": "Component with generic type parameter for type-safe data rendering (List, Table, Select).",
+      "detect": "function\\s+\\w+\\s*<\\s*T\\s*(extends|,|>)",
+      "action": "suggest",
+      "template": "interface {Name}Props<T> {\n  items: T[];\n  renderItem: (item: T, index: number) => React.ReactNode;\n  keyExtractor: (item: T) => string;\n  emptyMessage?: string;\n}\n\nfunction {Name}<T>({ items, renderItem, keyExtractor, emptyMessage }: {Name}Props<T>) {\n  if (items.length === 0) {\n    return <p>{emptyMessage ?? 'No items'}</p>;\n  }\n  return (\n    <ul>\n      {items.map((item, i) => (\n        <li key={keyExtractor(item)}>{renderItem(item, i)}</li>\n      ))}\n    </ul>\n  );\n}"
+    },
+    {
+      "id": "controlled-uncontrolled",
+      "name": "Controlled + Uncontrolled Dual Mode",
+      "description": "Component supports both controlled (value+onChange) and uncontrolled (defaultValue) modes.",
+      "detect": "(value|defaultValue).*onChange|controlled.*uncontrolled",
+      "action": "suggest",
+      "template": "interface {Name}Props {\n  value?: string;\n  defaultValue?: string;\n  onChange?: (value: string) => void;\n}\n\nfunction {Name}({ value: controlledValue, defaultValue = '', onChange }: {Name}Props) {\n  const [internalValue, setInternalValue] = useState(defaultValue);\n  const isControlled = controlledValue !== undefined;\n  const currentValue = isControlled ? controlledValue : internalValue;\n\n  const handleChange = (newValue: string) => {\n    if (!isControlled) setInternalValue(newValue);\n    onChange?.(newValue);\n  };\n\n  return <input value={currentValue} onChange={(e) => handleChange(e.target.value)} />;\n}"
+    },
+    {
+      "id": "polymorphic-component",
+      "name": "Polymorphic Component (as prop)",
+      "description": "Component that renders as a different HTML element or component via 'as' prop.",
+      "detect": "as\\s*[=:]\\s*(keyof|ElementType|ComponentType)",
+      "action": "suggest",
+      "template": "type {Name}Props<C extends React.ElementType = 'div'> = {\n  as?: C;\n  children: React.ReactNode;\n} & Omit<React.ComponentPropsWithoutRef<C>, 'as' | 'children'>;\n\nfunction {Name}<C extends React.ElementType = 'div'>({ as, children, ...props }: {Name}Props<C>) {\n  const Component = as || 'div';\n  return <Component {...props}>{children}</Component>;\n}\n\n// Usage: <Box as=\"section\" /> or <Box as={Link} href=\"/\" />"
+    },
+    {
+      "id": "error-boundary",
+      "name": "Error Boundary",
+      "description": "Class component that catches JavaScript errors in child tree and shows fallback UI.",
+      "detect": "componentDidCatch|getDerivedStateFromError|ErrorBoundary",
+      "action": "suggest",
+      "template": "interface ErrorBoundaryProps {\n  fallback: React.ReactNode | ((error: Error, reset: () => void) => React.ReactNode);\n  children: React.ReactNode;\n  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;\n}\n\ninterface ErrorBoundaryState {\n  error: Error | null;\n}\n\nclass ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {\n  state: ErrorBoundaryState = { error: null };\n\n  static getDerivedStateFromError(error: Error) {\n    return { error };\n  }\n\n  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {\n    this.props.onError?.(error, errorInfo);\n  }\n\n  reset = () => this.setState({ error: null });\n\n  render() {\n    if (this.state.error) {\n      const { fallback } = this.props;\n      return typeof fallback === 'function'\n        ? fallback(this.state.error, this.reset)\n        : fallback;\n    }\n    return this.props.children;\n  }\n}"
+    },
+    {
+      "id": "slot-pattern",
+      "name": "Slot Pattern (Named Children)",
+      "description": "Component accepts named slots for flexible layout composition.",
+      "detect": "(header|footer|sidebar|left|right|icon|prefix|suffix)\\s*[=:]\\s*React\\.ReactNode",
+      "action": "suggest",
+      "template": "interface {Name}Props {\n  header?: React.ReactNode;\n  footer?: React.ReactNode;\n  sidebar?: React.ReactNode;\n  children: React.ReactNode;\n}\n\nfunction {Name}({ header, footer, sidebar, children }: {Name}Props) {\n  return (\n    <div className=\"layout\">\n      {header && <header className=\"layout-header\">{header}</header>}\n      <div className=\"layout-body\">\n        {sidebar && <aside className=\"layout-sidebar\">{sidebar}</aside>}\n        <main className=\"layout-main\">{children}</main>\n      </div>\n      {footer && <footer className=\"layout-footer\">{footer}</footer>}\n    </div>\n  );\n}"
+    }
+  ]
+}

package/plugins/react/patterns/hooks.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://yuaone.com/schemas/patterns.json",
+  "name": "React Hook Patterns",
+  "version": "1.0.0",
+  "description": "Common React hook patterns for detection and suggestion",
+  "patterns": [
+    {
+      "id": "use-state-batching",
+      "name": "useState Batching",
+      "description": "Multiple related setState calls should use useReducer or a single state object to avoid intermediate renders.",
+      "detect": "set\\w+\\([^)]+\\);\\s*set\\w+\\(",
+      "action": "suggest",
+      "template": "// Instead of multiple setState calls:\n// setLoading(true); setError(null); setData(null);\n\n// Use useReducer for related state transitions:\ntype State = { data: T | null; loading: boolean; error: Error | null };\ntype Action =\n  | { type: 'FETCH_START' }\n  | { type: 'FETCH_SUCCESS'; data: T }\n  | { type: 'FETCH_ERROR'; error: Error };\n\nfunction reducer(state: State, action: Action): State {\n  switch (action.type) {\n    case 'FETCH_START': return { data: null, loading: true, error: null };\n    case 'FETCH_SUCCESS': return { data: action.data, loading: false, error: null };\n    case 'FETCH_ERROR': return { data: null, loading: false, error: action.error };\n  }\n}\n\nconst [state, dispatch] = useReducer(reducer, { data: null, loading: false, error: null });"
+    },
+    {
+      "id": "use-callback-deps",
+      "name": "useCallback with Dependencies",
+      "description": "useCallback should have correct dependency array. Functions passed to child components should be memoized.",
+      "detect": "useCallback\\(\\s*\\([^)]*\\)\\s*=>",
+      "action": "suggest",
+      "template": "// Stable callback reference to prevent child re-renders:\nconst handleClick = useCallback((id: string) => {\n  // Use functional updater to avoid deps on state:\n  setItems(prev => prev.filter(item => item.id !== id));\n}, []); // Empty deps because functional updater doesn't need current state\n\n// When you DO need external values:\nconst handleSubmit = useCallback(() => {\n  submitForm(formData);\n}, [formData]); // formData in deps"
+    },
+    {
+      "id": "use-memo-computation",
+      "name": "useMemo for Expensive Computation",
+      "description": "useMemo should be used for expensive computations, not for every variable. Profile before memoizing.",
+      "detect": "useMemo\\(\\s*\\(\\)\\s*=>",
+      "action": "suggest",
+      "template": "// Good: expensive computation that depends on data\nconst sortedItems = useMemo(\n  () => items.slice().sort((a, b) => a.name.localeCompare(b.name)),\n  [items]\n);\n\n// Good: object/array passed to child component (stable reference)\nconst contextValue = useMemo(\n  () => ({ user, settings, theme }),\n  [user, settings, theme]\n);\n\n// BAD: simple value derivation (no memoization needed)\n// const fullName = useMemo(() => `${first} ${last}`, [first, last]);\n// Just use: const fullName = `${first} ${last}`;"
+    },
+    {
+      "id": "use-ref-patterns",
+      "name": "useRef Patterns",
+      "description": "useRef for DOM access, mutable values that don't trigger re-renders, and previous value tracking.",
+      "detect": "useRef\\s*<",
+      "action": "suggest",
+      "template": "// 1. DOM reference\nconst inputRef = useRef<HTMLInputElement>(null);\nuseEffect(() => { inputRef.current?.focus(); }, []);\n\n// 2. Mutable value (no re-render on change)\nconst renderCount = useRef(0);\nuseEffect(() => { renderCount.current += 1; });\n\n// 3. Previous value tracking\nfunction usePrevious<T>(value: T): T | undefined {\n  const ref = useRef<T>();\n  useEffect(() => { ref.current = value; });\n  return ref.current;\n}\n\n// 4. Latest callback ref (avoid stale closures in intervals)\nconst callbackRef = useRef(callback);\nuseLayoutEffect(() => { callbackRef.current = callback; });"
+    },
+    {
+      "id": "use-effect-fetch",
+      "name": "useEffect Data Fetching",
+      "description": "Data fetching in useEffect with abort controller, loading state, and error handling.",
+      "detect": "useEffect\\(.*fetch\\(|useEffect\\(.*axios",
+      "action": "suggest",
+      "template": "function useDataFetch<T>(url: string) {\n  const [data, setData] = useState<T | null>(null);\n  const [loading, setLoading] = useState(true);\n  const [error, setError] = useState<Error | null>(null);\n\n  useEffect(() => {\n    const controller = new AbortController();\n    setLoading(true);\n    setError(null);\n\n    fetch(url, { signal: controller.signal })\n      .then(res => {\n        if (!res.ok) throw new Error(`HTTP ${res.status}`);\n        return res.json();\n      })\n      .then(setData)\n      .catch(err => {\n        if (err.name !== 'AbortError') setError(err);\n      })\n      .finally(() => setLoading(false));\n\n    return () => controller.abort();\n  }, [url]);\n\n  return { data, loading, error };\n}"
+    },
+    {
+      "id": "use-debounce",
+      "name": "useDebounce Hook",
+      "description": "Debounce a value to limit update frequency. Common for search inputs and API calls.",
+      "detect": "useDebounce|debounce.*useState|setTimeout.*setState",
+      "action": "suggest",
+      "template": "function useDebounce<T>(value: T, delay: number): T {\n  const [debouncedValue, setDebouncedValue] = useState(value);\n\n  useEffect(() => {\n    const timer = setTimeout(() => setDebouncedValue(value), delay);\n    return () => clearTimeout(timer);\n  }, [value, delay]);\n\n  return debouncedValue;\n}\n\n// Usage:\nconst [search, setSearch] = useState('');\nconst debouncedSearch = useDebounce(search, 300);\n\nuseEffect(() => {\n  if (debouncedSearch) fetchResults(debouncedSearch);\n}, [debouncedSearch]);"
+    },
+    {
+      "id": "use-local-storage",
+      "name": "useLocalStorage Hook",
+      "description": "Persist state to localStorage with SSR safety and type-safe serialization.",
+      "detect": "localStorage\\.(get|set)Item|useLocalStorage",
+      "action": "suggest",
+      "template": "function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void] {\n  const [storedValue, setStoredValue] = useState<T>(() => {\n    if (typeof window === 'undefined') return initialValue;\n    try {\n      const item = window.localStorage.getItem(key);\n      return item ? JSON.parse(item) : initialValue;\n    } catch {\n      return initialValue;\n    }\n  });\n\n  const setValue = useCallback((value: T | ((prev: T) => T)) => {\n    setStoredValue(prev => {\n      const newValue = value instanceof Function ? value(prev) : value;\n      try {\n        window.localStorage.setItem(key, JSON.stringify(newValue));\n      } catch (e) {\n        console.warn(`Failed to save ${key} to localStorage`, e);\n      }\n      return newValue;\n    });\n  }, [key]);\n\n  return [storedValue, setValue];\n}"
+    },
+    {
+      "id": "use-media-query",
+      "name": "useMediaQuery Hook",
+      "description": "SSR-safe media query matching for responsive behavior in JavaScript.",
+      "detect": "matchMedia|useMediaQuery|window\\.innerWidth",
+      "action": "suggest",
+      "template": "function useMediaQuery(query: string): boolean {\n  const [matches, setMatches] = useState(false);\n\n  useEffect(() => {\n    const media = window.matchMedia(query);\n    setMatches(media.matches);\n\n    const listener = (e: MediaQueryListEvent) => setMatches(e.matches);\n    media.addEventListener('change', listener);\n    return () => media.removeEventListener('change', listener);\n  }, [query]);\n\n  return matches;\n}\n\n// Usage:\nconst isMobile = useMediaQuery('(max-width: 768px)');\nconst prefersDark = useMediaQuery('(prefers-color-scheme: dark)');"
+    }
+  ]
+}

package/plugins/react/plugin.yaml

@@ -0,0 +1,229 @@
+# @yuaone/plugin-react — React/Next.js Expert Agent Skill Pack
+# SSOT for plugin metadata, skills, triggers, tools, and configuration.
+
+id: "@yuaone/plugin-react"
+name: "React Expert"
+version: "1.0.0"
+description: "React/Next.js expert agent skill pack — bugfix, component generation, hook extraction, testing, and SSR/hydration expertise"
+author: "yuaone"
+license: "MIT"
+category: "coding"
+type: "hybrid"
+trustLevel: "official"
+sandbox: "restricted"
+triggerMode: "auto"
+pluginApiVersion: 1
+estimatedPromptTokens: 3500
+engineVersion: ">=0.2.0"
+
+# Auto-detect — any match triggers plugin load
+detect:
+  files:
+    - "package.json"
+  dependencies:
+    - "react"
+    - "react-dom"
+  glob:
+    - "src/**/*.tsx"
+    - "src/**/*.jsx"
+    - "app/**/*.tsx"
+    - "pages/**/*.tsx"
+    - "components/**/*.tsx"
+
+# Skills — domain knowledge units
+skills:
+  - id: "react-bugfix"
+    name: "React Bugfix"
+    description: "React bug diagnosis and fix — hydration, hook loops, state issues, key props, memory leaks"
+    trigger:
+      kind: "auto"
+      pattern: "(hydration|Maximum update depth|Cannot read propert|React Hook|memory leak|Warning:.*key)"
+      confidence: 0.85
+      cooldown: 5000
+    template: "skills/bugfix.md"
+    enabled: true
+    tags: ["debug", "error", "fix", "react", "hooks", "state"]
+
+  - id: "react-component-gen"
+    name: "Component Generator"
+    description: "React component generation — atomic design, compound patterns, forwardRef, generics"
+    trigger:
+      kind: "command"
+      command: "/react-component"
+    template: "skills/component-gen.md"
+    enabled: true
+    tags: ["generate", "component", "atomic", "compound", "react"]
+
+  - id: "react-hook-extract"
+    name: "Hook Extractor"
+    description: "Extract custom hooks from components — state+effect grouping, hook composition, testability"
+    trigger:
+      kind: "command"
+      command: "/extract-hook"
+    template: "skills/hook-extract.md"
+    enabled: true
+    tags: ["refactor", "hook", "extract", "composition"]
+
+  - id: "react-test"
+    name: "React Test Generator"
+    description: "Generate React tests — RTL best practices, MSW API mocking, user events, async patterns"
+    trigger:
+      kind: "command"
+      command: "/react-test"
+    template: "skills/test.md"
+    enabled: true
+    tags: ["test", "jest", "rtl", "msw", "vitest"]
+
+  - id: "react-ssr"
+    name: "SSR/Hydration Expert"
+    description: "SSR and hydration specialist — Next.js App Router, Server Components, streaming SSR, hydration debugging"
+    trigger:
+      kind: "auto"
+      pattern: "(hydrat|server.?component|use.?client|use.?server|getServerSideProps|getStaticProps)"
+      confidence: 0.80
+      cooldown: 10000
+    template: "skills/ssr.md"
+    enabled: true
+    tags: ["ssr", "hydration", "server", "nextjs", "streaming"]
+
+# Triggers — error/task patterns mapped to skills and strategies
+triggers:
+  - pattern: "Text content does not match|Hydration failed|hydration mismatch"
+    kind: "error"
+    skill: "react-ssr"
+    strategy: "hydration-fix"
+    priority: 10
+    triggerMode: "auto"
+
+  - pattern: "Maximum update depth exceeded|Too many re-renders"
+    kind: "error"
+    skill: "react-bugfix"
+    strategy: "hook-loop-fix"
+    priority: 10
+    triggerMode: "auto"
+
+  - pattern: "Module not found|Cannot find module|Failed to compile"
+    kind: "error"
+    skill: "react-bugfix"
+    strategy: "build-fix"
+    priority: 5
+    triggerMode: "auto"
+
+  - pattern: "Cannot read properties of (null|undefined)"
+    kind: "error"
+    skill: "react-bugfix"
+    priority: 3
+    triggerMode: "auto"
+
+  - pattern: "Invalid hook call|Hooks can only be called inside"
+    kind: "error"
+    skill: "react-bugfix"
+    priority: 8
+    triggerMode: "auto"
+
+  - pattern: "Each child in a list should have a unique.*key"
+    kind: "error"
+    skill: "react-bugfix"
+    priority: 4
+    triggerMode: "auto"
+
+  - pattern: "Can't perform a React state update on an unmounted component"
+    kind: "error"
+    skill: "react-bugfix"
+    priority: 6
+    triggerMode: "auto"
+
+  - pattern: "Server Error.*getServerSideProps|Error.*server.?component"
+    kind: "error"
+    skill: "react-ssr"
+    strategy: "hydration-fix"
+    priority: 7
+    triggerMode: "auto"
+
+# Tools — analysis utilities
+tools:
+  - name: "jsx_analyzer"
+    description: "Analyze JSX/TSX files for React patterns, anti-patterns, and component structure"
+    inputSchema:
+      type: "object"
+      properties:
+        filePath:
+          type: "string"
+          description: "Path to the JSX/TSX file to analyze"
+        analysisType:
+          type: "string"
+          enum: ["patterns", "anti-patterns", "structure", "all"]
+          description: "Type of analysis to perform"
+      required: ["filePath"]
+    requiresApproval: false
+    riskLevel: "low"
+    sideEffectLevel: "read"
+
+  - name: "component_tree"
+    description: "Build and analyze React component tree from source files"
+    inputSchema:
+      type: "object"
+      properties:
+        rootDir:
+          type: "string"
+          description: "Root directory to scan for components"
+        depth:
+          type: "number"
+          description: "Maximum depth of component tree (default: 5)"
+        includeProps:
+          type: "boolean"
+          description: "Include prop types in the tree output"
+      required: ["rootDir"]
+    requiresApproval: false
+    riskLevel: "low"
+    sideEffectLevel: "read"
+
+# Strategy files
+strategies:
+  - "strategies/hydration-fix.json"
+  - "strategies/hook-loop-fix.json"
+  - "strategies/build-fix.json"
+
+# Validator files
+validators:
+  - "validators/rules.json"
+
+# Pattern files
+patterns:
+  - "patterns/components.json"
+  - "patterns/hooks.json"
+  - "patterns/anti-patterns.json"
+
+# Permissions
+permissions:
+  fileRead: true
+  fileWrite: true
+  shellExec: true
+  networkAccess: false
+  gitOps: false
+  maxTokensPerCall: 8000
+
+# User-configurable settings
+config:
+  auto_load:
+    type: "boolean"
+    default: true
+    description: "Automatically load when React project detected"
+  inject_into_prompt:
+    type: "boolean"
+    default: true
+    description: "Inject relevant skill knowledge into system prompt"
+  max_patterns_in_context:
+    type: "number"
+    default: 5
+    description: "Maximum number of patterns to inject into context"
+  preferred_test_runner:
+    type: "select"
+    default: "vitest"
+    description: "Preferred test runner for generated tests"
+    options: ["vitest", "jest"]
+  next_version:
+    type: "select"
+    default: "14"
+    description: "Target Next.js major version for SSR strategies"
+    options: ["13", "14", "15"]