From f709ac74b2106dbd715ed2a3d169ba0e1659419f Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 17 Sep 2026 13:19:29 +0200
Subject: [PATCH 1/2] feat: embed AI Basic Chat in the docs sandbox

Register examples/react/basic-chat as a WebContainer example, rewrite workspace:* for @tanstack/ai packages, and mount that player from a docs comment.
---
 .../examples/ClientExampleDocEmbed.client.tsx |  93 ++++++++++++++
 .../examples/ClientExampleDocEmbed.tsx        | 106 ++++++++++++++++
 src/components/markdown/MdComponents.tsx      |  17 +++
 src/utils/client-example-config.ts            |  13 ++
 src/utils/docs.functions.ts                   |  19 ++-
 src/utils/repository-example.ts               | 120 ++++++++++++++++++
 src/utils/sandbox.ts                          |   4 +
 tests/client-example-doc-embed.test.ts        |  44 +++++++
 tests/repo-path.test.ts                       |   6 +
 tests/repository-example.test.ts              |  31 +++++
 tests/rewrite-workspace-protocol.test.ts      |  75 +++++++++++
 11 files changed, 524 insertions(+), 4 deletions(-)
 create mode 100644 src/components/examples/ClientExampleDocEmbed.client.tsx
 create mode 100644 src/components/examples/ClientExampleDocEmbed.tsx
 create mode 100644 tests/client-example-doc-embed.test.ts
 create mode 100644 tests/rewrite-workspace-protocol.test.ts

