waveform-analysis 0.1.55 → 0.1.58

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

@@ -9,6 +9,8 @@ export interface WaveformGridOptions {
     fillIncompleteLastRow?: boolean;
     /** Stable grid slots. Empty IDs remain as empty chart frames and keep their page position. */
     trackOrder?: string[];
+    /** Omits ordered tracks without waveform series from layout and pagination. */
+    hideEmptyTracks?: boolean;
     trackLines?: WaveformGridTrackLines;
 }
 export interface WaveformGridLineOptions {
@@ -32,6 +34,7 @@ export interface NormalizedWaveformGridOptions {
     showPagination: boolean;
     fillIncompleteLastRow: boolean;
     trackOrder?: string[];
+    hideEmptyTracks?: boolean;
     trackLines: Record<string, NormalizedWaveformGridLineOptions>;
 }
 export interface GridCellGeometry {

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

@@ -10,6 +10,13 @@ export interface YAxisSeriesGroup {
     domain: [number, number];
     fixed: boolean;
 }
+export interface YAxisSlot {
+    side: 'left' | 'right';
+    sideIndex: number;
+    axisOffset: number;
+    labelOffset: number;
+    clearance: number;
+}
 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 axisTextMetrics(domain: [number, number], nice?: boolean, tickValues?: number[], unit?: string, tickCount?: number): {
@@ -20,6 +27,17 @@ export declare function measureTrackYAxisClearance(track: DisplayTrack, overlayM
     left: number;
     right: number;
 };
+/**
+ * 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): {
+    slots: YAxisSlot[];
+    clearance: {
+        left: number;
+        right: number;
+    };
+};
 type PositionedTrack = Pick<TrackLayout, 'left' | 'top' | 'width' | 'height'>;
 export declare function findClosestTrackAtPointer<T extends PositionedTrack>(tracks: readonly T[], pointerX: number, pointerY: number): T | undefined;
 export { buildTrackLayouts, type BuildTrackLayoutsOptions } from './trackLayoutBuilder';

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

@@ -2,6 +2,7 @@ import { type ZoomTransform } from 'd3';
 import { type ResolvedWaveformRenderingOptions } from '../../core/rendering';
 import type { 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';
 interface SeriesGridCell extends GridCellGeometry {
     series?: DisplayTrack;
@@ -28,6 +29,7 @@ export interface BuildTrackLayoutsOptions {
     linePointOverrides?: Readonly<Record<string, WaveformPoint[]>>;
     hideSecondaryLabels: boolean;
     yAxisLabelX: number;
+    yAxisSlots?: readonly YAxisSlot[];
     showCompactEmptyTracks: boolean;
 }
 export declare function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayout[];

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

@@ -0,0 +1,4 @@
+import type { DisplayTrack } from './types';
+export declare const resolvePageableTracks: (tracks: DisplayTrack[], hideEmptyTracks?: boolean) => DisplayTrack[];
+export declare const resolveTrackFrameNumber: (frameNumber: string | number | undefined, frameNumbers: Record<string, string | number> | undefined, trackCount: number, trackIndex: number, trackId: string) => string | number | undefined;
+export declare const createFrameNumberResolver: (getFrameNumber: () => string | number | undefined, getFrameNumbers: () => Record<string, string | number> | undefined, getTracks: () => DisplayTrack[]) => (trackId: string) => string | number | undefined;

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

@@ -246,6 +246,7 @@ export declare function useWaveformChartController(props: ResolvedWaveformChartP
     confirmAnnotation: (annotation: import("..").WaveformAnnotation) => void;
     chartSeries: import("./types").DisplaySeries[];
     chartTracks: import("./types").DisplayTrack[];
+    pageableTracks: import("./types").DisplayTrack[];
     renderingOptions: import("../..").ResolvedWaveformRenderingOptions;
     gridOptions: import("./grid").NormalizedWaveformGridOptions;
     pageCount: number;
@@ -281,7 +282,7 @@ export declare function useWaveformChartController(props: ResolvedWaveformChartP
     annotationTrackLayouts: import("../annotation").AnnotationTrackLayout[];
     renderedAnnotations: import("../annotation").RenderedAnnotation[];
     editorSeries: import("../annotation").AnnotationSeriesInfo | undefined;
-    resolveFrameNumber: (trackIndex: number) => string | number | undefined;
+    resolveFrameNumber: (trackId: string) => string | number | undefined;
     fixedWidth: number | undefined;
     fixedHeight: number | undefined;
     chartWidth: number;
@@ -341,6 +342,7 @@ export declare function useWaveformChartController(props: ResolvedWaveformChartP
     yDomains?: Record<string, [number, number]> | undefined;
     timeUnit: "s" | "ms";
     frameNumber?: string | number | undefined;
+    frameNumbers?: Record<string, string | number> | undefined;
     frameStyle?: import("..").WaveformFrameStyle | undefined;
     axes?: import("..").WaveformAxesOptions | undefined;
     annotations: import("..").WaveformAnnotation[];

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

@@ -23,6 +23,7 @@ interface LayoutContext {
 export declare function useWaveformLayout(context: LayoutContext): {
     chartSeries: ComputedRef<DisplaySeries[]>;
     chartTracks: ComputedRef<DisplayTrack[]>;
+    pageableTracks: ComputedRef<DisplayTrack[]>;
     renderingOptions: ComputedRef<import("../..").ResolvedWaveformRenderingOptions>;
     gridOptions: ComputedRef<import("./grid").NormalizedWaveformGridOptions>;
     pageCount: ComputedRef<number>;
@@ -58,6 +59,6 @@ export declare function useWaveformLayout(context: LayoutContext): {
     annotationTrackLayouts: ComputedRef<AnnotationTrackLayout[]>;
     renderedAnnotations: ComputedRef<import("../annotation").RenderedAnnotation[]>;
     editorSeries: ComputedRef<AnnotationSeriesInfo | undefined>;
-    resolveFrameNumber: (trackIndex: number) => string | number | undefined;
+    resolveFrameNumber: (trackId: string) => string | number | undefined;
 };
 export {};

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

@@ -22,6 +22,8 @@ export interface WaveformChartProps {
     yDomains?: Record<string, [number, number]>;
     timeUnit?: 's' | 'ms';
     frameNumber?: string | number;
+    /** Per-track frame watermark overrides, keyed by stable trackId. */
+    frameNumbers?: Record<string, string | number>;
     frameStyle?: WaveformFrameStyle;
     axes?: WaveformAxesOptions;
     annotations?: WaveformAnnotation[];

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

@@ -3,4 +3,5 @@ export declare const Y_AXIS_TICK_PADDING = 7;
 export declare const Y_AXIS_OUTER_PADDING = 4;
 export declare const Y_AXIS_LABEL_GAP = 0;
 export declare const Y_AXIS_LABEL_BAND_WIDTH = 12;
+export declare const Y_AXIS_RIGHT_LABEL_OFFSET = 10;
 export declare function resolveYAxisSides(axisCount: number): Array<'left' | 'right'>;

package/package.json

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

package/src/App.test.ts

@@ -231,7 +231,7 @@ describe('App workspace layout', { timeout: 20_000 }, () => {
       tracks.map((track) =>
         track.findAll('.waveform-chart__series').map((item) => item.attributes('data-series-name')),
       ),
-    ).toEqual([['正弦基波'], ['谐波扰动', '谐波对比'], ['阻尼振荡'], ['阶跃响应']])
+    ).toEqual([['正弦基波'], ['谐波扰动', '谐波对比', '谐波校正'], ['阻尼振荡'], ['阶跃响应']])
     expect(
       tracks
         .slice(1)
@@ -250,6 +250,7 @@ describe('App workspace layout', { timeout: 20_000 }, () => {
       '正弦基波',
       '谐波扰动',
       '谐波对比',
+      '谐波校正',
       '阻尼振荡',
       '阶跃响应',
       '脉冲响应',

package/src/components/WaveformChartView.vue

@@ -80,7 +80,7 @@ const {
   pageCount,
   currentPage,
   getPageSize,
-  chartTracks,
+  pageableTracks,
   goToPage,
   annotationInteraction,
   editorDraft,
@@ -230,7 +230,7 @@ function handleChartPointerLeave() {
           :interactive="!isPresentationMode"
           :display-mode="displayMode"
           :interaction-mode="activeInteractionMode"
-          :frame-number="resolveFrameNumber(track.index)"
+          :frame-number="resolveFrameNumber(track.id)"
           :frame-style="frameStyle"
           :axes="axes"
           :clean-view="isCleanView"
@@ -326,7 +326,7 @@ function handleChartPointerLeave() {
       aria-label="波形分页"
       :current="currentPage"
       :page-size="getPageSize(gridOptions)"
-      :total="chartTracks.length"
+      :total="pageableTracks.length"
       :show-size-changer="false"
       :show-quick-jumper="false"
       @change="goToPage"

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

@@ -17,6 +17,7 @@ describe('waveform grid helpers', () => {
       showPagination: true,
       fillIncompleteLastRow: false,
       trackOrder: [],
+      hideEmptyTracks: false,
       trackLines: {},
     })
     expect(normalizeGridOptions({ rowCount: 0, columnCount: 99 })).toEqual({
@@ -25,8 +26,10 @@ describe('waveform grid helpers', () => {
       showPagination: true,
       fillIncompleteLastRow: false,
       trackOrder: [],
+      hideEmptyTracks: false,
       trackLines: {},
     })
+    expect(normalizeGridOptions({ hideEmptyTracks: true }).hideEmptyTracks).toBe(true)
   })
 
   it('normalizes track order by trimming, dropping blanks, and removing duplicates', () => {

package/src/components/core/grid.ts

@@ -11,6 +11,8 @@ export interface WaveformGridOptions {
   fillIncompleteLastRow?: boolean
   /** Stable grid slots. Empty IDs remain as empty chart frames and keep their page position. */
   trackOrder?: string[]
+  /** Omits ordered tracks without waveform series from layout and pagination. */
+  hideEmptyTracks?: boolean
   trackLines?: WaveformGridTrackLines
 }
 
@@ -38,6 +40,7 @@ export interface NormalizedWaveformGridOptions {
   showPagination: boolean
   fillIncompleteLastRow: boolean
   trackOrder?: string[]
+  hideEmptyTracks?: boolean
   trackLines: Record<string, NormalizedWaveformGridLineOptions>
 }
 
@@ -95,6 +98,7 @@ export function normalizeGridOptions(options?: WaveformGridOptions): NormalizedW
     showPagination: options?.showPagination ?? true,
     fillIncompleteLastRow: options?.fillIncompleteLastRow ?? false,
     trackOrder: normalizeTrackOrder(options?.trackOrder),
+    hideEmptyTracks: options?.hideEmptyTracks ?? false,
     trackLines,
   }
 }

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

@@ -254,7 +254,7 @@ describe('multi-value Y-axis grouping', () => {
       })),
     ).toEqual([
       { side: 'left', labelOffset: 55 },
-      { side: 'right', labelOffset: 55 },
+      { side: 'right', labelOffset: 45 },
     ])
   })
 

package/src/components/core/layout.ts

@@ -35,6 +35,14 @@ export interface YAxisSeriesGroup {
   fixed: boolean
 }
 
+export interface YAxisSlot {
+  side: 'left' | 'right'
+  sideIndex: number
+  axisOffset: number
+  labelOffset: number
+  clearance: number
+}
+
 function resolveAxisSides(axisCount: number): Array<'left' | 'right'> {
   if (axisCount >= 4) return ['left', 'left', 'right', 'right']
   if (axisCount === 3) return ['left', 'right', 'right']
@@ -181,6 +189,61 @@ export function measureTrackYAxisClearance(
   )
 }
 
+/**
+ * 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 function buildYAxisSlots(
+  tracks: readonly DisplayTrack[],
+  overlayMode: WaveformOverlayMode,
+  yDomain?: WaveformYDomain,
+  yDomains?: Record<string, WaveformYDomain>,
+  tickCount?: number,
+  nice = true,
+): { slots: YAxisSlot[]; clearance: { left: number; right: number } } {
+  const widths = new Map<string, number>()
+  tracks.forEach((track) => {
+    const sideIndexes = { left: 0, right: 0 }
+    resolveYAxisSeriesGroups(track, overlayMode, yDomain, yDomains).forEach((group) => {
+      const sideIndex = sideIndexes[group.side]++
+      const key = `${group.side}:${sideIndex}`
+      const width = axisTextMetrics(
+        group.domain,
+        nice,
+        undefined,
+        group.seriesList[0]?.unit,
+        tickCount,
+      ).tickTextWidth
+      widths.set(key, Math.max(widths.get(key) ?? Y_AXIS_CHARACTER_WIDTH, width))
+    })
+  })
+
+  const slots: YAxisSlot[] = []
+  const clearance = { left: 0, right: 0 }
+  ;(['left', 'right'] as const).forEach((side) => {
+    const sideIndexes = Array.from(widths.keys())
+      .filter((key) => key.startsWith(`${side}:`))
+      .map((key) => Number(key.slice(side.length + 1)))
+      .sort((first, second) => first - second)
+    sideIndexes.forEach((sideIndex) => {
+      const tickTextWidth = widths.get(`${side}:${sideIndex}`) ?? Y_AXIS_CHARACTER_WIDTH
+      const axisOffset = side === 'left' && clearance.left > 0 ? -clearance.left : clearance[side]
+      const labelDistance =
+        tickTextWidth + Y_AXIS_TICK_PADDING + Y_AXIS_LABEL_GAP + Y_AXIS_LABEL_BAND_WIDTH / 2
+      const labelOffset = axisOffset + labelDistance * (side === 'left' ? -1 : 1)
+      const fullClearance =
+        tickTextWidth +
+        Y_AXIS_TICK_PADDING +
+        Y_AXIS_LABEL_GAP +
+        Y_AXIS_LABEL_BAND_WIDTH +
+        Y_AXIS_OUTER_PADDING
+      slots.push({ side, sideIndex, axisOffset, labelOffset, clearance: fullClearance })
+      clearance[side] += fullClearance
+    })
+  })
+  return { slots, clearance }
+}
+
 type PositionedTrack = Pick<TrackLayout, 'left' | 'top' | 'width' | 'height'>
 
 export function findClosestTrackAtPointer<T extends PositionedTrack>(

package/src/components/core/trackLayoutBuilder.ts

@@ -25,13 +25,19 @@ import {
   type GridCellGeometry,
   type NormalizedWaveformGridOptions,
 } from './grid'
-import { axisTextMetrics, resolveYAxisSeriesGroups, resolveYAxisTickCount } from './layout'
+import {
+  axisTextMetrics,
+  resolveYAxisSeriesGroups,
+  resolveYAxisTickCount,
+  type YAxisSlot,
+} from './layout'
 import type { DisplayTrack, TrackLayout, WaveformYAxisLayout } from './types'
 import { applyXDomainStrategy } from './xDomain'
 import {
   Y_AXIS_LABEL_BAND_WIDTH,
   Y_AXIS_LABEL_GAP,
   Y_AXIS_OUTER_PADDING,
+  Y_AXIS_RIGHT_LABEL_OFFSET,
   Y_AXIS_TICK_PADDING,
 } from './yAxisConstants'
 
@@ -61,6 +67,7 @@ export interface BuildTrackLayoutsOptions {
   linePointOverrides?: Readonly<Record<string, WaveformPoint[]>>
   hideSecondaryLabels: boolean
   yAxisLabelX: number
+  yAxisSlots?: readonly YAxisSlot[]
   showCompactEmptyTracks: boolean
 }
 
@@ -117,8 +124,10 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
     ).map((group) =>
       !group.fixed && configuredYDomain ? { ...group, domain: configuredYDomain } : group,
     )
+    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 niceCount = Math.max(1, tickCount - 1)
       const scale = scaleLinear(group.domain, [cell.plotHeight, 0])
@@ -144,11 +153,22 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
         Y_AXIS_LABEL_GAP +
         Y_AXIS_LABEL_BAND_WIDTH +
         Y_AXIS_OUTER_PADDING
-      const x = group.side === 'left' ? -sideOffsets.left : cell.width + sideOffsets.right
+      const slot = options.yAxisSlots?.find(
+        (candidate) => candidate.side === group.side && candidate.sideIndex === sideIndex,
+      )
+      const x = slot
+        ? (group.side === 'left' ? 0 : cell.width) + slot.axisOffset
+        : group.side === 'left'
+          ? -sideOffsets.left
+          : cell.width + sideOffsets.right
       const labelDistance =
         tickTextWidth + Y_AXIS_TICK_PADDING + Y_AXIS_LABEL_GAP + Y_AXIS_LABEL_BAND_WIDTH / 2
-      const labelX = x + (group.side === 'left' ? -labelDistance : labelDistance)
-      sideOffsets[group.side] += clearance
+      const labelX =
+        (slot
+          ? (group.side === 'left' ? 0 : cell.width) + slot.labelOffset
+          : x + (group.side === 'left' ? -labelDistance : labelDistance)) -
+        (group.side === 'right' ? Y_AXIS_RIGHT_LABEL_OFFSET : 0)
+      if (!slot) sideOffsets[group.side] += clearance
       return {
         index: group.index,
         side: group.side,

package/src/components/core/trackPagination.ts

@@ -0,0 +1,40 @@
+import type { DisplayTrack } from './types'
+
+export const resolvePageableTracks = (
+  tracks: DisplayTrack[],
+  hideEmptyTracks?: boolean,
+): DisplayTrack[] => (hideEmptyTracks ? tracks.filter((track) => track.series.length > 0) : tracks)
+
+export const resolveTrackFrameNumber = (
+  frameNumber: string | number | undefined,
+  frameNumbers: Record<string, string | number> | undefined,
+  trackCount: number,
+  trackIndex: number,
+  trackId: string,
+): string | number | undefined => {
+  const mappedFrameNumber = frameNumbers?.[trackId]
+  if (mappedFrameNumber !== undefined) return mappedFrameNumber
+  if (frameNumber === undefined) return undefined
+  if (trackCount === 1) return frameNumber
+  return typeof frameNumber === 'number'
+    ? frameNumber + trackIndex
+    : `${frameNumber}-${trackIndex + 1}`
+}
+
+export const createFrameNumberResolver =
+  (
+    getFrameNumber: () => string | number | undefined,
+    getFrameNumbers: () => Record<string, string | number> | undefined,
+    getTracks: () => DisplayTrack[],
+  ) =>
+  (trackId: string): string | number | undefined => {
+    const tracks = getTracks()
+    const trackIndex = tracks.findIndex((track) => track.id === trackId)
+    return resolveTrackFrameNumber(
+      getFrameNumber(),
+      getFrameNumbers(),
+      tracks.length,
+      trackIndex >= 0 ? trackIndex : 0,
+      trackId,
+    )
+  }

package/src/components/core/useWaveformLayout.ts

@@ -27,10 +27,11 @@ import {
 import {
   buildTrackLayouts,
   axisTextMetrics,
-  measureTrackYAxisClearance,
+  buildYAxisSlots,
   resolveYAxisSeriesGroups,
 } from './layout'
 import type { DisplaySeries, DisplayTrack, TrackLayout } from './types'
+import { createFrameNumberResolver, resolvePageableTracks } from './trackPagination'
 import type { PreparedWaveformSeries } from './useWaveformData'
 import type { ResolvedWaveformChartProps } from './waveformChartTypes'
 import { applyXDomainStrategy } from './xDomain'
@@ -107,9 +108,12 @@ export function useWaveformLayout(context: LayoutContext) {
     })
   })
   const renderingOptions = computed(() => resolveWaveformRenderingOptions(props.rendering))
-  const pageCount = computed(() => getPageCount(chartTracks.value.length, gridOptions.value))
+  const pageableTracks = computed(() =>
+    resolvePageableTracks(chartTracks.value, gridOptions.value.hideEmptyTracks),
+  )
+  const pageCount = computed(() => getPageCount(pageableTracks.value.length, gridOptions.value))
   const pagedTracks = computed(() =>
-    paginateSeries(chartTracks.value, currentPage.value, gridOptions.value),
+    paginateSeries(pageableTracks.value, currentPage.value, gridOptions.value),
   )
   const layoutTracks = computed(() => {
     const tracksWithSeries = pagedTracks.value.filter((track) => track.series.length > 0)
@@ -169,33 +173,24 @@ export function useWaveformLayout(context: LayoutContext) {
           : 0,
     ),
   )
-  const multiAxisClearance = computed(() =>
-    chartTracks.value.reduce(
-      (maximum, track) => {
-        const clearance = measureTrackYAxisClearance(
-          track,
-          props.overlayMode,
-          props.yDomain,
-          props.yDomains,
-          props.axes?.y?.splitNumber,
-          props.axes?.y?.nice !== false,
-        )
-        return {
-          left: Math.max(maximum.left, clearance.left),
-          right: Math.max(maximum.right, clearance.right),
-        }
-      },
-      { left: 0, right: 0 },
+  const yAxisSlots = computed(() =>
+    buildYAxisSlots(
+      layoutTracks.value.filter((track) => track.visibleSeries.length > 0),
+      props.overlayMode,
+      props.yDomain,
+      props.yDomains,
+      props.axes?.y?.splitNumber,
+      props.axes?.y?.nice !== false,
     ),
   )
   const resolvedChartLeftMargin = computed(() =>
     props.overlayMode === 'multi-axis'
-      ? Math.max(chartLeftMargin.value, multiAxisClearance.value.left)
+      ? Math.max(chartLeftMargin.value, yAxisSlots.value.clearance.left)
       : chartLeftMargin.value,
   )
   const chartRightMargin = computed(() =>
     props.overlayMode === 'multi-axis'
-      ? Math.max(margin.right, multiAxisClearance.value.right)
+      ? Math.max(margin.right, yAxisSlots.value.clearance.right)
       : margin.right,
   )
   const innerWidth = computed(() =>
@@ -212,7 +207,7 @@ export function useWaveformLayout(context: LayoutContext) {
     return {
       horizontalGap:
         props.overlayMode === 'multi-axis' && hasMultipleColumns && hasVisibleWaveformData.value
-          ? Math.max(baseGap, multiAxisClearance.value.left + multiAxisClearance.value.right)
+          ? Math.max(baseGap, yAxisSlots.value.clearance.left + yAxisSlots.value.clearance.right)
           : hasMultipleColumns && hasVisibleWaveformData.value
             ? hasYAxisLabels.value && canReserveLabelClearance
               ? fullGap
@@ -323,7 +318,10 @@ export function useWaveformLayout(context: LayoutContext) {
       rendering: renderingOptions.value,
       linePointOverrides: linePointOverrides?.value,
       hideSecondaryLabels: isCleanView.value || yAxisLayout.value.hideSecondaryLabels,
-      yAxisLabelX: yAxisMetrics.value.labelCenterX,
+      yAxisLabelX:
+        yAxisSlots.value.slots.find((slot) => slot.side === 'left' && slot.sideIndex === 0)
+          ?.labelOffset ?? yAxisMetrics.value.labelCenterX,
+      yAxisSlots: props.overlayMode === 'multi-axis' ? yAxisSlots.value.slots : undefined,
       showCompactEmptyTracks: props.displayMode === 'compact' && hasWaveformData.value,
     }),
   )
@@ -363,16 +361,15 @@ export function useWaveformLayout(context: LayoutContext) {
         }
       : undefined
   })
-  const resolveFrameNumber = (trackIndex: number): string | number | undefined => {
-    if (props.frameNumber === undefined || props.frameNumber === null) return undefined
-    if (chartTracks.value.length === 1) return props.frameNumber
-    return typeof props.frameNumber === 'number'
-      ? props.frameNumber + trackIndex
-      : `${props.frameNumber}-${trackIndex + 1}`
-  }
+  const resolveFrameNumber = createFrameNumberResolver(
+    () => props.frameNumber,
+    () => props.frameNumbers,
+    () => chartTracks.value,
+  )
   return {
     chartSeries,
     chartTracks,
+    pageableTracks,
     renderingOptions,
     gridOptions,
     pageCount,

package/src/components/core/waveformChartTypes.ts

@@ -43,6 +43,8 @@ export interface WaveformChartProps {
   yDomains?: Record<string, [number, number]>
   timeUnit?: 's' | 'ms'
   frameNumber?: string | number
+  /** Per-track frame watermark overrides, keyed by stable trackId. */
+  frameNumbers?: Record<string, string | number>
   frameStyle?: WaveformFrameStyle
   axes?: WaveformAxesOptions
   annotations?: WaveformAnnotation[]

package/src/components/core/yAxisConstants.ts

@@ -3,6 +3,7 @@ export const Y_AXIS_TICK_PADDING = 7
 export const Y_AXIS_OUTER_PADDING = 4
 export const Y_AXIS_LABEL_GAP = 0
 export const Y_AXIS_LABEL_BAND_WIDTH = 12
+export const Y_AXIS_RIGHT_LABEL_OFFSET = 10
 
 export function resolveYAxisSides(axisCount: number): Array<'left' | 'right'> {
   if (axisCount >= 4) return ['left', 'left', 'right', 'right']