fix: harden viewer/editor renderer init and error handling (#133)

apps/editor/app/editor/[projectId]/error.tsx

@@ -0,0 +1,42 @@
+'use client'
+
+import Link from 'next/link'
+import { useEffect } from 'react'
+
+export default function EditorRouteError({
+  error,
+  reset,
+}: Readonly<{
+  error: Error & { digest?: string }
+  reset: () => void
+}>) {
+  useEffect(() => {
+    console.error('[editor-route] Unhandled editor error:', error)
+  }, [error])
+
+  return (
+    <div className="flex min-h-screen w-full items-center justify-center bg-background p-4 text-foreground">
+      <div className="w-full max-w-md rounded-2xl border border-border/60 bg-background p-6 shadow-xl">
+        <h1 className="text-lg font-semibold">Editor error</h1>
+        <p className="mt-2 text-sm text-muted-foreground">
+          We couldn&apos;t load this editor route. You can retry or return home.
+        </p>
+        <div className="mt-4 flex items-center gap-2">
+          <button
+            className="rounded-md border border-border bg-accent px-3 py-2 text-sm font-medium hover:bg-accent/80"
+            onClick={reset}
+            type="button"
+          >
+            Try again
+          </button>
+          <Link
+            className="rounded-md border border-border bg-background px-3 py-2 text-sm font-medium hover:bg-accent/40"
+            href="/"
+          >
+            Back to home
+          </Link>
+        </div>
+      </div>
+    </div>
+  )
+}

apps/editor/app/viewer/[id]/error.tsx

@@ -0,0 +1,42 @@
+'use client'
+
+import Link from 'next/link'
+import { useEffect } from 'react'
+
+export default function ViewerRouteError({
+  error,
+  reset,
+}: Readonly<{
+  error: Error & { digest?: string }
+  reset: () => void
+}>) {
+  useEffect(() => {
+    console.error('[viewer-route] Unhandled viewer error:', error)
+  }, [error])
+
+  return (
+    <div className="flex min-h-screen w-full items-center justify-center bg-background p-4 text-foreground">
+      <div className="w-full max-w-md rounded-2xl border border-border/60 bg-background p-6 shadow-xl">
+        <h1 className="text-lg font-semibold">Viewer error</h1>
+        <p className="mt-2 text-sm text-muted-foreground">
+          We couldn&apos;t load this project view. You can retry without leaving the app.
+        </p>
+        <div className="mt-4 flex items-center gap-2">
+          <button
+            className="rounded-md border border-border bg-accent px-3 py-2 text-sm font-medium hover:bg-accent/80"
+            onClick={reset}
+            type="button"
+          >
+            Try again
+          </button>
+          <Link
+            className="rounded-md border border-border bg-background px-3 py-2 text-sm font-medium hover:bg-accent/40"
+            href="/"
+          >
+            Back to home
+          </Link>
+        </div>
+      </div>
+    </div>
+  )
+}

apps/editor/app/viewer/[id]/page.tsx

@@ -2,8 +2,11 @@
 
 import { initSpatialGridSync, useScene } from '@pascal-app/core'
 import { useViewer, Viewer } from '@pascal-app/viewer'
+import Link from 'next/link'
 import { useParams } from 'next/navigation'
 import { useEffect, useState } from 'react'
+import { ErrorBoundary } from '@/components/ui/primitives/error-boundary'
+import { SceneLoader } from '@/components/ui/scene-loader'
 import {
   getProjectModelPublic,
   incrementProjectViews,
@@ -14,7 +17,34 @@ import { ViewerGuestCTA } from './viewer-guest-cta'
 import { ViewerOverlay } from './viewer-overlay'
 import { ViewerZoneSystem } from './viewer-zone-system'
 
-import { SceneLoader } from '@/components/ui/scene-loader'
+function ViewerSceneCrashFallback({ projectName }: { projectName?: string | null }) {
+  return (
+    <div className="absolute inset-0 z-30 flex items-center justify-center bg-background/95 p-4 text-foreground">
+      <div className="w-full max-w-md rounded-2xl border border-border/60 bg-background p-6 shadow-xl">
+        <h2 className="text-lg font-semibold">The 3D scene failed to render</h2>
+        <p className="mt-2 text-sm text-muted-foreground">
+          {projectName ? `"${projectName}" ` : ''}
+          hit a rendering error. The rest of the app is still available.
+        </p>
+        <div className="mt-4 flex items-center gap-2">
+          <button
+            className="rounded-md border border-border bg-accent px-3 py-2 text-sm font-medium hover:bg-accent/80"
+            onClick={() => window.location.reload()}
+            type="button"
+          >
+            Reload scene
+          </button>
+          <Link
+            className="rounded-md border border-border bg-background px-3 py-2 text-sm font-medium hover:bg-accent/40"
+            href="/"
+          >
+            Back to home
+          </Link>
+        </div>
+      </div>
+    </div>
+  )
+}
 
 export default function ViewerPage() {
   const params = useParams()
@@ -33,27 +63,46 @@ export default function ViewerPage() {
   }, [projectId])
 
   useEffect(() => {
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+    setProjectId(null)
+    setProjectName(null)
+    setOwner(null)
+    setCanShowScans(true)
+    setCanShowGuides(true)
+    useViewer.getState().setShowScans(true)
+    useViewer.getState().setShowGuides(true)
+
     const loadContent = async () => {
       try {
         // Check if it's a demo file (starts with 'demo_')
         if (id.startsWith('demo_')) {
           const response = await fetch(`/demos/${id}.json`)
+          if (cancelled) return
+
           if (!response.ok) {
             throw new Error(`Demo "${id}" not found`)
           }
+
           const data = await response.json()
+          if (cancelled) return
+
           if (data.nodes && data.rootNodeIds) {
             setScene(data.nodes, data.rootNodeIds)
             initSpatialGridSync()
           }
+
           setProjectName('Demo')
         } else {
           // Load from database (public project)
           const result = await getProjectModelPublic(id)
+          if (cancelled) return
 
           if (result.success && result.data) {
             const { project, model, isOwner } = result.data
             const projectData = project as any
+
             setProjectId(project.id)
             setProjectName(project.name)
             setOwner(projectData.owner ?? null)
@@ -81,19 +130,28 @@ export default function ViewerPage() {
 
             // Increment view count
             await incrementProjectViews(id)
+            if (cancelled) return
           } else {
             throw new Error(result.error || 'Project not found')
           }
         }
 
+        if (!cancelled) {
           setLoading(false)
+        }
       } catch (err) {
+        if (!cancelled) {
           setError(err instanceof Error ? err.message : 'Failed to load content')
           setLoading(false)
         }
       }
+    }
 
     loadContent()
+
+    return () => {
+      cancelled = true
+    }
   }, [id, setScene])
 
   if (error) {
@@ -117,13 +175,15 @@ export default function ViewerPage() {
             canShowGuides={canShowGuides}
           />
           <ViewerGuestCTA />
-        </>
-      )}
 
+          <ErrorBoundary key={id} fallback={<ViewerSceneCrashFallback projectName={projectName} />}>
             <Viewer>
               <ViewerCameraControls />
               <ViewerZoneSystem />
             </Viewer>
+          </ErrorBoundary>
+        </>
+      )}
     </div>
   )
 }

