feat: add protein 2D/3D visualization components

- Add Smiles2DViewer for 2D molecule visualization using smiles-drawer
- Add ProteinViewer for 3D protein visualization using 3Dmol.js
- Add visualization-api.ts for fetching molecule/protein data
- Add visualization-types.ts for type definitions
- Install smiles-drawer and 3dmol dependencies

Co-authored-by: RaedAddala <addala.raed@gmail.com>

ui/components/visualization/index.ts

@@ -0,0 +1,2 @@
+export { Smiles2DViewer } from './smiles-2d-viewer';
+export { ProteinViewer } from './protein-viewer';

ui/components/visualization/protein-viewer.tsx

@@ -0,0 +1,243 @@
+'use client';
+
+import { AlertCircle, RotateCcw } from 'lucide-react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { Button } from '@/components/ui/button';
+import { Card, CardContent } from '@/components/ui/card';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { Skeleton } from '@/components/ui/skeleton';
+import { getProteinPdbUrl } from '@/lib/visualization-api';
+import type { ProteinRepresentation } from '@/lib/visualization-types';
+
+interface ProteinViewerProps {
+  pdbId: string;
+  width?: number;
+  height?: number;
+  className?: string;
+  initialRepresentation?: ProteinRepresentation;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type $3Dmol = any;
+
+export function ProteinViewer({
+  pdbId,
+  width = 500,
+  height = 500,
+  className,
+  initialRepresentation = 'cartoon',
+}: ProteinViewerProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const viewerRef = useRef<any>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [representation, setRepresentation] =
+    useState<ProteinRepresentation>(initialRepresentation);
+  const [$3Dmol, set$3Dmol] = useState<$3Dmol | null>(null);
+  const [pdbData, setPdbData] = useState<string | null>(null);
+
+  // Load 3Dmol.js dynamically
+  useEffect(() => {
+    const load3Dmol = async () => {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const module = await import('3dmol') as any;
+        set$3Dmol(module);
+      } catch (err) {
+        console.error('Failed to load 3Dmol:', err);
+        setError('Failed to load 3D visualization library');
+        setIsLoading(false);
+      }
+    };
+    load3Dmol();
+  }, []);
+
+  // Fetch PDB data when pdbId changes
+  useEffect(() => {
+    if (!pdbId) return;
+
+    const fetchPdb = async () => {
+      try {
+        setIsLoading(true);
+        setError(null);
+        const pdbUrl = getProteinPdbUrl(pdbId);
+        const response = await fetch(pdbUrl);
+
+        if (!response.ok) {
+          throw new Error(`Failed to fetch PDB: ${response.statusText}`);
+        }
+
+        const data = await response.text();
+        setPdbData(data);
+      } catch (err) {
+        console.error('Failed to fetch PDB:', err);
+        setError(
+          err instanceof Error ? err.message : 'Failed to load PDB data'
+        );
+        setIsLoading(false);
+      }
+    };
+    fetchPdb();
+  }, [pdbId]);
+
+  const getStyleForRepresentation = useCallback(
+    (rep: ProteinRepresentation) => {
+      switch (rep) {
+        case 'cartoon':
+          return { cartoon: { color: 'spectrum' } };
+        case 'ball-and-stick':
+          return { stick: { radius: 0.15 }, sphere: { scale: 0.25 } };
+        case 'surface':
+          return { surface: {} }; // Surface handled via addSurface
+        case 'ribbon':
+          return { cartoon: { style: 'trace', color: 'spectrum' } };
+        default:
+          return { cartoon: { color: 'spectrum' } };
+      }
+    },
+    []
+  );
+
+  const initViewer = useCallback(() => {
+    if (!containerRef.current || !$3Dmol || !pdbData) return;
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      // Clean up existing viewer
+      if (viewerRef.current) {
+        viewerRef.current.removeAllModels();
+      }
+
+      // Create viewer
+      const viewer = $3Dmol.createViewer(containerRef.current, {
+        backgroundColor: '#0a0a0a',
+      });
+      viewerRef.current = viewer;
+
+      // Add protein structure
+      viewer.addModel(pdbData, 'pdb');
+
+      if (representation === 'surface') {
+        viewer.setStyle({}, { cartoon: { color: 'spectrum' } }); // Base style
+        viewer.addSurface($3Dmol.SurfaceType.VDW, {
+          opacity: 0.85,
+          color: 'spectrum',
+        }, {}, {});
+      } else {
+        viewer.setStyle({}, getStyleForRepresentation(representation));
+      }
+
+      viewer.zoomTo();
+      viewer.render();
+
+      setIsLoading(false);
+    } catch (err) {
+      console.error('3D viewer error:', err);
+      setError(
+        err instanceof Error
+          ? `Visualization error: ${err.message}`
+          : 'Failed to render 3D structure'
+      );
+      setIsLoading(false);
+    }
+  }, [$3Dmol, pdbData, representation, getStyleForRepresentation]);
+
+  useEffect(() => {
+    initViewer();
+  }, [$3Dmol, pdbData, initViewer]);
+
+  // Update representation
+  useEffect(() => {
+    if (!viewerRef.current || !pdbData || !$3Dmol) return;
+    try {
+      viewerRef.current.removeAllSurfaces();
+
+      if (representation === 'surface') {
+        viewerRef.current.setStyle({}, { cartoon: { color: 'spectrum', opacity: 0.5 } });
+        viewerRef.current.addSurface($3Dmol.SurfaceType.VDW, {
+          opacity: 0.85,
+          color: 'spectrum',
+        }, {}, {});
+      } else {
+        viewerRef.current.setStyle({}, getStyleForRepresentation(representation));
+      }
+
+      viewerRef.current.render();
+    } catch (err) {
+      console.error('Style update error:', err);
+    }
+  }, [representation, getStyleForRepresentation, pdbData, $3Dmol]);
+
+  const handleResetCamera = useCallback(() => {
+    if (!viewerRef.current) return;
+    viewerRef.current.zoomTo();
+    viewerRef.current.render();
+  }, []);
+
+  if (error) {
+    return (
+      <Card className={`border-destructive bg-destructive/10 ${className}`}>
+        <CardContent className="flex items-center gap-3 p-4">
+          <AlertCircle className="size-5 text-destructive" />
+          <div className="flex flex-col">
+            <span className="text-sm font-medium text-destructive">
+              Protein Visualization Error
+            </span>
+            <span className="text-xs text-muted-foreground">{error}</span>
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <div className={`flex flex-col gap-3 ${className}`}>
+      <div className="flex items-center gap-2">
+        <Select
+          value={representation}
+          onValueChange={(value) =>
+            setRepresentation(value as ProteinRepresentation)
+          }
+        >
+          <SelectTrigger className="w-40">
+            <SelectValue placeholder="Representation" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="cartoon">Cartoon</SelectItem>
+            <SelectItem value="ball-and-stick">Ball & Stick</SelectItem>
+            <SelectItem value="surface">Surface</SelectItem>
+            <SelectItem value="ribbon">Ribbon</SelectItem>
+          </SelectContent>
+        </Select>
+        <Button variant="outline" size="sm" onClick={handleResetCamera}>
+          <RotateCcw className="mr-1 size-4" />
+          Reset
+        </Button>
+      </div>
+
+      <div className="relative">
+        {isLoading && (
+          <Skeleton
+            className="absolute inset-0 z-10"
+            style={{ width, height }}
+          />
+        )}
+        <div
+          ref={containerRef}
+          style={{ width, height }}
+          className={`rounded-lg border bg-background ${isLoading ? 'opacity-0' : 'opacity-100'} transition-opacity duration-200`}
+        />
+      </div>
+    </div>
+  );
+}

