@wangs-ui/skills 1.0.1

package/skills/i18n-usage/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: i18n-usage
+description: Comprehensive guidelines for application internationalization, JIT translations (t), ICU formatting, and locale-aware formatting with @wangs-ui/react-i18n.
+---
+
+# Skill: Application Internationalization & Formatting Protocol
+
+Use this skill when implementing multi-language interfaces, translating user-facing text, formatting dates, times, currencies, or numbers in React applications built with Wangs UI and `@wangs-ui/react-i18n`.
+
+---
+
+## 1. The MCP Discovery Protocol (Single Source of Truth)
+
+Do **NOT** guess component localization contracts, language switcher variants, or datepicker props. Query the MCP server dynamically to inspect exact props and live story implementations:
+
+### Inspect Localized Component Contracts:
+
+```json
+get-documentation({ "id": "languageswitcher" })
+get-documentation({ "id": "currencyinput" })
+get-documentation({ "id": "datepicker" })
+get-documentation({ "id": "select" })
+get-documentation({ "id": "datatable" })
+```
+
+### Inspect Live Story Implementations:
+
+```json
+get-documentation-for-story({ "id": "languageswitcher", "storyName": "Basic" })
+get-documentation-for-story({ "id": "currencyinput", "storyName": "Basic" })
+get-documentation-for-story({ "id": "datepicker", "storyName": "Default" })
+```
+
+---
+
+## 2. Root Provider Setup (`WangsUiI18nProvider`)
+
+Wrap the application root with `WangsUiI18nProvider` from `@wangs-ui/react-i18n` to enable dynamic JIT translations, versioned cache invalidation, and locale context:
+
+```tsx
+import { WangsUiI18nProvider } from '@wangs-ui/react-i18n';
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <WangsUiI18nProvider defaultLocale="en" baseUrl={import.meta.env.VITE_API_URL || ''}>
+      <App />
+    </WangsUiI18nProvider>
+  </React.StrictMode>,
+);
+```
+
+---
+
+## 3. Translation Protocol with `useI18n()`
+
+The `@wangs-ui/react-i18n` package uses a Just-In-Time (JIT) translation architecture where natural English text strings serve as database keys.
+
+### A. Consumer-Level Translation for `ReactNode` Props (Mandatory)
+
+All user-facing text props in Wangs UI components (`placeholder`, `label`, `emptyMessage`, `header`, `tooltip`, etc.) are typed as `ReactNode` and rendered as-is. Components do **NOT** automatically translate custom strings. Translation **MUST** be called at the application/consumer level:
+
+```tsx
+import { useI18n } from '@wangs-ui/react-i18n';
+import Button from '@wangs-ui/react-core/primitive/button';
+import DataTable from '@wangs-ui/react-core/primitive/datatable';
+import Select from '@wangs-ui/react-core/primitive/select';
+
+export function OrderList() {
+  const { t } = useI18n();
+
+  return (
+    <div>
+      <Select placeholder={t('Search category...')} />
+      <DataTable emptyMessage={t('No orders found')} />
+      <Button label={t('Create new order')} />
+    </div>
+  );
+}
+```
+
+### B. Natural English Sentence Keys
+
+Always write full, natural English sentences as translation keys. Never use artificial dotted namespace keys:
+
+```tsx
+// ✅ Good — Natural English
+t('Invoice Summary');
+t('Are you sure you want to delete this customer?');
+
+// ❌ Bad — Artificial dotted keys
+t('invoice.summary.title');
+t('dialog.delete.customer.confirm');
+```
+
+### C. Named Variable Interpolation (Single Braces `{var}`)
+
+Pass interpolation values inside a plain object using descriptive named variables. This provides crucial semantic context for AI translation engines:
+
+```tsx
+// ✅ Good — Named variables provide context
+t('Upload {count} files to {groupName}', { count: 5, groupName: 'Marketing' });
+t('Welcome back, {userName}!', { userName: user.name });
+
+// ❌ Bad — Concatenation or positional arguments
+t('Welcome back, ' + user.name);
+t('Upload {0} files to {1}', 5, 'Marketing');
+```
+
+### D. ICU Pluralization & Zero-State (`=0`)
+
+Always handle singular, plural, and zero states directly within ICU MessageFormat strings. Do **NOT** use JavaScript ternary operators:
+
+```tsx
+// ✅ Good — Clean ICU pluralization with zero-state handling
+t('{count, plural, =0 {No items selected} one {1 item selected} other {{count} items selected}}', {
+  count: selectedCount,
+});
+
+// ❌ Bad — Manual JS branching
+selectedCount === 0
+  ? t('No items selected')
+  : selectedCount === 1
+    ? t('1 item selected')
+    : t('{count} items selected', { count: selectedCount });
+```
+
+### E. Rich Text / Annotated Strings
+
+Use standard supported HTML tags (`<a>`, `<b>`, `<i>`, `<u>`, `<s>`, `<br/>`, `<sub>`, `<sup>`, `<code>`, `<mark>`) for inline styling. Tags are automatically parsed into React elements without custom regex or string manipulation:
+
+```tsx
+import Link from '@wangs-ui/foundation/theme/Link';
+
+t('You have selected <b>{count} items</b>. Click <a>here</a> to review.', {
+  count: selectedCount,
+  a: (chunks) => <Link href="/review">{chunks}</Link>,
+});
+```
+
+---
+
+## 4. Locale Formatting Protocol with `useLocaleFormatter()`
+
+For locale-aware formatting of dates, relative times, currencies, numbers, and display names, use the dedicated `useLocaleFormatter()` hook. All functions automatically adapt to the active locale without triggering backend database requests:
+
+```tsx
+import { useLocaleFormatter } from '@wangs-ui/react-i18n';
+
+export function SummaryCard({ updatedAt, amount, count }: Props) {
+  const {
+    formatDate,
+    formatRelativeTime,
+    formatCurrency,
+    formatNumber,
+    formatDisplayName,
+    formatList,
+    truncateText,
+  } = useLocaleFormatter();
+
+  return (
+    <div>
+      {/* Date formatting with Go tokens or date-fns tokens, and timezone */}
+      <p>{formatDate(new Date(), 'dd MMMM yyyy, HH:mm', 'Asia/Jakarta')}</p>
+
+      {/* Relative time */}
+      <p>{formatRelativeTime(updatedAt)}</p>
+
+      {/* Currency formatting */}
+      <p>{formatCurrency(amount, 'IDR')}</p>
+
+      {/* Number formatting with locale grouping */}
+      <p>{formatNumber(count)}</p>
+
+      {/* ISO code to localized name */}
+      <p>{formatDisplayName('id', 'language')}</p>
+
+      {/* Localized list */}
+      <p>{formatList(['Finance', 'Operations', 'IT'])}</p>
+
+      {/* Emoji & multi-byte safe text truncation */}
+      <p>{truncateText('Long product description with emojis 🚀', 20)}</p>
+    </div>
+  );
+}
+```
+
+> [!NOTE]
+> Formatters MUST NOT be called as standalone `t()` keys (e.g. `t(formatRelativeTime(date))`). Instead, pass the formatted result as a named variable:
+>
+> ```tsx
+> const { t } = useI18n();
+> const { formatRelativeTime } = useLocaleFormatter();
+> const label = t('Updated {time}', { time: formatRelativeTime(updatedAt) });
+> ```
+
+---
+
+## 5. Language Switching UI Integration
+
+Connect the Wangs UI `LanguageSwitcher` primitive directly with `useI18n()` state:
+
+```tsx
+import LanguageSwitcher from '@wangs-ui/react-core/primitive/languageswitcher';
+import { useI18n } from '@wangs-ui/react-i18n';
+
+export function HeaderLanguageSwitcher() {
+  const { locale, setLocale, languageOptions } = useI18n();
+
+  return (
+    <LanguageSwitcher
+      options={languageOptions}
+      value={locale}
+      onChange={(code) => setLocale(code)}
+    />
+  );
+}
+```
+
+---
+
+## 6. Strict Behavioral Constraints (MUST NOT)
+
+- **NO Formatters Destructured from `useI18n()`:** Formatters are isolated in `useLocaleFormatter()`. Never attempt to import `formatDate` or `formatCurrency` from `useI18n()`.
+- **NO String Concatenation in `t()` Keys:** Never concatenate strings or use dynamic template literals (e.g. `t('Hello ' + user.name)` or ``t(`Hello ${user.name}`)``). This creates infinite distinct keys in the translation database and prevents caching.
+- **NO Manual Zero-State JavaScript Branching:** Always use ICU `=0` syntax inside a single plural key.
+- **NO Dotted Artificial Translation Keys:** Never use dotted keys like `t('app.header.title')`. Use natural English sentences.
+- **NO Custom Markdown Formatting Symbols:** Do not use `*bold*` or `_italic_` in translation keys. Use valid HTML tags like `<b>bold</b>`.
+- **NO Hardcoded Static Translation Dictionaries:** Do not bundle static translation files (`id.json`, `zh.json`). The JIT backend broker manages translations dynamically.
+- **NO Unnecessary English Key Modifications:** Minor typos or punctuation changes in keys create orphaned entries in the translation backend and trigger new AI translation costs.

