@toolproof-core/visualization 1.0.0

package/dist/runtime/RuntimeView.js

@@ -0,0 +1,41 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Canvas } from '@react-three/fiber';
+import { OrbitControls } from '@react-three/drei';
+import { XR, createXRStore, useXR } from '@react-three/xr';
+import * as THREE from 'three';
+import { useEffect, useMemo, useRef } from 'react';
+export const runtimeXrStore = createXRStore();
+function RuntimeControls({ orbitControlsRef, target, }) {
+    const session = useXR((state) => state.session);
+    return (_jsx(OrbitControls, { ref: orbitControlsRef, target: target, makeDefault: true, enableDamping: true, dampingFactor: 0.05, enabled: !session }));
+}
+export default function RuntimeView(props) {
+    const { children, cameraConfig, background = 'skyblue' } = props;
+    const fallbackOrbitControlsRef = useRef(null);
+    const fallbackCameraRef = useRef(null);
+    const orbitControlsRef = props.orbitControlsRef ?? fallbackOrbitControlsRef;
+    const cameraRef = props.cameraRef ?? fallbackCameraRef;
+    const initialCamera = useMemo(() => ({ position: cameraConfig.position, fov: cameraConfig.fov }), 
+    // Only used for initial mount; follow-up updates happen via effect.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    useEffect(() => {
+        const camera = cameraRef.current;
+        const controls = orbitControlsRef.current;
+        if (!camera || !controls)
+            return;
+        camera.position.set(...cameraConfig.position);
+        if ('fov' in camera && typeof camera.fov === 'number') {
+            camera.fov = cameraConfig.fov;
+            camera.updateProjectionMatrix();
+        }
+        controls.target.set(...cameraConfig.target);
+        controls.update();
+    }, [cameraConfig, cameraRef, orbitControlsRef]);
+    return (_jsx(Canvas, { style: { width: '100%', height: '100%' }, camera: initialCamera, onCreated: ({ camera, scene }) => {
+            cameraRef.current = camera;
+            scene.background = new THREE.Color(background);
+        }, children: _jsxs(XR, { store: runtimeXrStore, children: [_jsx(RuntimeControls, { orbitControlsRef: orbitControlsRef, target: cameraConfig.target }), children] }) }));
+}
+//# sourceMappingURL=RuntimeView.js.map

package/dist/runtime/RuntimeView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeView.js","sourceRoot":"","sources":["../../src/runtime/RuntimeView.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@toolproof-core/visualization",
+  "version": "1.0.0",
+  "description": "",
+  "exports": {
+    "./runtime-controller": {
+      "types": "./dist/runtime/RuntimeController.d.ts",
+      "default": "./dist/runtime/RuntimeController.js"
+    },
+    "./ring-of-meshes": {
+      "types": "./dist/primitives/RingOfMeshes.d.ts",
+      "default": "./dist/primitives/RingOfMeshes.js"
+    },
+    "./spoke-of-meshes": {
+      "types": "./dist/primitives/SpokeOfMeshes.d.ts",
+      "default": "./dist/primitives/SpokeOfMeshes.js"
+    }
+  },
+  "type": "module",
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^20.19.25",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "@types/three": "^0.177.0",
+    "@types/react": "19.2.3",
+    "@types/react-dom": "19.2.3"
+  },
+  "peerDependencies": {
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.4.2",
+    "@react-three/xr": "^6.6.29",
+    "three": "^0.177.0"
+  },
+  "dependencies": {
+    "@toolproof-core/schema": "^1.0.18",
+    "@toolproof-core/lib": "1.0.12",
+    "gsap": "^3.14.2"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc -b"
+  }
+}

package/src/primitives/Portal.tsx

