@loradb/lora-graph-canvas 0.10.0

package/LICENSE

@@ -0,0 +1,87 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             LoraDB, Inc.
+Licensed Work:        LoraDB
+Change Date:          2029-04-19
+Change License:       Apache License, Version 2.0
+
+Additional Use Grant: You may use, copy, modify, create derivative works of,
+                      distribute, and make production use of the Licensed Work
+                      for internal business purposes and non-production
+                      purposes, provided that you do not use the Licensed Work
+                      to offer, operate, or make available a database-as-a-
+                      service, hosted API, managed database platform, or any
+                      substantially similar hosted service for third parties.
+
+                      The Additional Use Grant does not permit using the
+                      Licensed Work to provide a commercial or non-commercial
+                      hosted service that allows third parties to access LoraDB
+                      functionality, including as part of a competing managed
+                      database platform, backend-as-a-service, application
+                      platform, developer platform, or resale offering.
+
+Business Source License
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or modified
+form from a third party, the terms and conditions set forth in this License
+apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+3. To specify a Change Date.
+4. Not to modify this License in any other way.

package/README.md

@@ -0,0 +1,191 @@
+# @loradb/lora-graph-canvas
+
+React graph canvas for LoraDB. One component, `<LoraGraphCanvas />`, that
+wraps `force-graph` (2D HTML5 canvas) and `3d-force-graph` (WebGL via
+Three.js). Switch between 2D and 3D at runtime without re-mounting your
+data, and use the built-in tool palette to build, edit, select, and
+delete nodes interactively.
+
+```tsx
+import { LoraGraphCanvas } from "@loradb/lora-graph-canvas";
+import "@loradb/lora-graph-canvas/styles.css";
+
+<LoraGraphCanvas
+  defaultData={{
+    nodes: [{ id: "a" }, { id: "b" }],
+    links: [{ source: "a", target: "b" }],
+  }}
+  nodeLabel="id"
+  nodeAutoColorBy="group"
+/>;
+```
+
+## Install
+
+```sh
+yarn add @loradb/lora-graph-canvas three
+# or
+npm install @loradb/lora-graph-canvas three
+```
+
+`three` is a required peer dependency — the package itself does not bundle
+Three.js, so 2D-only consumers can dedupe with the rest of the app's
+Three usage, and 3D consumers can pin a specific version.
+
+## Built-in tools
+
+The toolbar ships with twelve tools, controllable individually:
+
+| Tool         | Shortcut | What it does                                       |
+| ------------ | -------- | -------------------------------------------------- |
+| Select       | `V`      | Click / shift-click nodes to select them.          |
+| Pan          | `H`      | Pan-only cursor.                                   |
+| Add node     | `N`      | Click on the canvas to drop a node.                |
+| Add link     | `L`      | Click two nodes to connect them.                   |
+| Delete       | `⌫` / `⌦` | Delete the current selection (cascades links).     |
+| Fit          | `F`      | `zoomToFit` to the current graph bbox.             |
+| Zoom in/out  | `+` `-`  | Step the zoom level.                               |
+| Pause/Resume | —        | Stop / start the d3 simulation.                    |
+| Screenshot   | —        | Download a PNG of the canvas.                      |
+| Toggle 2D/3D | `3`      | Swap engines, preserving data and selection.       |
+
+```tsx
+// Pick a subset…
+<LoraGraphCanvas tools={["select", "add-node", "delete", "toggle-mode"]} />
+
+// …or hide the whole bar and drive everything from the ref:
+<LoraGraphCanvas tools={false} ref={ref} />
+```
+
+## Ref handle
+
+```tsx
+import { useRef } from "react";
+import {
+  LoraGraphCanvas,
+  type LoraGraphCanvasHandle,
+} from "@loradb/lora-graph-canvas";
+
+const ref = useRef<LoraGraphCanvasHandle>(null);
+
+ref.current?.addNode({ id: "x", label: "hello" });
+ref.current?.addLink({ source: "x", target: "y" });
+ref.current?.removeNode("x");        // also removes attached links
+ref.current?.fit(400, 40);
+ref.current?.setMode("3d");
+const blob = await ref.current?.screenshot();
+```
+
+Available methods: data (`getData`, `setData`, `addNode`, `addNodes`,
+`updateNode`, `removeNode`, `removeNodes`, `addLink`, `addLinks`,
+`removeLink`, `clear`); selection (`getSelection`, `setSelection`,
+`selectAll`, `clearSelection`); view (`getMode`, `setMode`, `fit`,
+`centerAt`, `zoom`, `zoomIn`, `zoomOut`); engine (`pause`, `resume`,
+`reheat`, `screenshot`); escape hatches (`engine2D`, `engine3D`).
+
+## Controlled vs uncontrolled
+
+```tsx
+// Uncontrolled — internal state owns the graph, host gets a notification:
+<LoraGraphCanvas defaultData={initialData} onDataChange={save} />
+
+// Controlled — host owns the graph:
+<LoraGraphCanvas data={dataFromState} onDataChange={setDataState} />
+```
+
+The same dichotomy applies to `mode` (`defaultMode` vs `mode`).
+
+## Theming
+
+The chrome (toolbar, context menu, tooltips) is driven by `--lgc-*` CSS
+variables. Override the ones you want either through the `theme` prop or
+by attaching CSS to the `.lora-graph-canvas` container. The engine's own
+canvas reads `backgroundColor` from a regular prop, independent of the
+theme.
+
+```tsx
+import { LoraGraphCanvas, darkTheme } from "@loradb/lora-graph-canvas";
+
+<LoraGraphCanvas
+  backgroundColor="#0e1014"
+  theme={{ ...darkTheme, accent: "#ff6699" }}
+/>;
+```
+
+Two presets are exported: `lightTheme` and `darkTheme`.
+
+## Performance knobs
+
+For large graphs, cap `cooldownTicks` (default ∞) and increase
+`warmupTicks` to spend more time computing layout off-screen before the
+first paint:
+
+```tsx
+<LoraGraphCanvas cooldownTicks={50} warmupTicks={20} />
+```
+
+For graphs above ~10k nodes, switch the layout engine in 3D mode:
+
+```tsx
+<LoraGraphCanvas mode="3d" forceEngine="ngraph" />
+```
+
+## Opt-in UX flags
+
+Each is a single boolean prop:
+
+| Prop | What it does |
+| --- | --- |
+| `focusOnClick` | Click a node → animated camera focus; click again to restore. |
+| `highlightNeighborsOnHover` | Hover a node → it + its neighbours light up in the accent color. Pair with `autoIndexNeighbors` so the component builds the neighbour index for you, or stash `_neighbors` / `_links` yourself. |
+| `autoIndexNeighbors` | After every data change, build `_neighbors` and `_links` arrays on each node — required by the highlight flag if you don't provide them. |
+| `collideNodes` | Inject `d3-force-3d`'s `forceCollide` so circles don't overlap. Pass a number to override the radius. |
+| `showGrid` | Faint background grid that adapts to the zoom level. 2D only. Pass `{ spacing, color }` to customise. |
+| `showLegend` | Bottom-left widget enumerating `nodeAutoColorBy` groups with a colour swatch; click a group to toggle its visibility (drives `nodeVisibility` automatically). |
+| `enableRename` | (Default true.) Double-click a node to rename it inline. Set false to suppress. |
+| `enableClipboard` | (Default true.) ⌘C / ⌘X / ⌘V keybindings + matching ref methods. |
+
+```tsx
+<LoraGraphCanvas
+  data={graph}
+  nodeAutoColorBy="group"
+  focusOnClick
+  highlightNeighborsOnHover
+  autoIndexNeighbors
+  collideNodes
+  showGrid
+  showLegend
+/>
+```
+
+## Animated particles for events
+
+The kapsule emits an animated particle along a link via `emitParticle`.
+Wire it through the ref to visualise events (data flow, message sent,
+etc.):
+
+```tsx
+const ref = useRef<LoraGraphCanvasHandle>(null);
+useEffect(() => {
+  socket.on("message", (msg) => {
+    const link = graph.links.find((l) => l.id === msg.linkId);
+    if (link) ref.current?.emitParticle(link);
+  });
+}, []);
+```
+
+## Custom forces
+
+Inject d3-force primitives through `d3Force(name, fn)`:
+
+```tsx
+import { forceRadial } from "d3-force-3d";
+
+ref.current?.d3Force("radial", forceRadial(200));
+ref.current?.reheat();
+```
+
+## License
+
+BUSL-1.1. Third-party attributions for `force-graph` and `3d-force-graph`
+(MIT, © Vasco Asturiano) live in `THIRD_PARTY.md`.

