@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/react-expert/references/performance.md

@@ -0,0 +1,168 @@
+# Performance Optimization
+
+## React.memo
+
+```tsx
+import { memo } from 'react';
+
+// Memoize component - only re-renders when props change
+const ExpensiveList = memo(function ExpensiveList({ items }: { items: Item[] }) {
+  return (
+    <ul>
+      {items.map(item => <li key={item.id}>{item.name}</li>)}
+    </ul>
+  );
+});
+
+// Custom comparison function
+const UserCard = memo(
+  function UserCard({ user }: { user: User }) {
+    return <div>{user.name}</div>;
+  },
+  (prevProps, nextProps) => prevProps.user.id === nextProps.user.id
+);
+```
+
+## Preventing Re-renders
+
+```tsx
+// Problem: New object/function on each render
+function Parent() {
+  // ❌ Creates new object every render
+  return <Child style={{ color: 'red' }} onClick={() => doSomething()} />;
+}
+
+// Solution: Memoize or lift out
+const style = { color: 'red' }; // Lifted out
+
+function Parent() {
+  const handleClick = useCallback(() => doSomething(), []);
+  return <Child style={style} onClick={handleClick} />;
+}
+```
+
+## Code Splitting with lazy()
+
+```tsx
+import { lazy, Suspense } from 'react';
+
+// Split heavy components
+const HeavyChart = lazy(() => import('./HeavyChart'));
+const AdminPanel = lazy(() => import('./AdminPanel'));
+
+function App() {
+  return (
+    <Suspense fallback={<Loading />}>
+      {showChart && <HeavyChart data={data} />}
+    </Suspense>
+  );
+}
+
+// Route-based splitting (React Router)
+const routes = [
+  {
+    path: '/admin',
+    element: (
+      <Suspense fallback={<Loading />}>
+        <AdminPanel />
+      </Suspense>
+    ),
+  },
+];
+```
+
+## Virtualization
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual';
+
+function VirtualList({ items }: { items: Item[] }) {
+  const parentRef = useRef<HTMLDivElement>(null);
+
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 50,
+  });
+
+  return (
+    <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
+      <div style={{ height: virtualizer.getTotalSize() }}>
+        {virtualizer.getVirtualItems().map((virtualItem) => (
+          <div
+            key={virtualItem.key}
+            style={{
+              position: 'absolute',
+              top: virtualItem.start,
+              height: virtualItem.size,
+            }}
+          >
+            {items[virtualItem.index].name}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## useMemo for Expensive Calculations
+
+```tsx
+function Analytics({ data }: { data: DataPoint[] }) {
+  // Only recalculate when data changes
+  const stats = useMemo(() => ({
+    total: data.reduce((sum, d) => sum + d.value, 0),
+    average: data.reduce((sum, d) => sum + d.value, 0) / data.length,
+    max: Math.max(...data.map(d => d.value)),
+  }), [data]);
+
+  return <StatsDisplay stats={stats} />;
+}
+```
+
+## useTransition for Non-urgent Updates
+
+```tsx
+import { useTransition } from 'react';
+
+function Search() {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState<Item[]>([]);
+  const [isPending, startTransition] = useTransition();
+
+  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
+    setQuery(e.target.value); // Urgent: update input immediately
+
+    startTransition(() => {
+      // Non-urgent: can be interrupted
+      setResults(filterItems(e.target.value));
+    });
+  }
+
+  return (
+    <>
+      <input value={query} onChange={handleChange} />
+      {isPending ? <Spinner /> : <Results items={results} />}
+    </>
+  );
+}
+```
+
+## Quick Reference
+
+| Technique | When to Use |
+|-----------|-------------|
+| `memo()` | Prevent re-renders from unchanged props |
+| `useMemo()` | Cache expensive calculations |
+| `useCallback()` | Stable function references |
+| `lazy()` | Code split heavy components |
+| `useTransition()` | Keep UI responsive during updates |
+| Virtualization | Large lists (1000+ items) |
+
+| Anti-pattern | Fix |
+|--------------|-----|
+| Inline objects | Lift out or useMemo |
+| Inline functions | useCallback |
+| Large bundle | lazy() + Suspense |
+| Long lists | Virtualization |

package/Ai Agent Workflow/skills/react-expert/references/react-19-features.md

@@ -0,0 +1,174 @@
+# React 19 Features
+
+## use() Hook
+
+```tsx
+import { use, Suspense } from 'react';
+
+// Read promises in render
+function Comments({ commentsPromise }: { commentsPromise: Promise<Comment[]> }) {
+  const comments = use(commentsPromise);
+  return (
+    <ul>
+      {comments.map(c => <li key={c.id}>{c.text}</li>)}
+    </ul>
+  );
+}
+
+// Parent creates promise, child reads it
+function Post({ postId }: { postId: string }) {
+  const commentsPromise = fetchComments(postId);
+
+  return (
+    <article>
+      <PostContent id={postId} />
+      <Suspense fallback={<CommentsSkeleton />}>
+        <Comments commentsPromise={commentsPromise} />
+      </Suspense>
+    </article>
+  );
+}
+
+// Read context conditionally
+function Theme({ children }: { children: React.ReactNode }) {
+  if (someCondition) {
+    const theme = use(ThemeContext);
+    return <div className={theme}>{children}</div>;
+  }
+  return children;
+}
+```
+
+## useActionState
+
+```tsx
+'use client';
+import { useActionState } from 'react';
+
+interface FormState {
+  error?: string;
+  success?: boolean;
+}
+
+async function submitAction(prevState: FormState, formData: FormData): Promise<FormState> {
+  'use server';
+  const email = formData.get('email') as string;
+
+  try {
+    await subscribe(email);
+    return { success: true };
+  } catch {
+    return { error: 'Failed to subscribe' };
+  }
+}
+
+function NewsletterForm() {
+  const [state, formAction, isPending] = useActionState(submitAction, {});
+
+  return (
+    <form action={formAction}>
+      <input name="email" type="email" required disabled={isPending} />
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Subscribing...' : 'Subscribe'}
+      </button>
+      {state.error && <p className="error">{state.error}</p>}
+      {state.success && <p className="success">Subscribed!</p>}
+    </form>
+  );
+}
+```
+
+## useFormStatus
+
+```tsx
+'use client';
+import { useFormStatus } from 'react-dom';
+
+function SubmitButton() {
+  const { pending, data, method, action } = useFormStatus();
+
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? 'Submitting...' : 'Submit'}
+    </button>
+  );
+}
+
+// Must be used inside a <form>
+function ContactForm() {
+  return (
+    <form action={submitAction}>
+      <input name="message" />
+      <SubmitButton />
+    </form>
+  );
+}
+```
+
+## useOptimistic
+
+```tsx
+'use client';
+import { useOptimistic } from 'react';
+
+function TodoList({ todos }: { todos: Todo[] }) {
+  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
+    todos,
+    (state, newTodo: Todo) => [...state, newTodo]
+  );
+
+  async function addTodo(formData: FormData) {
+    const text = formData.get('text') as string;
+
+    // Immediately update UI
+    addOptimisticTodo({ id: 'temp', text, completed: false });
+
+    // Then persist
+    await createTodo(text);
+  }
+
+  return (
+    <>
+      <ul>
+        {optimisticTodos.map(todo => (
+          <li key={todo.id}>{todo.text}</li>
+        ))}
+      </ul>
+      <form action={addTodo}>
+        <input name="text" />
+        <button>Add</button>
+      </form>
+    </>
+  );
+}
+```
+
+## ref as Prop (No forwardRef)
+
+```tsx
+// React 19: ref is just a prop
+function Input({ ref, ...props }: { ref?: React.Ref<HTMLInputElement> }) {
+  return <input ref={ref} {...props} />;
+}
+
+// No need for forwardRef anymore
+function Form() {
+  const inputRef = useRef<HTMLInputElement>(null);
+  return <Input ref={inputRef} placeholder="Enter text" />;
+}
+```
+
+## Quick Reference
+
+| Hook | Purpose |
+|------|---------|
+| `use()` | Read promise/context in render |
+| `useActionState()` | Form action state + pending |
+| `useFormStatus()` | Form pending state (child) |
+| `useOptimistic()` | Optimistic UI updates |
+
+| Pattern | When |
+|---------|------|
+| `use(promise)` | Suspense data fetching |
+| `use(context)` | Conditional context read |
+| `useActionState` | Server Actions with state |

package/Ai Agent Workflow/skills/react-expert/references/server-components.md

@@ -0,0 +1,143 @@
+# Server Components
+
+## Server vs Client Components
+
+```tsx
+// Server Component (default in App Router)
+// Can: fetch data, access backend, use async/await
+// Cannot: use hooks, browser APIs, event handlers
+async function ProductList() {
+  const products = await db.products.findMany();
+  return (
+    <ul>
+      {products.map(p => <ProductCard key={p.id} product={p} />)}
+    </ul>
+  );
+}
+
+// Client Component (explicit)
+'use client';
+import { useState } from 'react';
+
+function AddToCartButton({ productId }: { productId: string }) {
+  const [loading, setLoading] = useState(false);
+  return (
+    <button onClick={() => addToCart(productId)} disabled={loading}>
+      Add to Cart
+    </button>
+  );
+}
+```
+
+## Data Fetching Pattern
+
+```tsx
+// app/products/page.tsx
+export default async function ProductsPage() {
+  // Runs on server only - no client bundle impact
+  const products = await fetch('https://api.example.com/products', {
+    next: { revalidate: 3600 } // Cache for 1 hour
+  }).then(res => res.json());
+
+  return <ProductGrid products={products} />;
+}
+
+// Parallel data fetching
+async function Dashboard() {
+  const [user, orders, recommendations] = await Promise.all([
+    getUser(),
+    getOrders(),
+    getRecommendations(),
+  ]);
+
+  return (
+    <>
+      <UserHeader user={user} />
+      <OrderList orders={orders} />
+      <Recommendations items={recommendations} />
+    </>
+  );
+}
+```
+
+## Streaming with Suspense
+
+```tsx
+import { Suspense } from 'react';
+
+async function SlowComponent() {
+  const data = await slowFetch(); // 3 second API call
+  return <div>{data}</div>;
+}
+
+export default function Page() {
+  return (
+    <main>
+      <h1>Dashboard</h1>
+      <FastComponent />
+
+      <Suspense fallback={<Skeleton />}>
+        <SlowComponent />
+      </Suspense>
+    </main>
+  );
+}
+```
+
+## Passing Data Server → Client
+
+```tsx
+// Server Component
+async function ProductPage({ id }: { id: string }) {
+  const product = await getProduct(id);
+
+  // Pass serializable data to client
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      {/* Client component receives serialized props */}
+      <AddToCartButton productId={product.id} price={product.price} />
+    </div>
+  );
+}
+```
+
+## Server Actions
+
+```tsx
+// actions.ts
+'use server';
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title') as string;
+  await db.posts.create({ data: { title } });
+  revalidatePath('/posts');
+}
+
+// page.tsx (Server Component)
+import { createPost } from './actions';
+
+export default function NewPost() {
+  return (
+    <form action={createPost}>
+      <input name="title" required />
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+## Quick Reference
+
+| Type | Can Use | Cannot Use |
+|------|---------|------------|
+| Server | async/await, db, fs | useState, onClick |
+| Client | hooks, events, browser APIs | async component |
+
+| Pattern | Use Case |
+|---------|----------|
+| Server Component | Data fetching, heavy deps |
+| Client Component | Interactivity, state |
+| `'use client'` | Mark client boundary |
+| `'use server'` | Server Action |
+| Suspense | Streaming, loading states |

package/Ai Agent Workflow/skills/react-expert/references/state-management.md

@@ -0,0 +1,171 @@
+# State Management
+
+## Local State (useState)
+
+```tsx
+function Counter() {
+  const [count, setCount] = useState(0);
+
+  // Functional update for derived state
+  const increment = () => setCount(prev => prev + 1);
+
+  return <button onClick={increment}>{count}</button>;
+}
+```
+
+## Context for Simple Global State
+
+```tsx
+interface ThemeContext {
+  theme: 'light' | 'dark';
+  toggle: () => void;
+}
+
+const ThemeContext = createContext<ThemeContext | null>(null);
+
+function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setTheme] = useState<'light' | 'dark'>('light');
+
+  const toggle = useCallback(() => {
+    setTheme(t => t === 'light' ? 'dark' : 'light');
+  }, []);
+
+  return (
+    <ThemeContext.Provider value={{ theme, toggle }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+function useTheme() {
+  const context = useContext(ThemeContext);
+  if (!context) throw new Error('useTheme must be inside ThemeProvider');
+  return context;
+}
+```
+
+## Zustand (Recommended)
+
+```tsx
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+interface CartStore {
+  items: CartItem[];
+  addItem: (item: CartItem) => void;
+  removeItem: (id: string) => void;
+  clear: () => void;
+  total: () => number;
+}
+
+const useCartStore = create<CartStore>()(
+  persist(
+    (set, get) => ({
+      items: [],
+      addItem: (item) => set((state) => ({
+        items: [...state.items, item]
+      })),
+      removeItem: (id) => set((state) => ({
+        items: state.items.filter(i => i.id !== id)
+      })),
+      clear: () => set({ items: [] }),
+      total: () => get().items.reduce((sum, i) => sum + i.price, 0),
+    }),
+    { name: 'cart-storage' }
+  )
+);
+
+// Component usage
+function Cart() {
+  const items = useCartStore((state) => state.items);
+  const total = useCartStore((state) => state.total());
+  const clear = useCartStore((state) => state.clear);
+
+  return (
+    <div>
+      {items.map(item => <CartItem key={item.id} item={item} />)}
+      <p>Total: ${total}</p>
+      <button onClick={clear}>Clear Cart</button>
+    </div>
+  );
+}
+```
+
+## Redux Toolkit
+
+```tsx
+import { createSlice, configureStore, PayloadAction } from '@reduxjs/toolkit';
+import { Provider, useSelector, useDispatch } from 'react-redux';
+
+const counterSlice = createSlice({
+  name: 'counter',
+  initialState: { value: 0 },
+  reducers: {
+    increment: (state) => { state.value += 1 },
+    decrement: (state) => { state.value -= 1 },
+    incrementBy: (state, action: PayloadAction<number>) => {
+      state.value += action.payload;
+    },
+  },
+});
+
+const store = configureStore({
+  reducer: { counter: counterSlice.reducer },
+});
+
+type RootState = ReturnType<typeof store.getState>;
+type AppDispatch = typeof store.dispatch;
+
+// Typed hooks
+const useAppSelector = useSelector.withTypes<RootState>();
+const useAppDispatch = useDispatch.withTypes<AppDispatch>();
+
+function Counter() {
+  const count = useAppSelector((state) => state.counter.value);
+  const dispatch = useAppDispatch();
+
+  return (
+    <button onClick={() => dispatch(counterSlice.actions.increment())}>
+      {count}
+    </button>
+  );
+}
+```
+
+## TanStack Query (Server State)
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+function UserProfile({ userId }: { userId: string }) {
+  const queryClient = useQueryClient();
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetchUser(userId),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  });
+
+  const mutation = useMutation({
+    mutationFn: updateUser,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['user', userId] });
+    },
+  });
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <Error error={error} />;
+
+  return <UserCard user={data} onUpdate={mutation.mutate} />;
+}
+```
+
+## Quick Reference
+
+| Solution | Best For |
+|----------|----------|
+| useState | Local component state |
+| Context | Theme, auth, simple globals |
+| Zustand | Medium complexity, minimal boilerplate |
+| Redux Toolkit | Complex state, middleware, devtools |
+| TanStack Query | Server state, caching |