tribunal-kit 4.3.0 → 4.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/.agent/history/architecture-explorer.html +352 -0
  2. package/.agent/history/architecture-graph.yaml +109 -0
  3. package/.agent/history/graph-cache.json +215 -0
  4. package/.agent/history/snapshots/migrate_refs.js.json +11 -0
  5. package/.agent/history/snapshots/scripts__changelog.js.json +12 -0
  6. package/.agent/history/snapshots/scripts__sync-version.js.json +11 -0
  7. package/.agent/history/snapshots/scripts__validate-payload.js.json +11 -0
  8. package/.agent/history/snapshots/test__integration__bridges.test.js.json +13 -0
  9. package/.agent/history/snapshots/test__integration__init.test.js.json +13 -0
  10. package/.agent/history/snapshots/test__integration__routing.test.js.json +11 -0
  11. package/.agent/history/snapshots/test__integration__swarm_dispatcher.test.js.json +13 -0
  12. package/.agent/history/snapshots/test__integration__wave2.test.js.json +13 -0
  13. package/.agent/history/snapshots/test__unit__args.test.js.json +10 -0
  14. package/.agent/history/snapshots/test__unit__case_law_manager.test.js.json +10 -0
  15. package/.agent/history/snapshots/test__unit__copyDir.test.js.json +13 -0
  16. package/.agent/history/snapshots/test__unit__graph_tools.test.js.json +11 -0
  17. package/.agent/history/snapshots/test__unit__selfInstall.test.js.json +13 -0
  18. package/.agent/history/snapshots/test__unit__semver.test.js.json +10 -0
  19. package/.agent/history/snapshots/test__unit__swarm_dispatcher.test.js.json +11 -0
  20. package/.agent/scripts/case_law_manager.js +684 -684
  21. package/.agent/scripts/dependency_analyzer.js +1 -1
  22. package/.agent/scripts/graph_builder.js +311 -0
  23. package/.agent/scripts/graph_visualizer.js +384 -0
  24. package/.agent/scripts/graph_zoom.js +154 -0
  25. package/.agent/scripts/mutation_runner.js +280 -0
  26. package/.agent/skills/agent-organizer/SKILL.md +9 -1
  27. package/.agent/skills/agentic-patterns/SKILL.md +9 -1
  28. package/.agent/skills/ai-prompt-injection-defense/SKILL.md +9 -1
  29. package/.agent/skills/api-patterns/SKILL.md +206 -198
  30. package/.agent/skills/api-security-auditor/SKILL.md +9 -1
  31. package/.agent/skills/app-builder/SKILL.md +9 -1
  32. package/.agent/skills/app-builder/templates/SKILL.md +77 -69
  33. package/.agent/skills/appflow-wireframe/SKILL.md +9 -1
  34. package/.agent/skills/architecture/SKILL.md +9 -1
  35. package/.agent/skills/authentication-best-practices/SKILL.md +9 -1
  36. package/.agent/skills/bash-linux/SKILL.md +9 -1
  37. package/.agent/skills/behavioral-modes/SKILL.md +9 -1
  38. package/.agent/skills/brainstorming/SKILL.md +9 -1
  39. package/.agent/skills/building-native-ui/SKILL.md +9 -1
  40. package/.agent/skills/clean-code/SKILL.md +9 -1
  41. package/.agent/skills/code-review-checklist/SKILL.md +9 -1
  42. package/.agent/skills/config-validator/SKILL.md +9 -1
  43. package/.agent/skills/csharp-developer/SKILL.md +9 -1
  44. package/.agent/skills/data-validation-schemas/SKILL.md +287 -279
  45. package/.agent/skills/database-design/SKILL.md +199 -191
  46. package/.agent/skills/deployment-procedures/SKILL.md +9 -1
  47. package/.agent/skills/devops-engineer/SKILL.md +9 -1
  48. package/.agent/skills/devops-incident-responder/SKILL.md +9 -1
  49. package/.agent/skills/documentation-templates/SKILL.md +9 -1
  50. package/.agent/skills/edge-computing/SKILL.md +9 -1
  51. package/.agent/skills/error-resilience/SKILL.md +387 -379
  52. package/.agent/skills/extract-design-system/SKILL.md +9 -1
  53. package/.agent/skills/framer-motion-expert/SKILL.md +203 -195
  54. package/.agent/skills/frontend-design/SKILL.md +160 -152
  55. package/.agent/skills/game-design-expert/SKILL.md +9 -1
  56. package/.agent/skills/game-engineering-expert/SKILL.md +9 -1
  57. package/.agent/skills/geo-fundamentals/SKILL.md +9 -1
  58. package/.agent/skills/github-operations/SKILL.md +9 -1
  59. package/.agent/skills/gsap-core/SKILL.md +54 -46
  60. package/.agent/skills/gsap-frameworks/SKILL.md +54 -46
  61. package/.agent/skills/gsap-performance/SKILL.md +54 -46
  62. package/.agent/skills/gsap-plugins/SKILL.md +54 -46
  63. package/.agent/skills/gsap-react/SKILL.md +54 -46
  64. package/.agent/skills/gsap-scrolltrigger/SKILL.md +54 -46
  65. package/.agent/skills/gsap-timeline/SKILL.md +54 -46
  66. package/.agent/skills/gsap-utils/SKILL.md +54 -46
  67. package/.agent/skills/i18n-localization/SKILL.md +9 -1
  68. package/.agent/skills/intelligent-routing/SKILL.md +38 -30
  69. package/.agent/skills/knowledge-graph/SKILL.md +52 -0
  70. package/.agent/skills/lint-and-validate/SKILL.md +9 -1
  71. package/.agent/skills/llm-engineering/SKILL.md +9 -1
  72. package/.agent/skills/local-first/SKILL.md +9 -1
  73. package/.agent/skills/mcp-builder/SKILL.md +9 -1
  74. package/.agent/skills/mobile-design/SKILL.md +222 -214
  75. package/.agent/skills/monorepo-management/SKILL.md +293 -285
  76. package/.agent/skills/motion-engineering/SKILL.md +193 -185
  77. package/.agent/skills/nextjs-react-expert/SKILL.md +193 -185
  78. package/.agent/skills/nodejs-best-practices/SKILL.md +9 -1
  79. package/.agent/skills/observability/SKILL.md +9 -1
  80. package/.agent/skills/parallel-agents/SKILL.md +9 -1
  81. package/.agent/skills/performance-profiling/SKILL.md +9 -1
  82. package/.agent/skills/plan-writing/SKILL.md +9 -1
  83. package/.agent/skills/platform-engineer/SKILL.md +9 -1
  84. package/.agent/skills/playwright-best-practices/SKILL.md +9 -1
  85. package/.agent/skills/powershell-windows/SKILL.md +9 -1
  86. package/.agent/skills/project-idioms/SKILL.md +9 -1
  87. package/.agent/skills/python-patterns/SKILL.md +9 -1
  88. package/.agent/skills/python-pro/SKILL.md +282 -274
  89. package/.agent/skills/react-specialist/SKILL.md +236 -228
  90. package/.agent/skills/readme-builder/SKILL.md +9 -1
  91. package/.agent/skills/realtime-patterns/SKILL.md +9 -1
  92. package/.agent/skills/red-team-tactics/SKILL.md +9 -1
  93. package/.agent/skills/rust-pro/SKILL.md +9 -1
  94. package/.agent/skills/seo-fundamentals/SKILL.md +9 -1
  95. package/.agent/skills/server-management/SKILL.md +9 -1
  96. package/.agent/skills/shadcn-ui-expert/SKILL.md +9 -1
  97. package/.agent/skills/skill-creator/SKILL.md +9 -1
  98. package/.agent/skills/sql-pro/SKILL.md +9 -1
  99. package/.agent/skills/supabase-postgres-best-practices/SKILL.md +9 -1
  100. package/.agent/skills/swiftui-expert/SKILL.md +9 -1
  101. package/.agent/skills/systematic-debugging/SKILL.md +9 -1
  102. package/.agent/skills/tailwind-patterns/SKILL.md +9 -1
  103. package/.agent/skills/tdd-workflow/SKILL.md +9 -1
  104. package/.agent/skills/test-result-analyzer/SKILL.md +9 -1
  105. package/.agent/skills/testing-patterns/SKILL.md +28 -3
  106. package/.agent/skills/trend-researcher/SKILL.md +9 -1
  107. package/.agent/skills/typescript-advanced/SKILL.md +294 -286
  108. package/.agent/skills/ui-ux-pro-max/SKILL.md +561 -116
  109. package/.agent/skills/ui-ux-researcher/SKILL.md +9 -1
  110. package/.agent/skills/vue-expert/SKILL.md +234 -226
  111. package/.agent/skills/vulnerability-scanner/SKILL.md +9 -1
  112. package/.agent/skills/web-accessibility-auditor/SKILL.md +9 -1
  113. package/.agent/skills/web-design-guidelines/SKILL.md +9 -1
  114. package/.agent/skills/webapp-testing/SKILL.md +9 -1
  115. package/.agent/skills/whimsy-injector/SKILL.md +9 -1
  116. package/.agent/skills/workflow-optimizer/SKILL.md +9 -1
  117. package/README.md +242 -242
  118. package/bin/tribunal-kit.js +157 -21
  119. package/package.json +81 -80
  120. package/scripts/validate-payload.js +73 -0
