@knotpad/app 0.1.0

package/components/graph/graph-overlays.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+import { ExternalLink, RotateCcw, ZoomIn, ChevronDown, ChevronRight } from "lucide-react";
+import { useRouter } from "next/navigation";
+import type { GraphNode } from "./graph-types";
+import { NODE_COLORS, LEGEND_LABELS } from "./graph-types";
+
+export function GraphLegend() {
+  return (
+    <>
+      {/* Mobile legend - compact horizontal at bottom */}
+      <div className="absolute bottom-3 left-3 right-3 z-10 flex md:hidden flex-wrap gap-x-3 gap-y-1.5 rounded-lg border border-zinc-800 bg-zinc-950/80 px-3 py-2 backdrop-blur text-[10px]">
+        {Object.entries(LEGEND_LABELS).map(([type, label]) => (
+          <div key={type} className="flex items-center gap-1.5">
+            <span
+              className="h-2 w-2 shrink-0 rounded-full"
+              style={{ backgroundColor: NODE_COLORS[type] }}
+            />
+            <span className="text-zinc-500">{label}</span>
+          </div>
+        ))}
+        <div className="flex items-center gap-1.5">
+          <span className="w-4 border-t border-zinc-500" />
+          <span className="text-zinc-600">Contains</span>
+        </div>
+        <div className="flex items-center gap-1.5">
+          <span className="w-4 border-t border-dashed border-zinc-600" />
+          <span className="text-zinc-600">Refs</span>
+        </div>
+      </div>
+
+      {/* Desktop legend - vertical at top right */}
+      <div className="absolute top-3 right-3 z-10 hidden md:flex flex-col gap-1.5 rounded-lg border border-zinc-800 bg-zinc-950/80 px-3 py-2.5 backdrop-blur text-xs">
+        {Object.entries(LEGEND_LABELS).map(([type, label]) => (
+          <div key={type} className="flex items-center gap-2">
+            <span
+              className="h-2.5 w-2.5 shrink-0 rounded-full"
+              style={{ backgroundColor: NODE_COLORS[type] }}
+            />
+            <span className="text-zinc-500">{label}</span>
+          </div>
+        ))}
+        <div className="mt-1 pt-1 border-t border-zinc-800 space-y-1">
+          <div className="flex items-center gap-2">
+            <span className="w-5 border-t border-zinc-500" />
+            <span className="text-zinc-600">Contains / assigned</span>
+          </div>
+          <div className="flex items-center gap-2">
+            <span className="w-5 border-t border-dashed border-zinc-600" />
+            <span className="text-zinc-600">References</span>
+          </div>
+        </div>
+        <p className="text-zinc-700 pt-1 border-t border-zinc-800">Scroll to zoom · Drag to pan</p>
+      </div>
+    </>
+  );
+}
+
+export function GraphTooltip({ tooltip }: { tooltip: { x: number; y: number; label: string; type: string } | null }) {
+  if (!tooltip) return null;
+  return (
+    <div
+      className="absolute z-20 pointer-events-none rounded border border-zinc-700 bg-zinc-900 px-2 py-1 text-xs text-zinc-300 shadow-lg"
+      style={{ left: tooltip.x + 12, top: tooltip.y + 12 }}
+    >
+      <span className="font-medium">{tooltip.label}</span>
+      <span className="ml-1.5 text-zinc-500">{tooltip.type}</span>
+    </div>
+  );
+}
+
+export function GraphContextMenu({
+  contextMenu,
+  contextNode,
+  collapsedNodeIds,
+  canCollapse,
+  onClose,
+  onToggleCollapse,
+  onZoomTo,
+  onFitView,
+}: {
+  contextMenu: { x: number; y: number; nodeId: string } | null;
+  contextNode: GraphNode | null;
+  collapsedNodeIds: Set<string>;
+  canCollapse: (nodeId: string) => boolean;
+  onClose: () => void;
+  onToggleCollapse: (nodeId: string) => void;
+  onZoomTo: (nodeId: string) => void;
+  onFitView: () => void;
+}) {
+  const router = useRouter();
+  if (!contextMenu || !contextNode) return null;
+  return (
+    <>
+      <div
+        className="fixed inset-0 z-20"
+        onClick={onClose}
+        onContextMenu={(e) => { e.preventDefault(); onClose(); }}
+      />
+      <div
+        className="absolute z-30 w-40 rounded-md border border-zinc-700 bg-zinc-900 py-1 shadow-xl"
+        style={{ left: contextMenu.x, top: contextMenu.y }}
+      >
+        {contextNode.href && (
+          <button
+            onClick={() => {
+              if (contextNode.href) router.push(contextNode.href);
+              onClose();
+            }}
+            className="flex w-full items-center gap-2 px-3 py-1.5 text-xs text-zinc-300 hover:bg-zinc-800"
+          >
+            <ExternalLink size={11} className="text-zinc-500" />
+            Open
+          </button>
+        )}
+        {canCollapse(contextNode.id) && (
+          <button
+            onClick={() => {
+              onToggleCollapse(contextNode.id);
+              onClose();
+            }}
+            className="flex w-full items-center gap-2 px-3 py-1.5 text-xs text-zinc-300 hover:bg-zinc-800"
+          >
+            {collapsedNodeIds.has(contextNode.id) ? (
+              <>
+                <ChevronRight size={11} className="text-zinc-500" />
+                Expand
+              </>
+            ) : (
+              <>
+                <ChevronDown size={11} className="text-zinc-500" />
+                Collapse
+              </>
+            )}
+          </button>
+        )}
+        <button
+          onClick={() => {
+            onZoomTo(contextNode.id);
+            onClose();
+          }}
+          className="flex w-full items-center gap-2 px-3 py-1.5 text-xs text-zinc-300 hover:bg-zinc-800"
+        >
+          <ZoomIn size={11} className="text-zinc-500" />
+          Zoom to
+        </button>
+        <button
+          onClick={() => {
+            onFitView();
+            onClose();
+          }}
+          className="flex w-full items-center gap-2 px-3 py-1.5 text-xs text-zinc-300 hover:bg-zinc-800"
+        >
+          <RotateCcw size={11} className="text-zinc-500" />
+          Reset view
+        </button>
+      </div>
+    </>
+  );
+}