package/THIRD_PARTY.md

@@ -0,0 +1,40 @@
+# Third-party notices
+
+This package depends on the following open-source projects. Their license
+texts are reproduced below in full.
+
+## force-graph
+
+- Copyright (c) Vasco Asturiano
+- License: MIT
+- Source: https://github.com/vasturiano/force-graph
+
+```
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+```
+
+## 3d-force-graph
+
+- Copyright (c) Vasco Asturiano
+- License: MIT
+- Source: https://github.com/vasturiano/3d-force-graph
+
+The MIT license text above applies identically.

package/dist/LoraGraphCanvas.d.ts

@@ -0,0 +1,9 @@
+import { LinkObject, LoraGraphCanvasHandle, LoraGraphCanvasProps, NodeObject } from './types';
+declare function LoraGraphCanvasInner<N extends NodeObject = NodeObject, L extends LinkObject = LinkObject>(props: LoraGraphCanvasProps<N, L>, ref: React.Ref<LoraGraphCanvasHandle<N, L>>): import("react/jsx-runtime").JSX.Element;
+/** React component exporting both a default-instantiated and a generic
+ *  signature. Consumers can pass `<LoraGraphCanvas<MyNode, MyLink> ... />`
+ *  to constrain the node / link shape. */
+export declare const LoraGraphCanvas: <N extends NodeObject = NodeObject, L extends LinkObject = LinkObject>(props: LoraGraphCanvasProps<N, L> & {
+    ref?: React.Ref<LoraGraphCanvasHandle<N, L>>;
+}) => ReturnType<typeof LoraGraphCanvasInner>;
+export {};