@@ -1,230 +1,230 @@
1
- ---
2
- name: react-specialist
3
- description: React 19+ specialist. use(), useActionState, useOptimistic, React Compiler, Server/Client Components, Zustand/Jotai, React Query. Use when building components, managing state, optimizing renders.
4
- allowed-tools: Read, Write, Edit, Glob, Grep
5
- version: 3.1.0
6
- last-updated: 2026-04-06
7
- ---
8
-
9
- # React 19+ — Dense Reference
10
-
11
- ## Hallucination Traps (Read First)
12
- - ❌ `useFormState` → ✅ `useActionState` (stable name)
13
- - ❌ `useContext()` in conditionals → ✅ `use(Context)` CAN be conditional
14
- - ❌ `useMemo/useCallback/React.memo` in React 19+ projects → ✅ React Compiler handles this
15
- - ❌ `exitBeforeEnter` (Framer) → ✅ `mode="wait"` on `<AnimatePresence>`
16
- - ❌ `next/router` → ✅ `next/navigation` in App Router
17
- - ❌ Server Components using `useState/useEffect` → must be `"use client"`
18
-
19
- ---
20
-
21
- ## React 19 Core APIs
22
-
23
- ### `use()` — Replaces many useEffect patterns
24
- ```tsx
25
- import { use } from "react";
26
- // Reads promises (suspends until resolved)
27
- function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
28
- const user = use(userPromise); // suspends
29
- return <h1>{user.name}</h1>;
30
- }
31
- // Reads context — CAN be called conditionally (unlike useContext)
32
- function Admin({ isAdmin }: { isAdmin: boolean }) {
33
- if (isAdmin) return <Panel theme={use(ThemeContext)} />;
34
- return <PublicPanel />;
35
- }
36
- ```
37
-
38
- ### `useActionState` — Form actions with state
39
- ```tsx
40
- import { useActionState } from "react"; // NOT useFormState
41
-
42
- async function submitForm(prevState: FormState, formData: FormData) {
43
- const email = formData.get("email") as string;
44
- if (!email.includes("@")) return { error: "Invalid email" };
45
- await saveToDatabase(email);
46
- return { error: null, success: true };
47
- }
48
-
49
- function SignupForm() {
50
- const [state, formAction, isPending] = useActionState(submitForm, { error: null });
51
- return (
52
- <form action={formAction}>
53
- <input name="email" disabled={isPending} />
54
- {state.error && <p>{state.error}</p>}
55
- <button disabled={isPending}>{isPending ? "Saving..." : "Submit"}</button>
56
- </form>
57
- );
58
- }
59
- ```
60
-
61
- ### `useOptimistic` — Instant UI feedback
62
- ```tsx
63
- import { useOptimistic } from "react";
64
- function TodoList({ todos }: { todos: Todo[] }) {
65
- const [optimistic, addOptimistic] = useOptimistic(
66
- todos,
67
- (current, newTodo: Todo) => [...current, newTodo]
68
- );
69
- async function handleAdd(formData: FormData) {
70
- addOptimistic({ id: crypto.randomUUID(), title: formData.get("title"), pending: true });
71
- await saveTodo(formData.get("title") as string);
72
- }
73
- return (
74
- <form action={handleAdd}>
75
- {optimistic.map(t => <li key={t.id} style={{ opacity: t.pending ? 0.5 : 1 }}>{t.title}</li>)}
76
- </form>
77
- );
78
- }
79
- ```
80
-
81
- ### `useFormStatus` — Button pending state (must be INSIDE `<form>`)
82
- ```tsx
83
- import { useFormStatus } from "react-dom";
84
- // ❌ TRAP: Cannot be called in the same component as <form>
85
- function SubmitButton() {
86
- const { pending } = useFormStatus(); // reads nearest parent form
87
- return <button disabled={pending}>{pending ? "Saving..." : "Save"}</button>;
88
- }
89
- ```
90
-
91
- ### `useTransition` — Non-blocking updates (React 19: supports async)
92
- ```tsx
93
- const [isPending, startTransition] = useTransition();
94
- startTransition(async () => {
95
- const data = await search(query); // async supported in React 19 only
96
- setResults(data);
97
- });
98
- ```
99
-
100
- ### `useDeferredValue` — Stale-while-rerender
101
- ```tsx
102
- const deferredQuery = useDeferredValue(query);
103
- const isStale = query !== deferredQuery;
104
- return <div style={{ opacity: isStale ? 0.6 : 1 }}><ExpensiveList query={deferredQuery} /></div>;
105
- // React 19: useDeferredValue(value, initialFallback) — 2-arg form
106
- ```
107
-
108
- ---
109
-
110
- ## React Compiler (React 19)
111
- - Auto-memoizes components/values/callbacks. **Don't manually memoize in React 19 projects.**
112
- - ❌ `useMemo(() => calc(a), [a])` / `useCallback(fn, [id])` / `React.memo(Comp)` — legacy
113
- - ✅ Write plain functions/values. Compiler optimizes automatically.
114
- - Exception: still use manual memo if compiler is explicitly disabled in config.
115
-
116
- ---
117
-
118
- ## Component Patterns
119
-
120
- ### Compound Components (shared state via context)
121
- ```tsx
122
- const TabsContext = createContext<{ active: string; setActive: (id: string) => void } | null>(null);
123
- function Tabs({ children, defaultTab }: { children: ReactNode; defaultTab: string }) {
124
- const [active, setActive] = useState(defaultTab);
125
- return <TabsContext value={{ active, setActive }}><div>{children}</div></TabsContext>;
126
- }
127
- function Tab({ id, children }: { id: string; children: ReactNode }) {
128
- const ctx = use(TabsContext)!;
129
- return <button onClick={() => ctx.setActive(id)} aria-selected={ctx.active === id}>{children}</button>;
130
- }
131
- ```
132
-
133
- ### Render Props / Higher Order Hooks
134
- Prefer custom hooks over render props for modern React.
135
-
136
- ### Context Performance Pattern
137
- ```tsx
138
- // Split context — prevents all consumers from re-rendering on every change
139
- const CountStateCtx = createContext<number>(0);
140
- const CountDispatchCtx = createContext<Dispatch<Action>>(() => {});
141
- ```
142
-
143
- ---
144
-
145
- ## State Management
146
-
147
- ### Zustand (preferred for global state)
148
- ```tsx
149
- import { create } from "zustand";
150
- import { persist } from "zustand/middleware";
151
- const useStore = create<Store>()(
152
- persist(
153
- (set, get) => ({
154
- count: 0,
155
- increment: () => set(s => ({ count: s.count + 1 })),
156
- getDoubled: () => get().count * 2,
157
- }),
158
- { name: "my-store" }
159
- )
160
- );
161
- // ❌ TRAP: Do NOT destructure the whole store — causes re-render on every change
162
- // ✅ const count = useStore(s => s.count); // selector
163
- ```
164
-
165
- ### Jotai (preferred for derived/atomic state)
166
- ```tsx
167
- import { atom, useAtom, useAtomValue, useSetAtom } from "jotai";
168
- const countAtom = atom(0);
169
- const doubledAtom = atom(get => get(countAtom) * 2); // derived atom
170
- // ❌ TRAP: atomWithStorage is from jotai/utils — NOT from jotai
171
- import { atomWithStorage } from "jotai/utils";
172
- ```
173
-
174
- ### React Query / TanStack Query
175
- ```tsx
176
- import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
177
- const { data, isPending, error } = useQuery({
178
- queryKey: ["user", userId],
179
- queryFn: () => fetchUser(userId),
180
- staleTime: 5 * 60 * 1000, // don't refetch for 5 minutes
181
- });
182
- // Optimistic update:
183
- const qc = useQueryClient();
184
- const mutation = useMutation({
185
- mutationFn: updateUser,
186
- onMutate: async (newUser) => {
187
- await qc.cancelQueries({ queryKey: ["user", newUser.id] });
188
- const prev = qc.getQueryData(["user", newUser.id]);
189
- qc.setQueryData(["user", newUser.id], newUser);
190
- return { prev };
191
- },
192
- onError: (_, __, ctx) => qc.setQueryData(["user"], ctx?.prev),
193
- onSettled: () => qc.invalidateQueries({ queryKey: ["user"] }),
194
- });
195
- ```
196
-
197
- ---
198
-
199
- ## Performance
200
-
201
- | Technique | When |
202
- |-----------|------|
203
- | `useDeferredValue` | Expensive derived render (charts, filters) |
204
- | `useTransition` | Page nav, tab switches, data load |
205
- | `lazy()` + `Suspense` | Code-split heavy components |
206
- | `<Virtuoso>` / `<WindowVirtualizer>` | Lists > 200 items |
207
- | Avoid `useEffect` for state transforms | Use `useMemo` or derived atoms |
208
-
209
- ---
210
-
211
- ## Refs & DOM
212
-
213
- ```tsx
214
- // React 19: ref is now a prop (no forwardRef needed)
215
- function Input({ ref, ...props }: ComponentProps<"input"> & { ref?: Ref<HTMLInputElement> }) {
216
- return <input ref={ref} {...props} />;
217
- }
218
- // ❌ TRAP: forwardRef is deprecated in React 19 — still works but not needed
219
- ```
220
-
221
- ---
222
-
223
- ## Testing Checklist
224
- - ✅ Use React Testing Library — test behavior, not implementation
225
- - ✅ `userEvent` over `fireEvent` (async, closer to real interaction)
226
- - ✅ Mock server calls with MSW (Mock Service Worker)
227
- - ❌ Never test internal state, ref values, or component instances
1
+ ---
2
+ name: react-specialist
3
+ description: React 19+ specialist. use(), useActionState, useOptimistic, React Compiler, Server/Client Components, Zustand/Jotai, React Query. Use when building components, managing state, optimizing renders.
4
+ allowed-tools: Read, Write, Edit, Glob, Grep
5
+ version: 3.1.0
6
+ last-updated: 2026-04-06
7
+ ---
8
+
9
+ # React 19+ — Dense Reference
10
+
11
+ ## Hallucination Traps (Read First)
12
+ - ❌ `useFormState` → ✅ `useActionState` (stable name)
13
+ - ❌ `useContext()` in conditionals → ✅ `use(Context)` CAN be conditional
14
+ - ❌ `useMemo/useCallback/React.memo` in React 19+ projects → ✅ React Compiler handles this
15
+ - ❌ `exitBeforeEnter` (Framer) → ✅ `mode="wait"` on `<AnimatePresence>`
16
+ - ❌ `next/router` → ✅ `next/navigation` in App Router
17
+ - ❌ Server Components using `useState/useEffect` → must be `"use client"`
18
+
19
+ ---
20
+
21
+ ## React 19 Core APIs
22
+
23
+ ### `use()` — Replaces many useEffect patterns
24
+ ```tsx
25
+ import { use } from "react";
26
+ // Reads promises (suspends until resolved)
27
+ function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
28
+ const user = use(userPromise); // suspends
29
+ return <h1>{user.name}</h1>;
30
+ }
31
+ // Reads context — CAN be called conditionally (unlike useContext)
32
+ function Admin({ isAdmin }: { isAdmin: boolean }) {
33
+ if (isAdmin) return <Panel theme={use(ThemeContext)} />;
34
+ return <PublicPanel />;
35
+ }
36
+ ```
37
+
38
+ ### `useActionState` — Form actions with state
39
+ ```tsx
40
+ import { useActionState } from "react"; // NOT useFormState
41
+
42
+ async function submitForm(prevState: FormState, formData: FormData) {
43
+ const email = formData.get("email") as string;
44
+ if (!email.includes("@")) return { error: "Invalid email" };
45
+ await saveToDatabase(email);
46
+ return { error: null, success: true };
47
+ }
48
+
49
+ function SignupForm() {
50
+ const [state, formAction, isPending] = useActionState(submitForm, { error: null });
51
+ return (
52
+ <form action={formAction}>
53
+ <input name="email" disabled={isPending} />
54
+ {state.error && <p>{state.error}</p>}
55
+ <button disabled={isPending}>{isPending ? "Saving..." : "Submit"}</button>
56
+ </form>
57
+ );
58
+ }
59
+ ```
60
+
61
+ ### `useOptimistic` — Instant UI feedback
62
+ ```tsx
63
+ import { useOptimistic } from "react";
64
+ function TodoList({ todos }: { todos: Todo[] }) {
65
+ const [optimistic, addOptimistic] = useOptimistic(
66
+ todos,
67
+ (current, newTodo: Todo) => [...current, newTodo]
68
+ );
69
+ async function handleAdd(formData: FormData) {
70
+ addOptimistic({ id: crypto.randomUUID(), title: formData.get("title"), pending: true });
71
+ await saveTodo(formData.get("title") as string);
72
+ }
73
+ return (
74
+ <form action={handleAdd}>
75
+ {optimistic.map(t => <li key={t.id} style={{ opacity: t.pending ? 0.5 : 1 }}>{t.title}</li>)}
76
+ </form>
77
+ );
78
+ }
79
+ ```
80
+
81
+ ### `useFormStatus` — Button pending state (must be INSIDE `<form>`)
82
+ ```tsx
83
+ import { useFormStatus } from "react-dom";
84
+ // ❌ TRAP: Cannot be called in the same component as <form>
85
+ function SubmitButton() {
86
+ const { pending } = useFormStatus(); // reads nearest parent form
87
+ return <button disabled={pending}>{pending ? "Saving..." : "Save"}</button>;
88
+ }
89
+ ```
90
+
91
+ ### `useTransition` — Non-blocking updates (React 19: supports async)
92
+ ```tsx
93
+ const [isPending, startTransition] = useTransition();
94
+ startTransition(async () => {
95
+ const data = await search(query); // async supported in React 19 only
96
+ setResults(data);
97
+ });
98
+ ```
99
+
100
+ ### `useDeferredValue` — Stale-while-rerender
101
+ ```tsx
102
+ const deferredQuery = useDeferredValue(query);
103
+ const isStale = query !== deferredQuery;
104
+ return <div style={{ opacity: isStale ? 0.6 : 1 }}><ExpensiveList query={deferredQuery} /></div>;
105
+ // React 19: useDeferredValue(value, initialFallback) — 2-arg form
106
+ ```
107
+
108
+ ---
109
+
110
+ ## React Compiler (React 19)
111
+ - Auto-memoizes components/values/callbacks. **Don't manually memoize in React 19 projects.**
112
+ - ❌ `useMemo(() => calc(a), [a])` / `useCallback(fn, [id])` / `React.memo(Comp)` — legacy
113
+ - ✅ Write plain functions/values. Compiler optimizes automatically.
114
+ - Exception: still use manual memo if compiler is explicitly disabled in config.
115
+
116
+ ---
117
+
118
+ ## Component Patterns
119
+
120
+ ### Compound Components (shared state via context)
121
+ ```tsx
122
+ const TabsContext = createContext<{ active: string; setActive: (id: string) => void } | null>(null);
123
+ function Tabs({ children, defaultTab }: { children: ReactNode; defaultTab: string }) {
124
+ const [active, setActive] = useState(defaultTab);
125
+ return <TabsContext value={{ active, setActive }}><div>{children}</div></TabsContext>;
126
+ }
127
+ function Tab({ id, children }: { id: string; children: ReactNode }) {
128
+ const ctx = use(TabsContext)!;
129
+ return <button onClick={() => ctx.setActive(id)} aria-selected={ctx.active === id}>{children}</button>;
130
+ }
131
+ ```
132
+
133
+ ### Render Props / Higher Order Hooks
134
+ Prefer custom hooks over render props for modern React.
135
+
136
+ ### Context Performance Pattern
137
+ ```tsx
138
+ // Split context — prevents all consumers from re-rendering on every change
139
+ const CountStateCtx = createContext<number>(0);
140
+ const CountDispatchCtx = createContext<Dispatch<Action>>(() => {});
141
+ ```
142
+
143
+ ---
144
+
145
+ ## State Management
146
+
147
+ ### Zustand (preferred for global state)
148
+ ```tsx
149
+ import { create } from "zustand";
150
+ import { persist } from "zustand/middleware";
151
+ const useStore = create<Store>()(
152
+ persist(
153
+ (set, get) => ({
154
+ count: 0,
155
+ increment: () => set(s => ({ count: s.count + 1 })),
156
+ getDoubled: () => get().count * 2,
157
+ }),
158
+ { name: "my-store" }
159
+ )
160
+ );
161
+ // ❌ TRAP: Do NOT destructure the whole store — causes re-render on every change
162
+ // ✅ const count = useStore(s => s.count); // selector
163
+ ```
164
+
165
+ ### Jotai (preferred for derived/atomic state)
166
+ ```tsx
167
+ import { atom, useAtom, useAtomValue, useSetAtom } from "jotai";
168
+ const countAtom = atom(0);
169
+ const doubledAtom = atom(get => get(countAtom) * 2); // derived atom
170
+ // ❌ TRAP: atomWithStorage is from jotai/utils — NOT from jotai
171
+ import { atomWithStorage } from "jotai/utils";
172
+ ```
173
+
174
+ ### React Query / TanStack Query
175
+ ```tsx
176
+ import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
177
+ const { data, isPending, error } = useQuery({
178
+ queryKey: ["user", userId],
179
+ queryFn: () => fetchUser(userId),
180
+ staleTime: 5 * 60 * 1000, // don't refetch for 5 minutes
181
+ });
182
+ // Optimistic update:
183
+ const qc = useQueryClient();
184
+ const mutation = useMutation({
185
+ mutationFn: updateUser,
186
+ onMutate: async (newUser) => {
187
+ await qc.cancelQueries({ queryKey: ["user", newUser.id] });
188
+ const prev = qc.getQueryData(["user", newUser.id]);
189
+ qc.setQueryData(["user", newUser.id], newUser);
190
+ return { prev };
191
+ },
192
+ onError: (_, __, ctx) => qc.setQueryData(["user"], ctx?.prev),
193
+ onSettled: () => qc.invalidateQueries({ queryKey: ["user"] }),
194
+ });
195
+ ```
196
+
197
+ ---
198
+
199
+ ## Performance
200
+
201
+ | Technique | When |
202
+ |-----------|------|
203
+ | `useDeferredValue` | Expensive derived render (charts, filters) |
204
+ | `useTransition` | Page nav, tab switches, data load |
205
+ | `lazy()` + `Suspense` | Code-split heavy components |
206
+ | `<Virtuoso>` / `<WindowVirtualizer>` | Lists > 200 items |
207
+ | Avoid `useEffect` for state transforms | Use `useMemo` or derived atoms |
208
+
209
+ ---
210
+
211
+ ## Refs & DOM
212
+
213
+ ```tsx
214
+ // React 19: ref is now a prop (no forwardRef needed)
215
+ function Input({ ref, ...props }: ComponentProps<"input"> & { ref?: Ref<HTMLInputElement> }) {
216
+ return <input ref={ref} {...props} />;
217
+ }
218
+ // ❌ TRAP: forwardRef is deprecated in React 19 — still works but not needed
219
+ ```
220
+
221
+ ---
222
+
223
+ ## Testing Checklist
224
+ - ✅ Use React Testing Library — test behavior, not implementation
225
+ - ✅ `userEvent` over `fireEvent` (async, closer to real interaction)
226
+ - ✅ Mock server calls with MSW (Mock Service Worker)
227
+ - ❌ Never test internal state, ref values, or component instances
228
228
 