package/components/graph/graph-page.test.tsx

@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { GraphPage } from "@/components/graph/graph-page";
+
+const push = vi.fn();
+
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({ push }),
+  usePathname: () => "/graph",
+  useSearchParams: () => new URLSearchParams(),
+}));
+
+vi.mock("@/components/graph/graph-view", () => ({
+  GraphView: ({
+    nodes,
+    onSelectionChange,
+  }: {
+    nodes?: Array<{ id: string; label: string; type: string }>;
+    onSelectionChange?: (node: { id: string; label: string; type: string } | null) => void;
+  }) => (
+    <div>
+      <div>Graph canvas</div>
+      <div>
+        {nodes?.map((node) => (
+          <span key={node.id}>{node.label}</span>
+        ))}
+      </div>
+      <button
+        type="button"
+        onClick={() => onSelectionChange?.({ id: "note-n1", label: "Launch", type: "note" })}
+      >
+        Select graph node
+      </button>
+    </div>
+  ),
+}));
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  push.mockReset();
+});
+
+describe("GraphPage", () => {
+  it("filters out task nodes when the Tasks category is disabled", async () => {
+    const user = userEvent.setup();
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          nodes: [
+            { id: "note-n1", type: "note", label: "Launch note" },
+            { id: "task-t1", type: "task", label: "Task node" },
+          ],
+          edges: [{ source: "note-n1", target: "task-t1", type: "references" }],
+        }),
+      })
+    );
+
+    render(<GraphPage selectedNoteIds={[]} />);
+
+    expect(await screen.findByText("Task node")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Tasks" }));
+
+    expect(screen.queryByText("Task node")).not.toBeInTheDocument();
+    expect(screen.getByText("Launch note")).toBeInTheDocument();
+  });
+
+  it("shows inspector details for the selected node", async () => {
+    const user = userEvent.setup();
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          nodes: [{ id: "note-n1", type: "note", label: "Launch", href: "/notes/n1" }],
+          edges: [],
+        }),
+      })
+    );
+
+    render(<GraphPage selectedNoteIds={["n1"]} />);
+
+    await user.click(await screen.findByRole("button", { name: "Select graph node" }));
+
+    const inspector = screen.getByText("Selected node").closest("aside");
+    expect(inspector).not.toBeNull();
+    expect(within(inspector!).getByText("Launch")).toBeInTheDocument();
+    expect(within(inspector!).getByText("note")).toBeInTheDocument();
+  });
+
+  it("shows a help panel and selected note summary after loading", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          nodes: [{ id: "note-n1", type: "note", label: "Launch" }],
+          edges: [],
+        }),
+      })
+    );
+
+    render(<GraphPage selectedNoteIds={["n1"]} />);
+
+    expect(await screen.findByText(/how to read this graph/i)).toBeInTheDocument();
+    expect(screen.getByText("Selected")).toBeInTheDocument();
+    expect(screen.getAllByText("Launch").length).toBeGreaterThanOrEqual(2);
+    expect(screen.getByText("Graph canvas")).toBeInTheDocument();
+  });
+
+  it("shows an error message when the graph request fails", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        json: async () => ({ message: "request failed" }),
+      })
+    );
+
+    render(<GraphPage selectedNoteIds={[]} />);
+
+    expect(await screen.findByText("Graph failed to load. Try refreshing.")).toBeInTheDocument();
+  });
+});

