@neo4j-nvl/base 2.0.0-c8e499dc → 2.0.0-ec6fdba7

package/skills/neo4j-nvl-skill/SKILL.md

@@ -1,456 +1,296 @@
 ---
 name: neo4j-nvl-skill
+metadata:
+  package: '@neo4j-nvl/base'
+  version: '2.0.0-ec6fdba7'
 description: Neo4j Visualization Library (NVL) — framework-agnostic graph rendering for the browser.
   Covers @neo4j-nvl/base (NVL class, nodes/relationships, Canvas vs WebGL renderer),
-  @neo4j-nvl/interaction-handlers (ZoomInteraction, PanInteraction, DragNodeInteraction, ClickInteraction,
-  HoverInteraction, BoxSelectInteraction, LassoInteraction, KeyboardInteraction), and @neo4j-nvl/react
-  (InteractiveNvlWrapper, BasicNvlWrapper, StaticPictureWrapper). Use when rendering a Neo4j graph in
-  a browser, feeding driver results through nvlResultTransformer, choosing Canvas vs WebGL,
-  wiring node/relationship click/hover/drag handlers, or embedding NVL in React, Vite,
-  or vanilla JS apps.
-  Does NOT handle Cypher query authoring — use neo4j-cypher-skill.
-  Does NOT handle driver lifecycle, sessions, or executeQuery setup — use neo4j-driver-javascript-skill.
-  Does NOT handle GraphVisualization/Needle default embed — use @neo4j-ndl/react.
-compatibility: "@neo4j-nvl packages 2.0.x; React 19 for @neo4j-nvl/react; modern browsers with Canvas2D + WebGL2"
-version: 2.0.0
+  @neo4j-nvl/interaction-handlers (zoom, pan, drag, click, hover, box/lasso select, keyboard) and
+  @neo4j-nvl/react (InteractiveNvlWrapper, BasicNvlWrapper, StaticPictureWrapper). Use when rendering
+  a Neo4j graph in a browser, feeding driver results through nvlResultTransformer, choosing Canvas vs
+  WebGL, clustering or laying out nodes, wiring node/relationship/cluster interactions, or embedding
+  NVL in React, Vite or vanilla JS apps.
+  Does NOT handle Cypher authoring — use neo4j-cypher-skill.
+  Does NOT handle driver lifecycle, sessions or executeQuery setup — use neo4j-driver-javascript-skill.
+  Does NOT handle the pre-styled GraphVisualization embed — use @neo4j-ndl/react.
+compatibility: '@neo4j-nvl packages 2.x; React 19 for @neo4j-nvl/react; browsers with Canvas2D and WebGL2'
 ---
 
-> **Version note:** This skill documents the NVL version in `compatibility`. If the project's installed `@neo4j-nvl/base` is a different version and `node_modules/@neo4j-nvl/base/skills/neo4j-nvl-skill/SKILL.md` exists, read that copy instead.
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
 
