Skip to content

armgit / nota

Public Imported from GitHub
0

Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.

(feat) New projects start with instrument, audio, Reverb and Delay tracks

Egor Khindikaynene46d88a9bfa9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ecae9ea0..1644defa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,11 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.
used to stick to whole beats.
### Changed
+- **New projects come ready to play:** a new project — and the workspace Nota opens with —
+ now starts with an instrument track, an audio track and two return tracks: **Reverb**
+ (Nota Reverb) and **Delay** (Nota Delay), both set to Wet Only, so turning up a send
+ adds space or echoes straight away. The new project is unmodified and has nothing to
+ undo; the tracks are ordinary tracks you can edit or delete.
- **Grid controls:** clicking the toolbar's GRID cell (and the new grid chip in the piano
roll's header) opens a menu with every grid option instead of cycling through five
values. The arrangement now draws sub-beat lines when zoomed in. The audio clip editor's
diff --git a/FEATURES.md b/FEATURES.md
index 4547c5dd..9928df21 100644
--- a/FEATURES.md
+++ b/FEATURES.md
@@ -45,6 +45,10 @@ JUCE module; the engine core is JUCE-free.
- **Project**: create / open / save (`.nota`), autosaves, undo/redo for every editing
operation.
+- **New project template**: a new project (and the workspace Nota opens with) starts with an
+ instrument track (Nota Synth), an audio track and two returns — **Reverb** (Nota Reverb)
+ and **Delay** (Nota Delay), both Wet Only — ready to send to; it opens unmodified, with
+ nothing to undo.
- **Version history**: every save records a version inside the project. The browser's
**History** tab draws them as a branching tree (the current one has a brass dot), each
described by what it changed ("Added Bass · Tempo 120.00 → 124.00"); switch
diff --git a/specs/004-default-project-template/checklists/requirements.md b/specs/004-default-project-template/checklists/requirements.md
new file mode 100644
index 00000000..8507eaaf
--- /dev/null
+++ b/specs/004-default-project-template/checklists/requirements.md
@@ -0,0 +1,38 @@
+# Specification Quality Checklist: Default Project Template
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-10-13
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- The Nota Context / Current state section names app areas (engine vs managed) by
+ template design; it is context, not a requirement.
+- Decisions taken as defaults and worth confirming in `/speckit-clarify`: fixed (non-
+ configurable) template, template also on app launch, returns fully wet, returns named
+ "Reverb" / "Delay".
diff --git a/specs/004-default-project-template/contracts/engine-abi.md b/specs/004-default-project-template/contracts/engine-abi.md
new file mode 100644
index 00000000..6515a47a
--- /dev/null
+++ b/specs/004-default-project-template/contracts/engine-abi.md
@@ -0,0 +1,38 @@
+# Contract: clear undo history
+
+## C ABI — `src/native/nota.engine/include/nota/nota_engine.h` (Undo / redo section)
+
+```c
+/* Drop the undo and redo history without touching the session: the current state
+ * becomes the baseline (e.g. a freshly built default project). Open undo groups are
+ * closed. Message thread only. No-op for a null engine. */
+NOTA_API void nota_engine_clear_undo_history(NotaEngine* engine);
+```
+
+- After the call: `nota_engine_can_undo` and `nota_engine_can_redo` return 0;
+ `nota_engine_undo` / `nota_engine_redo` return `NOTA_ERR_UNKNOWN`.
+- The session (tracks, clips, devices, params, transport) is unchanged; no graph is
+ published.
+- The next structural edit is undoable as usual (back to the cleared baseline).
+- Audio thread: not involved. Graphs dropped from the stacks stay alive through the
+ engine's retired list until the audio thread has moved past them.
+
+## Managed — `IAudioEngine` (`src/managed/Nota.Application/Engine/IAudioEngine.cs`)
+
+```csharp
+/// <summary>Forget the undo/redo history; the current state becomes the baseline.</summary>
+void ClearUndoHistory();
+```
+
+Implemented in `NotaEngine` over a `LibraryImport` of `nota_engine_clear_undo_history`.
+
+## Managed — `ProjectTemplate` (`src/managed/Nota.Infrastructure/Persistence/ProjectTemplate.cs`)
+
+```csharp
+/// <summary>Builds the default new-project content on a freshly reset engine and makes it
+/// the undo baseline. Returns the instrument track id (to select/arm).</summary>
+public static int ApplyDefault(IAudioEngine engine);
+```
+
+Precondition: the engine was just reset (no tracks). Postconditions: see
+[data-model.md](../data-model.md).
diff --git a/specs/004-default-project-template/data-model.md b/specs/004-default-project-template/data-model.md
new file mode 100644
index 00000000..3f9a6a27
--- /dev/null
+++ b/specs/004-default-project-template/data-model.md
@@ -0,0 +1,23 @@
+# Data Model: Default Project Template
+
+No new persisted data and no project-file format change: the template is ordinary
+project content, saved and loaded like anything the user creates.
+
+## Default project template (code-defined, not stored)
+
+| Order | Track kind | Name | Devices | Other |
+|-------|-------------|-------------------|---------------------------------|--------------------------------|
+| 1 | Instrument | engine default | Nota Synth (default instrument) | seed empty MIDI clip, beats 0–4 |
+| 2 | Audio | engine default | none | — |
+| A | Return | `Reverb` | Nota Reverb (kind 2), Wet Only = on (param 19) | — |
+| B | Return | `Delay` | Nota Delay (kind 3), Wet Only = on (param 22) | — |
+
+**Invariants after `ProjectTemplate.ApplyDefault` on a freshly reset engine**:
+
+- Exactly 2 non-return tracks and 2 return tracks.
+- All sends from tracks 1–2 to returns A–B at their default (off) level.
+- `CanUndo == false`, `CanRedo == false`.
+- Transport, master and scenes untouched (the caller resets them, as today).
+
+**State transitions**: none — it is a one-shot build applied to an empty engine. Any
+later edit is a normal, undoable edit.
diff --git a/specs/004-default-project-template/plan.md b/specs/004-default-project-template/plan.md
new file mode 100644
index 00000000..843dcd9d
--- /dev/null
+++ b/specs/004-default-project-template/plan.md
@@ -0,0 +1,115 @@
+# Implementation Plan: Default Project Template
+
+**Branch**: `004-default-project-template` | **Date**: 2026-10-13 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `/specs/004-default-project-template/spec.md`
+
+## Summary
+
+Every new project — File → New, the welcome screen's "New project", and the empty
+workspace on launch — starts with an instrument track (Nota Synth + seed clip), an
+audio track, and two returns: "Reverb" (Nota Reverb, Wet Only) and "Delay" (Nota
+Delay, Wet Only). A new `ProjectTemplate.ApplyDefault` builds it from existing engine
+operations on a freshly reset engine, then calls a new C ABI function
+`nota_engine_clear_undo_history` so the template is the undo baseline; the app then
+marks the project clean as it already does. See [research.md](research.md).
+
+## Nota: Read Before Planning
+
+- **Engine work** → [`ARCHITECTURE.md`](../../ARCHITECTURE.md): one new message-thread
+ ABI call; AR-6 and AR-7 apply (see Constitution Check).
+- **Anything** → [`CONTRIBUTING.md`](../../CONTRIBUTING.md): licensing, PR expectations.
+
+## Technical Context
+
+**Language/Version**: C++20 (one engine function + ABI wrapper), C# / .NET 10 (interop,
+template builder, two `MainWindow` call sites)
+
+**Primary Dependencies**: none new
+
+**Storage**: N/A — template content is saved by the existing project format; no format change
+
+**Audio-Thread Impact**: None. `clear_undo_history` runs on the message thread and only
+clears the undo/redo vectors of old authoring graphs; graphs are kept alive by the
+engine's `retired_` list until the audio thread's epoch passes them (same as
+`Engine::reset`). Template building uses the existing structural-edit path (immutable
+snapshot publish, AR-5) and `DeviceSetParam` (atomic params).
+
+**Testing**: `tests/Nota.SmokeTest` via `scripts/build.sh` — new checks for the ABI call
+and for `ProjectTemplate.ApplyDefault` on a real engine (incl. save/load round-trip)
+
+**Target Platform**: macOS, Windows, Linux desktop (unchanged)
+
+**Project Type**: desktop app (native engine + managed UI)
+
+**Performance Goals**: new project feels instant — 4 tracks + 2 devices, well under 100 ms
+
+**Constraints**: no project-format change; no behaviour change for opening/recovering/
+switching versions
+
+**Scale/Scope**: ~1 engine function, 1 ABI function, 1 interop method, 1 new managed
+file (~40 lines), 2 call sites, smoke tests, CHANGELOG/FEATURES/docs
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Note |
+|-----------|--------|------|
+| I. Real-time audio safety | PASS | Message-thread only; no audio-thread alloc/lock/I/O; graphs retired via `retired_` |
+| II. Boundary discipline | PASS | New call is a plain C function in `nota_engine.h`; no JUCE |
+| III. Licensing hygiene | PASS | New `ProjectTemplate.cs` gets the two-line SPDX header; no dependency |
+| IV. Verification gate | PASS (planned) | New ABI surface covered by the smoke test |
+| V. One logical change per PR | PASS | Template + the undo-clear it needs. The pre-existing "Undo after Open removes loaded tracks" gap is **not** fixed here (separate PR) |
+| VI. Docs in sync | PLANNED | CHANGELOG `[Unreleased]` (Changed), FEATURES.md via `nota-features`, user manual via `nota-docs` |
+| VII. Spec-first | PASS | spec → plan → tasks |
+| VIII. Safety rules not weakened | PASS | — |
+
+**Post-design re-check**: unchanged — all PASS.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/004-default-project-template/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/engine-abi.md
+├── checklists/requirements.md
+└── tasks.md # /speckit-tasks
+```
+
+### Source Code (repository root)
+
+```text
+src/
+├── native/nota.engine/
+│ ├── include/nota/nota_engine.h # + nota_engine_clear_undo_history (Undo/redo section)
+│ └── src/
+│ ├── Engine.h / Engine.cpp # + Engine::clearUndoHistory() (reset() reuses it)
+│ └── nota_engine_core.cpp # + C wrapper
+└── managed/
+ ├── Nota.Application/Engine/IAudioEngine.cs # + ClearUndoHistory()
+ ├── Nota.Infrastructure/Interop/NativeMethods.cs # + LibraryImport
+ ├── Nota.Infrastructure/Interop/NotaEngine*.cs # + implementation
+ ├── Nota.Infrastructure/Persistence/ProjectTemplate.cs # NEW: ApplyDefault(engine)
+ └── Nota.App/
+ ├── MainWindow.Files.cs # OnMenuNew: ApplyDefault after Reset, before RefreshAfterLoad
+ └── MainWindow.Recovery.cs # OnOpenedRecoveryCheck: ApplyDefault before MarkProjectClean
+
+tests/Nota.SmokeTest/
+└── ProjectTemplateTests.cs # NEW: ABI clear-undo + template shape + round-trip (wired from Program.cs)
+
+CHANGELOG.md, FEATURES.md # user-visible change
+```
+
+**Structure Decision**: Template logic lives in Infrastructure/Persistence beside
+`ProjectService.Apply` (engine-only, testable from the smoke test); `MainWindow` only
+calls it. The engine gets a policy-free primitive (clear history), not the template.
+
+## Complexity Tracking
+
+No constitution violations.
diff --git a/specs/004-default-project-template/quickstart.md b/specs/004-default-project-template/quickstart.md
new file mode 100644
index 00000000..a39a1780
--- /dev/null
+++ b/specs/004-default-project-template/quickstart.md
@@ -0,0 +1,31 @@
+# Quickstart: validating the default project template
+
+## Automated
+
+```bash
+scripts/build.sh
+```
+
+Must exit green. The smoke test covers, on a real engine:
+
+1. `nota_engine_clear_undo_history` — after a structural edit, clearing leaves
+ `CanUndo`/`CanRedo` false, keeps the session intact, and the next edit is undoable.
+2. `ProjectTemplate.ApplyDefault` on a reset engine — one instrument track (Synth, one
+ MIDI clip), one audio track, two returns named `Reverb` / `Delay` holding exactly
+ Nota Reverb / Nota Delay with Wet Only on; `CanUndo == false`.
+3. Save → load round-trip of the template yields the same tracks, devices and params.
+
+## Manual (in the app; isolate data with `NOTA_DATA_DIR`)
+
+| Step | Expected |
+|------|----------|
+| Launch the app with the welcome screen off | Arrangement shows Instrument, Audio, and returns Reverb, Delay |
+| File → New from a project with content | Same four tracks; nothing from the old project remains |
+| Play the computer keyboard on the instrument track | Synth sounds, dry |
+| Raise the instrument track's send A | Reverb tail added; dry level unchanged |
+| Raise send B | Echoes added |
+| Press Undo on the untouched new project | Nothing happens |
+| Quit right after File → New | No "save changes?" prompt |
+| Delete the audio track, then Undo | Track comes back |
+| Open an existing project | It loads exactly as saved — no extra tracks |
+| Save the new project, reopen it | Same four tracks, Wet Only still on |
diff --git a/specs/004-default-project-template/research.md b/specs/004-default-project-template/research.md
new file mode 100644
index 00000000..08475d30
--- /dev/null
+++ b/specs/004-default-project-template/research.md
@@ -0,0 +1,93 @@
+# Research: Default Project Template
+
+All findings come from reading the current code on `develop` (2026-10-13).
+
+## R1 — Where "a new project" is created today
+
+- **Decision**: Two entry points get the template: `MainWindow.OnMenuNew`
+ (`src/managed/Nota.App/MainWindow.Files.cs`) — reached from File → New, the
+ `file.new` shortcut and the welcome screen's "New project" — and
+ `MainWindow.OnOpenedRecoveryCheck` (`MainWindow.Recovery.cs`), which marks the empty
+ startup workspace clean before the welcome screen / recovery prompt.
+- **Rationale**: These are the only places a project starts empty. Every other path —
+ `OpenProject` (menu, browser, recent, recovery `ApplyPendingRecovery`, version switch
+ in `MainWindow.History.cs`) — goes through `ProjectService.Apply`, which resets the
+ engine and rebuilds from the document, so FR-009 holds without changes there.
+- **Alternatives considered**: Building the template inside `Engine::reset()` — rejected:
+ `reset` is also the first step of every project load, and the engine should not hold
+ app-level content policy.
+
+## R2 — Undo history after building the template (FR-007)
+
+- **Finding**: Every structural edit (`AddInstrumentTrack`, `AddReturnTrack`,
+ `AddBuiltinDevice`, `AddMidiClip`, `SetTrackName`) calls `Engine::publish` →
+ `pushUndo()`. The only way to empty the undo/redo stacks today is
+ `nota_engine_reset`, which also drops all tracks. An undo group would still leave one
+ step that removes the whole template.
+- **Decision**: Add `nota_engine_clear_undo_history(NotaEngine*)` to the C ABI
+ (message thread only): clears `undoStack_` / `redoStack_` and the undo-group state,
+ exactly the tail of `Engine::reset()`. Expose it as `IAudioEngine.ClearUndoHistory()`.
+- **Rationale**: Smallest change that makes "the template is the baseline" true. Safe
+ for the audio thread: the stacks hold old authoring graphs only; the live graph is
+ `authoring_`, and every published graph is also kept alive by `retired_` until the
+ audio thread's epoch passes it (the same reasoning that makes `reset()` safe). No
+ allocation, lock or I/O happens on the audio thread (AR-6).
+- **Alternatives considered**: (a) A managed-side "undo floor" that hides early steps —
+ rejected: the engine would still undo past it via MCP / remote. (b) Building the
+ template as raw publishes with no checkpoints through a dedicated ABI call
+ (`nota_engine_load_default_template`) — rejected: puts content policy in the engine.
+- **Note (out of scope)**: `ProjectService.Apply` has the same property — after opening
+ a project, Undo removes loaded tracks one by one. The new call would fix that too,
+ but that is a separate bug and a separate PR (Principle V).
+
+## R3 — Making the return effects fully wet (FR-004)
+
+- **Finding**: Both built-ins have a `Dry/Wet` param (index 12) and a `Wet Only` switch:
+ Nota Reverb (built-in kind 2) param 19, Nota Delay (kind 3) param 22. `Wet Only`
+ forces mix = 1 and dry gain = 0; the device cards show it as the WET ONLY switch
+ (`ReverbDeviceBody.cs`).
+- **Decision**: After `AddBuiltinDevice`, set `Wet Only` = 1 on each return effect via
+ `DeviceSetParam`. Leave every other param at its default.
+- **Rationale**: Explicit and visible to the user (the switch reads on), survives
+ save/load like any param, and does not depend on the current `Dry/Wet` default.
+- **Alternatives considered**: `Dry/Wet` = 1.0 — works for the wet path but leaves the
+ `Dry Level` stage meaningful only through the mix law; `Wet Only` is the device's own
+ "return use" switch.
+
+## R4 — What the instrument and audio tracks look like
+
+- **Decision**: Build them the way `MainWindow.AddTrack` does: `AddInstrumentTrack()`
+ (Nota Synth) plus the seed 1-bar MIDI clip at beat 0 (`AddMidiClip(t, 0, 4)`), and
+ `AddAudioTrack()`. Engine-assigned names and colours are kept. Returns get
+ `SetTrackName("Reverb")` / `SetTrackName("Delay")` (FR-006).
+- **Rationale**: FR-002 / FR-006 — a template track must be indistinguishable from one
+ added by hand. Order of creation gives top-to-bottom order Instrument, Audio; returns
+ always sit in their own section as A, B.
+- **Alternatives considered**: No seed clip on the template instrument — rejected for
+ consistency with the manual path; the user can delete it like any clip.
+
+## R5 — Where the template code lives
+
+- **Decision**: A small static `ProjectTemplate.ApplyDefault(IAudioEngine engine)` in
+ `src/managed/Nota.Infrastructure/Persistence/` next to `ProjectService.Apply`. It
+ assumes a freshly reset engine, builds the four tracks and two devices, and finishes
+ with `engine.ClearUndoHistory()`. `MainWindow` calls it in both entry points, then
+ `RefreshAfterLoad()` and `MarkProjectClean()` as it already does.
+- **Rationale**: Engine-only logic with no UI dependency, so the smoke test can run it
+ against the real engine. Mirrors where project-shaping code already lives.
+- **Alternatives considered**: Inline in `MainWindow.Files.cs` — rejected: not testable
+ from `tests/Nota.SmokeTest`.
+
+## R6 — Dirty state (FR-007, SC-004)
+
+- **Finding**: Unsaved-changes detection is fingerprint-based (`MarkProjectClean` stores
+ `CurrentFingerprint()`; `HasUnsavedChanges` compares). Both entry points already call
+ `MarkProjectClean()` at the end.
+- **Decision**: Build the template before that call; no other change needed.
+
+## R7 — Effects on other consumers
+
+- MCP (`Nota.Mcp`) and the phone remote (`Nota.Remote`) have no "new project" command;
+ they see the template tracks as ordinary tracks. No change.
+- Smoke test: the engine still starts empty and `reset()` is unchanged, so existing
+ tests are unaffected. New ABI surface → new smoke checks (Principle IV).
diff --git a/specs/004-default-project-template/spec.md b/specs/004-default-project-template/spec.md
new file mode 100644
index 00000000..fdb78367
--- /dev/null
+++ b/specs/004-default-project-template/spec.md
@@ -0,0 +1,198 @@
+# Feature Specification: Default Project Template
+
+**Feature Branch**: `004-default-project-template`
+
+**Created**: 2026-10-13
+
+**Status**: Draft
+
+**Input**: User description: "По умолчанию при создании нового проекта добавлять 1 инструментальную дорожку, 1 аудиодорожку и 2 return-дорожки: в первом return — reverb, во втором — delay."
+
+## Nota Context *(fill in — drives plan and tasks)*
+
+**Feature area** *(pick the main one)*:
+
+- [x] Engine (C++, `src/native/nota.engine`) — real-time audio rules apply, see `ARCHITECTURE.md` AR table
+- [x] Managed app (C#, `src/managed/*`) — domain, application, infrastructure, presentation
+- [ ] UI (Avalonia, `src/managed/Nota.Presentation`) — follow `DESIGN.md` (Ember)
+- [ ] Plugin hosting (`pluginhost/`) — the only place JUCE is allowed
+- [ ] Build / packaging / CI (`scripts/`, `.github/`) — see `BUILD.md`
+- [ ] Docs only
+
+The new project is assembled from operations the app already uses when the user adds
+tracks and devices by hand. The engine gains one small call (see plan): forgetting the
+undo history, so the template becomes the undo baseline.
+
+**Nota docs to keep in mind** *(links relative to `specs/<slug>/`, where this file lands)*:
+[`ARCHITECTURE.md`](../../ARCHITECTURE.md) (AR rules),
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) (licensing, dependency policy, PR
+expectations), [`BUILD.md`](../../BUILD.md), [`DESIGN.md`](../../DESIGN.md),
+[`FEATURES.md`](../../FEATURES.md).
+
+**Current state (for reference)**:
+
+- File → New (and "New project" on the welcome screen) resets the engine and transport
+ and leaves an empty arrangement: no tracks, no returns.
+- On app launch the workspace also starts as an empty, unmodified project, before or
+ without the welcome screen.
+- Adding an instrument track, an audio track or a return track by hand, and putting the
+ built-in Reverb or Delay on a track, are all existing actions.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - New project is ready to play (Priority: P1)
+
+A user picks File → New (or "New project" on the welcome screen). Instead of an empty
+arrangement they get one instrument track, one audio track and two return tracks. They
+can immediately play notes on the instrument track or drop a sample on the audio track
+without creating anything first.
+
+**Why this priority**: It is the core of the request — removing the same four setup
+steps from every new project.
+
+**Independent Test**: Create a new project; count the tracks and their kinds in the
+arrangement and the mixer.
+
+**Acceptance Scenarios**:
+
+1. **Given** any open project, **When** the user creates a new project, **Then** the
+ project contains exactly one instrument track, one audio track and two return tracks,
+ in that order, and nothing else.
+2. **Given** a new project, **When** the user arms the instrument track and plays the
+ computer keyboard or a MIDI keyboard, **Then** they hear the instrument with no
+ further setup.
+3. **Given** a new project, **When** the user drops an audio file on the audio track,
+ **Then** the clip lands on that track as on any audio track.
+
+---
+
+### User Story 2 - Reverb and delay sends are ready (Priority: P1)
+
+The two return tracks come with effects: the first holds a reverb, the second a delay.
+The user turns up a track's send to return A to add space, or to return B to add echoes,
+without building the return chains by hand.
+
+**Why this priority**: Part of the explicit request; returns without effects would not
+deliver the value.
+
+**Independent Test**: Create a new project, open each return's device chain; raise the
+instrument track's send to each return while playing and listen.
+
+**Acceptance Scenarios**:
+
+1. **Given** a new project, **When** the user opens the first return's devices, **Then**
+ it holds exactly one device, the built-in Reverb.
+2. **Given** a new project, **When** the user opens the second return's devices,
+ **Then** it holds exactly one device, the built-in Delay.
+3. **Given** a new project, **When** the user plays the instrument track with every
+ send at its default, **Then** the sound is dry — no reverb or delay is heard until a
+ send is raised.
+4. **Given** a new project, **When** the user raises the instrument track's send to the
+ reverb return, **Then** only the reverberated signal is added on top of the dry
+ track signal (the return effect is fully wet, the dry signal is not doubled).
+
+---
+
+### User Story 3 - The template is the starting point, not a change (Priority: P2)
+
+The prepared tracks are the project's starting state. The project is not marked as
+modified, and undo cannot take the template apart.
+
+**Why this priority**: Without it, closing a just-created project would ask to save,
+and the first Undo would delete a track the user never added.
+
+**Independent Test**: Create a new project, try to close it, then press Undo.
+
+**Acceptance Scenarios**:
+
+1. **Given** a just-created new project, **When** the user quits or opens another
+ project, **Then** no "save changes?" prompt appears.
+2. **Given** a just-created new project, **When** the user presses Undo, **Then**
+ nothing is undone (the history is empty).
+3. **Given** a just-created new project, **When** the user deletes, renames or edits
+ any of the template tracks, **Then** it behaves like any track the user added
+ themselves, and the change is undoable.
+
+---
+
+### Edge Cases
+
+- App launch: the empty startup workspace gets the same template, so launching with the
+ welcome screen switched off also opens a ready project (see Assumptions).
+- Opening an existing project or recovering a crash snapshot never adds template tracks;
+ the project loads exactly as saved.
+- Opening a project and then creating a new one replaces everything with the template —
+ nothing from the previous project leaks in (tracks, sends, devices, MIDI mappings).
+- A new project followed immediately by Save writes the template tracks into the project
+ file like any other tracks; reopening shows the same four tracks and two devices.
+- Creating a new project while playback runs stops/resets transport as today, then
+ builds the template.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Creating a new project (File → New, the welcome screen's "New project",
+ and the equivalent shortcut) MUST produce a project with exactly these tracks, top to
+ bottom: one instrument track, one audio track; and exactly two return tracks.
+- **FR-002**: The instrument track MUST carry the same default instrument a user gets
+ when adding an instrument track by hand, so it is playable at once.
+- **FR-003**: The first return track MUST contain the built-in Reverb as its only
+ device; the second return track MUST contain the built-in Delay as its only device.
+- **FR-004**: Both return effects MUST be set fully wet, so a send adds only the
+ effected signal.
+- **FR-005**: All sends from the instrument and audio tracks to both returns MUST start
+ at their default (silent) level.
+- **FR-006**: Track names, colours and other properties of the template tracks MUST
+ follow the same defaults as tracks added by hand, except that the returns are named
+ after their effect ("Reverb", "Delay").
+- **FR-007**: A freshly created project MUST be unmodified (no save prompt) and have an
+ empty undo history.
+- **FR-008**: The empty workspace shown on app launch MUST start from the same template.
+- **FR-009**: Opening an existing project, recovering a crash snapshot or switching to a
+ saved version MUST NOT add any template tracks.
+- **FR-010**: Template tracks MUST be ordinary tracks: they can be renamed, re-ordered,
+ edited and deleted like any other, and are saved and reloaded like any other.
+
+### Key Entities
+
+- **Default project template**: the fixed starting content of a new project — an
+ instrument track, an audio track, a "Reverb" return with the built-in Reverb and a
+ "Delay" return with the built-in Delay.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: In 100% of new projects the user can hear the instrument track within one
+ action (arm/select and play), with zero tracks or devices to create first.
+- **SC-002**: Adding reverb or delay to a track in a new project takes one action
+ (raising a send) instead of the current four or more (add return, add device, set mix,
+ raise send).
+- **SC-003**: Creating a new project is perceived as instant — no noticeable delay
+ compared with today's empty new project.
+- **SC-004**: 0 "save changes?" prompts and 0 undo steps on an untouched new project.
+
+## Assumptions
+
+- The template is fixed and not configurable in this feature; a user-editable template
+ ("save as default project") or a Preferences switch to get an empty project is out of
+ scope and can follow later.
+- "New project" also covers the empty project on app launch — otherwise users who skip
+ the welcome screen would still start empty, which contradicts the intent.
+- The return effects use their own default settings apart from the wet/dry mix; no
+ special "send" presets are introduced.
+- Return order is A = Reverb, B = Delay, matching the request ("в первом return —
+ reverb, во втором — delay").
+- The MCP tools and the remote control see the template tracks as ordinary tracks; no
+ MCP change is needed beyond what follows from the new starting state.
+
+## Nota Compliance Checklist *(review before implementation; re-check in tasks.md)*
+
+- [ ] Every new source file will carry the AGPL-3.0-only SPDX header (two lines, see CONTRIBUTING.md)
+- [x] No new dependency — or: license checked, AGPL-compatible, `LICENSES/third-party.md` row planned
+- [x] Audio-thread impact considered: no alloc / lock / I/O on the audio thread (AR-6), command queue for data in (AR-4), immutable snapshots for structural edits (AR-5) — reuses existing track/device add operations only
+- [x] Managed/native crossings go through the pure C ABI in `nota_engine.h` only (AR-7); no JUCE outside `pluginhost/`
+- [ ] Smoke-test impact assessed: engine behaviour change → extend `tests/Nota.SmokeTest` (engine unchanged; assess whether the smoke test relies on an empty new project)
+- [ ] User-visible change → `CHANGELOG.md` `[Unreleased]` entry planned (and FEATURES.md / user docs via the nota-features / nota-docs skills)
+- [x] UI change → follows `DESIGN.md` (Ember design language) — no new UI
diff --git a/specs/004-default-project-template/tasks.md b/specs/004-default-project-template/tasks.md
new file mode 100644
index 00000000..c3fc4b4e
--- /dev/null
+++ b/specs/004-default-project-template/tasks.md
@@ -0,0 +1,145 @@
+---
+
+description: "Tasks for the default project template"
+---
+
+# Tasks: Default Project Template
+
+**Input**: Design documents from `/specs/004-default-project-template/`
+
+**Prerequisites**: [plan.md](plan.md), [spec.md](spec.md), [research.md](research.md), [data-model.md](data-model.md), [contracts/engine-abi.md](contracts/engine-abi.md)
+
+**Tests**: The spec does not ask for TDD, but Constitution IV requires smoke-test coverage
+for new C ABI surface, and the template is cheap to check on a real engine — so smoke
+checks are included (in `tests/Nota.SmokeTest`, the PR gate).
+
+**Organization**: Tasks are grouped by user story. US1 and US2 share one builder
+(`ProjectTemplate.ApplyDefault`); US2 adds the return effects to it, US3 makes it the
+undo/dirty baseline.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (US1, US2, US3)
+
+---
+
+## Phase 1: Setup
+
+No setup: no new project, dependency or tool. Skipped.
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: The template builder skeleton and its two call sites, so every story lands
+in the real app.
+
+- [X] T001 Create `src/managed/Nota.Infrastructure/Persistence/ProjectTemplate.cs`: two-line AGPL-3.0-only SPDX header plus a comment header explaining why the file exists (the default new-project content, specs/004-default-project-template); `namespace Nota.Infrastructure.Persistence`; `public static class ProjectTemplate` with `public static int ApplyDefault(IAudioEngine engine)` documented as "Builds the default new-project content on a freshly reset engine and makes it the undo baseline. Returns the instrument track id." — body empty for now, returns -1. Match the style of `ProjectService.cs` in the same folder
+- [X] T002 In `src/managed/Nota.App/MainWindow.Files.cs` `OnMenuNew`: call `ProjectTemplate.ApplyDefault(Engine)` right after `Engine.Reset()` and the transport resets, before `RefreshAfterLoad()` (which already precedes `MarkProjectClean()`)
+- [X] T003 In `src/managed/Nota.App/MainWindow.Recovery.cs` `OnOpenedRecoveryCheck`: before `MarkProjectClean()` (the "fresh startup project" line), call `ProjectTemplate.ApplyDefault(Engine)` then `RefreshAfterLoad()`, so the launch workspace starts from the template (FR-008). Do not touch `ApplyPendingRecovery` / `OpenProject` (FR-009: those load through `ProjectService.Apply`, which resets first)
+
+**Checkpoint**: New project and launch both run the (still empty) builder.
+
+---
+
+## Phase 3: User Story 1 - New project is ready to play (Priority: P1) 🎯 MVP
+
+**Goal**: A new project has one instrument track and one audio track, built exactly like
+tracks added by hand.
+
+**Independent Test**: File → New; arrangement shows an instrument track (Nota Synth, an
+empty 1-bar clip) above an audio track; playing the keyboard on the instrument sounds.
+
+- [X] T004 [US1] In `ProjectTemplate.ApplyDefault` (`src/managed/Nota.Infrastructure/Persistence/ProjectTemplate.cs`): `int inst = engine.AddInstrumentTrack();` then `engine.AddMidiClip(inst, 0.0, 4.0);` (same seed clip as `MainWindow.AddTrack`), then `engine.AddAudioTrack();`. Keep engine-assigned names and colours (FR-002, FR-006). Return `inst`
+- [X] T005 [P] [US1] Create `tests/Nota.SmokeTest/ProjectTemplateTests.cs` (SPDX header, comment header naming specs/004-default-project-template, `internal static class ProjectTemplateTests` with `public static IEnumerable<(bool ok, string label)> Run()` in the style of `SnapGridTests.cs`): on `using var eng = new NotaEngine()` call `ProjectTemplate.ApplyDefault(eng)`; check exactly two non-return tracks in order instrument then audio (`TryGetTrackInfo(0/1, …)`), the instrument kind is Synth (`TrackInstrumentKind == 0`) with one MIDI clip at beat 0 length 4, the audio track has no clips, and the returned id is the instrument track
+- [X] T006 [US1] Wire the tests into `tests/Nota.SmokeTest/Program.cs`: `foreach (var (ok, label) in ProjectTemplateTests.Run()) Check(ok, label);` in the full run next to the `SnapGridTests.Run()` / `HistoryTests` calls, plus a `--template` standalone switch mirroring the `--grid` block
+
+**Checkpoint**: US1 works in the app (new project shows two playable tracks) and in the smoke test.
+
+---
+
+## Phase 4: User Story 2 - Reverb and delay sends are ready (Priority: P1)
+
+**Goal**: Two returns, "Reverb" with Nota Reverb and "Delay" with Nota Delay, both fully
+wet; sends start silent.
+
+**Independent Test**: New project → return A holds only Nota Reverb with WET ONLY on,
+return B only Nota Delay with WET ONLY on; raising a send adds only the effect.
+
+- [X] T007 [US2] In `ProjectTemplate.ApplyDefault`, after the audio track: `int rv = engine.AddReturnTrack(); engine.SetTrackName(rv, "Reverb"); int rd = engine.AddBuiltinDevice(rv, 2);` (built-in kind 2 = Reverb) and `engine.DeviceSetParam(rv, rd, 19, 1f);` (Reverb param 19 = "Wet Only"); then `int dl = engine.AddReturnTrack(); engine.SetTrackName(dl, "Delay"); int dd = engine.AddBuiltinDevice(dl, 3);` (kind 3 = Delay) and `engine.DeviceSetParam(dl, dd, 22, 1f);` (Delay param 22 = "Wet Only"). Use named constants with a short comment rather than bare numbers. Do not set sends (FR-005: they stay at their default)
+- [X] T008 [US2] Extend `ProjectTemplateTests.Run()` in `tests/Nota.SmokeTest/ProjectTemplateTests.cs`: exactly two return tracks, return indices 0 and 1, named "Reverb" and "Delay"; each has `TrackDeviceCount == 1` with `TrackDeviceBuiltinKind` 2 / 3; `DeviceParamName(…,19)` == "Wet Only" and `DeviceGetParam(…,19)` is 1 on the reverb, likewise param 22 on the delay; `GetTrackSend(track, 0/1)` for both tracks reads the default off level (compare with a send on a track added to a fresh engine)
+- [X] T009 [US2] Extend `ProjectTemplateTests.Run()`: save/load round trip — `ProjectService.Capture(eng, new TransportState(120, 1, false, false), warnings)`, `ProjectService.Save(doc, tempDir, eng)`, `ProjectService.Load(tempDir)`, `ProjectService.Apply(loaded, eng2, tempDir)` on a second `NotaEngine`; check the same four tracks, names, device kinds and Wet Only values; delete the temp dir in `finally` (pattern: `Program.cs` M7-6c round trip)
+
+**Checkpoint**: US1 + US2 — the full template content is built and survives save/load.
+
+---
+
+## Phase 5: User Story 3 - The template is the starting point, not a change (Priority: P2)
+
+**Goal**: No undo steps and no "save changes?" prompt on an untouched new project.
+
+**Independent Test**: File → New, press Undo → nothing happens; quit → no prompt; delete
+a template track, Undo → it returns.
+
+- [X] T010 [US3] Engine: add `void clearUndoHistory();` to `Engine` in `src/native/nota.engine/src/Engine.h` next to `canUndo()` and implement it in `src/native/nota.engine/src/Engine.cpp` as `undoStack_.clear(); redoStack_.clear(); undoGroupDepth_ = 0; undoGroupBase_ = 0;` with a comment that the stacks hold only old authoring graphs, which `retired_` keeps alive for the audio thread (message thread only). Make `Engine::reset()` call it instead of repeating those lines
+- [X] T011 [US3] C ABI: declare `NOTA_API void nota_engine_clear_undo_history(NotaEngine* engine);` in `src/native/nota.engine/include/nota/nota_engine.h` in the "Undo / redo (M6-6)" section with the doc comment from `contracts/engine-abi.md`; implement in `src/native/nota.engine/src/nota_engine_core.cpp` beside `nota_engine_undo_group_end`: `void nota_engine_clear_undo_history(NotaEngine* e) { if (e) ENG(e)->clearUndoHistory(); }`
+- [X] T012 [US3] Managed interop: add `[LibraryImport(Lib, EntryPoint = "nota_engine_clear_undo_history")]` `ClearUndoHistory(IntPtr)` in `src/managed/Nota.Infrastructure/Interop/NativeMethods.cs` next to `nota_engine_can_undo`; add `void ClearUndoHistory();` with summary "Forget the undo/redo history; the current state becomes the baseline." to the "Undo / redo (M6-6)" block of `src/managed/Nota.Application/Engine/IAudioEngine.cs`; implement in `src/managed/Nota.Infrastructure/Interop/NotaEngine.cs` beside `Reset()`: `public void ClearUndoHistory() { ThrowIfDisposed(); NativeMethods.ClearUndoHistory(_handle); }`
+- [X] T013 [US3] End `ProjectTemplate.ApplyDefault` with `engine.ClearUndoHistory();` (FR-007) in `src/managed/Nota.Infrastructure/Persistence/ProjectTemplate.cs`
+- [X] T014 [US3] Extend `tests/Nota.SmokeTest/ProjectTemplateTests.cs` with ABI checks: on a fresh engine add a track (CanUndo true), `ClearUndoHistory()` → `CanUndo` and `CanRedo` false, `Undo()` returns false, the track is still there; a following edit (add an audio track) makes `CanUndo` true and `Undo()` removes only that track. And after `ApplyDefault`: `CanUndo == false`, `CanRedo == false`; deleting the audio track then `Undo()` restores it (FR-010)
+- [X] T015 [US3] Verify the dirty-state path needs no change: `MarkProjectClean()` runs after the template in both `OnMenuNew` (`MainWindow.Files.cs`) and `OnOpenedRecoveryCheck` (`MainWindow.Recovery.cs`); if either call precedes the template, move it after
+
+**Checkpoint**: All stories done — template content, undo baseline, clean state.
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+- [X] T016 Run the manual checks in [quickstart.md](quickstart.md) in the real app with an isolated `NOTA_DATA_DIR` (welcome screen off and on, File → New over a project with content, sends A/B audible, Undo no-op, no save prompt, Open existing project unchanged)
+ - 2026-10-13: checked headlessly through the real MainWindow (harness /tmp/templateharness). With the welcome screen off, the launch workspace and File → New over a modified project both show Synth, Audio, Reverb and Delay, report nothing to undo and count as unmodified. Not checked: hearing the sends by ear, and the GUI quit prompt (it relies on the same unmodified check).
+
+### Nota closing tasks *(PR gates)*
+
+- [X] T017 Run `scripts/build.sh` until native + managed + smoke test are green
+ - 2026-10-13: native + managed build green; all 25 template checks pass (also `--template` alone). The full run reports 2 failures, both in `FilterGlideTests` (EQ-8 / Dynamic EQ-8 high cut). They come from separate uncommitted work in `Eq.h` / `DynamicEq.h`, not from this feature. Re-run once that work is settled.
+ - 2026-10-13 (re-run): `scripts/build.sh` exit 0, SMOKE TEST PASSED, 0 failures; 25/25 template checks pass.
+- [X] T018 AGPL-3.0-only SPDX two-line header on `ProjectTemplate.cs` and `ProjectTemplateTests.cs`
+- [X] T019 New dependency: N/A (none)
+- [X] T020 `CHANGELOG.md` `[Unreleased]` → Changed: "New projects start with an instrument track, an audio track and two returns — Reverb and Delay — ready to send to"
+- [X] T021 FEATURES.md via the `nota-features` skill; user manual (new project / returns pages, EN + RU) via `nota-docs`; shortcuts: N/A (no binding changes)
+- [X] T022 Engine behaviour change → smoke test covers `nota_engine_clear_undo_history` (T014)
+
+---
+
+## Dependencies & Execution Order
+
+- **Phase 2 (T001–T003)** blocks every story. T002 and T003 depend on T001.
+- **US1 (T004–T006)**: T004 after T001; T005 can be written in parallel with T004; T006 after T005.
+- **US2 (T007–T009)**: T007 after T004 (same method, appends after the audio track); T008/T009 extend the file from T005.
+- **US3 (T010–T015)**: T010 → T011 → T012 → T013 → T014 (each builds on the previous layer). T010–T012 do not depend on US1/US2 and can start right after Phase 2.
+- **Polish (T016–T022)** after all stories.
+
+### Parallel Opportunities
+
+- T005 (test file) alongside T004 (builder).
+- The US3 engine/ABI/interop chain (T010–T012) alongside US1/US2 builder work — different files.
+- T020 and T021 (docs) alongside T016.
+
+## Parallel Example: User Story 1
+
+```bash
+Task: "T004 Build instrument + audio tracks in ProjectTemplate.ApplyDefault"
+Task: "T005 Create ProjectTemplateTests.cs with the US1 checks"
+```
+
+## Implementation Strategy
+
+### MVP (US1)
+
+Phase 2 → US1 → build → File → New shows two playable tracks. Undo would still remove
+them (US3) — acceptable for an internal checkpoint, not for the PR.
+
+### Full delivery
+
+US1 → US2 (returns + effects) → US3 (undo baseline) → Polish. Ship as one PR: the
+feature is only correct with all three stories.
diff --git a/src/managed/Nota.App/MainWindow.Files.cs b/src/managed/Nota.App/MainWindow.Files.cs
index 3aedfaf0..b5905ceb 100644
--- a/src/managed/Nota.App/MainWindow.Files.cs
+++ b/src/managed/Nota.App/MainWindow.Files.cs
@@ -183,6 +183,7 @@ public partial class MainWindow
_projectPath = null;
_learn?.Clear(); // start with a clean MIDI-map for the new project
Timeline.ClearSections(); // …and a clean song structure
+ Nota.Infrastructure.ProjectTemplate.ApplyDefault(Engine); // instrument, audio, Reverb + Delay returns
RefreshAfterLoad();
UpdateWindowTitle();
MarkProjectClean();
diff --git a/src/managed/Nota.App/MainWindow.Recovery.cs b/src/managed/Nota.App/MainWindow.Recovery.cs
index 398aa573..d66761dc 100644
--- a/src/managed/Nota.App/MainWindow.Recovery.cs
+++ b/src/managed/Nota.App/MainWindow.Recovery.cs
@@ -93,6 +93,9 @@ public partial class MainWindow
private async void OnOpenedRecoveryCheck(object? sender, EventArgs e)
{
if (_vm is null) return;
+ // The launch workspace starts from the same template as File → New.
+ Nota.Infrastructure.ProjectTemplate.ApplyDefault(Engine);
+ RefreshAfterLoad();
MarkProjectClean(); // the fresh startup project counts as unmodified
// What's New shows once per new app version, ahead of the launcher.
diff --git a/src/managed/Nota.Application/Engine/IAudioEngine.cs b/src/managed/Nota.Application/Engine/IAudioEngine.cs
index 993cd87f..f87748e3 100644
--- a/src/managed/Nota.Application/Engine/IAudioEngine.cs
+++ b/src/managed/Nota.Application/Engine/IAudioEngine.cs
@@ -821,6 +821,8 @@ public interface IAudioEngine : IDisposable
/// <see cref="EndUndoGroup"/> undo as one step. Nests.</summary>
void BeginUndoGroup();
void EndUndoGroup();
+ /// <summary>Forget the undo/redo history; the current state becomes the baseline.</summary>
+ void ClearUndoHistory();
// --- Project load (M7-6) -----------------------------------------------
void Reset();
diff --git a/src/managed/Nota.Infrastructure/Interop/NativeMethods.cs b/src/managed/Nota.Infrastructure/Interop/NativeMethods.cs
index 444b2fa5..4560b57f 100644
--- a/src/managed/Nota.Infrastructure/Interop/NativeMethods.cs
+++ b/src/managed/Nota.Infrastructure/Interop/NativeMethods.cs
@@ -174,6 +174,9 @@ internal static partial class NativeMethods
[LibraryImport(Lib, EntryPoint = "nota_engine_undo_group_end")]
internal static partial void UndoGroupEnd(IntPtr engine);
+ [LibraryImport(Lib, EntryPoint = "nota_engine_clear_undo_history")]
+ internal static partial void ClearUndoHistory(IntPtr engine);
+
[LibraryImport(Lib, EntryPoint = "nota_engine_reset")]
internal static partial void Reset(IntPtr engine);
diff --git a/src/managed/Nota.Infrastructure/Interop/NotaEngine.cs b/src/managed/Nota.Infrastructure/Interop/NotaEngine.cs
index 0b6eeb80..d49699b2 100644
--- a/src/managed/Nota.Infrastructure/Interop/NotaEngine.cs
+++ b/src/managed/Nota.Infrastructure/Interop/NotaEngine.cs
@@ -146,6 +146,7 @@ public sealed partial class NotaEngine : IAudioEngine
public bool CanRedo { get { ThrowIfDisposed(); return NativeMethods.CanRedo(_handle) != 0; } }
public void BeginUndoGroup() { ThrowIfDisposed(); NativeMethods.UndoGroupBegin(_handle); }
public void EndUndoGroup() { ThrowIfDisposed(); NativeMethods.UndoGroupEnd(_handle); }
+ public void ClearUndoHistory() { ThrowIfDisposed(); NativeMethods.ClearUndoHistory(_handle); }
// --- Project load (M7-6) -----------------------------------------------
diff --git a/src/managed/Nota.Infrastructure/Persistence/ProjectTemplate.cs b/src/managed/Nota.Infrastructure/Persistence/ProjectTemplate.cs
new file mode 100644
index 00000000..0cb4e4da
--- /dev/null
+++ b/src/managed/Nota.Infrastructure/Persistence/ProjectTemplate.cs
@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// The default new-project content (specs/004-default-project-template): File → New and
+// the launch workspace start with an instrument track, an audio track and two returns —
+// "Reverb" and "Delay" — so a user can play and send at once. Built from the same
+// structural edits as adding tracks by hand, then made the undo baseline so the
+// template is the starting point rather than a stack of undoable edits.
+
+namespace Nota.Infrastructure;
+
+public static class ProjectTemplate
+{
+ // Built-in device kinds and their "Wet Only" switch (Reverb.h / Delay.h param order).
+ private const int ReverbKind = 2, ReverbWetOnly = 19;
+ private const int DelayKind = 3, DelayWetOnly = 22;
+
+ /// <summary>Builds the default new-project content on a freshly reset engine and makes it
+ /// the undo baseline. Returns the instrument track id.</summary>
+ public static int ApplyDefault(IAudioEngine engine)
+ {
+ // Same as the toolbar's Add Instrument: Nota Synth with a seed one-bar clip.
+ int inst = engine.AddInstrumentTrack();
+ engine.AddMidiClip(inst, 0.0, 4.0);
+ engine.AddAudioTrack();
+
+ // Returns are fully wet: a send adds only the effect, the dry signal isn't doubled.
+ AddReturn(engine, "Reverb", ReverbKind, ReverbWetOnly);
+ AddReturn(engine, "Delay", DelayKind, DelayWetOnly);
+
+ engine.ClearUndoHistory();
+ return inst;
+ }
+
+ private static void AddReturn(IAudioEngine engine, string name, int kind, int wetOnlyParam)
+ {
+ int track = engine.AddReturnTrack();
+ if (track <= 0) return;
+ engine.SetTrackName(track, name);
+ int dev = engine.AddBuiltinDevice(track, kind);
+ if (dev >= 0) engine.DeviceSetParam(track, dev, wetOnlyParam, 1f);
+ }
+}
diff --git a/src/native/nota.engine/include/nota/nota_engine.h b/src/native/nota.engine/include/nota/nota_engine.h
index 725cf4dc..cfc539b6 100644
--- a/src/native/nota.engine/include/nota/nota_engine.h
+++ b/src/native/nota.engine/include/nota/nota_engine.h
@@ -796,6 +796,10 @@ NOTA_API int32_t nota_engine_can_redo(const NotaEngine* engine);
* device in place = add + move + remove). Nests; pair every begin with an end. */
NOTA_API void nota_engine_undo_group_begin(NotaEngine* engine);
NOTA_API void nota_engine_undo_group_end(NotaEngine* engine);
+/* Drop the undo and redo history without touching the session: the current state
+ * becomes the baseline (e.g. a freshly built default project). Open undo groups are
+ * closed. Message thread only. No-op for a null engine. */
+NOTA_API void nota_engine_clear_undo_history(NotaEngine* engine);
/* ---- Project load (M7-6) ------------------------------------------------- */
/* Clear the session to an empty project: stop transport, drop all tracks,
diff --git a/src/native/nota.engine/src/Engine.cpp b/src/native/nota.engine/src/Engine.cpp
index e8ab1caa..8375d3ee 100644
--- a/src/native/nota.engine/src/Engine.cpp
+++ b/src/native/nota.engine/src/Engine.cpp
@@ -571,6 +571,13 @@ void Engine::reset() {
empty->masterTrack = std::make_shared<Track>(kMasterTrackId, TrackType::Audio);
publishRaw(std::move(empty));
nextTrackId_ = 1;
+ clearUndoHistory();
+}
+
+void Engine::clearUndoHistory() {
+ // The stacks hold old authoring graphs only — never the live one — and every published
+ // graph also sits in retired_ until the audio thread has moved past it, so dropping
+ // them here frees nothing the audio thread can still be reading.
undoStack_.clear();
redoStack_.clear();
undoGroupDepth_ = 0; undoGroupBase_ = 0;
diff --git a/src/native/nota.engine/src/Engine.h b/src/native/nota.engine/src/Engine.h
index 4141240c..5542d1df 100644
--- a/src/native/nota.engine/src/Engine.h
+++ b/src/native/nota.engine/src/Engine.h
@@ -999,6 +999,9 @@ public:
// without a begin is ignored.
void beginUndoGroup();
void endUndoGroup();
+ // Forget the undo/redo history: the current state becomes the baseline (a freshly
+ // built default project). Message thread only.
+ void clearUndoHistory();
// --- offline render (tests / export) ---
void renderOffline(float* out, int32_t frames);
diff --git a/src/native/nota.engine/src/nota_engine_core.cpp b/src/native/nota.engine/src/nota_engine_core.cpp
index 39b7adbf..8c3b369c 100644
--- a/src/native/nota.engine/src/nota_engine_core.cpp
+++ b/src/native/nota.engine/src/nota_engine_core.cpp
@@ -242,6 +242,7 @@ int32_t nota_engine_can_redo(const NotaEngine* e) {
}
void nota_engine_undo_group_begin(NotaEngine* e) { if (e) ENG(e)->beginUndoGroup(); }
void nota_engine_undo_group_end(NotaEngine* e) { if (e) ENG(e)->endUndoGroup(); }
+void nota_engine_clear_undo_history(NotaEngine* e) { if (e) ENG(e)->clearUndoHistory(); }
// ---- Project reset (M7-6) -------------------------------------------------
diff --git a/tests/Nota.SmokeTest/Program.cs b/tests/Nota.SmokeTest/Program.cs
index 04c7f428..5a6d5c05 100644
--- a/tests/Nota.SmokeTest/Program.cs
+++ b/tests/Nota.SmokeTest/Program.cs
@@ -231,6 +231,14 @@ if (args.Length >= 1 && args[0] == "--grid")
Console.WriteLine(failures == 0 ? "GRID PASSED" : $"GRID FAILED ({failures})");
return failures == 0 ? 0 : 1;
}
+// Default project template alone: `--template`. Also part of the full run.
+if (args.Length >= 1 && args[0] == "--template")
+{
+ Console.WriteLine("-- default project template --");
+ foreach (var (ok, label) in ProjectTemplateTests.Run()) Check(ok, label);
+ Console.WriteLine(failures == 0 ? "TEMPLATE PASSED" : $"TEMPLATE FAILED ({failures})");
+ return failures == 0 ? 0 : 1;
+}
// What Nota Mosaic makes of a real library: `--mosaic-dump <file.sfz | folder>`.
if (args.Length >= 2 && args[0] == "--mosaic-dump")
{
@@ -14532,6 +14540,9 @@ foreach (var (ok, label) in TapTempoTests.Run()) Check(ok, label);
Console.WriteLine("-- snap grid --");
foreach (var (ok, label) in SnapGridTests.Run()) Check(ok, label);
+Console.WriteLine("-- default project template --");
+foreach (var (ok, label) in ProjectTemplateTests.Run()) Check(ok, label);
+
Console.WriteLine("-- filter knob glide --");
foreach (var (ok, label) in FilterGlideTests.Run()) Check(ok, label);
diff --git a/tests/Nota.SmokeTest/ProjectTemplateTests.cs b/tests/Nota.SmokeTest/ProjectTemplateTests.cs
new file mode 100644
index 00000000..01eb70a9
--- /dev/null
+++ b/tests/Nota.SmokeTest/ProjectTemplateTests.cs
@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// Default project template (specs/004-default-project-template): the new-project content
+// (instrument + audio track, "Reverb" and "Delay" returns, both wet only), the
+// nota_engine_clear_undo_history baseline it relies on, and a save/load round trip.
+// Also runnable alone: `dotnet run --project tests/Nota.SmokeTest -- --template`.
+
+using Nota.Application;
+using Nota.Infrastructure;
+
+namespace Nota.SmokeTest;
+
+internal static class ProjectTemplateTests
+{
+ private const int ReverbWetOnly = 19, DelayWetOnly = 22;
+
+ public static IEnumerable<(bool ok, string label)> Run()
+ {
+ foreach (var r in ClearUndo()) yield return r;
+ foreach (var r in Template()) yield return r;
+ foreach (var r in RoundTrip()) yield return r;
+ }
+
+ // The ABI primitive: history goes, the session stays, later edits undo as usual.
+ private static IEnumerable<(bool, string)> ClearUndo()
+ {
+ using var eng = new NotaEngine();
+ int a = eng.AddAudioTrack();
+ yield return (eng.CanUndo, "clear-undo: an edit is undoable before clearing");
+ eng.ClearUndoHistory();
+ yield return (!eng.CanUndo && !eng.CanRedo, "clear-undo: no undo/redo after clearing");
+ yield return (!eng.Undo(), "clear-undo: Undo reports nothing to undo");
+ yield return (eng.TrackCount == 1 && eng.TryGetTrackInfo(0, out var t) && t.Id == a,
+ "clear-undo: the session is untouched");
+ eng.AddAudioTrack();
+ yield return (eng.CanUndo, "clear-undo: the next edit is undoable");
+ yield return (eng.Undo() && eng.TrackCount == 1 && !eng.CanUndo,
+ "clear-undo: Undo goes back to the cleared baseline, no further");
+ }
+
+ // Tracks in order, as plain tracks first, then the return section.
+ private static (List<NotaTrackInfo> tracks, List<NotaTrackInfo> returns) Split(IAudioEngine eng)
+ {
+ var tracks = new List<NotaTrackInfo>();
+ var returns = new List<NotaTrackInfo>();
+ for (int i = 0; i < eng.TrackCount; i++)
+ if (eng.TryGetTrackInfo(i, out var t)) (t.IsReturn ? returns : tracks).Add(t);
+ return (tracks, returns);
+ }
+
+ private static bool ReturnHolds(IAudioEngine eng, NotaTrackInfo r, string name, int kind, int wetOnly)
+ => eng.GetTrackName(r.Id) == name
+ && eng.TrackDeviceCount(r.Id) == 1
+ && eng.TrackDeviceBuiltinKind(r.Id, 0) == kind
+ && eng.DeviceParamName(r.Id, 0, wetOnly) == "Wet Only"
+ && eng.DeviceGetParam(r.Id, 0, wetOnly) >= 0.5f;
+
+ // Checks shared by the fresh template and its reloaded copy.
+ private static IEnumerable<(bool, string)> Shape(IAudioEngine eng, string tag)
+ {
+ var (tracks, returns) = Split(eng);
+ yield return (tracks.Count == 2 && returns.Count == 2,
+ $"{tag}: 2 tracks + 2 returns (got {tracks.Count} + {returns.Count})");
+ if (tracks.Count != 2 || returns.Count != 2) yield break;
+ var inst = tracks[0];
+ var audio = tracks[1];
+ yield return (inst.IsInstrument && eng.TrackInstrumentKind(inst.Id) == 0, $"{tag}: track 1 is an instrument with Nota Synth");
+ yield return (inst.ClipCount == 1 && eng.TryGetClipInfo(inst.Id, 0, out var c)
+ && c.IsMidi && c.StartBeat == 0.0 && c.LengthBeats == 4.0,
+ $"{tag}: the instrument has the seed 1-bar MIDI clip");
+ yield return (audio.Type == 0 && audio.ClipCount == 0, $"{tag}: track 2 is an empty audio track");
+ yield return (eng.TrackReturnIndex(returns[0].Id) == 0 && eng.TrackReturnIndex(returns[1].Id) == 1,
+ $"{tag}: returns are buses A and B");
+ yield return (ReturnHolds(eng, returns[0], "Reverb", 2, ReverbWetOnly), $"{tag}: return A = \"Reverb\" with Nota Reverb, Wet Only on");
+ yield return (ReturnHolds(eng, returns[1], "Delay", 3, DelayWetOnly), $"{tag}: return B = \"Delay\" with Nota Delay, Wet Only on");
+ }
+
+ private static IEnumerable<(bool, string)> Template()
+ {
+ using var eng = new NotaEngine();
+ int inst = ProjectTemplate.ApplyDefault(eng);
+ foreach (var r in Shape(eng, "template")) yield return r;
+ var (tracks, _) = Split(eng);
+ yield return (tracks.Count > 0 && tracks[0].Id == inst, "template: returns the instrument track id");
+
+ // Sends start where a hand-added track's sends start (off).
+ using var refEng = new NotaEngine();
+ int refTrack = refEng.AddAudioTrack();
+ refEng.AddReturnTrack();
+ float off = refEng.GetTrackSend(refTrack, 0);
+ bool sendsOff = tracks.All(t => eng.GetTrackSend(t.Id, 0) == off && eng.GetTrackSend(t.Id, 1) == off);
+ yield return (sendsOff, $"template: every send starts at the default level ({off})");
+
+ yield return (!eng.CanUndo && !eng.CanRedo, "template: the undo history is empty");
+ if (tracks.Count == 2)
+ {
+ int audio = tracks[1].Id;
+ eng.RemoveTrack(audio);
+ yield return (eng.Undo() && Split(eng).tracks.Any(t => t.Id == audio) && !eng.CanUndo,
+ "template: deleting a template track undoes back to the template");
+ }
+ }
+
+ private static IEnumerable<(bool, string)> RoundTrip()
+ {
+ string dir = Path.Combine(Path.GetTempPath(), "nota-template-" + Guid.NewGuid().ToString("N"));
+ try
+ {
+ using var eng = new NotaEngine();
+ ProjectTemplate.ApplyDefault(eng);
+ var warnings = new List<string>();
+ var doc = ProjectService.Capture(eng, new TransportState(120, 1, false, false), warnings);
+ ProjectService.Save(doc, dir, eng);
+ using var eng2 = new NotaEngine();
+ var applied = ProjectService.Apply(ProjectService.Load(dir), eng2, dir);
+ yield return (warnings.Count == 0 && applied.Count == 0, "round-trip: saved and reloaded without warnings");
+ foreach (var r in Shape(eng2, "round-trip")) yield return r;
+ }
+ finally
+ {
+ try { if (Directory.Exists(dir)) Directory.Delete(dir, recursive: true); } catch (IOException) { }
+ }
+ }
+}