@evoke-ui/zsort3d/README.md

TypeScript z-plane rendering engine with 3D depth simulation using Canvas 2D and mouse-based navigation

# ZSort3D

A modern TypeScript z-plane rendering engine that simulates 3D depth using mathematical transformations and Canvas 2D rendering. Port of the original ActionScript 3.0 ZSort3D engine.

## Installation

```bash
npm install zsort3d
```

## Features

- **3D Simulation**: Mathematical transformations using rotation matrices for realistic 3D space simulation
- **Mouse Interaction**: Drag-based rotation controls for intuitive navigation
- **Efficient Rendering**: Canvas 2D rendering with optimized depth sorting
- **Interactive Objects**: Click detection and event handling for 3D objects
- **Configurable Perspective**: Adjustable perspective distance for different 3D effects
- **Multiple Object Types**: Built-in support for balls, containers, and SVG objects
- **TypeScript**: Full type safety with comprehensive type declarations
- **Dual Module Support**: Both CommonJS and ESM exports for maximum compatibility

## Quick Usage

```typescript
import { Z3DRenderer, Z3DBall, Z3DContainer, Z3DSVG } from 'zsort3d';

// Create canvas element
const canvas = document.getElementById('my-canvas') as HTMLCanvasElement;

// Create 3D objects
const objects = [
  new Z3DBall(50), // radius 50
  new Z3DContainer(100, 100, '#FF0000'), // 100x100 red container
  new Z3DSVG('<svg>...</svg>', 80, 80, 'My SVG', 'https://example.com')
];

// Initialize renderer
const renderer = new Z3DRenderer(canvas, objects);

// Optional: adjust perspective
renderer.perspectiveDistance = 200;
```

## Architecture

- **IZ3DSortable**: Interface for 3D renderable objects
- **Z3DSortable**: Abstract base class implementing core 3D properties
- **Z3DRenderer**: Main rendering engine with Canvas 2D optimization
- **Z3DBall**: Sphere implementation with gradient shading
- **Z3DContainer**: Rectangular container implementation

## Rendering Optimizations

- **RequestAnimationFrame**: Smooth 60fps rendering loop
- **Depth Sorting**: Efficient back-to-front rendering order
- **Canvas Optimization**: Minimal clear/redraw operations
- **Scale-based Culling**: Skip expensive operations for tiny objects

## Development

### Library Development

```bash
# Install dependencies
npm install

# Build library (both CommonJS and ESM)
npm run build

# Watch mode for development
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint
```

### Demo Development

```bash
# Start demo server
npm run demo

# Build demo for production
npm run demo:build
```

### Publishing

The library is configured with a `prepublishOnly` script that automatically builds, type-checks, and lints before publishing:

```bash
npm publish
```

## Browser Support

- Modern browsers with Canvas 2D support
- ES2020+ JavaScript engines
- Node.js 16.0.0+

## License

MIT