@dawcore/components 0.0.9 → 0.0.11

package/README.md

@@ -31,7 +31,7 @@ npm install @waveform-playlist/core @waveform-playlist/engine @dawcore/transport
 
 Optional (for recording):
 ```bash
-npm install @waveform-playlist/recording @waveform-playlist/worklets
+npm install @waveform-playlist/worklets
 ```
 
 ## Quick Start
@@ -97,30 +97,28 @@ Access the native transport for tempo, metronome, count-in, meter, and effects:
 ```javascript
 const editor = document.getElementById('editor');
 
-// Transport is available after first track loads
-editor.addEventListener('daw-play', () => {
-  const transport = editor.engine?.adapter?.transport;
-  if (!transport) return;
+// Build engine eagerly so transport is available immediately
+await editor._ensureEngine();
+const transport = editor.transport;
 
-  // Tempo & meter
-  transport.setTempo(140);
-  transport.setMeter(3, 4);
+// Tempo & meter
+transport.setTempo(140);
+transport.setMeter(3, 4);
 
-  // Metronome (default click sounds built in)
-  transport.setMetronomeEnabled(true);
+// Metronome (default click sounds built in)
+transport.setMetronomeEnabled(true);
 
-  // Count-in
-  transport.setCountIn(true);
-  transport.setCountInBars(1);
-  transport.setCountInMode('always');
+// Count-in
+transport.setCountIn(true);
+transport.setCountInBars(1);
+transport.setCountInMode('always');
 
-  transport.on('countIn', ({ beat, totalBeats }) => {
-    console.log(beat + '/' + totalBeats);
-  });
-
-  // Effects hook — insert any AudioNode chain
-  transport.connectTrackOutput('track-id', reverbNode);
+transport.on('countIn', ({ beat, totalBeats }) => {
+  console.log(beat + '/' + totalBeats);
 });
+
+// Effects hook — insert any AudioNode chain
+transport.connectTrackOutput('track-id', reverbNode);
 ```
 
 ## Programmatic File Loading

package/dist/index.d.mts

@@ -1,8 +1,9 @@
 import * as lit from 'lit';
 import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost } from 'lit';
-import { Peaks, Bits, FadeType, PeakData, ClipTrack, KeyboardShortcut } from '@waveform-playlist/core';
+import { Peaks, Bits, FadeType, PeakData, MeterEntry, SnapTo, ClipTrack, KeyboardShortcut } from '@waveform-playlist/core';
 import WaveformData from 'waveform-data';
 import { PlaylistEngine } from '@waveform-playlist/engine';
+import { Transport } from '@dawcore/transport';
 
 declare class DawClipElement extends LitElement {
     src: string;
@@ -44,6 +45,17 @@ declare global {
     }
 }
 
