@zigrivers/scaffold 3.5.3 → 3.7.0

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

@@ -0,0 +1,221 @@
+---
+name: web-app-observability
+description: Real User Monitoring, Core Web Vitals tracking, error tracking with Sentry, CDN analytics, custom performance marks, and performance regression alerting
+topics: [web-app, observability, rum, core-web-vitals, sentry, performance, monitoring]
+---
+
+You cannot improve what you cannot measure. Frontend observability is often treated as an afterthought — added after users start complaining — but by then you have no baseline to regress against and no historical data to understand when performance degraded or errors started. Real User Monitoring (RUM) captures the experience of your actual users on their actual devices and networks, which lab-based tests like Lighthouse cannot replicate. Core Web Vitals are Google's standardized metrics for page experience and directly influence search ranking.
+
+## Summary
+
+### Real User Monitoring (RUM)
+
+RUM collects performance and behavioral data from real user sessions in production. Unlike synthetic monitoring (scheduled tests from a data center), RUM reflects the diversity of real-world conditions: slow Android devices, congested mobile networks, aggressive ad blockers, and geographically distant users.
+
+**Key RUM metrics:**
+
+- **Core Web Vitals** — Google's page experience signals (see below)
+- **Time to First Byte (TTFB)** — server response latency
+- **First Contentful Paint (FCP)** — when the first content is painted
+- **Time to Interactive (TTI)** — when the page is reliably interactive
+- **Custom marks** — application-specific milestones (e.g., "dashboard data loaded")
+- **Error rate** — JavaScript exceptions per session
+- **Rage clicks** — repeated clicks on non-interactive elements (UX frustration signal)
+- **Dead clicks** — clicks on elements that produce no response
+
+**RUM tools:** Vercel Analytics, Datadog RUM, New Relic Browser, Sentry Performance, web-vitals library (self-hosted reporting).
+
+### Core Web Vitals
+
+Google's three Core Web Vitals measure loading, interactivity, and visual stability:
+
+| Metric | Measures | Good | Needs Improvement | Poor |
+|---|---|---|---|---|
+| **LCP** (Largest Contentful Paint) | Load performance | ≤ 2.5s | 2.5–4s | > 4s |
+| **INP** (Interaction to Next Paint) | Responsiveness | ≤ 200ms | 200–500ms | > 500ms |
+| **CLS** (Cumulative Layout Shift) | Visual stability | ≤ 0.1 | 0.1–0.25 | > 0.25 |
+
+**Common LCP causes and fixes:**
+- Unoptimized hero images → use `srcset`, WebP/AVIF, CDN, `loading="eager"`, `fetchpriority="high"`
+- Render-blocking CSS/fonts → inline critical CSS, use `font-display: swap`
+- Slow TTFB → edge caching, CDN, server-side optimization
+
+**Common CLS causes and fixes:**
+- Images without explicit `width`/`height` attributes → always set dimensions
+- Late-loading ads or embeds → reserve space with aspect-ratio boxes
+- Custom fonts causing text reflow → use `font-display: optional` or `size-adjust`
+- Dynamic content injected above viewport content → append below, not prepend above
+
+**INP (replaced FID in 2024):** Measures the responsiveness of all user interactions, not just the first. Long JavaScript tasks (>50ms) block the main thread and inflate INP. Use `scheduler.postTask()`, web workers, and code splitting to break up long tasks.
+
+### Error Tracking with Sentry
+
+Sentry captures JavaScript exceptions, stack traces, user context, and breadcrumbs (the sequence of events leading to the error). Configure it to filter noise and surface actionable errors.
+
+**Critical Sentry configuration:**
+- Source maps for readable stack traces (never ship source maps publicly — upload to Sentry only)
+- User context (attach user ID, plan tier — never PII like email without consent)
+- Release tracking to correlate error spikes with deployments
+- Sampling rate: 100% for errors, 10–20% for performance transactions in high-traffic apps
+
+### Performance Regression Alerting
+
+The goal is to catch regressions before they reach users or before they compound. Alert on:
+- LCP p75 (75th percentile) increases by more than 300ms from the rolling 7-day average
+- Error rate increases by more than 0.5% from the rolling 24-hour baseline
+- Any new error type appearing in production for the first time
+
+## Deep Guidance
+
+### Web Vitals Collection
+
+```typescript
+// web-vitals library — collect and report Core Web Vitals
+import { onLCP, onINP, onCLS, onFCP, onTTFB } from 'web-vitals';
+
+function sendToAnalytics(metric: any) {
+  // Batch metrics to avoid sending too many beacons
+  const body = JSON.stringify({
+    name: metric.name,
+    value: metric.value,
+    rating: metric.rating,    // 'good', 'needs-improvement', 'poor'
+    id: metric.id,
+    navigationType: metric.navigationType,
+    url: window.location.pathname,
+    // Attach context for segmentation
+    connectionType: (navigator as any).connection?.effectiveType,
+    deviceMemory: (navigator as any).deviceMemory,
+  });
+
+  // sendBeacon is non-blocking and survives page unload
+  if (navigator.sendBeacon) {
+    navigator.sendBeacon('/api/vitals', body);
+  } else {
+    fetch('/api/vitals', { method: 'POST', body, keepalive: true });
+  }
+}
+
+// Register all Core Web Vitals + FCP + TTFB
+onLCP(sendToAnalytics);
+onINP(sendToAnalytics);
+onCLS(sendToAnalytics);
+onFCP(sendToAnalytics);
+onTTFB(sendToAnalytics);
+```
+
+Always use `navigator.sendBeacon` for analytics reporting — it queues the request to be sent after the page unloads without blocking navigation.
+
+### Custom Performance Marks
+
+Use the User Timing API to measure application-specific milestones that browser APIs cannot capture:
+
+```typescript
+// Mark application-level performance milestones
+class PerformanceTracker {
+  private marks: Map<string, number> = new Map();
+
+  mark(name: string): void {
+    performance.mark(name);
+    this.marks.set(name, performance.now());
+  }
+
+  measure(name: string, startMark: string, endMark?: string): number {
+    const end = endMark || name + '-end';
+    if (!endMark) this.mark(end);
+
+    const measure = performance.measure(name, startMark, end);
+    const duration = measure.duration;
+
+    // Report to RUM
+    this.report({ name, duration });
+    return duration;
+  }
+
+  private report(metric: { name: string; duration: number }): void {
+    navigator.sendBeacon?.('/api/perf', JSON.stringify(metric));
+  }
+}
+
+const perf = new PerformanceTracker();
+
+// Usage in application code
+async function loadDashboard() {
+  perf.mark('dashboard-fetch-start');
+  const data = await fetchDashboardData();
+  perf.mark('dashboard-fetch-end');
+
+  perf.measure('dashboard-fetch', 'dashboard-fetch-start', 'dashboard-fetch-end');
+
+  perf.mark('dashboard-render-start');
+  renderDashboard(data);
+  perf.mark('dashboard-render-end');
+
+  perf.measure('dashboard-render', 'dashboard-render-start', 'dashboard-render-end');
+}
+```
+
+These custom marks appear in Chrome DevTools Performance panel and can be reported to your RUM backend for tracking.
+
+### Sentry Setup for Next.js
+
+```typescript
+// sentry.client.config.ts
+import * as Sentry from '@sentry/nextjs';
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  environment: process.env.NEXT_PUBLIC_ENV,
+
+  // Performance monitoring sample rate — adjust based on traffic volume
+  tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0,
+
+  // Replay for error sessions only (privacy-conscious default)
+  replaysOnErrorSampleRate: 1.0,
+  replaysSessionSampleRate: 0.0,
+
+  // Filter noise — don't track network errors from ad blockers
+  ignoreErrors: [
+    'ResizeObserver loop limit exceeded',
+    'Non-Error promise rejection captured',
+    /Loading chunk \d+ failed/,
+  ],
+
+  beforeSend(event, hint) {
+    // Strip PII from error context
+    if (event.user) {
+      delete event.user.email;
+      delete event.user.username;
+    }
+    return event;
+  },
+
+  integrations: [
+    Sentry.replayIntegration({
+      maskAllText: true,     // Privacy: mask all text in replays
+      blockAllMedia: true,   // Privacy: block media in replays
+    }),
+  ],
+});
+```
+
+### CDN Analytics and Cache Hit Rate
+
+Monitor CDN cache performance as a leading indicator for LCP and TTFB:
+
+- **Cache hit rate** — percentage of requests served from CDN cache vs origin. Target >90% for static assets, >70% for edge-cached HTML.
+- **Origin shield hit rate** — for CDN tiers that include an origin shield, a low rate indicates cold cache or poor cache-control headers.
+- **Edge latency by region** — identify geographic regions where users have poor performance; expand CDN PoP coverage or investigate origin latency.
+
+Key cache-control headers:
+```
+# Immutable static assets (hashed filenames)
+Cache-Control: public, max-age=31536000, immutable
+
+# HTML pages — revalidate frequently but serve stale while revalidating
+Cache-Control: public, max-age=0, s-maxage=86400, stale-while-revalidate=3600
+
+# API responses — no public cache, short browser cache
+Cache-Control: private, max-age=30
+```
+
+Set `Surrogate-Key` (Fastly) or `Cache-Tag` (Cloudflare) headers on HTML responses to enable targeted cache purging when content changes.

