# TypeScript Guide for Bench3D

Bench3D is built with TypeScript and provides comprehensive type definitions out of the box.

## Import Style (Like Three.js and p5.js)

Bench3D uses the same simple import pattern as Three.js and p5.js:

```typescript
// ✅ Namespace import (like Three.js)
import * as Bench3D from 'bench-3d';

// Use everything through the namespace
const engine = new Bench3D.Bench3D({ canvas: myCanvas });
const cube = project.addCube({ size: [16, 16, 16] });
Bench3D.moveElements([cube], [10, 0, 0] as Bench3D.Vector3);
```

This is exactly like using Three.js:
```typescript
import * as THREE from 'three';
const scene = new THREE.Scene();
const mesh = new THREE.Mesh();
```

## Type Definitions

All type definitions are automatically generated and included in the package. The main types are exported from the main entry point:

```typescript
import {
  Bench3D,
  Bench3DOptions,
  Project,
  ProjectOptions,
  Cube,
  CubeData,
  Mesh,
  MeshData,
  Texture,
  TextureData,
  Animation,
  AnimationData,
  Vector3,
  Vector2,
  // ... and more
} from 'bench-3d';
```

## Type Safety Examples

### Creating an Engine

```typescript
import { Bench3D, Bench3DOptions } from 'bench-3d';

const options: Bench3DOptions = {
  canvas: document.getElementById('canvas') as HTMLCanvasElement,
  onUpdate: (event) => {
    // event.type and event.data are fully typed
    console.log(event.type, event.data);
  }
};

const engine = new Bench3D(options);
```

### Working with Projects

```typescript
import { Project, ProjectOptions, Cube, CubeData } from 'bench-3d';

const projectOptions: ProjectOptions = {
  name: 'My Project',
  texture_width: 16,
  texture_height: 16
};

const project: Project = engine.createProject(projectOptions);

// Type-safe cube creation
const cubeData: CubeData = {
  name: 'My Cube',
  size: [16, 16, 16],
  origin: [0, 0, 0]
};

const cube: Cube = project.addCube(cubeData);
```

### Transform Operations

```typescript
import { Vector3, moveElements, rotateElements, scaleElements } from 'bench-3d';

const offset: Vector3 = [10, 0, 0];
const rotation: Vector3 = [0, 45, 0];
const scale: Vector3 = [1.5, 1.5, 1.5];

moveElements([cube], offset);
rotateElements([cube], rotation, [0, 0, 0]);
scaleElements([cube], scale, [0, 0, 0]);
```

### Mesh Operations

```typescript
import { Mesh, extrudeFaces, loopCut, bevelEdges } from 'bench-3d';

const mesh: Mesh = project.addMesh({ name: 'My Mesh' });

// Type-safe mesh operations
const faceKeys = Object.keys(mesh.faces);
extrudeFaces(mesh, faceKeys, { distance: 2 });

const edges: Array<[string, string]> = [['v1', 'v2']];
bevelEdges(mesh, edges, { amount: 0.1 });
```

### Import/Export

```typescript
import { GLTFExporter, GLTFExportOptions, GLTFImporter, GLTFImportOptions } from 'bench-3d';

// Export with type safety
const exporter = new GLTFExporter();
const exportOptions: GLTFExportOptions = {
  scale: 1,
  binary: false,
  embed_textures: true,
  export_animations: true
};

const gltfData = exporter.export(project, exportOptions);

// Import with type safety
const importer = new GLTFImporter();
const importOptions: GLTFImportOptions = {
  scale: 1,
  importAnimations: true,
  importTextures: true
};

await importer.import(gltfData, project, importOptions);
```

## Framework Adapters

### React with TypeScript

All React hooks are fully typed:

```tsx
import { useBench3D, useProject, useMaterials } from 'bench-3d-react';
import type { UseBench3DReturn, UseProjectReturn } from 'bench-3d-react';

function MyComponent() {
  const { engine, project, isReady }: UseBench3DReturn = useBench3D();
  const { addCube, selectedElements }: UseProjectReturn = useProject(project);
  const { createMaterial, materials } = useMaterials(project);

  useEffect(() => {
    if (isReady && project) {
      const cube = addCube({ size: [16, 16, 16] });
      // cube is fully typed as Cube | null
    }
  }, [isReady, project, addCube]);

  return <div>Selected: {selectedElements.length}</div>;
}
```

See [bench-3d-react README](../bench-3d-react/README.md) for complete React TypeScript documentation.

### Vue with TypeScript

All Vue composables are fully typed:

```vue
<script setup lang="ts">
import { useBench3D, useProject, useMaterials } from 'bench-3d-vue';
import type { UseBench3DReturn, UseProjectReturn } from 'bench-3d-vue';

const { engine, project, isReady }: UseBench3DReturn = useBench3D();
const { addCube, selectedElements }: UseProjectReturn = useProject(project);
const { createMaterial, materials } = useMaterials(project);

onMounted(() => {
  if (isReady.value && project.value) {
    const cube = addCube({ size: [16, 16, 16] });
    // cube is fully typed as Cube | null
  }
});
</script>

<template>
  <div>Selected: {{ selectedElements.length }}</div>
</template>
```

See [bench-3d-vue README](../bench-3d-vue/README.md) for complete Vue TypeScript documentation.

## Type Checking

The package includes a `typecheck` script:

```bash
npm run typecheck
```

This will check all TypeScript files without emitting any output.

## Build Output

When you build the package, TypeScript declaration files (`.d.ts`) are automatically generated:

- `dist/index.d.ts` - Main entry point types
- `dist/core.d.ts` - Core-only types
- `dist/full.d.ts` - Full features types

These are included in the package and automatically picked up by TypeScript when you import from `bench3d`.

## Common Types

### Vector Types

```typescript
type Vector3 = [number, number, number];
type Vector2 = [number, number];
```

### Geometry Types

```typescript
interface CubeData {
  name?: string;
  size?: [number, number, number];
  origin?: [number, number, number];
  rotation?: [number, number, number];
  // ... more properties
}

interface MeshData {
  name?: string;
  vertices?: Record<string, Vector3>;
  faces?: Record<string, MeshFaceData>;
  // ... more properties
}
```

### Animation Types

```typescript
interface AnimationData {
  name?: string;
  length?: number;
  loop?: 'once' | 'loop' | 'hold';
  animators?: Record<string, AnimatorData>;
  // ... more properties
}
```

## IDE Support

With TypeScript, you'll get:

- ✅ Autocomplete for all methods and properties
- ✅ Type checking at compile time
- ✅ IntelliSense in VS Code, WebStorm, etc.
- ✅ Refactoring support
- ✅ Go to definition
- ✅ Find all references

## Strict Mode

The package is compiled with TypeScript's `strict` mode enabled, ensuring:

- No implicit `any` types
- Strict null checks
- Strict function types
- And more type safety features

This means you'll catch errors at compile time rather than runtime!