229
229
 
230
230
  ---
@@ -266,4 +266,12 @@ Review these questions before confirming output:
266
266
 
267
267
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
268
268
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
269
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
269
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
270
+
271
+
272
+ ## Pre-Flight Checklist
273
+ - [ ] Have I reviewed the user's specific constraints and requests?
274
+ - [ ] Have I checked the environment for relevant existing implementations?
275
+
276
+ ## VBC Protocol (Verification-Before-Completion)
277
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -289,4 +289,12 @@ Review these questions before confirming output:
289
289
 
290
290
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
291
291
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
292
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
292
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
293
+
294
+
295
+ ## Pre-Flight Checklist
296
+ - [ ] Have I reviewed the user's specific constraints and requests?
297
+ - [ ] Have I checked the environment for relevant existing implementations?
298
+
299
+ ## VBC Protocol (Verification-Before-Completion)
300
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -308,4 +308,12 @@ Review these questions before confirming output:
308
308
 
309
309
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
310
310
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
311
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
311
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
312
+
313
+
314
+ ## Pre-Flight Checklist
315
+ - [ ] Have I reviewed the user's specific constraints and requests?
316
+ - [ ] Have I checked the environment for relevant existing implementations?
317
+
318
+ ## VBC Protocol (Verification-Before-Completion)
319
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -207,4 +207,12 @@ Review these questions before confirming output:
207
207
 
