feat: Introduce fal.ai adapter for image and video generation

.gitignore

@@ -58,4 +58,7 @@ test-traces
 playwright-report
 test-results
 
-STATUS_*.md
+STATUS_*.md
+
+# Only .claude.settings.json should be committed
+.claude/settings.local.json

examples/ts-react-fal/.env.example

@@ -0,0 +1,4 @@
+# Duplicate the .env.example file and rename it to .env.local, then add your FAL_KEY.
+
+# Sign up for an account at https://fal.ai, and add $20 of credits to your account to get started.
+FAL_KEY=

examples/ts-react-fal/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "ts-react-fal",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "build": "vite build",
+    "serve": "vite preview",
+    "test": "exit 0",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-fal": "workspace:*",
+    "@tanstack/react-router": "^1.158.4",
+    "@tanstack/react-start": "^1.159.0",
+    "@tanstack/router-plugin": "^1.158.4",
+    "lucide-react": "^0.561.0",
+    "nitro": "3.0.1-alpha.2",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tailwindcss": "^4.1.18",
+    "vite-tsconfig-paths": "^5.1.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "typescript": "5.9.3",
+    "vite": "^7.2.7"
+  }
+}

examples/ts-react-fal/src/components/Header.tsx

@@ -0,0 +1,17 @@
+import { Link } from '@tanstack/react-router'
+
+export default function Header() {
+  return (
+    <header className="p-4 flex items-center bg-gray-800 text-white shadow-lg">
+      <h1 className="text-xl font-semibold">
+        <Link to="/" className="flex items-center gap-3">
+          <span className="text-2xl">🎨</span>
+          <span>TanStack AI Visual</span>
+        </Link>
+      </h1>
+      <span className="ml-4 text-sm text-gray-400">
+        Image & Video Generation with fal.ai
+      </span>
+    </header>
+  )
+}

examples/ts-react-fal/src/components/ImageGenerator.tsx