diff --git a/src/components/examples/ClientExampleDocEmbed.client.tsx b/src/components/examples/ClientExampleDocEmbed.client.tsx
new file mode 100644
index 000000000..c877a6c29
--- /dev/null
+++ b/src/components/examples/ClientExampleDocEmbed.client.tsx
@@ -0,0 +1,93 @@
+import * as React from 'react'
+import { getLibrary } from '~/libraries'
+import { getClientExampleConfig } from '~/utils/client-example-config'
+import { fetchClientExampleFiles } from '~/utils/docs'
+import type { ExampleDefinition } from '~/utils/example-workspace'
+import { createRepositoryExampleDefinition } from '~/utils/repository-example'
+
+const LazyExampleWorkbench = React.lazy(() =>
+  import('~/components/examples/ExampleWorkbench.client').then((module) => ({
+    default: module.ExampleWorkbench,
+  })),
+)
+
+export function ClientExampleDocEmbedClient({
+  fallback,
+  framework,
+  library,
+  slug,
+  version,
+}: {
+  fallback: React.ReactNode
+  framework: string
+  library: string
+  slug: string
+  version: string
+}) {
+  const config = getClientExampleConfig({
+    framework,
+    libraryId: library,
+    slug,
+    version,
+  })
+  const [definition, setDefinition] = React.useState<ExampleDefinition>()
+
+  React.useEffect(() => {
+    let cancelled = false
+    setDefinition(undefined)
+
+    const currentConfig = getClientExampleConfig({
+      framework,
+      libraryId: library,
+      slug,
+      version,
+    })
+    if (!currentConfig) return
+
+    void fetchClientExampleFiles({
+      data: {
+        example: currentConfig.slug,
+        framework: currentConfig.framework,
+        libraryId: currentConfig.libraryId,
+        version,
+      },
+    })
+      .then((result) => {
+        if (cancelled || !result.success) return
+
+        try {
+          const nextDefinition = createRepositoryExampleDefinition({
+            binaryFiles: result.binaryFiles,
+            entry: currentConfig.entry,
+            files: result.files,
+            id: `${currentConfig.libraryId}-${currentConfig.framework}-${currentConfig.slug}`,
+            runtime: currentConfig.runtime,
+            title: currentConfig.slug,
+          })
+          if (!cancelled) setDefinition(nextDefinition)
+        } catch {
+          if (!cancelled) setDefinition(undefined)
+        }
+      })
+      .catch(() => {
+        if (!cancelled) setDefinition(undefined)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [framework, library, slug, version])
+
+  if (!config || !definition) return fallback
+
+  return (
+    <React.Suspense fallback={fallback}>
+      <LazyExampleWorkbench
+        autoRun={config.autoStart}
+        definition={definition}
+        libraryColor={getLibrary(config.libraryId).bgStyle}
+        packageResolution="dynamic"
+      />
+    </React.Suspense>
+  )
+}
diff --git a/src/components/examples/ClientExampleDocEmbed.tsx b/src/components/examples/ClientExampleDocEmbed.tsx
new file mode 100644
index 000000000..c74b07800
--- /dev/null
+++ b/src/components/examples/ClientExampleDocEmbed.tsx
@@ -0,0 +1,106 @@
+import { ClientOnly, useParams } from '@tanstack/react-router'
+import * as React from 'react'
+import { getClientExampleConfig } from '~/utils/client-example-config'
+
+const LazyClientExampleDocEmbed = React.lazy(() =>
+  import('./ClientExampleDocEmbed.client').then((module) => ({
+    default: module.ClientExampleDocEmbedClient,
+  })),
+)
+
+const clientExampleAttributeKeys = ['framework', 'library', 'slug']
+const clientExampleAttributePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+export function parseClientExampleAttributes(value: unknown) {
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, clientExampleAttributeKeys) ||
+    typeof value.library !== 'string' ||
+    typeof value.framework !== 'string' ||
+    typeof value.slug !== 'string' ||
+    !isClientExampleAttribute(value.library) ||
+    !isClientExampleAttribute(value.framework) ||
+    !isClientExampleAttribute(value.slug)
+  ) {
+    return null
+  }
+
+  return {
+    library: value.library,
+    framework: value.framework,
+    slug: value.slug,
+  }
+}
+
+export function ClientExampleDocEmbed({
+  framework,
+  library,
+  slug,
+}: {
+  framework: string
+  library: string
+  slug: string
+}) {
+  const { version } = useParams({ strict: false })
+  const resolvedVersion = version ?? 'latest'
+  const config = getClientExampleConfig({
+    framework,
+    libraryId: library,
+    slug,
+    version: resolvedVersion,
+  })
+
+  if (!config) return null
+
+  const fallback = <ClientExampleDocEmbedFallback slug={config.slug} />
+
+  return (
+    <section className="not-prose my-5">
+      <ClientOnly fallback={fallback}>
+        <React.Suspense fallback={fallback}>
+          <LazyClientExampleDocEmbed
+            fallback={fallback}
+            framework={config.framework}
+            library={config.libraryId}
+            slug={config.slug}
+            version={resolvedVersion}
+          />
+        </React.Suspense>
+      </ClientOnly>
+    </section>
+  )
+}
+
+function ClientExampleDocEmbedFallback({ slug }: { slug: string }) {
+  return (
+    <div
+      className="flex h-[clamp(520px,75dvh,720px)] min-w-0 flex-col overflow-hidden rounded-lg border border-border-default bg-background-default"
+      data-client-example={slug}
+      data-client-example-state="static"
+    >
+      <header className="flex min-h-10 shrink-0 items-center border-b border-border-default px-3 font-ds-mono text-xs text-text-muted">
+        {slug}
+      </header>
+      <div
+        aria-hidden="true"
+        className="flex min-h-0 flex-1 flex-col gap-2 bg-background-subtle p-4"
+      >
+        <div className="h-3 w-2/3 rounded bg-border-subtle" />
+        <div className="h-3 w-1/2 rounded bg-border-subtle" />
+        <div className="h-3 w-3/4 rounded bg-border-subtle" />
+      </div>
+    </div>
+  )
+}
+
+function isClientExampleAttribute(value: string) {
+  return clientExampleAttributePattern.test(value)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, keys: Array<string>) {
+  return Object.keys(value).every((key) => keys.includes(key))
+}
diff --git a/src/components/markdown/MdComponents.tsx b/src/components/markdown/MdComponents.tsx
index 3c96cf1f7..286c2861b 100644
--- a/src/components/markdown/MdComponents.tsx
+++ b/src/components/markdown/MdComponents.tsx
@@ -1,5 +1,9 @@
 import * as React from 'react'
 import { ChartsCatalogDocExample } from '~/components/charts/ChartsCatalogDocExample'
+import {
+  ClientExampleDocEmbed,
+  parseClientExampleAttributes,
+} from '~/components/examples/ClientExampleDocEmbed'
 import { parseChartsCatalogExampleAttributes } from '~/utils/charts-catalog-embed'
 import { FileTabs } from './FileTabs'
 import { FrameworkContent } from './FrameworkContent'
@@ -171,6 +175,19 @@ export function MdCommentComponent({
     )
   }
 
+  if (normalizedComponentName === 'client-example') {
+    const example = parseClientExampleAttributes(parsedAttributes)
+    if (!example) return null
+
+    return (
+      <ClientExampleDocEmbed
+        framework={example.framework}
+        library={example.library}
+        slug={example.slug}
+      />
+    )
+  }
+
   if (normalizedComponentName === 'tabs') {
     const parsedPackageManagerMeta = parseJson(packageManagerMeta)
     const resolvedPackageManagerMeta = getPackageManagerMeta(
diff --git a/src/utils/client-example-config.ts b/src/utils/client-example-config.ts
index 38ec89bab..8330f71fa 100644
--- a/src/utils/client-example-config.ts
+++ b/src/utils/client-example-config.ts
@@ -253,6 +253,19 @@ const clientExampleConfigs: ReadonlyArray<ClientExampleConfig> = [
     },
     slug: 'start-basic',
   },
+  {
+    autoStart: true,
+    entry: '/src/routes/index.tsx',
+    framework: 'react',
+    libraryId: 'ai',
+    runtime: {
+      type: 'webcontainer',
+      compatibility: 'tanstack-start-async-context',
+      install: { command: 'pnpm', args: ['install'] },
+      start: { command: 'pnpm', args: ['run', 'dev'] },
+    },
+    slug: 'basic-chat',
+  },
   {
     autoStart: true,
     entry: '/src/routes/index.tsx',
diff --git a/src/utils/docs.functions.ts b/src/utils/docs.functions.ts
index 5c53fbb5e..b0f40250e 100644
--- a/src/utils/docs.functions.ts
+++ b/src/utils/docs.functions.ts
@@ -10,6 +10,7 @@ import type { DocsRedirectManifest } from './docs-redirects'
 import type { GitHubFileNode } from './documents.server'
 import { getBranch, getLibrary } from '~/libraries'
 import { getClientExampleConfig } from './client-example-config'
+import { rewriteWorkspaceProtocolDependencies } from './repository-example'
 
 export type DocsTreeNode = {
   path: string
@@ -548,14 +549,24 @@ export const fetchClientExampleFiles = createServerFn({ method: 'GET' })
     } = await loadGitHubExampleServerModule()
     const { getCachedDocsArtifact } = await loadGitHubContentCacheServerModule()
     const result = await getCachedDocsArtifact({
-      artifactKey: 'workspace-v1',
+      artifactKey: 'workspace-v2',
       artifactType: 'client-example',
-      build: async () =>
-        ensureCacheableFetchExampleFilesResponse(
+      build: async () => {
+        const fetched = ensureCacheableFetchExampleFilesResponse(
           await fetchExampleFiles(library.repo, gitRef, examplePath, {
             preserveBinary: true,
           }),
-        ),
+        )
+
+        if (!fetched.success) {
+          return fetched
+        }
+
+        return {
+          ...fetched,
+          files: rewriteWorkspaceProtocolDependencies(fetched.files),
+        }
+      },
       docsRoot: examplePath,
       gitRef,
       isValue: isFetchExampleFilesResponse,
diff --git a/src/utils/repository-example.ts b/src/utils/repository-example.ts
index f3229e26a..04199fa1b 100644
--- a/src/utils/repository-example.ts
+++ b/src/utils/repository-example.ts
@@ -46,3 +46,123 @@ export function createRepositoryExampleDefinition({
     workspace,
   }
 }
+
+const dependencyFields = [
+  'dependencies',
+  'devDependencies',
+  'peerDependencies',
+] as const
+const tanstackAiPackagePrefix = '@tanstack/ai'
+const workspaceProtocolVersion = 'workspace:*'
+const npmLatestVersion = 'latest'
+
+/**
+ * Replace `workspace:*` versions for `@tanstack/ai` packages with `latest`.
+ *
+ * Looks for `package.json` or `/package.json`. If that file is missing or is
+ * not valid JSON, the files stay the same.
+ *
+ * @param files - Example files, keyed by path
+ *
+ * @example
+ * const files = rewriteWorkspaceProtocolDependencies({
+ *   '/package.json': '{"dependencies":{"@tanstack/ai":"workspace:*"}}',
+ * })
+ */
+export function rewriteWorkspaceProtocolDependencies(
+  files: Record<string, string>,
+) {
+  const packageJson = getPackageJsonEntry(files)
+  if (!packageJson) {
+    return files
+  }
+
+  const parsed = parsePackageJson(packageJson.source)
+  if (!parsed) {
+    return files
+  }
+
+  let changed = false
+  const nextPackageJson = { ...parsed }
+
+  for (const field of dependencyFields) {
+    const current = parsed[field]
+    if (!isRecord(current)) {
+      continue
+    }
+
+    const nextDependencies = rewriteTanStackAiWorkspaceDependencies(current)
+    if (nextDependencies === current) {
+      continue
+    }
+
+    nextPackageJson[field] = nextDependencies
+    changed = true
+  }
+
+  if (!changed) {
+    return files
+  }
+
+  return {
+    ...files,
+    [packageJson.path]: `${JSON.stringify(nextPackageJson, null, 2)}\n`,
+  }
+}
+
+function getPackageJsonEntry(files: Record<string, string>) {
+  const unprefixed = files['package.json']
+  if (unprefixed !== undefined) {
+    return { path: 'package.json', source: unprefixed }
+  }
+
+  const prefixed = files['/package.json']
+  if (prefixed !== undefined) {
+    return { path: '/package.json', source: prefixed }
+  }
+
+  return undefined
+}
+
+function parsePackageJson(source: string) {
+  try {
+    const value: unknown = JSON.parse(source)
+    if (!isRecord(value)) {
+      return undefined
+    }
+    return value
+  } catch {
+    return undefined
+  }
+}
+
+function rewriteTanStackAiWorkspaceDependencies(
+  dependencies: Record<string, unknown>,
+) {
+  const nextDependencies = { ...dependencies }
+  let changed = false
+  const packageNames = Object.keys(dependencies)
+
+  for (const packageName of packageNames) {
+    const isTanStackAiPackage = packageName.startsWith(tanstackAiPackagePrefix)
+    const usesWorkspaceProtocol =
+      dependencies[packageName] === workspaceProtocolVersion
+
+    if (!isTanStackAiPackage || !usesWorkspaceProtocol) {
+      continue
+    }
+
+    nextDependencies[packageName] = npmLatestVersion
+    changed = true
+  }
+
+  if (!changed) {
+    return dependencies
+  }
+
+  return nextDependencies
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
diff --git a/src/utils/sandbox.ts b/src/utils/sandbox.ts
index 51c2379ed..9f2167dc1 100644
--- a/src/utils/sandbox.ts
+++ b/src/utils/sandbox.ts
@@ -8,6 +8,10 @@ export const getExampleStartingPath = (
     return 'src/routes/__root.tsx'
   }
 
+  if (libraryId === 'ai') {
+    return 'src/routes/index.tsx'
+  }
+
   const dir = framework === 'angular' ? 'src/app' : 'src'
 
   return `${dir}/${getExampleStartingFileName(framework, libraryId)}` as const
diff --git a/tests/client-example-doc-embed.test.ts b/tests/client-example-doc-embed.test.ts
new file mode 100644
index 000000000..be3fedd53
--- /dev/null
+++ b/tests/client-example-doc-embed.test.ts
@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { createElement, Fragment } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { renderMarkdownReact } from '@tanstack/markdown/react'
+import { parseClientExampleAttributes } from '../src/components/examples/ClientExampleDocEmbed'
+import { parseSiteMarkdown } from '../src/utils/markdown'
+
+test('client example comments parse into the markdown comment component', () => {
+  const document = parseSiteMarkdown(
+    '<!-- ::client-example library=ai framework=react slug=basic-chat -->',
+  )
+  const block = document.children[0]
+  assert.equal(block?.type, 'component')
+  if (block?.type !== 'component') return
+
+  assert.equal(block.name, 'client-example')
+  assert.deepEqual(parseClientExampleAttributes(block.attributes), {
+    library: 'ai',
+    framework: 'react',
+    slug: 'basic-chat',
+  })
+
+  const html = renderToStaticMarkup(
+    createElement(Fragment, null, renderMarkdownReact(document)),
+  )
+  assert.match(html, /<md-comment-component/)
+  assert.match(html, /data-component="client-example"/)
+})
+
+test('client example comments reject unsafe or extra attributes', () => {
+  for (const attributes of [
+    { library: 'ai', framework: 'react', slug: '../secret' },
+    { library: 'ai', framework: 'react', slug: '' },
+    {
+      library: 'ai',
+      framework: 'react',
+      slug: 'basic-chat',
+      src: 'https://example.com',
+    },
+  ]) {
+    assert.equal(parseClientExampleAttributes(attributes), null)
+  }
+})
diff --git a/tests/repo-path.test.ts b/tests/repo-path.test.ts
index b990d1ebc..7c2a78c65 100644
--- a/tests/repo-path.test.ts
+++ b/tests/repo-path.test.ts
@@ -55,6 +55,12 @@ assert.equal(
   'Start examples default to the root route file',
 )
 
+assert.equal(
+  getExampleStartingPath('react', 'ai'),
+  'src/routes/index.tsx',
+  'AI examples default to the index route file',
+)
+
 assert.equal(
   getExampleStartingPath('react', 'router'),
   'src/main.tsx',
diff --git a/tests/repository-example.test.ts b/tests/repository-example.test.ts
index e02a73eee..8090761b0 100644
--- a/tests/repository-example.test.ts
+++ b/tests/repository-example.test.ts
@@ -200,11 +200,42 @@ test('selects only verified current client examples', () => {
       slug: 'start-basic',
     },
   )
+  assert.deepEqual(
+    getClientExampleConfig({
+      framework: 'react',
+      libraryId: 'ai',
+      slug: 'basic-chat',
+      version: 'latest',
+    }),
+    {
+      autoStart: true,
+      entry: '/src/routes/index.tsx',
+      framework: 'react',
+      libraryId: 'ai',
+      runtime: {
+        type: 'webcontainer',
+        compatibility: 'tanstack-start-async-context',
+        install: { command: 'pnpm', args: ['install'] },
+        start: { command: 'pnpm', args: ['run', 'dev'] },
+      },
+      slug: 'basic-chat',
+    },
+  )
+  assert.equal(
+    getClientExampleConfig({
+      framework: 'react',
+      libraryId: 'ai',
+      slug: 'basic-chat',
+      version: 'v0',
+    }),
+    undefined,
+  )
   assert.deepEqual(
     getClientExampleConfig({
       framework: 'react',
       libraryId: 'start',
       slug: 'start-streaming-data-from-server-functions',
+
       version: 'latest',
     }),
     {
diff --git a/tests/rewrite-workspace-protocol.test.ts b/tests/rewrite-workspace-protocol.test.ts
new file mode 100644
index 000000000..90571d64e
--- /dev/null
+++ b/tests/rewrite-workspace-protocol.test.ts
@@ -0,0 +1,75 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { rewriteWorkspaceProtocolDependencies } from '../src/utils/repository-example'
+
+test('rewrites @tanstack/ai workspace:* versions to latest', () => {
+  const packageJson = JSON.stringify({
+    dependencies: {
+      '@tanstack/ai': 'workspace:*',
+      '@tanstack/ai-react': 'workspace:*',
+      '@tanstack/ai-solid': 'workspace:^',
+      react: '^19.2.3',
+    },
+    devDependencies: {
+      '@tanstack/ai-devtools': 'workspace:*',
+    },
+    peerDependencies: {
+      '@tanstack/react-query': 'workspace:*',
+    },
+  })
+  const expectedManifest = {
+    dependencies: {
+      '@tanstack/ai': 'latest',
+      '@tanstack/ai-react': 'latest',
+      '@tanstack/ai-solid': 'workspace:^',
+      react: '^19.2.3',
+    },
+    devDependencies: {
+      '@tanstack/ai-devtools': 'latest',
+    },
+    peerDependencies: {
+      '@tanstack/react-query': 'workspace:*',
+    },
+  }
+
+  for (const path of ['package.json', '/package.json']) {
+    const files = {
+      [path]: packageJson,
+      '/src/main.ts': 'export const value = 1',
+    }
+
+    const result = rewriteWorkspaceProtocolDependencies(files)
+
+    assert.deepEqual(JSON.parse(result[path]), expectedManifest)
+    assert.equal(result['/src/main.ts'], 'export const value = 1')
+    assert.equal(files[path], packageJson)
+  }
+})
+
+test('leaves files unchanged when package.json is missing', () => {
+  const files = {
+    '/src/main.ts': 'export const value = 1',
+  }
+
+  const result = rewriteWorkspaceProtocolDependencies(files)
+
+  assert.deepEqual(result, {
+    '/src/main.ts': 'export const value = 1',
+  })
+})
+
+test('leaves files unchanged when package.json is invalid JSON', () => {
+  const files = {
+    '/package.json': '{ not-json',
+    '/src/main.ts': 'export const value = 1',
+  }
+
+  const result = rewriteWorkspaceProtocolDependencies(files)
+
+  assert.deepEqual(result, {
+    '/package.json': '{ not-json',
+    '/src/main.ts': 'export const value = 1',
+  })
+  assert.equal(result['/package.json'], files['/package.json'])
+  assert.equal(result['/src/main.ts'], files['/src/main.ts'])
+})

From 34ddfaa5822983c942d8e60c58c83ae8883d7730 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 17 Sep 2026 14:39:21 +0200
Subject: [PATCH 2/2] feat: auto-run AI React examples in the docs sandbox

Any kebab-case slug under examples/react uses the Start WebContainer runtime. New AI tutorials do not need a site allowlist row.
---
 src/utils/client-example-config.ts | 57 ++++++++++++++++++++++--------
 tests/repository-example.test.ts   | 39 ++++++++++++++++++++
 2 files changed, 82 insertions(+), 14 deletions(-)

diff --git a/src/utils/client-example-config.ts b/src/utils/client-example-config.ts
index 8330f71fa..031d5aaf7 100644
--- a/src/utils/client-example-config.ts
+++ b/src/utils/client-example-config.ts
@@ -253,19 +253,6 @@ const clientExampleConfigs: ReadonlyArray<ClientExampleConfig> = [
     },
     slug: 'start-basic',
   },
-  {
-    autoStart: true,
-    entry: '/src/routes/index.tsx',
-    framework: 'react',
-    libraryId: 'ai',
-    runtime: {
-      type: 'webcontainer',
-      compatibility: 'tanstack-start-async-context',
-      install: { command: 'pnpm', args: ['install'] },
-      start: { command: 'pnpm', args: ['run', 'dev'] },
-    },
-    slug: 'basic-chat',
-  },
   {
     autoStart: true,
     entry: '/src/routes/index.tsx',
@@ -281,6 +268,37 @@ const clientExampleConfigs: ReadonlyArray<ClientExampleConfig> = [
   },
 ]
 
+const aiReactStartExampleRuntime = {
+  type: 'webcontainer',
+  compatibility: 'tanstack-start-async-context',
+  install: { command: 'pnpm', args: ['install'] },
+  start: { command: 'pnpm', args: ['run', 'dev'] },
+} as const satisfies ExampleRuntime
+
+const aiExampleSlugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+function isAiReactExampleSlug(slug: string) {
+  return aiExampleSlugPattern.test(slug)
+}
+
+function aiReactStartExampleConfig(slug: string): ClientExampleConfig {
+  return {
+    autoStart: true,
+    entry: '/src/routes/index.tsx',
+    framework: 'react',
+    libraryId: 'ai',
+    runtime: aiReactStartExampleRuntime,
+    slug,
+  }
+}
+
+/**
+ * Resolve the in-browser example player for a docs example.
+ *
+ * `libraryId` `ai` and `framework` `react` do not need an allowlist row.
+ * Any kebab-case `slug` uses the TanStack Start WebContainer runtime and
+ * fetches `examples/react/<slug>` from the AI repo.
+ */
 export function getClientExampleConfig({
   framework,
   libraryId,
@@ -294,10 +312,21 @@ export function getClientExampleConfig({
 }) {
   if (version !== 'latest') return undefined
 
-  return clientExampleConfigs.find(
+  const listed = clientExampleConfigs.find(
     (config) =>
       config.libraryId === libraryId &&
       config.framework === framework &&
       config.slug === slug,
   )
+  if (listed) return listed
+
+  if (
+    libraryId === 'ai' &&
+    framework === 'react' &&
+    isAiReactExampleSlug(slug)
+  ) {
+    return aiReactStartExampleConfig(slug)
+  }
+
+  return undefined
 }
diff --git a/tests/repository-example.test.ts b/tests/repository-example.test.ts
index 8090761b0..240072752 100644
--- a/tests/repository-example.test.ts
+++ b/tests/repository-example.test.ts
@@ -230,6 +230,45 @@ test('selects only verified current client examples', () => {
     }),
     undefined,
   )
+  assert.deepEqual(
+    getClientExampleConfig({
+      framework: 'react',
+      libraryId: 'ai',
+      slug: 'tools-chat',
+      version: 'latest',
+    }),
+    {
+      autoStart: true,
+      entry: '/src/routes/index.tsx',
+      framework: 'react',
+      libraryId: 'ai',
+      runtime: {
+        type: 'webcontainer',
+        compatibility: 'tanstack-start-async-context',
+        install: { command: 'pnpm', args: ['install'] },
+        start: { command: 'pnpm', args: ['run', 'dev'] },
+      },
+      slug: 'tools-chat',
+    },
+  )
+  assert.equal(
+    getClientExampleConfig({
+      framework: 'react',
+      libraryId: 'ai',
+      slug: '../secret',
+      version: 'latest',
+    }),
+    undefined,
+  )
+  assert.equal(
+    getClientExampleConfig({
+      framework: 'vue',
+      libraryId: 'ai',
+      slug: 'basic-chat',
+      version: 'latest',
+    }),
+    undefined,
+  )
   assert.deepEqual(
     getClientExampleConfig({
       framework: 'react',