@hybridlabor-api/bdb-antigravity-skills 1.0.0

package/skills/global_config/react-best-practices/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

package/skills/global_config/react-component-performance/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: react-component-performance
+description: Diagnose slow React components and suggest targeted performance fixes.
+risk: safe
+source: "Dimillian/Skills (MIT)"
+date_added: "2026-03-25"
+---
+
+# React Component Performance
+
+## Overview
+
+Identify render hotspots, isolate expensive updates, and apply targeted optimizations without changing UI behavior.
+
+## When to Use
+- When the user asks to profile or improve a slow React component.
+- When you need to reduce re-renders, list lag, or expensive render work in React UI.
+
+## Workflow
+
+1. Reproduce or describe the slowdown.
+2. Identify what triggers re-renders (state updates, props churn, effects).
+3. Isolate fast-changing state from heavy subtrees.
+4. Stabilize props and handlers; memoize where it pays off.
+5. Reduce expensive work (computation, DOM size, list length).
+6. **Validate**: open React DevTools Profiler → record the interaction → inspect the Flamegraph for components rendering longer than ~16 ms → compare against a pre-optimization baseline recording.
+
+## Checklist
+
+- Measure: use React DevTools Profiler or log renders; capture baseline.
+- Find churn: identify state updated on a timer, scroll, input, or animation.
+- Split: move ticking state into a child; keep heavy lists static.
+- Memoize: wrap leaf rows with `memo` only when props are stable.
+- Stabilize props: use `useCallback`/`useMemo` for handlers and derived values.
+- Avoid derived work in render: precompute, or compute inside memoized helpers.
+- Control list size: window/virtualize long lists; avoid rendering hidden items.
+- Keys: ensure stable keys; avoid index when order can change.
+- Effects: verify dependency arrays; avoid effects that re-run on every render.
+- Style/layout: watch for expensive layout thrash or large Markdown/diff renders.
+
+## Optimization Patterns
+
+### Isolate ticking state
+
+Move a timer or animation counter into a child so the parent list never re-renders on each tick.
+
+```tsx
+// ❌ Before – entire parent (and list) re-renders every second
+function Dashboard({ items }: { items: Item[] }) {
+  const [tick, setTick] = useState(0);
+  useEffect(() => {
+    const id = setInterval(() => setTick(t => t + 1), 1000);
+    return () => clearInterval(id);
+  }, []);
+  return (
+    <>
+      <Clock tick={tick} />
+      <ExpensiveList items={items} /> {/* re-renders every second */}
+    </>
+  );
+}
+
+// ✅ After – only <Clock> re-renders; list is untouched
+function Clock() {
+  const [tick, setTick] = useState(0);
+  useEffect(() => {
+    const id = setInterval(() => setTick(t => t + 1), 1000);
+    return () => clearInterval(id);
+  }, []);
+  return <span>{tick}s</span>;
+}
+
+function Dashboard({ items }: { items: Item[] }) {
+  return (
+    <>
+      <Clock />
+      <ExpensiveList items={items} />
+    </>
+  );
+}
+```
+
+### Stabilize callbacks with `useCallback` + `memo`
+
+```tsx
+// ❌ Before – new handler reference on every render busts Row memo
+function List({ items }: { items: Item[] }) {
+  const handleClick = (id: string) => console.log(id); // new ref each render
+  return items.map(item => <Row key={item.id} item={item} onClick={handleClick} />);
+}
+
+// ✅ After – stable handler; Row only re-renders when its own item changes
+const Row = memo(({ item, onClick }: RowProps) => (
+  <li onClick={() => onClick(item.id)}>{item.name}</li>
+));
+
+function List({ items }: { items: Item[] }) {
+  const handleClick = useCallback((id: string) => console.log(id), []);
+  return items.map(item => <Row key={item.id} item={item} onClick={handleClick} />);
+}
+```
+
+### Prefer derived data outside render
+
+```tsx
+// ❌ Before – recomputes on every render
+function Summary({ orders }: { orders: Order[] }) {
+  const total = orders.reduce((sum, o) => sum + o.amount, 0); // runs every render
+  return <p>Total: {total}</p>;
+}
+
+// ✅ After – recomputes only when orders changes
+function Summary({ orders }: { orders: Order[] }) {
+  const total = useMemo(() => orders.reduce((sum, o) => sum + o.amount, 0), [orders]);
+  return <p>Total: {total}</p>;
+}
+```
+
+### Additional patterns
+
+- **Split rows**: extract list rows into memoized components with narrow props.
+- **Defer heavy rendering**: lazy-render or collapse expensive content until expanded.
+
+## Profiling Validation Steps
+
+1. Open **React DevTools → Profiler** tab.
+2. Click **Record**, perform the slow interaction, then **Stop**.
+3. Switch to **Flamegraph** view; any bar labeled with a component and time > ~16 ms is a candidate.
+4. Use **Ranked chart** to sort by self render time and target the top offenders.
+5. Apply one optimization at a time, re-record, and compare render counts and durations against the baseline.
+
+## Example Reference
+
+Load `references/examples.md` when the user wants a concrete refactor example.
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/skills/global_config/react-component-performance/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "React Component Performance"
+  short_description: "Profile and fix React render issues"
+  default_prompt: "Use $react-component-performance to analyze and improve this React component's rendering performance."