@@ -0,0 +1,209 @@
+import { useState } from 'react'
+import { ImageIcon, Loader2, Shuffle } from 'lucide-react'
+import type { ImageGenerationResult } from '@tanstack/ai'
+
+import { generateImageFn } from '@/lib/server-functions'
+import { getRandomImagePrompt } from '@/lib/prompts'
+import { IMAGE_MODELS } from '@/lib/models'
+
+interface ImageGeneratorProps {
+  onImageGenerated?: (imageUrl: string) => void
+}
+
+type ModelResult = {
+  status: 'loading' | 'success' | 'error'
+  result?: ImageGenerationResult
+  error?: string
+}
+
+export default function ImageGenerator({
+  onImageGenerated,
+}: ImageGeneratorProps) {
+  const [prompt, setPrompt] = useState('')
+  const [selectedModel, setSelectedModel] = useState<string>('all')
+  const [isLoading, setIsLoading] = useState(false)
+  const [results, setResults] = useState<Record<string, ModelResult>>({})
+
+  const currentModel = IMAGE_MODELS.find((m) => m.id === selectedModel)
+
+  const handleGenerate = async () => {
+    if (!prompt.trim()) return
+
+    setIsLoading(true)
+    setResults({})
+
+    if (selectedModel === 'all') {
+      // Initialize all models as loading
+      const initialResults: Record<string, ModelResult> = {}
+      for (const model of IMAGE_MODELS) {
+        initialResults[model.id] = { status: 'loading' }
+      }
+      setResults(initialResults)
+
+      // Fire all requests in parallel
+      const promises = IMAGE_MODELS.map(async (model) => {
+        try {
+          const response = await generateImageFn({
+            data: { prompt, model: model.id },
+          })
+          setResults((prev) => ({
+            ...prev,
+            [model.id]: { status: 'success', result: response },
+          }))
+          const imageUrl = response.images[0]?.url
+          if (imageUrl) {
+            onImageGenerated?.(imageUrl)
+          }
+        } catch (err) {
+          setResults((prev) => ({
+            ...prev,
+            [model.id]: {
+              status: 'error',
+              error:
+                err instanceof Error ? err.message : 'Failed to generate image',
+            },
+          }))
+        }
+      })
+
+      await Promise.allSettled(promises)
+      setIsLoading(false)
+    } else {
+      // Single model generation
+      setResults({ [selectedModel]: { status: 'loading' } })
+
+      try {
+        const response = await generateImageFn({
+          data: { prompt, model: selectedModel },
+        })
+        setResults({ [selectedModel]: { status: 'success', result: response } })
+        const imageUrl = response.images[0]?.url
+        if (imageUrl) {
+          onImageGenerated?.(imageUrl)
+        }
+      } catch (err) {
+        setResults({
+          [selectedModel]: {
+            status: 'error',
+            error:
+              err instanceof Error ? err.message : 'Failed to generate image',
+          },
+        })
+      } finally {
+        setIsLoading(false)
+      }
+    }
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="space-y-4">
+        <div>
+          <label className="block text-sm font-medium text-gray-300 mb-2">
+            Model
+          </label>
+          <select
+            value={selectedModel}
+            onChange={(e) => setSelectedModel(e.target.value)}
+            disabled={isLoading}
+            className="w-full px-4 py-3 bg-gray-800 border border-gray-700 rounded-lg text-white focus:outline-none focus:ring-2 focus:ring-purple-500 focus:border-transparent disabled:opacity-50"
+          >
+            <option value="all">All Models</option>
+            {IMAGE_MODELS.map((model) => (
+              <option key={model.id} value={model.id}>
+                {model.name}
+              </option>
+            ))}
+          </select>
+          {currentModel && selectedModel !== 'all' && (
+            <p className="mt-1 text-xs text-gray-500">
+              {currentModel.description}
+            </p>
+          )}
+        </div>
+
+        <div>
+          <div className="flex items-center justify-between mb-2">
+            <label className="text-sm font-medium text-gray-300">Prompt</label>
+            <button
+              onClick={() => setPrompt(getRandomImagePrompt())}
+              disabled={isLoading}
+              className="flex items-center gap-1.5 px-3 py-1 text-xs font-medium text-purple-400 hover:text-purple-300 bg-purple-500/10 hover:bg-purple-500/20 rounded-md transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+            >
+              <Shuffle className="w-3.5 h-3.5" />
+              Shuffle
+            </button>
+          </div>
+          <textarea
+            value={prompt}
+            onChange={(e) => setPrompt(e.target.value)}
+            placeholder="Describe the image you want to generate..."
+            className="w-full px-4 py-3 bg-gray-800 border border-gray-700 rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:border-transparent resize-none"
+            rows={3}
+            disabled={isLoading}
+          />
+        </div>
+
+        <button
+          onClick={handleGenerate}
+          disabled={isLoading || !prompt.trim()}
+          className="w-full px-6 py-3 bg-purple-600 hover:bg-purple-700 disabled:bg-gray-700 disabled:cursor-not-allowed text-white font-medium rounded-lg transition-colors flex items-center justify-center gap-2"
+        >
+          {isLoading ? (
+            <>
+              <Loader2 className="w-5 h-5 animate-spin" />
+              Generating...
+            </>
+          ) : (
+            <>
+              <ImageIcon className="w-5 h-5" />
+              Generate Image
+            </>
+          )}
+        </button>
+      </div>
+
+      {Object.keys(results).length > 0 && (
+        <div className="space-y-6">
+          <h3 className="text-lg font-medium text-white">
+            {selectedModel === 'all' ? 'Generated Images' : 'Generated Image'}
+          </h3>
+          {Object.entries(results).map(([modelId, modelResult]) => {
+            const model = IMAGE_MODELS.find((m) => m.id === modelId)
+            return (
+              <div key={modelId} className="space-y-2">
+                {selectedModel === 'all' && (
+                  <h4 className="text-sm font-medium text-gray-300">
+                    {model?.name ?? modelId}
+                  </h4>
+                )}
+                {modelResult.status === 'loading' && (
+                  <div className="flex items-center gap-2 p-4 bg-gray-800 rounded-lg border border-gray-700">
+                    <Loader2 className="w-5 h-5 animate-spin text-purple-400" />
+                    <span className="text-gray-400">Generating...</span>
+                  </div>
+                )}
+                {modelResult.status === 'error' && (
+                  <div className="p-4 bg-red-500/10 border border-red-500/20 rounded-lg text-red-400">
+                    {modelResult.error}
+                  </div>
+                )}
+                {modelResult.status === 'success' &&
+                  modelResult.result &&
+                  modelResult.result.images.length > 0 && (
+                    <div className="rounded-lg overflow-hidden border border-gray-700">
+                      <img
+                        src={modelResult.result.images[0]?.url}
+                        alt={`Generated by ${model?.name ?? modelId}`}
+                        className="w-full h-auto"
+                      />
+                    </div>
+                  )}
+              </div>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}