@zigrivers/scaffold 3.6.0 → 3.7.0

package/content/knowledge/web-app/web-app-auth-patterns.md

@@ -0,0 +1,256 @@
+---
+name: web-app-auth-patterns
+description: OAuth 2.0 + PKCE flows, cookie security, passkey/WebAuthn, social login, CSRF protection, and auth state management
+topics: [web-app, auth, oauth, pkce, webauthn, passkeys, csrf, security]
+---
+
+Authentication in web applications is a deep domain where implementation mistakes have severe security consequences. The auth surface spans the browser, the server, and third-party identity providers — and each boundary has its own threat model. OAuth 2.0 with PKCE is now the standard for delegated authorization; WebAuthn/passkeys are rapidly becoming the standard for credential-free authentication; and session cookie security attributes are the baseline that every web app must get right. Skipping any of these correctly has historically led to breaches.
+
+## Summary
+
+### OAuth 2.0 + PKCE Flow
+
+OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange) is the correct flow for user-facing web apps. It prevents authorization code interception attacks that plagued the original Authorization Code flow.
+
+**PKCE flow:**
+1. Client generates a cryptographically random `code_verifier` (43–128 chars)
+2. Client derives `code_challenge = BASE64URL(SHA256(code_verifier))`
+3. Client redirects user to authorization server with `code_challenge` and `code_challenge_method=S256`
+4. User authenticates with the identity provider
+5. Authorization server redirects back with `code` in the query string
+6. Client exchanges `code` + `code_verifier` for tokens — the server verifies the challenge hash
+7. Without the original `code_verifier`, a stolen `code` is useless
+
+Never store the `code_verifier` in `localStorage` — use `sessionStorage` or in-memory. The code exchange must happen from your backend (BFF pattern) to avoid exposing `client_secret` in browser code.
+
+### Cookie Security Attributes
+
+Every session cookie and auth cookie must have all four attributes correctly configured:
+
+- **HttpOnly** — prevents JavaScript access, blocking XSS-based token theft
+- **Secure** — restricts transmission to HTTPS, preventing network interception
+- **SameSite=Strict** — cookie not sent on any cross-site request, preventing CSRF
+- **SameSite=Lax** — cookie sent on top-level navigations only; use when cross-site POST is never needed but external links should work
+- **`__Host-` prefix** — enforces Secure + path=/ + no Domain; prevents subdomain hijacking
+
+Use `SameSite=Strict` for session cookies. If your app needs to accept inbound cross-site navigation with the user's session (e.g., linking from a third-party site into an authenticated page), use `Lax`.
+
+### Passkey / WebAuthn Implementation
+
+WebAuthn is the W3C standard for hardware-backed authentication. Passkeys are synced WebAuthn credentials — the user registers once and the credential is available on all their devices via iCloud Keychain or Google Password Manager.
+
+**Why passkeys matter:**
+- No password to phish, leak, or forget
+- Phishing-resistant by design — the credential is bound to the origin URL
+- Biometric authentication without biometric data leaving the device
+- Major platform support as of 2023 (iOS 16+, macOS Ventura+, Android 9+, Windows 11)
+
+**Registration flow:** `navigator.credentials.create()` with a challenge from your server → user authenticates with biometric/PIN → store the public key and credential ID on your server.
+
+**Authentication flow:** `navigator.credentials.get()` with a challenge → WebAuthn assertion → verify signature on server using stored public key.
+
+### Social Login Integration
+
+Social login (Google, GitHub, Apple, etc.) delegates authentication to a trusted identity provider. The implementation pattern:
+
+1. Redirect to provider OAuth endpoint (with PKCE)
+2. Provider redirects back with `code`
+3. Backend exchanges `code` for `id_token` + `access_token`
+4. Verify `id_token` signature against provider's public keys (JWKS endpoint)
+5. Extract user identity (`sub`, `email`, `name`) from verified token
+6. Look up or create user record; issue your app's session
+
+**Account linking:** The same email across different providers should map to the same user account. Store `provider:sub` pairs linked to a single user record to handle this.
+
+## Deep Guidance
+
+### PKCE Implementation
+
+```typescript
+// PKCE utilities — run in browser before redirect
+async function generatePKCE() {
+  // Generate cryptographically random code_verifier
+  const codeVerifier = base64URLEncode(crypto.getRandomValues(new Uint8Array(32)));
+
+  // Derive code_challenge via SHA-256
+  const codeChallenge = base64URLEncode(
+    new Uint8Array(
+      await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier))
+    )
+  );
+
+  return { codeVerifier, codeChallenge };
+}
+
+function base64URLEncode(buffer: Uint8Array): string {
+  return btoa(String.fromCharCode(...buffer))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g, '');
+}
+
+// Initiate login
+async function initiateOAuthLogin(provider: string) {
+  const { codeVerifier, codeChallenge } = await generatePKCE();
+  const state = base64URLEncode(crypto.getRandomValues(new Uint8Array(16)));
+
+  // Store verifier and state — sessionStorage, never localStorage
+  sessionStorage.setItem('pkce_verifier', codeVerifier);
+  sessionStorage.setItem('oauth_state', state);
+
+  const params = new URLSearchParams({
+    client_id: process.env.NEXT_PUBLIC_OAUTH_CLIENT_ID!,
+    redirect_uri: `${window.location.origin}/auth/callback`,
+    response_type: 'code',
+    scope: 'openid email profile',
+    code_challenge: codeChallenge,
+    code_challenge_method: 'S256',
+    state,
+  });
+
+  window.location.href = `${OAUTH_AUTHORIZATION_ENDPOINT}?${params}`;
+}
+
+// Handle callback
+async function handleOAuthCallback(searchParams: URLSearchParams) {
+  const code = searchParams.get('code');
+  const returnedState = searchParams.get('state');
+
+  // Verify state to prevent CSRF
+  const savedState = sessionStorage.getItem('oauth_state');
+  if (!savedState || returnedState !== savedState) {
+    throw new Error('State mismatch — possible CSRF attack');
+  }
+
+  const codeVerifier = sessionStorage.getItem('pkce_verifier');
+  sessionStorage.removeItem('pkce_verifier');
+  sessionStorage.removeItem('oauth_state');
+
+  // Exchange code + verifier for tokens (via your backend)
+  return fetch('/api/auth/callback', {
+    method: 'POST',
+    body: JSON.stringify({ code, codeVerifier }),
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+```
+
+### WebAuthn Passkey Registration
+
+```typescript
+// Register a new passkey
+async function registerPasskey(userId: string, username: string) {
+  // 1. Get challenge from server
+  const { challenge, rpId } = await api.getRegistrationChallenge();
+
+  // 2. Create credential
+  const credential = await navigator.credentials.create({
+    publicKey: {
+      challenge: base64URLDecode(challenge),
+      rp: { name: 'My App', id: rpId },
+      user: {
+        id: new TextEncoder().encode(userId),
+        name: username,
+        displayName: username,
+      },
+      pubKeyCredParams: [
+        { alg: -7, type: 'public-key' },   // ES256 (most supported)
+        { alg: -257, type: 'public-key' }, // RS256 (Windows Hello fallback)
+      ],
+      authenticatorSelection: {
+        residentKey: 'required',          // Required for passkeys
+        userVerification: 'required',     // Biometric/PIN required
+      },
+      attestation: 'none',                // No attestation for consumer apps
+    },
+  }) as PublicKeyCredential;
+
+  // 3. Send response to server for verification and storage
+  const response = credential.response as AuthenticatorAttestationResponse;
+  return api.completeRegistration({
+    credentialId: base64URLEncode(credential.rawId),
+    clientDataJSON: base64URLEncode(response.clientDataJSON),
+    attestationObject: base64URLEncode(response.attestationObject),
+  });
+}
+```
+
+Use the `@simplewebauthn/server` library on the backend for verification. It handles the complex binary parsing, signature verification, and CBOR decoding correctly.
+
+### CSRF Protection
+
+With `SameSite=Strict` cookies, CSRF is largely mitigated for standard same-origin flows. However, for APIs that accept `application/json` content type (which browsers can't trigger via forms or `<img>` tags), the risk is already limited.
+
+For applications that cannot use `SameSite=Strict` (e.g., cross-site embedded auth flows):
+
+```typescript
+// Double-submit cookie pattern
+// Server sets a CSRF token in a readable cookie (not HttpOnly)
+// Client reads the cookie and sends it as a request header
+// Server validates that header matches cookie value
+
+// Server: set CSRF cookie on login
+res.cookie('csrf-token', generateCSRFToken(), {
+  httpOnly: false,  // Must be readable by JavaScript
+  secure: true,
+  sameSite: 'lax',
+});
+
+// Client: inject header on every mutating request
+apiClient.defaults.headers.common['X-CSRF-Token'] = getCookie('csrf-token');
+
+// Server: validate on every mutation
+app.use((req, res, next) => {
+  if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) {
+    if (req.headers['x-csrf-token'] !== req.cookies['csrf-token']) {
+      return res.status(403).json({ error: 'CSRF token mismatch' });
+    }
+  }
+  next();
+});
+```
+
+### Auth State Management in React
+
+```typescript
+// Auth context — single source of truth for authentication state
+interface AuthState {
+  user: User | null;
+  isLoading: boolean;
+  isAuthenticated: boolean;
+}
+
+// Use React Query to manage auth state (benefits from cache, refetch on focus)
+export function useAuth() {
+  const { data: user, isLoading } = useQuery({
+    queryKey: ['auth', 'me'],
+    queryFn: () => api.getCurrentUser(),
+    retry: false,         // Don't retry 401s
+    staleTime: Infinity,  // Only refetch manually or on window focus
+  });
+
+  return {
+    user: user ?? null,
+    isLoading,
+    isAuthenticated: !!user,
+  };
+}
+
+// Route protection
+function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { isAuthenticated, isLoading } = useAuth();
+  const router = useRouter();
+
+  useEffect(() => {
+    if (!isLoading && !isAuthenticated) {
+      router.replace(`/login?returnTo=${encodeURIComponent(router.asPath)}`);
+    }
+  }, [isAuthenticated, isLoading]);
+
+  if (isLoading) return <PageSpinner />;
+  if (!isAuthenticated) return null;
+  return <>{children}</>;
+}
+```
+
+Store the return URL before redirecting to login so users land on the page they were trying to reach after authentication.

package/content/knowledge/web-app/web-app-conventions.md

@@ -0,0 +1,121 @@
+---
+name: web-app-conventions
+description: Component naming, file colocation, state management patterns, custom hook conventions, and CSS methodology selection for web apps
+topics: [web-app, conventions, components, state-management, css, hooks]
+---
+
+Conventions are the difference between a codebase where any engineer can find and modify any file in minutes versus one where only the original author can navigate it confidently. Establish these once, enforce them via linting and code review, and never let individual preferences override them during the project lifecycle.
+
+## Summary
+
+Web app conventions establish consistent patterns for component naming (PascalCase, domain-specific), file colocation (feature-based over type-based), state management (local, server, global, URL tiers), custom hook conventions, and CSS methodology selection. Choose one approach per area and enforce it via linting.
+
+## Deep Guidance
+
+### Component Naming
+
+- **PascalCase for components**: `UserProfile`, `NavigationMenu`, `CheckoutSummary`. This is universal across React, Vue (single-file components), and Svelte.
+- **Descriptive, domain-specific names**: `ProductCard` not `Card`, `AuthModal` not `Modal`, `OrderStatusBadge` not `Badge`. Generic names cause naming conflicts as the codebase grows.
+- **Suffix by type where ambiguous**: `UserList` (renders list), `UserListItem` (renders one item), `UserListContainer` (fetches data and passes to list). Be consistent — never mix `Container`/`Provider`/`Wrapper` conventions across the codebase.
+- **Page components**: `LoginPage`, `DashboardPage`, `CheckoutPage` — suffix with `Page` to distinguish from reusable components.
+
+### File Colocation
+
+Colocate files that change together. The industry has converged on feature-based colocation over type-based grouping:
+
+**Preferred (feature-colocated):**
+```
+features/
+  user-profile/
+    UserProfile.tsx
+    UserProfile.test.tsx
+    UserProfile.stories.tsx   # Storybook stories
+    useUserProfile.ts         # Feature-specific hook
+    user-profile.types.ts     # Feature-specific types
+    index.ts                  # Barrel export
+```
+
+**Avoid (type-segregated):**
+```
+components/UserProfile.tsx
+hooks/useUserProfile.ts
+types/userProfile.ts
+tests/UserProfile.test.tsx
+```
+
+The type-segregated structure requires navigating four directories to understand one feature. It also means deleting a feature requires hunting across the entire directory tree.
+
+**Exception**: Truly shared utilities (`lib/`, `utils/`, `hooks/`) that have no single feature owner belong in a flat shared directory, not inside any feature.
+
+### State Management Patterns
+
+Choose the state tier that matches the problem. Do not reach for Redux when `useState` is sufficient:
+
+- **Local state (`useState`, `useReducer`)**: UI-only state that no sibling or parent needs (open/closed, form draft, hover state). Keep it local.
+- **Server state (React Query, SWR, RTK Query)**: Data fetched from an API. Use a server-state library — it handles caching, deduplication, background refresh, and error states for free. Do not put API data in a global Redux store unless you have a compelling reason.
+- **Global client state (Zustand, Jotai, Redux Toolkit)**: Shared UI state that multiple distant components need (authenticated user, theme, cart items, notification queue). Use sparingly. Every piece of global state is a coupling point.
+- **URL state**: Sort order, filters, pagination, tab selection — anything that should survive a page reload or be shareable via link. Use `useSearchParams` or a URL state library. This is underused; most "global state" is actually URL state in disguise.
+
+### Custom Hook Conventions
+
+- Name all custom hooks with the `use` prefix: `useAuth`, `usePagination`, `useDebounce`.
+- Single responsibility: one hook does one thing. `useUserProfile` fetches and returns user data. It does not also handle form state.
+- Return stable references: memoize returned objects and callbacks to prevent unnecessary re-renders in consumers.
+- Keep hooks pure from the component's perspective: no side effects that the hook consumer cannot control. Accept options objects for configuration rather than hardcoding behavior.
+- Co-locate the hook with the feature that owns it. Move to `lib/hooks/` only when reused across three or more features.
+
+### CSS Methodology Selection
+
+Choose one methodology and enforce it. Mixing methodologies creates chaos:
+
+- **Tailwind CSS**: Best for teams that want to move fast and avoid naming bikeshedding. Excellent with design tokens. Downsides: verbose JSX, requires purging to avoid large CSS bundles, learning curve for custom designs.
+- **CSS Modules**: Best for teams that prefer semantic class names and encapsulation without a utility framework. No runtime, good TypeScript support via `typed-css-modules`.
+- **CSS-in-JS (styled-components, Emotion)**: Best for highly dynamic styles or design systems with programmatic theming. Downsides: runtime cost, hydration complexity with SSR.
+- **Vanilla CSS with custom properties**: Best for simple apps or teams who want zero abstraction. Use a consistent BEM-like naming convention.
+
+### Enforcing Conventions with Tooling
+
+Conventions without enforcement degrade immediately. Configure linting to automate the common cases:
+
+```json
+// ESLint rules for React component conventions
+{
+  "rules": {
+    "react/jsx-pascal-case": "error",          // Enforce PascalCase for JSX components
+    "import/no-default-export": "warn",         // Prefer named exports (easier to find with search)
+    "@typescript-eslint/naming-convention": [
+      "error",
+      { "selector": "function", "format": ["camelCase", "PascalCase"] },
+      { "selector": "variable", "format": ["camelCase", "UPPER_CASE", "PascalCase"] }
+    ]
+  }
+}
+```
+
+Add a Storybook or component documentation requirement: every shared component must have a story before it can be merged. This enforces composability — if you cannot write a story for it in isolation, the component is too coupled.
+
+### State Management Decision Flowchart
+
+When choosing state location, answer in order:
+
+1. Is this state only used by one component? → `useState`
+2. Is this state fetched from a server? → React Query / SWR
+3. Can this state live in the URL? → `useSearchParams` / URL state
+4. Is this state shared across multiple distant routes? → Zustand / Jotai / Redux Toolkit
+5. Is this state needed server-side during SSR? → Context with SSR-safe initialization
+
+Resist the urge to centralize all state globally. Distributed state is easier to delete when features are removed and easier to reason about during debugging.
+
+### Hook Testing Conventions
+
+Test hooks in isolation using `renderHook` from React Testing Library. This keeps hook logic testable without mounting a component:
+
+```typescript
+// Good: test hook behavior directly
+const { result } = renderHook(() => useDebounce("search", 300));
+expect(result.current).toBe("");
+act(() => { jest.advanceTimersByTime(300); });
+expect(result.current).toBe("search");
+```
+
+Never test a hook only via its parent component — that couples the hook test to the component's rendering and makes failures harder to diagnose.

package/content/knowledge/web-app/web-app-data-patterns.md

@@ -0,0 +1,218 @@
+---
+name: web-app-data-patterns
+description: Client-side caching, optimistic updates, real-time sync, pagination strategies, form state management, and file upload patterns
+topics: [web-app, data-fetching, caching, react-query, swr, pagination, forms, file-upload]
+---
+
+Data management in web applications spans from simple fetch-and-display to complex real-time collaborative state. The wrong patterns here produce stale UIs, conflicting updates, degraded performance under load, and frustrated users. The right patterns make applications feel instantaneous even over slow networks — by understanding the difference between server state, client state, and ephemeral UI state, and applying the appropriate tool to each.
+
+## Summary
+
+### Server State vs Client State
+
+The most important conceptual distinction in modern web data management:
+
+- **Server state** — data owned by the server, shared across clients, and potentially stale as soon as it's fetched: user profiles, product listings, feed items. Use a data-fetching library (React Query, SWR) to manage this.
+- **Client state** — data owned by the current user's session, not persisted to the server: currently selected tab, sidebar open/closed, in-progress form data. Use React local state or Zustand/Jotai/Redux.
+
+Mixing these causes anti-patterns: putting server data in Redux, or making API calls from useEffect without caching. Libraries like React Query exist precisely because server state needs cache management, background refetching, deduplication, and stale-while-revalidate semantics that generic state managers don't provide.
+
+### SWR vs React Query
+
+Both implement stale-while-revalidate caching for server state:
+
+| Concern | SWR | React Query (TanStack Query) |
+|---|---|---|
+| Bundle size | ~6 KB | ~13 KB |
+| Mutations | Manual invalidation | Built-in `useMutation` + auto-invalidation |
+| Infinite scroll | `useSWRInfinite` | `useInfiniteQuery` |
+| Optimistic updates | Manual | First-class via `onMutate` + rollback |
+| DevTools | None built-in | Excellent DevTools panel |
+| Best for | Read-heavy apps, minimal mutations | Apps with complex mutation flows |
+
+**Rule:** Use React Query for most production applications. Use SWR for read-heavy dashboards where its simplicity is a net benefit.
+
+### Optimistic Updates
+
+Update the UI before the server confirms the mutation. If the server rejects, roll back.
+
+Optimistic updates are appropriate when: the mutation has a very high success rate, the latency is noticeable, and the rollback experience is not confusing. They are not appropriate when: the server-side result is unpredictable (e.g., a bid on an auction where you may lose).
+
+### Pagination Strategies
+
+**Cursor-based pagination** (preferred):
+- Each page returns a `nextCursor` opaque token; the next request passes `?cursor=<token>`
+- Stable across concurrent inserts/deletes — no items skipped or duplicated
+- Required for infinite scroll (offset pagination breaks on live data)
+- Cannot jump to arbitrary page numbers
+
+**Offset-based pagination**:
+- `?page=3&limit=20` or `?offset=40&limit=20`
+- Supports "jump to page N" UI
+- Items shift when rows are inserted/deleted — users see duplicates or skipped items on live data
+- Appropriate for admin tables with infrequent writes and explicit page navigation
+
+### Real-Time Data Sync
+
+Three patterns in increasing complexity:
+1. **Polling** — simplest, least efficient: re-fetch every N seconds. Acceptable for dashboards that update every few minutes.
+2. **Server-Sent Events (SSE)** — server pushes updates to client over a single long-lived HTTP connection. One-directional. Excellent for notifications, activity feeds, live counters. No WebSocket negotiation overhead.
+3. **WebSocket** — bidirectional full-duplex. Required for chat, collaborative editing, live games. Higher complexity: connection management, reconnection, presence.
+
+## Deep Guidance
+
+### React Query Patterns
+
+```typescript
+// 1. Standard query with stale time
+const { data: posts, isLoading, error } = useQuery({
+  queryKey: ['posts', { authorId, page }],
+  queryFn: () => fetchPosts({ authorId, page }),
+  staleTime: 5 * 60 * 1000,  // Data considered fresh for 5 minutes
+  gcTime: 10 * 60 * 1000,    // Keep in cache for 10 minutes after unmount
+});
+
+// 2. Optimistic mutation with rollback
+const queryClient = useQueryClient();
+
+const likeMutation = useMutation({
+  mutationFn: (postId: string) => api.likePost(postId),
+
+  onMutate: async (postId) => {
+    // Cancel any in-flight refetches that would overwrite optimistic update
+    await queryClient.cancelQueries({ queryKey: ['posts'] });
+
+    // Snapshot the previous value
+    const previousPosts = queryClient.getQueryData(['posts']);
+
+    // Optimistically update
+    queryClient.setQueryData(['posts'], (old: Post[]) =>
+      old.map(p => p.id === postId ? { ...p, likeCount: p.likeCount + 1, likedByMe: true } : p)
+    );
+
+    // Return context for rollback
+    return { previousPosts };
+  },
+
+  onError: (error, postId, context) => {
+    // Roll back to snapshot on failure
+    queryClient.setQueryData(['posts'], context?.previousPosts);
+  },
+
+  onSettled: () => {
+    // Always refetch to sync with server truth
+    queryClient.invalidateQueries({ queryKey: ['posts'] });
+  },
+});
+
+// 3. Infinite scroll
+const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
+  queryKey: ['feed'],
+  queryFn: ({ pageParam }) => fetchFeed({ cursor: pageParam }),
+  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+  initialPageParam: undefined as string | undefined,
+});
+```
+
+### File Upload Pattern
+
+Uploads require a different flow from standard JSON mutations: multipart form data, progress tracking, and (for large files) direct-to-storage upload via presigned URLs.
+
+```typescript
+// PATTERN: Presigned URL upload (bypasses app server, goes direct to S3/GCS)
+async function uploadFile(file: File, onProgress: (pct: number) => void) {
+  // Step 1: Get presigned URL from app server
+  const { uploadUrl, fileKey } = await api.getUploadUrl({
+    filename: file.name,
+    contentType: file.type,
+    size: file.size,
+  });
+
+  // Step 2: Upload directly to storage (no app server in the critical path)
+  await new Promise<void>((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open('PUT', uploadUrl);
+    xhr.setRequestHeader('Content-Type', file.type);
+
+    xhr.upload.onprogress = (event) => {
+      if (event.lengthComputable) {
+        onProgress(Math.round((event.loaded / event.total) * 100));
+      }
+    };
+
+    xhr.onload = () => xhr.status === 200 ? resolve() : reject(new Error(`Upload failed: ${xhr.status}`));
+    xhr.onerror = () => reject(new Error('Network error during upload'));
+    xhr.send(file);
+  });
+
+  // Step 3: Notify app server that upload is complete
+  return api.confirmUpload({ fileKey });
+}
+```
+
+Presigned URL uploads: never proxy large files through your app server. A 100 MB upload through an app server occupies a Node.js worker for the entire transfer duration.
+
+### Form State Management
+
+For most forms: `react-hook-form` + Zod schema validation. This pattern avoids controlled component re-renders (critical for large forms), provides schema-driven validation, and integrates cleanly with TypeScript.
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+
+const profileSchema = z.object({
+  displayName: z.string().min(2).max(50),
+  email: z.string().email(),
+  bio: z.string().max(500).optional(),
+});
+
+type ProfileForm = z.infer<typeof profileSchema>;
+
+function ProfileEditor() {
+  const { register, handleSubmit, formState: { errors, isDirty, isSubmitting } } = useForm<ProfileForm>({
+    resolver: zodResolver(profileSchema),
+    defaultValues: { displayName: user.displayName, email: user.email },
+  });
+
+  const onSubmit = async (data: ProfileForm) => {
+    await updateProfile(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('displayName')} />
+      {errors.displayName && <span>{errors.displayName.message}</span>}
+      <button type="submit" disabled={!isDirty || isSubmitting}>Save</button>
+    </form>
+  );
+}
+```
+
+Reserve heavier solutions (Formik, final-form) only for highly dynamic form generation requirements. For most product forms, react-hook-form is sufficient and faster.
+
+### Cursor Pagination Implementation
+
+```typescript
+// Server-side cursor pagination (PostgreSQL + Prisma)
+async function getPaginatedPosts(cursor?: string, limit = 20) {
+  const posts = await prisma.post.findMany({
+    take: limit + 1,  // Fetch one extra to determine if there's a next page
+    ...(cursor && {
+      cursor: { id: cursor },
+      skip: 1,  // Skip the cursor item itself
+    }),
+    orderBy: { createdAt: 'desc' },
+  });
+
+  const hasNextPage = posts.length > limit;
+  const items = hasNextPage ? posts.slice(0, -1) : posts;
+
+  return {
+    items,
+    nextCursor: hasNextPage ? items[items.length - 1].id : null,
+  };
+}
+```
+
+Always fetch `limit + 1` to check for next page existence without an extra COUNT query.