@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/react-patterns/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: react-patterns
+description: React component design rules for function components and hooks, covering where state should live, the Rules of Hooks, effects used only to synchronise with external systems, data fetching without race conditions, controlled and uncontrolled forms with React 19 actions, error boundaries, choosing context versus a state library, and accessible markup. Use when building or restructuring React components, deciding where a piece of state belongs, writing or removing a useEffect, wiring up a form, or picking between context, Zustand, Redux or a query cache.
+license: MIT
+compatibility: Any Agent Skills host. Applies to React 18 and 19 with any bundler or framework (Vite, Next.js, Remix, React Router). Needs Node.js and the project's package manager to run lint and tests.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# React patterns
+
+Write components that are pure during render, keep state as small and as local as possible, and treat effects as an escape hatch. For Next.js server/client concerns use the `nextjs-patterns` skill; for render speed use `react-performance`.
+
+## 0. Before you change anything
+
+1. Check the React version in `package.json` (`react`, `react-dom`). React 19 APIs (`useActionState`, `useOptimistic`, `use`, form `action` props, `ref` as a prop) don't exist in 18.
+2. Check what the project already uses for server state (TanStack Query, SWR, RTK Query, Apollo, framework loaders) and client state (context, Zustand, Redux, Jotai). Follow it. Don't add a second library for the same job.
+3. Check lint config for `eslint-plugin-react-hooks` (`rules-of-hooks`, `exhaustive-deps`). If it's missing, tell the user; don't silently add it.
+
+## 1. Where state lives
+
+Decide in this order and stop at the first that fits:
+
+1. **Derive it.** If a value can be computed from props or other state, compute it during render. Never mirror props into state (`useState(props.x)` plus an effect to sync it).
+2. **Local `useState`/`useReducer`** in the lowest component that needs it. Use `useReducer` when several fields change together or the next state depends on an action type.
+3. **Lift** to the closest common parent when two siblings need it.
+4. **URL** (search params, path) for anything that should survive reload or be shareable: filters, tabs, pagination, selected item.
+5. **Server-state cache** (the project's query library or framework loader) for data owned by the backend. Never copy fetched data into a global store by hand.
+6. **Context** for values many distant components read and that change rarely: theme, locale, current user, a feature-flag client.
+7. **A state library** only when client state is large, updated from many places, and context would re-render too much.
+
+Rules:
+- Store the minimum: an `id`, not a copy of the selected object.
+- Reset state with a `key` (`<Profile key={userId} />`), not with an effect.
+- Put the state setter and value in separate contexts if consumers only need one, or memoise the context value object.
+
+## 2. Rules of Hooks
+
+- Call hooks only at the top level of a component or a custom hook. No hooks inside conditions, loops, nested functions, `try` blocks or after an early `return`.
+- Custom hooks start with `use` and may call other hooks. A function that calls no hooks is not a hook; don't prefix it.
+- Never call a component as a function (`Row()`); render it (`<Row />`).
+- Never define a component inside another component's body. It remounts every render and loses state.
+- Render must be pure: no mutation of props, state or module variables, no `Math.random()`/`Date.now()` driving output without a stable source, no reading or writing `ref.current` during render (except lazy init).
+
+## 3. Effects: synchronisation only
+
+An effect is for keeping React in sync with something outside React: a subscription, a browser API, a non-React widget, a websocket. Before writing `useEffect`, check whether you need it:
+
+| You want to... | Do this instead |
+|---|---|
+| Compute a value from props/state | Compute during render (memoise only if measured slow) |
+| Respond to a click or submit | Put the logic in the event handler |
+| Reset state when a prop changes | Change the `key` |
+| Adjust part of state when a prop changes | Derive it, or store the previous prop and compare during render |
+| Notify a parent of a change | Call the parent's callback in the same handler that changed state |
+| Fetch data | Use the project's data library or framework loader (section 4) |
+
+When you do write one:
+1. List every reactive value it reads in the dependency array. Never suppress `exhaustive-deps`; restructure instead (move the function inside the effect, use an updater `setX(x => x + 1)`, or move non-reactive logic to `useEffectEvent` on React 19.2+).
+2. Return a cleanup that undoes the setup: unsubscribe, `clearInterval`, `controller.abort()`, `disconnect()`.
+3. Expect it to run twice in development under `<StrictMode>`. If that breaks something, the cleanup is wrong; don't remove StrictMode.
+4. Don't call `setState` synchronously in the effect body just to derive state; that is section 1, rule 1.
+
+## 4. Data fetching
+
+Prefer, in order: the framework's loader or a Server Component (Next.js, Remix, React Router), then the project's query library, then a hand-rolled effect.
+
+If you must fetch in an effect, guard against races and unmounts:
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+  setStatus("loading");
+  fetch(`/api/users/${id}`, { signal: controller.signal })
+    .then((r) => { if (!r.ok) throw new Error(`HTTP ${r.status}`); return r.json(); })
+    .then((data) => { setUser(data); setStatus("done"); })
+    .catch((e) => { if (e.name !== "AbortError") { setError(e); setStatus("error"); } });
+  return () => controller.abort();
+}, [id]);
+```
+
+- Model loading, error and empty states explicitly; never render `data.items.map` before data exists.
+- Start independent requests in parallel (`Promise.all`, or sibling components each with their own query), not one after another.
+- With `use(promise)` on React 19, create the promise outside render (in a loader, a Server Component or a cache) and wrap the reader in `<Suspense>`. A promise created during render is recreated every render.
+
+## 5. Forms
+
+- **Uncontrolled + `FormData`** is the default for submit-only forms: `<form action={fn}>` on React 19, or `onSubmit` with `new FormData(e.currentTarget)` on 18.
+- **Controlled inputs** (`value` + `onChange`) only when you need the value on every keystroke: live validation, formatting, dependent fields.
+- Never switch an input between controlled and uncontrolled; initialise with `""`, not `undefined`.
+- React 19: `useActionState(action, initialState)` returns `[state, formAction, isPending]` for results and errors; `useFormStatus()` (from `react-dom`) reads pending state inside a child of the `<form>`; `useOptimistic` shows the expected result while the action runs.
+- For large forms the project may use React Hook Form or similar; follow it.
+- Validate on the server too. Client validation is UX, not security.
+- Every input has a `<label htmlFor>` (or wraps the input); errors are linked with `aria-describedby` and announced (`role="alert"` or `aria-live="polite"`).
+- Disable the submit button while pending, and keep it focusable.
+
+## 6. Error boundaries
+
+- Error boundaries catch errors thrown during render, in lifecycle methods and in constructors below them. They do **not** catch errors in event handlers, async code (timers, promises after an `await`), or the boundary itself.
+- There is no hook equivalent: write a class with `static getDerivedStateFromError` and `componentDidCatch`, or use the project's `react-error-boundary` if it's installed. Frameworks may provide their own (`error.tsx` in Next.js).
+- Place boundaries around independent regions (a widget, a route segment), not just once at the root. Give each a fallback with a retry that resets it (`resetKeys` or a changed `key`).
+- Handle event-handler and async errors with `try/catch` and state; to route them into a boundary, set state and rethrow during render.
+- Report the error in `componentDidCatch` (or the root's `onCaughtError`/`onUncaughtError` on React 19) to the project's logger.
+
+## 7. Context vs state libraries
+
+- Context is a dependency-injection mechanism, not a store: every consumer re-renders when the value identity changes.
+- Split contexts by update frequency. Never put fast-changing values (mouse position, form text) in a widely consumed context.
+- Server data belongs in a query cache, not context or Redux.
+- Pick a store (Zustand, Redux Toolkit, Jotai) only for shared, frequently updated client state, and use selectors so components subscribe to slices.
+
+## 8. Accessibility basics
+
+- Use the right element: `<button>` for actions, `<a href>` for navigation, `<label>` for inputs, headings in order. A `<div onClick>` is not a button.
+- Every image has `alt` (`alt=""` if decorative). Icon-only buttons have `aria-label`.
+- Keyboard: everything clickable is reachable with Tab and works with Enter/Space; focus is visible; dialogs trap focus and return it on close (prefer `<dialog>` or the project's headless UI library).
+- After route changes or async updates, move focus or announce the change.
+- Lists use stable, unique `key`s from the data (an id), never the array index when items can be reordered, inserted or removed.
+- For full audits use the `web-accessibility` skill.
+
+## Never
+
+- Never mutate state or props in place (`arr.push`, `obj.x = 1`); create new values.
+- Never suppress `react-hooks` lint rules to make a warning go away.
+- Never put secrets or tokens in client code or `localStorage` because "it's only the frontend".
+- Never use `dangerouslySetInnerHTML` with unsanitised input.
+
+## Stop and ask the user
+
+- Before adding a new state, data or form library.
+- Before converting many components between controlled and uncontrolled, or between class and function components, beyond the task.
+- When the expected behaviour on error, empty or loading states isn't specified.
+
+## Report back
+
+End with: components changed, where each new piece of state lives and why, effects added or removed, the lint and test commands you ran with results, and anything not checked (for example "did not test with a screen reader").

package/skills/react-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Should this filter state live in the parent component, the URL, or a context?",
+    "I have a useEffect that copies props into state and it keeps getting out of sync, how should I restructure it?",
+    "Build a signup form component in React with validation errors shown under each field",
+    "Our dashboard crashes completely when one widget throws, add error boundaries properly",
+    "Is it worth adding Zustand or should I just use React context for the cart state?",
+    "Write a custom hook that subscribes to window resize and cleans up correctly"
+  ],
+  "should_not_trigger": [
+    "The product list re-renders 200 times when I type in the search box, profile it and speed it up",
+    "Should this Next.js page be a server component or a client component?",
+    "Review this React pull request for stale closures and hook violations",
+    "Set up revalidateTag caching for the blog posts in my App Router app",
+    "Write Playwright end-to-end tests for the checkout flow",
+    "Make my React Native FlatList scroll smoothly on Android"
+  ]
+}

package/skills/react-performance/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: react-performance
+description: Measure-first workflow for slow React UIs - profile renders with React DevTools and the Profiler API, cut wasted re-renders with memo, useMemo and useCallback only where the profile shows a win (or let React Compiler do it), virtualise long lists, split code with lazy and Suspense, remove request waterfalls, and shrink the JavaScript bundle. Use when a React or Next.js screen feels laggy, typing or scrolling stutters, a component re-renders too often, Interaction to Next Paint is poor, or the client bundle has grown too big.
+license: MIT
+compatibility: Any Agent Skills host. Applies to React 18 and 19 in any framework. Needs Node.js, the project's package manager and a browser with React DevTools for profiling.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# React performance
+
+No optimisation without a measurement before and after. Most React slowness comes from a few causes: rendering too much, rendering too often, loading too much JavaScript, or waiting on requests one after another. Component design rules live in `react-patterns`; Next.js caching and server/client splits in `nextjs-patterns`; Core Web Vitals and non-React page speed in `web-performance`.
+
+## 1. Define the problem
+
+1. Get a concrete symptom from the user: which screen, which interaction (typing, scrolling, opening a panel, first load), on what device. If it's vague, ask.
+2. Classify it:
+   - **Interaction is slow** (input lag, janky scroll): render cost. Go to 2.
+   - **First load is slow** (blank screen, late content): bundle or waterfalls. Go to 5 and 6.
+3. Measure in a production build (`npm run build` then the project's preview/start command). Development mode and StrictMode double-render and are several times slower; never judge speed there.
+
+## 2. Measure renders
+
+1. React DevTools → Profiler: record the slow interaction, then read the flame graph and ranked chart. Note the slowest commits, which components rendered, and "Why did this render?" (enable "Record why each component rendered while profiling" in settings).
+2. Turn on "Highlight updates when components render" to see what re-renders while you interact.
+3. Use the browser Performance panel with CPU throttling (4x or 6x) for long tasks over 50 ms and layout/paint cost that DevTools won't show.
+4. For numbers you can compare in code or CI, wrap the subtree in `<Profiler id="Grid" onRender={(id, phase, actualDuration, baseDuration) => ...}>`. `actualDuration` is time spent rendering this commit; `baseDuration` estimates a full re-render without memoisation. Profiling a production build needs the profiling build of `react-dom` (see the React docs for your bundler); `<Profiler>` adds overhead, so remove it or gate it after measuring.
+5. Write down the baseline: commit duration and count for the interaction, or long-task total. You'll compare against it.
+
+## 3. Fix rendering cost, cheapest first
+
+Work down this list and re-measure after each change:
+
+1. **Move state down.** If typing in one input re-renders the whole page, the state is too high. Move it into the component that uses it.
+2. **Lift content up (children as props).** A parent with fast-changing state that renders `{children}` doesn't re-render those children.
+3. **Split contexts.** One context with a frequently changing value re-renders every consumer. Split by update rate, or move fast state to a store with selectors.
+4. **Stop recreating expensive work.** `useMemo` for a computation the profile shows is slow (rule of thumb: over ~1 ms per render) or for an object/array passed to a memoised child or an effect dependency.
+5. **Skip unchanged subtrees.** `React.memo(Component)` on a component that renders often with the same props and is costly to render. It only helps if every prop is stable: wrap callbacks in `useCallback`, objects in `useMemo`, or pass primitives.
+6. **Defer non-urgent updates.** `useDeferredValue(query)` for a slow results list behind a fast input; `startTransition(() => setFilter(x))` for updates that can be interrupted.
+7. **Virtualise long lists** (section 4).
+
+Memoisation rules:
+- Don't wrap everything. `memo`/`useMemo`/`useCallback` cost memory and comparisons; unprofiled memoisation is noise.
+- A memoised child receiving `onClick={() => ...}` or `style={{...}}` inline never skips; fix the prop, not the child.
+- Keys: stable ids, never `Math.random()` or array index for lists that change. A changing key remounts the subtree, which is far slower than a re-render.
+- If the project has React Compiler enabled (`babel-plugin-react-compiler`, or `reactCompiler: true` in Next.js 16, `experimental.reactCompiler` in 15), it memoises automatically. Don't add manual `useMemo`/`useCallback` to compiled code unless a profile shows it's still needed; do keep components pure so the compiler doesn't skip them (the `react-hooks` lint compiler rules report why).
+- Don't enable the compiler as a side effect of a perf fix; ask first.
+
+## 4. Long lists and big tables
+
+- Over a few hundred rows, or rows that are expensive, render only what's visible. Use the library already in the project; otherwise `@tanstack/react-virtual` or `react-window`.
+- Give rows a fixed or measured height; variable heights need the library's measurement API.
+- Keep row components memoised with stable props, and keep scroll position, focus and keyboard navigation working. Check that Ctrl+F and screen readers are acceptable for the use case, or paginate instead.
+- For simple long pages, CSS `content-visibility: auto` with `contain-intrinsic-size` can be enough without a library.
+
+## 5. Waterfalls
+
+A waterfall is request B starting only after request A finishes when it didn't need A.
+
+1. Open the Network panel (throttled to "Fast 4G") and look for staircase-shaped requests.
+2. Common causes and fixes:
+   - Parent fetches, renders child, child fetches: hoist both fetches to the route loader or Server Component and start them together (`Promise.all`), or prefetch.
+   - Sequential `await`s in one function for independent data: start promises first, await later.
+   - `React.lazy` component that then fetches its data: start the data request in parallel with loading the code (route loader, prefetch on hover/intent).
+   - A `<Suspense>` boundary around each sibling that each suspends in turn: put siblings that load together under one boundary, separate ones under their own.
+3. In Next.js, fetch on the server and stream with `<Suspense>`; see `nextjs-patterns`.
+
+## 6. Bundle size and code splitting
+
+1. Measure what ships:
+   - Vite/Rollup: `rollup-plugin-visualizer`.
+   - webpack: `webpack-bundle-analyzer`.
+   - Next.js with Turbopack (16.1+): `npx next analyze` (`--output` writes to `.next/diagnostics/analyze` for before/after diffs). Next.js on webpack: `@next/bundle-analyzer` wrapped in `next.config` with `enabled: process.env.ANALYZE === "true"`, then `ANALYZE=true npm run build`.
+   - Any build with source maps: `source-map-explorer`.
+2. Look for: a large dependency used for one function (date, lodash, icon or chart libraries), duplicates of the same package at two versions, server-only or test code in the client bundle, and polyfills you don't need.
+3. Fix, in order: import only what you use (`import debounce from "lodash/debounce"`, per-icon imports); replace heavy libraries with platform APIs (`Intl.DateTimeFormat`, `structuredClone`) or lighter ones (ask before swapping); dedupe versions.
+4. Split by route first, then by heavy, rarely used components (editors, charts, maps, modals): `const Chart = lazy(() => import("./Chart"))` inside `<Suspense fallback>`; in Next.js use `next/dynamic` or keep the component on the server.
+5. Don't split tiny components; each chunk costs a request.
+6. Re-run the analyser and record the size change (gzip/brotli).
+
+## Never
+
+- Never claim a speed-up without before/after numbers from the same build type and device profile.
+- Never measure in development mode.
+- Never suppress `exhaustive-deps` to "stop an effect re-running"; fix the unstable dependency.
+- Never add a virtualisation, state or memo library when moving state or fixing a prop solves it.
+
+## Stop and ask the user
+
+- When the symptom or target (for example "INP under 200 ms on a mid-range Android") isn't stated.
+- Before replacing a dependency, enabling React Compiler, or changing list UX (virtualising, paginating).
+- When the fix needs a design change (removing a feature from a screen, changing data shape on the API).
+
+## Report back
+
+```
+Symptom: <screen + interaction>
+Baseline: <metric, build type, device/throttle>
+Cause: <what the profile showed>
+Change: <files and what changed>
+After: <same metric, same conditions>
+Not checked: <e.g. low-end mobile, Safari>
+```

package/skills/react-performance/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Typing in the search box lags badly because the whole results table re-renders on every keystroke",
+    "Use the React Profiler to find out why my dashboard is slow when I toggle the sidebar",
+    "Our main JS chunk is 1.8 MB, help me code split the React app and find what's bloating it",
+    "Rendering 10,000 rows in this React table freezes the browser, should I virtualise it?",
+    "Is wrapping every component in React.memo and useCallback actually helping or hurting?",
+    "The page loads data in a staircase: user, then orders, then items. Fix the waterfall in our React app"
+  ],
+  "should_not_trigger": [
+    "Should the shopping cart state live in context or in Zustand?",
+    "How do I write a server action that updates a profile in Next.js App Router?",
+    "Benchmark these two sorting functions in Node and tell me which is faster",
+    "Improve the Lighthouse SEO score and meta tags on our marketing site",
+    "Review this React PR for hook rule violations and missing keys",
+    "Our Postgres queries are slow, add the right indexes"
+  ]
+}

package/skills/react-testing/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: react-testing
+description: React Testing Library tests for components and custom hooks under Vitest or Jest, written the way a user drives the UI - userEvent.setup() interactions, getByRole and accessible-name queries, findBy and waitFor for async updates, MSW request handlers instead of mocked fetch, render wrappers for providers, routers and query clients, and renderHook for hooks. Use when writing or fixing tests for a React component or hook, replacing Enzyme or snapshot-heavy tests, a test fails with "not wrapped in act(...)" or cannot find an element, or tests break whenever a component is refactored.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node 18+ (Node 22+ with MSW 3), the project's test runner (Vitest or Jest) with a DOM environment (jsdom or happy-dom), @testing-library/react, @testing-library/user-event and @testing-library/jest-dom; MSW for network mocks.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# React testing
+
+Test a React component the way a person uses it: find things by role and label, act with a real-ish user, wait for what appears on screen, and fake only the network. A test that survives a refactor of the component's internals is the goal.
+
+For runner setup, module mocks and fake timers in general, see `typescript-testing`. For full-browser journeys, see `e2e-testing-playwright`. This skill is the component and hook layer.
+
+## 0. Before you start
+
+1. Find the runner and environment: `vitest.config.*` / `vite.config.*` `test` block (`environment: 'jsdom'`, `setupFiles`), or `jest.config.*` (`testEnvironment: 'jsdom'`, `setupFilesAfterEnv`). Note the test command in `package.json`.
+2. Check the setup file imports jest-dom matchers: `import '@testing-library/jest-dom/vitest'` for Vitest, `import '@testing-library/jest-dom'` for Jest. If there is no setup file, add one (setup in `references/setup.md`).
+3. Look for an existing custom `render` (often `test/utils.tsx` or `test-utils.tsx`). Reuse it. If providers are wrapped by hand in every test, propose one.
+4. Run the existing suite once. If it is already red, **stop and tell the user** which tests fail before writing new ones.
+
+## 1. Pick what to test
+
+- One behaviour per test, named for what the user sees: `shows an error when the email is invalid`.
+- Cover: initial render, each interaction that changes the screen, loading, empty and error states, and the callback or request the component is responsible for.
+- Do not test: state variable values, which hook was called, CSS class names, child component props, or the number of renders. Those are implementation details.
+
+## 2. Query priority
+
+Use the first that works (full table and pitfalls in `references/queries.md`):
+
+1. `getByRole('button', { name: /save/i })` - almost everything.
+2. `getByLabelText` - form fields.
+3. `getByPlaceholderText`, `getByText`, `getByDisplayValue`.
+4. `getByAltText`, `getByTitle`.
+5. `getByTestId` - only when nothing user-visible identifies it.
+
+Decision rules:
+
+- `getBy*` when it must be there now; `queryBy*` only to assert absence (`expect(queryByRole('alert')).not.toBeInTheDocument()`); `findBy*` when it appears after an async update.
+- If `getByRole` cannot find a control, the markup is probably inaccessible (a clickable `div`). Say so and suggest the fix rather than switching to a test ID.
+- Use `screen` rather than destructuring from `render`.
+- Use `within(row)` to scope queries inside a list item, dialog or table row.
+
+## 3. Interact with user-event
+
+```ts
+const user = userEvent.setup();
+render(<LoginForm onSubmit={onSubmit} />);
+await user.type(screen.getByLabelText(/email/i), 'ada@example.com');
+await user.click(screen.getByRole('button', { name: /sign in/i }));
+expect(onSubmit).toHaveBeenCalledWith({ email: 'ada@example.com' });
+```
+
+- Call `userEvent.setup()` once per test, before `render`, and `await` every action.
+- Prefer user-event over `fireEvent`; it fires the full event sequence (pointer, focus, keydown, input). Use `fireEvent` only for events user-event does not model (for example `scroll`).
+- With fake timers, pass `userEvent.setup({ advanceTimers: vi.advanceTimersByTime })` (or `jest.advanceTimersByTime`), or actions hang.
+
+## 4. Async updates
+
+- `await screen.findByRole(...)` for something that appears.
+- `await waitFor(() => expect(...))` for an assertion that becomes true; one assertion per `waitFor`, and no side effects inside it.
+- `await waitForElementToBeRemoved(() => screen.queryByText(/loading/i))` for spinners.
+- "Not wrapped in act(...)" means an update happened after the test stopped waiting. Fix it by awaiting the thing that causes the update (a `findBy`, the user action), not by wrapping code in `act` by hand. RTL's `render` and user-event already wrap in `act`.
+
+## 5. Network: MSW, not mocked fetch
+
+Mock at the network boundary so the component's real fetch code, query library and error handling run. Handlers, server lifecycle and per-test overrides are in `references/msw.md`.
+
+- One shared `server` with happy-path handlers; override per test with `server.use(...)` for errors and empty results.
+- Make unhandled requests fail the test (`onUnhandledRequest: 'error'` in MSW 2, `onUnhandledFrame: 'error'` in MSW 3), so a typo in a URL is not a silent pass.
+- Assert on what the user sees after the response. Assert on the request body only when sending it is the component's job.
+- Create a fresh `QueryClient` per test with `retry: false`, or error tests wait through retries.
+
+## 6. Providers, routers and context
+
+- Wrap with a custom `render` that accepts options (initial route, user, theme) and returns `render(ui, { wrapper })`. Example in `references/setup.md`.
+- Router: render inside `MemoryRouter` with `initialEntries`, or the framework's test helper. Assert navigation by what the new screen shows.
+- Context: render with the real provider and real initial value. Only mock a context whose provider talks to the outside world (auth SDK, feature flags).
+- Next.js: mock `next/navigation` hooks only when the component calls them; async Server Components cannot be rendered by RTL, test their output with e2e tests or test the data function directly.
+
+## 7. Hooks
+
+- Prefer testing a hook through a small component that uses it, if the hook only exists for one component.
+- For a shared hook, `renderHook(() => useCounter(), { wrapper })` from `@testing-library/react`; read `result.current` after each update, and wrap direct state changes in `act(() => result.current.increment())`.
+- Change props with `rerender(newProps)` and check cleanup with `unmount()`.
+
+## 8. Run and finish
+
+1. Run only the new test file, then the full suite.
+2. Check each new test fails when you break the behaviour it covers (comment out the handler line, change the text). A test that cannot fail is removed or rewritten.
+3. Run the suite twice; a test that passes once and fails once has a missing await or shared state.
+
+## Never
+
+- Never snapshot a whole component as the only assertion.
+- Never assert on `container.querySelector('.btn-primary')` or component internals.
+- Never use `waitFor` with an empty callback or arbitrary `setTimeout` sleeps.
+- Never mock the component under test, its child components to "isolate" it, or `fetch` itself when MSW is available.
+- Never delete or `.skip` a failing test to get green without telling the user why.
+
+## Migrating from Enzyme or implementation tests
+
+Rewrite, do not translate: list the behaviours the old test protected, delete `shallow`/`instance()`/`state()` calls, and write one RTL test per behaviour. Stop and ask before deleting a test whose behaviour you cannot identify.
+
+## Report back
+
+```
+## React tests: <component or hook>
+Added: <test names>
+Changed: <test names and why>
+Command: <exact command>   Result: <passed>/<total>
+Mutation check: <which behaviour you broke and which test caught it>
+Not covered: <states or flows left untested and why>
+Accessibility notes: <controls that had no role or label>
+```

package/skills/react-testing/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Write React Testing Library tests for the LoginForm component, typing into the fields with user-event",
+    "My component test keeps warning 'An update to TodoList inside a test was not wrapped in act(...)', how do I fix it?",
+    "Replace the Enzyme shallow tests for the CartDrawer with tests that don't break on every refactor",
+    "Mock the /api/orders call with MSW so the OrdersTable test can cover the empty and error states",
+    "How do I test my useDebouncedSearch hook that needs the QueryClientProvider?",
+    "getByText can't find the Save button in my Vitest component test even though it renders"
+  ],
+  "should_not_trigger": [
+    "Write Vitest unit tests for the date formatting utilities in src/lib",
+    "Write Playwright tests that log in and complete checkout in a real browser",
+    "Review this React pull request for hook dependency bugs before I merge it",
+    "Should the selected-tab state live in the URL or in component state?",
+    "Click through the staging site and file bugs for anything broken before the demo",
+    "The settings page re-renders on every keystroke, profile it and fix it"
+  ]
+}

package/skills/react-testing/references/msw.md

@@ -0,0 +1,64 @@
+# MSW network mocks for component tests
+
+MSW 2.x and 3.x syntax (handlers below are the same in both). Check the installed major in `package.json`; MSW 1 used `rest.get` and `res(ctx.json())`. MSW 3 is ESM-only and needs Node 22+; on a CommonJS Jest setup stay on MSW 2 unless the user agrees to migrate.
+
+## Handlers and server
+
+```ts
+// src/test/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const handlers = [
+  http.get('/api/users/:id', ({ params }) =>
+    HttpResponse.json({ id: params.id, name: 'Ada Lovelace' })),
+  http.post('/api/todos', async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: 't1', ...body }, { status: 201 });
+  }),
+];
+```
+
+```ts
+// src/test/server.ts
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);
+```
+
+Lifecycle (in the setup file): `server.listen({ onUnhandledRequest: 'error' })` before all, `server.resetHandlers()` after each, `server.close()` after all. MSW 3 renamed the option: `server.listen({ onUnhandledFrame: 'error' })`. MSW 2 uses `onUnhandledRequest`.
+
+## Per-test overrides
+
+```ts
+it('shows an error when the profile cannot load', async () => {
+  server.use(
+    http.get('/api/users/:id', () => HttpResponse.json({ message: 'nope' }, { status: 500 })),
+  );
+  renderWithProviders(<Profile id="1" />);
+  expect(await screen.findByRole('alert')).toHaveTextContent(/could not load/i);
+});
+```
+
+- Network failure: `http.get(url, () => HttpResponse.error())`.
+- Slow response to test a spinner: `import { delay } from 'msw'` (MSW 3 also exports it from `msw/utils`) then `await delay(200)` inside the resolver; or keep it pending with `await delay('infinite')`.
+- One-off: `http.get(url, resolver, { once: true })`.
+- Fake timers: MSW 3 no longer patches `setTimeout`, so with fake timers a `delay()` response only resolves after you advance the timers.
+
+## Asserting the request
+
+Only when sending the right data is the component's job:
+
+```ts
+let sent: unknown;
+server.use(http.post('/api/todos', async ({ request }) => {
+  sent = await request.json();
+  return HttpResponse.json({ id: 't1' }, { status: 201 });
+}));
+// ...interact...
+await waitFor(() => expect(sent).toEqual({ title: 'Buy milk' }));
+```
+
+## Absolute vs relative URLs
+
+jsdom resolves relative `fetch('/api/...')` against its `location` (default `http://localhost/` in Vitest and Jest). If the app uses an `API_URL` env variable, write handlers with the same base, or use a wildcard (`*/api/users/:id`).

