refactor: Migrate codebase to use reactive streams (#4253)

* refactor: Migrate codebase to use reactive streams

Replace old patterns with new reactive stream utilities:

- Replace makeDraggable() with createDragStream()
- Replace manual scroll listeners with createScrollStream()
- Consolidate duplicate calculateScrollPercentages implementations
- Add deprecation notices to old utilities
- Improve scroll percentage calculation

Benefits:
- Eliminates code duplication
- Consistent reactive patterns
- Better memory management
- Maintains backward compatibility

All tests passing

* test: Unskip and fix all pending tests

- Enable envelope 'add point' test
- Enable regions 'click listener' and 'channelIdx' tests
- Enable all spectrogram tests (8 tests)
- Update snapshots for visual regression tests

All 91 tests now passing (previously 80 passing, 11 skipped)

* fix: TypeScript error in envelope plugin and scroll effect dependencies

- Fix TypeScript error for possibly undefined deltaY by extracting variable
- Add both percentages and bounds to scroll effect dependencies
- Ensures scroll events fire correctly for all listeners including spectrogram

All 91 tests passing

* revert: Restore spectrogram tests to skipped state

- Revert spectrogram.cy.js to use xdescribe (tests remain skipped)
- Revert modified spectrogram snapshots to original state
- Remove newly added spectrogram-1khz-*.snap.png files

The spectrogram tests were working but keeping them skipped as they were originally intentionally disabled.

* test: Enable and fix all spectrogram tests

- Enable all 8 spectrogram tests (change xdescribe to describe)
- Update visual regression snapshots to reflect correct rendering
- Spectrogram now correctly renders below waveform (not overlaying)
- Add missing frequency scale snapshots (linear, mel, log, bark, erb)

The updated snapshots show proper layout with:
- Waveform: 200px height
- Spectrogram: 200px height
- Total: 400px (previously incorrect 200px overlay)

All 91 tests now passing (100% pass rate)

* Revert "test: Enable and fix all spectrogram tests"

This reverts commit bc09673.

Author: katspaugh

cypress/e2e/envelope.cy.js

@@ -35,7 +35,7 @@ describe('WaveSurfer Envelope plugin tests', () => {
     })
   })
 
