Cytoscape.js AGENTS.md

Guidelines for agents contributing to the Cytoscape.js graph theory and visualisation library.

Environment & tooling

Use Node via .nvmrc when possible: nvm use or mise en.
Use npm; the repo is configured around package-lock.json and the existing npm scripts.
Library source of truth is in src/. Documentation source lives in documentation/md/, documentation/demos/, and documentation/docmaker.json. Built artifacts in build/, dist/, and generated files under documentation/ should only be updated via the project scripts.
Bundles are produced with Rollup from src/index.mjs into UMD, minified UMD, CJS, ESM, and minified ESM outputs.
The repo uses ESM source files (.mjs), ESLint, Mocha, and Playwright.
Before starting significant work, read any repo docs directly related to the area you are changing. For architecture context, start with documentation/md/architecture.md.
If you want to read the documentation, you can grep documentation/docmaker.json, which contains all the documentation data (and API in JSON format). You can search for things like "cy.on" for the cy.on() method. docmaker.json references markdown files in documentation/md/ for prose that elaborates on particular API methods and also for general prose sections, like the intro or getting started sections. You can also grep documentation/md/**/*.md generally for doc searches. The paths broadly match the src/**/*.mjs paths.

Make sure dependencies are installed when you first start: npm install.
Install Playwright browsers before running browser coverage or the full test suite on a fresh environment: npx playwright install --with-deps.
Make your changes.
Lint source files: npm run lint.
Run the narrowest useful test loop while iterating, but run the relevant verification before handing work back:
- Source or algorithm changes: npm run test:js and npm run test:modules.
- Renderer or interaction changes: npm run test:js, npm run test:modules, and sanity check in debug/ via npm run watch; run Playwright when browser behaviour is affected.
- Bundle, packaging, or docs pipeline changes: npm run build, npm run docs, and any targeted release script checks that apply.
- If the change is broad or you are unsure, run npm test.
Build all bundles but only if you're modifying the build system: npm run build.

src/: Main library source.
- src/core/: Core instance lifecycle, viewport, rendering, style, layout, animation, and notifications.
- src/collection/: Collection APIs, traversals, dimensions, styling, and graph algorithms.
- src/style/: Style parsing, application, bypasses, and stylesheet helpers.
- src/selector/: Selector parsing and matching.
- src/extensions/: Built-in layouts and renderers.
  - src/extensions/renderer/base/: Shared renderer state and geometry logic.
  - src/extensions/renderer/canvas/: Canvas renderer, drawing pipeline, caches, and WebGL helpers.
  - src/extensions/layout/: Built-in layouts like grid, cose, concentric, and breadthfirst.
- src/util/: Shared low-level helpers.
test/: Mocha tests. Add regression coverage here for API and logic changes.
debug/: Manual visual and interaction test pages. Use this for renderer, interaction, and gesture changes that are hard to verify in unit tests alone.
playwright-tests/ and playwright.config.js: Browser-level regression coverage.
documentation/: Generated site plus source markdown, demos, and the doc generator.
- documentation/md/: Documentation source.
- documentation/demos/: Demo apps and assets used by the docs site.
- documentation/docmaker.mjs: Docs build entrypoint.
.github/workflows/: CI and release workflows.
benchmark/: Performance comparisons and targeted benchmark runners.
typescript/: TypeScript-related tests and fixtures.

Preserve the existing style: two-space indentation, single quotes, ESM imports/exports, and concise readable functions.
Do not hand-edit generated outputs when a source file exists instead. In particular, prefer editing src/ and documentation/md/ over generated files in build/, dist/, and compiled docs assets.
Keep module boundaries aligned with the existing architecture. New source files should live near the corresponding subsystem in src/.
When fixing a bug, add or update a regression test whenever practical. Put public-behaviour tests in test/; keep internal-only coverage in test/modules/ when applicable.
For renderer, gesture, or grab-state changes, verify behaviour in debug/ because visual regressions are not always caught by Mocha alone. You need to control a browser instance to use this and you need to run npm run watch to run a dev server with auto-rebuild.
Keep docs in sync with API or behaviour changes. Update documentation/md/, demos, and docmaker.json inputs rather than patching generated HTML by hand.
Avoid introducing new build tools, frameworks, or repo-wide conventions unless the task explicitly requires it.
When adding new top-level workflows, major directories, or important source areas not already documented here, update AGENTS.md.

npm test matches CI closely: GitHub Actions installs dependencies, installs Playwright browsers, and runs npm test.
npm run test:build exercises the built bundle rather than source files; use it when a bug could be introduced by bundling or build-time transforms.
Playwright setup depends on a built UMD bundle and a local HTTP server. Use the existing scripts rather than inventing a parallel harness.

Documentation HTML is generated. Do not edit generated docs directly when the corresponding markdown or template source (i.e. docmaker.json and template.html) should be changed instead.

Keep changes narrowly scoped. Cytoscape.js has a large public API and small internal regressions can surface broadly.
Prefer extending existing tests, demos, and docs over adding parallel mechanisms.
If a change affects public API semantics, selectors, style behaviour, layouts, rendering, or documentation structure, call that out explicitly in your summary to the user.