coderaph 0.1.0

package/src/web/app.js

@@ -0,0 +1,790 @@
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import { LineSegments2 } from 'three/addons/lines/LineSegments2.js';
+import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
+import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
+import { ConvexGeometry } from 'three/addons/geometries/ConvexGeometry.js';
+import { ForceGraph } from './graph.js';
+
+// ── State ──────────────────────────────────────────────────────────
+let scene, camera, renderer, controls;
+let graphData = null;
+let forceGraph = null;
+let nodeMeshes = new Map();
+let edgeGeometry = null;
+let edgeLine = null;
+let currentMode = 'file';
+let currentDimension = '3d';
+const raycaster = new THREE.Raycaster();
+const mouse = new THREE.Vector2();
+let hoveredNode = null;
+let selectedNode = null;
+let isDragging = false;
+const dragPlane = new THREE.Plane();
+
+// Labels
+let labelElements = new Map(); // id → HTMLElement
+let labelsVisible = true;
+let currentLabelFontSize = 10;
+
+// Shared geometry
+let sharedSphereGeometry = new THREE.SphereGeometry(1, 16, 16);
+let currentNodeScale = 1.0;
+
+// Color map for symbol / file kinds
+const KIND_COLORS = {
+  class: 0x4488ff,
+  function: 0x44cc66,
+  interface: 0xaa66cc,
+  type: 0xff8844,
+  enum: 0xee4444,
+  variable: 0x888888,
+  file: 0x4488ff,
+};
+
+// Theme colors
+const THEME = {
+  dark: { bg: 0x0a0a0a, edgeDim: 0x333333, edgeBright: 0x666666, edgeFilter: 0x111111 },
+  light: { bg: 0xf0f0f0, edgeDim: 0x999999, edgeBright: 0xcccccc, edgeFilter: 0xdddddd },
+};
+let currentTheme = 'dark';
+
+// Node visibility (for filter)
+let currentVisibleIds = null; // null = all visible, Set<string> = only these
+
+// Arrows
+let arrowMesh = null; // InstancedMesh
+let showArrows = false;
+let currentArrowScale = 1.0;
+const arrowDummy = new THREE.Object3D();
+const arrowUp = new THREE.Vector3(0, 1, 0);
+
+// Grouping (multi-group)
+let groupHulls = []; // {mesh, nodeIds, color}[]
+let activeGroups = []; // [{query, color}]
+
+// Tooltip
+const tooltip = document.getElementById('tooltip');
+const labelsContainer = document.getElementById('labels-container');
+
+// ── Initialisation ─────────────────────────────────────────────────
+
+function init() {
+  scene = new THREE.Scene();
+  scene.background = new THREE.Color(THEME[currentTheme].bg);
+
+  camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.1, 10000);
+  camera.position.set(0, 0, 150);
+
+  const canvas = document.getElementById('canvas');
+  renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
+  renderer.setSize(window.innerWidth, window.innerHeight);
+  renderer.setPixelRatio(window.devicePixelRatio);
+
+  controls = new OrbitControls(camera, renderer.domElement);
+  controls.enableDamping = true;
+
+  controls.addEventListener('start', () => {
+    const dir = new THREE.Vector3();
+    camera.getWorldDirection(dir);
+    const dist = camera.position.distanceTo(controls.target);
+    controls.target.copy(camera.position).addScaledVector(dir, dist);
+  });
+
+  const ambient = new THREE.AmbientLight(0xffffff, 0.6);
+  scene.add(ambient);
+  const directional = new THREE.DirectionalLight(0xffffff, 0.8);
+  directional.position.set(50, 50, 50);
+  scene.add(directional);
+
+  window.addEventListener('resize', onResize);
+  canvas.addEventListener('pointermove', onPointerMove);
+  canvas.addEventListener('pointerdown', onPointerDown);
+  canvas.addEventListener('pointerup', onPointerUp);
+  canvas.addEventListener('click', onClick);
+  canvas.addEventListener('dblclick', onDblClick);
+}
+
+function onResize() {
+  camera.aspect = window.innerWidth / window.innerHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(window.innerWidth, window.innerHeight);
+  if (edgeLine) {
+    edgeLine.material.resolution.set(window.innerWidth, window.innerHeight);
+  }
+}
+
+// ── Data loading ───────────────────────────────────────────────────
+
+async function loadData() {
+  const res = await fetch('/api/graph');
+  graphData = await res.json();
+  buildScene(currentMode);
+  document.getElementById('canvas').dispatchEvent(new CustomEvent('graph-ready'));
+}
+
+// ── Scene construction ─────────────────────────────────────────────
+
+function buildScene(mode) {
+  for (const mesh of nodeMeshes.values()) {
+    scene.remove(mesh);
+    mesh.material.dispose();
+  }
+  nodeMeshes.clear();
+
+  if (edgeLine) {
+    scene.remove(edgeLine);
+    edgeGeometry.dispose();
+    edgeLine.material.dispose();
+    edgeLine = null;
+    edgeGeometry = null;
+  }
+
+  clearLabels();
+
+  let nodes, edges;
+  if (mode === 'file') {
+    nodes = graphData.files;
+    edges = graphData.fileEdges;
+  } else {
+    nodes = graphData.symbols;
+    edges = graphData.symbolEdges;
+  }
+
+  forceGraph = new ForceGraph(nodes, edges, currentDimension === '2d');
+
+  for (const node of nodes) {
+    const kind = node.kind || 'file';
+    const color = KIND_COLORS[kind] ?? KIND_COLORS.file;
+    const material = new THREE.MeshStandardMaterial({ color });
+    const mesh = new THREE.Mesh(sharedSphereGeometry, material);
+    mesh.scale.setScalar(currentNodeScale);
+    mesh.position.set(node.x, node.y, node.z);
+    mesh.userData.nodeId = node.id;
+    scene.add(mesh);
+    nodeMeshes.set(node.id, mesh);
+    createLabel(node);
+  }
+
+  // Build positions and colors arrays for LineSegments2
+  const posArr = new Float32Array(edges.length * 6); // 2 points × 3 components per segment
+  const colArr = new Float32Array(edges.length * 6);
+  const dimColor = new THREE.Color(THEME[currentTheme].edgeDim);
+  const brightColor = new THREE.Color(THEME[currentTheme].edgeBright);
+
+  for (let i = 0; i < edges.length; i++) {
+    const edge = edges[i];
+    const srcNode = forceGraph.nodeMap.get(edge.source);
+    const tgtNode = forceGraph.nodeMap.get(edge.target);
+    const base = i * 6;
+    if (srcNode && tgtNode) {
+      posArr[base] = srcNode.x; posArr[base + 1] = srcNode.y; posArr[base + 2] = srcNode.z;
+      posArr[base + 3] = tgtNode.x; posArr[base + 4] = tgtNode.y; posArr[base + 5] = tgtNode.z;
+    }
+    colArr[base] = dimColor.r; colArr[base + 1] = dimColor.g; colArr[base + 2] = dimColor.b;
+    colArr[base + 3] = brightColor.r; colArr[base + 4] = brightColor.g; colArr[base + 5] = brightColor.b;
+  }
+
+  edgeGeometry = new LineSegmentsGeometry();
+  edgeGeometry.setPositions(posArr);
+  edgeGeometry.setColors(colArr);
+
+  const edgeMaterial = new LineMaterial({
+    vertexColors: true,
+    transparent: true,
+    opacity: 0.4,
+    linewidth: 1,
+    resolution: new THREE.Vector2(window.innerWidth, window.innerHeight),
+  });
+  edgeLine = new LineSegments2(edgeGeometry, edgeMaterial);
+  scene.add(edgeLine);
+
+  // Arrows
+  if (arrowMesh) { scene.remove(arrowMesh); arrowMesh.geometry.dispose(); arrowMesh.material.dispose(); arrowMesh = null; }
+  const arrowGeo = new THREE.ConeGeometry(0.4, 1.2, 6);
+  const arrowMat = new THREE.MeshBasicMaterial({ color: THEME[currentTheme].edgeBright, transparent: true, opacity: 0.6 });
+  arrowMesh = new THREE.InstancedMesh(arrowGeo, arrowMat, edges.length);
+  arrowMesh.visible = showArrows;
+  scene.add(arrowMesh);
+
+  buildGroupHulls();
+}
+
+// ── Labels ─────────────────────────────────────────────────────────
+
+function createLabel(node) {
+  const el = document.createElement('div');
+  el.className = 'node-label';
+  el.textContent = node.name || node.id.split('/').pop();
+  el.style.display = labelsVisible ? '' : 'none';
+  el.style.fontSize = currentLabelFontSize + 'px';
+  labelsContainer.appendChild(el);
+  labelElements.set(node.id, el);
+}
+
+function clearLabels() {
+  for (const el of labelElements.values()) el.remove();
+  labelElements.clear();
+}
+
+function updateLabelPositions() {
+  if (!labelsVisible) return;
+  const halfW = window.innerWidth / 2;
+  const halfH = window.innerHeight / 2;
+  const vec = new THREE.Vector3();
+
+  for (const [id, el] of labelElements) {
+    const mesh = nodeMeshes.get(id);
+    if (!mesh) continue;
+    // Respect filter visibility
+    if (currentVisibleIds && !currentVisibleIds.has(id)) { el.style.display = 'none'; continue; }
+    vec.copy(mesh.position);
+    vec.project(camera);
+    if (vec.z > 1) { el.style.display = 'none'; continue; }
+    el.style.display = '';
+    el.style.left = ((vec.x * halfW) + halfW) + 'px';
+    el.style.top = (-(vec.y * halfH) + halfH) + 'px';
+  }
+}
+
+// ── Tooltip ────────────────────────────────────────────────────────
+
+function showTooltip(node, event) {
+  const name = node.name || node.id;
+  const kind = node.kind ? node.kind : 'file';
+  const file = node.fileId || node.id;
+
+  tooltip.textContent = '';
+  const strong = document.createElement('strong');
+  strong.textContent = name;
+  tooltip.appendChild(strong);
+  tooltip.appendChild(document.createElement('br'));
+  tooltip.appendChild(document.createTextNode('Kind: ' + kind));
+  tooltip.appendChild(document.createElement('br'));
+  tooltip.appendChild(document.createTextNode('File: ' + file));
+  tooltip.classList.remove('hidden');
+  positionTooltip(event);
+}
+
+function positionTooltip(event) {
+  tooltip.style.left = (event.clientX + 14) + 'px';
+  tooltip.style.top = (event.clientY + 14) + 'px';
+}
+
+function hideTooltip() {
+  tooltip.classList.add('hidden');
+}
+
+// ── Animation loop ─────────────────────────────────────────────────
+
+function animate() {
+  requestAnimationFrame(animate);
+
+  const simRunning = forceGraph && !forceGraph.isStable();
+  if (simRunning) forceGraph.tick();
+
+  if (forceGraph) {
+    for (const node of forceGraph.nodes) {
+      const mesh = nodeMeshes.get(node.id);
+      if (mesh) mesh.position.set(node.x, node.y, node.z);
+    }
+
+    if (edgeGeometry) {
+      const edges = currentMode === 'file' ? graphData.fileEdges : graphData.symbolEdges;
+      const posArr = new Float32Array(edges.length * 6);
+      for (let i = 0; i < edges.length; i++) {
+        const edge = edges[i];
+        const srcNode = forceGraph.nodeMap.get(edge.source);
+        const tgtNode = forceGraph.nodeMap.get(edge.target);
+        if (!srcNode || !tgtNode) continue;
+        // Respect filter visibility
+        if (currentVisibleIds && (!currentVisibleIds.has(edge.source) || !currentVisibleIds.has(edge.target))) continue;
+        const base = i * 6;
+        posArr[base] = srcNode.x; posArr[base + 1] = srcNode.y; posArr[base + 2] = srcNode.z;
+        posArr[base + 3] = tgtNode.x; posArr[base + 4] = tgtNode.y; posArr[base + 5] = tgtNode.z;
+      }
+      edgeGeometry.setPositions(posArr);
+    }
+
+    // Update arrow positions
+    if (arrowMesh && showArrows) {
+      const edges = currentMode === 'file' ? graphData.fileEdges : graphData.symbolEdges;
+      const dir = new THREE.Vector3();
+      for (let i = 0; i < edges.length; i++) {
+        const edge = edges[i];
+        const sn = forceGraph.nodeMap.get(edge.source);
+        const tn = forceGraph.nodeMap.get(edge.target);
+        if (!sn || !tn) { arrowDummy.scale.setScalar(0); arrowDummy.updateMatrix(); arrowMesh.setMatrixAt(i, arrowDummy.matrix); continue; }
+        if (currentVisibleIds && (!currentVisibleIds.has(edge.source) || !currentVisibleIds.has(edge.target))) {
+          arrowDummy.scale.setScalar(0); arrowDummy.updateMatrix(); arrowMesh.setMatrixAt(i, arrowDummy.matrix); continue;
+        }
+        dir.set(tn.x - sn.x, tn.y - sn.y, tn.z - sn.z);
+        const len = dir.length();
+        if (len < 0.01) { arrowDummy.scale.setScalar(0); arrowDummy.updateMatrix(); arrowMesh.setMatrixAt(i, arrowDummy.matrix); continue; }
+        dir.divideScalar(len);
+        const offset = currentNodeScale + 0.8;
+        arrowDummy.position.set(tn.x - dir.x * offset, tn.y - dir.y * offset, tn.z - dir.z * offset);
+        arrowDummy.quaternion.setFromUnitVectors(arrowUp, dir);
+        arrowDummy.scale.setScalar(currentNodeScale * 0.6 * currentArrowScale);
+        arrowDummy.updateMatrix();
+        arrowMesh.setMatrixAt(i, arrowDummy.matrix);
+      }
+      arrowMesh.instanceMatrix.needsUpdate = true;
+    }
+  }
+
+  if (simRunning && groupHulls.length > 0) updateGroupHulls();
+
+  updateLabelPositions();
+  controls.update();
+  renderer.render(scene, camera);
+}
+
+// ── Mouse interaction ──────────────────────────────────────────────
+
+function getIntersectedMesh(event) {
+  mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
+  mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
+  raycaster.setFromCamera(mouse, camera);
+  const meshes = Array.from(nodeMeshes.values());
+  const hits = raycaster.intersectObjects(meshes);
+  return hits.length > 0 ? hits[0].object : null;
+}
+
+function findNodeData(nodeId) {
+  if (!graphData) return null;
+  if (currentMode === 'file') return graphData.files.find(f => f.id === nodeId);
+  return graphData.symbols.find(s => s.id === nodeId);
+}
+
+function onPointerMove(event) {
+  if (isDragging && hoveredNode) {
+    mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
+    mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
+    raycaster.setFromCamera(mouse, camera);
+    const intersection = new THREE.Vector3();
+    if (raycaster.ray.intersectPlane(dragPlane, intersection)) {
+      const nodeId = hoveredNode.userData.nodeId;
+      const node = forceGraph.nodeMap.get(nodeId);
+      if (node) {
+        node.x = intersection.x; node.y = intersection.y; node.z = intersection.z;
+        forceGraph.pinNode(nodeId, intersection.x, intersection.y, intersection.z);
+      }
+    }
+    positionTooltip(event);
+    return;
+  }
+
+  const mesh = getIntersectedMesh(event);
+  if (hoveredNode && hoveredNode !== mesh) hoveredNode.material.emissive.setHex(0x000000);
+
+  if (mesh) {
+    renderer.domElement.style.cursor = 'pointer';
+    mesh.material.emissive.setHex(0x222222);
+    hoveredNode = mesh;
+    const nodeData = findNodeData(mesh.userData.nodeId);
+    if (nodeData) showTooltip(nodeData, event);
+  } else {
+    renderer.domElement.style.cursor = 'default';
+    hoveredNode = null;
+    hideTooltip();
+  }
+}
+
+function onPointerDown(event) {
+  if (!hoveredNode) return;
+  isDragging = true;
+  controls.enabled = false;
+  const nodeId = hoveredNode.userData.nodeId;
+  const node = forceGraph.nodeMap.get(nodeId);
+  if (node) forceGraph.pinNode(nodeId, node.x, node.y, node.z);
+  const cameraDir = new THREE.Vector3();
+  camera.getWorldDirection(cameraDir);
+  dragPlane.setFromNormalAndCoplanarPoint(cameraDir, hoveredNode.position);
+}
+
+function onPointerUp() {
+  if (!isDragging) return;
+  isDragging = false;
+  controls.enabled = true;
+  if (hoveredNode) {
+    forceGraph.unpinNode(hoveredNode.userData.nodeId);
+    forceGraph.reheat();
+  }
+}
+
+function onClick(event) {
+  if (isDragging) return;
+  const mesh = getIntersectedMesh(event);
+  if (mesh) {
+    selectedNode = mesh;
+    const nodeId = mesh.userData.nodeId;
+    highlightConnected(nodeId);
+    renderer.domElement.dispatchEvent(new CustomEvent('node-click', { detail: { nodeId } }));
+  } else {
+    clearConnectedHighlight();
+    renderer.domElement.dispatchEvent(new CustomEvent('node-deselect'));
+  }
+}
+
+function onDblClick(event) {
+  const mesh = getIntersectedMesh(event);
+  if (mesh) {
+    renderer.domElement.dispatchEvent(
+      new CustomEvent('node-dblclick', { detail: { nodeId: mesh.userData.nodeId } }),
+    );
+  }
+}
+
+// ── Edge color helpers ─────────────────────────────────────────────
+
+function updateEdgeColors(visibleSet) {
+  if (!edgeLine || !edgeGeometry) return;
+  const edges = getCurrentEdges();
+  const colArr = new Float32Array(edges.length * 6);
+  const dimColor = new THREE.Color(visibleSet ? THEME[currentTheme].edgeFilter : THEME[currentTheme].edgeDim);
+  const srcColor = new THREE.Color(THEME[currentTheme].edgeDim);
+  const tgtColor = new THREE.Color(THEME[currentTheme].edgeBright);
+  for (let i = 0; i < edges.length; i++) {
+    const edge = edges[i];
+    const visible = !visibleSet || (visibleSet.has(edge.source) && visibleSet.has(edge.target));
+    const base = i * 6;
+    const s = visible ? srcColor : dimColor;
+    const t = visible ? tgtColor : dimColor;
+    colArr[base] = s.r; colArr[base + 1] = s.g; colArr[base + 2] = s.b;
+    colArr[base + 3] = t.r; colArr[base + 4] = t.g; colArr[base + 5] = t.b;
+  }
+  edgeGeometry.setColors(colArr);
+}
+
+// ── Connected node highlight (click) ───────────────────────────────
+
+let connectedHighlightActive = false;
+
+function highlightConnected(nodeId) {
+  const edges = getCurrentEdges();
+  const connected = new Set([nodeId]);
+  for (const edge of edges) {
+    if (edge.source === nodeId) connected.add(edge.target);
+    if (edge.target === nodeId) connected.add(edge.source);
+  }
+
+  for (const [id, mesh] of nodeMeshes) {
+    if (connected.has(id)) {
+      mesh.material.opacity = 1.0;
+      mesh.material.transparent = false;
+      mesh.material.emissive.setHex(id === nodeId ? 0x444444 : 0x222222);
+    } else {
+      mesh.material.opacity = 0.08;
+      mesh.material.transparent = true;
+      mesh.material.emissive.setHex(0x000000);
+    }
+  }
+
+  updateEdgeColors(connected);
+
+  for (const [id, el] of labelElements) {
+    el.style.opacity = connected.has(id) ? '1' : '0.1';
+  }
+  connectedHighlightActive = true;
+}
+
+function clearConnectedHighlight() {
+  if (!connectedHighlightActive) return;
+  for (const mesh of nodeMeshes.values()) {
+    mesh.material.opacity = 1.0;
+    mesh.material.transparent = false;
+    mesh.material.emissive.setHex(0x000000);
+  }
+  updateEdgeColors(null);
+  for (const el of labelElements.values()) el.style.opacity = '1';
+  connectedHighlightActive = false;
+}
+
+// ── Exports for controls.js ────────────────────────────────────────
+
+export function switchMode(mode) { currentMode = mode; buildScene(mode); }
+export function getGraphData() { return graphData; }
+export function getCurrentEdges() {
+  if (!graphData) return [];
+  return currentMode === 'file' ? graphData.fileEdges : graphData.symbolEdges;
+}
+export function getNodeMeshes() { return nodeMeshes; }
+
+export function focusNode(nodeId) {
+  const mesh = nodeMeshes.get(nodeId);
+  if (!mesh) return;
+  const target = mesh.position.clone();
+  controls.target.copy(target);
+  camera.position.copy(target.clone().add(new THREE.Vector3(0, 0, 80)));
+  controls.update();
+}
+
+export function highlightNodes(nodeIds, focusedId) {
+  const idSet = nodeIds instanceof Set ? nodeIds : new Set(nodeIds);
+  for (const [id, mesh] of nodeMeshes) {
+    if (id === focusedId) mesh.material.emissive.setHex(0x666666);
+    else if (idSet.has(id)) mesh.material.emissive.setHex(0x444444);
+  }
+}
+
+export function clearHighlights() {
+  for (const mesh of nodeMeshes.values()) mesh.material.emissive.setHex(0x000000);
+}
+
+export function setFilteredView(visibleNodeIds) {
+  const idSet = visibleNodeIds instanceof Set ? visibleNodeIds : new Set(visibleNodeIds);
+  for (const [id, mesh] of nodeMeshes) {
+    mesh.material.opacity = idSet.has(id) ? 1.0 : 0.05;
+    mesh.material.transparent = true;
+  }
+  updateEdgeColors(idSet);
+  for (const [id, el] of labelElements) el.style.opacity = idSet.has(id) ? '1' : '0.05';
+}
+
+export function clearFilter() {
+  for (const mesh of nodeMeshes.values()) {
+    mesh.material.opacity = 1.0;
+    mesh.material.transparent = false;
+  }
+  updateEdgeColors(null);
+  for (const el of labelElements.values()) el.style.opacity = '1';
+}
+
+// ── Settings API ───────────────────────────────────────────────────
+
+// ── Grouping ────────────────────────────────────────────────────────
+
+function matchGroupQuery(query, node) {
+  if (!query) return false;
+  const q = query.trim().toLowerCase();
+  if (q.startsWith('path:')) {
+    const val = q.slice(5);
+    const path = (node.fileId || node.id).toLowerCase();
+    return path.includes(val);
+  }
+  if (q.startsWith('file:')) {
+    const val = q.slice(5);
+    const fileName = (node.fileId || node.id).split('/').pop().toLowerCase();
+    return fileName.includes(val);
+  }
+  if (q.startsWith('kind:')) {
+    const val = q.slice(5);
+    return (node.kind || 'file').toLowerCase() === val;
+  }
+  // Plain text: match name, id, fileId
+  const name = (node.name || '').toLowerCase();
+  const id = node.id.toLowerCase();
+  const file = (node.fileId || '').toLowerCase();
+  return name.includes(q) || id.includes(q) || file.includes(q);
+}
+
+function computeGroupNodeIds(query) {
+  if (!graphData || !query.trim()) return [];
+  const nodes = currentMode === 'file' ? graphData.files : graphData.symbols;
+  const ids = [];
+  for (const node of nodes) {
+    if (matchGroupQuery(query, node)) ids.push(node.id);
+  }
+  return ids;
+}
+
+function padHullPoints(points) {
+  // ConvexGeometry needs at least 4 non-coplanar points
+  if (points.length === 0) return points;
+  const centroid = new THREE.Vector3();
+  for (const p of points) centroid.add(p);
+  centroid.divideScalar(points.length);
+  const padded = [...points];
+  const margin = 2;
+  const offsets = [
+    new THREE.Vector3(margin, 0, 0), new THREE.Vector3(0, margin, 0),
+    new THREE.Vector3(0, 0, margin), new THREE.Vector3(-margin, -margin, -margin),
+  ];
+  let idx = 0;
+  while (padded.length < 4) {
+    padded.push(centroid.clone().add(offsets[idx % offsets.length]));
+    idx++;
+  }
+  // Ensure non-coplanar in 2D mode
+  if (currentDimension === '2d') {
+    for (const p of padded) p.z += (Math.random() - 0.5) * 0.5;
+  }
+  return padded;
+}
+
+function clearGroupHulls() {
+  for (const h of groupHulls) {
+    scene.remove(h.mesh);
+    h.mesh.geometry.dispose();
+    h.mesh.material.dispose();
+  }
+  groupHulls = [];
+}
+
+function buildGroupHulls() {
+  clearGroupHulls();
+  if (!forceGraph || activeGroups.length === 0) return;
+
+  for (const group of activeGroups) {
+    const nodeIds = computeGroupNodeIds(group.query);
+    if (nodeIds.length === 0) continue;
+
+    const rawPoints = nodeIds.map(id => {
+      const n = forceGraph.nodeMap.get(id);
+      return new THREE.Vector3(n.x, n.y, n.z);
+    });
+    const points = padHullPoints(rawPoints);
+
+    try {
+      const geo = new ConvexGeometry(points);
+      const mat = new THREE.MeshBasicMaterial({
+        color: group.color, transparent: true, opacity: 0.08, side: THREE.DoubleSide, depthWrite: false,
+      });
+      const mesh = new THREE.Mesh(geo, mat);
+      scene.add(mesh);
+      groupHulls.push({ mesh, nodeIds, query: group.query, color: group.color });
+    } catch { /* degenerate hull, skip */ }
+  }
+}
+
+function updateGroupHulls() {
+  if (groupHulls.length === 0 || !forceGraph) return;
+
+  for (const h of groupHulls) {
+    const rawPoints = h.nodeIds.map(id => {
+      const n = forceGraph.nodeMap.get(id);
+      return new THREE.Vector3(n.x, n.y, n.z);
+    });
+    const points = padHullPoints(rawPoints);
+
+    try {
+      const oldGeo = h.mesh.geometry;
+      h.mesh.geometry = new ConvexGeometry(points);
+      oldGeo.dispose();
+    } catch { /* degenerate, keep old */ }
+  }
+}
+
+export function setGroups(groups) {
+  activeGroups = groups; // [{query, color}]
+  buildGroupHulls();
+}
+
+export function setShowArrows(visible) {
+  showArrows = visible;
+  if (arrowMesh) arrowMesh.visible = visible;
+}
+
+export function setDimension(dim) {
+  currentDimension = dim;
+  if (dim === '2d') {
+    if (forceGraph) forceGraph.setIs2D(true);
+    camera.position.set(0, 0, 150);
+    controls.target.set(0, 0, 0);
+    controls.enableRotate = false;
+    controls.mouseButtons = { LEFT: THREE.MOUSE.PAN, MIDDLE: THREE.MOUSE.DOLLY, RIGHT: THREE.MOUSE.PAN };
+  } else {
+    if (forceGraph) forceGraph.setIs2D(false);
+    controls.enableRotate = true;
+    controls.mouseButtons = { LEFT: THREE.MOUSE.ROTATE, MIDDLE: THREE.MOUSE.DOLLY, RIGHT: THREE.MOUSE.PAN };
+  }
+  controls.update();
+}
+
+export function setTheme(theme) {
+  currentTheme = theme;
+  if (scene) scene.background = new THREE.Color(THEME[theme].bg);
+  updateEdgeColors(null);
+}
+
+export function setNodeSize(scale) {
+  currentNodeScale = scale;
+  for (const mesh of nodeMeshes.values()) mesh.scale.setScalar(scale);
+}
+
+export function setEdgeThickness(width) {
+  if (edgeLine) {
+    edgeLine.material.linewidth = width;
+  }
+  currentArrowScale = width;
+}
+
+export function setNodeDistance(distance) {
+  if (forceGraph) {
+    forceGraph.idealDistance = distance;
+    forceGraph.reheat();
+  }
+}
+
+export function setLabelsVisible(visible) {
+  labelsVisible = visible;
+  for (const el of labelElements.values()) el.style.display = visible ? '' : 'none';
+}
+
+export function setLabelFontSize(px) {
+  currentLabelFontSize = px;
+  for (const el of labelElements.values()) el.style.fontSize = px + 'px';
+}
+
+function rebuildFilteredEdges() {
+  if (!edgeLine || !edgeGeometry || !forceGraph) return;
+  const edges = getCurrentEdges();
+  const posArr = new Float32Array(edges.length * 6);
+  const colArr = new Float32Array(edges.length * 6);
+  const dimColor = new THREE.Color(THEME[currentTheme].edgeDim);
+  const brightColor = new THREE.Color(THEME[currentTheme].edgeBright);
+
+  for (let i = 0; i < edges.length; i++) {
+    const edge = edges[i];
+    if (currentVisibleIds && (!currentVisibleIds.has(edge.source) || !currentVisibleIds.has(edge.target))) continue;
+    const srcNode = forceGraph.nodeMap.get(edge.source);
+    const tgtNode = forceGraph.nodeMap.get(edge.target);
+    if (!srcNode || !tgtNode) continue;
+    const base = i * 6;
+    posArr[base] = srcNode.x; posArr[base + 1] = srcNode.y; posArr[base + 2] = srcNode.z;
+    posArr[base + 3] = tgtNode.x; posArr[base + 4] = tgtNode.y; posArr[base + 5] = tgtNode.z;
+    colArr[base] = dimColor.r; colArr[base + 1] = dimColor.g; colArr[base + 2] = dimColor.b;
+    colArr[base + 3] = brightColor.r; colArr[base + 4] = brightColor.g; colArr[base + 5] = brightColor.b;
+  }
+  edgeGeometry.setPositions(posArr);
+  edgeGeometry.setColors(colArr);
+
+  // Also hide arrows for filtered edges
+  if (arrowMesh) {
+    for (let i = 0; i < edges.length; i++) {
+      const edge = edges[i];
+      if (currentVisibleIds && (!currentVisibleIds.has(edge.source) || !currentVisibleIds.has(edge.target))) {
+        arrowDummy.scale.setScalar(0);
+        arrowDummy.updateMatrix();
+        arrowMesh.setMatrixAt(i, arrowDummy.matrix);
+      }
+    }
+    arrowMesh.instanceMatrix.needsUpdate = true;
+  }
+}
+
+export function setNodeVisibility(visibleIds) {
+  currentVisibleIds = visibleIds;
+  for (const [id, mesh] of nodeMeshes) {
+    const vis = !visibleIds || visibleIds.has(id);
+    if (!vis) {
+      scene.remove(mesh);
+    } else if (!mesh.parent) {
+      scene.add(mesh);
+    }
+  }
+  for (const [id, el] of labelElements) {
+    const vis = !visibleIds || visibleIds.has(id);
+    el.style.display = (vis && labelsVisible) ? '' : 'none';
+  }
+  // Rebuild edge geometry with only visible edges
+  rebuildFilteredEdges();
+}
+
+export { clearConnectedHighlight };
+
+// ── Bootstrap ──────────────────────────────────────────────────────
+
+init();
+loadData().then(() => animate());