# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a React + TypeScript + Vite project called "perfviz" - a modern web application built with the latest versions of React (19.1.0), TypeScript (5.8.3), and Vite (7.0.4).

## Development Commands

- **Start development server**: `npm run dev` - Runs Vite dev server with HMR on http://localhost:5173/
- **Build for production**: `npm run build` - TypeScript compilation followed by Vite build
- **Lint code**: `npm run lint` - Run ESLint on the entire codebase
- **Preview production build**: `npm run preview` - Preview the production build locally

## Architecture

### Build System
- **Vite** as the build tool with React plugin for Fast Refresh
- **ES modules** configuration (`"type": "module"` in package.json)
- **Bundler module resolution** with TypeScript extensions allowed in imports

### TypeScript Configuration
- **Dual TypeScript configs**: 
  - `tsconfig.app.json` for application code (`src/` directory)
  - `tsconfig.node.json` for build tooling (Vite config)
- **Strict TypeScript** with unused locals/parameters checking enabled
- **React JSX transform** (`react-jsx`) for React 19+ compatibility

### Code Quality
- **ESLint** with TypeScript support and React-specific rules:
  - React Hooks rules for proper hooks usage
  - React Refresh rules for HMR compatibility
  - TypeScript recommended rules
- **Globals configured** for browser environment

### Application Structure
- **Entry point**: `src/main.tsx` renders the App component in React 19 StrictMode
- **Root component**: `src/App.tsx` contains the main application logic
- **3D Viewer**: `src/BabylonViewer.tsx` React component wrapping Babylon.js 3D scene
- **Styling**: CSS modules with `src/index.css` and `src/App.css`
- **Assets**: Static assets in `public/` and component assets in `src/assets/`

## Key Dependencies

- **React 19.1.0** with modern features and concurrent rendering
- **TypeScript 5.8.3** with latest language features
- **Vite 7.0.4** for fast development and optimized builds
- **ESLint 9.30.1** with typescript-eslint for code quality
- **BabylonJS 8.21.1** for 3D graphics and visualization

## Development Notes

- The project uses **React 19's new JSX transform** and concurrent features
- **HMR (Hot Module Replacement)** is enabled through Vite's React plugin
- **Strict mode** is enabled in development for better debugging
- **Browser targets** are ES2022+ for modern JavaScript features
- **Lines of code per function**: Functions should not exceed 50 lines. If they do, add a comment `//@LONGFUNCTION` to indicate this.
- **Lines of code per function**: Functions should have a hard limit of 200 lines, if we exceed this, prompt with approaches to refactor.
- **File size limits**: TypeScript files should not exceed 100 lines. If a file is over 100 lines but functions are under 150 lines, add `//@LONGFILE` comment at the top and warn the user. Files over 250 lines must be prompted to refactor.
- **Imports**: Ensure all imports are used, remove unused imports, and ensure imports are alphabetized and at the top of the file.
- **Code Style**: Follow consistent coding style with mostly widely used indentation, spacing, and comments for clarity.
- **Error Handling**: Use try/catch blocks for asynchronous operations and provide meaningful error messages.
- **CSS versus Styled Components**: Use CSS modules for styling instead of styled-components for better performance and simplicity.  

## Babylon.js Integration

- **Version**: Using Babylon.js 8.21.1 (modern version 8+)
- **Camera Management**: Use `scene.activeCamera` instead of deprecated `camera.attachToCanvas()`
- **ArcRotateCamera Controls**: Use `camera.attachControl(canvas, true)` for mouse interaction
- **Scene Setup**: Cameras, lights, and meshes are added directly to the scene object
- **Engine Integration**: Engine handles canvas interaction and render loop
- **React Integration**: Proper cleanup with engine disposal in useEffect return function
- **Version-Specific Documentation**: ALWAYS check Babylon.js documentation for version 8.21.1 specifically to avoid deprecated methods and ensure current API usage
- **API Verification**: Before suggesting any Babylon.js code, verify method signatures and availability in the current version
- **CSS**: Use CSS modules for styling components, avoid inline styles for better performance and maintainability