waveform-analysis 0.1.47 → 0.1.50

package/src/components/core/useWaveformLayout.ts

@@ -1,6 +1,5 @@
 import { scaleLinear, type ZoomTransform } from 'd3'
 import { computed, type ComputedRef, type Ref, type ShallowRef } from 'vue'
-
 import { resolveWaveformRenderingOptions } from '../../core'
 import { paddedDomain } from '../../utils'
 import {
@@ -36,7 +35,6 @@ import type { PreparedWaveformSeries } from './useWaveformData'
 import type { ResolvedWaveformChartProps } from './waveformChartTypes'
 import { applyXDomainStrategy } from './xDomain'
 import type { useWaveformAnnotationInteraction } from '../annotation'
-
 interface LayoutContext {
   props: ResolvedWaveformChartProps
   preparedSeries: ShallowRef<PreparedWaveformSeries[]>
@@ -50,8 +48,8 @@ interface LayoutContext {
   sharedYDomains: Ref<Record<string, [number, number]>>
   independentYDomains: Ref<Record<number, [number, number]>>
   annotationInteraction: ReturnType<typeof useWaveformAnnotationInteraction>
+  linePointOverrides?: ShallowRef<Readonly<Record<string, import('../../types').WaveformPoint[]>>>
 }
-
 export function useWaveformLayout(context: LayoutContext) {
   const {
     props,
@@ -66,6 +64,7 @@ export function useWaveformLayout(context: LayoutContext) {
     sharedYDomains,
     independentYDomains,
     annotationInteraction,
+    linePointOverrides,
   } = context
   const chartSeries = computed<DisplaySeries[]>(() =>
     preparedSeries.value.map((series, index): DisplaySeries => ({
@@ -112,6 +111,12 @@ export function useWaveformLayout(context: LayoutContext) {
   const pagedTracks = computed(() =>
     paginateSeries(chartTracks.value, currentPage.value, gridOptions.value),
   )
+  const layoutTracks = computed(() => {
+    const tracksWithSeries = pagedTracks.value.filter((track) => track.series.length > 0)
+    return gridOptions.value.fillIncompleteLastRow && tracksWithSeries.length > 0
+      ? tracksWithSeries
+      : pagedTracks.value
+  })
   const yAxisMetrics = computed(() => {
     const axisText = chartTracks.value
       .filter((track) => track.visibleSeries.length > 0)
@@ -122,7 +127,7 @@ export function useWaveformLayout(context: LayoutContext) {
         (group) =>
           axisTextMetrics(
             group.domain,
-            true,
+            props.axes?.y?.nice !== false,
             undefined,
             group.seriesList[0]?.unit,
             props.axes?.y?.splitNumber,
@@ -173,6 +178,7 @@ export function useWaveformLayout(context: LayoutContext) {
           props.yDomain,
           props.yDomains,
           props.axes?.y?.splitNumber,
+          props.axes?.y?.nice !== false,
         )
         return {
           left: Math.max(maximum.left, clearance.left),
@@ -223,9 +229,7 @@ export function useWaveformLayout(context: LayoutContext) {
   const hasChartArea = computed(() => innerWidth.value > 0 && innerHeight.value > 0)
   const resolvedXLabel = computed(() => props.xLabel ?? `时间（${props.timeUnit}）`)
   const activeInteractionMode = computed(() => props.interactionMode)
-  const isZoomMode = computed(
-    () => activeInteractionMode.value === 'zoom' || activeInteractionMode.value === undefined,
-  )
+  const isZoomMode = computed(() => activeInteractionMode.value !== 'annotation')
   const sharedXDomain = computed(() => {
     const values: number[] = []
     chartTracks.value.forEach((track) => {
@@ -285,10 +289,10 @@ export function useWaveformLayout(context: LayoutContext) {
       innerHeight.value,
       gridOptions.value,
       props.displayMode,
-      pagedTracks.value.map(Boolean),
+      layoutTracks.value.map(Boolean),
       yAxisLayout.value.horizontalGap,
     )
-    return cells.map((cell, index) => ({ ...cell, series: pagedTracks.value[index] }))
+    return cells.map((cell, index) => ({ ...cell, series: layoutTracks.value[index] }))
   })
   const trackLayouts = computed<TrackLayout[]>(() =>
     buildTrackLayouts({
@@ -315,7 +319,9 @@ export function useWaveformLayout(context: LayoutContext) {
       timeUnit: props.timeUnit,
       xAxisLabelFormatter: props.axes?.x?.labelFormatter,
       yAxisSplitNumber: props.axes?.y?.splitNumber,
+      yAxisNice: props.axes?.y?.nice,
       rendering: renderingOptions.value,
+      linePointOverrides: linePointOverrides?.value,
       hideSecondaryLabels: isCleanView.value || yAxisLayout.value.hideSecondaryLabels,
       yAxisLabelX: yAxisMetrics.value.labelCenterX,
       showCompactEmptyTracks: props.displayMode === 'compact' && hasWaveformData.value,
@@ -364,10 +370,10 @@ export function useWaveformLayout(context: LayoutContext) {
       ? props.frameNumber + trackIndex
       : `${props.frameNumber}-${trackIndex + 1}`
   }
-
   return {
     chartSeries,
     chartTracks,
+    renderingOptions,
     gridOptions,
     pageCount,
     pagedTracks,

package/src/components/core/useWaveformRenderSampling.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest'
+
+import { resolveAutoSelectedMode } from './latestTaskScheduler'
+
+describe('resolveAutoSelectedMode', () => {
+  it('uses the exact threshold when no interaction selection is supplied', () => {
+    expect(resolveAutoSelectedMode(1_000, 1_000, 200)).toBe('raw')
+    expect(resolveAutoSelectedMode(1_001, 1_000, 200)).toBe('sampled')
+  })
+
+  it('keeps the previous mode inside the configured interaction hysteresis band', () => {
+    expect(resolveAutoSelectedMode(1_100, 1_000, 200, 'raw')).toBe('raw')
+    expect(resolveAutoSelectedMode(1_201, 1_000, 200, 'raw')).toBe('sampled')
+    expect(resolveAutoSelectedMode(900, 1_000, 200, 'sampled')).toBe('sampled')
+    expect(resolveAutoSelectedMode(800, 1_000, 200, 'sampled')).toBe('raw')
+  })
+})

package/src/components/core/useWaveformRenderSampling.ts

@@ -0,0 +1,394 @@
+import { computed, onScopeDispose, shallowRef, watch, type ComputedRef, type ShallowRef } from 'vue'
+
+import {
+  type SampleViewportResponse,
+  type WorkerSamplingDiagnostics,
+  type WorkerSamplingSeriesRequest,
+} from '../../core/workerSampling'
+import type { WaveformPoint, WaveformSamplingError } from '../../types'
+import type { ResolvedWaveformRenderingOptions } from '../../core'
+import { pointSourceFromPoints, type WaveformPointSource } from '../../core/waveformPointSource'
+import type { PreparedWaveformSeries } from './useWaveformData'
+import type { DisplaySeries, TrackLayout } from './types'
+import type { ResolvedWaveformChartProps, WaveformChartEmit } from './waveformChartTypes'
+import { createLatestTaskScheduler, resolveAutoSelectedMode } from './latestTaskScheduler'
+import {
+  createWorkerSamplingClient,
+  isDatasetResponse,
+  type WorkerSamplingClient,
+} from './workerSamplingClient'
+
+interface SamplingTarget {
+  series: DisplaySeries
+  source: WaveformPointSource
+  request: WorkerSamplingSeriesRequest
+  visibleRange: { start: number; end: number }
+}
+interface SamplingContext {
+  props: ResolvedWaveformChartProps
+  emit: WaveformChartEmit
+  instanceId: string
+  preparedSeries: ShallowRef<PreparedWaveformSeries[]>
+  sourceTrackLayouts: ComputedRef<TrackLayout[]>
+  renderingOptions: ComputedRef<ResolvedWaveformRenderingOptions>
+  linePointOverrides: ShallowRef<Record<string, WaveformPoint[]>>
+}
+
+const AUTO_MODE_SETTLE_DELAY_MS = 120
+
+function sourcePoints(
+  result: SampleViewportResponse['results'][number],
+  source: WaveformPointSource,
+) {
+  const output = result.output
+  if (!output) return undefined
+  if (output.kind === 'aggregates') {
+    return Array.from(output.x, (x, index) => ({ x, y: output.y[index]! }))
+  }
+  return Array.from(output.sourceIndexes, (index) => source.pointAt(index)).filter(
+    (point): point is WaveformPoint => point !== undefined,
+  )
+}
+
+function rawDiagnostics(target: SamplingTarget, requestId: number): WorkerSamplingDiagnostics {
+  const sampling = target.request
+  const visiblePointCount = target.visibleRange.end - target.visibleRange.start
+  return {
+    seriesId: sampling.seriesId,
+    datasetId: sampling.datasetId,
+    mode: sampling.mode,
+    selectedMode: 'raw',
+    backend: 'raw',
+    strategy: sampling.strategy === 'auto' ? 'peak' : sampling.strategy,
+    sourcePointCount: target.source.length,
+    visiblePointCount,
+    renderedPointCount: visiblePointCount,
+    durationMs: 0,
+    cacheHit: false,
+    requestId,
+    revision: sampling.revision,
+    rawPointLimitExceeded:
+      visiblePointCount > target.request.rawPointLimit! && target.request.mode === 'raw',
+    scheduledRequestCount: 0,
+    coalescedRequestCount: 0,
+    maxPendingRequestCount: 0,
+  }
+}
+
+function fallbackPoints(target: SamplingTarget, maxPointsPerPixel: number) {
+  const { source } = target
+  const { start, end } = target.visibleRange
+  const count = end - start
+  const targetCount = Math.max(1, Math.floor(target.request.plotWidth * maxPointsPerPixel))
+  if (count <= targetCount) return source.pointsInRange(start, end)
+  if (targetCount === 1) return source.pointAt(start) ? [source.pointAt(start)!] : []
+  const points: WaveformPoint[] = []
+  for (let index = 0; index < targetCount; index += 1) {
+    const offset = Math.round((index * (count - 1)) / (targetCount - 1))
+    const point = source.pointAt(start + offset)
+    if (point) points.push(point)
+  }
+  return points
+}
+
+function errorPayload(
+  message: string,
+  mode: WaveformSamplingError['mode'],
+  fallback: WaveformSamplingError['fallback'],
+  seriesIds: string[],
+): WaveformSamplingError {
+  return { message, mode, fallback, seriesIds }
+}
+
+export function useWaveformRenderSampling(context: SamplingContext) {
+  const dataEpoch = shallowRef(0)
+  let client: WorkerSamplingClient | undefined
+  let requestId = 0
+  const revisions = new Map<string, number>()
+  const backendBySeries = new Map<string, WorkerSamplingDiagnostics['backend']>()
+  const selectedModeBySeries = new Map<string, 'raw' | 'sampled'>()
+  const emittedErrors = new Set<string>()
+  const pendingDiagnostics = new Map<string, WorkerSamplingDiagnostics>()
+  const samplingScheduler = createLatestTaskScheduler()
+  let diagnosticsTimer: ReturnType<typeof setTimeout> | undefined
+  let autoModeSettleTimer: ReturnType<typeof setTimeout> | undefined
+  let hasInitialSamplingRun = false
+
+  const targets = computed(() => {
+    const sampling = context.renderingOptions.value.sampling
+    return context.sourceTrackLayouts.value.flatMap((track) => {
+      const domain = track.xScale.domain() as [number, number]
+      return track.seriesList.flatMap((series) => {
+        if (series.lineType === 'none' || track.width <= 0) return []
+        const source = series.source ?? pointSourceFromPoints(series.points)
+        const range = source.visibleRange(domain)
+        const datasetId = `${context.instanceId}:${series.id}`
+        return [
+          {
+            series,
+            source,
+            visibleRange: range,
+            request: {
+              seriesId: series.id,
+              datasetId,
+              revision: revisions.get(datasetId) ?? 1,
+              xDomain: domain,
+              visibleStartIndex: range.start,
+              visibleEndIndex: range.end,
+              plotWidth: track.width,
+              mode: sampling.mode,
+              autoThreshold: sampling.autoThreshold,
+              autoHysteresis: sampling.autoHysteresis,
+              strategy: sampling.strategy,
+              maxPointsPerPixel: sampling.maxPointsPerPixel,
+              rawPointLimit: sampling.rawPointLimit,
+              wasmFailureFallback: sampling.wasmFailureFallback,
+              lineType: series.lineType,
+              pointType: series.pointType,
+              errorBarVisible: series.errorBar.visible,
+              pointMinSpacing: context.renderingOptions.value.pointMinSpacing,
+              errorBarMinSpacing: context.renderingOptions.value.errorBarMinSpacing,
+            },
+          } satisfies SamplingTarget,
+        ]
+      })
+    })
+  })
+  const targetSignature = computed(
+    () =>
+      `${dataEpoch.value}:${targets.value
+        .map(
+          (target) =>
+            `${target.request.datasetId}:${target.request.xDomain.join(',')}:${target.request.plotWidth}:${target.visibleRange.start}:${target.visibleRange.end}:${target.request.mode}:${target.request.autoThreshold}:${target.request.autoHysteresis}:${target.request.strategy}:${target.request.maxPointsPerPixel}:${target.request.rawPointLimit}:${target.request.wasmFailureFallback}:${target.request.lineType}:${target.request.pointType}:${target.request.errorBarVisible}:${target.request.pointMinSpacing}:${target.request.errorBarMinSpacing}`,
+        )
+        .join('|')}`,
+  )
+
+  const flushDiagnostics = () => {
+    diagnosticsTimer = undefined
+    pendingDiagnostics.forEach((diagnostic) => {
+      const previousBackend = backendBySeries.get(diagnostic.seriesId)
+      if (previousBackend && previousBackend !== diagnostic.backend) {
+        context.emit('sampling-backend-change', {
+          seriesId: diagnostic.seriesId,
+          previous: previousBackend,
+          current: diagnostic.backend,
+        })
+      }
+      backendBySeries.set(diagnostic.seriesId, diagnostic.backend)
+      context.emit('sampling-complete', diagnostic)
+    })
+    pendingDiagnostics.clear()
+  }
+  const emitDiagnostics = (diagnostics: WorkerSamplingDiagnostics[]) => {
+    diagnostics.forEach((diagnostic) =>
+      pendingDiagnostics.set(diagnostic.seriesId, {
+        ...diagnostic,
+        scheduledRequestCount: samplingScheduler.metrics.scheduled,
+        coalescedRequestCount: samplingScheduler.metrics.coalesced,
+        maxPendingRequestCount: samplingScheduler.metrics.maxPending,
+      }),
+    )
+    if (!diagnosticsTimer) diagnosticsTimer = setTimeout(flushDiagnostics, 100)
+  }
+
+  const emitErrorOnce = (payload: WaveformSamplingError) => {
+    const key = `${payload.mode}:${payload.fallback}:${payload.message}:${payload.seriesIds.join(',')}`
+    if (emittedErrors.has(key)) return
+    emittedErrors.add(key)
+    context.emit('sampling-error', payload)
+  }
+
+  const registerTargets = async (
+    workerClient: WorkerSamplingClient,
+    batch: SamplingTarget[],
+    token: number,
+  ) => {
+    await Promise.all(
+      batch.map(async (target) => {
+        if (revisions.has(target.request.datasetId)) return
+        const response = await workerClient.send({
+          type: 'register-dataset',
+          requestId: ++requestId,
+          datasetId: target.request.datasetId,
+          revision: 0,
+          dataset: target.source.toWorkerDataset(),
+        })
+        if (
+          !samplingScheduler.isCurrent(token) ||
+          !isDatasetResponse(response) ||
+          (response.status !== 'ok' && response.status !== 'stale-revision')
+        ) {
+          return
+        }
+        revisions.set(target.request.datasetId, response.revision)
+      }),
+    )
+  }
+
+  const runSampling = async (token: number, useAutoHysteresis = false) => {
+    const currentTargets = targets.value
+    const nextOverrides: Record<string, WaveformPoint[]> = { ...context.linePointOverrides.value }
+    const sampledTargets: SamplingTarget[] = []
+    const diagnostics: WorkerSamplingDiagnostics[] = []
+    currentTargets.forEach((target) => {
+      const visiblePointCount = target.visibleRange.end - target.visibleRange.start
+      const previousSelectedMode = useAutoHysteresis
+        ? selectedModeBySeries.get(target.series.id)
+        : undefined
+      const autoRaw =
+        target.request.mode === 'auto' &&
+        resolveAutoSelectedMode(
+          visiblePointCount,
+          target.request.autoThreshold!,
+          target.request.autoHysteresis ?? 0,
+          previousSelectedMode,
+        ) === 'raw'
+      if (target.request.mode === 'raw' || autoRaw) {
+        nextOverrides[target.series.id] = target.source.pointsInRange(
+          target.visibleRange.start,
+          target.visibleRange.end,
+        )
+        selectedModeBySeries.set(target.series.id, 'raw')
+        diagnostics.push(rawDiagnostics(target, token))
+      } else {
+        if (!nextOverrides[target.series.id]?.length) {
+          nextOverrides[target.series.id] = fallbackPoints(
+            target,
+            context.renderingOptions.value.sampling.maxPointsPerPixel,
+          )
+        }
+        sampledTargets.push({
+          ...target,
+          request: { ...target.request, previousSelectedMode },
+        })
+      }
+    })
+    if (!sampledTargets.length) {
+      if (!samplingScheduler.isCurrent(token)) return
+      context.linePointOverrides.value = nextOverrides
+      emitDiagnostics(diagnostics)
+      return
+    }
+
+    context.linePointOverrides.value = nextOverrides
+    client ??= createWorkerSamplingClient()
+    await registerTargets(client, sampledTargets, token)
+    if (!samplingScheduler.isCurrent(token)) return
+    const batch = sampledTargets.map((target) => ({
+      ...target.request,
+      revision: revisions.get(target.request.datasetId) ?? 1,
+    }))
+    let response: SampleViewportResponse
+    try {
+      const result = await client.send({
+        type: 'sample-viewport',
+        requestId: ++requestId,
+        series: batch,
+      })
+      if (result.type !== 'sample-viewport-response') return
+      response = result
+    } catch (error) {
+      if (!samplingScheduler.isCurrent(token)) return
+      emitErrorOnce(
+        errorPayload(
+          error instanceof Error ? error.message : String(error),
+          context.renderingOptions.value.sampling.mode,
+          'javascript',
+          sampledTargets.map((target) => target.series.id),
+        ),
+      )
+      return
+    }
+    if (!samplingScheduler.isCurrent(token)) return
+    const sourceById = new Map(sampledTargets.map((target) => [target.series.id, target.source]))
+    response.results.forEach((result) => {
+      const source = sourceById.get(result.seriesId)
+      const selected = source ? sourcePoints(result, source) : undefined
+      if (selected && (result.status === 'ok' || result.status === 'wasm-unavailable')) {
+        nextOverrides[result.seriesId] = selected
+      }
+      diagnostics.push(result.diagnostics)
+      selectedModeBySeries.set(result.seriesId, result.diagnostics.selectedMode)
+      if (result.status === 'wasm-unavailable') {
+        emitErrorOnce(
+          errorPayload(
+            response.workerError ?? 'WASM sampling is unavailable.',
+            result.diagnostics.mode,
+            result.diagnostics.backend === 'javascript' ? 'javascript' : 'none',
+            [result.seriesId],
+          ),
+        )
+      }
+    })
+    if (response.workerError) {
+      emitErrorOnce(
+        errorPayload(
+          response.workerError,
+          context.renderingOptions.value.sampling.mode,
+          'javascript',
+          sampledTargets.map((target) => target.series.id),
+        ),
+      )
+    }
+    if (
+      client.workerFailureReason &&
+      response.results.every((result) => result.status !== 'wasm-unavailable')
+    ) {
+      emitErrorOnce(
+        errorPayload(
+          client.workerFailureReason,
+          context.renderingOptions.value.sampling.mode,
+          'javascript',
+          sampledTargets.map((target) => target.series.id),
+        ),
+      )
+    }
+    context.linePointOverrides.value = { ...nextOverrides }
+    emitDiagnostics(diagnostics)
+  }
+
+  watch(
+    targetSignature,
+    () => {
+      if (autoModeSettleTimer) clearTimeout(autoModeSettleTimer)
+      const useAutoHysteresis = hasInitialSamplingRun
+      hasInitialSamplingRun = true
+      samplingScheduler.schedule((token) => runSampling(token, useAutoHysteresis))
+      if (
+        useAutoHysteresis &&
+        context.renderingOptions.value.sampling.mode === 'auto' &&
+        context.renderingOptions.value.sampling.autoHysteresis > 0
+      ) {
+        autoModeSettleTimer = setTimeout(() => {
+          autoModeSettleTimer = undefined
+          samplingScheduler.schedule((token) => runSampling(token, false))
+        }, AUTO_MODE_SETTLE_DELAY_MS)
+      }
+    },
+    { immediate: true },
+  )
+  watch(
+    context.preparedSeries,
+    () => {
+      samplingScheduler.cancelPending()
+      dataEpoch.value += 1
+      context.linePointOverrides.value = {}
+      revisions.clear()
+      backendBySeries.clear()
+      selectedModeBySeries.clear()
+      emittedErrors.clear()
+      client?.dispose()
+      client = undefined
+    },
+    { flush: 'sync' },
+  )
+  onScopeDispose(() => {
+    if (diagnosticsTimer) clearTimeout(diagnosticsTimer)
+    if (autoModeSettleTimer) clearTimeout(autoModeSettleTimer)
+    samplingScheduler.dispose()
+    client?.dispose()
+  })
+
+  return { linePointOverrides: context.linePointOverrides }
+}

package/src/components/core/waveformChartTypes.ts

@@ -10,6 +10,9 @@ import type {
   WaveformPlotMargin,
   WaveformPoint,
   WaveformRenderingOptions,
+  WaveformSamplingBackend,
+  WaveformSamplingDiagnostics,
+  WaveformSamplingError,
   WaveformTitleOptions,
   WaveformXDomainStrategy,
   WaveformZeroLineOptions,
@@ -97,6 +100,16 @@ export interface WaveformChartEmit {
   (event: 'annotation-update', annotation: WaveformAnnotation, previous: WaveformAnnotation): void
   (event: 'annotation-delete', annotation: WaveformAnnotation): void
   (event: 'page-change', page: number, pageCount: number): void
+  (event: 'sampling-complete', diagnostics: WaveformSamplingDiagnostics): void
+  (
+    event: 'sampling-backend-change',
+    payload: {
+      seriesId: string
+      previous: WaveformSamplingBackend
+      current: WaveformSamplingBackend
+    },
+  ): void
+  (event: 'sampling-error', error: WaveformSamplingError): void
 }
 
 interface ViewportSelectionBase {

package/src/components/core/workerSamplingClient.ts

@@ -0,0 +1,148 @@
+import { WorkerSamplingRepository } from '../../core/workerSampling'
+import type {
+  DatasetResponse,
+  WorkerSamplingRequest,
+  WorkerSamplingResponse,
+} from '../../core/workerSampling'
+import type { WaveformPoint } from '../../types'
+import type { WorkerSamplingDataset } from '../../core/waveformPointSource'
+
+interface StoredDataset {
+  points?: readonly WaveformPoint[]
+  dataset?: WorkerSamplingDataset
+  revision: number
+}
+
+interface PendingRequest {
+  request: WorkerSamplingRequest
+  resolve: (response: WorkerSamplingResponse) => void
+  reject: (error: Error) => void
+}
+
+export interface WorkerSamplingClient {
+  readonly workerFailureReason: string | undefined
+  send(request: WorkerSamplingRequest): Promise<WorkerSamplingResponse>
+  dispose(): void
+}
+
+function workerFailureMessage(event?: ErrorEvent) {
+  return event?.message || 'Web Worker is unavailable; JavaScript sampling is being used.'
+}
+
+export function createWorkerSamplingClient(): WorkerSamplingClient {
+  let worker: Worker | undefined
+  let fallback: WorkerSamplingRepository | undefined
+  let workerFailureReason: string | undefined
+  const pending = new Map<number, PendingRequest>()
+  const datasets = new Map<string, StoredDataset>()
+
+  const fallbackRepository = () => {
+    fallback ??= new WorkerSamplingRepository()
+    for (const [datasetId, dataset] of datasets) {
+      fallback.handle({
+        type: 'register-dataset',
+        requestId: 0,
+        datasetId,
+        revision: 0,
+        points: dataset.points,
+        dataset: dataset.dataset,
+      })
+      for (let revision = 1; revision < dataset.revision; revision += 1) {
+        fallback.handle({
+          type: 'replace-dataset',
+          requestId: 0,
+          datasetId,
+          revision,
+          points: dataset.points,
+          dataset: dataset.dataset,
+        })
+      }
+    }
+    return fallback
+  }
+
+  const recordDatasetRequest = (request: WorkerSamplingRequest) => {
+    if (request.type === 'register-dataset') {
+      datasets.set(request.datasetId, {
+        points: request.points,
+        dataset: request.dataset,
+        revision: 1,
+      })
+    }
+    if (request.type === 'replace-dataset') {
+      datasets.set(request.datasetId, {
+        points: request.points,
+        dataset: request.dataset,
+        revision: request.revision + 1,
+      })
+    }
+    if (request.type === 'dispose-dataset') datasets.delete(request.datasetId)
+    if (request.type === 'dispose-all') datasets.clear()
+  }
+
+  const resolveFallbackRequests = () => {
+    const outstanding = [...pending.values()]
+    pending.clear()
+    const repository = fallbackRepository()
+    outstanding.forEach(({ request, resolve }) => resolve(repository.handle(request)))
+  }
+
+  const fallBackToJavascript = (event?: ErrorEvent) => {
+    if (fallback) return
+    workerFailureReason = workerFailureMessage(event)
+    worker?.terminate()
+    worker = undefined
+    resolveFallbackRequests()
+  }
+
+  try {
+    if (typeof Worker === 'undefined') fallBackToJavascript()
+    else {
+      worker = new Worker(new URL('../../core/workerSampling/workerRuntime.ts', import.meta.url), {
+        type: 'module',
+      })
+      worker.onmessage = (event: MessageEvent<WorkerSamplingResponse>) => {
+        const request = pending.get(event.data.requestId)
+        if (!request) return
+        pending.delete(event.data.requestId)
+        request.resolve(event.data)
+      }
+      worker.onerror = (event) => fallBackToJavascript(event)
+      worker.onmessageerror = () => fallBackToJavascript()
+    }
+  } catch {
+    fallBackToJavascript()
+  }
+
+  return {
+    get workerFailureReason() {
+      return workerFailureReason
+    },
+    send(request) {
+      recordDatasetRequest(request)
+      if (fallback) return Promise.resolve(fallbackRepository().handle(request))
+      return new Promise<WorkerSamplingResponse>((resolve, reject) => {
+        pending.set(request.requestId, { request, resolve, reject })
+        try {
+          worker?.postMessage(request)
+        } catch {
+          pending.delete(request.requestId)
+          fallBackToJavascript()
+          resolve(fallbackRepository().handle(request))
+        }
+      })
+    },
+    dispose() {
+      worker?.terminate()
+      worker = undefined
+      pending.forEach(({ reject }) => reject(new Error('Sampling client was disposed.')))
+      pending.clear()
+      datasets.clear()
+      fallback = undefined
+    },
+  }
+}
+
+export function isDatasetResponse(response: WorkerSamplingResponse): response is DatasetResponse {
+  return response.type === 'dataset-response'
+}