tribunal-kit 4.2.0 → 4.3.1

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 (186) hide show
  1. package/.agent/ARCHITECTURE.md +21 -14
  2. package/.agent/agents/swarm-worker-contracts.md +5 -5
  3. package/.agent/agents/ui-ux-auditor.md +292 -0
  4. package/.agent/rules/GEMINI.md +8 -8
  5. package/.agent/scripts/__pycache__/_colors.cpython-311.pyc +0 -0
  6. package/.agent/scripts/__pycache__/_utils.cpython-311.pyc +0 -0
  7. package/.agent/scripts/__pycache__/case_law_manager.cpython-311.pyc +0 -0
  8. package/.agent/scripts/_colors.js +18 -0
  9. package/.agent/scripts/_utils.js +42 -0
  10. package/.agent/scripts/auto_preview.js +197 -0
  11. package/.agent/scripts/bundle_analyzer.js +290 -0
  12. package/.agent/scripts/case_law_manager.js +684 -0
  13. package/.agent/scripts/checklist.js +266 -0
  14. package/.agent/scripts/colors.js +17 -0
  15. package/.agent/scripts/compress_skills.js +141 -0
  16. package/.agent/scripts/consolidate_skills.js +149 -0
  17. package/.agent/scripts/context_broker.js +609 -0
  18. package/.agent/scripts/deep_compress.js +150 -0
  19. package/.agent/scripts/dependency_analyzer.js +272 -0
  20. package/.agent/scripts/graph_builder.js +199 -0
  21. package/.agent/scripts/graph_zoom.js +154 -0
  22. package/.agent/scripts/inner_loop_validator.js +465 -0
  23. package/.agent/scripts/lint_runner.js +187 -0
  24. package/.agent/scripts/minify_context.js +100 -0
  25. package/.agent/scripts/patch_skills_meta.js +156 -0
  26. package/.agent/scripts/patch_skills_output.js +244 -0
  27. package/.agent/scripts/schema_validator.js +297 -0
  28. package/.agent/scripts/security_scan.js +303 -0
  29. package/.agent/scripts/session_manager.js +276 -0
  30. package/.agent/scripts/skill_evolution.js +644 -0
  31. package/.agent/scripts/skill_integrator.js +313 -0
  32. package/.agent/scripts/strengthen_skills.js +193 -0
  33. package/.agent/scripts/strip_tribunal.js +47 -0
  34. package/.agent/scripts/swarm_dispatcher.js +360 -0
  35. package/.agent/scripts/test_runner.js +193 -0
  36. package/.agent/scripts/utils.js +32 -0
  37. package/.agent/scripts/verify_all.js +256 -0
  38. package/.agent/skills/agent-organizer/SKILL.md +12 -4
  39. package/.agent/skills/agentic-patterns/SKILL.md +12 -4
  40. package/.agent/skills/ai-prompt-injection-defense/SKILL.md +12 -4
  41. package/.agent/skills/api-patterns/SKILL.md +209 -201
  42. package/.agent/skills/api-security-auditor/SKILL.md +12 -4
  43. package/.agent/skills/app-builder/SKILL.md +12 -4
  44. package/.agent/skills/app-builder/templates/SKILL.md +76 -68
  45. package/.agent/skills/app-builder/templates/astro-static/TEMPLATE.md +1 -1
  46. package/.agent/skills/app-builder/templates/chrome-extension/TEMPLATE.md +1 -1
  47. package/.agent/skills/app-builder/templates/cli-tool/TEMPLATE.md +1 -1
  48. package/.agent/skills/app-builder/templates/electron-desktop/TEMPLATE.md +1 -1
  49. package/.agent/skills/app-builder/templates/express-api/TEMPLATE.md +1 -1
  50. package/.agent/skills/app-builder/templates/flutter-app/TEMPLATE.md +1 -1
  51. package/.agent/skills/app-builder/templates/monorepo-turborepo/TEMPLATE.md +1 -1
  52. package/.agent/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +1 -1
  53. package/.agent/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +1 -1
  54. package/.agent/skills/app-builder/templates/nextjs-static/TEMPLATE.md +1 -1
  55. package/.agent/skills/app-builder/templates/nuxt-app/TEMPLATE.md +1 -1
  56. package/.agent/skills/app-builder/templates/python-fastapi/TEMPLATE.md +1 -1
  57. package/.agent/skills/app-builder/templates/react-native-app/TEMPLATE.md +1 -1
  58. package/.agent/skills/appflow-wireframe/SKILL.md +12 -4
  59. package/.agent/skills/architecture/SKILL.md +12 -4
  60. package/.agent/skills/authentication-best-practices/SKILL.md +12 -4
  61. package/.agent/skills/bash-linux/SKILL.md +12 -4
  62. package/.agent/skills/behavioral-modes/SKILL.md +12 -4
  63. package/.agent/skills/brainstorming/SKILL.md +12 -4
  64. package/.agent/skills/building-native-ui/SKILL.md +12 -4
  65. package/.agent/skills/clean-code/SKILL.md +12 -4
  66. package/.agent/skills/code-review-checklist/SKILL.md +12 -4
  67. package/.agent/skills/config-validator/SKILL.md +12 -4
  68. package/.agent/skills/csharp-developer/SKILL.md +12 -4
  69. package/.agent/skills/data-validation-schemas/SKILL.md +290 -282
  70. package/.agent/skills/database-design/SKILL.md +202 -194
  71. package/.agent/skills/deployment-procedures/SKILL.md +12 -4
  72. package/.agent/skills/devops-engineer/SKILL.md +12 -4
  73. package/.agent/skills/devops-incident-responder/SKILL.md +12 -4
  74. package/.agent/skills/doc.md +1 -1
  75. package/.agent/skills/documentation-templates/SKILL.md +12 -4
  76. package/.agent/skills/edge-computing/SKILL.md +12 -4
  77. package/.agent/skills/error-resilience/SKILL.md +390 -382
  78. package/.agent/skills/extract-design-system/SKILL.md +12 -4
  79. package/.agent/skills/framer-motion-expert/SKILL.md +206 -199
  80. package/.agent/skills/frontend-design/SKILL.md +163 -155
  81. package/.agent/skills/game-design-expert/SKILL.md +12 -4
  82. package/.agent/skills/game-engineering-expert/SKILL.md +12 -4
  83. package/.agent/skills/geo-fundamentals/SKILL.md +12 -4
  84. package/.agent/skills/github-operations/SKILL.md +12 -4
  85. package/.agent/skills/gsap-core/SKILL.md +54 -48
  86. package/.agent/skills/gsap-frameworks/SKILL.md +54 -48
  87. package/.agent/skills/gsap-performance/SKILL.md +54 -48
  88. package/.agent/skills/gsap-plugins/SKILL.md +54 -48
  89. package/.agent/skills/gsap-react/SKILL.md +54 -48
  90. package/.agent/skills/gsap-scrolltrigger/SKILL.md +54 -48
  91. package/.agent/skills/gsap-timeline/SKILL.md +54 -48
  92. package/.agent/skills/gsap-utils/SKILL.md +54 -48
  93. package/.agent/skills/i18n-localization/SKILL.md +12 -4
  94. package/.agent/skills/intelligent-routing/SKILL.md +41 -33
  95. package/.agent/skills/knowledge-graph/SKILL.md +36 -0
  96. package/.agent/skills/lint-and-validate/SKILL.md +12 -4
  97. package/.agent/skills/llm-engineering/SKILL.md +12 -4
  98. package/.agent/skills/local-first/SKILL.md +12 -4
  99. package/.agent/skills/mcp-builder/SKILL.md +12 -4
  100. package/.agent/skills/mobile-design/SKILL.md +225 -217
  101. package/.agent/skills/monorepo-management/SKILL.md +296 -288
  102. package/.agent/skills/motion-engineering/SKILL.md +195 -187
  103. package/.agent/skills/nextjs-react-expert/SKILL.md +196 -188
  104. package/.agent/skills/nodejs-best-practices/SKILL.md +12 -4
  105. package/.agent/skills/observability/SKILL.md +12 -4
  106. package/.agent/skills/parallel-agents/SKILL.md +12 -4
  107. package/.agent/skills/performance-profiling/SKILL.md +12 -4
  108. package/.agent/skills/plan-writing/SKILL.md +12 -4
  109. package/.agent/skills/platform-engineer/SKILL.md +12 -4
  110. package/.agent/skills/playwright-best-practices/SKILL.md +12 -4
  111. package/.agent/skills/powershell-windows/SKILL.md +12 -4
  112. package/.agent/skills/project-idioms/SKILL.md +12 -4
  113. package/.agent/skills/python-patterns/SKILL.md +12 -4
  114. package/.agent/skills/python-pro/SKILL.md +285 -277
  115. package/.agent/skills/react-specialist/SKILL.md +239 -231
  116. package/.agent/skills/readme-builder/SKILL.md +12 -4
  117. package/.agent/skills/realtime-patterns/SKILL.md +12 -4
  118. package/.agent/skills/red-team-tactics/SKILL.md +12 -4
  119. package/.agent/skills/rust-pro/SKILL.md +12 -4
  120. package/.agent/skills/seo-fundamentals/SKILL.md +12 -4
  121. package/.agent/skills/server-management/SKILL.md +12 -4
  122. package/.agent/skills/shadcn-ui-expert/SKILL.md +12 -4
  123. package/.agent/skills/skill-creator/SKILL.md +12 -4
  124. package/.agent/skills/sql-pro/SKILL.md +12 -4
  125. package/.agent/skills/supabase-postgres-best-practices/SKILL.md +12 -4
  126. package/.agent/skills/swiftui-expert/SKILL.md +12 -4
  127. package/.agent/skills/systematic-debugging/SKILL.md +12 -4
  128. package/.agent/skills/tailwind-patterns/SKILL.md +12 -4
  129. package/.agent/skills/tdd-workflow/SKILL.md +12 -4
  130. package/.agent/skills/test-result-analyzer/SKILL.md +12 -4
  131. package/.agent/skills/testing-patterns/SKILL.md +12 -4
  132. package/.agent/skills/trend-researcher/SKILL.md +12 -4
  133. package/.agent/skills/typescript-advanced/SKILL.md +297 -289
  134. package/.agent/skills/ui-ux-pro-max/SKILL.md +12 -4
  135. package/.agent/skills/ui-ux-researcher/SKILL.md +12 -4
  136. package/.agent/skills/vue-expert/SKILL.md +237 -229
  137. package/.agent/skills/vulnerability-scanner/SKILL.md +12 -4
  138. package/.agent/skills/web-accessibility-auditor/SKILL.md +12 -4
  139. package/.agent/skills/web-design-guidelines/SKILL.md +12 -4
  140. package/.agent/skills/webapp-testing/SKILL.md +12 -4
  141. package/.agent/skills/whimsy-injector/SKILL.md +12 -4
  142. package/.agent/skills/workflow-optimizer/SKILL.md +12 -4
  143. package/.agent/workflows/audit.md +6 -6
  144. package/.agent/workflows/deploy.md +1 -1
  145. package/.agent/workflows/generate.md +23 -6
  146. package/.agent/workflows/session.md +5 -5
  147. package/.agent/workflows/swarm.md +2 -2
  148. package/README.md +242 -186
  149. package/bin/tribunal-kit.js +297 -57
  150. package/package.json +81 -77
  151. package/scripts/changelog.js +167 -0
  152. package/scripts/sync-version.js +81 -0
  153. package/scripts/validate-payload.js +73 -0
  154. package/.agent/scripts/__pycache__/auto_preview.cpython-311.pyc +0 -0
  155. package/.agent/scripts/__pycache__/bundle_analyzer.cpython-311.pyc +0 -0
  156. package/.agent/scripts/__pycache__/checklist.cpython-311.pyc +0 -0
  157. package/.agent/scripts/__pycache__/dependency_analyzer.cpython-311.pyc +0 -0
  158. package/.agent/scripts/__pycache__/security_scan.cpython-311.pyc +0 -0
  159. package/.agent/scripts/__pycache__/session_manager.cpython-311.pyc +0 -0
  160. package/.agent/scripts/__pycache__/skill_integrator.cpython-311.pyc +0 -0
  161. package/.agent/scripts/__pycache__/swarm_dispatcher.cpython-311.pyc +0 -0
  162. package/.agent/scripts/__pycache__/test_runner.cpython-311.pyc +0 -0
  163. package/.agent/scripts/__pycache__/verify_all.cpython-311.pyc +0 -0
  164. package/.agent/scripts/auto_preview.py +0 -180
  165. package/.agent/scripts/bundle_analyzer.py +0 -259
  166. package/.agent/scripts/case_law_manager.py +0 -755
  167. package/.agent/scripts/checklist.py +0 -209
  168. package/.agent/scripts/compress_skills.py +0 -167
  169. package/.agent/scripts/consolidate_skills.py +0 -173
  170. package/.agent/scripts/deep_compress.py +0 -202
  171. package/.agent/scripts/dependency_analyzer.py +0 -247
  172. package/.agent/scripts/lint_runner.py +0 -188
  173. package/.agent/scripts/minify_context.py +0 -80
  174. package/.agent/scripts/patch_skills_meta.py +0 -177
  175. package/.agent/scripts/patch_skills_output.py +0 -285
  176. package/.agent/scripts/schema_validator.py +0 -279
  177. package/.agent/scripts/security_scan.py +0 -224
  178. package/.agent/scripts/session_manager.py +0 -261
  179. package/.agent/scripts/skill_evolution.py +0 -563
  180. package/.agent/scripts/skill_integrator.py +0 -234
  181. package/.agent/scripts/strengthen_skills.py +0 -220
  182. package/.agent/scripts/strip_tribunal.py +0 -41
  183. package/.agent/scripts/swarm_dispatcher.py +0 -350
  184. package/.agent/scripts/test_runner.py +0 -192
  185. package/.agent/scripts/test_swarm_dispatcher.py +0 -163
  186. package/.agent/scripts/verify_all.py +0 -195
