waveform-analysis 0.1.47 → 0.1.50

package/src/core/samplingReferenceValues.ts

@@ -0,0 +1,169 @@
+import type { ReferenceSamplingStrategy } from './samplingReference'
+import type { WorkerSamplingOutput } from './workerSampling/protocol'
+
+interface Bounds {
+  start: number
+  end: number
+}
+
+function targetCount(value: number, pointCount: number) {
+  if (pointCount === 0) return 0
+  if (!Number.isFinite(value)) return pointCount
+  return Math.min(pointCount, Math.max(1, Math.floor(value)))
+}
+
+function bucketBounds(bucket: number, bucketCount: number, start: number, end: number): Bounds {
+  const span = end - start
+  return {
+    start: start + Math.floor((bucket * span) / bucketCount),
+    end: start + Math.floor(((bucket + 1) * span) / bucketCount),
+  }
+}
+
+function addUnique(indexes: number[], index: number) {
+  if (indexes[indexes.length - 1] !== index) indexes.push(index)
+}
+
+function withEndpoints(length: number, target: number, selectInterior: () => number[]) {
+  if (length <= target) return Array.from({ length }, (_, index) => index)
+  if (target === 1) return [0]
+  if (target === 2) return [0, length - 1]
+  const indexes = [0]
+  selectInterior().forEach((index) => addUnique(indexes, index))
+  addUnique(indexes, length - 1)
+  return indexes
+}
+
+function extremaIndexes(y: Float64Array, target: number, strategy: 'min' | 'max' | 'minmax') {
+  const bucketCount = strategy === 'minmax' ? Math.floor((target - 2) / 2) : Math.max(0, target - 2)
+  return withEndpoints(y.length, target, () => {
+    if (!bucketCount) return []
+    const result: number[] = []
+    for (let bucket = 0; bucket < bucketCount; bucket += 1) {
+      const bounds = bucketBounds(bucket, bucketCount, 1, y.length - 1)
+      let minimum = bounds.start
+      let maximum = bounds.start
+      for (let index = bounds.start + 1; index < bounds.end; index += 1) {
+        if (y[index]! < y[minimum]!) minimum = index
+        if (y[index]! > y[maximum]!) maximum = index
+      }
+      if (strategy === 'min') addUnique(result, minimum)
+      else if (strategy === 'max') addUnique(result, maximum)
+      else if (minimum <= maximum) {
+        addUnique(result, minimum)
+        addUnique(result, maximum)
+      } else {
+        addUnique(result, maximum)
+        addUnique(result, minimum)
+      }
+    }
+    return result
+  })
+}
+
+function peakIndexes(y: Float64Array, target: number) {
+  const bucketCount = Math.floor((target - 2) / 4)
+  return withEndpoints(y.length, target, () => {
+    if (!bucketCount) return []
+    const result: number[] = []
+    for (let bucket = 0; bucket < bucketCount; bucket += 1) {
+      const bounds = bucketBounds(bucket, bucketCount, 1, y.length - 1)
+      let minimum = bounds.start
+      let maximum = bounds.start
+      for (let index = bounds.start + 1; index < bounds.end; index += 1) {
+        if (y[index]! < y[minimum]!) minimum = index
+        if (y[index]! > y[maximum]!) maximum = index
+      }
+      ;[bounds.start, minimum, maximum, bounds.end - 1]
+        .sort((left, right) => left - right)
+        .forEach((index) => addUnique(result, index))
+    }
+    return result
+  })
+}
+
+function lttbIndexes(x: Float64Array, y: Float64Array, target: number) {
+  return withEndpoints(x.length, target, () => {
+    const bucketSize = (x.length - 2) / (target - 2)
+    const result: number[] = []
+    let previous = 0
+    for (let bucket = 0; bucket < target - 2; bucket += 1) {
+      const averageStart = Math.min(x.length, Math.floor((bucket + 1) * bucketSize) + 1)
+      const averageEnd = Math.min(x.length, Math.floor((bucket + 2) * bucketSize) + 1)
+      let averageX = 0
+      let averageY = 0
+      for (let index = averageStart; index < averageEnd; index += 1) {
+        averageX += x[index]!
+        averageY += y[index]!
+      }
+      const averageCount = averageEnd - averageStart
+      if (averageCount) {
+        averageX /= averageCount
+        averageY /= averageCount
+      } else {
+        averageX = x[x.length - 1]!
+        averageY = y[y.length - 1]!
+      }
+      const bounds = bucketBounds(bucket, target - 2, 1, x.length - 1)
+      let selected = bounds.start
+      let maximumArea = -1
+      for (let index = bounds.start; index < bounds.end; index += 1) {
+        const area = Math.abs(
+          (x[previous]! - averageX) * (y[index]! - y[previous]!) -
+            (x[previous]! - x[index]!) * (averageY - y[previous]!),
+        )
+        if (area > maximumArea) {
+          maximumArea = area
+          selected = index
+        }
+      }
+      result.push(selected)
+      previous = selected
+    }
+    return result
+  })
+}
+
+function aggregates(
+  x: Float64Array,
+  y: Float64Array,
+  target: number,
+  strategy: 'average' | 'sum',
+): WorkerSamplingOutput {
+  const count = targetCount(target, x.length)
+  const outputX = new Float64Array(count)
+  const outputY = new Float64Array(count)
+  for (let bucket = 0; bucket < count; bucket += 1) {
+    const bounds = bucketBounds(bucket, count, 0, x.length)
+    for (let index = bounds.start; index < bounds.end; index += 1) {
+      outputX[bucket] += x[index]!
+      outputY[bucket] += y[index]!
+    }
+    const size = bounds.end - bounds.start
+    outputX[bucket] /= size
+    if (strategy === 'average') outputY[bucket] /= size
+  }
+  return { kind: 'aggregates', x: outputX, y: outputY }
+}
+
+/** Numeric JavaScript fallback matching the WASM source-index and aggregate contracts. */
+export function sampleWaveformReferenceValues(
+  x: Float64Array,
+  y: Float64Array,
+  strategy: ReferenceSamplingStrategy,
+  targetPointCount: number,
+): WorkerSamplingOutput {
+  if (x.length !== y.length) throw new Error('x and y must have the same length')
+  if (strategy === 'average' || strategy === 'sum')
+    return aggregates(x, y, targetPointCount, strategy)
+  const target = targetCount(targetPointCount, x.length)
+  const indexes =
+    strategy === 'none' || x.length <= target
+      ? Array.from({ length: x.length }, (_, index) => index)
+      : strategy === 'peak'
+        ? peakIndexes(y, target)
+        : strategy === 'lttb'
+          ? lttbIndexes(x, y, target)
+          : extremaIndexes(y, target, strategy)
+  return { kind: 'source-indexes', sourceIndexes: Uint32Array.from(indexes) }
+}

