@drop-ai/core 0.2.0

package/dist/audio/SourceCache.js

@@ -0,0 +1,205 @@
+/**
+ * SourceCache — an LRU cache for decoded audio buffers keyed by source id.
+ *
+ * Inspired by Ardour's `SourceFactory` / `Source::DecodeCache`
+ * (`libs/ardour/source_factory.cc`).
+ *
+ * Large sessions can reference hundreds of audio files.  Decoding them on
+ * demand is expensive, but keeping *every* decoded buffer in memory is not
+ * always feasible.  `SourceCache` strikes a balance by caching up to a
+ * configurable memory limit and evicting least-recently-used entries when
+ * the limit is exceeded.
+ *
+ * This class has **no** external dependencies (no audio framework imports)
+ * and can be unit-tested in isolation.
+ *
+ * @example
+ * ```ts
+ * const cache = new SourceCache(256); // 256 MB limit
+ *
+ * cache.set('kick.wav', decodedBuffer);
+ *
+ * const buf = cache.get('kick.wav');  // cache hit
+ * console.log(cache.getCacheHitRate()); // 1.0
+ * ```
+ *
+ * @module SourceCache
+ */
+/**
+ * SourceCache provides an LRU (least-recently-used) cache for
+ * {@link AudioBuffer} instances, bounded by a configurable memory limit.
+ */
+export class SourceCache {
+    /**
+     * @param maxMemoryMB - Maximum cache size in megabytes.  Defaults to
+     *   512 MB.
+     */
+    constructor(maxMemoryMB = 512) {
+        /** Map of source id to cache entry. */
+        this.cache = new Map();
+        /** Running total of cached memory in bytes. */
+        this.currentMemoryBytes = 0;
+        // -- Statistics ---------------------------------------------------
+        /** Number of successful cache lookups. */
+        this.hits = 0;
+        /** Number of cache misses. */
+        this.misses = 0;
+        this.maxMemoryBytes = maxMemoryMB * 1024 * 1024;
+    }
+    // ---------------------------------------------------------------
+    // Core API
+    // ---------------------------------------------------------------
+    /**
+     * Retrieve a cached {@link AudioBuffer} by source id.
+     *
+     * On a hit the entry's `lastAccess` timestamp is refreshed so it is less
+     * likely to be evicted.
+     *
+     * @param sourceId - Unique identifier for the audio source.
+     * @returns The cached buffer, or `null` on a miss.
+     */
+    get(sourceId) {
+        const entry = this.cache.get(sourceId);
+        if (entry) {
+            entry.lastAccess = Date.now();
+            this.hits++;
+            return entry.buffer;
+        }
+        this.misses++;
+        return null;
+    }
+    /**
+     * Add or replace an {@link AudioBuffer} in the cache.
+     *
+     * If inserting the buffer would exceed the memory limit, LRU entries are
+     * evicted first.  If the buffer itself is larger than the entire cache
+     * limit it is still stored (after evicting everything), allowing
+     * single-buffer lookups to work.
+     *
+     * @param sourceId - Unique identifier for the audio source.
+     * @param buffer   - The decoded audio data to cache.
+     */
+    set(sourceId, buffer) {
+        // If this source is already cached, remove the old entry first
+        if (this.cache.has(sourceId)) {
+            this.remove(sourceId);
+        }
+        const sizeBytes = this.estimateBufferSize(buffer);
+        // Evict until there is room (or the cache is empty)
+        while (this.cache.size > 0 &&
+            this.currentMemoryBytes + sizeBytes > this.maxMemoryBytes) {
+            this.evictOne();
+        }
+        const entry = {
+            buffer,
+            lastAccess: Date.now(),
+            sizeBytes,
+        };
+        this.cache.set(sourceId, entry);
+        this.currentMemoryBytes += sizeBytes;
+    }
+    /**
+     * Check whether a source id is present in the cache without affecting
+     * access statistics or the LRU order.
+     *
+     * @param sourceId - The source id to look up.
+     */
+    has(sourceId) {
+        return this.cache.has(sourceId);
+    }
+    /**
+     * Explicitly remove a source from the cache.
+     *
+     * @param sourceId - The source id to remove.
+     */
+    remove(sourceId) {
+        const entry = this.cache.get(sourceId);
+        if (entry) {
+            this.currentMemoryBytes -= entry.sizeBytes;
+            this.cache.delete(sourceId);
+        }
+    }
+    // ---------------------------------------------------------------
+    // Eviction
+    // ---------------------------------------------------------------
+    /**
+     * Evict entries using LRU policy until the current memory usage is at or
+     * below the configured limit.
+     *
+     * This is called automatically by {@link set}, but can also be invoked
+     * manually (e.g. after reducing the memory limit at runtime).
+     */
+    evict() {
+        while (this.cache.size > 0 &&
+            this.currentMemoryBytes > this.maxMemoryBytes) {
+            this.evictOne();
+        }
+    }
+    /**
+     * Evict the single least-recently-used entry.
+     */
+    evictOne() {
+        let oldestId = null;
+        let oldestAccess = Infinity;
+        for (const [id, entry] of this.cache) {
+            if (entry.lastAccess < oldestAccess) {
+                oldestAccess = entry.lastAccess;
+                oldestId = id;
+            }
+        }
+        if (oldestId !== null) {
+            this.remove(oldestId);
+        }
+    }
+    // ---------------------------------------------------------------
+    // Statistics / diagnostics
+    // ---------------------------------------------------------------
+    /**
+     * Current memory usage in bytes.
+     */
+    getMemoryUsage() {
+        return this.currentMemoryBytes;
+    }
+    /**
+     * Current memory usage in megabytes.
+     */
+    getMemoryUsageMB() {
+        return this.currentMemoryBytes / (1024 * 1024);
+    }
+    /**
+     * Cache hit rate as a ratio `[0, 1]`.
+     *
+     * Returns `0` if no lookups have been performed yet.
+     */
+    getCacheHitRate() {
+        const total = this.hits + this.misses;
+        return total === 0 ? 0 : this.hits / total;
+    }
+    /**
+     * Number of entries currently in the cache.
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Remove all entries from the cache and reset statistics.
+     */
+    clear() {
+        this.cache.clear();
+        this.currentMemoryBytes = 0;
+        this.hits = 0;
+        this.misses = 0;
+    }
+    // ---------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------
+    /**
+     * Estimate the memory footprint of a decoded {@link AudioBuffer}.
+     *
+     * Each channel is a `Float32Array` (4 bytes per sample).
+     */
+    estimateBufferSize(buffer) {
+        return buffer.numberOfChannels * buffer.length * Float32Array.BYTES_PER_ELEMENT;
+    }
+}
+//# sourceMappingURL=SourceCache.js.map

