@dawcore/components 0.0.2 → 0.0.4

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import * as lit from 'lit';
 import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost } from 'lit';
-import { Peaks, Bits, FadeType, PeakData, ClipTrack } from '@waveform-playlist/core';
+import { Peaks, Bits, FadeType, PeakData, ClipTrack, KeyboardShortcut } from '@waveform-playlist/core';
+import WaveformData from 'waveform-data';
 import { PlaylistEngine } from '@waveform-playlist/engine';
 
 declare class DawClipElement extends LitElement {
@@ -184,6 +185,7 @@ interface TrackDescriptor {
 }
 interface ClipDescriptor {
     src: string;
+    peaksSrc: string;
     start: number;
     duration: number;
     offset: number;
@@ -213,6 +215,11 @@ declare class PeakPipeline {
     private _baseScale;
     private _bits;
     constructor(baseScale?: number, bits?: 8 | 16);
+    /**
+     * Inject externally-loaded WaveformData (e.g., from a .dat file) into the cache.
+     * Prevents worker generation for this AudioBuffer on all subsequent calls.
+     */
+    cacheWaveformData(audioBuffer: AudioBuffer, waveformData: WaveformData): void;
     /**
      * Generate PeakData for a clip from its AudioBuffer.
      * Uses cached WaveformData when available; otherwise generates via worker.
@@ -221,14 +228,26 @@ declare class PeakPipeline {
     generatePeaks(audioBuffer: AudioBuffer, samplesPerPixel: number, isMono: boolean, offsetSamples?: number, durationSamples?: number): Promise<PeakData>;
     /**
      * Re-extract peaks for all clips at a new zoom level using cached WaveformData.
-     * Only works for zoom levels coarser than (or equal to) the cached base scale.
-     * Returns a new Map of clipId → PeakData. Clips without cached data or where
-     * the target scale is finer than the cached base are skipped.
+     * Returns a new Map of clipId → PeakData. Clips without cached data are skipped.
+     * When the requested scale is finer than cached data, peaks are clamped to the
+     * cached scale and a single summary warning is logged.
      */
     reextractPeaks(clipBuffers: ReadonlyMap<string, AudioBuffer>, samplesPerPixel: number, isMono: boolean, clipOffsets?: ReadonlyMap<string, {
         offsetSamples: number;
         durationSamples: number;
     }>): Map<string, PeakData>;
+    /**
+     * Clamp requested scale to cached WaveformData scale.
+     * WaveformData.resample() can only go coarser — if the requested zoom is
+     * finer than the cached data, use the cached scale. Set warn=true to log
+     * (default); reextractPeaks passes false and logs a single summary instead.
+     */
+    private _clampScale;
+    /**
+     * Return the coarsest (largest) scale among cached WaveformData entries
+     * that correspond to the given clip buffers. Returns 0 if none are cached.
+     */
+    getMaxCachedScale(clipBuffers: ReadonlyMap<string, AudioBuffer>): number;
     terminate(): void;
     private _getWaveformData;
 }
@@ -335,13 +354,19 @@ interface ClipBounds {
 }
 /** Narrow engine contract for clip move/trim interactions. */
 interface ClipEngineContract {
-    moveClip(trackId: string, clipId: string, deltaSamples: number, skipAdapter?: boolean): void;
+    moveClip(trackId: string, clipId: string, deltaSamples: number, skipAdapter?: boolean): number;
     trimClip(trackId: string, clipId: string, boundary: 'left' | 'right', deltaSamples: number, skipAdapter?: boolean): void;
     updateTrack(trackId: string): void;
     /** Get a clip's full bounds for trim constraint computation. */
     getClipBounds(trackId: string, clipId: string): ClipBounds | null;
     /** Constrain a trim delta using the engine's collision/bounds logic. */
     constrainTrimDelta(trackId: string, clipId: string, boundary: 'left' | 'right', deltaSamples: number): number;
+    /** Begin a transaction — groups mutations into one undo step. */
+    beginTransaction(): void;
+    /** Commit the transaction — pushes one undo step for all grouped mutations. */
+    commitTransaction(): void;
+    /** Abort the transaction — restores pre-transaction state without pushing to undo. */
+    abortTransaction(): void;
 }
 /** Peak data returned by reextractClipPeaks for imperative waveform updates. */
 interface ClipPeakSlice {
@@ -510,7 +535,9 @@ interface LoadFilesResult {
 }
 
 declare class DawEditorElement extends LitElement {
-    samplesPerPixel: number;
+    get samplesPerPixel(): number;
+    set samplesPerPixel(value: number);
+    private _samplesPerPixel;
     waveHeight: number;
     timescale: boolean;
     mono: boolean;
@@ -537,12 +564,15 @@ declare class DawEditorElement extends LitElement {
     _engine: PlaylistEngine | null;
     private _enginePromise;
     _audioCache: Map<string, Promise<AudioBuffer>>;
+    private _peaksCache;
     _clipBuffers: Map<string, AudioBuffer>;
     _clipOffsets: Map<string, {
         offsetSamples: number;
         durationSamples: number;
     }>;
     _peakPipeline: PeakPipeline;
+    /** Coarsest scale from pre-computed peaks — zoom cannot go finer than this. 0 = no limit. */
+    private _minSamplesPerPixel;
     private _trackElements;
     private _childObserver;
     private _audioResume;
@@ -582,6 +612,7 @@ declare class DawEditorElement extends LitElement {
     private _readTrackDescriptor;
     private _loadTrack;
     _fetchAndDecode(src: string): Promise<AudioBuffer>;
+    private _fetchPeaks;
     _recomputeDuration(): void;
     _ensureEngine(): Promise<PlaylistEngine>;
     private _buildEngine;
@@ -593,10 +624,19 @@ declare class DawEditorElement extends LitElement {
     play(startTime?: number): Promise<void>;
     pause(): void;
     stop(): void;
+    /** Toggle between play and pause. */
+    togglePlayPause(): void;
     seekTo(time: number): void;
+    /** Undo the last structural edit. */
+    undo(): void;
+    /** Redo the last undone edit. */
+    redo(): void;
+    /** Whether undo is available. */
+    get canUndo(): boolean;
+    /** Whether redo is available. */
+    get canRedo(): boolean;
     /** Split the clip under the playhead on the selected track. */
     splitAtPlayhead(): boolean;
-    private _onKeyDown;
     recordingStream: MediaStream | null;
     get currentTime(): number;
     get isRecording(): boolean;
@@ -668,6 +708,59 @@ declare global {
     }
 }
 
+/** Key binding for remapping — derived from KeyboardShortcut to stay in sync. */
+type KeyBinding = Pick<KeyboardShortcut, 'key' | 'ctrlKey' | 'shiftKey' | 'metaKey' | 'altKey'>;
+interface PlaybackShortcutMap {
+    playPause?: KeyBinding;
+    stop?: KeyBinding;
+    rewindToStart?: KeyBinding;
+}
+interface SplittingShortcutMap {
+    splitAtPlayhead?: KeyBinding;
+}
+interface UndoShortcutMap {
+    undo?: KeyBinding;
+    redo?: KeyBinding;
+}
+/**
+ * Render-less element that enables keyboard shortcuts for a parent <daw-editor>.
+ * Place inside the editor element. Boolean attributes enable preset categories;
+ * JS properties allow remapping and custom shortcuts.
+ *
+ * ```html
+ * <daw-editor>
+ *   <daw-keyboard-shortcuts playback splitting undo></daw-keyboard-shortcuts>
+ * </daw-editor>
+ * ```
+ */
+declare class DawKeyboardShortcutsElement extends LitElement {
+    playback: boolean;
+    splitting: boolean;
+    undo: boolean;
+    playbackShortcuts: PlaybackShortcutMap | null;
+    splittingShortcuts: SplittingShortcutMap | null;
+    undoShortcuts: UndoShortcutMap | null;
+    /** Additional custom shortcuts. */
+    customShortcuts: KeyboardShortcut[];
+    private _editor;
+    private _cachedShortcuts;
+    /** All active shortcuts (read-only, cached). */
+    get shortcuts(): KeyboardShortcut[];
+    /** Invalidate cached shortcuts when Lit properties change. */
+    updated(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    createRenderRoot(): this;
+    private _buildShortcuts;
+    private _makeShortcut;
+    private _onKeyDown;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-keyboard-shortcuts': DawKeyboardShortcutsElement;
+    }
+}
+
 declare class AudioResumeController implements ReactiveController {
     private _host;
     private _target;
@@ -704,15 +797,20 @@ interface SplitEngineContract {
 interface SplitHost {
     readonly effectiveSampleRate: number;
     readonly currentTime: number;
+    readonly isPlaying: boolean;
     readonly engine: SplitEngineContract | null;
     dispatchEvent(event: Event): boolean;
+    stop(): void;
+    play(time: number): void;
 }
 /**
- * Splits the clip under the playhead on the selected track.
+ * Split the clip under the playhead on the selected track.
+ * Stops playback before split and resumes after to avoid duplicate audio
+ * from Transport rescheduling during playback.
  *
  * Returns true if the split occurred and dispatched a daw-clip-split event.
  * Returns false for any guard failure or engine no-op.
  */
 declare function splitAtPlayhead(host: SplitHost): boolean;
 
-export { AudioResumeController, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, DawClipElement, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawPauseButtonElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type LoadFilesResult, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type TrackDescriptor, splitAtPlayhead };
+export { AudioResumeController, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, DawClipElement, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawKeyboardShortcutsElement, DawPauseButtonElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackDescriptor, type UndoShortcutMap, splitAtPlayhead };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as lit from 'lit';
 import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost } from 'lit';
-import { Peaks, Bits, FadeType, PeakData, ClipTrack } from '@waveform-playlist/core';
+import { Peaks, Bits, FadeType, PeakData, ClipTrack, KeyboardShortcut } from '@waveform-playlist/core';
+import WaveformData from 'waveform-data';
 import { PlaylistEngine } from '@waveform-playlist/engine';
 
 declare class DawClipElement extends LitElement {
@@ -184,6 +185,7 @@ interface TrackDescriptor {
 }
 interface ClipDescriptor {
     src: string;
+    peaksSrc: string;
     start: number;
     duration: number;
     offset: number;
@@ -213,6 +215,11 @@ declare class PeakPipeline {
     private _baseScale;
     private _bits;
     constructor(baseScale?: number, bits?: 8 | 16);
+    /**
+     * Inject externally-loaded WaveformData (e.g., from a .dat file) into the cache.
+     * Prevents worker generation for this AudioBuffer on all subsequent calls.
+     */
+    cacheWaveformData(audioBuffer: AudioBuffer, waveformData: WaveformData): void;
     /**
      * Generate PeakData for a clip from its AudioBuffer.
      * Uses cached WaveformData when available; otherwise generates via worker.
@@ -221,14 +228,26 @@ declare class PeakPipeline {
     generatePeaks(audioBuffer: AudioBuffer, samplesPerPixel: number, isMono: boolean, offsetSamples?: number, durationSamples?: number): Promise<PeakData>;
     /**
      * Re-extract peaks for all clips at a new zoom level using cached WaveformData.
-     * Only works for zoom levels coarser than (or equal to) the cached base scale.
-     * Returns a new Map of clipId → PeakData. Clips without cached data or where
-     * the target scale is finer than the cached base are skipped.
+     * Returns a new Map of clipId → PeakData. Clips without cached data are skipped.
+     * When the requested scale is finer than cached data, peaks are clamped to the
+     * cached scale and a single summary warning is logged.
      */
     reextractPeaks(clipBuffers: ReadonlyMap<string, AudioBuffer>, samplesPerPixel: number, isMono: boolean, clipOffsets?: ReadonlyMap<string, {
         offsetSamples: number;
         durationSamples: number;
     }>): Map<string, PeakData>;
+    /**
+     * Clamp requested scale to cached WaveformData scale.
+     * WaveformData.resample() can only go coarser — if the requested zoom is
+     * finer than the cached data, use the cached scale. Set warn=true to log
+     * (default); reextractPeaks passes false and logs a single summary instead.
+     */
+    private _clampScale;
+    /**
+     * Return the coarsest (largest) scale among cached WaveformData entries
+     * that correspond to the given clip buffers. Returns 0 if none are cached.
+     */
+    getMaxCachedScale(clipBuffers: ReadonlyMap<string, AudioBuffer>): number;
     terminate(): void;
     private _getWaveformData;
 }
@@ -335,13 +354,19 @@ interface ClipBounds {
 }
 /** Narrow engine contract for clip move/trim interactions. */
 interface ClipEngineContract {
-    moveClip(trackId: string, clipId: string, deltaSamples: number, skipAdapter?: boolean): void;
+    moveClip(trackId: string, clipId: string, deltaSamples: number, skipAdapter?: boolean): number;
     trimClip(trackId: string, clipId: string, boundary: 'left' | 'right', deltaSamples: number, skipAdapter?: boolean): void;
     updateTrack(trackId: string): void;
     /** Get a clip's full bounds for trim constraint computation. */
     getClipBounds(trackId: string, clipId: string): ClipBounds | null;
     /** Constrain a trim delta using the engine's collision/bounds logic. */
     constrainTrimDelta(trackId: string, clipId: string, boundary: 'left' | 'right', deltaSamples: number): number;
+    /** Begin a transaction — groups mutations into one undo step. */
+    beginTransaction(): void;
+    /** Commit the transaction — pushes one undo step for all grouped mutations. */
+    commitTransaction(): void;
+    /** Abort the transaction — restores pre-transaction state without pushing to undo. */
+    abortTransaction(): void;
 }
 /** Peak data returned by reextractClipPeaks for imperative waveform updates. */
 interface ClipPeakSlice {
@@ -510,7 +535,9 @@ interface LoadFilesResult {
 }
 
 declare class DawEditorElement extends LitElement {
-    samplesPerPixel: number;
+    get samplesPerPixel(): number;
+    set samplesPerPixel(value: number);
+    private _samplesPerPixel;
     waveHeight: number;
     timescale: boolean;
     mono: boolean;
@@ -537,12 +564,15 @@ declare class DawEditorElement extends LitElement {
     _engine: PlaylistEngine | null;
     private _enginePromise;
     _audioCache: Map<string, Promise<AudioBuffer>>;
+    private _peaksCache;
     _clipBuffers: Map<string, AudioBuffer>;
     _clipOffsets: Map<string, {
         offsetSamples: number;
         durationSamples: number;
     }>;
     _peakPipeline: PeakPipeline;
+    /** Coarsest scale from pre-computed peaks — zoom cannot go finer than this. 0 = no limit. */
+    private _minSamplesPerPixel;
     private _trackElements;
     private _childObserver;
     private _audioResume;
@@ -582,6 +612,7 @@ declare class DawEditorElement extends LitElement {
     private _readTrackDescriptor;
     private _loadTrack;
     _fetchAndDecode(src: string): Promise<AudioBuffer>;
+    private _fetchPeaks;
     _recomputeDuration(): void;
     _ensureEngine(): Promise<PlaylistEngine>;
     private _buildEngine;
@@ -593,10 +624,19 @@ declare class DawEditorElement extends LitElement {
     play(startTime?: number): Promise<void>;
     pause(): void;
     stop(): void;
+    /** Toggle between play and pause. */
+    togglePlayPause(): void;
     seekTo(time: number): void;
+    /** Undo the last structural edit. */
+    undo(): void;
+    /** Redo the last undone edit. */
+    redo(): void;
+    /** Whether undo is available. */
+    get canUndo(): boolean;
+    /** Whether redo is available. */
+    get canRedo(): boolean;
     /** Split the clip under the playhead on the selected track. */
     splitAtPlayhead(): boolean;
-    private _onKeyDown;
     recordingStream: MediaStream | null;
     get currentTime(): number;
     get isRecording(): boolean;
@@ -668,6 +708,59 @@ declare global {
     }
 }
 
+/** Key binding for remapping — derived from KeyboardShortcut to stay in sync. */
+type KeyBinding = Pick<KeyboardShortcut, 'key' | 'ctrlKey' | 'shiftKey' | 'metaKey' | 'altKey'>;
+interface PlaybackShortcutMap {
+    playPause?: KeyBinding;
+    stop?: KeyBinding;
+    rewindToStart?: KeyBinding;
+}
+interface SplittingShortcutMap {
+    splitAtPlayhead?: KeyBinding;
+}
+interface UndoShortcutMap {
+    undo?: KeyBinding;
+    redo?: KeyBinding;
+}
+/**
+ * Render-less element that enables keyboard shortcuts for a parent <daw-editor>.
+ * Place inside the editor element. Boolean attributes enable preset categories;
+ * JS properties allow remapping and custom shortcuts.
+ *
+ * ```html
+ * <daw-editor>
+ *   <daw-keyboard-shortcuts playback splitting undo></daw-keyboard-shortcuts>
+ * </daw-editor>
+ * ```
+ */
+declare class DawKeyboardShortcutsElement extends LitElement {
+    playback: boolean;
+    splitting: boolean;
+    undo: boolean;
+    playbackShortcuts: PlaybackShortcutMap | null;
+    splittingShortcuts: SplittingShortcutMap | null;
+    undoShortcuts: UndoShortcutMap | null;
+    /** Additional custom shortcuts. */
+    customShortcuts: KeyboardShortcut[];
+    private _editor;
+    private _cachedShortcuts;
+    /** All active shortcuts (read-only, cached). */
+    get shortcuts(): KeyboardShortcut[];
+    /** Invalidate cached shortcuts when Lit properties change. */
+    updated(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    createRenderRoot(): this;
+    private _buildShortcuts;
+    private _makeShortcut;
+    private _onKeyDown;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-keyboard-shortcuts': DawKeyboardShortcutsElement;
+    }
+}
+
 declare class AudioResumeController implements ReactiveController {
     private _host;
     private _target;
@@ -704,15 +797,20 @@ interface SplitEngineContract {
 interface SplitHost {
     readonly effectiveSampleRate: number;
     readonly currentTime: number;
+    readonly isPlaying: boolean;
     readonly engine: SplitEngineContract | null;
     dispatchEvent(event: Event): boolean;
+    stop(): void;
+    play(time: number): void;
 }
 /**
- * Splits the clip under the playhead on the selected track.
+ * Split the clip under the playhead on the selected track.
+ * Stops playback before split and resumes after to avoid duplicate audio
+ * from Transport rescheduling during playback.
  *
  * Returns true if the split occurred and dispatched a daw-clip-split event.
  * Returns false for any guard failure or engine no-op.
  */
 declare function splitAtPlayhead(host: SplitHost): boolean;
 
-export { AudioResumeController, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, DawClipElement, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawPauseButtonElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type LoadFilesResult, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type TrackDescriptor, splitAtPlayhead };
+export { AudioResumeController, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, DawClipElement, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawKeyboardShortcutsElement, DawPauseButtonElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackDescriptor, type UndoShortcutMap, splitAtPlayhead };