@@ -0,0 +1,261 @@
+import React, { useEffect, useLayoutEffect, useRef } from "react";
+import * as THREE from "three";
+import { useFrame, useThree } from "@react-three/fiber";
+import type { ThreeEvent } from "@react-three/fiber";
+import {
+  Environment,
+  MeshPortalMaterial,
+  Sparkles,
+  Stars,
+} from "@react-three/drei";
+import gsap from "gsap";
+
+type OrbitControlsLike = {
+  target: THREE.Vector3;
+};
+
+type MeshPortalMaterialImpl = React.ElementRef<typeof MeshPortalMaterial>;
+
+// ... types remain the same
+
+export type PortalInteractionPolicy =
+  | "none"
+  | "activate-only"
+  | "deactivate-only"
+  | "toggle";
+
+export interface PortalProps {
+  isActive: boolean;
+  setIsActive: (active: boolean) => void;
+  /**
+   * Controls whether user gestures can change portal active state.
+   * Defaults to "toggle" to preserve existing behavior.
+   */
+  interactionPolicy?: PortalInteractionPolicy;
+  orbitControlsRef?: React.RefObject<OrbitControlsLike | null>;
+  onTransitionComplete?: (active: boolean) => void;
+  targetScale?: number;
+  onScaleAnimationEnd?: () => void;
+  children?: React.ReactNode;
+}
+
+const PortalRing: React.FC<{
+  radius: number;
+  rotation?: number;
+  speed?: number;
+}> = ({ radius, rotation = 0, speed = 1 }) => {
+  const ringRef = useRef<THREE.Mesh>(null);
+
+  useFrame((state) => {
+    if (ringRef.current) {
+      ringRef.current.rotation.z = state.clock.elapsedTime * speed + rotation;
+    }
+  });
+
+  return (
+    <mesh ref={ringRef}>
+      <torusGeometry args={[radius, 0.08, 16, 100]} />
+      <meshStandardMaterial
+        color="#00d4ff"
+        emissive="#00d4ff"
+        emissiveIntensity={2}
+        transparent
+        opacity={0.8}
+      />
+    </mesh>
+  );
+};
+
+export default function Portal({
+  isActive,
+  setIsActive,
+  interactionPolicy = "toggle",
+  orbitControlsRef,
+  onTransitionComplete,
+  targetScale = 1,
+  onScaleAnimationEnd,
+  children,
+}: PortalProps) {
+  const portalMaterial = useRef<MeshPortalMaterialImpl | null>(null);
+  const groupRef = useRef<THREE.Group>(null);
+  const { camera } = useThree();
+
+  const onTransitionCompleteRef =
+    useRef<PortalProps["onTransitionComplete"]>(undefined);
+  useEffect(() => {
+    onTransitionCompleteRef.current = onTransitionComplete;
+  }, [onTransitionComplete]);
+
+  /* useLayoutEffect(() => {
+    if (groupRef.current) {
+      gsap.to(groupRef.current.scale, {
+        x: isActive ? targetScale : 0,
+        y: isActive ? targetScale : 0,
+        z: isActive ? targetScale : 0,
+        duration: 1,
+        ease: "back.out(1.7)",
+        onComplete: onScaleAnimationEnd,
+      });
+    }
+  }, [isActive, targetScale, onScaleAnimationEnd]); */
+
+  // useLayoutEffect(() => {
+  //   if (!portalMaterial.current) return;
+
+  //   gsap.to(portalMaterial.current, {
+  //     blend: isActive ? 1 : 0,
+  //     duration: 0.7,
+  //     ease: "power2.inOut",
+  //   });
+  // }, [isActive]);
+
+  // useLayoutEffect(() => {
+  //   const targetPos = isActive
+  //     ? new THREE.Vector3(5, 5, 10)
+  //     : new THREE.Vector3(10, 10, 0);
+  //   const targetLookAt = isActive
+  //     ? new THREE.Vector3(0, 0, 20)
+  //     : new THREE.Vector3(0, 0, 0);
+
+  //   const tl = gsap.timeline({
+  //     defaults: { duration: 1.5, ease: "power3.inOut" },
+  //     onComplete: () => onTransitionCompleteRef.current?.(isActive),
+  //   });
+
+  //   tl.to(camera.position, {
+  //     x: targetPos.x,
+  //     y: targetPos.y,
+  //     z: targetPos.z,
+  //   });
+
+  //   const orbitControls = orbitControlsRef?.current ?? null;
+  //   if (orbitControls) {
+  //     tl.to(
+  //       orbitControls.target,
+  //       {
+  //         x: targetLookAt.x,
+  //         y: targetLookAt.y,
+  //         z: targetLookAt.z,
+  //       },
+  //       0,
+  //     );
+  //   }
+
+  //   return () => {
+  //     tl.kill();
+  //   };
+  // }, [isActive, camera, orbitControlsRef]);
+
+  const handleDoubleClick = (e: ThreeEvent<MouseEvent>) => {
+    let nextActive: boolean | null = null;
+
+    switch (interactionPolicy) {
+      case "none":
+        return;
+      case "toggle":
+        nextActive = !isActive;
+        break;
+      case "activate-only":
+        nextActive = isActive ? null : true;
+        break;
+      case "deactivate-only":
+        nextActive = isActive ? false : null;
+        break;
+      default:
+        // Defensive: if a consumer passes an unknown value, preserve legacy toggle.
+        nextActive = !isActive;
+        break;
+    }
+
+    if (nextActive === null) return;
+    e.stopPropagation();
+    setIsActive(nextActive);
+  };
+
+  return (
+    <group ref={groupRef}>
+      <PortalRing radius={8.5} rotation={0} speed={0.3} />
+      <PortalRing radius={9} rotation={Math.PI / 4} speed={-0.2} />
+      <PortalRing radius={9.5} rotation={Math.PI / 2} speed={0.15} />
+
+      <Sparkles
+        count={100}
+        size={3}
+        scale={[20, 20, 6]}
+        speed={0.5}
+        color="#00d4ff"
+      />
+
+      <mesh onDoubleClick={handleDoubleClick}>
+        <circleGeometry args={[8, 64]} />
+        <MeshPortalMaterial
+          ref={portalMaterial}
+          side={THREE.DoubleSide}
+          transparent
+          blur={0.3}
+          resolution={512}
+        >
+          <ambientLight intensity={0.3} />
+          <pointLight position={[0, 5, 5]} intensity={2} color="#00d4ff" />
+          <pointLight position={[0, -5, 5]} intensity={1} color="#8b5cf6" />
+          <Environment preset="night" />
+
+          <mesh>
+            <sphereGeometry args={[30, 64, 64]} />
+            <meshStandardMaterial color="#050520" side={THREE.BackSide} />
+          </mesh>
+
+          <mesh>
+            <sphereGeometry args={[28, 32, 32]} />
+            <meshBasicMaterial
+              color="#1a0a30"
+              transparent
+              opacity={0.5}
+              side={THREE.BackSide}
+            />
+          </mesh>
+
+          <Stars
+            radius={25}
+            depth={50}
+            count={3000}
+            factor={4}
+            saturation={0.5}
+            fade
+            speed={1}
+          />
+
+          <group>{children}</group>
+
+          <Sparkles
+            count={200}
+            size={2}
+            scale={[20, 20, 20]}
+            speed={0.3}
+            color="#ffffff"
+          />
+        </MeshPortalMaterial>
+      </mesh>
+
+      <mesh>
+        <ringGeometry args={[7.8, 8.2, 64]} />
+        <meshBasicMaterial
+          color="#00d4ff"
+          transparent
+          opacity={0.8}
+          side={THREE.DoubleSide}
+        />
+      </mesh>
+
+      <mesh>
+        <ringGeometry args={[8, 8.5, 64]} />
+        <meshBasicMaterial
+          color="#00d4ff"
+          transparent
+          opacity={0.4}
+          side={THREE.DoubleSide}
+        />
+      </mesh>
+    </group>
+  );
+}

