backpack-viewer 0.2.21 → 0.3.0

package/dist/sidebar.js

@@ -1,4 +1,12 @@
 import { showConfirm, showPrompt } from "./dialog";
+function formatTokenCount(n) {
+    if (n >= 1000)
+        return `${(n / 1000).toFixed(1)}k tokens`;
+    return `${n} tokens`;
+}
+function estimateTokensFromCounts(nodeCount, edgeCount) {
+    return nodeCount * 50 + edgeCount * 25 + 50; // rough: 50 tok/node, 25 tok/edge, 50 metadata
+}
 export function initSidebar(container, onSelectOrCallbacks) {
     const cbs = typeof onSelectOrCallbacks === "function"
         ? { onSelect: onSelectOrCallbacks }
@@ -12,6 +20,14 @@ export function initSidebar(container, onSelectOrCallbacks) {
     input.id = "filter";
     const list = document.createElement("ul");
     list.id = "ontology-list";
+    const remoteHeading = document.createElement("h3");
+    remoteHeading.className = "sidebar-section-heading";
+    remoteHeading.textContent = "REMOTE GRAPHS";
+    remoteHeading.hidden = true;
+    const remoteList = document.createElement("ul");
+    remoteList.id = "remote-list";
+    remoteList.className = "remote-list";
+    remoteList.hidden = true;
     const footer = document.createElement("div");
     footer.className = "sidebar-footer";
     footer.innerHTML =
@@ -43,8 +59,11 @@ export function initSidebar(container, onSelectOrCallbacks) {
     expandBtn.addEventListener("click", toggleSidebar);
     container.appendChild(input);
     container.appendChild(list);
+    container.appendChild(remoteHeading);
+    container.appendChild(remoteList);
     container.appendChild(footer);
     let items = [];
+    let remoteItems = [];
     let activeName = "";
     let activeBranchName = "main";
     // Filter
@@ -54,10 +73,19 @@ export function initSidebar(container, onSelectOrCallbacks) {
             const name = item.dataset.name ?? "";
             item.style.display = name.includes(query) ? "" : "none";
         }
+        for (const item of remoteItems) {
+            const name = item.dataset.name ?? "";
+            item.style.display = name.includes(query) ? "" : "none";
+        }
     });
     return {
         setSummaries(summaries) {
             list.innerHTML = "";
+            // Fetch all locks in one batch request, then distribute to items
+            // as they render. One HTTP roundtrip per sidebar refresh, not N.
+            const lockBatchPromise = fetch("/api/locks")
+                .then((r) => r.json())
+                .catch(() => ({}));
             items = summaries.map((s) => {
                 const li = document.createElement("li");
                 li.className = "ontology-item";
@@ -67,12 +95,30 @@ export function initSidebar(container, onSelectOrCallbacks) {
                 nameSpan.textContent = s.name;
                 const statsSpan = document.createElement("span");
                 statsSpan.className = "stats";
-                statsSpan.textContent = `${s.nodeCount} nodes, ${s.edgeCount} edges`;
+                const tokens = estimateTokensFromCounts(s.nodeCount, s.edgeCount);
+                statsSpan.textContent = `${s.nodeCount} nodes, ${s.edgeCount} edges · ~${formatTokenCount(tokens)}`;
                 const branchSpan = document.createElement("span");
                 branchSpan.className = "sidebar-branch";
                 branchSpan.dataset.graph = s.name;
+                // Lock heartbeat badge — populated from the batched fetch above
+                const lockBadge = document.createElement("span");
+                lockBadge.className = "sidebar-lock-badge";
+                lockBadge.dataset.graph = s.name;
+                lockBatchPromise.then((locks) => {
+                    // Bail if this badge has been detached from the DOM (sidebar
+                    // re-rendered before the batch resolved)
+                    if (!lockBadge.isConnected)
+                        return;
+                    const lock = locks[s.name];
+                    if (lock && typeof lock === "object" && lock.author) {
+                        lockBadge.textContent = `editing: ${lock.author}`;
+                        lockBadge.title = `Last activity: ${lock.lastActivity ?? ""}`;
+                        lockBadge.classList.add("active");
+                    }
+                });
                 li.appendChild(nameSpan);
                 li.appendChild(statsSpan);
+                li.appendChild(lockBadge);
                 li.appendChild(branchSpan);
                 if (cbs.onRename) {
                     const editBtn = document.createElement("button");
@@ -127,6 +173,49 @@ export function initSidebar(container, onSelectOrCallbacks) {
             for (const item of items) {
                 item.classList.toggle("active", item.dataset.name === name);
             }
+            for (const item of remoteItems) {
+                item.classList.toggle("active", item.dataset.name === name);
+            }
+        },
+        setRemotes(remotes) {
+            remoteList.replaceChildren();
+            remoteItems = remotes.map((r) => {
+                const li = document.createElement("li");
+                li.className = "ontology-item ontology-item-remote";
+                li.dataset.name = r.name;
+                const nameRow = document.createElement("div");
+                nameRow.className = "remote-name-row";
+                const nameSpan = document.createElement("span");
+                nameSpan.className = "name";
+                nameSpan.textContent = r.name;
+                const badge = document.createElement("span");
+                badge.className = "remote-badge";
+                badge.textContent = r.pinned ? "remote · pinned" : "remote";
+                badge.title = `Source: ${r.source ?? r.url}`;
+                nameRow.appendChild(nameSpan);
+                nameRow.appendChild(badge);
+                const statsSpan = document.createElement("span");
+                statsSpan.className = "stats";
+                const tokens = estimateTokensFromCounts(r.nodeCount, r.edgeCount);
+                statsSpan.textContent = `${r.nodeCount} nodes, ${r.edgeCount} edges · ~${formatTokenCount(tokens)}`;
+                const sourceSpan = document.createElement("span");
+                sourceSpan.className = "remote-source";
+                sourceSpan.textContent = r.source ?? new URL(r.url).hostname;
+                sourceSpan.title = r.url;
+                li.appendChild(nameRow);
+                li.appendChild(statsSpan);
+                li.appendChild(sourceSpan);
+                li.addEventListener("click", () => cbs.onSelect(r.name));
+                remoteList.appendChild(li);
+                return li;
+            });
+            const visible = remotes.length > 0;
+            remoteHeading.hidden = !visible;
+            remoteList.hidden = !visible;
+            // Re-apply active state in case the active graph is a remote
+            if (activeName) {
+                this.setActive(activeName);
+            }
         },
         setActiveBranch(graphName, branchName, allBranches) {
             activeBranchName = branchName;

package/dist/spatial-hash.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Grid-based spatial hash for O(1) average-case point queries on nodes.
+ * Cell size should be >= 2× the node radius so a node overlaps at most 4 cells.
+ */
+export interface Positioned {
+    x: number;
+    y: number;
+}
+export declare class SpatialHash<T extends Positioned> {
+    private cells;
+    private cellSize;
+    private invCell;
+    constructor(cellSize: number);
+    private key;
+    clear(): void;
+    /** Insert an item at its current position. */
+    insert(item: T): void;
+    /** Rebuild from an array of items. */
+    rebuild(items: T[]): void;
+    /** Find the nearest item within `radius` of (x, y), or null. */
+    query(x: number, y: number, radius: number): T | null;
+}

package/dist/spatial-hash.js

@@ -0,0 +1,67 @@
+/**
+ * Grid-based spatial hash for O(1) average-case point queries on nodes.
+ * Cell size should be >= 2× the node radius so a node overlaps at most 4 cells.
+ */
+export class SpatialHash {
+    cells = new Map();
+    cellSize;
+    invCell;
+    constructor(cellSize) {
+        this.cellSize = cellSize;
+        this.invCell = 1 / cellSize;
+    }
+    key(cx, cy) {
+        // Cantor-like hash combining two integers — fast and good enough for grid coords.
+        // Shift to positive range first to avoid issues with negative coordinates.
+        const a = (cx + 0x8000) | 0;
+        const b = (cy + 0x8000) | 0;
+        return (a * 73856093) ^ (b * 19349663);
+    }
+    clear() {
+        this.cells.clear();
+    }
+    /** Insert an item at its current position. */
+    insert(item) {
+        const cx = Math.floor(item.x * this.invCell);
+        const cy = Math.floor(item.y * this.invCell);
+        const k = this.key(cx, cy);
+        const bucket = this.cells.get(k);
+        if (bucket)
+            bucket.push(item);
+        else
+            this.cells.set(k, [item]);
+    }
+    /** Rebuild from an array of items. */
+    rebuild(items) {
+        this.cells.clear();
+        for (const item of items)
+            this.insert(item);
+    }
+    /** Find the nearest item within `radius` of (x, y), or null. */
+    query(x, y, radius) {
+        const r2 = radius * radius;
+        const cxMin = Math.floor((x - radius) * this.invCell);
+        const cxMax = Math.floor((x + radius) * this.invCell);
+        const cyMin = Math.floor((y - radius) * this.invCell);
+        const cyMax = Math.floor((y + radius) * this.invCell);
+        let best = null;
+        let bestDist = r2;
+        for (let cx = cxMin; cx <= cxMax; cx++) {
+            for (let cy = cyMin; cy <= cyMax; cy++) {
+                const bucket = this.cells.get(this.key(cx, cy));
+                if (!bucket)
+                    continue;
+                for (const item of bucket) {
+                    const dx = item.x - x;
+                    const dy = item.y - y;
+                    const d2 = dx * dx + dy * dy;
+                    if (d2 <= bestDist) {
+                        bestDist = d2;
+                        best = item;
+                    }
+                }
+            }
+        }
+        return best;
+    }
+}

package/dist/style.css

@@ -237,6 +237,54 @@ body {
   opacity: 0.7;
 }
 
+/* --- Remote graphs section in sidebar --- */
+
+.sidebar-section-heading {
+  font-size: 10px;
+  font-weight: 600;
+  color: var(--text-dim);
+  letter-spacing: 0.08em;
+  margin: 16px 12px 6px;
+}
+
+.remote-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.ontology-item-remote .name {
+  display: inline;
+}
+
+.remote-name-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.remote-badge {
+  font-size: 9px;
+  font-weight: 600;
+  color: var(--text-dim);
+  background: var(--bg-hover);
+  padding: 1px 6px;
+  border-radius: 4px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  border: 1px solid var(--border);
+}
+
+.remote-source {
+  display: block;
+  font-size: 10px;
+  color: var(--text-dim);
+  margin-top: 1px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .sidebar-edit-btn:hover {
   opacity: 1 !important;
   color: var(--text);
@@ -267,6 +315,22 @@ body {
   opacity: 1;
 }
 
+.sidebar-lock-badge {
+  font-size: 10px;
+  color: #c08c00;
+  display: none;
+  margin-top: 2px;
+}
+
+.sidebar-lock-badge.active {
+  display: block;
+}
+
+.sidebar-lock-badge.active::before {
+  content: "● ";
+  color: #c08c00;
+}
+
 .branch-picker {
   background: var(--bg-surface);
   border: 1px solid var(--border);
@@ -543,6 +607,23 @@ body {
   background: var(--bg-hover);
 }
 
+/* --- Node Tooltip --- */
+
+.node-tooltip {
+  position: absolute;
+  pointer-events: none;
+  background: var(--bg);
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 4px 8px;
+  font-size: 12px;
+  white-space: nowrap;
+  z-index: 20;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+  opacity: 0.95;
+}
+
 /* --- Canvas --- */
 
 #canvas-container {
@@ -905,6 +986,25 @@ body {
   margin-bottom: 8px;
 }
 
+.info-badge-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  margin-top: 6px;
+}
+
+.info-empty-message {
+  font-size: 12px;
+  color: var(--text-dim);
+}
+
+.share-list-message {
+  font-size: 13px;
+  color: var(--text-dim);
+  text-align: center;
+  padding: 12px;
+}
+
 .info-label {
   font-size: 18px;
   font-weight: 600;
@@ -1324,6 +1424,41 @@ body {
   color: var(--text-dim);
 }
 
+.tools-pane-token-card {
+  padding: 8px 10px;
+  margin-bottom: 10px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--bg-hover);
+  font-size: 11px;
+}
+
+.token-card-label {
+  font-weight: 600;
+  color: var(--text);
+  margin-bottom: 4px;
+}
+
+.token-card-stat {
+  color: var(--text-muted);
+  margin-bottom: 4px;
+}
+
+.token-card-bar {
+  height: 4px;
+  background: var(--border);
+  border-radius: 2px;
+  margin: 6px 0;
+  overflow: hidden;
+}
+
+.token-card-bar-fill {
+  height: 100%;
+  background: var(--accent);
+  border-radius: 2px;
+  transition: width 0.3s ease;
+}
+
 .tools-pane-clickable {
   cursor: pointer;
   border-radius: 4px;
@@ -1378,6 +1513,28 @@ body {
   color: var(--accent);
 }
 
+.tools-pane-actions {
+  display: flex;
+  gap: 6px;
+  padding-top: 4px;
+}
+
+.tools-pane-action-btn {
+  background: none;
+  border: 1px solid var(--border);
+  color: var(--text-muted);
+  font-size: 10px;
+  padding: 2px 8px;
+  border-radius: 3px;
+  cursor: pointer;
+  transition: color 0.1s, border-color 0.1s;
+}
+
+.tools-pane-action-btn:hover {
+  color: var(--accent);
+  border-color: var(--accent);
+}
+
 .tools-pane-focus-toggle {
   opacity: 0.4;
   font-size: 11px;
@@ -1556,16 +1713,52 @@ body {
   justify-content: center;
   z-index: 5;
   pointer-events: none;
+  overflow: hidden;
 }
 
 .empty-state.hidden {
   display: none;
 }
 
+.empty-state-bg {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+}
+
+.empty-state-circle {
+  position: absolute;
+  border-radius: 50%;
+  background: var(--accent);
+  opacity: 0.07;
+}
+
+.empty-state-circle.c1 { width: 80px; height: 80px; left: 20%; top: 15%; animation: float-circle 8s ease-in-out infinite; }
+.empty-state-circle.c2 { width: 50px; height: 50px; right: 25%; top: 25%; animation: float-circle 6s ease-in-out 1s infinite; }
+.empty-state-circle.c3 { width: 65px; height: 65px; left: 55%; bottom: 20%; animation: float-circle 7s ease-in-out 2s infinite; }
+.empty-state-circle.c4 { width: 40px; height: 40px; left: 15%; bottom: 30%; animation: float-circle 9s ease-in-out 0.5s infinite; }
+.empty-state-circle.c5 { width: 55px; height: 55px; right: 15%; bottom: 35%; animation: float-circle 7.5s ease-in-out 1.5s infinite; }
+
+.empty-state-lines {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  color: var(--text-dim);
+  animation: float-circle 10s ease-in-out infinite;
+}
+
+@keyframes float-circle {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-12px); }
+}
+
 .empty-state-content {
   text-align: center;
   max-width: 420px;
   padding: 40px 24px;
+  position: relative;
+  z-index: 1;
 }
 
 .empty-state-icon {

package/dist/tools-pane.d.ts

@@ -6,6 +6,7 @@ interface ToolsPaneCallbacks {
     onWalkTrailRemove?: (nodeId: string) => void;
     onWalkIsolate?: () => void;
     onWalkSaveSnippet?: (label: string) => void;
+    onStarredSaveSnippet?: (label: string, nodeIds: string[]) => void;
     onRenameNodeType: (oldType: string, newType: string) => void;
     onRenameEdgeType: (oldType: string, newType: string) => void;
     onToggleEdgeLabels: (visible: boolean) => void;

package/dist/tools-pane.js

@@ -76,6 +76,37 @@ export function initToolsPane(container, callbacks) {
                 `<span>${stats.edgeCount} edges</span><span class="tools-pane-sep">&middot;</span>` +
                 `<span>${stats.types.length} types</span>`;
         content.appendChild(summary);
+        // Token efficiency card
+        if (data && stats.nodeCount > 0) {
+            const graphTokens = Math.ceil(JSON.stringify(data).length / 4);
+            // Estimate a typical search response: ~5 NodeSummary results, each ~30 chars
+            const avgNodeTokens = Math.round(graphTokens / stats.nodeCount);
+            const searchTokens = Math.max(10, Math.round(avgNodeTokens * 0.3) * Math.min(5, stats.nodeCount));
+            const percent = graphTokens > searchTokens ? Math.round((1 - searchTokens / graphTokens) * 100) : 0;
+            const tokenCard = document.createElement("div");
+            tokenCard.className = "tools-pane-token-card";
+            const barWidth = Math.min(100, percent);
+            const label = document.createElement("div");
+            label.className = "token-card-label";
+            label.textContent = "Token Efficiency";
+            tokenCard.appendChild(label);
+            const storedStat = document.createElement("div");
+            storedStat.className = "token-card-stat";
+            storedStat.textContent = `~${graphTokens.toLocaleString()} tokens stored`;
+            tokenCard.appendChild(storedStat);
+            const bar = document.createElement("div");
+            bar.className = "token-card-bar";
+            const barFill = document.createElement("div");
+            barFill.className = "token-card-bar-fill";
+            barFill.style.width = `${barWidth}%`;
+            bar.appendChild(barFill);
+            tokenCard.appendChild(bar);
+            const reductionStat = document.createElement("div");
+            reductionStat.className = "token-card-stat";
+            reductionStat.textContent = `A search returns ~${searchTokens} tokens instead of ~${graphTokens.toLocaleString()} (${percent}% reduction)`;
+            tokenCard.appendChild(reductionStat);
+            content.appendChild(tokenCard);
+        }
         // Tab bar
         const tabBar = document.createElement("div");
         tabBar.className = "tools-pane-tabs";
@@ -442,6 +473,80 @@ export function initToolsPane(container, callbacks) {
         if (!stats)
             return;
         const qq = qualitySearch.toLowerCase();
+        // Starred nodes — click to navigate, focus button
+        const filteredStarred = stats.starred.filter((n) => !qq || n.label.toLowerCase().includes(qq) || n.type.toLowerCase().includes(qq));
+        if (filteredStarred.length) {
+            target.appendChild(makeSection("\u2605 Starred", (section) => {
+                for (const n of filteredStarred) {
+                    const row = document.createElement("div");
+                    row.className = "tools-pane-row tools-pane-clickable";
+                    const dot = document.createElement("span");
+                    dot.className = "tools-pane-dot";
+                    dot.style.backgroundColor = getColor(n.type);
+                    const name = document.createElement("span");
+                    name.className = "tools-pane-name";
+                    name.textContent = n.label;
+                    const focusBtn = document.createElement("button");
+                    focusBtn.className = "tools-pane-edit tools-pane-focus-toggle";
+                    if (isNodeFocused(n.id))
+                        focusBtn.classList.add("tools-pane-focus-active");
+                    focusBtn.textContent = "\u25CE";
+                    focusBtn.title = isNodeFocused(n.id)
+                        ? `Remove ${n.label} from focus`
+                        : `Add ${n.label} to focus`;
+                    row.appendChild(dot);
+                    row.appendChild(name);
+                    row.appendChild(focusBtn);
+                    row.addEventListener("click", (e) => {
+                        if (e.target.closest(".tools-pane-edit"))
+                            return;
+                        callbacks.onNavigateToNode(n.id);
+                    });
+                    focusBtn.addEventListener("click", (e) => {
+                        e.stopPropagation();
+                        if (focusSet.nodeIds.has(n.id)) {
+                            focusSet.nodeIds.delete(n.id);
+                        }
+                        else {
+                            focusSet.nodeIds.add(n.id);
+                        }
+                        emitFocusChange();
+                        render();
+                    });
+                    section.appendChild(row);
+                }
+                // Action buttons row
+                const actions = document.createElement("div");
+                actions.className = "tools-pane-row tools-pane-actions";
+                const focusAllBtn = document.createElement("button");
+                focusAllBtn.className = "tools-pane-action-btn";
+                focusAllBtn.textContent = "Focus all";
+                focusAllBtn.title = "Enter focus mode with all starred nodes";
+                focusAllBtn.addEventListener("click", () => {
+                    focusSet.nodeIds.clear();
+                    focusSet.types.clear();
+                    for (const n of stats.starred)
+                        focusSet.nodeIds.add(n.id);
+                    emitFocusChange();
+                    render();
+                });
+                actions.appendChild(focusAllBtn);
+                if (callbacks.onStarredSaveSnippet) {
+                    const saveBtn = document.createElement("button");
+                    saveBtn.className = "tools-pane-action-btn";
+                    saveBtn.textContent = "Save as snippet";
+                    saveBtn.title = "Save starred nodes as a reusable snippet";
+                    saveBtn.addEventListener("click", async () => {
+                        const label = await showPrompt("Snippet name", "starred");
+                        if (label) {
+                            callbacks.onStarredSaveSnippet(label, stats.starred.map((n) => n.id));
+                        }
+                    });
+                    actions.appendChild(saveBtn);
+                }
+                section.appendChild(actions);
+            }));
+        }
         // Most connected nodes — click to navigate, focus button
         const filteredConnected = stats.mostConnected.filter((n) => !qq || n.label.toLowerCase().includes(qq) || n.type.toLowerCase().includes(qq));
         if (filteredConnected.length) {
@@ -838,6 +943,9 @@ export function initToolsPane(container, callbacks) {
             connectedNodes.add(edge.targetId);
         }
         const nodeLabel = (n) => firstStringValue(n.properties) ?? n.id;
+        const starred = graphData.nodes
+            .filter((n) => n.properties._starred === true)
+            .map((n) => ({ id: n.id, label: nodeLabel(n), type: n.type }));
         const orphans = graphData.nodes
             .filter((n) => !connectedNodes.has(n.id))
             .map((n) => ({ id: n.id, label: nodeLabel(n), type: n.type }));
@@ -866,6 +974,7 @@ export function initToolsPane(container, callbacks) {
             edgeTypes: [...edgeTypeCounts.entries()]
                 .sort((a, b) => b[1] - a[1])
                 .map(([name, count]) => ({ name, count })),
+            starred,
             orphans,
             singletons,
             emptyNodes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backpack-viewer",
-  "version": "0.2.21",
+  "version": "0.3.0",
   "description": "Web-based graph visualizer for backpack-ontology — Canvas 2D, force-directed layout, live reload",
   "license": "Apache-2.0",
   "author": "Noah Irzinger",
@@ -23,7 +23,7 @@
     "release:major": "npm version major && git push && git push --tags"
   },
   "dependencies": {
-    "backpack-ontology": "^0.2.24"
+    "backpack-ontology": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",