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

package/skills/neo4j-nvl-skill/references/api/react/index.md

@@ -0,0 +1,34 @@
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# @neo4j-nvl/react
+
+## Interfaces
+
+| Interface | Description |
+| ------ | ------ |
+| [BasicReactWrapperProps](interfaces/BasicReactWrapperProps.md) | The properties that can be passed to the [BasicNvlWrapper](variables/BasicNvlWrapper.md) component. |
+| [InteractiveNvlWrapperProps](interfaces/InteractiveNvlWrapperProps.md) | The properties that can be passed to the [InteractiveNvlWrapper](variables/InteractiveNvlWrapper.md) component. |
+
+## Type Aliases
+
+| Type Alias | Description |
+| ------ | ------ |
+| [InteractionOptions](type-aliases/InteractionOptions.md) | Collection of interaction options that can be used with the [InteractiveNvlWrapper](variables/InteractiveNvlWrapper.md) component. |
+| [KeyboardEvent](type-aliases/KeyboardEvent.md) | - |
+| [KeyboardEventCallbacks](type-aliases/KeyboardEventCallbacks.md) | Collection of keyboard event callbacks that can be used with the [InteractiveNvlWrapper](variables/InteractiveNvlWrapper.md) component. |
+| [MouseEvent](type-aliases/MouseEvent.md) | The events that can be passed to the [MouseEventCallbacks](type-aliases/MouseEventCallbacks.md) object to turn on/off certain events for the [InteractiveNvlWrapper](variables/InteractiveNvlWrapper.md) component. |
+| [MouseEventCallbacks](type-aliases/MouseEventCallbacks.md) | Collection of mouse event callbacks that can be used with the [InteractiveNvlWrapper](variables/InteractiveNvlWrapper.md) component. |
+| [StaticPictureWrapperProps](type-aliases/StaticPictureWrapperProps.md) | The properties that can be passed to the StaticPictureWrapper component. |
+
+## Variables
+
+| Variable | Description |
+| ------ | ------ |
+| [BasicNvlWrapper](variables/BasicNvlWrapper.md) | A basic React wrapper that wraps the NVL base library within a React component. It takes the class' arguments as properties, which are passed to the NVL constructor. Any changes in properties will be reflected in the NVL instance by calling the corresponding methods. |
+| [InteractiveNvlWrapper](variables/InteractiveNvlWrapper.md) | The interactive React wrapper component contains a collection of interaction handlers by default and provides a variety of common functionality and callbacks. It is an extension of the [BasicNvlWrapper](variables/BasicNvlWrapper.md) component and incorporates the @neo4j-nvl/interaction-handlers module's decorators to provide a set of interaction events. |
+
+## Functions
+
+| Function | Description |
+| ------ | ------ |
+| [StaticPictureWrapper](functions/StaticPictureWrapper.md) | A React component that creates a static picture of a graph using NVL. This component is useful for generating static visualizations of graphs without requiring user interaction. The component automatically fits all nodes in the viewport before capturing the image NVL is automatically destroyed after capturing the image to free up resources. |

package/skills/neo4j-nvl-skill/references/api/react/interfaces/BasicReactWrapperProps.md

@@ -0,0 +1,24 @@
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# Interface: BasicReactWrapperProps
+
+The properties that can be passed to the [BasicNvlWrapper](../variables/BasicNvlWrapper.md) component.
+
+## Extended by
+
+- [`InteractiveNvlWrapperProps`](InteractiveNvlWrapperProps.md)
+
+## Properties
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| `nodes` | `Node`[] | The nodes of the graph of type Node[] |
+| `nvlCallbacks?` | `ExternalCallbacks` | an Object containing functions for callbacks on certain actions |
+| `nvlOptions?` | `NvlOptions` | An object containing options for the Nvl instance |
+| `onInitializationError?` | (`error`) => `void` | A callback to handle any errors that happen during NVL initialization |
+| `pan?` | \{ `x`: `number`; `y`: `number`; \} | Sets the pan coordinates of the viewport using the setPan method. **Remarks** If both zoom and pan are provided, the setZoomAndPan method will be used. |
+| `pan.x` | `number` | The x coordinate of the pan. |
+| `pan.y` | `number` | The y coordinate of the pan. |
+| `positions?` | `Node`[] | Sets the positions of the nodes in the graph using the setNodePositions method. |
+| `rels` | `Relationship`[] | The rels of the graph of type Relationship[] |
+| `zoom?` | `number` | Sets the zoom level of the viewport using the setZoom method. **Remarks** If both zoom and pan are provided, the setZoomAndPan method will be used. |

