waveform-analysis 0.1.74 → 0.1.76

package/dist/types/components/WaveformChart.vue.d.ts

@@ -84,8 +84,10 @@ declare const __VLS_export: import("vue").DefineComponent<WaveformChartProps, {
     minVisiblePoints: number;
     xDomainStrategy: import("..").WaveformXDomainStrategy;
     timeUnit: "s" | "ms";
+    frameNumber: string | number;
     annotations: import("..").WaveformAnnotation[];
     annotationsVisible: boolean;
+    interactionMode: import("..").WaveformInteractionMode;
     grid: import("..").WaveformGridOptions;
     rendering: import("..").WaveformRenderingOptions;
     plotMargin: import("..").WaveformPlotMargin;
@@ -94,8 +96,7 @@ declare const __VLS_export: import("vue").DefineComponent<WaveformChartProps, {
     cleanView: boolean;
     presentationMode: boolean;
     zeroLine: import("..").WaveformZeroLineOptions;
-    frameNumber: string | number;
-    interactionMode: import("..").WaveformInteractionMode;
+    animationEnabled: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/types/components/animation/annotationPresentation.d.ts

@@ -0,0 +1,17 @@
+import type { RenderedAnnotation } from '../annotation/types';
+import type { ResolvedAnimationProps } from './config';
+import type { WaveformAnnotation } from '@/types';
+import type { AnnotationAnimationState } from '@/animation/types';
+import { WaveformAnimationController } from '@/animation/WaveformAnimationController';
+export interface PresentedAnnotation extends RenderedAnnotation {
+    animationStyle?: AnnotationAnimationState;
+    leaving?: boolean;
+    seriesOpacity?: number;
+}
+export declare function createAnnotationPresentation(controller: WaveformAnimationController, invalidate: () => void): {
+    reconcile(rendered: RenderedAnnotation[], controlled: WaveformAnnotation[], config: ResolvedAnimationProps["animationAnnotation"], enabled: boolean, waitingSeries: Set<string>): void;
+    release(seriesId?: string): void;
+    finish(rendered: RenderedAnnotation[]): void;
+    project(rendered: RenderedAnnotation[], seriesOpacity: Map<string, number>): PresentedAnnotation[];
+    clear(): void;
+};

package/dist/types/components/animation/chartExportVersion.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedWaveformChartProps } from '../core/waveformChartTypes';
+export declare function chartExportVersion(props: ResolvedWaveformChartProps, state: object): unknown[];

package/dist/types/components/animation/config.d.ts

@@ -0,0 +1,31 @@
+import type { WaveformAnimationProps, AnnotationAnimationType, LineDrawingDirection } from '@/animation/types';
+export declare function resolveAnimationProps(props: WaveformAnimationProps, warn?: (message: string) => void): {
+    animationEnabled: boolean;
+    animationThreshold: number;
+    animation: {
+        delay: number;
+        staggerDelay: number;
+        direction: LineDrawingDirection;
+        enabled: boolean;
+        duration: number;
+        easing: NonNullable<import("../..").EasingType | import("../..").EasingFunction | undefined>;
+        onComplete: (() => void) | undefined;
+        onAbort: (() => void) | undefined;
+    };
+    animationUpdate: {
+        enabled: boolean;
+        duration: number;
+        easing: NonNullable<import("../..").EasingType | import("../..").EasingFunction | undefined>;
+        onComplete: (() => void) | undefined;
+        onAbort: (() => void) | undefined;
+    };
+    animationAnnotation: {
+        type: AnnotationAnimationType;
+        enabled: boolean;
+        duration: number;
+        easing: NonNullable<import("../..").EasingType | import("../..").EasingFunction | undefined>;
+        onComplete: (() => void) | undefined;
+        onAbort: (() => void) | undefined;
+    };
+};
+export type ResolvedAnimationProps = ReturnType<typeof resolveAnimationProps>;

package/dist/types/components/animation/context.d.ts

@@ -0,0 +1,20 @@
+import type { ComputedRef, Ref, ShallowRef } from 'vue';
+import type { TrackLayout } from '../core/types';
+import type { PreparedWaveformSeries } from '../core/useWaveformData';
+import type { ResolvedWaveformChartProps } from '../core/waveformChartTypes';
+export interface AnimationContext {
+    props: ResolvedWaveformChartProps;
+    tracks: ComputedRef<TrackLayout[]>;
+    currentPage: Ref<number>;
+    containerSize: ComputedRef<number[]>;
+    preparedSeries: ShallowRef<PreparedWaveformSeries[]>;
+    layoutReady: ComputedRef<boolean>;
+    innerWidth: ComputedRef<number>;
+    innerHeight: ComputedRef<number>;
+    sampling: {
+        state: ComputedRef<'pending' | 'success' | 'fallback' | 'error'>;
+        requestSignature: ComputedRef<string>;
+    };
+}
+export declare function animationLayoutSignature(context: AnimationContext): string;
+export declare function wrapAnimationCommands<T extends object>(commands: T, stabilize: () => void): T;

package/dist/types/components/animation/geometry.d.ts

@@ -0,0 +1,10 @@
+import type { ScaleLinear } from 'd3';
+import type { WaveformPoint, WaveformLineType } from '@/types';
+import type { TrackSeriesPath } from '../core/types';
+import type { NumericGeometry } from '@/animation/types';
+/** Private presentation buffer; the source/target snapshots and business points stay immutable. */
+export declare function interpolateGeometry(from: NumericGeometry, to: NumericGeometry, p: number): NumericGeometry;
+export declare function generateWaveformPath(points: WaveformPoint[], type: WaveformLineType, x: ScaleLinear<number, number>, y: ScaleLinear<number, number>): string | null;
+export declare function captureGeometry(path: TrackSeriesPath, x: ScaleLinear<number, number>): NumericGeometry;
+export declare function projectGeometry(path: TrackSeriesPath, geometry: NumericGeometry, x: ScaleLinear<number, number>, y: ScaleLinear<number, number>): TrackSeriesPath;
+export declare function compatibleGeometry(a: TrackSeriesPath, b: TrackSeriesPath, from: NumericGeometry, to: NumericGeometry): boolean;

package/dist/types/components/animation/paginationPresentation.d.ts

@@ -0,0 +1,13 @@
+import { type ComputedRef } from 'vue';
+import type { AnimationContext } from './context';
+import type { ResolvedAnimationProps } from './config';
+import type { WaveformAnimationController } from '@/animation/WaveformAnimationController';
+/** A single owner-scoped fade; it holds no old page geometry. */
+export declare function createPaginationPresentation(context: AnimationContext, controller: WaveformAnimationController, config: ComputedRef<ResolvedAnimationProps>, effective: ComputedRef<boolean>, commit: () => void): {
+    opacity: import("vue").ShallowRef<number, number>;
+    reset: () => void;
+    cancel: () => void;
+    reconcile: (dataChanged: boolean) => boolean;
+    wrapPagination: (goToPage: (page: number) => void, count: ComputedRef<number>) => (page: number) => void;
+    active: () => boolean;
+};

package/dist/types/components/animation/pathBuffer.d.ts

@@ -0,0 +1,4 @@
+import type { ScaleLinear } from 'd3';
+import type { WaveformPoint, WaveformLineType } from '@/types';
+/** Stable D3 accessors/context keep their feedback across frames; storage is private to points. */
+export declare function createPathBuffer(x: ScaleLinear<number, number>, y: ScaleLinear<number, number>): (points: WaveformPoint[], nextType: WaveformLineType, x: ScaleLinear<number, number>, y: ScaleLinear<number, number>) => string;

package/dist/types/components/animation/trackPresentation.d.ts

@@ -0,0 +1,35 @@
+import type { TrackLayout, TrackSeriesPath } from '../core/types';
+import type { WaveformAnnotation } from '@/types';
+import type { NumericGeometry } from '@/animation/types';
+interface AnchorValue {
+    seriesId: string;
+    annotationY: number;
+    x: number;
+    y: number;
+}
+interface SeriesGeometry {
+    path: TrackSeriesPath;
+    values: NumericGeometry;
+    old?: {
+        path: TrackSeriesPath;
+        values: NumericGeometry;
+    };
+    opacity: number;
+}
+export interface TrackPresentation {
+    target: TrackLayout;
+    series: Map<string, SeriesGeometry>;
+    xDomain: [number, number];
+    yDomains: [number, number][];
+    anchors: Map<string, AnchorValue>;
+    clips: Map<string, {
+        id: string;
+        x: number;
+        width: number;
+    }>;
+}
+export declare function staticTrack(track: TrackLayout, annotations: WaveformAnnotation[], previous?: TrackPresentation, refreshAnchors?: boolean): TrackPresentation;
+export declare function hasThirdGeometry(from: TrackPresentation): boolean;
+export declare function transitionTrack(from: TrackPresentation, to: TrackPresentation, p: number, terminal: boolean): TrackPresentation;
+export declare function projectTrack(state: TrackPresentation): TrackLayout;
+export {};

package/dist/types/components/animation/useWaveformAnimations.d.ts

@@ -0,0 +1,27 @@
+import { type AnimationContext } from './context';
+export declare function useWaveformAnimations(context: AnimationContext): {
+    presentationTracks: import("vue").ComputedRef<import("../core").TrackLayout[]>;
+    presentationAnnotations: import("vue").ComputedRef<{
+        seriesOpacity: number;
+        animationStyle?: import("../..").AnnotationAnimationState;
+        leaving?: boolean;
+        annotation: import("..").WaveformAnnotation;
+        trackIndex: number;
+        anchorX: number;
+        anchorY: number;
+        placement: import("../annotation").AnnotationPlacement;
+        lines: string[];
+        box: import("../annotation").AnnotationBoxLayout;
+        style: {
+            borderColor: string;
+            textColor: string;
+            backgroundColor: string;
+        };
+    }[]>;
+    paginationOpacity: import("vue").ShallowRef<number, number>;
+    stabilizeAnimations: (event?: Event) => void;
+    wrap: <T extends object>(commands: T) => T;
+    wrapPagination: (goToPage: (page: number) => void, count: import("vue").ComputedRef<number>) => (page: number) => void;
+    prepareExport: () => void;
+    releaseExport: () => void;
+};

package/dist/types/components/annotation/WaveformAnnotationContextMenu.vue.d.ts

@@ -6,12 +6,12 @@ interface Props {
 }
 declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
     edit: () => any;
-    delete: () => any;
     close: () => any;
+    delete: () => any;
 }, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
     onEdit?: (() => any) | undefined;