208
208
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
209
209
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
210
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
210
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
211
+
212
+
213
+ ## Pre-Flight Checklist
214
+ - [ ] Have I reviewed the user's specific constraints and requests?
215
+ - [ ] Have I checked the environment for relevant existing implementations?
216
+
217
+ ## VBC Protocol (Verification-Before-Completion)
218
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -662,4 +662,12 @@ Review these questions before confirming output:
662
662
 
663
663
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
664
664
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
665
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
665
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
666
+
667
+
668
+ ## Pre-Flight Checklist
669
+ - [ ] Have I reviewed the user's specific constraints and requests?
670
+ - [ ] Have I checked the environment for relevant existing implementations?
671
+
672
+ ## VBC Protocol (Verification-Before-Completion)
673
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -168,4 +168,12 @@ Review these questions before confirming output:
168
168
 
169
169
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
170
170
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
171
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
171
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
172
+
173
+
174
+ ## Pre-Flight Checklist
175
+ - [ ] Have I reviewed the user's specific constraints and requests?
176
+ - [ ] Have I checked the environment for relevant existing implementations?
177
+
178
+ ## VBC Protocol (Verification-Before-Completion)
179
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -203,4 +203,12 @@ Review these questions before confirming output:
203
203
 
204
204
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
205
205
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
206
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
206
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
207
+
208
+
209
+ ## Pre-Flight Checklist
210
+ - [ ] Have I reviewed the user's specific constraints and requests?
211
+ - [ ] Have I checked the environment for relevant existing implementations?
212
+
213
+ ## VBC Protocol (Verification-Before-Completion)
214
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -220,4 +220,12 @@ Review these questions before confirming output:
220
220
 
