@cosmos.gl/graph 2.4.0 → 2.5.0

package/src/modules/Lines/draw-curve-line.vert

@@ -4,13 +4,14 @@ attribute vec2 position, pointA, pointB;
 attribute vec4 color;
 attribute float width;
 attribute float arrow;
+attribute float linkIndices;
 
 uniform sampler2D positionsTexture;
 uniform sampler2D pointGreyoutStatus;
 uniform mat3 transformationMatrix;
 uniform float pointsTextureSize;
 uniform float widthScale;
-uniform float arrowSizeScale;
+uniform float linkArrowsSizeScale;
 uniform float spaceSize;
 uniform vec2 screenSize;
 uniform vec2 linkVisibilityDistanceRange;
@@ -22,6 +23,11 @@ uniform float curvedLinkControlPointDistance;
 uniform float curvedLinkSegments;
 uniform bool scaleLinksOnZoom;
 uniform float maxPointSize;
+// renderMode: 0.0 = normal rendering, 1.0 = index buffer rendering for picking
+uniform float renderMode;
+uniform float hoveredLinkIndex;
+uniform vec4 hoveredLinkColor;
+uniform float hoveredLinkWidthIncrease;
 
 varying vec4 rgbaColor;
 varying vec2 pos;
@@ -29,6 +35,7 @@ varying float arrowLength;
 varying float useArrow;
 varying float smoothing;
 varying float arrowWidthFactor;