package/skills/react-testing/references/queries.md

@@ -0,0 +1,41 @@
+# Queries and matchers
+
+## Variants
+
+| Prefix | 0 matches | 1 match | >1 match | Async |
+|---|---|---|---|---|
+| `getBy` | throws | returns | throws | no |
+| `queryBy` | `null` | returns | throws | no |
+| `findBy` | rejects | resolves | rejects | yes (default 1000 ms) |
+| `getAllBy` / `queryAllBy` / `findAllBy` | throw / `[]` / reject | array | array | as above |
+
+## Role queries that trip people up
+
+| Element | Role |
+|---|---|
+| `<a href>` | `link` (no `href` means no role) |
+| `<input type="text">`, `<textarea>` | `textbox` |
+| `<input type="search">` | `searchbox` |
+| `<input type="checkbox">` | `checkbox` |
+| `<input type="number">` | `spinbutton` |
+| `<select>` | `combobox` (single) or `listbox` (multiple / size > 1) |
+| `<h1>`-`<h6>` | `heading`, filter with `{ level: 2 }` |
+| `<ul>`, `<li>` | `list`, `listitem` |
+| `<table>` rows | `row`, `cell`, `columnheader` |
+| `<dialog open>` or `role="dialog"` | `dialog` |
+| `<img alt="">` | `presentation` (not `img`) |
+
+Useful options: `name` (accessible name, string or regex), `hidden: true` (include `aria-hidden`), `selected`, `checked`, `pressed`, `expanded`, `level`.
+
+`screen.logTestingPlaygroundURL()` and `screen.debug()` help find the right query; delete them before committing.
+
+## jest-dom matchers worth using
+
+`toBeInTheDocument`, `toBeVisible`, `toBeDisabled` / `toBeEnabled`, `toHaveValue`, `toBeChecked`, `toHaveAccessibleName`, `toHaveAccessibleDescription`, `toHaveAttribute`, `toHaveTextContent`, `toHaveFocus`, `toHaveAccessibleErrorMessage` (check the installed jest-dom version supports it).
+
+## Common mistakes
+
+- `expect(screen.getByText('x')).toBeInTheDocument()` is fine; `expect(screen.queryByText('x')).toBeInTheDocument()` hides the better error message `getBy` gives.
+- `await waitFor(() => screen.getByText('x'))` should be `await screen.findByText('x')`.
+- Text split across elements (`<b>3</b> items`) does not match `getByText('3 items')`; query the container by role or use a function matcher.
+- `userEvent.type` into a field that already has a value appends; call `user.clear(field)` first.

