Installing and loading EVK

EVK is one npm package, entity-viz-kit, with separate import paths. It has no runtime dependencies. React is an optional peer. It has not been published to a registry; install the packed tarball.

npm run pack:library                       # in the EVK repository → build/entity-viz-kit-<version>.tgz
npm install /path/to/entity-viz-kit-<version>.tgz   # in your application
npm install react react-dom                # only if you use entity-viz-kit/react or /react/graph

Import paths

Import	Loads	Needs
entity-viz-kit/core	IDs, schemas, registry, pure state, controller, anchors, presentation protocol	nothing
entity-viz-kit/highlighter	canonical DOM text map and live highlighter	a browser DOM when called
entity-viz-kit/graph	native WebGL2 graph (mountGraph)	a browser DOM when called, plus the worker asset
entity-viz-kit/graph/worker	the standalone force-layout Worker script	served as a file
entity-viz-kit/react	search, reading, inspection, workspace and presentation components	React 18.3 or 19
entity-viz-kit/react/graph	EntityGraph, ControllerGraph	React 18.3 or 19
entity-viz-kit/styles.css	all scoped styles	your bundler’s CSS handling

The separation is enforced, not just intended. npm run check:consumer computes each entry’s import closure and fails if /core reaches React, graph or highlighter code, if /highlighter reaches the graph, or if /react reaches the graph. It writes build/reports/bundle-analysis.json. npm run check:consumer:browser loads the packed package in a real browser without React and draws two graphs and a highlighter.

ESM only

The package is ESM-only. require('entity-viz-kit/core') fails with ERR_PACKAGE_PATH_NOT_EXPORTED; the consumer check asserts this. Use import (Node 22, any modern bundler, or native browser modules with an import map).

Server-side rendering

Importing /core, /highlighter, /graph, /react and /react/graph touches no document or window. The consumer check imports them with both globals set to throw. Only calling the DOM entry points needs a browser:

• mountGraph, attachHighlighter and createDomTextMap must run on the client, for example in a useEffect or after hydration.
• EntityGraph and ControllerGraph mount the canvas in an effect, so they render an empty container on the server.
• useEntityController(controller, serverSnapshot) accepts a server snapshot for hydration.

Server rendering with react-dom/server is checked on React 18.3 and 19 (npm run check:consumer). Client hydration is exercised by the browser suites on React 19.

Styles

Import the stylesheet once, anywhere in your application:

import 'entity-viz-kit/styles.css';

Every rule is scoped under .evk, .evk-graph, .evk-app or other evk- classes. No rule targets html, body or bare elements, and nothing loads fonts, images or other network assets. Wrap your EVK components in EntityVizProvider (see theming and localization), which renders the .evk root that carries the theme tokens.

If your page has a strict style-src, serve the stylesheet from your own origin like any other CSS file.

Graph worker asset

The graph runs force layout in a dedicated Worker. The Worker script is a file your host serves; EVK never fetches it from anywhere else.

1. Copy node_modules/entity-viz-kit/build/compiled/graph/layout.worker.js (also exported as entity-viz-kit/graph/worker) into your static assets.
2. Pass its URL as workerUrl, or a workerFactory if your bundler creates workers itself.
3. Without either, the graph loads evk-layout.worker.js next to the current HTML page.

Your CSP must allow that script as a worker: worker-src 'self', or a default-src 'self' like the demo server’s. If the Worker cannot start, the graph reports layout unavailable, keeps a static layout, and the accessible navigator still works. worker: false disables it on purpose. See graph and worker.

TypeScript

Declarations ship next to each entry (types in the export map). Use "moduleResolution": "NodeNext" or "Bundler". Identity types are branded: create IDs with entityId(...), documentId(...) and the other constructors from /core, never by casting strings.

The React declarations compile against genuine @types/react 18.3 and 19.3 (npm run check:consumer).

Node and browsers

• The package declares Node >=22.16.0 (engines). Development and CI use Node 24.14.0 (.nvmrc), and only Node 24 is tested.
• Tested browsers: Chrome for Testing 153 (all suites) and Firefox 156 (the extension suite).
• The graph needs WebGL2; without it, the graph shows its navigator-only fallback.
• The highlighter uses CSS Custom Highlights when available and an SVG overlay otherwise.

No Safari or real mobile browser has been run (see the handoff).