+varying float linkIndex;
 
 float map(float value, float min1, float max1, float min2, float max2) {
   return min2 + (value - min1) * (max2 - min2) / (max1 - min1);
@@ -73,6 +80,7 @@ float calculateArrowWidth(float arrowWidth) {
 
 void main() {
   pos = position;
+  linkIndex = linkIndices;
 
   vec2 pointTexturePosA = (pointA + 0.5) / pointsTextureSize;
   vec2 pointTexturePosB = (pointB + 0.5) / pointsTextureSize;
@@ -102,7 +110,7 @@ void main() {
   float k = 2.0;
   // Arrow width is proportionally larger than the line width
   float arrowWidth = linkWidth * k;
-  arrowWidth *= arrowSizeScale;
+  arrowWidth *= linkArrowsSizeScale;
 
   // Ensure arrow width difference is non-negative to prevent unwanted changes to link width
   float arrowWidthDifference = max(0.0, arrowWidth - linkWidth);
@@ -124,10 +132,22 @@ void main() {
 
   // Calculate final link width in pixels with smoothing
   float linkWidthPx = calculateLinkWidth(linkWidth);
+    
+  if (renderMode > 0.0) {
+    // Add 5 pixels padding for better hover detection
+    linkWidthPx += 5.0 / transformationMatrix[0][0];
+  } else {
+      // Add pixel increase if this is the hovered link
+    if (hoveredLinkIndex == linkIndex) {
+      linkWidthPx += hoveredLinkWidthIncrease / transformationMatrix[0][0];
+    }
+  }
   float smoothingPx = 0.5 / transformationMatrix[0][0];
   smoothing = smoothingPx / linkWidthPx;
   linkWidthPx += smoothingPx;
 
+
+
   // Calculate final color with opacity based on link distance
   vec3 rgbColor = color.rgb;
   // Adjust opacity based on link distance
@@ -141,6 +161,13 @@ void main() {
   // Pass final color to fragment shader
   rgbaColor = vec4(rgbColor, opacity);
 
+  // Apply hover color if this is the hovered link and hover color is defined
+  if (hoveredLinkIndex == linkIndex && hoveredLinkColor.a > -0.5) {
+    // Keep existing RGB values but multiply opacity with hover color opacity
+    rgbaColor.rgb = hoveredLinkColor.rgb;
+    rgbaColor.a *= hoveredLinkColor.a;
+  }
+
   // Calculate position on the curved path
   float t = position.x;
   float w = curvedWeight;

package/src/modules/Lines/hovered-line-index.frag

@@ -0,0 +1,27 @@
+precision highp float;
+
+uniform sampler2D linkIndexTexture;
+uniform vec2 mousePosition;
+uniform vec2 screenSize;
+
+varying vec2 vTexCoord;
+
+void main() {
+  // Convert mouse position to texture coordinates
+  vec2 texCoord = mousePosition / screenSize;
+  
+  // Read the link index from the linkIndexFbo texture at mouse position
+  vec4 linkIndexData = texture2D(linkIndexTexture, texCoord);
+  
+  // Extract the link index (stored in the red channel)
+  float linkIndex = linkIndexData.r;
+  
+  // Check if there's a valid link at this position (alpha > 0)
+  if (linkIndexData.a > 0.0 && linkIndex >= 0.0) {
+    // Output the link index
+    gl_FragColor = vec4(linkIndex, 0.0, 0.0, 1.0);
+  } else {
+    // No link at this position, output -1 to indicate no hover
+    gl_FragColor = vec4(-1.0, 0.0, 0.0, 0.0);
+  }
+} 

package/src/modules/Lines/hovered-line-index.vert

@@ -0,0 +1,8 @@
+attribute vec2 position;
+
+varying vec2 vTexCoord;
+
+void main() {
+  vTexCoord = position * 0.5 + 0.5;
+  gl_Position = vec4(position, 0.0, 1.0);
+} 

package/src/modules/Lines/index.ts

@@ -2,21 +2,44 @@ import regl from 'regl'
 import { CoreModule } from '@/graph/modules/core-module'
 import drawLineFrag from '@/graph/modules/Lines/draw-curve-line.frag'
 import drawLineVert from '@/graph/modules/Lines/draw-curve-line.vert'
+import hoveredLineIndexFrag from '@/graph/modules/Lines/hovered-line-index.frag'
+import hoveredLineIndexVert from '@/graph/modules/Lines/hovered-line-index.vert'
 import { defaultConfigValues } from '@/graph/variables'
 import { getCurveLineGeometry } from '@/graph/modules/Lines/geometry'
 
 export class Lines extends CoreModule {
+  public linkIndexFbo: regl.Framebuffer2D | undefined
+  public hoveredLineIndexFbo: regl.Framebuffer2D | undefined
   private drawCurveCommand: regl.DrawCommand | undefined
+  private hoveredLineIndexCommand: regl.DrawCommand | undefined
   private pointsBuffer: regl.Buffer | undefined
   private colorBuffer: regl.Buffer | undefined
   private widthBuffer: regl.Buffer | undefined
   private arrowBuffer: regl.Buffer | undefined
   private curveLineGeometry: number[][] | undefined
   private curveLineBuffer: regl.Buffer | undefined
+  private linkIndexBuffer: regl.Buffer | undefined
+  private quadBuffer: regl.Buffer | undefined
 
   public initPrograms (): void {
     const { reglInstance, config, store } = this
 
+    this.updateLinkIndexFbo()
+
+    // Initialize the hovered line index FBO
+    if (!this.hoveredLineIndexFbo) {
+      this.hoveredLineIndexFbo = reglInstance.framebuffer({
+        color: reglInstance.texture({
+          width: 1,
+          height: 1,
+          format: 'rgba',
+          type: 'float',
+        }),
+        depth: false,
+        stencil: false,
+      })
+    }
+
     if (!this.drawCurveCommand) {
       this.drawCurveCommand = reglInstance({
         vert: drawLineVert,
@@ -57,6 +80,12 @@ export class Lines extends CoreModule {
             offset: Float32Array.BYTES_PER_ELEMENT * 0,
             stride: Float32Array.BYTES_PER_ELEMENT * 1,
           },
+          linkIndices: {
+            buffer: () => this.linkIndexBuffer,
+            divisor: 1,
+            offset: Float32Array.BYTES_PER_ELEMENT * 0,
+            stride: Float32Array.BYTES_PER_ELEMENT * 1,
+          },
         },
         uniforms: {
           positionsTexture: () => this.points?.currentPositionFbo,
@@ -64,7 +93,7 @@ export class Lines extends CoreModule {
           transformationMatrix: () => store.transform,
           pointsTextureSize: () => store.pointsTextureSize,
           widthScale: () => config.linkWidthScale,
-          arrowSizeScale: () => config.linkArrowsSizeScale,
+          linkArrowsSizeScale: () => config.linkArrowsSizeScale,
           spaceSize: () => store.adjustedSpaceSize,
           screenSize: () => store.screenSize,
           linkVisibilityDistanceRange: () => config.linkVisibilityDistanceRange,
@@ -76,11 +105,24 @@ export class Lines extends CoreModule {
           curvedWeight: () => config.curvedLinkWeight,
           curvedLinkControlPointDistance: () => config.curvedLinkControlPointDistance,
           curvedLinkSegments: () => config.curvedLinks ? config.curvedLinkSegments ?? defaultConfigValues.curvedLinkSegments : 1,
+          hoveredLinkIndex: () => store.hoveredLinkIndex ?? -1,
+          hoveredLinkColor: () => store.hoveredLinkColor,
+          hoveredLinkWidthIncrease: () => config.hoveredLinkWidthIncrease,
+          renderMode: reglInstance.prop<{ renderMode: number }, 'renderMode'>('renderMode'),
         },
         cull: {
           enable: true,
           face: 'back',
         },
+        /**
+         * Blending behavior for link index rendering (renderMode: 1.0 - hover detection):
+         *
+         * When rendering link indices to the framebuffer, we use full opacity (1.0).
+         * This means:
+         * - The source color completely overwrites the destination
+         * - No blending occurs - it's like drawing with a permanent marker
+         * - This preserves the exact index values we need for picking/selection
+         */
         blend: {
           enable: true,
           func: {
@@ -98,11 +140,37 @@ export class Lines extends CoreModule {
           enable: false,
           mask: false,
         },
+        framebuffer: reglInstance.prop<{ framebuffer: regl.Framebuffer2D }, 'framebuffer'>('framebuffer'),
         count: () => this.curveLineGeometry?.length ?? 0,
         instances: () => this.data.linksNumber ?? 0,
         primitive: 'triangle strip',
       })
     }
+
+    if (!this.hoveredLineIndexCommand) {
+      this.hoveredLineIndexCommand = reglInstance({
+        vert: hoveredLineIndexVert,
+        frag: hoveredLineIndexFrag,
+        attributes: {
+          position: {
+            buffer: () => this.quadBuffer,
+          },
+        },
+        uniforms: {
+          linkIndexTexture: () => this.linkIndexFbo,
+          mousePosition: () => store.screenMousePosition,
+          screenSize: () => store.screenSize,
+        },
+        framebuffer: this.hoveredLineIndexFbo,
+        count: 4,
+        primitive: 'triangle strip',
+      })
+    }
+
+    // Initialize quad buffer for full-screen rendering
+    if (!this.quadBuffer) {
+      this.quadBuffer = reglInstance.buffer([-1, -1, 1, -1, -1, 1, 1, 1])
+    }
   }
 
   public draw (): void {
@@ -111,7 +179,28 @@ export class Lines extends CoreModule {
     if (!this.widthBuffer) this.updateWidth()
     if (!this.arrowBuffer) this.updateArrow()
     if (!this.curveLineGeometry) this.updateCurveLineGeometry()
-    this.drawCurveCommand?.()
+
+    // Render normal links (renderMode: 0.0 = normal rendering)
+    this.drawCurveCommand?.({ framebuffer: null, renderMode: 0.0 })
+  }
+
+  public updateLinkIndexFbo (): void {
+    const { reglInstance, store } = this
+
+    // Only create and update the link index FBO if link hovering is enabled
+    if (!this.store.isLinkHoveringEnabled) return
+
+    if (!this.linkIndexFbo) this.linkIndexFbo = reglInstance.framebuffer()
+    this.linkIndexFbo({
+      color: reglInstance.texture({
+        width: store.screenSize[0],
+        height: store.screenSize[1],
+        format: 'rgba',
+        type: 'float',
+      }),
+      depth: false,
+      stencil: false,
+    })
   }
 
   public updatePointsBuffer (): void {
@@ -134,6 +223,13 @@ export class Lines extends CoreModule {
 
     if (!this.pointsBuffer) this.pointsBuffer = reglInstance.buffer(0)
     this.pointsBuffer(instancePoints)
+
+    const linkIndices = new Float32Array(data.linksNumber)
+    for (let i = 0; i < data.linksNumber; i++) {
+      linkIndices[i] = i
+    }
+    if (!this.linkIndexBuffer) this.linkIndexBuffer = reglInstance.buffer(0)
+    this.linkIndexBuffer(linkIndices)
   }
 
   public updateColor (): void {
@@ -160,4 +256,18 @@ export class Lines extends CoreModule {
     if (!this.curveLineBuffer) this.curveLineBuffer = reglInstance.buffer(0)
     this.curveLineBuffer(this.curveLineGeometry)
   }
+
+  public findHoveredLine (): void {
+    if (!this.data.linksNumber || !this.store.isLinkHoveringEnabled) return
+    if (!this.linkIndexFbo) this.updateLinkIndexFbo()
+    this.reglInstance.clear({
+      framebuffer: this.linkIndexFbo as regl.Framebuffer2D,
+      color: [0, 0, 0, 0],
+    })
+    // Render to index buffer for picking/hover detection (renderMode: 1.0 = index rendering)
+    this.drawCurveCommand?.({ framebuffer: this.linkIndexFbo, renderMode: 1.0 })
+
+    // Execute the command to read the link index at mouse position
+    this.hoveredLineIndexCommand?.()
+  }
 }

package/src/modules/Store/index.ts

@@ -3,10 +3,18 @@ import { mat3 } from 'gl-matrix'
 import { Random } from 'random'
 import { getRgbaColor, rgbToBrightness } from '@/graph/helper'
 import { hoveredPointRingOpacity, focusedPointRingOpacity, defaultConfigValues } from '@/graph/variables'
+import type { GraphConfigInterface } from '@/graph/config'
 
 export const ALPHA_MIN = 0.001
 export const MAX_POINT_SIZE = 64
 
+/**
+ * Maximum number of executions to delay before performing hover detection.
+ * This threshold prevents excessive hover detection calls for performance optimization.
+ * The `findHoveredItem` method will skip actual detection until this count is reached.
+ */
+export const MAX_HOVER_DETECTION_DELAY = 4
+
 export type Hovered = { index: number; position: [ number, number ] }
 type Focused = { index: number }
 
@@ -26,6 +34,7 @@ export class Store {
   public hoveredPoint: Hovered | undefined = undefined
   public focusedPoint: Focused | undefined = undefined
   public draggingPointIndex: number | undefined = undefined
+  public hoveredLinkIndex: number | undefined = undefined
   public adjustedSpaceSize = defaultConfigValues.spaceSize
   public isSpaceKeyPressed = false
   public div: HTMLDivElement | undefined
@@ -33,10 +42,13 @@ export class Store {
 
   public hoveredPointRingColor = [1, 1, 1, hoveredPointRingOpacity]
   public focusedPointRingColor = [1, 1, 1, focusedPointRingOpacity]
+  public hoveredLinkColor = [-1, -1, -1, -1]
   // -1 means that the color is not set
   public greyoutPointColor = [-1, -1, -1, -1]
   // If backgroundColor is dark, isDarkenGreyout is true
   public isDarkenGreyout = false
+  // Whether link hovering is enabled based on configured event handlers
+  public isLinkHoveringEnabled = false
   private alphaTarget = 0
   private scalePointX = scaleLinear()
   private scalePointY = scaleLinear()
@@ -102,14 +114,14 @@ export class Store {
     return this.scalePointY(y)
   }
 
-  public setHoveredPointRingColor (color: string): void {
+  public setHoveredPointRingColor (color: string | [number, number, number, number]): void {
     const convertedRgba = getRgbaColor(color)
     this.hoveredPointRingColor[0] = convertedRgba[0]
     this.hoveredPointRingColor[1] = convertedRgba[1]
     this.hoveredPointRingColor[2] = convertedRgba[2]
   }
 
-  public setFocusedPointRingColor (color: string): void {
+  public setFocusedPointRingColor (color: string | [number, number, number, number]): void {
     const convertedRgba = getRgbaColor(color)
     this.focusedPointRingColor[0] = convertedRgba[0]
     this.focusedPointRingColor[1] = convertedRgba[1]
@@ -128,6 +140,25 @@ export class Store {
     this.greyoutPointColor[3] = convertedRgba[3]
   }
 
+  public updateLinkHoveringEnabled (config: Pick<GraphConfigInterface, 'onLinkClick' | 'onLinkMouseOver' | 'onLinkMouseOut'>): void {
+    this.isLinkHoveringEnabled = !!(config.onLinkClick || config.onLinkMouseOver || config.onLinkMouseOut)
+    if (!this.isLinkHoveringEnabled) {
+      this.hoveredLinkIndex = undefined
+    }
+  }
+
+  public setHoveredLinkColor (color?: string | [number, number, number, number]): void {
+    if (color === undefined) {
+      this.hoveredLinkColor = [-1, -1, -1, -1]
+      return
+    }
+    const convertedRgba = getRgbaColor(color)
+    this.hoveredLinkColor[0] = convertedRgba[0]
+    this.hoveredLinkColor[1] = convertedRgba[1]
+    this.hoveredLinkColor[2] = convertedRgba[2]
+    this.hoveredLinkColor[3] = convertedRgba[3]
+  }
+
   public setFocusedPoint (index?: number): void {
     if (index !== undefined) {
       this.focusedPoint = { index }

package/src/modules/core-module.ts

@@ -10,6 +10,7 @@ export class CoreModule {
   public readonly store: Store
   public readonly data: GraphData
   public readonly points: Points | undefined
+  public _debugRandomNumber = Math.floor(Math.random() * 1000)
 
   public constructor (
     reglInstance: regl.Regl,

package/src/stories/1. welcome.mdx

@@ -35,7 +35,8 @@ const config = {
   fitViewPadding: 0.3, // centers the graph width padding of ~30% of screen
   rescalePositions: true, // rescale positions
   enableDrag: true, // enable dragging points
-  onClick: pointIndex => { console.log('Clicked point index: ', pointIndex) },
+  onPointClick: pointIndex => { console.log('Clicked point index: ', pointIndex) },
+  onBackgroundClick: () => { console.log('Clicked background') },
   /* ... */
 }
 

package/src/stories/2. configuration.mdx

@@ -16,6 +16,7 @@ import { Meta } from "@storybook/blocks";
 | pointOpacity | Universal opacity value applied to all points. This value multiplies with individual point alpha values (if set via setPointColors). Useful for dynamically controlling opacity of all points without updating individual RGBA arrays. | `1.0` |
 | pointSizeScale | Scale factor for the point size | `1` |
 | hoveredPointCursor | Cursor style to use when hovering over a point | `auto` |
+| hoveredLinkCursor | Cursor style to use when hovering over a link | `auto` |
 | renderHoveredPointRing | Turns ring rendering around a point on hover on / off | `false` |
 | hoveredPointRingColor | Hovered point ring color hex value or an array of RGBA values | `white` |
 | focusedPointRingColor | Focused point ring color hex value or an array of RGBA values | `white` |
@@ -26,6 +27,8 @@ import { Meta } from "@storybook/blocks";
 | linkGreyoutOpacity | Greyed out link opacity value when the selection is active | `0.1` |
 | linkWidth | 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` | `1` |
 | linkWidthScale | Scale factor for the link width | `1` |
+| hoveredLinkColor | 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 | `undefined` |
+| hoveredLinkWidthIncrease | Number of pixels to add to the link width when hovered | `5` |
 | scaleLinksOnZoom | Increase/decrease link width when zooming | `false` |
 | curvedLinks | If set to true, links are rendered as curved lines. Otherwise as straight lines | `false` |
 | curvedLinkSegments | Number of segments in a curved line | `19` |
@@ -86,11 +89,17 @@ cosmos.gl layout algorithm was inspired by the [d3-force](https://github.com/d3/
 | onSimulationTick | Called on every simulation tick, with the current alpha value and hover information |
 | onSimulationEnd | Called when simulation stops |
 | onSimulationPause | Called when simulation pauses |
-| onSimulationRestart | Called when simulation restarts |
+| onSimulationUnpause | Called when simulation unpauses |
+| onSimulationRestart | **[DEPRECATED]** Called when simulation restarts. Use `onSimulationUnpause` instead |
 | onClick | Called on canvas click with point index and position |
+| onPointClick | Called when a point is clicked |
+| onLinkClick | Called when a link is clicked |
+| onBackgroundClick | Called when the background (empty space) is clicked |
 | onMouseMove | Called on mouse movement with hover info |
 | onPointMouseOver | Called when pointer enters a point |
 | onPointMouseOut | Called when pointer leaves a point |
+| onLinkMouseOver | Called when pointer enters a link |
+| onLinkMouseOut | Called when pointer leaves a link |
 | onZoomStart | Called when zoom/pan starts |
 | onZoom | Called during zoom/pan |
 | onZoomEnd | Called when zoom/pan ends |

package/src/stories/3. api-reference.mdx

@@ -8,11 +8,14 @@ This method sets the [cosmos.gl configuration](../?path=/docs/configuration--doc
 
 * **`config`** (Object): The configuration object adhering to cosmos.gl configuration properties.
 
-### <a name="set_point_positions" href="#set_point_positions">#</a> graph.<b>setPointPositions</b>(<i>pointPositions</i>)
+### <a name="set_point_positions" href="#set_point_positions">#</a> graph.<b>setPointPositions</b>(<i>pointPositions</i>, [<i>dontRescale</i>])
 
 This method sets the positions of points in a cosmos.gl graph using the provided coordinates array.
 
 * **`pointPositions`** (Float32Array): A Float32Array representing the x and y coordinates of points in the format `[x1, y1, x2, y2, ..., xN, yN]`. Each pair represents the coordinates of a single point.
+* **`dontRescale`** (Boolean, optional): For this call only, controls whether to rescale the points.
+  - `true`: Don't rescale the points.
+  - `false` or `undefined` (default): Use the behavior defined by `config.rescalePositions`.
 
 **Example:**
 ```javascript
@@ -246,7 +249,7 @@ graph.render();
 
 In this example, the `linkArrows` array contains three boolean values. The first value `true` sets an arrow on the first link, the second value `false` leaves the second link without an arrow, and the third value `true` sets an arrow on the third link.
 
-### <a name="set_link_strengths" href="#set_link_strengths">#</a> graph.<b>setLinkStrength</b>(<i>linkStrength</i>)
+### <a name="set_link_strength" href="#set_link_strength">#</a> graph.<b>setLinkStrength</b>(<i>linkStrength</i>)
 
 This method sets the strength of the graph links.
 
@@ -298,7 +301,7 @@ This method sets the force strength coefficients for clustering points in the gr
 
 The `render` method renders the graph and, optionally, controls the initial energy of the simulation.
 
-* **`runSimulation`** (number, optional): The higher the value, the more initial energy the simulation will get. Zero value stops the simulation.
+* **`simulationAlpha`** (number, optional): The higher the value, the more initial energy the simulation will get. Zero value stops the simulation.
 
 ### <a name="zoom_to_point_by_index" href="#zoom_to_point_by_index">#</a> graph.<b>zoomToPointByIndex</b>(<i>index</i>, [<i>duration</i>], [<i>scale</i>], [<i>canZoomOut</i>])
 
@@ -508,7 +511,13 @@ Starts the simulation with an optional <i>alpha</i> parameter, which controls th
 
 Pauses the current simulation in the graph.
 
-### <a name="restart" href="#restart">#</a> graph.<b>restart</b>()
+### <a name="unpause" href="#unpause">#</a> graph.<b>unpause</b>()
+
+Unpauses (resumes) the current simulation in the graph.
+
+### <a name="restart" href="#restart">#</a> graph.<b>restart</b>() <b style={{ color: 'orange' }}>[DEPRECATED]</b>
+
+**⚠️ Deprecated:** Use `unpause()` instead. This method will be removed in a future version.
 
 Restarts the current simulation in the graph.
 

package/src/stories/beginners/basic-set-up/index.ts

@@ -38,15 +38,15 @@ export const basicSetUp = (): { graph: Graph; div: HTMLDivElement} => {
     simulationRepulsion: 0.2,
     simulationGravity: 0.1,
     simulationDecay: 100000,
-    onClick: (index: number | undefined): void => {
-      if (index !== undefined) {
-        graph.selectPointByIndex(index)
-        graph.zoomToPointByIndex(index)
-      } else {
-        graph.unselectPoints()
-      }
+    onPointClick: (index: number): void => {
+      graph.selectPointByIndex(index)
+      graph.zoomToPointByIndex(index)
       console.log('Clicked point index: ', index)
     },
+    onBackgroundClick: (): void => {
+      graph.unselectPoints()
+      console.log('Clicked background')
+    },
     attribution: 'visualized with <a href="https://cosmograph.app/" style="color: var(--cosmosgl-attribution-color);" target="_blank">Cosmograph</a>',
   })
 
@@ -71,18 +71,28 @@ export const basicSetUp = (): { graph: Graph; div: HTMLDivElement} => {
     graph.pause()
   }
 
-  function start (): void {
+  function unpause (): void {
     isPaused = false
     pauseButton.textContent = 'Pause'
-    graph.start()
+    // if the graph is at 100% progress, start the graph
+    if (graph.progress === 1) {
+      graph.start()
+    } else {
+      graph.unpause()
+    }
   }
 
   function togglePause (): void {
-    if (isPaused) start()
+    if (isPaused) unpause()
     else pause()
   }
 
   pauseButton.addEventListener('click', togglePause)
+  graph.setConfig({
+    onSimulationEnd: (): void => {
+      pause()
+    },
+  })
 
   // Zoom and Select
   function getRandomPointIndex (): number {