@devaloop/devalang 0.0.1-alpha.17 → 0.0.1-alpha.18

package/.devalang

@@ -3,4 +3,8 @@ entry = "./examples"
 output = "./output"
 watch = false
 debug = true
-compress = true
+compress = true
+
+[[banks]]
+path = "devalang://bank/devaloop.808"
+version = "0.0.1"

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "devalang"
-version = "0.0.1-alpha.17"
+version = "0.0.1-alpha.18"
 authors = ["Devaloop <contact@devaloop.com>"]
 description = "Write music like code. Devalang is a domain-specific language (DSL) for sound designers and music hackers. Compose, automate, and control sound — in plain text."
 license = "MIT"
@@ -30,7 +30,7 @@ default = ["cli"]
 cli = ["crossterm", "indicatif", "inquire", "zip", "reqwest", "flate2", "tokio"]
 
 [dependencies]
-devalang_types = { path = "rust/types" }
+devalang_types = { path = "rust/types", version = "0.0.1" }
 clap = { version = "4.5", features = ["derive"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
@@ -68,9 +68,9 @@ getrandom = { version = "0.3", features = ["wasm_js"] }
 uuid = { version = "1.18.0", features = ["v4", "js", "rng-getrandom"] }
 # Keep a lightweight linkage to the utils crate for wasm builds without
 # enabling native CLI features.
-devalang_utils = { path = "rust/utils", default-features = false }
+devalang_utils = { path = "rust/utils", default-features = false, version = "0.0.1" }
 
 # devalang_utils with CLI and wasmtime are only needed for native targets.
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
-devalang_utils = { path = "rust/utils", features = ["cli"] }
+devalang_utils = { path = "rust/utils", features = ["cli"], version = "0.0.1" }
 wasmtime = "19"

package/README.md

@@ -84,13 +84,16 @@ Create a new Devalang file `src/index.deva` in the project directory:
 # BPM definition
 bpm 125
 
-# Bank picking (make sure you installed it)
+# Bank picking (make sure you've installed it)
 bank devaloop.808 as my808Bank
 
+# Pattern literal without options
+pattern kickPattern with my808Bank.kick = "x--- x--- x--- x---"
+
 group myGroup:
     # Rhythmic (each beat playing a kick)
-    on beat:
-        .my808Bank.kick 1/4
+    # on beat:
+    #     .my808Bank.kick 1/4
 
     # Synth definition with ADSR
     let myLead = synth sine {
@@ -133,12 +136,12 @@ group myGroup:
     })
 
     # Notes with params
-    myLead -> note(E4, { duration: 400 })
     myLead -> note(G4, { duration: 600, glide: true, target_freq: 659.25 })
     myLead -> note(B3, { duration: 400, slide: true, target_amp: 0.3 })
 
-# Calling the group to play it
-call myGroup
+# Spawning the group & the pattern to play them in parallel
+spawn myGroup
+spawn kickPattern
 ```
 
 ### And the best part ? You can play it directly from the command line:

package/docs/CHANGELOG.md

@@ -4,7 +4,52 @@
 
 # Changelog
 
-## Version 0.0.1-alpha.17 (2025-08-31)
+## Version 0.0.1-alpha.18 (2025-09-02)
+
+### ✨ Language Features
+
+- New `pattern` statement to define rhythmic patterns with an optional target entity.
+  - Example: `pattern kickPattern with my808.kick = "x--- x--- x--- x---"`
+- Patterns can be invoked with `call` or `spawn` just like functions or groups.
+
+### 🧠 Core Engine
+
+- Pattern playback: schedules steps across one bar (4 beats), computing per-step duration and triggering the target on non-rest characters.
+- ADSR envelope: improved interpolation at segment boundaries to avoid clicks and handle 0/1-sample edge cases.
+- Sample engine: robust stereo-to-mono mixdown with RMS-preserving scaling; applies a tiny automatic fade (~1 ms) when samples start/end abruptly to reduce clicks.
+
+### 🧩 Parser & Lexer
+
+- Added `Pattern` token and parser handler; supports `pattern <name> [with <bank.trigger>] = "..."`.
+- Introduced a dedicated lexer driver (`rust/core/lexer/driver.rs`) to separate file resolution from tokenization.
+- Map/array parsing now logs structured errors via the shared logger instead of printing to stdout.
+
+### 🔁 Preprocessor & Resolution
+
+- Pattern resolver stores definitions in the variable table, enabling later `call`/`spawn` usage.
+- Variable lookup now walks parent scopes, fixing missed resolutions for outer-scope identifiers.
+
+### 🛠️ CLI & Telemetry
+
+- `build`: non-watch mode now executes and surfaces errors correctly.
+- `install`: requires authentication and reports API/JSON errors with clear messages.
+- Telemetry: generates a stable UUID when missing; consistently records CLI version, OS, and args.
+- Ensures the `.deva` directory exists at startup.
+
+### 📚 Examples
+
+- Added `examples/pattern.deva`; updated `examples/index.deva` to demonstrate `pattern` and `spawn`.
+
+### 📦 Packaging
+
+- Added crate metadata (description, license, authors) and pinned internal versions for `devalang_types` and `devalang_utils`.
+
+### 🐛 Fixes & Stability
+
+- Safer `$math` parsing with diagnostics for malformed calls and argument evaluation failures.
+- Minor parser fixes (loop body collection, clearer error messages) and logging cleanups across modules.
+
+## Version 0.0.1-alpha.17 (2025-08-30)
 
 ### ✨ Addons
 

package/docs/TODO.md

@@ -73,7 +73,7 @@ This is a list of tasks and features to be implemented in Devalang. Note that th
 
 ## Addon generator
 
-- [ ] Implement addon generator
+- [x] Implement addon generator
 - [ ] Create example addons
 
 ## Other TODOs

package/examples/index.deva

@@ -3,13 +3,16 @@
 # BPM definition
 bpm 125
 
-# Bank picking (make sure you have installed it)
+# Bank picking (make sure you've installed it)
 bank devaloop.808 as my808Bank
 
+# Pattern literal without options
+pattern kickPattern with my808Bank.kick = "x--- x--- x--- x---"
+
 group myGroup:
     # Rhythmic (each beat playing a kick)
-    on beat:
-        .my808Bank.kick 1/4
+    # on beat:
+    #     .my808Bank.kick 1/4
 
     # Synth definition with ADSR
     let myLead = synth sine {
@@ -52,9 +55,9 @@ group myGroup:
     })
 
     # Notes with params
-    myLead -> note(E4, { duration: 400 })
     myLead -> note(G4, { duration: 600, glide: true, target_freq: 659.25 })
     myLead -> note(B3, { duration: 400, slide: true, target_amp: 0.3 })
 
-# Calling the group to play it
-call myGroup
+# Spawning the group & the pattern to play them in parallel
+spawn myGroup
+spawn kickPattern

package/examples/pattern.deva

@@ -1,8 +1,8 @@
-# TODO planned for future release
+# This file demonstrates the usage of patterns in Devaloop
 
-# bank devaloop.808 as 808
+bank devaloop.808 as my808
 
-# # Pattern literal without options
-# pattern kickPattern with 808.kick = "x--- x--- x--- x---"
+# Pattern literal without options
+pattern kickPattern with my808.kick = "x--- x--- x--- x---"
 
-# call kickPattern
+call kickPattern

package/out-tsc/pkg/devalang_core.d.ts

@@ -1,7 +1,7 @@
 /* tslint:disable */
 /* eslint-disable */
+export function register_playhead_callback(cb: Function): void;
 export function parse(entry_path: string, source: string): any;
 export function debug_render(user_code: string): any;
 export function render_audio(user_code: string): Float32Array;
-export function register_playhead_callback(cb: Function): void;
 export function unregister_playhead_callback(): void;

package/out-tsc/pkg/devalang_core_bg.wasm.d.ts

@@ -1,28 +1,28 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
-export const parse: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const debug_render: (a: number, b: number) => [number, number, number];
-export const render_audio: (a: number, b: number) => [number, number, number];
+export const parse: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const register_playhead_callback: (a: any) => void;
+export const render_audio: (a: number, b: number) => [number, number, number];
 export const unregister_playhead_callback: () => void;
-export const rust_lzma_wasm_shim_malloc: (a: number) => number;
 export const rust_lzma_wasm_shim_calloc: (a: number, b: number) => number;
 export const rust_lzma_wasm_shim_free: (a: number) => void;
+export const rust_lzma_wasm_shim_malloc: (a: number) => number;
+export const rust_lzma_wasm_shim_memchr: (a: number, b: number, c: number) => number;
 export const rust_lzma_wasm_shim_memcmp: (a: number, b: number, c: number) => number;
 export const rust_lzma_wasm_shim_memcpy: (a: number, b: number, c: number) => number;
 export const rust_lzma_wasm_shim_memmove: (a: number, b: number, c: number) => number;
 export const rust_lzma_wasm_shim_memset: (a: number, b: number, c: number) => number;
 export const rust_lzma_wasm_shim_strlen: (a: number) => number;
-export const rust_lzma_wasm_shim_memchr: (a: number, b: number, c: number) => number;
-export const rust_zstd_wasm_shim_qsort: (a: number, b: number, c: number, d: number) => void;
-export const rust_zstd_wasm_shim_malloc: (a: number) => number;
-export const rust_zstd_wasm_shim_memcmp: (a: number, b: number, c: number) => number;
 export const rust_zstd_wasm_shim_calloc: (a: number, b: number) => number;
 export const rust_zstd_wasm_shim_free: (a: number) => void;
+export const rust_zstd_wasm_shim_malloc: (a: number) => number;
+export const rust_zstd_wasm_shim_memcmp: (a: number, b: number, c: number) => number;
 export const rust_zstd_wasm_shim_memcpy: (a: number, b: number, c: number) => number;
 export const rust_zstd_wasm_shim_memmove: (a: number, b: number, c: number) => number;
 export const rust_zstd_wasm_shim_memset: (a: number, b: number, c: number) => number;
+export const rust_zstd_wasm_shim_qsort: (a: number, b: number, c: number, d: number) => void;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_exn_store: (a: number) => void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devaloop/devalang",
   "private": false,
-  "version": "0.0.1-alpha.17",
+  "version": "0.0.1-alpha.18",
   "description": "Write music like code. Devalang is a domain-specific language (DSL) for sound designers and music hackers. Compose, automate, and control sound — in plain text.",
   "main": "out-tsc/index.js",
   "bin": {

package/project-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.0.1-alpha.17",
+  "version": "0.0.1-alpha.18",
   "channel": "alpha",
-  "lastCommit": "b4c1bf479cbf2334b6732cc061a855ea527560f5",
-  "build": 16
+  "lastCommit": "c57dff0f8018777c6ef04433701ed150e1255c51",
+  "build": 17
 }

package/rust/cli/build/commands.rs

@@ -91,6 +91,16 @@ pub fn handle_build_command(
             );
         })
         .unwrap();
+    } else {
+        let res = crate::cli::build::process::process_build(
+            entry_file,
+            fetched_output,
+            debug,
+            compress,
+        );
+        if let Err(e) = res {
+            return Err(e);
+        }
     }
 
     Ok(())

package/rust/cli/install/addon.rs

@@ -22,59 +22,105 @@ pub async fn install_addon(
 pub async fn ask_api_for_signed_url(addon_type: AddonType, slug: &str) -> Result<String, String> {
     let api_url = get_api_url();
 
-    let user_config = get_user_config();
-    if user_config.is_none() {
-        return Err("User is not logged in".into());
-    }
+    use devalang_utils::logger::Logger;
+    use devalang_utils::logger::LogLevel;
+
+    // Require an authenticated user for addon installation: token must be present and non-empty
+    let stored_token_opt = get_user_config()
+        .and_then(|cfg| {
+            let t = cfg.session.clone();
+            if t.trim().is_empty() {
+                None
+            } else {
+                Some(t)
+            }
+        });
 
-    let stored_token = user_config.unwrap().session.clone();
+    if stored_token_opt.is_none() {
+        let logger = Logger::new();
+        let msg = "Authentication required — run `devalang login` to authenticate";
+        logger.log_message(LogLevel::Error, msg);
+        return Err("Authentication required: run 'devalang login' to authenticate".to_string());
+    }
 
-    let request_url = format!(
-        "{}/v1/assets/url?type={}&slug={}&token={}",
-        api_url,
-        match addon_type {
-            AddonType::Bank => "bank",
-            AddonType::Plugin => "plugin",
-            AddonType::Preset => "preset",
-            AddonType::Template => "template",
-        },
-        slug,
-        stored_token
-    );
+    let request_url = if let Some(token) = &stored_token_opt {
+        format!(
+            "{}/v1/assets/url?type={}&slug={}&token={}",
+            api_url,
+            match addon_type {
+                AddonType::Bank => "bank",
+                AddonType::Plugin => "plugin",
+                AddonType::Preset => "preset",
+                AddonType::Template => "template",
+            },
+            slug,
+            token
+        )
+    } else {
+        format!(
+            "{}/v1/assets/url?type={}&slug={}",
+            api_url,
+            match addon_type {
+                AddonType::Bank => "bank",
+                AddonType::Plugin => "plugin",
+                AddonType::Preset => "preset",
+                AddonType::Template => "template",
+            },
+            slug
+        )
+    };
 
     let mut headers = reqwest::header::HeaderMap::new();
-
-    headers.insert(
-        "Authorization",
-        format!("Bearer {}", stored_token).parse().unwrap(),
-    );
+    if let Some(token) = stored_token_opt {
+        headers.insert(
+            "Authorization",
+            format!("Bearer {}", token).parse().unwrap(),
+        );
+    }
 
     let client: reqwest::Client = reqwest::Client::builder()
         .default_headers(headers)
         .build()
         .map_err(|_| "Failed to build HTTP client".to_string())?;
 
-    let req = client
+    let resp = client
         .get(&request_url)
         .send()
         .await
-        .map_err(|_| "Failed to receive response".to_string())?;
+        .map_err(|e| format!("Failed to receive response: {}", e))?;
 
-    let response_body: serde_json::Value = req
-        .json()
+    let status = resp.status();
+    let body_text = resp
+        .text()
         .await
-        .map_err(|_| "Failed to read response body".to_string())?;
+        .map_err(|e| format!("Failed to read response body: {}", e))?;
+
+    // Try to parse JSON; if parsing fails, return body for diagnostics
+    let json: serde_json::Value = match serde_json::from_str(&body_text) {
+        Ok(v) => v,
+        Err(_) => {
+            return Err(format!(
+                "Invalid JSON response (status {}): {}",
+                status, body_text
+            ));
+        }
+    };
 
-    let signed_url: String = serde_json::from_value(
-        response_body
-            .get("payload")
-            .cloned()
-            .unwrap_or_default()
-            .get("url")
-            .cloned()
-            .unwrap_or_default(),
-    )
-    .map_err(|_| "Failed to parse response body".to_string())?;
+    // Extract payload.url safely
+    let signed_url_opt = json
+        .get("payload")
+        .and_then(|p| p.get("url"))
+        .and_then(|u| u.as_str())
+        .map(|s| s.to_string());
 
-    Ok(signed_url)
+    if let Some(signed_url) = signed_url_opt {
+        Ok(signed_url)
+    } else {
+        // Provide detailed diagnostics to help user understand why it's null
+        let err_msg = format!(
+            "API returned no URL (status {}): {}",
+            status, body_text
+        );
+        Err(err_msg)
+    }
 }

package/rust/cli/telemetry/event_creator.rs

@@ -2,6 +2,7 @@ use crate::config::settings::get_user_config;
 use devalang_types::{
     TelemetryErrorLevel as SharedTelemetryErrorLevel, TelemetryEvent as SharedTelemetryEvent,
 };
+use uuid::Uuid;
 
 pub type TelemetryEvent = SharedTelemetryEvent;
 pub type TelemetryErrorLevel = SharedTelemetryErrorLevel;
@@ -57,24 +58,23 @@ impl TelemetryEventCreator {
     }
 
     pub fn get_base_event(&self) -> TelemetryEvent {
-        let mut default_event = TelemetryEvent::default();
+        let uuid = match get_user_config() {
+            Some(cfg) if !cfg.telemetry.uuid.is_empty() => cfg.telemetry.uuid.clone(),
+            _ => Uuid::new_v4().to_string(),
+        };
 
-        if let Some(user_cfg) = get_user_config() {
-            default_event = TelemetryEvent {
-                uuid: user_cfg.telemetry.uuid.clone(),
-                cli_version: env!("CARGO_PKG_VERSION").to_string(),
-                os: std::env::consts::OS.to_string(),
-                command: std::env::args().collect::<Vec<_>>(),
-                project_info: None,
-                error_level: TelemetryErrorLevel::None,
-                error_message: None,
-                exit_code: None,
-                timestamp: chrono::Utc::now().to_string(),
-                duration: 0,
-                success: true,
-            };
+        TelemetryEvent {
+            uuid,
+            cli_version: env!("CARGO_PKG_VERSION").to_string(),
+            os: std::env::consts::OS.to_string(),
+            command: std::env::args().collect::<Vec<_>>(),
+            project_info: None,
+            error_level: TelemetryErrorLevel::None,
+            error_message: None,
+            exit_code: None,
+            timestamp: chrono::Utc::now().to_string(),
+            duration: 0,
+            success: true,
         }
-
-        default_event
     }
 }

package/rust/core/audio/engine/helpers.rs

@@ -105,17 +105,29 @@ pub fn adsr_envelope_value(
     release_samples: usize,
     sustain_level: f32,
 ) -> f32 {
-    if i < attack_samples {
-        (i as f32) / (attack_samples as f32)
-    } else if i < attack_samples + decay_samples {
-        1.0 - (1.0 - sustain_level) * (((i - attack_samples) as f32) / (decay_samples as f32))
-    } else if i < attack_samples + decay_samples + sustain_samples {
+    let attack_start = 0usize;
+    let decay_start = attack_samples;
+    let sustain_start = attack_samples + decay_samples;
+    let release_start = attack_samples + decay_samples + sustain_samples;
+
+    if i < attack_start + attack_samples && attack_samples > 0 {
+        let k = i - attack_start;
+        let denom = if attack_samples > 1 { (attack_samples - 1) as f32 } else { 1.0 };
+        (k as f32) / denom
+    } else if i < decay_start + decay_samples && decay_samples > 0 {
+        let k = i - decay_start;
+        let denom = if decay_samples > 1 { (decay_samples - 1) as f32 } else { 1.0 };
+        let ratio = (k as f32) / denom;
+        1.0 - (1.0 - sustain_level) * ratio
+    } else if i < sustain_start + sustain_samples {
         sustain_level
     } else if release_samples > 0 {
-        sustain_level
-            * (1.0
-                - ((i - attack_samples - decay_samples - sustain_samples) as f32)
-                    / (release_samples as f32))
+        // release: interpolate from sustain_level down to 0 inclusive
+        let k = i.saturating_sub(release_start);
+        let denom = if release_samples > 1 { (release_samples - 1) as f32 } else { 1.0 };
+        let ratio = (k as f32) / denom;
+        let val = sustain_level * (1.0 - ratio);
+        if val < 0.0 { 0.0 } else { val }
     } else {
         0.0
     }

package/rust/core/audio/engine/sample.rs

@@ -153,8 +153,30 @@ impl super::synth::AudioEngine {
             }
         };
 
-        let max_mono_samples = (dur_sec * (SAMPLE_RATE as f32)) as usize;
-        let samples: Vec<i16> = decoder.convert_samples().take(max_mono_samples).collect();
+        // Read frames from decoder and convert to mono if needed.
+        let max_frames = (dur_sec * (SAMPLE_RATE as f32)) as usize;
+        let dec_channels = decoder.channels() as usize;
+        let max_raw_samples = max_frames.saturating_mul(dec_channels.max(1));
+        let raw_samples: Vec<i16> = decoder.convert_samples().take(max_raw_samples).collect();
+
+        // Convert interleaved channels to mono by averaging channels per frame.
+        // Apply a small RMS-preserving scale so mono level is similar to mixed stereo.
+        let actual_frames = if dec_channels > 0 { raw_samples.len() / dec_channels } else { 0 };
+        let mut samples: Vec<i16> = Vec::with_capacity(actual_frames);
+        let rms_scale = (dec_channels as f32).sqrt();
+        for frame in 0..actual_frames {
+            let mut sum: i32 = 0;
+            for ch in 0..dec_channels {
+                sum += raw_samples[frame * dec_channels + ch] as i32;
+            }
+            if dec_channels > 0 {
+                let avg = (sum / (dec_channels as i32)) as f32;
+                let scaled = (avg * rms_scale).clamp(i16::MIN as f32, i16::MAX as f32) as i16;
+                samples.push(scaled);
+            } else {
+                samples.push(0);
+            }
+        }
 
         if samples.is_empty() {
             eprintln!("❌ No samples read from {}", resolved_path);
@@ -228,6 +250,37 @@ impl super::synth::AudioEngine {
         let fade_in_samples = (fade_in * (SAMPLE_RATE as f32)) as usize;
         let fade_out_samples = (fade_out * (SAMPLE_RATE as f32)) as usize;
 
+        // If no fade specified, apply a tiny default fade (2 ms) when sample boundaries are non-zero
+    let default_boundary_fade_ms = 1.0_f32; // 1 ms
+        let default_fade_samples = (default_boundary_fade_ms * (SAMPLE_RATE as f32)) as usize;
+    let mut effective_fade_in = fade_in_samples;
+    let mut effective_fade_out = fade_out_samples;
+        if effective_fade_in == 0 {
+            if let Some(&first) = samples.first() {
+                if first.abs() > 64 { // increased threshold to detect only strong abrupt starts
+                    effective_fade_in = default_fade_samples.max(1);
+                }
+            }
+        }
+        if effective_fade_out == 0 {
+            if let Some(&last) = samples.last() {
+                if last.abs() > 64 { // increased threshold to detect only strong abrupt ends
+                    effective_fade_out = default_fade_samples.max(1);
+                }
+            }
+        }
+
+        // Ensure fades do not exceed half the sample length to avoid silencing short samples
+        if total_samples > 0 {
+            let cap = total_samples / 2;
+            if effective_fade_in > cap {
+                effective_fade_in = cap.max(1);
+            }
+            if effective_fade_out > cap {
+                effective_fade_out = cap.max(1);
+            }
+        }
+
         let delay_samples = if delay > 0.0 {
             (delay * (SAMPLE_RATE as f32)) as usize
         } else {
@@ -235,7 +288,7 @@ impl super::synth::AudioEngine {
         };
         let mut delay_buffer: Vec<f32> = vec![0.0; total_samples + delay_samples];
 
-        for i in 0..total_samples {
+    for i in 0..total_samples {
             let pitch_index = if pitch != 1.0 {
                 ((i as f32) / pitch) as usize
             } else {
@@ -250,11 +303,19 @@ impl super::synth::AudioEngine {
 
             adjusted *= gain;
 
-            if fade_in_samples > 0 && i < fade_in_samples {
-                adjusted *= (i as f32) / (fade_in_samples as f32);
+            if effective_fade_in > 0 && i < effective_fade_in {
+                if effective_fade_in == 1 {
+                    adjusted *= 0.0;
+                } else {
+                    adjusted *= (i as f32) / (effective_fade_in as f32);
+                }
             }
-            if fade_out_samples > 0 && i >= total_samples.saturating_sub(fade_out_samples) {
-                adjusted *= ((total_samples - i) as f32) / (fade_out_samples as f32);
+            if effective_fade_out > 0 && i >= total_samples.saturating_sub(effective_fade_out) {
+                if effective_fade_out == 1 {
+                    adjusted *= 0.0;
+                } else {
+                    adjusted *= ((total_samples - 1 - i) as f32) / ((effective_fade_out - 1) as f32);
+                }
             }
 
             if drive > 0.0 {

package/rust/core/audio/engine/synth.rs

@@ -51,6 +51,12 @@ impl AudioEngine {
     }
 
     pub fn merge_with(&mut self, other: AudioEngine) {
+        // If the other buffer is empty, simply return without warning (common for spawns that produced nothing)
+        if other.buffer.is_empty() {
+            return;
+        }
+
+        // If the other buffer is present but contains only zeros, warn and skip merge
         if other.buffer.iter().all(|&s| s == 0) {
             eprintln!("⚠️ Skipping merge: other buffer is silent");
             return;
@@ -225,10 +231,19 @@ impl AudioEngine {
             );
 
             // Fade in/out
-            if i < fade_len {
-                value *= (i as f32) / (fade_len as f32);
-            } else if i >= total_samples - fade_len {
-                value *= ((total_samples - i) as f32) / (fade_len as f32);
+            if fade_len > 0 && i < fade_len {
+                if fade_len == 1 {
+                    value *= 0.0;
+                } else {
+                    value *= (i as f32) / (fade_len as f32);
+                }
+            } else if fade_len > 0 && i >= total_samples.saturating_sub(fade_len) {
+                if fade_len == 1 {
+                    value *= 0.0;
+                } else {
+                    // ensure last sample becomes exactly zero to avoid clicks
+                    value *= ((total_samples - 1 - i) as f32) / ((fade_len - 1) as f32);
+                }
             }
 
             value *= envelope;