package/content/knowledge/web-app/web-app-project-structure.md

@@ -0,0 +1,160 @@
+---
+name: web-app-project-structure
+description: Directory layout conventions, route organization, shared vs feature modules, barrel exports, and config file placement for web apps
+topics: [web-app, project-structure, architecture, routing, modules]
+---
+
+A well-structured web app project is navigable by any developer without a tour. The directory layout should communicate the architecture at a glance: where pages live, where shared code lives, where API logic lives, and where configuration lives. A poor structure forces every developer to ask "where does this go?" on every new file they create.
+
+## Summary
+
+Web app project structure separates `app/` (routes and layouts), `features/` (domain-owned modules), `components/` (shared UI), `hooks/` (shared hooks), and `lib/` (framework-agnostic utilities). Routes mirror URL structure with thin page files. Feature modules own their components, hooks, and types; shared modules have zero imports from feature modules.
+
+## Deep Guidance
+
+### Standard Directory Layout
+
+For a Next.js or similar SSR framework, the canonical structure is:
+
+```
+src/
+  app/              # App Router pages and layouts (Next.js 13+)
+  pages/            # Pages Router (Next.js legacy; or Remix/Vite routes)
+  components/       # Shared, reusable UI components
+  features/         # Feature modules (colocated components + hooks + logic)
+  hooks/            # Shared custom hooks used across features
+  lib/              # Framework-agnostic utilities and service clients
+  api/              # API route handlers (serverless functions)
+  types/            # Shared TypeScript types and interfaces
+  styles/           # Global CSS, design tokens, theme config
+public/             # Static assets served at root (images, fonts, robots.txt)
+```
+
+For a Vite/React SPA, drop `app/` and `api/` and substitute:
+
+```
+src/
+  routes/           # Route components and nested layouts
+  pages/            # Page-level components (one per route)
+```
+
+### Route Organization
+
+Routes should mirror the URL structure. Avoid flat route files that make the hierarchy ambiguous:
+
+- `/dashboard` → `app/dashboard/page.tsx`
+- `/dashboard/settings` → `app/dashboard/settings/page.tsx`
+- `/users/[id]` → `app/users/[id]/page.tsx`
+
+Keep route files thin — they orchestrate data loading and pass props to feature components. Business logic belongs in `features/`, not in the page file.
+
+**Layouts**: Use layout files (`layout.tsx`) to share navigation, auth checks, and providers across route groups. Do not repeat these in every page file.
+
+### Shared vs Feature Modules
+
+The critical distinction is "who owns this code":
+
+- **Feature module** (`features/checkout/`): Owned by one product domain. Contains everything the checkout feature needs — components, hooks, API calls, types. Other features do not import from it directly; they use shared interfaces.
+- **Shared module** (`components/`, `hooks/`, `lib/`): Owned by no single feature. Used by two or more features. Has no knowledge of any specific feature's business logic.
+
+The rule: shared modules must have zero imports from feature modules. Feature modules may import from shared modules. This prevents circular dependencies and keeps shared code reusable.
+
+### Barrel Exports
+
+Use `index.ts` barrel files at the feature and component directory level to create clean import paths:
+
+```typescript
+// features/user-profile/index.ts
+export { UserProfile } from "./UserProfile";
+export { useUserProfile } from "./useUserProfile";
+export type { UserProfileData } from "./user-profile.types";
+```
+
+Consumers import from `features/user-profile`, not from deep internal paths:
+```typescript
+// Good
+import { UserProfile } from "@/features/user-profile";
+
+// Bad — leaks internal structure
+import { UserProfile } from "@/features/user-profile/components/UserProfile";
+```
+
+Configure TypeScript path aliases (`@/`) to avoid relative path ladders (`../../../../../../`).
+
+### Config Files
+
+Config files belong at the repo root, not inside `src/`. Standard placement:
+
+- `next.config.ts` / `vite.config.ts` — build and bundler config
+- `tsconfig.json` — TypeScript compiler config
+- `eslint.config.js` — linting rules
+- `.env.example` — documented environment variables (committed); `.env.local` — actual values (gitignored)
+- `tailwind.config.ts` — if using Tailwind
+- `vitest.config.ts` / `jest.config.ts` — test runner config
+
+### Feature Module Template
+
+Every feature module follows the same internal structure. Establish this template in `CONTRIBUTING.md`:
+
+```
+features/
+  <feature-name>/
+    index.ts                  # Barrel export — public API of the feature
+    <FeatureName>.tsx          # Top-level feature component
+    <FeatureName>.test.tsx     # Component tests
+    <FeatureName>.stories.tsx  # Storybook stories (if applicable)
+    use<FeatureName>.ts        # Primary data hook
+    use<FeatureName>.test.ts   # Hook tests
+    <feature-name>.types.ts    # TypeScript types for this feature
+    <feature-name>.api.ts      # API calls made by this feature (if applicable)
+    components/                # Sub-components used only within this feature
+      <SubComponent>.tsx
+```
+
+Enforce "no cross-feature imports" with ESLint:
+
+```javascript
+// eslint-plugin-import rule to prevent cross-feature imports
+"import/no-restricted-paths": [
+  "error",
+  {
+    "zones": [{
+      "target": "./src/features",
+      "from": "./src/features",
+      "except": ["./src/features/index.ts"] // Only barrel is importable
+    }]
+  }
+]
+```
+
+### Environment Variable Management
+
+Never hardcode environment-specific values. Use `.env` files and document every variable:
+
+```bash
+# .env.example — committed to the repo
+# Never commit .env, .env.local, or .env.production
+
+# API base URL
+NEXT_PUBLIC_API_URL=https://api.example.com
+
+# Auth provider
+NEXT_PUBLIC_AUTH_DOMAIN=your-domain.auth0.com
+AUTH_SECRET=          # Server-only; never expose to client (no NEXT_PUBLIC_ prefix)
+
+# Feature flags
+NEXT_PUBLIC_FEATURE_NEW_CHECKOUT=false
+```
+
+Validate environment variables at startup using a schema (Zod is ideal). Fail fast with a clear error message if required variables are missing or malformed. Never let the app silently run with bad configuration.
+
+### Avoiding the "Utils Dumping Ground"
+
+A `utils/` directory with no sub-organization becomes a junk drawer within weeks. Apply the same discipline to utilities:
+
+- Group by domain: `lib/date.ts`, `lib/currency.ts`, `lib/validation.ts`
+- If a utility grows beyond ~100 lines, give it its own directory with an `index.ts`
+- Delete utilities that are no longer used — dead code in `lib/` is worse than no code
+- Never put business logic in `lib/`. Business logic belongs in features or hooks.
+
+The test for whether something belongs in `lib/`: "Could I copy this to a different web app project without modification?" If yes, it belongs in `lib/`. If it has knowledge of this app's domain, it belongs in `features/` or `hooks/`.

