feat(visualize): 3D orbit graph — rotatable with perspective depth

Upgrade the force-directed graph from 2D to 3D so it can be rotated:
- nodes now carry a z coordinate; physics (repulsion, degree-normalized
  springs, origin pull, annealing, speed cap) all run in 3D
- seed on a golden-angle sphere so 3D structure reads immediately
- per-frame project(): yaw/pitch rotation + perspective projection, with
  near=larger discs and depth fog (far nodes dim/recede)
- draw nodes far→near (painter's algorithm) so nearer ones occlude
- drag the background to orbit (yaw/pitch); scroll still zooms; dragging a
  node moves it in the current view plane via unproject(); pick() is now
  screen-space so hover/click stay accurate at any angle
- hover highlight + flow particles, click→glass panel, legend filter all
  preserved and verified in-browser on the real KB.

Default zoom bumped (scale 1.35) so the sphere fills more of the canvas.

Author: KylinMountain

openkb/templates/graph.html

@@ -158,8 +158,8 @@
 <div class="legend" id="legend"></div>
 
 <div class="hint">
-  <kbd>scroll</kbd> zoom &nbsp; <kbd>drag bg</kbd> pan<br>
-  <kbd>drag node</kbd> pin &nbsp; <kbd>click</kbd> inspect
+  <kbd>scroll</kbd> zoom &nbsp; <kbd>drag bg</kbd> rotate<br>
+  <kbd>drag node</kbd> move &nbsp; <kbd>click</kbd> inspect
 </div>
 
 <div class="panel" id="panel"></div>
@@ -187,9 +187,10 @@
 
 // build working nodes/edges from GRAPH (object-form edges: e.source/e.target)
 const nodes = GRAPH.nodes.map(n => ({
-  ...n, x:0, y:0, vx:0, vy:0,
+  ...n, x:0, y:0, z:0, vx:0, vy:0, vz:0,
   r: 8 + Math.min(10, (n.in || 0) + (n.out || 0)),   // radius scales with degree
-  alpha: 1                                             // per-node fade (legend toggle)
+  alpha: 1,                                            // per-node fade (legend toggle)
+  sx:0, sy:0, rz:0, pp:1                               // per-frame 3D projection cache
 }));
 const byId = Object.fromEntries(nodes.map(n => [n.id, n]));
 const edges = GRAPH.edges.filter(e => byId[e.source] && byId[e.target]);
@@ -211,8 +212,9 @@
 const visible = n => n.alpha > 0.02;      // for physics/picking (fully-faded skipped)
 
 let hover = null, drag = null, selected = null;
-let scale = 1, panX = 0, panY = 0;
-let panning = false, panStartX = 0, panStartY = 0, panOrigX = 0, panOrigY = 0;
+let scale = 1.35, panX = 0, panY = 0;
+let yaw = 0.5, pitch = -0.28;    // 3D orbit angles — drag the background to rotate
+let orbiting = false, oStartX = 0, oStartY = 0, yawStart = 0, pitchStart = 0;
 let didDrag = false;
 let alpha = 1;                   // simulated-annealing "temperature"; cools to 0 so motion stops
 
@@ -225,80 +227,106 @@
   canvas.height = H() * DPR;
 }
 function seed(){
-  const cx = W()/2, cy = H()/2;
+  const R = 250;
   nodes.forEach((n,i) => {
-    const a = i / Math.max(1, nodes.length) * 6.28318;
-    const rad = 150 + Math.random()*60;
-    n.x = cx + Math.cos(a)*rad + (Math.random()-.5)*40;
-    n.y = cy + Math.sin(a)*(rad*0.8) + (Math.random()-.5)*40;
-    n.vx = 0; n.vy = 0;
+    // spread nodes over a sphere (golden-angle spiral) so 3D structure shows from the start
+    const phi = Math.acos(1 - 2*(i+0.5)/Math.max(1,nodes.length));
+    const theta = 2.399963 * i;
+    const rad = R * (0.55 + Math.random()*0.45);
+    n.x = rad*Math.sin(phi)*Math.cos(theta);
+    n.y = rad*Math.sin(phi)*Math.sin(theta);
+    n.z = rad*Math.cos(phi);
+    n.vx = n.vy = n.vz = 0;
   });
 }
 
 /* ===================== physics (adapted from okf-spec.html step()) ===================== */
 const VMAX = 9;   // per-frame speed cap → no violent swings, even on a dense hub
 function step(){
-  const cx = W()/2, cy = H()/2;
   for(let i=0;i<nodes.length;i++){
     const a = nodes[i];
     if(!visible(a)) continue;
     for(let j=i+1;j<nodes.length;j++){
       const b = nodes[j];
       if(!visible(b)) continue;
-      let dx = a.x-b.x, dy = a.y-b.y, d = Math.hypot(dx,dy) || 1;
+      let dx = a.x-b.x, dy = a.y-b.y, dz = a.z-b.z, d = Math.hypot(dx,dy,dz) || 1;
       const dd = Math.max(d, 18);                  // floor distance so near-coincident nodes don't explode
       const f = 2600/(dd*dd) * alpha;
-      a.vx += dx/d*f; a.vy += dy/d*f;
-      b.vx -= dx/d*f; b.vy -= dy/d*f;
+      a.vx += dx/d*f; a.vy += dy/d*f; a.vz += dz/d*f;
+      b.vx -= dx/d*f; b.vy -= dy/d*f; b.vz -= dz/d*f;
     }
-    a.vx += (cx-a.x)*0.0016*alpha; a.vy += (cy-a.y)*0.0016*alpha;
+    a.vx += -a.x*0.0016*alpha; a.vy += -a.y*0.0016*alpha; a.vz += -a.z*0.0016*alpha;   // pull toward origin
   }
   edges.forEach(e => {
     const a = byId[e.source], b = byId[e.target];
     if(!visible(a) || !visible(b)) return;
-    let dx = b.x-a.x, dy = b.y-a.y, d = Math.hypot(dx,dy) || 1;
+    let dx = b.x-a.x, dy = b.y-a.y, dz = b.z-a.z, d = Math.hypot(dx,dy,dz) || 1;
     // normalize the pull by degree: a hub with N springs shouldn't feel N× the force
     const s = 1 / Math.min(adj[e.source].length || 1, adj[e.target].length || 1);
     const f = (d-118)*0.012 * s * alpha;
-    a.vx += dx/d*f; a.vy += dy/d*f;
-    b.vx -= dx/d*f; b.vy -= dy/d*f;
+    a.vx += dx/d*f; a.vy += dy/d*f; a.vz += dz/d*f;
+    b.vx -= dx/d*f; b.vy -= dy/d*f; b.vz -= dz/d*f;
   });
   nodes.forEach(n => {
     // smoothly approach the legend-toggle target opacity
     const target = typeVisible(n.type) ? 1 : 0;
     n.alpha += (target - n.alpha) * 0.12;
-    if(n === drag){ n.vx = n.vy = 0; return; }   // pinned: position set by drag handler
-    n.vx *= 0.84; n.vy *= 0.84;                   // stronger damping dissipates energy fast
+    if(n === drag){ n.vx = n.vy = n.vz = 0; return; }   // pinned: position set by drag handler
+    n.vx *= 0.84; n.vy *= 0.84; n.vz *= 0.84;           // stronger damping dissipates energy fast
     if(n.vx > VMAX) n.vx = VMAX; else if(n.vx < -VMAX) n.vx = -VMAX;
     if(n.vy > VMAX) n.vy = VMAX; else if(n.vy < -VMAX) n.vy = -VMAX;
-    n.x += n.vx; n.y += n.vy;
+    if(n.vz > VMAX) n.vz = VMAX; else if(n.vz < -VMAX) n.vz = -VMAX;
+    n.x += n.vx; n.y += n.vy; n.z += n.vz;
   });
   alpha += (0 - alpha) * 0.02;                    // anneal: forces fade → the layout settles and stops
 }
 
