backpack-viewer 0.2.20 → 0.3.0

package/dist/canvas.js

@@ -1,5 +1,7 @@
-import { createLayout, extractSubgraph, tick } from "./layout";
+import { createLayout, extractSubgraph, tick, getLayoutParams } from "./layout";
 import { getColor } from "./colors";
+import { SpatialHash } from "./spatial-hash";
+import { drawCachedLabel, clearLabelCache } from "./label-cache";
 /** Read a CSS custom property from :root. */
 function cssVar(name) {
     return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
@@ -7,7 +9,7 @@ function cssVar(name) {
 const NODE_RADIUS = 20;
 const ALPHA_MIN = 0.001;
 // Defaults — overridden per-instance via config
-const LOD_DEFAULTS = { hideBadges: 0.4, hideLabels: 0.25, hideEdgeLabels: 0.35, smallNodes: 0.2, hideArrows: 0.15 };
+const LOD_DEFAULTS = { hideBadges: 0.4, hideLabels: 0.25, hideEdgeLabels: 0.35, smallNodes: 0.2, hideArrows: 0.15, dotNodes: 0.1, hullsOnly: 0.05 };
 const NAV_DEFAULTS = { zoomFactor: 1.3, zoomMin: 0.05, zoomMax: 10, panAnimationMs: 300 };
 /** Check if a point is within the visible viewport (with padding). */
 function isInViewport(x, y, camera, canvasW, canvasH, pad = 100) {
@@ -18,6 +20,7 @@ function isInViewport(x, y, camera, canvasW, canvasH, pad = 100) {
 export function initCanvas(container, onNodeClick, onFocusChange, config) {
     const lod = { ...LOD_DEFAULTS, ...(config?.lod ?? {}) };
     const nav = { ...NAV_DEFAULTS, ...(config?.navigation ?? {}) };
+    const walkCfg = { pulseSpeed: 0.02, ...(config?.walk ?? {}) };
     const canvas = container.querySelector("canvas");
     const ctx = canvas.getContext("2d");
     const dpr = window.devicePixelRatio || 1;
@@ -37,6 +40,79 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
     let focusHops = 1;
     let savedFullState = null;
     let savedFullCamera = null;
+    // Highlighted path state (for path finding visualization)
+    let highlightedPath = null;
+    // Walk mode state
+    let walkMode = false;
+    let walkTrail = []; // node IDs visited during walk, most recent last
+    let pulsePhase = 0; // animation counter for pulse effect
+    // Entrance animation state
+    let loadTime = 0;
+    const ENTRANCE_DURATION = 400; // ms
+    // Spatial hash for O(1) hit testing — cell size = 2× node radius
+    const nodeHash = new SpatialHash(NODE_RADIUS * 2);
+    // Render coalescing — multiple requestRedraw() calls per frame result in one render()
+    let renderPending = 0;
+    function requestRedraw() {
+        invalidateSceneCache();
+        if (!renderPending)
+            renderPending = requestAnimationFrame(() => { renderPending = 0; render(); });
+    }
+    // Layout Web Worker — offloads physics simulation from the main thread.
+    // For small graphs (< WORKER_THRESHOLD nodes), runs on main thread to avoid overhead.
+    const WORKER_THRESHOLD = 150;
+    let layoutWorker = null;
+    let useWorker = false;
+    function getWorker() {
+        if (!layoutWorker) {
+            try {
+                layoutWorker = new Worker(new URL("./layout-worker.js", import.meta.url), { type: "module" });
+                layoutWorker.onmessage = onWorkerMessage;
+                layoutWorker.onerror = () => {
+                    // Worker failed to load — fall back to main-thread layout
+                    useWorker = false;
+                    layoutWorker = null;
+                    simulate();
+                };
+            }
+            catch {
+                useWorker = false;
+                return null;
+            }
+        }
+        return layoutWorker;
+    }
+    function onWorkerMessage(e) {
+        const msg = e.data;
+        if (msg.type === "tick" && state) {
+            const positions = msg.positions;
+            const nodes = state.nodes;
+            for (let i = 0; i < nodes.length; i++) {
+                nodes[i].x = positions[i * 4];
+                nodes[i].y = positions[i * 4 + 1];
+                nodes[i].vx = positions[i * 4 + 2];
+                nodes[i].vy = positions[i * 4 + 3];
+            }
+            alpha = msg.alpha;
+            nodeHash.rebuild(nodes);
+            render();
+        }
+        if (msg.type === "settled") {
+            alpha = 0;
+            if (walkMode && walkTrail.length > 0 && !walkAnimFrame) {
+                walkAnimFrame = requestAnimationFrame(walkAnimate);
+            }
+        }
+    }
+    // Scene cache — avoids full redraws during walk pulse animation.
+    // When the graph is settled, we snapshot the rendered scene (minus walk effects)
+    // to an OffscreenCanvas. Walk animate then composites cache + draws pulse overlay.
+    let sceneCache = null;
+    let sceneCacheCtx = null;
+    let sceneCacheDirty = true;
+    function invalidateSceneCache() {
+        sceneCacheDirty = true;
+    }
     // Pan animation state
     let panTarget = null;
     let panStart = null;
@@ -45,7 +121,8 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
     function resize() {
         canvas.width = canvas.clientWidth * dpr;
         canvas.height = canvas.clientHeight * dpr;
-        render();
+        invalidateSceneCache();
+        requestRedraw();
     }
     const observer = new ResizeObserver(resize);
     observer.observe(container);
@@ -62,23 +139,95 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         if (!state)
             return null;
         const [wx, wy] = screenToWorld(sx, sy);
-        // Iterate in reverse so topmost (last drawn) nodes are hit first
-        for (let i = state.nodes.length - 1; i >= 0; i--) {
-            const node = state.nodes[i];
-            const dx = wx - node.x;
-            const dy = wy - node.y;
-            if (dx * dx + dy * dy <= NODE_RADIUS * NODE_RADIUS) {
-                return node;
+        return nodeHash.query(wx, wy, NODE_RADIUS);
+    }
+    // --- Rendering ---
+    /** Draw only walk pulse effects (edges + node glows) + minimap on top of cached scene. */
+    function renderWalkOverlay() {
+        if (!state)
+            return;
+        pulsePhase += walkCfg.pulseSpeed;
+        const walkTrailSet = new Set(walkTrail);
+        ctx.save();
+        ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        // Composite cached scene
+        if (sceneCache) {
+            ctx.clearRect(0, 0, canvas.clientWidth, canvas.clientHeight);
+            ctx.drawImage(sceneCache, 0, 0, canvas.clientWidth, canvas.clientHeight);
+        }
+        ctx.save();
+        ctx.translate(-camera.x * camera.scale, -camera.y * camera.scale);
+        ctx.scale(camera.scale, camera.scale);
+        // Walk edge pulse — redraw only walk trail edges
+        const walkEdgeColor = cssVar("--canvas-walk-edge") || "#1a1a1a";
+        const walkLines = [];
+        for (const edge of state.edges) {
+            if (!walkTrailSet.has(edge.sourceId) || !walkTrailSet.has(edge.targetId))
+                continue;
+            if (edge.sourceId === edge.targetId)
+                continue;
+            const source = state.nodeMap.get(edge.sourceId);
+            const target = state.nodeMap.get(edge.targetId);
+            if (!source || !target)
+                continue;
+            walkLines.push(source.x, source.y, target.x, target.y);
+        }
+        if (walkLines.length > 0) {
+            ctx.beginPath();
+            for (let i = 0; i < walkLines.length; i += 4) {
+                ctx.moveTo(walkLines[i], walkLines[i + 1]);
+                ctx.lineTo(walkLines[i + 2], walkLines[i + 3]);
             }
+            ctx.strokeStyle = walkEdgeColor;
+            ctx.lineWidth = 3;
+            ctx.globalAlpha = 0.5 + 0.5 * Math.sin(pulsePhase);
+            ctx.stroke();
+            ctx.globalAlpha = 1;
+        }
+        // Walk node glows
+        const r = camera.scale < lod.smallNodes ? NODE_RADIUS * 0.5 : NODE_RADIUS;
+        const accent = cssVar("--accent") || "#d4a27f";
+        for (const nodeId of walkTrail) {
+            const node = state.nodeMap.get(nodeId);
+            if (!node)
+                continue;
+            if (!isInViewport(node.x, node.y, camera, canvas.clientWidth, canvas.clientHeight))
+                continue;
+            const isCurrent = nodeId === walkTrail[walkTrail.length - 1];
+            const pulse = 0.5 + 0.5 * Math.sin(pulsePhase);
+            ctx.strokeStyle = accent;
+            ctx.lineWidth = isCurrent ? 3 : 2;
+            ctx.globalAlpha = isCurrent ? 0.5 + 0.5 * pulse : 0.3 + 0.4 * pulse;
+            ctx.beginPath();
+            ctx.arc(node.x, node.y, r + (isCurrent ? 6 : 4), 0, Math.PI * 2);
+            ctx.stroke();
         }
-        return null;
+        ctx.globalAlpha = 1;
+        ctx.restore();
+        // Minimap
+        if (showMinimap && state.nodes.length > 1) {
+            drawMinimap();
+        }
+        ctx.restore();
     }
-    // --- Rendering ---
     function render() {
         if (!state) {
             ctx.clearRect(0, 0, canvas.width, canvas.height);
             return;
         }
+        // Fast path: walk-only animation with valid scene cache
+        if (!sceneCacheDirty && sceneCache && walkMode && walkTrail.length > 0 && alpha < ALPHA_MIN) {
+            renderWalkOverlay();
+            return;
+        }
+        // Determine if we should cache the scene (settled + walk mode active).
+        // When caching, we skip walk effects so the cache is a clean base layer.
+        const shouldCache = alpha < ALPHA_MIN && walkMode && walkTrail.length > 0;
+        // Advance pulse animation for walk mode
+        if (walkMode && walkTrail.length > 0) {
+            pulsePhase += walkCfg.pulseSpeed;
+        }
+        const walkTrailSet = (walkMode && !shouldCache) ? new Set(walkTrail) : null;
         // Read theme colors from CSS variables each frame
         const edgeColor = cssVar("--canvas-edge");
         const edgeHighlight = cssVar("--canvas-edge-highlight");
@@ -145,117 +294,236 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
                 ctx.globalAlpha = 1;
             }
         }
-        // Draw edges
-        if (showEdges)
+        // Pre-compute neighbor set for selected nodes (avoids O(n×e) scan)
+        let neighborIds = null;
+        if (selectedNodeIds.size > 0) {
+            neighborIds = new Set();
+            for (const edge of state.edges) {
+                if (selectedNodeIds.has(edge.sourceId))
+                    neighborIds.add(edge.targetId);
+                if (selectedNodeIds.has(edge.targetId))
+                    neighborIds.add(edge.sourceId);
+            }
+        }
+        const accent = cssVar("--accent") || "#d4a27f";
+        const walkEdgeColor = cssVar("--canvas-walk-edge") || "#1a1a1a";
+        const drawArrows = camera.scale >= lod.hideArrows;
+        const drawEdgeLabelsThisFrame = showEdgeLabels && camera.scale >= lod.hideEdgeLabels;
+        // Draw edges — batched by visual state to minimize Canvas state changes
+        if (showEdges) {
+            // Classify edges into batches by visual style
+            const normalBatch = [];
+            const highlightBatch = [];
+            const dimBatch = [];
+            const walkBatch = [];
+            const pathBatch = [];
+            const deferred = [];
             for (const edge of state.edges) {
                 const source = state.nodeMap.get(edge.sourceId);
                 const target = state.nodeMap.get(edge.targetId);
                 if (!source || !target)
                     continue;
-                // Viewport culling — skip if both endpoints are off-screen
+                // Viewport culling
                 if (!isInViewport(source.x, source.y, camera, canvas.clientWidth, canvas.clientHeight, 200) &&
                     !isInViewport(target.x, target.y, camera, canvas.clientWidth, canvas.clientHeight, 200))
                     continue;
                 const sourceMatch = filteredNodeIds === null || filteredNodeIds.has(edge.sourceId);
                 const targetMatch = filteredNodeIds === null || filteredNodeIds.has(edge.targetId);
                 const bothMatch = sourceMatch && targetMatch;
-                // Hide edges where neither endpoint matches the filter
                 if (filteredNodeIds !== null && !sourceMatch && !targetMatch)
                     continue;
                 const isConnected = selectedNodeIds.size > 0 &&
                     (selectedNodeIds.has(edge.sourceId) || selectedNodeIds.has(edge.targetId));
                 const highlighted = isConnected || (filteredNodeIds !== null && bothMatch);
                 const edgeDimmed = filteredNodeIds !== null && !bothMatch;
+                const isWalkEdge = walkTrailSet !== null && walkTrailSet.has(edge.sourceId) && walkTrailSet.has(edge.targetId);
+                const fullEdge = highlightedPath ? lastLoadedData?.edges.find(e => (e.sourceId === edge.sourceId && e.targetId === edge.targetId) ||
+                    (e.targetId === edge.sourceId && e.sourceId === edge.targetId)) : null;
+                const isPathEdge = !!(highlightedPath && fullEdge && highlightedPath.edgeIds.has(fullEdge.id));
                 // Self-loop
                 if (edge.sourceId === edge.targetId) {
                     drawSelfLoop(source, edge.type, highlighted, edgeColor, edgeHighlight, edgeLabel, edgeLabelHighlight);
                     continue;
                 }
-                // Line
+                // Sort into batch by visual state
+                const batch = isPathEdge ? pathBatch
+                    : isWalkEdge ? walkBatch
+                        : highlighted ? highlightBatch
+                            : edgeDimmed ? dimBatch
+                                : normalBatch;
+                batch.push(source.x, source.y, target.x, target.y);
+                // Queue deferred work (arrowheads, labels)
+                if (drawArrows || drawEdgeLabelsThisFrame) {
+                    deferred.push({ sx: source.x, sy: source.y, tx: target.x, ty: target.y, type: edge.type, highlighted, edgeDimmed, isPathEdge, isWalkEdge });
+                }
+            }
+            // Stroke each batch with one beginPath/stroke pair
+            const normalWidth = drawArrows ? 1.5 : 1;
+            const highlightWidth = drawArrows ? 2.5 : 1;
+            const batches = [
+                { lines: normalBatch, color: edgeColor, width: normalWidth, alpha: 1 },
+                { lines: dimBatch, color: edgeDimColor, width: normalWidth, alpha: 1 },
+                { lines: highlightBatch, color: edgeHighlight, width: highlightWidth, alpha: 1 },
+                { lines: pathBatch, color: accent, width: 3, alpha: 1 },
+                { lines: walkBatch, color: walkEdgeColor, width: 3, alpha: 0.5 + 0.5 * Math.sin(pulsePhase) },
+            ];
+            for (const b of batches) {
+                if (b.lines.length === 0)
+                    continue;
                 ctx.beginPath();
-                ctx.moveTo(source.x, source.y);
-                ctx.lineTo(target.x, target.y);
-                ctx.strokeStyle = highlighted
-                    ? edgeHighlight
-                    : edgeDimmed
-                        ? edgeDimColor
-                        : edgeColor;
-                ctx.lineWidth = camera.scale < lod.hideArrows ? 1 : highlighted ? 2.5 : 1.5;
+                for (let i = 0; i < b.lines.length; i += 4) {
+                    ctx.moveTo(b.lines[i], b.lines[i + 1]);
+                    ctx.lineTo(b.lines[i + 2], b.lines[i + 3]);
+                }
+                ctx.strokeStyle = b.color;
+                ctx.lineWidth = b.width;
+                ctx.globalAlpha = b.alpha;
                 ctx.stroke();
-                // Arrowhead
-                if (camera.scale >= lod.hideArrows) {
-                    drawArrowhead(source.x, source.y, target.x, target.y, highlighted, arrowColor, arrowHighlight);
+            }
+            ctx.globalAlpha = 1;
+            // Draw arrowheads and labels (can't batch — each needs individual positioning)
+            for (const d of deferred) {
+                if (drawArrows) {
+                    drawArrowhead(d.sx, d.sy, d.tx, d.ty, d.highlighted || d.isPathEdge, arrowColor, arrowHighlight);
                 }
-                // Edge label at midpoint
-                if (showEdgeLabels && camera.scale >= lod.hideEdgeLabels) {
-                    const mx = (source.x + target.x) / 2;
-                    const my = (source.y + target.y) / 2;
-                    ctx.fillStyle = highlighted
+                if (drawEdgeLabelsThisFrame) {
+                    const mx = (d.sx + d.tx) / 2;
+                    const my = (d.sy + d.ty) / 2;
+                    ctx.fillStyle = d.highlighted
                         ? edgeLabelHighlight
-                        : edgeDimmed
+                        : d.edgeDimmed
                             ? edgeLabelDim
                             : edgeLabel;
                     ctx.font = "9px system-ui, sans-serif";
                     ctx.textAlign = "center";
                     ctx.textBaseline = "bottom";
-                    ctx.fillText(edge.type, mx, my - 4);
+                    ctx.fillText(d.type, mx, my - 4);
                 }
             }
-        // Draw nodes
-        for (const node of state.nodes) {
-            // Viewport culling
-            if (!isInViewport(node.x, node.y, camera, canvas.clientWidth, canvas.clientHeight))
-                continue;
-            const color = getColor(node.type);
-            const isSelected = selectedNodeIds.has(node.id);
-            const isNeighbor = selectedNodeIds.size > 0 &&
-                state.edges.some((e) => (selectedNodeIds.has(e.sourceId) && e.targetId === node.id) ||
-                    (selectedNodeIds.has(e.targetId) && e.sourceId === node.id));
-            const filteredOut = filteredNodeIds !== null && !filteredNodeIds.has(node.id);
-            const dimmed = filteredOut ||
-                (selectedNodeIds.size > 0 && !isSelected && !isNeighbor);
-            const r = camera.scale < lod.smallNodes ? NODE_RADIUS * 0.5 : NODE_RADIUS;
-            // Glow for selected node
-            if (isSelected) {
-                ctx.save();
-                ctx.shadowColor = color;
-                ctx.shadowBlur = 20;
+        }
+        // Entrance animation — fade/scale nodes in over ENTRANCE_DURATION ms
+        const entranceElapsed = performance.now() - loadTime;
+        const entranceT = Math.min(1, entranceElapsed / ENTRANCE_DURATION);
+        const entranceProgress = 1 - (1 - entranceT) * (1 - entranceT); // ease-out quad
+        const isEntering = entranceT < 1;
+        // Draw nodes — skip entirely at extreme zoom-out (hulls-only mode)
+        const hullsOnlyMode = camera.scale < lod.hullsOnly;
+        const dotMode = !hullsOnlyMode && camera.scale < lod.dotNodes;
+        if (!hullsOnlyMode)
+            for (const node of state.nodes) {
+                // Viewport culling
+                if (!isInViewport(node.x, node.y, camera, canvas.clientWidth, canvas.clientHeight))
+                    continue;
+                const color = getColor(node.type);
+                // Dot mode — render as single-pixel colored dots, skip all decorations
+                if (dotMode) {
+                    const filteredOut = filteredNodeIds !== null && !filteredNodeIds.has(node.id);
+                    ctx.fillStyle = color;
+                    const dotAlpha = filteredOut ? 0.1 : 0.8;
+                    ctx.globalAlpha = isEntering ? dotAlpha * entranceProgress : dotAlpha;
+                    ctx.fillRect(node.x - 2, node.y - 2, 4, 4);
+                    continue;
+                }
+                const isSelected = selectedNodeIds.has(node.id);
+                const isNeighbor = neighborIds !== null && neighborIds.has(node.id);
+                const filteredOut = filteredNodeIds !== null && !filteredNodeIds.has(node.id);
+                const dimmed = filteredOut ||
+                    (selectedNodeIds.size > 0 && !isSelected && !isNeighbor);
+                const baseR = camera.scale < lod.smallNodes ? NODE_RADIUS * 0.5 : NODE_RADIUS;
+                const r = isEntering ? baseR * entranceProgress : baseR;
+                // Walk trail effect — all visited nodes pulse together
+                if (walkTrailSet?.has(node.id)) {
+                    const isCurrent = walkTrail[walkTrail.length - 1] === node.id;
+                    const pulse = 0.5 + 0.5 * Math.sin(pulsePhase);
+                    const accent = cssVar("--accent") || "#d4a27f";
+                    ctx.save();
+                    ctx.strokeStyle = accent;
+                    ctx.lineWidth = isCurrent ? 3 : 2;
+                    ctx.globalAlpha = isCurrent ? 0.5 + 0.5 * pulse : 0.3 + 0.4 * pulse;
+                    ctx.beginPath();
+                    ctx.arc(node.x, node.y, r + (isCurrent ? 6 : 4), 0, Math.PI * 2);
+                    ctx.stroke();
+                    ctx.restore();
+                }
+                // Glow for selected node
+                if (isSelected) {
+                    ctx.save();
+                    ctx.shadowColor = color;
+                    ctx.shadowBlur = 20;
+                    ctx.beginPath();
+                    ctx.arc(node.x, node.y, r + 3, 0, Math.PI * 2);
+                    ctx.fillStyle = color;
+                    ctx.globalAlpha = 0.3;
+                    ctx.fill();
+                    ctx.restore();
+                }
+                // Circle
                 ctx.beginPath();
-                ctx.arc(node.x, node.y, r + 3, 0, Math.PI * 2);
+                ctx.arc(node.x, node.y, r, 0, Math.PI * 2);
                 ctx.fillStyle = color;
-                ctx.globalAlpha = 0.3;
+                const baseAlpha = filteredOut ? 0.1 : dimmed ? 0.3 : 1;
+                ctx.globalAlpha = isEntering ? baseAlpha * entranceProgress : baseAlpha;
                 ctx.fill();
-                ctx.restore();
-            }
-            // Circle
-            ctx.beginPath();
-            ctx.arc(node.x, node.y, r, 0, Math.PI * 2);
-            ctx.fillStyle = color;
-            ctx.globalAlpha = filteredOut ? 0.1 : dimmed ? 0.3 : 1;
-            ctx.fill();
-            ctx.strokeStyle = isSelected ? selectionBorder : nodeBorder;
-            ctx.lineWidth = isSelected ? 3 : 1.5;
-            ctx.stroke();
-            // Label below
-            if (camera.scale >= lod.hideLabels) {
-                const label = node.label.length > 24 ? node.label.slice(0, 22) + "..." : node.label;
-                ctx.fillStyle = dimmed ? nodeLabelDim : nodeLabel;
-                ctx.font = "11px system-ui, sans-serif";
-                ctx.textAlign = "center";
-                ctx.textBaseline = "top";
-                ctx.fillText(label, node.x, node.y + r + 4);
-            }
-            // Type badge above
-            if (camera.scale >= lod.hideBadges) {
-                ctx.fillStyle = dimmed ? typeBadgeDim : typeBadge;
-                ctx.font = "9px system-ui, sans-serif";
-                ctx.textBaseline = "bottom";
-                ctx.fillText(node.type, node.x, node.y - r - 3);
+                ctx.strokeStyle = isSelected ? selectionBorder : nodeBorder;
+                ctx.lineWidth = isSelected ? 3 : 1.5;
+                ctx.stroke();
+                ctx.globalAlpha = 1;
+                // Highlighted path glow
+                if (highlightedPath && highlightedPath.nodeIds.has(node.id) && !isSelected) {
+                    ctx.save();
+                    ctx.shadowColor = cssVar("--accent") || "#d4a27f";
+                    ctx.shadowBlur = 15;
+                    ctx.beginPath();
+                    ctx.arc(node.x, node.y, r + 2, 0, Math.PI * 2);
+                    ctx.strokeStyle = cssVar("--accent") || "#d4a27f";
+                    ctx.globalAlpha = 0.5;
+                    ctx.lineWidth = 2;
+                    ctx.stroke();
+                    ctx.restore();
+                }
+                // Star indicator for starred nodes
+                const originalNode = lastLoadedData?.nodes.find(n => n.id === node.id);
+                const isStarred = originalNode?.properties?._starred === true;
+                if (isStarred) {
+                    ctx.fillStyle = "#ffd700";
+                    ctx.font = "10px system-ui, sans-serif";
+                    ctx.textAlign = "left";
+                    ctx.textBaseline = "bottom";
+                    ctx.fillText("\u2605", node.x + r - 2, node.y - r + 2);
+                }
+                // Label below (cached offscreen)
+                if (camera.scale >= lod.hideLabels) {
+                    const label = node.label.length > 24 ? node.label.slice(0, 22) + "..." : node.label;
+                    const labelColor = dimmed ? nodeLabelDim : nodeLabel;
+                    drawCachedLabel(ctx, label, node.x, node.y + r + 4, "11px system-ui, sans-serif", labelColor, "top");
+                }
+                // Type badge above (cached offscreen)
+                if (camera.scale >= lod.hideBadges) {
+                    const badgeColor = dimmed ? typeBadgeDim : typeBadge;
+                    drawCachedLabel(ctx, node.type, node.x, node.y - r - 3, "9px system-ui, sans-serif", badgeColor, "bottom");
+                }
+                ctx.globalAlpha = 1;
             }
-            ctx.globalAlpha = 1;
-        }
         ctx.restore();
         ctx.restore();
+        // Snapshot scene to cache BEFORE walk overlay and minimap.
+        // The cache contains the clean scene (hulls + edges + nodes) without walk effects.
+        if (shouldCache) {
+            const w = canvas.width;
+            const h = canvas.height;
+            if (!sceneCache || sceneCache.width !== w || sceneCache.height !== h) {
+                sceneCache = new OffscreenCanvas(w, h);
+                sceneCacheCtx = sceneCache.getContext("2d");
+            }
+            if (sceneCacheCtx) {
+                sceneCacheCtx.clearRect(0, 0, w, h);
+                sceneCacheCtx.drawImage(canvas, 0, 0);
+                sceneCacheDirty = false;
+            }
+            // Now draw walk effects + minimap on top for this frame
+            renderWalkOverlay();
+            return;
+        }
         // Minimap
         if (showMinimap && state.nodes.length > 1) {
             drawMinimap();
@@ -376,6 +644,7 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         const ease = 1 - Math.pow(1 - t, 3);
         camera.x = panStart.x + (panTarget.x - panStart.x) * ease;
         camera.y = panStart.y + (panTarget.y - panStart.y) * ease;
+        invalidateSceneCache();
         render();
         if (t < 1) {
             requestAnimationFrame(animatePan);
@@ -385,10 +654,49 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             panStart = null;
         }
     }
+    let walkAnimFrame = 0;
+    function walkAnimate() {
+        if (!walkMode || walkTrail.length === 0) {
+            walkAnimFrame = 0;
+            return;
+        }
+        render();
+        walkAnimFrame = requestAnimationFrame(walkAnimate);
+    }
+    function fitToNodes() {
+        if (!state || state.nodes.length === 0)
+            return;
+        let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+        for (const n of state.nodes) {
+            if (n.x < minX)
+                minX = n.x;
+            if (n.y < minY)
+                minY = n.y;
+            if (n.x > maxX)
+                maxX = n.x;
+            if (n.y > maxY)
+                maxY = n.y;
+        }
+        const pad = NODE_RADIUS * 4;
+        const graphW = (maxX - minX) + pad * 2;
+        const graphH = (maxY - minY) + pad * 2;
+        const scaleX = canvas.clientWidth / Math.max(graphW, 1);
+        const scaleY = canvas.clientHeight / Math.max(graphH, 1);
+        camera.scale = Math.min(scaleX, scaleY, 2);
+        camera.x = (minX + maxX) / 2 - canvas.clientWidth / (2 * camera.scale);
+        camera.y = (minY + maxY) / 2 - canvas.clientHeight / (2 * camera.scale);
+        requestRedraw();
+    }
     function simulate() {
-        if (!state || alpha < ALPHA_MIN)
+        if (!state || alpha < ALPHA_MIN) {
+            // Start walk animation loop if simulation stopped but walk mode is active
+            if (walkMode && walkTrail.length > 0 && !walkAnimFrame) {
+                walkAnimFrame = requestAnimationFrame(walkAnimate);
+            }
             return;
+        }
         alpha = tick(state, alpha);
+        nodeHash.rebuild(state.nodes);
         render();
         animFrame = requestAnimationFrame(simulate);
     }
@@ -408,13 +716,13 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             return;
         const dx = e.clientX - lastX;
         const dy = e.clientY - lastY;
-        if (Math.abs(dx) > 2 || Math.abs(dy) > 2)
+        if (Math.abs(dx) > 5 || Math.abs(dy) > 5)
             didDrag = true;
         camera.x -= dx / camera.scale;
         camera.y -= dy / camera.scale;
         lastX = e.clientX;
         lastY = e.clientY;
-        render();
+        requestRedraw();
     });
     canvas.addEventListener("mouseup", (e) => {
         dragging = false;
@@ -426,6 +734,71 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         const my = e.clientY - rect.top;
         const hit = nodeAtScreen(mx, my);
         const multiSelect = e.ctrlKey || e.metaKey;
+        if (walkMode && focusSeedIds && hit && state) {
+            // Walk mode: find path from current position to clicked node
+            const currentId = walkTrail.length > 0 ? walkTrail[walkTrail.length - 1] : focusSeedIds[0];
+            // BFS in the current subgraph to find path
+            const visited = new Set([currentId]);
+            const queue = [{ id: currentId, path: [currentId] }];
+            let pathToTarget = null;
+            while (queue.length > 0) {
+                const { id, path } = queue.shift();
+                if (id === hit.id) {
+                    pathToTarget = path;
+                    break;
+                }
+                for (const edge of state.edges) {
+                    let neighbor = null;
+                    if (edge.sourceId === id)
+                        neighbor = edge.targetId;
+                    else if (edge.targetId === id)
+                        neighbor = edge.sourceId;
+                    if (neighbor && !visited.has(neighbor)) {
+                        visited.add(neighbor);
+                        queue.push({ id: neighbor, path: [...path, neighbor] });
+                    }
+                }
+            }
+            // No path found — node is unreachable, ignore click
+            if (!pathToTarget)
+                return;
+            // Add all intermediate nodes to the trail (skip first since it's already the current position)
+            for (const id of pathToTarget.slice(1)) {
+                if (!walkTrail.includes(id))
+                    walkTrail.push(id);
+            }
+            focusSeedIds = [hit.id];
+            const walkHops = Math.max(1, focusHops);
+            focusHops = walkHops;
+            const subgraph = extractSubgraph(lastLoadedData, [hit.id], walkHops);
+            cancelAnimationFrame(animFrame);
+            if (layoutWorker)
+                layoutWorker.postMessage({ type: "stop" });
+            state = createLayout(subgraph);
+            nodeHash.rebuild(state.nodes);
+            alpha = 1;
+            selectedNodeIds = new Set([hit.id]);
+            filteredNodeIds = null;
+            camera = { x: 0, y: 0, scale: 1 };
+            useWorker = subgraph.nodes.length >= WORKER_THRESHOLD;
+            const w = useWorker ? getWorker() : null;
+            if (w) {
+                w.postMessage({ type: "start", data: subgraph });
+            }
+            else {
+                useWorker = false;
+                simulate();
+            }
+            // Center after physics settle
+            setTimeout(() => {
+                if (!state)
+                    return;
+                fitToNodes();
+            }, 300);
+            onFocusChange?.({ seedNodeIds: [hit.id], hops: walkHops, totalNodes: subgraph.nodes.length });
+            onNodeClick?.([hit.id]);
+            return; // skip normal selection
+        }
         if (hit) {
             if (multiSelect) {
                 // Toggle node in/out of multi-selection
@@ -453,7 +826,7 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             selectedNodeIds.clear();
             onNodeClick?.(null);
         }
-        render();
+        requestRedraw();
     });
     canvas.addEventListener("mouseleave", () => {
         dragging = false;
@@ -473,7 +846,7 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         camera.scale = Math.max(nav.zoomMin, Math.min(nav.zoomMax, camera.scale * factor));
         camera.x = wx - mx / camera.scale;
         camera.y = wy - my / camera.scale;
-        render();
+        requestRedraw();
     }, { passive: false });
     // --- Interaction: Touch (pinch zoom + drag) ---
     let touches = [];
@@ -504,7 +877,7 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             const dist = touchDistance(current[0], current[1]);
             const ratio = dist / initialPinchDist;
             camera.scale = Math.max(nav.zoomMin, Math.min(nav.zoomMax, initialPinchScale * ratio));
-            render();
+            requestRedraw();
         }
         else if (current.length === 1) {
             const dx = current[0].clientX - lastX;
@@ -517,7 +890,7 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             camera.y -= dy / camera.scale;
             lastX = current[0].clientX;
             lastY = current[0].clientY;
-            render();
+            requestRedraw();
         }
         touches = current;
     }, { passive: false });
@@ -545,7 +918,7 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             selectedNodeIds.clear();
             onNodeClick?.(null);
         }
-        render();
+        requestRedraw();
     }, { passive: false });
     // Prevent Safari page-level pinch zoom on the canvas
     canvas.addEventListener("gesturestart", (e) => e.preventDefault());
@@ -569,7 +942,7 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         camera.scale = Math.min(nav.zoomMax, camera.scale * nav.zoomFactor);
         camera.x = wx - cx / camera.scale;
         camera.y = wy - cy / camera.scale;
-        render();
+        requestRedraw();
     });
     const zoomOutBtn = document.createElement("button");
     zoomOutBtn.className = "zoom-btn";