package/content/knowledge/web-app/web-app-rendering-strategies.md

@@ -0,0 +1,133 @@
+---
+name: web-app-rendering-strategies
+description: SSR TTFB and SEO benefits, SSG for content sites, ISR, streaming SSR, React Server Components, and progressive hydration patterns
+topics: [web-app, rendering, ssr, ssg, isr, streaming, react-server-components, hydration]
+---
+
+Rendering strategy is the foundational technical decision in a web app — it determines server infrastructure requirements, SEO characteristics, performance profile, and the developer model for data fetching. Understanding the precise mechanics of each strategy (not just their marketing descriptions) is essential for making and defending the right choice for a given project.
+
+## Summary
+
+Rendering strategy determines server infrastructure, SEO characteristics, and performance profile. SSR provides SEO and fast LCP but adds server cost and TTFB. SSG gives sub-100ms TTFB from CDN but data is stale until rebuild. ISR extends SSG with per-route revalidation. Streaming SSR and React Server Components reduce bundle size and improve perceived performance by streaming content progressively. Most real-world apps need a hybrid approach.
+
+## Deep Guidance
+
+### SSR: Benefits and Real Costs
+
+Server-Side Rendering generates HTML on the server for each request. The benefits are real but often overstated:
+
+**Benefits:**
+- **SEO**: Search engines receive pre-rendered HTML immediately. Critical for pages that must be indexed.
+- **LCP on slow connections**: User sees content before JavaScript downloads and executes. Significant for mobile users on 3G.
+- **Social sharing**: OG tags, Twitter Cards, and link previews work because the HTML is complete on the server response.
+- **Auth-gated content**: Server can read session cookies and render personalized HTML without a client-side auth check causing layout flash.
+
+**Real costs (often understated):**
+- **TTFB**: Server must complete data fetching before sending the first byte. A slow database query delays the entire page. CSR serves a shell HTML in ~50 ms (CDN); SSR may take 200–500 ms for a database-backed page.
+- **Server load**: Every page view consumes server CPU. At scale, this is a significant infrastructure cost vs. CDN-served static pages.
+- **Caching complexity**: SSR responses may be personalized and cannot be cached at the CDN without careful `Vary` headers and cache key design.
+- **Cold starts**: In serverless environments, SSR functions have cold start latency that static serving does not.
+
+### SSG: When It Is the Right Tool
+
+Static Site Generation pre-builds every page at deploy time. It is the correct choice for:
+
+- Content that changes at most a few times per day (blog, docs, marketing pages)
+- Pages with no user-specific personalization in the HTML
+- Maximum performance requirements (sub-100 ms TTFB from CDN)
+
+SSG limitations are real and must be understood:
+- **Build time**: Every page generates during CI. At 10,000 pages with 100 ms per page: 17 minutes of build time. Use incremental builds and build caching to mitigate.
+- **Data freshness**: Pages are stale from the moment they are built. A product price change requires a rebuild to appear. Use on-demand revalidation (ISR) for this case.
+
+### ISR: Incremental Static Regeneration
+
+ISR extends SSG with per-route revalidation intervals. A page marked `revalidate: 60` is served from the CDN static cache, but regenerated in the background every 60 seconds when a visitor triggers it:
+
+- Stale-while-revalidate semantics: the first visitor after 60 seconds gets the old page; the next visitor gets the fresh page
+- The regeneration happens server-side, not in response to a specific user — it is eventual consistency, not real-time
+- On-demand ISR (via `res.revalidate(path)`) allows webhook-triggered immediate rebuilds — product price change → webhook → rebuild that product page within seconds
+
+ISR is appropriate when "a few seconds to a minute stale" is acceptable and you want CDN-level performance without a full rebuild per data change.
+
+### Streaming SSR
+
+React 18 and Next.js App Router support streaming HTML responses using `renderToPipeableStream` and `<Suspense>`:
+
+1. Server sends the page shell (header, navigation, above-fold layout) immediately — TTFB is fast
+2. Data-dependent sections are wrapped in `<Suspense>` with a fallback (skeleton)
+3. As each suspended section's data resolves, React streams its HTML directly into the response
+4. Browser progressively renders content as it arrives
+
+This transforms LCP dramatically: users see layout and fast content immediately; slow data sections (product reviews, recommendations) arrive asynchronously without blocking the critical paint.
+
+**Implementation pattern:**
+```tsx
+// app/product/[id]/page.tsx
+export default function ProductPage({ params }) {
+  return (
+    <main>
+      <ProductHero id={params.id} />        {/* Fast: renders immediately */}
+      <Suspense fallback={<ReviewSkeleton />}>
+        <ProductReviews id={params.id} />   {/* Slow: streams in when ready */}
+      </Suspense>
+      <Suspense fallback={<RecommendationSkeleton />}>
+        <Recommendations id={params.id} />  {/* Slow: streams in when ready */}
+      </Suspense>
+    </main>
+  );
+}
+```
+
+### React Server Components
+
+RSC is a model where components run exclusively on the server and send a serialized component description to the client — not HTML, not JavaScript:
+
+- **Server Components**: Zero client-side JS. Read databases, file systems, environment variables directly. Not interactive.
+- **Client Components**: Marked with `"use client"`. Run on both server (for initial HTML) and client (for interactivity). Receive server component output as props.
+- **Benefit**: A product page with 40 KB of component code can ship 5 KB to the browser if most components are server-only.
+
+The mental model shift: the client-server boundary is now drawn at the component level, not the page level. This is the most significant change in React architecture since hooks.
+
+### Choosing a Strategy: Decision Framework
+
+Answer these questions in order:
+
+1. **Does this page need SEO?** If no → CSR. If yes → continue.
+2. **Is the content personalized per user?** If no → SSG or ISR. If yes → SSR or RSC.
+3. **How stale can the data be?** Minutes acceptable → ISR. Real-time required → SSR.
+4. **How much traffic?** Millions of pageviews/day → CDN-served (SSG/ISR) wins on cost. Low traffic → SSR is fine.
+
+Most real-world apps need a hybrid: SSG for marketing, ISR for product listings, SSR for checkout, CSR for the user dashboard.
+
+### Progressive Hydration Pattern
+
+In Next.js without RSC, implement progressive hydration by deferring non-critical component hydration:
+
+```typescript
+import dynamic from "next/dynamic";
+
+// Defer hydration until the component is in the viewport
+const HeavyWidget = dynamic(() => import("./HeavyWidget"), {
+  ssr: false,  // Not needed for SEO
+  loading: () => <WidgetSkeleton />,
+});
+
+// Or: load but don't hydrate until user interacts
+const ChatWidget = dynamic(() => import("./ChatWidget"), {
+  ssr: false,
+});
+```
+
+Each dynamically imported component creates a separate JS chunk. Only load what is needed for the current page — analyze your bundle with `@next/bundle-analyzer` or `rollup-plugin-visualizer`.
+
+### Hydration Mismatch Debugging
+
+The most common SSR debugging problem is hydration mismatches — the server renders different HTML than the client expects. Common causes:
+
+- Browser-only APIs (`window`, `document`, `navigator`) accessed during server render
+- Date formatting that differs between server timezone and client timezone
+- Random values (`Math.random()`, `uuid()`) that differ between server and client renders
+- Conditional rendering based on browser features (`typeof window !== 'undefined'`)
+
+Fix by moving browser-only code into `useEffect` (runs only on client) or by using `dynamic(() => import(...), { ssr: false })` for components that inherently require the browser. Never suppress hydration warnings with `suppressHydrationWarning` except for timestamps and user-agent-dependent content where mismatch is expected and benign.

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

