Merge pull request #75 from devallibus/fix/tsl-playground-e2e-v3

fix(playground): report structured TSL errors

Author: devallibus

apps/web/src/components/TslPreviewCanvas.tsx

@@ -3,6 +3,8 @@ import type {
   TslPreviewModuleResult,
   TslPreviewModuleRuntime,
 } from '../../../../packages/schema/src/tsl-preview-module.ts'
+import { createPlainErrorReport, createTslErrorReport, TslPreviewError } from '../lib/tsl-error-reporting'
+import type { PlaygroundErrorReport } from '../lib/playground-types'
 
 type THREE = typeof import('three/webgpu')
 type TSL = typeof import('three/tsl')
@@ -12,7 +14,7 @@ type TslPreviewCanvasProps = {
   pipeline: string
   fallbackSvg?: string | null
   uniformOverrides?: Record<string, number | number[] | boolean>
-  onError?: (errors: string[]) => void
+  onError?: (report: PlaygroundErrorReport) => void
   onScreenshotReady?: (base64: string) => void
 }
 
@@ -55,14 +57,14 @@ export default function TslPreviewCanvas(props: TslPreviewCanvasProps) {
   const [loading, setLoading] = createSignal(true)
   const [error, setError] = createSignal('')
 
-  function setPreviewError(message: string) {
-    setError(message)
-    props.onError?.([message])
+  function setPreviewError(report: PlaygroundErrorReport) {
+    setError(report.errors[0] ?? report.structuredErrors[0]?.message ?? 'Preview unavailable')
+    props.onError?.(report)
   }
 
   function clearPreviewError() {
     setError('')
-    props.onError?.([])
+    props.onError?.(createPlainErrorReport([]))
   }
 
   function captureScreenshot() {
@@ -110,7 +112,10 @@ export default function TslPreviewCanvas(props: TslPreviewCanvasProps) {
 
       const module = (await import(/* @vite-ignore */ currentModuleUrl)) as PreviewModuleNamespace
       if (typeof module.createPreview !== 'function') {
-        throw new Error('TSL preview modules must export createPreview(runtime).')
+        throw new TslPreviewError(
+          'tsl-material-build',
+          'TSL preview modules must export createPreview(runtime).',
+        )
       }
 
       const nextPreview = module.createPreview({
@@ -123,7 +128,10 @@ export default function TslPreviewCanvas(props: TslPreviewCanvasProps) {
       })
 
       if (!nextPreview?.material || typeof nextPreview.material !== 'object') {
-        throw new Error('createPreview(runtime) must return an object with a material.')
+        throw new TslPreviewError(
+          'tsl-material-build',
+          'createPreview(runtime) must return an object with a material.',
+        )
       }
 
       previewInstance = nextPreview as PreviewInstance
@@ -144,9 +152,7 @@ export default function TslPreviewCanvas(props: TslPreviewCanvasProps) {
     } catch (previewError) {
       disposePreviewMesh()
       setPreviewError(
-        previewError instanceof Error
-          ? previewError.message
-          : 'Failed to build the TSL preview module.',
+        createTslErrorReport(previewError, 'tsl-runtime', 'Failed to build the TSL preview module.'),
       )
     } finally {
       setLoading(false)
@@ -155,7 +161,13 @@ export default function TslPreviewCanvas(props: TslPreviewCanvasProps) {
 
   onMount(async () => {
     if (!('gpu' in navigator)) {
-      setPreviewError('WebGPU is not available in this browser.')
+      setPreviewError(
+        createTslErrorReport(
+          new TslPreviewError('tsl-runtime', 'WebGPU is not available in this browser.'),
+          'tsl-runtime',
+          'WebGPU is not available in this browser.',
+        ),
+      )
       setLoading(false)
       return
     }
@@ -236,9 +248,7 @@ export default function TslPreviewCanvas(props: TslPreviewCanvasProps) {
       await renderPreview(props.previewModule)
     } catch (previewError) {
       setPreviewError(
-        previewError instanceof Error
-          ? previewError.message
-          : 'Failed to initialize the TSL preview runtime.',
+        createTslErrorReport(previewError, 'tsl-runtime', 'Failed to initialize the TSL preview runtime.'),
       )
       setLoading(false)
     }

apps/web/src/components/playground/PlaygroundCanvas.tsx

@@ -1,6 +1,8 @@
 import { createEffect, createMemo, createSignal, on, onCleanup, onMount } from 'solid-js'
 import { buildTslPreviewModule } from '../../../../../packages/schema/src/tsl-preview-module.ts'
 import { collectShaderDiagnostics, diagnosticsToMessages } from '../../lib/webgl-shader-errors'
+import { createPlainErrorReport, createTslErrorReport } from '../../lib/tsl-error-reporting'
+import type { PlaygroundErrorReport } from '../../lib/playground-types'
 import TslPreviewCanvas from '../TslPreviewCanvas'
 
 type THREE = typeof import('three')
@@ -11,7 +13,7 @@ type PlaygroundCanvasProps = {
   tslSource?: string
   pipeline: string
   language: 'glsl' | 'tsl'
-  onError: (errors: string[]) => void
+  onError: (report: PlaygroundErrorReport) => void
   onScreenshotReady: (base64: string) => void
 }
 
@@ -29,7 +31,7 @@ export default function PlaygroundCanvas(props: PlaygroundCanvasProps) {
     try {
       return buildTslPreviewModule(props.tslSource)
     } catch (error) {
-      props.onError([error instanceof Error ? error.message : 'Failed to build TSL preview module'])
+      props.onError(createTslErrorReport(error, 'tsl-parse', 'Failed to build TSL preview module.'))
       return ''
     }
   })
@@ -172,7 +174,7 @@ export default function PlaygroundCanvas(props: PlaygroundCanvasProps) {
         uniforms: shaderUniforms,
       })
     } catch (e) {
-      props.onError([e instanceof Error ? e.message : 'Shader compilation failed'])
+      props.onError(createPlainErrorReport([e instanceof Error ? e.message : 'Shader compilation failed']))
       return
     }
 
@@ -210,21 +212,21 @@ export default function PlaygroundCanvas(props: PlaygroundCanvasProps) {
         ? renderError.message
         : 'Shader compilation failed'
 
-      props.onError(
+      props.onError(createPlainErrorReport(
         shaderDiagnostics.length > 0 ? diagnosticsToMessages(shaderDiagnostics) : [fallbackMessage],
-      )
+      ))
       return
     } finally {
       renderer.debug.onShaderError = previousShaderError
     }
 
     if (shaderDiagnostics.length > 0) {
-      props.onError(diagnosticsToMessages(shaderDiagnostics))
+      props.onError(createPlainErrorReport(diagnosticsToMessages(shaderDiagnostics)))
       return
     }
 
     // No errors — clear any previous errors and capture screenshot
-    props.onError([])
+    props.onError(createPlainErrorReport([]))
     captureScreenshot()
   }
 

apps/web/src/components/playground/PlaygroundLayout.tsx

@@ -1,5 +1,5 @@
 import { createSignal, onCleanup, onMount, Show, lazy } from 'solid-js'
-import type { PlaygroundSession } from '../../lib/playground-types'
+import type { PlaygroundErrorReport, PlaygroundSession } from '../../lib/playground-types'
 
 const PlaygroundCanvas = lazy(() => import('./PlaygroundCanvas'))
 const PlaygroundEditor = lazy(() => import('./PlaygroundEditor'))
@@ -93,13 +93,13 @@ export default function PlaygroundLayout(props: PlaygroundLayoutProps) {
     }
   }
 
-  function handleErrors(errs: string[]) {
-    setErrors(errs)
+  function handleErrors(report: PlaygroundErrorReport) {
+    setErrors(report.errors)
     // Post errors to server so MCP can query them
     fetch(`/api/playground/${props.session.id}/errors`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ errors: errs }),
+      body: JSON.stringify(report),
     }).catch(() => {})
   }
 

apps/web/src/lib/playground-types.ts

@@ -29,6 +29,11 @@ export type PlaygroundError =
   | { kind: 'tsl-runtime'; message: string }
   | { kind: 'tsl-material-build'; message: string }
 
+export type PlaygroundErrorReport = {
+  errors: string[]
+  structuredErrors: PlaygroundError[]
+}
+
 // ---------------------------------------------------------------------------
 // Session types — discriminated union on language
 // ---------------------------------------------------------------------------

apps/web/src/lib/tsl-error-reporting.test.ts

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict'
+import {
+  createPlainErrorReport,
+  createTslErrorReport,
+  TslPreviewError,
+} from './tsl-error-reporting.ts'
+
+function runTest(name: string, callback: () => void) {
+  callback()
+  console.log(`ok ${name}`)
+}
+
+runTest('createPlainErrorReport keeps structured errors empty', () => {
+  assert.deepEqual(createPlainErrorReport(['plain error']), {
+    errors: ['plain error'],
+    structuredErrors: [],
+  })
+})
+
+runTest('createTslErrorReport preserves explicit preview error kinds', () => {
+  const report = createTslErrorReport(
+    new TslPreviewError('tsl-material-build', 'createPreview(runtime) must return a material.'),
+    'tsl-runtime',
+    'fallback',
+  )
+
+  assert.deepEqual(report, {
+    errors: ['createPreview(runtime) must return a material.'],
+    structuredErrors: [{
+      kind: 'tsl-material-build',
+      message: 'createPreview(runtime) must return a material.',
+    }],
+  })
+})
+
+runTest('createTslErrorReport maps SyntaxError to tsl-parse', () => {
+  const report = createTslErrorReport(
+    new SyntaxError('Unexpected token'),
+    'tsl-runtime',
+    'fallback',
+  )
+
+  assert.deepEqual(report, {
+    errors: ['Unexpected token'],
+    structuredErrors: [{
+      kind: 'tsl-parse',
+      message: 'Unexpected token',
+    }],
+  })
+})
+
+console.log('tsl-error-reporting tests passed')

apps/web/src/lib/tsl-error-reporting.ts

@@ -0,0 +1,50 @@
+import type { PlaygroundErrorReport, PlaygroundError } from './playground-types'
+
+type TslErrorKind = Extract<PlaygroundError['kind'], 'tsl-parse' | 'tsl-runtime' | 'tsl-material-build'>
+
+export class TslPreviewError extends Error {
+  kind: TslErrorKind
+
+  constructor(kind: TslErrorKind, message: string) {
+    super(message)
+    this.kind = kind
+    this.name = 'TslPreviewError'
+  }
+}
+
+function getMessage(error: unknown, fallbackMessage: string): string {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message.trim()
+  }
+
+  if (typeof error === 'string' && error.trim()) {
+    return error.trim()
+  }
+
+  return fallbackMessage
+}
+
+export function createPlainErrorReport(errors: string[]): PlaygroundErrorReport {
+  return {
+    errors,
+    structuredErrors: [],
+  }
+}
+
+export function createTslErrorReport(
+  error: unknown,
+  fallbackKind: TslErrorKind,
+  fallbackMessage: string,
+): PlaygroundErrorReport {
+  const message = getMessage(error, fallbackMessage)
+  const kind = error instanceof TslPreviewError
+    ? error.kind
+    : error instanceof SyntaxError
+      ? 'tsl-parse'
+      : fallbackKind
+
+  return {
+    errors: [message],
+    structuredErrors: [{ kind, message }],
+  }
+}

package.json

@@ -13,7 +13,7 @@
     "check": "bun run test && bun run typecheck && bun run validate:shaders && bun run build:web",
     "dev:web": "cd apps/web && bun run dev",
     "test": "node --experimental-strip-types packages/schema/src/index.test.ts && bun run test:cli && bun run test:mcp && bun run test:registry && bun run test:web",
-    "test:web": "node --experimental-strip-types apps/web/src/lib/server/shaders.test.ts && node --experimental-strip-types apps/web/src/lib/server/reviews-db.test.node.ts && node --experimental-strip-types apps/web/src/lib/server/playground-db.test.node.ts && node --experimental-strip-types apps/web/src/lib/webgl-shader-errors.test.ts",
+    "test:web": "node --experimental-strip-types apps/web/src/lib/server/shaders.test.ts && node --experimental-strip-types apps/web/src/lib/server/reviews-db.test.node.ts && node --experimental-strip-types apps/web/src/lib/server/playground-db.test.node.ts && node --experimental-strip-types apps/web/src/lib/webgl-shader-errors.test.ts && node --experimental-strip-types apps/web/src/lib/tsl-error-reporting.test.ts",
     "test:cli": "node --experimental-strip-types packages/cli/src/registry-types.test.ts && node --experimental-strip-types packages/cli/src/commands/search.test.ts && node --experimental-strip-types packages/cli/src/commands/add.test.ts && node --experimental-strip-types packages/cli/src/lib/resolve-source.test.ts && node --experimental-strip-types packages/cli/src/lib/build-manifest.test.ts && node --experimental-strip-types packages/cli/src/lib/github-pr.test.ts && node --experimental-strip-types packages/cli/src/commands/submit.test.ts",
     "test:mcp": "node --experimental-strip-types packages/mcp/src/handlers.test.ts && node --experimental-strip-types packages/mcp/src/index.test.ts",
     "test:registry": "node --experimental-strip-types scripts/build-registry.test.ts",