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

package/dist/modules/Drag/index.d.ts

@@ -1,9 +1,11 @@
 import { Store } from '../Store';
 import { GraphConfigInterface } from '../../config';
+import { Transition } from '../Transition';
 export declare class Drag {
     readonly store: Store;
     readonly config: GraphConfigInterface;
+    readonly transition: Transition;
     isActive: boolean;
     behavior: import('d3-drag').DragBehavior<HTMLCanvasElement, undefined, import('d3-drag').SubjectPosition | undefined>;
-    constructor(store: Store, config: GraphConfigInterface);
+    constructor(store: Store, config: GraphConfigInterface, transition: Transition);
 }

package/dist/modules/GraphData/index.d.ts

@@ -26,6 +26,18 @@ export declare class GraphData {
     inputClusterStrength: Float32Array | undefined;
     inputPinnedPoints: number[] | undefined;
     pointPositions: Float32Array | undefined;
+    /**
+     * Number of points before the latest data update.
+     * Used as the `from` value for point transitions.
+     * This lets transitions handle added or removed points correctly.
+     */
+    sourcePointsNumber: number;
+    /**
+     * Number of points after the latest data update.
+     * Used as the `to` value for point transitions.
+     * This lets transitions handle added or removed points correctly.
+     */
+    targetPointsNumber: number;
     pointColors: Float32Array | undefined;
     pointSizes: Float32Array | undefined;
     pointShapes: Float32Array | undefined;
@@ -93,7 +105,26 @@ export declare class GraphData {
     updateLinkStrength(): void;
     updateClusters(): void;
     update(): void;
-    getAdjacentIndices(index: number): number[] | undefined;
+    /**
+     * Returns unique point indices that are neighbors of the given point(s) —
+     * i.e., connected by a link in either direction.
+     * @param pointIndices - A single point index or an array of point indices.
+     * @returns Array of neighboring point indices.
+     */
+    getNeighboringPointIndices(pointIndices: number | number[]): number[];
+    /**
+     * Returns unique link indices where both the source and target endpoints
+     * are within the given point(s). Only links fully contained in the set are returned.
+     * @param pointIndices - A single point index or an array of point indices.
+     * @returns Array of link indices connecting points within the provided set.
+     */
+    getConnectedLinkIndices(pointIndices: number | number[]): number[];
+    /**
+     * Returns unique point indices at the endpoints (source and target) of the given link(s).
+     * @param linkIndices - A single link index or an array of link indices.
+     * @returns Array of point indices at the ends of the provided links.
+     */
+    getConnectedPointIndices(linkIndices: number | number[]): number[];
     private _createAdjacencyLists;
     private _calculateDegrees;
 }

package/dist/modules/Lines/index.d.ts

@@ -1,16 +1,22 @@
-import { Framebuffer, RenderPass } from '@luma.gl/core';
+import { Framebuffer, Texture, RenderPass } from '@luma.gl/core';
 import { CoreModule } from '../core-module';
 export declare class Lines extends CoreModule {
     linkIndexFbo: Framebuffer | undefined;
     hoveredLineIndexFbo: Framebuffer | undefined;
     sampledLinksFbo: Framebuffer | undefined;
+    linkStatusTexture: Texture | undefined;
+    private linkStatusTextureSize;
     private drawCurveCommand;
     private hoveredLineIndexCommand;
     private fillSampledLinksFboCommand;
     private pointABuffer;
     private pointBBuffer;
-    private colorBuffer;
-    private widthBuffer;
+    private sourceColorBuffer;
+    private targetColorBuffer;
+    private previousColorData;
+    private sourceWidthBuffer;
+    private targetWidthBuffer;
+    private previousWidthData;
     private arrowBuffer;
     private curveLineGeometry;
     private curveLineBuffer;
@@ -18,6 +24,9 @@ export declare class Lines extends CoreModule {
     private quadBuffer;
     private linkIndexTexture;
     private hoveredLineIndexTexture;
+    private transitionProgress;
+    private shouldAnimateLinkColors;
+    private shouldAnimateLinkWidths;
     private fillSampledLinksUniformStore;
     private drawLineUniformStore;
     private hoveredLineIndexUniformStore;
@@ -30,6 +39,7 @@ export declare class Lines extends CoreModule {
     updateColor(): void;
     updateWidth(): void;
     updateArrow(): void;
+    updateLinkStatus(): void;
     updateCurveLineGeometry(): void;
     getSampledLinkPositionsMap(): Map<number, [number, number, number]>;
     getSampledLinks(): {
@@ -38,9 +48,11 @@ export declare class Lines extends CoreModule {
         angles: number[];
     };
     findHoveredLine(): void;
+    setTransitionProgress(progress: number, animateColors?: boolean, animateWidths?: boolean): void;
     /**
      * Destruction order matters
      * Models -> Framebuffers -> Textures -> UniformStores -> Buffers
      */
     destroy(): void;
+    private ensureLinkStatusPlaceholder;
 }

package/dist/modules/Points/index.d.ts

@@ -1,10 +1,14 @@
 import { Framebuffer, Texture, RenderPass } from '@luma.gl/core';
 import { CoreModule } from '../core-module';
+import { Transition } from '../Transition';
 export declare class Points extends CoreModule {
+    transition: Transition | undefined;
     currentPositionFbo: Framebuffer | undefined;
     previousPositionFbo: Framebuffer | undefined;
+    sourcePositionFbo: Framebuffer | undefined;
+    targetPositionFbo: Framebuffer | undefined;
     velocityFbo: Framebuffer | undefined;
-    selectedFbo: Framebuffer | undefined;
+    searchFbo: Framebuffer | undefined;
     hoveredFbo: Framebuffer | undefined;
     scaleX: ((x: number) => number) | undefined;
     scaleY: ((y: number) => number) | undefined;
@@ -14,7 +18,9 @@ export declare class Points extends CoreModule {
     currentPositionTexture: Texture | undefined;
     previousPositionTexture: Texture | undefined;
     velocityTexture: Texture | undefined;
-    greyoutStatusTexture: Texture | undefined;
+    pointStatusTexture: Texture | undefined;
+    sourcePositionTexture: Texture | undefined;
+    targetPositionTexture: Texture | undefined;
     /**
      * Whether the cached cluster centroid positions are still valid.
      * Set to `false` in `swapFbo()` whenever GPU point positions change (simulation tick or drag).
@@ -22,8 +28,12 @@ export declare class Points extends CoreModule {
      * Used together with `Clusters.cachedCentroidPositions` to skip redundant GPU readbacks.
      */
     areClusterCentroidsUpToDate: boolean;
-    private colorBuffer;
-    private sizeBuffer;
+    private sourceColorBuffer;
+    private targetColorBuffer;
+    private previousColorData;
+    private sourceSizeBuffer;
+    private targetSizeBuffer;
+    private previousSizeData;
     private shapeBuffer;
     private imageIndicesBuffer;
     private imageSizesBuffer;
@@ -32,24 +42,32 @@ export declare class Points extends CoreModule {
     private trackedPositionsFbo;
     private sampledPointsFbo;
     private trackedPositions;
+    /**
+     * Guards the CPU-side `trackedPositions` cache in `getTrackedPositionsMap()`.
+     * Set to `true` after a successful readback when the simulation is inactive;
+     * must be set to `false` whenever `currentPositionFbo` is written to
+     * (simulation step, drag, position transition) so the next call re-reads from the GPU.
+     */
     private isPositionsUpToDate;
     private drawCommand;
     private drawHighlightedCommand;
     private updatePositionCommand;
+    private interpolatePositionCommand;
     private dragPointCommand;
-    private findPointsOnAreaSelectionCommand;
-    private findPointsOnPolygonSelectionCommand;
+    private findPointsInRectCommand;
+    private findPointsInPolygonCommand;
     private findHoveredPointCommand;
     private fillSampledPointsFboCommand;
     private trackPointsCommand;
     private updatePositionVertexCoordBuffer;
+    private interpolatePositionVertexCoordBuffer;
     private dragPointVertexCoordBuffer;
-    private findPointsOnAreaSelectionVertexCoordBuffer;
-    private findPointsOnPolygonSelectionVertexCoordBuffer;
+    private findPointsInRectVertexCoordBuffer;
+    private findPointsInPolygonVertexCoordBuffer;
     private drawHighlightedVertexCoordBuffer;
     private trackPointsVertexCoordBuffer;
     private trackedIndices;
-    private selectedTexture;
+    private searchTexture;
     private pinnedStatusTexture;
     private sizeTexture;
     private trackedIndicesTexture;
@@ -58,19 +76,23 @@ export declare class Points extends CoreModule {
     private drawPointIndices;
     private hoveredPointIndices;
     private sampledPointIndices;
+    private transitionProgress;
+    private shouldAnimatePointColors;
+    private shouldAnimatePointSizes;
     private updatePositionUniformStore;
+    private interpolatePositionUniformStore;
     private dragPointUniformStore;
     private drawUniformStore;
-    private findPointsOnAreaSelectionUniformStore;
-    private findPointsOnPolygonSelectionUniformStore;
+    private findPointsInRectUniformStore;
+    private findPointsInPolygonUniformStore;
     private findHoveredPointUniformStore;
     private fillSampledPointsUniformStore;
     private drawHighlightedUniformStore;
     private trackPointsUniformStore;
-    updatePositions(): void;
+    updatePositions(): boolean;
     initPrograms(): void;
     updateColor(): void;
-    updateGreyoutStatus(): void;
+    updatePointStatus(): void;
     updatePinnedStatus(): void;
     updateSize(): void;
     updateShape(): void;
@@ -79,11 +101,12 @@ export declare class Points extends CoreModule {
     createAtlas(): void;
     updateSampledPointsGrid(): void;
     trackPoints(): void;
+    setTransitionProgress(progress: number, animateColors?: boolean, animateSizes?: boolean): void;
     draw(renderPass: RenderPass): void;
     updatePosition(): void;
     drag(): void;
-    findPointsOnAreaSelection(): void;
-    findPointsOnPolygonSelection(): void;
+    findPointsInRect(): boolean;
+    findPointsInPolygon(): boolean;
     updatePolygonPath(polygonPath: [number, number][]): void;
     findHoveredPoint(): void;
     trackPointsByIndices(indices?: number[] | undefined): void;
@@ -103,10 +126,17 @@ export declare class Points extends CoreModule {
     };
     getTrackedPositionsArray(): number[];
     /**
-     * Destruction order matters
-     * Models -> Framebuffers -> Textures -> UniformStores -> Buffers
-     * */
+     * Destroy luma.gl resources in ownership order:
+     * Models -> Framebuffers -> Textures -> UniformStores -> Buffers.
+     */
     destroy(): void;
-    private swapFbo;
+    ensureSimulationResources(): void;
+    createTransitionResources(): void;
+    destroyTransitionResources(): void;
+    interpolatePosition(progress: number): void;
+    destroySimulationResources(): void;
+    swapFbo(): void;
+    private createOrUpdatePositionTextures;
+    private ensureUpdatePositionProgram;
     private rescaleInitialNodePositions;
 }

package/dist/modules/Points/position-utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Build RGBA32F texture data from a flat `[x, y, x, y, ...]` point positions array.
+ *
+ * Layout per pixel: `[x, y, index, 0]`. The blue channel encodes the point index —
+ * `drag-point.frag` reads it to match the drag target. Alpha is unused by shaders.
+ */
+export declare function buildPositionTextureData(pointPositions: Float32Array | undefined, pointsTextureSize: number, pointsNumber: number): Float32Array;
+/**
+ * Build the `sourcePosition` texture data for a transition when the point count changed.
+ *
+ * Shared indices (`0..sharedCount`) carry over their on-screen positions from
+ * `previousPositionPixels` (readback of the pre-transition `currentPositionFbo`), so the
+ * animation starts from where each point was last rendered. New indices (`sharedCount..targetCount`)
+ * start at their target position so they don't drift in from the origin.
+ *
+ * Precondition: `sharedCount * 4 <= previousPositionPixels.length` — the caller guarantees
+ * this by passing `min(previousPointsCount, targetCount)`.
+ */
+export declare function buildSourcePositionTextureData(previousPositionPixels: Float32Array, targetData: Float32Array, sharedCount: number, targetCount: number, newTextureSize: number): Float32Array;

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

@@ -1 +1,7 @@
+import { Buffer, Device } from '@luma.gl/core';
 export declare function createIndexesForBuffer(textureSize: number): Float32Array;
+export declare function updateAttributeBuffers(device: Device, targetData: Float32Array, sourceBuffer: Buffer | undefined, targetBuffer: Buffer | undefined, previousData: Float32Array | undefined, tupleSize: 1 | 4): {
+    source: Buffer;
+    target: Buffer;
+    previous: Float32Array;
+};

package/dist/modules/Store/index.d.ts

@@ -33,10 +33,9 @@ export declare class Store {
     screenSize: [number, number];
     mousePosition: number[];
     screenMousePosition: number[];
-    selectedArea: number[][];
+    searchArea: number[][];
     isSimulationRunning: boolean;
     simulationProgress: number;
-    selectedIndices: Float32Array | null;
     maxPointSize: number;
     hoveredPoint: Hovered | undefined;
     focusedPoint: Focused | undefined;
@@ -48,6 +47,9 @@ export declare class Store {
     webglMaxTextureSize: number;
     hoveredPointRingColor: number[];
     focusedPointRingColor: number[];
+    outlinedPointRingColor: number[];
+    highlightedPointSet: Set<number> | undefined;
+    outlinedPointSet: Set<number> | undefined;
     hoveredLinkColor: number[];
     greyoutPointColor: number[];
     isDarkenGreyout: boolean;
@@ -164,6 +166,9 @@ export declare class Store {
     scaleY(y: number): number;
     setHoveredPointRingColor(color: string | [number, number, number, number]): void;
     setFocusedPointRingColor(color: string | [number, number, number, number]): void;
+    setOutlinedPointRingColor(color: string | [number, number, number, number]): void;
+    setHighlightedPointSet(indices: number[] | undefined): void;
+    setOutlinedPointSet(indices: number[] | undefined): void;
     setGreyoutPointColor(color: string | [number, number, number, number] | undefined): void;
     updateLinkHoveringEnabled(config: Pick<GraphConfigInterface, 'onLinkClick' | 'onLinkContextMenu' | 'onLinkMouseOver' | 'onLinkMouseOut'>): void;
     setHoveredLinkColor(color?: string | [number, number, number, number]): void;

package/dist/modules/Transition/index.d.ts

@@ -0,0 +1,87 @@
+import { GraphConfigInterface } from '../../config';
+export declare enum TransitionProperty {
+    Positions = "positions",
+    PointColors = "pointColors",
+    PointSizes = "pointSizes",
+    LinkColors = "linkColors",
+    LinkWidths = "linkWidths"
+}
+export declare enum TransitionEasing {
+    Linear = "linear",
+    QuadIn = "quad-in",
+    QuadOut = "quad-out",
+    QuadInOut = "quad-in-out",
+    CubicIn = "cubic-in",
+    CubicOut = "cubic-out",
+    CubicInOut = "cubic-in-out",
+    SinIn = "sin-in",
+    SinOut = "sin-out",
+    SinInOut = "sin-in-out",
+    ExpIn = "exp-in",
+    ExpOut = "exp-out",
+    ExpInOut = "exp-in-out",
+    CircleIn = "circle-in",
+    CircleOut = "circle-out",
+    CircleInOut = "circle-in-out"
+}
+export declare class Transition {
+    /** Last eased progress value in the `[0, 1]` range. */
+    progress: number;
+    private readonly config;
+    private startTime;
+    /** Properties queued via `queue()`, awaiting `start()` to consume them. */
+    private pendingProperties;
+    /** Properties currently animating in the running cycle. */
+    private activeProperties;
+    constructor(config: GraphConfigInterface);
+    /** True while one or more properties are queued via `queue()` awaiting `start()`. */
+    get isPending(): boolean;
+    /** True between `start()` and the end of the cycle. */
+    get isActive(): boolean;
+    /** Reports whether a specific property is queued and awaiting `start()`. */
+    isPendingFor(property: TransitionProperty): boolean;
+    /** Reports whether a specific property is part of the active cycle. */
+    isActiveFor(property: TransitionProperty): boolean;
+    /** Queues a property for the next transition cycle. */
+    queue(property: TransitionProperty): void;
+    /** Removes a property from the pending queue without affecting the active cycle. */
+    dequeue(property: TransitionProperty): void;
+    /**
+     * Starts a queued transition cycle.
+     *
+     * - No pending queue → no-op.
+     * - `transitionDuration > 0` → begin cycle; fire `onTransitionStart`.
+     * - `transitionDuration <= 0` → pending is discarded; no cycle begins.
+     *
+     * In either non-no-op path, any active cycle is reported as interrupted
+     * via `onTransitionEnd(true)` before the new state takes effect.
+     */
+    start(): void;
+    /**
+     * Advances the active cycle.
+     *
+     * - No active cycle → no-op.
+     * - `transitionDuration <= 0` → end interrupted; fire `onTransitionEnd(true)`.
+     * - Progress < 1 → update `progress`; fire `onTransition(eased)`.
+     * - Progress reaches 1 → fire `onTransition(1)` then `onTransitionEnd(false)`.
+     */
+    step(): void;
+    /**
+     * Ends the active cycle.
+     *
+     * - No active cycle → no-op.
+     * - Otherwise → fire `onTransitionEnd(interrupted)`.
+     *
+     * TODO: support per-property end.
+     */
+    end(interrupted: boolean): void;
+    /**
+     * Clears all transition state — active cycle and pending queue — without
+     * firing lifecycle callbacks. Unlike `end()`, also drops any properties
+     * queued via `queue()`.
+     */
+    abort(): void;
+    private applyEasing;
+    /** Ends the active cycle, preserving any pending queue for the next `start()`. */
+    private clearActiveCycle;
+}

package/dist/variables.d.ts

@@ -1,9 +1,12 @@
 import { PointShape } from './modules/GraphData';
+import { TransitionEasing } from './modules/Transition';
 /**
  * Default values for all graph configuration properties.
  */
 export declare const defaultConfigValues: {
     enableSimulation: true;
+    transitionDuration: number;
+    transitionEasing: TransitionEasing.CubicInOut;
     backgroundColor: string;
     /** Setting to 4096 because larger values crash the graph on iOS. More info: https://github.com/cosmosgl/graph/issues/203 */
     spaceSize: number;
@@ -20,6 +23,9 @@ export declare const defaultConfigValues: {
     hoveredPointRingColor: string;
     focusedPointRingColor: string;
     focusedPointIndex: undefined;
+    highlightedPointIndices: undefined;
+    outlinedPointIndices: undefined;
+    outlinedPointRingColor: string;
     renderLinks: true;
     linkDefaultColor: string;
     linkDefaultWidth: number;
@@ -38,6 +44,9 @@ export declare const defaultConfigValues: {
     hoveredLinkCursor: string;
     hoveredLinkColor: undefined;
     hoveredLinkWidthIncrease: number;
+    highlightedLinkIndices: undefined;
+    focusedLinkIndex: undefined;
+    focusedLinkWidthIncrease: number;
     simulationDecay: number;
     simulationGravity: number;
     simulationCenter: number;
@@ -55,6 +64,9 @@ export declare const defaultConfigValues: {
     onSimulationEnd: undefined;
     onSimulationPause: undefined;
     onSimulationUnpause: undefined;
+    onTransitionStart: undefined;
+    onTransition: undefined;
+    onTransitionEnd: undefined;
     onClick: undefined;
     onPointClick: undefined;
     onLinkClick: undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmos.gl/graph",
-  "version": "3.0.0-beta.7",
+  "version": "3.0.0-beta.9",
   "description": "GPU-based force graph layout and rendering",
   "jsdelivr": "dist/index.min.js",
   "main": "dist/index.js",
@@ -72,9 +72,10 @@
     "vite-plugin-dts": "^4.3.0"
   },
   "dependencies": {
-    "@luma.gl/core": "^9.2.6",
-    "@luma.gl/engine": "^9.2.6",
-    "@luma.gl/webgl": "^9.2.6",
+    "@luma.gl/core": "~9.2.6",
+    "@luma.gl/engine": "~9.2.6",
+    "@luma.gl/shadertools": "~9.2.6",
+    "@luma.gl/webgl": "~9.2.6",
     "d3-array": "^3.2.0",
     "d3-color": "^3.1.0",
     "d3-drag": "^3.0.0",