fix(ai-worldlabs): reject empty worlds and settled wait:false jobs

Guard poll payloads and Spark setup errors. Cover seed photos, the
splat allowlist, and plan/recorder failures in tests.

Author: tombeckenham

docs/adapters/worldlabs.md

@@ -12,7 +12,7 @@ keywords:
   - adapter
 ---
 
-You want a finished 3D world from a prompt, an image, or a video. World Labs Marble generates splat files, a mesh, and a viewer URL. Generation takes a few minutes.
+You want a finished 3D world from a prompt, an image, or a video. World Labs Marble generates splat files, a mesh, and a viewer URL. Generation often takes several minutes.
 
 Use `worldlabsWorld()` with `generateWorld()`. This adapter does not support `chat()`.
 
@@ -45,12 +45,13 @@ const apiKey = process.env.WORLDLABS_API_KEY ?? ''
 const world = await generateWorld({
   adapter: worldlabsWorld('marble-1.1', { apiKey }),
   prompt: 'A mystical forest with glowing mushrooms',
+  timeout: 12 * 60 * 1000,
 })
 ```
 
-`world.url` is the Marble viewer URL (`https://marble.worldlabs.ai/world/{id}`). `world.assets` has splat, mesh, panorama, and thumbnail links when the job finishes.
+`world.url` is the Marble viewer URL (`https://marble.worldlabs.ai/world/{id}`). Do not iframe it. `world.assets` is optional. Splat, mesh, panorama, and thumbnail links appear only when the World Labs response includes them. Those URLs are often signed CDN links.
 
-World Labs bills in credits per generation. The call waits until the world is ready (about 5 minutes). Pass a long `timeout` on serverless, or set `wait: false` and poll later.
+World Labs bills in credits per generation. The call waits until the world is ready (often several minutes). Pass a long `timeout` on serverless, or set `wait: false` and poll later.
 
 ## Models
 
@@ -64,8 +65,8 @@ const adapter = worldlabsWorld('marble-1.1')
 
 | Id | Notes |
 | --- | --- |
-| `marble-1.1-plus` | Largest outdoor and indoor worlds. Uses more credits. |
-| `marble-1.1` | Default Marble 1.1 |
+| `marble-1.1-plus` | Dynamic world sizing |
+| `marble-1.1` | World Labs default model id |
 | `marble-1.0` | Marble 1.0 |
 | `marble-1.0-draft` | Faster draft quality |
 
@@ -97,23 +98,12 @@ Pass only one of `image`, `images`, or `video`.
 | `video` | One video. Same source fields as `image` |
 | `isPano` | `auto`, `true`, or `false` for a single image |
 | `wait` | Default `true`. Set `false` to return `operationId` at once |
+| `pollIntervalMs` | Poll delay when `wait` is true. Default 2000 |
 
-Optional metadata: `displayName`, `seed`, `tags`.
+Optional metadata: `displayName`, `seed`, `tags`, `disableRecaption`, `permission`.
 
-When `wait` is `false`, `world.status` is `waiting` and `world.operationId` is set. Call `generateWorld` again with `wait: true` only starts a new job. Poll the World Labs operations API with that id, or keep `wait` at the default.
-
-## Custom endpoint
-
-```ts
-import { worldlabsWorld } from '@tanstack/ai-worldlabs'
-
-const apiKey = process.env.WORLDLABS_API_KEY ?? ''
-const adapter = worldlabsWorld('marble-1.1', {
-  apiKey,
-  baseUrl: 'https://api.worldlabs.ai',
-})
-```
+When `wait` is `false`, `world.status` is `waiting` and `world.operationId` is set. This adapter cannot resume that id. Call `generateWorld` again with `wait: true` only starts a new job. Poll `GET /marble/v1/operations/{operationId}` yourself, or keep `wait` at the default.
 
 ## What you have now
 