package/skills/global_config/react-component-performance/references/examples.md

@@ -0,0 +1,88 @@
+# Examples
+
+## Isolate a ticking timer from a long list
+
+**Scenario:** A message list re-renders every second because a timer (`elapsedMs`) lives in the parent component. This causes visible jank on large lists.
+
+**Goal:** Keep UI identical but limit re-renders to the timer area.
+
+**Before (problematic pattern):**
+
+```tsx
+function Messages({ items, isThinking, processingStartedAt }) {
+  const [elapsedMs, setElapsedMs] = useState(0);
+
+  useEffect(() => {
+    if (!isThinking || !processingStartedAt) {
+      setElapsedMs(0);
+      return;
+    }
+    setElapsedMs(Date.now() - processingStartedAt);
+    const interval = window.setInterval(() => {
+      setElapsedMs(Date.now() - processingStartedAt);
+    }, 1000);
+    return () => window.clearInterval(interval);
+  }, [isThinking, processingStartedAt]);
+
+  return (
+    <div>
+      {items.map((item) => (
+        <MessageRow key={item.id} item={item} />
+      ))}
+      <div>{formatDurationMs(elapsedMs)}</div>
+    </div>
+  );
+}
+```
+
+**After (isolated ticking state):**
+
+```tsx
+type WorkingIndicatorProps = {
+  isThinking: boolean;
+  processingStartedAt?: number | null;
+};
+
+const WorkingIndicator = memo(function WorkingIndicator({
+  isThinking,
+  processingStartedAt = null,
+}: WorkingIndicatorProps) {
+  const [elapsedMs, setElapsedMs] = useState(0);
+
+  useEffect(() => {
+    if (!isThinking || !processingStartedAt) {
+      setElapsedMs(0);
+      return;
+    }
+    setElapsedMs(Date.now() - processingStartedAt);
+    const interval = window.setInterval(() => {
+      setElapsedMs(Date.now() - processingStartedAt);
+    }, 1000);
+    return () => window.clearInterval(interval);
+  }, [isThinking, processingStartedAt]);
+
+  return <div>{formatDurationMs(elapsedMs)}</div>;
+});
+
+function Messages({ items, isThinking, processingStartedAt }) {
+  return (
+    <div>
+      {items.map((item) => (
+        <MessageRow key={item.id} item={item} />
+      ))}
+      <WorkingIndicator
+        isThinking={isThinking}
+        processingStartedAt={processingStartedAt}
+      />
+    </div>
+  );
+}
+```
+
+**Why it helps:** Only the `WorkingIndicator` subtree re-renders every second. The list remains stable unless its props change.
+
+**Optional follow-ups:**
+
+- Wrap `MessageRow` in `memo` if props are stable.
+- Use `useCallback` for handlers passed to rows to avoid re-render churn.
+- Consider list virtualization if the list is very large.