@@ -1,235 +1,235 @@
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
+ ```
228
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.
229
115
 
230
116
  ---
231
117
 
232
- ## 🤖 LLM-Specific Traps
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
+
229
+
230
+ ---
231
+
232
+
233
233
 
234
234
  AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
235
235
 
@@ -241,7 +241,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
241
241
 
242
242
  ---
243
243
 
244
- ## 🏛️ Tribunal Integration (Anti-Hallucination)
244
+
245
245
 
246
246
  **Slash command: `/review` or `/tribunal-full`**
247
247
  **Active reviewers: `logic-reviewer` · `security-auditor`**
@@ -252,7 +252,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
252
252
  2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
253
253
  3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
254
254
 
255
- ### ✅ Pre-Flight Self-Audit
255
+
256
256
 
257
257
  Review these questions before confirming output:
258
258
  ```
@@ -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.
@@ -252,7 +252,7 @@ Evidence: [file written at path / content reviewed]
252
252
 
253
253
  ---
254
254
 
255
- ## 🤖 LLM-Specific Traps
255
+
256
256
 
257
257
  AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
258
258
 
@@ -264,7 +264,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
264
264
 
265
265
  ---
266
266
 
267
- ## 🏛️ Tribunal Integration (Anti-Hallucination)
267
+
268
268
 
