experiment(react-web-sdk): undefined SDK on server

[David Nalchevanidze (nalchevanidze)]

What this shows

This branch demonstrates what it would cost to return `undefined` from `useOptimization()` instead of the current `SSR_STUB` approach. It builds on top of `fix-ssr`, so all the SSR implementation work is included — you can see how the undefined path interacts with the actual SSR rendering.

Changes

`useOptimization.ts`

Returns `OptimizationSdk | undefined` — `undefined` before the SDK is ready (SSR and first client render).

All dependent hooks (7 files)

Each hook that consumed `useOptimization()` now needs explicit null guards:

• `useOptimizationState.ts` — each state hook: `sdk ? sdk.states.X : nullObs()`. Note `canOptimize` needs `nullObs(false)` (boolean), others need `nullObs(undefined)`.
• `useOptimizationActions.ts` — public API widens: `identify/page/screen/track` now return `Promise<EventEmissionResult | undefined>`. Every method needs an `if (sdk)` or ternary guard.
• `useEntryResolver.ts` — each resolver: `sdk ? sdk.resolveOptimizedEntry(...) : { entry }` fallback.
• `useMergeTagResolver.ts` — `sdk ? sdk.getMergeTagValue(...) : undefined`.
• `useAutoPageEmitter.ts` — `if (!sdk) return` guard in effect.

Callers: package layer

• `dev/app/App.tsx` — calls `useOptimization()` and passes `sdk` directly to child sections. Requires `if (!sdk) return null` early-exit at the component root.
• `OptimizationProvider.onStatesReady.test.tsx` — test probes using `useOptimization().states.X` must become `useOptimization()?.states.X`.

Callers: nextjs-sdk_ssr implementation

• `CustomViewTracker.tsx` — effect calling `sdk.trackView()` needs `if (!sdk) return` guard.
• `ControlPanel.tsx` — onClick handler calling `sdk.trackView()` needs optional chaining `sdk?.trackView()`.
• `hooks.ts` — `useControlPanel` already uses `useOptimizationContext()` for direct sdk access (bypasses the issue), but returns `sdk` to callers who must then guard.

Verdict

The undefined path distributes the SSR_STUB cost outward: instead of one central stub that makes the SDK always non-null, every hook and every direct consumer of `useOptimization()` must handle `undefined` explicitly. The API surface (`UseOptimizationActionsResult`) widens, and components that receive the SDK as a prop would also need to accept `undefined`.

The SSR_STUB approach keeps the contract simple: hooks always get a callable SDK, and the stub's no-ops are safe because real SDK calls happen in effects (after `useLayoutEffect` has set the real SDK). This branch shows the alternative is real but costly — every new direct caller of `useOptimization()` would need to know about and handle the undefined window.