waveform-analysis 0.1.74 → 0.1.76

package/src/components/core/layout.ts

@@ -1,4 +1,8 @@
-import type { WaveformOverlayMode } from '../../types'
+import type {
+  WaveformAmplitudeLimit,
+  WaveformAmplitudeLimits,
+  WaveformOverlayMode,
+} from '../../types'
 import { formatScientificAxisLabel, formatScientificAxisExponent, paddedDomain } from '../../utils'
 import type { DisplaySeries, DisplayTrack, TrackLayout } from './types'
 import { MAX_MULTI_Y_AXIS_COUNT } from './constants'
@@ -8,7 +12,9 @@ import {
   resolveTrackFixedYDomain,
   type WaveformYDomain,
 } from './yDomain'
-import { resolveYAxisTicksECharts } from './niceScale'
+import { resolveYAxisTicks } from './yAxisTicks'
+export { resolveYAxisTicks, type ResolvedYAxisTicks } from './yAxisTicks'
+import { applyAmplitudeLimits, mergeAmplitudeLimits } from './amplitudeLimits'
 import { applyYAxisPadding, withMaximumTick, type YAxisPaddingOptions } from './yAxisPadding'
 import { resolveYAxisLabelBandWidth } from './yAxisLabelStyle'
 
@@ -28,36 +34,6 @@ export function resolveYAxisTickCount(_plotHeight: number, splitNumber?: number)
   return 5
 }
 
