AlexandrAI AGENTS.md
agents-md

FileGraph Graph Canvas Agent Guide

Agent guide for the FileGraph Cytoscape graph canvas component and graph mode UI contract.

AGENTS.md

Guidance for coding agents working on FileGraph Graph Canvas in the FileGraph project.

Project overview

This guide covers src/components/graph-canvas.tsx and the graph tab in src/components/filegraph-app.tsx. The canvas converts GraphSnapshot nodes and edges into Cytoscape elements, highlights search matches, styles hierarchy and related edges differently, reports selected nodes back to the app, and falls back to a simple rendered count during jsdom tests.

Primary source files

  • src/components/graph-canvas.tsx owns Cytoscape element creation, layout, styling, selection sync, and jsdom fallback.
  • src/components/filegraph-app.tsx owns graph tab state, graph search, selectedGraphNodeId, community list, and Open in editor behavior.
  • src/lib/filegraph/types.ts defines GraphSnapshot, GraphNode, GraphEdge, and CommunitySnapshot.
  • src/components/filegraph-app.test.tsx verifies compact workspace rendering and switching to graph mode.

Setup commands

pnpm install pnpm test pnpm lint pnpm build pnpm dev

Change rules

  • Keep GraphCanvas as a client component; Cytoscape requires browser runtime state.
  • Recreate Cytoscape when elements change and destroy the instance on cleanup.
  • Keep jsdom fallback lightweight so component tests do not need canvas or layout APIs.
  • Use graph search only for highlight data; filtering out nodes would make relation context disappear.
  • Keep hierarchy edges directional and related edges visually distinct.
  • Selection belongs to the parent app state; GraphCanvas should report node taps and mirror selectedNodeId with a selected class.
  • Avoid adding network fetches inside GraphCanvas. The app should own refreshGraphSnapshot and route calls.
  • When changing GraphSnapshot shape, update canvas mapping, app sidebars, and tests together.

Testing

Test jsdom fallback rendering, graph tab navigation, search field behavior, selected node sidebar, Open in editor navigation, empty graph state, and graph refresh behavior. Browser-level tests are useful for Cytoscape interaction, but unit tests should remain stable without real layout.

PR checklist

  • Graph mode still renders with zero nodes.
  • Selected node opens the same note in editor mode.
  • Related edges remain visually distinct from hierarchy edges.
  • Component tests avoid relying on Cytoscape internals.