package/dist/audio/SourceCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceCache.js","sourceRoot":"","sources":["../../src/audio/SourceCache.ts"],"names":[],"mappings":"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"}

package/dist/audio/dto.d.ts

@@ -0,0 +1,50 @@
+import { RegionId, SourceId, FrameCount } from '../domain/types';
+import { TimeDomain } from '../domain/temporal/types';
+export interface RegionDTO {
+    id: RegionId;
+    sourceId: SourceId;
+    start: FrameCount;
+    length: FrameCount;
+    end: FrameCount;
+    sourceStart: FrameCount;
+    name: string;
+    gain: number;
+    muted: boolean;
+    layer: number;
+    fadeIn: FrameCount;
+    fadeOut: FrameCount;
+    playbackRate: number;
+    /** Pitch-preserving time stretch ratio (1.0 = normal) */
+    stretch: number;
+    /** Pitch shift in semitones (0 = no shift) */
+    pitchSemitones: number;
+    timeDomain: TimeDomain;
+}
+export interface TrackDTO {
+    id: string;
+    gain: number;
+    pan: number;
+    regions: RegionDTO[];
+}
+export interface MidiNoteDTO {
+    id: string;
+    pitch: number;
+    velocity: number;
+    startFrame: number;
+    durationFrames: number;
+    channel: number;
+}
+export interface MidiRegionDTO {
+    id: string;
+    name: string;
+    start: number;
+    length: number;
+    end: number;
+    muted: boolean;
+    notes: MidiNoteDTO[];
+}
+export interface AudioWorkletMessage {
+    type: string;
+    payload?: Record<string, unknown>;
+}
+//# sourceMappingURL=dto.d.ts.map

package/dist/audio/dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../../src/audio/dto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAEtD,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,QAAQ,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,UAAU,CAAC;IAChB,WAAW,EAAE,UAAU,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,UAAU,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;CAC1B;AAED,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,SAAS,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,WAAW,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC"}

package/dist/audio/dto.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dto.js.map

package/dist/audio/dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.js","sourceRoot":"","sources":["../../src/audio/dto.ts"],"names":[],"mappings":""}

