waveform-analysis 0.1.75 → 0.1.76

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/useWaveformChartController.d.ts

@@ -265,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;
@@ -387,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";

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/waveformChartTypes.d.ts

@@ -1,6 +1,6 @@
 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 extends WaveformAnimationProps {
     toolbar?: boolean | WaveformToolbarOptions;
@@ -18,7 +18,7 @@ export interface WaveformChartProps extends WaveformAnimationProps {
     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. */
@@ -29,6 +29,8 @@ export interface WaveformChartProps extends WaveformAnimationProps {
     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/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 输入数据（单波形或多通道）

package/dist/types/demo/DemoChartHost.vue.d.ts

@@ -1,5 +1,5 @@
 import type { DemoChartModel } from './types';
-declare function resetViewport(): void;
+declare function resetViewport(trackIndex?: number): void;
 type __VLS_ModelProps = {
     'model': DemoChartModel;
 };

package/dist/types/demo/remoteWaveformLoader.d.ts

@@ -0,0 +1,23 @@
+import type { InjectionKey } from 'vue';
+import type { WaveformData } from '../types';
+export interface RemoteWindowRequest {
+    start: number;
+    end: number;
+    seriesIds?: string[];
+}
+export type RemoteWindowLoader = (request: RemoteWindowRequest, signal: AbortSignal) => Promise<WaveformData>;
+export declare const remoteWindowLoaderKey: InjectionKey<RemoteWindowLoader>;
+export interface MockWindowOptions {
+    delayMs?: number | ((request: RemoteWindowRequest) => number);
+    empty?: boolean | ((request: RemoteWindowRequest) => boolean);
+    fail?: boolean | ((request: RemoteWindowRequest) => boolean);
+}
+/** Preserve series identities even when a window has no samples. */
+export declare function selectWaveformWindow(data: WaveformData, request: RemoteWindowRequest, empty?: boolean): WaveformData;
+export declare function mergeWaveformWindow(current: WaveformData, response: WaveformData, seriesIds?: string[]): WaveformData;
+/** Metadata is derived from the complete record, never from a loaded window. */
+export declare function waveformRecordMetadata(data: WaveformData): {
+    domain: [number, number];
+    minZoomSpan: number | undefined;
+};
+export declare function createMockWindowLoader(source: () => WaveformData, options?: MockWindowOptions): RemoteWindowLoader;

package/dist/types/demo/types.d.ts

@@ -1,4 +1,5 @@
-import type { WaveformAnnotation, WaveformAxesOptions, WaveformData, WaveformDisplayMode, WaveformFrameStyle, WaveformGridTrackLines, WaveformInteractionMode, WaveformLegendOrientation, WaveformLegendPosition, WaveformLineStyle, WaveformOverlayMode, WaveformPlotMargin, WaveformTitleOptions, WaveformZeroLineOptions, WaveformZoomEndPayload } from '../components';
+import type { WaveformAnnotation, WaveformAxesOptions, WaveformData, WaveformDisplayMode, WaveformFrameStyle, WaveformGridTrackLines, WaveformInteractionMode, WaveformLegendOrientation, WaveformLegendPosition, WaveformLineStyle, WaveformOverlayMode, WaveformPlotMargin, WaveformTitleOptions, WaveformZeroLineOptions, WaveformZoomEndPayload, WaveformZoomIntentPayload } from '../components';
+import type { WaveformZoomResetPayload, WaveformPanEndPayload } from '../types';
 import type { DemoXAxisLabelFormat, DemoXAxisLabelTimeZone } from './useDemoXAxisLabelControls';
 interface SelectOption<T> {
     label: string;
@@ -78,6 +79,11 @@ export interface DemoChartModel {
     toolbarVisible: boolean;
     data: WaveformData;
     initialXDomain?: [number, number];
+    recordDomain: [number, number];
+    minZoomSpan?: number;
+    loading: boolean;
+    errors: string[];
+    retry: () => Promise<void[]>;
     displayMode: WaveformDisplayMode;
     overlayMode: WaveformOverlayMode;
     rowCount: number;
@@ -101,6 +107,9 @@ export interface DemoChartModel {
     interactionMode: WaveformInteractionMode;
     hiddenSeriesIds: string[];
     handleZoomEnd: (payload: WaveformZoomEndPayload) => void | Promise<void>;
-    resetWaveformViewport: () => void;
+    handleZoomIntent: (payload: WaveformZoomIntentPayload) => void;
+    handleZoomChange: (domain: [number, number]) => void;
+    handlePanEnd: (payload: WaveformPanEndPayload) => void | Promise<void>;
+    resetWaveformViewport: (payload?: WaveformZoomResetPayload) => void | Promise<void>;
 }
 export {};

package/dist/types/demo/useRemoteWaveformWindow.d.ts

@@ -0,0 +1,22 @@
+import { type Ref } from 'vue';
+import type { WaveformData, WaveformPanEndPayload, WaveformZoomEndPayload, WaveformZoomIntentPayload, WaveformZoomResetPayload } from '../types';
+import { type RemoteWindowLoader } from './remoteWaveformLoader';
+interface RemoteWindowOptions {
+    loadWindow?: RemoteWindowLoader;
+    resetViewport?: (trackIndex?: number) => void;
+}
+export declare function useRemoteWaveformWindow(source: Ref<WaveformData>, options?: RemoteWindowOptions): {
+    chartData: import("vue").ShallowRef<WaveformData, WaveformData>;
+    recordDomain: import("vue").ComputedRef<[number, number]>;
+    initialXDomain: import("vue").ComputedRef<[number, number]>;
+    minZoomSpan: import("vue").ComputedRef<number | undefined>;
+    loading: import("vue").ComputedRef<boolean>;
+    errors: import("vue").ComputedRef<string[]>;
+    handleZoomIntent: (payload: WaveformZoomIntentPayload) => void;
+    handleZoomChange: (domain: [number, number]) => void;
+    handleZoomEnd: (payload: WaveformZoomEndPayload) => Promise<void>;
+    handlePanEnd: (payload: WaveformPanEndPayload) => Promise<void>;
+    resetWaveformViewport: (payload?: WaveformZoomResetPayload) => Promise<void>;
+    retry: () => Promise<void[]>;
+};
+export {};

package/dist/types/index.d.ts

@@ -13,7 +13,7 @@ export { Animation } from './animation/core/Animation';
 export { Animator, globalAnimator } from './animation/core/Animator';
 export type { AnimationValue, AnimationDirection, AnimationState, AnimationFrame, AnimationTrack, AnimationConfig, AnimationHandle, AnimationScheduler, EasingFunction, EasingFamily, EasingType, } from './animation/core/types';
 export type { LineDrawingDirection, AnnotationAnimationType, LineDrawingOptions, StaggeredLineDrawingOptions, DataUpdateOptions, AnnotationAnimationOptions, WaveformEnterAnimationOptions, WaveformUpdateAnimationOptions, WaveformAnnotationAnimationOptions, WaveformAnimationProps, ClipAnimationState, AnimationBinding, NumericGeometry, GeometryTransitionInput, GeometryTransitionFrame, AnnotationAnimationState, AnimationScope, AnimationObjectKey, WaveformAnimationControllerOptions, } from './animation/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, WaveformXAxisLabelKind, WaveformXAxisLabelFormatterContext, WaveformXAxisLabelFormatter, WaveformAxesOptions, WaveformYAxisLabelTextStyle, 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, WaveformXAxisLabelKind, WaveformXAxisLabelFormatterContext, WaveformXAxisLabelFormatter, WaveformAxesOptions, WaveformYAxisLabelTextStyle, WaveformZeroLineOptions, SingleWaveformData, WaveformLineType, WaveformLineStyle, WaveformPointType, WaveformErrorBarOptions, ResolvedWaveformErrorBarOptions, WaveformTypedValues, TypedSampleData, TypedPointData, WaveformSeries, WaveformData, NormalizedWaveformSeries, } from './types';
 export type { WaveformGridOptions, WaveformGridLineOptions, WaveformGridTrackLines, } from './components/core/grid';
 export { normalizeWaveformData, normalizeWaveformSeries } from './core';
 export { paddedDomain, buildMinorTicks, displayTime, formatEndpointTime, formatAxisTime, formatTooltipTime, resolveTrackGeometry, clamp, type TimeUnit, type TrackGeometry, } from './utils';

package/dist/types/types/chart.d.ts

@@ -68,7 +68,7 @@ export interface WaveformZoomIntentPayload extends WaveformCommandMetadata {
     trackIndex?: number;
     seriesIds?: string[];
 }
-/** Identifies the viewport reset by a double-click gesture. */
+/** Identifies the viewport reset by a toolbar or API command. */
 export interface WaveformZoomResetPayload extends WaveformCommandMetadata {
     trackIndex?: number;
     seriesIds?: string[];
@@ -279,3 +279,10 @@ export interface WaveformZeroLineOptions {
     /** Hide within this fraction of a Y-axis tick interval from either boundary. Defaults to 0.02. */
     boundaryThreshold?: number;
 }
+/** Strict amplitude display bounds, in the series' original Y units. */
+export interface WaveformAmplitudeLimit {
+    lower?: number;
+    upper?: number;
+}
+/** Keyed by stable normalized series IDs (not track IDs). */
+export type WaveformAmplitudeLimits = Record<string, WaveformAmplitudeLimit>;

package/dist/types/types/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * 类型定义统一导出
  */
-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, WaveformXAxisLabelKind, WaveformXAxisLabelFormatterContext, WaveformXAxisLabelFormatter, WaveformAxesOptions, WaveformYAxisLabelTextStyle, WaveformZeroLineOptions, } from './chart';
+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, WaveformXAxisLabelKind, WaveformXAxisLabelFormatterContext, WaveformXAxisLabelFormatter, WaveformAxesOptions, WaveformYAxisLabelTextStyle, WaveformZeroLineOptions, } from './chart';
 export type { SingleWaveformData, WaveformLineType, WaveformLineStyle, WaveformPointType, WaveformErrorBarOptions, ResolvedWaveformErrorBarOptions, WaveformTypedValues, TypedSampleData, TypedPointData, WaveformSeries, WaveformData, NormalizedWaveformSeries, } from './data';
 export type { WaveformToolbarItem, WaveformToolbarOptions, WaveformControlTarget, WaveformControlAction, WaveformCommandMetadata, WaveformTargetStatus, WaveformViewportSnapshot, WaveformTargetResult, WaveformControlResult, WaveformControlState, WaveformImageExportOptions, WaveformImageExportErrorCode, WaveformImageExportError, WaveformChartHandle, } from './controls';

package/dist/types/utils/formatters.d.ts

@@ -46,18 +46,18 @@ export declare function formatXAxisLabel(rawValue: number, domain: [number, numb
  */
 export declare function endpointFractionDigits(domain: [number, number], timeUnit: TimeUnit): number;
 /**
- * 将 X 轴端点时间格式化为当前显示单位下的普通十进制文本
+ * 将 X 轴端点时间格式化为当前显示单位下的自适应精度文本
  * @param value 时间值（秒）
- * @param _domain 数据域（为保持现有调用签名而保留）
+ * @param _domain 用于计算显示精度的可视域
  * @param timeUnit 时间单位
  * @returns 格式化的时间字符串
  */
 export declare function formatEndpointTime(value: number, _domain: [number, number], timeUnit: TimeUnit): string;
 /**
- * 将 X 轴时间刻度格式化为当前显示单位下的普通十进制文本
+ * 将 X 轴时间刻度格式化为当前显示单位下的自适应精度文本
  * @param value 时间值（秒）
  * @param timeUnit 时间单位
- * @param _domain 数据域（为保持现有调用签名而保留）
+ * @param _domain 用于计算显示精度的可视域
  * @returns 格式化的时间字符串
  */
 export declare function formatAxisTime(value: number, timeUnit: TimeUnit, _domain?: [number, number]): string;

package/dist/types/utils/xAxisNumber.d.ts

@@ -0,0 +1,2 @@
+/** Compact labels share precision so even extremely close endpoints stay distinct. */
+export declare function formatXAxisNumber(value: number, domain: [number, number]): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waveform-analysis",
-  "version": "0.1.75",
+  "version": "0.1.76",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/types/index.d.ts",

package/src/App.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, reactive, ref } from 'vue'
+import { computed, inject, onBeforeUnmount, onMounted, reactive, ref, shallowRef } from 'vue'
 import 'vue3-colorpicker/style.css'
 
 import {
@@ -16,7 +16,6 @@ import {
   type WaveformOverlayMode,
   type WaveformPlotMargin,
   type WaveformTitleOptions,
-  type WaveformZoomEndPayload,
   type WaveformZeroLineOptions,
 } from './components'
 import { normalizeWaveformSeries } from './core'
@@ -25,6 +24,8 @@ import DemoChartHost from './demo/DemoChartHost.vue'
 import DemoControlPanel from './demo/DemoControlPanel.vue'
 import type { DemoChartModel, DemoControlPanelModel } from './demo/types'
 import { useDemoXAxisLabelControls } from './demo/useDemoXAxisLabelControls'
+import { remoteWindowLoaderKey } from './demo/remoteWaveformLoader'
+import { useRemoteWaveformWindow } from './demo/useRemoteWaveformWindow'
 
 const demoPreset = new URLSearchParams(window.location.search).get('demo')
 const compactNineDemo = demoPreset === 'compact-nine'
@@ -164,20 +165,27 @@ const plotMargin = computed<WaveformPlotMargin>(() => ({
   bottom: plotMarginBottom.value,
 }))
 
-const initialXValues = normalizeWaveformSeries(fullChartData).flatMap((series) =>
-  series.points.map((point) => point.x),
-)
-const [initialXMinimum, initialXMaximum] = initialXValues.reduce<[number, number]>(
-  ([minimum, maximum], value) => [Math.min(minimum, value), Math.max(maximum, value)],
-  [Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY],
-)
-const initialXDomainValue: [number, number] | undefined =
-  Number.isFinite(initialXMinimum) && Number.isFinite(initialXMaximum)
-    ? [initialXMinimum, initialXMaximum]
-    : undefined
-// Keep the full source domain stable while viewport data windows are replaced.
-const initialXDomain = ref<[number, number] | undefined>(initialXDomainValue)
-const chartData = ref<WaveformData>(fullChartData)
+const demoChartHostRef = ref<{ resetViewport: (trackIndex?: number) => void }>()
+const sourceData = shallowRef<WaveformData>(fullChartData)
+const remoteWindow = useRemoteWaveformWindow(sourceData, {
+  loadWindow: inject(remoteWindowLoaderKey, undefined),
+  resetViewport: (trackIndex) => demoChartHostRef.value?.resetViewport(trackIndex),
+})
+const {
+  chartData,
+  initialXDomain,
+  recordDomain,
+  minZoomSpan,
+  loading,
+  errors,
+  handleZoomIntent,
+  handleZoomChange,
+  handleZoomEnd,
+  handlePanEnd,
+  resetWaveformViewport,
+  retry,
+} = remoteWindow
+onMounted(() => void resetWaveformViewport())
 const lineStyleOverrides = ref<Record<string, WaveformLineStyle>>({})
 const selectedSeriesId = ref(
   fullChartData.kind === 'series' ? (fullChartData.series[0]?.id ?? '') : '',
@@ -188,7 +196,7 @@ const lineStyleOptions: Array<{ label: string; value: WaveformLineStyle }> = [
   { label: '点划线', value: 'dash-dot' },
 ]
 const seriesStyleOptions = computed(() =>
-  normalizeWaveformSeries(chartData.value).map((series) => ({
+  normalizeWaveformSeries(sourceData.value).map((series) => ({
     label: series.name || series.id,
     value: series.id,
   })),
@@ -214,7 +222,7 @@ const displayChartData = computed<WaveformData>(() => {
 })
 const gridTrackLines = computed<WaveformGridTrackLines>(() =>
   Object.fromEntries(
-    normalizeWaveformSeries(displayChartData.value).map((series) => [
+    normalizeWaveformSeries(sourceData.value).map((series) => [
       series.trackId ?? series.id,
       {
         horizontal: horizontalGridVisible.value,
@@ -225,88 +233,6 @@ const gridTrackLines = computed<WaveformGridTrackLines>(() =>
     ]),
   ),
 )
-const demoChartHostRef = ref<{ resetViewport: (trackIndex?: number) => void }>()
-
-let zoomRequestSequence = 0
-
-function filterWaveformData(data: WaveformData, start: number, end: number): WaveformData {
-  const lower = Math.min(start, end)
-  const upper = Math.max(start, end)
-  if (data.kind !== 'series') {
-    if (data.kind !== 'points') return data
-    return {
-      kind: 'points',
-      points: data.points.filter((point) => point.x >= lower && point.x <= upper),
-    }
-  }
-  return {
-    kind: 'series',
-    series: data.series.map((series) => ({
-      ...series,
-      data:
-        series.data.kind === 'points'
-          ? {
-              kind: 'points',
-              points: series.data.points.filter((point) => point.x >= lower && point.x <= upper),
-            }
-          : series.data,
-    })),
-  }
-}
-
-function mergeIndependentWindow(
-  currentData: WaveformData,
-  responseData: WaveformData,
-  seriesIds: string[],
-): WaveformData {
-  if (currentData.kind !== 'series' || responseData.kind !== 'series') return responseData
-  const responseById = new Map(responseData.series.map((series) => [series.id, series]))
-  const changedIds = new Set(seriesIds)
-  return {
-    kind: 'series',
-    series: currentData.series.map((series) =>
-      series.id && changedIds.has(series.id) ? (responseById.get(series.id) ?? series) : series,
-    ),
-  }
-}
-
-let pendingCommandId: string | undefined
-let pendingPayloads: WaveformZoomEndPayload[] = []
-async function handleZoomEnd(payload: WaveformZoomEndPayload) {
-  if (payload.action === 'fit') return
-  if (payload.commandId && payload.commandId === pendingCommandId) {
-    pendingPayloads.push(payload)
-    return
-  }
-  pendingCommandId = payload.commandId
-  const batch = [payload]
-  pendingPayloads = batch
-  // Demo-only sequence number cancellation. Production code should use AbortController
-  // to cancel in-flight requests when a newer zoom gesture arrives.
-  const requestSequence = ++zoomRequestSequence
-  await new Promise((resolve) => window.setTimeout(resolve, 80))
-  if (requestSequence !== zoomRequestSequence) return
-
-  // Demo-only stand-in for the backend response. Production code should replace this
-  // with a request using payload.start/payload.end and the optional channel metadata.
-  let nextData = chartData.value
-  batch.forEach((item) => {
-    const responseData = filterWaveformData(fullChartData, item.start, item.end)
-    nextData =
-      item.trackIndex !== undefined && item.seriesIds?.length
-        ? mergeIndependentWindow(nextData, responseData, item.seriesIds)
-        : responseData
-  })
-  chartData.value = nextData
-  pendingCommandId = undefined
-}
-
-function resetWaveformViewport() {
-  zoomRequestSequence += 1
-  chartData.value = fullChartData
-  initialXDomain.value = initialXDomainValue
-  demoChartHostRef.value?.resetViewport()
-}
 const titleOptions = computed<WaveformTitleOptions>(() => ({
   visible: titleVisible.value,
   text: titleText.value,
@@ -406,6 +332,11 @@ const chartModel = reactive({
   toolbarVisible,
   data: displayChartData,
   initialXDomain,
+  recordDomain,
+  minZoomSpan,
+  loading,
+  errors,
+  retry,
   displayMode,
   overlayMode,
   rowCount,
@@ -428,7 +359,10 @@ const chartModel = reactive({
   annotationsVisible,
   interactionMode,
   hiddenSeriesIds,
+  handleZoomIntent,
+  handleZoomChange,
   handleZoomEnd,
+  handlePanEnd,
   resetWaveformViewport,
 }) satisfies DemoChartModel
 </script>

package/src/components/WaveformChartView.vue

@@ -46,7 +46,6 @@ const {
   chartWidth,
   drawingHeight,
   hasWaveformData,
-  requestViewportReset,
   trackLayouts,
   presentationTracks,
   presentationAnnotations,
@@ -189,7 +188,6 @@ function handleChartPointerLeave() {
       :height="drawingHeight"
       role="img"
       :aria-label="hasWaveformData ? '波形折线图' : '暂无波形数据'"
-      @dblclick="requestViewportReset"
     >
       <defs>
         <clipPath