-    onDelete?: (() => any) | undefined;
     onClose?: (() => any) | undefined;
+    onDelete?: (() => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/types/components/annotation/types.d.ts

@@ -48,6 +48,13 @@ export interface AnnotationBoxLayout {
 }
 export type AnnotationPlacement = 'top' | 'bottom' | 'right' | 'left' | 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
 export interface RenderedAnnotation {
+    animationStyle?: {
+        opacity: number;
+        scale: number;
+        offsetY: number;
+    };
+    leaving?: boolean;
+    seriesOpacity?: number;
     annotation: WaveformAnnotation;
     trackIndex: number;
     anchorX: number;

package/dist/types/components/controls/useChartImageExport.d.ts

@@ -10,6 +10,8 @@ interface Context {
     };
     version: () => unknown;
     ready: () => boolean;
+    prepare?: () => void;
+    release?: () => void;
 }
 export declare function useChartImageExport(c: Context): {
     exportImage: (options?: WaveformImageExportOptions) => Promise<Blob>;

package/dist/types/components/core/amplitudeLimits.d.ts

@@ -0,0 +1,6 @@
+import type { WaveformAmplitudeLimit, WaveformAmplitudeLimits } from '../../types';
+export declare function normalizeAmplitudeLimit(limit?: WaveformAmplitudeLimit): WaveformAmplitudeLimit | undefined;
+export declare function mergeAmplitudeLimits(series: readonly {
+    id: string;
+}[], limits?: WaveformAmplitudeLimits): WaveformAmplitudeLimit | undefined;
+export declare function applyAmplitudeLimits(padded: [number, number], limit: WaveformAmplitudeLimit, automatic?: [number, number]): [number, number];

package/dist/types/components/core/layout.d.ts

@@ -1,14 +1,10 @@
-import type { WaveformOverlayMode } from '../../types';
+import type { WaveformAmplitudeLimit, WaveformAmplitudeLimits, WaveformOverlayMode } from '../../types';
 import type { DisplaySeries, DisplayTrack, TrackLayout } from './types';
 import { type WaveformYDomain } from './yDomain';
+export { resolveYAxisTicks, type ResolvedYAxisTicks } from './yAxisTicks';
 import { type YAxisPaddingOptions } from './yAxisPadding';
 export { MAX_MULTI_Y_AXIS_COUNT } from './constants';
 export declare function resolveYAxisTickCount(_plotHeight: number, splitNumber?: number): number;
-export interface ResolvedYAxisTicks {
-    domain: [number, number];
-    values: number[];
-}
-export declare function resolveYAxisTicks(domain: [number, number], tickCount?: number, nice?: boolean): ResolvedYAxisTicks;
 export declare function formatYAxisTickLabel(value: number, domain: [number, number], tickValues: readonly number[], unit?: string, side?: 'left' | 'right'): string;
 /** Name spacing excludes scientific multipliers; outer clearance measures the full label. */
 export declare function formatYAxisTickLayoutLabel(value: number, domain: [number, number], tickValues: readonly number[], unit?: string): string;
@@ -18,6 +14,7 @@ export interface YAxisSeriesGroup {
     seriesList: DisplaySeries[];
     domain: [number, number];
     fixed: boolean;
+    amplitudeLimit?: WaveformAmplitudeLimit;
     maximumTick?: number;
     minimumTick?: number;
 }
@@ -30,8 +27,8 @@ export interface YAxisSlot {
 }
 export declare function buildYAxisSeriesGroups(track: DisplayTrack, overlayMode: WaveformOverlayMode): YAxisSeriesGroup[];
 export declare function resolveYAxisSeriesGroups(track: DisplayTrack, overlayMode: WaveformOverlayMode, yDomain?: WaveformYDomain, yDomains?: Record<string, WaveformYDomain>): YAxisSeriesGroup[];
-export declare function resolveRenderedYAxisSeriesGroups(track: DisplayTrack, overlayMode: WaveformOverlayMode, yDomain?: WaveformYDomain, yDomains?: Record<string, WaveformYDomain>, viewportYDomains?: Record<string, [number, number]>, padding?: YAxisPaddingOptions | number): YAxisSeriesGroup[];
-export declare function axisTextMetrics(domain: [number, number], nice?: boolean, tickValues?: number[], unit?: string, tickCount?: number, includeWithoutLastTick?: boolean, measureTextWidth?: (text: string) => number, maximumTick?: number, minimumTick?: number): {
+export declare function resolveRenderedYAxisSeriesGroups(track: DisplayTrack, overlayMode: WaveformOverlayMode, yDomain?: WaveformYDomain, yDomains?: Record<string, WaveformYDomain>, viewportYDomains?: Record<string, [number, number]>, padding?: YAxisPaddingOptions | number, amplitudeLimits?: WaveformAmplitudeLimits): YAxisSeriesGroup[];
+export declare function axisTextMetrics(domain: [number, number], nice?: boolean, tickValues?: number[], unit?: string, tickCount?: number, includeWithoutLastTick?: boolean, measureTextWidth?: (text: string) => number, maximumTick?: number, minimumTick?: number, amplitudeLimit?: WaveformAmplitudeLimit): {
     tickTextWidth: number;
     titleTextWidth: number;
 };
@@ -44,7 +41,7 @@ export declare function measureTrackYAxisClearance(track: DisplayTrack, overlayM
  * Reserves stable Y-axis positions for every visible track on the current page.
  * Slots are ordered from the plot edge outward for each side.
  */
-export declare function buildYAxisSlots(tracks: readonly DisplayTrack[], overlayMode: WaveformOverlayMode, yDomain?: WaveformYDomain, yDomains?: Record<string, WaveformYDomain>, tickCount?: number, nice?: boolean, includeWithoutLastTick?: boolean, viewportYDomains?: Record<string, [number, number]>, padding?: YAxisPaddingOptions | number, showUnits?: boolean, measureTextWidth?: (text: string) => number): {
+export declare function buildYAxisSlots(tracks: readonly DisplayTrack[], overlayMode: WaveformOverlayMode, yDomain?: WaveformYDomain, yDomains?: Record<string, WaveformYDomain>, tickCount?: number, nice?: boolean, includeWithoutLastTick?: boolean, viewportYDomains?: Record<string, [number, number]>, padding?: YAxisPaddingOptions | number, showUnits?: boolean, measureTextWidth?: (text: string) => number, amplitudeLimits?: WaveformAmplitudeLimits): {
     slots: YAxisSlot[];
     clearance: {
         left: number;

package/dist/types/components/core/trackLayoutBuilder.d.ts

@@ -1,7 +1,7 @@
 import { type YAxisPaddingOptions } from './yAxisPadding';
 import { type ZoomTransform } from 'd3';
 import { type ResolvedWaveformRenderingOptions } from '../../core/rendering';
-import type { WaveformDisplayMode, WaveformOverlayMode, WaveformPoint, WaveformXDomainStrategy, WaveformXAxisLabelFormatter } from '../../types';
+import type { WaveformAmplitudeLimits, WaveformDisplayMode, WaveformOverlayMode, WaveformPoint, WaveformXDomainStrategy, WaveformXAxisLabelFormatter } from '../../types';
 import { type GridCellGeometry, type NormalizedWaveformGridOptions } from './grid';
 import { type YAxisSlot } from './layout';
 import type { DisplayTrack, TrackLayout } from './types';
@@ -20,6 +20,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]>;
@@ -40,6 +41,7 @@ export interface BuildTrackLayoutsOptions {
     useNonEmptyBottomTracks?: boolean;
     compactYAxisLayout?: boolean;
     showAxisUnits?: boolean;
+    domainTimeUnit?: 's' | 'ms';
 }
 export declare function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayout[];
 export {};

package/dist/types/components/core/types.d.ts

@@ -37,6 +37,14 @@ 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/dist/types/components/core/useWaveformChartController.d.ts

@@ -210,6 +210,26 @@ export declare function useWaveformChartController(inputProps: ResolvedWaveformC
     setTitleMeasureElement: (element: Element | ComponentPublicInstance | null) => void;
     setSharedOverlayElement: (element: Element | ComponentPublicInstance | null) => void;
     exportImage: (options?: import("../..").WaveformImageExportOptions) => Promise<Blob>;
+    presentationTracks: import("./types").TrackLayout[];
+    presentationAnnotations: {
+        seriesOpacity: number;
+        animationStyle?: import("../..").AnnotationAnimationState;
+        leaving?: boolean;
+        annotation: import("..").WaveformAnnotation;
+        trackIndex: number;
+        anchorX: number;
+        anchorY: number;
+        placement: import("../annotation").AnnotationPlacement;
+        lines: string[];
+        box: import("../annotation").AnnotationBoxLayout;
+        style: {
+            borderColor: string;
+            textColor: string;
+            backgroundColor: string;
+        };
+    }[];
+    paginationOpacity: number;
+    stabilizeAnimations: (event?: Event) => void;
     controlState: import("../..").WaveformControlState;
     getControlState: () => import("../..").WaveformControlState;
     execute: (action: import("../..").WaveformControlAction, target?: import("../..").WaveformControlTarget, domain?: [number, number], source?: "toolbar" | "api") => import("../..").WaveformControlResult;
@@ -245,7 +265,6 @@ export declare function useWaveformChartController(inputProps: ResolvedWaveformC
     updateViewportDrag: (event: PointerEvent) => void;
     finishViewportDrag: (event: PointerEvent) => void;
     cancelViewportDrag: (event?: PointerEvent) => void;
-    requestViewportReset: (event: MouseEvent) => void;
     toggleSeriesVisibility: (seriesId: string) => void;
     changeDraftSeries: (seriesId: string) => void;
     changeDraftTime: (displayValue: string) => void;
@@ -367,6 +386,7 @@ export declare function useWaveformChartController(inputProps: ResolvedWaveformC
     maxZoomScale?: number | null | undefined;
     initialXDomains?: Record<string, [number, number]> | undefined;
     xDomainStrategy: import("../..").WaveformXDomainStrategy;
+    amplitudeLimits?: import("../..").WaveformAmplitudeLimits | undefined;
     yDomain?: [number, number] | undefined;
     yDomains?: Record<string, [number, number]> | undefined;
     timeUnit: "s" | "ms";
@@ -387,5 +407,10 @@ export declare function useWaveformChartController(inputProps: ResolvedWaveformC
     cleanView: boolean;
     presentationMode: boolean;
     zeroLine: import("..").WaveformZeroLineOptions;
+    animationEnabled?: boolean | undefined;
+    animation?: import("../..").WaveformEnterAnimationOptions | undefined;
+    animationUpdate?: import("../..").WaveformUpdateAnimationOptions | undefined;
+    animationAnnotation?: import("../..").WaveformAnnotationAnimationOptions | undefined;
+    animationThreshold?: number | undefined;
 };
 export type WaveformChartController = ReturnType<typeof useWaveformChartController>;

package/dist/types/components/core/useWaveformData.d.ts

@@ -18,5 +18,5 @@ export interface PreparedWaveformSeries {
     yDomain: [number, number];
     hasErrorPoints: boolean;
 }
-export declare function prepareWaveformSeries(data: WaveformData): PreparedWaveformSeries[];
-export declare function usePreparedWaveformSeries(data: () => WaveformData, onBeforeDataChange: () => void, onDataChange: () => void): import("vue").ShallowRef<PreparedWaveformSeries[], PreparedWaveformSeries[]>;
+export declare function prepareWaveformSeries(data: WaveformData, retainEmpty?: boolean): PreparedWaveformSeries[];
+export declare function usePreparedWaveformSeries(data: () => WaveformData, onBeforeDataChange: () => void, onDataChange: () => void, retainEmpty?: () => boolean): import("vue").ShallowRef<PreparedWaveformSeries[], PreparedWaveformSeries[]>;

package/dist/types/components/core/useWaveformMeasurements.d.ts

@@ -1,2 +1,5 @@
 import type { LifecycleContext } from './useWaveformChartLifecycle';
-export declare function useWaveformMeasurements(context: Pick<LifecycleContext, 'container' | 'titleMeasureElement' | 'resizeObserver' | 'observedWidth' | 'observedHeight' | 'measuredTitleWidth' | 'measuredTitleHeight' | 'resolvedTitleText' | 'titleAreaReserved' | 'titleMeasureStyle'>): void;
+export declare function useWaveformMeasurements(context: Pick<LifecycleContext, 'container' | 'titleMeasureElement' | 'resizeObserver' | 'observedWidth' | 'observedHeight' | 'measuredTitleWidth' | 'measuredTitleHeight' | 'resolvedTitleText' | 'titleAreaReserved' | 'titleMeasureStyle'>, resizeHooks?: {
+    beforeResize?: () => void;
+    afterResize?: () => void;
+}): void;

package/dist/types/components/core/useWaveformRenderSampling.d.ts

@@ -14,6 +14,8 @@ interface SamplingContext {
     linePointOverrides: ShallowRef<Record<string, WaveformPoint[]>>;
 }
 export declare function useWaveformRenderSampling(context: SamplingContext): {
+    requestSignature: ComputedRef<string>;
+    state: ComputedRef<"error" | "pending" | "success" | "fallback">;
     linePointOverrides: ShallowRef<Record<string, WaveformPoint[]>>;
     ready: () => boolean;
 };

package/dist/types/components/core/waveformChartTypes.d.ts

@@ -1,7 +1,8 @@
+import type { WaveformAnimationProps } from '../../animation/types';
 import type { WaveformToolbarOptions, WaveformControlState } from '../../types/controls';
-import type { WaveformAnnotation, WaveformAxesOptions, WaveformData, WaveformDisplayMode, WaveformUnitDisplayMode, WaveformLayoutPreset, WaveformFrameStyle, WaveformInteractionMode, WaveformLegendOptions, WaveformOverlayMode, WaveformPlotMargin, WaveformPoint, WaveformRenderingOptions, WaveformSamplingBackend, WaveformSamplingDiagnostics, WaveformSamplingError, WaveformTitleOptions, WaveformXDomainStrategy, WaveformZeroLineOptions, WaveformZoomIntentPayload, WaveformZoomEndPayload, WaveformPanEndPayload, WaveformZoomResetPayload } from '../data/types';
+import type { WaveformAmplitudeLimits, WaveformAnnotation, WaveformAxesOptions, WaveformData, WaveformDisplayMode, WaveformUnitDisplayMode, WaveformLayoutPreset, WaveformFrameStyle, WaveformInteractionMode, WaveformLegendOptions, WaveformOverlayMode, WaveformPlotMargin, WaveformPoint, WaveformRenderingOptions, WaveformSamplingBackend, WaveformSamplingDiagnostics, WaveformSamplingError, WaveformTitleOptions, WaveformXDomainStrategy, WaveformZeroLineOptions, WaveformZoomIntentPayload, WaveformZoomEndPayload, WaveformPanEndPayload, WaveformZoomResetPayload } from '../data/types';
 import type { WaveformGridOptions } from './grid';
-export interface WaveformChartProps {
+export interface WaveformChartProps extends WaveformAnimationProps {
     toolbar?: boolean | WaveformToolbarOptions;
     data: WaveformData;
     displayMode?: WaveformDisplayMode;
@@ -17,7 +18,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. */
@@ -28,6 +29,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';

package/dist/types/components/core/xAxisTicks.d.ts

@@ -0,0 +1,2 @@
+/** ECharts-style numeric ticks inside the viewport; never expands its domain. */
+export declare function resolveXAxisTicks(domain: readonly [number, number], splitNumber: number, minInterval?: number): number[];

package/dist/types/components/core/yAxisLayoutMetrics.d.ts

@@ -1,3 +1,4 @@
+import type { WaveformAmplitudeLimits } from '../../types';
 import type { WaveformOverlayMode } from '../data/types';
 import type { DisplayTrack } from './types';
 import type { WaveformYDomain } from './yDomain';
@@ -8,4 +9,4 @@ export interface YAxisLayoutMetrics {
     labelCenterX: number;
 }
 export declare function resolveViewportYDomains(displayMode: 'independent' | 'separated' | 'compact', chartTracks: DisplayTrack[], sharedYDomains: Record<string, [number, number]>, independentYDomains: Record<number, [number, number]>): Record<string, [number, number]>;
-export declare function resolveYAxisLayoutMetrics(chartTracks: DisplayTrack[], overlayMode: WaveformOverlayMode, yDomain: WaveformYDomain | undefined, yDomains: Record<string, WaveformYDomain> | undefined, viewportYDomains: Record<string, [number, number]>, nice: boolean, tickCount: number, compact: boolean, padding?: YAxisPaddingOptions | number, showUnits?: boolean, measureTextWidth?: (text: string) => number): YAxisLayoutMetrics;
+export declare function resolveYAxisLayoutMetrics(chartTracks: DisplayTrack[], overlayMode: WaveformOverlayMode, yDomain: WaveformYDomain | undefined, yDomains: Record<string, WaveformYDomain> | undefined, viewportYDomains: Record<string, [number, number]>, nice: boolean, tickCount: number, compact: boolean, padding?: YAxisPaddingOptions | number, showUnits?: boolean, measureTextWidth?: (text: string) => number, amplitudeLimits?: WaveformAmplitudeLimits): YAxisLayoutMetrics;

package/dist/types/components/core/yAxisTicks.d.ts

@@ -0,0 +1,6 @@
+import type { WaveformAmplitudeLimit } from '../../types';
+export interface ResolvedYAxisTicks {
+    domain: [number, number];
+    values: number[];
+}
+export declare function resolveYAxisTicks(domain: [number, number], tickCount?: number, nice?: boolean, limit?: WaveformAmplitudeLimit): ResolvedYAxisTicks;

package/dist/types/components/data/types.d.ts

@@ -2,6 +2,6 @@
  * 数据系统类型定义
  * 重新导出 src/types 中的类型，方便组件内部使用
  */
-export type { WaveformPoint, WaveformDisplayMode, WaveformUnitDisplayMode, WaveformLayoutPreset, WaveformOverlayMode, WaveformInteractionMode, WaveformXDomainStrategy, WaveformZoomIntentPayload, WaveformZoomEndPayload, WaveformPanEndPayload, WaveformZoomResetPayload, WaveformAnnotationStyle, WaveformAnnotation, WaveformSamplingMode, WaveformSamplingStrategy, WaveformSamplingOptions, WaveformSamplingBackend, WaveformSamplingDiagnostics, WaveformSamplingError, WaveformRenderingOptions, WaveformPlotMargin, WaveformTitleTextStyle, WaveformTitleOptions, WaveformLegendPosition, WaveformLegendOrientation, WaveformLegendOptions, WaveformFrameStyle, WaveformAxesOptions, WaveformZeroLineOptions, SingleWaveformData, WaveformLineType, WaveformLineStyle, WaveformPointType, WaveformErrorBarOptions, ResolvedWaveformErrorBarOptions, WaveformTypedValues, TypedSampleData, TypedPointData, WaveformSeries, WaveformData, NormalizedWaveformSeries, } from '../../types';
+export type { WaveformAmplitudeLimit, WaveformAmplitudeLimits, WaveformPoint, WaveformDisplayMode, WaveformUnitDisplayMode, WaveformLayoutPreset, WaveformOverlayMode, WaveformInteractionMode, WaveformXDomainStrategy, WaveformZoomIntentPayload, WaveformZoomEndPayload, WaveformPanEndPayload, WaveformZoomResetPayload, WaveformAnnotationStyle, WaveformAnnotation, WaveformSamplingMode, WaveformSamplingStrategy, WaveformSamplingOptions, WaveformSamplingBackend, WaveformSamplingDiagnostics, WaveformSamplingError, WaveformRenderingOptions, WaveformPlotMargin, WaveformTitleTextStyle, WaveformTitleOptions, WaveformLegendPosition, WaveformLegendOrientation, WaveformLegendOptions, WaveformFrameStyle, WaveformAxesOptions, WaveformZeroLineOptions, SingleWaveformData, WaveformLineType, WaveformLineStyle, WaveformPointType, WaveformErrorBarOptions, ResolvedWaveformErrorBarOptions, WaveformTypedValues, TypedSampleData, TypedPointData, WaveformSeries, WaveformData, NormalizedWaveformSeries, } from '../../types';
 export type { WaveformGridOptions, WaveformGridLineOptions, WaveformGridTrackLines, } from '../core/grid';
 export { normalizeWaveformData, normalizeWaveformSeries } from '../../core';

package/dist/types/components/interaction/integerZoom.d.ts

@@ -4,9 +4,9 @@ export interface IntegerZoomOptions {
 }
 export declare function integerZoomTicks(domain: [number, number], count: number, options: IntegerZoomOptions): number[];
 export declare function formatIntegerZoomLabel(value: number): string;
-/** Align outwards in display units; all returned coordinates remain in seconds. */
+/** Align outwards only when the displayed span reaches one unit. */
 export declare function alignIntegerZoomDomain(domain: [number, number], options: IntegerZoomOptions): [number, number];
-/** Recover aligned endpoints after a D3 transform, tolerating floating-point round-off. */
+/** Recover endpoints after a D3 transform without applying a new zoom or changing pan span. */
 export declare function normalizeIntegerZoomDomain(domain: [number, number], options: IntegerZoomOptions): [number, number];
-/** Translation snaps to the nearest unit so panning preserves the visible span. */
+/** Integer viewports snap translation; sub-unit viewports pan freely across integers. */
 export declare function alignIntegerPanDomain(domain: [number, number], options: IntegerZoomOptions): [number, number];

package/dist/types/components/interaction/stepZoom.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedWaveformChartProps } from '../core/waveformChartTypes';
+import type { ZoomSeriesGroup } from './zoomConstraints';
+export declare const sameZoomDomain: (a: [number, number], b: [number, number]) => boolean;
+/** Toolbar and wheel steps share their scale factor and constraints. */
+export declare function resolveStepZoomDomain(current: [number, number], action: 'zoom-in' | 'zoom-out', boundary: [number, number], groups: readonly ZoomSeriesGroup[], props: ResolvedWaveformChartProps, anchorRatio?: number): [number, number];

package/dist/types/components/interaction/useWaveformViewport.d.ts

@@ -24,8 +24,6 @@ export interface ViewportContext {
     isPresentationMode: ComputedRef<boolean>;
     editorSeriesOptions: Ref<AnnotationSeriesCandidate[]>;
     resolveInitialTrackDomain: (track: TrackLayout) => [number, number];
-    canZoomTrack: (track: TrackLayout) => boolean;
-    canZoomSharedTracks: () => boolean;
     configureZoom: () => void;
     cancelPendingZoom: () => void;
     clearHover: () => void;
@@ -45,5 +43,4 @@ export declare function useWaveformViewport(context: ViewportContext): {
     cancelViewportDrag: (event?: PointerEvent) => void;
     resetViewport: (trackIndex?: number) => void;
     setViewportDomain: (domain: [number, number], trackIndex?: number) => void;
-    requestViewportReset: (event: MouseEvent) => void;
 };

package/dist/types/components/interaction/useWaveformZoom.d.ts

@@ -23,8 +23,6 @@ interface ZoomContext {
 export declare function useWaveformZoom(context: ZoomContext): {
     cancelPendingZoom: () => void;
     clearZoomBindings: (preservePendingWheel?: boolean) => void;
-    canZoomTrack: (track: TrackLayout) => boolean;
-    canZoomSharedTracks: () => boolean;
     configureZoom: () => void;
     prepareForDataChange: () => void;
 };

package/dist/types/components/rendering/WaveformSeriesLayer.vue.d.ts

@@ -1,6 +1,7 @@
 import type { TrackLayout } from '../core/types';
 type __VLS_Props = {
     track: TrackLayout;
+    paginationOpacity?: number;
     clipPathId: string;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

package/dist/types/components/rendering/WaveformTrack.vue.d.ts

@@ -3,6 +3,7 @@ import type { TrackLayout } from '../core/types';
 import type { WaveformDisplayMode, WaveformInteractionMode } from '../data/types';
 interface Props {
     track: TrackLayout;
+    paginationOpacity?: number;
     clipPathId: string;
     innerWidth: number;
     zoomable: boolean;
@@ -23,25 +24,25 @@ interface Props {
     zeroLine?: Required<WaveformZeroLineOptions>;
 }
 declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
-    contextmenu: (mouseEvent: MouseEvent) => any;
     click: (mouseEvent: MouseEvent) => any;
+    contextmenu: (mouseEvent: MouseEvent) => any;
     "pointer-move": (pointerEvent: PointerEvent) => any;
     "pointer-down": (pointerEvent: PointerEvent) => any;
     "pointer-up": (pointerEvent: PointerEvent) => any;
     "pointer-cancel": (pointerEvent: PointerEvent) => any;
     "pointer-leave": () => any;
 }, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
-    onContextmenu?: ((mouseEvent: MouseEvent) => any) | undefined;
     onClick?: ((mouseEvent: MouseEvent) => any) | undefined;
+    onContextmenu?: ((mouseEvent: MouseEvent) => any) | undefined;
     "onPointer-move"?: ((pointerEvent: PointerEvent) => any) | undefined;
     "onPointer-down"?: ((pointerEvent: PointerEvent) => any) | undefined;
     "onPointer-up"?: ((pointerEvent: PointerEvent) => any) | undefined;
     "onPointer-cancel"?: ((pointerEvent: PointerEvent) => any) | undefined;
     "onPointer-leave"?: (() => any) | undefined;
 }>, {
+    interactionMode: WaveformInteractionMode;
     cleanView: boolean;
     zeroLine: Required<WaveformZeroLineOptions>;
-    interactionMode: WaveformInteractionMode;
     interactive: boolean;
     showAxisUnits: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

package/dist/types/components/rendering/updateAxis.d.ts

@@ -0,0 +1,5 @@
+import type { Axis, NumberValue, ScaleLinear } from 'd3';
+/** Avoid invalidating native SVG layout when an attribute already has the required value. */
+export declare function updateSvgAttribute(element: Element, name: string, value: string | number | null): void;
+/** Domain animation moves existing ticks; unchanged labels keep their native text nodes. */
+export declare function updateAxis(element: SVGGElement, axis: Axis<NumberValue>, scale: ScaleLinear<number, number>, ticks: number[], orientation: 'bottom' | 'left' | 'right', format: (value: number) => string): void;

package/dist/types/components/rendering/updateGrid.d.ts

@@ -0,0 +1,3 @@
+import type { ScaleLinear } from 'd3';
+/** Keep each grid line independently discoverable by the axis collision pass. */
+export declare function updateGrid(group: SVGGElement, ticks: readonly number[], scale: ScaleLinear<number, number>, direction: 'vertical' | 'horizontal', extent: number, color: string | undefined): void;

package/dist/types/components/rendering/yAxisTickVisibility.d.ts

@@ -6,6 +6,8 @@ interface Box {
 }
 export declare function labelsOverlap(a: Box, b: Box): boolean;
 export declare function linesOverlap(a: number, b: number, widthA?: number, widthB?: number): boolean;
+/** Coalesce sibling axes after Vue's current DOM patch, without adding a late animation frame. */
+export declare function scheduleMaximumTickVisibility(svg: SVGSVGElement): void;
 /** Apply after axes and grid are in the DOM; never feed the filtered set back into layout. */
 export declare function updateMaximumTickVisibility(svg: SVGSVGElement): void;
 export {};

package/dist/types/components/utils/assignElement.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentPublicInstance, Ref } from 'vue';
+export declare function assignElement<T extends Element>(target: Ref<T | undefined>, element: Element | ComponentPublicInstance | null): void;

package/dist/types/core/data.d.ts

@@ -14,7 +14,7 @@ export interface NormalizedWaveformSourceSeries extends Omit<NormalizedWaveformS
     source: WaveformPointSource;
 }
 /** Internal normalized series which preserves compact TypedArray storage for chart rendering. */
-export declare function normalizeWaveformSeriesSources(data: WaveformData): NormalizedWaveformSourceSeries[];
+export declare function normalizeWaveformSeriesSources(data: WaveformData, retainEmpty?: boolean): NormalizedWaveformSourceSeries[];
 /**
  * 规范化波形系列数据
  * @param data 输入数据（单波形或多通道）