package/dist/audio/engine/PlaylistEngine.d.ts

@@ -0,0 +1,19 @@
+import { RegionDTO } from '../dto';
+import { FrameCount } from '../../domain/types';
+/** Fade curve shape, matching Ardour's fade types */
+export declare const enum FadeCurve {
+    Linear = 0,
+    EqualPower = 1,
+    Exponential = 2
+}
+export declare class PlaylistEngine {
+    /**
+     * Renders a block of audio for a given set of regions.
+     * Higher-layer regions take priority — when regions overlap,
+     * only the top-most layer's audio is heard at each sample position.
+     * Fades are applied per-region before the layer priority check.
+     */
+    render(outputLeft: Float32Array, outputRight: Float32Array, startFrame: FrameCount, numFrames: FrameCount, regions: RegionDTO[], getBuffer: (url: string) => AudioBuffer | null): void;
+    private renderRegion;
+}
+//# sourceMappingURL=PlaylistEngine.d.ts.map

package/dist/audio/engine/PlaylistEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaylistEngine.d.ts","sourceRoot":"","sources":["../../../src/audio/engine/PlaylistEngine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,qDAAqD;AACrD,0BAAkB,SAAS;IACvB,MAAM,IAAI;IACV,UAAU,IAAI;IACd,WAAW,IAAI;CAClB;AAED,qBAAa,cAAc;IACvB;;;;;OAKG;IACI,MAAM,CACT,UAAU,EAAE,YAAY,EACxB,WAAW,EAAE,YAAY,EACzB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,SAAS,EAAE,EACpB,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,WAAW,GAAG,IAAI,GAC/C,IAAI;IAwBP,OAAO,CAAC,YAAY;CAqEvB"}

package/dist/audio/engine/PlaylistEngine.js

@@ -0,0 +1,83 @@
+/** Fade curve shape, matching Ardour's fade types */
+export var FadeCurve;
+(function (FadeCurve) {
+    FadeCurve[FadeCurve["Linear"] = 0] = "Linear";
+    FadeCurve[FadeCurve["EqualPower"] = 1] = "EqualPower";
+    FadeCurve[FadeCurve["Exponential"] = 2] = "Exponential";
+})(FadeCurve || (FadeCurve = {}));
+export class PlaylistEngine {
+    /**
+     * Renders a block of audio for a given set of regions.
+     * Higher-layer regions take priority — when regions overlap,
+     * only the top-most layer's audio is heard at each sample position.
+     * Fades are applied per-region before the layer priority check.
+     */
+    render(outputLeft, outputRight, startFrame, numFrames, regions, getBuffer) {
+        // 1. Find active regions in this block
+        const endFrame = startFrame + numFrames;
+        const activeRegions = regions.filter(r => r.start < endFrame && r.end > startFrame && !r.muted);
+        // 2. Sort by layer descending (highest layer renders first, takes priority)
+        activeRegions.sort((a, b) => b.layer - a.layer);
+        // 3. Clear output
+        outputLeft.fill(0);
+        outputRight.fill(0);
+        // 4. Coverage mask: tracks which sample positions are already filled
+        //    by a higher-layer region. Lower layers only write to uncovered positions.
+        const covered = new Uint8Array(numFrames);
+        // 5. Render each region (highest layer first)
+        for (const region of activeRegions) {
+            this.renderRegion(outputLeft, outputRight, startFrame, numFrames, region, getBuffer, covered);
+        }
+    }
+    renderRegion(outL, outR, startFrame, numFrames, region, getBuffer, covered) {
+        const buffer = getBuffer(region.sourceId);
+        if (!buffer)
+            return;
+        const bufferDataL = buffer.getChannelData(0);
+        const bufferDataR = buffer.numberOfChannels > 1 ? buffer.getChannelData(1) : bufferDataL;
+        const renderStart = Math.max(startFrame, region.start);
+        const renderEnd = Math.min(startFrame + numFrames, region.end);
+        const regionOffset = region.sourceStart + (renderStart - region.start);
+        const outOffset = renderStart - startFrame;
+        const length = renderEnd - renderStart;
+        const playbackRate = region.playbackRate || 1.0;
+        for (let i = 0; i < length; i++) {
+            const outIdx = outOffset + i;
+            // Skip positions already covered by a higher-layer region
+            if (covered[outIdx])
+                continue;
+            // With playbackRate, we need to resample
+            const sourcePosition = regionOffset + (i * playbackRate);
+            const sampleIdx = Math.floor(sourcePosition);
+            const frac = sourcePosition - sampleIdx;
+            if (sampleIdx >= bufferDataL.length - 1)
+                break;
+            // Linear interpolation for resampling
+            const sampleL0 = bufferDataL[sampleIdx];
+            const sampleL1 = bufferDataL[sampleIdx + 1];
+            const sampleR0 = bufferDataR[sampleIdx];
+            const sampleR1 = bufferDataR[sampleIdx + 1];
+            const interpolatedL = sampleL0 + (sampleL1 - sampleL0) * frac;
+            const interpolatedR = sampleR0 + (sampleR1 - sampleR0) * frac;
+            // Apply fade envelope
+            const currentPos = renderStart + i - region.start;
+            let fadeGain = 1.0;
+            if (region.fadeIn > 0 && currentPos < region.fadeIn) {
+                const t = currentPos / region.fadeIn;
+                fadeGain = Math.sqrt(t);
+            }
+            else if (region.fadeOut > 0 && currentPos >= region.length - region.fadeOut) {
+                const distFromEnd = region.length - currentPos;
+                const t = Math.max(0, distFromEnd / region.fadeOut);
+                fadeGain = Math.sqrt(t);
+            }
+            const gain = region.gain * fadeGain;
+            // Write to output (not additive — top layer wins)
+            outL[outIdx] = interpolatedL * gain;
+            outR[outIdx] = interpolatedR * gain;
+            // Mark this position as covered
+            covered[outIdx] = 1;
+        }
+    }
+}
+//# sourceMappingURL=PlaylistEngine.js.map

