chore: Release

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.0.3] - 2026-02-02
+
+### Added
+- Polyphonic parameters: param words (`note`, `freq`, `gain`, etc.) and sound words now consume the entire stack, enabling polyphony (e.g., `60 64 67 note sine s .` emits 3 voices).
+- New random distribution words: `exprand` (exponential) and `logrand` (logarithmic).
+- Music theory chord words: `maj`, `m`, `dim`, `aug`, `sus2`, `sus4`, `maj7`, `min7`, `dom7`, `dim7`, `m7b5`, `minmaj7`, `aug7`, `maj6`, `min6`, `dom9`, `maj9`, `min9`, `dom11`, `min11`, `dom13`, `add9`, `add11`, `madd9`, `dom7b9`, `dom7s9`, `dom7b5`, `dom7s5`.
+- Playing patterns are now saved with the project and restored on load.
+
+### Changed
+- `at` now consumes the entire stack for time offsets; polyphony multiplies with deltas (2 notes × 2 times = 4 voices).
+- Iterator (`iter`) now resets when a pattern restarts.
+- Project loading now properly resets state: stops all patterns, clears user variables/dictionary, and clears queued changes.
+
+### Removed
+- `tcycle` word (replaced by polyphonic parameter behavior).
+
 ## [0.0.2] - 2026-02-01
 - CI testing and codebase cleanup
 

Cargo.toml

@@ -2,7 +2,7 @@
 members = ["crates/forth", "crates/markdown", "crates/project", "crates/ratatui"]
 
 [workspace.package]
-version = "0.0.2"
+version = "0.0.3"
 edition = "2021"
 authors = ["Raphaël Forment <raphael.forment@gmail.com>"]
 license = "AGPL-3.0"

crates/forth/src/ops.rs