apps/editor/components/editor/index.tsx

@@ -16,6 +16,7 @@ import { ToolManager } from '../tools/tool-manager'
 import { ActionMenu } from '../ui/action-menu'
 import { HelperManager } from '../ui/helpers/helper-manager'
 import { PanelManager } from '../ui/panels/panel-manager'
+import { ErrorBoundary } from '../ui/primitives/error-boundary'
 import { SidebarProvider } from '../ui/primitives/sidebar'
 import { SceneLoader } from '../ui/scene-loader'
 import { AppSidebar } from '../ui/sidebar/app-sidebar'
@@ -23,12 +24,11 @@ import { CustomCameraControls } from './custom-camera-controls'
 import { ExportManager } from './export-manager'
 import { FloatingActionMenu } from './floating-action-menu'
 import { Grid } from './grid'
+import { PresetThumbnailGenerator } from './preset-thumbnail-generator'
 import { SelectionManager } from './selection-manager'
 import { SiteEdgeLabels } from './site-edge-labels'
-import { PresetThumbnailGenerator } from './preset-thumbnail-generator'
 import { ThumbnailGenerator } from './thumbnail-generator'
 
-
 // Load default scene initially (will be replaced when project loads)
 useScene.getState().loadScene()
 initSpatialGridSync()
@@ -66,6 +66,34 @@ interface EditorProps {
   projectId?: string
 }
 
