@cosmos.gl/graph 3.0.0-beta.8 → 3.0.0-beta.9

package/README.md

@@ -31,7 +31,7 @@ npm install @cosmos.gl/graph
 
 Get the data, [configure](https://cosmosgl.github.io/graph/?path=/docs/configuration--docs) the graph and run the simulation:
 
-```javascript
+```ts
 import { Graph } from '@cosmos.gl/graph'
 
 const div = document.querySelector('div')
@@ -85,9 +85,13 @@ cosmos.gl v3.0 brings a new rendering engine, async initialization, and several
 - **Link sampling** — sample visible links on screen with `getSampledLinks()` and `getSampledLinkPositionsMap()` for rendering labels or overlays along links.
 - **Context menu support** — new callbacks for right-click interactions: `onContextMenu`, `onPointContextMenu`, `onLinkContextMenu`, `onBackgroundContextMenu`.
 - **Fit viewport to points** — `setZoomTransformByPointPositions()` zooms and pans to fit a set of points into view.
-- **Hover improvements** — `onPointMouseOver` now includes an `isSelected` parameter; hover correctly highlights the topmost point when points overlap.
+- **Config-driven highlighting** — imperative selection methods replaced by `highlightedPointIndices`, `highlightedLinkIndices`, and `outlinedPointIndices` config properties. Points and links are highlighted independently. Focused points are rendered with rings via `focusedPointIndex`; focused links are rendered wider via `focusedLinkIndex`. New `findPointsInRect()`, `findPointsInPolygon()`, `getNeighboringPointIndices()`, `getConnectedLinkIndices()`, and `getConnectedPointIndices()` methods.
+- **Hover improvements** — `onPointMouseOver` now includes `isHighlighted` and `isOutlined` parameters; hover correctly highlights the topmost point when points overlap.
 - **Config API changes** — `setConfig()` now resets all values to defaults before applying; use the new `setConfigPartial()` to update individual properties without resetting the rest.
-- **Init-only config fields** — `enableSimulation`, `initialZoomLevel`, `randomSeed`, and `attribution` can only be set during initialization and are preserved across config updates.
+- **Init-only config fields** — `initialZoomLevel`, `randomSeed`, and `attribution` can only be set during initialization and are preserved across config updates.
+- **Runtime simulation toggle** — `enableSimulation` can now be changed at runtime via `setConfig()` or `setConfigPartial()`.
+- **GPU transitions** — point positions, point colors/sizes, and link colors/widths now animate by default (`transitionDuration: 800`, `transitionEasing: TransitionEasing.CubicInOut`). Use `transitionDuration: 0` to keep snap updates.
+- **Transition callbacks** — use `onTransitionStart`, `onTransition`, and `onTransitionEnd` to track transition lifecycle and progress.
 - **Default point shape** — new `pointDefaultShape` config property lets you set the fallback shape for all points when no per-point shapes are provided. Accepts a `PointShape` enum value (e.g., `PointShape.Star`), a plain number (e.g., `6`), or a numeric string (e.g., `"6"`).
 - **Exported defaults** — `defaultConfigValues` is now part of the public API.
 - **Optimized hover detection** — skips GPU work when the mouse hasn't moved.
@@ -111,7 +115,7 @@ Check the [Migration Guide](./migration-notes.md) for upgrading from v1.
 
 ### Examples
 
-- [Basic Set-Up](https://cosmosgl.github.io/graph/?path=/story/examples-beginners--basic-set-up)
+- [Actions](https://cosmosgl.github.io/graph/?path=/story/examples-beginners--actions)
 
 ---
 

package/dist/config.d.ts

@@ -2,14 +2,44 @@ import { D3ZoomEvent } from 'd3-zoom';
 import { D3DragEvent } from 'd3-drag';
 import { Hovered } from './modules/Store';
 import { PointShape } from './modules/GraphData';
+import { TransitionEasing } from './modules/Transition';
 export interface GraphConfigInterface {
     /**
      * If set to `false`, the simulation will not run.
-     * This property will be applied only on component initialization and it
-     * can't be changed using the `setConfig` or `setConfigPartial` methods.
+     * Can be toggled at runtime using `setConfig` or `setConfigPartial`.
      * Default value: `true`
      */
     enableSimulation: boolean;
+    /**
+     * Transition duration in milliseconds.
+     * Default value: `800`
+     * @note When a position transition is triggered via `setPointPositions()`, the simulation
+     * is automatically paused for the duration and remains paused afterwards so forces do not
+     * pull nodes away from the target layout. Call `unpause()` to resume the simulation explicitly.
+     */
+    transitionDuration: number;
+    /**
+     * Easing curve for transitions.
+     * Default value: `TransitionEasing.CubicInOut`
+     */
+    transitionEasing: TransitionEasing | `${TransitionEasing}`;
+    /**
+     * Callback function that will be called when a transition starts.
+     * Default value: `undefined`
+     */
+    onTransitionStart?: () => void;
+    /**
+     * Callback function that will be called on every transition frame.
+     * The `progress` value ranges from 0 to 1.
+     * Default value: `undefined`
+     */
+    onTransition?: (progress: number) => void;
+    /**
+     * Callback function that will be called when a transition ends.
+     * `interrupted` is `true` when a transition was replaced or aborted before completion.
+     * Default value: `undefined`
+     */
+    onTransitionEnd?: (interrupted: boolean) => void;
     /**
      * Canvas background color.
      * Can be either a hex color string (e.g., '#b3b3b3') or an array of RGBA values.
@@ -30,7 +60,7 @@ export interface GraphConfigInterface {
      */
     pointDefaultColor: string | [number, number, number, number];
     /**
-     * The color to use for points when they are greyed out (when selection is active).
+     * The color to use for points when they are greyed out (when highlighting is active).
      * This can be either a hex color string (e.g., '#b3b3b3') or an array of RGBA values
      * in the format `[red, green, blue, alpha]` where each value is a number between 0 and 1.
      *
@@ -44,12 +74,9 @@ export interface GraphConfigInterface {
      */
     pointGreyoutColor?: string | [number, number, number, number];
     /**
-     * Opacity multiplier for points when they are greyed out (when selection is active).
-     * Values range from 0 (completely transparent) to 1 (fully opaque).
-     *
-     * When defined, this value is multiplied with the point's final alpha instead of the
-     * default `pointOpacity`. When `undefined`, greyed-out points use `pointOpacity` as their multiplier.
-     *
+     * Opacity of greyed-out points when highlighting is active.
+     * Range: 0 (fully transparent) to 1 (fully opaque).
+     * When set, used instead of `pointOpacity` for greyed-out points.
      * Default value: `undefined`
      */
     pointGreyoutOpacity?: number;
@@ -106,11 +133,32 @@ export interface GraphConfigInterface {
      */
     focusedPointRingColor: string | [number, number, number, number];
     /**
-     * Set focus on a point by index.  A ring will be highlighted around the focused point.
+     * Set focus on a point by index. A ring will be rendered around the focused point.
+     * The focused ring is larger than outline rings to create a clear visual hierarchy.
      * When set to `undefined`, no point is focused.
      * Default value: `undefined`
      */
     focusedPointIndex?: number;
+    /**
+     * Array of point indices to highlight. When set, all points NOT in this array will be
+     * greyed out. An empty array `[]` activates highlighting with all points greyed out.
+     * Set to `undefined` to clear highlighting and show all points normally.
+     * Default value: `undefined`
+     */
+    highlightedPointIndices?: number[];
+    /**
+     * Array of point indices to draw an outline ring around. The outline ring is a circle
+     * rendered around the point regardless of the point's shape. When a point is both
+     * outlined and greyed out (not highlighted), the ring color is dimmed to match.
+     * Default value: `undefined`
+     */
+    outlinedPointIndices?: number[];
+    /**
+     * Color of the outline ring drawn around outlined points.
+     * Can be either a hex color string (e.g., '#b3b3b3') or an array of RGBA values.
+     * Default value: `'white'`
+     */
+    outlinedPointRingColor: string | [number, number, number, number];
     /**
      * Turns link rendering on / off.
      * Default value: `true`
@@ -132,10 +180,30 @@ export interface GraphConfigInterface {
      */
     linkOpacity: number;
     /**
-     * Greyed out link opacity value when the selection is active.
+     * Greyed-out link opacity value when link highlighting is active.
      * Default value: `0.1`
     */
     linkGreyoutOpacity: number;
+    /**
+     * Array of link indices to highlight. When set, all links NOT in this array will be
+     * greyed out. An empty array `[]` activates highlighting with all links greyed out.
+     * Set to `undefined` to clear highlighting and show all links normally.
+     * Link highlighting is independent of point highlighting.
+     * Default value: `undefined`
+     */
+    highlightedLinkIndices?: number[];
+    /**
+     * Set focus on a link by index. The focused link will be rendered with extra width.
+     * When set to `undefined`, no link is focused.
+     * Default value: `undefined`
+     */
+    focusedLinkIndex?: number;
+    /**
+     * Number of pixels to add to the link width when focused.
+     * The focused width is calculated as: originalWidth + focusedLinkWidthIncrease
+     * Default value: `5`
+     */
+    focusedLinkWidthIncrease: number;
     /**
      * The default width value to use for links when no link widths are provided or if the width value in the array is `undefined` or `null`.
      * Default value: `1`
@@ -377,12 +445,13 @@ export interface GraphConfigInterface {
      * Callback function that will be called when a point appears under the mouse
      * as a result of a mouse event, zooming and panning, or movement of points.
      * The point index will be passed as the first argument, position as the second argument,
-     * the corresponding mouse event or D3's zoom event as the third argument, and whether
-     * the hovered point is selected as the fourth argument:
-     * `(index: number, pointPosition: [number, number], event: MouseEvent | D3DragEvent<HTMLCanvasElement, undefined, Hovered> | D3ZoomEvent<HTMLCanvasElement, undefined> | undefined, isSelected: boolean) => void`.
+     * the corresponding mouse event or D3's zoom event as the third argument,
+     * whether the hovered point is highlighted as the fourth argument,
+     * and whether the hovered point is outlined as the fifth argument:
+     * `(index, pointPosition, event, isHighlighted, isOutlined) => void`.
      * Default value: `undefined`
      */
-    onPointMouseOver?: (index: number, pointPosition: [number, number], event: MouseEvent | D3DragEvent<HTMLCanvasElement, undefined, Hovered> | D3ZoomEvent<HTMLCanvasElement, undefined> | undefined, isSelected: boolean) => void;
+    onPointMouseOver?: (index: number, pointPosition: [number, number], event: MouseEvent | D3DragEvent<HTMLCanvasElement, undefined, Hovered> | D3ZoomEvent<HTMLCanvasElement, undefined> | undefined, isHighlighted: boolean, isOutlined: boolean) => void;
     /**
      * Callback function that will be called when a point is no longer underneath
      * the mouse pointer because of a mouse event, zoom/pan event, or movement of points.
@@ -591,22 +660,32 @@ export type Complete<T> = {
  * to their defaults, not retain their previous values.
  */
 export type GraphConfig = Partial<GraphConfigInterface>;
-/** Returns a fresh copy of `defaultConfigValues` with arrays cloned to prevent shared references. */
+/**
+ * Returns a fresh copy of `defaultConfigValues` with arrays cloned so each Graph instance
+ * gets its own copy rather than sharing array references with it.
+ * `defaultConfigValues` is a module-level object — one instance shared across the entire codebase.
+ * Called at construction time to initialise `Graph.config`, and via `resetConfigToDefaults` on every `setConfig()` call.
+ */
 export declare function createDefaultConfig(): GraphConfigInterface;
 /**
  * Resets the config object to default values in place, preserving the object reference
  * so that modules (Zoom, Store, etc.) that hold a reference to it stay in sync.
+ * Called at the start of `setConfig()` to wipe previous values before applying the new ones.
  */
 export declare function resetConfigToDefaults(target: GraphConfigInterface): void;
 /**
- * Applies only the provided `source` values onto `target`, leaving all other
- * properties unchanged.
+ * Applies `source` values onto `target` in place, leaving absent keys unchanged.
+ *
+ * Mutates in place rather than returning a new object, because multiple modules
+ * (Zoom, Store, etc.) hold a reference to the same config object and need to
+ * see updates immediately.
  *
- * Mutates `target` in place (via `Object.assign`) rather than replacing it,
- * because multiple modules (Zoom, Store, etc.) hold a reference to the same config object.
+ * Called in three places:
+ * - Constructor: applies the optional initial config on top of defaults.
+ * - `setConfig()`: applies a full replacement after `resetConfigToDefaults`.
+ * - `setConfigPartial()`: with `useDefaultsForUndefined = true`, so explicit
+ *   `undefined` values reset that property to its default.
  *
- * - When `useDefaultsForUndefined` is `false` (default): explicit `undefined` values in `source` are skipped.
- * - When `useDefaultsForUndefined` is `true`: explicit `undefined` values are replaced with their defaults.
- * - Array values are shallow-cloned to prevent shared references.
+ * Arrays from `source` are stored by reference — callers must not mutate them after passing.
  */
 export declare function applyConfig(target: GraphConfigInterface, source: GraphConfig, useDefaultsForUndefined?: boolean): void;

package/dist/helper.d.ts

@@ -47,6 +47,11 @@ export declare function rgbToBrightness(r: number, g: number, b: number): number
  * @note Cosmos currently supports WebGL only; support for other device types will be added later.
  */
 export declare function readPixels(device: Device, fbo: Framebuffer, sourceX?: number, sourceY?: number, sourceWidth?: number, sourceHeight?: number): Float32Array;
+/**
+ * Extracts point indices from a pixel readback buffer.
+ * Every 4th value (R channel) is checked — non-zero means the point at that index was found.
+ */
+export declare function extractIndicesFromPixels(pixels: Float32Array): number[];
 /**
  * Returns the maximum point size supported by the device, scaled by pixel ratio.
  * For WebGL devices, reads the limit from the context; for other device types, uses MAX_POINT_SIZE from Store.

package/dist/index.d.ts

@@ -34,6 +34,7 @@ export declare class Graph {
     private forceMouse;
     private clusters;
     private zoomInstance;
+    private transition;
     private dragInstance;
     private fpsMonitor;
     private currentEvent;
@@ -128,6 +129,8 @@ export declare class Graph {
      * @param {boolean | undefined} dontRescale - For this call only, don't rescale the points.
      *   - `true`: Don't rescale.
      *   - `false` or `undefined` (default): Use the behavior defined by `config.rescalePositions`.
+     * @note If `transitionDuration > 0` and the simulation is running, the simulation is automatically
+     * paused for the transition and remains paused afterwards. Call `unpause()` to resume it.
      */
     setPointPositions(pointPositions: Float32Array, dontRescale?: boolean | undefined): void;
     /**
@@ -385,56 +388,47 @@ export declare class Graph {
      */
     setZoomTransformByPointPositions(positions: Float32Array, duration?: number, scale?: number, padding?: number, enableSimulation?: boolean): void;
     /**
-     * Get points indices inside a rectangular area.
-     * @param selection - Array of two corner points `[[left, top], [right, bottom]]`.
-     * The `left` and `right` coordinates should be from 0 to the width of the canvas.
-     * The `top` and `bottom` coordinates should be from 0 to the height of the canvas.
-     * @returns A Float32Array containing the indices of points inside a rectangular area.
+     * Find point indices inside a rectangular area.
+     *
+     * **Important:** This method is synchronous and must only be called when the graph is ready.
+     * Ensure `await graph.ready` has resolved (or use the result inside `graph.ready.then(...)`) before
+     * calling. If called before initialization completes, returns an empty array.
+     *
+     * @param rect - Array of two corner points `[[left, top], [right, bottom]]`.
+     * The coordinates should be from 0 to the width/height of the canvas.
+     * @returns Array of point indices inside the rectangle.
      */
-    getPointsInRect(selection: [[number, number], [number, number]]): Float32Array;
+    findPointsInRect(rect: [[number, number], [number, number]]): number[];
     /**
-     * Get points indices inside a polygon area.
-     * @param polygonPath - Array of points `[[x1, y1], [x2, y2], ..., [xn, yn]]` that defines the polygon.
-     * The coordinates should be from 0 to the width/height of the canvas.
-     * @returns A Float32Array containing the indices of points inside the polygon area.
-     */
-    getPointsInPolygon(polygonPath: [number, number][]): Float32Array;
-    /** Select points inside a rectangular area.
-     * @param selection - Array of two corner points `[[left, top], [right, bottom]]`.
-     * The `left` and `right` coordinates should be from 0 to the width of the canvas.
-     * The `top` and `bottom` coordinates should be from 0 to the height of the canvas. */
-    selectPointsInRect(selection: [[number, number], [number, number]] | null): void;
-    /** Select points inside a polygon area.
+     * Find point indices inside a polygon area.
+     *
+     * **Important:** This method is synchronous and must only be called when the graph is ready.
+     * Ensure `await graph.ready` has resolved (or use the result inside `graph.ready.then(...)`) before
+     * calling. If called before initialization completes, returns an empty array.
+     *
      * @param polygonPath - Array of points `[[x1, y1], [x2, y2], ..., [xn, yn]]` that defines the polygon.
      * The coordinates should be from 0 to the width/height of the canvas.
-     * Set to null to clear selection. */
-    selectPointsInPolygon(polygonPath: [number, number][] | null): void;
-    /**
-     * Select a point by index. If you want the adjacent points to get selected too, provide `true` as the second argument.
-     * @param index The index of the point in the array of points.
-     * @param selectAdjacentPoints When set to `true`, selects adjacent points (`false` by default).
+     * @returns Array of point indices inside the polygon.
      */
-    selectPointByIndex(index: number, selectAdjacentPoints?: boolean): void;
+    findPointsInPolygon(polygonPath: [number, number][]): number[];
     /**
-     * Select multiples points by their indices.
-     * @param indices Array of points indices.
+     * Get point indices that are neighbors of the given point(s) — connected by a link in either direction.
+     * @param pointIndices A single point index or an array of point indices.
+     * @returns Deduplicated array of neighboring point indices.
      */
-    selectPointsByIndices(indices?: (number | undefined)[] | null): void;
+    getNeighboringPointIndices(pointIndices: number | number[]): number[];
     /**
-     * Unselect all points.
+     * Get link indices where both endpoints are within the given point(s).
+     * @param pointIndices A single point index or an array of point indices.
+     * @returns Deduplicated array of link indices connecting points within the provided set.
      */
-    unselectPoints(): void;
+    getConnectedLinkIndices(pointIndices: number | number[]): number[];
     /**
-     * Get indices of points that are currently selected.
-     * @returns Array of selected indices of points.
+     * Get point indices at the endpoints of the given link(s).
+     * @param linkIndices A single link index or an array of link indices.
+     * @returns Deduplicated array of point indices at the ends of the provided links.
      */
-    getSelectedIndices(): number[] | null;
-    /**
-     * Get indices that are adjacent to a specific point by its index.
-     * @param index Index of the point.
-     * @returns Array of adjacent indices.
-     */
-    getAdjacentIndices(index: number): number[] | undefined;
+    getConnectedPointIndices(linkIndices: number | number[]): number[];
     /**
      * Converts the X and Y point coordinates from the space coordinate system to the screen coordinate system.
      * @param spacePosition Array of x and y coordinates in the space coordinate system.
@@ -528,6 +522,9 @@ export declare class Graph {
     /**
      * Start the simulation.
      * This only controls the simulation state, not rendering.
+     * If the simulation is already running, calling `start(alpha)` reheats it by
+     * resetting `alpha` and `simulationProgress` without firing
+     * `onSimulationStart` again.
      * @param alpha Value from 0 to 1. The higher the value, the more initial energy the simulation will get.
      */
     start(alpha?: number): void;
@@ -575,15 +572,20 @@ export declare class Graph {
      */
     pair(pointPositions: number[]): [number, number][];
     /**
-     * Restores init-only fields (`enableSimulation`, `initialZoomLevel`, `randomSeed`, `attribution`)
+     * Restores init-only fields (`initialZoomLevel`, `randomSeed`, `attribution`)
      * to their pre-update values, preventing runtime changes via setConfig/setConfigPartial.
      */
     private preserveInitOnlyFields;
+    private getFitViewPositions;
     /**
      * Compares the previous config snapshot with the current `this.config` and
      * applies any necessary side effects (updating renderers, store, behaviors, etc.).
      */
     private updateStateFromConfig;
+    /**
+     * Applies `enableSimulation` lifecycle changes triggered by config updates.
+     */
+    private applyEnableSimulationConfigChange;
     /**
      * Ensures device is initialized before executing a method.
      * If device is not ready, queues the method to run after initialization.
@@ -623,6 +625,8 @@ export declare class Graph {
      */
     private runSimulationStep;
     private initPrograms;
+    private ensureSimulationModules;
+    private destroySimulationModules;
     /**
      * The rendering loop - schedules itself to run continuously
      */
@@ -649,12 +653,15 @@ export declare class Graph {
     private resizeCanvas;
     private updateZoomDragBehaviors;
     private findHoveredItem;
+    /** Detect hovered point and update store state. Returns flags for deferred callback firing. */
     private findHoveredPoint;
+    /** Detect hovered link and update store state. Returns flags for deferred callback firing. */
     private findHoveredLine;
     private updateCanvasCursor;
     private addAttribution;
 }
 export type { GraphConfig } from './config';
 export { PointShape } from './modules/GraphData';
+export { TransitionEasing } from './modules/Transition';
 export * from './variables';
 export * from './helper';