backpack-viewer 0.5.1 → 0.7.0

package/dist/main.js

@@ -2,14 +2,20 @@ import { listOntologies, loadOntology, saveOntology, renameOntology, listBranche
 import { initSidebar } from "./sidebar";
 import { initCanvas } from "./canvas";
 import { initInfoPanel } from "./info-panel";
+import { createPanelMount } from "./extensions/panel-mount";
 import { initSearch } from "./search";
 import { initToolsPane } from "./tools-pane";
 import { setLayoutParams, getLayoutParams, autoLayoutParams } from "./layout";
 import { initShortcuts } from "./shortcuts";
 import { initEmptyState } from "./empty-state";
+import { showToast } from "./dialog";
 import { createHistory } from "./history";
 import { matchKey } from "./keybindings";
 import { initContextMenu } from "./context-menu";
+import { initCopyPromptButton } from "./copy-prompt";
+import { publishViewerState } from "./bridge";
+import { createEventBus } from "./extensions/event-bus";
+import { loadExtensions } from "./extensions/loader";
 import defaultConfig from "./default-config.json";
 import "./style.css";
 let activeOntology = "";
@@ -68,6 +74,7 @@ async function main() {
         // Refresh sidebar counts
         const updated = await listOntologies();
         sidebar.setSummaries(updated);
+        eventBus.emit("graph-changed");
     }
     /** Snapshot current state, then save. Call this instead of save() for undoable actions. */
     async function undoableSave() {
@@ -88,7 +95,11 @@ async function main() {
     // canvas is used inside the navigate callback but declared below —
     // that's fine because the callback is only invoked after setup completes.
     let canvas;
-    const infoPanel = initInfoPanel(canvasContainer, {
+    // Create the shared panel-mount up front. Both info-panel and the
+    // extension loader use this single instance so all panels share the
+    // same click-to-front z-stack and the persistent layer DOM element.
+    const panelMount = createPanelMount(canvasContainer);
+    const infoPanel = initInfoPanel(canvasContainer, panelMount, {
         onUpdateNode(nodeId, properties) {
             if (!currentData)
                 return;
@@ -215,7 +226,7 @@ async function main() {
     pathBar.className = "path-bar hidden";
     canvasContainer.appendChild(pathBar);
     function showPathBar(path) {
-        pathBar.innerHTML = "";
+        pathBar.replaceChildren();
         if (!currentData)
             return;
         for (let i = 0; i < path.nodeIds.length; i++) {
@@ -248,11 +259,27 @@ async function main() {
     }
     function hidePathBar() {
         pathBar.classList.add("hidden");
-        pathBar.innerHTML = "";
+        pathBar.replaceChildren();
         canvas.clearHighlightedPath();
     }
+    // Event bus for extensions. Emitted from the same hooks that drive
+    // bridge publishing — selection changes, focus enter/exit, graph
+    // load, save. Subscribers run synchronously; errors in one don't
+    // affect others.
+    const eventBus = createEventBus();
+    function publishBridgeState() {
+        if (!activeOntology)
+            return;
+        publishViewerState({
+            graph: activeOntology,
+            selection: currentSelection,
+            focus: canvas?.getFocusInfo() ?? null,
+        });
+    }
     canvas = initCanvas(canvasContainer, (nodeIds) => {
         currentSelection = nodeIds ?? [];
+        publishBridgeState();
+        eventBus.emit("selection-changed");
         // Don't touch the path bar when walk mode is active — syncWalkTrail manages it
         if (!canvas.getWalkMode()) {
             if (nodeIds && nodeIds.length === 2) {
@@ -297,6 +324,8 @@ async function main() {
                 updateUrl(activeOntology);
             syncWalkTrail();
         }
+        publishBridgeState();
+        eventBus.emit("focus-changed");
     }, { lod: cfg.lod, navigation: cfg.navigation, walk: cfg.walk });
     const search = initSearch(canvasContainer, {
         maxResults: cfg.limits.maxSearchResults,
@@ -447,15 +476,46 @@ async function main() {
     const toolsToggle = canvasContainer.querySelector(".tools-pane-toggle");
     if (toolsToggle)
         topLeft.appendChild(toolsToggle);
-    // Move search overlay into center slot
-    const searchOverlay = canvasContainer.querySelector(".search-overlay");
-    if (searchOverlay)
-        topCenter.appendChild(searchOverlay);
     // Move zoom controls and theme toggle into right slot
     const zoomControls = canvasContainer.querySelector(".zoom-controls");
     if (zoomControls)
         topRight.appendChild(zoomControls);
     topRight.appendChild(themeBtn);
+    // Extension taskbar slots — four hosted containers, one per
+    // supported icon position. The top slots flank the search overlay
+    // INSIDE top-center, alongside the copy-prompt button. The viewer's
+    // own controls in top-left/top-right (zoom, theme, tools toggle)
+    // stay visually separated. Bottom slots float in the canvas
+    // corners. All four start hidden — they're invisible until at
+    // least one extension registers into them, so empty slots take no
+    // space.
+    const extSlotTopLeft = document.createElement("div");
+    extSlotTopLeft.className = "ext-slot ext-slot-top-left";
+    topCenter.appendChild(extSlotTopLeft);
+    // Move search overlay into center slot, after the left ext slot so
+    // top-center reads: [ext-left, search, ext-right, copy-prompt].
+    const searchOverlay = canvasContainer.querySelector(".search-overlay");
+    if (searchOverlay)
+        topCenter.appendChild(searchOverlay);
+    const extSlotTopRight = document.createElement("div");
+    extSlotTopRight.className = "ext-slot ext-slot-top-right";
+    topCenter.appendChild(extSlotTopRight);
+    // Copy-prompt button — viewer-owned, sits at the rightmost end of
+    // the top-center group so any registered ext-right icons (like
+    // chat) appear immediately to its left.
+    const copyPromptBtn = initCopyPromptButton(() => ({
+        graphName: activeOntology,
+        data: currentData,
+        selection: currentSelection,
+        focus: canvas.getFocusInfo(),
+    }));
+    topCenter.appendChild(copyPromptBtn);
+    const extSlotBottomLeft = document.createElement("div");
+    extSlotBottomLeft.className = "ext-slot ext-slot-bottom-left";
+    canvasContainer.appendChild(extSlotBottomLeft);
+    const extSlotBottomRight = document.createElement("div");
+    extSlotBottomRight.className = "ext-slot ext-slot-bottom-right";
+    canvasContainer.appendChild(extSlotBottomRight);
     topBar.appendChild(topLeft);
     topBar.appendChild(topCenter);
     topBar.appendChild(topRight);
@@ -732,6 +792,9 @@ async function main() {
         toolsPane.setData(currentData);
         emptyState.hide();
         updateUrl(name);
+        publishBridgeState();
+        eventBus.emit("graph-switched");
+        eventBus.emit("graph-changed");
         // Load branches and snapshots — skipped for remote graphs (read-only,
         // no branch/snapshot/snippet APIs on the remote endpoint)
         if (!activeIsRemote) {
@@ -782,31 +845,129 @@ async function main() {
         }
     })
         .catch(() => { });
-    // Load ontology list (local + remote in parallel)
-    const [summaries, remotes] = await Promise.all([
-        listOntologies(),
-        listRemotes().catch(() => []),
-    ]);
-    sidebar.setSummaries(summaries);
-    sidebar.setRemotes(remotes);
-    remoteNames = new Set(remotes.map((r) => r.name));
-    // Auto-load from URL hash, or first graph
-    const initialUrl = parseUrl();
-    const initialName = initialUrl.graph && summaries.some((s) => s.name === initialUrl.graph)
-        ? initialUrl.graph
-        : initialUrl.graph && remoteNames.has(initialUrl.graph)
-            ? initialUrl.graph
-            : summaries.length > 0
-                ? summaries[0].name
-                : remotes.length > 0
-                    ? remotes[0].name
-                    : null;
-    if (initialName) {
-        await selectGraph(initialName, initialUrl.nodes.length ? initialUrl.nodes : undefined, initialUrl.focus.length ? initialUrl.focus : undefined, initialUrl.hops);
+    // --- Share link detection ---
+    // If URL has ?share=TOKEN, load from the relay instead of local API.
+    // The #k=KEY fragment (if present) is used for client-side decryption.
+    const shareParams = new URLSearchParams(window.location.search);
+    const shareToken = shareParams.get("share");
+    if (shareToken) {
+        try {
+            const metaRes = await fetch(`/v1/share/${shareToken}/meta`);
+            if (!metaRes.ok)
+                throw new Error("Share link not found or expired");
+            const meta = await metaRes.json();
+            const dataRes = await fetch(`/v1/share/${shareToken}`);
+            if (!dataRes.ok)
+                throw new Error("Failed to download shared backpack");
+            // Parse the BPAK envelope (inline — avoids pulling Node.js deps from backpack-ontology)
+            const envelopeBytes = new Uint8Array(await dataRes.arrayBuffer());
+            if (envelopeBytes.length < 9 || envelopeBytes[0] !== 0x42 || envelopeBytes[1] !== 0x50 || envelopeBytes[2] !== 0x41 || envelopeBytes[3] !== 0x4B) {
+                throw new Error("Invalid share data: not a BPAK envelope");
+            }
+            const headerLen = new DataView(envelopeBytes.buffer, envelopeBytes.byteOffset, envelopeBytes.byteLength).getUint32(5, false);
+            if (9 + headerLen > envelopeBytes.length)
+                throw new Error("Invalid envelope: header length exceeds data");
+            const envelopeHeader = JSON.parse(new TextDecoder().decode(envelopeBytes.slice(9, 9 + headerLen)));
+            const envelopePayload = envelopeBytes.slice(9 + headerLen);
+            let graphData;
+            if (envelopeHeader.format !== "plaintext") {
+                // Encrypted — decrypt client-side using fragment key
+                const fragment = window.location.hash.slice(1);
+                const keyParam = new URLSearchParams(fragment).get("k") ?? fragment.split("k=")[1];
+                if (!keyParam)
+                    throw new Error("Missing decryption key in URL fragment");
+                const { Decrypter } = await import("age-encryption");
+                const secretKey = atob(keyParam.replace(/-/g, "+").replace(/_/g, "/"));
+                const d = new Decrypter();
+                d.addIdentity(secretKey);
+                const plaintext = await d.decrypt(envelopePayload);
+                graphData = JSON.parse(new TextDecoder().decode(plaintext));
+            }
+            else {
+                graphData = JSON.parse(new TextDecoder().decode(envelopePayload));
+            }
+            // Render in read-only mode
+            activeOntology = meta.backpack_name || "Shared Backpack";
+            currentData = graphData;
+            canvas.loadGraph(graphData);
+            search.setLearningGraphData(graphData);
+            sidebar.setSummaries([{
+                    name: activeOntology,
+                    description: "",
+                    nodeCount: graphData.nodes?.length ?? 0,
+                    edgeCount: graphData.edges?.length ?? 0,
+                    nodeTypes: [],
+                }]);
+            sidebar.setActive(activeOntology);
+            document.title = `${activeOntology} — Backpack`;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : "Failed to load shared backpack";
+            showToast(msg, 5000);
+            emptyState.show();
+        }
     }
     else {
-        emptyState.show();
+        // Normal mode — load from local/cloud API
+        const [summaries, remotes] = await Promise.all([
+            listOntologies(),
+            listRemotes().catch(() => []),
+        ]);
+        sidebar.setSummaries(summaries);
+        sidebar.setRemotes(remotes);
+        remoteNames = new Set(remotes.map((r) => r.name));
+        // Auto-load from URL hash, or first graph
+        const initialUrl = parseUrl();
+        const initialName = initialUrl.graph && summaries.some((s) => s.name === initialUrl.graph)
+            ? initialUrl.graph
+            : initialUrl.graph && remoteNames.has(initialUrl.graph)
+                ? initialUrl.graph
+                : summaries.length > 0
+                    ? summaries[0].name
+                    : remotes.length > 0
+                        ? remotes[0].name
+                        : null;
+        if (initialName) {
+            await selectGraph(initialName, initialUrl.nodes.length ? initialUrl.nodes : undefined, initialUrl.focus.length ? initialUrl.focus : undefined, initialUrl.hops);
+        }
+        else {
+            emptyState.show();
+        }
     }
+    // --- Extension system ---
+    // Load extensions after the viewer is fully initialized so any
+    // extension that immediately reads the current graph state gets a
+    // populated graph (not a startup race).
+    const host = {
+        getGraph: () => currentData,
+        getGraphName: () => activeOntology,
+        getSelection: () => [...currentSelection],
+        getFocus: () => canvas.getFocusInfo(),
+        saveCurrentGraph: async () => {
+            await save();
+        },
+        snapshotForUndo: () => {
+            if (currentData)
+                undoHistory.push(currentData);
+        },
+        panToNode: (id) => canvas.panToNode(id),
+        focusNodes: (ids, hops) => canvas.enterFocus(ids, hops),
+        exitFocus: () => {
+            if (canvas.isFocused())
+                canvas.exitFocus();
+        },
+        taskbarSlots: {
+            topLeft: extSlotTopLeft,
+            topRight: extSlotTopRight,
+            bottomLeft: extSlotBottomLeft,
+            bottomRight: extSlotBottomRight,
+        },
+        subscribe: (event, cb) => eventBus.subscribe(event, cb),
+    };
+    // Fire-and-forget — extension loading errors don't block startup
+    loadExtensions(host, panelMount).catch((err) => {
+        console.error("[backpack-viewer] extension loader failed:", err);
+    });
     // Keyboard shortcuts — dispatched via configurable bindings
     const actions = {
         search() { search.focus(); },
@@ -873,6 +1034,11 @@ async function main() {
         clusteringIncrease() { const p = getLayoutParams(); setLayoutParams({ clusterStrength: Math.min(1, p.clusterStrength + 0.03) }); canvas.reheat(); },
         help() { shortcuts.toggle(); },
         toggleSidebar() { sidebar.toggle(); },
+        resetPins() {
+            const released = canvas.releaseAllPins();
+            if (released)
+                showToast("Manual layout reset — pins released");
+        },
         walkIsolate() {
             if (!currentData)
                 return;
@@ -893,12 +1059,18 @@ async function main() {
                 walkBtn.classList.toggle("active", canvas.getWalkMode());
             syncWalkTrail();
         },
-        escape() { if (canvas.isFocused()) {
-            toolsPane.clearFocusSet();
-        }
-        else {
-            shortcuts.hide();
-        } },
+        escape() {
+            // Priority: 1. clear selection, 2. exit focus, 3. hide help modal
+            if (canvas.getSelectedNodeIds().length > 0) {
+                canvas.clearSelection();
+            }
+            else if (canvas.isFocused()) {
+                toolsPane.clearFocusSet();
+            }
+            else {
+                shortcuts.hide();
+            }
+        },
     };
     document.addEventListener("keydown", (e) => {
         if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement)
@@ -940,6 +1112,12 @@ async function main() {
             await refreshBackpacksAndGraphs();
         });
         import.meta.hot.on("ontology-change", async () => {
+            // If the user had manually pinned nodes, the incoming data change
+            // is going to reset their layout tweaks. Warn them so they know
+            // the change wasn't their fault — this is the one involuntary
+            // pin-release case (graph switches and focus toggles are all
+            // user-initiated and don't need a toast).
+            const hadPins = canvas.hasPinnedNodes();
             const [updated, updatedRemotes] = await Promise.all([
                 listOntologies(),
                 listRemotes().catch(() => []),
@@ -971,6 +1149,9 @@ async function main() {
                 search.setLearningGraphData(currentData);
                 toolsPane.setData(currentData);
             }
+            if (hadPins) {
+                showToast("Manual layout reset — new data arrived");
+            }
         });
     }
 }

package/dist/search.js

@@ -68,7 +68,7 @@ export function initSearch(container, config) {
         updateResults();
     }
     function updateResults() {
-        results.innerHTML = "";
+        results.replaceChildren();
         activeIndex = -1;
         const query = input.value.trim();
         if (!data || query.length === 0) {

package/dist/server-api-routes.d.ts

@@ -0,0 +1,56 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type JsonFileBackend, type RemoteRegistry } from "backpack-ontology";
+import type { ViewerConfig } from "./config.js";
+/**
+ * Shared API route handler. Both `bin/serve.js` (production raw http)
+ * and `vite.config.ts`'s middleware plugin (dev) call `handleApiRequest`
+ * with the raw Node IncomingMessage/ServerResponse — they share the
+ * exact same shape. Each entry only owns the static-file serving and
+ * its own startup wiring.
+ *
+ * Before this module existed, every route below had two near-identical
+ * copies (one per entry file) and adding/changing an endpoint required
+ * editing both, with predictable drift bugs. Consolidated here into a
+ * single source of truth.
+ *
+ * Storage handling: the active backpack can be swapped at runtime via
+ * `/api/backpacks/switch`, which atomically replaces the storage
+ * backend. The context holds a mutable wrapper so the swap is visible
+ * to subsequent requests. Vite needs to broadcast a WebSocket event on
+ * the swap; production has no WS channel, so the hook is optional.
+ */
+export interface BackpackEntry {
+    name: string;
+    path: string;
+    color: string;
+}
+export interface ApiContext {
+    /** Mutable wrapper around the storage backend so backpack-switch can swap it. */
+    storage: {
+        current: JsonFileBackend;
+        activeEntry: BackpackEntry | null;
+    };
+    remoteRegistry: RemoteRegistry;
+    viewerConfig: ViewerConfig;
+    /** Recreate the backend pointing at the active backpack. */
+    makeBackend: () => Promise<{
+        backend: JsonFileBackend;
+        entry: BackpackEntry;
+    }>;
+    /** Optional hook called after a successful backpack switch (vite uses this for WS broadcast). */
+    onActiveBackpackChange?: () => void;
+    /** How to answer GET /api/version-check. Differs between dev (always not-stale) and prod (cached npm lookup). */
+    versionCheck: () => Promise<{
+        current: string;
+        latest: string | null;
+        stale: boolean;
+    }>;
+}
+/**
+ * Try to match and handle an API request. Returns true if the request
+ * was handled (response written), false if no route matched and the
+ * caller should fall through to its own handlers (e.g., static files).
+ *
+ * Errors that escape route handlers result in a 500 with a JSON body.
+ */
+export declare function handleApiRequest(req: IncomingMessage, res: ServerResponse, ctx: ApiContext): Promise<boolean>;