backpack-viewer 0.4.0 → 0.5.1

package/dist/config.js

@@ -18,6 +18,7 @@ export function loadViewerConfig() {
         const raw = fs.readFileSync(filePath, "utf-8");
         const user = JSON.parse(raw);
         return {
+            server: { ...defaultConfig.server, ...(user.server ?? {}) },
             keybindings: { ...defaultConfig.keybindings, ...(user.keybindings ?? {}) },
             display: { ...defaultConfig.display, ...(user.display ?? {}) },
             layout: { ...defaultConfig.layout, ...(user.layout ?? {}) },

package/dist/default-config.json

@@ -33,6 +33,10 @@
         "walkMode": "w",
         "walkIsolate": "i"
     },
+    "server": {
+        "host": "127.0.0.1",
+        "port": 5173
+    },
     "display": {
         "edges": true,
         "edgeLabels": true,

package/dist/dialog.d.ts

@@ -3,6 +3,19 @@
 export declare function showConfirm(title: string, message: string): Promise<boolean>;
 /** Show a prompt dialog with an input field. Returns null if cancelled. */
 export declare function showPrompt(title: string, placeholder?: string, defaultValue?: string): Promise<string | null>;
+export interface BackpackAddResult {
+    path: string;
+    activate: boolean;
+}
+/**
+ * Show the Add Backpack dialog. Single path field with an optional
+ * native folder picker (Chromium only) and drag-and-drop hint. No
+ * name field — the display name is derived from the path tail by
+ * the backend. No suggestion chips — user pastes any path.
+ *
+ * Returns null if the user cancels.
+ */
+export declare function showBackpackAddDialog(): Promise<BackpackAddResult | null>;
 /** Show a danger confirmation (for destructive actions). */
 export declare function showDangerConfirm(title: string, message: string): Promise<boolean>;
 /** Show a brief toast notification. */

package/dist/dialog.js

@@ -87,6 +87,122 @@ export function showPrompt(title, placeholder, defaultValue) {
         input.select();
     });
 }
