Keep MDX snippets on the client boundary

Compiled MDX calls createContext; as Server Components that hits the
RSC React subset and breaks /ai. Wrap each snippet in a client leaf so
the section shells can stay on the server.

Author: hasparus

src/app/(main)/ai/components/by-the-numbers.tsx

@@ -1,9 +1,10 @@
 import { SectionLabel } from "@/app/conf/_design-system/section-label"
 import { Anchor } from "@/app/conf/_design-system/anchor"
-import { snippetComponents } from "./snippets"
-import SchemaSnippet from "./snippets/numbers-schema.mdx"
-import IntrospectionSnippet from "./snippets/numbers-introspection.mdx"
-import ResponseSnippet from "./snippets/numbers-response.mdx"
+import {
+  NumbersIntrospectionSnippet,
+  NumbersResponseSnippet,
+  NumbersSchemaSnippet,
+} from "./snippets"
 
 const stats = [
   {
@@ -159,9 +160,9 @@ export function ByTheNumbers() {
           to.
         </p>
         <div className="grid gap-4 lg:grid-cols-3">
-          <SchemaSnippet components={snippetComponents} />
-          <IntrospectionSnippet components={snippetComponents} />
-          <ResponseSnippet components={snippetComponents} />
+          <NumbersSchemaSnippet />
+          <NumbersIntrospectionSnippet />
+          <NumbersResponseSnippet />
         </div>
       </div>
     </section>

src/app/(main)/ai/components/how-it-works.tsx

@@ -5,11 +5,12 @@ import SearchIcon from "@/app/conf/_design-system/pixelarticons/search.svg?svgr"
 import CodeIcon from "@/app/conf/_design-system/pixelarticons/code.svg?svgr"
 import PlayIcon from "@/app/conf/_design-system/pixelarticons/play.svg?svgr"
 import CheckIcon from "@/app/conf/_design-system/pixelarticons/check.svg?svgr"
-import { snippetComponents } from "./snippets"
-import PromptSnippet from "./snippets/step-prompt.mdx"
-import IntrospectionSnippet from "./snippets/step-introspection.mdx"
-import QuerySnippet from "./snippets/step-query.mdx"
-import ResponseSnippet from "./snippets/step-response.mdx"
+import {
+  StepIntrospectionSnippet,
+  StepPromptSnippet,
+  StepQuerySnippet,
+  StepResponseSnippet,
+} from "./snippets"
 
 const steps = [
   {
@@ -18,31 +19,31 @@ const steps = [
     icon: PlayIcon,
     description:
       'A user gives an AI agent a natural language instruction — "Show me Q4 revenue by region." The agent needs to access business data through an API to fulfill this request.',
-    Snippet: PromptSnippet,
+    Snippet: StepPromptSnippet,
   },
   {
     number: "02",
     title: "Agent introspects the API",
     icon: SearchIcon,
     description:
       "Using GraphQL introspection, the agent queries `__schema` and discovers the available types: `Product`, `Order`, `Region`, `RevenueMetrics`. It learns field names, arguments, and relationships automatically.",
-    Snippet: IntrospectionSnippet,
+    Snippet: StepIntrospectionSnippet,
   },
   {
     number: "03",
     title: "Agent composes a query",
     icon: CodeIcon,
     description:
       "The LLM maps the user's intent to the discovered schema. It constructs a precise GraphQL query that fetches exactly the right data — revenue by region, top 5 categories, all in a single request — with no over-fetching.",
-    Snippet: QuerySnippet,
+    Snippet: StepQuerySnippet,
   },
   {
     number: "04",
     title: "Structured response returned",
     icon: CheckIcon,
     description:
       "The response is JSON in the query's shape. A nullable field can still come back null with an `errors` entry, but the agent already knows the shape, so it can use a partial result as-is.",
-    Snippet: ResponseSnippet,
+    Snippet: StepResponseSnippet,
   },
 ]
 
@@ -99,7 +100,7 @@ export function HowItWorks() {
                     "lg:flex lg:h-full lg:flex-col lg:[&>div]:flex lg:[&>div]:min-h-0 lg:[&>div]:flex-1 lg:[&>div]:flex-col lg:[&_pre]:min-h-0 lg:[&_pre]:flex-1",
                   )}
                 >
-                  <step.Snippet components={snippetComponents} />
+                  <step.Snippet />
                 </div>
               </div>
             ))}