@@ -582,7 +955,7 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         camera.scale = Math.max(nav.zoomMin, camera.scale / nav.zoomFactor);
         camera.x = wx - cx / camera.scale;
         camera.y = wy - cy / camera.scale;
-        render();
+        requestRedraw();
     });
     const zoomResetBtn = document.createElement("button");
     zoomResetBtn.className = "zoom-btn";
@@ -609,22 +982,77 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             camera.x = cx - canvas.clientWidth / 2;
             camera.y = cy - canvas.clientHeight / 2;
         }
-        render();
+        requestRedraw();
     });
     zoomControls.appendChild(zoomInBtn);
     zoomControls.appendChild(zoomResetBtn);
     zoomControls.appendChild(zoomOutBtn);
     container.appendChild(zoomControls);
+    // --- Hover tooltip ---
+    const tooltip = document.createElement("div");
+    tooltip.className = "node-tooltip";
+    tooltip.style.display = "none";
+    container.appendChild(tooltip);
+    let hoverNodeId = null;
+    let hoverTimeout = null;
+    canvas.addEventListener("mousemove", (e) => {
+        if (dragging) {
+            if (tooltip.style.display !== "none") {
+                tooltip.style.display = "none";
+                hoverNodeId = null;
+            }
+            return;
+        }
+        const rect = canvas.getBoundingClientRect();
+        const mx = e.clientX - rect.left;
+        const my = e.clientY - rect.top;
+        const hit = nodeAtScreen(mx, my);
+        const hitId = hit?.id ?? null;
+        if (hitId !== hoverNodeId) {
+            hoverNodeId = hitId;
+            tooltip.style.display = "none";
+            if (hoverTimeout)
+                clearTimeout(hoverTimeout);
+            hoverTimeout = null;
+            if (hitId && hit) {
+                hoverTimeout = setTimeout(() => {
+                    if (!state || !lastLoadedData)
+                        return;
+                    const edgeCount = state.edges.filter((edge) => edge.sourceId === hitId || edge.targetId === hitId).length;
+                    tooltip.textContent = `${hit.label} · ${hit.type} · ${edgeCount} edge${edgeCount !== 1 ? "s" : ""}`;
+                    tooltip.style.left = `${e.clientX - rect.left + 12}px`;
+                    tooltip.style.top = `${e.clientY - rect.top - 8}px`;
+                    tooltip.style.display = "block";
+                }, 200);
+            }
+        }
+        else if (hitId && tooltip.style.display === "block") {
+            tooltip.style.left = `${e.clientX - rect.left + 12}px`;
+            tooltip.style.top = `${e.clientY - rect.top - 8}px`;
+        }
+    });
+    canvas.addEventListener("mouseleave", () => {
+        tooltip.style.display = "none";
+        hoverNodeId = null;
+        if (hoverTimeout)
+            clearTimeout(hoverTimeout);
+        hoverTimeout = null;
+    });
     // --- Public API ---
     return {
         loadGraph(data) {
             cancelAnimationFrame(animFrame);
+            if (layoutWorker)
+                layoutWorker.postMessage({ type: "stop" });
+            clearLabelCache();
             lastLoadedData = data;
             // Exit any active focus when full graph reloads
             focusSeedIds = null;
             savedFullState = null;
             savedFullCamera = null;
+            loadTime = performance.now();
             state = createLayout(data);
+            nodeHash.rebuild(state.nodes);
             alpha = 1;
             selectedNodeIds = new Set();
             filteredNodeIds = null;
@@ -649,11 +1077,20 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
                 camera.x = cx - w / 2;
                 camera.y = cy - h / 2;
             }
-            simulate();
+            // Use worker for large graphs, main thread for small ones
+            useWorker = data.nodes.length >= WORKER_THRESHOLD;
+            const w = useWorker ? getWorker() : null;
+            if (w) {
+                w.postMessage({ type: "start", data });
+            }
+            else {
+                useWorker = false;
+                simulate();
+            }
         },
         setFilteredNodeIds(ids) {
             filteredNodeIds = ids;
-            render();
+            requestRedraw();
         },
         panToNode(nodeId) {
             this.panToNodes([nodeId]);
@@ -705,45 +1142,27 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         },
         setEdges(visible) {
             showEdges = visible;
-            render();
+            requestRedraw();
         },
         setEdgeLabels(visible) {
             showEdgeLabels = visible;
-            render();
+            requestRedraw();
         },
         setTypeHulls(visible) {
             showTypeHulls = visible;
-            render();
+            requestRedraw();
         },
         setMinimap(visible) {
             showMinimap = visible;
-            render();
+            requestRedraw();
         },
         centerView() {
-            if (!state)
-                return;
-            camera = { x: 0, y: 0, scale: 1 };
-            if (state.nodes.length > 0) {
-                let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-                for (const n of state.nodes) {
-                    if (n.x < minX)
-                        minX = n.x;
-                    if (n.y < minY)
-                        minY = n.y;
-                    if (n.x > maxX)
-                        maxX = n.x;
-                    if (n.y > maxY)
-                        maxY = n.y;
-                }
-                camera.x = (minX + maxX) / 2 - canvas.clientWidth / 2;
-                camera.y = (minY + maxY) / 2 - canvas.clientHeight / 2;
-            }
-            render();
+            fitToNodes();
         },
         panBy(dx, dy) {
             camera.x += dx / camera.scale;
             camera.y += dy / camera.scale;
-            render();
+            requestRedraw();
         },
         zoomBy(factor) {
             const cx = canvas.clientWidth / 2;
@@ -752,12 +1171,17 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             camera.scale = Math.max(nav.zoomMin, Math.min(nav.zoomMax, camera.scale * factor));
             camera.x = wx - cx / camera.scale;
             camera.y = wy - cy / camera.scale;
-            render();
+            requestRedraw();
         },
         reheat() {
-            alpha = 0.5;
-            cancelAnimationFrame(animFrame);
-            simulate();
+            if (useWorker && layoutWorker) {
+                layoutWorker.postMessage({ type: "params", params: getLayoutParams() });
+            }
+            else {
+                alpha = 0.5;
+                cancelAnimationFrame(animFrame);
+                simulate();
+            }
         },
         exportImage(format) {
             if (!state)
@@ -800,30 +1224,30 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             focusHops = hops;
             const subgraph = extractSubgraph(lastLoadedData, seedNodeIds, hops);
             cancelAnimationFrame(animFrame);
+            if (layoutWorker)
+                layoutWorker.postMessage({ type: "stop" });
             state = createLayout(subgraph);
+            nodeHash.rebuild(state.nodes);
             alpha = 1;
             selectedNodeIds = new Set(seedNodeIds);
             filteredNodeIds = null;
-            // Center camera
+            // Start simulation, then center after layout settles
             camera = { x: 0, y: 0, scale: 1 };
-            if (state.nodes.length > 0) {
-                let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-                for (const n of state.nodes) {
-                    if (n.x < minX)
-                        minX = n.x;
-                    if (n.y < minY)
-                        minY = n.y;
-                    if (n.x > maxX)
-                        maxX = n.x;
-                    if (n.y > maxY)
-                        maxY = n.y;
-                }
-                const cx = (minX + maxX) / 2;
-                const cy = (minY + maxY) / 2;
-                camera.x = cx - canvas.clientWidth / 2;
-                camera.y = cy - canvas.clientHeight / 2;
+            useWorker = subgraph.nodes.length >= WORKER_THRESHOLD;
+            const w = useWorker ? getWorker() : null;
+            if (w) {
+                w.postMessage({ type: "start", data: subgraph });
             }
-            simulate();
+            else {
+                useWorker = false;
+                simulate();
+            }
+            // Center + fit after physics settle
+            setTimeout(() => {
+                if (!state || !focusSeedIds)
+                    return;
+                fitToNodes();
+            }, 300);
             onFocusChange?.({
                 seedNodeIds,
                 hops,
@@ -834,14 +1258,17 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             if (!focusSeedIds || !savedFullState)
                 return;
             cancelAnimationFrame(animFrame);
+            if (layoutWorker)
+                layoutWorker.postMessage({ type: "stop" });
             state = savedFullState;
+            nodeHash.rebuild(state.nodes);
             camera = savedFullCamera ?? { x: 0, y: 0, scale: 1 };
             focusSeedIds = null;
             savedFullState = null;
             savedFullCamera = null;
             selectedNodeIds = new Set();
             filteredNodeIds = null;
-            render();
+            requestRedraw();
             onFocusChange?.(null);
         },
         isFocused() {
@@ -856,6 +1283,83 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
                 totalNodes: state.nodes.length,
             };
         },
+        findPath(sourceId, targetId) {
+            if (!state)
+                return null;
+            const visited = new Set([sourceId]);
+            const queue = [
+                { nodeId: sourceId, path: [sourceId], edges: [] }
+            ];
+            while (queue.length > 0) {
+                const { nodeId, path, edges } = queue.shift();
+                if (nodeId === targetId)
+                    return { nodeIds: path, edgeIds: edges };
+                for (const edge of state.edges) {
+                    let neighbor = null;
+                    if (edge.sourceId === nodeId)
+                        neighbor = edge.targetId;
+                    else if (edge.targetId === nodeId)
+                        neighbor = edge.sourceId;
+                    if (neighbor && !visited.has(neighbor)) {
+                        visited.add(neighbor);
+                        const fullEdge = lastLoadedData?.edges.find(e => (e.sourceId === edge.sourceId && e.targetId === edge.targetId) ||
+                            (e.targetId === edge.sourceId && e.sourceId === edge.targetId));
+                        queue.push({
+                            nodeId: neighbor,
+                            path: [...path, neighbor],
+                            edges: [...edges, fullEdge?.id ?? ""]
+                        });
+                    }
+                }
+            }
+            return null;
+        },
+        setHighlightedPath(nodeIds, edgeIds) {
+            if (nodeIds && edgeIds) {
+                highlightedPath = { nodeIds: new Set(nodeIds), edgeIds: new Set(edgeIds) };
+            }
+            else {
+                highlightedPath = null;
+            }
+            requestRedraw();
+        },
+        clearHighlightedPath() {
+            highlightedPath = null;
+            requestRedraw();
+        },
+        setWalkMode(enabled) {
+            walkMode = enabled;
+            if (enabled) {
+                walkTrail = focusSeedIds ? [...focusSeedIds] : [...selectedNodeIds];
+                if (!walkAnimFrame)
+                    walkAnimFrame = requestAnimationFrame(walkAnimate);
+            }
+            else {
+                walkTrail = [];
+                if (walkAnimFrame) {
+                    cancelAnimationFrame(walkAnimFrame);
+                    walkAnimFrame = 0;
+                }
+            }
+            requestRedraw();
+        },
+        getWalkMode() {
+            return walkMode;
+        },
+        getWalkTrail() {
+            return [...walkTrail];
+        },
+        getFilteredNodeIds() {
+            return filteredNodeIds;
+        },
+        removeFromWalkTrail(nodeId) {
+            walkTrail = walkTrail.filter((id) => id !== nodeId);
+            requestRedraw();
+        },
+        /** Hit-test a screen coordinate against nodes. Returns the node or null. */
+        nodeAtScreen(sx, sy) {
+            return nodeAtScreen(sx, sy);
+        },
         /** Get all node IDs in the current layout (subgraph if focused, full graph otherwise). Seed nodes first. */
         getNodeIds() {
             if (!state)
@@ -870,6 +1374,20 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         },
         destroy() {
             cancelAnimationFrame(animFrame);
+            if (renderPending) {
+                cancelAnimationFrame(renderPending);
+                renderPending = 0;
+            }
+            if (walkAnimFrame) {
+                cancelAnimationFrame(walkAnimFrame);
+                walkAnimFrame = 0;
+            }
+            if (layoutWorker) {
+                layoutWorker.terminate();
+                layoutWorker = null;
+            }
+            sceneCache = null;
+            sceneCacheCtx = null;
             observer.disconnect();
         },
     };