-## When to Use
-- Rendering a Neo4j graph in a browser (vanilla JS, React, Vite) with custom interactions, rendering, or data shapes
-- Visualizing `driver.executeQuery` results as an interactive graph
-- Wiring zoom, pan, drag, click, hover, lasso, or box-select interactions
-- Embedding NVL inside an existing app and synchronizing graph state
-
-## When NOT to Use
-- **Pre-styled embedded graph view with default behavior, no custom interactions** → `GraphVisualization` from `@neo4j-ndl/react` (Neo4j Needle / NDL design system) — wraps NVL with default Neo4j styling. See [Use NVL or the Needle Component?](#use-nvl-or-the-needle-component) below.
-- **Python / Jupyter notebook graph visualization** → `neo4j/python-graph-visualization` (the Python port of NVL)
-- **Writing/optimizing Cypher** → `neo4j-cypher-skill`
-- **Driver setup / executeQuery / sessions** → `neo4j-driver-javascript-skill`
-- **Server-side data fetching with no rendering** → `neo4j-driver-javascript-skill`
-- **GDS algorithm execution** → `neo4j-gds-skill` or `neo4j-aura-graph-analytics-skill`
-- **GraphQL API** → `neo4j-graphql-skill`
+# Neo4j Visualization Library (@neo4j-nvl/base)
 
----
+> Shipped with `@neo4j-nvl/base` v2.0.0-ec6fdba7. Once installed into a project this folder is detached from the
+> package: the installed types in `node_modules/@neo4j-nvl/*` are the source of truth. If the project's
+> `@neo4j-nvl/base` is a different version and `node_modules/@neo4j-nvl/base/skills/neo4j-nvl-skill/SKILL.md`
+> exists, read that copy instead.
 
-## Use NVL or the Needle Component?
+## When to use
+
+- Rendering a Neo4j graph in the browser with custom interactions, rendering or data shapes
+- Visualizing `driver.executeQuery` results as an interactive graph
+- Zoom, pan, drag, click, hover, lasso or box-select interactions; clustering; custom layouts
+
+Not for: a pre-styled graph view with default behaviour (`GraphVisualization` from `@neo4j-ndl/react` wraps
+NVL for that), Python notebooks (`neo4j/python-graph-visualization`), Cypher, driver setup, GDS or GraphQL.
+
+## Rules
+
+- **Types win.** Confirm every option, callback and method against this skill or the `.d.ts` files in
+  `node_modules/@neo4j-nvl/*` before using it. If they disagree, trust the types and say so.
+- **Never invent options.** NVL options and callbacks are flat, named keys. If a key is not in the API
+  reference below or the types, it does not exist.
+- **Do not reverse-engineer from compiled `dist/` or `lib/` output.** Use the types and these docs.
+- **Symptom first.** When something does not work, check the table below before changing code.
+
+## Before you code
+
+1. The container has explicit `width` **and** `height`; otherwise the graph is invisible.
+2. React wrappers: `layout`, `layoutOptions` and every other option go inside `nvlOptions`.
+3. Wheel zoom in `<InteractiveNvlWrapper>` is enabled by `mouseEventCallbacks.onZoomAndPan`; there is no `onZoom`.
+4. `fit()` needs explicit node ids. `fit([])` fits nothing.
+5. The WebGL renderer draws no captions. Use `'canvas'` when labels matter, or `html` / `icon` overlays.
+6. If the hierarchical layout never finishes under the Vite dev server, add `optimizeDeps: { include: ['bin-pack'] }`. Vite 7.3 pre-bundles it on its own, so only apply it when the symptom appears.
+7. `nvlResultTransformer` returns bare `{ id }` elements; labels and properties are in `recordObjectMap`.
+8. React: `nvlCallbacks` are captured once; use refs or stable functions. `interactionOptions` replaces
+   the defaults, so pass every option you need.
+9. Destroy interaction handlers, then `nvl.destroy()`, on teardown. The React wrappers do this for you.
+
+## Symptom → cause → fix
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Graph invisible / blank | Container has no height | Explicit `width` and `height` on the container |
+| Wheel does not zoom (React) | Zoom handler only wired from `onZoomAndPan` | `mouseEventCallbacks={{ onZoomAndPan: true }}` → [react-wrappers](references/react-wrappers.md) |
+| Hierarchical layout never finishes (Vite dev) | Layout `SharedWorker` imports CJS `bin-pack`; seen on older Vite, not on 7.3 | `optimizeDeps: { include: ['bin-pack'] }` → [vite-and-bundlers](references/vite-and-bundlers.md) |
+| No text on nodes with WebGL | Captions are Canvas-only | `html` / `icon`, own overlay, or `setRenderer('canvas')` → [labels-and-overlays](references/labels-and-overlays.md) |
+| `fit([])` does nothing | Empty array = no nodes | `fit(nvl.getNodes().map((n) => n.id))` |
+| `fit()` stops zoomed in on a huge graph | `minZoom` clamp (default `0.075`) | `fit(ids, { minZoom })` or lower the `minZoom` option |
+| Clicking a cluster selects all its nodes | `selectOnClick` selects `cluster.nodeIds` | `selectOnClick: false` and select in `onNodeClick` → [clustering](references/clustering.md) |
+| No cluster outlines / halos | Not force-directed, or mixed colours (halo) | Force-directed with `layoutOptions.clustering`; one colour per cluster → [clustering](references/clustering.md) |
+| Pinned nodes move when clustering is on | Cluster forces ignore pins | Do not combine → [clustering](references/clustering.md) |
+| Changing circle options does nothing | Layout is not re-run on option change | Bounce via `setLayout('free')` → [layouts-and-positions](references/layouts-and-positions.md) |
+| Un-pinned nodes stay frozen | Settled simulation is not restarted | `setNodePositions(current, true)` → [layouts-and-positions](references/layouts-and-positions.md) |
+| Node `x`/`y` props do not move existing nodes | Positions apply on insert only | `setNodePositions` → [layouts-and-positions](references/layouts-and-positions.md) |
+| Callbacks see stale state (React) | `nvlCallbacks` captured at creation | Refs or stable functions → [react-wrappers](references/react-wrappers.md) |
+| Minimap empty (React) | Container did not exist at creation | Keep the element in state → [react-wrappers](references/react-wrappers.md) |
+| Hover / shadow defaults lost | `interactionOptions` replaces defaults | Pass every option → [react-wrappers](references/react-wrappers.md) |
+| Many icons not drawn | Too many distinct icon images | Fewer distinct icons → [labels-and-overlays](references/labels-and-overlays.md) |
+| Layout looks hung in headless Chrome | Software WebGL | Hardware-GL flags → [verifying-nvl-apps](references/verifying-nvl-apps.md) |
+| Raw `executeQuery` result passed to NVL | Records are not graph elements | `resultTransformer: nvlResultTransformer` → [data-from-neo4j](references/data-from-neo4j.md) |
+
+## Choose
+
+**NVL or Needle?** Default Neo4j styling and no custom interaction → `GraphVisualization` from `@neo4j-ndl/react`.
+Anything custom → NVL.
 
 | Need | Use |
 |---|---|
-| Embed a graph view with default Neo4j styling, no custom interactions or rendering | `GraphVisualization` from `@neo4j-ndl/react` (Neo4j Needle / NDL design system) — wraps NVL and accepts records shaped `{ id, labels, properties: { key: { stringified, type } } }` (`NeoNode`) |
-| Custom interactions, custom rendering, non-standard data shapes, or framework-agnostic embedding | This skill — use NVL directly |
+| React, default interactions | `<InteractiveNvlWrapper>` from `@neo4j-nvl/react` |
+| React, custom interaction logic | `<BasicNvlWrapper>` + `ref` to the `NVL` instance |
+| Vanilla, standard interactions | `NVL` + `@neo4j-nvl/interaction-handlers` |
+| Vanilla, custom events | `NVL` + `container.addEventListener` + `nvl.getHits()` |
+| Static PNG / SVG | `<StaticPictureWrapper>` or `nvl.saveToFile()` / `nvl.saveToSvg()` |
 
-If the answer is the first row, install and use the Needle component instead of NVL — do not duplicate styling work.
+| Renderer | Nodes | Notes |
+|---|---|---|
+| `'canvas'` (default) | up to ~1,000 | Captions, icons, arrows, exact hit-testing |
+| `'webgl'` | 100,000+ | WebGL2 only; no captions; icons and arrowheads supported |
 
----
+`disableWebGL: true` forces Canvas rendering and non-GPU layouts.
 
 ## Install
 
 ```bash
-npm install @neo4j-nvl/base                  # core (required)
-npm install @neo4j-nvl/interaction-handlers  # standard interactions (optional, vanilla JS)
-npm install @neo4j-nvl/react                 # React wrappers (optional)
+npm install @neo4j-nvl/base                  # required
+npm install @neo4j-nvl/interaction-handlers  # vanilla interactions
+npm install @neo4j-nvl/react                 # React wrappers (React 19)
 ```
 
-Peer requirements: **React 19** for `@neo4j-nvl/react`. The published peerDependency range still permits React 18, but mixing major versions is not recommended — target 19. `@neo4j-nvl/layout-workers` is a transitive dependency — never install directly. `neo4j-driver` is a peer of `@neo4j-nvl/base` only when using `nvlResultTransformer`.
-
-Starter templates: https://github.com/neo4j-devtools/nvl-boilerplates — official per-framework scaffolds; prefer these over hand-rolled setups.
-
-License: NVL ships under the **Neo4j Visualization Library License** — for use with Neo4j products only. Cannot be used against other graph backends.
-
----
-
-## Pick the Right Paradigm
-
-| Need | Use |
-|---|---|
-| React app, default interactions | `<InteractiveNvlWrapper>` from `@neo4j-nvl/react` |
-| React app, custom interaction wiring | `<BasicNvlWrapper>` + own handlers via `ref` |
-| Vanilla JS, standard interactions | `NVL` + `@neo4j-nvl/interaction-handlers` |
-| Vanilla JS, fully custom event logic | `NVL` + `container.addEventListener` + `nvl.getHits()` |
-| Static PNG/SVG image export | `<StaticPictureWrapper>` or `nvl.saveToFile()` / `nvl.saveToSvg()` |
-
----
-
-## Pick the Right Renderer
-
-| Renderer | Max nodes | Detail | Use case |
-|---|---|---|---|
-| `'canvas'` (default) | ~1,000 | Captions, icons, arrows, pixel-perfect hit-testing | Detail investigation, small graphs |
-| `'webgl'` | 100,000+ | No captions; supports node icons and relationship arrowheads in 2.0 | Large-scale pattern exploration |
-
-```javascript
-const nvl = new NVL(container, nodes, rels, { renderer: 'webgl' })
-nvl.setRenderer('canvas')   // swap at runtime
-```
-
-NVL 2.0 requires **WebGL2** for the GPU renderer and force-directed physics engine. When GPU acceleration is unavailable, NVL can fall back to Canvas rendering and non-GPU layout implementations; use `disableWebGL: true` to explicitly avoid WebGL.
-
----
-
-## Container Setup
-
-The container must have an explicit `width` AND `height`. Missing height → container collapses to `0` → graph invisible. Most-reported NVL bug.
-
-```html
-<!-- ❌ height defaults to 0; graph invisible -->
-<div id="viz"></div>
-
-<!-- ✅ explicit dimensions -->
-<div id="viz" style="width: 100%; height: 600px;"></div>
-```
-
----
-
-## Vanilla — Base Library
-
-```javascript
-import { NVL } from '@neo4j-nvl/base'
-
-const container = document.getElementById('viz')
-const nodes = [{ id: '1' }, { id: '2' }]
-const relationships = [{ id: '12', from: '1', to: '2', type: 'KNOWS' }]
+`@neo4j-nvl/layout-workers` is transitive; never install it directly. `neo4j-driver` is only needed for
+`nvlResultTransformer`. License: Neo4j Visualization Library License, for use with Neo4j products.
+Starters: https://github.com/neo4j-devtools/nvl-boilerplates
 
-const nvl = new NVL(container, nodes, relationships)
-```
-
-With options + callbacks:
+## Minimal examples
 
 ```javascript
 import { NVL } from '@neo4j-nvl/base'
+import { ClickInteraction, ZoomInteraction, PanInteraction, DragNodeInteraction } from '@neo4j-nvl/interaction-handlers'
 
-const options = {
-  initialZoom: 1.0,
-  minZoom: 0.1,
-  maxZoom: 8,
-  layout: 'forceDirected',
-  renderer: 'canvas',
-  styling: { defaultNodeColor: '#0e86d4', defaultRelationshipColor: '#888' }
-}
-const callbacks = {
-  onInitialization: () => console.log('NVL ready'),
-  onLayoutDone: () => nvl.fit([]),
-  onError: (err) => console.error('NVL error', err)
-}
-
-const nvl = new NVL(container, nodes, relationships, options, callbacks)
-
-// On teardown — always:
-nvl.destroy()
-```
-
-`NVL` constructor signature: `new NVL(frame, nvlNodes?, nvlRels?, options?, callbacks?)`. All but `frame` are optional and default to empty.
-
----
-
-## Vanilla — Interaction Handlers
-
-Compose handlers onto an existing `NVL` instance. Each handler registers callbacks via `.updateCallback(name, fn)` and must be torn down with `.destroy()`.
-
-```javascript
-import { NVL } from '@neo4j-nvl/base'
-import {
-  ZoomInteraction, PanInteraction, DragNodeInteraction,
-  ClickInteraction, HoverInteraction, BoxSelectInteraction,
-  LassoInteraction, KeyboardInteraction
-} from '@neo4j-nvl/interaction-handlers'
-
-const nvl = new NVL(container, nodes, relationships)
-
-const zoom  = new ZoomInteraction(nvl)
-const pan   = new PanInteraction(nvl)
-const drag  = new DragNodeInteraction(nvl)
-const click = new ClickInteraction(nvl, { selectOnClick: true })
-const hover = new HoverInteraction(nvl, { drawShadowOnHover: true })
-
-click.updateCallback('onNodeClick',         (node, hits, evt) => console.log('node',  node.id))
-click.updateCallback('onRelationshipClick', (rel,  hits, evt) => console.log('rel',   rel.id))
-click.updateCallback('onClusterClick',      (cluster, hits, evt) => console.log('cluster', cluster.id))
-click.updateCallback('onCanvasClick',       (evt)             => console.log('canvas'))
-hover.updateCallback('onHover',             (el, hits, evt)   => el && console.log('over', el.id))
-drag.updateCallback('onDragEnd',            (nodes, evt)      => savePositions(nodes))
-zoom.updateCallback('onZoomAndPan',          (level, panX, panY) => console.log(level, panX, panY))
-
-// Teardown — destroy all handlers, then the NVL instance
-function teardown() {
-  for (const h of [zoom, pan, drag, click, hover]) h.destroy()
-  nvl.destroy()
-}
+const nodes = [{ id: '1', caption: 'A' }, { id: '2', caption: 'B' }]
+const rels = [{ id: '12', from: '1', to: '2', type: 'KNOWS' }]
+const nvl = new NVL(container, nodes, rels, { layout: 'forceDirected' }, {
+  onLayoutDone: () => nvl.fit(nodes.map((n) => n.id))
+})
+const handlers = [new ZoomInteraction(nvl), new PanInteraction(nvl), new DragNodeInteraction(nvl),
+  new ClickInteraction(nvl, { selectOnClick: true })]
+handlers[3].updateCallback('onNodeClick', (node) => console.log(node.id))
+// teardown: handlers.forEach((h) => h.destroy()); nvl.destroy()
 ```
 
-Disable an event without removing the handler: `click.removeCallback('onCanvasClick')`. Passing `true` instead of a function enables the event with a no-op (useful for default selection behavior).
-
----
-
-## React — InteractiveNvlWrapper
-
-Pre-wires every interaction handler. Toggle events with `mouseEventCallbacks` (function = on + callback; `true` = on, no-op; `false`/omit = off).
-
 ```tsx
 import { InteractiveNvlWrapper } from '@neo4j-nvl/react'
-import type { MouseEventCallbacks } from '@neo4j-nvl/react'
+import type { NVL } from '@neo4j-nvl/base'
 import { useRef } from 'react'
-import type { NVL, NvlOptions } from '@neo4j-nvl/base'
 
-export function GraphView({ nodes, rels }) {
+export function Graph({ nodes, rels }) {
   const nvlRef = useRef<NVL>(null)
-
-  const nvlOptions: NvlOptions = { initialZoom: 1, renderer: 'canvas' }
-
-  const mouseEventCallbacks: MouseEventCallbacks = {
-    onNodeClick:         (node, hits, evt) => console.log('node',  node.id),
-    onRelationshipClick: (rel,  hits, evt) => console.log('rel',   rel.id),
-    onClusterClick:      (cluster, hits, evt) => console.log('cluster', cluster.id),
-    onCanvasClick:       (evt)             => console.log('canvas'),
-    onHover:             (el, hits, evt)   => {
-      if (el) console.log('hover', el.id)
-      if (hits.clusters[0]) console.log('cluster hover', hits.clusters[0].data.id)
-    },
-    onDragEnd:           (nodes, evt)      => persist(nodes),
-    onZoomAndPan: true,                                 // enable, no callback
-    onPan:  true
-  }
-
   return (
     <div style={{ width: '100%', height: 600 }}>
       <InteractiveNvlWrapper
         ref={nvlRef}
         nodes={nodes}
         rels={rels}
-        nvlOptions={nvlOptions}
+        nvlOptions={{ layout: 'forceDirected', renderer: 'canvas' }}
         interactionOptions={{ selectOnClick: true, drawShadowOnHover: true }}
-        mouseEventCallbacks={mouseEventCallbacks}
-        onInitializationError={(err) => console.error('NVL init', err)}
-      />
-    </div>
-  )
-}
-```
-
-`ref` resolves to the underlying `NVL` instance — call any method on it: `nvlRef.current?.fit([])`, `nvlRef.current?.setRenderer('webgl')`, `nvlRef.current?.saveToFile()`.
-
----
-
-## NVL 2.0 — Layout Clustering
-
-`clusterBy` groups nodes whose callback returns the same string or number. Return `undefined` for independent nodes. Keep the callback reference stable in React with `useCallback`.
-
-Force-directed clustering nests all clustering settings under `layoutOptions.clustering`:
-
-```javascript
-const clusterBy = (nodeId) => categoryByNodeId[nodeId]
-
-const nvl = new NVL(container, nodes, relationships, {
-  layout: 'forceDirected',
-  layoutOptions: {
-    seedingMethod: 'circle',
-    clustering: {
-      clusterBy,
-      drawOutline: true,
-      drawHalo: true,
-      crossClusterRelationshipMultiplier: 0.2
-    }
-  },
-  minFps: 3,
-  maxFps: 30
-})
-```
-
-`crossClusterRelationshipMultiplier` is experimental, capped to `0..1`, and can destabilize highly connected graphs near `1`. It affects cross-cluster spring pull only; intra-cluster edges remain full strength.
-
-Hierarchical clustering places `clusterBy` directly in `layoutOptions`:
-
-```javascript
-const nvl = new NVL(container, nodes, relationships, {
-  layout: 'hierarchical',
-  layoutOptions: {
-    direction: 'down',
-    clusterBy
-  }
-})
-```
-
-Cluster decorations and cluster hull interactions apply to force-directed `layoutOptions.clustering`. A `Cluster` is not a graph element; it has `{ id: string | number, nodeIds: string[] }`. Cluster callbacks fire only for empty space inside a cluster hull; node and relationship hits retain priority.
-
----
-
-## Migrating from NVL 1.x to 2.0
-
-- Move React wrapper `layout` and `layoutOptions` props into `nvlOptions`:
-  `<InteractiveNvlWrapper nvlOptions={{ layout, layoutOptions }} />`.
-- Replace interaction callback `onZoom` with `onZoomAndPan(zoom, panX, panY, event)`.
-- Remove `intelWorkaround` and Cytoscape-related layout settings; they no longer exist.
-- Treat WebGL as WebGL2-only and do not expect captions in the WebGL renderer.
-- `getNodes()` and `onLayoutStep` return `NodeWithClientPosition[]`: `x`/`y` are layout coordinates and `clientPosition` is relative to the canvas element.
-- Use `styling.overlayLineColor`; `styling.minimapViewportBoxColor` is deprecated.
-
----
-
-## React — BasicNvlWrapper + Ref
-
-No interactions wired. The ref exposes every NVL method via `IncludeMethods<NVL>` — use when building custom interaction logic in React.
-
-```tsx
-import { BasicNvlWrapper } from '@neo4j-nvl/react'
-import type { NVL } from '@neo4j-nvl/base'
-import { useRef } from 'react'
-
-export function MiniGraph({ nodes, rels }) {
-  const nvlRef = useRef<NVL>(null)
-
-  return (
-    <div style={{ width: '100%', height: 400 }}>
-      <BasicNvlWrapper
-        ref={nvlRef}
-        nodes={nodes}
-        rels={rels}
-        nvlOptions={{ initialZoom: 2 }}
-        nvlCallbacks={{ onLayoutDone: () => nvlRef.current?.fit([]) }}
+        mouseEventCallbacks={{
+          onNodeClick: (node) => console.log(node.id),
+          onZoomAndPan: true,
+          onPan: true,
+          onDrag: true
+        }}
+        nvlCallbacks={{ onLayoutDone: () => nvlRef.current?.fit(nodes.map((n) => n.id)) }}
       />
-      <button onClick={() => nvlRef.current?.fit(['1', '2'])}>Zoom to 1,2</button>
     </div>
   )
 }
 ```
 
----
+## Topic guides
+
+Read the one that matches the task before writing code.
+
+- [references/data-from-neo4j.md](references/data-from-neo4j.md) — `nvlResultTransformer` output, `recordObjectMap`, enriching nodes, Integer and temporal values
+- [references/react-wrappers.md](references/react-wrappers.md) — callback-to-handler mapping, stale callbacks, live vs creation-time options, minimap container
+- [references/clustering.md](references/clustering.md) — `clusterBy` per layout, outlines and halos, cluster click and hover, pins
+- [references/layouts-and-positions.md](references/layouts-and-positions.md) — when layouts re-run, `setNodePositions`, pinning, layout callbacks
+- [references/labels-and-overlays.md](references/labels-and-overlays.md) — captions vs `html` / `icon` / `overlayIcon`, coordinates for custom overlays
+- [references/vite-and-bundlers.md](references/vite-and-bundlers.md) — worker setup per bundler, dev vs production, `disableWebWorkers`
+- [references/verifying-nvl-apps.md](references/verifying-nvl-apps.md) — `window.__Nvl_*` hooks, headless Chrome flags, detecting a settled layout
+- [references/lifecycle-and-updates.md](references/lifecycle-and-updates.md) — add/update/remove methods, `restart`, teardown, context loss, telemetry, `onError`
+- [references/migrating-1x-to-2.md](references/migrating-1x-to-2.md) — removed options and renamed callbacks
+
+## API reference
+
+Generated from the installed version's type declarations. Open the page for the symbol you need; do not
+load all of them.
+
+### `@neo4j-nvl/base`
+
+NVL class, options, callbacks, graph element types, hit testing, nvlResultTransformer.
+
+**Classes**
 
-## Wiring a Neo4j Driver Result
+- [NVL](references/api/base/classes/NVL.md) — Class for a NVL instance.
+
+**Functions**
+
+- [getZoomTargetForNodePositions](references/api/base/functions/getZoomTargetForNodePositions.md) — Gets the zoom target to fit the given node positions into the scene.
+
+**Interfaces**
 
-`@neo4j-nvl/base` exports a `ResultTransformer` for the JS driver that deduplicates nodes/relationships across any record shape.
+- [CircularOptions](references/api/base/interfaces/CircularOptions.md) — The options for the circular layout.
+- [ClusteringOptions](references/api/base/interfaces/ClusteringOptions.md) — Options that control physical clustering and cluster decorations for the force-directed layout.
+- [ExternalCallbacks](references/api/base/interfaces/ExternalCallbacks.md) — An object specifying the required callback functions for certain actions
+- [ForceDirectedOptions](references/api/base/interfaces/ForceDirectedOptions.md) — The options for the force directed layout
+- [HierarchicalOptions](references/api/base/interfaces/HierarchicalOptions.md) — The options for the hierarchical layout
+- [HitTargetCluster](references/api/base/interfaces/HitTargetCluster.md) — A ClusteringOptions.clusterBy cluster hull that has been hit by a pointer event
+- [HitTargetNode](references/api/base/interfaces/HitTargetNode.md) — A node that has been hit by a pointer event
+- [HitTargetRelationship](references/api/base/interfaces/HitTargetRelationship.md) — A relationship that has been hit by a pointer event
+- [Node](references/api/base/interfaces/Node.md) — A node inside the graph visualization.
+- [NvlMouseEvent](references/api/base/interfaces/NvlMouseEvent.md) — The result of a NVL.getHits call.
+- [NvlOptions](references/api/base/interfaces/NvlOptions.md) — Configurations for a NVL instance
+- [Point](references/api/base/interfaces/Point.md) — An object representing a point in 2D space.
+- [Relationship](references/api/base/interfaces/Relationship.md) — A relationship inside the graph visualization.
 
-```javascript
-import neo4j from 'neo4j-driver'
-import { NVL, nvlResultTransformer } from '@neo4j-nvl/base'
+**Types**
 
-const driver = neo4j.driver(process.env.NEO4J_URI,
-  neo4j.auth.basic(process.env.NEO4J_USERNAME, process.env.NEO4J_PASSWORD))
+- [CanvasRendererType](references/api/base/type-aliases/CanvasRendererType.md) — A renderer using canvas.
+- [Cluster](references/api/base/type-aliases/Cluster.md) — A physical cluster produced by ClusteringOptions.clusterBy.
+- [ClusterByFn](references/api/base/type-aliases/ClusterByFn.md) — Function that maps a node id to a ClusterId for force-directed clustering.
+- [ClusterId](references/api/base/type-aliases/ClusterId.md) — Identifier returned by ClusterByFn to group nodes into physical clusters.
+- [HitTargets](references/api/base/type-aliases/HitTargets.md) — A collection of nodes, relationships and clusters that have been hit by a pointer event
+- [HitTestTarget](references/api/base/type-aliases/HitTestTarget.md)
+- [Layout](references/api/base/type-aliases/Layout.md) — The different types of layouts available
+- [LayoutOptions](references/api/base/type-aliases/LayoutOptions.md) — The options for the layout.
+- [NodeWithClientPosition](references/api/base/type-aliases/NodeWithClientPosition.md) — A node returned by NVL.getNodes with layout coordinates and screen position.
+- [PartialNode](references/api/base/type-aliases/PartialNode.md) — A node with only a subset of its properties.
+- [PartialRelationship](references/api/base/type-aliases/PartialRelationship.md) — A relationship with only a subset of its properties.
+- [Renderer](references/api/base/type-aliases/Renderer.md) — The different types of renderers available
+- [StyledCaption](references/api/base/type-aliases/StyledCaption.md) — The caption text and its text style.
+- [WebGLRendererType](references/api/base/type-aliases/WebGLRendererType.md) — A WebGL2 renderer that uses the GPU for rendering.
+- [ZoomOptions](references/api/base/type-aliases/ZoomOptions.md) — Options that influence how fit-to-zoom should behave
 
-const { nodes, relationships } = await driver.executeQuery(
-  'MATCH (a)-[r]-(b) RETURN a, r, b LIMIT 25',
-  {},
-  { database: 'neo4j', resultTransformer: nvlResultTransformer }
-)
+**Variables**
 
-const nvl = new NVL(document.getElementById('viz'), nodes, relationships)
-```
+- [CircularLayoutType](references/api/base/variables/CircularLayoutType.md) — A basic circular layout.
+- [d3ForceLayoutType](references/api/base/variables/d3ForceLayoutType.md) — The commonly used d3-force layout.
+- [ForceDirectedLayoutType](references/api/base/variables/ForceDirectedLayoutType.md) — NVL's main force directed layout.
+- [FreeLayoutType](references/api/base/variables/FreeLayoutType.md) — A free layout that allows for arbitrary positioning of elements using NVL's setPosition method.
+- [GridLayoutType](references/api/base/variables/GridLayoutType.md) — A basic grid layout.
+- [HierarchicalLayoutType](references/api/base/variables/HierarchicalLayoutType.md) — A hierarchical layout using the dagre algorithm.
+- [nvlResultTransformer](references/api/base/variables/nvlResultTransformer.md) — Result transformer for the Neo4j JavaScript driver results to NVL graph elements.
 
-```javascript
-// ❌ raw EagerResult — records are not Node/Relationship objects
-const result = await driver.executeQuery('MATCH (a)-[r]-(b) RETURN a, r, b')
-new NVL(container, result.records, [])   // breaks
-
-// ✅ use the transformer
-const { nodes, relationships } = await driver.executeQuery(
-  'MATCH (a)-[r]-(b) RETURN a, r, b',
-  {},
-  { database: 'neo4j', resultTransformer: nvlResultTransformer }
-)
-new NVL(container, nodes, relationships)
-```
+### `@neo4j-nvl/interaction-handlers`
 
-For driver lifecycle, session management, Integer handling, and TypeScript types → `neo4j-driver-javascript-skill`.
-
----
+Zoom, pan, drag, click, hover, box/lasso select, keyboard handlers and their callbacks.
 
-## Updating the Graph
-
-| Method | Behavior |
-|---|---|
-| `addAndUpdateElementsInGraph(nodes, rels)` | Insert new; update existing by id (only specified fields) |
-| `updateElementsInGraph(nodes, rels)` | Update existing only; ignores unknown ids |
-| `addElementsToGraph(nodes, rels)` | Insert only; throws on existing id |
-| `removeNodesWithIds(ids)` | Remove nodes; adjacent relationships auto-removed |
-| `removeRelationshipsWithIds(ids)` | Remove relationships |
-| `setNodePositions(nodes, updateLayout?)` | Override positions; optionally re-run layout |
-| `restart(options?, retainPositions?)` | Restart with new options; positions optional |
-
-Diff updates use `PartialNode` / `PartialRelationship` — only `id` is required:
-
-```javascript
-nvl.updateElementsInGraph(
-  [{ id: '1', color: '#f00', selected: true }],   // PartialNode
-  [{ id: '12', width: 4 }]                         // PartialRelationship
-)
-```
-
----
+**Classes**
 
-## Hit Testing (Manual)
+- [BoxSelectInteraction](references/api/interaction-handlers/classes/BoxSelectInteraction.md) — An interaction handler for multi-selecting nodes and relationships.
+- [ClickInteraction](references/api/interaction-handlers/classes/ClickInteraction.md) — Click interaction handler that handles click, double click and right click events on
+- [DragNodeInteraction](references/api/interaction-handlers/classes/DragNodeInteraction.md) — Interaction handler for dragging nodes,
+- [HoverInteraction](references/api/interaction-handlers/classes/HoverInteraction.md) — Interaction handler for hovering nodes and relationships.
+- [KeyboardInteraction](references/api/interaction-handlers/classes/KeyboardInteraction.md) — Opinionated interaction handler for keyboard-driven focus navigation
+- [LassoInteraction](references/api/interaction-handlers/classes/LassoInteraction.md) — An interaction handler that lets you select nodes and relationships by drawing a lasso around them.
+- [PanInteraction](references/api/interaction-handlers/classes/PanInteraction.md) — Interaction handler for panning the scene, which is achieved by clicking and moving the scene.
+- [ZoomInteraction](references/api/interaction-handlers/classes/ZoomInteraction.md) — Interaction handler for zooming the canvas, which is achieved by:
 
-Use when NOT using the interaction-handlers package. In 2.0, `getHits()` resolves nodes, relationships, and force-directed cluster hulls. Its default targets are `['node', 'relationship', 'cluster']`.
+**Types**
 
-```javascript
-const nvl = new NVL(container, nodes, rels)
-
-container.addEventListener('click', (evt) => {
-  const { nvlTargets } = nvl.getHits(evt, ['node', 'relationship', 'cluster'], { hitNodeMarginWidth: 4 })
-  const hitNode = nvlTargets.nodes[0]
-  const hitRel  = nvlTargets.relationships[0]
-  const hitCluster = nvlTargets.clusters[0]
-  if (hitNode) console.log('hit node', hitNode.data.id)
-  else if (hitRel) console.log('hit rel', hitRel.data.id)
-  else if (hitCluster) console.log('hit cluster', hitCluster.data.id, hitCluster.data.nodeIds)
-  else console.log('hit canvas')
-})
-```
-
-`HitTargetNode` / `HitTargetRelationship` carry element hit data. `HitTargetCluster` carries `data`, `pointerCoordinates`, and the fitted convex `hull`. See [references/api-surface.md](references/api-surface.md).
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---|---|
-| Container with no `height` → invisible graph | Set explicit `width` and `height` on the container |
-| Pass `driver.executeQuery` result directly | Use `nvlResultTransformer` and consume `{ nodes, relationships }` |
-| WebGL for small label-rich graphs | Use `'canvas'`; labels are fully supported |
-| Canvas for 10k+ nodes | Switch to `'webgl'` via `renderer` option or `setRenderer` |
-| New `NVL` per React render | Use `<InteractiveNvlWrapper>` / `<BasicNvlWrapper>` or wrap in `useEffect` + `destroy()` |
-| Forgetting `nvl.destroy()` on teardown | Call `destroy()` on unmount; React wrappers handle this automatically |
-| Vanilla handlers not torn down | Call `.destroy()` on every interaction before `nvl.destroy()` |
-| Worker construction blocked (strict CSP / sandboxed runtime / older bundler) | `nvlOptions: { disableWebWorkers: true }` (NVL has a non-worker fallback) |
-| Telemetry enabled in regulated env | `nvlOptions: { disableTelemetry: true }` |
-| Layout never settles | Pin anchor nodes with `pinNode(id)`; tune `layoutTimeLimit` |
-| `selectOnClick` fires double | Toggle once at mount; don't flip `interactionOptions` per render |
-| Hit test misses near node edge | Pass `{ hitNodeMarginWidth: N }` to `getHits` |
-| Captions missing on WebGL | Expected in 2.0; captions are Canvas-only, so use `'canvas'` when labels matter |
-| React wrapper ignores `layout` / `layoutOptions` | In 2.0 these must be nested in `nvlOptions` |
-| `onZoom` never fires | It was removed in 2.0; use `onZoomAndPan` |
-| Cluster callback misses clicks on a node | Cluster callbacks target empty cluster-hull space; node hits take priority |
-
----
-
-## References
-
-Load on demand:
-- [references/api-surface.md](references/api-surface.md) — complete 2.0 `NVL` method table; clustering, FPS, seeding, `NodeWithClientPosition`, hit target and interaction callback types; React props; named exports; `nvlResultTransformer`
-- [references/troubleshooting.md](references/troubleshooting.md) — zero-height container, WebGL2 and Canvas trade-offs, clustering configuration, 1.x migration errors, worker fallback, context loss, telemetry, lifecycle, layout and hit-testing issues
-
-Canonical web documentation (use `WebFetch` when references above are insufficient):
-- https://neo4j.com/docs/nvl/current/ — user guide (installation, base library, interaction handlers, React wrappers)
-- https://neo4j.com/docs/api/nvl/current/ — TypeDoc API reference
-- https://neo4j.com/docs/api/nvl/current/examples.html — runnable examples
-- https://github.com/neo4j-devtools/nvl-boilerplates — official starter templates per supported framework
-- https://github.com/neo4j/python-graph-visualization — Python port of NVL (use this skill only for the JavaScript/browser path)
-
----
+- [BoxSelectInteractionCallbacks](references/api/interaction-handlers/type-aliases/BoxSelectInteractionCallbacks.md) — Callbacks for the box select interaction handler.
+- [BoxSelectInteractionOptions](references/api/interaction-handlers/type-aliases/BoxSelectInteractionOptions.md) — Options for the multi-select interaction handler to customize its behavior.
+- [ClickInteractionCallbacks](references/api/interaction-handlers/type-aliases/ClickInteractionCallbacks.md) — Callbacks for the click interaction handler.
+- [ClickInteractionOptions](references/api/interaction-handlers/type-aliases/ClickInteractionOptions.md) — Options for the click interaction handler to customize its behavior.
+- [DragNodeInteractionCallbacks](references/api/interaction-handlers/type-aliases/DragNodeInteractionCallbacks.md) — Callbacks for the drag node interaction handler.
+- [DrawInteractionOptions](references/api/interaction-handlers/type-aliases/DrawInteractionOptions.md) — Options for the draw interaction handler.
+- [HoverInteractionCallbacks](references/api/interaction-handlers/type-aliases/HoverInteractionCallbacks.md) — Callbacks for the hover interaction handler.
+- [HoverInteractionOptions](references/api/interaction-handlers/type-aliases/HoverInteractionOptions.md) — Options for the hover interaction handler to customize its behavior.
+- [KeyboardInteractionCallbacks](references/api/interaction-handlers/type-aliases/KeyboardInteractionCallbacks.md) — Callbacks for the keyboard interaction handler.
+- [KeyboardInteractionOptions](references/api/interaction-handlers/type-aliases/KeyboardInteractionOptions.md) — Options for the keyboard interaction handler.
+- [LassoInteractionCallbacks](references/api/interaction-handlers/type-aliases/LassoInteractionCallbacks.md) — Callbacks for the lasso interaction handler.
+- [LassoInteractionOptions](references/api/interaction-handlers/type-aliases/LassoInteractionOptions.md) — Options for the lasso interaction handler to customize its behavior.
+- [PanInteractionCallbacks](references/api/interaction-handlers/type-aliases/PanInteractionCallbacks.md) — Callbacks for the pan interaction handler.
+- [PanInteractionOptions](references/api/interaction-handlers/type-aliases/PanInteractionOptions.md) — Options for the pan interaction handler to customize its behavior.
+- [ZoomInteractionCallbacks](references/api/interaction-handlers/type-aliases/ZoomInteractionCallbacks.md) — Callbacks for the zoom interaction handler.
+- [ZoomInteractionOptions](references/api/interaction-handlers/type-aliases/ZoomInteractionOptions.md) — Options for the zoom interaction handler to customize its behavior.
+
+### `@neo4j-nvl/react`
+
+InteractiveNvlWrapper, BasicNvlWrapper, StaticPictureWrapper and their props.
 
-## Checklist
-- [ ] Container has explicit `width` AND `height` CSS
-- [ ] Correct paradigm chosen from the decision table (vanilla / handlers / React)
-- [ ] Renderer matches expected node count (Canvas ≲1k / WebGL 100k+)
-- [ ] Canvas selected whenever captions are required
-- [ ] React `layout` and `layoutOptions` nested inside `nvlOptions`
-- [ ] Zoom handlers use `onZoomAndPan`, not removed `onZoom`
-- [ ] `clusterBy` is stable in React and placed correctly for the selected layout
-- [ ] Driver `executeQuery` results piped through `nvlResultTransformer`
-- [ ] `database` specified on every `executeQuery` call (delegate to `neo4j-driver-javascript-skill`)
-- [ ] All interaction handlers `.destroy()`-ed before `nvl.destroy()` on teardown
-- [ ] `nvl.destroy()` called on React unmount (manual instances only — wrappers handle it)
-- [ ] `disableTelemetry: true` set when in regulated / offline environments
-- [ ] `disableWebWorkers: true` set when bundler / CSP blocks worker construction
-- [ ] Graph updates use `addAndUpdateElementsInGraph` / `updateElementsInGraph` — not `restart`
-- [ ] License compatible: target is a Neo4j product
+**Functions**
+
+- [StaticPictureWrapper](references/api/react/functions/StaticPictureWrapper.md) — A React component that creates a static picture of a graph using NVL.
+
+**Interfaces**
+
+- [BasicReactWrapperProps](references/api/react/interfaces/BasicReactWrapperProps.md) — The properties that can be passed to the BasicNvlWrapper component.
+- [InteractiveNvlWrapperProps](references/api/react/interfaces/InteractiveNvlWrapperProps.md) — The properties that can be passed to the InteractiveNvlWrapper component.
+
+**Types**
+
+- [InteractionOptions](references/api/react/type-aliases/InteractionOptions.md) — Collection of interaction options that can be used with
+- [KeyboardEvent](references/api/react/type-aliases/KeyboardEvent.md)
+- [KeyboardEventCallbacks](references/api/react/type-aliases/KeyboardEventCallbacks.md) — Collection of keyboard event callbacks that can be used with
+- [MouseEvent](references/api/react/type-aliases/MouseEvent.md) — The events that can be passed to the MouseEventCallbacks object
+- [MouseEventCallbacks](references/api/react/type-aliases/MouseEventCallbacks.md) — Collection of mouse event callbacks that can be used with
+- [StaticPictureWrapperProps](references/api/react/type-aliases/StaticPictureWrapperProps.md) — The properties that can be passed to the StaticPictureWrapper component.
+
+**Variables**
+
+- [BasicNvlWrapper](references/api/react/variables/BasicNvlWrapper.md) — A basic React wrapper that wraps the NVL base library within a React component.
+- [InteractiveNvlWrapper](references/api/react/variables/InteractiveNvlWrapper.md) — The interactive React wrapper component contains a collection of interaction handlers by default
+
+Web: user guide https://neo4j.com/docs/nvl/current/ · API https://neo4j.com/docs/api/nvl/current/ ·
+examples https://neo4j.com/docs/api/nvl/current/examples.html