src/app/(main)/ai/components/snippets/index.ts

@@ -0,0 +1,73 @@
+"use client"
+
+import { Code } from "nextra/components"
+
+import { Pre } from "@/components/pre"
+
+import NumbersIntrospection from "./numbers-introspection.mdx"
+import NumbersResponse from "./numbers-response.mdx"
+import NumbersSchema from "./numbers-schema.mdx"
+import StepIntrospection from "./step-introspection.mdx"
+import StepPrompt from "./step-prompt.mdx"
+import StepQuery from "./step-query.mdx"
+import StepResponse from "./step-response.mdx"
+import UseCaseAgents from "./use-case-agents.mdx"
+import UseCaseMcp from "./use-case-mcp.mdx"
+import UseCaseRag from "./use-case-rag.mdx"
+import WhyComposable from "./why-composable.mdx"
+import WhySelfDescribing from "./why-self-describing.mdx"
+import WhyStronglyTyped from "./why-strongly-typed.mdx"
+
+const components = { pre: Pre, code: Code }
+
+export function NumbersSchemaSnippet() {
+  return <NumbersSchema components={components} />
+}
+
+export function NumbersIntrospectionSnippet() {
+  return <NumbersIntrospection components={components} />
+}
+
+export function NumbersResponseSnippet() {
+  return <NumbersResponse components={components} />
+}
+
+export function StepPromptSnippet() {
+  return <StepPrompt components={components} />
+}
+
+export function StepIntrospectionSnippet() {
+  return <StepIntrospection components={components} />
+}
+
+export function StepQuerySnippet() {
+  return <StepQuery components={components} />
+}
+
+export function StepResponseSnippet() {
+  return <StepResponse components={components} />
+}
+
+export function UseCaseMcpSnippet() {
+  return <UseCaseMcp components={components} />
+}
+
+export function UseCaseRagSnippet() {
+  return <UseCaseRag components={components} />
+}
+
+export function UseCaseAgentsSnippet() {
+  return <UseCaseAgents components={components} />
+}
+
+export function WhySelfDescribingSnippet() {
+  return <WhySelfDescribing components={components} />
+}
+
+export function WhyStronglyTypedSnippet() {
+  return <WhyStronglyTyped components={components} />
+}
+
+export function WhyComposableSnippet() {
+  return <WhyComposable components={components} />
+}

src/app/(main)/ai/components/snippets/index.tsx

@@ -4,10 +4,11 @@ import ArrowDownIcon from "@/app/conf/_design-system/pixelarticons/arrow-down.sv
 import MCPIcon from "@/app/conf/_design-system/pixelarticons/modem.svg?svgr"
 import SearchIcon from "@/app/conf/_design-system/pixelarticons/search.svg?svgr"
 import CodeIcon from "@/app/conf/_design-system/pixelarticons/code.svg?svgr"
-import { snippetComponents } from "./snippets"
-import McpSnippet from "./snippets/use-case-mcp.mdx"
-import RagSnippet from "./snippets/use-case-rag.mdx"
-import AgentsSnippet from "./snippets/use-case-agents.mdx"
+import {
+  UseCaseAgentsSnippet,
+  UseCaseMcpSnippet,
+  UseCaseRagSnippet,
+} from "./snippets"
 
 const useCases = [
   {
@@ -20,7 +21,7 @@ const useCases = [
       "Type-safe inputs and structured outputs",
       "One MCP server exposes your entire API surface",
     ],
-    Snippet: McpSnippet,
+    Snippet: UseCaseMcpSnippet,
     href: "/blog/2025-10-14-announcing-ai-wg/",
     cta: "Join the AI Working Group",
   },
@@ -34,7 +35,7 @@ const useCases = [
       "Join data across collections and sources",
       "Minimize context window waste with field selection",
     ],
-    Snippet: RagSnippet,
+    Snippet: UseCaseRagSnippet,
     href: "/resources/ai",
     cta: "Explore AI resources",
   },