+/** A segment mapping a peak-index range to a pixel range within the waveform. */
+interface WaveformSegment {
+    /** Start position in the peaks array (fractional index). */
+    peakStart: number;
+    /** End position in the peaks array (fractional index). */
+    peakEnd: number;
+    /** Start pixel position within the waveform. */
+    pixelStart: number;
+    /** End pixel position within the waveform. */
+    pixelEnd: number;
+}
 declare class DawWaveformElement extends LitElement {
     private _peaks;
     private _dirtyPixels;
@@ -70,6 +82,8 @@ declare class DawWaveformElement extends LitElement {
     visibleEnd: number;
     /** This element's left offset on the timeline (for viewport intersection). */
     originX: number;
+    /** When set, draws per-segment with independent samples-per-pixel ratios. */
+    segments?: WaveformSegment[];
     static styles: lit.CSSResult;
     private _getVisibleChunkIndices;
     /**
@@ -82,6 +96,7 @@ declare class DawWaveformElement extends LitElement {
     private _scheduleDraw;
     private _drawDirty;
     private _drawChunk;
+    private _drawSegments;
     connectedCallback(): void;
     disconnectedCallback(): void;
     render(): lit.TemplateResult<1>;
@@ -103,6 +118,10 @@ declare class DawPlayheadElement extends LitElement {
     firstUpdated(): void;
     startAnimation(getTime: () => number, sampleRate: number, samplesPerPixel: number): void;
     stopAnimation(time: number, sampleRate: number, samplesPerPixel: number): void;
+    startBeatsAnimation(getTime: () => number, bpm: number, ppqn: number, ticksPerPixel: number): void;
+    stopBeatsAnimation(time: number, bpm: number, ppqn: number, ticksPerPixel: number): void;
+    startBeatsAnimationWithMap(getTime: () => number, secondsToTicks: (s: number) => number, ticksPerPixel: number): void;
+    stopBeatsAnimationWithMap(time: number, secondsToTicks: (s: number) => number, ticksPerPixel: number): void;
 }
 declare global {
     interface HTMLElementTagNameMap {
@@ -243,6 +262,15 @@ declare class PeakPipeline {
      * (default); reextractPeaks passes false and logs a single summary instead.
      */
     private _clampScale;
+    /**
+     * Extract peaks at the base scale from cached WaveformData.
+     * Returns null if no cached data exists for this buffer.
+     * Used by variable-tempo segments which handle stretching themselves.
+     */
+    getBaseScalePeaks(audioBuffer: AudioBuffer, isMono: boolean, offsetSamples?: number, durationSamples?: number): {
+        peaks: PeakData;
+        scale: number;
+    } | null;
     /**
      * Return the coarsest (largest) scale among cached WaveformData entries
      * that correspond to the given clip buffers. Returns 0 if none are cached.
@@ -275,6 +303,43 @@ declare global {
     }
 }
 
+/**
+ * `<daw-grid>` renders a musical grid overlay behind waveforms using the
+ * Audacity three-tier model:
+ *
+ *   - **Zebra stripes**: Alternating bar backgrounds at 2% white opacity.
+ *   - **Major lines** (bars): 10% white opacity, full height.
+ *   - **Minor lines** (beats): 6% white opacity, full height.
+ *   - **MinorMinor** (subdivisions): Ruler ticks only — no grid lines.
+ *
+ * Uses chunked 1000px canvases with virtual scrolling (same as daw-waveform).
+ *
+ * CSS custom properties:
+ *   --daw-grid-bar-highlight  Alternating bar fill  (default: rgba(255,255,255,0.02))
+ *   --daw-grid-major-line     Bar line color        (default: rgba(255,255,255,0.1))
+ *   --daw-grid-minor-line     Beat line color       (default: rgba(255,255,255,0.06))
+ */
+declare class DawGridElement extends LitElement {
+    ticksPerPixel: number;
+    meterEntries: MeterEntry[];
+    ppqn: number;
+    visibleStart: number;
+    visibleEnd: number;
+    length: number;
+    height: number;
+    private _tickData;
+    static styles: lit.CSSResult;
+    willUpdate(): void;
+    render(): lit.TemplateResult<1>;
+    updated(): void;
+    private _drawGrid;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-grid': DawGridElement;
+    }
+}
+
 interface RecordingOptions {
     trackId?: string;
     bits?: 8 | 16;
@@ -379,10 +444,20 @@ interface ClipPeakSlice {
 /** Host interface required by ClipPointerHandler. */
 interface ClipPointerHost {
     readonly samplesPerPixel: number;
+    /** In beats mode, the tick-derived SPP used for rendering. */
+    readonly renderSamplesPerPixel: number;
     readonly effectiveSampleRate: number;
     readonly interactiveClips: boolean;
     readonly engine: ClipEngineContract | null;
     readonly shadowRoot: ShadowRoot | null;
+    readonly scaleMode: 'temporal' | 'beats';
+    readonly ticksPerPixel: number;
+    readonly bpm: number;
+    readonly ppqn: number;
+    readonly _meterEntries: MeterEntry[];
+    readonly snapTo: SnapTo;
+    readonly _secondsToTicks: (seconds: number) => number;
+    readonly _ticksToSeconds: (ticks: number) => number;
     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;
@@ -404,7 +479,6 @@ declare class ClipPointerHandler {
     private _trackId;
     private _startPx;
     private _isDragging;
-    private _lastDeltaPx;
     private _cumulativeDeltaSamples;
     private _clipContainer;
     private _boundaryEl;
@@ -412,7 +486,17 @@ declare class ClipPointerHandler {
     private _originalWidth;
     private _originalOffsetSamples;
     private _originalDurationSamples;
+    private _originalStartSample;
     constructor(host: ClipPointerHost);
+    /**
+     * Convert a pixel delta to samples, snapping in tick space when in beats mode.
+     *
+     * The anchor is the absolute sample position being moved (e.g., clip start
+     * for move/left-trim, clip end for right-trim). Snapping the absolute
+     * position — not just the delta — ensures clips land exactly on grid lines
+     * even if they started off-grid.
+     */
+    private _snapDeltaToSamples;
     /** Returns true if a drag interaction is currently in progress. */
     get isActive(): boolean;
     /**
@@ -550,6 +634,25 @@ declare class DawEditorElement extends LitElement {
     clipHeaders: boolean;
     clipHeaderHeight: number;
     interactiveClips: boolean;
+    scaleMode: 'temporal' | 'beats';
+    get ticksPerPixel(): number;
+    set ticksPerPixel(value: number);
+    private _ticksPerPixel;
+    get bpm(): number;
+    set bpm(value: number);
+    private _bpm;
+    timeSignature: [number, number];
+    meterEntries?: MeterEntry[];
+    /** MeterEntries for grid/ruler: explicit meterEntries if set, otherwise derived from timeSignature. */
+    get _meterEntries(): MeterEntry[];
+    get ppqn(): number;
+    set ppqn(value: number);
+    private _ppqn;
+    snapTo: SnapTo;
+    /** Optional tempo-aware conversion: seconds → PPQN ticks. When provided, enables variable tempo. */
+    secondsToTicks?: (seconds: number) => number;
+    /** Optional tempo-aware conversion: PPQN ticks → seconds. Required alongside secondsToTicks. */
+    ticksToSeconds?: (ticks: number) => number;
     /** Desired sample rate. Creates a cross-browser AudioContext at this rate.
      *  Pre-computed .dat peaks render instantly when they match. */
     sampleRate: number;
@@ -572,6 +675,9 @@ declare class DawEditorElement extends LitElement {
     set audioContext(ctx: AudioContext | null);
     get audioContext(): AudioContext;
     _engine: PlaylistEngine | null;
+    private _adapter;
+    private _warnedMissingTicksToSeconds;
+    private _warnedMissingSecondsToTicks;
     private _enginePromise;
     _audioCache: Map<string, Promise<AudioBuffer>>;
     private _peaksCache;
@@ -591,6 +697,9 @@ declare class DawEditorElement extends LitElement {
     private _clipPointer;
     get _clipHandler(): ClipPointerHandler | null;
     get engine(): PlaylistEngine | null;
+    /** The adapter's Transport — use for tempo, metronome, and effects. */
+    get transport(): Transport | null;
+    get renderSamplesPerPixel(): number;
     /** Re-extract peaks for a clip at new offset/duration from cached WaveformData. */
     reextractClipPeaks(clipId: string, offsetSamples: number, durationSamples: number): {
         data: Peaks[];
@@ -601,7 +710,18 @@ declare class DawEditorElement extends LitElement {
     static styles: lit.CSSResult[];
     get effectiveSampleRate(): number;
     resolveAudioContextSampleRate(rate: number): void;
+    /**
+     * In beats mode, derive samplesPerPixel from ticksPerPixel so that
+     * clip positions, waveforms, and the tick-space grid all align.
+     */
+    private get _renderSpp();
+    /** Convert seconds to ticks — uses callback if provided, otherwise single-BPM fallback. */
+    _secondsToTicks(seconds: number): number;
+    /** Convert ticks to seconds — uses callback if provided, otherwise single-BPM fallback. */
+    _ticksToSeconds(ticks: number): number;
     private get _totalWidth();
+    /** Grid height when no tracks exist — matches scroll area's rendered height. */
+    private get _emptyGridHeight();
     _setSelectedTrackId(trackId: string | null): void;
     get tracks(): TrackDescriptor[];
     get selectedTrackId(): string | null;
@@ -673,7 +793,13 @@ declare class DawRulerElement extends LitElement {
     sampleRate: number;
     duration: number;
     rulerHeight: number;
+    scaleMode: 'temporal' | 'beats';
+    ticksPerPixel: number;
+    meterEntries: MeterEntry[];
+    ppqn: number;
+    totalWidth: number;
     private _tickData;
+    private _musicalTickData;
     static styles: lit.CSSResult;
     willUpdate(): void;
     render(): lit.TemplateResult<1>;
@@ -827,4 +953,4 @@ interface SplitHost {
  */
 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 };
+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, 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 KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackDescriptor, type UndoShortcutMap, type WaveformSegment, splitAtPlayhead };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import * as lit from 'lit';
 import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost } from 'lit';
-import { Peaks, Bits, FadeType, PeakData, ClipTrack, KeyboardShortcut } from '@waveform-playlist/core';
+import { Peaks, Bits, FadeType, PeakData, MeterEntry, SnapTo, ClipTrack, KeyboardShortcut } from '@waveform-playlist/core';
 import WaveformData from 'waveform-data';
 import { PlaylistEngine } from '@waveform-playlist/engine';
+import { Transport } from '@dawcore/transport';
 
 declare class DawClipElement extends LitElement {
     src: string;
@@ -44,6 +45,17 @@ declare global {
     }
 }
 
+/** A segment mapping a peak-index range to a pixel range within the waveform. */
+interface WaveformSegment {
+    /** Start position in the peaks array (fractional index). */
+    peakStart: number;
+    /** End position in the peaks array (fractional index). */
+    peakEnd: number;
+    /** Start pixel position within the waveform. */
+    pixelStart: number;
+    /** End pixel position within the waveform. */
+    pixelEnd: number;
+}
 declare class DawWaveformElement extends LitElement {
     private _peaks;
     private _dirtyPixels;
@@ -70,6 +82,8 @@ declare class DawWaveformElement extends LitElement {
     visibleEnd: number;
     /** This element's left offset on the timeline (for viewport intersection). */
     originX: number;
+    /** When set, draws per-segment with independent samples-per-pixel ratios. */
+    segments?: WaveformSegment[];
     static styles: lit.CSSResult;
     private _getVisibleChunkIndices;
     /**
@@ -82,6 +96,7 @@ declare class DawWaveformElement extends LitElement {
     private _scheduleDraw;
     private _drawDirty;
     private _drawChunk;
+    private _drawSegments;
     connectedCallback(): void;
     disconnectedCallback(): void;
     render(): lit.TemplateResult<1>;
@@ -103,6 +118,10 @@ declare class DawPlayheadElement extends LitElement {
     firstUpdated(): void;
     startAnimation(getTime: () => number, sampleRate: number, samplesPerPixel: number): void;
     stopAnimation(time: number, sampleRate: number, samplesPerPixel: number): void;
+    startBeatsAnimation(getTime: () => number, bpm: number, ppqn: number, ticksPerPixel: number): void;
+    stopBeatsAnimation(time: number, bpm: number, ppqn: number, ticksPerPixel: number): void;
+    startBeatsAnimationWithMap(getTime: () => number, secondsToTicks: (s: number) => number, ticksPerPixel: number): void;
+    stopBeatsAnimationWithMap(time: number, secondsToTicks: (s: number) => number, ticksPerPixel: number): void;
 }
 declare global {
     interface HTMLElementTagNameMap {
@@ -243,6 +262,15 @@ declare class PeakPipeline {
      * (default); reextractPeaks passes false and logs a single summary instead.
      */
     private _clampScale;
+    /**
+     * Extract peaks at the base scale from cached WaveformData.
+     * Returns null if no cached data exists for this buffer.
+     * Used by variable-tempo segments which handle stretching themselves.
+     */
+    getBaseScalePeaks(audioBuffer: AudioBuffer, isMono: boolean, offsetSamples?: number, durationSamples?: number): {
+        peaks: PeakData;
+        scale: number;
+    } | null;
     /**
      * Return the coarsest (largest) scale among cached WaveformData entries
      * that correspond to the given clip buffers. Returns 0 if none are cached.
@@ -275,6 +303,43 @@ declare global {
     }
 }
 
+/**
+ * `<daw-grid>` renders a musical grid overlay behind waveforms using the
+ * Audacity three-tier model:
+ *
+ *   - **Zebra stripes**: Alternating bar backgrounds at 2% white opacity.
+ *   - **Major lines** (bars): 10% white opacity, full height.
+ *   - **Minor lines** (beats): 6% white opacity, full height.
+ *   - **MinorMinor** (subdivisions): Ruler ticks only — no grid lines.
+ *
+ * Uses chunked 1000px canvases with virtual scrolling (same as daw-waveform).
+ *
+ * CSS custom properties:
+ *   --daw-grid-bar-highlight  Alternating bar fill  (default: rgba(255,255,255,0.02))
+ *   --daw-grid-major-line     Bar line color        (default: rgba(255,255,255,0.1))
+ *   --daw-grid-minor-line     Beat line color       (default: rgba(255,255,255,0.06))
+ */
+declare class DawGridElement extends LitElement {
+    ticksPerPixel: number;
+    meterEntries: MeterEntry[];
+    ppqn: number;
+    visibleStart: number;
+    visibleEnd: number;
+    length: number;
+    height: number;
+    private _tickData;
+    static styles: lit.CSSResult;
+    willUpdate(): void;
+    render(): lit.TemplateResult<1>;
+    updated(): void;
+    private _drawGrid;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-grid': DawGridElement;
+    }
+}
+
 interface RecordingOptions {
     trackId?: string;
     bits?: 8 | 16;
@@ -379,10 +444,20 @@ interface ClipPeakSlice {
 /** Host interface required by ClipPointerHandler. */
 interface ClipPointerHost {
     readonly samplesPerPixel: number;
+    /** In beats mode, the tick-derived SPP used for rendering. */
+    readonly renderSamplesPerPixel: number;
     readonly effectiveSampleRate: number;
     readonly interactiveClips: boolean;
     readonly engine: ClipEngineContract | null;
     readonly shadowRoot: ShadowRoot | null;
+    readonly scaleMode: 'temporal' | 'beats';
+    readonly ticksPerPixel: number;
+    readonly bpm: number;
+    readonly ppqn: number;
+    readonly _meterEntries: MeterEntry[];
+    readonly snapTo: SnapTo;
+    readonly _secondsToTicks: (seconds: number) => number;
+    readonly _ticksToSeconds: (ticks: number) => number;
     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;
@@ -404,7 +479,6 @@ declare class ClipPointerHandler {
     private _trackId;
     private _startPx;
     private _isDragging;
-    private _lastDeltaPx;
     private _cumulativeDeltaSamples;
     private _clipContainer;
     private _boundaryEl;
@@ -412,7 +486,17 @@ declare class ClipPointerHandler {
     private _originalWidth;
     private _originalOffsetSamples;
     private _originalDurationSamples;
+    private _originalStartSample;
     constructor(host: ClipPointerHost);
+    /**
+     * Convert a pixel delta to samples, snapping in tick space when in beats mode.
+     *
+     * The anchor is the absolute sample position being moved (e.g., clip start
+     * for move/left-trim, clip end for right-trim). Snapping the absolute
+     * position — not just the delta — ensures clips land exactly on grid lines
+     * even if they started off-grid.
+     */
+    private _snapDeltaToSamples;
     /** Returns true if a drag interaction is currently in progress. */
     get isActive(): boolean;
     /**
@@ -550,6 +634,25 @@ declare class DawEditorElement extends LitElement {
     clipHeaders: boolean;
     clipHeaderHeight: number;
     interactiveClips: boolean;
+    scaleMode: 'temporal' | 'beats';
+    get ticksPerPixel(): number;
+    set ticksPerPixel(value: number);
+    private _ticksPerPixel;
+    get bpm(): number;
+    set bpm(value: number);
+    private _bpm;
+    timeSignature: [number, number];
+    meterEntries?: MeterEntry[];
+    /** MeterEntries for grid/ruler: explicit meterEntries if set, otherwise derived from timeSignature. */
+    get _meterEntries(): MeterEntry[];
+    get ppqn(): number;
+    set ppqn(value: number);
+    private _ppqn;
+    snapTo: SnapTo;
+    /** Optional tempo-aware conversion: seconds → PPQN ticks. When provided, enables variable tempo. */
+    secondsToTicks?: (seconds: number) => number;
+    /** Optional tempo-aware conversion: PPQN ticks → seconds. Required alongside secondsToTicks. */
+    ticksToSeconds?: (ticks: number) => number;
     /** Desired sample rate. Creates a cross-browser AudioContext at this rate.
      *  Pre-computed .dat peaks render instantly when they match. */
     sampleRate: number;
@@ -572,6 +675,9 @@ declare class DawEditorElement extends LitElement {
     set audioContext(ctx: AudioContext | null);
     get audioContext(): AudioContext;
     _engine: PlaylistEngine | null;
+    private _adapter;
+    private _warnedMissingTicksToSeconds;
+    private _warnedMissingSecondsToTicks;
     private _enginePromise;
     _audioCache: Map<string, Promise<AudioBuffer>>;
     private _peaksCache;
@@ -591,6 +697,9 @@ declare class DawEditorElement extends LitElement {
     private _clipPointer;
     get _clipHandler(): ClipPointerHandler | null;
     get engine(): PlaylistEngine | null;
+    /** The adapter's Transport — use for tempo, metronome, and effects. */
+    get transport(): Transport | null;
+    get renderSamplesPerPixel(): number;
     /** Re-extract peaks for a clip at new offset/duration from cached WaveformData. */
     reextractClipPeaks(clipId: string, offsetSamples: number, durationSamples: number): {
         data: Peaks[];
@@ -601,7 +710,18 @@ declare class DawEditorElement extends LitElement {
     static styles: lit.CSSResult[];
     get effectiveSampleRate(): number;
     resolveAudioContextSampleRate(rate: number): void;
+    /**
+     * In beats mode, derive samplesPerPixel from ticksPerPixel so that
+     * clip positions, waveforms, and the tick-space grid all align.
+     */
+    private get _renderSpp();
+    /** Convert seconds to ticks — uses callback if provided, otherwise single-BPM fallback. */
+    _secondsToTicks(seconds: number): number;
+    /** Convert ticks to seconds — uses callback if provided, otherwise single-BPM fallback. */
+    _ticksToSeconds(ticks: number): number;
     private get _totalWidth();
+    /** Grid height when no tracks exist — matches scroll area's rendered height. */
+    private get _emptyGridHeight();
     _setSelectedTrackId(trackId: string | null): void;
     get tracks(): TrackDescriptor[];
     get selectedTrackId(): string | null;
@@ -673,7 +793,13 @@ declare class DawRulerElement extends LitElement {
     sampleRate: number;
     duration: number;
     rulerHeight: number;
+    scaleMode: 'temporal' | 'beats';
+    ticksPerPixel: number;
+    meterEntries: MeterEntry[];
+    ppqn: number;
+    totalWidth: number;
     private _tickData;
+    private _musicalTickData;
     static styles: lit.CSSResult;
     willUpdate(): void;
     render(): lit.TemplateResult<1>;
@@ -827,4 +953,4 @@ interface SplitHost {
  */
 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 };
+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, 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 KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackDescriptor, type UndoShortcutMap, type WaveformSegment, splitAtPlayhead };