@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/react/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: react
+description: >
+  Guide for writing and reviewing React code — hooks, effects, re-renders, and browser performance. Use this skill when:
+  (1) writing or reviewing React components and custom hooks,
+  (2) writing or debugging `useEffect` — deciding whether an Effect is needed at all,
+  (3) using `useState` for derived values, or syncing state between components,
+  (4) diagnosing unnecessary re-renders, stale closures, or memoization problems,
+  (5) fixing data-fetching waterfalls, race conditions, or duplicate requests, or using `use()` with Suspense,
+  (6) optimizing paint, hydration, resource loading, or hot-path JavaScript,
+  (7) working with refs, composition, prop drilling, or controlled vs. uncontrolled components,
+  (8) upgrading React 18 to 19 — removed APIs (`ReactDOM.render`, `findDOMNode`, string refs, legacy context), `forwardRef`, `defaultProps`, and tests (`test-utils`, `act`, StrictMode counts),
+  (9) forms and mutations with Actions — `useActionState`, `useFormStatus`, `useOptimistic`.
+license: MIT
+compatibility: React 18+ (React 19 for `use`, Actions, `Activity`, ref-as-prop)
+allowed-tools: Read Write Edit Glob Grep
+---
+
+# React Best Practices
+
+Apply these guidelines when writing or reviewing React code.
+
+## Reference Files
+
+Read ALL relevant references in the same turn, in parallel. Cite them when giving feedback:
+
+- [Effect patterns](references/effect-patterns.md): When you don't need an Effect, dependency rules, cleanup, subscriptions, `useSyncExternalStore`, one-time initialization
+- [Re-render optimization](references/rerender-optimization.md): `memo`/`useMemo`/`useCallback`, derived state, functional updates, lazy init, `useDeferredValue`, `startTransition`, `useEffectEvent`
+- [Component patterns](references/component-patterns.md): Refs, `useImperativeHandle`, custom hook rules, controlled vs. uncontrolled, composition over prop drilling, `flushSync`
+- [Data fetching](references/data-fetching.md): Parallelizing requests, Suspense boundaries, `use()` and stable promise sources, request deduplication, passive listeners, `localStorage` versioning
+- [Rendering performance](references/rendering-performance.md): `content-visibility`, hydration mismatches, resource hints, script loading, SVG animation, `Activity`, `useTransition`
+- [JS performance](references/js-performance.md): Layout thrashing, `Set`/`Map` lookups, index maps, single-pass iteration, `toSorted`, `requestIdleCallback`
+- [Actions](references/actions.md): `<form action>`, `useActionState`, `useFormStatus`, `useOptimistic` — pending, error, and optimistic state for mutations
+- [React 19 migration](references/react19-migration.md): Upgrading from 18 — root API, `findDOMNode`, `forwardRef`, `defaultProps`, legacy context, string refs, propTypes, JSX transform, TypeScript types, `act`/`test-utils`, StrictMode test counts
+
+## You Might Not Need an Effect
+
+Effects are an **escape hatch** from React. They synchronize with external systems. If no external system is involved, you probably don't need one.
+
+```
+Need to respond to something?
+├── User interaction (click, submit, drag)?
+│   └── EVENT HANDLER
+├── Props/state changed and need a derived value?
+│   └── CALCULATE DURING RENDER
+│       └── Measurably expensive? useMemo
+├── Need to reset state when an identity prop changes?
+│   └── key PROP on the component
+└── Component appeared on screen, and there's an external system?
+    └── EFFECT, with cleanup
+```
+
+**Do need an Effect:** non-React widgets and browser APIs, subscriptions (prefer `useSyncExternalStore`), analytics that fire because a component displayed, data fetching with cleanup (prefer a data library).
+
+**Don't need an Effect:** transforming data for rendering, handling user events, deriving state, chaining state updates, notifying a parent, resetting state.
+
+## Quick Reference
+
+### Effects
+
+| Situation | Don't | Do |
+|---|---|---|
+| Derived state from props/state | `useState` + `useEffect` | Calculate during render |
+| Expensive calculation | `useEffect` to cache | `useMemo` |
+| Reset state on prop change | `useEffect` + `setState` | `key` prop |
+| Response to a user event | `useEffect` watching state | Event handler |
+| Notify parent of a change | `useEffect` calling `onChange` | Call it in the event handler |
+| Subscribe to an external store | Manual `useEffect` subscription | `useSyncExternalStore` |
+| Fetch data | `useEffect` without cleanup | `ignore` flag, or a data library |
+| Effect re-runs every render | Object/function in deps | Move creation inside the effect |
+| Missing dependency | `eslint-disable exhaustive-deps` | Functional update or `useEffectEvent` |
+| One-time app init | `useRef` guard | Module-level flag |
+
+### Re-renders
+
+- Never define a component inside another component — it remounts every render
+- Use functional `setState` when the next state depends on the previous one
+- `useState(() => expensive())` for expensive defaults; the plain form runs every render
+- Don't wrap simple boolean/primitive expressions in `useMemo`
+- Split combined `useMemo`/`useEffect` — one concern each
+- Values that change often but aren't rendered (mouse position, flags) belong in refs
+- If React Compiler is enabled, skip manual `memo`/`useMemo`/`useCallback`
+
+### Data fetching
+
+- `Promise.all()` for independent requests; chain per item for dependent ones
+- Move `await` past early returns and behind cheap synchronous guards
+- One shared request per endpoint (SWR / React Query), not one per component instance
+- Every fetch effect needs an `ignore` flag or `AbortController`
+- Promises passed to `use()` come from a loader, cache, library, or Server Component — never created in render
+
+### Forms and mutations (React 19)
+
+- `<form action={fn}>` over `onSubmit` + `preventDefault`; `useActionState` over a loading/error reducer
+- Return expected errors from the action as state; thrown errors go to the error boundary
+- `useFormStatus` is imported from `react-dom` and only reads a parent `<form>`
+- Seed `useOptimistic` with confirmed state and call its setter inside an Action
+- After `await` inside an Action, wrap state updates in another `startTransition`
+
+### Upgrading to React 19
+
+- Run `npx codemod@latest react/19/migration-recipe` first; the upgrade PR changes API surface only
+- `forwardRef` still works — `ref` is a plain prop; convert opportunistically
+- `defaultProps` are ignored on function components but still work on class components
+- StrictMode still double-runs effects; what changed is `useMemo`/`useCallback` result reuse and double-invoked ref callbacks
+
+### Performance
+
+- Measure before optimizing — profile, don't guess
+- Batch DOM writes, then read once; interleaving forces reflow
+- `Set`/`Map` for repeated lookups; one pass instead of chained `.filter().map()`
+- `.toSorted()` on props and state — `.sort()` mutates
+- Defer analytics and prefetching with `requestIdleCallback`
+
+## Review Checklist
+
+1. Does every `useEffect` synchronize with an external system? If not, propose the alternative.
+2. Are dependency arrays complete, with no lint suppressions?
+3. Does every subscription, listener, timer, and fetch have cleanup?
+4. Is any state redundant — derivable from other props or state?
+5. Are components defined at module scope?
+6. Are independent async calls parallelized?
+7. Are mutating array methods used on props or state?
+8. Is every promise passed to `use()` stable across renders?
+9. On React 19: are forms using Actions with errors returned as state, and are removed APIs (`findDOMNode`, string refs, legacy context, `test-utils`) gone?

