From 4f45e04cb995fd978e8bf189dea46f4b3f22bd24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=96mer=20Faruk=20Demirel?= <omerfdmrl@gmail.com>
Date: Tue, 31 Mar 2026 15:35:12 +0300
Subject: [PATCH] fix: add orbit controlers and tooltip to 3d scenes

---
 .../content/GradientVectorScene.astro         | 88 ++++++++++++++++++-
 src/components/content/HyperplaneScene.astro  | 88 ++++++++++++++++++-
 src/components/content/Scene3D.astro          | 88 ++++++++++++++++++-
 src/utils/scene3d.ts                          | 46 ++++++++++
 4 files changed, 304 insertions(+), 6 deletions(-)

diff --git a/src/components/content/GradientVectorScene.astro b/src/components/content/GradientVectorScene.astro
index 3681f3a..8da750a 100644
--- a/src/components/content/GradientVectorScene.astro
+++ b/src/components/content/GradientVectorScene.astro
@@ -143,6 +143,7 @@ const chartId = `gradient-${id || Math.random().toString(36).slice(2, 9)}`
 
 <script>
 	import * as THREE from 'three'
+	import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
 	import { onHydration } from '../../utils/hydration'
 	import {
 		createBaseScene,
@@ -158,6 +159,9 @@ const chartId = `gradient-${id || Math.random().toString(36).slice(2, 9)}`
 		makeLabel,
 		getThemeColors3D,
 		setupZoomControls,
+		createTooltip,
+		showTooltip,
+		hideTooltip,
 	} from '../../utils/scene3d'
 
 	function hexToNum(hex: string): number {
@@ -208,7 +212,11 @@ const chartId = `gradient-${id || Math.random().toString(36).slice(2, 9)}`
 			let scene: THREE.Scene
 			let camera: THREE.PerspectiveCamera
 			let renderer: THREE.WebGLRenderer
-			let controls: any
+			let controls: OrbitControls
+			let pointsGroup: THREE.Group
+			let raycaster: THREE.Raycaster
+			let mouse: THREE.Vector2
+			let hoveredMesh: THREE.Mesh | null = null
 
 			function toWorld(v: { x: number; y: number; z: number }): THREE.Vector3 {
 				return new THREE.Vector3((v.x / axisRange) * CUBE, (v.y / axisRange) * CUBE, (v.z / axisRange) * CUBE)
@@ -267,7 +275,8 @@ const chartId = `gradient-${id || Math.random().toString(36).slice(2, 9)}`
 				rawPoints.forEach((p: any) => {
 					const color = p.color ? hexToNum(p.color) : 0xf59e0b
 					const pos = toWorld(p.position)
-					renderPoint(scene, pos, color, p.size || 10, 1)
+					const mesh = renderPoint(scene, pos, color, p.size || 10, 1)
+					mesh.userData = { index: rawPoints.indexOf(p), originalColor: new THREE.Color(color), data: p }
 					if (p.label) {
 						scene.add(
 							makeLabel(p.label, pos.clone().add(new THREE.Vector3(0, 0.18, 0)), color, 0.22, 0.09, 26),
@@ -275,6 +284,14 @@ const chartId = `gradient-${id || Math.random().toString(36).slice(2, 9)}`
 					}
 				})
 
+				pointsGroup = new THREE.Group()
+				scene.children.forEach((child) => {
+					if (child instanceof THREE.Mesh && child.geometry instanceof THREE.SphereGeometry) {
+						pointsGroup.add(child)
+					}
+				})
+				scene.add(pointsGroup)
+
 				rawVectors.forEach((v: any) => {
 					const color = v.color ? hexToNum(v.color) : 0x3b82f6
 					const vOrigin = v.origin ? toWorld(v.origin) : new THREE.Vector3(0, 0, 0)
@@ -295,6 +312,73 @@ const chartId = `gradient-${id || Math.random().toString(36).slice(2, 9)}`
 
 				setupZoomControls(wrapper as HTMLElement, camera, controls, DEFAULT_EYE, CENTER)
 
+				const tooltip = createTooltip(container)
+
+				raycaster = new THREE.Raycaster()
+				raycaster.params.Points = { threshold: 0.02 }
+				mouse = new THREE.Vector2()
+
+				renderer.domElement.addEventListener('mousemove', (e: MouseEvent) => {
+					const rect = renderer.domElement.getBoundingClientRect()
+					mouse.x = ((e.clientX - rect.left) / rect.width) * 2 - 1
+					mouse.y = -((e.clientY - rect.top) / rect.height) * 2 + 1
+
+					raycaster.setFromCamera(mouse, camera)
+					const hits = raycaster.intersectObjects(pointsGroup.children, false)
+
+					if (hoveredMesh && (!hits.length || hits[0].object !== hoveredMesh)) {
+						;(hoveredMesh.material as THREE.MeshStandardMaterial).color.copy(
+							hoveredMesh.userData.originalColor,
+						)
+						;(hoveredMesh.material as THREE.MeshStandardMaterial).emissive.set(0x000000)
+						hoveredMesh = null
+						hideTooltip(tooltip)
+					}
+
+					renderer.domElement.style.cursor = hits.length ? 'pointer' : 'grab'
+
+					if (hits.length) {
+						const mesh = hits[0].object as THREE.Mesh
+						if (mesh !== hoveredMesh) {
+							hoveredMesh = mesh
+							;(mesh.material as THREE.MeshStandardMaterial).color.set(0xffffff)
+							;(mesh.material as THREE.MeshStandardMaterial).emissive.set(0x444444)
+						}
+						const d = mesh.userData.data
+						const lbl = d.label ? `<strong>${d.label}</strong><br/>` : ''
+						showTooltip(
+							tooltip,
+							e.offsetX,
+							e.offsetY,
+							`${lbl}x: ${d.position.x.toFixed(2)}<br/>y: ${d.position.y.toFixed(2)}<br/>z: ${d.position.z.toFixed(2)}`,
+							container.getBoundingClientRect(),
+						)
+					}
+				})
+
+				renderer.domElement.addEventListener('click', (e: MouseEvent) => {
+					const rect = renderer.domElement.getBoundingClientRect()
+					mouse.x = ((e.clientX - rect.left) / rect.width) * 2 - 1
+					mouse.y = -((e.clientY - rect.top) / rect.height) * 2 + 1
+					raycaster.setFromCamera(mouse, camera)
+					const hits = raycaster.intersectObjects(pointsGroup.children, false)
+					if (hits.length) {
+						const d = (hits[0].object as THREE.Mesh).userData.data
+						container.dispatchEvent(
+							new CustomEvent('chart:click', {
+								bubbles: true,
+								detail: {
+									type: 'gradient',
+									x: d.position.x,
+									y: d.position.y,
+									z: d.position.z,
+									label: d.label,
+								},
+							}),
+						)
+					}
+				})
+
 				let rafId: number
 				function animate() {
 					rafId = requestAnimationFrame(animate)
diff --git a/src/components/content/HyperplaneScene.astro b/src/components/content/HyperplaneScene.astro
index c5e639e..0393a8d 100644
--- a/src/components/content/HyperplaneScene.astro
+++ b/src/components/content/HyperplaneScene.astro
@@ -127,6 +127,7 @@ const chartId = `hyperplane-${id || Math.random().toString(36).slice(2, 9)}`
 
 <script>
 	import * as THREE from 'three'
+	import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
 	import { onHydration } from '../../utils/hydration'
 	import {
 		createBaseScene,
@@ -142,6 +143,9 @@ const chartId = `hyperplane-${id || Math.random().toString(36).slice(2, 9)}`
 		makeLabel,
 		getThemeColors3D,
 		setupZoomControls,
+		createTooltip,
+		showTooltip,
+		hideTooltip,
 	} from '../../utils/scene3d'
 
 	function hexToNum(hex: string): number {
@@ -205,7 +209,11 @@ const chartId = `hyperplane-${id || Math.random().toString(36).slice(2, 9)}`
 			let scene: THREE.Scene
 			let camera: THREE.PerspectiveCamera
 			let renderer: THREE.WebGLRenderer
-			let controls: any
+			let controls: OrbitControls
+			let pointsGroup: THREE.Group
+			let raycaster: THREE.Raycaster
+			let mouse: THREE.Vector2
+			let hoveredMesh: THREE.Mesh | null = null
 
 			function scaleX(v: number) {
 				return ((v - xR.min) / (xR.max - xR.min)) * CUBE
@@ -267,7 +275,8 @@ const chartId = `hyperplane-${id || Math.random().toString(36).slice(2, 9)}`
 					const color = p.color ? hexToNum(p.color) : 0x3b82f6
 					const pos = toWorld(p.position)
 					pointsData.push(pos)
-					renderPoint(scene, pos, color, 10, 1)
+					const mesh = renderPoint(scene, pos, color, 10, 1)
+					mesh.userData = { index: rawPoints.indexOf(p), originalColor: new THREE.Color(color), data: p }
 					if (p.label) {
 						scene.add(
 							makeLabel(p.label, pos.clone().add(new THREE.Vector3(0, 0.15, 0)), color, 0.2, 0.08, 22),
@@ -275,6 +284,14 @@ const chartId = `hyperplane-${id || Math.random().toString(36).slice(2, 9)}`
 					}
 				})
 
+				pointsGroup = new THREE.Group()
+				scene.children.forEach((child) => {
+					if (child instanceof THREE.Mesh && child.geometry instanceof THREE.SphereGeometry) {
+						pointsGroup.add(child)
+					}
+				})
+				scene.add(pointsGroup)
+
 				if (showResiduals) {
 					pointsData.forEach((pos) => {
 						const projected = projectPointOnPlane(pos, planeNormalVec, planePointVec)
@@ -289,6 +306,73 @@ const chartId = `hyperplane-${id || Math.random().toString(36).slice(2, 9)}`
 
 				setupZoomControls(wrapper as HTMLElement, camera, controls, DEFAULT_EYE, CENTER)
 
+				const tooltip = createTooltip(container)
+
+				raycaster = new THREE.Raycaster()
+				raycaster.params.Points = { threshold: 0.02 }
+				mouse = new THREE.Vector2()
+
+				renderer.domElement.addEventListener('mousemove', (e: MouseEvent) => {
+					const rect = renderer.domElement.getBoundingClientRect()
+					mouse.x = ((e.clientX - rect.left) / rect.width) * 2 - 1
+					mouse.y = -((e.clientY - rect.top) / rect.height) * 2 + 1
+
+					raycaster.setFromCamera(mouse, camera)
+					const hits = raycaster.intersectObjects(pointsGroup.children, false)
+
+					if (hoveredMesh && (!hits.length || hits[0].object !== hoveredMesh)) {
+						;(hoveredMesh.material as THREE.MeshStandardMaterial).color.copy(
+							hoveredMesh.userData.originalColor,
+						)
+						;(hoveredMesh.material as THREE.MeshStandardMaterial).emissive.set(0x000000)
+						hoveredMesh = null
+						hideTooltip(tooltip)
+					}
+
+					renderer.domElement.style.cursor = hits.length ? 'pointer' : 'grab'
+
+					if (hits.length) {
+						const mesh = hits[0].object as THREE.Mesh
+						if (mesh !== hoveredMesh) {
+							hoveredMesh = mesh
+							;(mesh.material as THREE.MeshStandardMaterial).color.set(0xffffff)
+							;(mesh.material as THREE.MeshStandardMaterial).emissive.set(0x444444)
+						}
+						const d = mesh.userData.data
+						const lbl = d.label ? `<strong>${d.label}</strong><br/>` : ''
+						showTooltip(
+							tooltip,
+							e.offsetX,
+							e.offsetY,
+							`${lbl}x: ${d.position.x.toFixed(2)}<br/>y: ${d.position.y.toFixed(2)}<br/>z: ${d.position.z.toFixed(2)}`,
+							container.getBoundingClientRect(),
+						)
+					}
+				})
+
+				renderer.domElement.addEventListener('click', (e: MouseEvent) => {
+					const rect = renderer.domElement.getBoundingClientRect()
+					mouse.x = ((e.clientX - rect.left) / rect.width) * 2 - 1
+					mouse.y = -((e.clientY - rect.top) / rect.height) * 2 + 1
+					raycaster.setFromCamera(mouse, camera)
+					const hits = raycaster.intersectObjects(pointsGroup.children, false)
+					if (hits.length) {
+						const d = (hits[0].object as THREE.Mesh).userData.data
+						container.dispatchEvent(
+							new CustomEvent('chart:click', {
+								bubbles: true,
+								detail: {
+									type: 'hyperplane',
+									x: d.position.x,
+									y: d.position.y,
+									z: d.position.z,
+									label: d.label,
+								},
+							}),
+						)
+					}
+				})
+
 				let rafId: number
 				function animate() {
 					rafId = requestAnimationFrame(animate)
diff --git a/src/components/content/Scene3D.astro b/src/components/content/Scene3D.astro
index 5f028aa..5236916 100644
--- a/src/components/content/Scene3D.astro
+++ b/src/components/content/Scene3D.astro
@@ -122,6 +122,7 @@ const chartId = `scene3d-${id || Math.random().toString(36).slice(2, 9)}`
 
 <script>
 	import * as THREE from 'three'
+	import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
 	import { onHydration } from '../../utils/hydration'
 	import {
 		createBaseScene,
@@ -137,6 +138,9 @@ const chartId = `scene3d-${id || Math.random().toString(36).slice(2, 9)}`
 		makeLabel,
 		getThemeColors3D,
 		setupZoomControls,
+		createTooltip,
+		showTooltip,
+		hideTooltip,
 	} from '../../utils/scene3d'
 
 	function hexToNum(hex: string): number {
@@ -175,7 +179,11 @@ const chartId = `scene3d-${id || Math.random().toString(36).slice(2, 9)}`
 			let scene: THREE.Scene
 			let camera: THREE.PerspectiveCamera
 			let renderer: THREE.WebGLRenderer
-			let controls: any
+			let controls: OrbitControls
+			let pointsGroup: THREE.Group
+			let raycaster: THREE.Raycaster
+			let mouse: THREE.Vector2
+			let hoveredMesh: THREE.Mesh | null = null
 
 			function toWorld(v: { x: number; y: number; z: number }): THREE.Vector3 {
 				return new THREE.Vector3((v.x / axisRange) * CUBE, (v.y / axisRange) * CUBE, (v.z / axisRange) * CUBE)
@@ -212,7 +220,8 @@ const chartId = `scene3d-${id || Math.random().toString(36).slice(2, 9)}`
 				rawPoints.forEach((p: any) => {
 					const color = p.color ? hexToNum(p.color) : 0x3b82f6
 					const pos = toWorld(p.position)
-					renderPoint(scene, pos, color, p.size || 8, p.opacity ?? 1)
+					const mesh = renderPoint(scene, pos, color, p.size || 8, p.opacity ?? 1)
+					mesh.userData = { index: rawPoints.indexOf(p), originalColor: new THREE.Color(color), data: p }
 					if (p.label) {
 						scene.add(
 							makeLabel(p.label, pos.clone().add(new THREE.Vector3(0, 0.15, 0)), color, 0.2, 0.08, 22),
@@ -220,6 +229,14 @@ const chartId = `scene3d-${id || Math.random().toString(36).slice(2, 9)}`
 					}
 				})
 
+				pointsGroup = new THREE.Group()
+				scene.children.forEach((child) => {
+					if (child instanceof THREE.Mesh && child.geometry instanceof THREE.SphereGeometry) {
+						pointsGroup.add(child)
+					}
+				})
+				scene.add(pointsGroup)
+
 				rawVectors.forEach((v: any) => {
 					const color = v.color ? hexToNum(v.color) : 0x22c55e
 					const origin = v.origin ? toWorld(v.origin) : new THREE.Vector3(0, 0, 0)
@@ -255,6 +272,73 @@ const chartId = `scene3d-${id || Math.random().toString(36).slice(2, 9)}`
 
 				setupZoomControls(wrapper as HTMLElement, camera, controls, DEFAULT_EYE, CENTER)
 
+				const tooltip = createTooltip(container)
+
+				raycaster = new THREE.Raycaster()
+				raycaster.params.Points = { threshold: 0.02 }
+				mouse = new THREE.Vector2()
+
+				renderer.domElement.addEventListener('mousemove', (e: MouseEvent) => {
+					const rect = renderer.domElement.getBoundingClientRect()
+					mouse.x = ((e.clientX - rect.left) / rect.width) * 2 - 1
+					mouse.y = -((e.clientY - rect.top) / rect.height) * 2 + 1
+
+					raycaster.setFromCamera(mouse, camera)
+					const hits = raycaster.intersectObjects(pointsGroup.children, false)
+
+					if (hoveredMesh && (!hits.length || hits[0].object !== hoveredMesh)) {
+						;(hoveredMesh.material as THREE.MeshStandardMaterial).color.copy(
+							hoveredMesh.userData.originalColor,
+						)
+						;(hoveredMesh.material as THREE.MeshStandardMaterial).emissive.set(0x000000)
+						hoveredMesh = null
+						hideTooltip(tooltip)
+					}
+
+					renderer.domElement.style.cursor = hits.length ? 'pointer' : 'grab'
+
+					if (hits.length) {
+						const mesh = hits[0].object as THREE.Mesh
+						if (mesh !== hoveredMesh) {
+							hoveredMesh = mesh
+							;(mesh.material as THREE.MeshStandardMaterial).color.set(0xffffff)
+							;(mesh.material as THREE.MeshStandardMaterial).emissive.set(0x444444)
+						}
+						const d = mesh.userData.data
+						const lbl = d.label ? `<strong>${d.label}</strong><br/>` : ''
+						showTooltip(
+							tooltip,
+							e.offsetX,
+							e.offsetY,
+							`${lbl}x: ${d.position.x.toFixed(2)}<br/>y: ${d.position.y.toFixed(2)}<br/>z: ${d.position.z.toFixed(2)}`,
+							container.getBoundingClientRect(),
+						)
+					}
+				})
+
+				renderer.domElement.addEventListener('click', (e: MouseEvent) => {
+					const rect = renderer.domElement.getBoundingClientRect()
+					mouse.x = ((e.clientX - rect.left) / rect.width) * 2 - 1
+					mouse.y = -((e.clientY - rect.top) / rect.height) * 2 + 1
+					raycaster.setFromCamera(mouse, camera)
+					const hits = raycaster.intersectObjects(pointsGroup.children, false)
+					if (hits.length) {
+						const d = (hits[0].object as THREE.Mesh).userData.data
+						container.dispatchEvent(
+							new CustomEvent('chart:click', {
+								bubbles: true,
+								detail: {
+									type: 'scene3d',
+									x: d.position.x,
+									y: d.position.y,
+									z: d.position.z,
+									label: d.label,
+								},
+							}),
+						)
+					}
+				})
+
 				let rafId: number
 				function animate() {
 					rafId = requestAnimationFrame(animate)
diff --git a/src/utils/scene3d.ts b/src/utils/scene3d.ts
index 3b931a6..10ba1b2 100644
--- a/src/utils/scene3d.ts
+++ b/src/utils/scene3d.ts
@@ -416,3 +416,49 @@ export function createControlsHTML(): string {
 		</button>
 	</div>`
 }
+
+export function createTooltip(container: HTMLElement): HTMLElement {
+	const tooltip = document.createElement('div')
+	tooltip.className = 'chart-tooltip'
+	tooltip.style.cssText = `
+		position: absolute;
+		pointer-events: none;
+		background: oklch(0.15 0 0);
+		color: oklch(0.95 0 0);
+		padding: 8px 12px;
+		border-radius: 6px;
+		font-size: 13px;
+		font-weight: 500;
+		opacity: 0;
+		transition: opacity 0.15s ease;
+		box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+		z-index: 9999;
+		white-space: nowrap;
+	`
+	container.style.position = 'relative'
+	container.appendChild(tooltip)
+	return tooltip
+}
+
+export function showTooltip(tooltip: HTMLElement, x: number, y: number, content: string, containerRect: DOMRect) {
+	tooltip.innerHTML = content
+	tooltip.style.opacity = '1'
+
+	const tooltipRect = tooltip.getBoundingClientRect()
+	let left = x + 12
+	let top = y - 12
+
+	if (left + tooltipRect.width > containerRect.width) {
+		left = x - tooltipRect.width - 12
+	}
+	if (top < 0) {
+		top = y + 12
+	}
+
+	tooltip.style.left = `${left}px`
+	tooltip.style.top = `${top}px`
+}
+
+export function hideTooltip(tooltip: HTMLElement) {
+	tooltip.style.opacity = '0'
+}