package/dist/LoraGraphCanvas.stories.d.ts

@@ -0,0 +1,23 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { LoraGraphCanvas } from '.';
+declare const meta: Meta<typeof LoraGraphCanvas>;
+export default meta;
+type Story = StoryObj<typeof LoraGraphCanvas>;
+export declare const Basic: Story;
+export declare const ThreeDimensional: Story;
+export declare const ModeToggle: Story;
+export declare const BuildAGraphStory: Story;
+export declare const HeadlessStory: Story;
+export declare const LargeGraphStory: Story;
+export declare const StressGraphStory: Story;
+export declare const DagStoryStory: Story;
+export declare const Theming: Story;
+export declare const HighlightNeighbors: Story;
+export declare const ClickToFocus: Story;
+export declare const Grid: Story;
+export declare const Collide: Story;
+export declare const Legend: Story;
+export declare const Beeswarm: Story;
+export declare const EmitParticle: Story;
+export declare const RandomGraphStory: Story;
+export declare const LabeledStory: Story;

package/dist/engines/3d-force-graph/index.d.ts

@@ -0,0 +1 @@
+export { default } from './kapsule';

package/dist/engines/3d-force-graph/kapsule.d.ts

@@ -0,0 +1,12 @@
+import { WebGLRendererParameters } from 'three';
+import { KapsuleClassCtor } from '../../internal/kapsule';
+export interface ForceGraph3DConfigOptions {
+    controlType?: "trackball" | "orbit" | "fly";
+    rendererConfig?: WebGLRendererParameters;
+    /** Additional renderers (e.g. CSS2DRenderer for HTML overlays).
+     *  Typed loosely — three.js no longer exports a base `Renderer`
+     *  interface in newer revisions. */
+    extraRenderers?: unknown[];
+}
+declare const ForceGraph3D: KapsuleClassCtor;
+export default ForceGraph3D;

package/dist/engines/createEngineUnified.d.ts

@@ -0,0 +1,13 @@
+import { CreateEngineOptions, GraphEngine } from './types';
+import { GraphMode, LinkObject, LoraGraphCanvasProps, NodeObject } from '../types';
+export interface UnifiedEngine<N extends NodeObject = NodeObject, L extends LinkObject = LinkObject> extends GraphEngine<N, L> {
+    /** Switch presentation mode in place. Animates the camera + the
+     *  per-node z constraints; does not destroy the engine. */
+    setMode(mode: GraphMode, durationMs?: number): void;
+}
+export declare function createEngineUnified<N extends NodeObject, L extends LinkObject>(mount: HTMLElement, opts: CreateEngineOptions<N, L> & {
+    initialMode: GraphMode;
+}, handlerRef: {
+    current: LoraGraphCanvasProps<N, L>;
+}): UnifiedEngine<N, L>;
+export type EngineUnified = ReturnType<typeof createEngineUnified>;

