@kage-core/kage-graph-mcp 1.1.23 → 1.1.24

package/dist/daemon.js

@@ -232,6 +232,7 @@ async function startViewer(projectDir, options = {}) {
     const host = options.host ?? DEFAULT_HOST;
     const port = options.port ?? DEFAULT_VIEWER_PORT;
     const viewerDir = (0, node_path_1.resolve)(__dirname, "..", "viewer");
+    const threeDir = (0, node_path_1.resolve)(__dirname, "..", "node_modules", "three");
     const projectRoot = (0, node_path_1.resolve)(projectDir);
     const graphPath = (0, node_path_1.join)(projectRoot, ".agent_memory", "graph", "graph.json");
     const codePath = (0, node_path_1.join)(projectRoot, ".agent_memory", "code_graph", "graph.json");
@@ -262,13 +263,16 @@ async function startViewer(projectDir, options = {}) {
         else if (requestUrl.pathname.startsWith("/viewer/")) {
             filePath = (0, node_path_1.join)(viewerDir, (0, node_path_1.normalize)(requestUrl.pathname.replace(/^\/viewer\//, "")));
         }
+        else if (requestUrl.pathname.startsWith("/vendor/three/")) {
+            filePath = (0, node_path_1.join)(threeDir, (0, node_path_1.normalize)(requestUrl.pathname.replace(/^\/vendor\/three\//, "")));
+        }
         else {
             const decoded = decodeURIComponent(requestUrl.pathname);
             filePath = (0, node_path_1.resolve)(decoded);
             if (!isInside(projectRoot, filePath))
                 filePath = null;
         }
-        if (!filePath || (!isInside(viewerDir, filePath) && !isInside(projectRoot, filePath)) || !(0, node_fs_1.existsSync)(filePath)) {
+        if (!filePath || (!isInside(viewerDir, filePath) && !isInside(projectRoot, filePath) && !isInside(threeDir, filePath)) || !(0, node_fs_1.existsSync)(filePath)) {
             json(res, 404, { ok: false, error: "not_found" });
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "1.1.23",
+  "version": "1.1.24",
   "description": "Local-first repo memory, code graph, and recall MCP server for coding agents",
   "main": "dist/index.js",
   "files": [
@@ -37,6 +37,7 @@
   "license": "GPL-3.0-only",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.10.2",
+    "three": "^0.184.0",
     "typescript": "^5.0.0"
   },
   "devDependencies": {

package/viewer/app.js

@@ -37,6 +37,32 @@
       idleFrames: 0,
       adjacency: new Map()
     },
+    three: {
+      THREE: null,
+      loading: null,
+      failed: false,
+      renderer: null,
+      scene: null,
+      camera: null,
+      root: null,
+      nodeGroup: null,
+      edgeGroup: null,
+      nodeById: new Map(),
+      edgeRefs: [],
+      nodeTextureCache: new Map(),
+      physicsTick: 0,
+      physicsIdle: 0,
+      hoverNode: null,
+      pointer: null,
+      drag: null,
+      raycaster: null,
+      raf: null,
+      distance: 850,
+      target: { x: 0, y: 0, z: 0 },
+      rotationX: -0.20,
+      rotationY: 0.24,
+      lastPointerEvent: null
+    },
     pan: null
   };
 
@@ -84,6 +110,7 @@
     selectionStatus: document.getElementById("selectionStatus"),
     searchInput: document.getElementById("searchInput"),
     viewMode: document.getElementById("viewMode"),
+    renderMode: document.getElementById("renderMode"),
     typeFilter: document.getElementById("typeFilter"),
     relationFilter: document.getElementById("relationFilter"),
     scopeFilter: document.getElementById("scopeFilter"),
@@ -93,7 +120,10 @@
     zoomOut: document.getElementById("zoomOut"),
     zoomIn: document.getElementById("zoomIn"),
     fitView: document.getElementById("fitView"),
+    interactionHint: document.getElementById("interactionHint"),
+    graphWrap: document.getElementById("graphCanvasWrap"),
     canvas: document.getElementById("graphCanvas"),
+    threeGraph: document.getElementById("threeGraph"),
     tooltip: document.getElementById("graphTooltip"),
     svg: document.getElementById("graphSvg"),
     nodeLayer: document.getElementById("nodeLayer"),
@@ -122,33 +152,42 @@
   els.graphFile.addEventListener("change", handleFile);
   els.searchInput.addEventListener("input", scheduleRender);
   els.viewMode.addEventListener("change", render);
+  els.renderMode.addEventListener("change", function () {
+    state.lastVisibleSignature = "";
+    render();
+  });
   els.typeFilter.addEventListener("change", render);
   els.relationFilter.addEventListener("change", render);
   els.scopeFilter.addEventListener("change", render);
   els.maxNodes.addEventListener("change", render);
   els.showDependencies.addEventListener("change", render);
-  els.zoomOut.addEventListener("click", function () { zoomCanvas(0.82); });
-  els.zoomIn.addEventListener("click", function () { zoomCanvas(1.22); });
-  els.fitView.addEventListener("click", function () { fitCanvas(); drawCanvasGraph(); });
+  els.zoomOut.addEventListener("click", function () { zoomGraph(0.82); });
+  els.zoomIn.addEventListener("click", function () { zoomGraph(1.22); });
+  els.fitView.addEventListener("click", fitActiveGraph);
   els.canvas.addEventListener("mousedown", startCanvasPointer);
   els.canvas.addEventListener("mousemove", moveCanvasPointer);
   els.canvas.addEventListener("mouseup", endCanvasPointer);
   els.canvas.addEventListener("mouseleave", leaveCanvasPointer);
   els.canvas.addEventListener("wheel", handleCanvasWheel, { passive: false });
   els.canvas.addEventListener("dblclick", handleCanvasDoubleClick);
+  els.threeGraph.addEventListener("mousedown", startThreePointer);
+  els.threeGraph.addEventListener("mousemove", moveThreePointer);
+  els.threeGraph.addEventListener("mouseup", endThreePointer);
+  els.threeGraph.addEventListener("mouseleave", leaveThreePointer);
+  els.threeGraph.addEventListener("wheel", handleThreeWheel, { passive: false });
+  els.threeGraph.addEventListener("dblclick", handleThreeDoubleClick);
   els.svg.addEventListener("mousedown", startPan);
   els.svg.addEventListener("click", handleSvgClick);
   els.svg.addEventListener("wheel", handleWheelZoom, { passive: false });
   window.addEventListener("mousemove", continuePan);
   window.addEventListener("mouseup", endPan);
   window.addEventListener("resize", function () {
-    resizeCanvas();
-    fitCanvas();
-    drawCanvasGraph();
+    resizeActiveGraph();
   });
   els.resetView.addEventListener("click", function () {
     els.searchInput.value = "";
     els.viewMode.value = "combined";
+    els.renderMode.value = "2d";
     els.typeFilter.value = "";
     els.relationFilter.value = "";
     els.scopeFilter.value = "signal";
@@ -227,6 +266,7 @@
   function loadFromUrlParams() {
     var params = new URLSearchParams(window.location.search);
     applyRequestedView(params.get("view") || params.get("mode"));
+    applyRequestedRenderMode(params.get("render") || params.get("graphMode"));
     var memoryGraphPaths = splitParamValues(params.getAll("graph"));
     var codeGraphPaths = splitParamValues(params.getAll("code"));
     var graphPaths = memoryGraphPaths.concat(codeGraphPaths);
@@ -829,7 +869,7 @@
     var graphChanged = nextSignature !== state.lastVisibleSignature;
     state.lastVisibleSignature = nextSignature;
 
-    renderCanvasGraph(graphChanged);
+    renderActiveGraph(graphChanged);
     renderLists();
     renderDetails();
     renderMetrics();
@@ -1088,9 +1128,69 @@
     }));
   }
 
-  function renderCanvasGraph(graphChanged) {
-    resizeCanvas();
+  function activeRenderMode() {
+    return els.renderMode && els.renderMode.value === "3d" ? "3d" : "2d";
+  }
+
+  function renderActiveGraph(graphChanged) {
+    var mode = activeRenderMode();
+    updateGraphSurfaceMode(mode);
     syncSimulationGraph(graphChanged);
+    if (mode === "3d") {
+      stopSimulation();
+      renderThreeGraph(graphChanged);
+      return;
+    }
+    stopThreeGraph();
+    renderCanvasGraph(graphChanged, true);
+  }
+
+  function updateGraphSurfaceMode(mode) {
+    if (els.graphWrap) {
+      els.graphWrap.classList.toggle("mode-3d", mode === "3d");
+      els.graphWrap.classList.toggle("mode-2d", mode !== "3d");
+    }
+    if (els.interactionHint) {
+      els.interactionHint.textContent = mode === "3d"
+        ? "drag orb or node / wheel zoom / click node"
+        : "drag canvas / wheel zoom / click node";
+    }
+    if (els.tooltip) els.tooltip.classList.remove("visible");
+  }
+
+  function resizeActiveGraph() {
+    if (activeRenderMode() === "3d") {
+      resizeThreeGraph();
+      renderThreeFrame();
+      return;
+    }
+    resizeCanvas();
+    fitCanvas();
+    drawCanvasGraph();
+  }
+
+  function fitActiveGraph() {
+    if (activeRenderMode() === "3d") {
+      fitThreeGraph();
+      renderThreeFrame();
+      return;
+    }
+    fitCanvas();
+    drawCanvasGraph();
+  }
+
+  function zoomGraph(factor) {
+    if (activeRenderMode() === "3d") {
+      zoomThreeGraph(factor);
+      renderThreeFrame();
+      return;
+    }
+    zoomCanvas(factor);
+  }
+
+  function renderCanvasGraph(graphChanged, alreadySynced) {
+    resizeCanvas();
+    if (!alreadySynced) syncSimulationGraph(graphChanged);
     if (graphChanged) fitCanvas();
     startSimulation();
     drawCanvasGraph();
@@ -1817,6 +1917,15 @@
     els.viewMode.value = normalized;
   }
 
+  function applyRequestedRenderMode(mode) {
+    if (!mode) return;
+    var normalized = String(mode).toLowerCase();
+    if (normalized === "canvas") normalized = "2d";
+    if (normalized === "space") normalized = "3d";
+    if (["2d", "3d"].indexOf(normalized) === -1) return;
+    els.renderMode.value = normalized;
+  }
+
   function isMemoryCodeEdge(edge) {
     return Boolean(edge && (edge.memory_code_link || isMemoryCodeRelation(edge.relation)));
   }
@@ -2317,6 +2426,579 @@
     state.sim.panY = height / 2 - ((minY + maxY) / 2) * state.sim.zoom;
   }
 
+  function ensureThree() {
+    if (state.three.THREE) return Promise.resolve(state.three.THREE);
+    if (state.three.loading) return state.three.loading;
+    state.three.failed = false;
+    state.three.loading = import("/vendor/three/build/three.module.min.js")
+      .catch(function () {
+        return import("https://unpkg.com/three@0.184.0/build/three.module.min.js");
+      })
+      .then(function (mod) {
+        state.three.THREE = mod;
+        return mod;
+      })
+      .catch(function (error) {
+        state.three.failed = true;
+        throw error;
+      });
+    return state.three.loading;
+  }
+
+  function renderThreeGraph(graphChanged) {
+    drawThreeStatus("Loading 3D graph...");
+    ensureThree().then(function () {
+      if (activeRenderMode() !== "3d") return;
+      setupThreeScene();
+      rebuildThreeScene();
+      if (graphChanged || state.three.distance <= 0) fitThreeGraph();
+      startThreeGraph();
+      renderThreeFrame();
+    }).catch(function () {
+      drawThreeStatus("3D renderer unavailable. Falling back to 2D canvas.");
+      if (els.renderMode) els.renderMode.value = "2d";
+      updateGraphSurfaceMode("2d");
+      renderCanvasGraph(true);
+    });
+  }
+
+  function drawThreeStatus(message) {
+    if (!els.threeGraph || state.three.renderer) return;
+    els.threeGraph.innerHTML = "<div class=\"three-status\"></div>";
+    var status = els.threeGraph.querySelector(".three-status");
+    if (status) status.textContent = message;
+  }
+
+  function setupThreeScene() {
+    if (state.three.renderer) {
+      resizeThreeGraph();
+      return;
+    }
+    var THREE = state.three.THREE;
+    els.threeGraph.textContent = "";
+    state.three.renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true, powerPreference: "high-performance" });
+    state.three.renderer.setClearColor(new THREE.Color(graphPalette.background), 1);
+    state.three.renderer.setPixelRatio(Math.min(2, window.devicePixelRatio || 1));
+    els.threeGraph.appendChild(state.three.renderer.domElement);
+    state.three.scene = new THREE.Scene();
+    state.three.scene.fog = new THREE.FogExp2(new THREE.Color(graphPalette.background), 0.00016);
+    state.three.camera = new THREE.PerspectiveCamera(50, 1, 1, 5000);
+    state.three.root = new THREE.Group();
+    state.three.nodeGroup = new THREE.Group();
+    state.three.edgeGroup = new THREE.Group();
+    state.three.root.add(state.three.edgeGroup);
+    state.three.root.add(state.three.nodeGroup);
+    state.three.scene.add(state.three.root);
+    state.three.scene.add(new THREE.AmbientLight(0x8fffb1, 0.54));
+    var key = new THREE.PointLight(0x6ad7ff, 1.2, 2200);
+    key.position.set(280, 360, 520);
+    state.three.scene.add(key);
+    var fill = new THREE.PointLight(0xb88cff, 0.72, 1800);
+    fill.position.set(-420, -220, 360);
+    state.three.scene.add(fill);
+    state.three.raycaster = new THREE.Raycaster();
+    state.three.pointer = new THREE.Vector2();
+    resizeThreeGraph();
+  }
+
+  function rebuildThreeScene() {
+    var THREE = state.three.THREE;
+    clearThreeGroup(state.three.nodeGroup);
+    clearThreeGroup(state.three.edgeGroup);
+    state.three.nodeById = new Map();
+    state.three.edgeRefs = [];
+    state.three.physicsTick = 0;
+    state.three.physicsIdle = 0;
+
+    state.sim.nodes.forEach(function (node, index) {
+      var entity = node.entity;
+      var selected = state.selected && state.selected.kind === "entity" && state.selected.id === node.id;
+      var material = new THREE.SpriteMaterial({
+        map: threeNodeTexture(entity, selected),
+        transparent: true,
+        opacity: isDependencyEntity(entity) ? 0.70 : 1,
+        depthWrite: false
+      });
+      var mesh = new THREE.Sprite(material);
+      var position = threePosition(node, index);
+      mesh.position.set(position.x, position.y, position.z);
+      var size = threeNodeSize(node, selected);
+      mesh.scale.set(size, size, 1);
+      mesh.userData.node = node;
+      state.three.nodeGroup.add(mesh);
+      state.three.nodeById.set(node.id, { node: node, mesh: mesh, vx: 0, vy: 0, vz: 0 });
+    });
+
+    state.sim.edges.forEach(function (edge) {
+      var from = state.three.nodeById.get(edge.from);
+      var to = state.three.nodeById.get(edge.to);
+      if (!from || !to) return;
+      var fromEntity = from.node.entity;
+      var toEntity = to.node.entity;
+      var connected = state.selected && state.selected.kind === "entity" && (state.selected.id === edge.from || state.selected.id === edge.to);
+      var geometry = new THREE.BufferGeometry().setFromPoints([from.mesh.position, to.mesh.position]);
+      var material = new THREE.LineBasicMaterial({
+        color: new THREE.Color(edgeThemeColor(edge, fromEntity, toEntity)),
+        transparent: true,
+        opacity: threeEdgeOpacity(edge, fromEntity, toEntity, connected),
+        depthWrite: false,
+        depthTest: false
+      });
+      var line = new THREE.Line(geometry, material);
+      line.userData.edge = edge;
+      line.userData.from = edge.from;
+      line.userData.to = edge.to;
+      state.three.edgeGroup.add(line);
+      state.three.edgeRefs.push(line);
+    });
+
+    if (state.three.root) {
+      state.three.root.rotation.x = state.three.rotationX;
+      state.three.root.rotation.y = state.three.rotationY;
+    }
+  }
+
+  function clearThreeGroup(group) {
+    if (!group) return;
+    while (group.children.length) {
+      var child = group.children.pop();
+      if (!child) continue;
+      if (child.geometry && child.geometry.dispose) child.geometry.dispose();
+      if (child.material) {
+        if (Array.isArray(child.material)) child.material.forEach(function (material) { if (material.dispose) material.dispose(); });
+        else if (child.material.dispose) child.material.dispose();
+      }
+    }
+  }
+
+  function threeNodeTexture(entity, selected) {
+    var THREE = state.three.THREE;
+    var color = nodeThemeColor(entity);
+    var key = [color, entity.graph_kind || "", entity.type || "", selected ? "selected" : "normal", isDependencyEntity(entity) ? "dependency" : "primary"].join("|");
+    if (state.three.nodeTextureCache.has(key)) return state.three.nodeTextureCache.get(key);
+    var canvas = document.createElement("canvas");
+    canvas.width = 128;
+    canvas.height = 128;
+    var ctx = canvas.getContext("2d");
+    var rgb = hexToRgb(color);
+    var fill = nodeFillColor(entity);
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    var halo = ctx.createRadialGradient(64, 64, 8, 64, 64, 58);
+    halo.addColorStop(0, "rgba(" + rgb.r + "," + rgb.g + "," + rgb.b + "," + (selected ? 0.62 : 0.38) + ")");
+    halo.addColorStop(0.52, "rgba(" + rgb.r + "," + rgb.g + "," + rgb.b + "," + (selected ? 0.24 : 0.13) + ")");
+    halo.addColorStop(1, "rgba(" + rgb.r + "," + rgb.g + "," + rgb.b + ",0)");
+    ctx.fillStyle = halo;
+    ctx.beginPath();
+    ctx.arc(64, 64, 60, 0, Math.PI * 2);
+    ctx.fill();
+    ctx.fillStyle = fill;
+    ctx.beginPath();
+    ctx.arc(64, 64, selected ? 36 : 31, 0, Math.PI * 2);
+    ctx.fill();
+    ctx.strokeStyle = color;
+    ctx.lineWidth = selected ? 8 : 5;
+    ctx.beginPath();
+    ctx.arc(64, 64, selected ? 38 : 33, 0, Math.PI * 2);
+    ctx.stroke();
+    if (entity.graph_kind === "memory") {
+      ctx.fillStyle = color;
+      ctx.globalAlpha = 0.95;
+      ctx.beginPath();
+      ctx.arc(64, 64, 8, 0, Math.PI * 2);
+      ctx.fill();
+      ctx.globalAlpha = 1;
+    }
+    var texture = new THREE.CanvasTexture(canvas);
+    texture.needsUpdate = true;
+    state.three.nodeTextureCache.set(key, texture);
+    return texture;
+  }
+
+  function threeNodeSize(node, selected) {
+    var entity = node.entity;
+    var size = clamp(19 + degreeOf(node.id) * 1.65, 22, entity.graph_kind === "memory" ? 46 : 40);
+    if (entity.type === "file" || entity.type === "repo") size += 5;
+    if (selected) size *= 1.22;
+    return size;
+  }
+
+  function threeEdgeOpacity(edge, fromEntity, toEntity, connected) {
+    if (connected) return 0.48;
+    if (edge.memory_code_link || isMemoryCodeRelation(edge.relation)) return 0.34;
+    if (fromEntity.graph_kind === "code" && toEntity.graph_kind === "code") return 0.20;
+    if (fromEntity.graph_kind === "memory" && toEntity.graph_kind === "memory") return 0.12;
+    return 0.15;
+  }
+
+  function threePosition(node, index) {
+    var entity = node.entity;
+    var total = Math.max(1, state.sim.nodes.length);
+    var rank = index + 0.5;
+    var golden = Math.PI * (3 - Math.sqrt(5));
+    var theta = golden * rank + (hashString(node.id || index) % 360) * 0.004;
+    var yUnit = 1 - (2 * rank) / total;
+    var ring = Math.sqrt(Math.max(0, 1 - yUnit * yUnit));
+    var radius = threeOrbRadius(total);
+    var inner = threeOrbScale(entity);
+    var kindOffset = threeKindDepthBias(entity);
+    return {
+      x: Math.cos(theta) * ring * radius * inner,
+      y: yUnit * radius * inner,
+      z: (Math.sin(theta) * ring + kindOffset) * radius * inner
+    };
+  }
+
+  function threeOrbRadius(total) {
+    return clamp(245 + Math.max(1, total) * 2.1, 280, 455);
+  }
+
+  function threeOrbScale(entity) {
+    if (entity.graph_kind === "memory") return 0.88;
+    if (entity.type === "file" || entity.type === "repo") return 0.76;
+    if (isDependencyEntity(entity)) return 1.08;
+    return 1;
+  }
+
+  function threeKindDepthBias(entity) {
+    if (entity.graph_kind === "memory") return -0.22;
+    if (entity.graph_kind === "code") return 0.18;
+    return 0;
+  }
+
+  function resizeThreeGraph() {
+    if (!state.three.renderer || !els.threeGraph) return;
+    var rect = els.threeGraph.getBoundingClientRect();
+    var width = Math.max(320, rect.width);
+    var height = Math.max(360, rect.height);
+    state.three.renderer.setPixelRatio(Math.min(2, window.devicePixelRatio || 1));
+    state.three.renderer.setSize(width, height, false);
+    state.three.camera.aspect = width / height;
+    state.three.camera.updateProjectionMatrix();
+  }
+
+  function fitThreeGraph() {
+    var entries = Array.from(state.three.nodeById.values());
+    if (!entries.length) {
+      state.three.distance = 850;
+      return;
+    }
+    var maxRadius = entries.reduce(function (max, entry) {
+      var p = entry.mesh.position;
+      return Math.max(max, Math.sqrt(p.x * p.x + p.y * p.y + p.z * p.z));
+    }, 260);
+    state.three.distance = clamp(maxRadius * 2.35, 760, 2600);
+  }
+
+  function zoomThreeGraph(factor) {
+    state.three.distance = clamp(state.three.distance / factor, 320, 3200);
+  }
+
+  function startThreeGraph() {
+    if (state.three.raf) return;
+    function frame() {
+      if (activeRenderMode() !== "3d" || !state.three.renderer) {
+        state.three.raf = null;
+        return;
+      }
+      if (!state.three.drag && state.three.root) {
+        state.three.rotationY += 0.0017;
+        state.three.root.rotation.y = state.three.rotationY;
+      }
+      stepThreePhysics();
+      renderThreeFrame();
+      state.three.raf = window.requestAnimationFrame(frame);
+    }
+    state.three.raf = window.requestAnimationFrame(frame);
+  }
+
+  function stopThreeGraph() {
+    if (state.three.raf) window.cancelAnimationFrame(state.three.raf);
+    state.three.raf = null;
+    if (els.tooltip) els.tooltip.classList.remove("visible");
+  }
+
+  function renderThreeFrame() {
+    if (!state.three.renderer || !state.three.scene || !state.three.camera) return;
+    resizeThreeGraph();
+    state.three.camera.position.set(state.three.target.x, state.three.target.y, state.three.distance);
+    state.three.camera.lookAt(state.three.target.x, state.three.target.y, state.three.target.z);
+    updateThreeEdges();
+    state.three.renderer.render(state.three.scene, state.three.camera);
+  }
+
+  function stepThreePhysics() {
+    if (!state.three.nodeById || state.three.physicsTick > 180) return;
+    if (state.three.drag && state.three.drag.type === "node") return;
+    var entries = Array.from(state.three.nodeById.values());
+    var count = entries.length;
+    if (!count) return;
+    var forces = new Map(entries.map(function (entry) {
+      return [entry.node.id, { x: 0, y: 0, z: 0 }];
+    }));
+    var repulsion = count > 110 ? 1800 : count > 70 ? 2600 : 3400;
+    for (var i = 0; i < entries.length; i++) {
+      for (var j = i + 1; j < entries.length; j++) {
+        var a = entries[i];
+        var b = entries[j];
+        var dx = a.mesh.position.x - b.mesh.position.x;
+        var dy = a.mesh.position.y - b.mesh.position.y;
+        var dz = a.mesh.position.z - b.mesh.position.z;
+        var distSq = Math.max(1200, dx * dx + dy * dy + dz * dz);
+        var dist = Math.sqrt(distSq);
+        var force = repulsion / distSq;
+        var ax = (dx / dist) * force;
+        var ay = (dy / dist) * force;
+        var az = (dz / dist) * force;
+        var fa = forces.get(a.node.id);
+        var fb = forces.get(b.node.id);
+        fa.x += ax;
+        fa.y += ay;
+        fa.z += az;
+        fb.x -= ax;
+        fb.y -= ay;
+        fb.z -= az;
+      }
+    }
+
+    state.sim.edges.forEach(function (edge) {
+      var from = state.three.nodeById.get(edge.from);
+      var to = state.three.nodeById.get(edge.to);
+      if (!from || !to) return;
+      var dx = to.mesh.position.x - from.mesh.position.x;
+      var dy = to.mesh.position.y - from.mesh.position.y;
+      var dz = to.mesh.position.z - from.mesh.position.z;
+      var dist = Math.max(1, Math.sqrt(dx * dx + dy * dy + dz * dz));
+      var memoryCode = edge.memory_code_link || isMemoryCodeRelation(edge.relation);
+      var target = memoryCode ? 190 : (from.node.entity.graph_kind === "code" && to.node.entity.graph_kind === "code" ? 240 : 220);
+      var strength = memoryCode ? 0.0032 : 0.0018;
+      var force = (dist - target) * strength;
+      var fx = (dx / dist) * force;
+      var fy = (dy / dist) * force;
+      var fz = (dz / dist) * force;
+      var ff = forces.get(from.node.id);
+      var ft = forces.get(to.node.id);
+      ff.x += fx;
+      ff.y += fy;
+      ff.z += fz;
+      ft.x -= fx;
+      ft.y -= fy;
+      ft.z -= fz;
+    });
+
+    var baseRadius = threeOrbRadius(count);
+    var maxVelocity = 0;
+    entries.forEach(function (entry) {
+      var p = entry.mesh.position;
+      var entity = entry.node.entity;
+      var len = Math.max(1, Math.sqrt(p.x * p.x + p.y * p.y + p.z * p.z));
+      var desiredRadius = baseRadius * threeOrbScale(entity);
+      var radial = (desiredRadius - len) * 0.055;
+      var f = forces.get(entry.node.id);
+      f.x += (p.x / len) * radial;
+      f.y += (p.y / len) * radial;
+      f.z += (p.z / len) * radial;
+      var depthTarget = desiredRadius * threeKindDepthBias(entity);
+      f.z += (depthTarget - p.z) * 0.002;
+      entry.vx = clamp((entry.vx + f.x) * 0.80, -4.2, 4.2);
+      entry.vy = clamp((entry.vy + f.y) * 0.80, -4.2, 4.2);
+      entry.vz = clamp((entry.vz + f.z) * 0.80, -4.2, 4.2);
+      p.x += entry.vx;
+      p.y += entry.vy;
+      p.z += entry.vz;
+      var nextLen = Math.max(1, Math.sqrt(p.x * p.x + p.y * p.y + p.z * p.z));
+      var correction = (desiredRadius - nextLen) * 0.08;
+      p.x += (p.x / nextLen) * correction;
+      p.y += (p.y / nextLen) * correction;
+      p.z += (p.z / nextLen) * correction;
+      maxVelocity = Math.max(maxVelocity, Math.abs(entry.vx), Math.abs(entry.vy), Math.abs(entry.vz));
+    });
+    state.three.physicsTick += 1;
+    state.three.physicsIdle = maxVelocity < 0.030 ? state.three.physicsIdle + 1 : 0;
+    if (state.three.physicsIdle > 32) state.three.physicsTick = 181;
+  }
+
+  function startThreePointer(event) {
+    if (activeRenderMode() !== "3d" || event.button !== 0) return;
+    event.preventDefault();
+    var picked = pickThreeNode(event);
+    if (picked) {
+      var entry = state.three.nodeById.get(picked.id);
+      state.three.drag = {
+        type: "node",
+        x: event.clientX,
+        y: event.clientY,
+        moved: false,
+        picked: picked,
+        entry: entry,
+        plane: createThreeDragPlane(entry && entry.mesh)
+      };
+      return;
+    }
+    state.three.drag = {
+      type: "space",
+      x: event.clientX,
+      y: event.clientY,
+      rotationX: state.three.rotationX,
+      rotationY: state.three.rotationY,
+      moved: false,
+      picked: null
+    };
+  }
+
+  function moveThreePointer(event) {
+    if (activeRenderMode() !== "3d") return;
+    state.three.lastPointerEvent = event;
+    if (state.three.drag) {
+      var dx = event.clientX - state.three.drag.x;
+      var dy = event.clientY - state.three.drag.y;
+      if (Math.abs(dx) > 2 || Math.abs(dy) > 2) state.three.drag.moved = true;
+      if (state.three.drag.type === "node") {
+        moveThreeDraggedNode(event);
+        renderThreeFrame();
+        return;
+      }
+      state.three.rotationY = state.three.drag.rotationY + dx * 0.0065;
+      state.three.rotationX = clamp(state.three.drag.rotationX + dy * 0.0048, -1.15, 0.45);
+      if (state.three.root) {
+        state.three.root.rotation.x = state.three.rotationX;
+        state.three.root.rotation.y = state.three.rotationY;
+      }
+      renderThreeFrame();
+      return;
+    }
+    state.three.hoverNode = pickThreeNode(event);
+    updateThreeTooltip(event);
+  }
+
+  function endThreePointer(event) {
+    if (!state.three.drag) return;
+    var picked = !state.three.drag.moved || state.three.drag.type === "node"
+      ? (pickThreeNode(event) || state.three.drag.picked)
+      : null;
+    state.three.drag = null;
+    if (picked) {
+      state.selected = { kind: "entity", id: picked.id };
+      render();
+    }
+  }
+
+  function leaveThreePointer() {
+    state.three.hoverNode = null;
+    state.three.drag = null;
+    if (els.tooltip) els.tooltip.classList.remove("visible");
+  }
+
+  function handleThreeWheel(event) {
+    if (activeRenderMode() !== "3d") return;
+    event.preventDefault();
+    zoomThreeGraph(event.deltaY > 0 ? 0.88 : 1.14);
+    renderThreeFrame();
+  }
+
+  function handleThreeDoubleClick(event) {
+    var picked = pickThreeNode(event);
+    if (!picked) return;
+    state.selected = { kind: "entity", id: picked.id };
+    render();
+  }
+
+  function pickThreeNode(event) {
+    if (!state.three.raycaster || !state.three.camera || !state.three.pointer) return null;
+    setThreePointerFromEvent(event);
+    state.three.raycaster.setFromCamera(state.three.pointer, state.three.camera);
+    var meshes = Array.from(state.three.nodeById.values()).map(function (entry) { return entry.mesh; });
+    var hits = state.three.raycaster.intersectObjects(meshes, false);
+    return hits.length && hits[0].object.userData ? hits[0].object.userData.node : null;
+  }
+
+  function createThreeDragPlane(mesh) {
+    if (!mesh || !state.three.camera || !state.three.THREE) return null;
+    var THREE = state.three.THREE;
+    state.three.root.updateMatrixWorld(true);
+    state.three.camera.updateMatrixWorld(true);
+    var normal = new THREE.Vector3();
+    state.three.camera.getWorldDirection(normal);
+    var point = new THREE.Vector3();
+    mesh.getWorldPosition(point);
+    return new THREE.Plane().setFromNormalAndCoplanarPoint(normal, point);
+  }
+
+  function moveThreeDraggedNode(event) {
+    var drag = state.three.drag;
+    if (!drag || !drag.entry || !drag.entry.mesh || !drag.plane || !state.three.raycaster) return;
+    var THREE = state.three.THREE;
+    setThreePointerFromEvent(event);
+    state.three.raycaster.setFromCamera(state.three.pointer, state.three.camera);
+    var hit = new THREE.Vector3();
+    if (!state.three.raycaster.ray.intersectPlane(drag.plane, hit)) return;
+    var local = hit.clone();
+    state.three.root.worldToLocal(local);
+    drag.entry.mesh.position.copy(local);
+    drag.entry.vx = 0;
+    drag.entry.vy = 0;
+    drag.entry.vz = 0;
+    state.three.physicsTick = 0;
+    state.three.physicsIdle = 0;
+    updateThreeEdges();
+  }
+
+  function updateThreeEdges() {
+    if (!state.three.edgeRefs || !state.three.edgeRefs.length) return;
+    state.three.edgeRefs.forEach(function (line) {
+      var from = state.three.nodeById.get(line.userData.from);
+      var to = state.three.nodeById.get(line.userData.to);
+      if (!from || !to || !line.geometry) return;
+      var attr = line.geometry.getAttribute("position");
+      if (!attr) return;
+      attr.setXYZ(0, from.mesh.position.x, from.mesh.position.y, from.mesh.position.z);
+      attr.setXYZ(1, to.mesh.position.x, to.mesh.position.y, to.mesh.position.z);
+      attr.needsUpdate = true;
+      line.geometry.computeBoundingSphere();
+    });
+  }
+
+  function setThreePointerFromEvent(event) {
+    var rect = els.threeGraph.getBoundingClientRect();
+    state.three.pointer.x = ((event.clientX - rect.left) / Math.max(rect.width, 1)) * 2 - 1;
+    state.three.pointer.y = -(((event.clientY - rect.top) / Math.max(rect.height, 1)) * 2 - 1);
+  }
+
+  function updateThreeTooltip(event) {
+    if (!els.tooltip) return;
+    var node = state.three.hoverNode;
+    if (!node || state.three.drag) {
+      els.tooltip.classList.remove("visible");
+      return;
+    }
+    var entity = node.entity;
+    var relationCount = state.sim.edges.filter(function (edge) { return edge.from === node.id || edge.to === node.id; }).length;
+    var color = nodeThemeColor(entity);
+    els.tooltip.innerHTML = [
+      "<div class=\"tt-name\"></div>",
+      "<div class=\"tt-type\"></div>",
+      "<div class=\"tt-summary\"></div>",
+      "<div class=\"tt-conns\"></div>"
+    ].join("");
+    els.tooltip.querySelector(".tt-name").textContent = displayName(entity);
+    els.tooltip.querySelector(".tt-type").textContent = nodeKindLabel(entity);
+    els.tooltip.querySelector(".tt-type").style.color = color;
+    els.tooltip.querySelector(".tt-summary").textContent = shortName(entity.summary || entity.id, 150);
+    els.tooltip.querySelector(".tt-conns").textContent = relationCount + " relation" + (relationCount === 1 ? "" : "s");
+    var rect = els.threeGraph.getBoundingClientRect();
+    els.tooltip.style.left = (event.clientX - rect.left + 14) + "px";
+    els.tooltip.style.top = (event.clientY - rect.top + 14) + "px";
+    els.tooltip.classList.add("visible");
+  }
+
+  function hashString(value) {
+    var text = String(value || "");
+    var hash = 0;
+    for (var i = 0; i < text.length; i++) {
+      hash = ((hash << 5) - hash + text.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash);
+  }
+
   function focusedCanvasNodeId() {
     if (state.sim.hoverNode) return state.sim.hoverNode.id;
     if (state.selected && state.selected.kind === "entity") return state.selected.id;

package/viewer/index.html

@@ -4,7 +4,7 @@
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>Kage Memory Terminal</title>
-    <link rel="stylesheet" href="./styles.css?v=15">
+    <link rel="stylesheet" href="./styles.css?v=17">
   </head>
   <body>
     <header class="app-header">
@@ -29,14 +29,15 @@
             <p id="graphSubhead">Combined repo memory and source graph.</p>
           </div>
           <div class="graph-actions" aria-label="Graph view controls">
-            <span class="interaction-hint">drag canvas / wheel zoom / click node</span>
+            <span id="interactionHint" class="interaction-hint">drag canvas / wheel zoom / click node</span>
             <button id="zoomOut" type="button">-</button>
             <button id="fitView" type="button">Fit</button>
             <button id="zoomIn" type="button">+</button>
           </div>
         </div>
-        <div class="graph-canvas-wrap">
+        <div id="graphCanvasWrap" class="graph-canvas-wrap">
           <canvas id="graphCanvas" aria-label="Interactive Kage memory and code graph"></canvas>
+          <div id="threeGraph" class="three-graph" aria-label="Interactive 3D Kage memory and code graph"></div>
           <div id="graphTooltip" class="graph-tooltip" role="status"></div>
         </div>
         <svg id="graphSvg" class="fallback-graph" viewBox="0 0 1000 660" role="img" aria-labelledby="graphTitle graphDescription">
@@ -74,6 +75,13 @@
             <option value="code">Code</option>
           </select>
         </label>
+        <label>
+          <span>Graph Mode</span>
+          <select id="renderMode">
+            <option value="2d" selected>2D Canvas</option>
+            <option value="3d">3D Space</option>
+          </select>
+        </label>
         <label>
           <span>Node Type</span>
           <select id="typeFilter">
@@ -149,6 +157,6 @@
       </section>
     </main>
 
-    <script src="./app.js?v=15"></script>
+    <script src="./app.js?v=17"></script>
   </body>
 </html>

package/viewer/styles.css

@@ -337,16 +337,49 @@ input:focus, select:focus, button:focus, .file-picker:focus-within {
     #020503;
 }
 
-#graphCanvas {
+#graphCanvas, .three-graph {
   width: 100%;
   height: 100%;
   min-height: 600px;
   display: block;
+}
+
+#graphCanvas {
   cursor: grab;
 }
 
 #graphCanvas:active { cursor: grabbing; }
 
+.three-graph {
+  position: absolute;
+  inset: 0;
+  display: none;
+  cursor: grab;
+  background:
+    linear-gradient(rgba(65, 255, 143, 0.035) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(65, 255, 143, 0.035) 1px, transparent 1px),
+    radial-gradient(circle at 52% 46%, rgba(106, 215, 255, 0.10), transparent 46%),
+    #020503;
+  background-size: 34px 34px, 34px 34px, 100% 100%, 100% 100%;
+}
+.three-graph canvas {
+  display: block;
+  width: 100% !important;
+  height: 100% !important;
+}
+.three-graph:active { cursor: grabbing; }
+.three-status {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  color: var(--terminal-dim);
+  font-weight: 780;
+}
+.graph-canvas-wrap.mode-3d #graphCanvas { display: none; }
+.graph-canvas-wrap.mode-3d .three-graph { display: block; }
+.graph-canvas-wrap.mode-2d .three-graph { display: none; }
+
 #graphSvg {
   width: 100%;
   height: 100%;
@@ -693,7 +726,7 @@ input:focus, select:focus, button:focus, .file-picker:focus-within {
   .control-panel .panel-heading, .metrics-grid, .legend { grid-column: 1 / -1; }
   .control-panel label, .control-panel button { margin-top: 0; }
   .graph-panel { min-height: 620px; }
-  #graphCanvas, .graph-canvas-wrap, #graphSvg { min-height: 560px; }
+  #graphCanvas, .three-graph, .graph-canvas-wrap, #graphSvg { min-height: 560px; }
   .details-panel {
     height: auto;
     max-height: 70vh;
@@ -710,5 +743,5 @@ input:focus, select:focus, button:focus, .file-picker:focus-within {
   .graph-toolbar { align-items: flex-start; flex-direction: column; }
   .graph-actions { width: 100%; }
   .interaction-hint { flex: 1; white-space: normal; }
-  #graphCanvas, .graph-canvas-wrap, #graphSvg { min-height: 450px; }
+  #graphCanvas, .three-graph, .graph-canvas-wrap, #graphSvg { min-height: 450px; }
 }