221
221
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
222
222
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
223
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
223
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
224
+
225
+
226
+ ## Pre-Flight Checklist
227
+ - [ ] Have I reviewed the user's specific constraints and requests?
228
+ - [ ] Have I checked the environment for relevant existing implementations?
229
+
230
+ ## VBC Protocol (Verification-Before-Completion)
231
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -75,4 +75,12 @@ Review these questions before confirming output:
75
75
 
76
76
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
77
77
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
78
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
78
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
79
+
80
+
81
+ ## Pre-Flight Checklist
82
+ - [ ] Have I reviewed the user's specific constraints and requests?
83
+ - [ ] Have I checked the environment for relevant existing implementations?
84
+
85
+ ## VBC Protocol (Verification-Before-Completion)
86
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -618,4 +618,12 @@ Review these questions before confirming output:
618
618
 
619
619
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
620
620
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
621
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
621
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
622
+
623
+
624
+ ## Pre-Flight Checklist
625
+ - [ ] Have I reviewed the user's specific constraints and requests?
626
+ - [ ] Have I checked the environment for relevant existing implementations?
627
+
628
+ ## VBC Protocol (Verification-Before-Completion)
629
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -86,4 +86,12 @@ Review these questions before confirming output:
86
86
 
87
87
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
88
88
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
89
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
89
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
90
+
91
+
92
+ ## Pre-Flight Checklist
93
+ - [ ] Have I reviewed the user's specific constraints and requests?
94
+ - [ ] Have I checked the environment for relevant existing implementations?
95
+
96
+ ## VBC Protocol (Verification-Before-Completion)
97
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -190,4 +190,12 @@ Review these questions before confirming output:
190
190
 
191
191
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
192
192
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
193
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
193
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
194
+
195
+
196
+ ## Pre-Flight Checklist
197
+ - [ ] Have I reviewed the user's specific constraints and requests?
198
+ - [ ] Have I checked the environment for relevant existing implementations?
199
+
200
+ ## VBC Protocol (Verification-Before-Completion)
201
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
@@ -131,4 +131,12 @@ Review these questions before confirming output:
131
131
 
132
132
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
133
133
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
134
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
134
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
135
+
136
+
137
+ ## Pre-Flight Checklist
138
+ - [ ] Have I reviewed the user's specific constraints and requests?
139
+ - [ ] Have I checked the environment for relevant existing implementations?
140
+
141
+ ## VBC Protocol (Verification-Before-Completion)
142
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.