useZudoku must be used within a ZudokuProvider error on page load with React 19

[BastienCarcat]

Description

When running a fresh Zudoku project with React 19, the application crashes with the error:

Error: useZudoku must be used within a ZudokuProvider.

The error originates from the SyntaxHighlight component which calls useZudoku() before the ZudokuProvider context is available.

Stack Trace

Error: useZudoku must be used within a ZudokuProvider.
    at bt (chunk-LRVKVJCU.js:1488:11)
    at SyntaxHighlight (chunk-I5UUXJUE.js:30603:40)
    at renderWithHooks (react-dom_client.js:5654:24)
    at updateFunctionComponent (react-dom_client.js:7475:21)
    at updateSimpleMemoComponent (react-dom_client.js:7264:16)
    at updateMemoComponent (react-dom_client.js:7218:185)
    at beginWork (react-dom_client.js:8786:20)
    at runWithFiberInDEV (react-dom_client.js:997:72)
    at performUnitOfWork (react-dom_client.js:12561:98)

Environment

• Zudoku version: 0.66.4
• React version: 19.x (as required by Zudoku peer dependencies)
• Node version: 22.x
• OS: macOS

Reproduction

1. Create a new Zudoku project with zudoku dev --zuplo
2. Run npm install and npm run dev
3. Open the browser → Error appears immediately

Configuration

package.json:

{
  "dependencies": {
    "react": "^19",
    "react-dom": "^19",
    "@mdx-js/react": "3.0.1",
    "zudoku": "^0.66"
  }
}

zudoku.config.tsx: Default configuration (no authentication configured)

Root Cause Analysis

After investigating the source code:
SyntaxHighlight (src/lib/ui/SyntaxHighlight.tsx:21) calls useZudoku() to get syntaxHighlighting.highlighter
useZudoku() (src/lib/components/context/ZudokuContext.ts:15-23) throws if context is undefined
ZudokuProvider (src/lib/components/context/ZudokuProvider.tsx) uses useSuspenseQuery during initialization
During React 19 concurrent rendering/hydration, SyntaxHighlight appears to render before ZudokuProvider has provided the context

The issue seems to be a race condition between the Suspense boundary in ZudokuProvider and MDX components that use useZudoku.

Expected Behavior

The application should load without errors.

Workaround Attempted

Downgrading to React 18 is not possible (Zudoku 0.65+ requires react >= 19.2.0)
Removing markdown files with code blocks might help but is not a viable solution