-A server call that generates a Marble world and returns the viewer URL plus asset links. The media example loads `world.assets.splats.spzUrls` in Spark so you can walk the scene in the page. You can also open `world.url`. Splat export needs a World Labs plan that returns those files.
+A server call that generates a Marble world and returns the viewer URL plus optional asset links. The media example picks one SPZ (prefers `500k`) and loads it in Spark through `/api/marble-splat`. If no splat URL is present, it shows a thumbnail and an Open in Marble link.

docs/config.json

@@ -621,7 +621,7 @@
           "label": "World Generation",
           "to": "media/world-generation",
           "addedAt": "2026-09-04",
-          "updatedAt": "2026-09-15"
+          "updatedAt": "2026-09-17"
         },
         {
           "label": "Generation Hooks",
@@ -1026,7 +1026,7 @@
           "label": "World Labs",
           "to": "adapters/worldlabs",
           "addedAt": "2026-09-14",
-          "updatedAt": "2026-09-15"
+          "updatedAt": "2026-09-17"
         },
         {
           "label": "OpenRouter Adapter",

docs/media/world-generation.md

@@ -18,7 +18,7 @@ keywords:
 
 # World Generation (Experimental)
 
-You want a world from a prompt. Some providers open a live session you can steer. Other providers generate a finished 3D world you can view and download.
+You want a world from a prompt. Some providers open a live session you can steer. Other providers generate a finished 3D world. Open `world.url` to view it. Asset URLs on `world.assets` are often signed.
 
 Call `generateWorld()` on the server with a world adapter. Reactor mints a session token. World Labs returns a Marble viewer URL after the job finishes.
 
@@ -161,7 +161,7 @@ await reactor.sendCommand('start', {})
 
 Happy Oyster (`happy-oyster-adventure`, `happy-oyster-director`) uses `createWorld` and `startTravel` after connect. See the [Reactor adapter](../adapters/reactor) for every id. Helios also works with `generateLiveVideo()` and `reactorVideo()`. See [Live Generation](./live-generation).
 
-A full app lives in [`examples/ts-react-media`](https://github.com/TanStack/ai/tree/main/examples/ts-react-media). Open the World tab. Pick a Reactor model for a live stream, or a Marble model for a finished 3D world. Marble worlds play in the page with Spark.
+A full app lives in [`examples/ts-react-media`](https://github.com/TanStack/ai/tree/main/examples/ts-react-media). Open the World tab. Pick a Reactor model for a live stream, or a Marble model for a finished 3D world. If splat files are present, the example loads one SPZ in Spark. If not, it shows a thumbnail and an Open in Marble link.
 
 ## Finished 3D worlds (World Labs)
 
@@ -178,8 +178,8 @@ const world = await generateWorld({
 })
 ```
 
-`world.url` is the Marble viewer. `world.assets` has splat, mesh, and panorama URLs. See the [World Labs adapter](../adapters/worldlabs) for image and video inputs, models, and `wait: false`.
+`world.url` is the Marble viewer. Do not iframe it. `world.assets` is optional and holds splat, mesh, and panorama URLs when the provider returns them. See the [World Labs adapter](../adapters/worldlabs) for image and video inputs, models, and `wait: false`. `wait: false` returns `operationId`. This SDK cannot resume that id.
 
 ## What you have now
 
-A server route that mints a live world session, or a server call that returns a finished Marble world. For Reactor, connect in the browser and change the prompt to steer the stream. The media example can save a Reactor session as MP4 when the model has recording enabled, and download Marble splat files when the plan returns them.
+A server route that mints a live world session, or a server call that returns a finished Marble world. For Reactor, connect in the browser and change the prompt to steer the stream. The media example can save a Reactor session as MP4 when recording is enabled for that model or plan, and download Marble files when the response includes them.

examples/ts-react-media/package.json

@@ -6,7 +6,8 @@
     "dev": "vite dev --port 3000",
     "build": "vite build",
     "serve": "vite preview",
-    "test": "exit 0",
+    "test": "vitest run",
+    "test:lib": "vitest run",
     "test:types": "tsc"
   },
   "dependencies": {
@@ -41,6 +42,7 @@
     "@types/three": "0.180.0",
     "@vitejs/plugin-react": "^5.2.0",
     "typescript": "5.9.3",
-    "vite": "^8.2.1"
+    "vite": "^8.2.1",
+    "vitest": "^4.1.10"
   }
 }

examples/ts-react-media/src/components/MarbleViewer.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useRef, useState } from 'react'
 import { Loader2 } from 'lucide-react'
+import type { Object3D, PerspectiveCamera, Scene, WebGLRenderer } from 'three'
 import { marbleSplatProxyPath, splatFileName } from '@/lib/marble-splat'
 
 type MarbleViewerProps = {
@@ -8,73 +9,129 @@ type MarbleViewerProps = {
   groundPlaneOffset?: number
 }
 
+type ViewerRuntime = {
+  scene: Scene
+  camera: PerspectiveCamera
+  webgl: WebGLRenderer
+  controls: { update: (camera: Object3D) => void }
+}
+
 export function MarbleViewer({
   splatUrl,
   metricScaleFactor,
   groundPlaneOffset,
 }: MarbleViewerProps) {
   const containerRef = useRef<HTMLDivElement>(null)
+  const runtimeRef = useRef<ViewerRuntime | null>(null)
+  const splatRef = useRef<{ dispose: () => void } | null>(null)
+  const [runtimeReady, setRuntimeReady] = useState(0)
   const [loading, setLoading] = useState(true)
   const [error, setError] = useState<string | null>(null)
 
   useEffect(() => {
-    const container = containerRef.current
-    if (!container) return
+    const host = containerRef.current
+    if (!host) return
+    const root = host
 
-    let disposed = false
-    let renderer: import('three').WebGLRenderer | null = null
-    let splat: { dispose: () => void } | null = null
-    let resizeObserver: ResizeObserver | null = null
+    let cancelled = false
+    let webgl: WebGLRenderer | undefined
+    let resizeObserver: ResizeObserver | undefined
 
-    async function start() {
+    void (async () => {
       const THREE = await import('three')
       const spark = await import('@sparkjsdev/spark')
-      if (disposed || !container) return
-      const host = container
+      if (cancelled) return
 
       const scene = new THREE.Scene()
       const camera = new THREE.PerspectiveCamera(70, 1, 0.05, 8000)
       camera.position.set(0, 1.6, 0)
 
-      const webgl = new THREE.WebGLRenderer({ antialias: true })
+      webgl = new THREE.WebGLRenderer({ antialias: true })
       webgl.setClearColor(0x000000, 1)
       webgl.setPixelRatio(Math.min(window.devicePixelRatio, 2))
-      webgl.domElement.tabIndex = 0
-      webgl.domElement.className = 'block h-full w-full outline-none'
-      host.appendChild(webgl.domElement)
-      renderer = webgl
+      const canvas = webgl.domElement
+      canvas.tabIndex = 0
+      canvas.className = 'block h-full w-full outline-none'
+      root.appendChild(canvas)
 
       const sparkRenderer = new spark.SparkRenderer({ renderer: webgl })
       scene.add(sparkRenderer)
-      const controls = new spark.SparkControls({ canvas: webgl.domElement })
+      const controls = new spark.SparkControls({ canvas })
       controls.fpsMovement.enable = false
-      webgl.domElement.addEventListener('pointerdown', () => {
-        webgl.domElement.focus()
+      canvas.addEventListener('pointerdown', () => {
+        canvas.focus()
       })
-      webgl.domElement.addEventListener('focus', () => {
+      canvas.addEventListener('focus', () => {
         controls.fpsMovement.enable = true
       })
-      webgl.domElement.addEventListener('blur', () => {
+      canvas.addEventListener('blur', () => {
         controls.fpsMovement.enable = false
       })
+      canvas.addEventListener('webglcontextlost', (event) => {
+        event.preventDefault()
+        setError('The 3D viewer lost the GPU context')
+      })
 
       function resize() {
-        const width = host.clientWidth || 1
-        const height = host.clientHeight || 1
+        if (!webgl) return
+        const width = root.clientWidth || 1
+        const height = root.clientHeight || 1
         camera.aspect = width / height
         camera.updateProjectionMatrix()
         webgl.setSize(width, height, false)
       }
       resize()
       resizeObserver = new ResizeObserver(resize)
-      resizeObserver.observe(host)
+      resizeObserver.observe(root)
+
+      runtimeRef.current = { scene, camera, webgl, controls }
+      webgl.setAnimationLoop(() => {
+        const runtime = runtimeRef.current
+        if (!runtime) return
+        runtime.controls.update(runtime.camera)
+        runtime.webgl.render(runtime.scene, runtime.camera)
+      })
+      setRuntimeReady((count) => count + 1)
+    })().catch((caught: unknown) => {
+      if (cancelled) return
+      setLoading(false)
+      setError(caught instanceof Error ? caught.message : String(caught))
+    })
 
-      const response = await fetch(marbleSplatProxyPath(splatUrl))
-      if (!response.ok) {
-        throw new Error('Splat download failed')
+    return () => {
+      cancelled = true
+      resizeObserver?.disconnect()
+      splatRef.current?.dispose()
+      splatRef.current = null
+      if (webgl) {
+        webgl.setAnimationLoop(null)
+        webgl.dispose()
+        webgl.domElement.remove()
       }
+      runtimeRef.current = null
+    }
+  }, [])
+
+  useEffect(() => {
+    const runtime = runtimeRef.current
+    if (!runtimeReady || !runtime) return
+
+    let cancelled = false
+    const abort = new AbortController()
+    setLoading(true)
+    setError(null)
+
+    splatRef.current?.dispose()
+    splatRef.current = null
+
+    void (async () => {
+      const spark = await import('@sparkjsdev/spark')
+      const response = await fetch(marbleSplatProxyPath(splatUrl), {
+        signal: abort.signal,
+      })
+      if (!response.ok) throw new Error('Splat download failed')
       const fileBytes = await response.arrayBuffer()
-      if (disposed) return
+      if (cancelled) return
 
       const mesh = new spark.SplatMesh({
         fileBytes,
@@ -88,35 +145,27 @@ export function MarbleViewer({
       if (groundPlaneOffset != null) {
         mesh.position.y = -groundPlaneOffset
       }
-      scene.add(mesh)
-      splat = mesh
+      runtime.scene.add(mesh)
+      splatRef.current = mesh
       await mesh.initialized
-      if (disposed) return
+      if (cancelled) {
+        mesh.dispose()
+        return
+      }
       setLoading(false)
-
-      webgl.setAnimationLoop(() => {
-        controls.update(camera)
-        webgl.render(scene, camera)
-      })
-    }
-
-    start().catch((caught: unknown) => {
-      if (disposed) return
+    })().catch((caught: unknown) => {
+      if (cancelled || abort.signal.aborted) return
       setLoading(false)
       setError(caught instanceof Error ? caught.message : String(caught))
     })
 
     return () => {
-      disposed = true
-      resizeObserver?.disconnect()
-      if (renderer) {
-        renderer.setAnimationLoop(null)
-        renderer.dispose()
-        renderer.domElement.remove()
-      }
-      splat?.dispose()
+      cancelled = true
+      abort.abort()
+      splatRef.current?.dispose()
+      splatRef.current = null
     }
-  }, [splatUrl, metricScaleFactor, groundPlaneOffset])
+  }, [runtimeReady, splatUrl, metricScaleFactor, groundPlaneOffset])
 
   return (
     <div className="relative aspect-video w-full bg-black">