@dawcore/components 0.0.15 → 0.0.16

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, MeterEntry, SnapTo, ClipTrack, KeyboardShortcut } from '@waveform-playlist/core';
+import { MidiNoteData, FadeType, Peaks, Bits, PeakData, MeterEntry, SnapTo, ClipTrack, KeyboardShortcut } from '@waveform-playlist/core';
 import WaveformData from 'waveform-data';
 import { PlayoutAdapter, PlaylistEngine } from '@waveform-playlist/engine';
 
@@ -16,6 +16,16 @@ declare class DawClipElement extends LitElement {
     fadeIn: number;
     fadeOut: number;
     fadeType: string;
+    /** MIDI notes — JS property only, not reflected (note arrays are too large for attributes). */
+    midiNotes: MidiNoteData[] | null;
+    /** MIDI channel (0-indexed). Channel 9 = GM percussion. */
+    get midiChannel(): number | null;
+    set midiChannel(value: number | null);
+    private _midiChannel;
+    /** MIDI program (GM instrument 0-127). Used by SoundFontToneTrack. */
+    get midiProgram(): number | null;
+    set midiProgram(value: number | null);
+    private _midiProgram;
     readonly clipId: `${string}-${string}-${string}-${string}-${string}`;
     createRenderRoot(): this;
     connectedCallback(): void;
@@ -28,6 +38,111 @@ declare global {
     }
 }
 