package/skills/neo4j-nvl-skill/references/api/react/interfaces/InteractiveNvlWrapperProps.md

@@ -0,0 +1,27 @@
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# Interface: InteractiveNvlWrapperProps
+
+The properties that can be passed to the [InteractiveNvlWrapper](../variables/InteractiveNvlWrapper.md) component.
+
+## Extends
+
+- [`BasicReactWrapperProps`](BasicReactWrapperProps.md)
+
+## Properties
+
+| Property | Type | Description | Inherited from |
+| ------ | ------ | ------ | ------ |
+| `interactionOptions?` | [`InteractionOptions`](../type-aliases/InteractionOptions.md) | [InteractionOptions](../type-aliases/InteractionOptions.md) for the underlying interaction handlers | - |
+| `keyboardEventCallbacks?` | `KeyboardInteractionCallbacks` | [KeyboardEventCallbacks](../type-aliases/KeyboardEventCallbacks.md) containing functions for callbacks on keyboard actions | - |
+| `mouseEventCallbacks?` | [`MouseEventCallbacks`](../type-aliases/MouseEventCallbacks.md) | [MouseEventCallbacks](../type-aliases/MouseEventCallbacks.md) containing functions for callbacks on certain actions | - |
+| `nodes` | `Node`[] | The nodes of the graph of type Node[] | [`BasicReactWrapperProps`](BasicReactWrapperProps.md).[`nodes`](BasicReactWrapperProps.md#nodes) |
+| `nvlCallbacks?` | `ExternalCallbacks` | an Object containing functions for callbacks on certain actions | [`BasicReactWrapperProps`](BasicReactWrapperProps.md).[`nvlCallbacks`](BasicReactWrapperProps.md#nvlcallbacks) |
+| `nvlOptions?` | `NvlOptions` | An object containing options for the Nvl instance | [`BasicReactWrapperProps`](BasicReactWrapperProps.md).[`nvlOptions`](BasicReactWrapperProps.md#nvloptions) |
+| `onInitializationError?` | (`error`) => `void` | A callback to handle any errors that happen during NVL initialization | [`BasicReactWrapperProps`](BasicReactWrapperProps.md).[`onInitializationError`](BasicReactWrapperProps.md#oninitializationerror) |
+| `pan?` | \{ `x`: `number`; `y`: `number`; \} | Sets the pan coordinates of the viewport using the setPan method. **Remarks** If both zoom and pan are provided, the setZoomAndPan method will be used. | [`BasicReactWrapperProps`](BasicReactWrapperProps.md).[`pan`](BasicReactWrapperProps.md#pan) |
+| `pan.x` | `number` | The x coordinate of the pan. | - |
+| `pan.y` | `number` | The y coordinate of the pan. | - |
+| `positions?` | `Node`[] | Sets the positions of the nodes in the graph using the setNodePositions method. | [`BasicReactWrapperProps`](BasicReactWrapperProps.md).[`positions`](BasicReactWrapperProps.md#positions) |
+| `rels` | `Relationship`[] | The rels of the graph of type Relationship[] | [`BasicReactWrapperProps`](BasicReactWrapperProps.md).[`rels`](BasicReactWrapperProps.md#rels) |
+| `zoom?` | `number` | Sets the zoom level of the viewport using the setZoom method. **Remarks** If both zoom and pan are provided, the setZoomAndPan method will be used. | [`BasicReactWrapperProps`](BasicReactWrapperProps.md).[`zoom`](BasicReactWrapperProps.md#zoom) |

package/skills/neo4j-nvl-skill/references/api/react/type-aliases/InteractionOptions.md

@@ -0,0 +1,10 @@
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# Type Alias: InteractionOptions
+
+```ts
+type InteractionOptions = ClickInteractionOptions & BoxSelectInteractionOptions & HoverInteractionOptions & PanInteractionOptions & ZoomInteractionOptions & LassoInteractionOptions & DrawInteractionOptions & KeyboardInteractionOptions;
+```
+
+Collection of interaction options that can be used with
+the [InteractiveNvlWrapper](../variables/InteractiveNvlWrapper.md) component.

package/skills/neo4j-nvl-skill/references/api/react/type-aliases/KeyboardEvent.md

@@ -0,0 +1,7 @@
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# Type Alias: KeyboardEvent
+
+```ts
+type KeyboardEvent = keyof KeyboardEventCallbacks;
+```

package/skills/neo4j-nvl-skill/references/api/react/type-aliases/KeyboardEventCallbacks.md

@@ -0,0 +1,10 @@
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# Type Alias: KeyboardEventCallbacks
+
+```ts
+type KeyboardEventCallbacks = KeyboardInteractionCallbacks;
+```
+
+Collection of keyboard event callbacks that can be used with
+the [InteractiveNvlWrapper](../variables/InteractiveNvlWrapper.md) component.

package/skills/neo4j-nvl-skill/references/api/react/type-aliases/MouseEvent.md

@@ -0,0 +1,10 @@
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# Type Alias: MouseEvent
+
+```ts
+type MouseEvent = keyof MouseEventCallbacks;
+```
+
+The events that can be passed to the [MouseEventCallbacks](MouseEventCallbacks.md) object
+to turn on/off certain events for the [InteractiveNvlWrapper](../variables/InteractiveNvlWrapper.md) component.

package/skills/neo4j-nvl-skill/references/api/react/type-aliases/MouseEventCallbacks.md

@@ -0,0 +1,10 @@
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# Type Alias: MouseEventCallbacks
+
+```ts
+type MouseEventCallbacks = ClickInteractionCallbacks & DragNodeInteractionCallbacks & HoverInteractionCallbacks & PanInteractionCallbacks & ZoomInteractionCallbacks & BoxSelectInteractionCallbacks & DrawInteractionCallbacks & LassoInteractionCallbacks;
+```
+
+Collection of mouse event callbacks that can be used with
+the [InteractiveNvlWrapper](../variables/InteractiveNvlWrapper.md) component.

package/skills/neo4j-nvl-skill/references/api/react/type-aliases/StaticPictureWrapperProps.md

@@ -0,0 +1,27 @@
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# Type Alias: StaticPictureWrapperProps
+
+```ts
+type StaticPictureWrapperProps = {
+  format?: "png" | "svg";
+  height?: number;
+  nodes: Node[];
+  nvlOptions?: NvlOptions;
+  rels: Relationship[];
+  width?: number;
+};
+```
+
+The properties that can be passed to the StaticPictureWrapper component.
+
+## Properties
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| `format?` | `"png"` \| `"svg"` | The format of the static picture: 'png' or 'svg'. Defaults to 'png'. |
+| `height?` | `number` | The height of the static picture in pixels. |
+| `nodes` | `Node`[] | The nodes to be displayed in the graph. |
+| `nvlOptions?` | `NvlOptions` | Options to customize the NVL instance. |
+| `rels` | `Relationship`[] | The relationships to be displayed in the graph. |
+| `width?` | `number` | The width of the static picture in pixels. |

package/skills/neo4j-nvl-skill/references/api/react/variables/BasicNvlWrapper.md

@@ -0,0 +1,50 @@
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# Variable: BasicNvlWrapper
+
+```ts
+const BasicNvlWrapper: MemoExoticComponent<ForwardRefExoticComponent<Omit<BasicReactWrapperProps & HTMLProps<HTMLDivElement>, "ref"> & RefAttributes<Partial<Pick<NVL, 
+  | "restart"
+  | "addAndUpdateElementsInGraph"
+  | "getSelectedNodes"
+  | "getSelectedRelationships"
+  | "removeNodesWithIds"
+  | "removeRelationshipsWithIds"
+  | "getNodes"
+  | "getRelationships"
+  | "getNodeById"
+  | "getRelationshipById"
+  | "getPositionById"
+  | "getCurrentOptions"
+  | "destroy"
+  | "deselectAll"
+  | "fit"
+  | "resetZoom"
+  | "setRenderer"
+  | "setDisableWebGL"
+  | "pinNode"
+  | "unPinNode"
+  | "setLayout"
+  | "setLayoutOptions"
+  | "getNodesOnScreen"
+  | "getNodePositions"
+  | "setNodePositions"
+  | "isLayoutMoving"
+  | "saveToFile"
+  | "saveToSvg"
+  | "getImageDataUrl"
+  | "getSvgDataUrl"
+  | "saveFullGraphToLargeFile"
+  | "getZoomLimits"
+  | "setZoom"
+  | "getScale"
+  | "getPan"
+  | "getHits"
+| "getContainer">>>>>;
+```
+
+A basic React wrapper that wraps the NVL base library within a React component.
+It takes the class' arguments as properties, which are passed to the NVL constructor.
+Any changes in properties will be reflected in the NVL instance by calling the corresponding methods.
+
+For examples, head to the [Basic React wrapper documentation page](https://neo4j.com/docs/nvl/current/react-wrappers/#_basic_react_wrapper).

package/skills/neo4j-nvl-skill/references/api/react/variables/InteractiveNvlWrapper.md

@@ -0,0 +1,17 @@
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# Variable: InteractiveNvlWrapper
+
+```ts
+const InteractiveNvlWrapper: MemoExoticComponent<ForwardRefExoticComponent<Omit<InteractiveNvlWrapperProps & HTMLProps<HTMLDivElement>, "ref"> & RefAttributes<NVL>>>;
+```
+
+The interactive React wrapper component contains a collection of interaction handlers by default
+and provides a variety of common functionality and callbacks.
+It is an extension of the [BasicNvlWrapper](BasicNvlWrapper.md) component and incorporates the
+@neo4j-nvl/interaction-handlers module's decorators to provide a set of interaction events.
+
+The mouseEventCallbacks property takes an object where various callbacks can be defined
+and behavior can be toggled on and off.
+
+For examples, head to the [Interactive React wrapper documentation page](https://neo4j.com/docs/nvl/current/react-wrappers/#_interactive_react_wrapper).

package/skills/neo4j-nvl-skill/references/clustering.md

@@ -0,0 +1,87 @@
+# Clustering
+
+When you need this: you want nodes grouped by a property, drawn with outlines or halos, or you need to react to clicks and hovers on a cluster.
+
+Verification tags: **source**, **types**, **runtime** (see `SKILL.md`).
+
+## Options per layout
+
+`clusterBy` is `(nodeId: string) => string | number | undefined`. Nodes returning the same value share a cluster; `undefined` means independent. Keep the function reference stable (`useCallback` in React) or the clustering is re-evaluated on every render. *types*
+
+| Layout | Where | Decorations | Hulls / hit-testing |
+|---|---|---|---|
+| `forceDirected` | `layoutOptions.clustering: { clusterBy, drawOutline, drawHalo, crossClusterRelationshipMultiplier }` | yes | yes |
+| `hierarchical` | `layoutOptions.clusterBy` (experimental) | no | no |
+| `circular` | none; order nodes with `layoutOptions.sortFunction` | no | no |
+| `free`, `grid`, `d3Force` | not supported | no | no |
+
+*types, source*
+
+```javascript
+const clusterBy = (nodeId) => categoryByNodeId[nodeId]
+
+// force-directed
+new NVL(container, nodes, rels, {
+  layout: 'forceDirected',
+  layoutOptions: {
+    clustering: { clusterBy, drawOutline: true, drawHalo: true, crossClusterRelationshipMultiplier: 0.2 }
+  }
+})
+
+// hierarchical
+new NVL(container, nodes, rels, {
+  layout: 'hierarchical',
+  layoutOptions: { direction: 'down', clusterBy }
+})
+```
+
+`crossClusterRelationshipMultiplier` (default `0`, capped `0..1`) scales the spring pull of relationships that cross clusters; intra-cluster edges stay at full strength. Values near `1` can destabilise highly connected graphs. *types*
+
+## Outlines and halos
+
+- Outline colour is the shared node colour of the cluster; if colours differ it falls back to `styling.overlayLineColor`. *types*
+- A halo is drawn **only** when every node in the cluster has the same colour. Mixed colours → no halo, no error. *types*
+- Decorations are drawn for the force-directed layout only. Switching to `free` keeps positions but removes the overlay. *source, runtime*
+- Changing `layoutOptions.clustering` through `setLayoutOptions` redraws the overlay. *source*
+
+## A `Cluster` is not a graph element
+
+`Cluster = { id: string | number, nodeIds: string[] }`. It has no colour or position of its own; its hull is computed from the member positions. *types*
+
+## Clicks
+
+`ClickInteraction` resolves hits in priority order: nodes, then relationships, then clusters, then canvas. Cluster callbacks (`onClusterClick`, `onClusterDoubleClick`, `onClusterRightClick`) fire only for empty space inside a hull. *source*
+
+With `selectOnClick: true`, clicking inside a hull selects **all** `cluster.nodeIds`; clicking again deselects them (a cluster counts as selected when all members are). *source*
+
+To select single nodes but still know when a hull is clicked:
+
+```javascript
+const click = new ClickInteraction(nvl, { selectOnClick: false })
+click.updateCallback('onNodeClick', (node) => nvl.updateElementsInGraph([{ id: node.id, selected: true }], []))
+click.updateCallback('onClusterClick', (cluster) => console.log('hull', cluster.id, cluster.nodeIds.length))
+```
+
+## Hover
+
+`HoverInteraction` has a single `onHover(element, hitElements, event)` callback where `element` is a node, a relationship or `undefined`. There is no cluster hover event, but `hitElements.clusters` is filled: *types, source*
+
+```javascript
+hover.updateCallback('onHover', (element, hits) => {
+  const cluster = hits.clusters[0]?.data
+  if (!element && cluster) showTooltip(cluster.id)
+})
+```
+
+Without the interaction handlers: `nvl.getHits(event, ['cluster'])` returns `nvlTargets.clusters` with `data`, `pointerCoordinates` and the convex `hull` points. Clusters are included by default when the target list is omitted. *types*
+
+## Clustering and pinned nodes
+
+With `clustering.clusterBy` set, the force simulation moves pinned nodes too; re-applying positions does not hold them. Do not combine pinning with clustering. *runtime*
+
+## Checklist
+
+- Force-directed for decorations and hull interactions; hierarchical only groups.
+- One colour per cluster if you want halos.
+- `selectOnClick: false` if a hull click must not select every member.
+- Stable `clusterBy` reference in React.

package/skills/neo4j-nvl-skill/references/data-from-neo4j.md

@@ -0,0 +1,67 @@
+# Data from Neo4j
+
+When you need this: you have `neo4j-driver` results and want them on screen, styled from the data.
+
+Each statement below ends with how it was verified: **source** (read in the NVL repository), **types** (in the shipped `.d.ts`) or **runtime** (observed in a running app).
+
+## What `nvlResultTransformer` returns
+
+```typescript
+import { nvlResultTransformer } from '@neo4j-nvl/base'
+
+const { nodes, relationships, recordObjectMap } = await driver.executeQuery(
+  'MATCH (a)-[r]-(b) RETURN a, r, b LIMIT 100',
+  {},
+  { database: 'neo4j', resultTransformer: nvlResultTransformer }
+)
+```
+
+- `nodes` are bare `{ id }` and `relationships` are bare `{ id, from, to }`. `id` is the driver `elementId`. No caption, colour, size or type is set. *source*
+- `recordObjectMap` is a `Map<elementId, driver Node | Relationship | Path>`; it holds `labels`, `type` and `properties`. *source*
+- Every `Node`, `Relationship` and `Path` in every column is collected, including nested arrays. Paths are expanded to their segments. *source*
+- Output is not deduplicated. A node in several records appears several times. NVL ignores repeated ids on insert, so passing the array straight to NVL is fine. *source*
+
+## Enrich before rendering
+
+```typescript
+const styledNodes = nodes.map((node) => {
+  const record = recordObjectMap.get(node.id)
+  if (!record || !('labels' in record)) return node
+  const label = record.labels[0]
+  return {
+    ...node,
+    caption: String(record.properties.name ?? label),
+    color: colorByLabel[label],
+    size: 20
+  }
+})
+
+const styledRels = relationships.map((rel) => {
+  const record = recordObjectMap.get(rel.id)
+  return record && 'type' in record ? { ...rel, caption: record.type } : rel
+})
+
+new NVL(container, styledNodes, styledRels)
+```
+
+Dedupe yourself if you keep your own node store (`new Map(nodes.map((n) => [n.id, n]))`).
+
+## Values that need converting
+
+Driver values are not plain JS values. Convert before using them as captions or sizes. *types*
+
+- `Integer` → `value.toNumber()` (or `toString()` for ids), or open the driver with `disableLosslessIntegers: true`.
+- `Date`, `DateTime`, `Duration` → `value.toString()` or `toStandardDate()`.
+- Spatial `Point` → `value.x`, `value.y`.
+
+Driver setup, sessions and transactions belong to `neo4j-driver-javascript-skill`.
+
+## Passing the raw result
+
+```javascript
+// ❌ records are not graph elements; NVL gets ids missing
+const result = await driver.executeQuery('MATCH (a)-[r]-(b) RETURN a, r, b')
+new NVL(container, result.records, [])
+```
+
+Always go through the transformer, or map the records yourself to `{ id, ... }` / `{ id, from, to, ... }`.

package/skills/neo4j-nvl-skill/references/labels-and-overlays.md

@@ -0,0 +1,76 @@
+# Labels, icons and overlays
+
+When you need this: text or images on nodes, especially with the WebGL renderer, or you want to draw your own overlay (axes, legends, tooltips) that follows pan and zoom.
+
+Verification tags: **source**, **types**, **runtime** (see `SKILL.md`).
+
+## Renderer trade-off
+
+| Renderer | Practical ceiling | Captions | Icons / arrowheads | Hit-test |
+|---|---|---|---|---|
+| `'canvas'` (default) | ~1,000 nodes | yes | yes | exact |
+| `'webgl'` | 100,000+ nodes | **no** | yes | approximate |
+
+WebGL rendering and the force-directed physics need **WebGL2**. `disableWebGL: true` forces Canvas and the non-GPU layout implementations. Switch at runtime with `setRenderer`. *types*
+
+## Captions
+
+`caption` (single string) or `captions: StyledCaption[]` (styled, multiple); `captions` wins if both are set. Captions are drawn by the Canvas renderer only; with WebGL they are silently absent. There is no texture-size limit involved; it is a renderer feature gap. *types*
+
+Options when you need text and WebGL:
+
+1. `html` overlay per node (see below) for a few hundred visible nodes.
+2. `icon` for an image glyph instead of text.
+3. Draw your own overlay from `getNodes()` positions.
+4. Switch to `'canvas'` when zoomed in.
+
+## `icon`
+
+- URL of a square image drawn inside the node. Icons are expected to be black; on dark node colours they are inverted to white. *types*
+- Many distinct icon URLs (≈1,800 across 3,825 nodes) led to many nodes with no icon drawn and no warning. Keep the set of distinct images small. *runtime*
+
+## `overlayIcon`
+
+`{ url, position?: number[], size?: number }` draws a square image anywhere over the element; `size` is relative to the node size (default `1`). *types*
+
+## `html`
+
+`html: HTMLElement` is placed in an absolutely positioned `<div>` over the node, scaled with the zoom level. Experimental. *types, source*
+
+- Each node with `html` keeps about two DOM elements alive; 3,825 nodes gave ~7,700 elements and idle FPS fell from ~60 to ~50. *runtime*
+- Any `html` overlay disables the GPU position fast path, because positions must be read back to the CPU each frame. *source*
+- Relationship HTML captions are hidden with the WebGL renderer. *source*
+
+## Drawing your own overlay
+
+Use a sibling element over the container and convert coordinates:
+
+```javascript
+const toScreen = ({ x, y }) => {
+  const scale = nvl.getScale()
+  const pan = nvl.getPan()
+  const { width, height } = nvl.getContainer().getBoundingClientRect()
+  return { x: (x - pan.x) * scale + width / 2, y: (y - pan.y) * scale + height / 2 }
+}
+```
+
+- Node `size` is the radius in world units, so the screen radius is `size * scale`. *runtime*
+- `getNodes()` already includes `clientPosition` relative to the canvas, which is the same conversion. *types*
+- Redraw on `onZoomAndPan`, `onPan` and `onLayoutStep` (or on `onLayoutDone` if per-frame updates are not needed, to keep the GPU fast path).
+
+## Hit testing without interaction handlers
+
+```javascript
+container.addEventListener('click', (evt) => {
+  const { nvlTargets } = nvl.getHits(evt, ['node', 'relationship', 'cluster'], { hitNodeMarginWidth: 4 })
+  const node = nvlTargets.nodes[0]?.data
+  const rel = nvlTargets.relationships[0]?.data
+  const cluster = nvlTargets.clusters[0]?.data
+})
+```
+
+`HitTargetNode` / `HitTargetRelationship` carry `data`, `pointerCoordinates`, `distance` and `insideNode` (nodes). `HitTargetCluster` carries `data`, `pointerCoordinates` and the convex `hull`. Default `hitNodeMarginWidth` is `0`, so widen it when clicks near the edge miss. *types*
+
+## Image export
+
+Call `saveToFile({ filename, backgroundColor })`, `saveToSvg(...)` or `getImageDataUrl(...)` from `onLayoutDone`; before that the positions are still settling and the PNG can be blank. *types, runtime*

package/skills/neo4j-nvl-skill/references/layouts-and-positions.md

@@ -0,0 +1,65 @@
+# Layouts and positions
+
+When you need this: a layout does not re-run when you expect it to, nodes do not move when you set coordinates, or you need to choose a layout.
+
+Verification tags: **source**, **types**, **runtime** (see `SKILL.md`).
+
+## Choosing a layout
+
+| Data shape | `layout` | Notes |
+|---|---|---|
+| Generic network | `'forceDirected'` (default) | GPU physics on WebGL2; `layoutOptions.clustering`, `seedingMethod: 'box' \| 'circle'` |
+| Tree / DAG | `'hierarchical'` | `layoutOptions.direction`, `packing`; runs in a `SharedWorker` (see [vite-and-bundlers](vite-and-bundlers.md)) |
+| Ring | `'circular'` | `layoutOptions.sortFunction: (nodes) => nodes` |
+| Your own coordinates | `'free'` | Nothing moves; use `setNodePositions` |
+| Grid | `'grid'` | |
+| CPU force (d3) | `'d3Force'` | |
+
+*types*
+
+`minFps` / `maxFps` (defaults `3` / `30`, capped `1..120`) set the presentation rate while a layout is active. *types*
+
+## Callbacks
+
+- `onLayoutComputing(isComputing)` fires at start and end of a computation.
+- `onLayoutDone()` fires when the layout settles. Trigger `fit`, exports and screenshots from here.
+- `onLayoutStep(nodes)` fires every step with `NodeWithClientPosition[]`. Registering it disables the GPU position fast path (positions must be read back to the CPU each frame), so use it only when you need per-frame positions. *source*
+
+## When a layout re-runs, and when it does not
+
+- `setLayout(type)` with a **different** type switches and runs the new layout. Calling it with the current type does nothing visible. *source*
+- `setLayoutOptions(options)` updates the layout's options and redraws the cluster overlay when `clustering` is present. For the circular layout, changing `sortFunction` does **not** re-run the layout or fire `onLayoutDone`. *source, runtime*
+- Un-pinning nodes while `forceDirected` is active does not restart a settled simulation. *runtime*
+- `restart(options, true)` rebuilds NVL with merged options and keeps positions; it did not restart the simulation in the un-pin case. *runtime*
+
+Working restarts:
+
+```javascript
+// circular with a new order
+nvl.setLayout('free')
+nvl.setLayoutOptions({ sortFunction: byDegree })
+nvl.setLayout('circular')
+
+// wake a settled force-directed layout
+nvl.setNodePositions(nvl.getNodePositions(), true)
+```
+
+## Setting positions
+
+- `setNodePositions(nodes, updateLayout = false)` moves nodes to the given `x` / `y`. With `updateLayout: true` the current layout continues from there. *types*
+- `x` / `y` in node data are applied **on insert only**. Updating an existing node through `updateElementsInGraph` or the React `nodes` prop with new `x` / `y` does not move it; `setNodePositions` does. *source*
+- `pinNode(id)` / `unPinNode(ids: string[])` or `pinned: true` in node data hold nodes in place for the force-directed layout. Clustering forces ignore pins (see [clustering](clustering.md)). *types, runtime*
+- Mixed layouts (some nodes at data positions, others free): pin the fixed nodes, call `setNodePositions` for them, keep `forceDirected` for the rest. Switching back: un-pin, then `setNodePositions(current, true)`.
+
+## Coordinates
+
+`getNodes()` returns `x` / `y` in layout space and `clientPosition` relative to the canvas element. `getNodePositions()` returns layout coordinates only. *types*
+
+Layout → screen: `screen = (world - pan) * scale + containerSize / 2`, with `scale = getScale()` and `pan = getPan()`. A node's `size` is its radius in world units. *runtime*
+
+## Layout never settles
+
+- Pin anchor nodes (`pinNode`).
+- Use `hierarchical` for tree-shaped data.
+- Reduce the node count.
+- There is no `layoutTimeLimit` option; older guidance that mentions it is wrong. *types*

package/skills/neo4j-nvl-skill/references/lifecycle-and-updates.md

@@ -0,0 +1,65 @@
+# Lifecycle and graph updates
+
+When you need this: you add, change or remove elements after the first render, restart NVL, tear it down, or handle WebGL context loss.
+
+Verification tags: **source**, **types**, **runtime** (see `SKILL.md`).
+
+## Updating the graph
+
+| Method | Behaviour |
+|---|---|
+| `addAndUpdateElementsInGraph(nodes, rels)` | Insert new ids; update existing ones with the given fields |
+| `updateElementsInGraph(nodes, rels)` | Update existing only; unknown ids are ignored |
+| `addElementsToGraph(nodes, rels)` | Insert only; **existing ids are silently skipped** |
+| `removeNodesWithIds(ids)` | Remove nodes and their relationships |
+| `removeRelationshipsWithIds(ids)` | Remove relationships |
+| `setNodePositions(nodes, updateLayout?)` | Move nodes; optionally let the layout continue |
+| `restart(options?, retainPositions?)` | Rebuild with merged options |
+
+*source*
+
+Updates take `PartialNode` / `PartialRelationship`: only `id` is required. *types*
+
+```javascript
+nvl.updateElementsInGraph(
+  [{ id: '1', color: '#f00', selected: true }],
+  [{ id: '12', width: 4 }]
+)
+```
+
+Prefer the update methods over `restart` for data changes: `restart` recreates the renderer and layout and resets interaction state.
+
+Invalid elements (missing `id`, or a relationship whose `from` / `to` is unknown) go to `onError` when it is registered; otherwise a `TypeError` is thrown. *source*
+
+## Teardown
+
+Vanilla: destroy every interaction handler, then the instance.
+
+```javascript
+for (const h of handlers) h.destroy()
+nvl.destroy()
+```
+
+React: the wrappers do this on unmount. A manual `new NVL(...)` inside `useEffect` needs `return () => nvl.destroy()`, or the instance leaks across route changes.
+
+## `restart`
+
+`restart(options, retainPositions)` merges `options` into the current ones and rebuilds. With `retainPositions: true` nodes keep their coordinates. Use it to change creation-time options such as `styling` or `minZoom`; it does not restart a settled force-directed simulation (see [layouts-and-positions](layouts-and-positions.md)). *types, runtime*
+
+## WebGL context lost
+
+`onWebGLContextLost(event)` fires when the GPU drops the context (tab backgrounded, driver reset). Recover by switching renderer or restarting: *types*
+
+```javascript
+new NVL(container, nodes, rels, { renderer: 'webgl' }, {
+  onWebGLContextLost: () => nvl.restart({ renderer: 'canvas' }, true)
+})
+```
+
+## Telemetry
+
+NVL sends anonymous usage events through Segment unless `disableTelemetry: true` is set. Set it in regulated, offline and test environments. *source*
+
+## Errors
+
+Register `onError` to receive validation errors instead of exceptions; without it they throw. Worker construction failures are only logged with `console.warn` and fall back silently; a worker that loads but fails is not reported at all (see [vite-and-bundlers](vite-and-bundlers.md)). *source*

package/skills/neo4j-nvl-skill/references/migrating-1x-to-2.md

@@ -0,0 +1,50 @@
+# Migrating from NVL 1.x to 2.0
+
+When you need this: code or examples written for 1.x behave differently, or an option is reported as unknown.
+
+Verification tags: **source**, **types**, **runtime** (see `SKILL.md`).
+
+## React wrapper props
+
+`layout` and `layoutOptions` are no longer props of the wrappers; they live in `nvlOptions`. Passing them as props is a type error and has no effect. *types*
+
+```tsx
+// 1.x
+<InteractiveNvlWrapper layout="hierarchical" layoutOptions={{ direction: 'down' }} />
+
+// 2.0
+<InteractiveNvlWrapper nvlOptions={{ layout: 'hierarchical', layoutOptions: { direction: 'down' } }} />
+```
+
+## `onZoom` removed
+
+The `ZoomInteraction` callback is `onZoomAndPan(zoomLevel, panX, panY, event)`. In the React wrapper the key is `mouseEventCallbacks.onZoomAndPan`; it is also what enables wheel zoom. *source*
+
+## Removed options
+
+- `intelWorkaround` (GPU shader workaround) is gone.
+- `enableCytoscape` and other Cytoscape-related layout settings are gone.
+
+*types*
+
+## Renderer
+
+- WebGL rendering and the force-directed physics require **WebGL2**; WebGL1 is not supported.
+- The WebGL renderer supports node icons and relationship arrowheads but **not captions**. Use the Canvas renderer when labels matter.
+- `disableWebGL: true` forces Canvas rendering and non-GPU layouts.
+
+*types*
+
+## Return types
+
+`getNodes()` and `onLayoutStep` return `NodeWithClientPosition[]`: `x` / `y` are layout coordinates and `clientPosition` is relative to the canvas element. *types*
+
+## Styling
+
+`styling.minimapViewportBoxColor` is deprecated; use `styling.overlayLineColor`, which also colours cluster outlines for mixed-colour clusters. *types*
+
+## New in 2.0
+
+- Clustering: `layoutOptions.clustering` for force-directed, `layoutOptions.clusterBy` for hierarchical (see [clustering](clustering.md)).
+- `onClusterClick` / `onClusterDoubleClick` / `onClusterRightClick` in `ClickInteraction` and `getHits(event, ['cluster'])`.
+- `minFps` / `maxFps` presentation targets and `layoutOptions.seedingMethod` for force-directed.