-export interface ResolvedYAxisTicks {
-  domain: [number, number]
-  values: number[]
-}
-
-export function resolveYAxisTicks(
-  domain: [number, number],
-  tickCount = 5,
-  nice = true,
-): ResolvedYAxisTicks {
-  if (!nice) {
-    // 如果不需要 nice，使用简单的线性分割
-    const effectiveTickCount =
-      typeof tickCount === 'number' && Number.isFinite(tickCount)
-        ? Math.max(2, Math.floor(tickCount))
-        : 5
-    const [axisStart, axisEnd] = domain
-    return {
-      domain,
-      values: Array.from(
-        { length: effectiveTickCount },
-        (_, index) => axisStart + ((axisEnd - axisStart) * index) / (effectiveTickCount - 1),
-      ),
-    }
-  }
-
-  // 使用 ECharts 兼容的 1/2/5 系列算法
-  return resolveYAxisTicksECharts(domain, tickCount)
-}
-
 export function formatYAxisTickLabel(
   value: number,
   domain: [number, number],
@@ -101,6 +77,7 @@ export interface YAxisSeriesGroup {
   seriesList: DisplaySeries[]
   domain: [number, number]
   fixed: boolean
+  amplitudeLimit?: WaveformAmplitudeLimit
   maximumTick?: number
   minimumTick?: number
 }
@@ -191,6 +168,7 @@ export function resolveRenderedYAxisSeriesGroups(
   yDomains?: Record<string, WaveformYDomain>,
   viewportYDomains?: Record<string, [number, number]>,
   padding?: YAxisPaddingOptions | number,
+  amplitudeLimits?: WaveformAmplitudeLimits,
 ): YAxisSeriesGroup[] {
   const viewportYDomain = viewportYDomains?.[track.id]
   const axisTrack =
@@ -198,7 +176,13 @@ export function resolveRenderedYAxisSeriesGroups(
       ? track
       : { ...track, visibleSeries: track.series }
   return resolveYAxisSeriesGroups(axisTrack, overlayMode, yDomain, yDomains).map((group) => {
-    const padded = applyYAxisPadding(group, viewportYDomain, padding)
+    const limit = mergeAmplitudeLimits(group.seriesList, amplitudeLimits)
+    const automatic = limit ? buildYAxisSeriesGroups(axisTrack, overlayMode)[group.index]! : group
+    const padded = applyYAxisPadding(automatic, limit ? undefined : viewportYDomain, padding)
+    if (limit) {
+      padded.domain = applyAmplitudeLimits(padded.domain, limit, automatic.domain)
+      padded.amplitudeLimit = limit
+    }
     return track.visibleSeries.length
       ? padded
       : { ...padded, maximumTick: undefined, minimumTick: undefined }
@@ -215,10 +199,11 @@ export function axisTextMetrics(
   measureTextWidth?: (text: string) => number,
   maximumTick?: number,
   minimumTick?: number,
+  amplitudeLimit?: WaveformAmplitudeLimit,
 ): { tickTextWidth: number; titleTextWidth: number } {
   const resolvedTicks = tickValues
     ? { domain, values: tickValues }
-    : resolveYAxisTicks(domain, tickCount, nice)
+    : resolveYAxisTicks(domain, tickCount, nice, amplitudeLimit)
   const inRange = (value?: number) =>
     value !== undefined && value >= resolvedTicks.domain[0] && value <= resolvedTicks.domain[1]
       ? value
@@ -320,6 +305,7 @@ export function buildYAxisSlots(
   padding?: YAxisPaddingOptions | number,
   showUnits = true,
   measureTextWidth?: (text: string) => number,
+  amplitudeLimits?: WaveformAmplitudeLimits,
 ): { slots: YAxisSlot[]; clearance: { left: number; right: number } } {
   const labelBandWidth = resolveYAxisLabelBandWidth(
     typeof padding === 'object' ? padding.labelTextStyle : undefined,
@@ -335,6 +321,7 @@ export function buildYAxisSlots(
       yDomains,
       viewportYDomains,
       padding,
+      amplitudeLimits,
     ).forEach((group) => {
       const sideIndex = sideIndexes[group.side]++
       const key = `${group.side}:${sideIndex}`
@@ -348,6 +335,7 @@ export function buildYAxisSlots(
         measureTextWidth,
         group.maximumTick,
         group.minimumTick,
+        group.amplitudeLimit,
       )
       widths.set(key, Math.max(widths.get(key) ?? Y_AXIS_CHARACTER_WIDTH, tickTextWidth))
       titleWidths.set(key, Math.max(titleWidths.get(key) ?? Y_AXIS_CHARACTER_WIDTH, titleTextWidth))

package/src/components/core/trackLayoutBuilder.ts

@@ -1,18 +1,12 @@
+import { generateWaveformPath } from '../animation/geometry'
 import { withMaximumTick, type YAxisPaddingOptions } from './yAxisPadding'
 import { selectSeriesRenderSourcePoints } from '../../core/rendering'
 import { pointSourceFromPoints } from '../../core/waveformPointSource'
-import {
-  curveStep,
-  curveStepAfter,
-  curveStepBefore,
-  line,
-  scaleLinear,
-  zoomIdentity,
-  type ZoomTransform,
-} from 'd3'
+import { scaleLinear, zoomIdentity, type ZoomTransform } from 'd3'
 
 import { type ResolvedWaveformRenderingOptions } from '../../core/rendering'
 import type {
+  WaveformAmplitudeLimits,
   WaveformDisplayMode,
   WaveformOverlayMode,
   WaveformPoint,
@@ -41,7 +35,6 @@ import {
   alignIntegerZoomDomain,
   normalizeIntegerZoomDomain,
   integerZoomTicks,
-  formatIntegerZoomLabel,
 } from '../interaction/integerZoom'
 import {
   Y_AXIS_LABEL_GAP,
@@ -66,6 +59,7 @@ export interface BuildTrackLayoutsOptions {
   initialXDomains?: Record<string, [number, number]>
   xDomainStrategy?: WaveformXDomainStrategy
   integerZoom?: boolean
+  amplitudeLimits?: WaveformAmplitudeLimits
   fixedYDomain?: [number, number]
   fixedYDomains?: Record<string, [number, number]>
   yDomains?: Record<string, [number, number]>
@@ -86,6 +80,7 @@ export interface BuildTrackLayoutsOptions {
   useNonEmptyBottomTracks?: boolean
   compactYAxisLayout?: boolean
   showAxisUnits?: boolean
+  domainTimeUnit?: 's' | 'ms'
 }
 
 function resolveIndependentXDomain(
@@ -103,7 +98,7 @@ function resolveIndependentXDomain(
     explicitDomain
       ? applyXDomainStrategy(explicitDomain, strategy, true)
       : applyXDomainStrategy(track.xDomain, strategy),
-    options,
+    { integerZoom: options.integerZoom, timeUnit: options.domainTimeUnit ?? options.timeUnit },
   )
 }
 
@@ -148,13 +143,19 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
       options.fixedYDomains,
       options.yDomains,
       options.yAxisPadding ?? options.yAxisUpperPaddingRatio,
+      options.amplitudeLimits,
     )
     const sideIndexes = { left: 0, right: 0 }
     const sideOffsets = { left: 0, right: 0 }
     const yAxes: WaveformYAxisLayout[] = yAxisGroups.map((group) => {
       const sideIndex = sideIndexes[group.side]++
       const tickCount = resolveYAxisTickCount(cell.plotHeight, options.yAxisSplitNumber)
-      const resolvedTicks = resolveYAxisTicks(group.domain, tickCount, options.yAxisNice !== false)
+      const resolvedTicks = resolveYAxisTicks(
+        group.domain,
+        tickCount,
+        options.yAxisNice !== false,
+        group.amplitudeLimit,
+      )
       const scale = scaleLinear(resolvedTicks.domain, [cell.plotHeight, 0])
       const majorTicks = resolvedTicks.values
       const maximumTick =
@@ -227,8 +228,7 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
       Math.max(2, Math.floor(cell.width / 100)),
       options,
     )
-    const xAxisLabelFormatter =
-      options.xAxisLabelFormatter ?? (options.integerZoom ? formatIntegerZoomLabel : undefined)
+    const xAxisLabelFormatter = options.xAxisLabelFormatter
     const yMajorTicks =
       yAxes[0]?.majorTicks ??
       (isEmpty
@@ -264,17 +264,15 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
           hasErrorPoints: trackSeries.hasErrorPoints,
         },
       )
-      const pathGenerator = line<WaveformPoint>()
-        .x((point) => xScale(point.x))
-        .y((point) => seriesYScale(point.y))
-      if (trackSeries.lineType === 'step-start') pathGenerator.curve(curveStepBefore)
-      if (trackSeries.lineType === 'step-middle') pathGenerator.curve(curveStep)
-      if (trackSeries.lineType === 'step-end' || trackSeries.lineType === 'step-after') {
-        pathGenerator.curve(curveStepAfter)
-      }
       return {
         series: trackSeries,
-        path: renderPoints.linePoints.length ? pathGenerator(renderPoints.linePoints) : null,
+        path: generateWaveformPath(
+          renderPoints.linePoints,
+          trackSeries.lineType,
+          xScale,
+          seriesYScale,
+        ),
+        lineRenderPoints: renderPoints.linePoints,
         pointRenderPoints: renderPoints.pointRenderPoints,
         errorBarRenderPoints: renderPoints.errorBarRenderPoints,
         yScale: seriesYScale,

package/src/components/core/types.ts

@@ -47,6 +47,10 @@ export interface DisplayTrack {
 export interface TrackSeriesPath {
   series: DisplaySeries
   path: string | null
+  lineRenderPoints?: WaveformPoint[]
+  presentationKey?: string
+  opacity?: number
+  animationClip?: { id: string; x: number; width: number }
   pointRenderPoints: WaveformPoint[]
   errorBarRenderPoints: WaveformPoint[]
   yScale: ScaleLinear<number, number>

package/src/components/core/useWaveformChartController.ts

@@ -1,4 +1,6 @@
-import { chartExportOptions } from '../controls/chartExportOptions'
+import { assignElement } from '../utils/assignElement'
+import { chartExportVersion } from '../animation/chartExportVersion'
+import { useWaveformAnimations } from '../animation/useWaveformAnimations'
 import { useChartImageExport } from '../controls/useChartImageExport'
 import { useControlMode } from '../controls/useControlMode'
 import { useChartCommands } from '../controls/useChartCommands'
@@ -16,9 +18,7 @@ import {
   watch,
   watchEffect,
   type ComponentPublicInstance,
-  type Ref,
 } from 'vue'
-
 import { useWaveformInstanceId } from '../../utils/waveformId'
 import { useWaveformAnnotationInteraction, type AnnotationSeriesCandidate } from '../annotation'
 import { useWaveformChartAnnotations } from '../annotation/useWaveformChartAnnotations'
@@ -32,6 +32,7 @@ import { resolveCompactPaginationBand } from './pagination'
 import type { WaveformHoverState } from './types'
 import { useWaveformChartLifecycle } from './useWaveformChartLifecycle'
 import { usePreparedWaveformSeries } from './useWaveformData'
+import { remotePanBoundary } from '../interaction/remoteViewport'
 import { useWaveformLayout } from './useWaveformLayout'
 import { useWaveformPresentation } from './useWaveformPresentation'
 import { usePlotLabelLayout } from './usePlotLabelLayout'
@@ -41,14 +42,6 @@ import type {
   ViewportSelectionState,
   WaveformChartEmit,
 } from './waveformChartTypes'
-
-function assignElement<T extends Element>(
-  target: Ref<T | undefined>,
-  element: Element | ComponentPublicInstance | null,
-) {
-  target.value = element instanceof Element ? (element as T) : undefined
-}
-
 export function useWaveformChartController(
   inputProps: ResolvedWaveformChartProps,
   emit: WaveformChartEmit,
@@ -90,7 +83,7 @@ export function useWaveformChartController(
   const hoverThrottle = useAnimationFrameThrottle()
 
   watch(
-    [() => props.yDomain, () => props.yDomains],
+    [() => props.yDomain, () => props.yDomains, () => props.amplitudeLimits],
     () => {
       sharedYDomains.value = {}
       independentYDomains.value = {}
@@ -110,6 +103,7 @@ export function useWaveformChartController(
       handleBeforeDataReferenceChange()
     },
     () => handleDataReferenceChange(),
+    () => Boolean(remotePanBoundary(props)),
   )
 
   const presentation = useWaveformPresentation({
@@ -186,7 +180,17 @@ export function useWaveformChartController(
     renderingOptions,
     linePointOverrides,
   })
-
+  const animations = useWaveformAnimations({
+    props,
+    currentPage,
+    containerSize: computed(() => [observedWidth.value, observedHeight.value]),
+    layoutReady: computed(() => observedWidth.value > 0 && observedHeight.value > 0),
+    tracks: trackLayouts,
+    preparedSeries,
+    innerWidth,
+    innerHeight: presentation.innerHeight,
+    sampling,
+  })
   const paginationVisible = computed(
     () => gridOptions.value.showPagination && pageCount.value > 1 && !isCleanView.value,
   )
@@ -261,8 +265,6 @@ export function useWaveformChartController(
     isPresentationMode,
     editorSeriesOptions,
     resolveInitialTrackDomain,
-    canZoomTrack: zoom.canZoomTrack,
-    canZoomSharedTracks: zoom.canZoomSharedTracks,
     configureZoom: zoom.configureZoom,
     cancelPendingZoom: zoom.cancelPendingZoom,
     clearHover: () => hover.clearHover(),
@@ -389,10 +391,8 @@ export function useWaveformChartController(
       height: chartHeight.value,
       titleHeight: titleAreaHeight.value,
     }),
-    version: () => [
-      props.data,
-      JSON.stringify({
-        ...chartExportOptions(props),
+    version: () =>
+      chartExportVersion(props, {
         hidden: [...hiddenSeriesIdSet.value],
         width: chartWidth.value,
         height: chartHeight.value,
@@ -404,7 +404,8 @@ export function useWaveformChartController(
         independentY: independentYDomains.value,
         boundaries: boundaries.value,
       }),
-    ],
+    prepare: animations.prepareExport,
+    release: animations.releaseExport,
     ready: sampling.ready,
   })
 
@@ -418,7 +419,11 @@ export function useWaveformChartController(
     ...annotations,
     ...viewport,
     ...hover,
-    ...commands,
+    ...animations.wrap(commands),
+    presentationTracks: animations.presentationTracks,
+    presentationAnnotations: animations.presentationAnnotations,
+    paginationOpacity: animations.paginationOpacity,
+    stabilizeAnimations: animations.stabilizeAnimations,
     ...imageExport,
     margin,
     getPageSize,
@@ -431,7 +436,7 @@ export function useWaveformChartController(
     contextMenu: annotationInteraction.contextMenu,
     editorSeriesOptions,
     clipPathId,
-    goToPage: lifecycle.goToPage,
+    goToPage: animations.wrapPagination(lifecycle.goToPage, pageCount),
     setContainer: (element: Element | ComponentPublicInstance | null) =>
       assignElement(container, element),
     setSvgElement: (element: Element | ComponentPublicInstance | null) =>
@@ -442,5 +447,4 @@ export function useWaveformChartController(
       assignElement(sharedOverlayElement, element),
   })
 }
-
 export type WaveformChartController = ReturnType<typeof useWaveformChartController>

package/src/components/core/useWaveformChartLifecycle.ts

@@ -16,6 +16,7 @@ import type { NormalizedWaveformGridOptions } from './grid'
 import type { DisplaySeries, DisplayTrack, TrackLayout } from './types'
 import type { ResolvedWaveformChartProps, WaveformChartEmit } from './waveformChartTypes'
 import { isEditableTarget } from '../interaction/interactionTarget'
+import { remotePanBoundary } from '../interaction/remoteViewport'
 
 export interface LifecycleContext {
   preserveFullViewport?: () => boolean
@@ -64,7 +65,6 @@ export interface LifecycleContext {
 }
 
 export function useWaveformChartLifecycle(context: LifecycleContext) {
-  useWaveformMeasurements(context)
   const {
     props,
     emit,
@@ -135,6 +135,15 @@ export function useWaveformChartLifecycle(context: LifecycleContext) {
   const { handleBeforeDataReferenceChange, handleDataReferenceChange } =
     useWaveformViewportRestore(context)
 
+  useWaveformMeasurements(context, {
+    beforeResize: () => {
+      if (remotePanBoundary(props)) handleBeforeDataReferenceChange()
+    },
+    afterResize: () => {
+      if (remotePanBoundary(props)) handleDataReferenceChange()
+    },
+  })
+
   watch(
     [
       innerWidth,
@@ -163,7 +172,7 @@ export function useWaveformChartLifecycle(context: LifecycleContext) {
   )
 
   watch(
-    () => [props.displayMode, props.integerZoom, props.integerZoom ? props.timeUnit : undefined],
+    () => [props.displayMode, props.integerZoom],
     () => {
       const previousPage = currentPage.value
       currentPage.value = 1

package/src/components/core/useWaveformData.ts

@@ -31,8 +31,11 @@ export interface PreparedWaveformSeries {
   hasErrorPoints: boolean
 }
 
-export function prepareWaveformSeries(data: WaveformData): PreparedWaveformSeries[] {
-  return normalizeWaveformSeriesSources(data).map(({ source, ...series }) => {
+export function prepareWaveformSeries(
+  data: WaveformData,
+  retainEmpty = false,
+): PreparedWaveformSeries[] {
+  return normalizeWaveformSeriesSources(data, retainEmpty).map(({ source, ...series }) => {
     const sourceMetrics = source.metrics(series.errorBar.visible)
     return {
       ...series,
@@ -61,11 +64,14 @@ export function usePreparedWaveformSeries(
   data: () => WaveformData,
   onBeforeDataChange: () => void,
   onDataChange: () => void,
+  retainEmpty: () => boolean = () => false,
 ) {
-  const preparedSeries = shallowRef<PreparedWaveformSeries[]>(prepareWaveformSeries(data()))
-  watch(data, (nextData) => {
+  const preparedSeries = shallowRef<PreparedWaveformSeries[]>(
+    prepareWaveformSeries(data(), retainEmpty()),
+  )
+  watch([data, retainEmpty], ([nextData, preserveEmpty]) => {
     onBeforeDataChange()
-    preparedSeries.value = prepareWaveformSeries(nextData)
+    preparedSeries.value = prepareWaveformSeries(nextData, preserveEmpty)
     onDataChange()
   })
   return preparedSeries

package/src/components/core/useWaveformLayout.ts

@@ -52,6 +52,9 @@ export function useWaveformLayout(context: LayoutContext) {
     annotationInteraction,
     linePointOverrides,
   } = context
+  // Display-unit switches must not change the base used by existing D3 transforms.
+  const domainTimeUnit = props.timeUnit
+  const domainOptions = () => ({ integerZoom: props.integerZoom, timeUnit: domainTimeUnit })
   const chartSeries = computed<DisplaySeries[]>(() =>
     preparedSeries.value.map((series, index): DisplaySeries => ({
       ...series,
@@ -174,12 +177,12 @@ export function useWaveformLayout(context: LayoutContext) {
           props.xDomainStrategy,
           true,
         ),
-        props,
+        domainOptions(),
       )
     }
     return alignIntegerZoomDomain(
       applyXDomainStrategy(sharedXDomain.value, props.xDomainStrategy),
-      props,
+      domainOptions(),
     )
   })
   const resolveOriginalTrackDomain = (track: TrackLayout): [number, number] => {
@@ -201,7 +204,7 @@ export function useWaveformLayout(context: LayoutContext) {
           props.xDomainStrategy,
           true,
         ),
-        props,
+        domainOptions(),
       )
     }
     return alignIntegerZoomDomain(
@@ -209,7 +212,7 @@ export function useWaveformLayout(context: LayoutContext) {
         paddedDomain(track.seriesList.flatMap((series) => series.xDomain)),
         props.xDomainStrategy,
       ),
-      props,
+      domainOptions(),
     )
   }
   const initialXDomain = computed(
@@ -261,10 +264,12 @@ export function useWaveformLayout(context: LayoutContext) {
       effectiveXDomains: context.boundaries?.value,
       xDomainStrategy: props.xDomainStrategy,
       integerZoom: props.integerZoom,
+      amplitudeLimits: props.amplitudeLimits,
       fixedYDomain: props.yDomain,
       fixedYDomains: props.yDomains,
       yDomains: viewportYDomains.value,
       timeUnit: props.timeUnit,
+      domainTimeUnit,
       xAxisLabelFormatter: props.axes?.x?.labelFormatter,
       yAxisSplitNumber: props.axes?.y?.splitNumber,
       yAxisNice: props.axes?.y?.nice,

package/src/components/core/useWaveformMeasurements.ts

@@ -15,6 +15,7 @@ export function useWaveformMeasurements(
     | 'titleAreaReserved'
     | 'titleMeasureStyle'
   >,
+  resizeHooks: { beforeResize?: () => void; afterResize?: () => void } = {},
 ) {
   const {
     container,
@@ -53,8 +54,10 @@ export function useWaveformMeasurements(
   onMounted(() => {
     if (!container.value) return
     resizeObserver.value = new ResizeObserver(([entry]) => {
+      resizeHooks.beforeResize?.()
       observedWidth.value = Math.max(0, entry?.contentRect.width ?? 0)
       observedHeight.value = Math.max(0, entry?.contentRect.height ?? 0)
+      resizeHooks.afterResize?.()
       void nextTick(measureTitle)
     })
     resizeObserver.value.observe(container.value)

package/src/components/core/useWaveformRenderSampling.ts

@@ -103,6 +103,7 @@ function errorPayload(
 }
 
 export function useWaveformRenderSampling(context: SamplingContext) {
+  const resultState = shallowRef<'success' | 'fallback' | 'error'>('success')
   const settledSignature = shallowRef<string>()
   const dataEpoch = shallowRef(0)
   const session = createWaveformSamplingSession()
@@ -292,10 +293,14 @@ export function useWaveformRenderSampling(context: SamplingContext) {
         requestId: ++session.requestId,
         series: batch,
       })
-      if (result.type !== 'sample-viewport-response') return
+      if (result.type !== 'sample-viewport-response') {
+        if (samplingScheduler.isCurrent(token)) resultState.value = 'error'
+        return
+      }
       response = result
     } catch (error) {
       if (!samplingScheduler.isCurrent(token)) return
+      resultState.value = 'error'
       emitErrorOnce(
         errorPayload(
           error instanceof Error ? error.message : String(error),
@@ -310,8 +315,18 @@ export function useWaveformRenderSampling(context: SamplingContext) {
       return
     }
     if (!samplingScheduler.isCurrent(token)) return
+    if (response.workerError || client.workerFailureReason) resultState.value = 'fallback'
     const sourceById = new Map(sampledTargets.map((target) => [target.series.id, target.source]))
+    if (
+      sampledTargets.some(
+        (target) =>
+          !response.results.some((result) => result.seriesId === target.series.id && result.output),
+      )
+    )
+      resultState.value = 'error'
     response.results.forEach((result) => {
+      if (result.status !== 'ok' && resultState.value !== 'error')
+        resultState.value = result.output ? 'fallback' : 'error'
       const source = sourceById.get(result.seriesId)
       const selected = source ? sourcePoints(result, source) : undefined
       if (selected && (result.status === 'ok' || result.status === 'wasm-unavailable')) {
@@ -369,6 +384,7 @@ export function useWaveformRenderSampling(context: SamplingContext) {
   const scheduleSampling = (hysteresis: boolean) => {
     settledSignature.value = undefined
     const signature = targetSignature.value
+    resultState.value = 'success'
     samplingScheduler.schedule(async (token) => {
       try {
         await runSampling(token, hysteresis)
@@ -410,6 +426,12 @@ export function useWaveformRenderSampling(context: SamplingContext) {
   onScopeDispose(() => session.dispose())
 
   return {
+    requestSignature: targetSignature,
+    state: computed(() =>
+      settledSignature.value === targetSignature.value && !session.autoModeSettleTimer
+        ? resultState.value
+        : 'pending',
+    ),
     linePointOverrides: context.linePointOverrides,
     ready: () => settledSignature.value === targetSignature.value && !session.autoModeSettleTimer,
   }

package/src/components/core/useWaveformYAxisLayout.ts

@@ -49,6 +49,7 @@ export function useWaveformYAxisLayout(context: YAxisLayoutContext) {
       props.axes?.y,
       showUnits.value,
       isEdgeCompact.value ? measureYAxisTextWidth : undefined,
+      props.amplitudeLimits,
     ),
   )
   const hasYAxisLabels = computed(() =>
@@ -84,6 +85,7 @@ export function useWaveformYAxisLayout(context: YAxisLayoutContext) {
       props.axes?.y,
       showUnits.value,
       isEdgeCompact.value ? measureYAxisTextWidth : undefined,
+      props.amplitudeLimits,
     ),
   )
   const resolvedChartLeftMargin = computed(() =>

package/src/components/core/waveformChartTypes.ts

@@ -1,5 +1,7 @@
+import type { WaveformAnimationProps } from '../../animation/types'
 import type { WaveformToolbarOptions, WaveformControlState } from '../../types/controls'
 import type {
+  WaveformAmplitudeLimits,
   WaveformAnnotation,
   WaveformAxesOptions,
   WaveformData,
@@ -26,7 +28,7 @@ import type {
 } from '../data/types'
 import type { WaveformGridOptions } from './grid'
 
-export interface WaveformChartProps {
+export interface WaveformChartProps extends WaveformAnimationProps {
   toolbar?: boolean | WaveformToolbarOptions
   data: WaveformData
   displayMode?: WaveformDisplayMode
@@ -42,7 +44,7 @@ export interface WaveformChartProps {
   lineColor?: string
   showTooltip?: boolean
   zoomable?: boolean
-  /** Snap viewport endpoints outwards to integer X-axis display units. */
+  /** Prefer integer display-unit endpoints; preserve any window narrower than one unit. */
   integerZoom?: boolean
   pannable?: boolean
   /** Global record bounds in seconds; enables horizontal panning beyond loaded data. */
@@ -53,6 +55,8 @@ export interface WaveformChartProps {
   initialXDomain?: [number, number]
   initialXDomains?: Record<string, [number, number]>
   xDomainStrategy?: WaveformXDomainStrategy
+  /** Strict bounds per normalized series ID; active bounds override Y viewports. */
+  amplitudeLimits?: WaveformAmplitudeLimits
   yDomain?: [number, number]
   yDomains?: Record<string, [number, number]>
   timeUnit?: 's' | 'ms'