From e56c4ae182a6f0e52348a9270bdca229f9570fae Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 14:35:14 +0200
Subject: [PATCH 01/19] =?UTF-8?q?=F0=9F=90=9E=20fix(nextjs-ssr):=20Fix=20S?=
 =?UTF-8?q?SR=20rendering=20=E2=80=94=20always=20render=20children,=20use?=
 =?UTF-8?q?=20server-resolved=20optimization=20data?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- OptimizationProvider now always renders children (gates only when onStatesReady is set), enabling Next.js SSR to produce HTML from server components inside the provider tree
- Add SSR stub in useOptimization so the hook never throws during SSR / first client render before useLayoutEffect fires
- Introduce `getOptimizationData` (React.cache) as the single server-side entry point for optimization state, shared across pages in a request
- Add `loadPageData` + `ResolvedPageData` abstraction in lib/resolution.ts: fetches entries, resolves variants, applies merge tags, and recursively resolves linked entries before passing to components
- Refactor page components to use the new abstraction, removing per-page boilerplate
- Rename LiveEntryCard → EntryCard.client.tsx and consolidate into a single EntryCard component that handles both server (resolved) and client (live-updates) render paths
- Extract consent helpers to lib/consent.ts; expand lib/util.ts with entry/link type guards and resolveEntryLinks
- Extend contentful.ts with buildEntryRegistry/extendEntryRegistry for deep link resolution
- Update E2E_FLAGS to CSR,HYDRATION,SSR and fix seedIdentifiedProfile event shape in e2e utils

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 implementations/nextjs-sdk_ssr/.env.example   |   3 +-
 implementations/nextjs-sdk_ssr/AGENTS.md      |   5 +-
 implementations/nextjs-sdk_ssr/app/layout.tsx |  27 ++--
 .../nextjs-sdk_ssr/app/page-two/page.tsx      |  50 ++-----
 implementations/nextjs-sdk_ssr/app/page.tsx   |  91 +++----------
 ...LiveEntryCard.tsx => EntryCard.client.tsx} |  10 +-
 .../nextjs-sdk_ssr/components/EntryCard.tsx   |  93 ++++++-------
 .../nextjs-sdk_ssr/components/TrackingLog.tsx |   2 +-
 implementations/nextjs-sdk_ssr/lib/consent.ts |  10 ++
 .../nextjs-sdk_ssr/lib/contentful.ts          |  33 +++++
 implementations/nextjs-sdk_ssr/lib/hooks.ts   |   2 +-
 .../nextjs-sdk_ssr/lib/optimization.ts        |  22 ++-
 .../nextjs-sdk_ssr/lib/resolution.ts          | 128 ++++++++++++++++++
 implementations/nextjs-sdk_ssr/lib/util.ts    |  86 ++++++++++--
 lib/e2e-web/e2e/utils.ts                      |  19 ++-
 .../react-web-sdk/src/hooks/ssrStub.ts        | 100 ++++++++++++++
 .../src/hooks/useOptimization.ts              |  10 +-
 .../react-web-sdk/src/index.test.tsx          |  10 +-
 ...ptimizationProvider.onStatesReady.test.tsx |   5 +-
 .../src/provider/OptimizationProvider.tsx     |   9 +-
 20 files changed, 511 insertions(+), 204 deletions(-)
 rename implementations/nextjs-sdk_ssr/components/{LiveEntryCard.tsx => EntryCard.client.tsx} (74%)
 create mode 100644 implementations/nextjs-sdk_ssr/lib/consent.ts
 create mode 100644 implementations/nextjs-sdk_ssr/lib/resolution.ts
 create mode 100644 packages/web/frameworks/react-web-sdk/src/hooks/ssrStub.ts

diff --git a/implementations/nextjs-sdk_ssr/.env.example b/implementations/nextjs-sdk_ssr/.env.example
index 07e791524..ef67a4e32 100644
--- a/implementations/nextjs-sdk_ssr/.env.example
+++ b/implementations/nextjs-sdk_ssr/.env.example
@@ -1,7 +1,6 @@
 DOTENV_CONFIG_QUIET=true
 
-# SKIP_NO_JS skips the JavaScript-disabled variant resolution suite (SSR, JavaScript disabled).
-E2E_FLAGS=SSR,SKIP_NO_JS
+E2E_FLAGS=CSR,HYDRATION,SSR
 APP_PORT=3001
 
 PUBLIC_NINETAILED_CLIENT_ID="mock-client-id"
diff --git a/implementations/nextjs-sdk_ssr/AGENTS.md b/implementations/nextjs-sdk_ssr/AGENTS.md
index 64fe94551..f8f894457 100644
--- a/implementations/nextjs-sdk_ssr/AGENTS.md
+++ b/implementations/nextjs-sdk_ssr/AGENTS.md
@@ -16,9 +16,8 @@ server/client SDK composition; app code imports only Next.js SDK subpaths.
 ## E2E tests
 
 - All E2E tests live in `lib/e2e-web`. Hydration-specific specs are gated with `runIf('HYDRATION')`
-  and run automatically when `E2E_FLAGS=CSR,HYDRATION`. This implementation uses
-  `E2E_FLAGS=SSR,SKIP_NO_JS`: SSR enables the SSR suite, and `SKIP_NO_JS` skips the
-  JavaScript-disabled variant resolution suite (`Variant Resolution (SSR, JavaScript disabled)`).
+  and run automatically when `E2E_FLAGS=CSR,HYDRATION`. The `SSR` flag is intentionally omitted
+  because full SSR variant resolution has a known bug.
 - Entry cards must expose `data-ctfl-entry-id` on the `content-*` element so shared selectors work.
 - `test:e2e` delegates to `lib/e2e-web`.
 
diff --git a/implementations/nextjs-sdk_ssr/app/layout.tsx b/implementations/nextjs-sdk_ssr/app/layout.tsx
index a2c84a055..7c5bff7c0 100644
--- a/implementations/nextjs-sdk_ssr/app/layout.tsx
+++ b/implementations/nextjs-sdk_ssr/app/layout.tsx
@@ -2,13 +2,12 @@ import { GlobalLiveUpdatesProvider } from '@/components/GlobalLiveUpdatesProvide
 import { PreviewPanel } from '@/components/PreviewPanel'
 import { TrackingLog } from '@/components/TrackingLog'
 import { appConfig } from '@/lib/config'
-import { getAppConsent } from '@/lib/util'
+import { getOptimizationData } from '@/lib/optimization'
 import { NextAppAutoPageTracker, OptimizationRoot } from '@contentful/optimization-nextjs/client'
 import 'e2e-web/theme.css'
 import type { Metadata } from 'next'
-import { cookies } from 'next/headers'
 import Link from 'next/link'