-/* ===================== zoom / pan transform ===================== */
-function applyView(){ ctx.setTransform(DPR*scale, 0, 0, DPR*scale, DPR*panX, DPR*panY); }
-function toWorld(px,py){ return { x:(px-panX)/scale, y:(py-panY)/scale }; }
-function centerOn(n){ panX = W()/2 - n.x*scale; panY = H()/2 - n.y*scale; }
+/* ===================== 3D orbit projection + perspective ===================== */
+const FOCAL = 900;
+function project(){
+  const cyw = Math.cos(yaw), syw = Math.sin(yaw), cpt = Math.cos(pitch), spt = Math.sin(pitch);
+  const ox = W()/2 + panX, oy = H()/2 + panY;
+  for(const n of nodes){
+    const x1 = n.x*cyw + n.z*syw;          // rotate about Y (yaw)
+    const z1 = -n.x*syw + n.z*cyw;
+    const y2 = n.y*cpt - z1*spt;           // then about X (pitch)
+    const z2 = n.y*spt + z1*cpt;
+    const pp = FOCAL/(FOCAL + z2);          // perspective: near → larger
+    n.rz = z2; n.pp = pp;
+    n.sx = ox + x1*pp*scale;
+    n.sy = oy + y2*pp*scale;
+  }
+}
+// inverse of project for one node, holding its current depth — used while dragging
+function unproject(sx, sy, n){
+  const cyw = Math.cos(yaw), syw = Math.sin(yaw), cpt = Math.cos(pitch), spt = Math.sin(pitch);
+  const ox = W()/2 + panX, oy = H()/2 + panY;
+  const pp = n.pp || 1, z2 = n.rz || 0;
+  const x1 = (sx - ox)/(pp*scale);
+  const y2 = (sy - oy)/(pp*scale);
+  const y = y2*cpt + z2*spt;               // invert pitch
+  const z1 = -y2*spt + z2*cpt;
+  return { x: x1*cyw - z1*syw, y, z: x1*syw + z1*cyw };   // invert yaw
+}
+function centerOn(n){ panX += (W()/2 - n.sx); panY += (H()/2 - n.sy); }
 
 canvas.addEventListener("wheel", e => {
   e.preventDefault();
   const f = Math.exp(-e.deltaY * 0.0015);
-  const ns = Math.max(0.25, Math.min(4, scale*f));
-  const k = ns/scale;
-  const mx = e.offsetX, my = e.offsetY;
-  panX = mx - (mx-panX)*k; panY = my - (my-panY)*k;
-  scale = ns;
+  scale = Math.max(0.3, Math.min(4.5, scale*f));   // zoom about the screen centre
 }, {passive:false});
 
 /* ===================== picking ===================== */