package/dist/engines/propBindings.d.ts

@@ -0,0 +1,29 @@
+import { LinkObject, LoraGraphCanvasProps, NodeObject } from '../types';
+/** A kapsule prop the engine exposes as a chainable setter. */
+export interface PropBinding<P> {
+    /** Name of the prop on `LoraGraphCanvasProps` we read from. */
+    key: keyof LoraGraphCanvasProps<NodeObject, LinkObject>;
+    /** Name of the chainable setter on the engine instance. */
+    setter: string;
+    /** Whether this binding is supported in the current engine mode. */
+    supports: (mode: "2d" | "3d") => boolean;
+    /** Optional transformer applied before passing the value to the setter. */
+    transform?: (value: unknown, props: P) => unknown;
+}
+/** Bindings shared between 2D and 3D engines. Order doesn't matter; the
+ *  adapter just walks the list each render. */
+export declare const SHARED_BINDINGS: PropBinding<unknown>[];
+/** Walk the bindings, calling each engine setter for props whose value
+ *  changed (using Object.is). The engine instance is treated as a loose
+ *  record of chainable setters so this works for both kapsule types. */
+export declare function applyDiffedProps<N extends NodeObject, L extends LinkObject>(engine: Record<string, (value: unknown) => unknown>, props: LoraGraphCanvasProps<N, L>, prev: LoraGraphCanvasProps<N, L>, mode: "2d" | "3d"): void;
+/** Event-handler bindings. These are wired once at engine construction;
+ *  the React layer forwards through a stable trampoline so latest props
+ *  always win without re-binding. */
+export declare const EVENT_BINDINGS: readonly ["onNodeClick", "onNodeRightClick", "onNodeHover", "onNodeDrag", "onNodeDragEnd", "onLinkClick", "onLinkRightClick", "onLinkHover", "onBackgroundClick", "onBackgroundRightClick", "onEngineTick", "onEngineStop"];
+/** 2D-only event bindings (zoom + render-frame callbacks). The 3D
+ *  kapsule doesn't expose these — they're driven by Three.js controls
+ *  there. We wire them in the same trampoline way for consistency. */
+export declare const EVENT_BINDINGS_2D: readonly ["onZoom", "onZoomEnd", "onRenderFramePre", "onRenderFramePost"];
+export type EventName = (typeof EVENT_BINDINGS)[number];
+export type EventName2D = (typeof EVENT_BINDINGS_2D)[number];

package/dist/engines/rafAnim.d.ts

@@ -0,0 +1,13 @@
+/** A tiny RAF-driven tween we use instead of the kapsule's built-in
+ *  tween group. The kapsule's tweens live inside a private state
+ *  object — there's no public API for cancelling them once started.
+ *  Doing the animation ourselves lets us stop it the instant the
+ *  user interacts with the canvas.
+ *
+ *  Each `runAnim` returns a `cancel()` function; calling it freezes
+ *  the animation at the current frame (no further `step` invocations).
+ *  Returns null when running in an environment without
+ *  `requestAnimationFrame` (jsdom in unit tests). */
+export declare function runAnim(durationMs: number, step: (t: number) => void, onDone?: () => void): () => void;
+export declare function easeOutQuad(t: number): number;
+export declare function lerp(a: number, b: number, t: number): number;

package/dist/engines/types.d.ts