269
269
  **Slash command: `/review` or `/tribunal-full`**
270
270
  **Active reviewers: `logic-reviewer` · `security-auditor`**
@@ -275,7 +275,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
275
275
  2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
276
276
  3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
277
277
 
278
- ### ✅ Pre-Flight Self-Audit
278
+
279
279
 
280
280
  Review these questions before confirming output:
281
281
  ```
@@ -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.
@@ -271,7 +271,7 @@ class PresenceManager {
271
271
 
272
272
  ---
273
273
 
274
- ## 🤖 LLM-Specific Traps
274
+
275
275
 
276
276
  AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
277
277
 
@@ -283,7 +283,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
283
283
 
284
284
  ---
285
285
 
286
- ## 🏛️ Tribunal Integration (Anti-Hallucination)
286
+
287
287
 
288
288
  **Slash command: `/review` or `/tribunal-full`**
289
289
  **Active reviewers: `logic-reviewer` · `security-auditor`**
@@ -294,7 +294,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
294
294
  2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
295
295
  3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
296
296
 
297
- ### ✅ Pre-Flight Self-Audit
297
+
298
298
 
299
299
  Review these questions before confirming output:
300
300
  ```
@@ -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.
@@ -170,7 +170,7 @@ Pre-Flight: ✅ All checks passed
170
170
 
