@3lineas/grooveskills 1.0.2 → 1.0.3

package/skills/react-advanced/references/react-compiler.md

@@ -0,0 +1,90 @@
+# React Compiler — Adoption & Memoization Guidance
+
+> Source of truth: [React Compiler docs](https://react.dev/learn/react-compiler/introduction) and the [1.0 announcement](https://react.dev/blog/2025/10/07/react-compiler-1).
+
+## What the Compiler Is
+
+The React Compiler is a build-time optimizing compiler that rewrites components and hooks to memoize automatically. It reached **1.0 stable on 2025-10-07**. It analyzes which values a component computes, which of those depend on which inputs, and emits memoization at fine granularity — including **conditional** memoization that a hand-written `useMemo` cannot express.
+
+It supports React 17, 18, and 19, and produces the best results on 19. On 17/18 it relies on a runtime helper (`react-compiler-runtime`).
+
+## The Memoization Inversion
+
+Pre-compiler React guidance optimized for reference stability by hand: wrap derived values in `useMemo`, wrap callbacks in `useCallback`, wrap components in `React.memo`. With the compiler enabled, that work is redundant for new code, and over-memoization carries real cost (larger code, more cache slots, harder reading).
+
+### Before (manual, pre-compiler)
+
+```tsx
+export function Dashboard({ items, onSelect }: DashboardProps) {
+  const sorted = useMemo(() => items.slice().sort(byName), [items]);
+  const total = useMemo(() => items.reduce((s, i) => s + i.value, 0), [items]);
+  const handleSelect = useCallback((id: string): void => onSelect(id), [onSelect]);
+
+  return <ItemList items={sorted} total={total} onSelect={handleSelect} />;
+}
+
+const ItemList = React.memo(function ItemList({ items, total, onSelect }: ListProps) {
+  return /* ... */;
+});
+```
+
+### After (compiler enabled)
+
+```tsx
+// Plain code. The compiler memoizes `sorted`, `total`, `handleSelect`,
+// and the ItemList render output as needed — including conditionally.
+export function Dashboard({ items, onSelect }: DashboardProps) {
+  const sorted = items.slice().sort(byName);
+  const total = items.reduce((s, i) => s + i.value, 0);
+  const handleSelect = (id: string): void => onSelect(id);
+
+  return <ItemList items={sorted} total={total} onSelect={handleSelect} />;
+}
+```
+
+## When Manual Memo Still Earns Its Place
+
+Keep manual memo when:
+
+1. **A value is an effect dependency and correctness depends on its reference identity.** The compiler optimizes *render*; it does not guarantee a particular identity contract for an effect's dependency array. A value recreated each render re-fires the effect.
+
+```tsx
+const config = useMemo(() => ({ url, token }), [url, token]);
+useEffect(() => subscribe(config), [config]);
+```
+
+2. **Code the compiler cannot statically analyze.** When the compiler cannot prove a component follows the Rules of React, it safely skips that component rather than risk a miscompile. In a skipped component, manual memo remains a valid local optimization.
+
+## Do Not Strip Existing Manual Memo Blindly
+
+The compiler is designed to *preserve* existing `useMemo`/`useCallback`/`React.memo`. The [`preserve-manual-memoization`](https://react.dev/reference/eslint-plugin-react-hooks/lints/preserve-manual-memoization) lint flags cases where removing or altering manual memo would change behavior. Treat its warnings as a signal that the memo carried meaning beyond performance.
+
+## Adoption Path
+
+1. **Install ESLint support:** `eslint-plugin-react-hooks` v6+ absorbed the former `eslint-plugin-react-compiler`.
+2. **Fix reported Rules of React violations** (mutations during render, conditional hooks).
+3. **Enable the compiler in the build** (Babel, Vite, Metro, Next.js, or Rsbuild).
+
+```ts
+// vite.config.ts
+import react from "@vitejs/plugin-react";
+
+export default {
+  plugins: [
+    react({
+      babel: { plugins: [["babel-plugin-react-compiler", {}]] },
+    }),
+  ],
+};
+```
+
+4. **Verify in DevTools:** React DevTools marks compiler-optimized components with a `"Memo ✨"` badge.
+
+## Detection Checklist
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| New code still littered with `useMemo`/`useCallback` | Reflex memoization habit | Remove; let the compiler handle it |
+| `preserve-manual-memoization` warnings after cleanup | Removed load-bearing memo | Restore the memo; it stabilized an effect/identity contract |
+| A component shows no `"Memo ✨"` badge | Compiler skipped it (unanalyzable) | Fix Rules of React violations, or keep manual memo there |
+| Effect re-fires every render | A dependency value is recreated each render | Memoize that single dependency by hand |

package/skills/react-advanced/references/react19-actions-and-apis.md

@@ -0,0 +1,145 @@
+# React 19 Platform Hooks & APIs
+
+> Source of truth: [use()](https://react.dev/reference/react/use), [useActionState](https://react.dev/reference/react/useActionState), [useOptimistic](https://react.dev/reference/react/useOptimistic), [useFormStatus](https://react.dev/reference/react-dom/hooks/useFormStatus), and [<form>](https://react.dev/reference/react-dom/components/form).
+
+## The `use()` Hook
+
+`use()` reads the value of a promise or a context. Unlike every other hook, it may be called **conditionally** — after early returns or inside branches. When given a promise, it suspends the component until the promise resolves, integrating with the nearest Suspense boundary.
+
+```tsx
+import { use } from "react";
+import type { CommentItem } from "@/types/comment.types";
+
+export function CommentList({
+  commentsPromise,
+  isVisible,
+}: {
+  commentsPromise: Promise<CommentItem[]>;
+  isVisible: boolean;
+}) {
+  if (!isVisible) {
+    return null;
+  }
+
+  // Legal after an early return — `use` is exempt from the top-level rule.
+  const comments = use(commentsPromise);
+  return (
+    <ul>
+      {comments.map((c) => (
+        <li key={c.id}>{c.text}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Rules and pitfalls
+
+- **Never wrap `use()` in `try / catch`.** A suspended promise is not a synchronous error; rejections surface through an **Error Boundary**, not `catch`.
+- **Do not create the promise during render on the client.** A promise created in the render body is recreated every render, causing infinite suspension loops. Create it on the server, in a parent loader, or in an event handler, and pass it down.
+
+## Actions (`useActionState`, `useOptimistic`, `useFormStatus`)
+
+Actions are React's built-in async-mutation model, providing pending, error, and optimistic handling at the React level.
+
+### `useActionState`
+
+Runs an action function, tracks `isPending`, and threads the previous result forward (replaces the canary `useFormState`).
+
+```tsx
+import { useActionState } from "react";
+
+interface SaveResult {
+  error?: string;
+}
+
+export function UpdateNameForm({
+  saveName,
+}: {
+  saveName: (name: string) => Promise<SaveResult>;
+}) {
+  const [state, formAction, isPending] = useActionState<SaveResult, FormData>(
+    async (_prev, formData) => {
+      const name = String(formData.get("name") ?? "");
+      return await saveName(name);
+    },
+    {}
+  );
+
+  return (
+    <form action={formAction}>
+      <input name="name" disabled={isPending} />
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Saving..." : "Save"}
+      </button>
+      {state.error && <p role="alert">{state.error}</p>}
+    </form>
+  );
+}
+```
+
+### `useOptimistic`
+
+Renders an optimistic value while an async action is in flight, reverting automatically when the action settles.
+
+```tsx
+import { useOptimistic } from "react";
+
+export function LikeButton({
+  count,
+  onLike,
+}: {
+  count: number;
+  onLike: () => Promise<void>;
+}) {
+  const [optimisticCount, addOptimistic] = useOptimistic(
+    count,
+    (current, delta: number) => current + delta
+  );
+
+  async function handleAction(): Promise<void> {
+    addOptimistic(1);
+    await onLike();
+  }
+
+  return (
+    <form action={handleAction}>
+      <button type="submit">♥ {optimisticCount}</button>
+    </form>
+  );
+}
+```
+
+### `useFormStatus`
+
+Reads the pending state of the enclosing `<form>` from a child component without prop drilling.
+
+```tsx
+import { useFormStatus } from "react-dom";
+
+export function SubmitButton({ label }: { label: string }) {
+  const { pending } = useFormStatus();
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? "Submitting..." : label}
+    </button>
+  );
+}
+```
+
+## React 19 Ergonomic Changes
+
+1. **`ref` as a plain prop**: `forwardRef` is deprecated. Derive wrapper props from `ComponentProps<"input">` (which already includes `ref`), or add `ref?: React.Ref<HTMLElement>` to custom interfaces.
+2. **`<Context value>` as provider**: Render `<ThemeContext value={theme}>{children}</ThemeContext>` instead of `<ThemeContext.Provider>`.
+3. **Native document metadata**: Render `<title>`, `<meta>`, and `<link>` directly inside components; React hoists them to `<head>` automatically without `react-helmet`.
+
+## Migration Notes from React 17/18
+
+| React 17/18 idiom | React 19 replacement |
+|---|---|
+| `forwardRef((props, ref) => ...)` | `ref` as a plain prop |
+| `<Context.Provider value={...}>` | `<Context value={...}>` |
+| `react-helmet` for `<head>` tags | Native `<title>`, `<meta>`, `<link>` hoisting |
+| `useFormState` (canary) | `useActionState` (from `"react"`) |
+| Manual `isLoading`/`error` state in submit handlers | `useActionState` + `useOptimistic` + `useFormStatus` |
+| Fetch in `useEffect` + store in `useState` | Pass a promise to `use()` under `<Suspense>` |

package/skills/react-advanced/references/rsc-boundary.md

@@ -0,0 +1,129 @@
+# RSC / `'use client'` Boundary & `'use server'` Security
+
+> Source of truth: [Server Components](https://react.dev/reference/rsc/server-components), [`'use client'`](https://react.dev/reference/rsc/use-client), and [`'use server'`](https://react.dev/reference/rsc/use-server).
+
+## Server Components by Default
+
+In an RSC architecture, components render on the server ahead of time and emit a serializable UI tree:
+
+- **No client state or effects**: Server Components cannot call `useState`, `useEffect`, or browser DOM APIs.
+- **Direct `async / await`**: Server Components can `await` database/action calls directly without shipping library code to the browser.
+
+```tsx
+import { getArticleByIdAction } from "@/actions/articles/get-article-by-id.action";
+import { LikeButton } from "@/components/articles/like-button";
+
+export async function ArticleView({ articleId }: { articleId: string }) {
+  const article = await getArticleByIdAction(articleId);
+  if (!article) {
+    return <p>The requested article could not be found.</p>;
+  }
+
+  return (
+    <article>
+      <h1>{article.title}</h1>
+      <LikeButton articleId={article.id} initialLikes={article.likes} />
+    </article>
+  );
+}
+```
+
+## The Boundary Is on the Module Graph, Not the Render Tree
+
+`'use client'` placed at the top of a file marks that **module and all of its static imports** as client code.
+
+### Two Key Architectural Rules
+
+1. **Props crossing into a Client Component must be serializable** (primitives, plain objects, arrays, `ReactNode`, or `'use server'` functions). Class instances, closures, and `Date`/`Map` instances (unless supported by the framework serializer) cannot cross as props.
+2. **Client Components can render Server Components passed as `children` (Slot pattern).** Passing a Server Component via `children` keeps the server subtree on the server without pulling its dependencies into the client bundle:
+
+```tsx
+"use client";
+
+import { useState, type ReactNode } from "react";
+
+export function CollapsiblePanel({
+  title,
+  children,
+}: {
+  title: string;
+  children: ReactNode;
+}) {
+  const [isOpen, setIsOpen] = useState<boolean>(false);
+
+  return (
+    <section>
+      <button type="button" onClick={() => setIsOpen((prev) => !prev)}>
+        {title}
+      </button>
+      {isOpen && <div>{children}</div>}
+    </section>
+  );
+}
+```
+
+## `'use server'` — Server Functions & Valibot Validation
+
+`'use server'` marks a function as callable from the client but executed on the server. Treat every `'use server'` function as an **untrusted public HTTP endpoint**:
+
+1. **Always validate inputs with Valibot** (`* as v from "valibot"`). Never use Zod.
+2. **Always authenticate and authorize** the caller inside the function before mutating state.
+
+```tsx
+"use server";
+
+import * as v from "valibot";
+import { requireSessionUser } from "@/actions/auth/require-session-user.action";
+import { createCommentAction } from "@/actions/comments/create-comment.action";
+
+const publishCommentSchema = v.object({
+  text: v.pipe(
+    v.string("Please enter a comment."),
+    v.trim(),
+    v.minLength(2, "Your comment must be at least 2 characters long.")
+  ),
+});
+
+export async function publishCommentServerFn(formData: FormData) {
+  const parsed = v.safeParse(publishCommentSchema, {
+    text: formData.get("text"),
+  });
+
+  if (!parsed.success) {
+    return {
+      success: false,
+      error: parsed.issues[0].message,
+    };
+  }
+
+  const user = await requireSessionUser();
+  await createCommentAction({ userId: user.id, text: parsed.output.text });
+
+  return {
+    success: true,
+    message: "Your comment has been published successfully.",
+  };
+}
+```
+
+## Version Pinning in RSC Projects
+
+RSC relies on bundler-facing internals that are not semver-stable across minor/patch skews. Pin exact matching versions of `react` and `react-dom` in `package.json`:
+
+```json
+{
+  "dependencies": {
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
+  }
+}
+```
+
+## Anti-Patterns
+
+| Anti-pattern | Why it is wrong | Fix |
+|---|---|---|
+| Calling `useState`/`useEffect` in a Server Component | Server Components do not execute on the client | Extract interactive leaf into a `'use client'` component |
+| Importing server-only modules into a `'use client'` file | Pulls server code into the client bundle or fails build | Pass server data via serializable props or `children` slots |
+| Trusting `'use server'` arguments without validation | Client payloads can be forged like any HTTP POST | Validate with Valibot (`v.safeParse`) and verify auth inside the function |
+| Using caret ranges (`^19.0.0`) with RSC bundlers | Version skew between `react` and `react-dom` breaks RSC wiring | Pin exact matching versions |

package/skills/react-core/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: react-core
+description: Use when building or modifying React components, JSX, props, local state, core hooks (useState, useEffect, useRef, useContext, useMemo, useCallback), lists, conditional UI, or controlled inputs. TRIGGER when the project imports 'react' or 'react-dom', or when editing .tsx/.jsx files. Always adhere to the 'best-practices' skill and pair with 'react-advanced' for React 19 platform features and performance architecture.
+---
+
+# React Core Fundamentals & Opinionated Standards
+
+Canonical reference for React fundamentals in GrooveSkills projects: function components, JSX, props and immutable state, core hooks, composition, conditional and list rendering, and controlled inputs.
+
+---
+
+## 1. Golden Rules (Non-negotiable)
+
+1. **One Component per File & < 200 Lines**:
+   - Every exported React component resides in its own dedicated `.tsx` file and never exceeds **200 lines**.
+   - Extract sub-components or custom hooks (`use-*.ts`) into atomic files before reaching the limit.
+2. **Mandatory Path Aliases (`@/...`) & Zero Barrel Files**:
+   - Import components, hooks, schemas, and utilities directly via path aliases (`@/components/ui/card`, `@/hooks/use-window-width`).
+   - Never create `index.ts` or `index.tsx` barrel files to re-export components or hooks.
+3. **Strict Props Typing (Zero `any`)**:
+   - Define explicit `interface` or `type` declarations for component props.
+   - Treat `props` and `state` as strictly immutable.
+4. **Early Returns for UI States (No Nested Ternaries)**:
+   - Handle loading, error, and empty states with top-level guard clauses (`if (!data) return <EmptyState />;`) instead of deeply nested JSX conditionals.
+5. **Top-Level Hooks Only (Rules of Hooks)**:
+   - Call hooks unconditionally at the top level of function components or custom hooks—never inside loops, conditions, or nested functions (except React 19's `use()`, covered in `react-advanced`).
+6. **Immutable State Updates & Functional Updaters**:
+   - Never mutate arrays or objects in place (`items.push()`). Always pass a new reference (`[...items, next]`).
+   - Use functional updaters (`setCount((prev) => prev + step)`) whenever next state depends on previous state.
+7. **Compiler-Aware Memoization**:
+   - Do not wrap every value or callback in `useMemo` or `useCallback` by reflex. When the React Compiler is active, it memoizes automatically.
+   - Reserve manual `useMemo` and `useCallback` for stabilizing references passed to `useEffect` dependency arrays or for genuinely expensive computations in uncompiled modules.
+8. **Stable Identity Keys in Lists**:
+   - Always provide a stable, unique `key` derived from domain identity (`item.id`), never the array index (`i`) for dynamic or reorderable lists.
+9. **Controlled Inputs with Single Source of Truth**:
+   - Derive input `value` from state and handle updates via `onChange`, validating user input with **Valibot** (`* as v from "valibot"`) where applicable.
+
+---
+
+## 2. Components, JSX, Props, and Early Returns
+
+Name components in `PascalCase`. Return a single root element or Fragment (`<>...</>`). Use guard clauses to keep the primary render path flat.
+
+```tsx
+import { useState } from "react";
+
+interface UserSummaryProps {
+  name: string;
+  role?: string;
+  isActive: boolean;
+  step?: number;
+}
+
+export function UserSummary({ name, role = "Member", isActive, step = 1 }: UserSummaryProps) {
+  const [count, setCount] = useState<number>(0);
+
+  if (!isActive) {
+    return <p className="text-muted">This account is currently inactive.</p>;
+  }
+
+  return (
+    <section className="user-summary">
+      <h2>Hello, {name} ({role})</h2>
+      <button type="button" onClick={() => setCount((prev) => prev + step)}>
+        Count: {count}
+      </button>
+    </section>
+  );
+}
+```
+
+---
+
+## 3. Core Hooks Guide
+
+- **`useState`**: Holds reactive local state (`const [isOpen, setIsOpen] = useState<boolean>(false);`).
+- **`useEffect`**: Synchronizes with external systems (DOM listeners, timers, subscriptions). Always declare accurate dependencies and return a cleanup function.
+- **`useRef`**: Holds a mutable value across renders without causing re-renders, or references a DOM node.
+- **`useMemo` & `useCallback`**: Deliberate escape hatches to stabilize references for `useEffect` dependency arrays or heavy computations in uncompiled components.
+- **`useContext`**: Reads shared state from a `Context` higher in the tree (`<ThemeContext value={theme}>` in React 19).
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+
+export function AutoFocusWindowTracker() {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [width, setWidth] = useState<number>(() => window.innerWidth);
+
+  useEffect(() => {
+    inputRef.current?.focus();
+    const handleResize = (): void => setWidth(window.innerWidth);
+    window.addEventListener("resize", handleResize);
+    return () => window.removeEventListener("resize", handleResize);
+  }, []);
+
+  return <input ref={inputRef} placeholder={`Viewport: ${width}px`} />;
+}
+```
+
+---
+
+## 4. Composition, Lists, and Controlled Inputs
+
+Favor composition via `children` over bloated configuration props, use stable domain keys (`todo.id`) for lists, and bind controlled inputs to state:
+
+```tsx
+import { useState, type ReactNode } from "react";
+
+export interface TodoItem {
+  id: string;
+  text: string;
+  done: boolean;
+}
+
+export function TodoCard({
+  title,
+  todos,
+  children,
+}: {
+  title: string;
+  todos: TodoItem[];
+  children?: ReactNode;
+}) {
+  const [filter, setFilter] = useState<string>("");
+
+  if (todos.length === 0) {
+    return <p>Your task list is clear. Add a new item to get started.</p>;
+  }
+
+  const visible = todos.filter((t) => t.text.toLowerCase().includes(filter.toLowerCase()));
+
+  return (
+    <article className="card">
+      <h2>{title}</h2>
+      <input
+        value={filter}
+        onChange={(event) => setFilter(event.target.value)}
+        placeholder="Filter tasks..."
+      />
+      <ul>
+        {visible.map((todo) => (
+          <li key={todo.id}>{todo.done ? <s>{todo.text}</s> : todo.text}</li>
+        ))}
+      </ul>
+      {children}
+    </article>
+  );
+}
+```
+
+---
+
+## 5. Anti-Patterns to Avoid
+
+| Anti-Pattern | Why It Fails | Correct Pattern |
+| :--- | :--- | :--- |
+| Mutating state in place (`items.push(next)`) | Same array reference; React skips re-render | Create a new reference: `setItems((prev) => [...prev, next])` |
+| Calling hooks after `if` or inside loops | Breaks React's deterministic hook call order | Call hooks unconditionally at the top level; branch on results |
+| Using array index `key={i}` on dynamic lists | Misattributes component state on insert, delete, or sort | Use a stable domain identifier: `key={item.id}` |
+| Fetching or deriving synchronous state inside `useEffect` | Triggers an extra render pass and causes UI flicker | Derive values inline during render; use `use()` / Suspense or Actions for async data (`react-advanced`) |
+| Re-exporting components via `components/index.ts` | Violates Zero Barrel Files and harms tree-shaking | Import directly from `@/components/ui/card` |
+
+---
+
+## 6. Sibling Skills
+
+- **`best-practices`**: Universal clean architecture, `< 200` lines limit, `@/` path aliases, strict typing, and courteous user feedback.
+- **`react-advanced`**: React 19 platform features, React Compiler 1.0 auto-memoization, concurrent rendering (`useTransition`, `useDeferredValue`, `Suspense`), `use()`, Actions (`useActionState`, `useOptimistic`, `useFormStatus`), context optimization, virtualization, and RSC boundaries.