package/dist/audio/engine/PlaylistEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaylistEngine.js","sourceRoot":"","sources":["../../../src/audio/engine/PlaylistEngine.ts"],"names":[],"mappings":"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"}

package/dist/automation/AutomationCurve.d.ts

@@ -0,0 +1,61 @@
+import { AutomationPoint } from './types';
+/**
+ * Coefficients for a single cubic spline segment.
+ * The polynomial is: y = a + b*x + c*x^2 + d*x^3
+ * where x is the local offset from the segment start time.
+ */
+export interface SplineCoefficients {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+}
+/**
+ * Provides interpolation between automation points, including a CJC Kruger
+ * constrained cubic spline algorithm that prevents overshoot.
+ */
+export declare class AutomationCurve {
+    /** Cached spline coefficients, one per segment (points.length - 1). */
+    private _splineCoeffs;
+    /** The points array snapshot used to compute the current coefficients. */
+    private _splinePoints;
+    /**
+     * Calculates the interpolated value between two points at a given time.
+     * For non-spline interpolation types, this static method is sufficient.
+     * @param start The starting automation point
+     * @param end The ending automation point
+     * @param time The time to calculate the value for (must be between start.time and end.time)
+     * @param _curvature Optional tension/curvature parameter (not yet implemented fully)
+     */
+    static getValueAt(start: AutomationPoint, end: AutomationPoint, time: number, _curvature?: number): number;
+    /**
+     * Recomputes CJC Kruger constrained cubic spline coefficients for the
+     * given set of points. Must be called whenever points change if Curved
+     * interpolation is in use.
+     *
+     * The CJC Kruger variant constrains tangent slopes so that the spline
+     * is monotone between consecutive data points, preventing overshoot
+     * and oscillation artifacts common with natural cubic splines.
+     *
+     * @param points Sorted automation points array
+     */
+    computeSplineCoefficients(points: ReadonlyArray<AutomationPoint>): void;
+    /**
+     * Returns the spline-interpolated value at the given time.
+     * Falls back to the static getValueAt for non-Curved interpolation types.
+     *
+     * @param points The sorted automation points
+     * @param time The time to evaluate
+     * @returns The interpolated value, or null if no points exist
+     */
+    getValueAt(points: ReadonlyArray<AutomationPoint>, time: number): number | null;
+    /**
+     * Invalidates cached spline coefficients. Call this when points change.
+     */
+    invalidateSpline(): void;
+    /**
+     * Returns a copy of the current spline coefficients (for inspection/testing).
+     */
+    getSplineCoefficients(): ReadonlyArray<SplineCoefficients>;
+}
+//# sourceMappingURL=AutomationCurve.d.ts.map

