Architecture

Rendering contract

graphraum consumes positioned nodes and edges. It does not fetch data or infer graph semantics. Its optional force helpers produce positions independently from the renderer.

flowchart LR
  App[Application graph state] -->|nodes, edges, positions| Graphraum[graphraum]
  Layout[Layout worker or server] -->|positions| App
  Graphraum --> Viewport[Spatial viewport query]
  Viewport --> Scene[Three.js scene]
  Scene --> Nodes[One InstancedMesh]
  Scene --> Edges[One LineSegments geometry]
  Graphraum -->|picked node ID| App

This keeps layout work independently replaceable and prevents a complete force simulation from blocking the first useful render.

Layout producers can send GraphraumLayoutPositions batches: node IDs plus transferable XYZ Float32Array data. The host calls applyLayout() for each batch, so useful positions can appear before full convergence. The package also exports dimension-aware static, clustered, and incremental force helpers; applications still decide where and when they run.

On-demand rendering

graphraum renders when data, selection, camera controls, mode, or container size changes. It does not keep an idle animation loop alive. Calls within one browser frame are coalesced through requestAnimationFrame.

Viewport materialization

In 2D, graphraum queries visible nodes from its spatial grid with an overscan margin, derives unique incident edges without scanning the full edge list, and compacts that subset into the existing node and edge GPU buffers. The renderer remains at two draw calls.

When visible nodes exceed maxVisibleNodes, graphraum bins them into representative spatial density clusters. Density mode enters above 110% of the budget and exits below 85% so small camera changes do not flicker between tiers. Nodes overlay edges in 2D; 3D preserves normal depth ordering.

When incident edges exceed maxVisibleEdges, graphraum applies a deterministic overview budget and reports that decision through diagnostics. Application-specific clustering and semantic aggregation remain host concerns.

2D first

The default orthographic camera makes the graph behave as a native 2D surface. The perspective camera is available on demand for structures where depth carries meaning. Both modes use the same node and edge contract.

Application-owned concerns

The host remains responsible for:

• layout and progressive position updates;
• labels, clustering, and domain-specific semantic level of detail;
• keyboard navigation and an accessible node list;
• domain actions such as expand, focus, archive, or inspect;
• persistence and synchronization.

graphraum provides the rendering primitive, not a replacement application architecture.

Graphology direction

Graphology is the canonical mutable graph input (PRO-248). Its core graph object supplies node/edge identity, typed attributes, events, traversal, and serialization. bindGraphology() subscribes to that contract and renders visual attributes; graphraum does not require Graphology’s optional layout or algorithm packages.

The existing array snapshot remains useful for static data, transport boundaries, fixtures, and one-shot rendering.