@@ -0,0 +1,112 @@
+---
+name: web-app-requirements
+description: SSR/SPA decision criteria, Core Web Vitals budgets, responsive breakpoints, browser support matrix, PWA considerations, and SEO requirements
+topics: [web-app, requirements, performance, pwa, seo, accessibility]
+---
+
+Defining web app requirements before writing a line of code prevents the most expensive rework in the project lifecycle. Rendering strategy, performance budgets, and browser support targets affect every architectural decision downstream. Locking these down early — with explicit tradeoff acknowledgment — removes ambiguity and gives the team a shared definition of "done."
+
+## Summary
+
+Web app requirements establish rendering strategy (SSR for SEO, SPA for authenticated apps, hybrid for content-heavy sites), Core Web Vitals budgets (LCP < 2.5s, INP < 200ms, CLS < 0.1), responsive breakpoints from a shared token set, browser support matrix encoded via Browserslist, PWA scope decisions, and SEO requirements. Lock these down before sprint one.
+
+## Deep Guidance
+
+### SSR vs SPA Decision Criteria
+
+Rendering strategy is the first architectural decision. The wrong choice costs weeks of retrofit:
+
+- **Choose SSR (Next.js, Remix, SvelteKit, Nuxt)** when: SEO is critical (content sites, e-commerce, marketing), first-paint performance matters on slow connections, users are on low-powered devices, or content changes frequently and needs crawlability.
+- **Choose SPA (React, Vue, Angular with CSR)** when: the app is behind authentication (no SEO need), interactions are highly dynamic (dashboards, tools, editors), and the user base is on capable hardware with fast connections.
+- **Choose hybrid (SSG + client hydration)** when: most pages are static but some routes need real-time data. This is the default for most content-heavy sites — build pages at deploy time, hydrate interactive islands on the client.
+
+Never choose SSR just because it is the current trend. Server rendering adds operational complexity (cold starts, caching headers, streaming), infrastructure cost, and harder debugging. Quantify the SEO and performance benefit before committing.
+
+### Core Web Vitals Budgets
+
+Establish explicit targets before sprint one. These directly affect Google ranking and user conversion:
+
+- **LCP (Largest Contentful Paint)**: Target under 2.5 seconds on a 3G mobile connection. Optimize with image preloads, font subsetting, and eliminating render-blocking resources.
+- **FID / INP (Interaction to Next Paint)**: Target under 200 ms. Long JavaScript tasks block the main thread. Break up tasks, defer non-critical code, use Web Workers for heavy computation.
+- **CLS (Cumulative Layout Shift)**: Target under 0.1. Reserve space for images and embeds. Avoid inserting content above the fold after initial paint.
+
+Set budget alerts in Lighthouse CI on every PR. Treat regressions as build failures.
+
+### Responsive Breakpoints
+
+Establish a breakpoint set and document it in the design system. A common mobile-first set:
+
+- **Mobile**: base styles (320–767 px)
+- **Tablet**: 768 px and up
+- **Desktop**: 1024 px and up
+- **Wide**: 1280 px and up (optional; cap content width at 1440 px to prevent excessive line length)
+
+Do not invent per-component breakpoints. All breakpoints must come from a shared token set in CSS custom properties or a design token file.
+
+### Browser Support Matrix
+
+Define this explicitly and commit it to the repo's `CONTRIBUTING.md` or a `BROWSERS.md` file:
+
+- **Evergreen tier** (full support): Chrome, Edge, Firefox, Safari — last 2 major versions
+- **Legacy tier** (functional, degraded): IE 11, Safari 12 — no graceful degradation unless business requires it
+- **Mobile browsers**: Chrome for Android, Safari iOS — test on real devices, not just emulators
+
+Use Browserslist to encode the matrix and share it across tools (Babel, PostCSS Autoprefixer, ESLint). Target: `"> 0.5%, last 2 versions, not dead"` as a safe default.
+
+### PWA Considerations
+
+Decide at project start whether PWA features are required:
+
+- **Service worker / offline**: Required if the app must function without connectivity or if mobile install is a goal. Adds complexity — cache invalidation is the #1 source of PWA bugs.
+- **Web App Manifest**: Low cost, high value. Enables mobile home screen install and controls display mode. Add for any app targeting mobile users.
+- **Push notifications**: Requires backend infrastructure and user permission flows. Scope carefully — most apps do not need this.
+
+### SEO Requirements
+
+For public-facing apps:
+
+- Server-render or statically generate all pages indexed by search engines. Client-rendered content is not reliably indexed.
+- Implement `<title>`, `<meta description>`, Open Graph, and structured data (JSON-LD) on every route.
+- Generate a sitemap at deploy time; submit to Google Search Console.
+- Ensure canonical URLs, `robots.txt`, and proper handling of 404/301/302 responses.
+
+### Performance Budget Enforcement
+
+Encode budgets in `budget.json` and enforce in CI:
+
+```json
+{
+  "resourceSizes": [
+    { "resourceType": "script", "budget": 300 },
+    { "resourceType": "total", "budget": 1000 },
+    { "resourceType": "image", "budget": 500 }
+  ],
+  "timings": [
+    { "metric": "first-contentful-paint", "budget": 1500 },
+    { "metric": "interactive", "budget": 3500 },
+    { "metric": "largest-contentful-paint", "budget": 2500 }
+  ]
+}
+```
+
+Run `lighthouse-ci` on every PR against a representative page. Block merges that regress LCP, INP, or CLS beyond tolerance.
+
+### Defining "Supported" vs "Functional"
+
+Do not conflate browser support tiers. Define what each means:
+
+- **Supported**: All features work, tested in CI, regressions are P0 bugs.
+- **Functional**: Core user journey works, advanced features may degrade gracefully.
+- **Unsupported**: App may not load at all; display an upgrade notice.
+
+Document which tier each browser falls into and socialize it with stakeholders before launch. Retrofitting support after launch is significantly more expensive than scoping it at project start.
+
+### Accessibility Requirements
+
+Accessibility is a requirement, not a feature. Decide on the compliance target upfront:
+
+- **WCAG 2.1 AA**: Industry baseline. Required for most government and enterprise customers.
+- **WCAG 2.2 AA**: Current standard; prefer this for new projects.
+- **Section 508**: Required for US federal contractors.
+
+Automated tools (axe, Lighthouse) catch ~30–40% of issues. Manual keyboard navigation and screen reader testing (VoiceOver, NVDA) must supplement automation.