tribunal-kit 9.2.4 → 9.2.5

package/.agents/skills/react-specialist/SKILL.md

@@ -1,280 +1,280 @@
----
-name: react-specialist
-description: "Use when React 19+ specialist. use(), useActionState, useOptimistic, React Compiler, Server/Client Components, Zustand/Jotai, React Query. Use when building components, managing state, optimizing renders."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - nextjs-react-expert
-  - react-doctor
-  - baseline-ui
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# React 19+ — Dense Reference
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
-## 2026 React 19 Performance & Architecture Invariants
-
-1. **Direct `ref` as a Prop**: Never use `forwardRef`. In React 19, `ref` is passed directly as a standard component prop.
-2. **Server Actions & `useActionState`**: Prefer native form actions and `useActionState` over manual `onSubmit` event handlers with `preventDefault()`.
-3. **Optimistic Updates**: Use `useOptimistic` for instant local feedback before network requests settle.
-4. **Transition-Aware State Updates**: Wrap non-urgent state updates in `startTransition` to keep main thread interactions responsive.
-5. **No Context Provider Wrapper Boilerplate**: In React 19, `<ThemeContext value={theme}>` replaces `<ThemeContext.Provider value={theme}>`.
-
-## Hallucination Traps (Read First)
-
-- ❌ `forwardRef((props, ref) => ...)` → ✅ In React 19, accept `ref` directly as a component prop
-- ❌ `<ThemeContext.Provider value={...}>` → ✅ In React 19, use `<ThemeContext value={...}>`
-- ❌ `useFormState()` → ✅ `useActionState()` (stable API)
-- ❌ `useContext()` inside `if` conditionals → ✅ `use(Context)` CAN be called conditionally
-- ❌ Manual `useMemo`/`useCallback` everywhere → ✅ Let React Compiler handle memoization automatically
-- ❌ Destructuring whole store `const { user } = useStore()` → ✅ Granular selector `useStore(s => s.user)`
-- ❌ `next/router` → ✅ `next/navigation` in App Router
-
----
-
-## React 19 Core APIs
-
-### `use()` — Replaces many useEffect patterns
-
-```tsx
-import { use } from 'react';
-// Reads promises (suspends until resolved)
-function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
-  const user = use(userPromise); // suspends
-  return <h1>{user.name}</h1>;
-}
-// Reads context — CAN be called conditionally (unlike useContext)
-function Admin({ isAdmin }: { isAdmin: boolean }) {
-  if (isAdmin) return <Panel theme={use(ThemeContext)} />;
-  return <PublicPanel />;
-}
-```
-
-### `useActionState` — Form actions with state
-
-```tsx
-import { useActionState } from 'react'; // NOT useFormState
-
-async function submitForm(prevState: FormState, formData: FormData) {
-  const email = formData.get('email') as string;
-  if (!email.includes('@')) return { error: 'Invalid email' };
-  await saveToDatabase(email);
-  return { error: null, success: true };
-}
-
-function SignupForm() {
-  const [state, formAction, isPending] = useActionState(submitForm, { error: null });
-  return (
-    <form action={formAction}>
-      <input name="email" disabled={isPending} />
-      {state.error && <p>{state.error}</p>}
-      <button disabled={isPending}>{isPending ? 'Saving...' : 'Submit'}</button>
-    </form>
-  );
-}
-```
-
-### `useOptimistic` — Instant UI feedback
-
-```tsx
-import { useOptimistic } from 'react';
-function TodoList({ todos }: { todos: Todo[] }) {
-  const [optimistic, addOptimistic] = useOptimistic(todos, (current, newTodo: Todo) => [
-    ...current,
-    newTodo,
-  ]);
-  async function handleAdd(formData: FormData) {
-    addOptimistic({ id: crypto.randomUUID(), title: formData.get('title'), pending: true });
-    await saveTodo(formData.get('title') as string);
-  }
-  return (
-    <form action={handleAdd}>
-      {optimistic.map(t => (
-        <li key={t.id} style={{ opacity: t.pending ? 0.5 : 1 }}>
-          {t.title}
-        </li>
-      ))}
-    </form>
-  );
-}
-```
-
-### `useFormStatus` — Button pending state (must be INSIDE `<form>`)
-
-```tsx
-import { useFormStatus } from 'react-dom';
-// ❌ TRAP: Cannot be called in the same component as <form>
-function SubmitButton() {
-  const { pending } = useFormStatus(); // reads nearest parent form
-  return <button disabled={pending}>{pending ? 'Saving...' : 'Save'}</button>;
-}
-```
-
-### `useTransition` — Non-blocking updates (React 19: supports async)
-
-```tsx
-const [isPending, startTransition] = useTransition();
-startTransition(async () => {
-  const data = await search(query); // async supported in React 19 only
-  setResults(data);
-});
-```
-
-### `useDeferredValue` — Stale-while-rerender
-
-```tsx
-const deferredQuery = useDeferredValue(query);
-const isStale = query !== deferredQuery;
-return (
-  <div style={{ opacity: isStale ? 0.6 : 1 }}>
-    <ExpensiveList query={deferredQuery} />
-  </div>
-);
-// React 19: useDeferredValue(value, initialFallback) — 2-arg form
-```
-
----
-
-## React Compiler (React 19)
-
-- Auto-memoizes components/values/callbacks. **Don't manually memoize in React 19 projects.**
-- ❌ `useMemo(() => calc(a), [a])` / `useCallback(fn, [id])` / `React.memo(Comp)` — legacy
-- ✅ Write plain functions/values. Compiler optimizes automatically.
-- Exception: still use manual memo if compiler is explicitly disabled in config.
-
----
-
-## Component Patterns
-
-### Compound Components (shared state via context)
-
-```tsx
-const TabsContext = createContext<{ active: string; setActive: (id: string) => void } | null>(null);
-function Tabs({ children, defaultTab }: { children: ReactNode; defaultTab: string }) {
-  const [active, setActive] = useState(defaultTab);
-  return (
-    <TabsContext value={{ active, setActive }}>
-      <div>{children}</div>
-    </TabsContext>
-  );
-}
-function Tab({ id, children }: { id: string; children: ReactNode }) {
-  const ctx = use(TabsContext)!;
-  return (
-    <button onClick={() => ctx.setActive(id)} aria-selected={ctx.active === id}>
-      {children}
-    </button>
-  );
-}
-```
-
-### Render Props / Higher Order Hooks
-
-Prefer custom hooks over render props for modern React.
-
-### Context Performance Pattern
-
-```tsx
-// Split context — prevents all consumers from re-rendering on every change
-const CountStateCtx = createContext<number>(0);
-const CountDispatchCtx = createContext<Dispatch<Action>>(() => {});
-```
-
----
-
-## State Management
-
-### Zustand (preferred for global state)
-
-```tsx
-import { create } from 'zustand';
-import { persist } from 'zustand/middleware';
-const useStore = create<Store>()(
-  persist(
-    (set, get) => ({
-      count: 0,
-      increment: () => set(s => ({ count: s.count + 1 })),
-      getDoubled: () => get().count * 2,
-    }),
-    { name: 'my-store' },
-  ),
-);
-// ❌ TRAP: Do NOT destructure the whole store — causes re-render on every change
-// ✅ const count = useStore(s => s.count); // selector
-```
-
-### Jotai (preferred for derived/atomic state)
-
-```tsx
-import { atom, useAtom, useAtomValue, useSetAtom } from 'jotai';
-const countAtom = atom(0);
-const doubledAtom = atom(get => get(countAtom) * 2); // derived atom
-// ❌ TRAP: atomWithStorage is from jotai/utils — NOT from jotai
-import { atomWithStorage } from 'jotai/utils';
-```
-
-### React Query / TanStack Query
-
-```tsx
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-const { data, isPending, error } = useQuery({
-  queryKey: ['user', userId],
-  queryFn: () => fetchUser(userId),
-  staleTime: 5 * 60 * 1000, // don't refetch for 5 minutes
-});
-// Optimistic update:
-const qc = useQueryClient();
-const mutation = useMutation({
-  mutationFn: updateUser,
-  onMutate: async newUser => {
-    await qc.cancelQueries({ queryKey: ['user', newUser.id] });
-    const prev = qc.getQueryData(['user', newUser.id]);
-    qc.setQueryData(['user', newUser.id], newUser);
-    return { prev };
-  },
-  onError: (_, __, ctx) => qc.setQueryData(['user'], ctx?.prev),
-  onSettled: () => qc.invalidateQueries({ queryKey: ['user'] }),
-});
-```
-
----
-
-## Performance
-
-| Technique                              | When                                       |
-| -------------------------------------- | ------------------------------------------ |
-| `useDeferredValue`                     | Expensive derived render (charts, filters) |
-| `useTransition`                        | Page nav, tab switches, data load          |
-| `lazy()` + `Suspense`                  | Code-split heavy components                |
-| `<Virtuoso>` / `<WindowVirtualizer>`   | Lists > 200 items                          |
-| Avoid `useEffect` for state transforms | Use `useMemo` or derived atoms             |
-
----
-
-## Refs & DOM
-
-```tsx
-// React 19: ref is now a prop (no forwardRef needed)
-function Input({ ref, ...props }: ComponentProps<'input'> & { ref?: Ref<HTMLInputElement> }) {
-  return <input ref={ref} {...props} />;
-}
-// ❌ TRAP: forwardRef is deprecated in React 19 — still works but not needed
-```
-
----
-
-## Testing Checklist
-
-- ✅ Use React Testing Library — test behavior, not implementation
-- ✅ `userEvent` over `fireEvent` (async, closer to real interaction)
-- ✅ Mock server calls with MSW (Mock Service Worker)
-- ❌ Never test internal state, ref values, or component instances
+---
+name: react-specialist
+description: "Use when React 19+ specialist. use(), useActionState, useOptimistic, React Compiler, Server/Client Components, Zustand/Jotai, React Query. Use when building components, managing state, optimizing renders."
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - nextjs-react-expert
+  - react-doctor
+  - baseline-ui
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# React 19+ — Dense Reference
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+## 2026 React 19 Performance & Architecture Invariants
+
+1. **Direct `ref` as a Prop**: Never use `forwardRef`. In React 19, `ref` is passed directly as a standard component prop.
+2. **Server Actions & `useActionState`**: Prefer native form actions and `useActionState` over manual `onSubmit` event handlers with `preventDefault()`.
+3. **Optimistic Updates**: Use `useOptimistic` for instant local feedback before network requests settle.
+4. **Transition-Aware State Updates**: Wrap non-urgent state updates in `startTransition` to keep main thread interactions responsive.
+5. **No Context Provider Wrapper Boilerplate**: In React 19, `<ThemeContext value={theme}>` replaces `<ThemeContext.Provider value={theme}>`.
+
+## Hallucination Traps (Read First)
+
+- ❌ `forwardRef((props, ref) => ...)` → ✅ In React 19, accept `ref` directly as a component prop
+- ❌ `<ThemeContext.Provider value={...}>` → ✅ In React 19, use `<ThemeContext value={...}>`
+- ❌ `useFormState()` → ✅ `useActionState()` (stable API)
+- ❌ `useContext()` inside `if` conditionals → ✅ `use(Context)` CAN be called conditionally
+- ❌ Manual `useMemo`/`useCallback` everywhere → ✅ Let React Compiler handle memoization automatically
+- ❌ Destructuring whole store `const { user } = useStore()` → ✅ Granular selector `useStore(s => s.user)`
+- ❌ `next/router` → ✅ `next/navigation` in App Router
+
+---
+
+## React 19 Core APIs
+
+### `use()` — Replaces many useEffect patterns
+
+```tsx
+import { use } from 'react';
+// Reads promises (suspends until resolved)
+function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
+  const user = use(userPromise); // suspends
+  return <h1>{user.name}</h1>;
+}
+// Reads context — CAN be called conditionally (unlike useContext)
+function Admin({ isAdmin }: { isAdmin: boolean }) {
+  if (isAdmin) return <Panel theme={use(ThemeContext)} />;
+  return <PublicPanel />;
+}
+```
+
+### `useActionState` — Form actions with state
+
+```tsx
+import { useActionState } from 'react'; // NOT useFormState
+
+async function submitForm(prevState: FormState, formData: FormData) {
+  const email = formData.get('email') as string;
+  if (!email.includes('@')) return { error: 'Invalid email' };
+  await saveToDatabase(email);
+  return { error: null, success: true };
+}
+
+function SignupForm() {
+  const [state, formAction, isPending] = useActionState(submitForm, { error: null });
+  return (
+    <form action={formAction}>
+      <input name="email" disabled={isPending} />
+      {state.error && <p>{state.error}</p>}
+      <button disabled={isPending}>{isPending ? 'Saving...' : 'Submit'}</button>
+    </form>
+  );
+}
+```
+
+### `useOptimistic` — Instant UI feedback
+
+```tsx
+import { useOptimistic } from 'react';
+function TodoList({ todos }: { todos: Todo[] }) {
+  const [optimistic, addOptimistic] = useOptimistic(todos, (current, newTodo: Todo) => [
+    ...current,
+    newTodo,
+  ]);
+  async function handleAdd(formData: FormData) {
+    addOptimistic({ id: crypto.randomUUID(), title: formData.get('title'), pending: true });
+    await saveTodo(formData.get('title') as string);
+  }
+  return (
+    <form action={handleAdd}>
+      {optimistic.map(t => (
+        <li key={t.id} style={{ opacity: t.pending ? 0.5 : 1 }}>
+          {t.title}
+        </li>
+      ))}
+    </form>
+  );
+}
+```
+
+### `useFormStatus` — Button pending state (must be INSIDE `<form>`)
+
+```tsx
+import { useFormStatus } from 'react-dom';
+// ❌ TRAP: Cannot be called in the same component as <form>
+function SubmitButton() {
+  const { pending } = useFormStatus(); // reads nearest parent form
+  return <button disabled={pending}>{pending ? 'Saving...' : 'Save'}</button>;
+}
+```
+
+### `useTransition` — Non-blocking updates (React 19: supports async)
+
+```tsx
+const [isPending, startTransition] = useTransition();
+startTransition(async () => {
+  const data = await search(query); // async supported in React 19 only
+  setResults(data);
+});
+```
+
+### `useDeferredValue` — Stale-while-rerender
+
+```tsx
+const deferredQuery = useDeferredValue(query);
+const isStale = query !== deferredQuery;
+return (
+  <div style={{ opacity: isStale ? 0.6 : 1 }}>
+    <ExpensiveList query={deferredQuery} />
+  </div>
+);
+// React 19: useDeferredValue(value, initialFallback) — 2-arg form
+```
+
+---
+
+## React Compiler (React 19)
+
+- Auto-memoizes components/values/callbacks. **Don't manually memoize in React 19 projects.**
+- ❌ `useMemo(() => calc(a), [a])` / `useCallback(fn, [id])` / `React.memo(Comp)` — legacy
+- ✅ Write plain functions/values. Compiler optimizes automatically.
+- Exception: still use manual memo if compiler is explicitly disabled in config.
+
+---
+
+## Component Patterns
+
+### Compound Components (shared state via context)
+
+```tsx
+const TabsContext = createContext<{ active: string; setActive: (id: string) => void } | null>(null);
+function Tabs({ children, defaultTab }: { children: ReactNode; defaultTab: string }) {
+  const [active, setActive] = useState(defaultTab);
+  return (
+    <TabsContext value={{ active, setActive }}>
+      <div>{children}</div>
+    </TabsContext>
+  );
+}
+function Tab({ id, children }: { id: string; children: ReactNode }) {
+  const ctx = use(TabsContext)!;
+  return (
+    <button onClick={() => ctx.setActive(id)} aria-selected={ctx.active === id}>
+      {children}
+    </button>
+  );
+}
+```
+
+### Render Props / Higher Order Hooks
+
+Prefer custom hooks over render props for modern React.
+
+### Context Performance Pattern
+
+```tsx
+// Split context — prevents all consumers from re-rendering on every change
+const CountStateCtx = createContext<number>(0);
+const CountDispatchCtx = createContext<Dispatch<Action>>(() => {});
+```
+
+---
+
+## State Management
+
+### Zustand (preferred for global state)
+
+```tsx
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+const useStore = create<Store>()(
+  persist(
+    (set, get) => ({
+      count: 0,
+      increment: () => set(s => ({ count: s.count + 1 })),
+      getDoubled: () => get().count * 2,
+    }),
+    { name: 'my-store' },
+  ),
+);
+// ❌ TRAP: Do NOT destructure the whole store — causes re-render on every change
+// ✅ const count = useStore(s => s.count); // selector
+```
+
+### Jotai (preferred for derived/atomic state)
+
+```tsx
+import { atom, useAtom, useAtomValue, useSetAtom } from 'jotai';
+const countAtom = atom(0);
+const doubledAtom = atom(get => get(countAtom) * 2); // derived atom
+// ❌ TRAP: atomWithStorage is from jotai/utils — NOT from jotai
+import { atomWithStorage } from 'jotai/utils';
+```
+
+### React Query / TanStack Query
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+const { data, isPending, error } = useQuery({
+  queryKey: ['user', userId],
+  queryFn: () => fetchUser(userId),
+  staleTime: 5 * 60 * 1000, // don't refetch for 5 minutes
+});
+// Optimistic update:
+const qc = useQueryClient();
+const mutation = useMutation({
+  mutationFn: updateUser,
+  onMutate: async newUser => {
+    await qc.cancelQueries({ queryKey: ['user', newUser.id] });
+    const prev = qc.getQueryData(['user', newUser.id]);
+    qc.setQueryData(['user', newUser.id], newUser);
+    return { prev };
+  },
+  onError: (_, __, ctx) => qc.setQueryData(['user'], ctx?.prev),
+  onSettled: () => qc.invalidateQueries({ queryKey: ['user'] }),
+});
+```
+
+---
+
+## Performance
+
+| Technique                              | When                                       |
+| -------------------------------------- | ------------------------------------------ |
+| `useDeferredValue`                     | Expensive derived render (charts, filters) |
+| `useTransition`                        | Page nav, tab switches, data load          |
+| `lazy()` + `Suspense`                  | Code-split heavy components                |
+| `<Virtuoso>` / `<WindowVirtualizer>`   | Lists > 200 items                          |
+| Avoid `useEffect` for state transforms | Use `useMemo` or derived atoms             |
+
+---
+
+## Refs & DOM
+
+```tsx
+// React 19: ref is now a prop (no forwardRef needed)
+function Input({ ref, ...props }: ComponentProps<'input'> & { ref?: Ref<HTMLInputElement> }) {
+  return <input ref={ref} {...props} />;
+}
+// ❌ TRAP: forwardRef is deprecated in React 19 — still works but not needed
+```
+
+---
+
+## Testing Checklist
+
+- ✅ Use React Testing Library — test behavior, not implementation
+- ✅ `userEvent` over `fireEvent` (async, closer to real interaction)
+- ✅ Mock server calls with MSW (Mock Service Worker)
+- ❌ Never test internal state, ref values, or component instances