package/src/core/samplingReferenceVectors.ts

@@ -0,0 +1,46 @@
+import type { WaveformPoint } from '../types'
+import type { ReferenceSamplingStrategy } from './samplingReference'
+
+/** Stable source data shared by the TypeScript reference and future WASM conformance suites. */
+export const REFERENCE_SAMPLING_POINTS: readonly WaveformPoint[] = [
+  { x: 0, y: 4 },
+  { x: 1, y: 1 },
+  { x: 2, y: 8 },
+  { x: 3, y: 2 },
+  { x: 4, y: 7 },
+  { x: 5, y: 0 },
+  { x: 6, y: 9 },
+  { x: 7, y: 3 },
+]
+
+export interface SourceIndexSamplingVector {
+  strategy: Exclude<ReferenceSamplingStrategy, 'average' | 'sum'>
+  targetPointCount: number
+  expectedSourceIndexes: readonly number[]
+}
+
+export const REFERENCE_SOURCE_INDEX_VECTORS: readonly SourceIndexSamplingVector[] = [
+  { strategy: 'none', targetPointCount: 3, expectedSourceIndexes: [0, 1, 2, 3, 4, 5, 6, 7] },
+  { strategy: 'peak', targetPointCount: 6, expectedSourceIndexes: [0, 1, 5, 6, 7] },
+  { strategy: 'min', targetPointCount: 6, expectedSourceIndexes: [0, 1, 3, 4, 5, 7] },
+  { strategy: 'max', targetPointCount: 6, expectedSourceIndexes: [0, 1, 2, 4, 6, 7] },
+  { strategy: 'minmax', targetPointCount: 6, expectedSourceIndexes: [0, 1, 2, 5, 6, 7] },
+  { strategy: 'lttb', targetPointCount: 5, expectedSourceIndexes: [0, 2, 3, 6, 7] },
+]
+
+export interface AggregateSamplingVector {
+  strategy: Extract<ReferenceSamplingStrategy, 'average' | 'sum'>
+  targetPointCount: number
+  expectedX: readonly number[]
+  expectedY: readonly number[]
+}
+
+export const REFERENCE_AGGREGATE_VECTORS: readonly AggregateSamplingVector[] = [
+  {
+    strategy: 'average',
+    targetPointCount: 3,
+    expectedX: [0.5, 3, 6],
+    expectedY: [2.5, 17 / 3, 4],
+  },
+  { strategy: 'sum', targetPointCount: 3, expectedX: [0.5, 3, 6], expectedY: [5, 17, 12] },
+]

