@waveform-playlist/browser 7.1.3 → 8.1.0

package/dist/index.d.ts

@@ -1,16 +1,17 @@
 import { Analyser } from 'tone';
-import { BaseContext } from 'tone';
 import { default as default_2 } from 'react';
 import { default as default_3 } from 'waveform-data';
+import { DragCancelEvent } from '@dnd-kit/core';
 import { DragEndEvent } from '@dnd-kit/core';
 import { DragMoveEvent } from '@dnd-kit/core';
 import { DragStartEvent } from '@dnd-kit/core';
-import { Fade as Fade_2 } from '@waveform-playlist/core';
+import { EngineState } from '@waveform-playlist/engine';
 import { Gain } from 'tone';
 import { InputNode } from 'tone';
 import { MediaElementPlayout } from '@waveform-playlist/media-element-playout';
 import { Modifier } from '@dnd-kit/core';
 import { MutableRefObject } from 'react';
+import { PlaylistEngine } from '@waveform-playlist/engine';
 import { Provider } from 'react';
 import react__default from 'react';
 import { ReactNode } from 'react';
@@ -19,7 +20,6 @@ import { SensorDescriptor } from '@dnd-kit/core';
 import { SensorOptions } from '@dnd-kit/core';
 import * as Tone from 'tone';
 import { ToneAudioNode } from 'tone';
