backpack-viewer 0.5.1 → 0.7.0

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

@@ -0,0 +1,281 @@
+/**
+ * Tool definitions handed to the LLM. These are vendor-neutral —
+ * they're shaped like Anthropic's tool format because we're starting
+ * with Claude, but the same shape is trivially adaptable to OpenAI's
+ * function-calling format inside an OpenAI provider implementation.
+ *
+ * The execution side runs against `viewer` (the extension API), which
+ * gives us auto-undo, auto-persist, and auto-rerender for free — the
+ * same call paths the user's manual edits go through.
+ */
+export const TOOLS = [
+    {
+        name: "get_graph_summary",
+        description: "Get a summary of the current learning graph: total nodes, total edges, and counts by node type. Use this first to understand what's in the graph before drilling in.",
+        input_schema: { type: "object", properties: {}, required: [] },
+    },
+    {
+        name: "search_nodes",
+        description: "Search nodes in the current graph by a substring match against any string property. Returns up to 20 matching nodes with id, type, and label.",
+        input_schema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Substring to search for (case-insensitive)" },
+                type: { type: "string", description: "Optional: restrict to nodes of this type" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "get_node",
+        description: "Get full details (all properties + type) for a specific node by id.",
+        input_schema: {
+            type: "object",
+            properties: { nodeId: { type: "string" } },
+            required: ["nodeId"],
+        },
+    },
+    {
+        name: "get_neighbors",
+        description: "Get all nodes directly connected to the given node, with the edge type for each connection.",
+        input_schema: {
+            type: "object",
+            properties: { nodeId: { type: "string" } },
+            required: ["nodeId"],
+        },
+    },
+    {
+        name: "list_node_types",
+        description: "List all distinct node types in the current graph with counts.",
+        input_schema: { type: "object", properties: {}, required: [] },
+    },
+    {
+        name: "add_node",
+        description: "Add a new node to the current graph. Returns the new node id. Properties should follow the existing convention in the graph — use list_node_types and get_node first to see what shape similar nodes use.",
+        input_schema: {
+            type: "object",
+            properties: {
+                type: { type: "string", description: "Node type (freeform)" },
+                properties: {
+                    type: "object",
+                    description: "Freeform key/value properties — usually includes a 'name' or 'title' field",
+                },
+            },
+            required: ["type", "properties"],
+        },
+    },
+    {
+        name: "update_node",
+        description: "Update properties on an existing node. Pass only the properties you want to change — others are preserved.",
+        input_schema: {
+            type: "object",
+            properties: {
+                nodeId: { type: "string" },
+                properties: { type: "object" },
+            },
+            required: ["nodeId", "properties"],
+        },
+    },
+    {
+        name: "remove_node",
+        description: "Delete a node and all edges touching it. This is destructive — confirm with the user first if the node is non-trivial.",
+        input_schema: {
+            type: "object",
+            properties: { nodeId: { type: "string" } },
+            required: ["nodeId"],
+        },
+    },
+    {
+        name: "add_edge",
+        description: "Connect two existing nodes with a typed edge.",
+        input_schema: {
+            type: "object",
+            properties: {
+                sourceId: { type: "string" },
+                targetId: { type: "string" },
+                type: { type: "string", description: "Edge type (freeform, e.g. 'contains', 'depends_on')" },
+            },
+            required: ["sourceId", "targetId", "type"],
+        },
+    },
+    {
+        name: "remove_edge",
+        description: "Delete an edge by id.",
+        input_schema: {
+            type: "object",
+            properties: { edgeId: { type: "string" } },
+            required: ["edgeId"],
+        },
+    },
+    {
+        name: "focus_nodes",
+        description: "Tell the viewer to enter focus mode on the given seed nodes, expanding to N hops of neighbors. Call this when the user is asking about a specific region of the graph so they can see what you're talking about.",
+        input_schema: {
+            type: "object",
+            properties: {
+                nodeIds: { type: "array", items: { type: "string" } },
+                hops: { type: "number", description: "Hop distance (default 1)" },
+            },
+            required: ["nodeIds"],
+        },
+    },
+    {
+        name: "pan_to_node",
+        description: "Pan and zoom the viewer to a specific node.",
+        input_schema: {
+            type: "object",
+            properties: { nodeId: { type: "string" } },
+            required: ["nodeId"],
+        },
+    },
+];
+function labelOf(node) {
+    const first = Object.values(node.properties).find((v) => typeof v === "string");
+    return first ?? node.id;
+}
+/**
+ * Execute one tool call against the viewer extension API. Returns a
+ * string that gets fed back to the LLM as the tool_result. Throws on
+ * bad input — the caller turns the error into a tool_result with
+ * `is_error: true`.
+ */
+export async function executeTool(viewer, name, input) {
+    const data = viewer.getGraph();
+    if (!data)
+        throw new Error("no graph loaded in viewer");
+    switch (name) {
+        case "get_graph_summary": {
+            const typeCounts = new Map();
+            for (const n of data.nodes) {
+                typeCounts.set(n.type, (typeCounts.get(n.type) ?? 0) + 1);
+            }
+            return JSON.stringify({
+                name: viewer.getGraphName(),
+                nodeCount: data.nodes.length,
+                edgeCount: data.edges.length,
+                nodeTypes: Object.fromEntries(typeCounts),
+            }, null, 2);
+        }
+        case "search_nodes": {
+            const query = String(input.query ?? "").toLowerCase();
+            const filterType = input.type ? String(input.type) : null;
+            if (!query)
+                throw new Error("query is required");
+            const matches = [];
+            for (const n of data.nodes) {
+                if (filterType && n.type !== filterType)
+                    continue;
+                const haystack = Object.values(n.properties)
+                    .filter((v) => typeof v === "string")
+                    .join(" ")
+                    .toLowerCase();
+                if (haystack.includes(query) || n.id.toLowerCase().includes(query)) {
+                    matches.push({ id: n.id, type: n.type, label: labelOf(n) });
+                    if (matches.length >= 20)
+                        break;
+                }
+            }
+            return JSON.stringify({ query, matchCount: matches.length, matches }, null, 2);
+        }
+        case "get_node": {
+            const nodeId = String(input.nodeId ?? "");
+            const node = data.nodes.find((n) => n.id === nodeId);
+            if (!node)
+                throw new Error(`node not found: ${nodeId}`);
+            return JSON.stringify(node, null, 2);
+        }
+        case "get_neighbors": {
+            const nodeId = String(input.nodeId ?? "");
+            const node = data.nodes.find((n) => n.id === nodeId);
+            if (!node)
+                throw new Error(`node not found: ${nodeId}`);
+            const neighbors = [];
+            for (const e of data.edges) {
+                if (e.sourceId === nodeId) {
+                    const other = data.nodes.find((n) => n.id === e.targetId);
+                    if (other) {
+                        neighbors.push({
+                            edgeId: e.id,
+                            edgeType: e.type,
+                            direction: "out",
+                            node: { id: other.id, type: other.type, label: labelOf(other) },
+                        });
+                    }
+                }
+                else if (e.targetId === nodeId) {
+                    const other = data.nodes.find((n) => n.id === e.sourceId);
+                    if (other) {
+                        neighbors.push({
+                            edgeId: e.id,
+                            edgeType: e.type,
+                            direction: "in",
+                            node: { id: other.id, type: other.type, label: labelOf(other) },
+                        });
+                    }
+                }
+            }
+            return JSON.stringify({ nodeId, label: labelOf(node), neighborCount: neighbors.length, neighbors }, null, 2);
+        }
+        case "list_node_types": {
+            const counts = new Map();
+            for (const n of data.nodes)
+                counts.set(n.type, (counts.get(n.type) ?? 0) + 1);
+            return JSON.stringify(Object.fromEntries(counts), null, 2);
+        }
+        case "add_node": {
+            const type = String(input.type ?? "");
+            const properties = (input.properties ?? {});
+            if (!type)
+                throw new Error("type is required");
+            const id = await viewer.addNode(type, properties);
+            return JSON.stringify({ ok: true, id, type }, null, 2);
+        }
+        case "update_node": {
+            const nodeId = String(input.nodeId ?? "");
+            const properties = (input.properties ?? {});
+            await viewer.updateNode(nodeId, properties);
+            return JSON.stringify({ ok: true, id: nodeId }, null, 2);
+        }
+        case "remove_node": {
+            const nodeId = String(input.nodeId ?? "");
+            await viewer.removeNode(nodeId);
+            return JSON.stringify({ ok: true, removed: nodeId }, null, 2);
+        }
+        case "add_edge": {
+            const sourceId = String(input.sourceId ?? "");
+            const targetId = String(input.targetId ?? "");
+            const type = String(input.type ?? "");
+            if (!sourceId || !targetId || !type) {
+                throw new Error("sourceId, targetId, and type are required");
+            }
+            const id = await viewer.addEdge(sourceId, targetId, type);
+            return JSON.stringify({ ok: true, id }, null, 2);
+        }
+        case "remove_edge": {
+            const edgeId = String(input.edgeId ?? "");
+            await viewer.removeEdge(edgeId);
+            return JSON.stringify({ ok: true, removed: edgeId }, null, 2);
+        }
+        case "focus_nodes": {
+            const nodeIds = (input.nodeIds ?? []);
+            const hops = typeof input.hops === "number" ? input.hops : 1;
+            if (nodeIds.length === 0)
+                throw new Error("nodeIds is required");
+            const valid = nodeIds.filter((id) => data.nodes.some((n) => n.id === id));
+            if (valid.length === 0)
+                throw new Error("no valid node ids in focus_nodes");
+            viewer.focusNodes(valid, hops);
+            return JSON.stringify({ ok: true, focused: valid, hops }, null, 2);
+        }
+        case "pan_to_node": {
+            const nodeId = String(input.nodeId ?? "");
+            const node = data.nodes.find((n) => n.id === nodeId);
+            if (!node)
+                throw new Error(`node not found: ${nodeId}`);
+            viewer.panToNode(nodeId);
+            return JSON.stringify({ ok: true, panned: nodeId }, null, 2);
+        }
+        default:
+            throw new Error(`unknown tool: ${name}`);
+    }
+}

package/dist/extensions/chat/style.css

@@ -0,0 +1,147 @@
+/* Chat extension stylesheet — loaded by the extension loader from
+   <viewer-origin>/extensions/chat/style.css. All styles are scoped to
+   chat-ext-* class names so they don't collide with other extensions
+   or the viewer core. */
+
+.chat-ext-body {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 320px;
+}
+
+.chat-ext-messages {
+  flex: 1;
+  overflow-y: auto;
+  padding: 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-height: 200px;
+  max-height: 60vh;
+}
+
+.chat-ext-intro {
+  font-size: 12px;
+  color: var(--text-muted);
+  line-height: 1.5;
+  padding: 8px 10px;
+  border-radius: 6px;
+  background: var(--bg-hover);
+}
+
+.chat-ext-msg {
+  display: flex;
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.chat-ext-msg-text {
+  padding: 8px 12px;
+  border-radius: 10px;
+  max-width: 90%;
+  white-space: pre-wrap;
+  word-wrap: break-word;
+}
+
+.chat-ext-msg-user {
+  justify-content: flex-end;
+}
+
+.chat-ext-msg-user .chat-ext-msg-text {
+  background: var(--accent, #d4a27f);
+  color: #1a1a1a;
+}
+
+.chat-ext-msg-assistant {
+  justify-content: flex-start;
+}
+
+.chat-ext-msg-assistant .chat-ext-msg-text {
+  background: var(--bg-hover);
+  color: var(--text);
+}
+
+.chat-ext-tool-call {
+  font-size: 11px;
+  font-family: monospace;
+  color: var(--text-muted);
+  padding: 4px 8px;
+  border-left: 2px solid var(--accent, #d4a27f);
+  margin-left: 8px;
+  opacity: 0.85;
+  word-break: break-all;
+}
+
+.chat-ext-tool-result {
+  font-size: 11px;
+  font-family: monospace;
+  color: var(--text-dim);
+  padding: 4px 8px;
+  border-left: 2px solid var(--border);
+  margin-left: 8px;
+  opacity: 0.7;
+  white-space: pre-wrap;
+  word-break: break-all;
+}
+
+.chat-ext-tool-error {
+  font-size: 11px;
+  color: #ef4444;
+  padding: 4px 8px;
+  border-left: 2px solid #ef4444;
+  margin-left: 8px;
+}
+
+.chat-ext-input-row {
+  display: flex;
+  gap: 8px;
+  padding: 10px 12px;
+  border-top: 1px solid var(--border);
+  flex-shrink: 0;
+}
+
+.chat-ext-input {
+  flex: 1;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  color: var(--text);
+  padding: 6px 10px;
+  font-family: inherit;
+  font-size: 13px;
+  line-height: 1.4;
+  resize: none;
+  outline: none;
+  transition: border-color 0.15s;
+}
+
+.chat-ext-input:focus {
+  border-color: var(--accent, #d4a27f);
+}
+
+.chat-ext-input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.chat-ext-send {
+  background: var(--accent, #d4a27f);
+  border: none;
+  border-radius: 6px;
+  color: #1a1a1a;
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  padding: 6px 14px;
+  transition: opacity 0.15s;
+}
+
+.chat-ext-send:hover:not(:disabled) {
+  opacity: 0.85;
+}
+
+.chat-ext-send:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}

package/dist/extensions/event-bus.d.ts

@@ -0,0 +1,12 @@
+import type { ViewerEvent } from "./types";
+/**
+ * Tiny pub/sub for viewer events. Used by main.ts to emit and by the
+ * extension API to subscribe. Synchronous — handlers run in registration
+ * order on the same tick as the emit. Errors in one handler don't affect
+ * others.
+ */
+export interface EventBus {
+    emit(event: ViewerEvent): void;
+    subscribe(event: ViewerEvent, cb: () => void): () => void;
+}
+export declare function createEventBus(): EventBus;

package/dist/extensions/event-bus.js

@@ -0,0 +1,30 @@
+export function createEventBus() {
+    const handlers = new Map();
+    return {
+        emit(event) {
+            const set = handlers.get(event);
+            if (!set)
+                return;
+            for (const cb of set) {
+                try {
+                    cb();
+                }
+                catch (err) {
+                    console.error(`[backpack-viewer] event handler for ${event} threw:`, err);
+                }
+            }
+        },
+        subscribe(event, cb) {
+            let set = handlers.get(event);
+            if (!set) {
+                set = new Set();
+                handlers.set(event, set);
+            }
+            set.add(cb);
+            return () => {
+                const s = handlers.get(event);
+                s?.delete(cb);
+            };
+        },
+    };
+}

package/dist/extensions/loader.d.ts

@@ -0,0 +1,32 @@
+import type { ViewerExtensionAPI, ViewerHost } from "./types";
+import type { PanelMount } from "./panel-mount";
+/**
+ * Browser-side extension loader.
+ *
+ * On startup, fetches `/api/extensions` to learn which extensions the
+ * server has loaded. For each one:
+ *   1. Constructs a per-extension API instance scoped to its name
+ *   2. Loads the extension's stylesheet (if any) by appending a <link>
+ *   3. Dynamic-imports the extension's entry file from
+ *      `/extensions/<name>/<entry>`
+ *   4. Calls `module.activate(api)` inside a try/catch
+ *
+ * One extension's failure (load error, activate throw) does not affect
+ * the others. Errors are surfaced to the console with the extension
+ * name so the user can debug.
+ */
+interface ExtensionInfo {
+    name: string;
+    version: string;
+    viewerApi: string;
+    displayName?: string;
+    description?: string;
+    entry: string;
+    stylesheet?: string;
+}
+export interface LoadedExtensionInstance {
+    info: ExtensionInfo;
+    api: ViewerExtensionAPI;
+}
+export declare function loadExtensions(host: ViewerHost, panelMount: PanelMount): Promise<LoadedExtensionInstance[]>;
+export {};

package/dist/extensions/loader.js

@@ -0,0 +1,71 @@
+import { createExtensionAPI } from "./api";
+import { createTaskbar } from "./taskbar";
+import { VIEWER_API_VERSION } from "./types";
+export async function loadExtensions(host, panelMount) {
+    // Construct the taskbar (icons routed into one of four host-owned
+    // slot containers). Panel mount is provided by main.ts so the same
+    // instance is shared with built-in panels (info-panel) — that way
+    // the click-to-front z-stack and persistent storage work across the
+    // whole panel system.
+    const taskbar = createTaskbar(host.taskbarSlots);
+    let infos = [];
+    try {
+        const res = await fetch("/api/extensions");
+        if (!res.ok) {
+            console.warn(`[backpack-viewer] /api/extensions returned ${res.status}; no extensions will be loaded`);
+            return [];
+        }
+        infos = (await res.json());
+    }
+    catch (err) {
+        console.error(`[backpack-viewer] failed to fetch extensions list: ${err.message}`);
+        return [];
+    }
+    const loaded = [];
+    for (const info of infos) {
+        if (info.viewerApi !== VIEWER_API_VERSION) {
+            console.warn(`[backpack-viewer] extension "${info.name}" targets viewerApi "${info.viewerApi}" but this viewer supports "${VIEWER_API_VERSION}"; skipping`);
+            continue;
+        }
+        // Load stylesheet first so it's available before the extension's
+        // panel/widget mounts.
+        if (info.stylesheet) {
+            try {
+                loadStylesheet(info.name, info.stylesheet);
+            }
+            catch (err) {
+                console.error(`[backpack-viewer] extension "${info.name}" stylesheet load failed:`, err);
+            }
+        }
+        const api = createExtensionAPI(info.name, host, taskbar, panelMount);
+        try {
+            const moduleUrl = `/extensions/${encodeURIComponent(info.name)}/${info.entry}`;
+            const mod = await import(/* @vite-ignore */ moduleUrl);
+            const activate = mod.activate;
+            if (typeof activate !== "function") {
+                console.error(`[backpack-viewer] extension "${info.name}" has no exported activate(api) function; skipping`);
+                continue;
+            }
+            await activate(api);
+            loaded.push({ info, api });
+            console.log(`[backpack-viewer] loaded extension "${info.name}" v${info.version}`);
+        }
+        catch (err) {
+            console.error(`[backpack-viewer] extension "${info.name}" failed to activate:`, err);
+        }
+    }
+    return loaded;
+}
+function loadStylesheet(extName, stylesheet) {
+    // Reject anything that smells like a path traversal — the server
+    // already enforces this server-side, but we mirror it client-side
+    // for clarity.
+    if (stylesheet.includes("..")) {
+        throw new Error(`stylesheet path "${stylesheet}" is invalid`);
+    }
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = `/extensions/${encodeURIComponent(extName)}/${stylesheet}`;
+    link.dataset.extension = extName;
+    document.head.appendChild(link);
+}

package/dist/extensions/manifest.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Manifest schema for `backpack-extension.json`. Hand-rolled validation
+ * (no zod) because the manifest is small and we want zero runtime deps
+ * for the extension system.
+ */
+export interface NetworkPermission {
+    /** Origin the extension is allowed to call (e.g. "https://api.anthropic.com") */
+    origin: string;
+    /**
+     * Headers to inject server-side when this extension fetches the
+     * matching origin. Each value is either { fromEnv: ENV_VAR_NAME } —
+     * pulled from process.env, never sent to browser — or { literal: "..." }
+     * — a fixed string baked into the manifest. Used for things like API
+     * keys (env) or anthropic-version (literal).
+     */
+    injectHeaders?: Record<string, {
+        fromEnv: string;
+    } | {
+        literal: string;
+    }>;
+}
+export interface ManifestPermissions {
+    graph?: ("read" | "write")[];
+    viewer?: ("focus" | "pan")[];
+    settings?: boolean;
+    network?: NetworkPermission[];
+}
+export interface ExtensionManifest {
+    /** Extension id, must match its on-disk dir name. */
+    name: string;
+    /** Extension version (semver-ish, free-form). */
+    version: string;
+    /** Versioned API contract this extension targets. */
+    viewerApi: string;
+    /** Human-readable display name shown in the UI. */
+    displayName?: string;
+    /** Short user-facing description. */
+    description?: string;
+    /** Path to the JS entry file, relative to the extension directory. */
+    entry: string;
+    /** Optional CSS file relative to the extension dir. */
+    stylesheet?: string;
+    /** What this extension is allowed to do. */
+    permissions?: ManifestPermissions;
+}
+export declare class ManifestError extends Error {
+    constructor(extensionPath: string, problem: string);
+}
+/**
+ * Validate a parsed manifest object. Throws ManifestError on invalid input.
+ * Returns the typed manifest. Stricter than tsc since the file comes from
+ * disk; we want clear errors at load time, not silent misbehavior later.
+ */
+export declare function validateManifest(raw: unknown, extensionPath: string): ExtensionManifest;