package/dist/automation/AutomationCurve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutomationCurve.d.ts","sourceRoot":"","sources":["../../src/automation/AutomationCurve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAqB,MAAM,SAAS,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,qBAAa,eAAe;IACxB,uEAAuE;IACvE,OAAO,CAAC,aAAa,CAA4B;IACjD,0EAA0E;IAC1E,OAAO,CAAC,aAAa,CAAsC;IAE3D;;;;;;;OAOG;WACW,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,MAAY,GAAG,MAAM;IAiCtH;;;;;;;;;;OAUG;IACI,yBAAyB,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI;IAwF9E;;;;;;;OAOG;IACI,UAAU,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAyCtF;;OAEG;IACI,gBAAgB,IAAI,IAAI;IAK/B;;OAEG;IACI,qBAAqB,IAAI,aAAa,CAAC,kBAAkB,CAAC;CAGpE"}

package/dist/automation/AutomationCurve.js

@@ -0,0 +1,198 @@
+import { InterpolationType } from './types';
+/**
+ * Provides interpolation between automation points, including a CJC Kruger
+ * constrained cubic spline algorithm that prevents overshoot.
+ */
+export class AutomationCurve {
+    constructor() {
+        /** Cached spline coefficients, one per segment (points.length - 1). */
+        this._splineCoeffs = [];
+        /** The points array snapshot used to compute the current coefficients. */
+        this._splinePoints = [];
+    }
+    /**
+     * Calculates the interpolated value between two points at a given time.
+     * For non-spline interpolation types, this static method is sufficient.
+     * @param start The starting automation point
+     * @param end The ending automation point
+     * @param time The time to calculate the value for (must be between start.time and end.time)
+     * @param _curvature Optional tension/curvature parameter (not yet implemented fully)
+     */
+    static getValueAt(start, end, time, _curvature = 0.5) {
+        if (time <= start.time)
+            return start.value;
+        if (time >= end.time)
+            return end.value;
+        // Normalized time (0 to 1)
+        const t = (time - start.time) / (end.time - start.time);
+        switch (start.interpolation) {
+            case InterpolationType.Hold:
+                return start.value;
+            case InterpolationType.Linear:
+                return start.value + t * (end.value - start.value);
+            case InterpolationType.Exponential:
+                // Safe geometric interpolation (fallback to linear if signs differ or zero)
+                if (start.value > 0.0001 && end.value > 0.0001) {
+                    return start.value * Math.pow(end.value / start.value, t);
+                }
+                // Fallback to simpler curve: y = x^2 (slow start, fast end)
+                const curveT = t * t;
+                return start.value + curveT * (end.value - start.value);
+            case InterpolationType.Logarithmic:
+                // y = sqrt(x) (fast start, slow end)
+                const logT = Math.sqrt(t);
+                return start.value + logT * (end.value - start.value);
+            default:
+                return start.value + t * (end.value - start.value);
+        }
+    }
+    /**
+     * Recomputes CJC Kruger constrained cubic spline coefficients for the
+     * given set of points. Must be called whenever points change if Curved
+     * interpolation is in use.
+     *
+     * The CJC Kruger variant constrains tangent slopes so that the spline
+     * is monotone between consecutive data points, preventing overshoot
+     * and oscillation artifacts common with natural cubic splines.
+     *
+     * @param points Sorted automation points array
+     */
+    computeSplineCoefficients(points) {
+        this._splinePoints = points;
+        this._splineCoeffs = [];
+        const n = points.length;
+        if (n < 2)
+            return;
+        // Step 1: compute finite-difference slopes delta_k = (y_{k+1} - y_k) / (x_{k+1} - x_k)
+        const delta = new Array(n - 1);
+        for (let i = 0; i < n - 1; i++) {
+            const dx = points[i + 1].time - points[i].time;
+            delta[i] = dx === 0 ? 0 : (points[i + 1].value - points[i].value) / dx;
+        }
+        // Step 2: CJC Kruger constrained tangent slopes
+        // For interior points, use harmonic mean when signs agree, else 0.
+        // Boundary tangents use one-sided finite difference.
+        const m = new Array(n);
+        // Boundary slopes
+        m[0] = delta[0];
+        m[n - 1] = delta[n - 2];
+        for (let i = 1; i < n - 1; i++) {
+            if (delta[i - 1] * delta[i] <= 0) {
+                // Slopes have different signs or one is zero -> constrain to zero
+                m[i] = 0;
+            }
+            else {
+                // CJC Kruger: harmonic mean of adjacent slopes
+                m[i] = 2 / (1 / delta[i - 1] + 1 / delta[i]);
+            }
+        }
+        // Additional Kruger constraint: ensure monotonicity
+        // If delta[i] == 0, the tangents at both ends of that segment must be 0
+        for (let i = 0; i < n - 1; i++) {
+            if (delta[i] === 0) {
+                m[i] = 0;
+                m[i + 1] = 0;
+            }
+        }
+        // Clamp boundary slopes to prevent overshoot (Fritsch-Carlson style check)
+        for (let i = 0; i < n - 1; i++) {
+            if (delta[i] !== 0) {
+                const alpha = m[i] / delta[i];
+                const beta = m[i + 1] / delta[i];
+                // If the vector (alpha, beta) lies outside the circle of radius 3, scale it back
+                const mag = Math.sqrt(alpha * alpha + beta * beta);
+                if (mag > 3) {
+                    const tau = 3 / mag;
+                    m[i] = tau * alpha * delta[i];
+                    m[i + 1] = tau * beta * delta[i];
+                }
+            }
+        }
+        // Step 3: compute cubic Hermite coefficients per segment
+        // Given segment from x_i to x_{i+1} with values y_i, y_{i+1} and slopes m_i, m_{i+1}:
+        // Using local variable x = (time - x_i), h = x_{i+1} - x_i
+        // Hermite basis -> polynomial coefficients a,b,c,d where y = a + b*x + c*x^2 + d*x^3
+        for (let i = 0; i < n - 1; i++) {
+            const h = points[i + 1].time - points[i].time;
+            const y0 = points[i].value;
+            const y1 = points[i + 1].value;
+            const m0 = m[i];
+            const m1 = m[i + 1];
+            if (h === 0) {
+                // Degenerate segment (coincident times)
+                this._splineCoeffs.push({ a: y0, b: 0, c: 0, d: 0 });
+                continue;
+            }
+            // Hermite to power basis conversion:
+            // a = y0
+            // b = m0
+            // c = (3*(y1-y0)/h - 2*m0 - m1) / h
+            // d = (2*(y0-y1)/h + m0 + m1) / h^2
+            const a = y0;
+            const b = m0;
+            const c = (3 * (y1 - y0) / h - 2 * m0 - m1) / h;
+            const d = (2 * (y0 - y1) / h + m0 + m1) / (h * h);
+            this._splineCoeffs.push({ a, b, c, d });
+        }
+    }
+    /**
+     * Returns the spline-interpolated value at the given time.
+     * Falls back to the static getValueAt for non-Curved interpolation types.
+     *
+     * @param points The sorted automation points
+     * @param time The time to evaluate
+     * @returns The interpolated value, or null if no points exist
+     */
+    getValueAt(points, time) {
+        const n = points.length;
+        if (n === 0)
+            return null;
+        if (time <= points[0].time)
+            return points[0].value;
+        if (time >= points[n - 1].time)
+            return points[n - 1].value;
+        // Find the segment containing `time` via binary search
+        let lo = 0;
+        let hi = n - 1;
+        while (lo < hi - 1) {
+            const mid = (lo + hi) >> 1;
+            if (points[mid].time <= time) {
+                lo = mid;
+            }
+            else {
+                hi = mid;
+            }
+        }
+        const start = points[lo];
+        const end = points[hi];
+        // For non-Curved types, delegate to the static method
+        if (start.interpolation !== InterpolationType.Curved) {
+            return AutomationCurve.getValueAt(start, end, time);
+        }
+        // Curved: use precomputed spline coefficients
+        if (this._splineCoeffs.length === 0 || this._splinePoints !== points) {
+            this.computeSplineCoefficients(points);
+        }
+        if (lo < this._splineCoeffs.length) {
+            const coeff = this._splineCoeffs[lo];
+            const x = time - start.time;
+            return coeff.a + coeff.b * x + coeff.c * x * x + coeff.d * x * x * x;
+        }
+        // Fallback
+        return AutomationCurve.getValueAt(start, end, time);
+    }
+    /**
+     * Invalidates cached spline coefficients. Call this when points change.
+     */
+    invalidateSpline() {
+        this._splineCoeffs = [];
+        this._splinePoints = [];
+    }
+    /**
+     * Returns a copy of the current spline coefficients (for inspection/testing).
+     */
+    getSplineCoefficients() {
+        return [...this._splineCoeffs];
+    }
+}
+//# sourceMappingURL=AutomationCurve.js.map