feat: group spatial clustering with box clouds, cluster force, and strength slider

- Add custom cluster force (centroid-pull) registered on first engine tick
- Change cloud geometry from SphereGeometry to BoxGeometry with EdgesGeometry wireframe
- Add clusterStrength config (default 0.3) with slider in Settings > Grouping
- Fix label aspect ratio (0.1875 matching 512x96 canvas)
- Extract createClusterForce to lib/cluster-force.ts with 5 unit tests
- Add e2e test for cluster strength slider

Author: bntvllnt

components/graph-canvas.tsx

@@ -33,6 +33,7 @@ import {
   getModuleColor,
 } from "@/lib/views";
 import { cloudGroup } from "@/src/cloud-group";
+import { createClusterForce } from "@/lib/cluster-force";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const ForceGraph3D = dynamic(() => import("react-force-graph-3d") as any, {
@@ -155,6 +156,17 @@ export function GraphCanvas({
     fg.d3ReheatSimulation();
   }, [config.charge, config.distance]);
 
+  // Cluster force — update strength when slider changes (registration happens in handleEngineTick)
+  useEffect(() => {
+    const fg = fgRef.current;
+    if (!fg) return;
+    const cluster = fg.d3Force("cluster");
+    if (cluster && typeof cluster.strength === "function") {
+      cluster.strength(config.clusterStrength);
+      fg.d3ReheatSimulation();
+    }
+  }, [config.clusterStrength]);
+
   // Module clouds — stable tick handler using refs
   const clearClouds = useCallback((fg: ForceGraph3DInstance) => {
     if (cloudsRef.current.size === 0) return;
@@ -181,6 +193,20 @@ export function GraphCanvas({
     if (!fg) return;
     const cfg = configRef.current;
 
+    // Register cluster force on first tick (fgRef is guaranteed live here)
+    if (!fg.d3Force("cluster")) {
+      const cluster = createClusterForce(
+        (node) => {
+          const mod = (node.module as string | undefined)?.startsWith(".worktrees/")
+            ? undefined
+            : (node.module as string) || undefined;
+          return mod ? cloudGroup(mod) : undefined;
+        },
+        cfg.clusterStrength,
+      );
+      fg.d3Force("cluster", cluster);
+    }
+
     if (!cfg.showModuleBoxes) {
       if (cloudsRef.current.size > 0) clearClouds(fg);
       if (containerRef.current) containerRef.current.dataset.cloudCount = "0";
@@ -250,12 +276,12 @@ export function GraphCanvas({
           existing.label.position.set(cx, maxY + pad + 8, cz);
           existing.label.material.opacity = zoomFade;
           const labelScale = Math.max(rx, ry, rz) * 1.2;
-          existing.label.scale.set(labelScale, labelScale * 0.15, 1);
+          existing.label.scale.set(labelScale, labelScale * 0.1875, 1);
         } else {
           const color = getModuleColor(mod);
 
           // Solid cloud with Phong shading — responds to scene lights
-          const geo = new THREE.SphereGeometry(2, 24, 16);
+          const geo = new THREE.BoxGeometry(2, 2, 2);
           const mat = new THREE.MeshPhongMaterial({
             color,
             transparent: true,
@@ -272,16 +298,15 @@ export function GraphCanvas({
           mesh.renderOrder = -1;
           scene.add(mesh);
 
-          // Wireframe overlay for 3D depth cues
-          const wireGeo = new THREE.SphereGeometry(2, 12, 8);
+          // Wireframe overlay for 3D depth cues — EdgesGeometry for clean 12-edge box outline
           const wireMat = new THREE.LineBasicMaterial({
             color,
             transparent: true,
             opacity: baseOpacity * 0.5,
             depthWrite: false,
           });
           const wireframe = new THREE.LineSegments(
-            new THREE.WireframeGeometry(wireGeo),
+            new THREE.EdgesGeometry(geo),
             wireMat,
           );
           wireframe.position.set(cx, cy, cz);
@@ -308,7 +333,7 @@ export function GraphCanvas({
           const spriteMat = new THREE.SpriteMaterial({ map: texture, transparent: true, depthWrite: false, opacity: zoomFade });
           const label = new THREE.Sprite(spriteMat);
           const labelScale = Math.max(rx, ry, rz) * 1.2;
-          label.scale.set(labelScale, labelScale * 0.15, 1);
+          label.scale.set(labelScale, labelScale * 0.1875, 1);
           label.position.set(cx, maxY + pad + 8, cz);
           scene.add(label);
 

components/settings-panel.tsx

@@ -78,6 +78,7 @@ export function SettingsPanel({
         <span className="text-[#e0e0e0]">Module Clouds</span>
       </label>
       <Slider label="Cloud Opacity" value={config.boxOpacity} min={0.05} max={0.8} step={0.05} format={(v) => v.toFixed(2)} onChange={(v) => { onChange("boxOpacity", v); }} />
+      <Slider label="Cluster Strength" value={config.clusterStrength} min={0} max={1} step={0.05} format={(v) => v.toFixed(2)} onChange={(v) => { onChange("clusterStrength", v); }} />
 
       <div className="text-[10px] text-[#2563eb] uppercase mt-4 mb-2 tracking-wider">Physics</div>
       <Slider label="Repulsion" value={config.charge} min={-200} max={-5} step={5} format={(v) => String(Math.round(v))} onChange={(v) => { onChange("charge", v); }} />

e2e/groups.spec.ts

@@ -101,6 +101,22 @@ test.describe("Group Selection", () => {
     expect(attrs).toEqual(expect.arrayContaining(["services", "models", "utils", "src", "types"]));
   });
 
+  test("cluster strength slider exists and is adjustable", async ({ page }) => {
+    const slider = page.locator("input[type='range']").last();
+    await expect(slider).toBeVisible();
+
+    // The settings panel should show "Cluster Strength" label
+    await expect(page.getByText("Cluster Strength")).toBeVisible();
+
+    // Adjust the slider value
+    await slider.fill("0.8");
+    await expect(slider).toHaveValue("0.8");
+
+    // Set to 0 (off)
+    await slider.fill("0");
+    await expect(slider).toHaveValue("0");
+  });
+
   test("groups only visible when Module Clouds checkbox is checked", async ({ page }) => {
     // Groups should be visible initially (checkbox is checked by default)
     await expect(page.getByText("Groups", { exact: false })).toBeVisible();

lib/cluster-force.ts

@@ -0,0 +1,60 @@
+export interface ClusterForce {
+  (alpha: number): void;
+  initialize: (nodes: Array<Record<string, unknown>>) => void;
+  strength: (s: number) => ClusterForce;
+}
+
+export function createClusterForce(
+  getClusterId: (node: Record<string, unknown>) => string | undefined,
+  strength: number,
+): ClusterForce {
+  let nodes: Array<Record<string, unknown>> = [];
+  let currentStrength = strength;
+
+  function force(alpha: number): void {
+    if (currentStrength === 0) return;
+    const centroids = new Map<string, { x: number; y: number; z: number; count: number }>();
+    for (const node of nodes) {
+      if (node.x === undefined) continue;
+      const id = getClusterId(node);
+      if (!id) continue;
+      const c = centroids.get(id) ?? { x: 0, y: 0, z: 0, count: 0 };
+      c.x += node.x as number;
+      c.y += node.y as number;
+      c.z += node.z as number;
+      c.count++;
+      centroids.set(id, c);
+    }
+    for (const c of centroids.values()) {
+      c.x /= c.count;
+      c.y /= c.count;
+      c.z /= c.count;
+    }
+    const k = currentStrength * alpha;
+    for (const node of nodes) {
+      if (node.x === undefined) continue;
+      const id = getClusterId(node);
+      if (!id) continue;
+      const c = centroids.get(id);
+      if (!c || c.count < 2) continue;
+      const dx = c.x - (node.x as number);
+      const dy = c.y - (node.y as number);
+      const dz = c.z - (node.z as number);
+      if (dx * dx + dy * dy + dz * dz < 25) continue;
+      node.vx = ((node.vx as number) || 0) + dx * k;
+      node.vy = ((node.vy as number) || 0) + dy * k;
+      node.vz = ((node.vz as number) || 0) + dz * k;
+    }
+  }
+
+  force.initialize = function (n: Array<Record<string, unknown>>): void {
+    nodes = n;
+  };
+
+  force.strength = function (s: number): ClusterForce {
+    currentStrength = s;
+    return force;
+  };
+
+  return force;
+}

lib/types.ts

@@ -127,6 +127,7 @@ export interface GraphConfig {
   distance: number;
   showModuleBoxes: boolean;
   boxOpacity: number;
+  clusterStrength: number;
 }
 
 export const DEFAULT_CONFIG: GraphConfig = {
@@ -140,6 +141,7 @@ export const DEFAULT_CONFIG: GraphConfig = {
   distance: 120,
   showModuleBoxes: true,
   boxOpacity: 0.4,
+  clusterStrength: 0.3,
 };
 
 export interface RenderNode {