@cosmos.gl/graph 2.7.0-beta.0 → 2.7.0-beta.2

package/dist/{config.d.ts → src/config.d.ts}

@@ -27,13 +27,15 @@ export interface GraphConfigInterface {
      * in the format `[red, green, blue, alpha]` where each value is a number between 0 and 255.
      * Default value: '#b3b3b3'
      */
+    pointDefaultColor?: string | [number, number, number, number];
+    /** @deprecated Use `pointDefaultColor` instead */
     pointColor?: string | [number, number, number, number];
     /**
      * The color to use for points when they are greyed out (when selection 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 255.
      *
-     * If not provided, the color will be the same as the `pointColor`,
+     * If not provided, the color will be the same as the point's original color,
      * but darkened or lightened depending on the background color.
      *
      * If `pointGreyoutOpacity` is also defined, it will override the alpha/opacity component
@@ -56,6 +58,8 @@ export interface GraphConfigInterface {
      * if the size value in the array is `undefined` or `null`.
      * Default value: `4`
     */
+    pointDefaultSize?: number;
+    /** @deprecated Use `pointDefaultSize` instead */
     pointSize?: number;
     /**
      * Universal opacity value applied to all points.
@@ -114,6 +118,8 @@ export interface GraphConfigInterface {
      * in the format `[red, green, blue, alpha]` where each value is a number between 0 and 255.
      * Default value: '#666666'
      */
+    linkDefaultColor?: string | [number, number, number, number];
+    /** @deprecated Use `linkDefaultColor` instead */
     linkColor?: string | [number, number, number, number];
     /**
      * Universal opacity value applied to all links.
@@ -131,6 +137,8 @@ export interface GraphConfigInterface {
      * 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`
     */
+    linkDefaultWidth?: number;
+    /** @deprecated Use `linkDefaultWidth` instead */
     linkWidth?: number;
     /**
      * The color to use for links when they are hovered.
@@ -181,6 +189,8 @@ export interface GraphConfigInterface {
      * The default link arrow value that controls whether or not to display link arrows.
      * Default value: `false`
      */
+    linkDefaultArrows?: boolean;
+    /** @deprecated Use `linkDefaultArrows` instead */
     linkArrows?: boolean;
     /**
      * Scale factor for the link arrows size.
@@ -203,13 +213,6 @@ export interface GraphConfigInterface {
      * Default value: `0.25`
      */
     linkVisibilityMinTransparency?: number;
-    /**
-     * Use the classic quadtree algorithm for the Many-Body force.
-     * This property will be applied only on component initialization and it
-     * can't be changed using the `setConfig` method.
-     * Default value: `false`
-     */
-    useClassicQuadtree?: boolean;
     /**
      * Decay coefficient. Use smaller values if you want the simulation to "cool down" slower.
      * Default value: `5000`
@@ -232,16 +235,9 @@ export interface GraphConfigInterface {
     simulationRepulsion?: number;
     /**
      * Decreases / increases the detalization of the Many-Body force calculations.
-     * When `useClassicQuadtree` is set to `true`, this property corresponds to the Barnes–Hut approximation criterion.
      * Default value: `1.15`
      */
     simulationRepulsionTheta?: number;
-    /**
-     * Barnes–Hut approximation depth.
-     * Can only be used when `useClassicQuadtree` is set `true`.
-     * Default value: `12`
-     */
-    simulationRepulsionQuadtreeLevels?: number;
     /**
      * Link spring force coefficient.
      * Default value: `1`
@@ -437,10 +433,8 @@ export interface GraphConfigInterface {
      */
     showFPSMonitor?: boolean;
     /**
-     * Pixel ratio for the canvas. Controls the resolution of the drawing buffer.
-     * - Higher values use more GPU memory but provide better quality on high-DPI displays
-     * - If not provided, uses `window.devicePixelRatio` or falls back to `2`
-     * Default value: `typeof window !== 'undefined' ? window.devicePixelRatio || 2 : 2`
+     * Pixel ratio for the canvas. Higher values use more GPU memory but provide better quality on high-DPI displays.
+     * Default value: `window.devicePixelRatio || 2`
      */
     pixelRatio?: number;
     /**
@@ -547,9 +541,11 @@ export declare class GraphConfig implements GraphConfigInterface {
     backgroundColor: string;
     spaceSize: number;
     pointColor: string;
+    pointDefaultColor: undefined;
     pointGreyoutOpacity: undefined;
     pointGreyoutColor: undefined;
     pointSize: number;
+    pointDefaultSize: undefined;
     pointOpacity: number;
     pointSizeScale: number;
     hoveredPointCursor: string;
@@ -559,9 +555,11 @@ export declare class GraphConfig implements GraphConfigInterface {
     focusedPointRingColor: string;
     focusedPointIndex: undefined;
     linkColor: string;
+    linkDefaultColor: undefined;
     linkOpacity: number;
     linkGreyoutOpacity: number;
     linkWidth: number;
+    linkDefaultWidth: undefined;
     linkWidthScale: number;
     hoveredLinkColor: undefined;
     hoveredLinkWidthIncrease: number;
@@ -571,17 +569,16 @@ export declare class GraphConfig implements GraphConfigInterface {
     curvedLinkWeight: number;
     curvedLinkControlPointDistance: number;
     linkArrows: boolean;
+    linkDefaultArrows: undefined;
     linkArrowsSizeScale: number;
     scaleLinksOnZoom: boolean;
     linkVisibilityDistanceRange: number[];
     linkVisibilityMinTransparency: number;
-    useClassicQuadtree: boolean;
     simulationDecay: number;
     simulationGravity: number;
     simulationCenter: number;
     simulationRepulsion: number;
     simulationRepulsionTheta: number;
-    simulationRepulsionQuadtreeLevels: number;
     simulationLinkSpring: number;
     simulationLinkDistance: number;
     simulationLinkDistRandomVariationRange: number[];

package/dist/{index.d.ts → src/index.d.ts}

@@ -1,3 +1,4 @@
+import { Device } from '@luma.gl/core';
 import { GraphConfig, GraphConfigInterface } from './config';
 import { GraphData } from './modules/GraphData';
 export declare class Graph {
@@ -53,7 +54,7 @@ export declare class Graph {
     private isForceCenterUpdateNeeded;
     private isPointImageSizesUpdateNeeded;
     private _isDestroyed;
-    constructor(div: HTMLDivElement, config?: GraphConfigInterface);
+    constructor(div: HTMLDivElement, config?: GraphConfigInterface, devicePromise?: Promise<Device>);
     /**
      * Returns the current simulation progress
      */
@@ -239,11 +240,31 @@ export declare class Graph {
      */
     setPointClusterStrength(clusterStrength: Float32Array): void;
     /**
-     * Renders the graph.
+     * Sets which points are pinned (fixed) in position.
      *
-     * @param {number} [simulationAlpha] - Optional value between 0 and 1
-     * that controls the initial energy of the simulation.The higher the value,
-     * the more initial energy the simulation will get. Zero value stops the simulation.
+     * Pinned points:
+     * - Do not move due to physics forces (gravity, repulsion, link forces, etc.)
+     * - Still participate in force calculations (other nodes are attracted to/repelled by them)
+     * - Can still be dragged by the user if `enableDrag` is true
+     *
+     * @param {number[] | null} pinnedIndices - Array of point indices to pin. Set to `[]` or `null` to unpin all points.
+     * @example
+     *   // Pin points 0 and 5
+     *   graph.setPinnedPoints([0, 5])
+     *
+     *   // Unpin all points
+     *   graph.setPinnedPoints([])
+     *   graph.setPinnedPoints(null)
+     */
+    setPinnedPoints(pinnedIndices: number[] | null): void;
+    /**
+     * Renders the graph and starts rendering.
+     * Does NOT modify simulation state - use start(), stop(), pause(), unpause() to control simulation.
+     *
+     * @param {number} [simulationAlpha] - Optional alpha value to set.
+     *   - If 0: Sets alpha to 0, simulation stops after one frame (graph becomes static).
+     *   - If positive: Sets alpha to that value.
+     *   - If undefined: Keeps current alpha value.
      */
     render(simulationAlpha?: number): void;
     /**
@@ -440,12 +461,19 @@ export declare class Graph {
     getScaleY(): ((y: number) => number) | undefined;
     /**
      * Start the simulation.
+     * This only controls the simulation state, not rendering.
      * @param alpha Value from 0 to 1. The higher the value, the more initial energy the simulation will get.
      */
     start(alpha?: number): void;
+    /**
+     * Stop the simulation. This stops the simulation and resets its state.
+     * Use start() to begin a new simulation cycle.
+     */
+    stop(): void;
     /**
      * Pause the simulation. When paused, the simulation stops running
-     * and can be resumed using the unpause method.
+     * but preserves its current state (progress, alpha).
+     * Can be resumed using the unpause method.
      */
     pause(): void;
     /**
@@ -460,7 +488,8 @@ export declare class Graph {
      */
     restart(): void;
     /**
-     * Render only one frame of the simulation (stops the simulation if it was running).
+     * Run one step of the simulation manually.
+     * Works even when the simulation is paused.
      */
     step(): void;
     /**
@@ -490,15 +519,56 @@ export declare class Graph {
      * @returns true if device was not ready and operation was queued, false if device is ready
      */
     private ensureDevice;
+    /**
+     * Validates that a device has the required HTMLCanvasElement canvas context.
+     * Cosmos requires an HTMLCanvasElement canvas context and does not support
+     * OffscreenCanvas or compute-only devices.
+     * @param device - The device to validate
+     * @returns The validated canvas context (guaranteed to be non-null and HTMLCanvasElement type)
+     * @throws Error if the device does not meet Cosmos requirements
+     */
+    private validateDevice;
     /**
      * Internal device creation method
      * Graph class decides what device to create with sensible defaults
      */
     private createDevice;
+    /**
+    * Updates and recreates the graph visualization based on pending changes.
+    *
+    * @param simulationAlpha - Optional alpha value to set. If not provided, keeps current alpha.
+    */
     private update;
+    /**
+     * Runs one step of the simulation (forces, position updates, alpha decay).
+     * This is the core simulation logic that can be called by step() or during rendering.
+     *
+     * @param forceExecution - Controls whether to run the simulation step when paused.
+     *   - If true: Always runs the simulation step, even when isSimulationRunning is false.
+     *     Used by step() to allow manual stepping while the simulation is paused.
+     *   - If false: Only runs if isSimulationRunning is true. Used during rendering
+     *     to respect pause/unpause state.
+     */
+    private runSimulationStep;
     private initPrograms;
+    /**
+     * The rendering loop - schedules itself to run continuously
+     */
     private frame;
+    /**
+     * Renders a single frame (the actual rendering logic).
+     * This does NOT schedule the next frame.
+     */
+    private renderFrame;
     private stopFrames;
+    /**
+     * Starts continuous rendering
+     */
+    private startFrames;
+    /**
+     * Called automatically when simulation completes (alpha < ALPHA_MIN).
+     * Rendering continues after this is called (for rendering/interaction).
+     */
     private end;
     private onClick;
     private updateMousePosition;

package/dist/{modules → src/modules}/Clusters/index.d.ts

@@ -1,12 +1,8 @@
-import { Framebuffer, RenderPass } from '@luma.gl/core';
+import { Framebuffer } from '@luma.gl/core';
 import { CoreModule } from '../core-module';
 export declare class Clusters extends CoreModule {
     centermassFbo: Framebuffer | undefined;
     clusterCount: number | undefined;
-    private clusterFbo;
-    private clusterPositionsFbo;
-    private clusterForceCoefficientFbo;
-    private clearCentermassCommand;
     private calculateCentermassCommand;
     private applyForcesCommand;
     private clusterTexture;
@@ -15,7 +11,6 @@ export declare class Clusters extends CoreModule {
     private centermassTexture;
     private pointIndices;
     private clustersTextureSize;
-    private clearCentermassVertexCoordBuffer;
     private applyForcesVertexCoordBuffer;
     private previousPointsTextureSize;
     private previousClustersTextureSize;
@@ -25,6 +20,10 @@ export declare class Clusters extends CoreModule {
     create(): void;
     initPrograms(): void;
     calculateCentermass(): void;
-    run(renderPass?: RenderPass): void;
+    run(): void;
+    /**
+     * Destruction order matters
+     * Models -> Framebuffers -> Textures -> UniformStores -> Buffers
+     */
     destroy(): void;
 }

package/dist/{modules → src/modules}/ForceCenter/index.d.ts

@@ -1,19 +1,20 @@
-import { RenderPass } from '@luma.gl/core';
 import { CoreModule } from '../core-module';
 export declare class ForceCenter extends CoreModule {
     private centermassTexture;
     private centermassFbo;
     private pointIndices;
-    private clearCentermassCommand;
     private calculateCentermassCommand;
     private runCommand;
-    private clearVertexCoordBuffer;
     private forceVertexCoordBuffer;
     private calculateUniformStore;
     private forceUniformStore;
     private previousPointsTextureSize;
     create(): void;
     initPrograms(): void;
-    run(renderPass?: RenderPass): void;
+    run(): void;
+    /**
+     * Destruction order matters
+     * Models -> Framebuffers -> Textures -> UniformStores -> Buffers
+     */
     destroy(): void;
 }

package/dist/{modules → src/modules}/ForceGravity/index.d.ts

@@ -1,10 +1,13 @@
-import { RenderPass } from '@luma.gl/core';
 import { CoreModule } from '../core-module';
 export declare class ForceGravity extends CoreModule {
     private runCommand;
     private vertexCoordBuffer;
     private uniformStore;
     initPrograms(): void;
-    run(renderPass?: RenderPass): void;
+    run(): void;
+    /**
+     * Destruction order matters
+     * Models -> Framebuffers -> Textures -> UniformStores -> Buffers
+     */
     destroy(): void;
 }

package/dist/{modules → src/modules}/ForceLink/index.d.ts

@@ -1,4 +1,3 @@
-import { RenderPass } from '@luma.gl/core';
 import { CoreModule } from '../core-module';
 export declare enum LinkDirection {
     OUTGOING = "outgoing",
@@ -20,6 +19,10 @@ export declare class ForceLink extends CoreModule {
     private randomDistanceTexture;
     create(direction: LinkDirection): void;
     initPrograms(): void;
-    run(renderPass?: RenderPass): void;
+    run(): void;
+    /**
+     * Destruction order matters
+     * Models -> Framebuffers -> Textures -> UniformStores -> Buffers
+     */
     destroy(): void;
 }

package/dist/{modules → src/modules}/ForceManyBody/index.d.ts

@@ -1,15 +1,12 @@
-import { RenderPass } from '@luma.gl/core';
 import { CoreModule } from '../core-module';
 export declare class ForceManyBody extends CoreModule {
     private randomValuesTexture;
     private pointIndices;
     private levels;
     private levelTargets;
-    private clearLevelsCommand;
     private calculateLevelsCommand;
     private forceCommand;
     private forceFromItsOwnCentermassCommand;
-    private clearLevelsVertexCoordBuffer;
     private forceVertexCoordBuffer;
     private calculateLevelsUniformStore;
     private forceUniformStore;
@@ -18,7 +15,11 @@ export declare class ForceManyBody extends CoreModule {
     private previousSpaceSize;
     create(): void;
     initPrograms(): void;
-    run(renderPass?: RenderPass): void;
+    run(): void;
+    /**
+     * Destruction order matters
+     * Models -> Framebuffers -> Textures -> UniformStores -> Buffers
+     */
     destroy(): void;
     private drawLevels;
     private drawForces;

package/dist/{modules → src/modules}/ForceMouse/index.d.ts

@@ -1,10 +1,13 @@
-import { RenderPass } from '@luma.gl/core';
 import { CoreModule } from '../core-module';
 export declare class ForceMouse extends CoreModule {
     private runCommand;
     private vertexCoordBuffer;
     private uniformStore;
     initPrograms(): void;
-    run(renderPass?: RenderPass): void;
+    run(): void;
+    /**
+     * Destruction order matters
+     * Models -> Framebuffers -> Textures -> UniformStores -> Buffers
+     */
     destroy(): void;
 }

package/dist/{modules → src/modules}/GraphData/index.d.ts

@@ -24,6 +24,7 @@ export declare class GraphData {
     inputPointClusters: (number | undefined)[] | undefined;
     inputClusterPositions: (number | undefined)[] | undefined;
     inputClusterStrength: Float32Array | undefined;
+    inputPinnedPoints: number[] | undefined;
     pointPositions: Float32Array | undefined;
     pointColors: Float32Array | undefined;
     pointSizes: Float32Array | undefined;

package/dist/{modules → src/modules}/Lines/index.d.ts

@@ -28,4 +28,9 @@ export declare class Lines extends CoreModule {
     updateArrow(): void;
     updateCurveLineGeometry(): void;
     findHoveredLine(): void;
+    /**
+     * Destruction order matters
+     * Models -> Framebuffers -> Textures -> UniformStores -> Buffers
+     */
+    destroy(): void;
 }

package/dist/{modules → src/modules}/Points/index.d.ts

@@ -6,7 +6,6 @@ export declare class Points extends CoreModule {
     velocityFbo: Framebuffer | undefined;
     selectedFbo: Framebuffer | undefined;
     hoveredFbo: Framebuffer | undefined;
-    greyoutStatusFbo: Framebuffer | undefined;
     scaleX: ((x: number) => number) | undefined;
     scaleY: ((y: number) => number) | undefined;
     shouldSkipRescale: boolean | undefined;
@@ -17,14 +16,12 @@ export declare class Points extends CoreModule {
     velocityTexture: Texture | undefined;
     greyoutStatusTexture: Texture | undefined;
     private colorBuffer;
-    private sizeFbo;
     private sizeBuffer;
     private shapeBuffer;
     private imageIndicesBuffer;
     private imageSizesBuffer;
     private imageAtlasCoordsTexture;
     private imageAtlasCoordsTextureSize;
-    private trackedIndicesFbo;
     private trackedPositionsFbo;
     private sampledPointsFbo;
     private trackedPositions;
@@ -36,24 +33,20 @@ export declare class Points extends CoreModule {
     private findPointsOnAreaSelectionCommand;
     private findPointsOnPolygonSelectionCommand;
     private findHoveredPointCommand;
-    private clearHoveredFboCommand;
-    private clearSampledPointsFboCommand;
     private fillSampledPointsFboCommand;
     private trackPointsCommand;
     private updatePositionVertexCoordBuffer;
     private dragPointVertexCoordBuffer;
     private findPointsOnAreaSelectionVertexCoordBuffer;
     private findPointsOnPolygonSelectionVertexCoordBuffer;
-    private clearHoveredFboVertexCoordBuffer;
-    private clearSampledPointsFboVertexCoordBuffer;
     private drawHighlightedVertexCoordBuffer;
     private trackPointsVertexCoordBuffer;
     private trackedIndices;
     private selectedTexture;
+    private pinnedStatusTexture;
     private sizeTexture;
     private trackedIndicesTexture;
     private polygonPathTexture;
-    private polygonPathFbo;
     private polygonPathLength;
     private drawPointIndices;
     private hoveredPointIndices;
@@ -71,6 +64,7 @@ export declare class Points extends CoreModule {
     initPrograms(): void;
     updateColor(): void;
     updateGreyoutStatus(): void;
+    updatePinnedStatus(): void;
     updateSize(): void;
     updateShape(): void;
     updateImageIndices(): void;
@@ -101,6 +95,10 @@ export declare class Points extends CoreModule {
         positions: number[];
     };
     getTrackedPositionsArray(): number[];
+    /**
+     * Destruction order matters
+     * Models -> Framebuffers -> Textures -> UniformStores -> Buffers
+     * */
     destroy(): void;
     private swapFbo;
     private rescaleInitialNodePositions;

package/dist/src/modules/Shared/buffer.d.ts

@@ -0,0 +1 @@
+export declare function createIndexesForBuffer(textureSize: number): Float32Array;

package/dist/src/modules/Shared/texture-utils.d.ts

@@ -0,0 +1,8 @@
+import { TextureFormat } from '@luma.gl/core';
+/**
+ * Calculates bytesPerRow for texture uploads.
+ * @param format - Texture format
+ * @param width - Texture width in pixels
+ * @returns bytesPerRow in bytes
+ */
+export declare function getBytesPerRow(format: TextureFormat, width: number): number;

package/dist/src/modules/Shared/uniform-utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validates and normalizes array values to fixed-size tuples for shader uniforms.
+ */
+/**
+ * Ensures a value is a vec2 tuple [number, number].
+ */
+export declare function ensureVec2(arr: number[] | undefined, fallback: [number, number]): [number, number];
+/**
+ * Ensures a value is a vec4 tuple [number, number, number, number].
+ */
+export declare function ensureVec4(arr: number[] | undefined, fallback: [number, number, number, number]): [number, number, number, number];

package/dist/{modules → src/modules}/Store/index.d.ts

@@ -147,6 +147,7 @@ export declare class Store {
     /**
      * If the config parameter `spaceSize` exceeds the limits of WebGL,
      * it reduces the space size without changing the config parameter.
+     * Ensures `spaceSize` is always a positive number >= 2 (required for Math.log2).
      */
     adjustSpaceSize(configSpaceSize: number, webglMaxTextureSize: number): void;
     /**

package/dist/{variables.d.ts → src/variables.d.ts}

@@ -30,14 +30,12 @@ export declare const defaultConfigValues: {
     hoveredLinkWidthIncrease: number;
     focusedPointRingColor: string;
     focusedPointIndex: undefined;
-    useClassicQuadtree: boolean;
     simulation: {
         decay: number;
         gravity: number;
         center: number;
         repulsion: number;
         repulsionTheta: number;
-        repulsionQuadtreeLevels: number;
         linkSpring: number;
         linkDistance: number;
         linkDistRandomVariationRange: number[];

package/dist/vite.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vite').UserConfigFnObject;
+export default _default;