@@ -48,7 +49,7 @@ const useCases = [
       "Real-time subscriptions for streaming agents",
       "Single endpoint for all data operations",
     ],
-    Snippet: AgentsSnippet,
+    Snippet: UseCaseAgentsSnippet,
     href: "/blog/2025-07-03-graphql-supercharging-ai/",
     cta: "Read the blog post",
   },
@@ -84,7 +85,7 @@ export function UseCases() {
             </p>
 
             <div className="mt-5">
-              <useCase.Snippet components={snippetComponents} />
+              <useCase.Snippet />
             </div>
 
             <ul className="typography-body-sm mt-5 flex flex-col gap-1.5">

src/app/(main)/ai/components/use-cases.tsx

@@ -3,10 +3,11 @@ import CheckIcon from "@/app/conf/_design-system/pixelarticons/check.svg?svgr"
 import SearchIcon from "@/app/conf/_design-system/pixelarticons/search.svg?svgr"
 import ZapIcon from "@/app/conf/_design-system/pixelarticons/zap.svg?svgr"
 import SlidersIcon from "@/app/conf/_design-system/pixelarticons/sliders.svg?svgr"
-import { snippetComponents } from "./snippets"
-import SelfDescribingSnippet from "./snippets/why-self-describing.mdx"
-import StronglyTypedSnippet from "./snippets/why-strongly-typed.mdx"
-import ComposableSnippet from "./snippets/why-composable.mdx"
+import {
+  WhyComposableSnippet,
+  WhySelfDescribingSnippet,
+  WhyStronglyTypedSnippet,
+} from "./snippets"
 import { Eyebrow } from "@/_design-system/eyebrow"
 
 const benefits = [
@@ -16,7 +17,7 @@ const benefits = [
     icon: SearchIcon,
     description:
       "Every GraphQL API ships with a built-in type system. AI agents query `__schema` and immediately understand what data is available, what arguments each field accepts, and how types relate — no hand-written tool descriptions needed.",
-    Snippet: SelfDescribingSnippet,
+    Snippet: WhySelfDescribingSnippet,
     bullets: [
       "Auto-generated tool definitions for LLMs",
       "Agents discover capabilities at runtime",
@@ -29,7 +30,7 @@ const benefits = [
     icon: ZapIcon,
     description:
       "Every field has a known, validated type. LLMs can reason about inputs and outputs with confidence. A wrong guess comes back as a named validation error the agent can correct, rather than a 200 with the wrong data in it.",
-    Snippet: StronglyTypedSnippet,
+    Snippet: WhyStronglyTypedSnippet,
     bullets: [
       "LLMs understand data shapes natively",
       "Validated responses prevent parsing errors",
@@ -42,7 +43,7 @@ const benefits = [
     icon: SlidersIcon,
     description:
       "Request exactly what you need, nothing more. GraphQL lets AI agents compose precise queries on the fly — requesting nested data, using aliases, and applying filters. One endpoint serves any data access pattern without client-side stitching.",
-    Snippet: ComposableSnippet,
+    Snippet: WhyComposableSnippet,
     bullets: [
       "Response size tracks the query, not the endpoint",
       "Dynamic query composition by AI agents",
@@ -83,7 +84,7 @@ export function WhyGraphQLAI() {
             </p>
 
             <div className="mt-5">
-              <benefit.Snippet components={snippetComponents} />
+              <benefit.Snippet />
             </div>
 
             <ul className="typography-body-sm flex flex-col gap-2 pt-5">