@@ -0,0 +1,86 @@
+import { GraphData, GraphMode, LinkObject, NodeObject, LoraGraphCanvasProps } from '../types';
+/** Camera state snapshot. The shape differs per mode so we can
+ *  faithfully restore in both 2D (pan + zoom) and 3D (position +
+ *  lookAt). */
+export type CameraState = {
+    mode: "2d";
+    x: number;
+    y: number;
+    k: number;
+} | {
+    mode: "3d";
+    x: number;
+    y: number;
+    z: number;
+    lookAt: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+/** Subset of the kapsule API both 2D and 3D engines implement. Each
+ *  adapter normalises naming so the React layer never has to special-case
+ *  the dimension. */
+export interface GraphEngine<N extends NodeObject = NodeObject, L extends LinkObject = LinkObject> {
+    mode: GraphMode;
+    setGraphData(data: GraphData<N, L>): void;
+    getGraphData(): GraphData<N, L>;
+    fit(durationMs?: number, padding?: number): void;
+    centerAt(x: number, y: number, z?: number, durationMs?: number): void;
+    zoom(scale: number, durationMs?: number): void;
+    getZoom(): number;
+    screen2Graph(x: number, y: number, distance?: number): {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    graph2Screen(x: number, y: number, z?: number): {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    getGraphBbox(): {
+        x: [number, number];
+        y: [number, number];
+        z?: [number, number];
+    };
+    pause(): void;
+    resume(): void;
+    reheat(): void;
+    resize(width: number, height: number): void;
+    /** Get / set / clear a d3-force by name. Pass `null` to remove. */
+    d3Force(name: string, fn?: unknown | null): unknown;
+    /** Emit a one-off animated particle along the given link. */
+    emitParticle(link: L): void;
+    /** Snap any in-flight camera tween (centerAt / zoom / cameraPosition)
+     *  to its current state. Used to interrupt a focus animation when
+     *  the user starts a new interaction. No-op when nothing is
+     *  animating. */
+    stopAnimation(): void;
+    /** Animate the camera so the given target point is centered, while
+     *  preserving the current viewing angle. In 3D the camera flies
+     *  along its current vector from the target so the user's orbit
+     *  is kept; in 2D it's a `centerAt` + `zoom`. */
+    focusOn(target: {
+        x: number;
+        y: number;
+        z?: number;
+    }, opts?: {
+        distance?: number;
+        zoom?: number;
+        durationMs?: number;
+    }): void;
+    /** Snapshot the current camera so it can be restored later. */
+    getCameraState(): CameraState;
+    /** Restore a snapshot produced by `getCameraState`. */
+    setCameraState(state: CameraState, durationMs?: number): void;
+    applyProps(props: LoraGraphCanvasProps<N, L>, prev: LoraGraphCanvasProps<N, L>): void;
+    getCanvasElement(): HTMLCanvasElement | null;
+    destroy(): void;
+}
+export interface CreateEngineOptions<N extends NodeObject = NodeObject, L extends LinkObject = LinkObject> {
+    initialProps: LoraGraphCanvasProps<N, L>;
+    initialData: GraphData<N, L>;
+    width: number;
+    height: number;
+}

package/dist/hooks/useAccessorOverrides.d.ts

@@ -0,0 +1,62 @@
+import { Accessor, GraphMode, LinkObject, NodeObject } from '../types';
+export type NodePointerAreaPaint<N extends NodeObject> = (node: N, color: string, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+export interface UseAccessorOverridesParams<N extends NodeObject, L extends LinkObject> {
+    mode: GraphMode;
+    accentColor: string;
+    nodeColor?: Accessor<string, N>;
+    linkColor?: Accessor<string, L>;
+    linkWidth?: Accessor<number, L>;
+    nodeVal?: Accessor<number, N>;
+    nodeRelSize?: number;
+    nodePointerAreaPaint?: NodePointerAreaPaint<N>;
+    nodeAutoColorBy?: Accessor<string | null, N>;
+    nodeVisibility?: Accessor<boolean, N>;
+    selectedNodeSet: ReadonlySet<string | number>;
+    selectedLinkSet: ReadonlySet<string | number>;
+    highlightNeighborsOnHover: boolean;
+    highlightedNodeIds: ReadonlySet<string | number>;
+    highlightedLinkIds: ReadonlySet<string | number>;
+    hoverNodeId: string | number | null;
+    /** Direct-link hover. Distinct from `highlightedLinkIds`, which
+     *  only fires when a node is hovered and its neighbour links light
+     *  up. When the user hovers a link itself, only `hoverLinkId` is
+     *  set — both signals need to flow into the size/colour wrappers
+     *  so the link bumps up on direct hover, not just node-neighbour
+     *  hover. */
+    hoverLinkId: string | number | null;
+    hiddenGroups: ReadonlySet<string>;
+}
+export interface AccessorOverrides<N extends NodeObject, L extends LinkObject> {
+    nodeColor: Accessor<string, N> | undefined;
+    linkColor: Accessor<string, L> | undefined;
+    linkWidth: Accessor<number, L> | undefined;
+    nodeVal: Accessor<number, N> | undefined;
+    nodePointerAreaPaint: NodePointerAreaPaint<N> | undefined;
+    nodeVisibility: ((node: N) => boolean) | undefined;
+}
+/** Wrap the host's color / width / value / visibility accessors so the
+ *  current selection + hover-highlight + legend-filter overlay on top
+ *  without losing the underlying styling.
+ *
+ *  Each wrapper is conditional in two ways:
+ *
+ *  1. When there's nothing to overlay (no selection, no hover, no
+ *     legend filter) we return the host's accessor *untouched*. The
+ *     kapsule never enters our closure on hot paths in that case.
+ *
+ *  2. When an overlay is active, the wrapper identity flips on every
+ *     selection/hover state change. This is REQUIRED — three-forcegraph's
+ *     link/node digest (see `three-forcegraph.mjs:1185`) only re-evaluates
+ *     accessors when one of its tracked props changes identity. Keeping
+ *     the wrapper "stable" through selection changes — as an earlier
+ *     iteration of this hook did — caused the kapsule to cache the colour
+ *     and width of whichever link the user first clicked and never update
+ *     them on subsequent clicks, despite the React state being correct.
+ *
+ *     The closure body still reads the latest state from a ref, but the
+ *     memo deps include every overlay signal so the identity flips with
+ *     each tick of the state machine. The kapsule's own internal digest
+ *     is smart enough to only rebuild geometries/materials whose value
+ *     actually changed (cheap on small per-click selection deltas), so
+ *     the cost of identity churn here is bounded. */
+export declare function useAccessorOverrides<N extends NodeObject, L extends LinkObject>(params: UseAccessorOverridesParams<N, L>): AccessorOverrides<N, L>;

package/dist/hooks/useAutoIndexNeighbors.d.ts

@@ -0,0 +1,6 @@
+import { GraphData, LinkObject, NodeObject } from '../types';
+/** When enabled, walk the graph once on every data change and stash
+ *  `_neighbors` (Node[]) and `_links` (Link[]) arrays on each node. The
+ *  hover-highlight code reads from these refs directly so the per-frame
+ *  work stays O(1). */
+export declare function useAutoIndexNeighbors<N extends NodeObject, L extends LinkObject>(enabled: boolean, data: GraphData<N, L>): void;

package/dist/hooks/useClickToleranceShim.d.ts

@@ -0,0 +1,46 @@
+export interface ClickToleranceShimOptions {
+    /** Distance in CSS pixels the cursor may travel from the press
+     *  position before the gesture is committed as a drag. */
+    tolerancePx?: number;
+    /** Milliseconds after `pointerdown` during which every move is
+     *  suppressed regardless of distance, so press-induced jitter never
+     *  promotes a click into a drag. */
+    pressGraceMs?: number;
+}
+/** Click-vs-drag tolerance shim.
+ *
+ *  The upstream kapsule (force-graph + 3d-force-graph) flips
+ *  `isPointerDragging` to true on the *first* pointermove after
+ *  pointerdown for any mouse event — even a 1px jitter — which then
+ *  suppresses the click / right-click handler on pointerup. That
+ *  makes background-click deselect, node selection, and right-click
+ *  context menu all feel fragile.
+ *
+ *  We add a movement dead-zone by intercepting pointer **and** mouse
+ *  move events at the window level in the capture phase. Two
+ *  independent thresholds combine to keep clicks from accidentally
+ *  becoming drags:
+ *
+ *    1. **Press-grace window** — for the first `pressGraceMs` after
+ *       `pointerdown`, every move is swallowed regardless of distance.
+ *       This covers the involuntary jitter spike that fires right
+ *       after the button physically engages, which on a HiDPI trackpad
+ *       can easily exceed 6–8px in a single event.
+ *    2. **Distance dead-zone** — past the grace window, moves within
+ *       `tolerancePx` of the press position are still swallowed. Once
+ *       the cursor crosses that radius the gesture commits to "drag"
+ *       and we stop intercepting, so pan / orbit / drag-node remain
+ *       snappy for the rest of the gesture.
+ *
+ *  Suppressing moves stops them propagating to:
+ *    - the kapsule's container-level `pointermove` listener (so its
+ *      `isPointerDragging` flag stays false and the click handler
+ *      still fires on `pointerup`);
+ *    - d3-zoom's `mousemove.zoom` listener on `window` (so a slight
+ *      pan doesn't shift a node under the cursor between pointerdown
+ *      and pointerup — that was the bug where clicking empty space to
+ *      deselect would silently toggle whichever node slid under the
+ *      cursor mid-gesture);
+ *    - Three.js OrbitControls in 3D (same idea — no camera nudge
+ *      during a click). */
+export declare function useClickToleranceShim(mount: HTMLElement | null, options?: number | ClickToleranceShimOptions): void;