backpack-viewer 0.6.0 → 0.7.1

package/dist/dom-utils.js

@@ -0,0 +1,57 @@
+/**
+ * Tiny DOM helpers used across the viewer to avoid `innerHTML` for
+ * static SVG icons and other markup that previously got built as
+ * strings. Keeps every call site CSP-clean and XSS-safe by construction
+ * (no string concatenation, no parsing of user content).
+ */
+const SVG_NS = "http://www.w3.org/2000/svg";
+/**
+ * Build an SVG icon from a list of child element specs. Each spec is
+ * `{ tag, attrs }` where tag is one of the standard SVG element names.
+ *
+ * Example:
+ *   makeSvgIcon({ size: 14 }, [
+ *     { tag: "polyline", attrs: { points: "11 17 6 12 11 7" } },
+ *     { tag: "polyline", attrs: { points: "18 17 13 12 18 7" } },
+ *   ])
+ */
+export function makeSvgIcon(opts, children) {
+    const svg = document.createElementNS(SVG_NS, "svg");
+    const size = opts.size ?? 16;
+    svg.setAttribute("width", String(size));
+    svg.setAttribute("height", String(size));
+    svg.setAttribute("viewBox", opts.viewBox ?? "0 0 24 24");
+    svg.setAttribute("fill", "none");
+    svg.setAttribute("stroke", "currentColor");
+    svg.setAttribute("stroke-width", String(opts.strokeWidth ?? 2));
+    if (opts.strokeLinecap)
+        svg.setAttribute("stroke-linecap", opts.strokeLinecap);
+    if (opts.strokeLinejoin)
+        svg.setAttribute("stroke-linejoin", opts.strokeLinejoin);
+    if (opts.className)
+        svg.setAttribute("class", opts.className);
+    for (const child of children) {
+        const el = document.createElementNS(SVG_NS, child.tag);
+        for (const [k, v] of Object.entries(child.attrs)) {
+            el.setAttribute(k, String(v));
+        }
+        svg.appendChild(el);
+    }
+    return svg;
+}
+/**
+ * Snapshot the current children of an element so they can be restored
+ * later via `restoreChildren()`. Used by inline-edit flows that
+ * temporarily replace a row's contents with an input.
+ *
+ * Returns a frozen array of cloned nodes — the original references are
+ * NOT preserved (which would break if the parent is mutated). Cloning
+ * is fine because the snapshotted markup is static — no event handlers
+ * to lose.
+ */
+export function snapshotChildren(el) {
+    return Array.from(el.childNodes).map((n) => n.cloneNode(true));
+}
+export function restoreChildren(el, snapshot) {
+    el.replaceChildren(...snapshot);
+}

package/dist/empty-state.js

@@ -1,37 +1,69 @@
+import { makeSvgIcon } from "./dom-utils";
 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">