package/skills/layout-navigation/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: layout-navigation
+description: Architecture, navigation hierarchies, and MCP discovery protocol for AppLayout, Sidebar, Breadcrumb, and Tabs in Wangs UI.
+---
+
+# Skill: Application Layout & Navigation Hierarchy
+
+Use this skill when constructing application shells, multi-level sidebars, page headers, breadcrumbs, or tabbed views with `@wangs-ui/react-core`.
+
+---
+
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** guess layout block slots, sidebar item interfaces, or breadcrumb props. Query the MCP server dynamically to inspect exact contracts and live story implementations:
+
+### Inspect Layout & Navigation Contracts:
+
+```json
+get-documentation({ "id": "applayout" })
+get-documentation({ "id": "sidebar" })
+get-documentation({ "id": "breadcrumb" })
+get-documentation({ "id": "tabs" })
+```
+
+### Inspect Live Story Implementations:
+
+```json
+get-documentation-for-story({ "id": "applayout", "storyName": "Default" })
+get-documentation-for-story({ "id": "sidebar", "storyName": "Default" })
+get-documentation-for-story({ "id": "breadcrumb", "storyName": "Default" })
+get-documentation-for-story({ "id": "tabs", "storyName": "Default" })
+```
+
+### Inspect Knowledge Graph & Usages:
+
+```json
+query_graph({ "query": "AppLayout" })
+query_graph({ "query": "Sidebar" })
+```
+
+---
+
+## 2. Layout Architecture & Mental Model
+
+1. **Top-Level App Shell (`AppLayout`)**:
+   Provides structured slots for `sidebar`, `header`, and main content view, handling responsive viewport scaling and mobile navigation overlays.
+2. **Hierarchical Menu (`Sidebar`)**:
+   Renders single and nested navigation items, active route indicators, collapsible state, and notification badges.
+3. **Breadcrumb Trail (`Breadcrumb`)**:
+   Maintains clear navigational hierarchy on page headers.
+4. **Tabbed Sub-Views (`Tabs`)**:
+   Organizes complex entity detail views or multi-section settings into distinct tabbed panels.
+
+---
+
+## 3. Mandatory Implementation Rules
+
+1. **Query MCP for Current Code Patterns**: Inspect `applayout` and `sidebar` stories via MCP before assembling the layout.
+2. **Strict Subpath Imports**: Import layout blocks via `@wangs-ui/react-core/blocks/*` and primitives via `@wangs-ui/react-core/primitive/*`.
+3. **Consistent Spacing Grid**: Use standard container padding (`p-6` or `p-xxl`) across page contents.
+4. **Page Hierarchy Alignment**: Every page view inside the layout must provide a clear `.heading-1` hierarchy and synchronized breadcrumbs.
+5. **Translate Navigation Labels**: Wrap all sidebar item labels and breadcrumb texts in `t('...')` from `@wangs-ui/react-i18n`.

