@cristiancosano/pallet-builder 0.1.0

package/README.md

@@ -0,0 +1,293 @@
+# 📦 @cristiancosano/pallet-builder
+
+Sistema modular para visualización 3D de logística basado en React y React Three Fiber.
+
+## 🎯 Descripción
+
+Librería de componentes React que permite construir escenas 3D interactivas para visualizar operaciones logísticas como almacenes, pallets, cajas y contenedores de transporte.
+
+## ✨ Características
+
+- 🧱 **Sistema Modular**: Arquitectura limpia con separación entre lógica core y visualización
+- 🎨 **Componentes Declarativos**: API simple basada en componentes React
+- 📐 **Estándares Industriales**: Soporte para pallets EURO, ISO y personalizados  
+- 🔄 **Real-time**: Visualización 3D interactiva con controles de cámara
+- 📊 **Validaciones**: Lógica de negocio para validar dimensiones, pesos y ocupación
+- 🎯 **Agnóstico**: Core en TypeScript puro sin dependencias de frameworks de visualización
+
+## 🚀 Inicio Rápido
+
+### Instalación
+
+```bash
+pnpm install
+```
+
+### Desarrollo
+
+```bash
+pnpm dev
+```
+
+Abre [http://localhost:5173](http://localhost:5173) para ver la demo.
+
+## 📖 Uso Básico
+
+```tsx
+import { Warehouse, Pallet, Box } from '@cristiancosano/pallet-builder';
+
+function MiAppLogistica() {
+  return (
+    <Warehouse width={5000} depth={5000} showGrid>
+      
+      <Pallet id="pallet-A" position={[0, 0, 0]} type="EURO">
+        <Box 
+          dimensions={[400, 300, 200]} 
+          position={[0, 0, 0]} 
+          color="orange" 
+          label="Caja 1"
+        />
+      </Pallet>
+
+      <Pallet id="pallet-B" position={[1500, 0, 0]} type="ISO">
+        <Box 
+          dimensions={[500, 400, 300]} 
+          position={[0, 0, 0]} 
+          color="blue" 
+        />
+      </Pallet>
+
+    </Warehouse>
+  );
+}
+```
+
+## 🏗️ Arquitectura
+
+### Core (TypeScript Puro)
+
+Lógica de negocio agnóstica al framework de visualización:
+
+```typescript
+import { BoxEntity, PalletEntity, ContainerEntity } from '@cristiancosano/pallet-builder';
+
+// Crear un pallet con validaciones
+const pallet = new PalletEntity({
+  id: 'pallet-1',
+  type: 'EURO',
+  position: [0, 0, 0],
+  boxes: [
+    {
+      id: 'box-1',
+      dimensions: [400, 300, 200], // mm
+      position: [0, 0, 0],
+      weight: 25, // kg
+    }
+  ]
+});
+
+// Validar configuración
+const validation = pallet.validate();
+console.log('Peso total:', pallet.getTotalWeight(), 'kg');
+console.log('Ocupación:', pallet.getOccupancyRate(), '%');
+```
+
+### Componentes (React + R3F)
+
+Componentes visuales 3D construidos con React Three Fiber:
+
+- **`<Warehouse>`**: Contenedor principal de la escena 3D
+- **`<Pallet>`**: Representa un pallet con soporte para EURO, ISO o custom
+- **`<Box>`**: Caja/paquete posicionable dentro de un pallet
+- **`<CameraControls>`**: Controles de cámara (órbita, primera persona, etc.)
+
+## 📐 Estándares de Pallets
+
+### EUR-Pallet (EURO)
+- Dimensiones: 800 x 1200 x 144 mm
+- Peso máximo: 1500 kg
+- Altura máxima: 2200 mm
+
+### ISO Pallet (ISO)
+- Dimensiones: 1000 x 1200 x 144 mm
+- Peso máximo: 2000 kg
+- Altura máxima: 2200 mm
+
+### Custom
+- Dimensiones personalizables
+- Configuración flexible
+
+## 🎨 Componentes Disponibles
+
+### Warehouse
+
+Contenedor principal que crea la escena 3D con iluminación y controles.
+
+```tsx
+<Warehouse 
+  width={5000}      // mm
+  depth={5000}      // mm
+  height={3000}     // mm (opcional)
+  showGrid={true}   // Mostrar grid del suelo
+  backgroundColor="#f0f0f0"
+>
+  {/* Contenido */}
+</Warehouse>
+```
+
+### Pallet
+
+Representa un pallet estándar o personalizado.
+
+```tsx
+<Pallet 
+  id="pallet-1"
+  type="EURO"             // 'EURO' | 'ISO' | 'CUSTOM'
+  position={[0, 0, 0]}    // [x, y, z] en mm
+  rotation={[0, 0, 0]}    // [x, y, z] en radianes
+  color="#8B4513"
+  showDimensions={false}
+  customDimensions={[1000, 144, 1200]}  // Para CUSTOM
+>
+  {/* Cajas */}
+</Pallet>
+```
+
+### Box
+
+Caja o paquete dentro de un pallet.
+
+```tsx
+<Box 
+  dimensions={[400, 300, 200]}  // [ancho, alto, fondo] en mm
+  position={[0, 0, 0]}           // [x, y, z] dentro del pallet
+  color="#ff6b35"
+  label="Caja 1"
+  onClick={() => console.log('Click!')}
+  onHover={(hovered) => console.log(hovered)}
+/>
+```
+
+## 🎨 Personalización con AspectConfig
+
+El sistema `AspectConfig` permite personalizar la apariencia visual de cada componente individualmente.
+
+### Configuración Global
+
+Define valores por defecto para todos los componentes:
+
+```tsx
+import { ConfigurationProvider, PalletBuilder, Box } from '@cristiancosano/pallet-builder';
+
+function App() {
+  return (
+    <ConfigurationProvider 
+      config={{ 
+        usePalletModel: true,
+        palletModelUrl: '/objects/pallet.glb',
+        palletTextureUrl: '/textures/pallet_planks.png',
+        useBoxModel: true,
+        boxModelUrl: '/objects/box.glb',
+        boxTextureUrl: '/textures/crate_roughness.png'
+      }}
+    >
+      <PalletBuilder palletType="EURO">
+        <Box dimensions={[400, 300, 200]} position={[0, 0, 0]} color="#ff6b35" />
+      </PalletBuilder>
+    </ConfigurationProvider>
+  );
+}
+```
+
+### Personalización por Componente
+
+Cada pallet o caja puede tener su propia textura, modelo o color:
+
+```tsx
+<PalletBuilder 
+  palletType="EURO"
+  palletAspect={{ textureUrl: '/textures/dark_wood.png' }}
+>
+  {/* Caja con color personalizado */}
+  <Box 
+    dimensions={[400, 300, 200]} 
+    position={[0, 0, 0]}
+    aspect={{ color: '#00d9ff' }}
+    label="Caja Azul"
+  />
+  
+  {/* Caja con textura personalizada */}
+  <Box 
+    dimensions={[400, 300, 200]} 
+    position={[400, 0, 0]}
+    aspect={{ textureUrl: '/textures/cardboard.png' }}
+    label="Caja Cartón"
+  />
+  
+  {/* Caja con modelo 3D personalizado */}
+  <Box 
+    dimensions={[400, 300, 200]} 
+    position={[0, 0, 400]}
+    aspect={{ 
+      modelUrl: '/objects/custom_box.glb',
+      textureUrl: '/textures/metal.png'
+    }}
+    label="Caja Metal"
+  />
+</PalletBuilder>
+```
+
+### Modelos 3D y Texturas por Defecto
+
+La librería viene configurada con modelos y texturas por defecto:
+
+**Pallets:**
+- Modelo: `/objects/pallet.glb`
+- Textura: `/textures/pallet_planks.png`
+
+**Cajas:**
+- Modelo: `/objects/box.glb`
+- Textura: `/textures/crate_roughness.png`
+
+Puedes usar tus propios modelos GLB y texturas personalizando la configuración global o usando el prop `aspect` en cada componente individual.
+
+**Prioridad**: `aspect prop` > `ConfigurationProvider` > `defaults`
+
+Ver [docs/guides/aspect-customization.md](./docs/guides/aspect-customization.md) para ejemplos completos.
+
+## 🔮 Roadmap
+
+- [ ] **`<Truck>`**: Componente para visualizar camiones
+- [ ] **`<Container>`**: Contenedor marítimo
+- [ ] **Algoritmos de optimización**: Sugerencias automáticas de colocación
+- [ ] **Exportación**: Generar reportes y visualizaciones
+- [ ] **Física**: Simulación de peso y estabilidad
+- [ ] **Multiplayer**: Colaboración en tiempo real
+
+## 📚 Documentación
+
+Consulta la carpeta `/docs` para más información:
+
+- [Guía de Componentes 3D](./docs/guides/3d-components-development.md)
+- [Modelo de Dominio](./docs/context/domain-model.md)
+- [Convenciones de Código](./docs/context/coding-conventions.md)
+
+## 🤝 Contribuir
+
+Ver [CONTRIBUTING.md](./docs/guides/contributing.md)
+
+## � Atribuciones
+
+Este proyecto utiliza assets de terceros:
+
+- **HDR Environment Map**: [HDRI Haven/Poly Haven](https://polyhaven.com/) (CC0 License) via [pmndrs/drei-assets](https://github.com/pmndrs/drei-assets)
+
+Ver [ATTRIBUTIONS.md](./ATTRIBUTIONS.md) para detalles completos.
+
+## �📄 Licencia
+
+MIT © Cristian Cosano
+
+---
+
+**Hecho con ❤️ usando React Three Fiber**

package/dist/App.d.ts

@@ -0,0 +1,4 @@
+import './index.css';
+import './examples/examples.css';
+declare function App(): import("react/jsx-runtime").JSX.Element;
+export default App;

package/dist/components/controls/CameraControls/CameraControls.d.ts

@@ -0,0 +1,16 @@
+export type CameraPreset = 'perspective' | 'top' | 'front' | 'side' | 'isometric';
+export interface CameraControlsProps {
+    preset?: CameraPreset;
+    autoRotate?: boolean;
+    enablePan?: boolean;
+    enableZoom?: boolean;
+    target?: [number, number, number];
+    minDistance?: number;
+    maxDistance?: number;
+    sceneSize?: {
+        width: number;
+        height: number;
+        depth: number;
+    };
+}
+export declare const CameraControlsComponent: import("react").NamedExoticComponent<CameraControlsProps>;

package/dist/components/controls/CameraControls/index.d.ts

@@ -0,0 +1,2 @@
+export { CameraControlsComponent } from './CameraControls';
+export type { CameraControlsProps, CameraPreset } from './CameraControls';

package/dist/components/controls/CameraTracker/CameraTracker.d.ts

@@ -0,0 +1,8 @@
+export interface CameraTrackerProps {
+    onPositionChange: (position: {
+        x: number;
+        y: number;
+        z: number;
+    }) => void;
+}
+export declare function CameraTracker({ onPositionChange }: CameraTrackerProps): null;

package/dist/components/controls/CameraTracker/index.d.ts

@@ -0,0 +1,2 @@
+export { CameraTracker } from './CameraTracker';
+export type { CameraTrackerProps } from './CameraTracker';

package/dist/components/controls/MiniMap/MiniMap.d.ts

@@ -0,0 +1,20 @@
+import './MiniMap.css';
+export interface MiniMapProps {
+    sceneWidth: number;
+    sceneDepth: number;
+    sceneType: 'truck' | 'warehouse';
+    floorPolygon?: Array<{
+        x: number;
+        z: number;
+    }>;
+    cameraPosition?: {
+        x: number;
+        z: number;
+    };
+    targetPosition?: {
+        x: number;
+        z: number;
+    };
+    position?: 'bottom-left' | 'bottom-right';
+}
+export declare const MiniMap: import("react").NamedExoticComponent<MiniMapProps>;

package/dist/components/controls/MiniMap/index.d.ts

@@ -0,0 +1,2 @@
+export { MiniMap } from './MiniMap';
+export type { MiniMapProps } from './MiniMap';

package/dist/components/controls/ViewControls/ViewControls.d.ts

@@ -0,0 +1,8 @@
+import type { CameraPreset } from '../CameraControls';
+import './ViewControls.css';
+export interface ViewControlsProps {
+    currentPreset: CameraPreset;
+    onPresetChange: (preset: CameraPreset) => void;
+    position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+}
+export declare const ViewControls: import("react").NamedExoticComponent<ViewControlsProps>;

package/dist/components/controls/ViewControls/index.d.ts

@@ -0,0 +1,2 @@
+export { ViewControls } from './ViewControls';
+export type { ViewControlsProps } from './ViewControls';

package/dist/components/controls/index.d.ts

@@ -0,0 +1,8 @@
+export { CameraControlsComponent } from './CameraControls';
+export type { CameraControlsProps, CameraPreset } from './CameraControls';
+export { ViewControls } from './ViewControls';
+export type { ViewControlsProps } from './ViewControls';
+export { MiniMap } from './MiniMap';
+export type { MiniMapProps } from './MiniMap';
+export { CameraTracker } from './CameraTracker';
+export type { CameraTrackerProps } from './CameraTracker';

package/dist/components/environments/TruckEnvironment/TruckEnvironment.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from 'react';
+import type { Truck } from '@/core/entities/Truck';
+export interface TruckEnvironmentProps {
+    truck: Truck;
+    showGrid?: boolean;
+    wallOpacity?: number;
+    showRoof?: boolean;
+    showSideWalls?: boolean;
+    children?: ReactNode;
+}
+export declare const TruckEnvironment: import("react").NamedExoticComponent<TruckEnvironmentProps>;

package/dist/components/environments/TruckEnvironment/index.d.ts

@@ -0,0 +1,2 @@
+export { TruckEnvironment } from './TruckEnvironment';
+export type { TruckEnvironmentProps } from './TruckEnvironment';

package/dist/components/environments/WarehouseEnvironment/WarehouseEnvironment.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from 'react';
+import type { Room } from '@/core/entities/Room';
+export interface WarehouseEnvironmentProps {
+    room: Room;
+    floorColor?: string;
+    wallColor?: string;
+    showGrid?: boolean;
+    children?: ReactNode;
+}
+export declare const WarehouseEnvironment: import("react").NamedExoticComponent<WarehouseEnvironmentProps>;

package/dist/components/environments/WarehouseEnvironment/index.d.ts

@@ -0,0 +1,2 @@
+export { WarehouseEnvironment } from './WarehouseEnvironment';
+export type { WarehouseEnvironmentProps } from './WarehouseEnvironment';

package/dist/components/environments/index.d.ts

@@ -0,0 +1,4 @@
+export { WarehouseEnvironment } from './WarehouseEnvironment';
+export type { WarehouseEnvironmentProps } from './WarehouseEnvironment';
+export { TruckEnvironment } from './TruckEnvironment';
+export type { TruckEnvironmentProps } from './TruckEnvironment';

package/dist/components/index.d.ts

@@ -0,0 +1,4 @@
+export * from './primitives';
+export * from './environments';
+export * from './controls';
+export * from './scenes';

package/dist/components/primitives/Box/Box.d.ts

@@ -0,0 +1,14 @@
+import type { PlacedBox } from '@/core/entities/PlacedBox';
+export interface BoxProps {
+    placedBox: PlacedBox;
+    selected?: boolean;
+    highlighted?: boolean;
+    showLabel?: boolean;
+    color?: string;
+    opacity?: number;
+    selectedColor?: string;
+    highlightedColor?: string;
+    onClick?: (id: string) => void;
+    onHover?: (id: string | null) => void;
+}
+export declare const BoxComponent: import("react").NamedExoticComponent<BoxProps>;

package/dist/components/primitives/Box/index.d.ts

@@ -0,0 +1,2 @@
+export { BoxComponent } from './Box';
+export type { BoxProps } from './Box';

package/dist/components/primitives/Label/Label.d.ts

@@ -0,0 +1,10 @@
+import type { Position3D } from '@/core/types';
+export interface LabelProps {
+    text: string;
+    position: Position3D;
+    visible?: boolean;
+    fontSize?: number;
+    color?: string;
+    background?: string;
+}
+export declare const Label: import("react").NamedExoticComponent<LabelProps>;

package/dist/components/primitives/Label/index.d.ts

@@ -0,0 +1,2 @@
+export { Label } from './Label';
+export type { LabelProps } from './Label';

package/dist/components/primitives/Pallet/Pallet.d.ts

@@ -0,0 +1,9 @@
+import type { Pallet } from '@/core/entities/Pallet';
+import type { Position3D } from '@/core/types';
+export interface PalletComponentProps {
+    pallet: Pallet;
+    position?: Position3D;
+    color?: string;
+    edgeColor?: string;
+}
+export declare const PalletComponent: import("react").NamedExoticComponent<PalletComponentProps>;

package/dist/components/primitives/Pallet/index.d.ts

@@ -0,0 +1,2 @@
+export { PalletComponent } from './Pallet';
+export type { PalletComponentProps } from './Pallet';

package/dist/components/primitives/Separator/Separator.d.ts

@@ -0,0 +1,7 @@
+import type { Separator } from '@/core/entities/Separator';
+import type { Position3D } from '@/core/types';
+export interface SeparatorComponentProps {
+    separator: Separator;
+    position?: Position3D;
+}
+export declare const SeparatorComponent: import("react").NamedExoticComponent<SeparatorComponentProps>;

package/dist/components/primitives/Separator/index.d.ts

@@ -0,0 +1,2 @@
+export { SeparatorComponent } from './Separator';
+export type { SeparatorComponentProps } from './Separator';

package/dist/components/primitives/StackedPallet/StackedPallet.d.ts

@@ -0,0 +1,16 @@
+import type { StackedPallet } from '@/core/entities/StackedPallet';
+import type { Position3D } from '@/core/types';
+export interface StackedPalletComponentProps {
+    stackedPallet: StackedPallet;
+    position?: Position3D;
+    yRotation?: 0 | 90 | 180 | 270;
+    palletId?: string;
+    selectedBoxId?: string | null;
+    highlightedBoxId?: string | null;
+    selectedColor?: string;
+    highlightedColor?: string;
+    showLabels?: boolean;
+    onBoxClick?: (id: string) => void;
+    onBoxHover?: (id: string | null) => void;
+}
+export declare const StackedPalletComponent: import("react").NamedExoticComponent<StackedPalletComponentProps>;

package/dist/components/primitives/StackedPallet/index.d.ts

@@ -0,0 +1,2 @@
+export { StackedPalletComponent } from './StackedPallet';
+export type { StackedPalletComponentProps } from './StackedPallet';

package/dist/components/primitives/index.d.ts

@@ -0,0 +1,10 @@
+export { BoxComponent } from './Box';
+export type { BoxProps } from './Box';
+export { PalletComponent } from './Pallet';
+export type { PalletComponentProps } from './Pallet';
+export { SeparatorComponent } from './Separator';
+export type { SeparatorComponentProps } from './Separator';
+export { StackedPalletComponent } from './StackedPallet';
+export type { StackedPalletComponentProps } from './StackedPallet';
+export { Label } from './Label';
+export type { LabelProps } from './Label';

package/dist/components/scenes/PalletScene/PalletScene.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from 'react';
+import type { StackedPallet } from '@/core/entities/StackedPallet';
+import type { CameraPreset } from '@/components/controls/CameraControls';
+import type { ScenePreset } from '@/core/presets';
+export interface PalletSceneProps {
+    stackedPallet: StackedPallet;
+    preset?: string | ScenePreset;
+    selectedBoxId?: string | null;
+    highlightedBoxId?: string | null;
+    selectedColor?: string;
+    highlightedColor?: string;
+    showLabels?: boolean;
+    cameraPreset?: CameraPreset;
+    showGrid?: boolean;
+    showMiniMap?: boolean;
+    onBoxClick?: (id: string) => void;
+    onBoxHover?: (id: string | null) => void;
+    children?: ReactNode;
+    style?: React.CSSProperties;
+}
+export declare const PalletScene: import("react").NamedExoticComponent<PalletSceneProps>;

package/dist/components/scenes/PalletScene/index.d.ts

@@ -0,0 +1,2 @@
+export { PalletScene } from './PalletScene';
+export type { PalletSceneProps } from './PalletScene';

package/dist/components/scenes/TruckScene/TruckScene.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from 'react';
+import type { Truck } from '@/core/entities/Truck';
+import type { CameraPreset } from '@/components/controls/CameraControls';
+import type { ScenePreset } from '@/core/presets';
+export interface TruckSceneProps {
+    truck: Truck;
+    preset?: string | ScenePreset;
+    selectedBoxId?: string | null;
+    highlightedBoxId?: string | null;
+    selectedColor?: string;
+    highlightedColor?: string;
+    showLabels?: boolean;
+    showGrid?: boolean;
+    wallOpacity?: number;
+    showRoof?: boolean;
+    showSideWalls?: boolean;
+    cameraPreset?: CameraPreset;
+    showMiniMap?: boolean;
+    onBoxClick?: (id: string) => void;
+    onBoxHover?: (id: string | null) => void;
+    children?: ReactNode;
+    style?: React.CSSProperties;
+}
+export declare const TruckScene: import("react").NamedExoticComponent<TruckSceneProps>;

package/dist/components/scenes/TruckScene/index.d.ts

@@ -0,0 +1,2 @@
+export { TruckScene } from './TruckScene';
+export type { TruckSceneProps } from './TruckScene';

package/dist/components/scenes/WarehouseScene/WarehouseScene.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from 'react';
+import type { Room } from '@/core/entities/Room';
+import type { CameraPreset } from '@/components/controls/CameraControls';
+import type { ScenePreset } from '@/core/presets';
+export interface WarehouseSceneProps {
+    room: Room;
+    preset?: string | ScenePreset;
+    selectedBoxId?: string | null;
+    highlightedBoxId?: string | null;
+    selectedColor?: string;
+    highlightedColor?: string;
+    showLabels?: boolean;
+    cameraPreset?: CameraPreset;
+    showMiniMap?: boolean;
+    onBoxClick?: (id: string) => void;
+    onBoxHover?: (id: string | null) => void;
+    children?: ReactNode;
+    style?: React.CSSProperties;
+}
+export declare const WarehouseScene: import("react").NamedExoticComponent<WarehouseSceneProps>;

package/dist/components/scenes/WarehouseScene/index.d.ts

@@ -0,0 +1,2 @@
+export { WarehouseScene } from './WarehouseScene';
+export type { WarehouseSceneProps } from './WarehouseScene';

package/dist/components/scenes/index.d.ts

@@ -0,0 +1,6 @@
+export { PalletScene } from './PalletScene';
+export type { PalletSceneProps } from './PalletScene';
+export { TruckScene } from './TruckScene';
+export type { TruckSceneProps } from './TruckScene';
+export { WarehouseScene } from './WarehouseScene';
+export type { WarehouseSceneProps } from './WarehouseScene';

package/dist/context/PresetContext.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+import type { ScenePreset } from '@/core/presets';
+export interface PresetProviderProps {
+    preset?: string | ScenePreset;
+    children: ReactNode;
+}
+export declare function PresetProvider({ preset, children }: PresetProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function usePreset(): ScenePreset;

package/dist/core/constants.d.ts

@@ -0,0 +1,16 @@
+import { TruckType } from './types';
+import type { PalletPreset, TruckPreset } from './types';
+export declare const STANDARD_PALLETS: Record<string, PalletPreset>;
+export declare const AMERICAN_PALLET: PalletPreset;
+export declare const TRUCK_PRESETS: Record<Exclude<TruckType, 'CUSTOM'>, TruckPreset>;
+export declare const SEPARATOR_DEFAULTS: {
+    readonly thickness: 10;
+    readonly weight: 2;
+};
+export declare const UNITS: {
+    readonly MM_TO_M: 0.001;
+    readonly M_TO_MM: 1000;
+};
+export declare const COLLISION_TOLERANCE = 1;
+export declare const MIN_SUPPORT_PERCENTAGE = 0.6;
+export declare const WEIGHT_WARNING_THRESHOLD = 0.9;

package/dist/core/entities/Box.d.ts

@@ -0,0 +1,15 @@
+import type { Dimensions3D } from '../types';
+export interface Box {
+    id: string;
+    dimensions: Dimensions3D;
+    weight: number;
+    sku?: string;
+    type?: string;
+    fragile: boolean;
+    fragilityMaxWeight?: number;
+    stackable: boolean;
+    color?: string;
+    texture?: string;
+    modelUrl?: string;
+    metadata: Record<string, unknown>;
+}