Nt 3090 nextjs csr (#262)

* init nextjs app

* scaffold Next.js reference implementation with monorepo conventions

Restructure the bare create-next-app scaffold into a proper monorepo
implementation with both React Web SDK and Node SDK dependencies,
PM2-managed mock/serve scripts, env config, and AGENTS.md aligned
with existing implementation patterns.

* feat: add client-side React SDK integration with OptimizationProvider
and client-resolved demo

* docs: comment OptimizationProvider mount to client to avoid SSR
localStorage crash

* refactor: use next/dynamic with ssr:false for client-only SDK provider

Replace the useState/useEffect mount guard with a dedicated
ClientProviderWrapper that uses next/dynamic({ ssr: false }). This is
the standard Next.js pattern for browser-only third-party SDKs and
keeps OptimizationProvider clean without SSR workarounds.

* feat: add server-resolved pattern and isolate route SDK boundaries

- Add Node SDK server singleton and Next.js middleware for cookie
  lifecycle (ctfl-opt-aid profile management).
- Add server-resolved page: Server Component fetches entries and
  resolves them via Node SDK, renders pure server HTML with zero
  client JS for content.
- Add InteractiveControls as a small 'use client' component for
  consent/identify on the server-resolved route.
- Isolate SDK setup per route: each route has its own layout with
  its own ClientProviderWrapper, root layout is neutral.
- Remove custom OptimizationProvider wrapper; use SDK's
  OptimizationRoot directly via dynamic import.

* docs: update README and AGENTS.md to reflect current architecture

Document isolated route layouts, server-resolved vs client-resolved
patterns, design decisions, cookie-based profile management, and the
singleton dev-mode recovery tip.

* docs: document singleton conflict, customer setup context, and future direction

Add context on why this reference implementation exists, the known
singleton conflict when navigating between routes, and plans to
gather customer architecture patterns from pre/post-sales to inform
which setups to prioritize.

* refactor: convert react-web-sdk_nextjs to CSR-only implementation

Remove server-resolved route, middleware, Node SDK dependency, and
all server-side resolution code. This implementation now uses only
@contentful/optimization-react-web for pure client-side entry
resolution. The SSR hybrid pattern lives in a separate
react-web-sdk+node-sdk_nextjs implementation.

* chore: remove spike-nextjs-support.md

Superseded by the actual reference implementations.

* chore: remove session notes file

* fix: exclude Next.js implementations from root ESLint

The root ESLint (v10) is incompatible with eslint-plugin-react pulled
by eslint-config-next. The Next.js implementations have their own
local eslint.config.mjs and are linted via their own setup.

* docs: update docs to match nextJs-ssr pattern

* chore: rename directory and project

* fix: ignore nextJs projects in the linting commands due to NextJs bug

* docs: fix format

* feat: implement Hybrid SSR + CSR Takeover pattern (Setup 2)

Convert from pure CSR to hybrid pattern: Server Component first paint
via Node SDK, Client Component interactive page via useOptimization().
Add middleware for cookie lifecycle, Node SDK singleton, and Link-based
SPA navigation between SSR and CSR routes.

* refactor: consolidate to single-page hybrid SSR+CSR takeover

* fix: format

* feat: prime Web SDK with server-resolved defaults on hydration

Pass server-resolved profile, selectedOptimizations, and changes into
OptimizationRoot via defaults prop. Eliminates the state gap between
SSR first paint and client takeover. Provider moved to page level to
receive server data as props.

* refactor: move SSR priming to stable app layout

Prime the layout-level OptimizationRoot from shared request-scoped
optimization data so SSR and CSR takeover use the same evaluated state.
This keeps the provider stable across navigations while preserving a
seamless first-paint handoff.

* docs: add nextJs implementation guide

* fix:format

Author: Lotfi-Arif

documentation/guides/README.md

@@ -6,6 +6,8 @@ children:
   - ./integrating-the-web-sdk-in-a-web-app.md
   - ./integrating-the-react-web-sdk-in-a-react-app.md
   - ./integrating-the-react-native-sdk-in-a-react-native-app.md
+  - ./integrating-the-optimization-sdk-in-a-nextjs-app-ssr.md
+  - ./integrating-the-optimization-sdk-in-a-nextjs-app-ssr-csr.md
 ---
 
 # Guides
@@ -33,3 +35,10 @@ inventory instead.
 - [Integrating the Optimization React Native SDK in a React Native app](./integrating-the-react-native-sdk-in-a-react-native-app.md) -
   step-by-step React Native / Expo integration guidance covering setup, consent, personalization and
   interaction tracking, screen tracking, live updates, and the in-app preview panel
+- [Integrating the Optimization SDK in a Next.js app (SSR-primary)](./integrating-the-optimization-sdk-in-a-nextjs-app-ssr.md) -
+  step-by-step Next.js App Router guidance for the SSR-primary pattern where the Node SDK resolves
+  entries server-side and the React Web SDK handles client-side tracking and interactive controls
+- [Integrating the Optimization SDK in a Next.js app (hybrid SSR + CSR takeover)](./integrating-the-optimization-sdk-in-a-nextjs-app-ssr-csr.md) -
+  step-by-step Next.js App Router guidance for the hybrid pattern where first paint is
+  server-resolved and the React Web SDK takes over for instant client-side reactivity after
+  hydration