+/**
+ * Show the Add Backpack dialog. Single path field with an optional
+ * native folder picker (Chromium only) and drag-and-drop hint. No
+ * name field — the display name is derived from the path tail by
+ * the backend. No suggestion chips — user pastes any path.
+ *
+ * Returns null if the user cancels.
+ */
+export function showBackpackAddDialog() {
+    return new Promise((resolve) => {
+        const overlay = createOverlay();
+        const modal = createModal(overlay, "Add Backpack");
+        const description = document.createElement("p");
+        description.className = "bp-dialog-message";
+        description.textContent =
+            "Enter the absolute path to a directory that should become a backpack. It will be shown in the sidebar using the last segment of the path as its display name.";
+        modal.appendChild(description);
+        const pathLabel = document.createElement("label");
+        pathLabel.className = "bp-dialog-label";
+        pathLabel.textContent = "Path";
+        modal.appendChild(pathLabel);
+        const pathRow = document.createElement("div");
+        pathRow.className = "bp-dialog-path-row";
+        modal.appendChild(pathRow);
+        const pathInput = document.createElement("input");
+        pathInput.type = "text";
+        pathInput.className = "bp-dialog-input bp-dialog-path-input";
+        pathInput.placeholder = "/Users/you/OneDrive/work";
+        pathRow.appendChild(pathInput);
+        const browseBtn = document.createElement("button");
+        browseBtn.type = "button";
+        browseBtn.className = "bp-dialog-btn bp-dialog-browse-btn";
+        browseBtn.textContent = "Browse...";
+        pathRow.appendChild(browseBtn);
+        // File System Access API is Chromium-only. On Safari/Firefox the
+        // picker doesn't exist; even on Chromium it returns a handle, not
+        // a filesystem path, so the user still types or pastes the
+        // absolute path. The picker is only a hint.
+        const hasNativePicker = typeof window.showDirectoryPicker === "function";
+        if (!hasNativePicker) {
+            browseBtn.disabled = true;
+            browseBtn.title =
+                "Browser doesn't support native folder picker — paste the path manually";
+        }
+        browseBtn.addEventListener("click", async (e) => {
+            e.preventDefault();
+            try {
+                const handle = await window.showDirectoryPicker({
+                    mode: "read",
+                });
+                pickerHint.textContent = `Picked "${handle.name}" — paste the absolute path to it below.`;
+                pathInput.focus();
+            }
+            catch {
+                // User cancelled
+            }
+        });
+        const pickerHint = document.createElement("div");
+        pickerHint.className = "bp-dialog-picker-hint";
+        modal.appendChild(pickerHint);
+        // Activate checkbox
+        const activateRow = document.createElement("div");
+        activateRow.className = "bp-dialog-activate-row";
+        const activateCheckbox = document.createElement("input");
+        activateCheckbox.type = "checkbox";
+        activateCheckbox.id = "bp-dialog-activate";
+        activateCheckbox.checked = true;
+        const activateLabel = document.createElement("label");
+        activateLabel.htmlFor = "bp-dialog-activate";
+        activateLabel.textContent = "Switch to this backpack after registering";
+        activateRow.appendChild(activateCheckbox);
+        activateRow.appendChild(activateLabel);
+        modal.appendChild(activateRow);
+        // Drag-and-drop: dropping a folder gives us the folder name via
+        // webkitGetAsEntry but not the full OS path (sandboxed). Use it as
+        // a visual hint only.
+        pathInput.addEventListener("dragover", (e) => {
+            e.preventDefault();
+            pathInput.classList.add("bp-dialog-drag-over");
+        });
+        pathInput.addEventListener("dragleave", () => {
+            pathInput.classList.remove("bp-dialog-drag-over");
+        });
+        pathInput.addEventListener("drop", (e) => {
+            e.preventDefault();
+            pathInput.classList.remove("bp-dialog-drag-over");
+            const items = e.dataTransfer?.items;
+            if (!items || items.length === 0)
+                return;
+            const entry = items[0].webkitGetAsEntry?.();
+            if (entry?.isDirectory) {
+                pickerHint.textContent = `Dropped "${entry.name}" — paste the absolute path to it below.`;
+            }
+        });
+        const submit = () => {
+            const p = pathInput.value.trim();
+            if (!p)
+                return;
+            overlay.remove();
+            resolve({ path: p, activate: activateCheckbox.checked });
+        };
+        pathInput.addEventListener("keydown", (e) => {
+            if (e.key === "Enter")
+                submit();
+            if (e.key === "Escape") {
+                overlay.remove();
+                resolve(null);
+            }
+        });
+        addButtons(modal, [
+            { label: "Cancel", onClick: () => { overlay.remove(); resolve(null); } },
+            { label: "Register", accent: true, onClick: submit },
+        ]);
+        pathInput.focus();
+    });
+}
 /** Show a danger confirmation (for destructive actions). */
 export function showDangerConfirm(title, message) {
     return new Promise((resolve) => {

package/dist/main.js

@@ -528,11 +528,11 @@ async function main() {
             // live-reload channel, so we refresh immediately as fallback.
             await refreshBackpacksAndGraphs();
         },
-        onBackpackRegister: async (name, p, activate) => {
+        onBackpackRegister: async (p, activate) => {
             await fetch("/api/backpacks", {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ name, path: p, activate }),
+                body: JSON.stringify({ path: p, activate }),
             });
             await refreshBackpacksAndGraphs();
         },
@@ -771,6 +771,17 @@ async function main() {
         sidebar.setBackpacks(list);
     }
     catch { }
+    // Fire-and-forget stale-version check. If we're running an out-of-date
+    // viewer (classic npx cache trap), show a banner in the sidebar with
+    // the exact command to unblock.
+    fetch("/api/version-check")
+        .then((r) => r.json())
+        .then((info) => {
+        if (info.stale && info.latest) {
+            sidebar.setStaleVersionBanner(info.current, info.latest);
+        }
+    })
+        .catch(() => { });
     // Load ontology list (local + remote in parallel)
     const [summaries, remotes] = await Promise.all([
         listOntologies(),

package/dist/sidebar.d.ts

@@ -14,10 +14,11 @@ export interface SidebarCallbacks {
     onBranchDelete?: (graphName: string, branchName: string) => void;
     onSnippetLoad?: (graphName: string, snippetId: string) => void;
     onSnippetDelete?: (graphName: string, snippetId: string) => void;
-    onBackpackSwitch?: (name: string) => void;
-    onBackpackRegister?: (name: string, path: string, activate: boolean) => void;
+    onBackpackSwitch?: (pathOrName: string) => void;
+    onBackpackRegister?: (path: string, activate: boolean) => void;
 }
 export declare function initSidebar(container: HTMLElement, onSelectOrCallbacks: ((name: string) => void) | SidebarCallbacks): {
+    setStaleVersionBanner(current: string, latest: string): void;
     setBackpacks(list: BackpackSummary[]): void;
     setActiveBackpack(entry: BackpackSummary): void;
     getActiveBackpack(): BackpackSummary | null;

package/dist/sidebar.js

@@ -1,4 +1,4 @@
-import { showConfirm, showPrompt } from "./dialog";
+import { showConfirm, showPrompt, showBackpackAddDialog } from "./dialog";
 function formatTokenCount(n) {
     if (n >= 1000)
         return `${(n / 1000).toFixed(1)}k tokens`;
@@ -51,6 +51,14 @@ export function initSidebar(container, onSelectOrCallbacks) {
     headingRow.appendChild(heading);
     headingRow.appendChild(collapseBtn);
     container.appendChild(headingRow);
+    // Stale-version banner — hidden by default. setStaleVersionBanner()
+    // populates and reveals it when the startup check detects that the
+    // running viewer is older than the latest published npm version
+    // (classic npx cache trap).
+    const staleBanner = document.createElement("div");
+    staleBanner.className = "sidebar-stale-banner";
+    staleBanner.hidden = true;
+    container.appendChild(staleBanner);
     // Backpack picker pill — discrete indicator of the active backpack with
     // a dropdown to switch between registered ones.
     const backpackPicker = document.createElement("button");
@@ -146,14 +154,10 @@ export function initSidebar(container, onSelectOrCallbacks) {
             closePicker();
             if (!cbs.onBackpackRegister)
                 return;
-            const name = await showPrompt("Backpack name", "Short kebab-case name (e.g. work, family, project-alpha)", "");
-            if (!name)
+            const result = await showBackpackAddDialog();
+            if (!result)
                 return;
-            const p = await showPrompt("Backpack path", "Absolute or tilde-expanded path to the graphs directory", "");
-            if (!p)
-                return;
-            const activate = await showConfirm("Switch to new backpack?", `Make "${name}" the active backpack immediately?`);
-            cbs.onBackpackRegister(name, p, activate);
+            cbs.onBackpackRegister(result.path, result.activate);
         });
         pickerDropdown.appendChild(addItem);
     }
@@ -185,6 +189,22 @@ export function initSidebar(container, onSelectOrCallbacks) {
         }
     });
     return {
+        setStaleVersionBanner(current, latest) {
+            staleBanner.replaceChildren();
+            const title = document.createElement("div");
+            title.className = "sidebar-stale-banner-title";
+            title.textContent = `Viewer ${current} is out of date`;
+            const subtitle = document.createElement("div");
+            subtitle.className = "sidebar-stale-banner-subtitle";
+            subtitle.textContent = `Latest is ${latest}. Your version is stuck because of an npx cache.`;
+            const hint = document.createElement("pre");
+            hint.className = "sidebar-stale-banner-hint";
+            hint.textContent = "npm cache clean --force\nnpx backpack-viewer@latest";
+            staleBanner.appendChild(title);
+            staleBanner.appendChild(subtitle);
+            staleBanner.appendChild(hint);
+            staleBanner.hidden = false;
+        },
         setBackpacks(list) {
             currentBackpacks = list.slice();
             const active = list.find((b) => b.active) ?? null;

package/dist/style.css

@@ -318,6 +318,40 @@ body {
   opacity: 1;
 }
 
+/* --- Stale viewer version banner --- */
+
+.sidebar-stale-banner {
+  background: #fff3cd;
+  color: #5c3a00;
+  border: 1px solid #e6c263;
+  border-radius: 6px;
+  padding: 10px 12px;
+  margin-bottom: 10px;
+  font-size: 11px;
+}
+
+.sidebar-stale-banner-title {
+  font-weight: 600;
+  margin-bottom: 2px;
+}
+
+.sidebar-stale-banner-subtitle {
+  opacity: 0.85;
+  margin-bottom: 6px;
+}
+
+.sidebar-stale-banner-hint {
+  background: rgba(0, 0, 0, 0.08);
+  border-radius: 4px;
+  padding: 6px 8px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 10px;
+  line-height: 1.4;
+  margin: 0;
+  white-space: pre-wrap;
+  word-break: break-all;
+}
+
 /* --- Backpack picker (active backpack indicator + switcher) --- */
 
 .backpack-picker-container {
@@ -330,10 +364,10 @@ body {
   align-items: center;
   gap: 6px;
   width: 100%;
-  padding: 4px 8px;
+  padding: 6px 10px;
   background: var(--bg-base);
   border: 1px solid var(--border);
-  border-radius: 999px;
+  border-radius: 6px;
   color: var(--fg);
   font-size: 11px;
   font-family: inherit;
@@ -2135,6 +2169,68 @@ body {
   border-color: var(--accent);
 }
 
+.bp-dialog-label {
+  display: block;
+  font-size: 11px;
+  color: var(--text-muted);
+  margin-bottom: 4px;
+  margin-top: 8px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.bp-dialog-path-row {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 4px;
+}
+
+.bp-dialog-path-input {
+  flex: 1;
+  margin-bottom: 0;
+}
+
+.bp-dialog-browse-btn {
+  flex-shrink: 0;
+  padding: 8px 14px;
+  font-size: 12px;
+}
+
+.bp-dialog-browse-btn:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.bp-dialog-path-input.bp-dialog-drag-over {
+  border-color: var(--accent);
+  background: var(--bg-hover);
+}
+
+.bp-dialog-picker-hint {
+  font-size: 11px;
+  color: var(--text-muted);
+  min-height: 1em;
+  margin-bottom: 8px;
+}
+
+.bp-dialog-activate-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-top: 8px;
+  margin-bottom: 12px;
+  font-size: 12px;
+  color: var(--text-muted);
+}
+
+.bp-dialog-activate-row input[type="checkbox"] {
+  margin: 0;
+}
+
+.bp-dialog-activate-row label {
+  cursor: pointer;
+}
+
 .bp-dialog-buttons {
   display: flex;
   justify-content: flex-end;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backpack-viewer",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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.4.0"
+    "backpack-ontology": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",