@cosmos.gl/graph 2.3.1 → 2.5.0

package/.eslintrc

@@ -13,6 +13,9 @@
     "unicorn"
   ],
   "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
   "rules": {
     "object-curly-spacing": ["error", "always"],
     "prefer-template": "error",
@@ -67,6 +70,64 @@
     "@typescript-eslint/member-ordering": "error",
     "@typescript-eslint/explicit-member-accessibility": "error",
     "@typescript-eslint/explicit-function-return-type": "error",
+    "@typescript-eslint/naming-convention": [
+      "error",
+      {
+        "selector": "default",
+        "format": ["camelCase"],
+        "leadingUnderscore": "allow",
+        "trailingUnderscore": "allow"
+      },
+      {
+        "selector": "import",
+        "format": ["camelCase", "PascalCase"]
+      },
+      {
+        "selector": "classProperty",
+        "format": ["camelCase", "UPPER_CASE"],
+        "leadingUnderscore": "allow",
+        "trailingUnderscore": "allow"
+      },
+      {
+        "selector": "classProperty",
+        "types": ["boolean"],
+        "format": ["PascalCase"],
+        "prefix": ["is", "should", "has", "can", "did", "will", "are"],
+        "leadingUnderscore": "allow",
+        "trailingUnderscore": "allow"
+      },
+      {
+        "selector": "function",
+        "format": ["camelCase", "PascalCase"],
+        "modifiers": ["exported"],
+        "leadingUnderscore": "allow",
+        "trailingUnderscore": "allow"
+      },
+      {
+        "selector": "variable",
+        "format": ["camelCase", "UPPER_CASE"],
+        "leadingUnderscore": "allow",
+        "trailingUnderscore": "allow"
+      },
+      {
+        "selector": "variable",
+        "modifiers": ["exported"],
+        "format": ["camelCase", "UPPER_CASE", "PascalCase"]
+      },
+      {
+        "selector": "typeLike",
+        "format": ["PascalCase"]
+      },
+      {
+        "selector": "enumMember",
+        "format": ["PascalCase"]
+      },
+      {
+        "selector": "property",
+        "leadingUnderscore": "allowSingleOrDouble",
+        "format": ["camelCase", "snake_case", "UPPER_CASE"]
+      }
+    ],
     "max-len": ["warn", { "code": 160, "comments": 160 }],
     "unicorn/filename-case": "error",
     "unicorn/no-for-loop": "error",

package/CHARTER.md

@@ -0,0 +1,69 @@
+# cosmos.gl Charter
+
+## **Section 0: Guiding Principles**
+
+**Mission:** Provide the web development community with a high-performance framework for visualizing network graphs and scatter plots.
+
+**Vision:** Deliver fast, robust, open-source data visualization tools that empower interactive, scalable analysis in the browser.
+
+**Values:**
+
+- **Performance First:** Prioritize speed and efficiency in every feature and implementation.  
+- **Accessibility:** Ensure the API is intuitive and the tooling easy to adopt, lowering barriers for developers.  
+- **Community:** Foster open collaboration, welcoming contributions and feedback.  
+- **Transparency:** Maintain clear documentation, benchmarks, and decision-making processes.
+
+## **Section 1: Scope**
+
+cosmos.gl is a browser-native, GPU-accelerated force-directed graph layout and rendering engine designed to visualize and interact with massive, complex datasets at scale. By leveraging WebGL, it delivers fast simulations and real-time rendering of millions of nodes and edges directly in the browser. cosmos.gl bridges the gap between high-performance data visualization and interactive web-based research workflows, serving developers, researchers, and analysts. Its value lies in unlocking scalable, explainable graph exploration for AI, biotech, finance, and data science stakeholders.
+
+### **1.1: In-scope**
+
+- GPU-accelerated graph algorithms  
+- WebGL- and WebGPU-based rendering of large-scale network graph and machine learning embeddings  
+- Browser-native integration with frontend tooling and workflows
+
+### **1.2: Out-of-Scope**
+
+- Server-side computation, backend data processing and pipelines
+- Native desktop or mobile applications (outside browser environment)
+- Direct integration with domain-specific tools
+
+## **Section 2: Relationship with OpenJS Foundation CPC**
+
+Technical leadership of the cosmos.gl project is delegated to the cosmos.gl Technical Steering Committee (TSC) by the OpenJS Cross Project Council (CPC). Amendments to this charter require approval from both the CPC, through its [decision-making process](https://github.com/openjs-foundation/cross-project-council/blob/master/CPC-CHARTER.md#section-9-decision-making), and the TSC.
+
+## **Section 3: Technical Steering Committee (TSC)**
+
+TSC members may attend meetings, participate in discussions, and vote on all matters before the TSC.
+
+TSC memberships are not time-limited. There is no maximum size of the TSC. 
+
+There is no specific set of requirements or qualifications for TSC membership beyond these rules. A TSC member can be removed from the TSC by voluntary resignation or by a standard TSC motion.
+
+The TSC shall meet regularly using tools that enable participation by the community. The meeting shall be directed by the TSC chairperson. Responsibility for directing individual meetings may be delegated by the TSC chairperson to any other TSC member. Minutes or an appropriate recording shall be taken and made available to the community through accessible public postings.
+
+TSC members are expected to regularly participate in TSC activities.
+
+The TSC chairperson is elected by a simple majority vote of all TSC members. The chairperson serves until they resign or are replaced by a TSC vote. Any TSC member may call for a vote at any time, provided the proposal is made in writing and shared with the full TSC. Votes may be held in meetings or asynchronously using any communication tool commonly used by the TSC.
+
+## **Section 4: Roles & Responsibilities**
+The roles and responsibilities of cosmos.gl's TSC are described in [GOVERNANCE.md](./GOVERNANCE.md).
+
+### **Section 4.1 Project Operations & Management**
+The Project Operations & Management processes are defined in [GOVERNANCE.md](./GOVERNANCE.md).
+
+### **Section 4.2: Decision-making, Voting, and/or Elections**
+
+Project decisions shall operate under a model of Lazy Consensus by default. The TSC shall define appropriate guidelines for implementing Lazy Consensus (e.g., notification periods, review windows) within the development process.
+
+When consensus cannot be reached, the TSC shall decide via public voting.
+
+Each vote presents the available options in a format that supports clear expression of member preferences—this may include polls, emoji reactions, checklists, or comparable methods. TSC members may vote for one or more options or abstain. Unless otherwise specified, the winning option is the one that receives the greatest support among participating members.
+
+For decisions involving three or more options, the TSC may optionally conduct pairwise comparisons between all candidates. In such cases, the winner is the candidate who secures a simple majority against every other candidate in head-to-head matchups (Condorcet winner). All votes are public, and voting activity may be adjusted until the close of the voting period.
+
+## **Section 5: Definitions**
+### **Agenda Item**
+
+An agenda item is a specific topic, proposal, or issue scheduled for discussion or decision during a TSC meeting. Examples include proposed technical changes, governance matters, or any subject requiring TSC review or input. Agenda items are published in advance to allow TSC members and the community to prepare for discussion or decision-making.

package/GOVERNANCE.md

@@ -0,0 +1,21 @@
+# cosmos.gl Governance Guidelines
+
+The [TSC Charter](./CHARTER.md) governs the operations of the TSC. All changes to the Charter need approval by the OpenJS Foundation Cross-Project Council (CPC).
+
+The TSC oversees all technical development in the cosmos.gl project, as long as it follows policies set by CPC, including:
+- Setting release dates.  
+- Release quality standards.  
+- Technical direction.  
+- Project governance and process.  
+- GitHub repository hosting.  
+- Conduct guidelines.  
+- Maintaining the list of additional collaborators.  
+- Development process and any coding standards.  
+- Mediating technical conflicts between collaborators or foundation projects.
+
+The TSC will define cosmos.gl project’s release vehicles.
+
+### **Project Operations & Management**
+The TSC will establish and maintain a development process for the cosmos.gl project. The development process will establish guidelines for how the developers and community will operate. It will, for example, establish appropriate timelines for TSC review (e.g. agenda items must be published at least a certain number of hours in advance of a TSC meeting).
+
+The TSC and entire technical community will follow any processes as may be specified by the OpenJS Foundation Board relating to the intake and license compliance review of contributions, including the OpenJS Foundation IP Policy.

package/dist/config.d.ts

@@ -74,6 +74,11 @@ export interface GraphConfigInterface {
      * Default value: `auto`
      */
     hoveredPointCursor?: string;
+    /**
+     * Cursor style to use when hovering over a link
+     * Default value: `auto`
+     */
+    hoveredLinkCursor?: string;
     /**
      * Turns ring rendering around a point on hover on / off
      * Default value: `false`
@@ -127,6 +132,19 @@ export interface GraphConfigInterface {
      * Default value: `1`
     */
     linkWidth?: number;
+    /**
+     * The color to use for links when they are hovered.
+     * This can be either a hex color string (e.g., '#ff3333') or an array of RGBA values
+     * in the format `[red, green, blue, alpha]` where each value is a number between 0 and 255.
+     * Default value: `undefined`
+     */
+    hoveredLinkColor?: string | [number, number, number, number];
+    /**
+     * Number of pixels to add to the link width when hovered.
+     * The hovered width is calculated as: originalWidth + hoveredLinkWidthIncrease
+     * Default value: `5`
+     */
+    hoveredLinkWidthIncrease?: number;
     /**
      * Scale factor for the link width.
      * Default value: `1`
@@ -289,9 +307,15 @@ export interface GraphConfigInterface {
     onSimulationPause?: () => void;
     /**
      * Callback function that will be called when the simulation is restarted.
+     * @deprecated Use `onSimulationUnpause` instead. This callback will be removed in a future version.
      * Default value: `undefined`
      */
     onSimulationRestart?: () => void;
+    /**
+     * Callback function that will be called when the simulation is unpaused.
+     * Default value: `undefined`
+     */
+    onSimulationUnpause?: () => void;
     /**
      * Callback function that will be called on every canvas click.
      * If clicked on a point, its index will be passed as the first argument,
@@ -300,6 +324,28 @@ export interface GraphConfigInterface {
      * Default value: `undefined`
      */
     onClick?: (index: number | undefined, pointPosition: [number, number] | undefined, event: MouseEvent) => void;
+    /**
+     * Callback function that will be called when a point is clicked.
+     * The point index will be passed as the first argument,
+     * position as the second argument and the corresponding mouse event as the third argument:
+     * `(index: number, pointPosition: [number, number], event: MouseEvent) => void`.
+     * Default value: `undefined`
+     */
+    onPointClick?: (index: number, pointPosition: [number, number], event: MouseEvent) => void;
+    /**
+     * Callback function that will be called when a link is clicked.
+     * The link index will be passed as the first argument and the corresponding mouse event as the second argument:
+     * `(linkIndex: number, event: MouseEvent) => void`.
+     * Default value: `undefined`
+     */
+    onLinkClick?: (linkIndex: number, event: MouseEvent) => void;
+    /**
+     * Callback function that will be called when the background (empty space) is clicked.
+     * The mouse event will be passed as the first argument:
+     * `(event: MouseEvent) => void`.
+     * Default value: `undefined`
+     */
+    onBackgroundClick?: (event: MouseEvent) => void;
     /**
      * Callback function that will be called when mouse movement happens.
      * If the mouse moves over a point, its index will be passed as the first argument,
@@ -326,6 +372,20 @@ export interface GraphConfigInterface {
      * Default value: `undefined`
      */
     onPointMouseOut?: (event: MouseEvent | D3ZoomEvent<HTMLCanvasElement, undefined> | D3DragEvent<HTMLCanvasElement, undefined, Hovered> | undefined) => void;
+    /**
+     * Callback function that will be called when the mouse moves over a link.
+     * The link index will be passed as the first argument:
+     * `(linkIndex: number) => void`.
+     * Default value: `undefined`
+     */
+    onLinkMouseOver?: (linkIndex: number) => void;
+    /**
+     * Callback function that will be called when the mouse moves out of a link.
+     * The event will be passed as the first argument:
+     * `(event: MouseEvent | D3ZoomEvent<HTMLCanvasElement, undefined> | D3DragEvent<HTMLCanvasElement, undefined, Hovered> | undefined) => void`.
+     * Default value: `undefined`
+     */
+    onLinkMouseOut?: (event: MouseEvent | D3ZoomEvent<HTMLCanvasElement, undefined> | D3DragEvent<HTMLCanvasElement, undefined, Hovered> | undefined) => void;
     /**
      * Callback function that will be called when zooming or panning starts.
      * First argument is a D3 Zoom Event and second indicates whether
@@ -491,6 +551,7 @@ export declare class GraphConfig implements GraphConfigInterface {
     pointOpacity: number;
     pointSizeScale: number;
     hoveredPointCursor: string;
+    hoveredLinkCursor: string;
     renderHoveredPointRing: boolean;
     hoveredPointRingColor: string;
     focusedPointRingColor: string;
@@ -500,6 +561,8 @@ export declare class GraphConfig implements GraphConfigInterface {
     linkGreyoutOpacity: number;
     linkWidth: number;
     linkWidthScale: number;
+    hoveredLinkColor: undefined;
+    hoveredLinkWidthIncrease: number;
     renderLinks: boolean;
     curvedLinks: boolean;
     curvedLinkSegments: number;
@@ -529,10 +592,16 @@ export declare class GraphConfig implements GraphConfigInterface {
     onSimulationEnd: GraphConfigInterface['onSimulationEnd'];
     onSimulationPause: GraphConfigInterface['onSimulationPause'];
     onSimulationRestart: GraphConfigInterface['onSimulationRestart'];
+    onSimulationUnpause: GraphConfigInterface['onSimulationUnpause'];
     onClick: GraphConfigInterface['onClick'];
+    onPointClick: GraphConfigInterface['onPointClick'];
+    onLinkClick: GraphConfigInterface['onLinkClick'];
+    onBackgroundClick: GraphConfigInterface['onBackgroundClick'];
     onMouseMove: GraphConfigInterface['onMouseMove'];
     onPointMouseOver: GraphConfigInterface['onPointMouseOver'];
     onPointMouseOut: GraphConfigInterface['onPointMouseOut'];
+    onLinkMouseOver: GraphConfigInterface['onLinkMouseOver'];
+    onLinkMouseOut: GraphConfigInterface['onLinkMouseOut'];
     onZoomStart: GraphConfigInterface['onZoomStart'];
     onZoom: GraphConfigInterface['onZoom'];
     onZoomEnd: GraphConfigInterface['onZoomEnd'];

package/dist/index.d.ts

@@ -24,12 +24,12 @@ export declare class Graph {
     private fpsMonitor;
     private currentEvent;
     /**
-     * The value of `_findHoveredPointExecutionCount` is incremented by 1 on each animation frame.
-     * When the counter reaches 2 (or more), it is reset to 0 and the `findHoveredPoint` method is executed.
+     * The value of `_findHoveredItemExecutionCount` is incremented by 1 on each animation frame.
+     * When the counter reaches MAX_HOVER_DETECTION_DELAY (default 4), it is reset to 0 and the `findHoveredPoint` or `findHoveredLine` method is executed.
      */
-    private _findHoveredPointExecutionCount;
+    private _findHoveredItemExecutionCount;
     /**
-     * If the mouse is not on the Canvas, the `findHoveredPoint` method will not be executed.
+     * If the mouse is not on the Canvas, the `findHoveredPoint` or `findHoveredLine` method will not be executed.
      */
     private _isMouseOnCanvas;
     /**
@@ -37,18 +37,20 @@ export declare class Graph {
      * */
     private _isFirstRenderAfterInit;
     private _fitViewOnInitTimeoutID;
-    private _needsPointPositionsUpdate;
-    private _needsPointColorUpdate;
-    private _needsPointSizeUpdate;
-    private _needsPointShapeUpdate;
-    private _needsLinksUpdate;
-    private _needsLinkColorUpdate;
-    private _needsLinkWidthUpdate;
-    private _needsLinkArrowUpdate;
-    private _needsPointClusterUpdate;
-    private _needsForceManyBodyUpdate;
-    private _needsForceLinkUpdate;
-    private _needsForceCenterUpdate;
+    private isPointPositionsUpdateNeeded;
+    private isPointColorUpdateNeeded;
+    private isPointSizeUpdateNeeded;
+    private isPointShapeUpdateNeeded;
+    private isPointImageIndicesUpdateNeeded;
+    private isLinksUpdateNeeded;
+    private isLinkColorUpdateNeeded;
+    private isLinkWidthUpdateNeeded;
+    private isLinkArrowUpdateNeeded;
+    private isPointClusterUpdateNeeded;
+    private isForceManyBodyUpdateNeeded;
+    private isForceLinkUpdateNeeded;
+    private isForceCenterUpdateNeeded;
+    private isPointImageSizesUpdateNeeded;
     private _isDestroyed;
     constructor(div: HTMLDivElement, config?: GraphConfigInterface);
     /**
@@ -108,10 +110,37 @@ export declare class Graph {
      *
      * @param {Float32Array} pointShapes - A Float32Array representing the shapes of points in the format [shape1, shape2, ..., shapen],
      * where `n` is the index of the point and each shape value corresponds to a PointShape enum:
-     * 0 = Circle, 1 = Square, 2 = Triangle, 3 = Diamond, 4 = Pentagon, 5 = Hexagon, 6 = Star, 7 = Cross.
+     * 0 = Circle, 1 = Square, 2 = Triangle, 3 = Diamond, 4 = Pentagon, 5 = Hexagon, 6 = Star, 7 = Cross, 8 = None.
      * Example: `new Float32Array([0, 1, 2])` sets the first point to Circle, the second point to Square, and the third point to Triangle.
+     * Images are rendered above shapes.
      */
     setPointShapes(pointShapes: Float32Array): void;
+    /**
+     * Sets the images for the graph points using ImageData objects.
+     * Images are rendered above shapes.
+     * To use images, provide image indices via setPointImageIndices().
+     *
+     * @param {ImageData[]} imageDataArray - Array of ImageData objects to use as point images.
+     * Example: `setImageData([imageData1, imageData2, imageData3])`
+     */
+    setImageData(imageDataArray: ImageData[]): void;
+    /**
+     * Sets which image each point should use from the images array.
+     * Images are rendered above shapes.
+     *
+     * @param {Float32Array} imageIndices - A Float32Array representing which image each point uses in the format [index1, index2, ..., indexn],
+     * where `n` is the index of the point and each value is an index into the images array provided to `setImageData`.
+     * Example: `new Float32Array([0, 1, 0])` sets the first point to use image 0, second point to use image 1, third point to use image 0.
+     */
+    setPointImageIndices(imageIndices: Float32Array): void;
+    /**
+     * Sets the sizes for the point images.
+     *
+     * @param {Float32Array} imageSizes - A Float32Array representing the sizes of point images in the format [size1, size2, ..., sizen],
+     * where `n` is the index of the point.
+     * Example: `new Float32Array([10, 20, 30])` sets the first image to size 10, the second image to size 20, and the third image to size 30.
+     */
+    setPointImageSizes(imageSizes: Float32Array): void;
     /**
      * Gets the current sizes of the graph points.
      *
@@ -367,9 +396,11 @@ export declare class Graph {
     trackPointPositionsByIndices(indices: number[]): void;
     /**
      * Get current X and Y coordinates of the tracked points.
-     * @returns A Map object where keys are the indices of the points and values are their corresponding X and Y coordinates in the [number, number] format.
+     * Do not mutate the returned map - it may affect future calls.
+     * @returns A ReadonlyMap where keys are point indices and values are their corresponding X and Y coordinates in the [number, number] format.
+     * @see trackPointPositionsByIndices To set which points should be tracked
      */
-    getTrackedPointPositionsMap(): Map<number, [number, number]>;
+    getTrackedPointPositionsMap(): ReadonlyMap<number, [number, number]>;
     /**
      * Get current X and Y coordinates of the tracked points as an array.
      * @returns Array of point positions in the format [x1, y1, x2, y2, ..., xn, yn] for tracked points only.
@@ -412,11 +443,19 @@ export declare class Graph {
      */
     start(alpha?: number): void;
     /**
-     * Pause the simulation.
+     * Pause the simulation. When paused, the simulation stops running
+     * and can be resumed using the unpause method.
      */
     pause(): void;
     /**
-     * Restart the simulation.
+     * Unpause the simulation. This method resumes a paused
+     * simulation and continues its execution.
+     */
+    unpause(): void;
+    /**
+     * Restart/Resume the simulation. This method unpauses a paused
+     * simulation and resumes its execution.
+     * @deprecated Use `unpause()` instead. This method will be removed in a future version.
      */
     restart(): void;
     /**
@@ -455,7 +494,9 @@ export declare class Graph {
     private resizeCanvas;
     private setZoomTransformByPointPositions;
     private updateZoomDragBehaviors;
+    private findHoveredItem;
     private findHoveredPoint;
+    private findHoveredLine;
     private updateCanvasCursor;
     private addAttribution;
 }