@@ -58,7 +58,6 @@ pub enum Op {
     Seed,
     Cycle,
     PCycle,
-    TCycle,
     Choose,
     ChanceExec,
     ProbExec,

crates/forth/src/types.rs

@@ -154,6 +154,14 @@ impl CmdRegister {
         &self.deltas
     }
 
+    pub(super) fn sound(&self) -> Option<&Value> {
+        self.sound.as_ref()
+    }
+
+    pub(super) fn params(&self) -> &[(String, Value)] {
+        &self.params
+    }
+
     pub(super) fn snapshot(&self) -> Option<CmdSnapshot<'_>> {
         if self.sound.is_some() || !self.params.is_empty() {
             Some((self.sound.as_ref(), self.params.as_slice()))

crates/forth/src/vm.rs

@@ -152,6 +152,23 @@ impl Forth {
             select_and_run(selected, stack, outputs, cmd)
         };
 
+        let compute_poly_count = |cmd: &CmdRegister| -> usize {
+            let sound_len = match cmd.sound() {
+                Some(Value::CycleList(items)) => items.len(),
+                _ => 1,
+            };
+            let param_max = cmd
+                .params()
+                .iter()
+                .map(|(_, v)| match v {
+                    Value::CycleList(items) => items.len(),
+                    _ => 1,
+                })
+                .max()
+                .unwrap_or(1);
+            sound_len.max(param_max)
+        };
+
         let emit_with_cycling = |cmd: &CmdRegister,
                                  emit_idx: usize,
                                  delta_secs: f64,
@@ -363,38 +380,56 @@ impl Forth {
                 }
 
                 Op::NewCmd => {
-                    let val = stack.pop().ok_or("stack underflow")?;
+                    if stack.is_empty() {
+                        return Err("stack underflow".into());
+                    }
+                    let values = std::mem::take(stack);
+                    let val = if values.len() == 1 {
+                        values.into_iter().next().unwrap()
+                    } else {
+                        Value::CycleList(values)
+                    };
                     cmd.set_sound(val);
                 }
                 Op::SetParam(param) => {
-                    let val = stack.pop().ok_or("stack underflow")?;
+                    if stack.is_empty() {
+                        return Err("stack underflow".into());
+                    }
+                    let values = std::mem::take(stack);
+                    let val = if values.len() == 1 {
+                        values.into_iter().next().unwrap()
+                    } else {
+                        Value::CycleList(values)
+                    };
                     cmd.set_param(param.clone(), val);
                 }
 
                 Op::Emit => {
+                    let poly_count = compute_poly_count(cmd);
                     let deltas = if cmd.deltas().is_empty() {
                         vec![Value::Float(0.0, None)]
                     } else {
                         cmd.deltas().to_vec()
                     };
 
-                    for (emit_idx, delta_val) in deltas.iter().enumerate() {
-                        let delta_frac = delta_val.as_float()?;
-                        let delta_secs = ctx.nudge_secs + delta_frac * ctx.step_duration();
-                        // Record delta span for highlighting
-                        if let Some(span) = delta_val.span() {
-                            if let Some(trace) = trace_cell.borrow_mut().as_mut() {
-                                trace.selected_spans.push(span);
-                            }
-                        }
-                        if let Some(sound_val) =
-                            emit_with_cycling(cmd, emit_idx, delta_secs, outputs)?
-                        {
-                            if let Some(span) = sound_val.span() {
+                    for poly_idx in 0..poly_count {
+                        for delta_val in deltas.iter() {
+                            let delta_frac = delta_val.as_float()?;
+                            let delta_secs = ctx.nudge_secs + delta_frac * ctx.step_duration();
+                            if let Some(span) = delta_val.span() {
                                 if let Some(trace) = trace_cell.borrow_mut().as_mut() {
                                     trace.selected_spans.push(span);
                                 }
                             }
+                            if let Some(sound_val) =
+                                emit_with_cycling(cmd, poly_idx, delta_secs, outputs)?
+                            {
+                                if let Some(span) = sound_val.span() {
+                                    if let Some(trace) = trace_cell.borrow_mut().as_mut() {
+                                        trace.selected_spans.push(span);
+                                    }
+                                }
+                            }
                         }
                     }
                 }
@@ -503,19 +538,6 @@ impl Forth {
                     drain_select_run(count, idx, stack, outputs, cmd)?;
                 }
 
-                Op::TCycle => {
-                    let count = stack.pop().ok_or("stack underflow")?.as_int()? as usize;
-                    if count == 0 {
-                        return Err("tcycle count must be > 0".into());
-                    }
-                    if stack.len() < count {
-                        return Err("stack underflow".into());
-                    }
-                    let start = stack.len() - count;
-                    let values: Vec<Value> = stack.drain(start..).collect();
-                    stack.push(Value::CycleList(values));
-                }
-
                 Op::Choose => {
                     let count = stack.pop().ok_or("stack underflow")?.as_int()? as usize;
                     if count == 0 {
@@ -692,27 +714,10 @@ impl Forth {
                 }
 
                 Op::At => {
-                    let top = stack.pop().ok_or("stack underflow")?;
-                    let deltas = match &top {
-                        Value::Float(..) => vec![top],
-                        Value::Int(n, _) => {
-                            let count = *n as usize;
-                            if stack.len() < count {
-                                return Err(format!(
-                                    "at: stack underflow, expected {} values but got {}",
-                                    count,
-                                    stack.len()
-                                ));
-                            }
-                            let mut vals = Vec::with_capacity(count);
-                            for _ in 0..count {
-                                vals.push(stack.pop().ok_or("stack underflow")?);
-                            }
-                            vals.reverse();
-                            vals
-                        }
-                        _ => return Err("at expects float or int count".into()),
-                    };
+                    if stack.is_empty() {
+                        return Err("stack underflow".into());
+                    }
+                    let deltas = std::mem::take(stack);
                     cmd.set_deltas(deltas);
                 }
 

crates/forth/src/words.rs

@@ -563,16 +563,6 @@ pub const WORDS: &[Word] = &[
         compile: Simple,
         varargs: true,
     },
-    Word {
-        name: "tcycle",
-        aliases: &[],
-        category: "Probability",
-        stack: "(v1..vn n -- CycleList)",
-        desc: "Create cycle list for emit-time resolution",
-        example: "60 64 67 3 tcycle note",
-        compile: Simple,
-        varargs: true,
-    },
     Word {
         name: "every",
         aliases: &[],
@@ -1231,9 +1221,9 @@ pub const WORDS: &[Word] = &[
         name: "at",
         aliases: &[],
         category: "Time",
-        stack: "(v1..vn n --)",
+        stack: "(v1..vn --)",
         desc: "Set delta context for emit timing",
-        example: "0 0.5 2 at kick s . => emits at 0 and 0.5 of step",
+        example: "0 0.5 at kick s . => emits at 0 and 0.5 of step",
         compile: Simple,
         varargs: true,
     },
@@ -2819,7 +2809,6 @@ pub(super) fn simple_op(name: &str) -> Option<Op> {
         "seed" => Op::Seed,
         "cycle" => Op::Cycle,
         "pcycle" => Op::PCycle,
-        "tcycle" => Op::TCycle,
         "choose" => Op::Choose,
         "every" => Op::Every,
         "chance" => Op::ChanceExec,

crates/project/src/file.rs

@@ -25,6 +25,8 @@ struct ProjectFile {
     sample_paths: Vec<PathBuf>,
     #[serde(default = "default_tempo")]
     tempo: f64,
+    #[serde(default)]
+    playing_patterns: Vec<(usize, usize)>,
 }
 
 fn default_tempo() -> f64 {
@@ -38,6 +40,7 @@ impl From<&Project> for ProjectFile {
             banks: project.banks.clone(),
             sample_paths: project.sample_paths.clone(),
             tempo: project.tempo,
+            playing_patterns: project.playing_patterns.clone(),
         }
     }
 }
@@ -48,6 +51,7 @@ impl From<ProjectFile> for Project {
             banks: file.banks,
             sample_paths: file.sample_paths,
             tempo: file.tempo,
+            playing_patterns: file.playing_patterns,
         };
         project.normalize();
         project

crates/project/src/project.rs

@@ -450,6 +450,8 @@ pub struct Project {
     pub sample_paths: Vec<PathBuf>,
     #[serde(default = "default_tempo")]
     pub tempo: f64,
+    #[serde(default)]
+    pub playing_patterns: Vec<(usize, usize)>,
 }
 
 fn default_tempo() -> f64 {
@@ -462,6 +464,7 @@ impl Default for Project {
             banks: (0..MAX_BANKS).map(|_| Bank::default()).collect(),
             sample_paths: Vec::new(),
             tempo: default_tempo(),
+            playing_patterns: Vec::new(),
         }
     }
 }

docs/oddities.md

@@ -193,21 +193,42 @@ You can also use quotations if you need to execute code:
 
 When the selected value is a quotation, it gets executed. When it is a plain value, it gets pushed onto the stack.
 
-Three cycling words exist:
+Two cycling words exist:
 
 - `cycle` - selects based on `runs` (how many times this step has played)
 - `pcycle` - selects based on `iter` (how many times the pattern has looped)
-- `tcycle` - creates a cycle list that resolves at emit time
 
 The difference between `cycle` and `pcycle` matters when patterns have different lengths. `cycle` counts per-step, `pcycle` counts per-pattern.
 
-`tcycle` is special. It does not select immediately. Instead it creates a value that cycles when emitted:
+## Polyphonic Parameters
+
+Parameter words like `note`, `freq`, and `gain` consume the entire stack. If you push multiple values before a param word, you get polyphony:
 
 ```forth
-0.3 0.5 0.7 3 tcycle gain
+60 64 67 note sine s .    ;; emits 3 voices with notes 60, 64, 67
 ```
 
-If you emit multiple times in one step (using `at`), each emit gets the next value from the cycle.
+This works for any param and for the sound word itself:
+
+```forth
+440 880 freq sine tri s .    ;; 2 voices: sine at 440, tri at 880
+```
+
+When params have different lengths, shorter lists cycle:
+
+```forth
+60 64 67 note           ;; 3 notes
+0.5 1.0 gain            ;; 2 gains (cycles: 0.5, 1.0, 0.5)
+sine s .                ;; emits 3 voices
+```
+
+Polyphony multiplies with `at` deltas:
+
+```forth
+0 0.5 at                ;; 2 time points
+60 64 note              ;; 2 notes
+sine s .                ;; emits 4 voices (2 notes × 2 times)
+```
 
 ## Summary
 

src/app.rs

@@ -527,10 +527,15 @@ impl App {
         self.load_step_to_editor();
     }
 
-    pub fn save(&mut self, path: PathBuf, link: &LinkState) {
+    pub fn save(&mut self, path: PathBuf, link: &LinkState, snapshot: &SequencerSnapshot) {
         self.save_editor_to_step();
         self.project_state.project.sample_paths = self.audio.config.sample_paths.clone();
         self.project_state.project.tempo = link.tempo();
+        self.project_state.project.playing_patterns = snapshot
+            .active_patterns
+            .iter()
+            .map(|p| (p.bank, p.pattern))
+            .collect();
         match model::save(&self.project_state.project, &path) {
             Ok(final_path) => {
                 self.ui
@@ -547,12 +552,27 @@ impl App {
         match model::load(&path) {
             Ok(project) => {
                 let tempo = project.tempo;
+                let playing = project.playing_patterns.clone();
+
                 self.project_state.project = project;
                 self.editor_ctx.step = 0;
                 self.load_step_to_editor();
                 self.compile_all_steps(link);
                 self.mark_all_patterns_dirty();
                 link.set_tempo(tempo);
+
+                self.playback.clear_queues();
+                self.variables.lock().unwrap().clear();
+                self.dict.lock().unwrap().clear();
+
+                for (bank, pattern) in playing {
+                    self.playback.queued_changes.push(StagedChange {
+                        change: PatternChange::Start { bank, pattern },
+                        quantization: crate::model::LaunchQuantization::Immediate,
+                        sync_mode: crate::model::SyncMode::Reset,
+                    });
+                }
+
                 self.ui.set_status(format!("Loaded: {}", path.display()));
                 self.project_state.file_path = Some(path);
             }
@@ -1103,7 +1123,7 @@ impl App {
                 }
                 self.project_state.mark_dirty(bank, pattern);
             }
-            AppCommand::Save(path) => self.save(path, link),
+            AppCommand::Save(path) => self.save(path, link, snapshot),
             AppCommand::Load(path) => self.load(path, link),
 
             // UI

src/engine/sequencer.rs

@@ -450,6 +450,10 @@ impl RunsCounter {
         *count += 1;
         current
     }
+
+    fn clear_pattern(&mut self, bank: usize, pattern: usize) {
+        self.counts.retain(|&(b, p, _), _| b != bank || p != pattern);
+    }
 }
 
 pub(crate) struct TickInput {
@@ -716,6 +720,7 @@ impl SequencerState {
                         }
                     }
                 };
+                self.runs_counter.clear_pattern(pending.id.bank, pending.id.pattern);
                 self.audio_state.active_patterns.insert(
                     pending.id,
                     ActivePattern {

src/input.rs

@@ -258,6 +258,7 @@ fn handle_modal_input(ctx: &mut InputContext, key: KeyEvent) -> InputResult {
                     match mode {
                         FileBrowserMode::Save => ctx.dispatch(AppCommand::Save(path)),
                         FileBrowserMode::Load => {
+                            let _ = ctx.seq_cmd_tx.send(SeqCommand::StopAll);
                             ctx.dispatch(AppCommand::Load(path));
                             load_project_samples(ctx);
                         }

src/state/playback.rs

@@ -28,4 +28,9 @@ impl PlaybackState {
     pub fn toggle(&mut self) {
         self.playing = !self.playing;
     }
+
+    pub fn clear_queues(&mut self) {
+        self.staged_changes.clear();
+        self.queued_changes.clear();
+    }
 }

tests/forth/list_words.rs

@@ -74,22 +74,6 @@ fn dupn_alias() {
     expect_int("5 3 ! + +", 15);
 }
 
-#[test]
-fn tcycle_creates_cycle_list() {
-    let outputs = expect_outputs(r#"0.0 at 60 64 67 3 tcycle note sine s ."#, 1);
-    assert!(outputs[0].contains("note/60"));
-}
-
-#[test]
-fn tcycle_with_multiple_emits() {
-    let f = forth();
-    let ctx = default_ctx();
-    let outputs = f.evaluate(r#"0 0.5 2 at 60 64 2 tcycle note sine s ."#, &ctx).unwrap();
-    assert_eq!(outputs.len(), 2);
-    assert!(outputs[0].contains("note/60"));
-    assert!(outputs[1].contains("note/64"));
-}
-
 #[test]
 fn cycle_zero_count_error() {
     expect_error("1 2 3 0 cycle", "cycle count must be > 0");
@@ -99,8 +83,3 @@ fn cycle_zero_count_error() {
 fn choose_zero_count_error() {
     expect_error("1 2 3 0 choose", "choose count must be > 0");
 }
-
-#[test]
-fn tcycle_zero_count_error() {
-    expect_error("1 2 3 0 tcycle", "tcycle count must be > 0");
-}

tests/forth/sound.rs

@@ -106,3 +106,35 @@ fn param_only_multiple_params() {
     assert!(outputs[0].contains("gain/0.5"));
     assert!(!outputs[0].contains("sound/"));
 }
+
+#[test]
+fn polyphonic_notes() {
+    let outputs = expect_outputs(r#"60 64 67 note sine s ."#, 3);
+    assert!(outputs[0].contains("note/60"));
+    assert!(outputs[1].contains("note/64"));
+    assert!(outputs[2].contains("note/67"));
+}
+
+#[test]
+fn polyphonic_sounds() {
+    let outputs = expect_outputs(r#"440 freq kick hat s ."#, 2);
+    assert!(outputs[0].contains("sound/kick"));
+    assert!(outputs[1].contains("sound/hat"));
+}
+
+#[test]
+fn polyphonic_cycling() {
+    let outputs = expect_outputs(r#"60 64 67 note 0.5 1.0 gain sine s ."#, 3);
+    assert!(outputs[0].contains("note/60"));
+    assert!(outputs[0].contains("gain/0.5"));
+    assert!(outputs[1].contains("note/64"));
+    assert!(outputs[1].contains("gain/1"));
+    assert!(outputs[2].contains("note/67"));
+    assert!(outputs[2].contains("gain/0.5"));
+}
+
+#[test]
+fn polyphonic_with_at() {
+    let outputs = expect_outputs(r#"0 0.5 at 60 64 note sine s ."#, 4);
+    assert_eq!(outputs.len(), 4);
+}

tests/forth/temporal.rs

@@ -42,13 +42,6 @@ fn get_sounds(outputs: &[String]) -> Vec<String> {
         .collect()
 }
 
-fn get_param(outputs: &[String], param: &str) -> Vec<f64> {
-    outputs
-        .iter()
-        .map(|o| parse_params(o).get(param).copied().unwrap_or(0.0))
-        .collect()
-}
-
 const EPSILON: f64 = 1e-9;
 
 fn approx_eq(a: f64, b: f64) -> bool {
@@ -156,7 +149,7 @@ fn at_single_delta() {
 
 #[test]
 fn at_list_deltas() {
-    let outputs = expect_outputs(r#"0 0.5 2 at "kick" s ."#, 2);
+    let outputs = expect_outputs(r#"0 0.5 at "kick" s ."#, 2);
     let deltas = get_deltas(&outputs);
     let step_dur = 0.125;
     assert!(approx_eq(deltas[0], 0.0), "expected delta 0, got {}", deltas[0]);
@@ -165,7 +158,7 @@ fn at_list_deltas() {
 
 #[test]
 fn at_three_deltas() {
-    let outputs = expect_outputs(r#"0 0.33 0.67 3 at "kick" s ."#, 3);
+    let outputs = expect_outputs(r#"0 0.33 0.67 at "kick" s ."#, 3);
     let deltas = get_deltas(&outputs);
     let step_dur = 0.125;
     assert!(approx_eq(deltas[0], 0.0), "expected delta 0");
@@ -175,70 +168,26 @@ fn at_three_deltas() {
 
 #[test]
 fn at_persists_across_emits() {
-    let outputs = expect_outputs(r#"0 0.5 2 at "kick" s . "hat" s ."#, 4);
+    let outputs = expect_outputs(r#"0 0.5 at "kick" s . "hat" s ."#, 4);
     let sounds = get_sounds(&outputs);
     assert_eq!(sounds, vec!["kick", "kick", "hat", "hat"]);
 }
 
-#[test]
-fn tcycle_basic() {
-    let outputs = expect_outputs(r#"0 0.5 0.75 3 at 60 64 67 3 tcycle note sine s ."#, 3);
-    let notes = get_param(&outputs, "note");
-    assert_eq!(notes, vec![60.0, 64.0, 67.0]);
-}
-
-#[test]
-fn tcycle_wraps() {
-    let outputs = expect_outputs(r#"0 0.33 0.67 3 at 60 64 2 tcycle note sine s ."#, 3);
-    let notes = get_param(&outputs, "note");
-    assert_eq!(notes, vec![60.0, 64.0, 60.0]);
-}
-
-#[test]
-fn tcycle_with_sound() {
-    let outputs = expect_outputs(r#"0 0.5 2 at kick hat 2 tcycle s ."#, 2);
-    let sounds = get_sounds(&outputs);
-    assert_eq!(sounds, vec!["kick", "hat"]);
-}
-
-#[test]
-fn tcycle_multiple_params() {
-    let outputs = expect_outputs(r#"0 0.5 0.75 3 at 60 64 67 3 tcycle note 0.5 1.0 2 tcycle gain sine s ."#, 3);
-    let notes = get_param(&outputs, "note");
-    let gains = get_param(&outputs, "gain");
-    assert_eq!(notes, vec![60.0, 64.0, 67.0]);
-    assert_eq!(gains, vec![0.5, 1.0, 0.5]);
-}
 
 #[test]
 fn at_reset_with_zero() {
-    let outputs = expect_outputs(r#"0 0.5 2 at "kick" s . 0.0 at "hat" s ."#, 3);
+    let outputs = expect_outputs(r#"0 0.5 at "kick" s . 0.0 at "hat" s ."#, 3);
     let sounds = get_sounds(&outputs);
     assert_eq!(sounds, vec!["kick", "kick", "hat"]);
 }
 
-#[test]
-fn tcycle_records_selected_spans() {
-    use cagire::forth::ExecutionTrace;
-
-    let f = forth();
-    let mut trace = ExecutionTrace::default();
-    let script = r#"0 0.5 2 at kick hat 2 tcycle s ."#;
-    f.evaluate_with_trace(script, &default_ctx(), &mut trace).unwrap();
-
-    // Should have 4 selected spans:
-    // - 2 for at deltas (0 and 0.5)
-    // - 2 for tcycle sound values (kick and hat)
-    assert_eq!(trace.selected_spans.len(), 4, "expected 4 selected spans (2 at + 2 tcycle)");
-}
-
 #[test]
 fn at_records_selected_spans() {
     use cagire::forth::ExecutionTrace;
 
     let f = forth();
     let mut trace = ExecutionTrace::default();
-    let script = r#"0 0.5 0.75 3 at "kick" s ."#;
+    let script = r#"0 0.5 0.75 at "kick" s ."#;
     f.evaluate_with_trace(script, &default_ctx(), &mut trace).unwrap();
 
     // Should have 6 selected spans: 3 for at deltas + 3 for sound (one per emit)