package/skills/react/references/actions.md

@@ -0,0 +1,251 @@
+---
+name: react-actions
+description: Handle form submissions and async mutations with React 19 Actions — useActionState, useFormStatus, and useOptimistic.
+license: MIT
+last_reviewed: 2026-09-26
+---
+
+# React Actions — forms, pending state, and optimistic updates
+
+## When to apply
+
+- A form tracks `loading` / `error` / `data` by hand, with `useState` flags or a reducer with `'loading' | 'success' | 'error'` cases
+- `onSubmit` calls `e.preventDefault()` and builds `FormData` manually
+- A submit button receives `isPending` through props from the form above it
+- An optimistic update is hand-rolled: snapshot the list, add the item, restore the snapshot in `catch`
+
+Actions are React 19 only. For a non-form async update that just needs `isPending`, see [`useTransition`](rendering-performance.md#pattern-10--use-usetransition-over-manual-loading-states).
+
+## What an Action is
+
+An Action is a function React runs inside a Transition: a function passed to `<form action>` or `formAction`, or one called inside `startTransition`. React tracks its pending state, sends thrown errors to the nearest error boundary, and lets `useActionState` and `useOptimistic` hook into it. After a `<form action>` succeeds, React resets the form's uncontrolled fields.
+
+One limitation: state updates after an `await` are not part of the Transition. Wrap them in another `startTransition`:
+
+```tsx
+startTransition(async () => {
+  const saved = await save(draft)
+  startTransition(() => setItems(curr => [...curr, saved]))  // after await: wrap again
+})
+```
+
+## Pattern 1 — `useActionState` instead of hand-managed loading state
+
+```tsx
+const [state, dispatchAction, isPending] = useActionState(reducerAction, initialState)
+// reducerAction(previousState, payload) — with <form action>, payload is the FormData
+```
+
+**Incorrect (reducer + manual dispatch around the request):**
+
+```tsx
+function SignupForm() {
+  const [state, dispatch] = useReducer(signupReducer, { loading: false, error: null })
+
+  async function handleSubmit(e: FormEvent<HTMLFormElement>) {
+    e.preventDefault()
+    dispatch({ type: 'loading' })
+    try {
+      await signup(new FormData(e.currentTarget))
+      dispatch({ type: 'success' })
+    } catch (err) {
+      dispatch({ type: 'error', error: (err as Error).message })
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="email" />
+      {state.error && <p role="alert">{state.error}</p>}
+      <button disabled={state.loading}>Sign up</button>
+    </form>
+  )
+}
+```
+
+**Correct:**
+
+```tsx
+import { useActionState } from 'react'
+
+type State = { error: string | null }
+
+async function signupAction(prev: State, formData: FormData): Promise<State> {
+  const result = await signup(formData.get('email') as string)
+  if (!result.ok) return { error: result.message }  // expected failure → state
+  return { error: null }
+}
+
+function SignupForm() {
+  const [state, formAction, isPending] = useActionState(signupAction, { error: null })
+
+  return (
+    <form action={formAction}>
+      <input name="email" />
+      {state.error && <p role="alert">{state.error}</p>}
+      <button disabled={isPending}>Sign up</button>
+    </form>
+  )
+}
+```
+
+Rules:
+
+- **Return expected errors, throw unexpected ones.** A thrown error cancels all queued actions and shows the nearest error boundary instead of the form. Validation failures and 4xx responses belong in the returned state.
+- **Outside a form, dispatch inside `startTransition`.** Called from `onClick` without it, React logs an error and `isPending` doesn't track the call:
+
+  ```tsx
+  <button onClick={() => startTransition(() => dispatchAction({ type: 'remove', id }))}>Remove</button>
+  ```
+
+- **Calls queue.** Multiple dispatches run in order; each `reducerAction` receives the previous result.
+- **The form resets on success.** Uncontrolled fields clear after the action succeeds. To keep what the user typed after an error, return the submitted values in state and render them as `defaultValue`.
+
+## Pattern 2 — `useFormStatus` instead of passing `isPending` down
+
+`useFormStatus` is imported from **`react-dom`**, not `react`. It reports the status of the **parent** `<form>` only, so call it in a component rendered inside the form.
+
+**Incorrect (same component renders the form — `pending` is always `false`):**
+
+```tsx
+import { useFormStatus } from 'react-dom'
+
+function CommentForm({ action }: Props) {
+  const { pending } = useFormStatus()  // no parent <form> here
+  return (
+    <form action={action}>
+      <textarea name="body" />
+      <button disabled={pending}>Post</button>
+    </form>
+  )
+}
+```
+
+**Correct (a child of the form reads it — no prop drilling):**
+
+```tsx
+import { useFormStatus } from 'react-dom'
+
+function SubmitButton({ children }: { children: ReactNode }) {
+  const { pending } = useFormStatus()
+  return <button disabled={pending}>{pending ? 'Saving…' : children}</button>
+}
+
+function CommentForm({ action }: Props) {
+  return (
+    <form action={action}>
+      <textarea name="body" />
+      <SubmitButton>Post</SubmitButton>
+    </form>
+  )
+}
+```
+
+It works with a function passed to `<form action>`. A plain `onSubmit` form never reports `pending`.
+
+## Pattern 3 — `useOptimistic` instead of snapshot-and-revert
+
+```tsx
+const [optimisticState, setOptimistic] = useOptimistic(value, reducer?)
+```
+
+Call the setter inside an Action. When the Transition finishes, the optimistic state converges to whatever `value` is by then. If the Action updated `value`, the confirmed data shows. If it failed and `value` didn't change, the UI shows what it showed before, so there is no manual revert.
+
+**Incorrect (manual copy, manual revert):**
+
+```tsx
+function TodoList({ initialTodos }: Props) {
+  const [todos, setTodos] = useState(initialTodos)
+
+  async function handleAdd(text: string) {
+    const temp = { id: `temp-${Date.now()}`, text }
+    const snapshot = todos
+    setTodos([...todos, temp])
+    try {
+      const saved = await api.createTodo(text)
+      setTodos(curr => curr.map(t => (t.id === temp.id ? saved : t)))
+    } catch {
+      setTodos(snapshot)  // stale if anything else changed meanwhile
+    }
+  }
+}
+```
+
+**Correct:**
+
+```tsx
+import { startTransition, useOptimistic, useState } from 'react'
+
+function TodoList({ initialTodos }: Props) {
+  const [todos, setTodos] = useState(initialTodos)  // confirmed state
+  const [optimisticTodos, addOptimistic] = useOptimistic(
+    todos,
+    (current: Todo[], draft: Todo) => [...current, { ...draft, pending: true }]
+  )
+
+  async function addTodo(formData: FormData) {
+    const text = formData.get('text') as string
+    addOptimistic({ id: crypto.randomUUID(), text })  // shows immediately
+    const saved = await api.createTodo(text)            // throws → item disappears, error boundary shows
+    startTransition(() => setTodos(curr => [...curr, saved]))  // after await: wrap again
+  }
+
+  return (
+    <>
+      <ul>
+        {optimisticTodos.map(t => (
+          <li key={t.id} style={{ opacity: t.pending ? 0.5 : 1 }}>{t.text}</li>
+        ))}
+      </ul>
+      <form action={addTodo}>
+        <input name="text" required />
+        <SubmitButton>Add</SubmitButton>
+      </form>
+    </>
+  )
+}
+```
+
+Generate IDs in the Action and pass them in. The reducer runs during render, so an ID created there changes on every render and remounts the item.
+
+## Finding refactor candidates
+
+```bash
+grep -rnE "case ['\"](loading|pending|success|error)['\"]" src/   # reducer-managed request state
+grep -rnE "set(Is)?(Loading|Submitting|Pending)\(true\)" src/     # hand-rolled pending flags
+grep -rn "preventDefault()" src/ | grep -i submit                  # onSubmit handlers
+```
+
+Refactor these after the React 19 upgrade is stable, not as part of it (see [React 19 migration](react19-migration.md#ground-rule--an-upgrade-pr-changes-api-surface-only)).
+
+## Decision table — React 18 pattern → React 19 Action
+
+| React 18 pattern | React 19 replacement |
+|---|---|
+| `onSubmit` + `preventDefault` + `new FormData(e.target)` | `<form action={fn}>` receives `FormData` |
+| `useReducer` with `loading` / `success` / `error` cases | `useActionState` — return the next state |
+| Manual `setIsLoading(true/false)` | `isPending` from `useActionState` or `useTransition` |
+| `isPending` passed to the submit button as a prop | `useFormStatus()` in the button (from `react-dom`) |
+| Snapshot, update, restore in `catch` | `useOptimistic` — converges automatically |
+| Error shown via `catch` + state | Return expected errors as state; error boundary for the rest |
+
+## When NOT to apply
+
+- **React 18 codebases:** none of these APIs exist.
+- **Forms owned by a form library** (react-hook-form, Formik) with field-level validation as you type: don't mix two sources of truth for pending and error state.
+- **Mutations that need retries, cancellation, or cache invalidation:** a data library's mutation API (e.g. React Query `useMutation`) already handles them.
+- **During the React 19 upgrade PR itself:** adopt Actions in a follow-up.
+
+## Common failure modes
+
+| Mistake | Consequence |
+|---|---|
+| `import { useFormStatus } from 'react'` | Import fails — it lives in `react-dom` |
+| `useFormStatus` in the component that renders the `<form>` | `pending` is always `false` |
+| Throwing for validation errors in a `useActionState` action | Queued actions cancel; the error boundary replaces the form |
+| `dispatchAction` from `onClick` without `startTransition` | Dev error; `isPending` doesn't update |
+| `useOptimistic(initialProp)` where the prop never updates | Optimistic item vanishes when the Transition ends |
+| Optimistic setter called outside an Action | Warning: "An optimistic state update occurred outside a Transition or Action" |
+| State update after `await` without `startTransition` | The update escapes the Transition |
+| Random ID generated inside the `useOptimistic` reducer | Key changes every render; the item remounts |
+| Relying on field values after a successful submit | Uncontrolled fields reset; return values in state if they must persist |

package/skills/react/references/component-patterns.md

@@ -0,0 +1,275 @@
+---
+name: react-component-patterns
+description: Apply ref, custom hook, and component composition patterns correctly in React.
+license: MIT
+last_reviewed: 2026-05-02
+---
+
+# React component patterns — refs, custom hooks, and composition
+
+## When to apply
+
+- Reading or writing `ref.current` during render causes inconsistent behavior
+- A dynamic list needs DOM refs for each item
+- A parent holds a ref to a child and accesses too much of its DOM
+- A custom hook is named `use*` but calls no hooks internally
+- A `useMount` / `useUnmount` wrapper hides missing effect dependencies
+- State in a child is duplicated in the parent, causing synchronization bugs
+- Multiple intermediate components forward a prop that only the leaf needs
+
+## Ref rule 1 — Never read or write `ref.current` during render
+
+Refs are mutable boxes outside React's render cycle. Mutating them during render makes the output non-deterministic (especially in StrictMode, which renders twice).
+
+**Wrong:**
+
+```tsx
+function MyComponent() {
+  const ref = useRef(0);
+  ref.current++; // mutates during render — different value on re-render
+  return <div>{ref.current}</div>; // reading during render — may be stale
+}
+```
+
+**Correct (read/write only in handlers and effects):**
+
+```tsx
+function MyComponent() {
+  const ref = useRef(0);
+
+  function handleClick() {
+    ref.current++; // OK in event handler
+  }
+
+  useEffect(() => {
+    ref.current = computedValue; // OK in effect
+  }, [computedValue]);
+
+  return <button onClick={handleClick}>Click</button>;
+}
+```
+
+## Ref rule 2 — Use ref callbacks for dynamic lists
+
+`useRef` inside a loop violates Rules of Hooks. Use a `Map` ref with a callback instead.
+
+**Wrong:**
+
+```tsx
+{items.map((item) => {
+  const ref = useRef(null); // Rules of Hooks violation
+  return <li key={item.id} ref={ref} />;
+})}
+```
+
+**Correct:**
+
+```tsx
+const itemsRef = useRef(new Map());
+
+{items.map((item) => (
+  <li
+    key={item.id}
+    ref={(node) => {
+      if (node) {
+        itemsRef.current.set(item.id, node);
+      } else {
+        itemsRef.current.delete(item.id);
+      }
+    }}
+  />
+))}
+
+// Access a specific item DOM node:
+// itemsRef.current.get(targetId)?.scrollIntoView()
+```
+
+## Ref rule 3 — Use `useImperativeHandle` to limit exposed DOM surface
+
+When a parent holds a ref to a child, expose only the methods you intend — not the full DOM node.
+
+```tsx
+function MyInput({ ref }: { ref: React.Ref<{ focus(): void }> }) {
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useImperativeHandle(ref, () => ({
+    focus() {
+      inputRef.current?.focus();
+    },
+    // Parent can ONLY call focus(). It cannot access .value, .style, etc.
+  }));
+
+  return <input ref={inputRef} />;
+}
+```
+
+Without `useImperativeHandle`, the parent can mutate any property on the DOM node, breaking encapsulation.
+
+## Custom hook rule 1 — Hooks share logic, not state
+
+Each call to a custom hook creates independent state. Two components calling `useOnlineStatus()` do not share a subscription — they each get their own.
+
+```tsx
+function StatusBar() {
+  const isOnline = useOnlineStatus(); // independent subscription
+}
+
+function SaveButton() {
+  const isOnline = useOnlineStatus(); // independent subscription
+}
+```
+
+To share state between components, lift it up or use context — not a custom hook.
+
+## Custom hook rule 2 — Name `use*` only if the function calls hooks
+
+The `use` prefix tells the linter (and other developers) that Rules of Hooks apply. Misusing it disables lint checks.
+
+**Wrong:**
+
+```tsx
+function useSorted(items: Item[]) {
+  return items.slice().sort(); // no hooks called — misleading name
+}
+```
+
+**Correct:**
+
+```tsx
+function getSorted(items: Item[]) {
+  return items.slice().sort(); // plain function
+}
+
+function useFilteredItems(category: string) {
+  const items = useContext(ItemsContext); // actually uses a hook
+  return useMemo(() => items.filter(i => i.category === category), [items, category]);
+}
+```
+
+## Custom hook rule 3 — Avoid lifecycle wrapper hooks
+
+`useMount` and `useUnmount` wrappers pass a function to an empty-dep effect. The linter cannot see inside the wrapper to catch missing dependencies.
+
+**Wrong:**
+
+```tsx
+function useMount(fn: () => void) {
+  useEffect(() => {
+    fn();
+  }, []); // fn missing from deps — linter can't warn about stale closures inside fn
+}
+```
+
+**Correct (use `useEffect` directly):**
+
+```tsx
+useEffect(() => {
+  doSomethingWith(value); // linter sees `value` and warns if it's missing
+}, [value]);
+```
+
+The only valid use for lifecycle wrappers is logging or observability, where you explicitly don't want reactive re-runs.
+
+## Component rule 1 — Prefer controlled components when the parent cares about the value
+
+| Style | Who owns state | When to use |
+|---|---|---|
+| Uncontrolled | Component itself | Isolated input with no external sync |
+| Controlled | Parent via props | Testing, form validation, parent-level reset |
+
+```tsx
+// Uncontrolled — component owns its query
+function SearchInput() {
+  const [query, setQuery] = useState('');
+  return <input value={query} onChange={e => setQuery(e.target.value)} />;
+}
+
+// Controlled — parent owns the query; easier to test and compose
+function SearchInput({ query, onQueryChange }: Props) {
+  return <input value={query} onChange={e => onQueryChange(e.target.value)} />;
+}
+```
+
+## Component rule 2 — Prefer composition over prop drilling
+
+Prop drilling (passing a value through N components that don't use it) is the wrong default. Try composition first; reach for context only when composition isn't practical.
+
+**Wrong (every layer receives and forwards `user`):**
+
+```tsx
+<App user={user}>
+  <Layout user={user}>
+    <Header user={user}>
+      <Avatar user={user} />
+    </Header>
+  </Layout>
+</App>
+```
+
+**Correct (pass the rendered node; intermediate components don't see `user`):**
+
+```tsx
+<App>
+  <Layout>
+    <Header avatar={<Avatar user={user} />} />
+  </Layout>
+</App>
+```
+
+**When composition isn't enough (global, read-only state like auth or locale):**
+
+```tsx
+<UserContext.Provider value={user}>
+  <App />
+</UserContext.Provider>
+```
+
+## Component rule 3 — Use `flushSync` to read the DOM after a synchronous state update
+
+React batches state updates by default. When you must read updated layout immediately (e.g., scroll to a new item), force synchronous flush.
+
+```tsx
+import { flushSync } from 'react-dom';
+
+function handleAdd() {
+  flushSync(() => {
+    setTodos([...todos, newTodo]);
+  });
+  // DOM is now updated — safe to measure or scroll
+  listRef.current?.lastElementChild?.scrollIntoView();
+}
+```
+
+Do NOT use `flushSync` as a general pattern. It disables batching and hurts performance. Use it only when you need to read layout immediately after a state update.
+
+## Decision table — which pattern to apply
+
+| Situation | Pattern |
+|---|---|
+| Reading or mutating ref during render | Move to event handler or effect |
+| `useRef` called inside a map | Ref callback with `Map` |
+| Parent ref exposes full DOM node | `useImperativeHandle` |
+| Two components need shared subscription result | Lift state or use context |
+| Utility function named `useFoo` with no hooks | Rename to `getFoo` |
+| `useMount(fn)` hides dependency | Replace with `useEffect(() => fn(), [dep])` |
+| Child state duplicated in parent | Lift state; make child controlled |
+| Prop passed through 3+ components that don't use it | Composition (pass the element) or context |
+| Must scroll to DOM node after state update | `flushSync` |
+
+## When NOT to apply
+
+- **`useImperativeHandle`:** If the parent only needs to focus/scroll the child and a regular forwarded ref would work, skip the extra indirection.
+- **Controlled components everywhere:** UI-only widgets (date pickers, color swatches) with no external state needs work fine as uncontrolled.
+- **`flushSync`:** Never in render paths, loops, or event handlers where batching is beneficial. The cost is always a synchronous re-render.
+
+## Common failure modes
+
+| Mistake | Consequence |
+|---|---|
+| Writing to `ref.current` during render | Non-deterministic output; StrictMode double-render shows inconsistent values |
+| `useRef(null)` inside `.map()` | Rules of Hooks violation; random crashes |
+| Forwarding a ref without `useImperativeHandle` | Parent mutates arbitrary DOM properties, breaking encapsulation |
+| `useMount(fn)` wrapping stale closure | Silent bug: `fn` always captures values from first render |
+| `use` prefix on a function with no hooks | Linter may flag valid call sites or skip invalid ones |
+| Prop drilling vs. composition | Refactoring cost multiplies with every new intermediate layer |
+| `flushSync` inside another `flushSync` | Throws; React does not support nested synchronous flushes |