package/src/core/wasmSampling.test.ts

@@ -0,0 +1,205 @@
+/// <reference types="node" />
+
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+import { beforeAll, describe, expect, it } from 'vitest'
+
+import { sampleWaveformReference } from './samplingReference'
+import {
+  REFERENCE_AGGREGATE_VECTORS,
+  REFERENCE_SAMPLING_POINTS,
+  REFERENCE_SOURCE_INDEX_VECTORS,
+} from './samplingReferenceVectors'
+import {
+  calculateWasmRange,
+  createInitializedWasmSamplingBackend,
+  findWasmVisibleRange,
+  initializeWasmSampling,
+  sampleWaveformWasm,
+} from './wasmSampling'
+
+const x = Float64Array.from(REFERENCE_SAMPLING_POINTS, (point) => point.x)
+const y = Float64Array.from(REFERENCE_SAMPLING_POINTS, (point) => point.y)
+
+describe('sampleWaveformWasm', () => {
+  beforeAll(async () => {
+    await initializeWasmSampling(
+      await readFile(resolve(process.cwd(), 'wasm/pkg/waveform_sampling_wasm_bg.wasm')),
+    )
+  })
+
+  it('matches the shared source-index vectors and TypeScript reference', async () => {
+    for (const vector of REFERENCE_SOURCE_INDEX_VECTORS) {
+      const wasm = await sampleWaveformWasm({ x, y, ...vector })
+      const reference = sampleWaveformReference({
+        points: REFERENCE_SAMPLING_POINTS,
+        strategy: vector.strategy,
+        targetPointCount: vector.targetPointCount,
+      })
+
+      expect(wasm.kind).toBe('source-indexes')
+      expect(reference.kind).toBe('source-indexes')
+      if (wasm.kind === 'source-indexes' && reference.kind === 'source-indexes') {
+        expect(Array.from(wasm.sourceIndexes)).toEqual(vector.expectedSourceIndexes)
+        expect(Array.from(wasm.sourceIndexes)).toEqual(Array.from(reference.sourceIndexes))
+      }
+    }
+  })
+
+  it('matches the shared aggregate vectors and TypeScript reference', async () => {
+    for (const vector of REFERENCE_AGGREGATE_VECTORS) {
+      const wasm = await sampleWaveformWasm({ x, y, ...vector })
+      const reference = sampleWaveformReference({
+        points: REFERENCE_SAMPLING_POINTS,
+        strategy: vector.strategy,
+        targetPointCount: vector.targetPointCount,
+      })
+
+      expect(wasm.kind).toBe('aggregates')
+      expect(reference.kind).toBe('aggregates')
+      if (wasm.kind === 'aggregates' && reference.kind === 'aggregates') {
+        expect(Array.from(wasm.x)).toEqual(vector.expectedX)
+        expect(Array.from(wasm.y)).toEqual(vector.expectedY)
+        expect(Array.from(wasm.x)).toEqual(Array.from(reference.x))
+        expect(Array.from(wasm.y)).toEqual(Array.from(reference.y))
+      }
+    }
+  })
+
+  it('preserves reference filtering, stable sorting, and original source indexes', async () => {
+    const wasm = await sampleWaveformWasm({
+      x: Float64Array.from([2, Number.NaN, 1, 1, 3]),
+      y: Float64Array.from([20, 99, 10, 11, Number.POSITIVE_INFINITY]),
+      strategy: 'none',
+      targetPointCount: 1,
+    })
+
+    expect(wasm).toEqual({ kind: 'source-indexes', sourceIndexes: Uint32Array.from([2, 3, 0]) })
+  })
+
+  it('calculates full domains and normalized visible ranges', async () => {
+    const range = await calculateWasmRange(
+      Float64Array.from([2, Number.NaN, 1, 1, 3]),
+      Float64Array.from([20, 99, 10, 11, Number.POSITIVE_INFINITY]),
+    )
+    const visible = await findWasmVisibleRange(
+      Float64Array.from([2, Number.NaN, 1, 1, 3]),
+      Float64Array.from([20, 99, 10, 11, Number.POSITIVE_INFINITY]),
+      [1, 1],
+    )
+
+    expect(range).toEqual({ x: [1, 2], y: [10, 20] })
+    expect(visible).toEqual([0, 2])
+    await expect(calculateWasmRange(Float64Array.of(0), new Float64Array())).rejects.toThrow(
+      'x and y must have the same length',
+    )
+  })
+
+  it('matches the reference across strategy and target boundary cases', async () => {
+    const points = [
+      { x: 3, y: 3 },
+      { x: 1, y: -2 },
+      { x: 1, y: 4 },
+      { x: Number.NaN, y: 6 },
+      { x: 2, y: -1 },
+      { x: 4, y: Number.POSITIVE_INFINITY },
+      { x: 5, y: 0 },
+    ]
+    const caseX = Float64Array.from(points, (point) => point.x)
+    const caseY = Float64Array.from(points, (point) => point.y)
+    const strategies = ['none', 'peak', 'lttb', 'average', 'min', 'max', 'minmax', 'sum'] as const
+    const targets = [0, 1, 2, 3, 6, 20, Number.POSITIVE_INFINITY]
+
+    for (const strategy of strategies) {
+      for (const targetPointCount of targets) {
+        const wasm = await sampleWaveformWasm({
+          x: caseX,
+          y: caseY,
+          strategy,
+          targetPointCount,
+        })
+        const reference = sampleWaveformReference({ points, strategy, targetPointCount })
+
+        expect(wasm.kind).toBe(reference.kind)
+        if (wasm.kind === 'source-indexes' && reference.kind === 'source-indexes') {
+          expect(Array.from(wasm.sourceIndexes)).toEqual(Array.from(reference.sourceIndexes))
+        }
+        if (wasm.kind === 'aggregates' && reference.kind === 'aggregates') {
+          expect(Array.from(wasm.x)).toEqual(Array.from(reference.x))
+          expect(Array.from(wasm.y)).toEqual(Array.from(reference.y))
+        }
+      }
+    }
+  })
+
+  it('rejects coordinate arrays with unequal lengths', async () => {
+    await expect(
+      sampleWaveformWasm({
+        x: Float64Array.of(0),
+        y: new Float64Array(),
+        strategy: 'none',
+        targetPointCount: 1,
+      }),
+    ).rejects.toThrow('x and y must have the same length')
+  })
+
+  it('keeps a bounded dataset index in WASM for unaligned viewport queries and releases it', () => {
+    const backend = createInitializedWasmSamplingBackend()
+    const handle = backend.registerDataset(x, y, 1024 * 1024)
+    const visible = REFERENCE_SAMPLING_POINTS.slice(2, 9)
+
+    for (const strategy of ['peak', 'min', 'max', 'minmax'] as const) {
+      const actual = backend.sampleDataset(handle, 2, 9, strategy, 6)
+      const expected = sampleWaveformReference({
+        points: visible,
+        strategy,
+        targetPointCount: 6,
+      })
+      expect(actual.kind).toBe('source-indexes')
+      expect(expected.kind).toBe('source-indexes')
+      if (actual.kind === 'source-indexes' && expected.kind === 'source-indexes') {
+        expect(Array.from(actual.sourceIndexes)).toEqual(
+          Array.from(expected.sourceIndexes, (index) => index + 2),
+        )
+      }
+    }
+
+    const aggregates = backend.sampleDataset(handle, 2, 9, 'average', 4)
+    const expectedAggregates = sampleWaveformReference({
+      points: visible,
+      strategy: 'average',
+      targetPointCount: 4,
+    })
+    expect(aggregates.kind).toBe('aggregates')
+    expect(expectedAggregates.kind).toBe('aggregates')
+    if (aggregates.kind === 'aggregates' && expectedAggregates.kind === 'aggregates') {
+      aggregates.x.forEach((value, index) =>
+        expect(value).toBeCloseTo(expectedAggregates.x[index]!, 12),
+      )
+      aggregates.y.forEach((value, index) =>
+        expect(value).toBeCloseTo(expectedAggregates.y[index]!, 12),
+      )
+    }
+    expect(backend.datasetIndexBytes(handle)).toBeGreaterThan(0)
+    backend.disposeDataset(handle)
+    expect(backend.datasetIndexBytes(handle)).toBe(0)
+  })
+
+  it('registers evenly sampled values without an explicit X column', () => {
+    const backend = createInitializedWasmSamplingBackend()
+    const handle = backend.registerSamples(
+      new Float64Array([1, 9, 2]),
+      new Uint32Array([0, 2, 3]),
+      10,
+      2,
+      1024 * 1024,
+    )
+
+    expect(backend.sampleDataset(handle, 0, 3, 'max', 3)).toMatchObject({
+      kind: 'source-indexes',
+      sourceIndexes: Uint32Array.from([0, 1, 2]),
+    })
+    backend.disposeDataset(handle)
+  })
+})

