msagljs copilot-instructions.md

Copilot Instructions for msagl-js

Project Overview

msagl-js is a JavaScript/TypeScript implementation of Microsoft's Automatic Graph Layout (MSAGL) algorithms. It computes node positions and edge routes for graph visualization.

Build, Test, and Lint

yarn build          # Build all modules (lerna + tsc + esbuild bundles)
yarn test           # Run all tests (Jest with ts-jest)
yarn typecheck      # Type-check without emitting (tsc --noEmit)
yarn eslint         # Lint modules/core/src
yarn prettier       # Format modules/core/src

Run a single test file:

npx jest --testPathPattern="graph.spec"

Run examples locally:

cd examples/svg-renderer && npm run start
cd examples/webgl-renderer && npm run start

Architecture

This is a Yarn workspaces + Lerna monorepo with six @msagl/* packages under modules/:

@msagl/core            → Graph data model, layout algorithms, math, routing
@msagl/drawing         → Visual attributes (colors, shapes, styles) for nodes/edges
@msagl/parser          → DOT and JSON graph format parsers
@msagl/renderer-common → Shared renderer utilities (text measurement, etc.)
@msagl/renderer-svg    → SVG renderer (uses panzoom)
@msagl/renderer-webgl  → WebGL renderer (uses deck.gl)

Dependency flow (each arrow means "depends on"):

core ← drawing ← parser ← renderer-common ← renderer-svg
                                            ← renderer-webgl

core has zero internal dependencies. All other modules depend on core.

Core Data Model (@msagl/core)

• Graph extends Node — a graph is also a node, enabling nested/clustered subgraphs
• Node extends Entity — has an id string and inEdges/outEdges/selfEdges sets
• Edge extends Entity — connects source and target nodes; self-registers in node edge sets on construction
• GeomGraph/GeomNode/GeomEdge — geometry layer counterparts that store computed positions, curves, and bounding boxes
• Layout and geometry are separate from the structural graph — Graph/Node/Edge hold structure, Geom* objects hold layout results