backpack-viewer 0.2.20 → 0.3.0

package/dist/config.js

@@ -23,6 +23,7 @@ export function loadViewerConfig() {
             layout: { ...defaultConfig.layout, ...(user.layout ?? {}) },
             navigation: { ...defaultConfig.navigation, ...(user.navigation ?? {}) },
             lod: { ...defaultConfig.lod, ...(user.lod ?? {}) },
+            walk: { ...defaultConfig.walk, ...(user.walk ?? {}) },
             limits: { ...defaultConfig.limits, ...(user.limits ?? {}) },
         };
     }

package/dist/context-menu.d.ts

@@ -0,0 +1,13 @@
+export interface ContextMenuCallbacks {
+    onStar: (nodeId: string) => void;
+    onFocusNode: (nodeId: string) => void;
+    onExploreInBranch: (nodeId: string) => void;
+    onCopyId: (nodeId: string) => void;
+    onExpand?: (nodeId: string) => void;
+    onExplainPath?: (nodeId: string) => void;
+    onEnrich?: (nodeId: string) => void;
+}
+export declare function initContextMenu(container: HTMLElement, callbacks: ContextMenuCallbacks): {
+    show: (nodeId: string, nodeLabel: string, isStarred: boolean, screenX: number, screenY: number) => void;
+    hide: () => void;
+};

package/dist/context-menu.js

@@ -0,0 +1,64 @@
+export function initContextMenu(container, callbacks) {
+    let menuEl = null;
+    function show(nodeId, nodeLabel, isStarred, screenX, screenY) {
+        hide();
+        menuEl = document.createElement("div");
+        menuEl.className = "context-menu";
+        menuEl.style.left = `${screenX}px`;
+        menuEl.style.top = `${screenY}px`;
+        const items = [
+            { label: isStarred ? "\u2605 Unstar" : "\u2606 Star", action: () => callbacks.onStar(nodeId), premium: false },
+            { label: "\u25CE Focus on node", action: () => callbacks.onFocusNode(nodeId), premium: false },
+            { label: "\u2442 Explore in branch", action: () => callbacks.onExploreInBranch(nodeId), premium: false },
+            { label: "\u2398 Copy ID", action: () => callbacks.onCopyId(nodeId), premium: false },
+        ];
+        if (callbacks.onExpand)
+            items.push({ label: "\u2295 Expand node", action: () => callbacks.onExpand(nodeId), premium: true });
+        if (callbacks.onExplainPath)
+            items.push({ label: "\u2194 Explain path to\u2026", action: () => callbacks.onExplainPath(nodeId), premium: true });
+        if (callbacks.onEnrich)
+            items.push({ label: "\u2261 Enrich from web", action: () => callbacks.onEnrich(nodeId), premium: true });
+        let addedSep = false;
+        for (const item of items) {
+            if (!addedSep && item.premium) {
+                const sep = document.createElement("div");
+                sep.className = "context-menu-separator";
+                menuEl.appendChild(sep);
+                addedSep = true;
+            }
+            const row = document.createElement("div");
+            row.className = "context-menu-item";
+            row.textContent = item.label;
+            row.addEventListener("click", () => {
+                item.action();
+                hide();
+            });
+            menuEl.appendChild(row);
+        }
+        container.appendChild(menuEl);
+        // Clamp to viewport
+        const rect = menuEl.getBoundingClientRect();
+        if (rect.right > window.innerWidth) {
+            menuEl.style.left = `${screenX - rect.width}px`;
+        }
+        if (rect.bottom > window.innerHeight) {
+            menuEl.style.top = `${screenY - rect.height}px`;
+        }
+        // Close on outside click (delayed to not catch the opening right-click)
+        setTimeout(() => document.addEventListener("click", hide), 0);
+        document.addEventListener("keydown", handleEscape);
+    }
+    function hide() {
+        if (menuEl) {
+            menuEl.remove();
+            menuEl = null;
+        }
+        document.removeEventListener("click", hide);
+        document.removeEventListener("keydown", handleEscape);
+    }
+    function handleEscape(e) {
+        if (e.key === "Escape")
+            hide();
+    }
+    return { show, hide };
+}

