@cosmos.gl/graph 2.7.0-beta.1 → 2.7.0-beta.3

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

@@ -213,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`
@@ -242,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`
@@ -588,13 +574,11 @@ export declare class GraphConfig implements GraphConfigInterface {
     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/{helper.d.ts → src/helper.d.ts}

@@ -43,8 +43,18 @@ export declare function rgbToBrightness(r: number, g: number, b: number): number
  * - Consider batching the migration to avoid inconsistencies
  *
  * Current status: Deprecated but still functional. Keeping for now until full migration can be planned.
+ *
+ * @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;
+/**
+ * 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.
+ * @param device - The luma.gl device
+ * @param pixelRatio - Device pixel ratio to scale the result
+ * @returns Maximum point size (device limit / pixelRatio)
+ */
+export declare function getMaxPointSize(device: Device, pixelRatio: number): number;
 export declare function clamp(num: number, min: number, max: number): number;
 export declare function isNumber(value: number | undefined | null | typeof NaN): boolean;
 /**

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

@@ -1,13 +1,21 @@
+import { Device } from '@luma.gl/core';
 import { GraphConfig, GraphConfigInterface } from './config';
 import { GraphData } from './modules/GraphData';
 export declare class Graph {
     config: GraphConfig;
     graph: GraphData;
+    /** Canvas element, assigned asynchronously during device initialization */
     private canvas;
     private attributionDivElement;
     private canvasD3Selection;
     private device;
     private deviceInitPromise;
+    /**
+     * Tracks whether this Graph instance owns the device and should destroy it on cleanup.
+     * Set to `true` when Graph creates its own device, `false` when using an external device.
+     * When `false`, the external device lifecycle is managed by the user.
+     */
+    private shouldDestroyDevice;
     private requestAnimationFrameId;
     private isRightClickMouse;
     private store;
@@ -33,6 +41,21 @@ export declare class Graph {
      * If the mouse is not on the Canvas, the `findHoveredPoint` or `findHoveredLine` method will not be executed.
      */
     private _isMouseOnCanvas;
+    /**
+     * Last mouse position for detecting significant mouse movement
+     */
+    private _lastMouseX;
+    private _lastMouseY;
+    /**
+     * Last checked mouse position for hover detection
+     */
+    private _lastCheckedMouseX;
+    private _lastCheckedMouseY;
+    /**
+     * Force hover detection on next frame, bypassing mouse movement check.
+     * Set when scene changes but mouse stays still (after simulation or zoom ends).
+     */
+    private _shouldForceHoverDetection;
     /**
      * After setting data and render graph at a first time, the fit logic will run
      * */
@@ -53,7 +76,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
      */
@@ -518,6 +541,15 @@ 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

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

@@ -1,9 +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 clearCentermassCommand;
     private calculateCentermassCommand;
     private applyForcesCommand;
     private clusterTexture;
@@ -12,7 +11,6 @@ export declare class Clusters extends CoreModule {
     private centermassTexture;
     private pointIndices;
     private clustersTextureSize;
-    private clearCentermassVertexCoordBuffer;
     private applyForcesVertexCoordBuffer;
     private previousPointsTextureSize;
     private previousClustersTextureSize;
@@ -22,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}/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

@@ -33,16 +33,12 @@ 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;
@@ -99,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

@@ -8,6 +8,11 @@ export declare const MAX_POINT_SIZE = 64;
  * The `findHoveredItem` method will skip actual detection until this count is reached.
  */
 export declare const MAX_HOVER_DETECTION_DELAY = 4;
+/**
+ * Minimum mouse movement threshold (in pixels) to trigger hover detection.
+ * If the mouse moves less than this distance, hover detection will be skipped to save performance.
+ */
+export declare const MIN_MOUSE_MOVEMENT_THRESHOLD = 2;
 export type Hovered = {
     index: number;
     position: [number, number];
@@ -19,7 +24,7 @@ type Focused = {
  * Type alias for a 4x4 matrix stored as a 16-element array in column-major order.
  * Used for std140 uniform buffer layout compatibility.
  */
-type Mat4Array = [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number];
+export type Mat4Array = [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number];
 export declare class Store {
     pointsTextureSize: number;
     linksTextureSize: number;
@@ -147,6 +152,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;