@dawcore/components 0.0.1 → 0.0.3

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 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 { PlaylistEngine } from '@waveform-playlist/engine';
 
 declare class DawClipElement extends LitElement {
@@ -130,6 +130,12 @@ declare class DawTransportButton extends LitElement {
 }
 
 declare class DawPlayButtonElement extends DawTransportButton {
+    private _isRecording;
+    private _targetRef;
+    private _onRecStart;
+    private _onRecEnd;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     render(): lit.TemplateResult<1>;
     private _onClick;
 }
@@ -140,6 +146,14 @@ declare global {
 }
 
 declare class DawPauseButtonElement extends DawTransportButton {
+    private _isPaused;
+    private _isRecording;
+    private _targetRef;
+    private _onRecStart;
+    private _onRecEnd;
+    static styles: lit.CSSResultGroup[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     render(): lit.TemplateResult<1>;
     private _onClick;
 }
@@ -196,19 +210,25 @@ declare class PeakPipeline {
     private _worker;
     private _cache;
     private _inflight;
+    private _baseScale;
+    private _bits;
+    constructor(baseScale?: number, bits?: 8 | 16);
     /**
      * Generate PeakData for a clip from its AudioBuffer.
      * Uses cached WaveformData when available; otherwise generates via worker.
-     * The worker generates at `scale` (= samplesPerPixel) for exact rendering.
+     * Worker generates at baseScale (default 128); extractPeaks resamples to the requested zoom.
      */
-    generatePeaks(audioBuffer: AudioBuffer, samplesPerPixel: number, isMono: boolean): Promise<PeakData>;
+    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.
      */
-    reextractPeaks(clipBuffers: ReadonlyMap<string, AudioBuffer>, samplesPerPixel: number, isMono: boolean): Map<string, PeakData>;
+    reextractPeaks(clipBuffers: ReadonlyMap<string, AudioBuffer>, samplesPerPixel: number, isMono: boolean, clipOffsets?: ReadonlyMap<string, {
+        offsetSamples: number;
+        durationSamples: number;
+    }>): Map<string, PeakData>;
     terminate(): void;
     private _getWaveformData;
 }
@@ -240,6 +260,8 @@ interface RecordingOptions {
     trackId?: string;
     bits?: 8 | 16;
     startSample?: number;
+    /** Start playback during recording so user hears existing tracks. */
+    overdub?: boolean;
 }
 interface RecordingSession {
     readonly trackId: string;
@@ -259,12 +281,16 @@ interface RecordingSession {
     readonly channelCount: number;
     readonly bits: Bits;
     isFirstMessage: boolean;
+    /** Latency samples to skip in live preview (outputLatency + lookAhead). */
+    readonly latencySamples: number;
+    readonly wasOverdub: boolean;
     /** Stored so it can be removed on stop/cleanup — not just when stream ends. */
     readonly _onTrackEnded: (() => void) | null;
     readonly _audioTrack: MediaStreamTrack | null;
 }
 /** Readonly view of a recording session for external consumers. */
-type ReadonlyRecordingSession = Readonly<Omit<RecordingSession, 'chunks' | 'peaks' | '_onTrackEnded' | '_audioTrack'>> & {
+type ReadonlyRecordingSession = Readonly<Omit<RecordingSession, 'chunks' | 'peaks' | '_onTrackEnded' | '_audioTrack' | 'latencySamples'>> & {
+    readonly latencySamples: number;
     readonly chunks: ReadonlyArray<ReadonlyArray<Float32Array>>;
     readonly peaks: ReadonlyArray<Int8Array | Int16Array>;
 };
@@ -276,7 +302,9 @@ interface RecordingHost extends ReactiveControllerHost {
     readonly _currentTime: number;
     readonly shadowRoot: ShadowRoot | null;
     resolveAudioContextSampleRate(rate: number): void;
-    _addRecordedClip?(trackId: string, buf: AudioBuffer, startSample: number, durSamples: number): void;
+    _addRecordedClip?(trackId: string, buf: AudioBuffer, startSample: number, durSamples: number, offsetSamples?: number): void;
+    play?(startTime?: number): Promise<void>;
+    stop?(): void;
     dispatchEvent(event: Event): boolean;
 }
 declare class RecordingController implements ReactiveController {
@@ -289,6 +317,8 @@ declare class RecordingController implements ReactiveController {
     get isRecording(): boolean;
     getSession(trackId: string): ReadonlyRecordingSession | undefined;
     startRecording(stream: MediaStream, options?: RecordingOptions): Promise<void>;
+    pauseRecording(trackId?: string): void;
+    resumeRecording(trackId?: string): void;
     stopRecording(trackId?: string): void;
     private _onWorkletMessage;
     private _createClipFromRecording;
@@ -296,6 +326,91 @@ declare class RecordingController implements ReactiveController {
     private _cleanupSession;
 }
 
+/** Snapshot of a clip's bounds for trim constraint computation. */
+interface ClipBounds {
+    readonly offsetSamples: number;
+    readonly durationSamples: number;
+    readonly startSample: number;
+    readonly sourceDurationSamples: number;
+}
+/** Narrow engine contract for clip move/trim interactions. */
+interface ClipEngineContract {
+    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 {
+    data: ArrayLike<number>[];
+    length: number;
+}
+/** Host interface required by ClipPointerHandler. */
+interface ClipPointerHost {
+    readonly samplesPerPixel: number;
+    readonly effectiveSampleRate: number;
+    readonly interactiveClips: boolean;
+    readonly engine: ClipEngineContract | null;
+    readonly shadowRoot: ShadowRoot | null;
+    dispatchEvent(event: Event): boolean;
+    /** Re-extract peaks for a clip at new offset/duration from cached WaveformData. */
+    reextractClipPeaks(clipId: string, offsetSamples: number, durationSamples: number): ClipPeakSlice | null;
+}
+/**
+ * Handles pointer interactions for clip move and trim drag operations.
+ * Converts pixel deltas to sample deltas and delegates to the engine.
+ *
+ * Move: sends incremental deltas per-frame with skipAdapter=true (engine shifts
+ *   startSample additively without touching audio adapter). Adapter synced once
+ *   via updateTrack() at drag end.
+ * Trim: updates clip container CSS imperatively during drag for visual feedback,
+ *   then applies cumulative delta to engine once at drag end.
+ */
+declare class ClipPointerHandler {
+    private _host;
+    private _mode;
+    private _clipId;
+    private _trackId;
+    private _startPx;
+    private _isDragging;
+    private _lastDeltaPx;
+    private _cumulativeDeltaSamples;
+    private _clipContainer;
+    private _boundaryEl;
+    private _originalLeft;
+    private _originalWidth;
+    private _originalOffsetSamples;
+    private _originalDurationSamples;
+    constructor(host: ClipPointerHost);
+    /** Returns true if a drag interaction is currently in progress. */
+    get isActive(): boolean;
+    /**
+     * Attempts to handle a pointerdown event on the given target element.
+     * Returns true if the target is a recognized clip interaction element.
+     */
+    tryHandle(target: Element, e: PointerEvent): boolean;
+    private _beginDrag;
+    /** Processes pointermove events during an active drag. */
+    onPointerMove(e: PointerEvent): void;
+    /** Processes pointerup events to finalize and dispatch result events. */
+    onPointerUp(_e: PointerEvent): void;
+    /** Re-extract peaks from cache and set on waveform elements during trim drag.
+     *  Returns true if peaks were successfully updated. */
+    private _updateWaveformPeaks;
+    /** Restore clip container CSS to original values after trim visual preview. */
+    private _restoreTrimVisual;
+    private _reset;
+}
+
 interface DawSelectionDetail {
     start: number;
     end: number;
@@ -342,11 +457,33 @@ interface DawRecordingCompleteDetail {
     audioBuffer: AudioBuffer;
     startSample: number;
     durationSamples: number;
+    offsetSamples: number;
 }
 interface DawRecordingErrorDetail {
     trackId: string;
     error: unknown;
 }
+interface DawClipMoveDetail {
+    readonly trackId: string;
+    readonly clipId: string;
+    /** Requested cumulative delta. May exceed actual applied movement due to
+     *  collision constraints. Query engine state for actual clip positions. */
+    readonly deltaSamples: number;
+}
+interface DawClipTrimDetail {
+    readonly trackId: string;
+    readonly clipId: string;
+    readonly boundary: 'left' | 'right';
+    /** Constrained cumulative delta applied by the engine. Already clamped
+     *  by collision and boundary constraints during drag. */
+    readonly deltaSamples: number;
+}
+interface DawClipSplitDetail {
+    readonly trackId: string;
+    readonly originalClipId: string;
+    readonly leftClipId: string;
+    readonly rightClipId: string;
+}
 interface DawEventMap {
     'daw-selection': CustomEvent<DawSelectionDetail>;
     'daw-seek': CustomEvent<DawSeekDetail>;
@@ -365,6 +502,9 @@ interface DawEventMap {
     'daw-recording-start': CustomEvent<DawRecordingStartDetail>;
     'daw-recording-complete': CustomEvent<DawRecordingCompleteDetail>;
     'daw-recording-error': CustomEvent<DawRecordingErrorDetail>;
+    'daw-clip-move': CustomEvent<DawClipMoveDetail>;
+    'daw-clip-trim': CustomEvent<DawClipTrimDetail>;
+    'daw-clip-split': CustomEvent<DawClipSplitDetail>;
 }
 type DawEvent<K extends keyof DawEventMap> = DawEventMap[K];
 interface LoadFilesResult {
@@ -383,6 +523,9 @@ declare class DawEditorElement extends LitElement {
     barWidth: number;
     barGap: number;
     fileDrop: boolean;
+    clipHeaders: boolean;
+    clipHeaderHeight: number;
+    interactiveClips: boolean;
     /** Initial sample rate hint. Overridden by decoded audio buffer's actual rate. */
     sampleRate: number;
     /** Resolved sample rate — falls back to sampleRate property until first audio decode. */
@@ -399,15 +542,26 @@ declare class DawEditorElement extends LitElement {
     _currentTime: number;
     _engine: PlaylistEngine | null;
     private _enginePromise;
-    private _audioInitialized;
     _audioCache: Map<string, Promise<AudioBuffer>>;
     _clipBuffers: Map<string, AudioBuffer>;
+    _clipOffsets: Map<string, {
+        offsetSamples: number;
+        durationSamples: number;
+    }>;
     _peakPipeline: PeakPipeline;
     private _trackElements;
     private _childObserver;
     private _audioResume;
     eagerResume?: string;
     private _recordingController;
+    private _clipPointer;
+    get _clipHandler(): ClipPointerHandler | null;
+    get engine(): PlaylistEngine | null;
+    /** Re-extract peaks for a clip at new offset/duration from cached WaveformData. */
+    reextractClipPeaks(clipId: string, offsetSamples: number, durationSamples: number): {
+        data: Peaks[];
+        length: number;
+    } | null;
     private _pointer;
     private _viewport;
     static styles: lit.CSSResult[];
@@ -442,14 +596,29 @@ declare class DawEditorElement extends LitElement {
     private _onDragLeave;
     private _onDrop;
     loadFiles(files: FileList | File[]): Promise<LoadFilesResult>;
-    play(): Promise<void>;
+    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;
     recordingStream: MediaStream | null;
+    get currentTime(): number;
     get isRecording(): boolean;
+    pauseRecording(): void;
+    resumeRecording(): void;
     stopRecording(): void;
-    _addRecordedClip(trackId: string, buf: AudioBuffer, startSample: number, durSamples: number): void;
+    _addRecordedClip(trackId: string, buf: AudioBuffer, startSample: number, durSamples: number, offsetSamples?: number): void;
     startRecording(stream?: MediaStream, options?: RecordingOptions): Promise<void>;
     private _renderRecordingPreview;
     _startPlayhead(): void;
@@ -514,6 +683,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;
@@ -538,4 +760,32 @@ interface PointerEngineContract {
     selectTrack(trackId: string | null): void;
 }
 
-export { AudioResumeController, type ClipDescriptor, DawClipElement, 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 TrackDescriptor };
+/** Narrow engine contract for split operations. */
+interface SplitEngineContract {
+    getState(): {
+        selectedTrackId: string | null;
+        tracks: ClipTrack[];
+    };
+    splitClip(trackId: string, clipId: string, atSample: number): void;
+}
+/** Host interface for splitAtPlayhead. */
+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;
+}
+/**
+ * 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, 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 };