ui/components/visualization/smiles-2d-viewer.tsx

@@ -0,0 +1,119 @@
+'use client';
+
+import { AlertCircle } from 'lucide-react';
+import { useCallback, useEffect, useId, useRef, useState } from 'react';
+import SmilesDrawer from 'smiles-drawer';
+
+import { Card, CardContent } from '@/components/ui/card';
+import { Skeleton } from '@/components/ui/skeleton';
+
+interface Smiles2DViewerProps {
+  smiles: string;
+  width?: number;
+  height?: number;
+  className?: string;
+}
+
+export function Smiles2DViewer({
+  smiles,
+  width = 400,
+  height = 300,
+  className,
+}: Smiles2DViewerProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const canvasId = useId();
+  const [error, setError] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  const drawMolecule = useCallback(async () => {
+    if (!canvasRef.current || !smiles) {
+      setIsLoading(false);
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const drawer = new SmilesDrawer.SmiDrawer({
+        width,
+        height,
+        bondThickness: 1.5,
+        bondLength: 15,
+        shortBondLength: 0.85,
+        bondSpacing: 4,
+        atomVisualization: 'default',
+        isomeric: true,
+        debug: false,
+        terminalCarbons: false,
+        explicitHydrogens: false,
+        compactDrawing: true,
+        fontSizeLarge: 11,
+        fontSizeSmall: 8,
+        padding: 20,
+      });
+
+      try {
+        await new Promise<void>((resolve, reject) => {
+          (drawer as any).draw(
+            smiles,
+            `[id="${canvasId}"]`,
+            'light',
+            () => resolve(),
+            (drawError: Error) => reject(drawError)
+          );
+        });
+      } catch (drawError) {
+        throw drawError;
+      }
+
+      setIsLoading(false);
+    } catch (err) {
+      console.error('SMILES drawing error:', err);
+      setError(
+        err instanceof Error
+          ? `Invalid SMILES: ${err.message}`
+          : 'Failed to render molecule structure'
+      );
+      setIsLoading(false);
+    }
+  }, [smiles, width, height, canvasId]);
+
+  useEffect(() => {
+    drawMolecule();
+  }, [drawMolecule]);
+
+  if (error) {
+    return (
+      <Card className={`border-destructive bg-destructive/10 ${className}`}>
+        <CardContent className="flex items-center gap-3 p-4">
+          <AlertCircle className="size-5 text-destructive" />
+          <div className="flex flex-col">
+            <span className="text-sm font-medium text-destructive">
+              Visualization Error
+            </span>
+            <span className="text-xs text-muted-foreground">{error}</span>
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <div className={`relative ${className}`}>
+      {isLoading && (
+        <Skeleton
+          className="absolute inset-0"
+          style={{ width, height }}
+        />
+      )}
+      <canvas
+        ref={canvasRef}
+        id={canvasId}
+        width={width}
+        height={height}
+        className={`bg-background rounded-lg ${isLoading ? 'opacity-0' : 'opacity-100'} transition-opacity duration-200`}
+      />
+    </div>
+  );
+}

ui/lib/visualization-api.ts

@@ -0,0 +1,57 @@
+import type { Molecule, Protein } from './visualization-types';
+
+const API_BASE = '/api';
+
+// Generic fetch helper with error handling
+async function fetchApi<T>(url: string): Promise<T> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+    throw new Error(error.error || `HTTP ${response.status}`);
+  }
+  return response.json();
+}
+
+async function fetchText(url: string): Promise<string> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+    throw new Error(error.error || `HTTP ${response.status}`);
+  }
+  return response.text();
+}
+
+// Molecule API
+export async function getMolecules(): Promise<Molecule[]> {
+  return fetchApi<Molecule[]>(`${API_BASE}/molecules`);
+}
+
+export async function getMolecule(id: string): Promise<Molecule> {
+  return fetchApi<Molecule>(`${API_BASE}/molecules/${id}`);
+}
+
+export async function getMoleculeSDF(id: string): Promise<string> {
+  return fetchText(`${API_BASE}/molecules/${id}/sdf`);
+}
+
+// Protein API
+export async function getProteins(): Promise<Protein[]> {
+  return fetchApi<Protein[]>(`${API_BASE}/proteins`);
+}
+
+export async function getProtein(id: string): Promise<Protein> {
+  return fetchApi<Protein>(`${API_BASE}/proteins/${id}`);
+}
+
+export async function getProteinPDB(id: string): Promise<string> {
+  return fetchText(`${API_BASE}/proteins/${id}/pdb`);
+}
+
+// URL builders for direct links
+export function getMoleculeSdfUrl(id: string): string {
+  return `${API_BASE}/molecules/${id}/sdf`;
+}
+
+export function getProteinPdbUrl(id: string): string {
+  return `${API_BASE}/proteins/${id}/pdb`;
+}