package/skills/react-testing/references/setup.md

@@ -0,0 +1,74 @@
+# Setup and custom render
+
+## Vitest
+
+```ts
+// vitest.config.ts (or the `test` block of vite.config.ts)
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',        // or 'happy-dom'
+    setupFiles: ['./src/test/setup.ts'],
+    globals: false,              // keep explicit imports unless the repo already uses globals
+  },
+});
+```
+
+```ts
+// src/test/setup.ts
+import '@testing-library/jest-dom/vitest';
+import { afterAll, afterEach, beforeAll } from 'vitest';
+import { cleanup } from '@testing-library/react';
+import { server } from './server';
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' })); // MSW 3: onUnhandledFrame
+afterEach(() => { server.resetHandlers(); cleanup(); });
+afterAll(() => server.close());
+```
+
+`cleanup` runs automatically when the runner exposes a global `afterEach` (Jest, or Vitest with `globals: true`). With Vitest and `globals: false`, call it yourself as above.
+
+Install: `npm i -D vitest jsdom @testing-library/react @testing-library/dom @testing-library/user-event @testing-library/jest-dom msw` (React Testing Library 16 lists `@testing-library/dom` as a peer dependency).
+
+## Jest
+
+```js
+// jest.config.js
+module.exports = {
+  testEnvironment: 'jsdom',            // needs the jest-environment-jsdom package from Jest 28
+  setupFilesAfterEnv: ['<rootDir>/src/test/setup.ts'],
+};
+```
+
+In the setup file use `import '@testing-library/jest-dom';` and the same MSW lifecycle with Jest globals.
+
+MSW 2 under Jest + jsdom may need the Fetch API globals (`Request`, `Response`, `TextEncoder`) supplied; MSW's docs recommend `jest-fixed-jsdom` as the environment for this. Vitest does not need it.
+
+## Custom render
+
+```tsx
+// src/test/utils.tsx
+import { render, type RenderOptions } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { MemoryRouter } from 'react-router-dom';
+import type { ReactElement, ReactNode } from 'react';
+
+type Options = RenderOptions & { route?: string };
+
+export function renderWithProviders(ui: ReactElement, { route = '/', ...options }: Options = {}) {
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  const Wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={client}>
+      <MemoryRouter initialEntries={[route]}>{children}</MemoryRouter>
+    </QueryClientProvider>
+  );
+  return { client, ...render(ui, { wrapper: Wrapper, ...options }) };
+}
+
+export * from '@testing-library/react';
+```
+
+Keep only the providers the app actually uses. A new `QueryClient` per call stops cached data leaking between tests.