The 3D system lives in src/3d/. Core logic is plain TypeScript classes and pure functions; the React layer is a thin shell that mounts them. This page maps every file to its responsibility and exports.

Core 3D Files

File	Responsibility
types.ts	Central type definitions and default constants for the entire 3D system. Defines every interface and enum, plus all DEFAULT_* config objects.
ThreeDShapeElement.ts	Top-level facade. Each instance owns one ThreeDEngine and provides the public API consumed by ThreeDShapeRenderer.
ThreeDEngine.ts	Creates and manages the WebGLRenderer, Scene, Camera, OrbitControls, lights and render loop. Delegates shape management to SceneManager and gizmo management to GizmoController.
SceneManager.ts	Maintains the registry of 3D objects in a scene. Handles add, remove, select, raycast, transform, material and geometry updates.
GizmoController.ts	Wraps Three.js TransformControls. Manages attach/detach, mode switching and the OrbitControls conflict.
GeometryFactory.ts	Pure functions that create BufferGeometry instances from a GeometryConfig. Supports all six primitives plus SVG extrusion.
MaterialSystem.ts	Creates and updates Three.js materials from a MaterialConfig. Handles texture loading, caching and disposal.
ModelLoader.ts	Loads external 3D model files. Handles format detection, loader instantiation, normalization and object-URL lifecycle.
SceneSerializer.ts	Serializes engine scene state to a JSON-safe snapshot and restores it on load.

React UI Components

File	Responsibility
ThreeDShapeRenderer.tsx	Mounts a ThreeDShapeElement into a DOM container. Manages element lifecycle, resize syncing, interaction mode and visibility-based pause/resume.
ThreeDPropertiesPanel.tsx	The properties panel shown when a 3D shape is selected. Controls canvas position, gizmo mode, 3D transform, geometry, material type, material properties and texture maps.
ThreeDShapePicker.tsx	Modal for choosing a primitive or importing a model. Shows a grid of six shape cards with a live 3D preview.
ThreeDShapePreview.tsx	Self-contained auto-rotating preview renderer used inside the picker. Creates a temporary engine, adds the primitive and orbits the camera.

Integration Points Outside src/3d/

File	3D Relevance
src/types/design.ts	Defines the threeDMetadata, threeDGeometryType and threeDSceneState fields on DesignElement (lines 200-205).
src/components/design-tool/Canvas.tsx	Renders ThreeDShapeRenderer for every threed-shape element. Controls pointer-event routing via activeThreeDElementId.
public/draco/gltf/	Draco decoder WASM files required by DRACOLoader.

Dependency Graph

types.ts  <-----------------------------------------------+
  ^                                                      |
  +-- GeometryFactory.ts <- MaterialSystem.ts            |
  |         ^                     ^                      |
  |         +------ SceneManager.ts ------------+        |
  |                       ^                     |        |
  |              ThreeDEngine.ts <- GizmoController.ts   |
  |                       ^                              |
  |              SceneSerializer.ts ---------------------+
  |                       ^
  |              ThreeDShapeElement.ts
  |                       ^
  |         +-------------+--------------+
  |         |             |              |
  |  ThreeDShapeRenderer  |  ThreeDPropertiesPanel
  |         |             |
  |         |    ThreeDShapePicker
  |         |             |
  |         |    ThreeDShapePreview
  |         |
  |    Canvas.tsx (design-tool)
  |
  +-- design.ts (types)

File Structure

Core 3D Files

React UI Components

Integration Points Outside src/3d/

Dependency Graph