package/src/core/wasmSampling.ts

@@ -0,0 +1,230 @@
+import initWasm, {
+  calculate_range,
+  dataset_index_bytes,
+  dispose_all_datasets,
+  dispose_dataset,
+  find_visible_range,
+  register_dataset,
+  register_sample_dataset,
+  sample_aggregates,
+  sample_dataset_aggregates,
+  sample_dataset_indexes,
+  sample_indexes,
+} from '../../wasm/pkg/waveform_sampling_wasm'
+import type { InitInput } from '../../wasm/pkg/waveform_sampling_wasm'
+
+import type { ReferenceSamplingStrategy } from './samplingReference'
+import type { WorkerSamplingBackend, WorkerSamplingOutput } from './workerSampling/protocol'
+
+export type WasmSamplingStrategy = ReferenceSamplingStrategy
+
+export interface WasmSamplingRequest {
+  x: Float64Array
+  y: Float64Array
+  strategy: WasmSamplingStrategy
+  targetPointCount: number
+}
+
+export interface WasmSourceIndexSamplingResult {
+  kind: 'source-indexes'
+  sourceIndexes: Uint32Array
+}
+
+export interface WasmAggregateSamplingResult {
+  kind: 'aggregates'
+  x: Float64Array
+  y: Float64Array
+}
+
+export type WasmSamplingResult = WasmSourceIndexSamplingResult | WasmAggregateSamplingResult
+
+export interface WasmDatasetSamplingBackend extends WorkerSamplingBackend {
+  registerDataset(x: Float64Array, y: Float64Array, indexMaxBytes?: number): number
+  registerSamples(
+    y: Float64Array,
+    sourceIndexes: Uint32Array | undefined,
+    startTime: number,
+    sampleRate: number,
+    indexMaxBytes?: number,
+  ): number
+  disposeDataset(handle: number): void
+  disposeAllDatasets(): void
+  datasetIndexBytes(handle: number): number
+  sampleDataset(
+    handle: number,
+    start: number,
+    end: number,
+    strategy: WasmSamplingStrategy,
+    targetPointCount: number,
+  ): WorkerSamplingOutput
+}
+
+export interface WasmRangeMetrics {
+  x: [number, number]
+  y: [number, number]
+}
+
+const strategyCodes: Record<WasmSamplingStrategy, number> = {
+  none: 0,
+  peak: 1,
+  lttb: 2,
+  average: 3,
+  min: 4,
+  max: 5,
+  minmax: 6,
+  sum: 7,
+}
+
+let initialization: Promise<void> | undefined
+
+function targetPointCountForWasm(value: number, pointCount: number) {
+  if (pointCount === 0) return 0
+  if (!Number.isFinite(value)) return pointCount
+  return Math.min(pointCount, Math.max(1, Math.floor(value)))
+}
+
+function validateRequest(request: WasmSamplingRequest) {
+  if (request.x.length !== request.y.length) {
+    throw new Error('x and y must have the same length')
+  }
+}
+
+/** Initializes the bundled WebAssembly module once for the current JavaScript realm. */
+export function initializeWasmSampling(input?: InitInput | Promise<InitInput>): Promise<void> {
+  initialization ??= Promise.resolve(initWasm(input)).then(() => undefined)
+  return initialization
+}
+
+/**
+ * Runs the pure numeric sampler on flat Float64Array coordinates. The caller owns source-data
+ * normalization and receives either original input indexes or newly allocated aggregate arrays.
+ */
+export async function sampleWaveformWasm(
+  request: WasmSamplingRequest,
+): Promise<WasmSamplingResult> {
+  validateRequest(request)
+  await initializeWasmSampling()
+  const target = targetPointCountForWasm(request.targetPointCount, request.x.length)
+  const strategy = strategyCodes[request.strategy]
+  if (request.strategy !== 'average' && request.strategy !== 'sum') {
+    return {
+      kind: 'source-indexes',
+      sourceIndexes: sample_indexes(request.x, request.y, strategy, target),
+    }
+  }
+
+  const values = sample_aggregates(request.x, request.y, strategy, target)
+  const x = new Float64Array(values.length / 2)
+  const y = new Float64Array(values.length / 2)
+  for (let index = 0; index < x.length; index += 1) {
+    x[index] = values[index * 2]!
+    y[index] = values[index * 2 + 1]!
+  }
+  return { kind: 'aggregates', x, y }
+}
+
+/**
+ * Creates the synchronous backend used only after this realm has finished WASM initialization.
+ * Worker code calls `initializeWasmSampling` before exposing this backend to its repository.
+ */
+export function createInitializedWasmSamplingBackend(): WasmDatasetSamplingBackend {
+  const aggregateOutput = (values: Float64Array): WasmAggregateSamplingResult => {
+    const x = new Float64Array(values.length / 2)
+    const y = new Float64Array(values.length / 2)
+    for (let index = 0; index < x.length; index += 1) {
+      x[index] = values[index * 2]!
+      y[index] = values[index * 2 + 1]!
+    }
+    return { kind: 'aggregates', x, y }
+  }
+  const backend: WasmDatasetSamplingBackend = {
+    kind: 'wasm',
+    sample({ x, y, strategy, targetPointCount }) {
+      const request = { x, y, strategy, targetPointCount }
+      validateRequest(request)
+      const target = targetPointCountForWasm(request.targetPointCount, request.x.length)
+      if (request.strategy !== 'average' && request.strategy !== 'sum') {
+        return {
+          kind: 'source-indexes' as const,
+          sourceIndexes: sample_indexes(
+            request.x,
+            request.y,
+            strategyCodes[request.strategy],
+            target,
+          ),
+        }
+      }
+      const values = sample_aggregates(
+        request.x,
+        request.y,
+        strategyCodes[request.strategy],
+        target,
+      )
+      return aggregateOutput(values)
+    },
+    registerDataset(x, y, indexMaxBytes) {
+      validateRequest({ x, y, strategy: 'peak', targetPointCount: x.length })
+      return register_dataset(
+        x,
+        y,
+        Math.max(0, Math.min(0xffffffff, Math.floor(indexMaxBytes ?? 8 * 1024 * 1024))),
+      )
+    },
+    registerSamples(y, sourceIndexes, startTime, sampleRate, indexMaxBytes) {
+      return register_sample_dataset(
+        y,
+        sourceIndexes ?? new Uint32Array(),
+        startTime,
+        sampleRate,
+        Math.max(0, Math.min(0xffffffff, Math.floor(indexMaxBytes ?? 8 * 1024 * 1024))),
+      )
+    },
+    disposeDataset(handle) {
+      dispose_dataset(handle)
+    },
+    disposeAllDatasets() {
+      dispose_all_datasets()
+    },
+    datasetIndexBytes(handle) {
+      return dataset_index_bytes(handle)
+    },
+    sampleDataset(handle, start, end, strategy, targetPointCount) {
+      const target = Math.max(0, Math.floor(targetPointCount))
+      if (strategy === 'average' || strategy === 'sum') {
+        return aggregateOutput(
+          sample_dataset_aggregates(handle, start, end, strategyCodes[strategy], target),
+        )
+      }
+      return {
+        kind: 'source-indexes',
+        sourceIndexes: sample_dataset_indexes(handle, start, end, strategyCodes[strategy], target),
+      }
+    },
+  }
+  return backend
+}
+
+/** Calculates domains from valid points without changing the input arrays. */
+export async function calculateWasmRange(
+  x: Float64Array,
+  y: Float64Array,
+): Promise<WasmRangeMetrics | undefined> {
+  if (x.length !== y.length) throw new Error('x and y must have the same length')
+  await initializeWasmSampling()
+  const result = calculate_range(x, y)
+  return result.length === 4
+    ? { x: [result[0]!, result[1]!], y: [result[2]!, result[3]!] }
+    : undefined
+}
+
+/** Locates a half-open visible range in the filtered, stable ascending-X point sequence. */
+export async function findWasmVisibleRange(
+  x: Float64Array,
+  y: Float64Array,
+  domain: [number, number],
+): Promise<[number, number]> {
+  if (x.length !== y.length) throw new Error('x and y must have the same length')
+  await initializeWasmSampling()
+  const result = find_visible_range(x, y, domain[0], domain[1])
+  return [result[0]!, result[1]!]
+}