Feat: refactoring codebase

docs/getting-started/banks_patterns.md

@@ -0,0 +1,51 @@
+# Banks & Patterns
+
+Cagire organizes all your patterns and data following a strict hierarchy:
+
+- **Projects** contain **Banks**.
+- **Banks** contain **Patterns**.
+- **Patterns** contain **Steps**.
+
+## Structure
+
+```
+Project
+└── 32 Banks
+    └── 32 Patterns (per bank)
+        └── 1024 Steps (per pattern)
+```
+
+A single project gives you 32 banks, each holding 32 patterns. You get 1024 patterns in each project, ~1.048.000 steps.
+
+## Patterns
+
+Each pattern is an independent sequence of steps with its own properties:
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| Length | Steps before the pattern loops (`1`-`1024`) | `16` |
+| Speed | Playback rate (`1/8x` to `8x`) | `1x` |
+| Quantization | When the pattern launches | `Bar` |
+| Sync Mode | Reset or Phase-Lock on re-trigger | `Reset` |
+
+Press `e` in the patterns view to edit these settings.
+
+## Patterns View
+
+Access the patterns view with `Ctrl+Up` from the sequencer. The view shows all banks and patterns in a grid. Indicators show pattern state:
+
+- `>` Currently playing
+- `+` Staged to play
+- `-` Staged to stop
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Arrows` | Navigate banks and patterns |
+| `Enter` | Select and return to sequencer |
+| `Space` | Toggle pattern playback |
+| `e` | Edit pattern properties |
+| `r` | Rename bank or pattern |
+| `c` / `v` | Copy / Paste |
+| `Delete` | Reset to empty pattern |

docs/getting-started/editing.md

@@ -0,0 +1,62 @@
+# Editing a Step
+
+Each step in Cagire contains a Forth script. When the sequencer reaches that step, it runs the script to produce sound. This is where you write your music. Press `Enter` when hovering over any step to open the `code editor`. The editor appears as a modal overlay with the step number in the title bar. If the step is a linked step (shown with an arrow like `→05`), pressing `Enter` navigates to the source step instead.
+
+## Writing Scripts
+
+Scripts are written in Forth. Type words and numbers separated by spaces. The simplest script that makes sound is:
+
+```forth
+sine sound .
+```
+
+Add parameters before words to modify them:
+
+```forth
+c4 note 0.75 decay sine sound .
+```
+
+Writing long lines is not recommended because it can become quite unmanageable. Instead, break them into multiple lines for clarity:
+
+```forth
+c4 note
+0.75 decay
+sine sound
+0.4 verb
+.
+```
+
+## Saving
+
+- `Esc` - Save and close the editor
+- `Ctrl+E` - Save without closing
+
+When you save, the script is compiled and sent to the sequencer. If there's an error, a message appears briefly at the bottom of the screen. You will also receive visual feedback in the form of a flashing window when saving / evaluating a script.
+
+## Completion
+
+As you type, the editor suggests matching Forth words. The completion list shows all built-in words that start with your current input. Press `Tab` to insert the selected suggestion, or `Esc` to dismiss the list. Use arrow keys to navigate between suggestions.
+
+Completion helps you discover words without memorizing them all. Type a few letters and browse what's available. For example, typing `ver` will suggest `verb` (reverb), typing `fil` will show filter-related words.
+
+## Debugging
+
+Press `Ctrl+S` to toggle the stack display. This shows the stack state evaluated up to the cursor line, useful for understanding how values flow through your script. Press `Ctrl+R` to execute the script immediately without waiting for the sequencer to reach the step.
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Save and close |
+| `Ctrl+E` | Save without closing |
+| `Ctrl+R` | Execute script once |
+| `Ctrl+S` | Toggle stack display |
+| `Ctrl+F` | Search |
+| `Ctrl+N` | Find next |
+| `Ctrl+P` | Find previous |
+| `Ctrl+A` | Select all |
+| `Ctrl+C` | Copy |
+| `Ctrl+X` | Cut |
+| `Ctrl+V` | Paste |
+| `Shift+Arrows` | Extend selection |
+| `Tab` | Accept completion |

docs/getting-started/grid.md

@@ -0,0 +1,52 @@
+# The Sequencer Grid
+
+The sequencer grid is the main view of Cagire. This is the one you see when you open the application. On this view, you can see the step sequencer grid and edit each step using the `code editor`. At the top, you can optionally display an oscilloscope and a spectrum analyzer.
+
+## Navigation
+
+Use arrow keys to move between steps. The grid wraps around at pattern boundaries. You can move in any direction.
+
+## Preview
+
+Press `P` to enter preview mode. In preview mode, a view-only code editor opens so that you can see the script of the currently playing step. While in preview mode, you can still move around the grid. Press `Esc` to exit preview mode.
+
+## Selection
+
+Hold `Shift` while pressing arrow keys to select multiple steps. Press `Esc` to clear the selection.
+
+## Editing Steps
+
+- `Enter` - Open the script editor.
+- `t` - Toggle step active/inactive.
+- `r` - Rename a step.
+- `Del` - Delete selected steps.
+
+## Copy & Paste
+
+- `Ctrl+C` - Copy selected steps.
+- `Ctrl+V` - Paste as copies.
+- `Ctrl+B` - Paste as linked steps.
+- `Ctrl+D` - Duplicate selection.
+- `Ctrl+H` - Harden links (convert to copies).
+
+`Linked steps` share the same script as their source. When you edit the source, all linked steps update automatically. This is an extremely important and powerful feature. It allows you to create complex patterns with minimal effort. `Ctrl+H` is your best friend to manage linked steps and convert them to real steps. 
+
+## Pattern Controls
+
+- `<` / `>` - Decrease/increase pattern length
+- `[` / `]` - Decrease/increase pattern speed
+- `L` - Set length directly
+- `S` - Set speed directly
+
+## Playback
+
+- `Space` - Toggle play/stop
+- `+` / `-` - Adjust tempo
+- `T` - Set tempo directly
+- `Ctrl+R` - Run current step once (preview)
+
+## Visual Indicators
+
+- **Highlighted cell** - Currently playing step
+- **Colored backgrounds** - Linked steps share colors by source
+- **Arrow prefix** (`→05`) - Step is linked to step 05

docs/getting-started/how_it_works.md

@@ -0,0 +1,58 @@
+# How Does It Work?
+
+Cagire is a step sequencer where each step contains a **Forth script** instead of the typical note data. When the sequencer reaches a step, it runs the script. A script _can do whatever it is programed to do_, such as producing sound commands sent to an internal audio engine. Everything else is similar to a step sequencer: you can `toggle` / `untoggle`, `copy` / `paste` any step or group of steps, etc. You are completely free to define what your scripts will do. It can be as simple as playing a note, or as complex as triggering random audio samples with complex effects. Scripts can also share code and data with each other.
+
+## Project / session organization
+
+Cagire can run multiple patterns concurrently. Each pattern contains a given number of steps. Every session / project is organized hierarchically:
+
+- **32 Banks** 
+- **32 Patterns** per bank
+- **1024 Steps** per pattern
+
+That's over 1,000,000 possible steps per project. Most of my sessions use 15-20 at best.
+
+## What does a script look like?
+
+Forth is a stack-based programming language. It is very minimalistic and emphasizes simplicity and readability. Using Forth doesn't feel like programming at all. It feels more like juggling with words and numbers or writing bad computer poetry. There is pretty much no syntax to learn, just a few rules to follow. Forth is ancient, powerful, flexible, and... super fun to live code with! Here is a minimal program that will play a middle C note using a sine wave:
+
+```forth
+c4 note sine sound .
+```
+
+Read the program backwards and you will understand what it does instantly:
+
+- `.`: we want to play a sound.
+- `sine sound`: the sound is a sinewave.
+- `c4 note`: the pitch is C4 (middle-C).
+
+Scripts can be simple one-liners or complex programs with conditionals, loops, and randomness. They tend to look like an accumulation of words and numbers. Use space and line returns to your advantage. The Forth language can be learned... on the spot. You just need to understand the following basic rules:
+
+- there are `words` and `numbers`.
+- they are delimited by spaces.
+- everything piles up on the `stack`.
+
+Obviously you will need to understand what the **stack** is, but it will take you five minutes. That's it. See the **Forth** section for details.
+
+## The Audio Engine
+
+Cagire includes a complete synthesis engine. No external software is required to play music. It comes with a large number of sound sources and sound shaping tools: oscillators, sample players, effects, filters, and more. The audio engine is quite capable and versatile, and can accomodate a vast array of genres / styles. Here are a few examples :
+
+```forth
+;; sawtooth wave with lowpass filter, chorus and reverb
+saw sound 1200 lpf 0.2 chorus 0.8 verb .
+```
+
+```forth
+;; pure sine wave with vibrato and bit crushing
+0.5 vibmod 4 vib sine sound 8 crush 0.8 gain .
+```
+
+```forth
+;; very loud and pitched-down kick drum using an audio sample
+kkick sound 1.5 distort 0.9 postgain 0.8 speed .
+```
+
+## Timing & Synchronization
+
+Cagire uses **Ableton Link** to manage timing and synchronization. This means that all devices using the same protocol can be synchronized to the same tempo. Most commercial softwares support this protocol. The playback speed is defined as a BPM (beats per minute) value. Patterns can run at different speeds relative to the master tempo. Most of the durations in Cagire are defined in terms of beats.

docs/getting-started/navigation.md

@@ -0,0 +1,40 @@
+# Navigation
+
+The Cagire application is organized as a grid composed of six views:
+
+```
+  Dict       Patterns    Options
+  Help       Sequencer   Engine
+```
+
+- `Dict` (Dictionary): A comprehensive list of all the `Forth` words used in the application.
+- `Help`: Provides detailed information about the application's features and functionalities.
+- `Patterns`: Pattern banks and pattern manager. Used to organize a session / project.
+- `Sequencer`: The main view, where you edit sequences and play music.
+- `Options`: Configuration settings for the application.
+- `Engine`: Configuration settings for the internal audio engine.
+
+## Switching Views
+
+Use `Ctrl+Arrow` keys to move between views. A minimap appears briefly showing your position in the grid.
+
+- `Ctrl+Left` / `Ctrl+Right` - move horizontally
+- `Ctrl+Up` / `Ctrl+Down` - move vertically
+
+The grid wraps horizontally, so you can cycle through views on the same row.
+
+## Getting Help
+
+Press `?` on any view to see its keybindings. This shows all available shortcuts for the current context.
+
+Press `Esc` to close the keybindings panel.
+
+## Common Keys
+
+These work on most views:
+
+- `Arrow keys` - move or scroll
+- `Tab` - switch focus between panels
+- `/` or `Ctrl+f` - search (where available)
+- `:` - jump to step number (sequencer view)
+- `q` - quit (with confirmation)

docs/getting-started/staging.md

@@ -0,0 +1,50 @@
+# Stage / Commit
+
+Cagire requires you to `stage` changes you wish to make to the playback state and then `commit` it. It is way more simple than it seems. For instance, you mark pattern `04` and `05` to start playing, and _then_ you send the order to start the playback (`commit`). The same goes for stopping patterns. You mark which pattern to stop (`stage`) and then you give the order to stop them (`commit`). Why is staging useful? Here are some reasons why this design choice was made:
+
+- **To apply multiple changes**: Queue several patterns to start/stop, commit them together.
+- **To get clean timing**: All changes happen on beat/bar boundaries.
+- **To help with live performance**: Prepare the next section without affecting current playback.
+
+Staging is an essential feature to understand to be effective when doing live performances:
+
+1. Open the **Patterns** view (`Ctrl+Up` from sequencer)
+2. Navigate to a pattern you wish to change/play
+3. Press `Space` to stage it. The pending change is going to be displayed:
+   - `+` (staged to play) 
+   - `-` (staged to stop)
+4. Repeat for other patterns you want to change
+5. Press `c` to commit all changes
+6. Or press `Esc` to cancel
+
+A pattern might not start immediately depending on the sync mode you have chosen. It might wait for the next beat/bar boundary.
+
+## Status Indicators
+
+| Indicator | Meaning |
+|-----------|---------|
+| `>` | Currently playing |
+| `+` | Staged to play |
+| `-` | Staged to stop |
+
+A pattern can show both `>` (playing) and `-` (staged to stop).
+
+## Quantization
+
+Committed changes don't execute immediately. They wait for a quantization boundary:
+
+| Setting | Behavior |
+|---------|----------|
+| Immediate | Next sequencer tick |
+| Beat | Next beat |
+| 1 Bar | Next bar (default) |
+| 2/4/8 Bars | Next 2, 4, or 8-bar boundary |
+
+Edit quantization in pattern properties (press `e` on a pattern).
+
+## Sync Mode
+
+When a pattern starts, its playback position depends on sync mode:
+
+- **Reset**: Always start at step 0
+- **Phase-Lock**: Start at the current beat-aligned position (stays in sync with other patterns)