-import { Track } from '@waveform-playlist/core';
 import { Volume } from 'tone';
 
 export declare interface ActiveEffect {
@@ -262,16 +262,6 @@ export declare const AutomaticScrollCheckbox: default_2.FC<{
  */
 declare type Bits = 8 | 16;
 
-declare interface ClipInfo {
-    buffer: AudioBuffer;
-    startTime: number;
-    duration: number;
-    offset: number;
-    fadeIn?: Fade_2;
-    fadeOut?: Fade_2;
-    gain: number;
-}
-
 declare interface ClipPeaks {
     clipId: string;
     trackName: string;
@@ -630,6 +620,8 @@ export declare const MasterVolumeControl: default_2.FC<{
 export declare interface MasterVolumeControls {
     masterVolume: number;
     setMasterVolume: (volume: number) => void;
+    /** Ref holding the current masterVolume for seeding a fresh engine. */
+    masterVolumeRef: React.RefObject<number>;
 }
 
 export declare interface MediaElementAnimationContextValue {
@@ -890,6 +882,8 @@ declare interface PlaybackAnimationContextValue {
     currentTimeRef: default_2.RefObject<number>;
     playbackStartTimeRef: default_2.RefObject<number>;
     audioStartPositionRef: default_2.RefObject<number>;
+    /** Returns current playback time from engine (auto-wraps at loop boundaries). */
+    getPlaybackTime: () => number;
 }
 
 export declare const PlayButton: default_2.FC<{
@@ -908,9 +902,9 @@ declare interface PlayheadProps {
     isPlaying: boolean;
     /** Ref to current time in seconds - use for smooth animation during playback */
     currentTimeRef: react__default.RefObject<number>;
-    /** Audio context start time when playback began - for calculating elapsed time */
+    /** Audio context start time when playback began. Fallback when getPlaybackTime is not provided. */
     playbackStartTimeRef: react__default.RefObject<number>;
-    /** Audio position when playback started - for calculating current position */
+    /** Audio position when playback started. Fallback when getPlaybackTime is not provided. */
     audioStartPositionRef: react__default.RefObject<number>;
     /** Samples per pixel - for converting time to pixels */
     samplesPerPixel: number;
@@ -920,6 +914,8 @@ declare interface PlayheadProps {
     controlsOffset: number;
     /** Function to get current audio context time - required for smooth animation */
     getAudioContextTime?: () => number;
+    /** Returns current playback time (auto-wraps at loop boundaries). Preferred over manual elapsed calculation. */
+    getPlaybackTime?: () => number;
 }
 
 /**
@@ -1004,7 +1000,7 @@ declare interface PlaylistDataContextValue {
         show: boolean;
         width: number;
     };
-    playoutRef: default_2.RefObject<TonePlayout | null>;
+    playoutRef: default_2.RefObject<PlaylistEngine | null>;
     samplesPerPixel: number;
     timeFormat: TimeFormat;
     masterVolume: number;
@@ -1018,6 +1014,9 @@ declare interface PlaylistDataContextValue {
     isReady: boolean;
     /** Whether tracks are rendered in mono mode */
     mono: boolean;
+    /** Ref set by useClipDragHandlers during boundary trim drags.
+     *  When true, loadAudio skips engine rebuild — visual updates flow via React state only. */
+    isDraggingRef: default_2.MutableRefObject<boolean>;
 }
 
 declare interface PlaylistStateContextValue {
@@ -1246,88 +1245,6 @@ export declare const TimeFormatSelect: default_2.FC<{
 
 export { Tone }
 
-declare class TonePlayout {
-    private tracks;
-    private masterVolume;
-    private isInitialized;
-    private soloedTracks;
-    private manualMuteState;
-    private effectsCleanup?;
-    private onPlaybackCompleteCallback?;
-    private activeTracks;
-    private playbackSessionId;
-    constructor(options?: TonePlayoutOptions);
-    private gainToDb;
-    init(): Promise<void>;
-    addTrack(trackOptions: ToneTrackOptions): ToneTrack;
-    /**
-     * Apply solo muting after all tracks have been added.
-     * Call this after adding all tracks to ensure solo logic is applied correctly.
-     */
-    applyInitialSoloState(): void;
-    removeTrack(trackId: string): void;
-    getTrack(trackId: string): ToneTrack | undefined;
-    play(when?: number, offset?: number, duration?: number): void;
-    pause(): void;
-    stop(): void;
-    setMasterGain(gain: number): void;
-    setSolo(trackId: string, soloed: boolean): void;
-    private updateSoloMuting;
-    setMute(trackId: string, muted: boolean): void;
-    getCurrentTime(): number;
-    seekTo(time: number): void;
-    dispose(): void;
-    get context(): BaseContext;
-    get sampleRate(): number;
-    setOnPlaybackComplete(callback: () => void): void;
-}
-
-declare interface TonePlayoutOptions {
-    tracks?: ToneTrack[];
-    masterGain?: number;
-    effects?: EffectsFunction;
-}
-
-declare class ToneTrack {
-    private clips;
-    private volumeNode;
-    private panNode;
-    private muteGain;
-    private track;
-    private effectsCleanup?;
-    private onStopCallback?;
-    private activePlayers;
-    constructor(options: ToneTrackOptions);
-    /**
-     * Schedule fade envelopes for a clip at the given start time
-     */
-    private scheduleFades;
-    private gainToDb;
-    setVolume(gain: number): void;
-    setPan(pan: number): void;
-    setMute(muted: boolean): void;
-    setSolo(soloed: boolean): void;
-    play(when?: number, offset?: number, duration?: number): void;
-    pause(): void;
-    stop(when?: number): void;
-    dispose(): void;
-    get id(): string;
-    get duration(): number;
-    get buffer(): AudioBuffer;
-    get isPlaying(): boolean;
-    get muted(): boolean;
-    get startTime(): number;
-    setOnStopCallback(callback: () => void): void;
-}
-
-declare interface ToneTrackOptions {
-    buffer?: AudioBuffer;
-    clips?: ClipInfo[];
-    track: Track;
-    effects?: TrackEffectsFunction;
-    destination?: ToneAudioNode;
-}
-
 export declare interface TrackActiveEffect {
     instanceId: string;
     effectId: string;
@@ -1601,13 +1518,22 @@ declare interface UseAudioTracksOptions {
  * Provides drag handlers and collision modifier for use with @dnd-kit/core DndContext.
  * Handles both clip movement (dragging entire clips) and boundary trimming (adjusting clip edges).
  *
+ * **Move:** `onDragEnd` delegates to `engine.moveClip()` in one shot.
+ *
+ * **Trim:** `onDragMove` updates React state per-frame via `onTracksChange` for smooth
+ * visual feedback (using cumulative deltas from the original clip snapshot). `isDraggingRef`
+ * prevents loadAudio from rebuilding the engine during the drag, so the engine keeps the
+ * original clip positions. On drag end, `engine.trimClip()` commits the final delta.
+ *
  * @example
  * ```tsx
- * const { onDragStart, onDragMove, onDragEnd, collisionModifier } = useClipDragHandlers({
+ * const { onDragStart, onDragMove, onDragEnd, onDragCancel, collisionModifier } = useClipDragHandlers({
  *   tracks,
  *   onTracksChange: setTracks,
  *   samplesPerPixel,
  *   sampleRate,
+ *   engineRef: playoutRef,
+ *   isDraggingRef,
  * });
  *
  * return (
@@ -1615,6 +1541,7 @@ declare interface UseAudioTracksOptions {
  *     onDragStart={onDragStart}
  *     onDragMove={onDragMove}
  *     onDragEnd={onDragEnd}
+ *     onDragCancel={onDragCancel}
  *     modifiers={[restrictToHorizontalAxis, collisionModifier]}
  *   >
  *     <Waveform showClipHeaders={true} />
@@ -1622,10 +1549,11 @@ declare interface UseAudioTracksOptions {
  * );
  * ```
  */
-export declare function useClipDragHandlers({ tracks, onTracksChange, samplesPerPixel, sampleRate, }: UseClipDragHandlersOptions): {
+export declare function useClipDragHandlers({ tracks, onTracksChange, samplesPerPixel, sampleRate, engineRef, isDraggingRef, }: UseClipDragHandlersOptions): {
     onDragStart: (event: DragStartEvent) => void;
     onDragMove: (event: DragMoveEvent) => void;
     onDragEnd: (event: DragEndEvent) => void;
+    onDragCancel: (_event: DragCancelEvent) => void;
     collisionModifier: (args: Parameters<Modifier>[0]) => {
         scaleX: number;
         scaleY: number;
@@ -1639,11 +1567,20 @@ declare interface UseClipDragHandlersOptions {
     onTracksChange: (tracks: ClipTrack[]) => void;
     samplesPerPixel: number;
     sampleRate: number;
+    engineRef: default_2.RefObject<PlaylistEngine | null>;
+    /** Ref toggled during boundary trim drags. When true, the provider's loadAudio
+     *  skips engine rebuilds so engine keeps original clip positions. On drag end,
+     *  engine.trimClip() commits the final delta. Obtain from usePlaylistData(). */
+    isDraggingRef: default_2.MutableRefObject<boolean>;
 }
 
 /**
  * Hook for splitting clips at the playhead or at a specific time
  *
+ * Splitting delegates to `engine.splitClip()` — the engine handles clip creation,
+ * adapter sync, and emits statechange. The provider's statechange handler propagates
+ * the updated tracks to the parent via `onTracksChange`.
+ *
  * @param options - Configuration options
  * @returns Object with split functions
  *
@@ -1651,8 +1588,9 @@ declare interface UseClipDragHandlersOptions {
  * ```tsx
  * const { splitClipAtPlayhead } = useClipSplitting({
  *   tracks,
- *   onTracksChange: setTracks,
- *   currentTime,
+ *   sampleRate,
+ *   samplesPerPixel,
+ *   engineRef: playoutRef,
  * });
  *
  * // In keyboard handler
@@ -1667,9 +1605,9 @@ export declare const useClipSplitting: (options: UseClipSplittingOptions) => Use
 
 declare interface UseClipSplittingOptions {
     tracks: ClipTrack[];
-    onTracksChange: (tracks: ClipTrack[]) => void;
     sampleRate: number;
     samplesPerPixel: number;
+    engineRef: default_2.RefObject<PlaylistEngine | null>;
 }
 
 declare interface UseClipSplittingResult {
@@ -1808,27 +1746,19 @@ export declare const useMasterAnalyser: (fftSize?: number) => {
 };
 
 /**
- * Hook for managing master volume control
+ * Hook for managing master volume via PlaylistEngine delegation.
  *
- * @example
- * ```tsx
- * const { masterVolume, setMasterVolume } = useMasterVolume({
- *   playoutRef,
- *   initialVolume: 1.0,
- * });
- *
- * <MasterVolumeControl
- *   volume={masterVolume}
- *   onChange={setMasterVolume}
- * />
- * ```
+ * setMasterVolume delegates to the engine. State is mirrored back from
+ * the engine via onEngineState(), which the provider's statechange
+ * handler calls on every engine event.
  */
-export declare function useMasterVolume({ playoutRef, initialVolume, onVolumeChange, }: UseMasterVolumeProps): MasterVolumeControls;
+export declare function useMasterVolume({ engineRef, initialVolume, }: UseMasterVolumeProps): MasterVolumeControls & {
+    onEngineState: (state: EngineState) => void;
+};
 
 declare interface UseMasterVolumeProps {
-    playoutRef: RefObject<TonePlayout | null>;
+    engineRef: RefObject<PlaylistEngine | null>;
     initialVolume?: number;
-    onVolumeChange?: (volume: number) => void;
 }
 
 export declare const useMediaElementAnimation: () => MediaElementAnimationContextValue;
@@ -1950,11 +1880,24 @@ export declare interface UseTrackDynamicEffectsReturn {
     availableEffects: EffectDefinition[];
 }
 
-export declare function useZoomControls({ initialSamplesPerPixel, zoomLevels, }: UseZoomControlsProps): ZoomControls;
+/**
+ * Hook for managing zoom controls via PlaylistEngine delegation.
+ *
+ * zoomIn/zoomOut delegate to the engine. State is mirrored back from
+ * the engine via onEngineState(), which the provider's statechange
+ * handler calls on every engine event.
+ *
+ * samplesPerPixel updates use startTransition so React treats them as
+ * non-urgent — during playback, animation RAF callbacks interleave
+ * with the zoom re-render instead of being blocked.
+ */
+export declare function useZoomControls({ engineRef, initialSamplesPerPixel, }: UseZoomControlsProps): ZoomControls & {
+    onEngineState: (state: EngineState) => void;
+};
 
 declare interface UseZoomControlsProps {
+    engineRef: RefObject<PlaylistEngine | null>;
     initialSamplesPerPixel: number;
-    zoomLevels?: number[];
 }
 
 /**
@@ -2087,6 +2030,15 @@ declare interface WaveformPlaylistProviderProps {
     barGap?: number;
     /** Width in pixels of progress bars. Default: barWidth + barGap (fills gaps). */
     progressBarWidth?: number;
+    /** Callback when engine clip operations (move, trim, split) change tracks.
+     * The provider calls this so the parent can update its tracks state without
+     * triggering a full engine rebuild.
+     *
+     * **Important:** The parent must pass the received `tracks` reference back as
+     * the `tracks` prop (i.e. `setState(tracks)`). The provider uses reference
+     * identity (`tracks === engineTracksRef.current`) to detect engine-originated
+     * updates and skip the expensive `loadAudio` rebuild. */
+    onTracksChange?: (tracks: ClipTrack[]) => void;
     children: ReactNode;
 }