package/src/primitives/RingOfMeshes.tsx

@@ -0,0 +1,149 @@
+import type { NucleusBaseSmall } from '@toolproof-core/lib/types';
+import type { ReactNode } from 'react';
+import { useEffect, useMemo } from 'react';
+import * as THREE from 'three';
+import type { ThreeElements } from '@react-three/fiber';
+
+
+export type RingMeshConfig = {
+    geometry: THREE.BufferGeometry;
+    material: THREE.Material | THREE.Material[];
+};
+
+export type RingGuideConfig = {
+    /** Number of segments for the circle polyline. */
+    segments?: number;
+    /** Y offset for the guide relative to ring center. */
+    y?: number;
+    /** Provide your own material if you want full control. */
+    material?: THREE.LineBasicMaterial;
+    /** Convenience when not providing a material. */
+    color?: THREE.ColorRepresentation;
+    /** Convenience when not providing a material. Defaults to 0.35. */
+    opacity?: number;
+};
+
+export type RingOfMeshesProps<TItem extends NucleusBaseSmall = NucleusBaseSmall> = {
+    items: readonly TItem[];
+    ringRadius: number;
+    ringRotation?: [number, number, number];
+
+    /**
+     * Optional angular range (in radians) to distribute items across, instead of a full 2π ring.
+     * When provided:
+     * - count === 1: item is placed at the midpoint of the range
+     * - count > 1: items are evenly distributed from start → end
+     */
+    angleRange?: { start: number; end: number };
+    /**
+     * Optional visual guide (circle line) drawn through the centers of the meshes.
+     * - Omit/undefined/false: do not render.
+     * - Provide config object: render with given config.
+     */
+    ringGuide?: false | RingGuideConfig;
+    meshConfig: RingMeshConfig;
+    getMeshConfig?: (item: TItem, index: number) => RingMeshConfig;
+    getMeshProps?: (item: TItem, index: number) => ThreeElements['mesh'];
+    getItemGroupProps?: (item: TItem, index: number) => ThreeElements['group'];
+
+    /**
+     * Optional slot rendered after the mesh inside each positioned item group.
+     * Keeps this component focused on layout + mesh while allowing callers
+     * to render labels/overlays without duplicating ring math.
+     */
+    renderItemChildren?: (item: TItem, index: number) => ReactNode;
+};
+
+export function RingOfMeshes<TItem extends NucleusBaseSmall = NucleusBaseSmall>(props: RingOfMeshesProps<TItem>) {
+    const {
+        items,
+        ringRadius,
+        ringRotation = [0, 0, 0],
+        angleRange,
+        meshConfig,
+        ringGuide,
+        getMeshConfig,
+        getMeshProps,
+        getItemGroupProps,
+        renderItemChildren,
+    } = props;
+
+    const count = items.length;
+
+    const showRingGuide = ringGuide != null && ringGuide !== false;
+    const ringGuideConfig = showRingGuide ? ringGuide : undefined;
+
+    const ringGuideProvidedMaterial = ringGuideConfig?.material;
+    const ringGuideColor = ringGuideConfig?.color;
+    const ringGuideOpacity = ringGuideConfig?.opacity;
+
+    const ringGuideSegments = ringGuideConfig?.segments ?? 128;
+    const ringGuideY = ringGuideConfig?.y ?? 0;
+
+    const ringGuideGeometry = useMemo(() => {
+        if (!showRingGuide || count === 0) return null;
+        const points: THREE.Vector3[] = [];
+        for (let i = 0; i < ringGuideSegments; i++) {
+            const angle = (i / ringGuideSegments) * Math.PI * 2;
+            points.push(new THREE.Vector3(Math.cos(angle) * ringRadius, ringGuideY, Math.sin(angle) * ringRadius));
+        }
+        const geometry = new THREE.BufferGeometry();
+        geometry.setFromPoints(points);
+        return geometry;
+    }, [showRingGuide, count, ringGuideSegments, ringGuideY, ringRadius]);
+
+    const ringGuideMaterial = useMemo(() => {
+        if (!showRingGuide || count === 0) return null;
+        if (ringGuideProvidedMaterial) return ringGuideProvidedMaterial;
+        const opacity = ringGuideOpacity ?? 0.35;
+        return new THREE.LineBasicMaterial({
+            color: ringGuideColor ?? 'white',
+            transparent: opacity < 1,
+            opacity,
+        });
+    }, [showRingGuide, count, ringGuideProvidedMaterial, ringGuideOpacity, ringGuideColor]);
+
+    useEffect(() => {
+        return () => {
+            ringGuideGeometry?.dispose();
+            if (showRingGuide && ringGuideProvidedMaterial == null) {
+                ringGuideMaterial?.dispose();
+            }
+        };
+    }, [ringGuideGeometry, ringGuideMaterial, showRingGuide, ringGuideProvidedMaterial]);
+
+    if (count === 0) return null;
+
+    return (
+        <group rotation={ringRotation}>
+            {showRingGuide && ringGuideGeometry && ringGuideMaterial ? (
+                <lineLoop geometry={ringGuideGeometry} material={ringGuideMaterial} />
+            ) : null}
+            {items.map((item, index) => {
+                const angle = (() => {
+                    if (angleRange) {
+                        const { start, end } = angleRange;
+                        if (count <= 1) return (start + end) / 2;
+                        const t = index / (count - 1);
+                        return start + t * (end - start);
+                    }
+                    return (index / count) * Math.PI * 2;
+                })();
+                const x = Math.cos(angle) * ringRadius;
+                const z = Math.sin(angle) * ringRadius;
+
+                const resolvedMeshConfig = getMeshConfig ? getMeshConfig(item, index) : meshConfig;
+
+                const rawGroupProps = getItemGroupProps ? getItemGroupProps(item, index) : undefined;
+                const rawMeshProps = getMeshProps ? getMeshProps(item, index) : undefined;
+
+                return (
+                    <group key={item.identity} {...rawGroupProps} position={[x, 0, z]}>
+                        <mesh {...rawMeshProps} geometry={resolvedMeshConfig.geometry} material={resolvedMeshConfig.material} />
+                        {renderItemChildren ? renderItemChildren(item, index) : null}
+                    </group>
+                );
+            })}
+        </group>
+    );
+}