+type TrackRenderMode = 'waveform' | 'piano-roll';
+interface TrackDescriptor {
+    name: string;
+    src: string;
+    volume: number;
+    pan: number;
+    muted: boolean;
+    soloed: boolean;
+    renderMode: TrackRenderMode;
+    clips: ClipDescriptor[];
+}
+/**
+ * Common fields shared by all clip descriptors regardless of source.
+ */
+interface BaseClipDescriptor {
+    src: string;
+    peaksSrc: string;
+    start: number;
+    duration: number;
+    offset: number;
+    gain: number;
+    name: string;
+    fadeIn: number;
+    fadeOut: number;
+    fadeType: FadeType;
+    midiNotes: MidiNoteData[] | null;
+    midiChannel: number | null;
+    midiProgram: number | null;
+}
+/**
+ * A clip descriptor sourced from a `<daw-clip>` DOM element. `clipId` is
+ * always set — `<daw-clip>.clipId` is a `crypto.randomUUID()` generated at
+ * construction. Engine `clip.id` is aligned with this id in `_loadTrack`
+ * and `_loadAndAppendClip` so DOM and engine reference the same clip.
+ */
+interface DomClipDescriptor extends BaseClipDescriptor {
+    kind: 'dom';
+    clipId: string;
+}
+/**
+ * A clip descriptor synthesized from a non-DOM source — file drops, the
+ * `<daw-track src>` shorthand fallback, or recording-clip insertion. No
+ * `clipId` because there's no DOM element to align with; the engine
+ * generates its own id at clip-creation time.
+ */
+interface DropClipDescriptor extends BaseClipDescriptor {
+    kind: 'drop';
+}
+type ClipDescriptor = DomClipDescriptor | DropClipDescriptor;
+/**
+ * Type predicate for the `'dom'` discriminator. Use to narrow a
+ * `ClipDescriptor` to `DomClipDescriptor` (which has `clipId`) without
+ * inline `c.kind === 'dom'` repetition.
+ */
+declare function isDomClip(desc: ClipDescriptor): desc is DomClipDescriptor;
+/**
+ * Public input shape for `editor.addTrack(config)`. All fields optional —
+ * defaults match the declarative `<daw-track>` defaults.
+ */
+interface TrackConfig {
+    name?: string;
+    volume?: number;
+    pan?: number;
+    muted?: boolean;
+    soloed?: boolean;
+    renderMode?: TrackRenderMode;
+    clips?: ClipConfig[];
+    /**
+     * Convenience: creates a single piano-roll `<daw-clip>` child with these
+     * notes and sets `render-mode="piano-roll"` on the track. Equivalent to
+     * passing `{ renderMode: 'piano-roll', clips: [{ midiNotes, midiChannel, midiProgram }] }`.
+     * An explicit `renderMode` takes precedence over the inferred `'piano-roll'`.
+     *
+     * Creation-only — ignored by `updateTrack`. To modify notes after the
+     * track is built, use `editor.updateClip(trackId, clipId, { midiNotes })` or
+     * mutate the `<daw-clip>` element's `midiNotes` property directly.
+     */
+    midi?: {
+        notes: MidiNoteData[];
+        channel?: number;
+        program?: number;
+    };
+}
+/**
+ * Public input shape for clips passed via `TrackConfig.clips` or
+ * `editor.addClip(trackId, config)`. `src` is optional to support MIDI clips
+ * with no audio source. Other fields default to the matching `<daw-clip>`
+ * attribute defaults.
+ */
+interface ClipConfig {
+    src?: string;
+    peaksSrc?: string;
+    start?: number;
+    duration?: number;
+    offset?: number;
+    gain?: number;
+    name?: string;
+    fadeIn?: number;
+    fadeOut?: number;
+    fadeType?: FadeType;
+    midiNotes?: MidiNoteData[];
+    midiChannel?: number;
+    midiProgram?: number;
+}
+
 declare class DawTrackElement extends LitElement {
     src: string;
     name: string;
@@ -35,6 +150,7 @@ declare class DawTrackElement extends LitElement {
     pan: number;
     muted: boolean;
     soloed: boolean;
+    renderMode: TrackRenderMode;
     readonly trackId: `${string}-${string}-${string}-${string}-${string}`;
     createRenderRoot(): this;
     connectedCallback(): void;
@@ -112,6 +228,42 @@ declare global {
     }
 }
 
+declare class DawPianoRollElement extends LitElement {
+    midiNotes: MidiNoteData[];
+    length: number;
+    waveHeight: number;
+    get samplesPerPixel(): number;
+    set samplesPerPixel(value: number);
+    private _samplesPerPixel;
+    get sampleRate(): number;
+    set sampleRate(value: number);
+    private _sampleRate;
+    clipOffsetSeconds: number;
+    /** Visible viewport start in pixels (relative to timeline origin). */
+    visibleStart: number;
+    /** Visible viewport end in pixels (relative to timeline origin). */
+    visibleEnd: number;
+    /** This element's left offset on the timeline (for viewport intersection). */
+    originX: number;
+    selected: boolean;
+    static styles: lit.CSSResult;
+    private _rafHandle;
+    private _scheduleDraw;
+    willUpdate(_changed: PropertyValues): void;
+    updated(changedProperties: Map<string, unknown>): void;
+    private _getPitchRange;
+    private _getNoteColor;
+    private _draw;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-piano-roll': DawPianoRollElement;
+    }
+}
+
 declare class DawPlayheadElement extends LitElement {
     private _animation;
     private _line;
@@ -173,6 +325,8 @@ declare class DawPauseButtonElement extends DawTransportButton {
     private _targetRef;
     private _onRecStart;
     private _onRecEnd;
+    private _onRecPause;
+    private _onRecResume;
     static styles: lit.CSSResultGroup[];
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -195,87 +349,6 @@ declare global {
     }
 }
 
-interface TrackDescriptor {
-    name: string;
-    src: string;
-    volume: number;
-    pan: number;
-    muted: boolean;
-    soloed: boolean;
-    clips: ClipDescriptor[];
-}
-/**
- * Common fields shared by all clip descriptors regardless of source.
- */
-interface BaseClipDescriptor {
-    src: string;
-    peaksSrc: string;
-    start: number;
-    duration: number;
-    offset: number;
-    gain: number;
-    name: string;
-    fadeIn: number;
-    fadeOut: number;
-    fadeType: FadeType;
-}
-/**
- * A clip descriptor sourced from a `<daw-clip>` DOM element. `clipId` is
- * always set — `<daw-clip>.clipId` is a `crypto.randomUUID()` generated at
- * construction. Engine `clip.id` is aligned with this id in `_loadTrack`
- * and `_loadAndAppendClip` so DOM and engine reference the same clip.
- */
-interface DomClipDescriptor extends BaseClipDescriptor {
-    kind: 'dom';
-    clipId: string;
-}
-/**
- * A clip descriptor synthesized from a non-DOM source — file drops, the
- * `<daw-track src>` shorthand fallback, or recording-clip insertion. No
- * `clipId` because there's no DOM element to align with; the engine
- * generates its own id at clip-creation time.
- */
-interface DropClipDescriptor extends BaseClipDescriptor {
-    kind: 'drop';
-}
-type ClipDescriptor = DomClipDescriptor | DropClipDescriptor;
-/**
- * Type predicate for the `'dom'` discriminator. Use to narrow a
- * `ClipDescriptor` to `DomClipDescriptor` (which has `clipId`) without
- * inline `c.kind === 'dom'` repetition.
- */
-declare function isDomClip(desc: ClipDescriptor): desc is DomClipDescriptor;
-/**
- * Public input shape for `editor.addTrack(config)`. All fields optional —
- * defaults match the declarative `<daw-track>` defaults.
- */
-interface TrackConfig {
-    name?: string;
-    volume?: number;
-    pan?: number;
-    muted?: boolean;
-    soloed?: boolean;
-    clips?: ClipConfig[];
-}
-/**
- * Public input shape for clips passed via `TrackConfig.clips` or
- * `editor.addClip(trackId, config)`. `src` is required — every clip needs
- * an audio source to load. Other fields default to the matching
- * `<daw-clip>` attribute defaults.
- */
-interface ClipConfig {
-    src: string;
-    peaksSrc?: string;
-    start?: number;
-    duration?: number;
-    offset?: number;
-    gain?: number;
-    name?: string;
-    fadeIn?: number;
-    fadeOut?: number;
-    fadeType?: FadeType;
-}
-
 /**
  * Peak generation pipeline: AudioBuffer → web worker → WaveformData → PeakData.
  *
@@ -434,6 +507,12 @@ interface RecordingSession {
     /** Stored so it can be removed on stop/cleanup — not just when stream ends. */
     readonly _onTrackEnded: (() => void) | null;
     readonly _audioTrack: MediaStreamTrack | null;
+    /** Set during stopRecording, cleared by the done message from the worklet. */
+    stopAckResolve: (() => void) | null;
+    /** True from the start of stopRecording until the session is deleted.
+     * Guards pauseRecording / resumeRecording so a mid-drain pause toggle
+     * can't dispatch events for a session that's already terminating. */
+    stopping: boolean;
 }
 /** Readonly view of a recording session for external consumers. */
 type ReadonlyRecordingSession = Readonly<Omit<RecordingSession, 'chunks' | 'peaks' | '_onTrackEnded' | '_audioTrack' | 'latencySamples'>> & {
@@ -475,16 +554,21 @@ declare class RecordingController implements ReactiveController {
     private _host;
     private _sessions;
     private _workletLoadedCtx;
+    /** Tracks worklet pause state explicitly so external consumers (editor,
+     * pause button, spacebar) can share one source of truth. */
+    private _isPaused;
     constructor(host: RecordingHost & HTMLElement);
     hostConnected(): void;
     hostDisconnected(): void;
     get isRecording(): boolean;
+    get isPaused(): 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;
+    stopRecording(trackId?: string): Promise<void>;
     private _onWorkletMessage;
+    private _processWorkletSamples;
     private _createClipFromRecording;
     private _removeTrackEndedListener;
     private _cleanupSession;
@@ -538,6 +622,11 @@ interface ClipPointerHost {
     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;
+    /**
+     * Returns true if the clip is a MIDI clip (has midiNotes).
+     * Trim handles are inert for MIDI clips — note slicing is not yet implemented.
+     */
+    isMidiClip(trackId: string, clipId: string): boolean;
 }
 /**
  * Handles pointer interactions for clip move and trim drag operations.
@@ -646,6 +735,12 @@ interface DawRecordingErrorDetail {
     trackId: string;
     error: unknown;
 }
+interface DawRecordingPauseDetail {
+    trackId: string;
+}
+interface DawRecordingResumeDetail {
+    trackId: string;
+}
 interface DawClipConnectedDetail {
     clipId: string;
     element: DawClipElement;
@@ -702,6 +797,8 @@ interface DawEventMap {
     'daw-recording-start': CustomEvent<DawRecordingStartDetail>;
     'daw-recording-complete': CustomEvent<DawRecordingCompleteDetail>;
     'daw-recording-error': CustomEvent<DawRecordingErrorDetail>;
+    'daw-recording-pause': CustomEvent<DawRecordingPauseDetail>;
+    'daw-recording-resume': CustomEvent<DawRecordingResumeDetail>;
     'daw-clip-connected': CustomEvent<DawClipConnectedDetail>;
     'daw-clip-update': CustomEvent<DawClipUpdateDetail>;
     'daw-clip-ready': CustomEvent<DawClipIdDetail>;
@@ -801,6 +898,12 @@ declare class DawEditorElement extends LitElement {
     get renderSamplesPerPixel(): number;
     /** Re-extract peaks for a clip at new offset/duration from cached WaveformData. */
     reextractClipPeaks(clipId: string, offsetSamples: number, durationSamples: number): PeakData | null;
+    /**
+     * Returns true if the clip is a MIDI clip (has midiNotes).
+     * Used by ClipPointerHandler to make trim handles inert for MIDI clips.
+     * Returns false for unknown track/clip IDs (defensive).
+     */
+    isMidiClip(trackId: string, clipId: string): boolean;
     private _pointer;
     private _viewport;
     static styles: lit.CSSResult[];
@@ -859,6 +962,27 @@ declare class DawEditorElement extends LitElement {
      * uses sync `extractPeaks` and inserts a preview track BEFORE audio decode.
      */
     private _finalizeAudioClip;
+    /**
+     * Filter MIDI notes to only those with finite, in-range fields. Logs a
+     * warning for each dropped note. Used by _buildMidiClip and the
+     * _applyClipUpdate MIDI branch to prevent NaN propagation through the
+     * timeline.
+     */
+    private _validMidiNotes;
+    /**
+     * A clip descriptor is treated as MIDI when it has no audio src.
+     * Includes placeholder MIDI clips (no notes, no duration yet — registered
+     * with a 1s default span; notes upgrade via _applyClipUpdate). Warns when
+     * a clip ambiguously has both src and midiNotes — the audio path runs
+     * and notes would be silently ignored.
+     */
+    private _isMidiDescriptor;
+    /**
+     * Build an engine clip from a MIDI clip descriptor. Always returns a clip
+     * — empty notes / no declared duration get a 1-second placeholder span so
+     * the clip is reachable via `engine.updateTrack` once notes arrive.
+     */
+    private _buildMidiClip;
     /** Remove a single clip from all per-clip caches. Used by error rollbacks. */
     private _purgeClipCaches;
     /**
@@ -963,9 +1087,20 @@ declare class DawEditorElement extends LitElement {
     recordingStream: MediaStream | null;
     get currentTime(): number;
     get isRecording(): boolean;
+    get isRecordingPaused(): boolean;
     pauseRecording(): void;
     resumeRecording(): void;
-    stopRecording(): void;
+    /**
+     * Audacity-style pause toggle for active recordings: pauses both the
+     * worklet capture and (if running) the playback Transport. On resume,
+     * Transport restarts only if it was running before — non-overdub
+     * recordings stay silent on resume.
+     */
+    togglePauseRecording(): void;
+    /** Set in togglePauseRecording when Transport is paused alongside the
+     * worklet, so resume can restart it. Cleared on resume and on stop. */
+    private _wasPlayingDuringRecording;
+    stopRecording(): Promise<void>;
     _addRecordedClip(trackId: string, buf: AudioBuffer, startSample: number, durSamples: number, offsetSamples?: number): void;
     addWorkletModule(url: string): Promise<void>;
     createAudioWorkletNode(name: string, options?: AudioWorkletNodeOptions): AudioWorkletNode;
@@ -1149,4 +1284,4 @@ interface SplitHost {
  */
 declare function splitAtPlayhead(host: SplitHost): boolean;
 
-export { AudioResumeController, type ClipConfig, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, type DawClipConnectedDetail, DawClipElement, type DawClipErrorDetail, type DawClipIdDetail, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, type DawClipUpdateDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawGridElement, 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 DomClipDescriptor, type DropClipDescriptor, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackConfig, type TrackDescriptor, type UndoShortcutMap, type WaveformSegment, isDomClip, splitAtPlayhead };
+export { AudioResumeController, type ClipConfig, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, type DawClipConnectedDetail, DawClipElement, type DawClipErrorDetail, type DawClipIdDetail, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, type DawClipUpdateDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawGridElement, DawKeyboardShortcutsElement, DawPauseButtonElement, DawPianoRollElement, 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 DomClipDescriptor, type DropClipDescriptor, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackConfig, type TrackDescriptor, type TrackRenderMode, type UndoShortcutMap, type WaveformSegment, isDomClip, splitAtPlayhead };