backpack-viewer 0.1.3

package/README.md

@@ -0,0 +1,94 @@
+# Backpack Ontology Viewer
+
+A web-based graph visualizer for [backpack-ontology](../backpack-ontology). Renders ontology graphs on a Canvas 2D surface with force-directed layout, pan/zoom navigation, node inspection, and live reload when data changes.
+
+## Quick Start
+
+```bash
+# Build the ontology engine first (required — viewer depends on it)
+cd ../backpack-ontology && npm run build
+
+# Install and start the viewer
+cd ../backpack-viewer
+npm install
+npm run dev
+```
+
+Open [http://localhost:5173](http://localhost:5173). The sidebar lists all ontologies stored by backpack-ontology. Click one to visualize it.
+
+## How It Works
+
+### Architecture
+
+```
+Claude (MCP tools) ──writes──> StorageBackend ──persists──> ontology data
+                                     │
+Viewer (Vite plugin) ──reads via─────┘
+         │
+    HTTP API ──> Browser ──> Canvas 2D
+```
+
+The viewer connects to backpack-ontology through the `StorageBackend` interface — the same abstraction the engine uses for persistence. It calls two methods:
+
+- `listOntologies()` — returns names, descriptions, and counts
+- `loadOntology(name)` — returns the full graph (nodes + edges)
+
+This means the viewer works with **any** storage backend (JSON files, SQLite, remote API) without code changes.
+
+### Live Reload
+
+The Vite dev server watches the ontologies directory for file changes. When Claude adds or modifies nodes via MCP tools, the viewer automatically re-fetches and re-renders the active graph.
+
+### Rendering
+
+- **Layout**: Custom force-directed algorithm (repulsion + spring attraction + centering gravity). Nodes start in a circle and settle over ~200 frames.
+- **Nodes**: Colored circles. Colors are deterministic by node type (hash → palette). Label below, type badge above.
+- **Edges**: Straight lines with arrowheads. Edge type label at midpoint. Self-loops rendered as small circles.
+- **Navigation**: Mouse drag to pan. Scroll wheel to zoom. Trackpad pinch to zoom. Touch drag/pinch on mobile.
+- **Node inspection**: Click any node to open a detail panel showing all properties, connections, and timestamps. Selected nodes glow and highlight their connected edges. Non-connected nodes dim to focus attention.
+
+### Data Handling
+
+Ontology schemas are freeform — LLMs generate arbitrary node types and property shapes. The viewer handles this defensively:
+
+- **Labels**: First string value in `node.properties`, fallback to `node.id`
+- **Colors**: Deterministic hash of `node.type` into a 16-color palette — no hardcoded type lists
+- **Properties**: Iterated dynamically, never assumed to have specific keys
+- **Edge cases**: Self-loops, multiple edges between same pair, nodes with no string properties, empty edge properties
+
+## API Endpoints
+
+The Vite dev server exposes two endpoints (served by the ontology-api plugin):
+
+| Endpoint | Returns |
+|----------|---------|
+| `GET /api/ontologies` | `OntologySummary[]` — name, description, nodeCount, edgeCount |
+| `GET /api/ontologies/:name` | `OntologyData` — full graph with all nodes and edges |
+
+## Project Structure
+
+```
+backpack-viewer/
+├── vite.config.ts       # Vite plugin: StorageBackend → HTTP API + file watcher
+├── index.html           # Single page shell
+└── src/
+    ├── main.ts          # Entry point, wires sidebar + canvas + live reload
+    ├── api.ts           # fetch() wrappers returning backpack-ontology types
+    ├── sidebar.ts       # Ontology list with text filter
+    ├── canvas.ts        # Canvas 2D rendering + pan/zoom/pinch + node selection
+    ├── info-panel.ts    # Node detail panel (properties, connections, timestamps)
+    ├── layout.ts        # Force-directed graph layout algorithm
+    ├── colors.ts        # Deterministic type → color mapping
+    └── style.css        # Dark theme
+```
+
+## Dependencies
+
+- **Runtime**: `backpack-ontology` (local sibling — `StorageBackend` interface + types)
+- **Dev**: `vite`, `typescript`
+
+No frameworks. No UI libraries. Pure TypeScript + Canvas 2D.
+
+## License
+
+Apache-2.0

package/bin/serve.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { createServer } from "vite";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, "..");
+
+const port = parseInt(process.env.PORT || "5173", 10);
+
+const server = await createServer({
+  root,
+  configFile: path.resolve(root, "vite.config.ts"),
+  server: { port, open: true },
+});
+
+await server.listen();
+server.printUrls();