ui/lib/visualization-types.ts

@@ -0,0 +1,20 @@
+// Molecule types
+export type Molecule = {
+  id: string;
+  name: string;
+  smiles: string;
+  pubchemCid: number;
+  description?: string;
+};
+
+// Protein types
+export type Protein = {
+  id: string;
+  pdbId: string;
+  name: string;
+  description?: string;
+};
+
+// Viewer representation types
+export type MoleculeRepresentation = 'stick' | 'sphere' | 'line' | 'cartoon';
+export type ProteinRepresentation = 'cartoon' | 'ball-and-stick' | 'surface' | 'ribbon';

ui/package.json

@@ -10,6 +10,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
+    "3dmol": "^2.5.4",
     "@floating-ui/react": "^0.27.16",
     "@radix-ui/react-avatar": "^1.1.11",
     "@radix-ui/react-collapsible": "^1.1.12",
@@ -32,6 +33,7 @@
     "react-dom": "^19.2.3",
     "reactflow": "^11.11.4",
     "recharts": "^3.7.0",
+    "smiles-drawer": "^2.1.7",
     "tailwind-merge": "^3.4.0",
     "zod": "^4.3.6"
   },

ui/pnpm-lock.yaml

@@ -8,6 +8,9 @@ importers:
 
   .:
     dependencies:
+      3dmol:
+        specifier: ^2.5.4
+        version: 2.5.4
       '@floating-ui/react':
         specifier: ^0.27.16
         version: 0.27.16(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
@@ -74,6 +77,9 @@ importers:
       recharts:
         specifier: ^3.7.0
         version: 3.7.0(@types/react@19.2.9)(react-dom@19.2.3(react@19.2.3))(react-is@16.13.1)(react@19.2.3)(redux@5.0.1)
+      smiles-drawer:
+        specifier: ^2.1.7
+        version: 2.1.7
       tailwind-merge:
         specifier: ^3.4.0
         version: 3.4.0
@@ -129,6 +135,10 @@ importers:
 
 packages:
 
+  3dmol@2.5.4:
+    resolution: {integrity: sha512-stbHw2c2T12bABmFyBrhJL4tufw+hUjvhmJthOxAxKVDwAtAZSI17Kue8VNxaHewf5oRydPo6W62BlWrbrNa6Q==}
+    engines: {node: '>=16.16.0', npm: '>=8.11'}
+
   '@alloc/quick-lru@5.2.0':
     resolution: {integrity: sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==}
     engines: {node: '>=10'}
@@ -2076,6 +2086,9 @@ packages:
     resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
     engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
 
+  chroma-js@2.6.0:
+    resolution: {integrity: sha512-BLHvCB9s8Z1EV4ethr6xnkl/P2YRFOGqfgvuMG/MyCbZPrTA+NeiByY6XvgF0zP4/2deU2CXnWyMa3zu1LqQ3A==}
+
   class-variance-authority@0.7.1:
     resolution: {integrity: sha512-Ka+9Trutv7G8M6WT6SeiRWz792K5qEqIGEGzXKhAE6xOWAY6pPH8U+9IY3oCMv6kqTmLsv7Xh/2w2RigkePMsg==}
 
@@ -2879,6 +2892,9 @@ packages:
     resolution: {integrity: sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==}
     engines: {node: '>=12'}
 
+  iobuffer@5.4.0:
+    resolution: {integrity: sha512-DRebOWuqDvxunfkNJAlc3IzWIPD5xVxwUNbHr7xKB8E6aLJxIPfNX3CoMJghcFjpv6RWQsrcJbghtEwSPoJqMA==}
+
   ipaddr.js@1.9.1:
     resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
     engines: {node: '>= 0.10'}
@@ -3348,6 +3364,9 @@ packages:
     resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
     engines: {node: '>= 0.6'}
 
+  netcdfjs@3.0.0:
+    resolution: {integrity: sha512-LOvT8KkC308qtpUkcBPiCMBtii7ZQCN6LxcVheWgyUeZ6DQWcpSRFV9dcVXLj/2eHZ/bre9tV5HTH4Sf93vrFw==}
+
   next@16.1.4:
     resolution: {integrity: sha512-gKSecROqisnV7Buen5BfjmXAm7Xlpx9o2ueVQRo5DxQcjC8d330dOM1xiGWc2k3Dcnz0In3VybyRPOsudwgiqQ==}
     engines: {node: '>=20.9.0'}
@@ -3470,6 +3489,12 @@ packages:
   package-manager-detector@1.6.0:
     resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
 
+  pako@1.0.11:
+    resolution: {integrity: sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==}
+
+  pako@2.1.0:
+    resolution: {integrity: sha512-w+eufiZ1WuJYgPXbV/PO3NCMEc3xqylkKHzp8bxp1uW4qaSNQUkwmLLEc3kKsfz8lpV1F8Ht3U1Cm+9Srog2ug==}
+
   parent-module@1.0.1:
     resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
     engines: {node: '>=6'}
@@ -3825,6 +3850,9 @@ packages:
   sisteransi@1.0.5:
     resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
 
+  smiles-drawer@2.1.7:
+    resolution: {integrity: sha512-gApm5tsWrAYDkjbGYQb5OhwIyHvtM2kIO40DfATaOV0DPm0wA63yn4Ow7us27BT49lDdU9busCOPN9fpyonzaA==}
+
   source-map-js@1.2.1:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
     engines: {node: '>=0.10.0'}
@@ -4071,6 +4099,9 @@ packages:
     peerDependencies:
       browserslist: '>= 4.21.0'
 
+  upng-js@2.1.0:
+    resolution: {integrity: sha512-d3xzZzpMP64YkjP5pr8gNyvBt7dLk/uGI67EctzDuVp4lCZyVMo0aJO6l/VDlgbInJYDY6cnClLoBp29eKWI6g==}
+
   uri-js@4.4.1:
     resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
 
@@ -4223,6 +4254,13 @@ packages:
 
 snapshots:
 
+  3dmol@2.5.4:
+    dependencies:
+      iobuffer: 5.4.0
+      netcdfjs: 3.0.0
+      pako: 2.1.0
+      upng-js: 2.1.0
+
   '@alloc/quick-lru@5.2.0': {}
 
   '@antfu/ni@25.0.0':
@@ -6267,6 +6305,8 @@ snapshots:
 
   chalk@5.6.2: {}
 
+  chroma-js@2.6.0: {}
+
   class-variance-authority@0.7.1:
     dependencies:
       clsx: 2.1.1
@@ -7184,6 +7224,8 @@ snapshots:
 
   internmap@2.0.3: {}
 
+  iobuffer@5.4.0: {}
+
   ipaddr.js@1.9.1: {}
 
   is-array-buffer@3.0.5:
@@ -7579,6 +7621,10 @@ snapshots:
 
   negotiator@1.0.0: {}
 
+  netcdfjs@3.0.0:
+    dependencies:
+      iobuffer: 5.4.0
+
   next@16.1.4(@babel/core@7.28.6)(react-dom@19.2.3(react@19.2.3))(react@19.2.3):
     dependencies:
       '@next/env': 16.1.4
@@ -7730,6 +7776,10 @@ snapshots:
 
   package-manager-detector@1.6.0: {}
 
+  pako@1.0.11: {}
+
+  pako@2.1.0: {}
+
   parent-module@1.0.1:
     dependencies:
       callsites: 3.1.0
@@ -8242,6 +8292,10 @@ snapshots:
 
   sisteransi@1.0.5: {}
 
+  smiles-drawer@2.1.7:
+    dependencies:
+      chroma-js: 2.6.0
+
   source-map-js@1.2.1: {}
 
   source-map@0.6.1: {}
@@ -8524,6 +8578,10 @@ snapshots:
       escalade: 3.2.0
       picocolors: 1.1.1
 
+  upng-js@2.1.0:
+    dependencies:
+      pako: 1.0.11
+
   uri-js@4.4.1:
     dependencies:
       punycode: 2.3.1