feat: embed AI Basic Chat in the docs sandbox

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>
+  )
+}

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))
+}

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(

src/utils/client-example-config.ts

@@ -268,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,
@@ -281,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
 }

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,