package/skills/global_config/react-patterns/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: react-patterns
+description: "Modern React patterns and principles. Hooks, composition, performance, TypeScript best practices."
+risk: safe
+source: community
+date_added: "2026-02-27"
+---
+
+# React Patterns
+
+> Principles for building production-ready React applications.
+
+---
+
+## 1. Component Design Principles
+
+### Component Types
+
+| Type | Use | State |
+|------|-----|-------|
+| **Server** | Data fetching, static | None |
+| **Client** | Interactivity | useState, effects |
+| **Presentational** | UI display | Props only |
+| **Container** | Logic/state | Heavy state |
+
+### Design Rules
+
+- One responsibility per component
+- Props down, events up
+- Composition over inheritance
+- Prefer small, focused components
+
+---
+
+## 2. Hook Patterns
+
+### When to Extract Hooks
+
+| Pattern | Extract When |
+|---------|-------------|
+| **useLocalStorage** | Same storage logic needed |
+| **useDebounce** | Multiple debounced values |
+| **useFetch** | Repeated fetch patterns |
+| **useForm** | Complex form state |
+
+### Hook Rules
+
+- Hooks at top level only
+- Same order every render
+- Custom hooks start with "use"
+- Clean up effects on unmount
+
+---
+
+## 3. State Management Selection
+
+| Complexity | Solution |
+|------------|----------|
+| Simple | useState, useReducer |
+| Shared local | Context |
+| Server state | React Query, SWR |
+| Complex global | Zustand, Redux Toolkit |
+
+### State Placement
+
+| Scope | Where |
+|-------|-------|
+| Single component | useState |
+| Parent-child | Lift state up |
+| Subtree | Context |
+| App-wide | Global store |
+
+---
+
+## 4. React 19 Patterns
+
+### New Hooks
+
+| Hook | Purpose |
+|------|---------|
+| **useActionState** | Form submission state |
+| **useOptimistic** | Optimistic UI updates |
+| **use** | Read resources in render |
+
+### Compiler Benefits
+
+- Automatic memoization
+- Less manual useMemo/useCallback
+- Focus on pure components
+
+---
+
+## 5. Composition Patterns
+
+### Compound Components
+
+- Parent provides context
+- Children consume context
+- Flexible slot-based composition
+- Example: Tabs, Accordion, Dropdown
+
+### Render Props vs Hooks
+
+| Use Case | Prefer |
+|----------|--------|
+| Reusable logic | Custom hook |
+| Render flexibility | Render props |
+| Cross-cutting | Higher-order component |
+
+---
+
+## 6. Performance Principles
+
+### When to Optimize
+
+| Signal | Action |
+|--------|--------|
+| Slow renders | Profile first |
+| Large lists | Virtualize |
+| Expensive calc | useMemo |
+| Stable callbacks | useCallback |
+
+### Optimization Order
+
+1. Check if actually slow
+2. Profile with DevTools
+3. Identify bottleneck
+4. Apply targeted fix
+
+---
+
+## 7. Error Handling
+
+### Error Boundary Usage
+
+| Scope | Placement |
+|-------|-----------|
+| App-wide | Root level |
+| Feature | Route/feature level |
+| Component | Around risky component |
+
+### Error Recovery
+
+- Show fallback UI
+- Log error
+- Offer retry option
+- Preserve user data
+
+---
+
+## 8. TypeScript Patterns
+
+### Props Typing
+
+| Pattern | Use |
+|---------|-----|
+| Interface | Component props |
+| Type | Unions, complex |
+| Generic | Reusable components |
+
+### Common Types
+
+| Need | Type |
+|------|------|
+| Children | ReactNode |
+| Event handler | MouseEventHandler |
+| Ref | RefObject<Element> |
+
+---
+
+## 9. Testing Principles
+
+| Level | Focus |
+|-------|-------|
+| Unit | Pure functions, hooks |
+| Integration | Component behavior |
+| E2E | User flows |
+
+### Test Priorities
+
+- User-visible behavior
+- Edge cases
+- Error states
+- Accessibility
+
+---
+
+## 10. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Prop drilling deep | Use context |
+| Giant components | Split smaller |
+| useEffect for everything | Server components |
+| Premature optimization | Profile first |
+| Index as key | Stable unique ID |
+
+---
+
+## 11. File Structure
+
+<img width="1150" height="1438" alt="image" src="https://github.com/user-attachments/assets/10369698-472c-4695-a494-2c0672103aa1" />
+
+Use this image as a reference for a better file structure of the project
+
+---
+
+> **Remember:** React is about composition. Build small, combine thoughtfully.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.