-          <path d="M21 16V8a2 2 0 00-1-1.73l-7-4a2 2 0 00-2 0l-7 4A2 2 0 002 8v8a2 2 0 001 1.73l7 4a2 2 0 002 0l7-4A2 2 0 0022 16z"/>
-          <polyline points="3.27 6.96 12 12.01 20.73 6.96"/>
-          <line x1="12" y1="22.08" x2="12" y2="12"/>
-        </svg>
-      </div>
-      <h2 class="empty-state-title">No learning graphs yet</h2>
-      <p class="empty-state-desc">Connect Backpack to Claude, then start a conversation. Claude will build your first learning graph automatically.</p>
-      <div class="empty-state-setup">
-        <div class="empty-state-label">Add Backpack to Claude Code:</div>
-        <code class="empty-state-code">claude mcp add backpack-local -s user -- npx backpack-ontology@latest</code>
-      </div>
-      <p class="empty-state-hint">Press <kbd>?</kbd> for keyboard shortcuts</p>
-    </div>
-  `;
+    // Background circles + decorative line art
+    const bg = document.createElement("div");
+    bg.className = "empty-state-bg";
+    for (const cls of ["c1", "c2", "c3", "c4", "c5"]) {
+        const circle = document.createElement("div");
+        circle.className = `empty-state-circle ${cls}`;
+        bg.appendChild(circle);
+    }
+    bg.appendChild(makeSvgIcon({ size: 0, viewBox: "0 0 400 300", className: "empty-state-lines" }, [
+        { tag: "line", attrs: { x1: 80, y1: 60, x2: 220, y2: 140, "stroke-width": "0.5", opacity: "0.15" } },
+        { tag: "line", attrs: { x1: 220, y1: 140, x2: 320, y2: 80, "stroke-width": "0.5", opacity: "0.15" } },
+        { tag: "line", attrs: { x1: 220, y1: 140, x2: 160, y2: 240, "stroke-width": "0.5", opacity: "0.15" } },
+        { tag: "line", attrs: { x1: 160, y1: 240, x2: 300, y2: 220, "stroke-width": "0.5", opacity: "0.15" } },
+    ]));
+    // makeSvgIcon sets width/height attrs; the lines layer is sized by CSS
+    // (preserveAspectRatio comes from the empty-state-lines class).
+    const linesSvg = bg.querySelector(".empty-state-lines");
+    if (linesSvg) {
+        linesSvg.removeAttribute("width");
+        linesSvg.removeAttribute("height");
+        linesSvg.setAttribute("preserveAspectRatio", "xMidYMid slice");
+    }
+    el.appendChild(bg);
+    // Content card
+    const content = document.createElement("div");
+    content.className = "empty-state-content";
+    const iconWrap = document.createElement("div");
+    iconWrap.className = "empty-state-icon";
+    iconWrap.appendChild(makeSvgIcon({ size: 48, strokeWidth: 1.5, strokeLinecap: "round", strokeLinejoin: "round" }, [
+        { tag: "path", attrs: { d: "M21 16V8a2 2 0 00-1-1.73l-7-4a2 2 0 00-2 0l-7 4A2 2 0 002 8v8a2 2 0 001 1.73l7 4a2 2 0 002 0l7-4A2 2 0 0022 16z" } },
+        { tag: "polyline", attrs: { points: "3.27 6.96 12 12.01 20.73 6.96" } },
+        { tag: "line", attrs: { x1: 12, y1: 22.08, x2: 12, y2: 12 } },
+    ]));
+    content.appendChild(iconWrap);
+    const title = document.createElement("h2");
+    title.className = "empty-state-title";
+    title.textContent = "No learning graphs yet";
+    content.appendChild(title);
+    const desc = document.createElement("p");
+    desc.className = "empty-state-desc";
+    desc.textContent =
+        "Connect Backpack to Claude, then start a conversation. Claude will build your first learning graph automatically.";
+    content.appendChild(desc);
+    const setup = document.createElement("div");
+    setup.className = "empty-state-setup";
+    const setupLabel = document.createElement("div");
+    setupLabel.className = "empty-state-label";
+    setupLabel.textContent = "Add Backpack to Claude Code:";
+    const setupCode = document.createElement("code");
+    setupCode.className = "empty-state-code";
+    setupCode.textContent = "claude mcp add backpack-local -s user -- npx backpack-ontology@latest";
+    setup.append(setupLabel, setupCode);
+    content.appendChild(setup);
+    const hint = document.createElement("p");
+    hint.className = "empty-state-hint";
+    hint.append("Press ");
+    const kbd = document.createElement("kbd");
+    kbd.textContent = "?";
+    hint.appendChild(kbd);
+    hint.append(" for keyboard shortcuts");
+    content.appendChild(hint);
+    el.appendChild(content);
     container.appendChild(el);
     return {
         show() { el.classList.remove("hidden"); },

package/dist/extensions/api.d.ts

@@ -0,0 +1,15 @@
+import type { ViewerExtensionAPI, ViewerHost } from "./types";
+import type { Taskbar } from "./taskbar";
+import type { PanelMount } from "./panel-mount";
+/**
+ * Construct a per-extension `ViewerExtensionAPI` instance. Each loaded
+ * extension gets its own API object whose closures know its name — that
+ * scoping is what makes per-extension settings + per-extension fetch
+ * proxies work.
+ *
+ * The API surface is intentionally minimal in v1: graph reads, graph
+ * mutations (auto-undo, auto-persist, auto-rerender), viewer driving,
+ * mount surfaces, settings, network proxy. Anything else extensions
+ * need will get added in v2 with a viewerApi version bump.
+ */
+export declare function createExtensionAPI(extensionName: string, host: ViewerHost, taskbar: Taskbar, panelMount: PanelMount): ViewerExtensionAPI;

package/dist/extensions/api.js

@@ -0,0 +1,185 @@
+import { VIEWER_API_VERSION } from "./types";
+/**
+ * Construct a per-extension `ViewerExtensionAPI` instance. Each loaded
+ * extension gets its own API object whose closures know its name — that
+ * scoping is what makes per-extension settings + per-extension fetch
+ * proxies work.
+ *
+ * The API surface is intentionally minimal in v1: graph reads, graph
+ * mutations (auto-undo, auto-persist, auto-rerender), viewer driving,
+ * mount surfaces, settings, network proxy. Anything else extensions
+ * need will get added in v2 with a viewerApi version bump.
+ */
+export function createExtensionAPI(extensionName, host, taskbar, panelMount) {
+    function newId() {
+        // Sufficient for client-side ids; backpack-ontology accepts arbitrary
+        // string ids and we already use a similar pattern in main.ts callbacks.
+        return Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
+    }
+    function ensureGraph() {
+        const data = host.getGraph();
+        if (!data)
+            throw new Error("no graph loaded in viewer");
+        return data;
+    }
+    return {
+        name: extensionName,
+        viewerApiVersion: VIEWER_API_VERSION,
+        // --- Graph reads ---
+        getGraph: () => host.getGraph(),
+        getGraphName: () => host.getGraphName(),
+        getSelection: () => host.getSelection(),
+        getFocus: () => host.getFocus(),
+        // --- Events ---
+        on(event, callback) {
+            return host.subscribe(event, callback);
+        },
+        // --- Graph mutations ---
+        async addNode(type, properties) {
+            if (!type)
+                throw new Error("addNode: type is required");
+            const data = ensureGraph();
+            host.snapshotForUndo();
+            const id = newId();
+            const now = new Date().toISOString();
+            data.nodes.push({
+                id,
+                type,
+                properties: properties,
+                createdAt: now,
+                updatedAt: now,
+            });
+            await host.saveCurrentGraph();
+            return id;
+        },
+        async updateNode(nodeId, properties) {
+            const data = ensureGraph();
+            const node = data.nodes.find((n) => n.id === nodeId);
+            if (!node)
+                throw new Error(`updateNode: node not found: ${nodeId}`);
+            host.snapshotForUndo();
+            node.properties = { ...node.properties, ...properties };
+            node.updatedAt = new Date().toISOString();
+            await host.saveCurrentGraph();
+        },
+        async removeNode(nodeId) {
+            const data = ensureGraph();
+            const node = data.nodes.find((n) => n.id === nodeId);
+            if (!node)
+                throw new Error(`removeNode: node not found: ${nodeId}`);
+            host.snapshotForUndo();
+            data.nodes = data.nodes.filter((n) => n.id !== nodeId);
+            data.edges = data.edges.filter((e) => e.sourceId !== nodeId && e.targetId !== nodeId);
+            await host.saveCurrentGraph();
+        },
+        async addEdge(sourceId, targetId, type) {
+            if (!sourceId || !targetId || !type) {
+                throw new Error("addEdge: sourceId, targetId, and type are required");
+            }
+            const data = ensureGraph();
+            if (!data.nodes.find((n) => n.id === sourceId)) {
+                throw new Error(`addEdge: source not found: ${sourceId}`);
+            }
+            if (!data.nodes.find((n) => n.id === targetId)) {
+                throw new Error(`addEdge: target not found: ${targetId}`);
+            }
+            host.snapshotForUndo();
+            const id = newId();
+            data.edges.push({ id, sourceId, targetId, type });
+            await host.saveCurrentGraph();
+            return id;
+        },
+        async removeEdge(edgeId) {
+            const data = ensureGraph();
+            const edge = data.edges.find((e) => e.id === edgeId);
+            if (!edge)
+                throw new Error(`removeEdge: edge not found: ${edgeId}`);
+            host.snapshotForUndo();
+            data.edges = data.edges.filter((e) => e.id !== edgeId);
+            await host.saveCurrentGraph();
+        },
+        // --- Viewer driving ---
+        panToNode: (nodeId) => host.panToNode(nodeId),
+        focusNodes: (nodeIds, hops) => host.focusNodes(nodeIds, hops),
+        exitFocus: () => host.exitFocus(),
+        // --- UI mounting ---
+        registerTaskbarIcon(opts) {
+            return taskbar.register(opts);
+        },
+        mountPanel(element, opts) {
+            return panelMount.mount(extensionName, element, opts);
+        },
+        // --- Settings ---
+        settings: {
+            async get(key) {
+                const url = `/api/extensions/${encodeURIComponent(extensionName)}/settings`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    return null;
+                const all = (await res.json());
+                return key in all ? all[key] : null;
+            },
+            async set(key, value) {
+                const url = `/api/extensions/${encodeURIComponent(extensionName)}/settings/${encodeURIComponent(key)}`;
+                const res = await fetch(url, {
+                    method: "PUT",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ value }),
+                });
+                if (!res.ok) {
+                    const err = await res.text().catch(() => "");
+                    throw new Error(`settings.set failed: ${err || res.status}`);
+                }
+            },
+            async remove(key) {
+                const url = `/api/extensions/${encodeURIComponent(extensionName)}/settings/${encodeURIComponent(key)}`;
+                const res = await fetch(url, { method: "DELETE" });
+                if (!res.ok) {
+                    const err = await res.text().catch(() => "");
+                    throw new Error(`settings.remove failed: ${err || res.status}`);
+                }
+            },
+        },
+        // --- Network ---
+        async fetch(url, init = {}) {
+            // The browser-side viewer.fetch wraps the call into a POST against
+            // the per-extension proxy endpoint. The proxy validates the URL
+            // against the manifest's network allowlist and injects any
+            // configured headers (env-var or literal) server-side.
+            const proxyUrl = `/api/extensions/${encodeURIComponent(extensionName)}/fetch`;
+            const headers = {};
+            if (init.headers) {
+                if (init.headers instanceof Headers) {
+                    init.headers.forEach((v, k) => {
+                        headers[k] = v;
+                    });
+                }
+                else if (Array.isArray(init.headers)) {
+                    for (const [k, v] of init.headers)
+                        headers[k] = v;
+                }
+                else {
+                    Object.assign(headers, init.headers);
+                }
+            }
+            const body = typeof init.body === "string" || init.body == null
+                ? init.body
+                : // RequestInit body can be many things; for v1 we only support
+                    // strings (which is what JSON-based APIs use). Throw on
+                    // anything else so extension authors get a clear error.
+                    (() => {
+                        throw new Error("viewer.fetch only supports string bodies in v1");
+                    })();
+            return fetch(proxyUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    url,
+                    method: init.method ?? "POST",
+                    headers,
+                    body,
+                }),
+            });
+        },
+    };
+}

package/dist/extensions/chat/backpack-extension.json

@@ -0,0 +1,23 @@
+{
+  "name": "chat",
+  "version": "0.1.0",
+  "viewerApi": "1",
+  "displayName": "Chat",
+  "description": "Chat with Claude (or another LLM provider) about your graph. The model can read nodes, follow edges, and add/edit/remove graph data with your approval.",
+  "entry": "src/index.js",
+  "stylesheet": "style.css",
+  "permissions": {
+    "graph": ["read", "write"],
+    "viewer": ["focus", "pan"],
+    "settings": true,
+    "network": [
+      {
+        "origin": "https://api.anthropic.com",
+        "injectHeaders": {
+          "x-api-key": { "fromEnv": "ANTHROPIC_API_KEY" },
+          "anthropic-version": { "literal": "2023-06-01" }
+        }
+      }
+    ]
+  }
+}

package/dist/extensions/chat/src/index.js

@@ -0,0 +1,32 @@
+import { createAnthropicProvider } from "./providers/anthropic.js";
+import { createChatPanelController } from "./panel.js";
+/**
+ * Chat extension entry. The viewer's loader dynamic-imports this file
+ * and calls `activate(viewer)`.
+ *
+ * Wires up:
+ *   - One LLM provider (Anthropic for v1; future: OpenAI, Ollama, …)
+ *   - The chat panel controller (mounts/unmounts the panel)
+ *   - A taskbar icon that toggles the panel
+ *
+ * Everything goes through the viewer extension API. There is no
+ * special-case wiring into viewer internals — this extension uses
+ * exactly the same surface a third-party extension would.
+ */
+export function activate(viewer) {
+    const provider = createAnthropicProvider(viewer.fetch.bind(viewer));
+    const controller = createChatPanelController(viewer, provider);
+    viewer.registerTaskbarIcon({
+        label: "Chat",
+        // Top-right groups the chat toggle with the existing top-bar
+        // controls (zoom, copy-prompt, theme) and aligns visually with the
+        // chat panel itself, which docks to the right side of the canvas.
+        position: "top-right",
+        onClick: () => controller.toggle(),
+    });
+    // Restore any persisted history before the user opens the panel.
+    // Errors are non-fatal — first run has nothing to restore.
+    controller.loadHistory().catch((err) => {
+        console.warn("[chat] failed to load history:", err);
+    });
+}