171
171
  ---
172
172
 
173
- ## 🤖 LLM-Specific Traps
173
+
174
174
 
175
175
  AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
176
176
 
@@ -182,7 +182,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
182
182
 
183
183
  ---
184
184
 
185
- ## 🏛️ Tribunal Integration (Anti-Hallucination)
185
+
186
186
 
187
187
  **Slash command: `/review` or `/tribunal-full`**
188
188
  **Active reviewers: `logic-reviewer` · `security-auditor`**
@@ -193,7 +193,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
193
193
  2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
194
194
  3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
195
195
 
196
- ### ✅ Pre-Flight Self-Audit
196
+
197
197
 
198
198
  Review these questions before confirming output:
199
199
  ```
@@ -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.
@@ -625,7 +625,7 @@ let word_counts: HashMap<&str, usize> = words.iter()
625
625
 
626
626
  ---
627
627
 
628
- ## 🤖 LLM-Specific Traps
628
+
629
629
 
630
630
  AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
631
631
 
@@ -637,7 +637,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
637
637
 
638
638
  ---
639
639
 
640
- ## 🏛️ Tribunal Integration (Anti-Hallucination)
640
+
641
641
 
642
642
  **Slash command: `/review` or `/tribunal-full`**
643
643
  **Active reviewers: `logic-reviewer` · `security-auditor`**
@@ -648,7 +648,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
648
648
  2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
649
649
  3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
650
650
 
651
- ### ✅ Pre-Flight Self-Audit
651
+
652
652
 
653
653
  Review these questions before confirming output:
654
654
  ```
@@ -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.