Adopting Entity Viz Kit

This is the one page to read before using EVK in an application. It ships in the package, is served at /docs/adopting/ on the site, and feeds the site’s /llms.txt. Everything else is detail behind the links at the end.

What EVK is. Drop-in components for entity search and connection graphs. Your application supplies entities (people, organizations, places and so on) with explicit IDs, search results, relations and the evidence behind them, through one adapter. EVK supplies the client-side state and the UI: query tags, results with highlighted mentions, profiles, relation and evidence views, and a WebGL graph with pinning. EVK never guesses identity from names and never calls a backend itself.

Install

On the construction machine, each release is published under /srv/artifacts/entity-viz-kit/<version>/. Pin a version directory; latest moves. There is no public registry yet.

npm install /srv/artifacts/entity-viz-kit/<version>/entity-viz-kit-<version>.tgz
npm install react react-dom      # only for entity-viz-kit/react and entity-viz-kit/react/graph (React 18.3 or 19)

Each version directory also holds INSTALL.md, SHA256SUMS (run sha256sum -c SHA256SUMS), verification-summary.md and ONAB’s onab-run.json for that exact commit. The package is ESM-only, has no runtime dependencies, and importing it touches no DOM global, so server rendering is safe.

The smallest working integration

import { createElement as h } from 'react';
import { createRoot } from 'react-dom/client';
import 'entity-viz-kit/styles.css';
import { createController } from 'entity-viz-kit/core';
import { EntityVizProvider, EntitySearchControls, InspectionPanel } from 'entity-viz-kit/react';
import { ControllerGraph } from 'entity-viz-kit/react/graph';

// `adapter` is yours: `search`, plus `profile`, `relation`, `evidence` and `source` if you serve them.
// `graph` is a GraphSnapshot built from your relations.
const controller = createController(adapter);

function Explorer() {
  return h(
    EntityVizProvider,
    { theme: 'auto' },
    h(EntitySearchControls, { controller }),
    h(ControllerGraph, { controller, snapshot: graph, workerUrl: '/evk-layout.worker.js' }),
    h(InspectionPanel, { controller, relations: graph.pairs })
  );
}

createRoot(document.getElementById('explorer')!).render(h(Explorer));
void controller.start();

Three things the host must provide:

The worker file. Serve node_modules/entity-viz-kit/build/compiled/graph/layout.worker.js from your own origin and pass its URL as workerUrl.
Content Security Policy. EVK needs no inline script or eval. Allow the worker from your origin (worker-src 'self') and your bundled stylesheet. EVK loads nothing from third parties.
The adapter. Answer each request with the response shape in entity-viz-kit/core, echoing requestId and revision. EVK validates every response and treats its contents as data, never as code or instructions. Unknown fields, bad IDs and unsafe URLs are rejected. An operation you don’t serve becomes an “unavailable” state in the UI, not an error. The host-integration guide has the protocol and a JSON-over-HTTP adapter you can copy.

Stable and experimental

Stable, and covered by semantic versioning from 1.0.0: entity-viz-kit/core, entity-viz-kit/react, entity-viz-kit/graph, entity-viz-kit/react/graph, entity-viz-kit/graph/worker and entity-viz-kit/styles.css.

Experimental, which may change in any minor release: entity-viz-kit/highlighter, the presentation protocol in /core and the PresentationControls/AudienceDisplay components in /react, and the browser extensions. Each experimental export says so in its documentation. exports-stability.json is the classification, and a test keeps it, the README, the JSDoc and the API reference in agreement.

Versions before 1.0

Patch (0.y.z). Fixes only, with no change to public behavior or types.
Minor (0.y.0). May change public behavior or types. Each change is listed in CHANGELOG.md under that version, with what to do instead.
Deprecations. Announced in the changelog at least one minor release before the removal, whenever the old path can keep working in the meantime.
Tags. Every release is an annotated Git tag, created by the release pipeline, and the version comes from package.json alone.

Reporting problems

Write a short Markdown file into /srv/feedback/entity-viz-kit/ on the construction machine, following the README.md template there. EVK’s agent reads the folder at the start of each session and answers in the same file. Include the EVK version, what you expected, what happened, and the smallest input that shows it. Never include credentials or private data.