refactor: extract usePathtracingMesh hook and optimize Zustand selectors (#865)

* refactor: extract usePathtracingMesh hook and optimize Zustand selectors

- Create usePathtracingMesh hook to encapsulate pathtracing mesh conversion
  logic, eliminating ~40 lines of duplicate code from 6 geometry components
- Refactor Particles, Bonds, Arrow, Box, Plane, Shape to use the new hook
- Fix type error in Bonds.tsx (hoverMeshRef was Mesh instead of InstancedMesh)
- Optimize Zustand store access by using individual selectors instead of
  object destructuring to prevent unnecessary re-renders
- Improve convertInstancedMesh utility with better bounding box computation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* use larger array if needed

* something finally working

* fix: add missing effect dependencies and cleanup unused imports

- Add updateMergedMesh to useEffect dependencies in all geometry components
- Memoize fullData in Cell.tsx for consistency with other components
- Remove unused BufferGeometryUtils import from convertInstancedMesh.ts

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* address comments

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

app/src/components/Canvas.tsx

@@ -51,21 +51,27 @@ const PATHTRACING_GEOMETRY_COMPONENTS = {
 	Box: Box,
 	Plane: Plane,
 	Shape: Shape,
+	Curve: Curve,
 } as const;
 
 /**
  * Components that accept geometryKey but NOT pathtracingEnabled.
  */
 const SIMPLE_GEOMETRY_COMPONENTS = {
-	Curve: Curve,
 	Camera: Camera,
 } as const;
 
 /**
- * Components that only accept data prop (no geometryKey).
+ * Components that only accept data prop AND pathtracingEnabled.
  */
-const DATA_ONLY_GEOMETRY_COMPONENTS = {
+const DATA_PATHTRACING_GEOMETRY_COMPONENTS = {
 	Cell: Cell,
+} as const;
+
+/**
+ * Components that only accept data prop (no geometryKey, no pathtracingEnabled).
+ */
+const DATA_ONLY_GEOMETRY_COMPONENTS = {
 	Floor: Floor,
 } as const;
 
@@ -321,6 +327,22 @@ function MyScene() {
 								);
 							}
 
+							// Check data + pathtracing components (no geometryKey, but pathtracingEnabled)
+							if (type in DATA_PATHTRACING_GEOMETRY_COMPONENTS) {
+								const Component =
+									DATA_PATHTRACING_GEOMETRY_COMPONENTS[
+										type as keyof typeof DATA_PATHTRACING_GEOMETRY_COMPONENTS
+									];
+								return (
+									<GeometryErrorBoundary key={name} geometryKey={name}>
+										<Component
+											data={config.data}
+											pathtracingEnabled={pathtracingEnabled}
+										/>
+									</GeometryErrorBoundary>
+								);
+							}
+
 							// Check data-only components (no geometryKey)
 							if (type in DATA_ONLY_GEOMETRY_COMPONENTS) {
 								const Component =

app/src/components/PathtracingUpdater.tsx

@@ -1,16 +1,15 @@
 import { useEffect, useRef } from "react";
 import { usePathtracer } from "@react-three/gpu-pathtracer";
+import { useFrame } from "@react-three/fiber";
 import { useAppStore } from "../store";
 import type { PathTracing } from "../types/room-config";
 
 /**
  * Component that watches for pathtracing update requests and calls
  * pathtracer.update() to rebuild the BVH acceleration structure.
  *
- * This is needed when:
- * - Scene changes dynamically (e.g., particles switching from instanced to individual meshes)
- * - Current frame changes (particles move, arrows change, etc.)
- * - Pathtracing settings change
+ * Uses useFrame to ensure update() is called after R3F has finished
+ * processing all scene updates in the render loop.
  */
 export function PathtracingUpdater({ settings }: { settings: PathTracing }) {
 	const pathtracingNeedsUpdate = useAppStore(
@@ -25,38 +24,32 @@ export function PathtracingUpdater({ settings }: { settings: PathTracing }) {
 
 	// Track if this is the first render to avoid calling update on mount
 	const isFirstRender = useRef(true);
+	// Pending update flag - processed in useFrame to ensure scene is stable
+	const pendingUpdate = useRef(false);
 
-	// Handle manual update requests (e.g., when switching to individual meshes)
+	// Capture manual update requests
 	useEffect(() => {
-		if (pathtracingNeedsUpdate && update) {
-			update();
+		if (pathtracingNeedsUpdate) {
+			pendingUpdate.current = true;
 			clearPathtracingUpdate();
 		}
-	}, [pathtracingNeedsUpdate, update, clearPathtracingUpdate]);
+	}, [pathtracingNeedsUpdate, clearPathtracingUpdate]);
 
-	// Handle automatic updates when frame changes
+	// Capture frame change updates
 	useEffect(() => {
-		// Skip the first render
 		if (isFirstRender.current) {
 			isFirstRender.current = false;
 			return;
 		}
+		pendingUpdate.current = true;
+	}, [currentFrame]);
 
-		if (update) {
-			update();
-		}
-	}, [currentFrame, update]);
-
-	// Handle automatic updates when pathtracing settings change
+	// Capture settings change updates
 	useEffect(() => {
-		// Skip the first render
 		if (isFirstRender.current) {
 			return;
 		}
-
-		if (update) {
-			update();
-		}
+		pendingUpdate.current = true;
 	}, [
 		settings.samples,
 		settings.min_samples,
@@ -66,9 +59,15 @@ export function PathtracingUpdater({ settings }: { settings: PathTracing }) {
 		settings.environment_intensity,
 		settings.environment_blur,
 		settings.environment_background,
-		update,
 	]);
 
-	// This component doesn't render anything
+	// Execute update in useFrame - guarantees R3F has processed scene updates
+	useFrame(() => {
+		if (pendingUpdate.current && update) {
+			update();
+			pendingUpdate.current = false;
+		}
+	});
+
 	return null;
 }

app/src/components/ProgressBar.tsx

@@ -27,26 +27,27 @@ const FrameProgressBar = () => {
 	const sliderContainerRef = useRef<HTMLDivElement>(null);
 	const [sliderWidth, setSliderWidth] = useState(0);
 
-	const {
-		currentFrame,
-		setCurrentFrame,
-		frameCount,
-		isConnected,
-		isLoading,
-		skipFrames,
-		setSkipFrames,
-		frame_selection,
-		bookmarks,
-		addBookmark,
-		deleteBookmark,
-		frameSelectionEnabled,
-		setFrameSelectionEnabled,
-		synchronizedMode,
-		setSynchronizedMode,
-		getIsFetching,
-		playing,
-		setPlaying,
-	} = useAppStore();
+	const currentFrame = useAppStore((state) => state.currentFrame);
+	const frameCount = useAppStore((state) => state.frameCount);
+	const isConnected = useAppStore((state) => state.isConnected);
+	const isLoading = useAppStore((state) => state.isLoading);
+	const skipFrames = useAppStore((state) => state.skipFrames);
+	const setSkipFrames = useAppStore((state) => state.setSkipFrames);
+	const frame_selection = useAppStore((state) => state.frame_selection);
+	const bookmarks = useAppStore((state) => state.bookmarks);
+	const addBookmark = useAppStore((state) => state.addBookmark);
+	const deleteBookmark = useAppStore((state) => state.deleteBookmark);
+	const frameSelectionEnabled = useAppStore(
+		(state) => state.frameSelectionEnabled,
+	);
+	const setFrameSelectionEnabled = useAppStore(
+		(state) => state.setFrameSelectionEnabled,
+	);
+	const synchronizedMode = useAppStore((state) => state.synchronizedMode);
+	const setSynchronizedMode = useAppStore((state) => state.setSynchronizedMode);
+	const getIsFetching = useAppStore((state) => state.getIsFetching);
+	const playing = useAppStore((state) => state.playing);
+	const setPlaying = useAppStore((state) => state.setPlaying);
 
 	const { setStep, remoteLocked } = useStepControl();
 

app/src/components/SelectionGroupsPanel.tsx

@@ -41,14 +41,16 @@ interface SelectionGroupRow {
 }
 
 export default function SelectionGroupsPanel() {
-	const {
-		roomId,
-		selections,
-		selectionGroups,
-		activeSelectionGroup,
-		updateSelectionForGeometry,
-		showSnackbar,
-	} = useAppStore();
+	const roomId = useAppStore((state) => state.roomId);
+	const selections = useAppStore((state) => state.selections);
+	const selectionGroups = useAppStore((state) => state.selectionGroups);
+	const activeSelectionGroup = useAppStore(
+		(state) => state.activeSelectionGroup,
+	);
+	const updateSelectionForGeometry = useAppStore(
+		(state) => state.updateSelectionForGeometry,
+	);
+	const showSnackbar = useAppStore((state) => state.showSnackbar);
 
 	// Local state
 	const [currentGroupName, setCurrentGroupName] = useState("");

app/src/components/three/Arrow.tsx

@@ -30,10 +30,7 @@ import {
 	_matrix2,
 	_color,
 } from "../../utils/threeObjectPools";
-import {
-	convertInstancedMeshToMerged,
-	disposeMesh,
-} from "../../utils/convertInstancedMesh";
+import { usePathtracingMesh } from "../../hooks/usePathtracingMesh";
 import { getGeometryWithDefaults } from "../../utils/geometryDefaults";
 import { useFrameKeys } from "../../hooks/useSchemas";
 
@@ -105,10 +102,9 @@ export default function Arrow({
 	const geometryDefaults = useAppStore((state) => state.geometryDefaults);
 
 	// Merge with defaults from Pydantic (single source of truth)
-	const fullData = getGeometryWithDefaults<ArrowData>(
-		data,
-		"Arrow",
-		geometryDefaults,
+	const fullData = useMemo(
+		() => getGeometryWithDefaults<ArrowData>(data, "Arrow", geometryDefaults),
+		[data, geometryDefaults],
 	);
 	const {
 		position: positionProp,
@@ -126,9 +122,17 @@ export default function Arrow({
 	const mainMeshRef = useRef<THREE.InstancedMesh | null>(null);
 	const selectionMeshRef = useRef<THREE.InstancedMesh | null>(null);
 	const hoverMeshRef = useRef<THREE.Mesh | null>(null);
-	const mergedMeshRef = useRef<THREE.Mesh | null>(null);
+	const parentGroupRef = useRef<THREE.Group | null>(null);
 	const [instanceCount, setInstanceCount] = useState(0);
 
+	// Pathtracing: convert instanced mesh to merged mesh
+	// Uses refs and manual scene management for precise timing control
+	const updateMergedMesh = usePathtracingMesh(
+		parentGroupRef,
+		mainMeshRef,
+		pathtracingEnabled,
+	);
+
 	// Use individual selectors to prevent unnecessary re-renders
 	const currentFrame = useAppStore((state) => state.currentFrame);
 	const frameCount = useAppStore((state) => state.frameCount);
@@ -151,9 +155,6 @@ export default function Arrow({
 	const removeGeometryFetching = useAppStore(
 		(state) => state.removeGeometryFetching,
 	);
-	const requestPathtracingUpdate = useAppStore(
-		(state) => state.requestPathtracingUpdate,
-	);
 
 	// Fetch frame keys to check if required data is available
 	const { data: frameKeysData, isLoading: isLoadingKeys } = useFrameKeys(
@@ -443,6 +444,11 @@ export default function Arrow({
 			mainMesh.computeBoundingBox();
 			mainMesh.computeBoundingSphere();
 
+			// Update pathtracing mesh if enabled
+			if (pathtracingEnabled) {
+				updateMergedMesh(geometry);
+			}
+
 			// --- Selection Mesh Update ---
 			if (selecting.enabled && selectionMeshRef.current) {
 				const selectionMesh = selectionMeshRef.current;
@@ -491,7 +497,6 @@ export default function Arrow({
 			if (instanceCount !== 0) setInstanceCount(0);
 		}
 	}, [
-		data, // Add data to dependencies to ensure updates trigger
 		frameCount, // Watch frameCount to clear arrows when it becomes 0
 		isFetching,
 		positionData,
@@ -508,6 +513,12 @@ export default function Arrow({
 		validSelectedIndices,
 		selecting,
 		geometryKey,
+		pathtracingEnabled,
+		resolution,
+		material,
+		opacity,
+		data,
+		updateMergedMesh,
 	]);
 
 	// Separate effect for hover mesh updates - doesn't trigger data reprocessing
@@ -544,45 +555,6 @@ export default function Arrow({
 		}
 	}, [hoveredGeometryInstance, instanceCount, hovering, geometryKey]);
 
-	// Convert instanced mesh to merged mesh for path tracing
-	useEffect(() => {
-		if (!pathtracingEnabled) {
-			// Clean up merged mesh when pathtracing disabled
-			if (mergedMeshRef.current) {
-				disposeMesh(mergedMeshRef.current);
-				mergedMeshRef.current = null;
-			}
-			return;
-		}
-
-		if (!mainMeshRef.current || instanceCount === 0) return;
-
-		// Dispose old merged mesh if it exists
-		if (mergedMeshRef.current) {
-			disposeMesh(mergedMeshRef.current);
-		}
-
-		// Convert instanced mesh to single merged mesh with vertex colors
-		const mergedMesh = convertInstancedMeshToMerged(mainMeshRef.current);
-		mergedMeshRef.current = mergedMesh;
-
-		// Request pathtracing update
-		requestPathtracingUpdate();
-
-		// Cleanup on unmount or when dependencies change
-		return () => {
-			if (mergedMeshRef.current) {
-				disposeMesh(mergedMeshRef.current);
-				mergedMeshRef.current = null;
-			}
-		};
-	}, [
-		pathtracingEnabled,
-		instanceCount,
-		geometryKey,
-		requestPathtracingUpdate,
-	]);
-
 	// Create the base geometry, recreate when resolution changes
 	const geometry = useMemo(() => createArrowMesh(resolution), [resolution]);
 
@@ -631,8 +603,9 @@ export default function Arrow({
 	}
 
 	return (
-		<group>
+		<group ref={parentGroupRef}>
 			{/* Main instanced mesh - visible when NOT pathtracing */}
+			{/* Merged mesh for pathtracing is added to this group imperatively via usePathtracingMesh */}
 			<instancedMesh
 				key={instanceCount}
 				ref={mainMeshRef}
@@ -688,11 +661,6 @@ export default function Arrow({
 					/>
 				</mesh>
 			)}
-
-			{/* Merged mesh - visible when pathtracing */}
-			{pathtracingEnabled && mergedMeshRef.current && (
-				<primitive object={mergedMeshRef.current} />
-			)}
 		</group>
 	);
 }