+function EditorSceneCrashFallback() {
+  return (
+    <div className="fixed inset-0 z-[80] flex items-center justify-center bg-background/95 p-4 text-foreground">
+      <div className="w-full max-w-md rounded-2xl border border-border/60 bg-background p-6 shadow-xl">
+        <h2 className="text-lg font-semibold">The editor scene failed to render</h2>
+        <p className="mt-2 text-sm text-muted-foreground">
+          You can retry the scene or return home without reloading the whole app shell.
+        </p>
+        <div className="mt-4 flex items-center gap-2">
+          <button
+            className="rounded-md border border-border bg-accent px-3 py-2 text-sm font-medium hover:bg-accent/80"
+            onClick={() => window.location.reload()}
+            type="button"
+          >
+            Reload editor
+          </button>
+          <a
+            className="rounded-md border border-border bg-background px-3 py-2 text-sm font-medium hover:bg-accent/40"
+            href="/"
+          >
+            Back to home
+          </a>
+        </div>
+      </div>
+    </div>
+  )
+}
+
 export default function Editor({ projectId }: EditorProps) {
   useKeyboard()
   useProjectScene()
@@ -109,6 +137,7 @@ export default function Editor({ projectId }: EditorProps) {
       <SidebarProvider className="fixed z-20">
         <AppSidebar />
       </SidebarProvider>
+      <ErrorBoundary key={projectId} fallback={<EditorSceneCrashFallback />}>
         <Viewer selectionManager="custom">
           <SelectionManager />
           <FloatingActionMenu />
@@ -124,6 +153,7 @@ export default function Editor({ projectId }: EditorProps) {
           <PresetThumbnailGenerator />
           <SiteEdgeLabels />
         </Viewer>
+      </ErrorBoundary>
     </div>
   )
 }

packages/viewer/src/components/viewer/index.tsx

@@ -64,20 +64,18 @@ interface ViewerProps {
   selectionManager?: 'default' | 'custom'
 }
 
-const Viewer: React.FC<ViewerProps> = ({
+const Viewer: React.FC<ViewerProps> = ({ children, selectionManager = 'default' }) => {
-  children,
-  selectionManager = 'default',
-}) => {
   const theme = useViewer((state) => state.theme)
 
   return (
     <Canvas
       dpr={[1, 1.5]}
       className={`transition-colors duration-700 ${theme === 'dark' ? 'bg-[#1f2433]' : 'bg-[#fafafa]'}`}
-      gl={(props) => {
+      gl={async (props) => {
         const renderer = new THREE.WebGPURenderer(props as any)
         renderer.toneMapping = THREE.ACESFilmicToneMapping
         renderer.toneMappingExposure = 0.9
+        await renderer.init()
         return renderer
       }}
       shadows={{

packages/viewer/src/components/viewer/post-processing.tsx

@@ -43,19 +43,31 @@ export const SSGI_PARAMS = {
 const PostProcessingPasses = () => {
   const { gl: renderer, scene, camera } = useThree()
   const renderPipelineRef = useRef<RenderPipeline | null>(null)
+  const hasPipelineErrorRef = useRef(false)
   const [isInitialized, setIsInitialized] = useState(false)
 
   useEffect(() => {
     let mounted = true
+
     const initRenderer = async () => {
+      try {
         if (renderer && (renderer as any).init) {
           await (renderer as any).init()
         }
+
         if (mounted) {
           setIsInitialized(true)
         }
+      } catch (error) {
+        console.error('[viewer] Failed to initialize renderer for post-processing.', error)
+        if (mounted) {
+          setIsInitialized(false)
         }
+      }
+    }
+
     initRenderer()
+
     return () => {
       mounted = false
     }
@@ -66,6 +78,9 @@ const PostProcessingPasses = () => {
       return
     }
 
+    hasPipelineErrorRef.current = false
+
+    try {
       // Scene pass with MRT for SSGI
       const scenePass = pass(scene, camera)
       scenePass.setMRT(
@@ -99,7 +114,6 @@ const PostProcessingPasses = () => {
       // SSGI Pass (cast to PerspectiveCamera for SSGI)
       const giPass = ssgi(scenePassColor, scenePassDepth, sceneNormal, camera as any)
 
-    
       giPass.sliceCount.value = SSGI_PARAMS.sliceCount
       giPass.stepCount.value = SSGI_PARAMS.stepCount
       giPass.radius.value = SSGI_PARAMS.radius
@@ -143,6 +157,7 @@ const PostProcessingPasses = () => {
 
         return outlineColor
       }
+
       function generateHoverOutlinePass() {
         const edgeStrength = uniform(5)
         const edgeGlow = uniform(0.5)
@@ -166,6 +181,7 @@ const PostProcessingPasses = () => {
           .add(hiddenEdge.mul(hiddenEdgeColor))
           .mul(edgeStrength)
         const outlinePulse = pulsePeriod.greaterThan(0).select(outlineColor.mul(osc), outlineColor)
+
         return outlinePulse
       }
 
@@ -183,6 +199,17 @@ const PostProcessingPasses = () => {
       const renderPipeline = new RenderPipeline(renderer as unknown as WebGPURenderer)
       renderPipeline.outputNode = finalOutput
       renderPipelineRef.current = renderPipeline
+    } catch (error) {
+      hasPipelineErrorRef.current = true
+      console.error(
+        '[viewer] Failed to set up post-processing pipeline. Rendering without post FX.',
+        error,
+      )
+      if (renderPipelineRef.current) {
+        renderPipelineRef.current.dispose()
+      }
+      renderPipelineRef.current = null
+    }
 
     return () => {
       if (renderPipelineRef.current) {
@@ -193,8 +220,20 @@ const PostProcessingPasses = () => {
   }, [renderer, scene, camera, isInitialized])
 
   useFrame(() => {
-    if (renderPipelineRef.current) {
+    if (hasPipelineErrorRef.current || !renderPipelineRef.current) {
+      return
+    }
+
+    try {
       renderPipelineRef.current.render()
+    } catch (error) {
+      hasPipelineErrorRef.current = true
+      console.error(
+        '[viewer] Post-processing render pass failed. Disabling post FX for this session.',
+        error,
+      )
+      renderPipelineRef.current.dispose()
+      renderPipelineRef.current = null
     }
   }, 1)
 

packages/viewer/src/hooks/use-gltf-ktx2.tsx

@@ -1,18 +1,38 @@
-import { useGLTF } from "@react-three/drei"
+import { useGLTF } from '@react-three/drei'
-import { useThree } from "@react-three/fiber"
+import { useThree } from '@react-three/fiber'
-import { KTX2Loader } from "three/examples/jsm/Addons.js"
+import { KTX2Loader } from 'three/examples/jsm/Addons.js'
-import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js"
+import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js'
 
 const ktx2LoaderInstance = new KTX2Loader()
 ktx2LoaderInstance.setTranscoderPath('https://cdn.jsdelivr.net/gh/pmndrs/drei-assets@master/basis/')
+const ktx2ConfiguredRenderers = new WeakSet<object>()
+const ktx2WarningLoggedRenderers = new WeakSet<object>()
 
 const useGLTFKTX2 = (path: string): ReturnType<typeof useGLTF> => {
   const gl = useThree((state) => state.gl)
 
   return useGLTF(path, true, true, (loader) => {
+    const renderer = gl as unknown as object
+
+    if (!ktx2ConfiguredRenderers.has(renderer)) {
+      try {
         ktx2LoaderInstance.detectSupport(gl)
+        ktx2ConfiguredRenderers.add(renderer)
+      } catch (error) {
+        // Some WebGPU flows can transiently call this before backend init.
+        // Avoid crashing the whole scene; scans may render without KTX2 on this pass.
+        if (!ktx2WarningLoggedRenderers.has(renderer)) {
+          console.warn('[viewer] Skipping KTX2 support detection for now.', error)
+          ktx2WarningLoggedRenderers.add(renderer)
+        }
+      }
+    }
+
+    if (ktx2ConfiguredRenderers.has(renderer)) {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       loader.setKTX2Loader(ktx2LoaderInstance as any)
+    }
+
     loader.setMeshoptDecoder(MeshoptDecoder)
   })
 }