-function pick(wx,wy){
-  for(let i=nodes.length-1;i>=0;i--){
-    const n = nodes[i];
+function pick(sx, sy){
+  let best = null, bestDepth = Infinity;
+  for(const n of nodes){
     if(!visible(n)) continue;
-    if(Math.hypot(n.x-wx, n.y-wy) < n.r + 6) return n;
+    const rr = n.r*n.pp*scale + 6;
+    if(Math.hypot(n.sx - sx, n.sy - sy) < rr && n.rz < bestDepth){
+      best = n; bestDepth = n.rz;   // nearest (smallest depth) wins where discs overlap
+    }
   }
-  return null;
+  return best;
 }
 
 /* ===================== rendering ===================== */
@@ -308,16 +336,18 @@
   if(al < 0.02) return;
   const hot = hover && (e.source===hover || e.target===hover);
   const dim = hover && !hot;
-  ctx.globalAlpha = al;
-  ctx.strokeStyle = hot ? "rgba(45,212,191,.85)" : (dim ? "rgba(255,255,255,.04)" : "rgba(255,255,255,.13)");
-  ctx.lineWidth = (hot ? 2 : 1) / scale;
-  ctx.beginPath(); ctx.moveTo(a.x,a.y); ctx.lineTo(b.x,b.y); ctx.stroke();
-  // arrowhead at b, backed off by b's radius
-  const ang = Math.atan2(b.y-a.y, b.x-a.x);
-  const off = b.r + 4;
-  const hx = b.x - Math.cos(ang)*off, hy = b.y - Math.sin(ang)*off;
-  const ah = 8/Math.max(.6,scale);
-  ctx.fillStyle = hot ? "rgba(45,212,191,.9)" : (dim ? "rgba(255,255,255,.04)" : "rgba(255,255,255,.22)");
+  const ax=a.sx, ay=a.sy, bx=b.sx, by=b.sy;
+  const fog = Math.max(0.2, Math.min(1, 1 - (a.rz+b.rz)/1300));   // far edges recede
+  ctx.globalAlpha = al * (hot ? 1 : fog);
+  ctx.strokeStyle = hot ? "rgba(45,212,191,.85)" : (dim ? "rgba(255,255,255,.035)" : "rgba(255,255,255,.12)");
+  ctx.lineWidth = hot ? 2 : 1;
+  ctx.beginPath(); ctx.moveTo(ax,ay); ctx.lineTo(bx,by); ctx.stroke();
+  // arrowhead at b, backed off by b's projected radius
+  const ang = Math.atan2(by-ay, bx-ax);
+  const off = b.r*b.pp*scale + 4;
+  const hx = bx - Math.cos(ang)*off, hy = by - Math.sin(ang)*off;
+  const ah = 7;
+  ctx.fillStyle = hot ? "rgba(45,212,191,.9)" : (dim ? "rgba(255,255,255,.035)" : "rgba(255,255,255,.2)");
   ctx.beginPath();
   ctx.moveTo(hx, hy);
   ctx.lineTo(hx - Math.cos(ang-.4)*ah, hy - Math.sin(ang-.4)*ah);
@@ -326,10 +356,10 @@
   // animated flow particle along highlighted edges
   if(hot){
     const k = (t*0.0006) % 1;
-    const fx = a.x + (b.x-a.x)*k, fy = a.y + (b.y-a.y)*k;
+    const fx = ax + (bx-ax)*k, fy = ay + (by-ay)*k;
     ctx.shadowColor = "rgba(45,212,191,.9)"; ctx.shadowBlur = 8;
     ctx.fillStyle = "rgba(170,255,240,.98)";
-    ctx.beginPath(); ctx.arc(fx, fy, 2.6/Math.max(.6,scale), 0, 6.2832); ctx.fill();
+    ctx.beginPath(); ctx.arc(fx, fy, 2.8, 0, 6.2832); ctx.fill();
     ctx.shadowBlur = 0;
   }
   ctx.globalAlpha = 1;
@@ -343,83 +373,84 @@
   // idle breathing for hubs (when nothing is hovered)
   const breathe = (!hover && hubIds.has(n.id)) ? (1 + 0.10*Math.sin(t*0.0024)) : 1;
   const pulse = (n.id===hover) ? (1.32 + 0.10*Math.sin(t*0.006)) : 1;
-  const r = n.r * pulse * breathe;
-  ctx.globalAlpha = n.alpha;
+  const r = Math.max(2, n.r * pulse * breathe * n.pp * scale);   // perspective: near = larger
+  const fog = Math.max(0.32, Math.min(1, 1 - n.rz/640));         // depth cue: far nodes recede
+  const x = n.sx, y = n.sy;
+  ctx.globalAlpha = n.alpha * (faded ? 0.9 : fog);
   // selected ring
   if(n.id === selected){
-    ctx.beginPath(); ctx.arc(n.x, n.y, r+6, 0, 6.2832);
-    ctx.strokeStyle = `rgba(${col},.85)`; ctx.lineWidth = 2/scale; ctx.stroke();
+    ctx.beginPath(); ctx.arc(x, y, r+6, 0, 6.2832);
+    ctx.strokeStyle = `rgba(${col},.85)`; ctx.lineWidth = 2; ctx.stroke();
   }
   // hover halo
   if(n.id === hover){
-    ctx.beginPath(); ctx.arc(n.x, n.y, r+11, 0, 6.2832);
+    ctx.beginPath(); ctx.arc(x, y, r+11, 0, 6.2832);
     ctx.fillStyle = `rgba(${col},.16)`; ctx.fill();
   }
   // disc + glow
-  ctx.beginPath(); ctx.arc(n.x, n.y, r, 0, 6.2832);
+  ctx.beginPath(); ctx.arc(x, y, r, 0, 6.2832);
   ctx.fillStyle = `rgba(${col},${faded ? .25 : 1})`;
   ctx.shadowColor = `rgba(${col},.85)`;
-  ctx.shadowBlur = (faded ? 0 : (n.id===hover ? 22 : 14)) / Math.max(.6, scale);
+  ctx.shadowBlur = (faded ? 0 : (n.id===hover ? 22 : 14)) * fog;
   ctx.fill();
   ctx.shadowBlur = 0;
   // bright inner core
   if(!faded){
-    ctx.beginPath(); ctx.arc(n.x-r*0.28, n.y-r*0.28, r*0.34, 0, 6.2832);
+    ctx.beginPath(); ctx.arc(x-r*0.28, y-r*0.28, r*0.34, 0, 6.2832);
     ctx.fillStyle = "rgba(255,255,255,.55)"; ctx.fill();
   }
-  // label — declutter: hubs at rest; hovered node + neighbors; selection; all when zoomed in
+  // label — declutter: hubs at rest; hovered node + neighbors; selection; zoomed in; near depth only
   const showLabel = (scale > 1.4) || (n.id === selected) || (hover ? near : labelIds.has(n.id));
-  if(showLabel){
+  if(showLabel && fog > 0.55){
     ctx.fillStyle = faded ? "rgba(170,184,199,.3)" : "rgba(238,242,247,.95)";
-    ctx.font = `600 ${11/Math.max(.7,scale)}px ui-monospace,monospace`;
+    ctx.font = `600 11px ui-monospace,monospace`;
     ctx.textAlign = "center";
     ctx.shadowColor = "rgba(4,6,10,.92)"; ctx.shadowBlur = 4;   // legibility over the edge web
-    ctx.fillText(n.label, n.x, n.y + r + 13/Math.max(.7,scale));
+    ctx.fillText(n.label, x, y + r + 12);
     ctx.shadowBlur = 0;
   }
   ctx.globalAlpha = 1;
 }
 
 function frame(t){
   if(alpha > 0.005) step();   // once cooled, stop integrating — the graph holds still
+  project();                  // 3D → screen coords for this frame
   ctx.setTransform(DPR,0,0,DPR,0,0);
   ctx.clearRect(0,0,W(),H());
-  applyView();
   edges.forEach(e => drawEdge(e, t));
-  nodes.forEach(n => drawNode(n, t));
+  // draw nodes far → near so nearer discs occlude farther ones (painter's algorithm)
+  nodes.filter(visible).sort((a,b) => b.rz - a.rz).forEach(n => drawNode(n, t));
   requestAnimationFrame(frame);
 }
 
 /* ===================== hover / drag / pan ===================== */
 canvas.addEventListener("mousemove", e => {
-  const w = toWorld(e.offsetX, e.offsetY);
   if(drag){
-    drag.x = w.x; drag.y = w.y; drag.vx = drag.vy = 0; didDrag = true;
+    const w = unproject(e.offsetX, e.offsetY, drag);   // move the node within the current view plane
+    drag.x = w.x; drag.y = w.y; drag.z = w.z; drag.vx = drag.vy = drag.vz = 0; didDrag = true;
     alpha = Math.max(alpha, 0.5);   // reheat so neighbors re-settle around the dragged node
     return;
   }
-  if(panning){
-    panX = panOrigX + (e.offsetX - panStartX);
-    panY = panOrigY + (e.offsetY - panStartY);
+  if(orbiting){
+    yaw = yawStart + (e.offsetX - oStartX) * 0.01;
+    pitch = Math.max(-1.45, Math.min(1.45, pitchStart - (e.offsetY - oStartY) * 0.01));
     didDrag = true; return;
   }
-  const n = pick(w.x, w.y);
+  const n = pick(e.offsetX, e.offsetY);
   hover = n ? n.id : null;
-  canvas.style.cursor = n ? "grab" : "grab";
 });
 canvas.addEventListener("mousedown", e => {
-  const w = toWorld(e.offsetX, e.offsetY);
-  const n = pick(w.x, w.y);
+  const n = pick(e.offsetX, e.offsetY);
   didDrag = false;
   if(n){ drag = n; hover = n.id; canvas.style.cursor = "grabbing"; }
-  else { panning = true; panStartX = e.offsetX; panStartY = e.offsetY; panOrigX = panX; panOrigY = panY; }
+  else { orbiting = true; oStartX = e.offsetX; oStartY = e.offsetY; yawStart = yaw; pitchStart = pitch; canvas.style.cursor = "grabbing"; }
 });
 window.addEventListener("mouseup", e => {
   if(drag && !didDrag){ openPanel(drag); }     // click (no drag) on a node → inspect
-  drag = null; panning = false;
+  drag = null; orbiting = false;
   canvas.style.cursor = "grab";
 });
-canvas.addEventListener("mouseleave", () => { if(!drag && !panning) hover = null; });
+canvas.addEventListener("mouseleave", () => { if(!drag && !orbiting) hover = null; });
 
 /* ===================== inspector panel ===================== */
 function esc(s){ return String(s == null ? "" : s).replace(/[&<>"]/g, c => ({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;"}[c])); }