package/components/graph/graph-page.tsx

@@ -0,0 +1,263 @@
+"use client";
+
+import { useEffect, useState, useCallback, useRef, useMemo } from "react";
+import { useRouter, usePathname, useSearchParams } from "next/navigation";
+import { RotateCw, X, Maximize, Search } from "lucide-react";
+import { GraphView, type GraphViewHandle } from "./graph-view";
+import type { GraphData } from "@/app/api/graph/route";
+import { LEGEND_LABELS, type GraphSelection } from "./graph-types";
+import { loadPreference, savePreference } from "@/lib/view-preferences";
+
+type VisibleNodeType = keyof typeof LEGEND_LABELS;
+
+const GRAPH_NODE_TYPES = Object.keys(LEGEND_LABELS) as VisibleNodeType[];
+
+export function GraphPage({ selectedNoteIds }: { selectedNoteIds: string[] }) {
+  const [data, setData] = useState<GraphData | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState("");
+  const [searchQuery, setSearchQuery] = useState("");
+  const [selectedNode, setSelectedNode] = useState<GraphSelection | null>(null);
+  const [visibleTypes, setVisibleTypes] = useState<VisibleNodeType[]>(() =>
+    loadPreference("brief:graph-visible-types", GRAPH_NODE_TYPES)
+  );
+  const graphViewRef = useRef<GraphViewHandle>(null);
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const allNodes = useMemo(() => data?.nodes ?? [], [data]);
+  const filteredNodes = useMemo(
+    () => allNodes.filter((node) => visibleTypes.includes(node.type as VisibleNodeType)),
+    [allNodes, visibleTypes]
+  );
+  const filteredEdges = useMemo(() => {
+    const visibleNodeIds = new Set(filteredNodes.map((node) => node.id));
+    return (data?.edges ?? []).filter(
+      (edge) => visibleNodeIds.has(edge.source) && visibleNodeIds.has(edge.target)
+    );
+  }, [data, filteredNodes]);
+
+  useEffect(() => {
+    savePreference("brief:graph-visible-types", visibleTypes);
+  }, [visibleTypes]);
+
+  const load = useCallback(() => {
+    setLoading(true);
+    setError("");
+    fetch("/api/graph")
+      .then((r) => {
+        if (!r.ok) {
+          throw new Error("request failed");
+        }
+
+        return r.json();
+      })
+      .then((d: GraphData) => {
+        setData(d);
+        setError("");
+      })
+      .catch(() => {
+        setData(null);
+        setError("Graph failed to load. Try refreshing.");
+      })
+      .finally(() => {
+        setLoading(false);
+      });
+  }, []);
+
+  useEffect(() => { load(); }, [load]);
+
+  // Escape key clears selection
+  useEffect(() => {
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key === "Escape") {
+        graphViewRef.current?.clearSelection();
+      }
+    }
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, []);
+
+  const handleNoteSelect = useCallback((noteId: string | null) => {
+    const params = new URLSearchParams(searchParams.toString());
+    if (noteId) {
+      params.set("notes", noteId);
+    } else {
+      params.delete("notes");
+    }
+    router.push(`${pathname}?${params.toString()}`);
+  }, [pathname, router, searchParams]);
+
+  const selectedSummary = useMemo(() => {
+    const labels = selectedNoteIds
+      .map((noteId) => filteredNodes.find((node) => node.id === `note-${noteId}`)?.label)
+      .filter((label): label is string => Boolean(label));
+
+    if (labels.length === 0) {
+      return null;
+    }
+
+    if (labels.length === 1) {
+      return labels[0];
+    }
+
+    return `${labels.length} notes selected`;
+  }, [filteredNodes, selectedNoteIds]);
+  const inspectorNode = useMemo(() => {
+    if (selectedNode) {
+      return filteredNodes.find((node) => node.id === selectedNode.id) ?? null;
+    }
+
+    if (selectedNoteIds.length !== 1) {
+      return null;
+    }
+
+    return filteredNodes.find((node) => node.id === `note-${selectedNoteIds[0]}`) ?? null;
+  }, [filteredNodes, selectedNode, selectedNoteIds]);
+
+  if (loading) {
+    return (
+      <div className="flex flex-1 items-center justify-center">
+        <div className="h-6 w-6 rounded-full border-2 border-zinc-700 border-t-zinc-400 animate-spin" />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex flex-1 items-center justify-center px-4 text-center text-sm text-red-300">
+        {error}
+      </div>
+    );
+  }
+
+  if (allNodes.length === 0) {
+    return (
+      <div className="flex flex-1 flex-col items-center justify-center gap-3 text-center">
+        <p className="text-sm font-medium text-zinc-500">Nothing to graph yet</p>
+        <p className="text-xs text-zinc-700 max-w-xs">
+          Create notes with tasks and @mentions to see your workspace as a relationship graph.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="relative flex flex-1 flex-col overflow-hidden">
+      {/* Controls top-left */}
+      <div className="absolute top-3 left-3 z-10 flex items-center gap-2">
+        <button
+          onClick={load}
+          title="Refresh graph"
+          aria-label="Refresh graph"
+          className="flex h-7 w-7 items-center justify-center rounded border border-zinc-800 bg-zinc-950/80 text-zinc-500 backdrop-blur hover:border-zinc-700 hover:text-zinc-300 transition-colors ring-focus"
+        >
+          <RotateCw size={13} />
+        </button>
+        <button
+          onClick={() => graphViewRef.current?.clearSelection()}
+          title="Clear selection"
+          aria-label="Clear selection"
+          className="flex h-7 w-7 items-center justify-center rounded border border-zinc-800 bg-zinc-950/80 text-zinc-500 backdrop-blur hover:border-zinc-700 hover:text-zinc-300 transition-colors ring-focus"
+        >
+          <X size={13} />
+        </button>
+        <button
+          onClick={() => graphViewRef.current?.fitView()}
+          title="Fit to view"
+          aria-label="Fit to view"
+          className="flex h-7 w-7 items-center justify-center rounded border border-zinc-800 bg-zinc-950/80 text-zinc-500 backdrop-blur hover:border-zinc-700 hover:text-zinc-300 transition-colors ring-focus"
+        >
+          <Maximize size={13} />
+        </button>
+      </div>
+
+      <div className="absolute left-3 top-12 z-10 flex max-w-[min(24rem,calc(100vw-1.5rem))] flex-wrap gap-1.5 rounded-lg border border-zinc-800 bg-zinc-950/90 p-1.5 text-xs backdrop-blur">
+        {GRAPH_NODE_TYPES.map((type) => {
+          const active = visibleTypes.includes(type);
+          return (
+            <button
+              key={type}
+              type="button"
+              aria-pressed={active}
+              onClick={() => {
+                setSelectedNode((current) => (current?.type === type ? null : current));
+                setVisibleTypes((current) =>
+                  current.includes(type)
+                    ? current.filter((value) => value !== type)
+                    : [...current, type]
+                );
+              }}
+              className={`rounded-md border px-2 py-1 transition-colors ring-focus ${
+                active
+                  ? "border-zinc-700 bg-zinc-800 text-zinc-100"
+                  : "border-zinc-800 bg-zinc-950 text-zinc-500 hover:border-zinc-700 hover:text-zinc-300"
+              }`}
+            >
+              {LEGEND_LABELS[type]}
+            </button>
+          );
+        })}
+      </div>
+
+      {/* Search bar */}
+      <div className="absolute top-3 left-1/2 z-10 flex w-[min(16rem,calc(100vw-1.5rem))] -translate-x-1/2 items-center gap-1.5 rounded border border-zinc-800 bg-zinc-950/80 px-2 py-1 backdrop-blur">
+        <Search size={12} className="shrink-0 text-zinc-600" />
+        <input
+          type="text"
+          value={searchQuery}
+          onChange={(e) => setSearchQuery(e.target.value)}
+          placeholder="Search nodes..."
+          aria-label="Search graph nodes"
+          className="w-full bg-transparent text-xs text-zinc-300 placeholder:text-zinc-600 outline-none"
+        />
+        {searchQuery && (
+          <button
+            onClick={() => setSearchQuery("")}
+            className="shrink-0 text-zinc-600 hover:text-zinc-400"
+          >
+            <X size={12} />
+          </button>
+        )}
+      </div>
+
+      {inspectorNode && (
+        <aside className="absolute bottom-3 right-3 z-10 w-72 rounded-lg border border-zinc-800 bg-zinc-950/90 p-3 text-sm text-zinc-300 backdrop-blur">
+          <p className="text-xs text-zinc-500">Selected node</p>
+          <p className="mt-1 text-sm font-medium text-zinc-100">{inspectorNode.label}</p>
+          <p className="text-xs uppercase tracking-wide text-zinc-500">{inspectorNode.type}</p>
+          <div className="mt-3 flex items-center gap-2">
+            {inspectorNode.href && (
+              <a
+                href={inspectorNode.href}
+                className="rounded-md border border-zinc-700 px-2 py-1 text-xs text-zinc-200 transition-colors hover:border-zinc-600 hover:bg-zinc-900"
+              >
+                Open node
+              </a>
+            )}
+            <button
+              type="button"
+              onClick={() => {
+                setSelectedNode(null);
+                graphViewRef.current?.clearSelection();
+              }}
+              className="rounded-md border border-zinc-800 px-2 py-1 text-xs text-zinc-400 transition-colors hover:border-zinc-700 hover:text-zinc-200"
+            >
+              Clear
+            </button>
+          </div>
+        </aside>
+      )}
+
+      <GraphView
+        ref={graphViewRef}
+        nodes={filteredNodes}
+        edges={filteredEdges}
+        selectedNoteIds={selectedNoteIds}
+        searchQuery={searchQuery}
+        onNoteSelect={handleNoteSelect}
+        onSelectionChange={setSelectedNode}
+      />
+    </div>
+  );
+}