package/dist/default-config.json

@@ -29,7 +29,9 @@
         "spacingIncrease": "]",
         "clusteringDecrease": "{",
         "clusteringIncrease": "}",
-        "toggleSidebar": "Tab"
+        "toggleSidebar": "Tab",
+        "walkMode": "w",
+        "walkIsolate": "i"
     },
     "display": {
         "edges": true,
@@ -57,6 +59,9 @@
         "smallNodes": 0.2,
         "hideArrows": 0.15
     },
+    "walk": {
+        "pulseSpeed": 0.02
+    },
     "limits": {
         "maxSearchResults": 8,
         "maxQualityItems": 5,

package/dist/empty-state.js

@@ -2,6 +2,19 @@ export function initEmptyState(container) {
     const el = document.createElement("div");
     el.className = "empty-state";
     el.innerHTML = `
+    <div class="empty-state-bg">
+      <div class="empty-state-circle c1"></div>
+      <div class="empty-state-circle c2"></div>
+      <div class="empty-state-circle c3"></div>
+      <div class="empty-state-circle c4"></div>
+      <div class="empty-state-circle c5"></div>
+      <svg class="empty-state-lines" viewBox="0 0 400 300" preserveAspectRatio="xMidYMid slice">
+        <line x1="80" y1="60" x2="220" y2="140" stroke="currentColor" stroke-width="0.5" opacity="0.15"/>
+        <line x1="220" y1="140" x2="320" y2="80" stroke="currentColor" stroke-width="0.5" opacity="0.15"/>
+        <line x1="220" y1="140" x2="160" y2="240" stroke="currentColor" stroke-width="0.5" opacity="0.15"/>
+        <line x1="160" y1="240" x2="300" y2="220" stroke="currentColor" stroke-width="0.5" opacity="0.15"/>
+      </svg>
+    </div>
     <div class="empty-state-content">
       <div class="empty-state-icon">
         <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">

package/dist/info-panel.js

@@ -403,7 +403,7 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
         label.textContent = `${nodes.length} nodes selected`;
         header.appendChild(label);
         const badgeRow = document.createElement("div");
-        badgeRow.style.cssText = "display:flex;flex-wrap:wrap;gap:4px;margin-top:6px";
+        badgeRow.className = "info-badge-row";
         const typeCounts = new Map();
         for (const node of nodes) {
             typeCounts.set(node.type, (typeCounts.get(node.type) ?? 0) + 1);
@@ -451,7 +451,7 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
             : "Connections Between Selected");
         if (sharedEdges.length === 0) {
             const empty = document.createElement("p");
-            empty.style.cssText = "font-size:12px;color:var(--text-dim)";
+            empty.className = "info-empty-message";
             empty.textContent = "No direct connections between selected nodes";
             connSection.appendChild(empty);
         }

package/dist/keybindings.d.ts

@@ -1,4 +1,4 @@
-export type KeybindingAction = "search" | "searchAlt" | "undo" | "redo" | "help" | "escape" | "focus" | "toggleEdges" | "center" | "nextNode" | "prevNode" | "nextConnection" | "prevConnection" | "historyBack" | "historyForward" | "hopsIncrease" | "hopsDecrease" | "panLeft" | "panDown" | "panUp" | "panRight" | "panFastLeft" | "zoomOut" | "zoomIn" | "panFastRight" | "spacingDecrease" | "spacingIncrease" | "clusteringDecrease" | "clusteringIncrease" | "toggleSidebar";
+export type KeybindingAction = "search" | "searchAlt" | "undo" | "redo" | "help" | "escape" | "focus" | "toggleEdges" | "center" | "nextNode" | "prevNode" | "nextConnection" | "prevConnection" | "historyBack" | "historyForward" | "hopsIncrease" | "hopsDecrease" | "panLeft" | "panDown" | "panUp" | "panRight" | "panFastLeft" | "zoomOut" | "zoomIn" | "panFastRight" | "spacingDecrease" | "spacingIncrease" | "clusteringDecrease" | "clusteringIncrease" | "toggleSidebar" | "walkMode" | "walkIsolate";
 export type KeybindingMap = Record<KeybindingAction, string>;
 /** Parse a binding string like "ctrl+shift+z" and check if it matches a KeyboardEvent. */
 export declare function matchKey(e: KeyboardEvent, binding: string): boolean;

package/dist/keybindings.js

@@ -63,5 +63,7 @@ export function actionDescriptions() {
         clusteringDecrease: "Decrease clustering",
         clusteringIncrease: "Increase clustering",
         toggleSidebar: "Toggle sidebar",
+        walkMode: "Toggle walk mode (in focus)",
+        walkIsolate: "Isolate walk trail nodes",
     };
 }

package/dist/label-cache.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Offscreen canvas label cache.
+ *
+ * Pre-renders text labels to small offscreen canvases, then draws them
+ * via drawImage() which is much faster than fillText() per frame.
+ * Cache keys are "text|font|color" to handle theme changes.
+ */
+/**
+ * Draw a cached label centered at (x, y) with the given baseline alignment.
+ * Returns immediately — cache miss renders inline and stores for next frame.
+ */
+export declare function drawCachedLabel(ctx: CanvasRenderingContext2D, text: string, x: number, y: number, font: string, color: string, align: "top" | "bottom"): void;
+/** Clear the entire cache (call on theme change or graph reload). */
+export declare function clearLabelCache(): void;

package/dist/label-cache.js

@@ -0,0 +1,54 @@
+/**
+ * Offscreen canvas label cache.
+ *
+ * Pre-renders text labels to small offscreen canvases, then draws them
+ * via drawImage() which is much faster than fillText() per frame.
+ * Cache keys are "text|font|color" to handle theme changes.
+ */
+const cache = new Map();
+const MAX_CACHE_SIZE = 2000;
+function key(text, font, color) {
+    return `${text}|${font}|${color}`;
+}
+// Shared measurement canvas — reused across all renderLabel calls
+const measureCanvas = new OffscreenCanvas(1, 1);
+const measureCtx = measureCanvas.getContext("2d");
+function renderLabel(text, font, color) {
+    measureCtx.font = font;
+    const metrics = measureCtx.measureText(text);
+    const w = Math.ceil(metrics.width) + 2; // 1px padding each side
+    const h = Math.ceil(metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent) + 4;
+    const canvas = new OffscreenCanvas(w, h);
+    const ctx = canvas.getContext("2d");
+    ctx.font = font;
+    ctx.fillStyle = color;
+    ctx.textAlign = "left";
+    ctx.textBaseline = "top";
+    ctx.fillText(text, 1, 1);
+    return { canvas, width: w, height: h };
+}
+/**
+ * Draw a cached label centered at (x, y) with the given baseline alignment.
+ * Returns immediately — cache miss renders inline and stores for next frame.
+ */
+export function drawCachedLabel(ctx, text, x, y, font, color, align) {
+    const k = key(text, font, color);
+    let entry = cache.get(k);
+    if (!entry) {
+        // Evict oldest entries if cache is full
+        if (cache.size >= MAX_CACHE_SIZE) {
+            const first = cache.keys().next().value;
+            if (first !== undefined)
+                cache.delete(first);
+        }
+        entry = renderLabel(text, font, color);
+        cache.set(k, entry);
+    }
+    const dx = x - entry.width / 2;
+    const dy = align === "top" ? y : y - entry.height;
+    ctx.drawImage(entry.canvas, dx, dy);
+}
+/** Clear the entire cache (call on theme change or graph reload). */
+export function clearLabelCache() {
+    cache.clear();
+}

package/dist/layout-worker.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Web Worker for off-main-thread force-directed layout.
+ *
+ * Runs the tick loop in a worker thread so physics never blocks
+ * the main thread's rendering or input handling.
+ *
+ * Protocol:
+ *   Main → Worker:
+ *     { type: 'start', nodes, edges, params }  — begin simulation
+ *     { type: 'stop' }                          — halt simulation
+ *     { type: 'params', params }                — update layout params + reheat
+ *
+ *   Worker → Main:
+ *     { type: 'tick', positions: Float64Array, alpha }  — position update per tick
+ *     { type: 'settled' }                                — simulation converged
+ */
+export {};

package/dist/layout-worker.js

@@ -0,0 +1,78 @@
+/**
+ * Web Worker for off-main-thread force-directed layout.
+ *
+ * Runs the tick loop in a worker thread so physics never blocks
+ * the main thread's rendering or input handling.
+ *
+ * Protocol:
+ *   Main → Worker:
+ *     { type: 'start', nodes, edges, params }  — begin simulation
+ *     { type: 'stop' }                          — halt simulation
+ *     { type: 'params', params }                — update layout params + reheat
+ *
+ *   Worker → Main:
+ *     { type: 'tick', positions: Float64Array, alpha }  — position update per tick
+ *     { type: 'settled' }                                — simulation converged
+ */
+import { createLayout, tick, setLayoutParams, autoLayoutParams } from "./layout.js";
+const ALPHA_MIN = 0.001;
+const TICK_BATCH = 3; // ticks per message to reduce postMessage overhead
+let running = false;
+let state = null;
+let alpha = 1;
+function packPositions(nodes) {
+    const buf = new Float64Array(nodes.length * 4);
+    for (let i = 0; i < nodes.length; i++) {
+        const n = nodes[i];
+        buf[i * 4] = n.x;
+        buf[i * 4 + 1] = n.y;
+        buf[i * 4 + 2] = n.vx;
+        buf[i * 4 + 3] = n.vy;
+    }
+    return buf;
+}
+function runLoop() {
+    if (!running || !state)
+        return;
+    for (let i = 0; i < TICK_BATCH; i++) {
+        if (alpha < ALPHA_MIN) {
+            running = false;
+            const positions = packPositions(state.nodes);
+            self.postMessage({ type: "tick", positions, alpha }, { transfer: [positions.buffer] });
+            self.postMessage({ type: "settled" });
+            return;
+        }
+        alpha = tick(state, alpha);
+    }
+    const positions = packPositions(state.nodes);
+    self.postMessage({ type: "tick", positions, alpha }, { transfer: [positions.buffer] });
+    // Yield to allow incoming messages, then continue
+    setTimeout(runLoop, 0);
+}
+self.onmessage = (e) => {
+    const msg = e.data;
+    if (msg.type === "start") {
+        running = false; // stop any existing loop
+        const data = msg.data;
+        const params = msg.params;
+        // Auto-scale params based on graph size, then apply overrides
+        const auto = autoLayoutParams(data.nodes.length);
+        setLayoutParams({ ...auto, ...params });
+        state = createLayout(data);
+        alpha = 1;
+        running = true;
+        runLoop();
+    }
+    if (msg.type === "stop") {
+        running = false;
+    }
+    if (msg.type === "params") {
+        setLayoutParams(msg.params);
+        // Reheat simulation
+        alpha = Math.max(alpha, 0.3);
+        if (!running && state) {
+            running = true;
+            runLoop();
+        }
+    }
+};

package/dist/layout.js

@@ -1,3 +1,4 @@
+import { buildQuadtree, applyRepulsion } from "./quadtree.js";
 export const DEFAULT_LAYOUT_PARAMS = {
     clusterStrength: 0.08,
     spacing: 1.5,
@@ -106,27 +107,81 @@ export function createLayout(data) {
     }));
     return { nodes, edges, nodeMap };
 }
+// Barnes-Hut accuracy parameter (0.5 = accurate, 1.0 = fast).
+// 0.7 is a good balance for interactive use.
+const BH_THETA = 0.7;
+// Threshold below which we fall back to direct O(n²) — quadtree overhead isn't worth it
+const BH_THRESHOLD = 80;
 /** Run one tick of the force simulation. Returns new alpha. */
 export function tick(state, alpha) {
     const { nodes, edges, nodeMap } = state;
-    // Repulsion — all pairs (stronger between different types)
-    for (let i = 0; i < nodes.length; i++) {
-        for (let j = i + 1; j < nodes.length; j++) {
-            const a = nodes[i];
-            const b = nodes[j];
-            let dx = b.x - a.x;
-            let dy = b.y - a.y;
-            let dist = Math.sqrt(dx * dx + dy * dy);
-            if (dist < MIN_DISTANCE)
-                dist = MIN_DISTANCE;
-            const rep = a.type === b.type ? REPULSION : CROSS_TYPE_REPULSION_BASE * params.spacing;
-            const force = (rep * alpha) / (dist * dist);
-            const fx = (dx / dist) * force;
-            const fy = (dy / dist) * force;
-            a.vx -= fx;
-            a.vy -= fy;
-            b.vx += fx;
-            b.vy += fy;
+    // Repulsion — Barnes-Hut O(n log n) for large graphs, direct O(n²) for small
+    const crossRep = CROSS_TYPE_REPULSION_BASE * params.spacing;
+    if (nodes.length >= BH_THRESHOLD) {
+        // Barnes-Hut: apply cross-type repulsion strength globally via quadtree
+        const tree = buildQuadtree(nodes);
+        if (tree) {
+            for (const node of nodes) {
+                applyRepulsion(tree, node, BH_THETA, crossRep, alpha, MIN_DISTANCE);
+            }
+        }
+        // Same-type correction: same-type pairs should use REPULSION (weaker) not crossRep.
+        // Apply a negative correction of (crossRep - REPULSION) for same-type pairs.
+        // Group by type to avoid checking all n² pairs — only intra-group pairs.
+        const repDiff = crossRep - REPULSION;
+        if (repDiff > 0) {
+            const typeGroups = new Map();
+            for (const node of nodes) {
+                let group = typeGroups.get(node.type);
+                if (!group) {
+                    group = [];
+                    typeGroups.set(node.type, group);
+                }
+                group.push(node);
+            }
+            for (const group of typeGroups.values()) {
+                for (let i = 0; i < group.length; i++) {
+                    for (let j = i + 1; j < group.length; j++) {
+                        const a = group[i];
+                        const b = group[j];
+                        let dx = b.x - a.x;
+                        let dy = b.y - a.y;
+                        let dist = Math.sqrt(dx * dx + dy * dy);
+                        if (dist < MIN_DISTANCE)
+                            dist = MIN_DISTANCE;
+                        // Subtract the excess repulsion (correction is attractive between same-type)
+                        const force = (repDiff * alpha) / (dist * dist);
+                        const fx = (dx / dist) * force;
+                        const fy = (dy / dist) * force;
+                        a.vx += fx;
+                        a.vy += fy;
+                        b.vx -= fx;
+                        b.vy -= fy;
+                    }
+                }
+            }
+        }
+    }
+    else {
+        // Small graph — direct all-pairs (original algorithm)
+        for (let i = 0; i < nodes.length; i++) {
+            for (let j = i + 1; j < nodes.length; j++) {
+                const a = nodes[i];
+                const b = nodes[j];
+                let dx = b.x - a.x;
+                let dy = b.y - a.y;
+                let dist = Math.sqrt(dx * dx + dy * dy);
+                if (dist < MIN_DISTANCE)
+                    dist = MIN_DISTANCE;
+                const rep = a.type === b.type ? REPULSION : crossRep;
+                const force = (rep * alpha) / (dist * dist);
+                const fx = (dx / dist) * force;
+                const fy = (dy / dist) * force;
+                a.vx -= fx;
+                a.vy -= fy;
+                b.vx += fx;
+                b.vy += fy;
+            }
         }
     }
     // Attraction — along edges (shorter rest length within same type)