package/skills/react19-compiler-typescript/SKILL.md

@@ -0,0 +1,388 @@
+---
+name: react19-compiler-typescript
+description: Enforce idiomatic React 19 + TypeScript conventions built around the React Compiler's automatic memoization. Use this any time writing, generating, reviewing, or refactoring React components, hooks, or props in TypeScript/TSX — including code that manually wraps things in useMemo/useCallback/React.memo, uses forwardRef, mutates props/state, or needs typing for Actions, useOptimistic, use(), or refs. Trigger even if the user didn't say "React 19" or "compiler" explicitly; it applies whenever React component/hook code is being written or optimized.
+---
+
+# React 19 + TypeScript with the React Compiler
+
+## Why this matters
+
+React Compiler (stable since React Compiler 1.0, October 2025) rewrites your components
+and hooks at build time, inserting memoization equivalent to `useMemo`/`useCallback`/
+`React.memo` automatically and more granularly than a human would by hand. It ships as
+`babel-plugin-react-compiler`, and its lint rules live inside `eslint-plugin-react-hooks`
+(recommended preset) so linting and compilation share one source of truth.
+
+The practical consequence: **manual memoization is no longer the default** — it's
+either redundant, or actively harmful if it doesn't match what the compiler would have
+inferred (the compiler bails out silently rather than risk breaking your app). Writing
+"optimized" React in 2026 means writing _plain, rule-following_ React and trusting the
+build step, not sprinkling `useMemo` everywhere out of habit.
+
+This skill assumes and builds on the base `typescript-strict-typing` skill for general
+typing discipline (no `any`, `interface` for entities, discriminated unions for variant
+state, etc.) — apply both together.
+
+## Core principle
+
+> Write plain, obviously-pure React. Let the compiler memoize. The Rules of React are no
+> longer just style guidance — the compiler's correctness depends on you following them.
+
+---
+
+## 1. Stop hand-rolling memoization
+
+> ⚠️ **Everything in this section assumes the compiler is confirmed active** (wired per
+> §7, verified via the "Memo ✨" badge in §8). If you drop manual memoization _without_
+> that confirmation, you don't get automatic memoization to replace it — you get
+> **neither**. That's not a correctness bug (React still renders the right output), but
+> every child re-renders on every parent render regardless of whether its props
+> actually changed, and every inline computation reruns every render with nothing
+> caching it. It's the pre-memoization default behavior of React — often invisible in
+> small trees, but a real source of jank in large lists, heavy computations, or deep
+> trees under a frequently-re-rendering parent. If you're not certain the compiler is
+> active yet, keep existing manual memoization until you've verified it, then remove it.
+
+Don't reach for `useMemo`, `useCallback`, or `React.memo` by default — the compiler adds
+this automatically wherever it determines it helps.
+
+```tsx
+// ❌ Old habit — noisy, and a mismatched dependency array is a whole class of bugs
+const filteredUsers = useMemo(() => users.filter((u) => u.isActive), [users]);
+const handleClick = useCallback(() => onSelect(user.id), [onSelect, user.id]);
+
+// ✅ New default — just write the logic; the compiler memoizes what's worth memoizing
+const filteredUsers = users.filter((u) => u.isActive);
+const handleClick = () => onSelect(user.id);
+```
+
+Manual memoization is still justified, narrowly, when:
+
+- You've **confirmed a compiler bail-out** (see §6) on a genuine hot path via profiling,
+  and fixing the underlying Rules-of-React violation isn't possible right now.
+- A value must have **stable referential identity across a boundary the compiler can't
+  see** — e.g. passed into a non-React library, a WebSocket subscription, or a
+  third-party hook incompatible with the compiler (`react-hook-form`'s `useForm`,
+  `@tanstack/react-table`'s `useReactTable` are known cases).
+- Keep any manual memoization it produces isolated and commented with _why_, so it
+  doesn't silently rot into a bail-out later when the code around it changes.
+
+## 2. The Rules of React are now load-bearing
+
+The compiler assumes your components and hooks are pure. Violating these rules doesn't
+just risk a subtle bug anymore — it causes the compiler to silently skip optimizing that
+component:
+
+- **Idempotent renders** — given the same props/state/context, a component must return
+  the same output. No random values, no `Date.now()`, no side effects during render.
+- **Immutability** — never mutate props, state, or context directly. Always create new
+  objects/arrays for changes.
+- **Side effects only in effects or event handlers** — never during render.
+- **Hooks called unconditionally, top-level, same order every render** — no hooks inside
+  conditionals, loops, or nested functions.
+
+```tsx
+// ❌ Mutates a prop — breaks purity and the compiler can't safely memoize this
+function TodoList({ todos }: { todos: Todo[] }) {
+  todos.sort((a, b) => a.priority - b.priority); // mutates caller's array
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  );
+}
+
+// ✅ Creates a new array — pure, compiler-safe
+function TodoList({ todos }: { todos: Todo[] }) {
+  const sorted = [...todos].sort((a, b) => a.priority - b.priority);
+  return (
+    <ul>
+      {sorted.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## 3. Naming conventions the compiler relies on
+
+The compiler identifies what to optimize by naming heuristics, same as the Rules of
+Hooks linter:
+
+| Kind                                                                     | Convention                      | Notes                                                                         |
+| ------------------------------------------------------------------------ | ------------------------------- | ----------------------------------------------------------------------------- |
+| Components                                                               | `PascalCase`, returns JSX       | Compiler treats it as a component to optimize                                 |
+| Custom hooks                                                             | `camelCase`, prefixed `use`     | Required for both Rules-of-Hooks lint and compiler analysis                   |
+| Plain helper functions that return JSX-like values but aren't components | Avoid `PascalCase`/`use` naming | Prevents the compiler (and other devs) from mistaking it for a component/hook |
+
+## 4. Typing React 19 primitives
+
+**`ref` as a normal prop** — `forwardRef` is no longer required for most cases; function
+components can accept `ref` directly.
+
+```tsx
+type InputProps = {
+  ref?: React.Ref<HTMLInputElement>;
+  placeholder?: string;
+};
+
+function TextInput({ ref, placeholder }: InputProps) {
+  return <input ref={ref} placeholder={placeholder} />;
+}
+```
+
+**Actions with `useActionState`** — type the state and payload as generics; model the
+result as a discriminated union (per the base typing skill) rather than optional fields.
+
+```tsx
+type FormState = { status: 'idle' } | { status: 'error'; message: string } | { status: 'success' };
+
+const [state, formAction, isPending] = useActionState<FormState, FormData>(
+  async (_previous, formData) => {
+    const email = formData.get('email');
+    if (typeof email !== 'string' || !email.includes('@')) {
+      return { status: 'error', message: 'Invalid email' };
+    }
+    await submit(email);
+    return { status: 'success' };
+  },
+  { status: 'idle' },
+);
+```
+
+**Optimistic updates with `useOptimistic`** — type both the state and the update shape.
+
+```tsx
+const [optimisticTodos, addOptimisticTodo] = useOptimistic<Todo[], Todo>(
+  todos,
+  (state, newTodo) => [...state, newTodo],
+);
+```
+
+**Reading a promise or context with `use()`** — type the resolved value, not the
+promise wrapper; `use()` is not a hook and may be called conditionally.
+
+```tsx
+function Comments({ commentsPromise }: { commentsPromise: Promise<Comment[]> }) {
+  const comments = use(commentsPromise); // suspends until resolved
+  return (
+    <ul>
+      {comments.map((c) => (
+        <li key={c.id}>{c.text}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+**Stable event callbacks with `useEffectEvent`** (React 19.2+) — separates "event"
+logic from "reactive" effect logic so the callback always sees the latest props/state
+without being listed as an effect dependency. Needs `eslint-plugin-react-hooks@6+` to
+lint correctly.
+
+```tsx
+const onVisit = useEffectEvent((url: string) => {
+  logVisit(url, theme); // always fresh `theme`, never re-triggers the effect
+});
+
+useEffect(() => {
+  onVisit(url);
+}, [url]); // `theme` intentionally omitted — onVisit is stable
+```
+
+## 5. Compiler-friendly render patterns
+
+- Creating new object/array/function literals inline in render (`style={{ color }}`,
+  `onClick={() => ...}`) is fine — stop manually hoisting or `useMemo`-wrapping these
+  preemptively; the compiler memoizes them if it determines it's worthwhile.
+- Avoid module-level mutable variables read or written during render — that state is
+  invisible to the compiler and breaks idempotence.
+- Don't use `useRef` to store a value that should trigger a re-render when it changes —
+  refs are an imperative escape hatch, not state, and the compiler treats them as such.
+- Keep components small and composable. The compiler optimizes per component/hook
+  boundary, so a single 300-line component gives it far less to work with than several
+  focused ones.
+
+## 6. Typing props (builds on `typescript-strict-typing`)
+
+- `interface` for a component's `Props` — it's an entity shape, often extended.
+- A discriminated union when a component has mutually exclusive prop combinations,
+  instead of a pile of optional props that can contradict each other.
+
+```tsx
+// ❌ Bad — nothing stops passing both `href` and `onClick` incoherently
+interface ButtonProps {
+  label: string;
+  href?: string;
+  onClick?: () => void;
+}
+
+// ✅ Good — the two variants can't be mixed
+type ButtonProps =
+  | { variant: 'link'; label: string; href: string }
+  | { variant: 'action'; label: string; onClick: () => void };
+```
+
+## 7. Tooling setup
+
+**The compiler is opt-in — no default setup enables it automatically.** Plain
+`@vitejs/plugin-react` (`react()`), plain Next.js, plain Babel/webpack config, etc. do
+**not** run the compiler on their own. Verify it's actually wired up before assuming any
+of the memoization guidance above applies to your build.
+
+```bash
+# Compiler (build-time transform)
+npm install --save-dev --save-exact babel-plugin-react-compiler@latest
+```
+
+**Lint rules — oxlint.** Oxlint ships a **native, Rust-based** `react/react-compiler`
+rule that runs the same compiler analysis in lint-only mode — same diagnostics as the
+Babel-based ESLint version, no Babel needed for linting. It's experimental and **off by
+default**, so it has to be enabled explicitly:
+
+```json
+// .oxlintrc.json
+{
+  "plugins": ["react"],
+  "rules": {
+    "react/react-compiler": "error"
+  }
+}
+```
+
+This single rule reports two distinct things — both worth fixing, but for different
+reasons:
+
+- **Rules-of-React violations** (conditional hooks, reading a ref during render, mutating
+  props) — these are real bugs, independent of the compiler.
+- **Compiler bail-outs** — places the compiler declined to optimize (e.g. unsupported
+  syntax) without a rule violation. Not incorrect code, just a missed optimization —
+  lower priority than a violation, but worth knowing about on a hot path.
+
+If you'd rather use an existing ESLint plugin's rules through oxlint instead of the
+native one (e.g. to match a team convention), oxlint's `jsPlugins` can load
+`eslint-plugin-react-hooks` directly — slower than the native rule since it still runs
+through Babel, but useful if you need a rule the native port doesn't cover yet:
+
+```json
+{
+  "jsPlugins": [{ "name": "react-hooks-js", "specifier": "eslint-plugin-react-hooks" }],
+  "rules": { "react-hooks-js/set-state-in-render": "error" }
+}
+```
+
+**Lint rules — ESLint** (if not on oxlint): the same rules ship inside
+`eslint-plugin-react-hooks`.
+
+```bash
+npm install --save-dev eslint-plugin-react-hooks@latest
+```
+
+```js
+// eslint.config.js
+import reactHooks from 'eslint-plugin-react-hooks';
+import { defineConfig } from 'eslint/config';
+
+export default defineConfig([reactHooks.configs.flat.recommended]);
+```
+
+**Wiring it into Vite 8.** `@vitejs/plugin-react` v6+ (the version that ships with Vite 8) switched its default transform from Babel to oxc for speed, so the compiler is
+**never** on by default and the old `react({ babel: {...} })` option **does not work**
+on this setup — it's silently ignored, not an error, which is an easy way to think the
+compiler is running when it isn't. Wire it in explicitly, as a separate Babel pass that
+runs before `react()`:
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import react, { reactCompilerPreset } from '@vitejs/plugin-react';
+import babel from '@rolldown/plugin-babel';
+
+export default defineConfig({
+  plugins: [
+    babel({ presets: [reactCompilerPreset()] }), // must run before react()
+    react(),
+  ],
+});
+```
+
+```bash
+npm install --save-dev @rolldown/plugin-babel @babel/core babel-plugin-react-compiler
+npm install --save-dev @types/babel__core   # if using TypeScript
+```
+
+`reactCompilerPreset()` is a helper exported from `@vitejs/plugin-react` itself — it
+bundles `babel-plugin-react-compiler` with sane default include/exclude filters so you
+don't have to hand-roll a Babel preset. It optionally accepts:
+
+- `compilationMode: 'annotation'` — only compile components explicitly marked with a
+  `"use memo"` directive, instead of the whole codebase (useful for a gradual rollout).
+- `target: '17' | '18'` — if any part of the app still runs on an older React major and
+  needs the `react-compiler-runtime` package instead of `react/compiler-runtime`.
+
+After adding this, confirm it's actually active via the React DevTools "Memo ✨" badge
+(§8) before trusting the "don't hand-roll memoization" guidance in §1 — a silently
+misconfigured Babel order (`react()` before `babel()`) is a common way for this to look
+wired up but do nothing.
+
+- Treat compiler-related lint errors (Rules-of-React violations, mismatched manual
+  memoization) as must-fix, not optional — an unfixed violation means that component
+  silently gets **zero** compiler optimization.
+- For a large existing codebase, adopt incrementally by scoping the babel plugin to a
+  directory (e.g. a UI component library) before enabling it globally.
+- If a specific function is genuinely incompatible with the compiler (e.g. it calls
+  `useForm` from `react-hook-form`), opt it out with the `"use no memo"` directive as
+  the **first line of the function body** — it's a temporary escape hatch, not a
+  permanent fix, so leave a comment explaining why.
+
+```tsx
+function LegacyForm() {
+  'use no memo';
+  const form = useForm(); // incompatible with the compiler today
+  // ...
+}
+```
+
+## 8. Checking whether the compiler is actually optimizing
+
+- **React DevTools** — an optimized component shows a "Memo ✨" badge next to its name
+  in the component tree.
+- **ESLint** — the compiler's recommended rules flag Rules-of-React violations at lint
+  time, before they ever become a silent runtime bail-out.
+- A bail-out is not a crash — it just means that specific component/hook is running
+  unoptimized. Treat a missing "Memo ✨" badge on a component you expect to be optimized
+  as a signal to check for a Rules-of-React violation, not a compiler bug.
+
+---
+
+## Review checklist
+
+- [ ] Compiler confirmed active ("Memo ✨" badge) before removing any _existing_ manual
+      memoization — don't strip it on faith
+- [ ] No new `useMemo`/`useCallback`/`React.memo` added without a documented reason
+      (confirmed bail-out, or a boundary the compiler can't see through)
+- [ ] No prop/state/context mutation anywhere in render
+- [ ] All hooks called unconditionally at the top level, same order every render
+- [ ] Side effects live in `useEffect`/event handlers, never during render
+- [ ] Components are `PascalCase`; hooks are `camelCase` and prefixed `use`
+- [ ] `ref` accepted as a normal prop instead of `forwardRef`, unless targeting a version
+      that requires it
+- [ ] Action/optimistic-update state modeled as a discriminated union, not optional
+      fields
+- [ ] Mutually exclusive prop combinations modeled as a discriminated union `Props` type
+- [ ] `eslint-plugin-react-hooks` recommended config enabled and passing
+- [ ] Any `"use no memo"` usage has a comment explaining why
+
+## Quick reference
+
+| Situation                                                      | Do                                                            |
+| -------------------------------------------------------------- | ------------------------------------------------------------- |
+| Tempted to write `useMemo`/`useCallback`                       | Don't — write the plain expression, let the compiler decide   |
+| Need a ref on a function component                             | Accept `ref` as a prop, skip `forwardRef`                     |
+| Form/async state with distinct outcomes                        | Discriminated union via `useActionState`, not optional fields |
+| Callback needs latest props/state without re-running an effect | `useEffectEvent`                                              |
+| A hook/library is known-incompatible with the compiler         | `"use no memo"` at the top of that function, with a comment   |
+| Checking if optimization is happening                          | React DevTools "Memo ✨" badge + compiler ESLint rules        |