package/components/graph/graph-types.ts

@@ -0,0 +1,47 @@
+import type { GraphNode, GraphEdge } from "@/app/api/graph/route";
+import type * as d3 from "d3";
+
+export type { GraphNode, GraphEdge };
+
+export const NODE_COLORS: Record<string, string> = {
+  folder: "#f59e0b",
+  note:   "#7c3aed",
+  task:   "#0d9488",
+  person: "#f43f5e",
+  agent:  "#3b82f6",
+};
+
+export const NODE_RADIUS: Record<string, number> = {
+  folder: 18,
+  note:   14,
+  task:   9,
+  person: 12,
+  agent:  10,
+};
+
+export const LEGEND_LABELS: Record<string, string> = {
+  folder: "Folders",
+  note:   "Notes",
+  task:   "Tasks",
+  person: "People",
+  agent:  "Agents",
+};
+
+export type SimNode = GraphNode & d3.SimulationNodeDatum;
+export type SimLink = d3.SimulationLinkDatum<SimNode> & { type: GraphEdge["type"] };
+export type GraphSelection = Pick<GraphNode, "id" | "label" | "type" | "href" | "status">;
+
+export interface GraphViewHandle {
+  fitView: () => void;
+  clearSelection: () => void;
+  zoomToNode: (nodeId: string) => void;
+}
+
+export type Props = {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  selectedNoteIds: string[];
+  searchQuery: string;
+  onNoteSelect: (noteId: string | null) => void;
+  onSelectionChange?: (node: GraphSelection | null) => void;
+};