package/src/primitives/SpokeOfMeshes.tsx

@@ -0,0 +1,168 @@
+import type { NucleusBaseSmall } from '@toolproof-core/lib/types';
+import type { ReactNode } from 'react';
+import { useEffect, useMemo } from 'react';
+import * as THREE from 'three';
+import type { ThreeElements } from '@react-three/fiber';
+
+
+export type SpokeMeshConfig = {
+    geometry: THREE.BufferGeometry;
+    material: THREE.Material | THREE.Material[];
+};
+
+export type SpokeGuideConfig = {
+    /** Provide your own material if you want full control. */
+    material?: THREE.LineBasicMaterial;
+    /** Convenience when not providing a material. */
+    color?: THREE.ColorRepresentation;
+    /** Convenience when not providing a material. Defaults to 0.35. */
+    opacity?: number;
+};
+
+export type SpokeOfMeshesProps<TItem extends NucleusBaseSmall = NucleusBaseSmall> = {
+    items: readonly TItem[];
+
+    /** World position for the origin-nearest mesh (items[0]). */
+    originNearestPosition: [number, number, number];
+
+    /** Direction in which the line extends. Will be normalized internally. */
+    direction: [number, number, number];
+
+    /** Optional rotation around the anchor position. */
+    spokeRotation?: [number, number, number];
+
+    /** Optional visual guide (straight line) drawn through the centers of the meshes. */
+    spokeGuide?: false | SpokeGuideConfig;
+
+    meshConfig: SpokeMeshConfig;
+    getMeshConfig?: (item: TItem, index: number) => SpokeMeshConfig;
+    getMeshProps?: (item: TItem, index: number) => ThreeElements['mesh'];
+    getItemGroupProps?: (item: TItem, index: number) => ThreeElements['group'];
+
+    /**
+     * Explicit spacing between adjacent meshes.
+     * If omitted, spacing is derived from `meshConfig.geometry` bounding sphere.
+     */
+    itemSpacing?: number;
+
+    /** Multiplier applied when deriving spacing from geometry. */
+    itemSpacingMultiplier?: number;
+
+    /** Optional slot rendered after the mesh inside each positioned item group. */
+    renderItemChildren?: (item: TItem, index: number) => ReactNode;
+};
+
+export function SpokeOfMeshes<TItem extends NucleusBaseSmall = NucleusBaseSmall>(props: SpokeOfMeshesProps<TItem>) {
+    const {
+        items,
+        originNearestPosition,
+        direction,
+        spokeRotation: spokeRotation = [0, 0, 0],
+        spokeGuide,
+        meshConfig,
+        getMeshConfig,
+        getMeshProps,
+        getItemGroupProps,
+        renderItemChildren,
+        itemSpacing,
+        itemSpacingMultiplier,
+    } = props;
+
+    const count = items.length;
+    const showSpokeGuide = spokeGuide != null && spokeGuide !== false;
+    const spokeGuideConfig = showSpokeGuide ? spokeGuide : undefined;
+
+    const spokeGuideProvidedMaterial = spokeGuideConfig?.material;
+    const spokeGuideColor = spokeGuideConfig?.color;
+    const spokeGuideOpacity = spokeGuideConfig?.opacity;
+
+    const directionUnit = useMemo(() => {
+        const [dx, dy, dz] = direction;
+        const vec = new THREE.Vector3(dx, dy, dz);
+        if (vec.lengthSq() < 1e-12) {
+            vec.set(1, 0, 0);
+        } else {
+            vec.normalize();
+        }
+        return vec;
+    }, [direction]);
+
+    const resolvedItemSpacing = useMemo(() => {
+        if (typeof itemSpacing === 'number' && Number.isFinite(itemSpacing) && itemSpacing > 0) {
+            return itemSpacing;
+        }
+
+        const geometry = meshConfig.geometry;
+        if (!geometry.boundingSphere) {
+            geometry.computeBoundingSphere();
+        }
+
+        const radius = geometry.boundingSphere?.radius;
+        const diameter = typeof radius === 'number' && Number.isFinite(radius) && radius > 0 ? radius * 2 : 1;
+        const mult = typeof itemSpacingMultiplier === 'number' && Number.isFinite(itemSpacingMultiplier) && itemSpacingMultiplier > 0 ? itemSpacingMultiplier : 1.0;
+        return diameter * mult;
+    }, [itemSpacing, itemSpacingMultiplier, meshConfig.geometry]);
+
+    const spokeGuideGeometry = useMemo(() => {
+        if (!showSpokeGuide || count < 2) return null;
+
+        const start = new THREE.Vector3(0, 0, 0);
+        const end = directionUnit.clone().multiplyScalar(resolvedItemSpacing * (count - 1));
+
+        const geometry = new THREE.BufferGeometry();
+        geometry.setFromPoints([start, end]);
+        return geometry;
+    }, [showSpokeGuide, count, directionUnit, resolvedItemSpacing]);
+
+    const spokeGuideMaterial = useMemo(() => {
+        if (!showSpokeGuide || count < 2) return null;
+        if (spokeGuideProvidedMaterial) return spokeGuideProvidedMaterial;
+
+        const opacity = spokeGuideOpacity ?? 0.35;
+        return new THREE.LineBasicMaterial({
+            color: spokeGuideColor ?? 'white',
+            transparent: opacity < 1,
+            opacity,
+        });
+    }, [showSpokeGuide, count, spokeGuideProvidedMaterial, spokeGuideOpacity, spokeGuideColor]);
+
+    useEffect(() => {
+        return () => {
+            spokeGuideGeometry?.dispose();
+            if (showSpokeGuide && spokeGuideProvidedMaterial == null) {
+                spokeGuideMaterial?.dispose();
+            }
+        };
+    }, [spokeGuideGeometry, spokeGuideMaterial, showSpokeGuide, spokeGuideProvidedMaterial]);
+
+    if (count === 0) return null;
+
+    return (
+        <group position={originNearestPosition} rotation={spokeRotation}>
+            {showSpokeGuide && spokeGuideGeometry && spokeGuideMaterial ? (
+                <lineSegments geometry={spokeGuideGeometry} material={spokeGuideMaterial} />
+            ) : null}
+
+            {items.map((item, index) => {
+                const offset = resolvedItemSpacing * index;
+                const x = directionUnit.x * offset;
+                const y = directionUnit.y * offset;
+                const z = directionUnit.z * offset;
+
+                const resolvedMeshConfig = getMeshConfig ? getMeshConfig(item, index) : meshConfig;
+
+                const rawGroupProps = getItemGroupProps ? getItemGroupProps(item, index) : undefined;
+                const rawMeshProps = getMeshProps ? getMeshProps(item, index) : undefined;
+
+                return (
+                    <group key={item.identity} position={[x, y, z]}>
+                        <group {...rawGroupProps}>
+                            <mesh {...rawMeshProps} geometry={resolvedMeshConfig.geometry} material={resolvedMeshConfig.material} />
+                            {renderItemChildren ? renderItemChildren(item, index) : null}
+                        </group>
+                    </group>
+                );
+            })}
+        </group>
+    );
+}