Troubleshooting

These checks cover the current source-checkout preview. Graphora packages are not published to npm, and the repository is private.

The package cannot be resolved

Run examples from the graph-library/ workspace with its checked-in Vite configuration:

pnpm install --frozen-lockfile
pnpm build
pnpm exec vite examples/vanilla/basic \
  --config examples/vanilla/vite.config.ts

Use examples/react/vite.config.ts for a React example. A public pnpm add @graphora/engine command cannot work yet because the packages have not been published.

The Canvas is blank or has the wrong size

Give the graph container an explicit height before mounting. The engine reads clientWidth and clientHeight, then uses ResizeObserver for later changes when the browser provides it.

#graph {
  width: 100%;
  height: 480px;
}

Also check that the graph has nodes, the container exists, and a renderer was given to createGraphEngine(). Nodes without positions start at the origin until a layout result is applied. Run the configured layout and fit it:

await engine.runLayout({ fitToView: { padding: 48 } })

A layout run is rejected

The engine rejects a result if another layout superseded it or graph data changed while an async run was in progress. Catch the rejection and run the layout again against the current graph if that matches the application action. Do not apply a stale result manually.

Force layout runs on the main thread by default. The browser Worker adapter can move that computation off-thread, but its owner must call dispose() when the layout is no longer used.

React reloads or relayouts unexpectedly

Do not create graph, layout, theme, interactionStyles, or rendererFactory objects inline when they are logically unchanged. Define static values outside the component or memoize state-derived values. A changed graph reference is a data update; a changed layout, theme, interaction-style, or renderer-factory reference rebuilds the runtime.

For filters and incremental data changes, consider graphUpdatePolicy="preserve". The default is relayout.

Pointer input does nothing

In vanilla code, call attachGraphInput(container, engine, renderer) after the engine and renderer use that same container. Keep the returned disposer and call it before engine.destroy(). Check that another overlay is not intercepting pointer events and that the container has a nonzero size.

The React Graph component enables its standard pointer behaviors by default. Check the interactive prop if some behaviors were disabled.

Labels disappear while zooming

CanvasGraphRenderer draws every visible label by default. If it was created with labels: { mode: 'automatic' }, zoom thresholds and collision suppression can hide ordinary labels. Selected, focused, hovered, highlighted, and dragged items receive priority. label.visible: false always hides a label.

Image export fails

Canvas export requires a mounted CanvasGraphRenderer that has rendered at least one snapshot. It exports the current viewport, not the whole graph. Requested JPEG or WebP may fall back to PNG when the browser lacks an encoder; inspect the returned type.

A screen reader cannot reach graph items

The Canvas surface does not create semantic DOM for every node and edge. Provide a companion list, details panel, status output, and explicit commands for important workflows. Current browser checks do not constitute screen-reader or physical-touch certification. See accessibility and input.

Get help or report a problem

Developers with repository access can use the Issues tab and the bug-report or documentation-feedback template. Include the revision, browser, smallest reproduction, and relevant console output. See contributing. A public support route will be documented when the repository opens.

Do not post suspected vulnerabilities or credentials in a public issue. The current security policy directs reporters to the private maintainer channel until private vulnerability reporting is configured.

Use the API reference to check exact signatures, or compare behavior with the live examples.