graphraum
_{Nodes. Edges. Space.}

graphraum

An opinionated WebGL engine for interactive node-edge graphs in 2D and 3D.

graphraum is deliberately narrow: it renders graphs, accepts positions from any layout engine, and keeps the hot path outside a component framework. Nodes use one instanced mesh, edges use one batched geometry, and rendering happens on demand.

Pre-1.0 development. The API will continue to evolve while the rendering and visual contracts are proven.

Principles

• Graph-native data: nodes, edges, stable identities, positions, and selection.
• Native 2D first, with 3D available over the same graph state.
• One node draw call and one edge draw call for the baseline scene.
• Layout is an input, not hidden renderer work.
• Framework adapters belong outside the rendering core.

Development

Requires Bun.

bun install
bun run dev

The local graph laboratory exposes every renderer option, theme and visual mapping control, presentation metadata, diagnostics, and fixture tiers from 100 to 100,000 nodes.

bun run test
bun run check
bun run build

Repository decisions and agent instructions live in AGENTS.md. Changes use Conventional Commits and require a matching PR title because squash merges become release commits.

Install

graphraum is currently published to the GitHub Packages npm registry. Configure the @domudev scope and authenticate with a classic GitHub token that has read:packages permission:

# .npmrc
@domudev:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

Then install it with Bun:

bun add @domudev/graphraum

Publishing is automated with semantic-release after CI succeeds on main. Commit types determine the next version, semantic-release creates the v<version> tag and GitHub Release, and the package is published to GitHub Packages. Do not manually edit the package version or create routine release tags.

Documentation

The documentation, API reference, visual language, and executable browser benchmark are published on GitHub Pages. Run them locally with:

bun install --cwd docs
bun run docs:dev

Status

The initial engine includes batched edges, instanced nodes, explicit render scheduling, 2D and 3D cameras, selection colors, picking, fitting, resize handling, and resource disposal. Smooth 2D–3D camera transitions, semantic label LOD, incremental buffer updates, and accessibility adapters remain ahead.

License

Apache-2.0