package/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Backpack Ontology Viewer</title>
+  </head>
+  <body>
+    <div id="app">
+      <aside id="sidebar"></aside>
+      <div id="canvas-container">
+        <canvas id="graph-canvas"></canvas>
+      </div>
+    </div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "backpack-viewer",
+  "version": "0.1.3",
+  "description": "Web-based graph visualizer for backpack-ontology — Canvas 2D, force-directed layout, live reload",
+  "license": "Apache-2.0",
+  "author": "Noah Irzinger",
+  "type": "module",
+  "bin": {
+    "backpack-viewer": "./bin/serve.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "index.html",
+    "vite.config.ts",
+    "tsconfig.json",
+    "tsconfig.node.json"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "serve": "node bin/serve.js",
+    "release:patch": "npm version patch && git push && git push --tags",
+    "release:minor": "npm version minor && git push && git push --tags",
+    "release:major": "npm version major && git push && git push --tags"
+  },
+  "dependencies": {
+    "backpack-ontology": "^0.1.3",
+    "vite": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/api.ts

@@ -0,0 +1,13 @@
+import type { OntologyData, OntologySummary } from "backpack-ontology";
+
+export async function listOntologies(): Promise<OntologySummary[]> {
+  const res = await fetch("/api/ontologies");
+  if (!res.ok) return [];
+  return res.json();
+}
+
+export async function loadOntology(name: string): Promise<OntologyData> {
+  const res = await fetch(`/api/ontologies/${encodeURIComponent(name)}`);
+  if (!res.ok) throw new Error(`Failed to load ontology: ${name}`);
+  return res.json();
+}

package/src/canvas.ts

@@ -0,0 +1,409 @@
+import type { OntologyData } from "backpack-ontology";
+import { createLayout, tick, type LayoutState, type LayoutNode } from "./layout";
+import { getColor } from "./colors";
+
+interface Camera {
+  x: number;
+  y: number;
+  scale: number;
+}
+
+const NODE_RADIUS = 20;
+const ALPHA_MIN = 0.001;
+
+export function initCanvas(
+  container: HTMLElement,
+  onNodeClick?: (nodeId: string | null) => void
+) {
+  const canvas = container.querySelector("canvas") as HTMLCanvasElement;
+  const ctx = canvas.getContext("2d")!;
+  const dpr = window.devicePixelRatio || 1;
+
+  let camera: Camera = { x: 0, y: 0, scale: 1 };
+  let state: LayoutState | null = null;
+  let alpha = 1;
+  let animFrame = 0;
+  let selectedNodeId: string | null = null;
+
+  // --- Sizing ---
+
+  function resize() {
+    canvas.width = canvas.clientWidth * dpr;
+    canvas.height = canvas.clientHeight * dpr;
+    render();
+  }
+
+  const observer = new ResizeObserver(resize);
+  observer.observe(container);
+  resize();
+
+  // --- Coordinate transforms ---
+
+  function screenToWorld(sx: number, sy: number): [number, number] {
+    return [
+      sx / camera.scale + camera.x,
+      sy / camera.scale + camera.y,
+    ];
+  }
+
+  // --- Hit testing ---
+
+  function nodeAtScreen(sx: number, sy: number): LayoutNode | null {
+    if (!state) return null;
+    const [wx, wy] = screenToWorld(sx, sy);
+    // Iterate in reverse so topmost (last drawn) nodes are hit first
+    for (let i = state.nodes.length - 1; i >= 0; i--) {
+      const node = state.nodes[i];
+      const dx = wx - node.x;
+      const dy = wy - node.y;
+      if (dx * dx + dy * dy <= NODE_RADIUS * NODE_RADIUS) {
+        return node;
+      }
+    }
+    return null;
+  }
+
+  // --- Rendering ---
+
+  function render() {
+    if (!state) {
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
+      return;
+    }
+
+    ctx.save();
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.clearRect(0, 0, canvas.clientWidth, canvas.clientHeight);
+
+    ctx.save();
+    ctx.translate(-camera.x * camera.scale, -camera.y * camera.scale);
+    ctx.scale(camera.scale, camera.scale);
+
+    // Draw edges
+    for (const edge of state.edges) {
+      const source = state.nodeMap.get(edge.sourceId);
+      const target = state.nodeMap.get(edge.targetId);
+      if (!source || !target) continue;
+
+      const isConnected =
+        selectedNodeId !== null &&
+        (edge.sourceId === selectedNodeId || edge.targetId === selectedNodeId);
+
+      // Self-loop
+      if (edge.sourceId === edge.targetId) {
+        drawSelfLoop(source, edge.type, isConnected);
+        continue;
+      }
+
+      // Line
+      ctx.beginPath();
+      ctx.moveTo(source.x, source.y);
+      ctx.lineTo(target.x, target.y);
+      ctx.strokeStyle = isConnected
+        ? "rgba(212, 162, 127, 0.5)"
+        : "rgba(255, 255, 255, 0.08)";
+      ctx.lineWidth = isConnected ? 2.5 : 1.5;
+      ctx.stroke();
+
+      // Arrowhead
+      drawArrowhead(source.x, source.y, target.x, target.y, isConnected);
+
+      // Edge label at midpoint
+      const mx = (source.x + target.x) / 2;
+      const my = (source.y + target.y) / 2;
+      ctx.fillStyle = isConnected
+        ? "rgba(212, 162, 127, 0.7)"
+        : "rgba(255, 255, 255, 0.2)";
+      ctx.font = "9px system-ui, sans-serif";
+      ctx.textAlign = "center";
+      ctx.textBaseline = "bottom";
+      ctx.fillText(edge.type, mx, my - 4);
+    }
+
+    // Draw nodes
+    for (const node of state.nodes) {
+      const color = getColor(node.type);
+      const isSelected = node.id === selectedNodeId;
+      const isNeighbor =
+        selectedNodeId !== null &&
+        state.edges.some(
+          (e) =>
+            (e.sourceId === selectedNodeId && e.targetId === node.id) ||
+            (e.targetId === selectedNodeId && e.sourceId === node.id)
+        );
+      const dimmed =
+        selectedNodeId !== null && !isSelected && !isNeighbor;
+
+      // Glow for selected node
+      if (isSelected) {
+        ctx.save();
+        ctx.shadowColor = color;
+        ctx.shadowBlur = 20;
+        ctx.beginPath();
+        ctx.arc(node.x, node.y, NODE_RADIUS + 3, 0, Math.PI * 2);
+        ctx.fillStyle = color;
+        ctx.globalAlpha = 0.3;
+        ctx.fill();
+        ctx.restore();
+      }
+
+      // Circle
+      ctx.beginPath();
+      ctx.arc(node.x, node.y, NODE_RADIUS, 0, Math.PI * 2);
+      ctx.fillStyle = color;
+      ctx.globalAlpha = dimmed ? 0.3 : 1;
+      ctx.fill();
+      ctx.strokeStyle = isSelected
+        ? "#d4d4d4"
+        : "rgba(255, 255, 255, 0.15)";
+      ctx.lineWidth = isSelected ? 3 : 1.5;
+      ctx.stroke();
+
+      // Label below
+      const label =
+        node.label.length > 24 ? node.label.slice(0, 22) + "..." : node.label;
+      ctx.fillStyle = dimmed
+        ? "rgba(212, 212, 212, 0.2)"
+        : "#a3a3a3";
+      ctx.font = "11px system-ui, sans-serif";
+      ctx.textAlign = "center";
+      ctx.textBaseline = "top";
+      ctx.fillText(label, node.x, node.y + NODE_RADIUS + 4);
+
+      // Type badge above
+      ctx.fillStyle = dimmed
+        ? "rgba(115, 115, 115, 0.15)"
+        : "rgba(115, 115, 115, 0.5)";
+      ctx.font = "9px system-ui, sans-serif";
+      ctx.textBaseline = "bottom";
+      ctx.fillText(node.type, node.x, node.y - NODE_RADIUS - 3);
+
+      ctx.globalAlpha = 1;
+    }
+
+    ctx.restore();
+    ctx.restore();
+  }
+
+  function drawArrowhead(
+    sx: number,
+    sy: number,
+    tx: number,
+    ty: number,
+    highlighted: boolean
+  ) {
+    const angle = Math.atan2(ty - sy, tx - sx);
+    const tipX = tx - Math.cos(angle) * NODE_RADIUS;
+    const tipY = ty - Math.sin(angle) * NODE_RADIUS;
+    const size = 8;
+
+    ctx.beginPath();
+    ctx.moveTo(tipX, tipY);
+    ctx.lineTo(
+      tipX - size * Math.cos(angle - 0.4),
+      tipY - size * Math.sin(angle - 0.4)
+    );
+    ctx.lineTo(
+      tipX - size * Math.cos(angle + 0.4),
+      tipY - size * Math.sin(angle + 0.4)
+    );
+    ctx.closePath();
+    ctx.fillStyle = highlighted
+      ? "rgba(212, 162, 127, 0.5)"
+      : "rgba(255, 255, 255, 0.12)";
+    ctx.fill();
+  }
+
+  function drawSelfLoop(
+    node: LayoutNode,
+    type: string,
+    highlighted: boolean
+  ) {
+    const cx = node.x + NODE_RADIUS + 15;
+    const cy = node.y - NODE_RADIUS - 15;
+    ctx.beginPath();
+    ctx.arc(cx, cy, 15, 0, Math.PI * 2);
+    ctx.strokeStyle = highlighted
+      ? "rgba(212, 162, 127, 0.5)"
+      : "rgba(255, 255, 255, 0.08)";
+    ctx.lineWidth = highlighted ? 2.5 : 1.5;
+    ctx.stroke();
+
+    ctx.fillStyle = highlighted
+      ? "rgba(212, 162, 127, 0.7)"
+      : "rgba(255, 255, 255, 0.2)";
+    ctx.font = "9px system-ui, sans-serif";
+    ctx.textAlign = "center";
+    ctx.fillText(type, cx, cy - 18);
+  }
+
+  // --- Simulation loop ---
+
+  function simulate() {
+    if (!state || alpha < ALPHA_MIN) return;
+    alpha = tick(state, alpha);
+    render();
+    animFrame = requestAnimationFrame(simulate);
+  }
+
+  // --- Interaction: Pan + Click ---
+
+  let dragging = false;
+  let didDrag = false;
+  let lastX = 0;
+  let lastY = 0;
+
+  canvas.addEventListener("mousedown", (e) => {
+    dragging = true;
+    didDrag = false;
+    lastX = e.clientX;
+    lastY = e.clientY;
+  });
+
+  canvas.addEventListener("mousemove", (e) => {
+    if (!dragging) return;
+    const dx = e.clientX - lastX;
+    const dy = e.clientY - lastY;
+    if (Math.abs(dx) > 2 || Math.abs(dy) > 2) didDrag = true;
+    camera.x -= dx / camera.scale;
+    camera.y -= dy / camera.scale;
+    lastX = e.clientX;
+    lastY = e.clientY;
+    render();
+  });
+
+  canvas.addEventListener("mouseup", (e) => {
+    dragging = false;
+    if (didDrag) return;
+
+    // Click — hit test for node selection
+    const rect = canvas.getBoundingClientRect();
+    const mx = e.clientX - rect.left;
+    const my = e.clientY - rect.top;
+    const hit = nodeAtScreen(mx, my);
+
+    if (hit) {
+      selectedNodeId = hit.id;
+      onNodeClick?.(hit.id);
+    } else {
+      selectedNodeId = null;
+      onNodeClick?.(null);
+    }
+    render();
+  });
+
+  canvas.addEventListener("mouseleave", () => {
+    dragging = false;
+  });
+
+  // --- Interaction: Zoom (wheel + pinch) ---
+
+  canvas.addEventListener(
+    "wheel",
+    (e) => {
+      e.preventDefault();
+
+      const rect = canvas.getBoundingClientRect();
+      const mx = e.clientX - rect.left;
+      const my = e.clientY - rect.top;
+
+      const [wx, wy] = screenToWorld(mx, my);
+
+      const factor = e.ctrlKey
+        ? 1 - e.deltaY * 0.01
+        : e.deltaY > 0
+          ? 0.9
+          : 1.1;
+
+      camera.scale = Math.max(0.05, Math.min(10, camera.scale * factor));
+
+      camera.x = wx - mx / camera.scale;
+      camera.y = wy - my / camera.scale;
+
+      render();
+    },
+    { passive: false }
+  );
+
+  // --- Interaction: Touch (pinch zoom + drag) ---
+
+  let touches: Touch[] = [];
+  let initialPinchDist = 0;
+  let initialPinchScale = 1;
+
+  canvas.addEventListener("touchstart", (e) => {
+    e.preventDefault();
+    touches = Array.from(e.touches);
+    if (touches.length === 2) {
+      initialPinchDist = touchDistance(touches[0], touches[1]);
+      initialPinchScale = camera.scale;
+    } else if (touches.length === 1) {
+      lastX = touches[0].clientX;
+      lastY = touches[0].clientY;
+    }
+  }, { passive: false });
+
+  canvas.addEventListener("touchmove", (e) => {
+    e.preventDefault();
+    const current = Array.from(e.touches);
+
+    if (current.length === 2 && touches.length === 2) {
+      const dist = touchDistance(current[0], current[1]);
+      const ratio = dist / initialPinchDist;
+      camera.scale = Math.max(0.05, Math.min(10, initialPinchScale * ratio));
+      render();
+    } else if (current.length === 1) {
+      const dx = current[0].clientX - lastX;
+      const dy = current[0].clientY - lastY;
+      camera.x -= dx / camera.scale;
+      camera.y -= dy / camera.scale;
+      lastX = current[0].clientX;
+      lastY = current[0].clientY;
+      render();
+    }
+
+    touches = current;
+  }, { passive: false });
+
+  function touchDistance(a: Touch, b: Touch): number {
+    const dx = a.clientX - b.clientX;
+    const dy = a.clientY - b.clientY;
+    return Math.sqrt(dx * dx + dy * dy);
+  }
+
+  // --- Public API ---
+
+  return {
+    loadGraph(data: OntologyData) {
+      cancelAnimationFrame(animFrame);
+      state = createLayout(data);
+      alpha = 1;
+      selectedNodeId = null;
+
+      // Center camera on the graph
+      camera = { x: 0, y: 0, scale: 1 };
+      if (state.nodes.length > 0) {
+        let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+        for (const n of state.nodes) {
+          if (n.x < minX) minX = n.x;
+          if (n.y < minY) minY = n.y;
+          if (n.x > maxX) maxX = n.x;
+          if (n.y > maxY) maxY = n.y;
+        }
+        const cx = (minX + maxX) / 2;
+        const cy = (minY + maxY) / 2;
+        const w = canvas.clientWidth;
+        const h = canvas.clientHeight;
+        camera.x = cx - w / 2;
+        camera.y = cy - h / 2;
+      }
+
+      simulate();
+    },
+
+    destroy() {
+      cancelAnimationFrame(animFrame);
+      observer.disconnect();
+    },
+  };
+}

package/src/colors.ts

@@ -0,0 +1,40 @@
+/**
+ * Deterministic type → color mapping.
+ * Earth-tone accent palette on a neutral gray UI.
+ * These are the only warm colors in the interface —
+ * everything else is grayscale.
+ */
+
+const PALETTE = [
+  "#d4a27f", // warm tan
+  "#c17856", // terracotta
+  "#b07a5e", // sienna
+  "#d4956b", // burnt amber
+  "#a67c5a", // walnut
+  "#cc9e7c", // copper
+  "#c4866a", // clay
+  "#cb8e6c", // apricot
+  "#b8956e", // wheat
+  "#a88a70", // driftwood
+  "#d9b08c", // caramel
+  "#c4a882", // sand
+  "#e8b898", // peach
+  "#b5927a", // dusty rose
+  "#a8886e", // muted brown
+  "#d1a990", // blush tan
+];
+
+const cache = new Map<string, string>();
+
+export function getColor(type: string): string {
+  const cached = cache.get(type);
+  if (cached) return cached;
+
+  let hash = 0;
+  for (let i = 0; i < type.length; i++) {
+    hash = ((hash << 5) - hash + type.charCodeAt(i)) | 0;
+  }
+  const color = PALETTE[Math.abs(hash) % PALETTE.length];
+  cache.set(type, color);
+  return color;
+}