> ## Documentation Index
> Fetch the complete documentation index at: https://songbird.studiocollective.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# songbird-state

# songbird-state

Pure data layer for the Songbird DAW. Defines the project data model, entity types, channel-aligned state slices, and persistence.

**This crate has no business logic, no I/O beyond persistence, and no engine dependencies.**

## Architecture

```
songbird-state/src/
├── ids.rs              Strongly-typed entity IDs (TrackId, ClipId, etc.)
├── map.rs              Map<K, V> — ordered collection with dirty tracking
├── entities/           Domain entity structs (atoms)
├── slices/             Channel-aligned slice structs (molecules)
├── state_manager.rs    StateManager — root state container (organism)
├── store/              StateStore — change tracking, undo/redo, listeners
└── persistence/        File I/O: bird text, session autosave, git history
```

### Layer Hierarchy

```
StateManager           ← single root, composes all slices
  └── 10 Slices        ← one per sync engine channel
       └── Entities    ← individual domain types
            └── IDs    ← strongly-typed keys
```

## Entities

Domain types with `Serialize + Deserialize`. No business logic beyond constructors and accessors.

| Entity              | File                     | Description                                  |
| ------------------- | ------------------------ | -------------------------------------------- |
| `Track`             | `entities/track.rs`      | Audio/MIDI track metadata                    |
| `Clip`              | `entities/clip.rs`       | Audio or MIDI clip content                   |
| `MixerState`        | `entities/mixer.rs`      | Per-track mix state (gain, pan, mute, solo)  |
| `PluginInstance`    | `entities/plugin.rs`     | Plugin instance with saved parameter state   |
| `AutomationLane`    | `entities/automation.rs` | Parameter automation breakpoints             |
| `Section`           | `entities/section.rs`    | Arrangement section                          |
| `SongMetadata`      | `entities/song.rs`       | BPM, key, time signature                     |
| `ProjectMetadata`   | `entities/project.rs`    | Project name, ID, sample rate                |
| `LoopState`         | `entities/transport.rs`  | Loop region and enable state                 |
| `MetronomeState`    | `entities/transport.rs`  | Click track settings                         |
| `ArmState`          | `entities/recording.rs`  | Per-track record arm and input routing       |
| `Marker` / `Region` | `entities/marker.rs`     | Timeline markers, regions, tempo/key markers |
| `ChatStore`         | `entities/chat.rs`       | AI chat history and model config             |
| `GenerationStore`   | `entities/generation.rs` | AI generation job history                    |
| `UserSettings`      | `entities/settings.rs`   | Global user preferences                      |

## Slices

Channel-aligned structs that group related entities. Each slice maps 1:1 to a sync engine channel and a persistence file.

| Slice             | Channel                | Persistence file   | Contents                                  |
| ----------------- | ---------------------- | ------------------ | ----------------------------------------- |
| `SongSlice`       | `track.*`, `section.*` | `{name}.bird`      | tracks, sections, tempo/key markers       |
| `ClipSlice`       | `track.*`              | `{name}.bird`      | clips                                     |
| `AutomationSlice` | `track.*`              | `{name}.bird`      | automation lanes                          |
| `ProjectSlice`    | `project.*`            | `daw.state.json`   | metadata, markers, regions, engine config |
| `TransportSlice`  | `transport.*`          | `daw.state.json`   | loop state, metronome                     |
| `RecordingSlice`  | `recording.*`          | `daw.state.json`   | per-track arm state                       |
| `MixerSlice`      | `mixer.*`              | `daw.mixer.json`   | per-track mix, sends, returns, master bus |
| `PluginSlice`     | `plugin.*`             | `daw.plugins.json` | plugin instances                          |
| `AiSlice`         | `ai.*`                 | `daw.ai.json`      | chat, generation                          |
| `SettingsSlice`   | `settings.*`           | `settings.json`    | user preferences (global)                 |

## StateManager

The root state container. One `StateManager` per open project.

```rust theme={null}
pub struct StateManager {
    pub song:       SongSlice,
    pub clip:       ClipSlice,
    pub automation: AutomationSlice,
    pub project:    ProjectSlice,
    pub transport:  TransportSlice,
    pub recording:  RecordingSlice,
    pub mixer:      MixerSlice,
    pub plugin:     PluginSlice,
    pub ai:         AiSlice,
    pub settings:   SettingsSlice,
}
```

**Key property**: because each field is a separate struct, Rust allows simultaneous `&mut` borrows of different slices — e.g., a mixer command can mutate `state.mixer` while a transport command reads `state.transport`.

## StateStore

Wraps `StateManager` with:

* **Undo/redo** — snapshots before each mutation
* **Change listeners** — notify subscribers on mutation
* **Dirty tracking** — which slices changed since last persist
* **Git persistence** — commit state to git-backed project history

## Persistence

| Module                           | Purpose                                       |
| -------------------------------- | --------------------------------------------- |
| `persistence/bird_io.rs`         | `.bird` text format read/write                |
| `persistence/session.rs`         | Crash-recovery autosave + recent project list |
| `persistence/project_history.rs` | Git-based commit history                      |

## Related Crates

| Crate            | Relationship                                                                                                     |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `songbird-sync`  | Imports entities/slices for command dispatch. Also hosts `generation_state` and `bridge_layer` runtime services. |
| `songbird-files` | Filesystem services (samples, presets, loops, templates). No dependency on state.                                |
| `songbird-types` | Shared low-level types (`TimeStretchMode`, ARA traits). State depends on this.                                   |