-import { Suspense, type ReactNode } from 'react'
+import { type ReactNode } from 'react'
 
 export const metadata: Metadata = {
   title: 'Optimization Next.js SDK SSR',
@@ -16,9 +15,21 @@ export const metadata: Metadata = {
     'Next.js App Router reference: the Next.js SDK resolves entries server-side and handles client-side tracking and interactive controls.',
 }
 
+export const dynamic = 'force-dynamic'
+
 export default async function RootLayout({ children }: Readonly<{ children: ReactNode }>) {
-  const cookieStore = await cookies()
-  const appConsent = getAppConsent(cookieStore)
+  const { data: optimizationData, hasConsent } = await getOptimizationData()
+  const defaults = optimizationData
+    ? {
+        profile: optimizationData.profile,
+        ...(hasConsent
+          ? {
+              selectedOptimizations: optimizationData.selectedOptimizations,
+              changes: optimizationData.changes,
+            }
+          : {}),
+      }
+    : undefined
 
   return (
     <html lang={appConfig.locale.split('-')[0]}>
@@ -30,17 +41,15 @@ export default async function RootLayout({ children }: Readonly<{ children: Reac
           api={appConfig.api}
           trackEntryInteraction={{ views: true, clicks: true, hovers: true }}
           logLevel="debug"
+          defaults={defaults}
           app={{
             name: 'Contentful Optimization Next.js SDK SSR (Client)',
             version: '0.1.0',
           }}
-          defaults={{ consent: appConsent, persistenceConsent: appConsent }}
         >
           <GlobalLiveUpdatesProvider>
             <PreviewPanel />
-            <Suspense>
-              <NextAppAutoPageTracker initialPageEvent={appConsent ? 'skip' : 'emit'} />
-            </Suspense>
+            <NextAppAutoPageTracker initialPageEvent={hasConsent ? 'skip' : 'emit'} />
             <div className="app-shell">
               <nav>
                 <Link data-testid="link-home" href="/">
diff --git a/implementations/nextjs-sdk_ssr/app/page-two/page.tsx b/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
index 8de467ce3..4eafbc1a4 100644
--- a/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
+++ b/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
@@ -1,40 +1,15 @@
 import { ControlPanel } from '@/components/ControlPanel'
 import { CustomViewTracker } from '@/components/CustomViewTracker'
 import { EntryCard } from '@/components/EntryCard'
-import { appConfig } from '@/lib/config'
-import { loadPageEntries } from '@/lib/contentful'
-import { optimization } from '@/lib/optimization'
-import { getAppConsent, toIdMap } from '@/lib/util'
-import { NextjsOptimizationState } from '@contentful/optimization-nextjs/client'
-import { getNextjsServerOptimizationData } from '@contentful/optimization-nextjs/server'
+import { loadPageData } from '@/lib/resolution'
 import { PAGES } from 'e2e-web'
-import { cookies, headers } from 'next/headers'
 import Link from 'next/link'
 
 export default async function PageTwo() {
-  const [cookieStore, headerStore] = await Promise.all([cookies(), headers()])
+  const data = await loadPageData(PAGES.pageTwo.ids)
 
-  const [entries, optimizationData] = await Promise.all([
-    loadPageEntries(PAGES.pageTwo.ids),
-    getAppConsent(cookieStore)
-      ? getNextjsServerOptimizationData(optimization, {
-          consent: { events: true, persistence: true },
-          cookies: cookieStore,
-          headers: headerStore,
-          locale: appConfig.locale,
-        }).then(({ data }) => data)
-      : undefined,
-  ])
-
-  const entriesById = toIdMap(entries)
-  const autoEntry = entriesById.get(PAGES.pageTwo.auto)
-  const manualEntry = entriesById.get(PAGES.pageTwo.manual)
-  const autoResolved = autoEntry
-    ? optimization.resolveOptimizedEntry(autoEntry, optimizationData?.selectedOptimizations)
-    : undefined
-  const manualResolved = manualEntry
-    ? optimization.resolveOptimizedEntry(manualEntry, optimizationData?.selectedOptimizations)
-    : undefined
+  const auto = data.get(PAGES.pageTwo.auto)
+  const manual = data.get(PAGES.pageTwo.manual)
 
   return (
     <section data-testid="page-two-view">
@@ -47,7 +22,6 @@ export default async function PageTwo() {
 
       <CustomViewTracker componentId="page-two-hero" />
       <ControlPanel demoCTA />
-      <NextjsOptimizationState data={optimizationData} />
 
       <div className="sections-grid sections-grid--split" data-testid="page-two-optimization">
         <section className="page-section">
@@ -55,12 +29,8 @@ export default async function PageTwo() {
             <h2>Auto-observed</h2>
           </header>
           <div className="entry-grid">
-            {autoEntry && autoResolved ? (
-              <EntryCard
-                baselineEntry={autoEntry}
-                resolvedData={autoResolved}
-                manualTracking={false}
-              />
+            {auto ? (
+              <EntryCard entry={auto} manualTracking={false} />
             ) : (
               <p>Auto tracked entry is unavailable.</p>
             )}
@@ -72,12 +42,8 @@ export default async function PageTwo() {
             <h2>Manually-observed</h2>
           </header>
           <div className="entry-grid">
-            {manualEntry && manualResolved ? (
-              <EntryCard
-                baselineEntry={manualEntry}
-                resolvedData={manualResolved}
-                manualTracking={true}
-              />
+            {manual ? (
+              <EntryCard entry={manual} manualTracking={true} />
             ) : (
               <p>Manual tracked entry is unavailable.</p>
             )}
diff --git a/implementations/nextjs-sdk_ssr/app/page.tsx b/implementations/nextjs-sdk_ssr/app/page.tsx
index 49e00b721..711a0c9ba 100644
--- a/implementations/nextjs-sdk_ssr/app/page.tsx
+++ b/implementations/nextjs-sdk_ssr/app/page.tsx
@@ -1,48 +1,12 @@
 import { ControlPanel } from '@/components/ControlPanel'
 import { EntryCard } from '@/components/EntryCard'
-import { LiveEntryCard } from '@/components/LiveEntryCard'
-import { appConfig } from '@/lib/config'
-import { type ContentEntry, loadPageEntries } from '@/lib/contentful'
-import { optimization } from '@/lib/optimization'
-import { getAppConsent, toIdMap } from '@/lib/util'
-import { NextjsOptimizationState } from '@contentful/optimization-nextjs/client'
-import {
-  type ServerTrackingResolvedData,
-  getNextjsServerOptimizationData,
-} from '@contentful/optimization-nextjs/server'
+import { loadPageData } from '@/lib/resolution'
 import { CLICK_SCENARIOS, PAGES } from 'e2e-web'
-import { cookies, headers } from 'next/headers'
 
 export default async function Home() {
-  const [cookieStore, headerStore] = await Promise.all([cookies(), headers()])
+  const data = await loadPageData(PAGES.home.ids)
 
-  const [entries, optimizationData] = await Promise.all([
-    loadPageEntries(PAGES.home.ids),
-    getAppConsent(cookieStore)
-      ? getNextjsServerOptimizationData(optimization, {
-          consent: { events: true, persistence: true },
-          cookies: cookieStore,
-          headers: headerStore,
-          locale: appConfig.locale,
-        }).then(({ data }) => data)
-      : undefined,
-  ])
-
-  const entriesById = toIdMap(entries)
-  const resolvedById = new Map(
-    entries.map((entry) => [
-      entry.sys.id,
-      optimization.resolveOptimizedEntry(entry, optimizationData?.selectedOptimizations),
-    ]),
-  )
-
-  const profile = optimizationData?.profile
-  const getMergeTagValue = (entry: unknown): string | undefined =>
-    optimization.getMergeTagValue(entry as never, profile)
-  const resolveEntry = (entry: ContentEntry): ServerTrackingResolvedData =>
-    optimization.resolveOptimizedEntry(entry, optimizationData?.selectedOptimizations)
-
-  const liveUpdatesEntry = entriesById.get(PAGES.home.liveUpdates)
+  const liveUpdatesEntry = data.get(PAGES.home.liveUpdates)?.baselineEntry
 
   return (
     <>
@@ -55,7 +19,6 @@ export default async function Home() {
       </div>
 
       <ControlPanel />
-      <NextjsOptimizationState data={optimizationData} />
 
       <section className="page-section" data-testid="live-updates-section">
         <header className="page-section__header">
@@ -69,17 +32,17 @@ export default async function Home() {
           <div className="sections-grid" data-testid="live-updates-examples">
             <section data-testid="live-updates-default">
               <h3>Default (inherits global setting)</h3>
-              <LiveEntryCard entry={liveUpdatesEntry} testId="live-default" />
+              <EntryCard entry={liveUpdatesEntry} testId="live-default" />
             </section>
 
             <section data-testid="live-updates-enabled">
               <h3>Always On (liveUpdates=true)</h3>
-              <LiveEntryCard entry={liveUpdatesEntry} liveUpdates={true} testId="live-enabled" />
+              <EntryCard entry={liveUpdatesEntry} liveUpdates={true} testId="live-enabled" />
             </section>
 
             <section data-testid="live-updates-locked">
               <h3>Locked (liveUpdates=false)</h3>
-              <LiveEntryCard entry={liveUpdatesEntry} liveUpdates={false} testId="live-locked" />
+              <EntryCard entry={liveUpdatesEntry} liveUpdates={false} testId="live-locked" />
             </section>
           </div>
         ) : (
@@ -93,22 +56,14 @@ export default async function Home() {
             <h2>Auto Observed Entries</h2>
           </header>
           <div id="auto-observed" className="entry-grid">
-            {PAGES.home.auto.flatMap((id) => {
-              const entry = entriesById.get(id)
-              const resolvedData = resolvedById.get(id)
-              if (!entry || !resolvedData) return []
-              return [
-                <EntryCard
-                  key={id}
-                  baselineEntry={entry}
-                  clickScenario={CLICK_SCENARIOS[id]}
-                  getMergeTagValue={getMergeTagValue}
-                  manualTracking={false}
-                  resolveEntry={resolveEntry}
-                  resolvedData={resolvedData}
-                />,
-              ]
-            })}
+            {data.resolve(PAGES.home.auto).map((entry) => (
+              <EntryCard
+                key={entry.baselineEntry.sys.id}
+                entry={entry}
+                clickScenario={CLICK_SCENARIOS[entry.baselineEntry.sys.id]}
+                manualTracking={false}
+              />
+            ))}
           </div>
         </section>
 
@@ -117,21 +72,9 @@ export default async function Home() {
             <h2>Manually Observed Entries</h2>
           </header>
           <div id="manually-observed" className="entry-grid">
-            {PAGES.home.manual.flatMap((id) => {
-              const entry = entriesById.get(id)
-              const resolvedData = resolvedById.get(id)
-              if (!entry || !resolvedData) return []
-              return [
-                <EntryCard
-                  key={id}
-                  baselineEntry={entry}
-                  getMergeTagValue={getMergeTagValue}
-                  manualTracking={true}
-                  resolveEntry={resolveEntry}
-                  resolvedData={resolvedData}
-                />,
-              ]
-            })}
+            {data.resolve(PAGES.home.manual).map((entry) => (
+              <EntryCard key={entry.baselineEntry.sys.id} entry={entry} manualTracking={true} />
+            ))}
           </div>
         </section>
       </div>
diff --git a/implementations/nextjs-sdk_ssr/components/LiveEntryCard.tsx b/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
similarity index 74%
rename from implementations/nextjs-sdk_ssr/components/LiveEntryCard.tsx
rename to implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
index c0dd6d80a..5348a2dc0 100644
--- a/implementations/nextjs-sdk_ssr/components/LiveEntryCard.tsx
+++ b/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
@@ -4,19 +4,18 @@ import type { ContentEntry } from '@/lib/contentful'
 import { OptimizedEntry } from '@contentful/optimization-nextjs/client'
 import type { JSX } from 'react'
 
-interface LiveEntryCardProps {
+interface EntryCardClientProps {
   entry: ContentEntry
   liveUpdates?: boolean
   testId: string
 }
 
-export function LiveEntryCard({ entry, liveUpdates, testId }: LiveEntryCardProps): JSX.Element {
+export function EntryCardClient({ entry, liveUpdates, testId }: EntryCardClientProps): JSX.Element {
   return (
     <OptimizedEntry baselineEntry={entry} liveUpdates={liveUpdates}>
       {(resolvedEntry) => {
         const asCf = resolvedEntry as ContentEntry
         const text = typeof asCf.fields.text === 'string' ? asCf.fields.text : ''
-        const fullLabel = `${text} [Entry: ${resolvedEntry.sys.id}]`
 
         return (
           <div
@@ -24,7 +23,10 @@ export function LiveEntryCard({ entry, liveUpdates, testId }: LiveEntryCardProps
             data-test-entry-id={resolvedEntry.sys.id}
             data-testid={`content-${testId}`}
           >
-            <div aria-label={fullLabel} data-testid={`entry-text-${testId}`}>
+            <div
+              aria-label={`${text} [Entry: ${resolvedEntry.sys.id}]`}
+              data-testid={`entry-text-${testId}`}
+            >
               <p>{text}</p>
               <p>{`[Entry: ${resolvedEntry.sys.id}]`}</p>
             </div>
diff --git a/implementations/nextjs-sdk_ssr/components/EntryCard.tsx b/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
index 93f17d363..f27a57b53 100644
--- a/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
+++ b/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
@@ -1,13 +1,8 @@
-import type { ContentEntry, ContentEntrySkeleton } from '@/lib/contentful'
-import {
-  isRecord,
-  isResolvedContentfulEntry,
-  isRichTextDocument,
-} from '@contentful/optimization-nextjs/api-schemas'
-import {
-  ServerOptimizedEntry,
-  type ServerTrackingResolvedData,
-} from '@contentful/optimization-nextjs/server'
+import { EntryCardClient } from '@/components/EntryCard.client'
+import type { ContentEntry, RichTextDocument } from '@/lib/contentful'
+import type { Entry } from '@/lib/resolution'
+import { isRecord } from '@/lib/util'
+import { ServerOptimizedEntry } from '@contentful/optimization-nextjs/server'
 import { documentToReactComponents, type Options } from '@contentful/rich-text-react-renderer'
 import { INLINES } from '@contentful/rich-text-types'
 import type { EntryClickScenario } from 'e2e-web'
@@ -15,44 +10,53 @@ import type { JSX } from 'react'
 
 const HOVER_DURATION_UPDATE_INTERVAL_MS = 1000
 
-type MergeTagResolver = (entry: unknown) => string | undefined
-
-interface EntryCardProps {
-  baselineEntry: ContentEntry
+interface EntryCardServerProps {
+  entry: Entry
   clickScenario?: EntryClickScenario
-  getMergeTagValue?: MergeTagResolver
   manualTracking: boolean
-  resolveEntry?: (entry: ContentEntry) => ServerTrackingResolvedData
-  resolvedData: ServerTrackingResolvedData
+  liveUpdates?: never
+  testId?: never
+}
+
+interface EntryCardClientProps {
+  entry: ContentEntry
+  liveUpdates?: boolean
+  testId: string
+  clickScenario?: never
+  manualTracking?: never
 }
 
-function buildRenderOptions(getMergeTagValue?: MergeTagResolver): Options {
-  return {
-    renderNode: {
-      [INLINES.EMBEDDED_ENTRY]: (node): string => {
-        const { data } = node
-        if (!isRecord(data) || !('target' in data)) return ''
-        return getMergeTagValue?.(data.target) ?? ''
-      },
+type EntryCardProps = EntryCardServerProps | EntryCardClientProps
+
+function isRichTextField(field: unknown): field is RichTextDocument {
+  return isRecord(field) && field.nodeType === 'document' && Array.isArray(field.content)
+}
+
+const RENDER_OPTIONS: Options = {
+  renderNode: {
+    [INLINES.EMBEDDED_ENTRY]: (node): string => {
+      const { data } = node
+      if (!isRecord(data)) return ''
+      return typeof data.resolvedValue === 'string' ? data.resolvedValue : ''
     },
-  }
+  },
 }
 
-export function EntryCard({
-  baselineEntry,
-  clickScenario,
-  getMergeTagValue,
-  manualTracking,
-  resolveEntry,
-  resolvedData,
-}: EntryCardProps): JSX.Element {
-  const resolvedEntry = resolvedData.entry as ContentEntry
+export function EntryCard(props: EntryCardProps): JSX.Element {
+  if (!('baselineEntry' in props.entry)) {
+    const { entry, liveUpdates, testId } = props as EntryCardClientProps
+    return (
+      <section className="entry-card" data-testid={`content-entry-${testId}`}>
+        <EntryCardClient entry={entry} liveUpdates={liveUpdates} testId={testId} />
+      </section>
+    )
+  }
+
+  const { entry, clickScenario, manualTracking } = props as EntryCardServerProps
+  const { baselineEntry, resolvedData, resolvedEntry } = entry
   const autoTrackViews = !manualTracking
-  const richText = Object.values(resolvedEntry.fields).find(isRichTextDocument)
-  const nested = Array.isArray(resolvedEntry.fields.nested)
-    ? resolvedEntry.fields.nested.filter(isResolvedContentfulEntry<ContentEntrySkeleton>)
-    : []
-  const renderOptions = buildRenderOptions(getMergeTagValue)
+  const richText = Object.values(resolvedEntry.fields).find(isRichTextField)
+  const nested: Entry[] = resolvedEntry.fields.nested ?? []
 
   const content = (
     <div data-ctfl-entry-id={resolvedEntry.sys.id} data-testid={`content-${baselineEntry.sys.id}`}>
@@ -62,7 +66,7 @@ export function EntryCard({
         data-testid={`entry-text-${baselineEntry.sys.id}`}
       >
         {richText ? (
-          <>{documentToReactComponents(richText, renderOptions)}</>
+          <>{documentToReactComponents(richText, RENDER_OPTIONS)}</>
         ) : (
           <p>{typeof resolvedEntry.fields.text === 'string' ? resolvedEntry.fields.text : ''}</p>
         )}
@@ -77,12 +81,9 @@ export function EntryCard({
         <div className="entry-card__nested-children">
           {nested.map((nestedEntry) => (
             <EntryCard
-              baselineEntry={nestedEntry}
-              getMergeTagValue={getMergeTagValue}
-              key={nestedEntry.sys.id}
+              key={nestedEntry.baselineEntry.sys.id}
+              entry={nestedEntry}
               manualTracking={false}
-              resolveEntry={resolveEntry}
-              resolvedData={resolveEntry ? resolveEntry(nestedEntry) : { entry: nestedEntry }}
             />
           ))}
         </div>
diff --git a/implementations/nextjs-sdk_ssr/components/TrackingLog.tsx b/implementations/nextjs-sdk_ssr/components/TrackingLog.tsx
index 434d89538..7f6cde187 100644
--- a/implementations/nextjs-sdk_ssr/components/TrackingLog.tsx
+++ b/implementations/nextjs-sdk_ssr/components/TrackingLog.tsx
@@ -1,7 +1,7 @@
 'use client'
 
 import { useEventStream, useTick } from '@/lib/hooks'
-import { isRecord } from '@contentful/optimization-nextjs/api-schemas'
+import { isRecord } from '@/lib/util'
 import { type JSX } from 'react'
 
 const MS_PER_SECOND = 1000
diff --git a/implementations/nextjs-sdk_ssr/lib/consent.ts b/implementations/nextjs-sdk_ssr/lib/consent.ts
new file mode 100644
index 000000000..da081d6c3
--- /dev/null
+++ b/implementations/nextjs-sdk_ssr/lib/consent.ts
@@ -0,0 +1,10 @@
+import { appConfig } from './config'
+
+export function setAppConsent(consented: boolean): void {
+  const value = consented ? 'granted' : 'denied'
+  document.cookie = `${appConfig.personalizationConsentCookie}=${value}; Path=/; SameSite=Lax`
+}
+
+export function getAppConsent(cookies: { get(i: string): { value: string } | undefined }): boolean {
+  return cookies.get(appConfig.personalizationConsentCookie)?.value === 'granted'
+}
diff --git a/implementations/nextjs-sdk_ssr/lib/contentful.ts b/implementations/nextjs-sdk_ssr/lib/contentful.ts
index f7ef6413d..8d132c83e 100644
--- a/implementations/nextjs-sdk_ssr/lib/contentful.ts
+++ b/implementations/nextjs-sdk_ssr/lib/contentful.ts
@@ -2,6 +2,7 @@ import type { Document } from '@contentful/rich-text-types'
 import type { Entry, EntryFieldTypes, EntrySkeletonType } from 'contentful'
 import { createClient } from 'contentful'
 import { appConfig } from './config'
+import { collectLinkIds, toIdMap } from './util'
 
 export interface ContentEntryFields {
   text?: EntryFieldTypes.Text | EntryFieldTypes.RichText
@@ -40,3 +41,35 @@ export async function loadPageEntries(entryIds: readonly string[]): Promise<Cont
   const results = await Promise.all(entryIds.map(fetchEntry))
   return results.filter((entry): entry is ContentEntry => entry !== undefined)
 }
+
+export async function extendEntryRegistry(
+  registry: Map<string, ContentEntry>,
+  entries: ContentEntry[],
+): Promise<void> {
+  const queue = new Set<string>()
+  for (const entry of entries) {
+    for (const id of collectLinkIds(entry)) {
+      if (!registry.has(id)) queue.add(id)
+    }
+  }
+  while (queue.size > 0) {
+    const fetched = await loadPageEntries([...queue])
+    queue.clear()
+    for (const entry of fetched) {
+      if (!registry.has(entry.sys.id)) {
+        registry.set(entry.sys.id, entry)
+        for (const id of collectLinkIds(entry)) {
+          if (!registry.has(id)) queue.add(id)
+        }
+      }
+    }
+  }
+}
+
+export async function buildEntryRegistry(
+  entries: ContentEntry[],
+): Promise<Map<string, ContentEntry>> {
+  const registry = toIdMap(entries)
+  await extendEntryRegistry(registry, entries)
+  return registry
+}
diff --git a/implementations/nextjs-sdk_ssr/lib/hooks.ts b/implementations/nextjs-sdk_ssr/lib/hooks.ts
index 153c739c8..5071456d7 100644
--- a/implementations/nextjs-sdk_ssr/lib/hooks.ts
+++ b/implementations/nextjs-sdk_ssr/lib/hooks.ts
@@ -7,7 +7,7 @@ import {
   useOptimizationContext,
 } from '@contentful/optimization-nextjs/client'
 import { useEffect, useReducer, useRef, useState } from 'react'
-import { setAppConsent } from './util'
+import { setAppConsent } from './consent'
 
 export function useConsent(): {
   consent: boolean | undefined
diff --git a/implementations/nextjs-sdk_ssr/lib/optimization.ts b/implementations/nextjs-sdk_ssr/lib/optimization.ts
index 600335ec4..284a408cf 100644
--- a/implementations/nextjs-sdk_ssr/lib/optimization.ts
+++ b/implementations/nextjs-sdk_ssr/lib/optimization.ts
@@ -1,5 +1,11 @@
-import { createNextjsOptimization } from '@contentful/optimization-nextjs/server'
+import {
+  createNextjsOptimization,
+  getNextjsServerOptimizationData,
+} from '@contentful/optimization-nextjs/server'
+import { cookies, headers } from 'next/headers'
+import { cache } from 'react'
 import { appConfig } from './config'
+import { getAppConsent } from './consent'
 
 export const optimization = createNextjsOptimization({
   clientId: appConfig.clientId,
@@ -12,3 +18,17 @@ export const optimization = createNextjsOptimization({
     version: '0.1.0',
   },
 })
+
+export const getOptimizationData = cache(async () => {
+  const cookieStore = await cookies()
+  const headerStore = await headers()
+  const hasConsent = getAppConsent(cookieStore)
+  const { data } = await getNextjsServerOptimizationData(optimization, {
+    consent: { events: hasConsent, persistence: hasConsent },
+    cookies: hasConsent ? cookieStore : undefined,
+    headers: headerStore,
+    locale: appConfig.locale,
+  })
+
+  return { data, hasConsent }
+})
diff --git a/implementations/nextjs-sdk_ssr/lib/resolution.ts b/implementations/nextjs-sdk_ssr/lib/resolution.ts
new file mode 100644
index 000000000..5ec624312
--- /dev/null
+++ b/implementations/nextjs-sdk_ssr/lib/resolution.ts
@@ -0,0 +1,128 @@
+import { type ServerTrackingResolvedData } from '@contentful/optimization-nextjs/server'
+import { INLINES } from '@contentful/rich-text-types'
+import {
+  buildEntryRegistry,
+  extendEntryRegistry,
+  loadPageEntries,
+  type ContentEntry,
+  type RichTextDocument,
+} from './contentful'
+import { getOptimizationData, optimization } from './optimization'
+import { isEntry, isRecord, resolveEntryLinks } from './util'
+
+type Profile = Parameters<typeof optimization.getMergeTagValue>[1]
+type SelectedOptimizations = Parameters<typeof optimization.resolveOptimizedEntry>[1]
+
+export interface ResolvedEntry extends Omit<ContentEntry, 'fields'> {
+  fields: Omit<ContentEntry['fields'], 'nested'> & {
+    nested?: Entry[]
+  }
+}
+
+export interface Entry {
+  baselineEntry: ContentEntry
+  /** Raw resolved data for the SDK (ServerOptimizedEntry). entry is a vanilla ContentEntry. */
+  resolvedData: ServerTrackingResolvedData
+  /** Resolved entry for rendering — fields.nested contains resolved Entry children. */
+  resolvedEntry: ResolvedEntry
+}
+
+export interface ResolvedPageData {
+  resolve(ids: readonly string[]): Entry[]
+  get(id: string): Entry | undefined
+}
+
+function substituteMergeTags(doc: RichTextDocument, profile: Profile): RichTextDocument {
+  const walk = (node: unknown): unknown => {
+    if (!isRecord(node)) return node
+    if (node.nodeType === INLINES.EMBEDDED_ENTRY && isRecord(node.data) && 'target' in node.data) {
+      const value = optimization.getMergeTagValue(node.data.target as never, profile) ?? ''
+      return { ...node, data: { ...node.data, resolvedValue: value } }
+    }
+    if (Array.isArray(node.content)) return { ...node, content: node.content.map(walk) }
+    return node
+  }
+  return walk(doc) as RichTextDocument
+}
+
+function applyMergeTags(entry: ContentEntry, profile: Profile): ContentEntry {
+  const fields = Object.fromEntries(
+    Object.entries(entry.fields).map(([key, value]) => {
+      if (isRecord(value) && value.nodeType === 'document' && Array.isArray(value.content)) {
+        return [key, substituteMergeTags(value as unknown as RichTextDocument, profile)]
+      }
+      return [key, value]
+    }),
+  ) as ContentEntry['fields']
+  return { ...entry, fields }
+}
+
+function buildEntry(
+  baselineEntry: ContentEntry,
+  selectedOptimizations: SelectedOptimizations,
+  registry: Map<string, ContentEntry>,
+  profile: Profile,
+  visited: Set<string>,
+): Entry {
+  visited.add(baselineEntry.sys.id)
+
+  const resolvedData = {
+    ...optimization.resolveOptimizedEntry(baselineEntry, selectedOptimizations),
+    entry: resolveEntryLinks(
+      optimization.resolveOptimizedEntry(baselineEntry, selectedOptimizations)
+        .entry as ContentEntry,
+      registry,
+    ),
+  } as ServerTrackingResolvedData
+
+  const withMergeTags = applyMergeTags(resolvedData.entry as ContentEntry, profile)
+
+  const nestedBaselines = Array.isArray(withMergeTags.fields.nested)
+    ? withMergeTags.fields.nested.filter(isEntry)
+    : []
+
+  const nested = nestedBaselines
+    .filter((n) => !visited.has(n.sys.id))
+    .map((n) => buildEntry(n, selectedOptimizations, registry, profile, new Set(visited)))
+
+  const resolvedEntry: ResolvedEntry = {
+    ...withMergeTags,
+    fields: { ...withMergeTags.fields, nested: nested.length > 0 ? nested : undefined },
+  }
+
+  return { baselineEntry, resolvedData, resolvedEntry }
+}
+
+export async function loadPageData(entryIds: readonly string[]): Promise<ResolvedPageData> {
+  const [entries, { data: optimizationData }] = await Promise.all([
+    loadPageEntries(entryIds),
+    getOptimizationData(),
+  ])
+  const selectedOptimizations = optimizationData?.selectedOptimizations
+  const profile = optimizationData?.profile
+  const registry = await buildEntryRegistry(entries)
+
+  const resolvedVariants = entries.map((entry) =>
+    optimization.resolveOptimizedEntry(entry, selectedOptimizations),
+  )
+  await extendEntryRegistry(
+    registry,
+    resolvedVariants.map((r) => r.entry as ContentEntry),
+  )
+
+  const byId = new Map(
+    entries.map((entry) => [
+      entry.sys.id,
+      buildEntry(entry, selectedOptimizations, registry, profile, new Set()),
+    ]),
+  )
+
+  return {
+    resolve: (ids) =>
+      ids.flatMap((id) => {
+        const e = byId.get(id)
+        return e ? [e] : []
+      }),
+    get: (id) => byId.get(id),
+  }
+}
diff --git a/implementations/nextjs-sdk_ssr/lib/util.ts b/implementations/nextjs-sdk_ssr/lib/util.ts
index aaffbca3d..89c0dbf4d 100644
--- a/implementations/nextjs-sdk_ssr/lib/util.ts
+++ b/implementations/nextjs-sdk_ssr/lib/util.ts
@@ -1,14 +1,84 @@
-import { appConfig } from './config'
+import type { ContentEntry } from './contentful'
 
-export function toIdMap<T extends { sys: { id: string } }>(items: T[]): Map<string, T> {
-  return new Map(items.map((item) => [item.sys.id, item]))
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isLink(value: unknown): value is { sys: { type: 'Link'; linkType: 'Entry'; id: string } } {
+  return (
+    isRecord(value) &&
+    isRecord(value.sys) &&
+    value.sys.type === 'Link' &&
+    value.sys.linkType === 'Entry' &&
+    typeof value.sys.id === 'string'
+  )
+}
+
+export function isEntry(value: unknown): value is ContentEntry {
+  return (
+    isRecord(value) &&
+    isRecord(value.sys) &&
+    typeof value.sys.id === 'string' &&
+    isRecord(value.fields)
+  )
+}
+
+function resolveField(
+  value: unknown,
+  entryMap: Map<string, ContentEntry>,
+  visited: Set<string>,
+): unknown {
+  if (isLink(value)) {
+    const resolved = entryMap.get(value.sys.id)
+    if (!resolved) return value
+    return resolveEntryLinksInternal(resolved, entryMap, visited)
+  }
+  if (Array.isArray(value)) return value.map((item) => resolveField(item, entryMap, visited))
+  return value
+}
+
+function resolveEntryLinksInternal(
+  entry: ContentEntry,
+  entryMap: Map<string, ContentEntry>,
+  visited: Set<string>,
+): ContentEntry {
+  if (visited.has(entry.sys.id)) return entry
+  visited.add(entry.sys.id)
+  const resolvedFields = Object.fromEntries(
+    Object.entries(entry.fields).map(([key, value]) => [
+      key,
+      resolveField(value, entryMap, visited),
+    ]),
+  ) as ContentEntry['fields']
+  return { ...entry, fields: resolvedFields }
 }
 
-export function setAppConsent(consented: boolean): void {
-  const value = consented ? 'granted' : 'denied'
-  document.cookie = `${appConfig.personalizationConsentCookie}=${value}; Path=/; SameSite=Lax`
+export function resolveEntryLinks(
+  entry: ContentEntry,
+  entryMap: Map<string, ContentEntry>,
+): ContentEntry {
+  return resolveEntryLinksInternal(entry, entryMap, new Set())
 }
 
-export function getAppConsent(cookies: { get(i: string): { value: string } | undefined }): boolean {
-  return cookies.get(appConfig.personalizationConsentCookie)?.value === 'granted'
+export function collectLinkIds(entry: ContentEntry, visited = new Set<string>()): string[] {
+  if (visited.has(entry.sys.id)) return []
+  visited.add(entry.sys.id)
+  const ids: string[] = []
+  for (const value of Object.values(entry.fields)) {
+    if (isLink(value)) {
+      ids.push(value.sys.id)
+    } else if (Array.isArray(value)) {
+      for (const item of value) {
+        if (isLink(item)) ids.push(item.sys.id)
+        else if (isEntry(item)) ids.push(...collectLinkIds(item, visited))
+      }
+    } else if (isEntry(value)) {
+      ids.push(...collectLinkIds(value, visited))
+    }
+  }
+  return ids
+}
+
+export function toIdMap<T extends { sys: { id: string } }>(items: T[]): Map<string, T> {
+  return new Map(items.map((item) => [item.sys.id, item]))
 }
diff --git a/lib/e2e-web/e2e/utils.ts b/lib/e2e-web/e2e/utils.ts
index 0e8224422..8124c0cf3 100644
--- a/lib/e2e-web/e2e/utils.ts
+++ b/lib/e2e-web/e2e/utils.ts
@@ -53,12 +53,29 @@ export async function seedIdentifiedProfile(
   request: APIRequestContext,
   profileId: string,
 ): Promise<void> {
+  const now = new Date().toISOString()
   await request.post(
     `${MOCK_EXPERIENCE_URL}/v2/organizations/mock-client-id/environments/main/profiles/${profileId}`,
     {
       data: {
         events: [
-          { type: 'identify', properties: { userId: 'charles', traits: { identified: true } } },
+          {
+            channel: 'web',
+            context: {
+              app: { name: 'e2e-seed', version: '0.0.0' },
+              campaign: {},
+              gdpr: { isConsentGiven: true },
+              library: { name: 'e2e-seed', version: '0.0.0' },
+              locale: 'en-US',
+            },
+            messageId: profileId,
+            originalTimestamp: now,
+            sentAt: now,
+            timestamp: now,
+            type: 'identify',
+            userId: 'charles',
+            traits: { identified: true },
+          },
         ],
       },
     },
diff --git a/packages/web/frameworks/react-web-sdk/src/hooks/ssrStub.ts b/packages/web/frameworks/react-web-sdk/src/hooks/ssrStub.ts
new file mode 100644
index 000000000..b8d70a972
--- /dev/null
+++ b/packages/web/frameworks/react-web-sdk/src/hooks/ssrStub.ts
@@ -0,0 +1,100 @@
+import ContentfulOptimization from '@contentful/optimization-web'
+import type { EventEmissionResult, ResolvedData } from '@contentful/optimization-web/core-sdk'
+import type { Entry, EntrySkeletonType } from 'contentful'
+
+import type { OptimizationSdk } from '../context/OptimizationContext'
+
+function noop(): void {
+  // intentional no-op
+}
+
+interface StubSubscription {
+  unsubscribe: () => void
+}
+
+interface StubObservable<T> {
+  readonly current: T
+  subscribe: (next: (v: T) => void) => StubSubscription
+  subscribeOnce: (next: (v: NonNullable<T>) => void) => StubSubscription
+}
+
+function ssrObs<T>(current: T): StubObservable<T> {
+  return {
+    current,
+    subscribe: () => ({ unsubscribe: noop }),
+    subscribeOnce: () => ({ unsubscribe: noop }),
+  }
+}
+
+const SSR_STATES: OptimizationSdk['states'] = {
+  blockedEventStream: ssrObs(undefined),
+  canOptimize: ssrObs(false),
+  consent: ssrObs(undefined),
+  eventStream: ssrObs(undefined),
+  experienceRequestState: ssrObs({ status: 'idle' as const }),
+  flag: () => ssrObs(undefined),
+  locale: ssrObs(undefined),
+  optimizationPossible: ssrObs(false),
+  persistenceConsent: ssrObs(undefined),
+  previewPanelAttached: ssrObs(false),
+  previewPanelOpen: ssrObs(false),
+  profile: ssrObs(undefined),
+  selectedOptimizations: ssrObs(undefined),
+}
+
+const SSR_TRACKING: OptimizationSdk['tracking'] = {
+  clearElement: noop,
+  disable: noop,
+  disableElement: noop,
+  enable: noop,
+  enableElement: noop,
+}
+
+const NOT_ACCEPTED: EventEmissionResult = { accepted: false }
+
+function makeSsrStub(): OptimizationSdk {
+  const stub = {
+    consent: noop,
+    destroy: noop,
+    getFlag: () => undefined,
+    getMergeTagValue: () => undefined,
+    hasConsent: () => false,
+    identify: async () => {
+      await Promise.resolve()
+      return NOT_ACCEPTED
+    },
+    locale: undefined,
+    page: async () => {
+      await Promise.resolve()
+      return NOT_ACCEPTED
+    },
+    reset: noop,
+    resolveOptimizedEntry: (_entry: Entry): ResolvedData<EntrySkeletonType> => ({
+      entry: _entry,
+    }),
+    setLocale: () => undefined,
+    states: SSR_STATES,
+    track: async () => {
+      await Promise.resolve()
+      return NOT_ACCEPTED
+    },
+    trackClick: async () => {
+      await Promise.resolve()
+    },
+    trackView: async () => {
+      await Promise.resolve()
+      return NOT_ACCEPTED
+    },
+    tracking: SSR_TRACKING,
+  }
+
+  Object.setPrototypeOf(stub, ContentfulOptimization.prototype)
+
+  if (!(stub instanceof ContentfulOptimization)) {
+    throw new Error('Expected SSR stub to use the ContentfulOptimization prototype.')
+  }
+
+  return stub
+}
+
+export const SSR_STUB: OptimizationSdk = makeSsrStub()
diff --git a/packages/web/frameworks/react-web-sdk/src/hooks/useOptimization.ts b/packages/web/frameworks/react-web-sdk/src/hooks/useOptimization.ts
index d2792e18f..796e486d0 100644
--- a/packages/web/frameworks/react-web-sdk/src/hooks/useOptimization.ts
+++ b/packages/web/frameworks/react-web-sdk/src/hooks/useOptimization.ts
@@ -5,6 +5,7 @@ import {
   type OptimizationContextValue,
   type OptimizationSdk,
 } from '../context/OptimizationContext'
+import { SSR_STUB } from './ssrStub'
 
 function getMissingProviderError(): Error {
   return new Error(
@@ -38,10 +39,11 @@ export function useOptimization(): OptimizationSdk {
       })
     }
 
-    throw new Error(
-      'ContentfulOptimization SDK is still initializing. ' +
-        'This should not happen when using the loading gate in OptimizationProvider.',
-    )
+    // The SDK initializes in useLayoutEffect. Before that fires (during SSR and on the first
+    // client render), return a stub so components can render without throwing. All actual SDK
+    // method calls happen in effects or event handlers, which run after useLayoutEffect has
+    // already set the real SDK into context.
+    return SSR_STUB
   }
 
   return sdk
diff --git a/packages/web/frameworks/react-web-sdk/src/index.test.tsx b/packages/web/frameworks/react-web-sdk/src/index.test.tsx
index 2cfea12d8..8014fd843 100644
--- a/packages/web/frameworks/react-web-sdk/src/index.test.tsx
+++ b/packages/web/frameworks/react-web-sdk/src/index.test.tsx
@@ -159,8 +159,9 @@ describe('@contentful/optimization-react-web core providers', () => {
       </OptimizationProvider>,
     )
 
-    expect(markup).toBe('')
-    expect(renderedChild).toBe(false)
+    // Children render during SSR; the SDK constructor must never run on the server.
+    expect(markup).toMatchInlineSnapshot(`""`)
+    expect(renderedChild).toBe(true)
     expect(window.contentfulOptimization).toBeUndefined()
   })
 
@@ -546,7 +547,10 @@ describe('@contentful/optimization-react-web core providers', () => {
     renderClient(<FirstScenario />).unmount()
     renderClient(<SecondScenario />).unmount()
 
-    expect(results).toEqual([true, false, true])
+    // Children render twice per mount: once in the initial state (isReady: false) and once after
+    // useLayoutEffect fires and sets the owned SDK (isReady: true). The liveUpdates values are
+    // stable across both renders since they come from provider props, not SDK readiness.
+    expect(results).toEqual([true, false, true, false, true, true])
   })
 
   it('destroys the optimization singleton on provider unmount', () => {
diff --git a/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.onStatesReady.test.tsx b/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.onStatesReady.test.tsx
index c7569c612..b3d20a4fa 100644
--- a/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.onStatesReady.test.tsx
+++ b/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.onStatesReady.test.tsx
@@ -352,8 +352,9 @@ describe('OptimizationProvider onStatesReady', () => {
       </OptimizationProvider>,
     )
 
-    expect(markup).toBe('')
-    expect(childRendered).toBe(false)
+    // Children render during SSR; the SDK constructor must never run on the server.
+    expect(markup).toMatchInlineSnapshot(`""`)
+    expect(childRendered).toBe(true)
     expect(window.contentfulOptimization).toBeUndefined()
   })
 
diff --git a/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.tsx b/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.tsx
index eaa002daa..578290b9f 100644
--- a/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.tsx
+++ b/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.tsx
@@ -248,9 +248,12 @@ export function OptimizationProvider(props: OptimizationProviderProps): ReactEle
     }
   }, [liveLocale, props.sdk, state.sdk])
 
-  const shouldRenderChildren = state.isReady || state.error !== undefined
-
-  if (!shouldRenderChildren) {
+  // When onStatesReady is set, gate rendering until the callback has run — the app may subscribe
+  // to SDK state in the callback and children must not mount before that.
+  // Without onStatesReady, always render: the owned SDK initializes in useLayoutEffect and
+  // client components already guard on isReady/sdk in their own effects. This also allows
+  // Next.js SSR to produce HTML from server components that live inside the provider tree.
+  if (props.onStatesReady && !state.isReady && state.error === undefined) {
     return null
   }
 

From 15be51db99858931b4af99d405e0fc7990bc8edd Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 15:15:46 +0200
Subject: [PATCH 02/19] =?UTF-8?q?=F0=9F=92=A1=20refactor(nextjs-ssr):=20Cl?=
 =?UTF-8?q?ean=20up=20lib=20utilities=20and=20resolution=20module?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove unused `useManualViewTracking` hook and its `useOptimization` import
- Move `setAppConsent`/`getAppConsent` back into `util.ts`, delete `consent.ts`
- Fix double `resolveOptimizedEntry` call in `buildEntry` — cache result in variable
- Pass pre-resolved variant into `buildEntry` from `loadPageData` to avoid resolving twice
- Rename `applyMergeTags` → `resolveMergeTags`, flatten closure in merge tag walker into top-level `resolveMergeTagNode`
- Remove redundant `substituteMergeTags` wrapper
- Simplify `ResolvedPageData.resolve` from `flatMap` to `map + filter`
- Update AGENTS.md E2E flags note to match current `.env.example` (CSR,HYDRATION,SSR)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 implementations/nextjs-sdk_ssr/AGENTS.md      |  4 +-
 implementations/nextjs-sdk_ssr/lib/consent.ts | 10 ---
 implementations/nextjs-sdk_ssr/lib/hooks.ts   | 26 +------
 .../nextjs-sdk_ssr/lib/optimization.ts        |  2 +-
 .../nextjs-sdk_ssr/lib/resolution.ts          | 76 +++++++++----------
 implementations/nextjs-sdk_ssr/lib/util.ts    | 10 +++
 6 files changed, 51 insertions(+), 77 deletions(-)
 delete mode 100644 implementations/nextjs-sdk_ssr/lib/consent.ts

diff --git a/implementations/nextjs-sdk_ssr/AGENTS.md b/implementations/nextjs-sdk_ssr/AGENTS.md
index f8f894457..4de7d0f24 100644
--- a/implementations/nextjs-sdk_ssr/AGENTS.md
+++ b/implementations/nextjs-sdk_ssr/AGENTS.md
@@ -16,8 +16,8 @@ server/client SDK composition; app code imports only Next.js SDK subpaths.
 ## E2E tests
 
 - All E2E tests live in `lib/e2e-web`. Hydration-specific specs are gated with `runIf('HYDRATION')`
-  and run automatically when `E2E_FLAGS=CSR,HYDRATION`. The `SSR` flag is intentionally omitted
-  because full SSR variant resolution has a known bug.
+  and run automatically when `E2E_FLAGS=CSR,HYDRATION`. This implementation uses
+  `E2E_FLAGS=CSR,HYDRATION,SSR`.
 - Entry cards must expose `data-ctfl-entry-id` on the `content-*` element so shared selectors work.
 - `test:e2e` delegates to `lib/e2e-web`.
 
diff --git a/implementations/nextjs-sdk_ssr/lib/consent.ts b/implementations/nextjs-sdk_ssr/lib/consent.ts
deleted file mode 100644
index da081d6c3..000000000
--- a/implementations/nextjs-sdk_ssr/lib/consent.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import { appConfig } from './config'
-
-export function setAppConsent(consented: boolean): void {
-  const value = consented ? 'granted' : 'denied'
-  document.cookie = `${appConfig.personalizationConsentCookie}=${value}; Path=/; SameSite=Lax`
-}
-
-export function getAppConsent(cookies: { get(i: string): { value: string } | undefined }): boolean {
-  return cookies.get(appConfig.personalizationConsentCookie)?.value === 'granted'
-}
diff --git a/implementations/nextjs-sdk_ssr/lib/hooks.ts b/implementations/nextjs-sdk_ssr/lib/hooks.ts
index 5071456d7..dfeebefec 100644
--- a/implementations/nextjs-sdk_ssr/lib/hooks.ts
+++ b/implementations/nextjs-sdk_ssr/lib/hooks.ts
@@ -2,12 +2,11 @@
 
 import {
   useConsentState,
-  useOptimization,
   useOptimizationActions,
   useOptimizationContext,
 } from '@contentful/optimization-nextjs/client'
 import { useEffect, useReducer, useRef, useState } from 'react'
-import { setAppConsent } from './consent'
+import { setAppConsent } from './util'
 
 export function useConsent(): {
   consent: boolean | undefined
@@ -88,26 +87,3 @@ export function useFlagSubscription(flagName: string): unknown {
 
   return value
 }
-
-export function useManualViewTracking(
-  manualTracking: boolean | undefined,
-): (element: HTMLDivElement | null, entryId: string) => void {
-  const sdk = useOptimization()
-  const trackedElement = useRef<HTMLDivElement | null>(null)
-
-  useEffect(
-    () => () => {
-      const { current } = trackedElement
-      if (current) sdk.tracking.clearElement('views', current)
-    },
-    [sdk.tracking],
-  )
-
-  return (element: HTMLDivElement | null, entryId: string): void => {
-    const { current: previous } = trackedElement
-    if (previous && previous !== element) sdk.tracking.clearElement('views', previous)
-    trackedElement.current = element
-    if (!element || !manualTracking) return
-    sdk.tracking.enableElement('views', element, { data: { entryId } })
-  }
-}
diff --git a/implementations/nextjs-sdk_ssr/lib/optimization.ts b/implementations/nextjs-sdk_ssr/lib/optimization.ts
index 284a408cf..0d72293a9 100644
--- a/implementations/nextjs-sdk_ssr/lib/optimization.ts
+++ b/implementations/nextjs-sdk_ssr/lib/optimization.ts
@@ -5,7 +5,7 @@ import {
 import { cookies, headers } from 'next/headers'
 import { cache } from 'react'
 import { appConfig } from './config'
-import { getAppConsent } from './consent'
+import { getAppConsent } from './util'
 
 export const optimization = createNextjsOptimization({
   clientId: appConfig.clientId,
diff --git a/implementations/nextjs-sdk_ssr/lib/resolution.ts b/implementations/nextjs-sdk_ssr/lib/resolution.ts
index 5ec624312..3bfecc5cf 100644
--- a/implementations/nextjs-sdk_ssr/lib/resolution.ts
+++ b/implementations/nextjs-sdk_ssr/lib/resolution.ts
@@ -32,29 +32,30 @@ export interface ResolvedPageData {
   get(id: string): Entry | undefined
 }
 
-function substituteMergeTags(doc: RichTextDocument, profile: Profile): RichTextDocument {
-  const walk = (node: unknown): unknown => {
-    if (!isRecord(node)) return node
-    if (node.nodeType === INLINES.EMBEDDED_ENTRY && isRecord(node.data) && 'target' in node.data) {
-      const value = optimization.getMergeTagValue(node.data.target as never, profile) ?? ''
-      return { ...node, data: { ...node.data, resolvedValue: value } }
-    }
-    if (Array.isArray(node.content)) return { ...node, content: node.content.map(walk) }
-    return node
+function resolveMergeTagNode(node: unknown, profile: Profile): unknown {
+  if (!isRecord(node)) return node
+  if (node.nodeType === INLINES.EMBEDDED_ENTRY && isRecord(node.data) && 'target' in node.data) {
+    const value = optimization.getMergeTagValue(node.data.target as never, profile) ?? ''
+    return { ...node, data: { ...node.data, resolvedValue: value } }
   }
-  return walk(doc) as RichTextDocument
+  if (Array.isArray(node.content)) {
+    return { ...node, content: node.content.map((child) => resolveMergeTagNode(child, profile)) }
+  }
+  return node
 }
 
-function applyMergeTags(entry: ContentEntry, profile: Profile): ContentEntry {
-  const fields = Object.fromEntries(
-    Object.entries(entry.fields).map(([key, value]) => {
+function resolveMergeTags(
+  fields: ContentEntry['fields'],
+  profile: Profile,
+): ContentEntry['fields'] {
+  return Object.fromEntries(
+    Object.entries(fields).map(([key, value]) => {
       if (isRecord(value) && value.nodeType === 'document' && Array.isArray(value.content)) {
-        return [key, substituteMergeTags(value as unknown as RichTextDocument, profile)]
+        return [key, resolveMergeTagNode(value, profile) as RichTextDocument]
       }
       return [key, value]
     }),
   ) as ContentEntry['fields']
-  return { ...entry, fields }
 }
 
 function buildEntry(
@@ -63,34 +64,35 @@ function buildEntry(
   registry: Map<string, ContentEntry>,
   profile: Profile,
   visited: Set<string>,
+  preResolved?: ReturnType<typeof optimization.resolveOptimizedEntry>,
 ): Entry {
   visited.add(baselineEntry.sys.id)
 
+  const resolved =
+    preResolved ?? optimization.resolveOptimizedEntry(baselineEntry, selectedOptimizations)
   const resolvedData = {
-    ...optimization.resolveOptimizedEntry(baselineEntry, selectedOptimizations),
-    entry: resolveEntryLinks(
-      optimization.resolveOptimizedEntry(baselineEntry, selectedOptimizations)
-        .entry as ContentEntry,
-      registry,
-    ),
+    ...resolved,
+    entry: resolveEntryLinks(resolved.entry as ContentEntry, registry),
   } as ServerTrackingResolvedData
 
-  const withMergeTags = applyMergeTags(resolvedData.entry as ContentEntry, profile)
-
-  const nestedBaselines = Array.isArray(withMergeTags.fields.nested)
-    ? withMergeTags.fields.nested.filter(isEntry)
-    : []
+  const resolvedEntry = resolvedData.entry as ContentEntry
+  const fields = resolveMergeTags(resolvedEntry.fields, profile)
 
-  const nested = nestedBaselines
+  const nested = (Array.isArray(fields.nested) ? fields.nested.filter(isEntry) : [])
     .filter((n) => !visited.has(n.sys.id))
     .map((n) => buildEntry(n, selectedOptimizations, registry, profile, new Set(visited)))
 
-  const resolvedEntry: ResolvedEntry = {
-    ...withMergeTags,
-    fields: { ...withMergeTags.fields, nested: nested.length > 0 ? nested : undefined },
+  return {
+    baselineEntry,
+    resolvedData,
+    resolvedEntry: {
+      ...resolvedEntry,
+      fields: {
+        ...fields,
+        nested: nested.length > 0 ? nested : undefined,
+      } as unknown as ResolvedEntry['fields'],
+    },
   }
-
-  return { baselineEntry, resolvedData, resolvedEntry }
 }
 
 export async function loadPageData(entryIds: readonly string[]): Promise<ResolvedPageData> {
@@ -111,18 +113,14 @@ export async function loadPageData(entryIds: readonly string[]): Promise<Resolve
   )
 
   const byId = new Map(
-    entries.map((entry) => [
+    entries.map((entry, i) => [
       entry.sys.id,
-      buildEntry(entry, selectedOptimizations, registry, profile, new Set()),
+      buildEntry(entry, selectedOptimizations, registry, profile, new Set(), resolvedVariants[i]),
     ]),
   )
 
   return {
-    resolve: (ids) =>
-      ids.flatMap((id) => {
-        const e = byId.get(id)
-        return e ? [e] : []
-      }),
+    resolve: (ids) => ids.map((id) => byId.get(id)).filter((e): e is Entry => e !== undefined),
     get: (id) => byId.get(id),
   }
 }
diff --git a/implementations/nextjs-sdk_ssr/lib/util.ts b/implementations/nextjs-sdk_ssr/lib/util.ts
index 89c0dbf4d..6dfccd178 100644
--- a/implementations/nextjs-sdk_ssr/lib/util.ts
+++ b/implementations/nextjs-sdk_ssr/lib/util.ts
@@ -1,5 +1,15 @@
+import { appConfig } from './config'
 import type { ContentEntry } from './contentful'
 
+export function setAppConsent(consented: boolean): void {
+  const value = consented ? 'granted' : 'denied'
+  document.cookie = `${appConfig.personalizationConsentCookie}=${value}; Path=/; SameSite=Lax`
+}
+
+export function getAppConsent(cookies: { get(i: string): { value: string } | undefined }): boolean {
+  return cookies.get(appConfig.personalizationConsentCookie)?.value === 'granted'
+}
+
 export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null
 }

From c6f2bc37eeea6850a37311d3af30b1eec343ad84 Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 15:18:11 +0200
Subject: [PATCH 03/19] =?UTF-8?q?=F0=9F=92=A1=20refactor(nextjs-ssr):=20Re?=
 =?UTF-8?q?move=20unused=20Tailwind=20CSS=20setup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Delete app/globals.css (only contained @import 'tailwindcss', not imported anywhere)
- Delete postcss.config.mjs (only configured @tailwindcss/postcss plugin)
- Remove @tailwindcss/postcss, postcss, tailwindcss from devDependencies

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 implementations/nextjs-sdk_ssr/app/globals.css    | 1 -
 implementations/nextjs-sdk_ssr/package.json       | 3 ---
 implementations/nextjs-sdk_ssr/postcss.config.mjs | 7 -------
 3 files changed, 11 deletions(-)
 delete mode 100644 implementations/nextjs-sdk_ssr/app/globals.css
 delete mode 100644 implementations/nextjs-sdk_ssr/postcss.config.mjs

diff --git a/implementations/nextjs-sdk_ssr/app/globals.css b/implementations/nextjs-sdk_ssr/app/globals.css
deleted file mode 100644
index d4b507858..000000000
--- a/implementations/nextjs-sdk_ssr/app/globals.css
+++ /dev/null
@@ -1 +0,0 @@
-@import 'tailwindcss';
diff --git a/implementations/nextjs-sdk_ssr/package.json b/implementations/nextjs-sdk_ssr/package.json
index 15ac7ba2f..17ccc0ddc 100644
--- a/implementations/nextjs-sdk_ssr/package.json
+++ b/implementations/nextjs-sdk_ssr/package.json
@@ -38,7 +38,6 @@
     "react-dom": "19.2.5"
   },
   "devDependencies": {
-    "@tailwindcss/postcss": "4.1.11",
     "@types/node": "24.11.0",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
@@ -46,9 +45,7 @@
     "eslint": "9.29.0",
     "eslint-config-next": "16.2.4",
     "pm2": "6.0.14",
-    "postcss": "8.5.10",
     "rimraf": "6.1.3",
-    "tailwindcss": "4.1.11",
     "typescript": "5.9.3"
   }
 }
diff --git a/implementations/nextjs-sdk_ssr/postcss.config.mjs b/implementations/nextjs-sdk_ssr/postcss.config.mjs
deleted file mode 100644
index ae85b2fe4..000000000
--- a/implementations/nextjs-sdk_ssr/postcss.config.mjs
+++ /dev/null
@@ -1,7 +0,0 @@
-const config = {
-  plugins: {
-    '@tailwindcss/postcss': {},
-  },
-}
-
-export default config

From a198006304dc6a1a4ee4526d3dd0cabf5912ac6c Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 15:47:40 +0200
Subject: [PATCH 04/19] =?UTF-8?q?=F0=9F=92=A1=20refactor(nextjs-ssr):=20Fu?=
 =?UTF-8?q?rther=20cleanup=20of=20components=20and=20resolution=20logic?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- PreviewPanel: replace module-level mutable flag with useRef — scoped to component instance, safe across HMR
- GlobalLiveUpdatesProvider: remove useMemo — context value object was recreated every render anyway so memo had no effect
- Inline buildEntryRegistry into loadPageData — it was a one-call wrapper; two extendEntryRegistry calls collapsed into one by combining baseline and variant entries into a single pass
- Remove buildEntryRegistry export and toIdMap import from contentful.ts

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../components/GlobalLiveUpdatesProvider.tsx  | 17 +++++++--------
 .../components/PreviewPanel.tsx               | 21 ++++++-------------
 .../nextjs-sdk_ssr/lib/contentful.ts          | 10 +--------
 .../nextjs-sdk_ssr/lib/resolution.ts          | 15 +++++++------
 4 files changed, 21 insertions(+), 42 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/components/GlobalLiveUpdatesProvider.tsx b/implementations/nextjs-sdk_ssr/components/GlobalLiveUpdatesProvider.tsx
index a0c461594..35bfacf3a 100644
--- a/implementations/nextjs-sdk_ssr/components/GlobalLiveUpdatesProvider.tsx
+++ b/implementations/nextjs-sdk_ssr/components/GlobalLiveUpdatesProvider.tsx
@@ -1,7 +1,7 @@
 'use client'
 
 import { LiveUpdatesProvider } from '@contentful/optimization-nextjs/client'
-import { createContext, useContext, useMemo, useState, type JSX, type ReactNode } from 'react'
+import { createContext, useContext, useState, type JSX, type ReactNode } from 'react'
 
 interface GlobalLiveUpdatesContextValue {
   readonly globalLiveUpdates: boolean
@@ -26,15 +26,12 @@ export function GlobalLiveUpdatesProvider({
   readonly children: ReactNode
 }): JSX.Element {
   const [globalLiveUpdates, setGlobalLiveUpdates] = useState(false)
-  const value = useMemo<GlobalLiveUpdatesContextValue>(
-    () => ({
-      globalLiveUpdates,
-      onToggleGlobalLiveUpdates: () => {
-        setGlobalLiveUpdates((current) => !current)
-      },
-    }),
-    [globalLiveUpdates],
-  )
+  const value: GlobalLiveUpdatesContextValue = {
+    globalLiveUpdates,
+    onToggleGlobalLiveUpdates: () => {
+      setGlobalLiveUpdates((current) => !current)
+    },
+  }
 
   return (
     <GlobalLiveUpdatesContext.Provider value={value}>
diff --git a/implementations/nextjs-sdk_ssr/components/PreviewPanel.tsx b/implementations/nextjs-sdk_ssr/components/PreviewPanel.tsx
index 708452cd1..f151761fc 100644
--- a/implementations/nextjs-sdk_ssr/components/PreviewPanel.tsx
+++ b/implementations/nextjs-sdk_ssr/components/PreviewPanel.tsx
@@ -2,36 +2,27 @@
 
 import { appConfig } from '@/lib/config'
 import { useOptimizationContext } from '@contentful/optimization-nextjs/client'
-import { useEffect, type JSX } from 'react'
-
-let previewPanelAttachmentStarted = false
+import { useEffect, useRef, type JSX } from 'react'
 
 export function PreviewPanel(): JSX.Element | null {
   const { isReady, sdk } = useOptimizationContext()
+  const started = useRef(false)
 
   useEffect(() => {
-    if (
-      !appConfig.previewPanelEnabled ||
-      !isReady ||
-      sdk === undefined ||
-      previewPanelAttachmentStarted
-    ) {
+    if (!appConfig.previewPanelEnabled || !isReady || sdk === undefined || started.current) {
       return
     }
 
-    previewPanelAttachmentStarted = true
+    started.current = true
     void Promise.all([
       import('@contentful/optimization-web-preview-panel'),
       import('@/lib/contentful'),
     ])
       .then(async ([{ default: attachOptimizationPreviewPanel }, { client }]) => {
-        await attachOptimizationPreviewPanel({
-          contentful: client,
-          nonce: undefined,
-        })
+        await attachOptimizationPreviewPanel({ contentful: client, nonce: undefined })
       })
       .catch((error: unknown) => {
-        previewPanelAttachmentStarted = false
+        started.current = false
         console.warn('Failed to attach the Contentful Optimization preview panel.', error)
       })
   }, [isReady, sdk])
diff --git a/implementations/nextjs-sdk_ssr/lib/contentful.ts b/implementations/nextjs-sdk_ssr/lib/contentful.ts
index 8d132c83e..cd1fbdd64 100644
--- a/implementations/nextjs-sdk_ssr/lib/contentful.ts
+++ b/implementations/nextjs-sdk_ssr/lib/contentful.ts
@@ -2,7 +2,7 @@ import type { Document } from '@contentful/rich-text-types'
 import type { Entry, EntryFieldTypes, EntrySkeletonType } from 'contentful'
 import { createClient } from 'contentful'
 import { appConfig } from './config'
-import { collectLinkIds, toIdMap } from './util'
+import { collectLinkIds } from './util'
 
 export interface ContentEntryFields {
   text?: EntryFieldTypes.Text | EntryFieldTypes.RichText
@@ -65,11 +65,3 @@ export async function extendEntryRegistry(
     }
   }
 }
-
-export async function buildEntryRegistry(
-  entries: ContentEntry[],
-): Promise<Map<string, ContentEntry>> {
-  const registry = toIdMap(entries)
-  await extendEntryRegistry(registry, entries)
-  return registry
-}
diff --git a/implementations/nextjs-sdk_ssr/lib/resolution.ts b/implementations/nextjs-sdk_ssr/lib/resolution.ts
index 3bfecc5cf..10eb3feab 100644
--- a/implementations/nextjs-sdk_ssr/lib/resolution.ts
+++ b/implementations/nextjs-sdk_ssr/lib/resolution.ts
@@ -1,14 +1,13 @@
 import { type ServerTrackingResolvedData } from '@contentful/optimization-nextjs/server'
 import { INLINES } from '@contentful/rich-text-types'
 import {
-  buildEntryRegistry,
   extendEntryRegistry,
   loadPageEntries,
   type ContentEntry,
   type RichTextDocument,
 } from './contentful'
 import { getOptimizationData, optimization } from './optimization'
-import { isEntry, isRecord, resolveEntryLinks } from './util'
+import { isEntry, isRecord, resolveEntryLinks, toIdMap } from './util'
 
 type Profile = Parameters<typeof optimization.getMergeTagValue>[1]
 type SelectedOptimizations = Parameters<typeof optimization.resolveOptimizedEntry>[1]
@@ -102,15 +101,15 @@ export async function loadPageData(entryIds: readonly string[]): Promise<Resolve
   ])
   const selectedOptimizations = optimizationData?.selectedOptimizations
   const profile = optimizationData?.profile
-  const registry = await buildEntryRegistry(entries)
-
   const resolvedVariants = entries.map((entry) =>
     optimization.resolveOptimizedEntry(entry, selectedOptimizations),
   )
-  await extendEntryRegistry(
-    registry,
-    resolvedVariants.map((r) => r.entry as ContentEntry),
-  )
+
+  const registry = toIdMap(entries)
+  await extendEntryRegistry(registry, [
+    ...entries,
+    ...resolvedVariants.map((r) => r.entry as ContentEntry),
+  ])
 
   const byId = new Map(
     entries.map((entry, i) => [

From 0d937432553f8c947d66c788c095b2736a24c930 Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 17:29:43 +0200
Subject: [PATCH 05/19] =?UTF-8?q?=F0=9F=92=A1=20refactor(nextjs-ssr):=20Fe?=
 =?UTF-8?q?tch=20and=20resolve=20entry=20links=20lazily=20inside=20fetchEn?=
 =?UTF-8?q?try?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../nextjs-sdk_ssr/lib/contentful.ts          | 70 ++++++++++---------
 .../nextjs-sdk_ssr/lib/resolution.ts          | 30 +++-----
 implementations/nextjs-sdk_ssr/lib/util.ts    | 70 -------------------
 3 files changed, 46 insertions(+), 124 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/lib/contentful.ts b/implementations/nextjs-sdk_ssr/lib/contentful.ts
index cd1fbdd64..e27d7dde3 100644
--- a/implementations/nextjs-sdk_ssr/lib/contentful.ts
+++ b/implementations/nextjs-sdk_ssr/lib/contentful.ts
@@ -2,7 +2,7 @@ import type { Document } from '@contentful/rich-text-types'
 import type { Entry, EntryFieldTypes, EntrySkeletonType } from 'contentful'
 import { createClient } from 'contentful'
 import { appConfig } from './config'
-import { collectLinkIds } from './util'
+import { isRecord } from './util'
 
 export interface ContentEntryFields {
   text?: EntryFieldTypes.Text | EntryFieldTypes.RichText
@@ -26,42 +26,48 @@ export const client = createClient({
   ...(basePath ? { basePath } : {}),
 })
 
-async function fetchEntry(entryId: string): Promise<ContentEntry | undefined> {
+function isLink(value: unknown): value is { sys: { type: 'Link'; linkType: 'Entry'; id: string } } {
+  return (
+    isRecord(value) &&
+    isRecord(value.sys) &&
+    value.sys.type === 'Link' &&
+    value.sys.linkType === 'Entry' &&
+    typeof value.sys.id === 'string'
+  )
+}
+
+async function resolveField(value: unknown, visited: Set<string>): Promise<unknown> {
+  if (isLink(value)) {
+    const fetched = await fetchEntry(value.sys.id)
+    if (!fetched) return value
+    return resolveLinks(fetched, visited)
+  }
+  if (Array.isArray(value)) return Promise.all(value.map((item) => resolveField(item, visited)))
+  return value
+}
+
+async function resolveLinks(entry: ContentEntry, visited: Set<string>): Promise<ContentEntry> {
+  if (visited.has(entry.sys.id)) return entry
+  visited.add(entry.sys.id)
+  const resolvedFields = Object.fromEntries(
+    await Promise.all(
+      Object.entries(entry.fields).map(async ([key, value]) => [
+        key,
+        await resolveField(value, visited),
+      ]),
+    ),
+  ) as ContentEntry['fields']
+  return { ...entry, fields: resolvedFields }
+}
+
+export async function fetchEntry(entryId: string): Promise<ContentEntry | undefined> {
   try {
-    return await client.getEntry<ContentEntrySkeleton>(entryId, {
+    const entry = await client.getEntry<ContentEntrySkeleton>(entryId, {
       include: ENTRY_INCLUDE_DEPTH,
       locale: appConfig.locale,
     })
+    return resolveLinks(entry, new Set())
   } catch {
     return undefined
   }
 }
-
-export async function loadPageEntries(entryIds: readonly string[]): Promise<ContentEntry[]> {
-  const results = await Promise.all(entryIds.map(fetchEntry))
-  return results.filter((entry): entry is ContentEntry => entry !== undefined)
-}
-
-export async function extendEntryRegistry(
-  registry: Map<string, ContentEntry>,
-  entries: ContentEntry[],
-): Promise<void> {
-  const queue = new Set<string>()
-  for (const entry of entries) {
-    for (const id of collectLinkIds(entry)) {
-      if (!registry.has(id)) queue.add(id)
-    }
-  }
-  while (queue.size > 0) {
-    const fetched = await loadPageEntries([...queue])
-    queue.clear()
-    for (const entry of fetched) {
-      if (!registry.has(entry.sys.id)) {
-        registry.set(entry.sys.id, entry)
-        for (const id of collectLinkIds(entry)) {
-          if (!registry.has(id)) queue.add(id)
-        }
-      }
-    }
-  }
-}
diff --git a/implementations/nextjs-sdk_ssr/lib/resolution.ts b/implementations/nextjs-sdk_ssr/lib/resolution.ts
index 10eb3feab..1b87ce714 100644
--- a/implementations/nextjs-sdk_ssr/lib/resolution.ts
+++ b/implementations/nextjs-sdk_ssr/lib/resolution.ts
@@ -1,13 +1,8 @@
 import { type ServerTrackingResolvedData } from '@contentful/optimization-nextjs/server'
 import { INLINES } from '@contentful/rich-text-types'
-import {
-  extendEntryRegistry,
-  loadPageEntries,
-  type ContentEntry,
-  type RichTextDocument,
-} from './contentful'
+import { fetchEntry, type ContentEntry, type RichTextDocument } from './contentful'
 import { getOptimizationData, optimization } from './optimization'
-import { isEntry, isRecord, resolveEntryLinks, toIdMap } from './util'
+import { isEntry, isRecord } from './util'
 
 type Profile = Parameters<typeof optimization.getMergeTagValue>[1]
 type SelectedOptimizations = Parameters<typeof optimization.resolveOptimizedEntry>[1]
@@ -60,7 +55,6 @@ function resolveMergeTags(
 function buildEntry(
   baselineEntry: ContentEntry,
   selectedOptimizations: SelectedOptimizations,
-  registry: Map<string, ContentEntry>,
   profile: Profile,
   visited: Set<string>,
   preResolved?: ReturnType<typeof optimization.resolveOptimizedEntry>,
@@ -69,17 +63,13 @@ function buildEntry(
 
   const resolved =
     preResolved ?? optimization.resolveOptimizedEntry(baselineEntry, selectedOptimizations)
-  const resolvedData = {
-    ...resolved,
-    entry: resolveEntryLinks(resolved.entry as ContentEntry, registry),
-  } as ServerTrackingResolvedData
-
+  const resolvedData = resolved as ServerTrackingResolvedData
   const resolvedEntry = resolvedData.entry as ContentEntry
   const fields = resolveMergeTags(resolvedEntry.fields, profile)
 
   const nested = (Array.isArray(fields.nested) ? fields.nested.filter(isEntry) : [])
     .filter((n) => !visited.has(n.sys.id))
-    .map((n) => buildEntry(n, selectedOptimizations, registry, profile, new Set(visited)))
+    .map((n) => buildEntry(n, selectedOptimizations, profile, new Set(visited)))
 
   return {
     baselineEntry,
@@ -96,7 +86,9 @@ function buildEntry(
 
 export async function loadPageData(entryIds: readonly string[]): Promise<ResolvedPageData> {
   const [entries, { data: optimizationData }] = await Promise.all([
-    loadPageEntries(entryIds),
+    Promise.all(entryIds.map(fetchEntry)).then((r) =>
+      r.filter((e): e is ContentEntry => e !== undefined),
+    ),
     getOptimizationData(),
   ])
   const selectedOptimizations = optimizationData?.selectedOptimizations
@@ -105,16 +97,10 @@ export async function loadPageData(entryIds: readonly string[]): Promise<Resolve
     optimization.resolveOptimizedEntry(entry, selectedOptimizations),
   )
 
-  const registry = toIdMap(entries)
-  await extendEntryRegistry(registry, [
-    ...entries,
-    ...resolvedVariants.map((r) => r.entry as ContentEntry),
-  ])
-
   const byId = new Map(
     entries.map((entry, i) => [
       entry.sys.id,
-      buildEntry(entry, selectedOptimizations, registry, profile, new Set(), resolvedVariants[i]),
+      buildEntry(entry, selectedOptimizations, profile, new Set(), resolvedVariants[i]),
     ]),
   )
 
diff --git a/implementations/nextjs-sdk_ssr/lib/util.ts b/implementations/nextjs-sdk_ssr/lib/util.ts
index 6dfccd178..eb2b6818f 100644
--- a/implementations/nextjs-sdk_ssr/lib/util.ts
+++ b/implementations/nextjs-sdk_ssr/lib/util.ts
@@ -14,16 +14,6 @@ export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null
 }
 
-function isLink(value: unknown): value is { sys: { type: 'Link'; linkType: 'Entry'; id: string } } {
-  return (
-    isRecord(value) &&
-    isRecord(value.sys) &&
-    value.sys.type === 'Link' &&
-    value.sys.linkType === 'Entry' &&
-    typeof value.sys.id === 'string'
-  )
-}
-
 export function isEntry(value: unknown): value is ContentEntry {
   return (
     isRecord(value) &&
@@ -32,63 +22,3 @@ export function isEntry(value: unknown): value is ContentEntry {
     isRecord(value.fields)
   )
 }
-
-function resolveField(
-  value: unknown,
-  entryMap: Map<string, ContentEntry>,
-  visited: Set<string>,
-): unknown {
-  if (isLink(value)) {
-    const resolved = entryMap.get(value.sys.id)
-    if (!resolved) return value
-    return resolveEntryLinksInternal(resolved, entryMap, visited)
-  }
-  if (Array.isArray(value)) return value.map((item) => resolveField(item, entryMap, visited))
-  return value
-}
-
-function resolveEntryLinksInternal(
-  entry: ContentEntry,
-  entryMap: Map<string, ContentEntry>,
-  visited: Set<string>,
-): ContentEntry {
-  if (visited.has(entry.sys.id)) return entry
-  visited.add(entry.sys.id)
-  const resolvedFields = Object.fromEntries(
-    Object.entries(entry.fields).map(([key, value]) => [
-      key,
-      resolveField(value, entryMap, visited),
-    ]),
-  ) as ContentEntry['fields']
-  return { ...entry, fields: resolvedFields }
-}
-
-export function resolveEntryLinks(
-  entry: ContentEntry,
-  entryMap: Map<string, ContentEntry>,
-): ContentEntry {
-  return resolveEntryLinksInternal(entry, entryMap, new Set())
-}
-
-export function collectLinkIds(entry: ContentEntry, visited = new Set<string>()): string[] {
-  if (visited.has(entry.sys.id)) return []
-  visited.add(entry.sys.id)
-  const ids: string[] = []
-  for (const value of Object.values(entry.fields)) {
-    if (isLink(value)) {
-      ids.push(value.sys.id)
-    } else if (Array.isArray(value)) {
-      for (const item of value) {
-        if (isLink(item)) ids.push(item.sys.id)
-        else if (isEntry(item)) ids.push(...collectLinkIds(item, visited))
-      }
-    } else if (isEntry(value)) {
-      ids.push(...collectLinkIds(value, visited))
-    }
-  }
-  return ids
-}
-
-export function toIdMap<T extends { sys: { id: string } }>(items: T[]): Map<string, T> {
-  return new Map(items.map((item) => [item.sys.id, item]))
-}

From 8dc540ae75a5259042bb8a48acfd87d797605b4d Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 17:48:41 +0200
Subject: [PATCH 06/19] =?UTF-8?q?=F0=9F=92=A1=20refactor(nextjs-ssr):=20Co?=
 =?UTF-8?q?nsolidate=20optimization=20logic=20into=20ServerOptimization=20?=
 =?UTF-8?q?class?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 implementations/nextjs-sdk_ssr/app/layout.tsx |   4 +-
 .../nextjs-sdk_ssr/app/page-two/page.tsx      |  10 +-
 implementations/nextjs-sdk_ssr/app/page.tsx   |  14 +-
 .../nextjs-sdk_ssr/components/EntryCard.tsx   |   2 +-
 .../nextjs-sdk_ssr/lib/optimization.ts        | 147 +++++++++++++++---
 .../nextjs-sdk_ssr/lib/resolution.ts          | 111 -------------
 6 files changed, 140 insertions(+), 148 deletions(-)
 delete mode 100644 implementations/nextjs-sdk_ssr/lib/resolution.ts

diff --git a/implementations/nextjs-sdk_ssr/app/layout.tsx b/implementations/nextjs-sdk_ssr/app/layout.tsx
index 7c5bff7c0..fb0dd68b6 100644
--- a/implementations/nextjs-sdk_ssr/app/layout.tsx
+++ b/implementations/nextjs-sdk_ssr/app/layout.tsx
@@ -2,7 +2,7 @@ import { GlobalLiveUpdatesProvider } from '@/components/GlobalLiveUpdatesProvide
 import { PreviewPanel } from '@/components/PreviewPanel'
 import { TrackingLog } from '@/components/TrackingLog'
 import { appConfig } from '@/lib/config'
-import { getOptimizationData } from '@/lib/optimization'
+import { optimization } from '@/lib/optimization'
 import { NextAppAutoPageTracker, OptimizationRoot } from '@contentful/optimization-nextjs/client'
 import 'e2e-web/theme.css'
 import type { Metadata } from 'next'
@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const dynamic = 'force-dynamic'
 
 export default async function RootLayout({ children }: Readonly<{ children: ReactNode }>) {
-  const { data: optimizationData, hasConsent } = await getOptimizationData()
+  const { data: optimizationData, hasConsent } = await optimization.getOptimizationData()
   const defaults = optimizationData
     ? {
         profile: optimizationData.profile,
diff --git a/implementations/nextjs-sdk_ssr/app/page-two/page.tsx b/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
index 4eafbc1a4..b9c0a3c6d 100644
--- a/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
+++ b/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
@@ -1,15 +1,15 @@
 import { ControlPanel } from '@/components/ControlPanel'
 import { CustomViewTracker } from '@/components/CustomViewTracker'
 import { EntryCard } from '@/components/EntryCard'
-import { loadPageData } from '@/lib/resolution'
+import { optimization } from '@/lib/optimization'
 import { PAGES } from 'e2e-web'
 import Link from 'next/link'
 
 export default async function PageTwo() {
-  const data = await loadPageData(PAGES.pageTwo.ids)
-
-  const auto = data.get(PAGES.pageTwo.auto)
-  const manual = data.get(PAGES.pageTwo.manual)
+  const [auto, manual] = await Promise.all([
+    optimization.getEntry(PAGES.pageTwo.auto),
+    optimization.getEntry(PAGES.pageTwo.manual),
+  ])
 
   return (
     <section data-testid="page-two-view">
diff --git a/implementations/nextjs-sdk_ssr/app/page.tsx b/implementations/nextjs-sdk_ssr/app/page.tsx
index 711a0c9ba..9c7b12dd4 100644
--- a/implementations/nextjs-sdk_ssr/app/page.tsx
+++ b/implementations/nextjs-sdk_ssr/app/page.tsx
@@ -1,12 +1,16 @@
 import { ControlPanel } from '@/components/ControlPanel'
 import { EntryCard } from '@/components/EntryCard'
-import { loadPageData } from '@/lib/resolution'
+import { optimization } from '@/lib/optimization'
 import { CLICK_SCENARIOS, PAGES } from 'e2e-web'
 
 export default async function Home() {
-  const data = await loadPageData(PAGES.home.ids)
+  const [liveUpdates, auto, manual] = await Promise.all([
+    optimization.getEntry(PAGES.home.liveUpdates),
+    optimization.getEntries(PAGES.home.auto),
+    optimization.getEntries(PAGES.home.manual),
+  ])
 
-  const liveUpdatesEntry = data.get(PAGES.home.liveUpdates)?.baselineEntry
+  const liveUpdatesEntry = liveUpdates?.baselineEntry
 
   return (
     <>
@@ -56,7 +60,7 @@ export default async function Home() {
             <h2>Auto Observed Entries</h2>
           </header>
           <div id="auto-observed" className="entry-grid">
-            {data.resolve(PAGES.home.auto).map((entry) => (
+            {auto.map((entry) => (
               <EntryCard
                 key={entry.baselineEntry.sys.id}
                 entry={entry}
@@ -72,7 +76,7 @@ export default async function Home() {
             <h2>Manually Observed Entries</h2>
           </header>
           <div id="manually-observed" className="entry-grid">
-            {data.resolve(PAGES.home.manual).map((entry) => (
+            {manual.map((entry) => (
               <EntryCard key={entry.baselineEntry.sys.id} entry={entry} manualTracking={true} />
             ))}
           </div>
diff --git a/implementations/nextjs-sdk_ssr/components/EntryCard.tsx b/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
index f27a57b53..16b756c36 100644
--- a/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
+++ b/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
@@ -1,6 +1,6 @@
 import { EntryCardClient } from '@/components/EntryCard.client'
 import type { ContentEntry, RichTextDocument } from '@/lib/contentful'
-import type { Entry } from '@/lib/resolution'
+import type { Entry } from '@/lib/optimization'
 import { isRecord } from '@/lib/util'
 import { ServerOptimizedEntry } from '@contentful/optimization-nextjs/server'
 import { documentToReactComponents, type Options } from '@contentful/rich-text-react-renderer'
diff --git a/implementations/nextjs-sdk_ssr/lib/optimization.ts b/implementations/nextjs-sdk_ssr/lib/optimization.ts
index 0d72293a9..739dbc7f2 100644
--- a/implementations/nextjs-sdk_ssr/lib/optimization.ts
+++ b/implementations/nextjs-sdk_ssr/lib/optimization.ts
@@ -1,34 +1,133 @@
 import {
   createNextjsOptimization,
   getNextjsServerOptimizationData,
+  type ServerTrackingResolvedData,
 } from '@contentful/optimization-nextjs/server'
+import { INLINES } from '@contentful/rich-text-types'
 import { cookies, headers } from 'next/headers'
 import { cache } from 'react'
 import { appConfig } from './config'
-import { getAppConsent } from './util'
-
-export const optimization = createNextjsOptimization({
-  clientId: appConfig.clientId,
-  environment: appConfig.environment,
-  locale: appConfig.locale,
-  logLevel: 'debug',
-  api: appConfig.api,
-  app: {
-    name: 'Contentful Optimization Next.js SDK SSR (Server)',
-    version: '0.1.0',
-  },
-})
-
-export const getOptimizationData = cache(async () => {
-  const cookieStore = await cookies()
-  const headerStore = await headers()
-  const hasConsent = getAppConsent(cookieStore)
-  const { data } = await getNextjsServerOptimizationData(optimization, {
-    consent: { events: hasConsent, persistence: hasConsent },
-    cookies: hasConsent ? cookieStore : undefined,
-    headers: headerStore,
+import { fetchEntry, type ContentEntry, type RichTextDocument } from './contentful'
+import { getAppConsent, isEntry, isRecord } from './util'
+
+type Profile = Parameters<ReturnType<typeof createNextjsOptimization>['getMergeTagValue']>[1]
+type SelectedOptimizations = Parameters<
+  ReturnType<typeof createNextjsOptimization>['resolveOptimizedEntry']
+>[1]
+
+export interface ResolvedEntry extends Omit<ContentEntry, 'fields'> {
+  fields: Omit<ContentEntry['fields'], 'nested'> & {
+    nested?: Entry[]
+  }
+}
+
+export interface Entry {
+  baselineEntry: ContentEntry
+  /** Raw resolved data for the SDK (ServerOptimizedEntry). entry is a vanilla ContentEntry. */
+  resolvedData: ServerTrackingResolvedData
+  /** Resolved entry for rendering — fields.nested contains resolved Entry children. */
+  resolvedEntry: ResolvedEntry
+}
+
+class ServerOptimization {
+  private readonly sdk = createNextjsOptimization({
+    clientId: appConfig.clientId,
+    environment: appConfig.environment,
     locale: appConfig.locale,
+    logLevel: 'debug',
+    api: appConfig.api,
+    app: {
+      name: 'Contentful Optimization Next.js SDK SSR (Server)',
+      version: '0.1.0',
+    },
   })
 
-  return { data, hasConsent }
-})
+  readonly getOptimizationData = cache(async () => {
+    const cookieStore = await cookies()
+    const headerStore = await headers()
+    const hasConsent = getAppConsent(cookieStore)
+    const { data } = await getNextjsServerOptimizationData(this.sdk, {
+      consent: { events: hasConsent, persistence: hasConsent },
+      cookies: hasConsent ? cookieStore : undefined,
+      headers: headerStore,
+      locale: appConfig.locale,
+    })
+
+    return { data, hasConsent }
+  })
+
+  private resolveMergeTagNode(node: unknown, profile: Profile): unknown {
+    if (!isRecord(node)) return node
+    if (node.nodeType === INLINES.EMBEDDED_ENTRY && isRecord(node.data) && 'target' in node.data) {
+      const value = this.sdk.getMergeTagValue(node.data.target as never, profile) ?? ''
+      return { ...node, data: { ...node.data, resolvedValue: value } }
+    }
+    if (Array.isArray(node.content)) {
+      return {
+        ...node,
+        content: node.content.map((child) => this.resolveMergeTagNode(child, profile)),
+      }
+    }
+    return node
+  }
+
+  private resolveMergeTags(
+    fields: ContentEntry['fields'],
+    profile: Profile,
+  ): ContentEntry['fields'] {
+    return Object.fromEntries(
+      Object.entries(fields).map(([key, value]) => {
+        if (isRecord(value) && value.nodeType === 'document' && Array.isArray(value.content)) {
+          return [key, this.resolveMergeTagNode(value, profile) as RichTextDocument]
+        }
+        return [key, value]
+      }),
+    ) as ContentEntry['fields']
+  }
+
+  private buildEntry(
+    baselineEntry: ContentEntry,
+    selectedOptimizations: SelectedOptimizations,
+    profile: Profile,
+    visited: Set<string>,
+    preResolved?: ReturnType<typeof this.sdk.resolveOptimizedEntry>,
+  ): Entry {
+    visited.add(baselineEntry.sys.id)
+
+    const resolved =
+      preResolved ?? this.sdk.resolveOptimizedEntry(baselineEntry, selectedOptimizations)
+    const resolvedData = resolved as ServerTrackingResolvedData
+    const resolvedEntry = resolvedData.entry as ContentEntry
+    const fields = this.resolveMergeTags(resolvedEntry.fields, profile)
+
+    const nested = (Array.isArray(fields.nested) ? fields.nested.filter(isEntry) : [])
+      .filter((n) => !visited.has(n.sys.id))
+      .map((n) => this.buildEntry(n, selectedOptimizations, profile, new Set(visited)))
+
+    return {
+      baselineEntry,
+      resolvedData,
+      resolvedEntry: {
+        ...resolvedEntry,
+        fields: {
+          ...fields,
+          nested: nested.length > 0 ? nested : undefined,
+        } as unknown as ResolvedEntry['fields'],
+      },
+    }
+  }
+
+  async getEntry(id: string): Promise<Entry | undefined> {
+    const entry = await fetchEntry(id)
+    if (!entry) return undefined
+    const { data } = await this.getOptimizationData()
+    return this.buildEntry(entry, data?.selectedOptimizations, data?.profile, new Set())
+  }
+
+  async getEntries(ids: readonly string[]): Promise<Entry[]> {
+    const results = await Promise.all(ids.map((id) => this.getEntry(id)))
+    return results.filter((e): e is Entry => e !== undefined)
+  }
+}
+
+export const optimization = new ServerOptimization()
diff --git a/implementations/nextjs-sdk_ssr/lib/resolution.ts b/implementations/nextjs-sdk_ssr/lib/resolution.ts
deleted file mode 100644
index 1b87ce714..000000000
--- a/implementations/nextjs-sdk_ssr/lib/resolution.ts
+++ /dev/null
@@ -1,111 +0,0 @@
-import { type ServerTrackingResolvedData } from '@contentful/optimization-nextjs/server'
-import { INLINES } from '@contentful/rich-text-types'
-import { fetchEntry, type ContentEntry, type RichTextDocument } from './contentful'
-import { getOptimizationData, optimization } from './optimization'
-import { isEntry, isRecord } from './util'
-
-type Profile = Parameters<typeof optimization.getMergeTagValue>[1]
-type SelectedOptimizations = Parameters<typeof optimization.resolveOptimizedEntry>[1]
-
-export interface ResolvedEntry extends Omit<ContentEntry, 'fields'> {
-  fields: Omit<ContentEntry['fields'], 'nested'> & {
-    nested?: Entry[]
-  }
-}
-
-export interface Entry {
-  baselineEntry: ContentEntry
-  /** Raw resolved data for the SDK (ServerOptimizedEntry). entry is a vanilla ContentEntry. */
-  resolvedData: ServerTrackingResolvedData
-  /** Resolved entry for rendering — fields.nested contains resolved Entry children. */
-  resolvedEntry: ResolvedEntry
-}
-
-export interface ResolvedPageData {
-  resolve(ids: readonly string[]): Entry[]
-  get(id: string): Entry | undefined
-}
-
-function resolveMergeTagNode(node: unknown, profile: Profile): unknown {
-  if (!isRecord(node)) return node
-  if (node.nodeType === INLINES.EMBEDDED_ENTRY && isRecord(node.data) && 'target' in node.data) {
-    const value = optimization.getMergeTagValue(node.data.target as never, profile) ?? ''
-    return { ...node, data: { ...node.data, resolvedValue: value } }
-  }
-  if (Array.isArray(node.content)) {
-    return { ...node, content: node.content.map((child) => resolveMergeTagNode(child, profile)) }
-  }
-  return node
-}
-
-function resolveMergeTags(
-  fields: ContentEntry['fields'],
-  profile: Profile,
-): ContentEntry['fields'] {
-  return Object.fromEntries(
-    Object.entries(fields).map(([key, value]) => {
-      if (isRecord(value) && value.nodeType === 'document' && Array.isArray(value.content)) {
-        return [key, resolveMergeTagNode(value, profile) as RichTextDocument]
-      }
-      return [key, value]
-    }),
-  ) as ContentEntry['fields']
-}
-
-function buildEntry(
-  baselineEntry: ContentEntry,
-  selectedOptimizations: SelectedOptimizations,
-  profile: Profile,
-  visited: Set<string>,
-  preResolved?: ReturnType<typeof optimization.resolveOptimizedEntry>,
-): Entry {
-  visited.add(baselineEntry.sys.id)
-
-  const resolved =
-    preResolved ?? optimization.resolveOptimizedEntry(baselineEntry, selectedOptimizations)
-  const resolvedData = resolved as ServerTrackingResolvedData
-  const resolvedEntry = resolvedData.entry as ContentEntry
-  const fields = resolveMergeTags(resolvedEntry.fields, profile)
-
-  const nested = (Array.isArray(fields.nested) ? fields.nested.filter(isEntry) : [])
-    .filter((n) => !visited.has(n.sys.id))
-    .map((n) => buildEntry(n, selectedOptimizations, profile, new Set(visited)))
-
-  return {
-    baselineEntry,
-    resolvedData,
-    resolvedEntry: {
-      ...resolvedEntry,
-      fields: {
-        ...fields,
-        nested: nested.length > 0 ? nested : undefined,
-      } as unknown as ResolvedEntry['fields'],
-    },
-  }
-}
-
-export async function loadPageData(entryIds: readonly string[]): Promise<ResolvedPageData> {
-  const [entries, { data: optimizationData }] = await Promise.all([
-    Promise.all(entryIds.map(fetchEntry)).then((r) =>
-      r.filter((e): e is ContentEntry => e !== undefined),
-    ),
-    getOptimizationData(),
-  ])
-  const selectedOptimizations = optimizationData?.selectedOptimizations
-  const profile = optimizationData?.profile
-  const resolvedVariants = entries.map((entry) =>
-    optimization.resolveOptimizedEntry(entry, selectedOptimizations),
-  )
-
-  const byId = new Map(
-    entries.map((entry, i) => [
-      entry.sys.id,
-      buildEntry(entry, selectedOptimizations, profile, new Set(), resolvedVariants[i]),
-    ]),
-  )
-
-  return {
-    resolve: (ids) => ids.map((id) => byId.get(id)).filter((e): e is Entry => e !== undefined),
-    get: (id) => byId.get(id),
-  }
-}

From a7a06791e0f5ba196177821cad0f18ced70a19d8 Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 17:56:43 +0200
Subject: [PATCH 07/19] =?UTF-8?q?=F0=9F=92=A1=20refactor(nextjs-ssr):=20Fi?=
 =?UTF-8?q?nalize=20ServerOptimization=20API=20and=20clean=20up=20public/p?=
 =?UTF-8?q?rivate=20boundary?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 implementations/nextjs-sdk_ssr/app/layout.tsx | 15 +----
 .../nextjs-sdk_ssr/app/page-two/page.tsx      |  5 +-
 .../nextjs-sdk_ssr/lib/optimization.ts        | 64 ++++++++++++-------
 3 files changed, 44 insertions(+), 40 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/app/layout.tsx b/implementations/nextjs-sdk_ssr/app/layout.tsx
index fb0dd68b6..796394225 100644
--- a/implementations/nextjs-sdk_ssr/app/layout.tsx
+++ b/implementations/nextjs-sdk_ssr/app/layout.tsx
@@ -18,18 +18,7 @@ export const metadata: Metadata = {
 export const dynamic = 'force-dynamic'
 
 export default async function RootLayout({ children }: Readonly<{ children: ReactNode }>) {
-  const { data: optimizationData, hasConsent } = await optimization.getOptimizationData()
-  const defaults = optimizationData
-    ? {
-        profile: optimizationData.profile,
-        ...(hasConsent
-          ? {
-              selectedOptimizations: optimizationData.selectedOptimizations,
-              changes: optimizationData.changes,
-            }
-          : {}),
-      }
-    : undefined
+  const { defaults, initialPageEvent } = await optimization.getServerState()
 
   return (
     <html lang={appConfig.locale.split('-')[0]}>
@@ -49,7 +38,7 @@ export default async function RootLayout({ children }: Readonly<{ children: Reac
         >
           <GlobalLiveUpdatesProvider>
             <PreviewPanel />
-            <NextAppAutoPageTracker initialPageEvent={hasConsent ? 'skip' : 'emit'} />
+            <NextAppAutoPageTracker initialPageEvent={initialPageEvent} />
             <div className="app-shell">
               <nav>
                 <Link data-testid="link-home" href="/">
diff --git a/implementations/nextjs-sdk_ssr/app/page-two/page.tsx b/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
index b9c0a3c6d..3bac27816 100644
--- a/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
+++ b/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
@@ -6,10 +6,7 @@ import { PAGES } from 'e2e-web'
 import Link from 'next/link'
 
 export default async function PageTwo() {
-  const [auto, manual] = await Promise.all([
-    optimization.getEntry(PAGES.pageTwo.auto),
-    optimization.getEntry(PAGES.pageTwo.manual),
-  ])
+  const [auto, manual] = await optimization.getEntries([PAGES.pageTwo.auto, PAGES.pageTwo.manual])
 
   return (
     <section data-testid="page-two-view">
diff --git a/implementations/nextjs-sdk_ssr/lib/optimization.ts b/implementations/nextjs-sdk_ssr/lib/optimization.ts
index 739dbc7f2..972e09c76 100644
--- a/implementations/nextjs-sdk_ssr/lib/optimization.ts
+++ b/implementations/nextjs-sdk_ssr/lib/optimization.ts
@@ -30,6 +30,8 @@ export interface Entry {
 }
 
 class ServerOptimization {
+  // --- private ---
+
   private readonly sdk = createNextjsOptimization({
     clientId: appConfig.clientId,
     environment: appConfig.environment,
@@ -42,7 +44,7 @@ class ServerOptimization {
     },
   })
 
-  readonly getOptimizationData = cache(async () => {
+  private readonly fetchOptimizationData = cache(async () => {
     const cookieStore = await cookies()
     const headerStore = await headers()
     const hasConsent = getAppConsent(cookieStore)
@@ -56,29 +58,30 @@ class ServerOptimization {
     return { data, hasConsent }
   })
 
-  private resolveMergeTagNode(node: unknown, profile: Profile): unknown {
-    if (!isRecord(node)) return node
-    if (node.nodeType === INLINES.EMBEDDED_ENTRY && isRecord(node.data) && 'target' in node.data) {
-      const value = this.sdk.getMergeTagValue(node.data.target as never, profile) ?? ''
-      return { ...node, data: { ...node.data, resolvedValue: value } }
-    }
-    if (Array.isArray(node.content)) {
-      return {
-        ...node,
-        content: node.content.map((child) => this.resolveMergeTagNode(child, profile)),
-      }
-    }
-    return node
-  }
-
   private resolveMergeTags(
     fields: ContentEntry['fields'],
     profile: Profile,
   ): ContentEntry['fields'] {
+    const resolveNode = (node: unknown): unknown => {
+      if (!isRecord(node)) return node
+      if (
+        node.nodeType === INLINES.EMBEDDED_ENTRY &&
+        isRecord(node.data) &&
+        'target' in node.data
+      ) {
+        const value = this.sdk.getMergeTagValue(node.data.target as never, profile) ?? ''
+        return { ...node, data: { ...node.data, resolvedValue: value } }
+      }
+      if (Array.isArray(node.content)) {
+        return { ...node, content: node.content.map(resolveNode) }
+      }
+      return node
+    }
+
     return Object.fromEntries(
       Object.entries(fields).map(([key, value]) => {
         if (isRecord(value) && value.nodeType === 'document' && Array.isArray(value.content)) {
-          return [key, this.resolveMergeTagNode(value, profile) as RichTextDocument]
+          return [key, resolveNode(value) as RichTextDocument]
         }
         return [key, value]
       }),
@@ -90,12 +93,10 @@ class ServerOptimization {
     selectedOptimizations: SelectedOptimizations,
     profile: Profile,
     visited: Set<string>,
-    preResolved?: ReturnType<typeof this.sdk.resolveOptimizedEntry>,
   ): Entry {
     visited.add(baselineEntry.sys.id)
 
-    const resolved =
-      preResolved ?? this.sdk.resolveOptimizedEntry(baselineEntry, selectedOptimizations)
+    const resolved = this.sdk.resolveOptimizedEntry(baselineEntry, selectedOptimizations)
     const resolvedData = resolved as ServerTrackingResolvedData
     const resolvedEntry = resolvedData.entry as ContentEntry
     const fields = this.resolveMergeTags(resolvedEntry.fields, profile)
@@ -117,14 +118,31 @@ class ServerOptimization {
     }
   }
 
-  async getEntry(id: string): Promise<Entry | undefined> {
+  // --- public ---
+
+  public async getServerState() {
+    const { data, hasConsent } = await this.fetchOptimizationData()
+    return {
+      defaults: data
+        ? {
+            profile: data.profile,
+            ...(hasConsent
+              ? { selectedOptimizations: data.selectedOptimizations, changes: data.changes }
+              : {}),
+          }
+        : undefined,
+      initialPageEvent: hasConsent ? ('skip' as const) : ('emit' as const),
+    }
+  }
+
+  public async getEntry(id: string): Promise<Entry | undefined> {
     const entry = await fetchEntry(id)
     if (!entry) return undefined
-    const { data } = await this.getOptimizationData()
+    const { data } = await this.fetchOptimizationData()
     return this.buildEntry(entry, data?.selectedOptimizations, data?.profile, new Set())
   }
 
-  async getEntries(ids: readonly string[]): Promise<Entry[]> {
+  public async getEntries(ids: readonly string[]): Promise<Entry[]> {
     const results = await Promise.all(ids.map((id) => this.getEntry(id)))
     return results.filter((e): e is Entry => e !== undefined)
   }

From b373f3454c8cc979fb92a82a7e5d1cffe381aef6 Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 18:11:24 +0200
Subject: [PATCH 08/19] =?UTF-8?q?=E2=9C=A8=20feat(nextjs-ssr):=20Pass=20se?=
 =?UTF-8?q?rver-side=20consent,=20identified=20and=20optimization=20count?=
 =?UTF-8?q?=20to=20ControlPanel?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../nextjs-sdk_ssr/app/page-two/page.tsx      | 13 ++++++++++--
 implementations/nextjs-sdk_ssr/app/page.tsx   | 18 ++++++++++------
 .../components/ControlPanel.tsx               | 21 +++++++++++++++----
 implementations/nextjs-sdk_ssr/lib/hooks.ts   |  5 +++--
 .../nextjs-sdk_ssr/lib/optimization.ts        |  3 +++
 5 files changed, 46 insertions(+), 14 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/app/page-two/page.tsx b/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
index 3bac27816..78fe48953 100644
--- a/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
+++ b/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
@@ -6,7 +6,11 @@ import { PAGES } from 'e2e-web'
 import Link from 'next/link'
 
 export default async function PageTwo() {
-  const [auto, manual] = await optimization.getEntries([PAGES.pageTwo.auto, PAGES.pageTwo.manual])
+  const [{ hasConsent, isIdentified, activeOptimizationsCount }, [auto, manual]] =
+    await Promise.all([
+      optimization.getServerState(),
+      optimization.getEntries([PAGES.pageTwo.auto, PAGES.pageTwo.manual]),
+    ])
 
   return (
     <section data-testid="page-two-view">
@@ -18,7 +22,12 @@ export default async function PageTwo() {
       </div>
 
       <CustomViewTracker componentId="page-two-hero" />
-      <ControlPanel demoCTA />
+      <ControlPanel
+        demoCTA
+        initialConsent={hasConsent}
+        initialIsIdentified={isIdentified}
+        initialActiveOptimizationsCount={activeOptimizationsCount}
+      />
 
       <div className="sections-grid sections-grid--split" data-testid="page-two-optimization">
         <section className="page-section">
diff --git a/implementations/nextjs-sdk_ssr/app/page.tsx b/implementations/nextjs-sdk_ssr/app/page.tsx
index 9c7b12dd4..1ba5290cf 100644
--- a/implementations/nextjs-sdk_ssr/app/page.tsx
+++ b/implementations/nextjs-sdk_ssr/app/page.tsx
@@ -4,11 +4,13 @@ import { optimization } from '@/lib/optimization'
 import { CLICK_SCENARIOS, PAGES } from 'e2e-web'
 
 export default async function Home() {
-  const [liveUpdates, auto, manual] = await Promise.all([
-    optimization.getEntry(PAGES.home.liveUpdates),
-    optimization.getEntries(PAGES.home.auto),
-    optimization.getEntries(PAGES.home.manual),
-  ])
+  const [{ hasConsent, isIdentified, activeOptimizationsCount }, liveUpdates, auto, manual] =
+    await Promise.all([
+      optimization.getServerState(),
+      optimization.getEntry(PAGES.home.liveUpdates),
+      optimization.getEntries(PAGES.home.auto),
+      optimization.getEntries(PAGES.home.manual),
+    ])
 
   const liveUpdatesEntry = liveUpdates?.baselineEntry
 
@@ -22,7 +24,11 @@ export default async function Home() {
         </p>
       </div>
 
-      <ControlPanel />
+      <ControlPanel
+        initialConsent={hasConsent}
+        initialIsIdentified={isIdentified}
+        initialActiveOptimizationsCount={activeOptimizationsCount}
+      />
 
       <section className="page-section" data-testid="live-updates-section">
         <header className="page-section__header">
diff --git a/implementations/nextjs-sdk_ssr/components/ControlPanel.tsx b/implementations/nextjs-sdk_ssr/components/ControlPanel.tsx
index d7deaafe1..f23e752cc 100644
--- a/implementations/nextjs-sdk_ssr/components/ControlPanel.tsx
+++ b/implementations/nextjs-sdk_ssr/components/ControlPanel.tsx
@@ -12,16 +12,29 @@ import {
 } from '@contentful/optimization-nextjs/client'
 import type { JSX } from 'react'
 
-export function ControlPanel({ demoCTA }: { readonly demoCTA?: boolean } = {}): JSX.Element {
+interface ControlPanelProps {
+  readonly demoCTA?: boolean
+  readonly initialConsent?: boolean
+  readonly initialIsIdentified?: boolean
+  readonly initialActiveOptimizationsCount?: number
+}
+
+export function ControlPanel({
+  demoCTA,
+  initialConsent,
+  initialIsIdentified = false,
+  initialActiveOptimizationsCount = 0,
+}: ControlPanelProps = {}): JSX.Element {
   const sdk = useOptimization()
   const { identify, reset } = useOptimizationActions()
-  const { consent, setConsent } = useConsent()
+  const { consent, setConsent } = useConsent(initialConsent)
   const profile = useProfileState()
   const selectedOptimizations = useSelectedOptimizationsState()
   const { globalLiveUpdates, onToggleGlobalLiveUpdates } = useGlobalLiveUpdatesControls()
   const { previewPanelVisible, setPreviewPanelVisible } = useLiveUpdates()
   const booleanFlag = useFlagSubscription('boolean')
-  const isIdentified = Boolean(profile?.traits.identified)
+  const isIdentified = profile ? Boolean(profile.traits.identified) : initialIsIdentified
+  const activeCount = selectedOptimizations?.length ?? initialActiveOptimizationsCount
 
   return (
     <section className="control-panel" id="utility-panel">
@@ -153,7 +166,7 @@ export function ControlPanel({ demoCTA }: { readonly demoCTA?: boolean } = {}):
           Active optimizations
         </span>
         <span className="control-panel__row-value" data-testid="selected-optimizations-count">
-          {selectedOptimizations?.length ?? 0}
+          {activeCount}
         </span>
         <span />
       </div>
diff --git a/implementations/nextjs-sdk_ssr/lib/hooks.ts b/implementations/nextjs-sdk_ssr/lib/hooks.ts
index dfeebefec..e0fbdb71e 100644
--- a/implementations/nextjs-sdk_ssr/lib/hooks.ts
+++ b/implementations/nextjs-sdk_ssr/lib/hooks.ts
@@ -8,12 +8,13 @@ import {
 import { useEffect, useReducer, useRef, useState } from 'react'
 import { setAppConsent } from './util'
 
-export function useConsent(): {
+export function useConsent(initial?: boolean): {
   consent: boolean | undefined
   setConsent: (value: boolean) => void
 } {
-  const consent = useConsentState()
+  const sdkConsent = useConsentState()
   const { consent: setConsent } = useOptimizationActions()
+  const consent = sdkConsent ?? initial
   useEffect(() => {
     if (typeof consent === 'boolean') setAppConsent(consent)
   }, [consent])
diff --git a/implementations/nextjs-sdk_ssr/lib/optimization.ts b/implementations/nextjs-sdk_ssr/lib/optimization.ts
index 972e09c76..2a76760e1 100644
--- a/implementations/nextjs-sdk_ssr/lib/optimization.ts
+++ b/implementations/nextjs-sdk_ssr/lib/optimization.ts
@@ -132,6 +132,9 @@ class ServerOptimization {
           }
         : undefined,
       initialPageEvent: hasConsent ? ('skip' as const) : ('emit' as const),
+      hasConsent,
+      isIdentified: Boolean(data?.profile?.traits.identified),
+      activeOptimizationsCount: hasConsent ? (data?.selectedOptimizations?.length ?? 0) : 0,
     }
   }
 

From 1e5922f24a97d433eb4c11e47d2baf317c0350d6 Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 18:27:06 +0200
Subject: [PATCH 09/19] =?UTF-8?q?=F0=9F=92=A1=20refactor(nextjs-ssr):=20Co?=
 =?UTF-8?q?nsolidate=20ControlPanel=20hooks=20into=20useControlPanel=20and?=
 =?UTF-8?q?=20pass=20serverState=20as=20single=20prop?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../nextjs-sdk_ssr/app/page-two/page.tsx      | 16 ++---
 implementations/nextjs-sdk_ssr/app/page.tsx   | 19 +++---
 .../components/ControlPanel.tsx               | 33 +++-------
 implementations/nextjs-sdk_ssr/lib/hooks.ts   | 61 ++++++++++++-------
 .../nextjs-sdk_ssr/lib/optimization.ts        |  2 +-
 5 files changed, 60 insertions(+), 71 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/app/page-two/page.tsx b/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
index 78fe48953..a68f5245e 100644
--- a/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
+++ b/implementations/nextjs-sdk_ssr/app/page-two/page.tsx
@@ -6,11 +6,10 @@ import { PAGES } from 'e2e-web'
 import Link from 'next/link'
 
 export default async function PageTwo() {
-  const [{ hasConsent, isIdentified, activeOptimizationsCount }, [auto, manual]] =
-    await Promise.all([
-      optimization.getServerState(),
-      optimization.getEntries([PAGES.pageTwo.auto, PAGES.pageTwo.manual]),
-    ])
+  const [serverState, [auto, manual]] = await Promise.all([
+    optimization.getServerState(),
+    optimization.getEntries([PAGES.pageTwo.auto, PAGES.pageTwo.manual]),
+  ])
 
   return (
     <section data-testid="page-two-view">
@@ -22,12 +21,7 @@ export default async function PageTwo() {
       </div>
 
       <CustomViewTracker componentId="page-two-hero" />
-      <ControlPanel
-        demoCTA
-        initialConsent={hasConsent}
-        initialIsIdentified={isIdentified}
-        initialActiveOptimizationsCount={activeOptimizationsCount}
-      />
+      <ControlPanel demoCTA serverState={serverState} />
 
       <div className="sections-grid sections-grid--split" data-testid="page-two-optimization">
         <section className="page-section">
diff --git a/implementations/nextjs-sdk_ssr/app/page.tsx b/implementations/nextjs-sdk_ssr/app/page.tsx
index 1ba5290cf..760628dd9 100644
--- a/implementations/nextjs-sdk_ssr/app/page.tsx
+++ b/implementations/nextjs-sdk_ssr/app/page.tsx
@@ -4,13 +4,12 @@ import { optimization } from '@/lib/optimization'
 import { CLICK_SCENARIOS, PAGES } from 'e2e-web'
 
 export default async function Home() {
-  const [{ hasConsent, isIdentified, activeOptimizationsCount }, liveUpdates, auto, manual] =
-    await Promise.all([
-      optimization.getServerState(),
-      optimization.getEntry(PAGES.home.liveUpdates),
-      optimization.getEntries(PAGES.home.auto),
-      optimization.getEntries(PAGES.home.manual),
-    ])
+  const [serverState, liveUpdates, auto, manual] = await Promise.all([
+    optimization.getServerState(),
+    optimization.getEntry(PAGES.home.liveUpdates),
+    optimization.getEntries(PAGES.home.auto),
+    optimization.getEntries(PAGES.home.manual),
+  ])
 
   const liveUpdatesEntry = liveUpdates?.baselineEntry
 
@@ -24,11 +23,7 @@ export default async function Home() {
         </p>
       </div>
 
-      <ControlPanel
-        initialConsent={hasConsent}
-        initialIsIdentified={isIdentified}
-        initialActiveOptimizationsCount={activeOptimizationsCount}
-      />
+      <ControlPanel serverState={serverState} />
 
       <section className="page-section" data-testid="live-updates-section">
         <header className="page-section__header">
diff --git a/implementations/nextjs-sdk_ssr/components/ControlPanel.tsx b/implementations/nextjs-sdk_ssr/components/ControlPanel.tsx
index f23e752cc..09d864ad3 100644
--- a/implementations/nextjs-sdk_ssr/components/ControlPanel.tsx
+++ b/implementations/nextjs-sdk_ssr/components/ControlPanel.tsx
@@ -2,39 +2,22 @@
 
 import { useGlobalLiveUpdatesControls } from '@/components/GlobalLiveUpdatesProvider'
 import { appConfig } from '@/lib/config'
-import { useConsent, useFlagSubscription } from '@/lib/hooks'
-import {
-  useLiveUpdates,
-  useOptimization,
-  useOptimizationActions,
-  useProfileState,
-  useSelectedOptimizationsState,
-} from '@contentful/optimization-nextjs/client'
+import { type ControlPanelServerState, useControlPanel } from '@/lib/hooks'
+
+import { useLiveUpdates } from '@contentful/optimization-nextjs/client'
 import type { JSX } from 'react'
 
 interface ControlPanelProps {
   readonly demoCTA?: boolean
-  readonly initialConsent?: boolean
-  readonly initialIsIdentified?: boolean
-  readonly initialActiveOptimizationsCount?: number
+  readonly serverState?: ControlPanelServerState
 }
 
-export function ControlPanel({
-  demoCTA,
-  initialConsent,
-  initialIsIdentified = false,
-  initialActiveOptimizationsCount = 0,
-}: ControlPanelProps = {}): JSX.Element {
-  const sdk = useOptimization()
-  const { identify, reset } = useOptimizationActions()
-  const { consent, setConsent } = useConsent(initialConsent)
-  const profile = useProfileState()
-  const selectedOptimizations = useSelectedOptimizationsState()
+export function ControlPanel({ demoCTA, serverState }: ControlPanelProps = {}): JSX.Element {
   const { globalLiveUpdates, onToggleGlobalLiveUpdates } = useGlobalLiveUpdatesControls()
   const { previewPanelVisible, setPreviewPanelVisible } = useLiveUpdates()
-  const booleanFlag = useFlagSubscription('boolean')
-  const isIdentified = profile ? Boolean(profile.traits.identified) : initialIsIdentified
-  const activeCount = selectedOptimizations?.length ?? initialActiveOptimizationsCount
+  const { sdk, identify, reset, consent, setConsent, profile, activeCount, booleanFlag } =
+    useControlPanel(serverState)
+  const isIdentified = Boolean(profile?.traits.identified)
 
   return (
     <section className="control-panel" id="utility-panel">
diff --git a/implementations/nextjs-sdk_ssr/lib/hooks.ts b/implementations/nextjs-sdk_ssr/lib/hooks.ts
index e0fbdb71e..26e9fb484 100644
--- a/implementations/nextjs-sdk_ssr/lib/hooks.ts
+++ b/implementations/nextjs-sdk_ssr/lib/hooks.ts
@@ -2,23 +2,55 @@
 
 import {
   useConsentState,
+  useOptimization,
   useOptimizationActions,
   useOptimizationContext,
+  useProfileState,
+  useSelectedOptimizationsState,
 } from '@contentful/optimization-nextjs/client'
 import { useEffect, useReducer, useRef, useState } from 'react'
 import { setAppConsent } from './util'
 
-export function useConsent(initial?: boolean): {
-  consent: boolean | undefined
-  setConsent: (value: boolean) => void
-} {
+type Profile = ReturnType<typeof useProfileState>
+
+export interface ControlPanelServerState {
+  readonly hasConsent?: boolean
+  readonly profile?: Profile
+  readonly activeOptimizationsCount?: number
+}
+
+export function useControlPanel(serverState: ControlPanelServerState = {}) {
+  const sdk = useOptimization()
+  const { identify, reset, consent: setConsent } = useOptimizationActions()
   const sdkConsent = useConsentState()
-  const { consent: setConsent } = useOptimizationActions()
-  const consent = sdkConsent ?? initial
+  const profile = useProfileState() ?? serverState.profile
+  const selectedOptimizations = useSelectedOptimizationsState()
+  const { sdk: sdkCtx, isReady } = useOptimizationContext()
+  const [booleanFlag, setBooleanFlag] = useState<unknown>(undefined)
+
+  useEffect(() => {
+    if (!sdkCtx || !isReady) return
+    const subscription = sdkCtx.states.flag('boolean').subscribe(setBooleanFlag)
+    return () => subscription.unsubscribe()
+  }, [isReady, sdkCtx])
+
+  const consent = sdkConsent ?? serverState.hasConsent
+  const activeCount = selectedOptimizations?.length ?? serverState.activeOptimizationsCount ?? 0
+
   useEffect(() => {
     if (typeof consent === 'boolean') setAppConsent(consent)
   }, [consent])
-  return { consent, setConsent }
+
+  return {
+    sdk,
+    identify,
+    reset,
+    consent,
+    setConsent,
+    profile,
+    activeCount,
+    booleanFlag,
+  }
 }
 
 const MS_PER_SECOND = 1000
@@ -73,18 +105,3 @@ export function useEventStream<T>(
 
   return { events, rawCount }
 }
-
-export function useFlagSubscription(flagName: string): unknown {
-  const { sdk, isReady } = useOptimizationContext()
-  const [value, setValue] = useState<unknown>(undefined)
-
-  useEffect(() => {
-    if (!sdk || !isReady) return
-    const subscription = sdk.states.flag(flagName).subscribe(setValue)
-    return () => {
-      subscription.unsubscribe()
-    }
-  }, [isReady, sdk, flagName])
-
-  return value
-}
diff --git a/implementations/nextjs-sdk_ssr/lib/optimization.ts b/implementations/nextjs-sdk_ssr/lib/optimization.ts
index 2a76760e1..0d0c18303 100644
--- a/implementations/nextjs-sdk_ssr/lib/optimization.ts
+++ b/implementations/nextjs-sdk_ssr/lib/optimization.ts
@@ -133,7 +133,7 @@ class ServerOptimization {
         : undefined,
       initialPageEvent: hasConsent ? ('skip' as const) : ('emit' as const),
       hasConsent,
-      isIdentified: Boolean(data?.profile?.traits.identified),
+      profile: data?.profile,
       activeOptimizationsCount: hasConsent ? (data?.selectedOptimizations?.length ?? 0) : 0,
     }
   }

From 8d338d9a6747dc1ab2b2893d976639f83a854d59 Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 18:35:38 +0200
Subject: [PATCH 10/19] =?UTF-8?q?=F0=9F=92=A1=20refactor(nextjs-ssr):=20Fl?=
 =?UTF-8?q?atten=20serverState=20and=20derive=20ControlPanelServerState=20?=
 =?UTF-8?q?from=20defaults=20shape?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 implementations/nextjs-sdk_ssr/app/layout.tsx |  9 +++++++--
 implementations/nextjs-sdk_ssr/lib/hooks.ts   | 10 ++++++----
 .../nextjs-sdk_ssr/lib/optimization.ts        | 19 +++++++++----------
 3 files changed, 22 insertions(+), 16 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/app/layout.tsx b/implementations/nextjs-sdk_ssr/app/layout.tsx
index 796394225..b84583a11 100644
--- a/implementations/nextjs-sdk_ssr/app/layout.tsx
+++ b/implementations/nextjs-sdk_ssr/app/layout.tsx
@@ -18,7 +18,8 @@ export const metadata: Metadata = {
 export const dynamic = 'force-dynamic'
 
 export default async function RootLayout({ children }: Readonly<{ children: ReactNode }>) {
-  const { defaults, initialPageEvent } = await optimization.getServerState()
+  const { profile, selectedOptimizations, changes, initialPageEvent, hasConsent } =
+    await optimization.getServerState()
 
   return (
     <html lang={appConfig.locale.split('-')[0]}>
@@ -30,7 +31,11 @@ export default async function RootLayout({ children }: Readonly<{ children: Reac
           api={appConfig.api}
           trackEntryInteraction={{ views: true, clicks: true, hovers: true }}
           logLevel="debug"
-          defaults={defaults}
+          defaults={
+            (profile ?? selectedOptimizations)
+              ? { profile, ...(hasConsent ? { selectedOptimizations, changes } : {}) }
+              : undefined
+          }
           app={{
             name: 'Contentful Optimization Next.js SDK SSR (Client)',
             version: '0.1.0',
diff --git a/implementations/nextjs-sdk_ssr/lib/hooks.ts b/implementations/nextjs-sdk_ssr/lib/hooks.ts
index 26e9fb484..bba0ac4e9 100644
--- a/implementations/nextjs-sdk_ssr/lib/hooks.ts
+++ b/implementations/nextjs-sdk_ssr/lib/hooks.ts
@@ -13,12 +13,13 @@ import { setAppConsent } from './util'
 
 type Profile = ReturnType<typeof useProfileState>
 
-export interface ControlPanelServerState {
-  readonly hasConsent?: boolean
+type ServerDefaults = {
   readonly profile?: Profile
-  readonly activeOptimizationsCount?: number
+  readonly selectedOptimizations?: readonly unknown[]
 }
 
+export type ControlPanelServerState = ServerDefaults & { readonly hasConsent?: boolean }
+
 export function useControlPanel(serverState: ControlPanelServerState = {}) {
   const sdk = useOptimization()
   const { identify, reset, consent: setConsent } = useOptimizationActions()
@@ -35,7 +36,8 @@ export function useControlPanel(serverState: ControlPanelServerState = {}) {
   }, [isReady, sdkCtx])
 
   const consent = sdkConsent ?? serverState.hasConsent
-  const activeCount = selectedOptimizations?.length ?? serverState.activeOptimizationsCount ?? 0
+  const activeCount =
+    selectedOptimizations?.length ?? serverState.selectedOptimizations?.length ?? 0
 
   useEffect(() => {
     if (typeof consent === 'boolean') setAppConsent(consent)
diff --git a/implementations/nextjs-sdk_ssr/lib/optimization.ts b/implementations/nextjs-sdk_ssr/lib/optimization.ts
index 0d0c18303..993c631cc 100644
--- a/implementations/nextjs-sdk_ssr/lib/optimization.ts
+++ b/implementations/nextjs-sdk_ssr/lib/optimization.ts
@@ -122,19 +122,18 @@ class ServerOptimization {
 
   public async getServerState() {
     const { data, hasConsent } = await this.fetchOptimizationData()
+    const defaults = data
+      ? {
+          profile: data.profile,
+          ...(hasConsent
+            ? { selectedOptimizations: data.selectedOptimizations, changes: data.changes }
+            : {}),
+        }
+      : undefined
     return {
-      defaults: data
-        ? {
-            profile: data.profile,
-            ...(hasConsent
-              ? { selectedOptimizations: data.selectedOptimizations, changes: data.changes }
-              : {}),
-          }
-        : undefined,
+      ...defaults,
       initialPageEvent: hasConsent ? ('skip' as const) : ('emit' as const),
       hasConsent,
-      profile: data?.profile,
-      activeOptimizationsCount: hasConsent ? (data?.selectedOptimizations?.length ?? 0) : 0,
     }
   }
 

From c390f10842b73cc2146d7af9423f488a16cb95b6 Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 19:39:08 +0200
Subject: [PATCH 11/19] fix(nextjs-ssr): Stop using serverState.profile after
 SDK is ready

After reset(), useProfileState() returns null intentionally, but null ?? serverState.profile
fell back to the SSR-resolved identified profile, keeping isIdentified true and hiding the
identify-button.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 implementations/nextjs-sdk_ssr/lib/hooks.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/implementations/nextjs-sdk_ssr/lib/hooks.ts b/implementations/nextjs-sdk_ssr/lib/hooks.ts
index bba0ac4e9..13cb8b8a2 100644
--- a/implementations/nextjs-sdk_ssr/lib/hooks.ts
+++ b/implementations/nextjs-sdk_ssr/lib/hooks.ts
@@ -24,9 +24,10 @@ export function useControlPanel(serverState: ControlPanelServerState = {}) {
   const sdk = useOptimization()
   const { identify, reset, consent: setConsent } = useOptimizationActions()
   const sdkConsent = useConsentState()
-  const profile = useProfileState() ?? serverState.profile
+  const clientProfile = useProfileState()
   const selectedOptimizations = useSelectedOptimizationsState()
   const { sdk: sdkCtx, isReady } = useOptimizationContext()
+  const profile = isReady ? clientProfile : (clientProfile ?? serverState.profile)
   const [booleanFlag, setBooleanFlag] = useState<unknown>(undefined)
 
   useEffect(() => {

From 451471683f5160ace3ac0a7d02cad0663ead9968 Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 19:53:34 +0200
Subject: [PATCH 12/19] refactor(nextjs-ssr): Remove double entry-card wrapper
 in EntryCardClient

The client card rendered entry-card inside entry-card; collapse to a single
content div since the outer section.entry-card comes from EntryCard already.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../components/EntryCard.client.tsx           | 30 +++++++------------
 1 file changed, 10 insertions(+), 20 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx b/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
index 5348a2dc0..3e5e5a893 100644
--- a/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
+++ b/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
@@ -13,26 +13,16 @@ interface EntryCardClientProps {
 export function EntryCardClient({ entry, liveUpdates, testId }: EntryCardClientProps): JSX.Element {
   return (
     <OptimizedEntry baselineEntry={entry} liveUpdates={liveUpdates}>
-      {(resolvedEntry) => {
-        const asCf = resolvedEntry as ContentEntry
-        const text = typeof asCf.fields.text === 'string' ? asCf.fields.text : ''
-
-        return (
-          <div
-            className="entry-card"
-            data-test-entry-id={resolvedEntry.sys.id}
-            data-testid={`content-${testId}`}
-          >
-            <div
-              aria-label={`${text} [Entry: ${resolvedEntry.sys.id}]`}
-              data-testid={`entry-text-${testId}`}
-            >
-              <p>{text}</p>
-              <p>{`[Entry: ${resolvedEntry.sys.id}]`}</p>
-            </div>
-          </div>
-        )
-      }}
+      {({ fields, sys: { id } }) => (
+        <div
+          aria-label={`${fields.text ?? ''} [Entry: ${id}]`}
+          data-test-entry-id={id}
+          data-testid={`entry-text-${testId}`}
+        >
+          <p>{String(fields.text ?? '')}</p>
+          <p>{`[Entry: ${id}]`}</p>
+        </div>
+      )}
     </OptimizedEntry>
   )
 }

From e372370490a0f2ca6222d38c0ca93d1091966238 Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 20:05:35 +0200
Subject: [PATCH 13/19] fix(nextjs-ssr): Include consent in OptimizationRoot
 defaults

defaults was passing profile/selectedOptimizations but omitting
consent/persistenceConsent, so the SDK had no consent on startup
and blocked all tracking events.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 implementations/nextjs-sdk_ssr/app/layout.tsx | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/app/layout.tsx b/implementations/nextjs-sdk_ssr/app/layout.tsx
index b84583a11..afbb86717 100644
--- a/implementations/nextjs-sdk_ssr/app/layout.tsx
+++ b/implementations/nextjs-sdk_ssr/app/layout.tsx
@@ -31,11 +31,12 @@ export default async function RootLayout({ children }: Readonly<{ children: Reac
           api={appConfig.api}
           trackEntryInteraction={{ views: true, clicks: true, hovers: true }}
           logLevel="debug"
-          defaults={
-            (profile ?? selectedOptimizations)
-              ? { profile, ...(hasConsent ? { selectedOptimizations, changes } : {}) }
-              : undefined
-          }
+          defaults={{
+            consent: hasConsent,
+            persistenceConsent: hasConsent,
+            ...(profile ? { profile } : {}),
+            ...(hasConsent && selectedOptimizations ? { selectedOptimizations, changes } : {}),
+          }}
           app={{
             name: 'Contentful Optimization Next.js SDK SSR (Client)',
             version: '0.1.0',

From 3375600c8819d592c7c1488fa18fa79c2fde8f2d Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 22:24:20 +0200
Subject: [PATCH 14/19] fix(nextjs-ssr): Restore content-* and entry-text-*
 testids in EntryCardClient

The double-wrapper removal dropped data-testid="content-${testId}" which
live-updates E2E tests rely on for locating cards and reading data-test-entry-id.
Restore both testids with a minimal two-div structure, keeping entry-card class
removed (that was the actual duplicate).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../components/EntryCard.client.tsx               | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx b/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
index 3e5e5a893..58b51b45f 100644
--- a/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
+++ b/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
@@ -14,13 +14,14 @@ export function EntryCardClient({ entry, liveUpdates, testId }: EntryCardClientP
   return (
     <OptimizedEntry baselineEntry={entry} liveUpdates={liveUpdates}>
       {({ fields, sys: { id } }) => (
-        <div
-          aria-label={`${fields.text ?? ''} [Entry: ${id}]`}
-          data-test-entry-id={id}
-          data-testid={`entry-text-${testId}`}
-        >
-          <p>{String(fields.text ?? '')}</p>
-          <p>{`[Entry: ${id}]`}</p>
+        <div data-test-entry-id={id} data-testid={`content-${testId}`}>
+          <div
+            aria-label={`${fields.text ?? ''} [Entry: ${id}]`}
+            data-testid={`entry-text-${testId}`}
+          >
+            <p>{String(fields.text ?? '')}</p>
+            <p>{`[Entry: ${id}]`}</p>
+          </div>
         </div>
       )}
     </OptimizedEntry>

From 38a5f6a93a6d0e08a561d56205c950429ed6b889 Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Tue, 30 Jun 2026 23:01:58 +0200
Subject: [PATCH 15/19] refactor(nextjs-ssr): Simplify EntryCard props and move
 isRichTextField to util

Collapse dual server/client interfaces into a single EntryCardProps, extract
isRichTextField into util.ts so both EntryCard and ServerOptimization share it.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../components/EntryCard.client.tsx           |  2 +-
 .../nextjs-sdk_ssr/components/EntryCard.tsx   | 34 ++++++-------------
 .../nextjs-sdk_ssr/lib/optimization.ts        | 14 ++++----
 implementations/nextjs-sdk_ssr/lib/util.ts    |  6 +++-
 4 files changed, 22 insertions(+), 34 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx b/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
index 58b51b45f..05bcb64c1 100644
--- a/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
+++ b/implementations/nextjs-sdk_ssr/components/EntryCard.client.tsx
@@ -7,7 +7,7 @@ import type { JSX } from 'react'
 interface EntryCardClientProps {
   entry: ContentEntry
   liveUpdates?: boolean
-  testId: string
+  testId?: string
 }
 
 export function EntryCardClient({ entry, liveUpdates, testId }: EntryCardClientProps): JSX.Element {
diff --git a/implementations/nextjs-sdk_ssr/components/EntryCard.tsx b/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
index 16b756c36..467903aa5 100644
--- a/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
+++ b/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
@@ -1,7 +1,7 @@
 import { EntryCardClient } from '@/components/EntryCard.client'
-import type { ContentEntry, RichTextDocument } from '@/lib/contentful'
+import type { ContentEntry } from '@/lib/contentful'
 import type { Entry } from '@/lib/optimization'
-import { isRecord } from '@/lib/util'
+import { isRecord, isRichTextField } from '@/lib/util'
 import { ServerOptimizedEntry } from '@contentful/optimization-nextjs/server'
 import { documentToReactComponents, type Options } from '@contentful/rich-text-react-renderer'
 import { INLINES } from '@contentful/rich-text-types'
@@ -10,26 +10,12 @@ import type { JSX } from 'react'
 
 const HOVER_DURATION_UPDATE_INTERVAL_MS = 1000
 
-interface EntryCardServerProps {
-  entry: Entry
-  clickScenario?: EntryClickScenario
-  manualTracking: boolean
-  liveUpdates?: never
-  testId?: never
-}
-
-interface EntryCardClientProps {
-  entry: ContentEntry
+interface EntryCardProps {
+  entry: ContentEntry | Entry
   liveUpdates?: boolean
-  testId: string
-  clickScenario?: never
-  manualTracking?: never
-}
-
-type EntryCardProps = EntryCardServerProps | EntryCardClientProps
-
-function isRichTextField(field: unknown): field is RichTextDocument {
-  return isRecord(field) && field.nodeType === 'document' && Array.isArray(field.content)
+  testId?: string
+  clickScenario?: EntryClickScenario
+  manualTracking?: boolean
 }
 
 const RENDER_OPTIONS: Options = {
@@ -43,8 +29,9 @@ const RENDER_OPTIONS: Options = {
 }
 
 export function EntryCard(props: EntryCardProps): JSX.Element {
-  if (!('baselineEntry' in props.entry)) {
-    const { entry, liveUpdates, testId } = props as EntryCardClientProps
+  const { entry, liveUpdates, testId, clickScenario, manualTracking } = props
+
+  if (!('baselineEntry' in entry)) {
     return (
       <section className="entry-card" data-testid={`content-entry-${testId}`}>
         <EntryCardClient entry={entry} liveUpdates={liveUpdates} testId={testId} />
@@ -52,7 +39,6 @@ export function EntryCard(props: EntryCardProps): JSX.Element {
     )
   }
 
-  const { entry, clickScenario, manualTracking } = props as EntryCardServerProps
   const { baselineEntry, resolvedData, resolvedEntry } = entry
   const autoTrackViews = !manualTracking
   const richText = Object.values(resolvedEntry.fields).find(isRichTextField)
diff --git a/implementations/nextjs-sdk_ssr/lib/optimization.ts b/implementations/nextjs-sdk_ssr/lib/optimization.ts
index 993c631cc..6c7bb5157 100644
--- a/implementations/nextjs-sdk_ssr/lib/optimization.ts
+++ b/implementations/nextjs-sdk_ssr/lib/optimization.ts
@@ -7,8 +7,8 @@ import { INLINES } from '@contentful/rich-text-types'
 import { cookies, headers } from 'next/headers'
 import { cache } from 'react'
 import { appConfig } from './config'
-import { fetchEntry, type ContentEntry, type RichTextDocument } from './contentful'
-import { getAppConsent, isEntry, isRecord } from './util'
+import { fetchEntry, type ContentEntry } from './contentful'
+import { getAppConsent, isEntry, isRecord, isRichTextField } from './util'
 
 type Profile = Parameters<ReturnType<typeof createNextjsOptimization>['getMergeTagValue']>[1]
 type SelectedOptimizations = Parameters<
@@ -79,12 +79,10 @@ class ServerOptimization {
     }
 
     return Object.fromEntries(
-      Object.entries(fields).map(([key, value]) => {
-        if (isRecord(value) && value.nodeType === 'document' && Array.isArray(value.content)) {
-          return [key, resolveNode(value) as RichTextDocument]
-        }
-        return [key, value]
-      }),
+      Object.entries(fields).map(([key, value]) => [
+        key,
+        isRichTextField(value) ? resolveNode(value) : value,
+      ]),
     ) as ContentEntry['fields']
   }
 
diff --git a/implementations/nextjs-sdk_ssr/lib/util.ts b/implementations/nextjs-sdk_ssr/lib/util.ts
index eb2b6818f..0543269c6 100644
--- a/implementations/nextjs-sdk_ssr/lib/util.ts
+++ b/implementations/nextjs-sdk_ssr/lib/util.ts
@@ -1,5 +1,5 @@
 import { appConfig } from './config'
-import type { ContentEntry } from './contentful'
+import type { ContentEntry, RichTextDocument } from './contentful'
 
 export function setAppConsent(consented: boolean): void {
   const value = consented ? 'granted' : 'denied'
@@ -22,3 +22,7 @@ export function isEntry(value: unknown): value is ContentEntry {
     isRecord(value.fields)
   )
 }
+
+export function isRichTextField(field: unknown): field is RichTextDocument {
+  return isRecord(field) && field.nodeType === 'document' && Array.isArray(field.content)
+}

From 20a3dbb89de184da3dc6fb3c6930a76185ba9fee Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Wed, 1 Jul 2026 10:55:26 +0200
Subject: [PATCH 16/19] test(e2e-web): Add SSR first-paint state tests and
 refactor shared cookie utils

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../e2e/server-rendering-behavior.spec.ts     | 27 --------
 lib/e2e-web/e2e/ssr.spec.ts                   | 67 +++++++++++++++++++
 lib/e2e-web/e2e/utils.ts                      | 28 ++++++--
 lib/e2e-web/e2e/variant-resolution.spec.ts    | 15 +----
 4 files changed, 94 insertions(+), 43 deletions(-)
 delete mode 100644 lib/e2e-web/e2e/server-rendering-behavior.spec.ts
 create mode 100644 lib/e2e-web/e2e/ssr.spec.ts

diff --git a/lib/e2e-web/e2e/server-rendering-behavior.spec.ts b/lib/e2e-web/e2e/server-rendering-behavior.spec.ts
deleted file mode 100644
index 75974725f..000000000
--- a/lib/e2e-web/e2e/server-rendering-behavior.spec.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import { expect, test } from '@playwright/test'
-import { runIf } from './utils'
-
-test.describe('Server-Rendering Behavior', () => {
-  runIf('HYDRATION')
-
-  test('does not issue a client Experience request after consented SSR hydration', async ({
-    baseURL,
-    context,
-    page,
-  }) => {
-    await context.addCookies([
-      { name: 'app-personalization-consent', value: 'granted', url: baseURL },
-    ])
-    const clientExperienceRequests: string[] = []
-    await page.route('**/experience/**', async (route) => {
-      clientExperienceRequests.push(route.request().url())
-      await route.continue()
-    })
-
-    await page.goto('/')
-    await page.waitForLoadState('networkidle')
-    await expect(page.getByRole('heading', { name: 'Utilities' })).toBeVisible()
-
-    expect(clientExperienceRequests).toEqual([])
-  })
-})
diff --git a/lib/e2e-web/e2e/ssr.spec.ts b/lib/e2e-web/e2e/ssr.spec.ts
new file mode 100644
index 000000000..e9f6029ec
--- /dev/null
+++ b/lib/e2e-web/e2e/ssr.spec.ts
@@ -0,0 +1,67 @@
+import { expect, test } from '@playwright/test'
+import { CONSENT_COOKIE, runIf, seedAnonymousProfile, seedIdentifiedProfile } from './utils'
+
+test.describe('Hydration', () => {
+  runIf('HYDRATION')
+
+  test('does not issue a client Experience request after consented SSR hydration', async ({
+    baseURL,
+    context,
+    page,
+  }) => {
+    await context.addCookies([{ name: CONSENT_COOKIE, value: 'granted', url: baseURL }])
+    const clientExperienceRequests: string[] = []
+    await page.route('**/experience/**', async (route) => {
+      clientExperienceRequests.push(route.request().url())
+      await route.continue()
+    })
+
+    await page.goto('/')
+    await page.waitForLoadState('networkidle')
+    await expect(page.getByRole('heading', { name: 'Utilities' })).toBeVisible()
+
+    expect(clientExperienceRequests).toEqual([])
+  })
+})
+
+test.describe('SSR first-paint state', () => {
+  runIf('SSR')
+  test.use({ javaScriptEnabled: false })
+
+  test.describe('unidentified user', () => {
+    test('consent-status is No without consent cookie', async ({ page }) => {
+      await page.goto('/')
+      await page.waitForLoadState('domcontentloaded')
+
+      await expect(page.getByTestId('consent-status')).toHaveText('No')
+      await expect(page.getByTestId('identified-status')).toHaveText('No')
+    })
+
+    test('consent-status is Yes with consent cookie', async ({ baseURL, context, page }) => {
+      await seedAnonymousProfile(context, baseURL)
+
+      await page.goto('/')
+      await page.waitForLoadState('domcontentloaded')
+
+      await expect(page.getByTestId('consent-status')).toHaveText('Yes')
+      await expect(page.getByTestId('identified-status')).toHaveText('No')
+    })
+  })
+
+  test.describe('identified user', () => {
+    test('consent-status and identified-status reflect server profile', async ({
+      baseURL,
+      context,
+      page,
+      request,
+    }) => {
+      await seedIdentifiedProfile(context, baseURL, request)
+
+      await page.goto('/')
+      await page.waitForLoadState('domcontentloaded')
+
+      await expect(page.getByTestId('consent-status')).toHaveText('Yes')
+      await expect(page.getByTestId('identified-status')).toHaveText('Yes')
+    })
+  })
+})
diff --git a/lib/e2e-web/e2e/utils.ts b/lib/e2e-web/e2e/utils.ts
index 8124c0cf3..f0bb53a6e 100644
--- a/lib/e2e-web/e2e/utils.ts
+++ b/lib/e2e-web/e2e/utils.ts
@@ -30,7 +30,25 @@ export function onlyWithPreviewPanel(): void {
   test.skip(!isPreviewPanelEnabled, 'Preview panel is disabled for this build.')
 }
 
-const MOCK_EXPERIENCE_URL = 'http://localhost:8000/experience'
+export const CONSENT_COOKIE = 'app-personalization-consent'
+export const PROFILE_COOKIE = 'ctfl-opt-aid'
+
+interface CookieContext {
+  addCookies: (cookies: Array<{ name: string; value: string; url: string }>) => Promise<void>
+}
+
+export async function seedAnonymousProfile(
+  context: CookieContext,
+  baseURL: string | undefined,
+): Promise<string> {
+  if (!baseURL) throw new Error('baseURL is required')
+  const profileId = crypto.randomUUID()
+  await context.addCookies([
+    { name: CONSENT_COOKIE, value: 'granted', url: baseURL },
+    { name: PROFILE_COOKIE, value: profileId, url: baseURL },
+  ])
+  return profileId
+}
 
 export async function setup(page: Page): Promise<void> {
   await page.goto('/')
@@ -47,12 +65,14 @@ export async function scrollThroughEntries(page: Page): Promise<void> {
   }
 }
 
-// Seed the mock so it returns identified-visitor data for this profile ID.
-// The mock tracks identified state in-memory via POSTed identify events.
+const MOCK_EXPERIENCE_URL = 'http://localhost:8000/experience'
+
 export async function seedIdentifiedProfile(
+  context: CookieContext,
+  baseURL: string | undefined,
   request: APIRequestContext,
-  profileId: string,
 ): Promise<void> {
+  const profileId = await seedAnonymousProfile(context, baseURL)
   const now = new Date().toISOString()
   await request.post(
     `${MOCK_EXPERIENCE_URL}/v2/organizations/mock-client-id/environments/main/profiles/${profileId}`,
diff --git a/lib/e2e-web/e2e/variant-resolution.spec.ts b/lib/e2e-web/e2e/variant-resolution.spec.ts
index 114d7845f..74338120a 100644
--- a/lib/e2e-web/e2e/variant-resolution.spec.ts
+++ b/lib/e2e-web/e2e/variant-resolution.spec.ts
@@ -1,6 +1,6 @@
 import { expect, test } from '@playwright/test'
 import { CLICK_SCENARIO_IDS, PAGES } from '../src/fixtures'
-import { runIf, seedIdentifiedProfile, skipIf } from './utils'
+import { runIf, seedAnonymousProfile, seedIdentifiedProfile, skipIf } from './utils'
 
 test.describe('Variant Resolution (CSR)', () => {
   runIf('CSR')
@@ -175,11 +175,7 @@ test.describe('Variant Resolution (SSR, JavaScript disabled)', () => {
 
   test.describe('unidentified user', () => {
     test.beforeEach(async ({ baseURL, context, page }) => {
-      const profileId = crypto.randomUUID()
-      await context.addCookies([
-        { name: 'app-personalization-consent', value: 'granted', url: baseURL },
-        { name: 'ctfl-opt-aid', value: profileId, url: baseURL },
-      ])
+      await seedAnonymousProfile(context, baseURL)
 
       await page.goto('/')
       await page.waitForLoadState('domcontentloaded')
@@ -247,12 +243,7 @@ test.describe('Variant Resolution (SSR, JavaScript disabled)', () => {
 
   test.describe('identified user', () => {
     test.beforeEach(async ({ baseURL, context, page, request }) => {
-      const profileId = crypto.randomUUID()
-      await seedIdentifiedProfile(request, profileId)
-      await context.addCookies([
-        { name: 'app-personalization-consent', value: 'granted', url: baseURL },
-        { name: 'ctfl-opt-aid', value: profileId, url: baseURL },
-      ])
+      await seedIdentifiedProfile(context, baseURL, request)
 
       await page.goto('/')
       await page.waitForLoadState('domcontentloaded')

From 6c22250e789cc6b1a2ca96156a91a03136317d4f Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Wed, 1 Jul 2026 11:13:46 +0200
Subject: [PATCH 17/19] refactor(nextjs-ssr): Extract isMergeTagNode to util
 and remove cast

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../nextjs-sdk_ssr/lib/optimization.ts         | 18 +++++++++---------
 implementations/nextjs-sdk_ssr/lib/util.ts     | 15 +++++++++++++++
 2 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/lib/optimization.ts b/implementations/nextjs-sdk_ssr/lib/optimization.ts
index 6c7bb5157..d04fdbd72 100644
--- a/implementations/nextjs-sdk_ssr/lib/optimization.ts
+++ b/implementations/nextjs-sdk_ssr/lib/optimization.ts
@@ -3,12 +3,11 @@ import {
   getNextjsServerOptimizationData,
   type ServerTrackingResolvedData,
 } from '@contentful/optimization-nextjs/server'
-import { INLINES } from '@contentful/rich-text-types'
 import { cookies, headers } from 'next/headers'
 import { cache } from 'react'
 import { appConfig } from './config'
 import { fetchEntry, type ContentEntry } from './contentful'
-import { getAppConsent, isEntry, isRecord, isRichTextField } from './util'
+import { getAppConsent, isEntry, isMergeTagNode, isRecord, isRichTextField } from './util'
 
 type Profile = Parameters<ReturnType<typeof createNextjsOptimization>['getMergeTagValue']>[1]
 type SelectedOptimizations = Parameters<
@@ -64,13 +63,14 @@ class ServerOptimization {
   ): ContentEntry['fields'] {
     const resolveNode = (node: unknown): unknown => {
       if (!isRecord(node)) return node
-      if (
-        node.nodeType === INLINES.EMBEDDED_ENTRY &&
-        isRecord(node.data) &&
-        'target' in node.data
-      ) {
-        const value = this.sdk.getMergeTagValue(node.data.target as never, profile) ?? ''
-        return { ...node, data: { ...node.data, resolvedValue: value } }
+      if (isMergeTagNode(node)) {
+        return {
+          ...node,
+          data: {
+            ...node.data,
+            resolvedValue: this.sdk.getMergeTagValue(node.data.target, profile) ?? '',
+          },
+        }
       }
       if (Array.isArray(node.content)) {
         return { ...node, content: node.content.map(resolveNode) }
diff --git a/implementations/nextjs-sdk_ssr/lib/util.ts b/implementations/nextjs-sdk_ssr/lib/util.ts
index 0543269c6..e16fb4d6b 100644
--- a/implementations/nextjs-sdk_ssr/lib/util.ts
+++ b/implementations/nextjs-sdk_ssr/lib/util.ts
@@ -1,6 +1,10 @@
+import { type createNextjsOptimization } from '@contentful/optimization-nextjs/server'
+import { INLINES } from '@contentful/rich-text-types'
 import { appConfig } from './config'
 import type { ContentEntry, RichTextDocument } from './contentful'
 
+type MergeTagEntry = Parameters<ReturnType<typeof createNextjsOptimization>['getMergeTagValue']>[0]
+
 export function setAppConsent(consented: boolean): void {
   const value = consented ? 'granted' : 'denied'
   document.cookie = `${appConfig.personalizationConsentCookie}=${value}; Path=/; SameSite=Lax`
@@ -26,3 +30,14 @@ export function isEntry(value: unknown): value is ContentEntry {
 export function isRichTextField(field: unknown): field is RichTextDocument {
   return isRecord(field) && field.nodeType === 'document' && Array.isArray(field.content)
 }
+
+export function isMergeTagNode(
+  node: unknown,
+): node is Record<string, unknown> & { data: Record<string, unknown> & { target: MergeTagEntry } } {
+  return (
+    isRecord(node) &&
+    node.nodeType === INLINES.EMBEDDED_ENTRY &&
+    isRecord(node.data) &&
+    'target' in node.data
+  )
+}

From 0fd6a79172f9f3363966a6142741f5c40fa535a9 Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Wed, 1 Jul 2026 11:16:10 +0200
Subject: [PATCH 18/19] refactor(nextjs-ssr): Resolve merge tags to text nodes
 like Angular

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../nextjs-sdk_ssr/components/EntryCard.tsx     | 17 +++--------------
 .../nextjs-sdk_ssr/lib/optimization.ts          |  9 ++++-----
 2 files changed, 7 insertions(+), 19 deletions(-)

diff --git a/implementations/nextjs-sdk_ssr/components/EntryCard.tsx b/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
index 467903aa5..44fdd1c34 100644
--- a/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
+++ b/implementations/nextjs-sdk_ssr/components/EntryCard.tsx
@@ -1,10 +1,9 @@
 import { EntryCardClient } from '@/components/EntryCard.client'
 import type { ContentEntry } from '@/lib/contentful'
 import type { Entry } from '@/lib/optimization'
-import { isRecord, isRichTextField } from '@/lib/util'
+import { isRichTextField } from '@/lib/util'
 import { ServerOptimizedEntry } from '@contentful/optimization-nextjs/server'
-import { documentToReactComponents, type Options } from '@contentful/rich-text-react-renderer'
-import { INLINES } from '@contentful/rich-text-types'
+import { documentToReactComponents } from '@contentful/rich-text-react-renderer'
 import type { EntryClickScenario } from 'e2e-web'
 import type { JSX } from 'react'
 
@@ -18,16 +17,6 @@ interface EntryCardProps {
   manualTracking?: boolean
 }
 
-const RENDER_OPTIONS: Options = {
-  renderNode: {
-    [INLINES.EMBEDDED_ENTRY]: (node): string => {
-      const { data } = node
-      if (!isRecord(data)) return ''
-      return typeof data.resolvedValue === 'string' ? data.resolvedValue : ''
-    },
-  },
-}
-
 export function EntryCard(props: EntryCardProps): JSX.Element {
   const { entry, liveUpdates, testId, clickScenario, manualTracking } = props
 
@@ -52,7 +41,7 @@ export function EntryCard(props: EntryCardProps): JSX.Element {
         data-testid={`entry-text-${baselineEntry.sys.id}`}
       >
         {richText ? (
-          <>{documentToReactComponents(richText, RENDER_OPTIONS)}</>
+          <>{documentToReactComponents(richText)}</>
         ) : (
           <p>{typeof resolvedEntry.fields.text === 'string' ? resolvedEntry.fields.text : ''}</p>
         )}
diff --git a/implementations/nextjs-sdk_ssr/lib/optimization.ts b/implementations/nextjs-sdk_ssr/lib/optimization.ts
index d04fdbd72..b7dd479f9 100644
--- a/implementations/nextjs-sdk_ssr/lib/optimization.ts
+++ b/implementations/nextjs-sdk_ssr/lib/optimization.ts
@@ -65,11 +65,10 @@ class ServerOptimization {
       if (!isRecord(node)) return node
       if (isMergeTagNode(node)) {
         return {
-          ...node,
-          data: {
-            ...node.data,
-            resolvedValue: this.sdk.getMergeTagValue(node.data.target, profile) ?? '',
-          },
+          nodeType: 'text',
+          value: this.sdk.getMergeTagValue(node.data.target, profile) ?? '',
+          marks: [],
+          data: {},
         }
       }
       if (Array.isArray(node.content)) {

From f4238a28c75eb2adb533d12c8570940ab12e3d1a Mon Sep 17 00:00:00 2001
From: Daviti Nalchevanidze <d.nalchevanidze@gmail.com>
Date: Wed, 1 Jul 2026 14:11:11 +0200
Subject: [PATCH 19/19] =?UTF-8?q?refactor(fix-ssr):=20Remove=20react-web-s?=
 =?UTF-8?q?dk=20SSR=20stub=20=E2=80=94=20moved=20to=20experiment/ssr-stub?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The stub approach is now isolated in PR #349. fix-ssr contains only
the nextjs-sdk implementation and surrounding changes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../react-web-sdk/src/hooks/ssrStub.ts        | 100 ------------------
 .../src/hooks/useOptimization.ts              |  10 +-
 .../react-web-sdk/src/index.test.tsx          |  10 +-
 ...ptimizationProvider.onStatesReady.test.tsx |   5 +-
 .../src/provider/OptimizationProvider.tsx     |   9 +-
 5 files changed, 12 insertions(+), 122 deletions(-)
 delete mode 100644 packages/web/frameworks/react-web-sdk/src/hooks/ssrStub.ts

diff --git a/packages/web/frameworks/react-web-sdk/src/hooks/ssrStub.ts b/packages/web/frameworks/react-web-sdk/src/hooks/ssrStub.ts
deleted file mode 100644
index b8d70a972..000000000
--- a/packages/web/frameworks/react-web-sdk/src/hooks/ssrStub.ts
+++ /dev/null
@@ -1,100 +0,0 @@
-import ContentfulOptimization from '@contentful/optimization-web'
-import type { EventEmissionResult, ResolvedData } from '@contentful/optimization-web/core-sdk'
-import type { Entry, EntrySkeletonType } from 'contentful'
-
-import type { OptimizationSdk } from '../context/OptimizationContext'
-
-function noop(): void {
-  // intentional no-op
-}
-
-interface StubSubscription {
-  unsubscribe: () => void
-}
-
-interface StubObservable<T> {
-  readonly current: T
-  subscribe: (next: (v: T) => void) => StubSubscription
-  subscribeOnce: (next: (v: NonNullable<T>) => void) => StubSubscription
-}
-
-function ssrObs<T>(current: T): StubObservable<T> {
-  return {
-    current,
-    subscribe: () => ({ unsubscribe: noop }),
-    subscribeOnce: () => ({ unsubscribe: noop }),
-  }
-}
-
-const SSR_STATES: OptimizationSdk['states'] = {
-  blockedEventStream: ssrObs(undefined),
-  canOptimize: ssrObs(false),
-  consent: ssrObs(undefined),
-  eventStream: ssrObs(undefined),
-  experienceRequestState: ssrObs({ status: 'idle' as const }),
-  flag: () => ssrObs(undefined),
-  locale: ssrObs(undefined),
-  optimizationPossible: ssrObs(false),
-  persistenceConsent: ssrObs(undefined),
-  previewPanelAttached: ssrObs(false),
-  previewPanelOpen: ssrObs(false),
-  profile: ssrObs(undefined),
-  selectedOptimizations: ssrObs(undefined),
-}
-
-const SSR_TRACKING: OptimizationSdk['tracking'] = {
-  clearElement: noop,
-  disable: noop,
-  disableElement: noop,
-  enable: noop,
-  enableElement: noop,
-}
-
-const NOT_ACCEPTED: EventEmissionResult = { accepted: false }
-
-function makeSsrStub(): OptimizationSdk {
-  const stub = {
-    consent: noop,
-    destroy: noop,
-    getFlag: () => undefined,
-    getMergeTagValue: () => undefined,
-    hasConsent: () => false,
-    identify: async () => {
-      await Promise.resolve()
-      return NOT_ACCEPTED
-    },
-    locale: undefined,
-    page: async () => {
-      await Promise.resolve()
-      return NOT_ACCEPTED
-    },
-    reset: noop,
-    resolveOptimizedEntry: (_entry: Entry): ResolvedData<EntrySkeletonType> => ({
-      entry: _entry,
-    }),
-    setLocale: () => undefined,
-    states: SSR_STATES,
-    track: async () => {
-      await Promise.resolve()
-      return NOT_ACCEPTED
-    },
-    trackClick: async () => {
-      await Promise.resolve()
-    },
-    trackView: async () => {
-      await Promise.resolve()
-      return NOT_ACCEPTED
-    },
-    tracking: SSR_TRACKING,
-  }
-
-  Object.setPrototypeOf(stub, ContentfulOptimization.prototype)
-
-  if (!(stub instanceof ContentfulOptimization)) {
-    throw new Error('Expected SSR stub to use the ContentfulOptimization prototype.')
-  }
-
-  return stub
-}
-
-export const SSR_STUB: OptimizationSdk = makeSsrStub()
diff --git a/packages/web/frameworks/react-web-sdk/src/hooks/useOptimization.ts b/packages/web/frameworks/react-web-sdk/src/hooks/useOptimization.ts
index 796e486d0..d2792e18f 100644
--- a/packages/web/frameworks/react-web-sdk/src/hooks/useOptimization.ts
+++ b/packages/web/frameworks/react-web-sdk/src/hooks/useOptimization.ts
@@ -5,7 +5,6 @@ import {
   type OptimizationContextValue,
   type OptimizationSdk,
 } from '../context/OptimizationContext'
-import { SSR_STUB } from './ssrStub'
 
 function getMissingProviderError(): Error {
   return new Error(
@@ -39,11 +38,10 @@ export function useOptimization(): OptimizationSdk {
       })
     }
 
-    // The SDK initializes in useLayoutEffect. Before that fires (during SSR and on the first
-    // client render), return a stub so components can render without throwing. All actual SDK
-    // method calls happen in effects or event handlers, which run after useLayoutEffect has
-    // already set the real SDK into context.
-    return SSR_STUB
+    throw new Error(
+      'ContentfulOptimization SDK is still initializing. ' +
+        'This should not happen when using the loading gate in OptimizationProvider.',
+    )
   }
 
   return sdk
diff --git a/packages/web/frameworks/react-web-sdk/src/index.test.tsx b/packages/web/frameworks/react-web-sdk/src/index.test.tsx
index 8014fd843..2cfea12d8 100644
--- a/packages/web/frameworks/react-web-sdk/src/index.test.tsx
+++ b/packages/web/frameworks/react-web-sdk/src/index.test.tsx
@@ -159,9 +159,8 @@ describe('@contentful/optimization-react-web core providers', () => {
       </OptimizationProvider>,
     )
 
-    // Children render during SSR; the SDK constructor must never run on the server.
-    expect(markup).toMatchInlineSnapshot(`""`)
-    expect(renderedChild).toBe(true)
+    expect(markup).toBe('')
+    expect(renderedChild).toBe(false)
     expect(window.contentfulOptimization).toBeUndefined()
   })
 
@@ -547,10 +546,7 @@ describe('@contentful/optimization-react-web core providers', () => {
     renderClient(<FirstScenario />).unmount()
     renderClient(<SecondScenario />).unmount()
 
-    // Children render twice per mount: once in the initial state (isReady: false) and once after
-    // useLayoutEffect fires and sets the owned SDK (isReady: true). The liveUpdates values are
-    // stable across both renders since they come from provider props, not SDK readiness.
-    expect(results).toEqual([true, false, true, false, true, true])
+    expect(results).toEqual([true, false, true])
   })
 
   it('destroys the optimization singleton on provider unmount', () => {
diff --git a/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.onStatesReady.test.tsx b/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.onStatesReady.test.tsx
index b3d20a4fa..c7569c612 100644
--- a/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.onStatesReady.test.tsx
+++ b/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.onStatesReady.test.tsx
@@ -352,9 +352,8 @@ describe('OptimizationProvider onStatesReady', () => {
       </OptimizationProvider>,
     )
 
-    // Children render during SSR; the SDK constructor must never run on the server.
-    expect(markup).toMatchInlineSnapshot(`""`)
-    expect(childRendered).toBe(true)
+    expect(markup).toBe('')
+    expect(childRendered).toBe(false)
     expect(window.contentfulOptimization).toBeUndefined()
   })
 
diff --git a/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.tsx b/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.tsx
index 578290b9f..eaa002daa 100644
--- a/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.tsx
+++ b/packages/web/frameworks/react-web-sdk/src/provider/OptimizationProvider.tsx
@@ -248,12 +248,9 @@ export function OptimizationProvider(props: OptimizationProviderProps): ReactEle
     }
   }, [liveLocale, props.sdk, state.sdk])
 
-  // When onStatesReady is set, gate rendering until the callback has run — the app may subscribe
-  // to SDK state in the callback and children must not mount before that.
-  // Without onStatesReady, always render: the owned SDK initializes in useLayoutEffect and
-  // client components already guard on isReady/sdk in their own effects. This also allows
-  // Next.js SSR to produce HTML from server components that live inside the provider tree.
-  if (props.onStatesReady && !state.isReady && state.error === undefined) {
+  const shouldRenderChildren = state.isReady || state.error !== undefined
+
+  if (!shouldRenderChildren) {
     return null
   }