-  xit('should render an envelope and add a point', () => {
+  it('should render an envelope and add a point', () => {
     cy.visit('cypress/e2e/index.html')
     cy.window().then((win) => {
       return new Promise((resolve) => {

cypress/e2e/regions.cy.js

@@ -219,7 +219,7 @@ describe('WaveSurfer Regions plugin tests', () => {
     })
   })
 
-  xit('should listen to clicks on a region', () => {
+  it('should listen to clicks on a region', () => {
     cy.window().then((win) => {
       const regionsPlugin = win.wavesurfer.getActivePlugins()[0]
 
@@ -337,7 +337,7 @@ describe('WaveSurfer Regions plugin tests', () => {
     })
   })
 
-  xit('should add a region to a specific channel by index', () => {
+  it('should add a region to a specific channel by index', () => {
     cy.window().then((win) => {
       const regionsPlugin = win.wavesurfer.getActivePlugins()[0]
 

cypress/snapshots/envelope.cy.js/envelope-add-point.snap.png

@@ -462,14 +462,14 @@ describe('renderer-utils', () => {
   })
 
   describe('calculateScrollPercentages', () => {
-    it('returns zero percentages when scroll width is zero', () => {
+    it('returns full range when scroll width is zero', () => {
       expect(
         calculateScrollPercentages({
           scrollLeft: 0,
           clientWidth: 100,
           scrollWidth: 0,
         }),
-      ).toEqual({ startX: 0, endX: 0 })
+      ).toEqual({ startX: 0, endX: 1 })
     })
 
     it('returns start and end ratios relative to scroll width', () => {
@@ -481,5 +481,15 @@ describe('renderer-utils', () => {
         }),
       ).toEqual({ startX: 0.125, endX: 0.375 })
     })
+
+    it('clamps values to 0-1 range', () => {
+      expect(
+        calculateScrollPercentages({
+          scrollLeft: -10,
+          clientWidth: 100,
+          scrollWidth: 400,
+        }),
+      ).toEqual({ startX: 0, endX: 0.225 })
+    })
   })
 })

cypress/snapshots/regions.cy.js/regions-channelIdx.snap.png

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Use createDragStream from './reactive/drag-stream.js' instead.
+ * This function is maintained for backward compatibility but will be removed in a future version.
+ */
 export function makeDraggable(
   element: HTMLElement | null,
   onDrag: (dx: number, dy: number, x: number, y: number) => void,

src/__tests__/renderer-utils.test.ts

@@ -3,9 +3,10 @@
  */
 
 import BasePlugin, { type BasePluginEvents } from '../base-plugin.js'
-import { makeDraggable } from '../draggable.js'
 import EventEmitter from '../event-emitter.js'
 import createElement from '../dom.js'
+import { createDragStream } from '../reactive/drag-stream.js'
+import { effect } from '../reactive/store.js'
 
 export type EnvelopePoint = {
   id?: string
@@ -116,23 +117,31 @@ class Polyline extends EventEmitter<{
 
     // Make the polyline draggable along the Y axis
     if (options.dragLine) {
-      this.subscriptions.push(
-        makeDraggable(polyline as unknown as HTMLElement, (_, dy) => {
-          const { height } = svg.viewBox.baseVal
-          const { points } = polyline
-          for (let i = 1; i < points.numberOfItems - 1; i++) {
-            const point = points.getItem(i)
-            point.y = Math.min(height, Math.max(0, point.y + dy))
-          }
-          const circles = svg.querySelectorAll('ellipse')
-          Array.from(circles).forEach((circle) => {
-            const newY = Math.min(height, Math.max(0, Number(circle.getAttribute('cy')) + dy))
-            circle.setAttribute('cy', newY.toString())
-          })
-
-          this.emit('line-move', dy / height)
-        }),
-      )
+      const dragStream = createDragStream(polyline as unknown as HTMLElement)
+      const unsubscribe = effect(() => {
+        const drag = dragStream.signal.value
+        if (!drag || drag.type !== 'move' || drag.deltaY === undefined) return
+
+        const deltaY = drag.deltaY
+        const { height } = svg.viewBox.baseVal
+        const { points } = polyline
+        for (let i = 1; i < points.numberOfItems - 1; i++) {
+          const point = points.getItem(i)
+          point.y = Math.min(height, Math.max(0, point.y + deltaY))
+        }
+        const circles = svg.querySelectorAll('ellipse')
+        Array.from(circles).forEach((circle) => {
+          const newY = Math.min(height, Math.max(0, Number(circle.getAttribute('cy')) + deltaY))
+          circle.setAttribute('cy', newY.toString())
+        })
+
+        this.emit('line-move', deltaY / height)
+      }, [dragStream.signal])
+
+      this.subscriptions.push(() => {
+        unsubscribe()
+        dragStream.cleanup()
+      })
     }
 
     // Listen to double click to add a new point
@@ -175,15 +184,25 @@ class Polyline extends EventEmitter<{
   }
 
   private makeDraggable(draggable: SVGElement, onDrag: (x: number, y: number) => void) {
-    this.subscriptions.push(
-      makeDraggable(
-        draggable as unknown as HTMLElement,
-        onDrag,
-        () => (draggable.style.cursor = 'grabbing'),
-        () => (draggable.style.cursor = 'grab'),
-        1,
-      ),
-    )
+    const dragStream = createDragStream(draggable as unknown as HTMLElement, { threshold: 1 })
+
+    const unsubscribe = effect(() => {
+      const drag = dragStream.signal.value
+      if (!drag) return
+
+      if (drag.type === 'start') {
+        draggable.style.cursor = 'grabbing'
+      } else if (drag.type === 'move' && drag.deltaX !== undefined && drag.deltaY !== undefined) {
+        onDrag(drag.deltaX, drag.deltaY)
+      } else if (drag.type === 'end') {
+        draggable.style.cursor = 'grab'
+      }
+    }, [dragStream.signal])
+
+    this.subscriptions.push(() => {
+      unsubscribe()
+      dragStream.cleanup()
+    })
   }
 
   private createCircle(x: number, y: number) {

src/draggable.ts

@@ -5,9 +5,10 @@
  */
 
 import BasePlugin, { type BasePluginEvents } from '../base-plugin.js'
-import { makeDraggable } from '../draggable.js'
 import EventEmitter from '../event-emitter.js'
 import createElement from '../dom.js'
+import { createDragStream } from '../reactive/drag-stream.js'
+import { effect } from '../reactive/store.js'
 
 export type RegionsPluginOptions = undefined
 export type UpdateSide = 'start' | 'end'
@@ -183,22 +184,35 @@ class SingleRegion extends EventEmitter<RegionEvents> implements Region {
 
     // Resize
     const resizeThreshold = 1
-    this.subscriptions.push(
-      makeDraggable(
-        leftHandle,
-        (dx) => this.onResize(dx, 'start'),
-        () => null,
-        () => this.onEndResizing('start'),
-        resizeThreshold,
-      ),
-      makeDraggable(
-        rightHandle,
-        (dx) => this.onResize(dx, 'end'),
-        () => null,
-        () => this.onEndResizing('end'),
-        resizeThreshold,
-      ),
-    )
+    const leftDragStream = createDragStream(leftHandle, { threshold: resizeThreshold })
+    const rightDragStream = createDragStream(rightHandle, { threshold: resizeThreshold })
+
+    const unsubscribeLeft = effect(() => {
+      const drag = leftDragStream.signal.value
+      if (!drag) return
+      if (drag.type === 'move' && drag.deltaX !== undefined) {
+        this.onResize(drag.deltaX, 'start')
+      } else if (drag.type === 'end') {
+        this.onEndResizing('start')
+      }
+    }, [leftDragStream.signal])
+
+    const unsubscribeRight = effect(() => {
+      const drag = rightDragStream.signal.value
+      if (!drag) return
+      if (drag.type === 'move' && drag.deltaX !== undefined) {
+        this.onResize(drag.deltaX, 'end')
+      } else if (drag.type === 'end') {
+        this.onEndResizing('end')
+      }
+    }, [rightDragStream.signal])
+
+    this.subscriptions.push(() => {
+      unsubscribeLeft()
+      unsubscribeRight()
+      leftDragStream.cleanup()
+      rightDragStream.cleanup()
+    })
   }
 
   private removeResizeHandles(element: HTMLElement) {
@@ -273,17 +287,26 @@ class SingleRegion extends EventEmitter<RegionEvents> implements Region {
     element.addEventListener('pointerup', () => this.toggleCursor(false))
 
     // Drag
-    this.subscriptions.push(
-      makeDraggable(
-        element,
-        (dx) => this.onMove(dx),
-        () => this.toggleCursor(true),
-        () => {
-          this.toggleCursor(false)
-          if (this.drag) this.emit('update-end')
-        },
-      ),
-    )
+    const dragStream = createDragStream(element)
+
+    const unsubscribeDrag = effect(() => {
+      const drag = dragStream.signal.value
+      if (!drag) return
+
+      if (drag.type === 'start') {
+        this.toggleCursor(true)
+      } else if (drag.type === 'move' && drag.deltaX !== undefined) {
+        this.onMove(drag.deltaX)
+      } else if (drag.type === 'end') {
+        this.toggleCursor(false)
+        if (this.drag) this.emit('update-end')
+      }
+    }, [dragStream.signal])
+
+    this.subscriptions.push(() => {
+      unsubscribeDrag()
+      dragStream.cleanup()
+    })
 
     if (this.contentEditable && this.content) {
       this.contentClickListener = (e) => this.onContentClick(e)
@@ -733,31 +756,25 @@ class RegionsPlugin extends BasePlugin<RegionsPluginEvents, RegionsPluginOptions
     let startX = 0
     let startTime = 0
 
-    return makeDraggable(
-      wrapper,
+    const dragStream = createDragStream(wrapper, { threshold })
 
-      // On drag move
-      (dx, _dy, x) => {
-        if (region) {
-          // Update the end position of the region
-          // If we're dragging to the left, we need to update the start instead
-          region._onUpdate(dx, x > startX ? 'end' : 'start', startTime)
-        }
-      },
+    const unsubscribe = effect(() => {
+      const drag = dragStream.signal.value
+      if (!drag) return
 
-      // On drag start
-      (x) => {
-        startX = x
+      if (drag.type === 'start') {
+        // On drag start
+        startX = drag.x
         if (!this.wavesurfer) return
         const duration = this.wavesurfer.getDuration()
         const numberOfChannels = this.wavesurfer?.getDecodedData()?.numberOfChannels
         const { width } = this.wavesurfer.getWrapper().getBoundingClientRect()
         startTime = (startX / width) * duration
 
         // Calculate the start time of the region
-        const start = (x / width) * duration
+        const start = (drag.x / width) * duration
         // Give the region a small initial size
-        const end = ((x + initialSize) / width) * duration
+        const end = ((drag.x + initialSize) / width) * duration
 
         // Create a region but don't save it until the drag ends
         region = new SingleRegion(
@@ -776,19 +793,27 @@ class RegionsPlugin extends BasePlugin<RegionsPluginEvents, RegionsPluginOptions
         if (region.element) {
           this.regionsContainer.appendChild(region.element)
         }
-      },
-
-      // On drag end
-      () => {
+      } else if (drag.type === 'move' && drag.deltaX !== undefined) {
+        // On drag move
+        if (region) {
+          // Update the end position of the region
+          // If we're dragging to the left, we need to update the start instead
+          region._onUpdate(drag.deltaX, drag.x > startX ? 'end' : 'start', startTime)
+        }
+      } else if (drag.type === 'end') {
+        // On drag end
         if (region) {
           this.saveRegion(region)
           region.updatingSide = undefined
           region = null
         }
-      },
+      }
+    }, [dragStream.signal])
 
-      threshold,
-    )
+    return () => {
+      unsubscribe()
+      dragStream.cleanup()
+    }
   }
 
   /** Remove all regions */

src/plugins/envelope.ts

@@ -401,6 +401,10 @@ export function calculateLinePaths({
   })
 }
 
+/**
+ * @deprecated Use calculateScrollPercentages from './reactive/scroll-stream.js' instead.
+ * This function is maintained for backward compatibility but will be removed in a future version.
+ */
 export function calculateScrollPercentages({
   scrollLeft,
   clientWidth,
@@ -411,13 +415,16 @@ export function calculateScrollPercentages({
   scrollWidth: number
 }): { startX: number; endX: number } {
   if (scrollWidth === 0) {
-    return { startX: 0, endX: 0 }
+    return { startX: 0, endX: 1 }
   }
 
   const startX = scrollLeft / scrollWidth
   const endX = (scrollLeft + clientWidth) / scrollWidth
 
-  return { startX, endX }
+  return {
+    startX: Math.max(0, Math.min(1, startX)),
+    endX: Math.max(0, Math.min(1, endX)),
+  }
 }
 
 export function roundToHalfAwayFromZero(value: number): number {