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) Aurora: both oscillators on one card (#379)

Chris Laupama4508a93de032
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 24c2f7c3..8ff19e40 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -363,6 +363,15 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.
the response to drag over Freq, Res, Drive and Dry/wet knobs. The size is a new View
parameter appended to the device, so it saves with the project; presets, A/B and the
automation menu leave it alone, and old projects open in L.
+- **Nota Aurora: both oscillators on one Osc tab** (specs/053): the 1 / 2 switch is gone.
+ Osc 1 and Osc 2 sit side by side, each with its own table window (naming what modulates its
+ position, or "no modulation"), table and warp-mode drop-downs, on / off switch and its
+ Position, Warp, Level, Oct, Semi and Fine knobs, so both tables are on screen together. An
+ oscillator that is off greys out in place. The sub and unison stay in one row under both.
+ The Global rail keeps voices, bend, Volume and Pan: its Pos 1, Cutoff and Unison sliders
+ were second copies of the Osc and Filter tab controls and go (one home per control). The
+ table windows keep their drawing between paints, so two of them cost no more than the one
+ before. Sound, parameters, automation, MIDI learn and presets are unchanged.
- **Nota Volt: envelope knobs and a cleaner Global rail** (nota-daw/nota#531): each envelope
stage box on the Env tab carries a gauge knob (as on Nota Aurora), with its value centred
under it and the A / D / S / R letter in the box's corner. The box still drags and types
diff --git a/DESIGN.md b/DESIGN.md
index 0c574b38..3cb7425b 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -1255,6 +1255,13 @@ What the guide changes inside a card:
- Use thin sliders, monospace readouts or capital-letter labels.
- Fade anything out; draw it in ink 4 with nothing picked.
+**Layout changes decided since** (each its own decision, as above):
+
+- **Aurora's Osc tab** (specs/053): the two oscillators sit side by side in the same
+ 700 × 260 card, each column with its name and switch, its table and warp-mode drop-downs,
+ its table window and six 34 px knobs; the sub and unison row runs under both. There is no
+ 1 / 2 pick any more. An oscillator that is off takes the unavailable look in place.
+
### The card shell
- **Every card uses one shell**: effects, instruments, MIDI effects, racks (the
diff --git a/specs/053-aurora-one-card/checklists/requirements.md b/specs/053-aurora-one-card/checklists/requirements.md
new file mode 100644
index 00000000..f0e8c035
--- /dev/null
+++ b/specs/053-aurora-one-card/checklists/requirements.md
@@ -0,0 +1,44 @@
+# Specification Quality Checklist: Aurora, both wavetables on one card, and custom wavetables from samples
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-10-29
+**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
+
+- Three [NEEDS CLARIFICATION] markers remain on purpose, each a choice that changes scope:
+ 1. US2 acceptance 5: how a longer recording is cut into frames (even zero-crossing windows,
+ pitch-detected periods, or not supported).
+ 2. US4: whether the windows follow the modulated position live in this feature.
+ 3. FR-005: whether the card stays 700 wide or moves to the Wide 1050 size.
+ Resolve them with `/speckit-clarify` before `/speckit-plan`.
+- The "Nota Context" section cites code (file:line) by design of the Nota template; the
+ requirements and success criteria themselves stay free of implementation. SC-003 names the
+ per-thread CPU method only through Assumptions, and SC-006 names the 036 benchmark scenario
+ as the yardstick, as 036 did.
+- Items marked incomplete require spec updates before `/speckit-clarify` or `/speckit-plan`
diff --git a/specs/053-aurora-one-card/contracts/c-abi.md b/specs/053-aurora-one-card/contracts/c-abi.md
new file mode 100644
index 00000000..c4e188cc
--- /dev/null
+++ b/specs/053-aurora-one-card/contracts/c-abi.md
@@ -0,0 +1,114 @@
+# Contract: C ABI additions (`include/nota/nota_engine.h`)
+
+Pure C (AR-7): `extern "C"`, opaque handles, UTF-8, plain structs, integer results. Threads
+are stated per function. "Message thread" means the managed UI / engine-owner thread,
+like every other structural call.
+
+## Types
+
+```c
+typedef struct NotaAuroraTable NotaAuroraTable; /* opaque, immutable once built */
+
+typedef struct NotaAuroraTableInfo {
+ int32_t frames; /* 1..256; 0 = no table in that slot */
+ int32_t origin; /* 0 wavetable file, 1 single cycle, 2 recording */
+ int32_t truncated_length; /* 1 = only the first 60 s were read */
+ int32_t truncated_frames; /* 1 = frames beyond 256 were dropped */
+ int32_t use_custom; /* track queries only: the source flag */
+ int32_t missing; /* track queries only: 1 = restore failed, name holds it */
+ uint32_t serial; /* changes whenever the slot's table changes; 0 = none */
+ uint8_t hash[16]; /* content hash of the base frames */
+ char name[256]; /* UTF-8, NUL-terminated */
+} NotaAuroraTableInfo;
+
+enum {
+ NOTA_AURORA_OK = 0,
+ NOTA_AURORA_ERR_DECODE = -1, /* unreadable or broken file */
+ NOTA_AURORA_ERR_FORMAT = -2, /* not WAV / FLAC / MP3 */
+ NOTA_AURORA_ERR_SILENT = -3, /* peak below -60 dBFS */
+ NOTA_AURORA_ERR_EMPTY = -4,
+ NOTA_AURORA_ERR_ARGS = -5,
+};
+```
+
+## Building (any thread; touches no engine state)
+
+```c
+/* Decode a file and build a conditioned, band-limited table (spec FR-008/FR-009).
+ * On success *out receives a new handle (caller frees). Returns NOTA_AURORA_OK or an error. */
+NOTA_API int32_t nota_aurora_table_build(const char* path_utf8, NotaAuroraTable** out);
+
+/* Build from already-conditioned frames (project / preset reload): no DC removal, no
+ * normalisation, no windowing — only mips are rebuilt, so a reload is bit-identical. */
+NOTA_API int32_t nota_aurora_table_from_frames(const float* frames, int32_t frame_count,
+ const char* name_utf8, int32_t origin,
+ NotaAuroraTable** out);
+
+NOTA_API int32_t nota_aurora_table_info(const NotaAuroraTable* t, NotaAuroraTableInfo* out);
+NOTA_API void nota_aurora_table_free(NotaAuroraTable* t);
+```
+
+## Applying to a track (message thread)
+
+```c
+/* Put t into oscillator osc (0/1) of an Aurora track and make it the active source.
+ * checkpoint 1 = one undo step (clone + republish; sounding notes stop), 0 = no undo
+ * (project load). t stays owned by the caller (the engine takes its own reference).
+ * Returns 1 on success, 0 when the track is not an Aurora or osc is out of range. */
+NOTA_API int32_t nota_track_aurora_set_table(NotaEngine* e, int32_t track_id, int32_t osc,
+ const NotaAuroraTable* t, int32_t checkpoint);
+/* Remove the imported table from osc (one undo step); the oscillator plays its built-in. */
+NOTA_API int32_t nota_track_aurora_clear_table(NotaEngine* e, int32_t track_id, int32_t osc);
+/* In place, lock-free: 1 = play the imported table, 0 = the built-in. No undo. */
+NOTA_API int32_t nota_track_aurora_set_source(NotaEngine* e, int32_t track_id, int32_t osc, int32_t use_custom);
+/* Mark osc as missing (name shown as "Missing: <name>"); "" clears. No undo. */
+NOTA_API int32_t nota_track_aurora_set_missing(NotaEngine* e, int32_t track_id, int32_t osc, const char* name_utf8);
+```
+
+## Queries (message thread)
+
+```c
+NOTA_API int32_t nota_track_aurora_table_info(const NotaEngine* e, int32_t track_id, int32_t osc,
+ NotaAuroraTableInfo* out);
+/* Copy the base frames (2048 × frames floats) into out; returns floats written, 0 if none. */
+NOTA_API int64_t nota_track_aurora_table_read(const NotaEngine* e, int32_t track_id, int32_t osc,
+ float* out, int64_t cap);
+/* Drawing preview: rep_frames (≤ 16) evenly chosen frames then grid_frames (≤ 64) evenly chosen
+ * frames, each `points` (≤ 256) samples of the lowest mip level that keeps the shape, back to
+ * back. Returns floats written. */
+NOTA_API int32_t nota_track_aurora_table_preview(const NotaEngine* e, int32_t track_id, int32_t osc,
+ int32_t rep_frames, int32_t grid_frames, int32_t points,
+ float* out, int32_t cap);
+/* State blob with (1) or without (0) the table section — 0 is what a project save of a
+ * top-level track stores beside its samples/ files. Same size/copy semantics as
+ * nota_track_get_plugin_state. */
+NOTA_API int32_t nota_track_aurora_state(const NotaEngine* e, int32_t track_id, int32_t include_tables,
+ uint8_t* out, int32_t cap);
+```
+
+Live follow uses the existing `nota_track_instrument_scope` (`nota_engine.h:1081-1083`), with
+the layout given in [../data-model.md](../data-model.md) § Scope telemetry.
+
+## Rack chains (message thread)
+
+These mirror `nota_rack_set_chain_sampler_sample` (`nota_engine.h:1801`). They carry the same
+semantics, but address an Aurora in Instrument Rack chain `chain`, or on a Drum Rack pad:
+
+```c
+NOTA_API int32_t nota_rack_chain_aurora_set_table(NotaEngine* e, int32_t track_id, int32_t chain, int32_t osc,
+ const NotaAuroraTable* t); /* one undo step */
+NOTA_API int32_t nota_rack_chain_aurora_clear_table(NotaEngine* e, int32_t track_id, int32_t chain, int32_t osc);
+NOTA_API int32_t nota_rack_chain_aurora_set_source(NotaEngine* e, int32_t track_id, int32_t chain, int32_t osc, int32_t use_custom);
+NOTA_API int32_t nota_rack_chain_aurora_table_info(const NotaEngine* e, int32_t track_id, int32_t chain, int32_t osc,
+ NotaAuroraTableInfo* out);
+NOTA_API int32_t nota_rack_chain_aurora_table_preview(const NotaEngine* e, int32_t track_id, int32_t chain, int32_t osc,
+ int32_t rep_frames, int32_t grid_frames, int32_t points,
+ float* out, int32_t cap);
+```
+
+## Invariants
+
+- No function here runs or blocks on the audio thread. The `set_*` calls publish a new
+ snapshot (republish or `SnapshotHistory::publish`), and frees happen on the message thread.
+- The `nota_aurora_table_*` builders are re-entrant; two builds may run at once.
+- Smoke coverage: every function is called by `AuroraTableTests.cs` (tasks T017, T025–T030, T047).
diff --git a/specs/053-aurora-one-card/contracts/persistence.md b/specs/053-aurora-one-card/contracts/persistence.md
new file mode 100644
index 00000000..5af312fc
--- /dev/null
+++ b/specs/053-aurora-one-card/contracts/persistence.md
@@ -0,0 +1,40 @@
+# Contract: project format v28 and preset fields
+
+## Project (`project.json`, `ProjectService.CurrentFormatVersion` 27 → 28)
+
+- **Migration**: append `new Migration(27, _ => { })` (`ProjectMigrations.cs:25-50`
+ pattern). A v27 document has no `wavetables`, and the DTO defaults to null.
+- **Save** of a top-level Aurora (kind 5, `ProjectService.cs:150-153` branch):
+ 1. `instrument.state` comes from `nota_track_aurora_state(include_tables = 0)`, through
+ `RegisterBlob`.
+ 2. For each oscillator with a table: read the frames (`nota_track_aurora_table_read`) and
+ write them through a WAV writer as float32 mono with a `clm ` chunk (frame size 2048).
+ Name the file by content hash (`BundleContent.SampleRel`), skip it if it is already on
+ disk, and add a `WavetableDto` ([../data-model.md](../data-model.md)).
+ 3. A missing slot is saved as `{ Missing: true, Sample: "", Name }`.
+- **Load**:
+ 1. Create the track, then `SetPluginState(blob)`.
+ 2. For each `WavetableDto`: if `Missing`, call `nota_track_aurora_set_missing` and add the
+ warning. Otherwise decode the WAV (`nota_file_decode_mono`, exact for float32) and call
+ `nota_aurora_table_from_frames`, then `nota_track_aurora_set_table(checkpoint = 0)` and
+ `nota_track_aurora_set_source(UseCustom)`.
+ 3. On a failure (file absent, unreadable, or frame count mismatch), add the warning
+ `"Track {n}: Aurora Osc {o} table \"{Name}\" is missing — it plays its built-in table."`,
+ then `set_missing(Name)` and `set_source(0)`.
+- **History and pruning**: `samples/<hash>.wav` files referenced by `wavetables` are pinned
+ like other sample references (`ProjectHistory.cs:4-18`, `BundleContent.PruneUnreferenced`).
+- **Older Nota**: a v28 file is refused by the existing "higher version" check
+ (`ProjectService.cs:34-40` doc comment). That is expected behaviour and needs no change.
+
+## Presets (`PresetDocument`)
+
+- New: `[JsonIgnore(Condition = WhenWritingNull)] List<PresetAuroraTable>? AuroraTables`,
+ placed beside `MosaicProgram` (`PresetModel.cs:47-49`). `FormatVersion` stays 1, because
+ unknown fields round-trip (`PresetModel.cs` forward-compat note).
+- **Save** (`PresetService.cs:62` neighbourhood): when kind 5 has any table, write one entry
+ per slot with `Data = base64(float32 LE frames)`.
+- **Apply**: first the named parameters, then:
+ - if `AuroraTables` is null: `clear_table` for both slots and `set_source(0)`;
+ - otherwise `from_frames`, then `set_table`, then `set_source`.
+ The whole apply is one undo group with the parameter change.
+- Factory presets carry no `AuroraTables`, so they always play the built-in tables.
diff --git a/specs/053-aurora-one-card/contracts/state-blob.md b/specs/053-aurora-one-card/contracts/state-blob.md
new file mode 100644
index 00000000..28110583
--- /dev/null
+++ b/specs/053-aurora-one-card/contracts/state-blob.md
@@ -0,0 +1,47 @@
+# Contract: WavetableSynth state blob, table trailer v1
+
+The parameter layout is unchanged: `kNumParams` little-endian float32 values
+(`WavetableSynth.cpp:227-234`), append-only (`WavetableSynth.h:19`). An optional trailer
+follows at the **end** of the blob:
+
+```text
+offset content
+0 float32 × P parameters (P = kNumParams of the writer; 156 today)
+4P section (S bytes):
+ char[4] "AWT1"
+ u32 version = 1
+ u8 useCustom[2]
+ for osc in 0..1:
+ u8 present (0 = no table)
+ u16 missingLen, char[missingLen] missing name ("" = not missing)
+ if present:
+ u8 sameAsOsc0 (osc 1 only; 1 = identical hash, no frames follow)
+ u16 nameLen, char[nameLen]
+ u8 origin, u8 truncatedLength, u8 truncatedFrames
+ u32 frames (1..256)
+ float32 × 2048 × frames base level (mips rebuilt on read)
+4P + S u32 S
+4P + S + 4 char[4] "AWT1"
+```
+
+## Rules
+
+- **Writer.** The trailer is written only when a slot holds a table, a source flag is 1, or
+ a missing name is set. Otherwise the blob is exactly `4P` bytes, byte-identical to today's,
+ so content-addressed `plugin-states/<hash>.bin` names do not change for existing projects.
+- **Reader.**
+ 1. If `size ≥ 8` and the last 4 bytes are `"AWT1"`, read `S` and check that
+ `4 + S + 4 ≤ size` and that the section starts with `"AWT1"`. If so, the parameter
+ region is `size − S − 8` bytes; otherwise the whole blob is parameters.
+ 2. Parameters are read as today: `min(kNumParams, region / 4)`.
+ 3. Unknown trailer versions are ignored: parameters are read, and the tables stay as they
+ were.
+- **Excluded tables.** `nota_track_aurora_state(include_tables = 0)` writes the trailer with
+ `present = 0` for both slots but keeps `useCustom` and the missing names. The project save
+ then lists the tables in `InstrumentDto.Wavetables`.
+- **Setting state.** `setState` builds the new `AuroraTableSet` on the calling (message)
+ thread, then publishes it through the `SnapshotHistory` (research R1). A blob without a
+ trailer clears both slots and both flags, so a v27-era state restored over a live instance
+ resets it (the preset FR-015 semantics).
+- **Clones and racks.** `clone()` shares the current set and flags. Rack blobs carry the
+ child state unchanged (`RackCore.cpp:661-663`).
diff --git a/specs/053-aurora-one-card/contracts/ui-osc-tab.md b/specs/053-aurora-one-card/contracts/ui-osc-tab.md
new file mode 100644
index 00000000..d362b784
--- /dev/null
+++ b/specs/053-aurora-one-card/contracts/ui-osc-tab.md
@@ -0,0 +1,81 @@
+# Contract: Aurora Osc tab (700 × 260 default)
+
+The card shell, the wheels (56), the rail (186), the tab row and the other five tabs are
+unchanged (`AuroraInstrumentCard.cs:51-53, 849-876`). The Osc tab body is about 438 × 166.
+
+```text
+┌──────────────── Osc 1 (216) ────────────────┐ 6 ┌──────────────── Osc 2 (216) ────────────────┐
+│ Osc 1 [on] [Formant ⌄] [Sync ⌄] 20 │ │ Osc 2 [on] [vox_aa.wav ⌄] [Off ⌄] 20 │
+│ ┌ window 216 × 60 ───────────────────────┐ │ │ ┌ window 216 × 60 ───────────────────────┐ │
+│ │ Formant · 5/16 · lfo 1 → pos │ │ │ │ vox_aa.wav · 9/16 · no modulation │ │
+│ │ (stack: ≤ 16 frames + lit) │ │ │ │ │ │
+│ └────────────────────────────────────────┘ │ │ └────────────────────────────────────────┘ │
+│ POS WARP LEVEL OCT SEMI FINE (34 px) 54│ │ POS WARP LEVEL OCT SEMI FINE 54 │
+└──────────────────────────────────────────────┘ └──────────────────────────────────────────────┘
+ SUB [sin sqr tri] LEVEL OCT │ UNI VOICES DETUNE SPREAD 22
+```
+
+## Elements per oscillator
+
+- **Name** "Osc 1" / "Osc 2", in section type. It is no longer a picker.
+- **On switch**, 18 × 10.
+- **Type drop-down** (22 high), listing:
+ - `Analog`, `Pulse`, `Formant`, `Chroma`;
+ - a separator, then the imported table's name when present (a check mark on the active
+ source), `Import…`, and `Remove imported table` (only when present).
+ When the source is imported and the built-in parameter is automated, the built-in row
+ shows its value in ink 4 (FR-010).
+- **Warp drop-down**: `Off`, `Sync`, `Bend`, `PWM`, `Fold`.
+- **Window**:
+ - a `NotaGraph` window with the title row (name · frame n/N · position modulation);
+ - the stack drawn under `PlotTop`, at most 16 frames plus the lit frame;
+ - the lit frame in `VizInk` 1.7 px, the rest in depth washes, as today
+ (`AuroraStack.cs:27-43`);
+ - when Osc is off, the `Inactive` look.
+- **Knobs**: Position, Warp, Level, Oct, Semi, Fine; 34 px; the interaction contract as
+ today (`AuroraInstrumentCard.cs:198-222`).
+
+## States of the window
+
+| State | What shows |
+|---|---|
+| Built-in | the bank's stack, lit at the set or played position |
+| Imported | the preview stack. The caption says "1 frame" for single cycles, and notes "shortened to 60 s" / "first 256 frames" for 4 s after import |
+| Drag over | a 1.5 px orange inner ring, and the caption "Drop to load into Osc n" |
+| Loading | the caption "Loading…". The old stack stays, and the oscillator keeps playing |
+| Error | a one-line reason for 4 s ("Couldn't read this file — use WAV, FLAC or MP3", "This file is silent"), then the previous state |
+| Missing | the caption "Missing: <name>". The type drop-down reads the same; the built-in stack is shown |
+
+## Live follow
+
+On each 30 Hz tick, read the scope:
+
+- if the played position ≥ 0, the lit frame follows it;
+- otherwise the lit frame follows the set Position.
+
+Repaint only on a lit-index change (a 64-step grid), a source change, dim, theme or resize.
+
+## Drop targets
+
+The whole oscillator column accepts a file from the browser (`BrowserView.IsAcceptableDrag`
+/ `DroppedItems`) or from the file manager. MIDI files and presets are ignored. The file
+picker filter is `*.wav;*.flac;*.mp3`.
+
+## Removed
+
+`oscPick`, `osel`, `applyOsc`, the shared strip `oscStrip` / `oscTableHosts` / `oscWarpHosts`
+(`AuroraInstrumentCard.cs:423-442, 480-487`) and the single 128 px `tableWindow` (`:534`).
+`Hint()` and `Summary()` stop naming "the picked oscillator".
+
+After the merge with `ui/style-guide` (#531, one home per control): the Global rail's
+`POS 1`, `CUTOFF` and `UNISON` sliders go, being second copies of the Osc tab's Osc 1
+Position, the Filter tab's Freq and the unison Detune; the rail keeps Voices, Bend, Volume
+and Pan. `Summary()` and the status strip are already gone with #531.
+
+## At 1050 (only if FR-005 is answered "Wide")
+
+- Columns are about 391 px.
+- The type and warp selectors become inline segment chips (4 + 5, plus an `Import…` chip
+ and the import's name chip).
+- The window is about 150 × 86, to the left of a 3 × 2 knob grid at 36 px.
+- The sub / unison row is unchanged.
diff --git a/specs/053-aurora-one-card/data-model.md b/specs/053-aurora-one-card/data-model.md
new file mode 100644
index 00000000..213a6352
--- /dev/null
+++ b/specs/053-aurora-one-card/data-model.md
@@ -0,0 +1,117 @@
+# Data Model: Aurora one card and custom wavetables
+
+Phase 1 of [plan.md](plan.md). Entities follow the spec's Key Entities; the field names here are the
+planned ones.
+
+## AuroraTable (engine, immutable)
+
+An imported wavetable after conditioning. Built on any thread, never mutated after
+construction, shared by `shared_ptr<const AuroraTable>`.
+
+| Field | Type | Rule |
+|---|---|---|
+| `frames` | int | 1–256 |
+| `base` | float[frames × 2048] | DC-free per frame, table peak = 1.0 (R3) |
+| `mip[k]`, k = 1…5 | float[frames × (2048 >> k)] | FFT-truncated to ≤ 1024 >> k harmonics (R4); `mip[0]` is `base` |
+| `name` | UTF-8, ≤ 255 bytes | the source file name without its folder; the default display name |
+| `origin` | enum | 0 wavetable file · 1 single cycle · 2 recording |
+| `truncatedLength` | bool | more than 60 s of audio was given |
+| `truncatedFrames` | bool | more than 256 frames were given |
+| `hash` | 16 bytes | 128-bit content hash of `base` (R3 step 5) |
+| `serial` | u32 | process-unique, for UI cache invalidation |
+
+**Validation**: a build fails with a typed error if:
+
+- the file cannot be decoded (`NOTA_AURORA_ERR_DECODE`);
+- the format is not WAV / FLAC / MP3 (`ERR_FORMAT`);
+- the peak before normalising is below −60 dBFS (`ERR_SILENT`);
+- the file is empty (`ERR_EMPTY`).
+
+The `frames` rules: (a) a wavetable file has its count clamped to 256; (b) a single cycle
+gives 1; (c) a recording always gives 16 windows, which overlap when the file is shorter than
+16 × 2048 samples.
+
+## AuroraTableSet (engine, immutable, behind SnapshotHistory)
+
+| Field | Type |
+|---|---|
+| `slot[2]` | `shared_ptr<const AuroraTable>` (null = none) |
+| `missing[2]` | UTF-8 name of a table that could not be restored ("" = not missing) |
+
+Owned by `WavetableSynth::tables_` (`SnapshotHistory<const AuroraTableSet>`). The audio thread
+reads `live()` once per block.
+
+## Per-oscillator source state (engine)
+
+| Field | Type | Rule |
+|---|---|---|
+| `useCustom_[osc]` | `std::atomic<uint8_t>` | 1 plays `slot[osc]` when present; otherwise the built-in `table` / `osc2table` parameter decides. Relaxed. |
+
+**State transitions** (per oscillator):
+
+```text
+Built-in ──import ok──▶ Imported(active) ──pick built-in──▶ Imported(kept, inactive)
+ ▲ │ ▲ │
+ │ remove │ pick imported ◀──────────────────┘
+ └────────────remove───────────┘
+Any ──project load, file missing──▶ Missing(name) (plays built-in; import or pick built-in clears)
+Any ──import failed──▶ unchanged (card shows the reason)
+```
+
+Import and remove are undoable (a graph republish). A pick is in place. Missing is set by the
+load path.
+
+## Scope telemetry (engine → UI)
+
+`WavetableSynth::scopeRead`, through `nota_track_instrument_scope`:
+
+| Index | Meaning |
+|---|---|
+| 0 | Osc 1 played position 0..1 (most recent sounding voice, modulation included), −1 = silent |
+| 1 | Osc 2 played position, as above |
+| 2 | Osc 1 table serial (0 = built-in) |
+| 3 | Osc 2 table serial |
+| 4 | active voices |
+
+## State blob trailer
+
+See [contracts/state-blob.md](contracts/state-blob.md).
+
+## Project (managed, format v28)
+
+`InstrumentDto.Wavetables : List<WavetableDto>?`. It is null when the Aurora has no custom
+table, so an Aurora without one saves exactly as in v27.
+
+| WavetableDto field | Type | Rule |
+|---|---|---|
+| `Osc` | int | 0 or 1 |
+| `Sample` | string | bundle-relative `samples/<hash>.wav` ("" when `Missing`) |
+| `Name` | string | display name |
+| `Origin` | int | as `AuroraTable.origin` |
+| `Frames` | int | 1–256, cross-checked on load |
+| `UseCustom` | bool | the source flag |
+| `Missing` | bool | saved while the table was missing, so the warning and the name persist |
+
+The stored WAV is float32 mono, 2048 × `Frames`, with a `clm ` frame-size chunk. Identical
+tables share one file (content-addressed, `BundleContent.cs:4-9`).
+
+## Preset (managed)
+
+`PresetDocument.AuroraTables : List<PresetAuroraTable>?` (null = no custom tables; loading
+such a preset clears them).
+
+| PresetAuroraTable field | Type |
+|---|---|
+| `Osc` | int |
+| `Name` | string |
+| `Origin` | int |
+| `Frames` | int |
+| `UseCustom` | bool |
+| `Data` | string: base64 of little-endian float32, 2048 × `Frames` |
+
+## UI view state (managed, not persisted)
+
+| Entity | Fields |
+|---|---|
+| `AuroraTableView` | source key (built-in bank, or table serial), lit index (0..63 of the lit grid), dim, load state (idle / loading / error(text) / missing(name)), cached geometries per bounds |
+| `AuroraTablePreview` cache | key (track, osc, serial) → up to 16 representative frames + 64 lit-grid frames × 96 points |
diff --git a/specs/053-aurora-one-card/plan.md b/specs/053-aurora-one-card/plan.md
new file mode 100644
index 00000000..ff6a5d53
--- /dev/null
+++ b/specs/053-aurora-one-card/plan.md
@@ -0,0 +1,342 @@
+# Implementation Plan: Aurora, both wavetables on one card, and custom wavetables from samples
+
+**Branch**: `feat/aurora-one-card` | **Date**: 2026-10-29 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `specs/053-aurora-one-card/spec.md` (committed at 41bd30d3,
+with the Clarifications session of 2026-10-29)
+
+## Summary
+
+The Osc tab of Nota Aurora drops its "1 / 2" switch. Both oscillators are drawn side by side,
+each with its own table window, type selector, warp-mode selector and six knobs. The card
+stays 700 × 260 (the open FR-005 question; § Layout at 1050 lists what would change). Each
+oscillator can also load a custom wavetable made from an audio file:
+
+- a standard wavetable file keeps its frames, up to 256 × 2048;
+- a single cycle becomes one frame;
+- a longer recording becomes 16 even, zero-crossing-aligned 2048-sample windows (no pitch
+ detection).
+
+The engine holds a custom table as an immutable, band-limited **table set** with mip levels.
+It is built off the audio thread and reaches the audio thread in one of two ways:
+
+- **Undoable edits** (import, remove) publish a cloned instrument through the existing
+ `republishWithTrack` path, so they get undo for free (AR-5).
+- **In-place loads** (`setState` from a preset or a project) swap it through the engine's
+ existing `SnapshotHistory` epoch retirement (AR-6).
+
+The audio thread only ever reads a raw pointer. It never allocates, never frees and never
+takes a lock.
+
+Persistence:
+
+- **Engine state blob**: the table rides as a trailer section after the 156 parameters, so a
+ blob without a custom table stays byte-identical to today's. The trailer keeps racks,
+ clones and copy/paste self-contained.
+- **Top-level project tracks**: tables are also written as content-addressed
+ `samples/<hash>.wav` files, so identical tables are stored once. The project format goes
+ from 27 to 28.
+- **User presets**: carry the table as an embedded payload.
+
+The two table windows read a cached preview per table, cache their geometry, draw at most
+17 frames, and repaint only when the lit frame changes. "Lit" means the played position,
+since live follow comes from a new Aurora scope. UI cost is measured per thread with
+`pidstat` on the 036 reference machine, plus an opt-in paint-time probe.
+
+## Nota: Read Before Planning
+
+Consult the matching source of truth before designing:
+
+- **Engine work** → [`ARCHITECTURE.md`](../../ARCHITECTURE.md): the AR rules table is binding (AR-4 lock-free queue, AR-5 immutable snapshots, AR-6 audio-thread restrictions, AR-7 pure C ABI, AR-9 `Transport` is the only source of musical time).
+- **UI work** → [`DESIGN.md`](../../DESIGN.md) (Studio design language) and the `nota-design` skill.
+- **A built-in instrument / audio or MIDI effect** → the `nota-instrument` skill (DSP class, kind registration across C++ and C#, device-card UI).
+- **Build / packaging** → [`BUILD.md`](../../BUILD.md).
+- **Anything** → [`CONTRIBUTING.md`](../../CONTRIBUTING.md): licensing, dependency policy, PR expectations.
+
+## Technical Context
+
+**Language/Version**: C++20 (engine: `WavetableSynth`, the new table builder, C ABI); C# / .NET 10
+(interop, persistence, presets, Avalonia card).
+
+**Primary Dependencies**: Existing only.
+
+- dr_libs (WAV / FLAC / MP3 decoding, `src/media/AudioFile.cpp:29-73`, `LICENSES/third-party.md:19`)
+ through `decodeAudioFile`.
+- signalsmith-linear `RealFFT`, already used by `dsp/primitives/Convolution.h:14` and
+ `SpectrumAnalyzer.h:18`, for band-limiting and periodic resampling.
+- Avalonia 12.
+
+There is **no new dependency** and no `LICENSES/third-party.md` change.
+
+**Storage**:
+
+- `.nota` bundle, two parts:
+ - `project.json`: `InstrumentDto.Wavetables`, new in format v28.
+ - `samples/<hash>.wav`: content-addressed, the `BundleContent` pattern (`BundleContent.cs:4-9`).
+- `plugin-states/<hash>.bin` for the instrument state blob (unchanged mechanism, `ProjectService.cs:150-153`).
+- User preset JSON: `PresetDocument.AuroraTables`, new.
+
+**Audio-Thread Impact** *(required)*:
+
+- **New per-block reads.** The table set is read once per block through `SnapshotHistory::live()`,
+ plus two relaxed atomic source flags. Imported oscillators use a mip-level pick and reads from
+ a new size-masked morph reader.
+- **Built-in path untouched.** Built-in oscillators keep the exact current code path
+ (`oscStack` → `readMorph`, `WavetableSynth.cpp:681-703`), so factory sound stays bit-identical
+ (036 null gate).
+- **Scope writes.** One scope write per block: a few relaxed atomic floats.
+- **Nothing heavy on the audio thread.** No allocation, lock, I/O or free there. Table builds run
+ on a background thread; swaps happen on the message thread.
+- **Retirement.** Old instruments are retired by the existing snapshot mechanisms
+ (`Engine.cpp:671-688`, `SnapshotHistory.h:4-14`).
+
+**Testing**: `tests/Nota.SmokeTest`.
+
+- New `AuroraTableTests.cs` (ABI-level: conditioning, persistence, undo, missing, presets, racks, scope).
+- The existing `AuroraNullTests.cs` gate (bit-identical factory renders).
+- `tests/perf/nota_perf.cpp`: existing `aurora-supersaw-2x` plus a new `aurora-imported-2x` scenario.
+- Manual UI performance runs with `pidstat` and the paint probe (quickstart § 4).
+
+**Target Platform**: macOS, Windows, Linux x86-64. Performance acceptance is on the 036 reference
+machine (i7-12700, Linux, `specs/036-aurora-perf/baseline-env.md:6-13`).
+
+**Project Type**: Desktop app (native engine + managed UI).
+
+**Performance Goals**:
+
+- UI thread at most +2 points of one core over today's card, and the card at most 5 % of a core (SC-003).
+- Both windows paint in at most 2 ms at p99 (SC-004).
+- The card shows within 100 ms of switching tracks, with no UI frame over 50 ms (SC-005).
+- `aurora-supersaw-2x` within ±10 % of about 28 ms/s; imported tables cost at most 10 % more than built-in (SC-006).
+- A table build takes at most 1 s for a 10 s file (SC-002).
+
+**Constraints**:
+
+- A table is at most 256 frames × 2048 samples (2 MB as float32 at the base level; about 4 MB
+ with its mips).
+- Reading stops at 60 s of audio.
+- The state blob layout is append-only.
+- No new automatable parameter (spec Assumptions).
+- The card is 260 high and 700 wide by default.
+
+**Scale/Scope**:
+
+- 2 table slots per Aurora; any number of Auroras, including inside Instrument Rack chains and
+ Drum Rack pads.
+- About 12 C ABI functions.
+- One card tab rebuilt.
+- Persistence in 3 places: blob, project, preset.
+
+## Constitution Check
+
+*GATE: checked before Phase 0 and again after Phase 1 design. Result: PASS, no violations.*
+
+| Principle | How this plan complies |
+|---|---|
+| I. Real-time audio safety | The table set is built on a worker thread (`nota_aurora_table_build`, which touches no engine state, like `nota_audio_import`, `nota_engine.h:613-631`). It is handed over either by an instrument clone plus graph republish (AR-5), or through `SnapshotHistory` epoch retirement for in-place `setState` (AR-6). The audio thread reads `live()` once per block. Frees always happen on the message thread. The source flags are relaxed atomics. |
+| II. Boundary discipline | All additions are `extern "C"` in `nota_engine.h` with an opaque `NotaAuroraTable*` handle, plain structs, UTF-8 and integer results ([contracts/c-abi.md](contracts/c-abi.md)). No JUCE. |
+| III. Licensing hygiene | New files carry the two-line SPDX header. No new dependency (dr_libs and signalsmith-linear are already listed). |
+| IV. Verification gate | Smoke-test coverage is listed per story in tasks.md. The 036 Aurora null gate must stay green. |
+| V. One logical change per PR | One PR for the feature, built in reviewable commits by phase. If review needs it, US1 (layout only) can ship first as its own PR (tasks.md § Strategy). |
+| VI. Docs in sync | `CHANGELOG.md` `[Unreleased]`, FEATURES.md (nota-features), the manual EN + RU (nota-docs), DESIGN.md Aurora note. |
+| VII. Spec first | Spec committed (41bd30d3). One clarification is still open (FR-005, card width). The plan takes the 700 default and isolates the layout so a switch to 1050 touches only the card ([research.md](research.md) R10). |
+| VIII. Safety rules not weakened | The design never mutates the table in place on the audio thread. It does not use a lock "just for the swap", and it does not decode on the audio thread. |
+
+**Post-design re-check (after Phase 1)**: PASS. The contracts add no C++ types to the ABI. The
+blob trailer keeps old blobs byte-identical. The only non-POD state crossing threads is the
+immutable table set behind `SnapshotHistory`.
+
+## Design overview
+
+### Engine (`src/native/nota.engine`)
+
+1. **`AuroraTable` (new, `src/devices/instruments/AuroraTable.h/.cpp`).** An immutable
+ table: `frames` (1–256), base level 2048 × frames, mip levels of length 2048 >> k
+ (k = 0…5, at most 1024 >> k harmonics each), the display name, the origin
+ (wavetable file / single cycle / recording) and notes (`truncatedLength`,
+ `truncatedFrames`). Also the pure build functions:
+ - `buildFromFile(path)`: decode via `decodeAudioFile` → mono mix → rules (a) / (b) / (c)
+ → condition;
+ - `buildFromFrames(const float*, frames, name)`: the raw path used by project reload,
+ with no re-conditioning, so a reload is bit-identical;
+ - the conditioning steps: DC removal per frame, a 32-sample loop-seam blend for
+ recording windows, per-table peak normalisation to 1.0 (the built-in level,
+ `WavetableSynth.cpp:739-741`), refusal below −60 dBFS, and mip generation by FFT
+ truncation.
+ - A content hash of the base level, used for dedup inside a blob and for UI caching.
+ See [data-model.md](data-model.md) § AuroraTable.
+2. **`WavetableSynth` changes.**
+ - A `SnapshotHistory<const AuroraTableSet>` member holds `{ shared_ptr<const AuroraTable>
+ slot[2]; std::string missing[2]; }`, plus `std::atomic<uint8_t> useCustom_[2]`.
+ - `render()` opens a `RenderScope` and reads `live()` once per block next to the existing
+ block snapshot (`WavetableSynth.cpp:330-345`). For an oscillator with `useCustom` and a
+ table present, it calls a new `oscStackCustom` with the mip level picked from the
+ voice's highest phase increment (unison detune and a warp-mode bias included). Otherwise
+ it calls the unchanged `oscStack` (`:497-500`).
+ - `clone()` (`:246-252`) shares the table set and copies the flags.
+ - `getState()` / `setState()` (`:227-244`) add the trailer section
+ ([contracts/state-blob.md](contracts/state-blob.md)). `setState` builds the set on the
+ calling (message) thread and publishes it through the history, so a live preset load or
+ a rack restore is safe.
+ - `scopeRead()` (the `Instrument.h:155-159` hook, Keys pattern `Keys.h:199-215`) publishes
+ the played position of each oscillator, from the most recently started sounding voice
+ including modulation, plus the two table serials.
+3. **`Engine` (`Engine_Devices.cpp`)**, next to the Rhythm sample path
+ (`Engine_Devices.cpp:328-343`):
+ - `auroraSetTable(track, osc, table)` and `auroraClearTable(track, osc)`: clone →
+ modify → `republishWithTrack` → one undo step (`Engine.cpp:685-688`, undo at
+ `:694-714`). Sounding notes stop, as with a Mosaic program change
+ (`nota_engine.h:705-709`).
+ - `auroraSetSource(track, osc, useCustom)`: in place, an atomic store, notes continue.
+ - `auroraSetMissing(track, osc, name)`: message-thread metadata, published through the
+ history.
+ - Read-only queries for table info, the full frames and a preview.
+ - Rack-chain variants mirror `nota_rack_set_chain_sampler_sample` (`nota_engine.h:1801`).
+4. **C ABI**: [contracts/c-abi.md](contracts/c-abi.md), implemented in
+ `src/abi/nota_engine_track.cpp`, with the builder in `src/abi/nota_engine_import.cpp`
+ (next to `nota_file_decode_mono`, `:103`).
+
+### Managed
+
+- **Interop**: `NativeMethods.Tracks.cs`, `NotaEngine.Tracks.cs`, `IAudioEngine.cs`, and the
+ rack proxy engine used for in-rack cards (`RackCardView.cs:211`).
+- **Application service `AuroraTableImporter`** (`src/managed/Nota.Application/Instruments/Aurora/`):
+ checks the extension against `SampleIndex.AudioExtensions` (`SampleIndex.cs:20-21`), runs
+ the build on a `Task`, marshals the result to the UI thread, applies it with
+ `AuroraSetTable` and reports a typed result (ok / truncated / unreadable / silent).
+- **Project** (`ProjectService.cs`):
+ - Save, for kind 5 with any table: the blob is written **without** tables
+ (`nota_track_aurora_state(include_tables = 0)`). Each table is written as
+ `samples/<hash>.wav` (float32 mono, 2048 × N, itself a standard wavetable file) and
+ listed in `InstrumentDto.Wavetables`.
+ - Load: replay the blob, then `AuroraTableFromFrames` per entry. A missing file → a
+ warning plus `AuroraSetMissing` (FR-016).
+ - `CurrentFormatVersion` 27 → 28 (`ProjectService.cs:40`), with a no-op migration
+ appended (`ProjectMigrations.cs:25-50`).
+ - Pruning: `PinnedBinaries` / `PruneUnreferenced` learn the new references
+ (`ProjectHistory.cs:4-18`).
+ - Aurora instances nested in racks stay self-contained in the rack blob (rack Sampler
+ precedent, `RackCore.cpp:664-674`, `:801-814`).
+- **Presets** (`PresetModel.cs`, `PresetService.cs`): `AuroraTables` (osc, name, origin,
+ frames, base64 float32 frames), written at save and applied after the parameters on load.
+ This follows the `MosaicProgram` pattern (`PresetService.cs:62`, `:313-324`). A preset
+ without the field clears both custom tables (FR-015).
+
+### UI (`src/managed/Nota.App`)
+
+- **`AuroraTableView`** (new, replaces `AuroraStack` on the Osc tab): one per oscillator.
+ - Built-in tables use the existing per-process shape cache (`AuroraStack.cs:47-49, 86-115`).
+ - Imported tables use a preview read once per table serial (at most 16 representative
+ frames plus up to 64 for the lit frame, 96 points each).
+ - Geometries are cached per (source, size), so a repaint is at most 17 `DrawGeometry`
+ calls (today it rebuilds 16 geometries on every paint, `AuroraStack.cs:138-152`).
+ - `Set(source, litPos, dim)` invalidates only when the lit index or the source changes.
+ - It acts as the drop target, with a hover highlight (Rhythm pattern,
+ `RhythmInstrumentCard.cs:220-235`), and shows the loading, error and missing states.
+- **Osc tab layout at 700**: [contracts/ui-osc-tab.md](contracts/ui-osc-tab.md). There are
+ two 216 px columns:
+ - header row: name, on switch, type drop-down, warp drop-down;
+ - a 216 × 60 window;
+ - a row of six 34 px knobs.
+ The shared sub / unison row spans below. The `osel` pick, `oscPick`, `applyOsc` and the
+ shared strip (`AuroraInstrumentCard.cs:423-442, 480-487`) are removed.
+- **Live tick**: `Refresh` reads the 5-float Aurora scope on every tick before the
+ `ParamsMoved` gate (`AuroraInstrumentCard.cs:147-176`). It updates only the windows when
+ only the played position moved.
+
+### Measurement (SC-002 to SC-006)
+
+- **UI CPU**: a smoke-test helper `--aurora-ui-fixture <dir> [--builtin]` writes two fixture
+ projects:
+ - the scenario: 4 Auroras, both oscillators on generated 256-frame tables, LFO 1 → Osc 1
+ position and LFO 2 → Osc 2 position at 2 Hz, a 4-bar chord loop;
+ - the baseline: the same with built-in tables and format v27, so today's build can open it.
+ `pidstat -t -p <pid> 1 60` gives the UI thread (TID = PID) average. See
+ [quickstart.md](quickstart.md) § 4.
+- **Paint and card-build time**: an opt-in probe (`NOTA_UI_PROBE=aurora`). Stopwatch ticks go
+ into a fixed ring in `AuroraTableView.Render`, and the time from track selection to the
+ card's first render is measured in `DeviceChainView`. It logs p50 / p99 every 10 s to
+ stderr and costs nothing when off.
+- **Audio**: `nota_perf aurora-supersaw-2x` and the new `aurora-imported-2x`; `--aurora-null`
+ for bit-identity.
+- Results go into `specs/053-aurora-one-card/perf-baseline.md`, in the same table format as
+ `036-aurora-perf/baseline-env.md`.
+
+### Layout at 1050 (if FR-005 is answered "Wide")
+
+Only `AuroraInstrumentCard.cs` and `AuroraTableView` sizes change:
+
+- `CardWidth` becomes 1050;
+- the centre panel grows to about 788 px, so each column is about 391 px;
+- the type and warp selectors go back to inline segment chips (4 + 5 cells, as today);
+- each window becomes about 150 × 86, beside its knob grid;
+- the knobs grow to 36 with full labels.
+
+The engine, ABI, persistence, measurement and tasks for US2–US4 do not change. T019, T020 and
+T024 change their numbers, and DESIGN.md's Aurora note moves from L to Wide.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/053-aurora-one-card/
+├── spec.md
+├── plan.md # this file
+├── research.md # Phase 0 decisions R1–R12
+├── data-model.md # AuroraTable, table set, blob trailer, DTOs, scope layout
+├── quickstart.md # validation runs, incl. the UI CPU measurement
+├── contracts/
+│ ├── c-abi.md # new nota_engine.h functions
+│ ├── state-blob.md # WavetableSynth state trailer v1
+│ ├── persistence.md # project v28 + preset fields
+│ └── ui-osc-tab.md # Osc tab layout and states at 700 (and 1050 delta)
+├── checklists/requirements.md
+├── perf-baseline.md # written during implementation (T005, T045)
+└── tasks.md
+```
+
+### Source Code (repository root)
+
+```text
+src/native/nota.engine/
+├── include/nota/nota_engine.h # + Aurora table ABI (contracts/c-abi.md)
+├── CMakeLists.txt # + AuroraTable.cpp (list at :171)
+└── src/
+ ├── devices/instruments/AuroraTable.h/.cpp # NEW: build, condition, mips, hash
+ ├── devices/instruments/WavetableSynth.h/.cpp # table set, custom reader, state trailer, scope
+ ├── engine/Engine.h, Engine_Devices.cpp # auroraSetTable / Clear / Source / Missing / queries
+ ├── devices/racks/RackCore.cpp # (no change: child getState carries the trailer)
+ └── abi/nota_engine_track.cpp, nota_engine_import.cpp, nota_engine_rack.cpp
+src/managed/
+├── Nota.Application/Engine/IAudioEngine.cs # + Aurora table members
+├── Nota.Application/Instruments/Aurora/AuroraTableImporter.cs # NEW
+├── Nota.Infrastructure/Interop/NativeMethods.Tracks.cs, NotaEngine.Tracks.cs
+├── Nota.Infrastructure/Persistence/ProjectModel.cs, ProjectService.cs, ProjectMigrations.cs,
+│ PresetModel.cs, PresetService.cs, BundleContent.cs
+└── Nota.App/
+ ├── DeviceCards/Instruments/AuroraInstrumentCard.cs # Osc tab rebuilt
+ ├── Controls/AuroraTableView.cs # NEW (AuroraStack's successor)
+ ├── Controls/AuroraStack.cs # shape cache kept, view removed
+ ├── DeviceCards/Rack/RackCardView.cs # proxy engine forwards the new calls
+ └── DeviceChainView.Instruments.cs # opt-in probe hook
+tests/
+├── Nota.SmokeTest/AuroraTableTests.cs # NEW
+├── Nota.SmokeTest/AuroraNullTests.cs # unchanged gate, re-run
+├── Nota.SmokeTest/Fixtures/ # generated test tables (written at run time)
+└── perf/nota_perf.cpp # + aurora-imported-2x
+```
+
+**Structure Decision**: The change goes into the existing engine instrument, the C ABI, the
+Infrastructure persistence and the App card. The one new engine file pair isolates table
+building (pure, any-thread) from the DSP class. The one new managed service keeps
+file / threading logic out of the card.
+
+## Complexity Tracking
+
+No constitution violations. Two choices add weight on purpose:
+
+| Choice | Why needed | Simpler alternative rejected because |
+|---|---|---|
+| Tables stored twice by shape (self-contained blob trailer **and** bundle `samples/` for top-level tracks) | FR-014 asks for storage once across Auroras and project versions, and racks, clones and copy/paste need self-contained state | Blob only: no dedup across instances (2–4 MB per copy). `samples/` only: rack chains and device copy/paste would lose the table |
+| Two hand-over paths (republish for edits, `SnapshotHistory` for in-place `setState`) | Undo comes from graph snapshots (AR-5). `setState` is called in place on the live instrument (`Engine_Devices.cpp:1644-1650`) | Republish only: in-place preset or state loads would race. History only: no undo without a custom undo entry |
diff --git a/specs/053-aurora-one-card/quickstart.md b/specs/053-aurora-one-card/quickstart.md
new file mode 100644
index 00000000..9be5cb72
--- /dev/null
+++ b/specs/053-aurora-one-card/quickstart.md
@@ -0,0 +1,126 @@
+# Quickstart: validating Aurora one card and custom wavetables
+
+**Feature**: `053-aurora-one-card` | **Date**: 2026-10-29
+
+Commands run from the repo root. Performance numbers (§ 4, § 5) count only on the **036
+reference machine** (i7-12700, Linux, performance governor;
+`specs/036-aurora-perf/baseline-env.md`). Record them in `perf-baseline.md` in this folder.
+
+## 0. Build and gates
+
+```sh
+scripts/build-linux.sh # native + managed + smoke test (macOS: scripts/build.sh)
+dotnet run --project tests/Nota.SmokeTest -- --aurora-null # 036 sound gate: factory presets bit-identical
+dotnet run --project tests/Nota.SmokeTest -- --aurora-tables # this feature's ABI-level tests
+```
+
+Expected:
+
+- all green;
+- `--aurora-null` reports −240 dBFS (bit-identical) for the ten presets, as in
+ 036 baseline-env;
+- `--aurora-tables` covers the [c-abi](contracts/c-abi.md) and
+ [state-blob](contracts/state-blob.md) contracts.
+
+## 1. One card (US1)
+
+1. `dotnet run --project src/managed/Nota.App`, add Aurora, and load the factory preset
+ **Glacier Pad** (both oscillators on).
+2. On the Osc tab, check that both windows, both type and warp selectors and 2 × 6 knobs are
+ visible, and that there is no "1 / 2" switch ([ui-osc-tab](contracts/ui-osc-tab.md)).
+3. Change Osc 2 to Chroma. Only Osc 2's window and sound change.
+4. Switch Osc 2 off. Its column takes the unavailable look, and nothing moves.
+5. Open a project saved by the base build. The same values show, and the 036 null gate
+ (§ 0) is green.
+6. Do steps 2–4 in Studio Dark and Studio Light, and at Interface scale 100 % and 150 %.
+ Nothing overlaps (DESIGN.md § Graphs, "room for the words").
+
+## 2. Import (US2)
+
+Fixtures are written by `dotnet run --project tests/Nota.SmokeTest -- --aurora-fixtures <dir>`:
+
+| File | Expect |
+|---|---|
+| `cycle-2048.wav` (one saw cycle) | 1 frame. Caption "1 frame". Plays at the note's pitch |
+| `table-64x2048.wav` (`clm ` chunk) | 64 frames. Position sweeps through all of them |
+| `table-300x2048.wav` | 256 frames, with the notice "first 256 frames" |
+| `vowel-2s.flac` (stereo) | 16 frames (recording), morphing along the file |
+| `long-90s.mp3` | 16 frames from the first 60 s, with the notice "shortened to 60 s" |
+| `silence.wav` | refused: "This file is silent". The oscillator is unchanged |
+| `broken.wav`, `x.aiff` | refused with the format message. The picker does not list AIFF |
+
+For each file: drop it onto Osc 1's column, then use Osc 2's Import… for the next one.
+Check that:
+
+- the other oscillator is unaffected;
+- Undo restores the previous table, and Redo re-applies it;
+- picking a built-in and then the import name again switches back with notes still
+ sounding.
+
+Persistence:
+
+1. Save the project as `t.nota`. Move the fixture folder away, then close and reopen.
+ The sound is the same; render the same bar before and after for SC-007.
+2. Look in `t.nota/samples/`: an identical table used by two Auroras is one file.
+3. Delete one `samples/<hash>.wav` and reopen. The warning names the track, the oscillator
+ and the file; the selector reads "Missing: <name>"; the oscillator plays its built-in
+ table.
+4. Save a user preset from an Aurora with a 256-frame table, then load it on a new track and
+ on a second machine. The table travels with it. Then load a factory preset: both
+ oscillators return to built-in tables.
+5. Put the Aurora into an Instrument Rack chain and onto a Drum Rack pad, duplicate the
+ track, copy and paste the device, and save and reopen. The table survives each step.
+
+## 3. Audio behaviour
+
+- **Click-free loops.** Hold C3 with each imported table and sweep Position. There is no
+ click at the loop point, and no DC thump on note-on.
+- **Aliasing.** Play `table-64x2048.wav` (bright frames) at C7 with Warp Off. Compare it
+ with the built-in Chroma table at a similar brightness: there are no audible fold-back
+ tones. The smoke test also checks the alias energy, at most −60 dB (T028).
+- **Import during playback.** Play a chord loop and drop a table onto Osc 2. There is no
+ dropout (the xrun counter stays at 0). Held notes may stop, which is the Mosaic
+ precedent.
+- **Memory.** Import ten 256-frame tables in a row. Process RSS rises by about 4 MB per
+ undo step kept, and stays flat after clearing undo history.
+
+## 4. UI CPU budget (US3, SC-003 / SC-004 / SC-005)
+
+```sh
+dotnet run --project tests/Nota.SmokeTest -- --aurora-ui-fixture /tmp/aui # v28 scenario
+dotnet run --project tests/Nota.SmokeTest -- --aurora-ui-fixture /tmp/aui --builtin # v27 baseline
+```
+
+The fixture holds 4 Auroras, each with both oscillators on 256-frame generated tables (the
+baseline uses Formant and Chroma instead). LFO 1 → Osc 1 position and LFO 2 → Osc 2 position
+run at 2 Hz, over a 4-bar 6-note chord loop.
+
+1. **Baseline**: the base build opens `/tmp/aui/baseline.nota`, with the Aurora card on the
+ Osc tab and playback looping. After 10 s of warm-up:
+ ```sh
+ pidstat -t -p $(pgrep -f Nota.App | head -1) 1 60 > base.txt
+ ```
+ Average the `%CPU` of the row whose TID equals the PID (the UI thread).
+2. **Feature**: the feature build opens `/tmp/aui/scenario.nota` the same way, with
+ `NOTA_UI_PROBE=aurora` set:
+ ```sh
+ NOTA_UI_PROBE=aurora dotnet run -c Release --project src/managed/Nota.App -- /tmp/aui/scenario.nota 2> probe.txt
+ pidstat -t -p <pid> 1 60 > feat.txt
+ ```
+3. **Pass**:
+ - the UI thread in `feat.txt` is at most the `base.txt` value + 2.0 points, and the
+ card's share is at most 5 % (SC-003);
+ - `probe.txt` "aurora paint p99" is at most 2.0 ms (SC-004);
+ - clicking through the 4 Aurora tracks, "aurora card build→first paint" is at most
+ 100 ms, and the longest UI frame is at most 50 ms (SC-005).
+ Run everything twice; the runs agree within ±10 %.
+4. **Hidden**: minimise the window for 30 s. The probe reports 0 paints (FR-018).
+
+## 5. Audio cost (SC-006)
+
+```sh
+cmake -G Ninja -S tests/perf -B build/perf-tools -DCMAKE_BUILD_TYPE=Release
+cmake --build build/perf-tools --target nota_perf
+./build/perf-tools/nota_perf run aurora-supersaw-2x 30 # within ±10 % of ~28 ms/s (036)
+./build/perf-tools/nota_perf run aurora-imported-2x 30 # ≤ 1.10 × aurora-supersaw-2x
+```
diff --git a/specs/053-aurora-one-card/research.md b/specs/053-aurora-one-card/research.md
new file mode 100644
index 00000000..2fa819cd
--- /dev/null
+++ b/specs/053-aurora-one-card/research.md
@@ -0,0 +1,296 @@
+# Research: Aurora one card and custom wavetables
+
+Phase 0 of [plan.md](plan.md). Each entry gives the decision, the reason and the
+alternatives. Code references are to `ui/style-guide` at cc1531b6 plus the spec commit 41bd30d3.
+
+## R1. How a custom table reaches the audio thread
+
+**Decision**: An immutable `AuroraTableSet`, holding both slots plus their "missing" names,
+is owned by `SnapshotHistory<const AuroraTableSet>` inside `WavetableSynth`. It is changed in
+one of two ways:
+
+- **Undoable edits** (import, remove) clone the instrument, publish the new set on the
+ clone, and republish the track through `Engine::republishWithTrack`
+ (`Engine.cpp:685-688`). Undo swaps the graph back (`Engine.cpp:694-714`), and the old
+ instrument still holds the old set.
+- **In-place changes**: `setState` from a live preset load, a rack restore or a project
+ replay, and "missing" metadata. These build a new set on the message thread and
+ `publish()` it into the history.
+
+`SnapshotHistory` retires the old pointer with the render epoch and frees it only after
+two later renders, on the message thread (`SnapshotHistory.h:4-14, 33-43`). `render()`
+holds a `RenderScope` and reads `live()` once per block.
+
+**Rationale**: AR-5 / AR-6. This is the same pattern Rhythm uses for voice samples
+(`Engine_Devices.cpp:328-343`) and racks use for chains. `Engine::setPluginState` calls
+`instrument->setState` in place on the live instrument (`Engine_Devices.cpp:1644-1650`), so a
+plain `shared_ptr` member swap there would race the audio thread. The history removes that
+race without a lock.
+
+**Alternatives**:
+
+- `std::atomic<std::shared_ptr>`: may lock on some standard libraries, and the last
+ reference could drop on the audio thread.
+- A lock-free command-queue message carrying a pointer (AR-4): still needs a retirement
+ scheme, which the history already provides.
+- Republish for every change: would make preset loads stop notes, and `setState` callers
+ do not republish.
+
+## R2. Undo granularity and held notes
+
+**Decision**:
+
+- Import and remove: one undo step each, via republish. Sounding notes stop, as with Mosaic's
+ checkpointed program change (`nota_engine.h:705-709`).
+- Switching an oscillator between its imported table and a built-in (FR-010): an in-place
+ relaxed `std::atomic<uint8_t>` store, read per block. Notes keep sounding, and it is not an
+ undo step.
+
+**Rationale**: The spec allows notes to stop on import (Edge Cases). The spec does not
+require undo for the source switch, and that switch is a performance gesture.
+
+**Alternatives**:
+
+- A hidden appended plugin parameter for the source: it would become automatable (no
+ non-automatable flag exists in `Instrument.h`), which contradicts the spec Assumption.
+- In-place import keeping notes: no graph undo entry, so FR-013 would need a bespoke undo
+ type in `Engine`.
+
+## R3. Table building and conditioning
+
+**Decision**: These are pure functions in `AuroraTable.cpp`, safe on any thread. They touch
+no engine state, like `nota_audio_import` (`nota_engine.h:613-631`).
+
+1. Decode with `decodeAudioFile` (`AudioFile.cpp:73`). Mix to mono by channel average, as
+ `nota_file_decode_mono` does (`nota_engine.h:718-721`). Keep only the first 60 s × the file
+ rate, and set `truncatedLength`.
+2. Classify the file:
+ - **(a) Standard wavetable file.** A WAV `clm ` chunk gives the frame size; read it if
+ present. Otherwise the length is a multiple of 2048 and at least 2 × 2048. If the
+ declared frame size is not 2048, each frame is resampled to 2048 periodically by FFT.
+ Keep at most 256 frames and set `truncatedFrames`.
+ - **(b) Single cycle.** Length ≤ 4096 and not (a). Resample one period to 2048 by FFT
+ (zero-pad or truncate the spectrum): exact for a periodic signal, no pitch detection.
+ - **(c) Recording.** Otherwise, 16 windows of 2048 samples. Window *i* is centred at
+ `i × (L − 2048) / 15`, then snapped to the nearest upward zero crossing within ±1024
+ samples (or kept where it is if there is none). There is no resampling and no pitch
+ detection (Clarification 1).
+3. For each frame:
+ - subtract the mean (DC);
+ - for (c), blend the last 32 samples into the first 32 with an equal-power crossfade so
+ the frame loops without a click. For (a) and (b) the stored cycle is kept as is,
+ because those are already periodic.
+4. Normalise per table to a peak of 1.0, the built-in tables' level
+ (`WavetableSynth.cpp:739-741` normalises each built-in frame to 1.0). Relative frame
+ levels are kept. Refuse the file if its peak before normalising is below −60 dBFS.
+5. Build mips (R4) and compute the content hash (128-bit, over the base-level float bytes,
+ matching `BundleContent`'s 128-bit SHA-256 prefix, `BundleContent.cs:4-9`).
+
+**Rationale**: These rules follow the spec rules in FR-009 and the clarification. The
+FFT already exists (signalsmith-linear). A file declaring frames with a `clm ` marker is the
+common wavetable-file convention.
+
+**Alternatives**: pitch-detected cycles were rejected by Clarification 1; linear-interpolation
+resampling adds roll-off and aliasing.
+
+## R4. Band-limiting (mip levels)
+
+**Decision**: Six levels, k = 0…5. Level k has length `2048 >> k` and keeps harmonics
+≤ `1024 >> k`, made by FFT truncation of each base frame. Memory is about 2 × base, so at
+most about 4 MB per 256-frame table.
+
+Per voice per block, pick the smallest k with
+`(1024 >> k) × f_max ≤ 0.45 × sr`, where `f_max = f0 × max unison detune factor × warpBias`:
+
+- warpBias is 1 for Off, PWM and Fold;
+- for Sync it is `1 + 7 × warp`;
+- for Bend it is `1 + 3 × warp`.
+
+Clamp k to 5. `readMorphSized(t0, t1, ff, phase, len)` masks with `len − 1`.
+
+Built-in tables are untouched: they keep at most 64 harmonics with no mips, read by
+`readMorph` (`WavetableSynth.h:281-290`, `.cpp:717-743`), so FR-006 holds bit for bit.
+
+**Rationale**: FR-011 asks for "no more aliasing than a built-in of similar brightness". An
+imported frame may hold up to 1024 harmonics, so it must be filtered by pitch. Halving the
+length per level keeps memory bounded and the reader simple.
+
+**Alternatives**:
+
+- Full-length 2048 tables at every level: 8–11 × memory (about 22 MB per table).
+- Oversampling the oscillator: CPU cost on every voice, which would break SC-006.
+- A crossfade between levels: doubles the reads. It is deferred, and a level change only
+ happens when pitch changes (risk logged in plan, R12).
+
+## R5. State blob layout
+
+**Decision**: The parameters stay first (156 floats). An optional trailer, `"AWT1"`
+section + `u32 size` + `"AWT1"`, goes at the very end
+([contracts/state-blob.md](contracts/state-blob.md)). It holds the source flags, the missing
+names and each slot's base frames (mips are rebuilt on load), and a "same as slot 0" flag
+when both slots hold the same hash.
+
+`setState` finds the trailer from the end, so future appended parameters still parse.
+With no table, no source flag and no missing name, the blob is byte-identical to today's
+(`WavetableSynth.cpp:227-234`).
+
+**Rationale**:
+
+- The existing reader takes `min(kNumParams, size/4)` floats (`:236-244`), so a trailer never
+ disturbs the parameters.
+- Racks embed child state blobs (`RackCore.cpp:661-663`), so tables survive racks with no
+ rack change.
+- Clones and device copy/paste go through state or `clone()`.
+
+**Alternatives**: a separate side-channel ABI for racks, as the Sampler payload v3
+(`RackCore.cpp:664-674`) does, means more rack format churn.
+
+## R6. Project persistence and dedup
+
+**Decision**:
+
+- **Top-level Aurora tracks.** `ProjectService` saves the blob via
+ `nota_track_aurora_state(include_tables = 0)`. Each present table is written as
+ `samples/<hash>.wav`: float32 mono, 2048 × N, with a `clm ` marker, so it is itself a
+ standard wavetable file. It is listed in `InstrumentDto.Wavetables` as
+ `{ Osc, Sample, Name, Origin, Frames, UseCustom, Missing }`. Save registers it like other
+ samples (`ProjectService.cs:1067-1080` `RegisterSample` analogue), which gives dedup
+ across Auroras and across history versions (`ProjectHistory.cs:4-18`).
+- **Load.** `SetPluginState` the blob, then decode each WAV raw (no re-conditioning:
+ `nota_aurora_table_from_frames`), then `AuroraSetTable` without an undo checkpoint (the
+ load path is not undoable). A missing or unreadable file becomes a warning in the existing
+ style ("Couldn't reload…", `ProjectService.cs:582, 662`) plus `AuroraSetMissing`.
+- **Format.** `CurrentFormatVersion` 27 → 28 (`ProjectService.cs:40`), with a no-op
+ migration (an absent `Wavetables` means none; `ProjectMigrations.cs:25-50`).
+- **Racks.** Auroras inside racks rely on the blob trailer: no cross-instance dedup there,
+ but the rack blob itself is content-addressed.
+
+**Rationale**: This meets FR-014 for the common case. Reload is bit-identical (SC-007)
+because the stored frames are the conditioned frames and the reload path skips
+conditioning. Float32 WAV round-trips exactly through dr_wav.
+
+**Alternatives**:
+
+- Store the source audio and re-import on load: not bit-stable across builder changes, and
+ larger.
+- Blob only: no dedup.
+
+## R7. Presets
+
+**Decision**: `PresetDocument.AuroraTables` holds a list of
+`{ Osc, Name, Origin, Frames, UseCustom, Data }`, where `Data` is base64 of
+little-endian float32 base frames. It is written by `PresetService` when an Aurora has a
+table, and applied after the parameters on load (the `MosaicProgram` pattern,
+`PresetService.cs:62, 313-324`; `PresetModel.cs:47-49`).
+
+Loading a preset without the field clears both custom tables and sets the source to
+built-in (FR-015). That is one combined undoable step, together with the preset's parameter
+change.
+
+**Rationale**: Presets are single JSON files that must travel between machines. A 16-frame
+table is about 175 KB of base64; a 256-frame one is about 2.8 MB, which is acceptable for a
+user preset.
+
+**Alternatives**: a sidecar file next to the preset would break the one-file preset contract
+and the preset library index.
+
+## R8. Live follow telemetry (US4)
+
+**Decision**: `WavetableSynth::scopeRead` returns 5 floats:
+
+- `[0]`, `[1]`: the played position (0..1) of Osc 1 / Osc 2 for the most recently started
+ sounding voice, including matrix, macro and MPE modulation, or −1 when no voice sounds;
+- `[2]`, `[3]`: table serials (a change means the UI should refetch the preview);
+- `[4]`: active voice count.
+
+These are relaxed atomic floats written once per block (the Keys pattern, `Keys.h:199-215`,
+`Keys.cpp:60`). They are read by the existing `nota_track_instrument_scope`
+(`nota_engine.h:1081-1083`).
+
+**Rationale**: No new channel is needed, and the cost is 5 stores per block.
+
+**Alternatives**: a per-voice position array is more data for no visible gain, since one lit
+frame is drawn.
+
+## R9. UI drawing cost
+
+**Decision**:
+
+- `AuroraTableView` keeps the per-process built-in shape cache (`AuroraStack.cs:47-49, 86-115`).
+- For imported tables it fetches a **preview** once per table serial: up to 16 representative
+ frames plus a 64-frame lit grid, 96 points each, through `nota_track_aurora_table_preview`,
+ cached per (track, osc, serial).
+- It caches the `StreamGeometry` of each drawn frame per (source, bounds). Today they are
+ rebuilt on every paint (`AuroraStack.cs:138-152`).
+- A repaint is at most 17 `DrawGeometry` calls plus the window chrome.
+- `Set` invalidates only when the quantised lit index (of the 64-grid), the source, the dim
+ state or the bounds change.
+- The live tick reads the scope (one P/Invoke of 5 floats) before the `ParamsMoved` gate
+ (`AuroraInstrumentCard.cs:151-166`). Card readouts update only when parameters moved.
+
+**Rationale**: FR-018 and FR-019. The cost is independent of frame count. In the worst case
+(both positions moving every tick) that is 2 × 30 repaints/s of 17 cached geometries, well
+under the 2 ms p99 budget.
+
+**Alternatives**: rendering the stack to a bitmap per lit frame trades memory for little
+gain, and bitmaps need re-rendering on theme and scale changes.
+
+## R10. Osc tab layout at 700 (FR-005 still open)
+
+**Decision**: The centre body is 438 × 166 px (`AuroraInstrumentCard.cs:51`, `DeviceGap` 5 at
+`NotaGeometry.cs:70`). It is split into two 216 px columns with a 6 px gap. Each column has:
+
+- a header row of 20: name, on switch, a type drop-down of about 96 px, a warp drop-down of
+ about 64 px (drop-down 22 high, `DESIGN.md:521-537`);
+- a 3 px gap;
+- the window, 216 × 60;
+- a 3 px gap;
+- a knob row of 54: six 34 px knobs (`KnobSecondary`, `DESIGN.md:530`) in 36 px cells.
+
+The shared sub / unison row (22) spans both columns. That gives 20 + 3 + 60 + 3 + 54 + 22 =
+162 ≤ 166. The window caption uses the graph title row (`NotaGraph.PlotTop` 22,
+`DESIGN.md:813-818`) on one line: "Formant · 5/16 · lfo 1 → pos".
+
+Under 1050 (if chosen): columns of about 391 px, inline segment chips, windows of about
+150 × 86 beside the knob grid ([plan.md](plan.md) § Layout at 1050).
+
+**Rationale**: The default is the current card size, with no change to the device panel
+height or width rules (`DESIGN.md:983-993`, 038 FR-025). The layout code is isolated so the
+1050 answer is a sizing change.
+
+**Alternatives**: hiding the rail on the Osc tab (the rail holds Global and the meter, which
+the card always shows); a vertical stack of the two oscillators (the window would be under
+40 px tall).
+
+## R11. UI CPU measurement method
+
+**Decision**:
+
+- **Machine**: the 036 reference machine (i7-12700, Linux, performance governor,
+ `036-aurora-perf/baseline-env.md:6-13`).
+- **Fixtures**: generated by a smoke-test helper (`--aurora-ui-fixture`): a scenario fixture
+ (v28) and a baseline fixture (v27, built-in tables, the same LFO routing) that today's
+ build opens.
+- **UI thread CPU**: `pidstat -t -p <pid> 1 60`, averaged for TID = PID (the Avalonia UI
+ thread), which is the linux-idle-cpu method (`.specify/bugs/linux-idle-cpu/assessment.md:27`).
+- **Paint and card-build times**: the opt-in `NOTA_UI_PROBE=aurora` probe (p50 / p99 over
+ 10 s windows).
+- Each run happens twice; runs must agree within ±10 %, as in 036 SC-004.
+
+**Rationale**: It is repeatable, uses the project's existing methods, and compares like
+with like (the same project shape on old and new cards).
+
+**Alternatives**: `dotnet-counters` (process-wide only, so the audio threads blur it).
+
+## R12. Risks
+
+| Risk | Mitigation |
+|---|---|
+| Held notes stop on import (republish) | Spec accepts it. The importer applies at once, and the card says "loaded" |
+| Undo stack and retired graphs keep old tables alive (up to about 4 MB each) | Bounded by undo depth. Noted in the CHANGELOG. Re-check memory with 10 imports in quickstart § 3 |
+| Mip pick under Sync / Bend warp still aliases at extreme settings | A warp bias in level selection. A quickstart listening check plus a smoke spectral check (energy above Nyquist folding ≤ −60 dB at C7 for a bright table, Warp Off) |
+| A level jump is audible during pitch bends | Pick on the block's highest increment; add an adjacent-level crossfade only if listening shows it |
+| 700 layout too tight (knob row exactly 216 px, drop-downs instead of chips) | FR-005 is still open. The 1050 delta is planned |
+| Rack-hosted Aurora import goes through the proxy engine | Dedicated task, with rack-chain ABI variants |
+| Preset JSON of about 2.8 MB for 256-frame tables | Acceptable. Tested for load time in quickstart § 3 |
+| Built-in sound regression | The built-in branch stays untouched. The `--aurora-null` gate runs in the smoke test |
diff --git a/specs/053-aurora-one-card/spec.md b/specs/053-aurora-one-card/spec.md
new file mode 100644
index 00000000..9b241ea3
--- /dev/null
+++ b/specs/053-aurora-one-card/spec.md
@@ -0,0 +1,485 @@
+# Feature Specification: Aurora, both wavetables on one card, and custom wavetables from samples
+
+**Feature Branch**: `feat/aurora-one-card` (based on `ui/style-guide`)
+
+**Created**: 2026-10-29
+
+**Status**: Draft
+
+**Input**: Egor's review of the Aurora card: "In Aurora, switching between wavetables (1 and 2)
+is actually quite inconvenient. It might be worth trying to combine both wavetables into a
+single card — incorporating two visualizations, two type selectors, and all the necessary
+knobs. The only concern is performance, as rendering this proved to be quite heavy in the
+past. Also, it's essential to add the ability to import custom samples."
+
+## 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
+- [x] UI (Avalonia, `src/managed/Nota.Presentation`) — follow `DESIGN.md` (Studio)
+- [ ] Plugin hosting (`pluginhost/`) — the only place JUCE is allowed
+- [ ] Build / packaging / CI (`scripts/`, `.github/`) — see `BUILD.md`
+- [ ] Docs only
+
+The main area is the UI (the Osc tab of the Aurora card). Custom wavetables also touch the
+engine (a table that is not one of the four built-in banks) and project / preset persistence.
+
+**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).
+
+### What Aurora does today (ui/style-guide at cc1531b6)
+
+**The card.** 700 × 260 (`AuroraInstrumentCard.cs:49`, `DeviceCardKit.cs:22`): a 56 px
+wheels column, a centre panel with six tabs (Osc, Filter, Env, LFO, Mod, FX) and a 186 px
+rail (Global / Macros) (`AuroraInstrumentCard.cs:51-53`). That leaves about 438 px × 166 px
+for a tab's body (700 − 2 × 5 margin − 56 − 186 − 2 × 5 gaps; body 186 − tab row 20).
+
+**How switching works.** The Osc tab already shows both oscillators' knob rows: name and
+on/off, Position, Warp, Level, Oct, Semi, Fine (`AuroraInstrumentCard.cs:444-479`). What is
+shared, and therefore switched, is:
+
+- one table window, 128 px wide, drawing only the picked oscillator's table
+ (`AuroraInstrumentCard.cs:534`, fed at `:168-169`);
+- one strip on top that holds the bank chips (Analog / Pulse / Formant / Chroma) and the
+ warp-mode chips (Off / Sync / Bend / PWM / Fold) of the picked oscillator only
+ (`:423-442`, shown or hidden by `applyOsc` at `:480-487`).
+
+You pick the oscillator with a "1 / 2" segment (`:431`) or by clicking its name (`:465-469`).
+So to see or change Osc 2's table you first switch the strip and the window away from
+Osc 1, and the two tables are never on screen together. The window's caption names the
+table, the frame ("frame 5/16") and what modulates position (`:509-526`). The sub and
+unison values sit in one row under both oscillators (`:489-507`).
+
+**The table window and its performance history.** `AuroraStack` draws the 16 frames as a
+skewed 3-D pile, the frame Position lands on in bright ink (`Controls/AuroraStack.cs:4-8`).
+It does not read the engine: it rebuilds the shapes from its own copy of the bank recipe,
+with fewer harmonics (`:6-7`, `:77-84`). It used to rebuild those shapes inside every paint:
+"thirty thousand sines and a thousand line segments on every one of the thirty ticks a
+second the device panel runs, which is what made switching to an Aurora track stutter"
+(`:9-13`). The fix computes all four banks' frames once per process and shares them across
+cards (`:47-49`, `:86-115`). Each frame is now drawn as one geometry (`:118-153`), and the
+window only repaints when the bank or the frame changes (`:66-75`). On the card, the
+30-per-second live tick (`AuroraInstrumentCard.cs:1171`, driven from
+`DeviceChainView.Instruments.cs:120-126`) first checks whether any of the 156 parameters
+moved and returns at once if none did (`AuroraInstrumentCard.cs:147-176`). The window does
+not follow modulation: it shows the set Position, not the position being played.
+
+`specs/036-aurora-perf` was about Aurora's **audio** CPU, not the UI. It measured offline
+render cost with `tests/perf/nota_perf.cpp` (scenario `aurora-supersaw-2x`, `:195`), on a
+fixed reference machine (i7-12700, Linux, `036-aurora-perf/baseline-env.md:6-13`), with a
+null test for "same sound" (036 FR-003). The result was about 28 ms of render per second of
+audio (`baseline-env.md:21`). UI CPU in this project has been measured per thread with
+`top -H` / `pidstat` (`.specify/bugs/linux-idle-cpu/assessment.md:27`, `fix.md:77`), and as
+"UI CPU within N % of a baseline" (`specs/017-live-midi-record-notes/spec.md:176`).
+
+**Engine.** `WavetableSynth` (kind 5) has 4 built-in banks × 16 frames × 2048 samples
+(`WavetableSynth.h:195`), generated once per process from an additive recipe with at most
+64 harmonics, each frame normalised to its own peak (`WavetableSynth.cpp:705-743`). The
+banks are shared, read-only, by every instance (`WavetableSynth.h:16-18`, `:291-295`).
+Playback blends neighbouring frames (`readMorph`, `WavetableSynth.h:281-290`). A table is
+picked by a normalised parameter rounded to four steps (`bankOf`, `WavetableSynth.h:226`):
+`table` and `osc2table`, Analog 0 / Pulse .333 / Formant .667 / Chroma 1
+(`FactoryPresetCatalog.cs:178`). The parameter order is the saved layout, append-only
+(`WavetableSynth.h:19`). The instrument's state is just the 156 parameter values
+(`WavetableSynth.cpp:227-244`), and `clone()` copies only those (`:246-252`). Aurora has no
+scope or telemetry output today.
+
+**Sample infrastructure to reuse.**
+
+- Decoding: WAV, FLAC and MP3 through dr_libs (`src/media/AudioFile.cpp:29-73`,
+ `LICENSES/third-party.md:19`). The managed side lists the same three as the formats the
+ engine decodes (`SampleIndex.cs:18-21`). There is already a call that decodes a file's
+ head as mono (`nota_file_decode_mono`, `nota_engine.h:718-721`), and a background,
+ block-by-block import job (`nota_engine.h:613-631`).
+- Loading a sample into an instrument: Sampler, Grain and Rhythm voices take a file path
+ (`nota_engine.h:727`, `:778-780`). Rhythm's card shows the two entry points to copy: a
+ file picker (`RhythmInstrumentCard.cs:205-218`) and dropping from the browser onto a
+ target, with a hover highlight (`:220-235`, `BrowserView.IsAcceptableDrag` /
+ `DroppedItems`). Rhythm's picker also lists AIFF and OGG (`:211`), which the engine does
+ not decode.
+- With the project: a `.nota` bundle embeds every referenced sample as `samples/<hash>.wav`.
+ The name is content-addressed and deduplicated, shared by every version in the project
+ history (`ProjectService.cs:4-8`, `BundleContent.cs:4-9`, `ProjectHistory.cs:4-18`).
+ Rhythm is the closest precedent: its state blob holds flags and its per-voice samples
+ are saved next to it (`ProjectService.cs:155-167`) and reloaded with a warning on failure
+ (`:661-666`). Aurora today saves only its state blob (`ProjectService.cs:150-153`).
+- Missing audio: the load path warns ("Couldn't reload…", `ProjectService.cs:582`,
+ `:662`; "A referenced sample was missing and was skipped.", `:1075`), and Mosaic's card
+ shows a missing panel ("Samples unavailable · notes muted",
+ `MosaicInstrumentCard.cs:448-507`, `:1171`).
+- Format version: projects are at version 27 (`ProjectService.cs:40`). A new field is a
+ version bump with a no-op migration (`ProjectMigrations.cs:25-50`). Presets store
+ instrument values by parameter id (`PresetModel.cs:30-34`), with optional extra payloads
+ for sample-based instruments (Grain source, Mosaic program, `PresetModel.cs:35-49`).
+- Undo: Mosaic's program change is one undo step that republishes the instrument
+ (`nota_engine.h:705-709`). Structural edits publish a new graph snapshot (AR-5).
+
+**Design rules.** Cards are 260 high with fixed widths S 260 / L 700 / Wide 1050
+(`specs/038-style-guide/spec.md:430`, `DESIGN.md:529`). A card keeps its layout unless a
+layout change is decided on its own; this spec is that decision (`DESIGN.md:1175-1178`). Tab
+rows, graphs (one `NotaGraph` window: `SurfaceInset` ground, a `Rule` frame, a title top
+left, corner labels, no fills under curves, room for the words) and the interaction
+contract are set out in `DESIGN.md:674-682` and `:795-855`. Values are orange; there are no
+identity colours, so the two oscillators are told apart by shade and label
+(`DESIGN.md:1163-1165`, 038 US acceptance 6). Units take a thin space (`DESIGN.md:460`).
+
+## Clarifications
+
+### Session 2026-10-29
+
+- Q: How is a longer recording cut into frames? → A: 16 evenly spaced 2048-sample windows
+ aligned to zero crossings, no pitch detection.
+- Q: Does each window follow the modulated position live? → A: Yes; the performance budget
+ covers both windows following live.
+- Q: Does the card stay 700 wide or move to the Wide 1050 size? → A: Stays 700 wide.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - See and shape both oscillators at once (Priority: P1)
+
+A sound designer builds a pad from two tables: Formant on Osc 1, Analog on Osc 2. On the
+Osc tab they see both tables side by side, each with its own type selector, warp mode and
+knobs. They sweep Osc 2's Position while watching Osc 1 stay put, without any 1 / 2
+switching.
+
+**Why this priority**: This is the reported problem. It is useful on its own, with no
+import feature.
+
+**Independent Test**: Open any two-oscillator factory preset (e.g. Glacier Pad). Without
+clicking anything, check that the card shows both tables, both type selectors, both warp
+modes and all six knobs per oscillator. Change each one and check that only its own
+oscillator changes.
+
+**Acceptance Scenarios**:
+
+1. **Given** an Aurora on the Osc tab, **When** the card is shown, **Then** two table
+ windows are visible at once, labelled Osc 1 and Osc 2. Each shows its own table type, its
+ current frame and what modulates its position. There is no "1 / 2" switch.
+2. **Given** both oscillators are visible, **When** the user picks Chroma in Osc 2's type
+ selector, **Then** only Osc 2's window and sound change, and Osc 1's selector still
+ reads its own table.
+3. **Given** Osc 2 is switched off, **When** the card is shown, **Then** Osc 2's window and
+ controls take the unavailable look and stay where they are. Switching it on again needs
+ one click.
+4. **Given** a project saved before this feature, **When** it is opened, **Then** every
+ Aurora sounds bit-identical and shows the same table, warp mode and knob values as
+ before.
+5. **Given** the new layout, **When** any Osc control is used, **Then** it keeps today's
+ interaction contract: vertical drag, double-click to reset, Alt-click or double-click
+ the read-out to type, right-click menu, MIDI learn, automation follow.
+
+---
+
+### User Story 2 - Turn my own sample into a wavetable (Priority: P1)
+
+A producer has a recorded vocal "aaa-ooo" and a single-cycle wave they made elsewhere. They
+drag the single cycle onto Osc 1's window and the vocal onto Osc 2's. Osc 1 now plays that
+exact cycle; Osc 2 becomes a table whose frames morph from "aaa" to "ooo" as Position
+moves. Both stay with the project and in a saved preset.
+
+**Why this priority**: Egor called it essential. It needs no part of US1 to be useful, but
+it lands in the same card.
+
+**Independent Test**: Import a 2048-sample single cycle, a standard multi-frame wavetable
+file and a two-second recording into a fresh Aurora. Play each one, sweep Position, save,
+close, move the source files away, reopen. Everything sounds the same as before saving.
+
+**Acceptance Scenarios**:
+
+1. **Given** an Aurora, **When** the user drops a WAV, FLAC or MP3 file from the browser or
+ the system file manager onto Osc 1's window, **Then** Osc 1 plays a table made from that
+ file. Its type selector names the file. Osc 2 is unaffected.
+2. **Given** an Aurora, **When** the user picks "Import…" in an oscillator's type selector
+ and chooses a file, **Then** the result is the same as a drop.
+3. **Given** a file whose length is an exact multiple of 2048 samples (a standard wavetable
+ file), **When** it is imported, **Then** each 2048-sample block becomes one frame, in
+ order, up to 256 frames.
+4. **Given** a single cycle (any length up to 4096 samples that is not a standard wavetable
+ file), **When** it is imported, **Then** it becomes a one-frame table that plays the
+ cycle at the played note's pitch. Position then has no audible effect, and the window
+ says so.
+5. **Given** a longer recording, **When** it is imported, **Then** it becomes a table of 16
+ frames taken across the whole file of evenly spaced 2048-sample windows aligned to zero
+ crossings (no pitch detection; decided Oct 29, see Clarifications).
+6. **Given** an imported table, **When** the user saves the project, closes Nota, deletes or
+ moves the source file and reopens the project, **Then** the oscillator sounds the same,
+ because the table is stored inside the project.
+7. **Given** an imported table, **When** the user saves an Aurora preset and loads it on
+ another track, or on another machine, **Then** the preset brings the imported table
+ with it.
+8. **Given** an import just made, **When** the user presses Undo, **Then** the oscillator
+ returns to the table it had before (built-in or an earlier import). Redo brings the
+ import back.
+
+---
+
+### User Story 3 - Two tables on screen without a slower app (Priority: P1)
+
+A user on the reference Linux machine has a busy project with an Aurora whose two
+positions are both swept by LFOs. They keep the Aurora card open while the song plays. The
+interface stays as smooth as it is with today's single window, and switching to the Aurora
+track shows the card with no hitch.
+
+**Why this priority**: Egor's stated concern. A two-window card that brings back the old
+stutter would be a regression.
+
+**Independent Test**: Measure the worst-case scenario in SC-003 to SC-005 before and after,
+with the same method, on the same machine.
+
+**Acceptance Scenarios**:
+
+1. **Given** both windows are visible and both positions are modulated, **When** the
+ transport plays for 60 seconds, **Then** the UI thread's CPU stays within the budget in
+ SC-003.
+2. **Given** a project with four Aurora tracks, each with two 256-frame imported tables,
+ **When** the user clicks from track to track, **Then** each card appears within the time
+ in SC-005, with no visible stall.
+3. **Given** the device panel is hidden or the window is minimised, **When** the song
+ plays, **Then** the table windows do no drawing work.
+
+---
+
+### User Story 4 - See where modulation has taken the table (Priority: P3)
+
+While an LFO sweeps Osc 1's position, the lit frame in Osc 1's window moves with the
+position actually being played, not just the knob's set value (live follow is in scope; decided Oct 29, see
+Clarifications).
+
+**Why this priority**: It makes the windows more informative, but it is the most expensive
+part to draw and the windows work without it.
+
+**Independent Test**: Route LFO 1 to Position at 1 Hz, hold a note, and watch the lit frame
+travel through the stack once a second. With no note held, it rests at the set Position.
+
+**Acceptance Scenarios**:
+
+1. **Given** a held note with position modulation, **When** the window is shown, **Then**
+ the lit frame follows the played position at the card's normal refresh rate.
+2. **Given** no notes sound, **When** the window is shown, **Then** the lit frame sits at
+ the set Position and the window stops repainting.
+
+---
+
+### Edge Cases
+
+- **Unsupported or broken file** (AIFF, OGG, a text file, a truncated WAV): nothing
+ changes, and a short message on the card says the file could not be read and which
+ formats work. The picker offers only WAV, FLAC and MP3.
+- **Stereo or multichannel file**: the channels are mixed to mono.
+- **Silence, or a file that is almost silent** (peak below −60 dBFS): the import is refused
+ with a message, rather than being normalised up into noise.
+- **DC offset or a cycle that does not end where it starts**: DC is removed from each frame
+ and the frame edges are matched, so a held note does not click or buzz.
+- **Very bright material** (noise, a hard sync sweep): the table is band-limited the same
+ way as the built-in tables, so high notes do not fold back into the audible range any
+ more than a built-in table of similar brightness.
+- **Long file**: only the first 60 seconds are read. The card says the file was shortened.
+- **More than 256 frames in a wavetable file**: the first 256 are kept, and the card says
+ so.
+- **Huge or slow file** (for example on a network drive): the import runs in the background,
+ the card shows that it is loading, the oscillator keeps playing its old table until the
+ new one is ready, and audio never drops out.
+- **Import while notes are held**: the switch to the new table is click-free or, at most,
+ stops the sounding notes the way a Mosaic program change does. It never glitches or
+ drops out.
+- **Dropping on the wrong place**: a drop counts only on a table window (or on the whole
+ oscillator column). The target window is highlighted during the drag. Dropping a MIDI
+ file or a preset there does nothing.
+- **Missing table data on load** (the bundle's copy was deleted, or the project was copied
+ without its `samples/` folder): the project still opens. A load warning names the
+ oscillator and the file, as for other missing samples. The type selector reads
+ "Missing: <name>" and the oscillator plays its stored built-in table so the track still
+ sounds. Importing again, or picking a built-in, clears the state.
+- **Copy, duplicate, clone and racks**: duplicating the track, copying the device, freezing,
+ and putting the Aurora inside an Instrument Rack chain or on a Drum Rack pad all keep the
+ imported table.
+- **Automation of the type parameter while an imported table is active**: the imported
+ table keeps playing. The built-in type value is remembered and shown dimmed in the
+ selector, and it takes over only when the user picks a built-in again (see FR-010).
+- **One-frame table with Position modulated**: no audible change, no error. The window
+ shows the one frame and the caption says "1 frame".
+- **Both oscillators import the same file**: it is stored once in the project.
+- **Opening a project made with this feature in an older Nota**: the existing format check
+ refuses it, as for any newer project. Projects without imported tables keep the same
+ values, so they lose nothing in other versions.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+**One card, both tables**
+
+- **FR-001**: The Osc tab MUST show both oscillators at once, each with its own: name, on/off
+ switch, table window, table-type selector, warp-mode selector, and the Position, Warp,
+ Level, Oct, Semi and Fine knobs. No control of either oscillator may sit behind a switch
+ or a picked state.
+- **FR-002**: The "1 / 2" oscillator pick, and every place where one oscillator's controls
+ replace the other's, MUST be removed from the Osc tab. The sub-oscillator and unison
+ controls stay on the Osc tab, shared, and still visible.
+- **FR-003**: Each table window MUST show its oscillator's table as a stack of frames with
+ the current frame lit, a caption with the table's name, the frame as "n/N" (N = that
+ table's frame count) and what modulates its position (as today). It MUST follow the
+ style guide's graph rules (one graph window, title top left, room for the words, no
+ fills under curves).
+- **FR-004**: The two oscillators MUST be told apart by their labels and position on the
+ card, not by identity colours (style guide). An oscillator that is off MUST take the
+ unavailable look without moving anything.
+- **FR-005**: The card MUST stay 260 high, with every control it has today still on it and stays 700 wide, both oscillators side by side in the
+ centre panel (decided Oct 29, see Clarifications). The other five tabs, the wheels and
+ the rail keep their content.
+- **FR-006**: Factory presets, saved projects and saved user presets MUST load with the
+ same values and sound bit-identical (null test as in 036 FR-003). This feature changes
+ the layout and adds a table source. It does not change how a built-in table sounds.
+
+**Custom wavetables**
+
+- **FR-007**: Each oscillator MUST be able to load its own custom table from an audio file,
+ by dropping a file onto its table window (from Nota's browser or the system file manager)
+ and from an "Import…" entry in its type selector.
+- **FR-008**: The import MUST accept WAV, FLAC and MP3, in any sample rate and channel
+ count, mixed to mono. Only the first 60 seconds are read.
+- **FR-009**: The import MUST turn the file into a table of 2048-sample frames by these
+ rules, in order:
+ (a) a file that declares its frame size, or whose length is an exact multiple of 2048
+ samples, is a standard wavetable file: each frame is read as stored, up to 256 frames;
+ (b) otherwise a file of up to 4096 samples is one cycle, resampled to one 2048-sample
+ frame;
+ (c) otherwise the file is a recording, cut into 16 frames as decided in US2
+ acceptance 5.
+ Each table MUST be normalised to the same peak level as the built-in tables, with the
+ frames' relative levels kept. DC MUST be removed from each frame, and each frame MUST
+ loop without a click. No pitch detection is used, unless the US2 clarification picks it.
+- **FR-010**: An imported table MUST be an extra choice in that oscillator's type selector,
+ named after the file, beside the four built-in tables. Picking a built-in table MUST keep
+ the import, so one click can return to it, until the user removes or replaces it. While
+ an imported table is chosen, automation or modulation of the built-in type value MUST
+ NOT replace it.
+- **FR-011**: An imported table MUST play through everything a built-in table does: all
+ five warp modes, Position (blending between neighbouring frames), unison, the mod matrix,
+ macros, MPE slide and the filters. It MUST be band-limited so it does not alias more
+ than a built-in table of similar brightness.
+- **FR-012**: Importing MUST NOT interrupt audio. The file is read and prepared away from
+ audio playback. The oscillator keeps its old table until the new one is ready, then
+ switches without a dropout. While it loads, the card MUST show that it is loading.
+- **FR-013**: An import (and removing an import) MUST be one undo step. Undo returns the
+ oscillator to its previous table, built-in or imported, and redo repeats the import.
+- **FR-014**: An imported table MUST be saved inside the project, so the project needs
+ nothing outside its bundle. It MUST be stored once if both oscillators, or several
+ Auroras, use the same file. It MUST survive save / reopen, project version history,
+ "save as", collecting the project, duplicating a track or device, and Instrument Rack /
+ Drum Rack chains. The original file's name MUST be kept for display.
+- **FR-015**: A user preset saved from an Aurora with an imported table MUST carry the table
+ itself, so it works on another machine. Loading a preset MUST set both oscillators'
+ tables to what the preset holds: built-in or imported. Factory presets do not change.
+- **FR-016**: If a project's stored table cannot be read when it opens, the project MUST
+ still open. A load warning MUST name the track, the oscillator and the file. The type
+ selector MUST read "Missing: <name>", and the oscillator MUST play its stored built-in
+ table until the user imports again or picks a built-in.
+- **FR-017**: A failed import (unreadable file, unsupported format, silence) MUST leave the
+ oscillator unchanged and show a one-line reason on the card.
+
+**Performance**
+
+- **FR-018**: The two table windows MUST NOT repaint unless what they show has changed:
+ table, lit frame, on/off, theme or size (and, if US4 is in, the played position while
+ notes sound). Neither window may draw while the card is hidden or the app is minimised.
+- **FR-019**: A table window's cost to draw MUST NOT depend on the table's frame count. A
+ table with more frames than the window can show is drawn with a fixed number of
+ representative frames plus the lit one. Frame shapes for drawing MUST be prepared once
+ per table (on import or load), not on each paint or tick.
+- **FR-020**: Showing the two windows MUST meet the UI budgets in SC-003 to SC-005, and
+ Aurora's audio cost MUST stay within SC-006.
+
+### Key Entities
+
+- **Oscillator table choice**: per oscillator, either one of the four built-in tables
+ (Analog, Pulse, Formant, Chroma) or that oscillator's imported table. The built-in value
+ stays a normal, automatable parameter with today's four steps.
+- **Imported table**: a mono table of 1 to 256 frames, each 2048 samples. It carries the
+ source file's name, its frame count, and how it was made (standard wavetable file, single
+ cycle, or recording cut into frames). It is stored inside the project, and inside a
+ preset when one is saved. It is shared when its content is identical.
+- **Table window**: one per oscillator. It shows the chosen table's frames, the lit frame,
+ the caption (name · frame n/N · position modulation) and the load / missing / error
+ state, and it is the drop target for imports.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: With the card open on the Osc tab, every control of both oscillators can be
+ reached in zero clicks (today, reaching Osc 2's table or warp mode from Osc 1 takes one
+ switch, and the two tables are never visible together).
+- **SC-002**: Importing a 2048-sample cycle, a 256-frame standard wavetable file or a
+ 10-second recording onto an oscillator takes one drop or three clicks (selector,
+ "Import…", file), and the new table plays within 1 second for files up to 10 seconds on
+ the reference machine.
+- **SC-003**: **UI CPU budget.** On the 036 reference machine (i7-12700, Linux), with the
+ same per-thread measurement before and after (see Assumptions; 60 s average): an
+ Aurora card open on the Osc tab, both oscillators on 256-frame imported tables, both
+ positions modulated by LFOs at 2 Hz, and a chord loop playing. The UI thread uses no more
+ than **2 percentage points of one core above** the same project shown with today's card,
+ and no more than 5 % of one core in total for the card's drawing.
+- **SC-004**: In the SC-003 scenario, painting both table windows takes no more than **2 ms
+ per frame** at the 99th percentile, so the card stays inside a 60 fps frame with room to
+ spare.
+- **SC-005**: Switching to an Aurora track shows the full card within **100 ms**, with no UI
+ frame longer than 50 ms. This holds for a project with four such Auroras, clicked through
+ in turn.
+- **SC-006**: Aurora's audio cost in the `aurora-supersaw-2x` benchmark stays within ±10 %
+ of the 036 baseline (about 28 ms of render per second of audio). Factory presets pass the
+ 036 null test bit-identically. Two Auroras playing imported tables cost no more than the
+ same patch on built-in tables plus 10 %.
+- **SC-007**: In 10 out of 10 trials, a project with imported tables, saved, closed and
+ reopened after the source files were deleted, renders bit-identically to the render
+ before it was saved.
+- **SC-008**: The build and the smoke test pass. The smoke test covers importing a table,
+ saving and reloading it, and a missing table on load.
+
+## Assumptions
+
+- **Frame size and count.** Imported frames use the same 2048-sample size as the built-in
+ tables. Standard wavetable files keep their frame count up to 256. Recordings become 16
+ frames, like the built-in tables. One-cycle files become 1 frame.
+- **Normalisation** is per table (frames keep their relative loudness), to the built-in
+ tables' peak. Built-in tables stay normalised per frame, as today.
+- **Formats** are what the engine already decodes (WAV, FLAC, MP3). Adding AIFF or OGG is
+ out of scope; it would be a new dependency.
+- **Length cap**: 60 seconds read. Longer files are shortened, with a notice.
+- **No pitch detection** for single cycles: a one-cycle file is taken to be exactly one
+ period. Pitch detection for recordings depends on the US2 clarification.
+- **Storage**: the imported table is kept in the project bundle the same way as other
+ samples (embedded and content-addressed, not a link to the original file), so a moved or
+ deleted source file never breaks a project. The project format version goes up by one,
+ with a no-op migration.
+- **No user wavetable library.** Imported tables live in the project and in user presets.
+ A browser category of "my wavetables" is out of scope.
+- **Importing does not switch an oscillator on.** Importing into an off oscillator loads
+ the table and leaves the oscillator off; its window shows the table in the unavailable
+ look.
+- **The table choice is not automatable as a new parameter.** Choosing an imported table
+ works like loading a sample: it is an edit with undo, not an automation target. The
+ built-in type stays automatable, as today.
+- **No in-card table editor** (drawing frames, re-ordering, spectral tools). Only import,
+ replace and remove.
+- **The other tabs** (Filter, Env, LFO, Mod, FX) and the rail are unchanged, apart from what
+ FR-005's clarification decides about width.
+- **Measurement**: UI budgets are measured on the 036 reference machine with the same
+ per-thread method before and after (UI thread CPU sampled once a second with `top -H` /
+ `pidstat`, as in the linux-idle-cpu report), and recorded in the plan. macOS numbers are not
+ acceptance evidence, as in 036.
+
+## 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)
+- [ ] No new dependency — or: license checked, AGPL-compatible, `LICENSES/third-party.md` row planned
+- [ ] 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)
+- [ ] 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`
+- [ ] User-visible change → `CHANGELOG.md` `[Unreleased]` entry planned (and FEATURES.md / user docs via the nota-features / nota-docs skills when working with an agent that has them)
+- [ ] UI change → follows `DESIGN.md` (Studio design language)
diff --git a/specs/053-aurora-one-card/tasks.md b/specs/053-aurora-one-card/tasks.md
new file mode 100644
index 00000000..7f643abe
--- /dev/null
+++ b/specs/053-aurora-one-card/tasks.md
@@ -0,0 +1,269 @@
+---
+
+description: "Task list for 053-aurora-one-card"
+---
+
+# Tasks: Aurora, both wavetables on one card, and custom wavetables from samples
+
+**Input**: Design documents from `specs/053-aurora-one-card/`. These are
+[plan.md](plan.md), [spec.md](spec.md), [research.md](research.md),
+[data-model.md](data-model.md), [contracts/](contracts/) and [quickstart.md](quickstart.md).
+
+**Prerequisites**: spec committed at 41bd30d3. FR-005 (card width) is still open; the tasks
+assume **700** wide. If the answer is 1050, only T019, T020 and T024 change
+(plan § Layout at 1050).
+
+**Tests**: These are included. The constitution requires smoke-test coverage for engine
+behaviour changes (IV), and SC-008 names the cases. Engine and ABI tests go in
+`tests/Nota.SmokeTest/AuroraTableTests.cs` (run alone with `--aurora-tables`). UI budgets are
+measured by hand (quickstart § 4).
+
+**Organization**: Tasks are grouped by user story, so each story can be built and tested on
+its own.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: US1 one card · US2 import · US3 performance · US4 live follow
+- Every task names its files
+
+---
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: The test harness, fixtures, the measurement probe, and the baseline numbers
+taken on the **unchanged** code.
+
+- [ ] T001 Add `tests/Nota.SmokeTest/AuroraTableTests.cs` (SPDX header, empty test groups for conditioning, undo, state, project, preset, rack, scope). Register the `--aurora-tables` mode in `tests/Nota.SmokeTest/Program.cs`, next to `--aurora-null` (`Program.cs:536-551`), and add the group to the full run.
+- [ ] T002 [P] Add `tests/Nota.SmokeTest/AuroraFixtures.cs` and the `--aurora-fixtures <dir>` mode. It writes the quickstart § 2 files (cycle-2048, table-64x2048 with a `clm ` chunk, table-300x2048, stereo vowel-2s FLAC, long-90s, silence, broken, x.aiff) through `tests/Nota.SmokeTest/WavWriter.cs` and the engine's encoder.
+- [ ] T003 [P] Add the `--aurora-ui-fixture <dir> [--builtin]` mode in `tests/Nota.SmokeTest/AuroraFixtures.cs`. For now it writes the **v27 baseline** project: 4 Auroras, Formant / Chroma, LFO 1 → Osc 1 position, LFO 2 → Osc 2 position at 2 Hz, a 4-bar 6-note chord loop. The scenario variant is added in T043.
+- [ ] T004 [P] Add the opt-in UI probe `src/managed/Nota.App/Diagnostics/UiProbe.cs`: `NOTA_UI_PROBE=aurora`, fixed rings of Stopwatch ticks, p50 / p99 to stderr every 10 s, no cost when off. Hook it into the current `src/managed/Nota.App/Controls/AuroraStack.cs` `Render`, and add a "card build → first paint" mark in `src/managed/Nota.App/DeviceChainView.Instruments.cs` (`:120-126`).
+- [ ] T005 On the 036 reference machine, record the baselines in `specs/053-aurora-one-card/perf-baseline.md` (format of `specs/036-aurora-perf/baseline-env.md`): `nota_perf run aurora-supersaw-2x 30` twice, plus `pidstat` UI-thread %CPU, paint p99 and card build time with the T003 baseline fixture on the unchanged card (quickstart § 4 step 1).
+
+**Checkpoint**: baselines recorded. Every later number is compared against them.
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites for US2, US3, US4)
+
+**Purpose**: The engine table model, the hand-over to the audio thread, the state blob, the
+C ABI and interop. US1 does not need this phase and can start right after Phase 1.
+
+- [ ] T006 Create `src/native/nota.engine/src/devices/instruments/AuroraTable.h` and `.cpp` (SPDX header): the immutable `AuroraTable` and `AuroraTableSet` types from data-model.md, with a serial counter. Add the .cpp to `src/native/nota.engine/CMakeLists.txt` (list at `:171`).
+- [ ] T007 Implement `AuroraTable::buildFromFile` in `AuroraTable.cpp`:
+ - `decodeAudioFile` (`src/media/AudioFile.cpp:73`), mono mix, the 60 s cap;
+ - classification (a) `clm ` chunk or a multiple of 2048, at most 256 frames, (b) at most
+ 4096 samples as one cycle by FFT resample, (c) 16 zero-crossing-aligned windows
+ (research R3);
+ - typed errors (contracts/c-abi.md).
+- [ ] T008 Implement conditioning in `AuroraTable.cpp`: DC removal per frame, the 32-sample equal-power seam blend for (c), per-table normalisation to peak 1.0, refusal below −60 dBFS, and `buildFromFrames` (no re-conditioning).
+- [ ] T009 Implement mip levels k = 0…5 by FFT truncation with signalsmith-linear `RealFFT` (as in `src/dsp/primitives/SpectrumAnalyzer.h:18`), and the 128-bit content hash of the base level, in `AuroraTable.cpp`.
+- [ ] T010 In `src/native/nota.engine/src/devices/instruments/WavetableSynth.h/.cpp`, add:
+ - a `SnapshotHistory<const AuroraTableSet>` member and `std::atomic<uint8_t> useCustom_[2]`;
+ - a `RenderScope` in `render()`, and a `live()` read next to the block snapshot (`WavetableSynth.cpp:330-345`);
+ - `clone()` (`:246-252`) sharing the set and flags;
+ - message-thread setters `setTable`, `clearTable`, `setSource`, `setMissing`.
+- [ ] T011 In `WavetableSynth.h/.cpp`, add `readMorphSized` and `oscStackCustom`, with the mip pick per voice per block (unison detune and warp bias, research R4). Call it only when `useCustom_` is set and a table is present; leave the built-in `oscStack` / `readMorph` calls at `:497-500` untouched.
+- [ ] T012 In `WavetableSynth.cpp`, implement the state trailer v1 in `getState` / `setState` (`:227-244`) per contracts/state-blob.md, with an `includeTables` flag. A blob with no table, flag or missing name stays byte-identical.
+- [ ] T013 In `WavetableSynth.h/.cpp`, implement `scopeRead` (5 floats, data-model.md § Scope telemetry, the Keys pattern `Keys.h:199-215`): relaxed atomics written once per block, holding the played position of the most recently started sounding voice.
+- [ ] T014 In `src/native/nota.engine/src/engine/Engine.h` and `Engine_Devices.cpp`, add:
+ - `auroraSetTable` (checkpoint → clone + `republishWithTrack`; otherwise in place through the history), `auroraClearTable`, `auroraSetSource`, `auroraSetMissing`;
+ - `auroraTableInfo`, `auroraTableRead`, `auroraTablePreview`, `auroraState`.
+ Model them on `setRhythmVoiceSample` (`Engine_Devices.cpp:328-343`).
+- [ ] T015 Declare the contracts/c-abi.md functions in `src/native/nota.engine/include/nota/nota_engine.h`. Implement the builders in `src/native/nota.engine/src/abi/nota_engine_import.cpp` and the track functions in `src/native/nota.engine/src/abi/nota_engine_track.cpp`.
+- [ ] T016 [P] Add managed interop:
+ - `src/managed/Nota.Infrastructure/Interop/NativeMethods.Tracks.cs` (`[LibraryImport]`, `NotaAuroraTableInfo` struct);
+ - `NotaEngine.Tracks.cs` wrappers, with a `SafeHandle` for `NotaAuroraTable*`;
+ - `src/managed/Nota.Application/Engine/IAudioEngine.cs` members;
+ - any test fakes that implement `IAudioEngine`.
+- [ ] T017 In `tests/Nota.SmokeTest/AuroraTableTests.cs`, add the regression tests: an Aurora with no table gives a byte-identical `getState` (compare against the 156-float layout); a factory preset after the change still passes `--aurora-null` (`AuroraNullTests.cs`).
+
+**Checkpoint**: the engine can hold, play, save and report a custom table. Built-in sound is bit-identical.
+
+---
+
+## Phase 3: User Story 1 — See and shape both oscillators at once (Priority: P1) 🎯 MVP
+
+**Goal**: The Osc tab shows both oscillators with their own window, selectors and knobs. There is no 1 / 2 switch.
+
+**Independent Test**: quickstart § 1. Glacier Pad shows both tables, both type and warp selectors and 2 × 6 knobs with zero clicks; editing one leaves the other unchanged; old projects show the same values.
+
+- [x] T018 [US1] *(Done for US1 inside `Controls/AuroraStack.cs`: per-frame geometry cache and change-only invalidation; the class keeps its name until the imported-table source arrives in T034, which creates `AuroraTableView.cs`. The probe hook waits for T004.)* Create `src/managed/Nota.App/Controls/AuroraTableView.cs` (SPDX header):
+ - a `NotaGraph` window whose title row carries the caption;
+ - the built-in source drawn from `AuroraStack`'s shared shape cache (keep the cache in `Controls/AuroraStack.cs`, remove its view role);
+ - one `StreamGeometry` cached per frame per bounds;
+ - `Set(source, litPos, dim)` that invalidates only on a change of lit index, source, dim or bounds (FR-018 / FR-019);
+ - the probe hook from T004.
+- [x] T019 [US1] In `src/managed/Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs`, rebuild the Osc body as two 216 px columns: a header row 20, a window 216 × 60, a knob row 54 with the six existing `PKnob` cells at 34 px; then the shared sub / unison row (`:489-507`) spanning both columns (contracts/ui-osc-tab.md).
+- [x] T020 [US1] In `AuroraInstrumentCard.cs`, give each oscillator its own type drop-down (built-ins) and warp drop-down, bound to `table` / `osc2table` and `osc1warpmode` / `osc2warpmode`, with MIDI learn, readouts and automation follow, as `Chips` does today (`:292-300`).
+- [x] T021 [US1] In `AuroraInstrumentCard.cs`, remove `osel`, `oscPick`, `applyOsc`, `oscStrip`, `oscTableHosts` / `oscWarpHosts` and the single `tableWindow` (`:423-442, 480-487, 534`). Feed both windows in `Refresh` (`:164-176`) instead of `stack.Set` (`:168-169`). Update `Hint()` / `Summary()` and the header comment (`:8-11`).
+- [x] T022 [US1] In `AuroraInstrumentCard.cs`, apply the `Inactive` look to a column when its oscillator is off (FR-004). Each caption names its own position modulation (adapt `:509-526` per oscillator).
+- [x] T023 [P] [US1] Update `DESIGN.md` § Devices with an Aurora note: the Osc tab layout change, decided by spec 053.
+- [x] T024 [US1] Check quickstart § 1 in Studio Dark and Studio Light at 100 % and 150 % scale, and with `DesignTokenCheck*` in the smoke test green. Fix any overlap in `AuroraInstrumentCard.cs` / `AuroraTableView.cs`. *(Checked from the docs-shot renders at 2× in Studio Dark and Light, default and Glacier Pad; interface scale is a uniform transform and device cards ignore Text size (038 FR-038), so no extra case.)*
+
+**Checkpoint**: US1 is shippable alone (the UI only; the engine is untouched by this phase).
+
+---
+
+## Phase 4: User Story 2 — Turn my own sample into a wavetable (Priority: P1)
+
+**Goal**: Drop or import a file per oscillator. It plays, saves with the project and presets, survives racks, and handles undo and missing files.
+
+**Independent Test**: quickstart § 2 and § 3. Import the three kinds, save, move the sources away, and reopen: the render is bit-identical. Presets and racks carry the table.
+
+### Tests for User Story 2 (write first; they fail before the implementation)
+
+- [ ] T025 [P] [US2] In `AuroraTableTests.cs`, add the conditioning tests:
+ - each of rules (a) / (b) / (c) gives the expected frame count, using the T002 fixtures;
+ - the 256-frame clamp and the 60 s cap set their flags;
+ - silence gives `ERR_SILENT`; AIFF / broken files give `ERR_FORMAT` / `ERR_DECODE`;
+ - each frame's mean is below 1e-6; the table peak equals 1.0;
+ - the loop seam jump is at most the median step for (c).
+- [ ] T026 [P] [US2] In `AuroraTableTests.cs`, add the undo and source tests: `set_table(checkpoint 1)`, then undo restores the previous table info and redo re-applies it; `clear_table` is one step; `set_source` toggles with no undo entry and keeps the voices active.
+- [ ] T027 [P] [US2] In `AuroraTableTests.cs`, add the state tests:
+ - the trailer round-trips through `getState` / `setState` (contracts/state-blob.md);
+ - a blob without a trailer clears the tables;
+ - an unknown trailer version is ignored;
+ - `clone()`, track duplicate, device copy/paste, and an Instrument Rack chain / Drum Rack pad round trip keep the table (`RackNestingTests.cs` style).
+- [ ] T028 [P] [US2] In `AuroraTableTests.cs`, add the render tests: an imported 2048-sample saw cycle and the built-in Analog at frame 0 differ by less than −40 dB at C3 (sanity); with Warp Off at C7 the alias energy of a bright 64-frame table is at most −60 dB relative to the fundamental (FR-011).
+- [ ] T029 [P] [US2] In `AuroraTableTests.cs`, add the project tests:
+ - save, reopen and render bit-identically (SC-007);
+ - two Auroras with the same table give one `samples/<hash>.wav`;
+ - with a deleted sample, the load warns, `table_info.missing` is 1 and the built-in plays;
+ - v27 projects load unchanged and migrate to 28.
+- [ ] T030 [P] [US2] In `AuroraTableTests.cs`, add the preset tests: a user preset carries `AuroraTables` and restores the frames exactly; a factory preset clears custom tables; the preset apply is one undo group.
+
+### Implementation for User Story 2
+
+- [ ] T031 [US2] Create `src/managed/Nota.Application/Instruments/Aurora/AuroraTableImporter.cs` (SPDX header):
+ - check the extension against `SampleIndex.AudioExtensions` (`src/managed/Nota.Infrastructure/SampleStore/SampleIndex.cs:20-21`);
+ - run `AuroraTableBuild` on a `Task`, then apply on the UI thread with `AuroraSetTable(checkpoint: true)`;
+ - return a typed result (Ok / Shortened / FirstFrames / Unreadable / Format / Silent).
+- [ ] T032 [US2] In `AuroraInstrumentCard.cs`, make each column a drop target (`BrowserView.IsAcceptableDrag` / `DroppedItems`, Rhythm pattern `RhythmInstrumentCard.cs:220-235`, ignoring MIDI files and presets). Add an `Import…` file picker filtered to `*.wav;*.flac;*.mp3` (Rhythm `:205-218`, without AIFF / OGG). Both call T031.
+- [ ] T033 [US2] In `AuroraInstrumentCard.cs`, extend each type drop-down with the imported table's name (a check mark on the active source, via `AuroraSetSource`), `Remove imported table` (`AuroraClearTable`), and the dimmed built-in value while the imported table is active (FR-010).
+- [ ] T034 [US2] In `src/managed/Nota.App/Controls/AuroraTableView.cs`, add the imported source: fetch `AuroraTablePreview` once per (track, osc, serial) into a shared cache; the "n/N" caption; "1 frame"; the drag-over ring and Loading / Error (4 s) / Missing states (contracts/ui-osc-tab.md).
+- [ ] T035 [US2] In `src/managed/Nota.Infrastructure/Persistence/ProjectModel.cs` (`InstrumentDto` `:316-341`), add `WavetableDto` and `InstrumentDto.Wavetables`. Bump `CurrentFormatVersion` to 28 in `ProjectService.cs:40`, with its doc line, and append the no-op v27→v28 `Migration` in `ProjectMigrations.cs`.
+- [ ] T036 [US2] In `ProjectService.cs`, make the save of kind 5 (`:150-153`) store `AuroraState(includeTables: false)`, write each table as float32 `clm ` WAV under `samples/<hash>.wav` via `BundleContent`, and fill `Wavetables` (contracts/persistence.md).
+- [ ] T037 [US2] In `ProjectService.cs`, make the load of kind 5 (`:637` area) apply the blob, then for each `WavetableDto` call `nota_file_decode_mono` → `AuroraTableFromFrames` → `AuroraSetTable(checkpoint: false)` → `AuroraSetSource`. On failure, add the warning text from contracts/persistence.md and call `AuroraSetMissing`.
+- [ ] T038 [US2] In `src/managed/Nota.Infrastructure/Persistence/BundleContent.cs` and `ProjectHistory.cs`, pin `Wavetables` samples in `PinnedBinaries` / `PruneUnreferenced` so that version history and pruning keep them.
+- [ ] T039 [P] [US2] In `src/managed/Nota.Infrastructure/Persistence/PresetModel.cs` and `PresetService.cs`, add `PresetAuroraTable` and `AuroraTables`. Write it in save (`PresetService.cs:62` area) and apply it after the parameters (`:274`, `:313-324` pattern), clearing tables when it is absent.
+- [ ] T040 [US2] Add the rack-chain variants (contracts/c-abi.md § Rack chains) in `src/native/nota.engine/src/engine/Engine_Devices.cpp`, `src/abi/nota_engine_rack.cpp`, `nota_engine.h`, and managed interop `NativeMethods.Rack.cs` / `NotaEngine.Rack.cs` / `IAudioEngine.cs`.
+- [ ] T041 [US2] In `src/managed/Nota.App/DeviceCards/Rack/RackCardView.cs` (proxy engine, `:211`), forward the Aurora table calls to the chain variants, so an Aurora card opened inside a rack can import, switch source and remove.
+
+**Checkpoint**: US2 complete. T025–T030 pass; quickstart § 2 and § 3 pass.
+
+---
+
+## Phase 5: User Story 3 — Two tables on screen without a slower app (Priority: P1)
+
+**Goal**: Prove and hold the budgets in SC-003 to SC-006.
+
+**Independent Test**: quickstart § 4 and § 5 on the reference machine, compared with the T005 baselines.
+
+- [ ] T042 [P] [US3] In `tests/perf/nota_perf.cpp`, add the `aurora-imported-2x` scenario next to `aurora-supersaw-2x` (`:195`, `:254`): the same load, with both oscillators on generated 256-frame tables.
+- [ ] T043 [P] [US3] In `tests/Nota.SmokeTest/AuroraFixtures.cs`, extend `--aurora-ui-fixture` with the v28 scenario project (256-frame generated tables on both oscillators of all 4 Auroras).
+- [ ] T044 [US3] Check that no table-view work runs while the device panel is hidden or the window is minimised (FR-018). Gate `RefreshSynthLive` / the probe in `src/managed/Nota.App/DeviceChainView.Instruments.cs` if needed; the probe should show 0 paints (quickstart § 4 step 4).
+- [ ] T045 [US3] Run quickstart § 4 and § 5 twice on the reference machine. Record UI-thread %CPU, paint p50 / p99, card build time and `nota_perf` numbers in `specs/053-aurora-one-card/perf-baseline.md`, against T005.
+- [ ] T046 [US3] Only if T045 misses a budget: profile (`perf record` on the UI thread, or `dotnet-trace`). Fix in `AuroraTableView.cs` / `AuroraInstrumentCard.cs` (geometry cache, invalidation gate) or in `oscStackCustom`, then re-run T045. The budgets themselves are not loosened.
+
+**Checkpoint**: SC-003 to SC-006 recorded as met.
+
+---
+
+## Phase 6: User Story 4 — See where modulation has taken the table (Priority: P3, in scope per Clarification 2)
+
+**Goal**: The lit frame follows the played position while notes sound.
+
+**Independent Test**: LFO 1 → Position at 1 Hz with a held note: the lit frame travels once a second. With no note, it rests at the set Position and repaints stop.
+
+- [ ] T047 [P] [US4] In `AuroraTableTests.cs`, add the scope tests: with LFO 1 routed to Position and a held note, `nota_track_instrument_scope` floats [0] / [1] move over 1 s and stay in 0..1; with no voice they are −1; [2] / [3] change on `set_table`.
+- [ ] T048 [US4] In `AuroraInstrumentCard.cs`, read the 5-float scope on every tick **before** the `ParamsMoved` gate (`:151-166`). Push the played position to both `AuroraTableView`s (the set Position when −1). Refetch the preview when a serial changes. Leave the readouts and graphs gated as today.
+- [ ] T049 [US4] In `AuroraTableView.cs`, use the 64-frame lit grid of the preview for imported tables (built-ins: the 16 frames), and quantise the lit index so repaints happen only on a grid step.
+
+**Checkpoint**: US4 complete. Re-run T045 with live follow active; it is part of the SC-003 scenario.
+
+---
+
+## Phase 7: Polish & Cross-Cutting Concerns
+
+- [ ] T050 [P] Add a `CHANGELOG.md` `[Unreleased]` entry: both oscillators on the Osc tab, custom wavetable import (formats, rules, limits), project format 28, and that held notes stop on import.
+- [ ] T051 [P] Update `FEATURES.md` with the nota-features skill.
+- [ ] T052 [P] Update the user manual (EN + RU) page `instruments/aurora` with the nota-docs skill (`src/managed/Nota.App/NotaDocs.cs:23` lists it).
+- [ ] T053 [P] Check that every new file has the two-line SPDX header (`AuroraTable.h/.cpp`, `AuroraTableView.cs`, `AuroraTableImporter.cs`, `UiProbe.cs`, `AuroraFixtures.cs`, `AuroraTableTests.cs`), and that `LICENSES/third-party.md` needs no change (no new dependency).
+- [ ] T054 Run `scripts/build-linux.sh` (and `scripts/build.sh` on macOS) and the whole of quickstart.md. Re-check the plan's Constitution Check and the spec's Nota Compliance Checklist.
+- [ ] T055 Run `/speckit-converge` until it reports **Converged**.
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)** has no dependencies. T005 needs T003 and T004 and must run on the **unchanged** code.
+- **Foundational (Phase 2)** depends on Phase 1 (T001). It blocks US2, US3 and US4.
+- **US1 (Phase 3)** depends on Phase 1 only. It can run in parallel with Phase 2.
+- **US2 (Phase 4)** depends on Phase 2 and on US1's T018–T021 (the card it extends).
+- **US3 (Phase 5)** depends on US1 and US2: it measures the finished views with imported tables. T042 can start after Phase 2.
+- **US4 (Phase 6)** depends on Phase 2 (T013) and US1 (T018). T045 is re-run after it.
+- **Polish (Phase 7)** depends on all stories.
+
+### Within each phase
+
+- T006 → T007 → T008 → T009; T010 → T011 → T012 → T013; T014 → T015 → T016; T017 last.
+- Tests T025–T030 are written before T031–T041 and fail before them.
+- T035 → T036 → T037 → T038 (same persistence files, in order). T039 is independent ([P]).
+
+### Parallel Opportunities
+
+- Phase 1: T002, T003 and T004 run in parallel after T001.
+- Phase 2 and Phase 3 run side by side (engine and UI files are disjoint).
+- US2 tests T025–T030 are all [P] (separate test groups in one new file; merge in order).
+- T039 (presets) runs in parallel with T035–T038 (project). T042 and T043 run in parallel.
+- Polish T050–T053 run in parallel.
+
+---
+
+## Parallel Example: User Story 2
+
+```bash
+# Tests first, side by side:
+Task: "T025 conditioning tests in tests/Nota.SmokeTest/AuroraTableTests.cs"
+Task: "T027 state / rack round-trip tests in tests/Nota.SmokeTest/AuroraTableTests.cs"
+Task: "T030 preset tests in tests/Nota.SmokeTest/AuroraTableTests.cs"
+
+# Then persistence in two lanes:
+Task: "T035–T038 project v28 in src/managed/Nota.Infrastructure/Persistence/{ProjectModel,ProjectService,ProjectMigrations,BundleContent,ProjectHistory}.cs"
+Task: "T039 presets in src/managed/Nota.Infrastructure/Persistence/{PresetModel,PresetService}.cs"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP first (User Story 1)
+
+1. Phase 1 (baselines on the unchanged code).
+2. Phase 3 (US1): the two-column Osc tab with built-in tables only. Stop and validate with
+ quickstart § 1 and a first UI CPU check (the T045 method with the baseline fixture).
+ This answers Egor's main complaint, and it can ship as its own PR if review prefers.
+
+### Incremental delivery
+
+1. Phase 2 (engine and ABI) in parallel with US1.
+2. US2: import, persistence, presets, racks.
+3. US4: live follow.
+4. US3: full measurement with everything on, then fixes if needed.
+5. Polish, the build gate, converge.
+
+### Task count
+
+| Phase | Tasks |
+|---|---|
+| 1 Setup | 5 (T001–T005) |
+| 2 Foundational | 12 (T006–T017) |
+| 3 US1 | 7 (T018–T024) |
+| 4 US2 | 17 (T025–T041) |
+| 5 US3 | 5 (T042–T046) |
+| 6 US4 | 3 (T047–T049) |
+| 7 Polish | 6 (T050–T055) |
+| **Total** | **55** |
diff --git a/src/managed/Nota.App/Controls/AuroraStack.cs b/src/managed/Nota.App/Controls/AuroraStack.cs
index fece8818..d6f790fb 100644
--- a/src/managed/Nota.App/Controls/AuroraStack.cs
+++ b/src/managed/Nota.App/Controls/AuroraStack.cs
@@ -11,6 +11,9 @@
// a thousand line segments on every one of the thirty ticks a second the device panel
// runs, which is what made switching to an Aurora track stutter. Render now draws each
// frame as a single geometry, and Set only invalidates when the picture actually changes.
+// The Osc tab shows two of these at once (specs/053), so the sixteen geometries are also
+// kept between paints and rebuilt only when the bank, the size or the inset changes: a
+// repaint for a new lit frame is sixteen DrawGeometry calls and nothing else.
using System;
using System.Threading;
@@ -51,6 +54,11 @@ internal sealed class AuroraStack : Control
private int _bank = -1, _active = -1;
private bool _dim;
+ // The geometry cache: the frames as laid out for (bank, size, inset).
+ private readonly StreamGeometry?[] _geo = new StreamGeometry?[Frames];
+ private int _geoBank = -1;
+ private double _geoW = -1, _geoH = -1, _geoInset = -1;
+
/// <summary>Space kept clear at the top of the window for a caption drawn over it.</summary>
public double TopInset { get; set; }
@@ -121,7 +129,6 @@ internal sealed class AuroraStack : Control
if (w <= 2 || h <= 2 || _bank < 0) return;
NotaGraph.Window(ctx, new Rect(0, 0, w, h));
- var frames = Bank(_bank);
// The stack is skewed up-and-right: frame 0 sits bottom-front, frame 15 top-back,
// sized so every frame's centre ± amplitude stays inside the window.
const double padX = 9, padY = 7;
@@ -134,21 +141,28 @@ internal sealed class AuroraStack : Control
var pens = _dim ? DimPens : DepthPens;
var hot = _dim ? DimPens[^1] : HotPen;
- // Back to front, so a nearer frame overlaps the one behind it.
- for (int f = Frames - 1; f >= 0; f--)
+ if (_geoBank != _bank || _geoW != w || _geoH != h || _geoInset != TopInset)
{
- bool on = f == _active;
- var buf = frames[f];
- double ox = padX + f * skewX;
- double cy = cyBottom - (cyBottom - cyTop) * f / (Frames - 1);
- var geo = new StreamGeometry();
- using (var g = geo.Open())
+ var frames = Bank(_bank);
+ for (int f = 0; f < Frames; f++)
{
- g.BeginFigure(new Point(ox, cy - buf[0] * amp), false);
- for (int j = 1; j <= N; j++)
- g.LineTo(new Point(ox + (double)j / N * waveW, cy - buf[j % N] * amp));
+ var buf = frames[f];
+ double ox = padX + f * skewX;
+ double cy = cyBottom - (cyBottom - cyTop) * f / (Frames - 1);
+ var geo = new StreamGeometry();
+ using (var g = geo.Open())
+ {
+ g.BeginFigure(new Point(ox, cy - buf[0] * amp), false);
+ for (int j = 1; j <= N; j++)
+ g.LineTo(new Point(ox + (double)j / N * waveW, cy - buf[j % N] * amp));
+ }
+ _geo[f] = geo;
}
- ctx.DrawGeometry(null, on ? hot : pens[f * Depth.Length / Frames], geo);
+ _geoBank = _bank; _geoW = w; _geoH = h; _geoInset = TopInset;
}
+
+ // Back to front, so a nearer frame overlaps the one behind it.
+ for (int f = Frames - 1; f >= 0; f--)
+ ctx.DrawGeometry(null, f == _active ? hot : pens[f * Depth.Length / Frames], _geo[f]!);
}
}
diff --git a/src/managed/Nota.App/Controls/Knob.cs b/src/managed/Nota.App/Controls/Knob.cs
index 64adc522..5ab4fb34 100644
--- a/src/managed/Nota.App/Controls/Knob.cs
+++ b/src/managed/Nota.App/Controls/Knob.cs
@@ -83,8 +83,10 @@ public sealed class Knob : Control
private IBrush? _arc;
/// <summary>Drawn as inactive (no brass) while still taking input — see Inactive.</summary>
- public bool IsDim { get => _dim; set { if (_dim == value) return; _dim = value; InvalidateVisual(); } }
+ public bool IsDim { get => _dim; set { if (_dim == value) return; _dim = value; InvalidateVisual(); DimChanged?.Invoke(); } }
private bool _dim;
+ /// <summary>After <see cref="IsDim"/> changes, so a cell can repaint its label and value.</summary>
+ public event Action? DimChanged;
/// <summary>A live reading marked on the track as a short tick, as a 0..max position (NaN = none).</summary>
public double Marker { get => _marker; set { if (_marker.Equals(value)) return; _marker = value; InvalidateVisual(); } }
diff --git a/src/managed/Nota.App/DeviceCardKit.cs b/src/managed/Nota.App/DeviceCardKit.cs
index cd318e10..96a016f1 100644
--- a/src/managed/Nota.App/DeviceCardKit.cs
+++ b/src/managed/Nota.App/DeviceCardKit.cs
@@ -83,13 +83,17 @@ internal static class DeviceCardKit
TextTrimming = TextTrimming.CharacterEllipsis,
};
var valueInk = value.Foreground ?? TextPrimary;
+ // A dimmed knob (Inactive: a bypassed card, an oscillator switched off) keeps its text
+ // in the disabled ink even when automation or MIDI moves it.
void Paint()
{
+ if (knob.IsDim) { lbl.Foreground = value.Foreground = TextDisabled; return; }
bool hot = knob.ArcColor is null && (emphasised || knob.IsModified);
lbl.Foreground = hot ? TextSecondary : labelInk ?? TextTertiary;
value.Foreground = valueInk;
}
knob.ValueSet += Paint;
+ knob.DimChanged += Paint;
Paint();
// ⌥-click the knob, or double-click its value, to type one; double-click the knob to reset (specs/035). A knob
// without a Format is typed by reading its value line back after each probe.
diff --git a/src/managed/Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs b/src/managed/Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs
index 3e0a9de8..72d81ec0 100644
--- a/src/managed/Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs
+++ b/src/managed/Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs
@@ -6,9 +6,9 @@
//
// Wheels 56 pitch bend and mod wheel, on screen on every tab.
// Centre six tabs:
-// Osc — the 16-frame wavetable stack beside the two oscillators, the sub
-// and the unison stack; the strip on top carries the bank and the
-// warp mode of whichever oscillator you are looking at.
+// Osc — both oscillators side by side (specs/053), each with its own
+// table window, table and warp-mode drop-downs, on switch and six
+// knobs; the sub and the unison stack share a row under them.
// Filter — the selected filter's response as a drag pad, with its type,
// slope, cutoff, resonance, env / LFO / key amounts and where each
// source (Osc 1 / Osc 2 / Sub) is sent.
@@ -18,9 +18,10 @@
// that draws the selected LFO's own shape.
// Mod — the 8 × 7 matrix: drag a cell up for +, down for −.
// FX — drive · chorus · reverb, each on its own switch.
-// Rail 186 Global (voice mode, bend range, position, cutoff, unison, volume and
-// pan) or Macros (eight, three to a page, each a value, an
-// amount and one of twelve targets). Picking Mod brings the macros up, as
+// Rail 186 Global (voice mode, bend range, volume and pan; position, cutoff and
+// unison detune have their one home on the Osc and Filter tabs) or Macros
+// (eight, three to a page, each a value, an amount and one of twelve
+// targets). Picking Mod brings the macros up, as
// the almanac draws that state.
//
// Neutral ink is the parameter itself; teal is modulation and what receives it; the accent
@@ -126,9 +127,12 @@ internal sealed class AuroraInstrumentCard : IInstrumentCard
(int, string) P(string id) => (I(id), id);
var readouts = new List<Action>();
- int tab = 0, railTab = 0, fsel = 0, osel = 0; // Osc · Global · Filter 1 · Osc 1
+ int tab = 0, railTab = 0, fsel = 0; // Osc · Global · Filter 1
- var stack = new AuroraStack { VerticalAlignment = VerticalAlignment.Stretch, MinHeight = 60 };
+ // One table window per oscillator: both are on screen together (specs/053).
+ var stacks = new AuroraStack[2];
+ for (int o = 0; o < 2; o++) stacks[o] = new AuroraStack { VerticalAlignment = VerticalAlignment.Stretch, MinHeight = 40 };
+ var oscDimmed = new List<Control>[] { new(), new() }; // what an off oscillator greys
var filtGraph = new VoltFilter(engine, track) { VerticalAlignment = VerticalAlignment.Stretch, MinHeight = 60, Spectrum = new FilterSpectrum(engine, track) };
var env1 = new VoltEnv(engine, track) { VerticalAlignment = VerticalAlignment.Stretch, MinHeight = 50 };
var env2 = new VoltEnv(engine, track) { VerticalAlignment = VerticalAlignment.Stretch, MinHeight = 50 };
@@ -141,7 +145,6 @@ internal sealed class AuroraInstrumentCard : IInstrumentCard
Margin = new Thickness(0, 0, 6, 0), TextTrimming = TextTrimming.CharacterEllipsis,
};
Action applyFilter = () => { };
- Action applyOsc = () => { };
Action showTab = () => { };
// ---- the live tick's gate -------------------------------------------------
@@ -164,12 +167,24 @@ internal sealed class AuroraInstrumentCard : IInstrumentCard
void Refresh(bool force)
{
if (!ParamsMoved() && !force) return;
- applyOsc(); applyFilter();
- stack.Set(Sel(osel == 0 ? "table" : "osc2table", 4), G(osel == 0 ? "position" : "osc2position"));
- stack.Dimmed = G(osel == 0 ? "osc1on" : "osc2on") < 0.5f;
+ applyFilter();
+ for (int o = 0; o < 2; o++)
+ {
+ stacks[o].Set(Sel(o == 0 ? "table" : "osc2table", 4), G(o == 0 ? "position" : "osc2position"));
+ stacks[o].Dimmed = G(o == 0 ? "osc1on" : "osc2on") < 0.5f;
+ }
env1.Refresh(); env2.Refresh();
lfoStrip.Set(Sel("lfo1shape", 4), LfoCycles(0), G("lfo1depth"));
+ // Undim first so the readouts paint over the real colours, not ones saved while the
+ // oscillator was off (a cleared route would come back in its old modulation colour).
+ for (int o = 0; o < 2; o++)
+ foreach (var c in oscDimmed[o]) Inactive.Set(c, false, interactive: true);
foreach (var r in readouts) r();
+ // After the readouts' own paint: an oscillator that is off takes the unavailable
+ // look, its controls staying where they are and still usable.
+ for (int o = 0; o < 2; o++)
+ if (G(o == 0 ? "osc1on" : "osc2on") < 0.5f)
+ foreach (var c in oscDimmed[o]) Inactive.Set(c, true, interactive: true);
hint.Text = Hint();
}
void Touch() => Refresh(true);
@@ -299,19 +314,6 @@ internal sealed class AuroraInstrumentCard : IInstrumentCard
Control StopChips(string id, string[] names, float[] stops, bool fill = false)
=> Chips(id, names, () => NearestExact(G(id), stops), iv => { SetP(id, stops[iv]); Touch(); }, fill);
- Grid Slider(string label, string id, Func<string> text, double labelW = 0, double valueW = 40)
- {
- int pi = I(id);
- var row = SliderRow(label, () => G(id), v => { SetP(id, (float)v); Touch(); }, text, out var sync,
- begin: pi >= 0 ? () => Begin(id) : null,
- end: pi >= 0 ? () => End(id) : null,
- reset: pi >= 0 ? () => { SetP(id, engine.InstrumentParamDefault(track, pi)); Touch(); } : null,
- labelWidth: labelW, valueWidth: valueW);
- readouts.Add(sync);
- if (pi >= 0) MidiLearn.Bind(row, MidiTarget.PluginParam(track, -1, pi), label);
- return row;
- }
-
Control Toggle(string label, string id, Func<string>? live = null)
{
var host = Switch(label, () => G(id) >= 0.5f, () => { SetP(id, G(id) >= 0.5f ? 0f : 1f); Touch(); }, out var sync, liveLabel: live);
@@ -413,76 +415,138 @@ internal sealed class AuroraInstrumentCard : IInstrumentCard
wheelsPanel.Width = WheelsW;
// ---- Osc tab --------------------------------------------------------------
- // Both oscillators own a bank and a warp mode. Two chip strips per oscillator
- // would not fit, so ONE strip across the top carries them for whichever oscillator
- // is selected — the 1 / 2 pick leads it, and clicking an oscillator's name picks it
- // too. The pick and the bank names say what they are, so they go without captions. Under it: the table window on the left, the two oscillator rows on the
- // right, and a line of drag values for the sub and the unison stack.
- var oscTableHosts = new Panel[2];
- var oscWarpHosts = new Panel[2];
- for (int o = 0; o < 2; o++)
+ // Both oscillators side by side, nothing behind a pick (specs/053): each column
+ // carries its name and on switch, its table and warp-mode drop-downs, its table
+ // window and its six knobs. Under both, a line of drag values for the sub and the
+ // unison stack. Four banks and five warp modes would not fit as segments in a
+ // 210 px column, so both are drop-downs (more than four choices is one anyway).
+
+ // A drop-down on a stepped parameter: the picked name in a groove with a chevron.
+ // A click opens the list, the wheel steps through it, right-click bubbles to the
+ // parameter menu; MIDI learn and automation follow as for the chips it replaces.
+ Control Drop(string id, string[] names, string learn, double width)
{
- string pre = o == 0 ? "osc1" : "osc2";
- oscTableHosts[o] = new Panel { Children = { Chips(o == 0 ? "table" : "osc2table", Banks) } };
- oscWarpHosts[o] = new Panel { Children = { Chips(pre + "warpmode", WarpModes) } };
+ int n = names.Length;
+ var name = Mono("", TextPrimary, NotaType.RowLabel);
+ name.TextTrimming = TextTrimming.CharacterEllipsis;
+ var chev = new Glyph(GlyphKind.ChevronDown, 7)
+ {
+ Foreground = TextTertiary, Margin = new Thickness(4, 0, 0, 0), VerticalAlignment = VerticalAlignment.Center,
+ };
+ DockPanel.SetDock(chev, Dock.Right);
+ var box = new Border
+ {
+ Height = 16, Width = width, Background = NotaPalette.Groove, CornerRadius = NotaRadius.Cell,
+ Padding = new Thickness(6, 0, 5, 0), Cursor = new Cursor(StandardCursorType.Hand),
+ VerticalAlignment = VerticalAlignment.Center,
+ Child = new DockPanel { Children = { chev, name } },
+ };
+ box.BindResource(Border.BoxShadowProperty, "Shadow.Groove");
+ void Pick(int iv) { SetP(id, iv / (float)(n - 1)); Touch(); }
+ box.PointerPressed += (_, e) =>
+ {
+ if (!e.GetCurrentPoint(box).Properties.IsLeftButtonPressed) return;
+ var fly = new MenuFlyout();
+ int cur = Sel(id, n);
+ for (int i = 0; i < n; i++)
+ {
+ int iv = i;
+ var mi = new MenuItem { Header = names[i], ToggleType = MenuItemToggleType.Radio, IsChecked = i == cur };
+ mi.Click += (_, _) => Pick(iv);
+ fly.Items.Add(mi);
+ }
+ fly.ShowAt(box);
+ e.Handled = true;
+ };
+ box.PointerWheelChanged += (_, e) =>
+ {
+ if (WheelInput.Step(e, box) is not { } st) return;
+ e.Handled = true; if (st == 0) return;
+ Pick(Math.Clamp(Sel(id, n) - st, 0, n - 1));
+ };
+ readouts.Add(() => name.Text = names[Sel(id, n)]);
+ ToolTip.SetTip(box, learn + Loc.T("device.aurora.click_to_pick_scroll_to_step"));
+ if (I(id) is var pi and >= 0) MidiLearn.Bind(box, MidiTarget.PluginParam(track, -1, pi), learn);
+ return box;
}
- var oscPick = Segments(new[] { "1", "2" }, () => osel, iv => { osel = iv; Touch(); }, out var oscPickSync);
- readouts.Add(oscPickSync);
- ToolTip.SetTip(oscPick, Loc.T("device.aurora.the_oscillator_whose_table_and"));
- var oscTableStack = new Panel();
- foreach (var h in oscTableHosts) oscTableStack.Children.Add(h);
- var oscWarpStack = new Panel();
- foreach (var h in oscWarpHosts) oscWarpStack.Children.Add(h);
- var oscStrip = new StackPanel
- {
- Orientation = Orientation.Horizontal, Spacing = 4, VerticalAlignment = VerticalAlignment.Center,
- Children = { oscPick, oscTableStack, Cap("WARP"), oscWarpStack },
- };
- var oscGrid = new Grid
+ // What steers the position: the strongest matrix route into Position (it moves
+ // both oscillators, so both windows name it).
+ string PosModText()
{
- ColumnDefinitions = new ColumnDefinitions("40,*,*,*,*,*,*"),
- RowDefinitions = new RowDefinitions("Auto,Auto,Auto"),
- VerticalAlignment = VerticalAlignment.Top,
- };
- var oscNames = new TextBlock[2];
- for (int o = 0; o < 2; o++)
+ int best = -1; double mag = 0.02;
+ for (int s = 0; s < SrcNames.Length; s++)
+ {
+ double a = Math.Abs(G($"mtx{s}_2") - 0.5) * 2;
+ if (a > mag) { mag = a; best = s; }
+ }
+ return best < 0 ? "" : SrcNames[best].ToLowerInvariant() + " → pos";
+ }
+
+ Control OscColumn(int o)
{
- int ov = o;
string pre = o == 0 ? "osc1" : "osc2";
- string nm = o == 0 ? "OSC 1" : "OSC 2";
- int row = o * 2;
- if (o > 0) { var rule = Rule(); rule.Margin = new Thickness(0, 1); Grid.SetRow(rule, 1); Grid.SetColumnSpan(rule, 7); oscGrid.Children.Add(rule); }
- var name = Section(nm);
- oscNames[o] = name;
- var head = new StackPanel
+ string nm = Loc.F("device.aurora.osc_n", o + 1);
+ string tableId = o == 0 ? "table" : "osc2table";
+ string posId = o == 0 ? "position" : "osc2position";
+
+ var head = new Grid { ColumnDefinitions = new ColumnDefinitions("Auto,Auto,*,Auto,Auto"), ColumnSpacing = 5, Height = 18 };
+ var tableDrop = Drop(tableId, Banks, Loc.F("device.aurora.osc_table", nm), 74);
+ var warpDrop = Drop(pre + "warpmode", WarpModes, Loc.F("device.aurora.osc_warp_mode", nm), 52);
+ var headCells = new Control[] { Section(nm), Toggle("", pre + "on", () => G(pre + "on") >= 0.5f ? "on" : "off"), new Panel(), tableDrop, warpDrop };
+ for (int i = 0; i < headCells.Length; i++) { Grid.SetColumn(headCells[i], i); head.Children.Add(headCells[i]); }
+
+ // The window's caption, one line in its title row: the bank, the frame and what
+ // modulates the position.
+ var bankCap = Mono("", TextSecondary, NotaType.Axis);
+ var frameCap = Mono("", TextPrimary, NotaType.Axis);
+ var modCap = Mono("", Teal, NotaType.Axis);
+ modCap.HorizontalAlignment = HorizontalAlignment.Right;
+ readouts.Add(() =>
+ {
+ bankCap.Text = Banks[Sel(tableId, 4)];
+ frameCap.Text = FrameText(G(posId));
+ // Nothing drives Position: say so, greyed, as the single window did.
+ string mod = PosModText();
+ modCap.Text = mod.Length > 0 ? mod : Loc.T("device.aurora.no_modulation");
+ modCap.Foreground = mod.Length > 0 ? Teal : TextDisabled;
+ });
+ var capRow = new Grid
{
- Spacing = 3, VerticalAlignment = VerticalAlignment.Center, Cursor = new Cursor(StandardCursorType.Hand),
- Children = { name, Toggle("", pre + "on", () => G(pre + "on") >= 0.5f ? "on" : "off") },
+ ColumnDefinitions = new ColumnDefinitions("Auto,Auto,*"), ColumnSpacing = 5,
+ Margin = new Thickness(7, 3, 7, 0), VerticalAlignment = VerticalAlignment.Top, IsHitTestVisible = false,
};
- head.PointerPressed += (_, e) =>
+ capRow.Children.Add(bankCap);
+ Grid.SetColumn(frameCap, 1); capRow.Children.Add(frameCap);
+ Grid.SetColumn(modCap, 2); capRow.Children.Add(modCap);
+ stacks[o].TopInset = 12; // the caption line in the window's top edge
+ var window = new Panel { Children = { stacks[o], capRow } };
+
+ // Position is what the modulators reach for on this synth.
+ var knobs = new Grid { ColumnDefinitions = new ColumnDefinitions("*,*,*,*,*,*") };
+ var cells = new[]
{
- if (!e.GetCurrentPoint(head).Properties.IsLeftButtonPressed) return;
- osel = ov; Touch();
+ PKnob(posId, "Position", nm + " Position", FrameText, 34, 35, Teal), // what the modulators reach for: the modulation mark
+ PKnob(o == 0 ? "warp" : "osc2warp", "Warp", nm + " Warp", Pct, 34, 35),
+ PKnob(pre + "level", "Level", nm + " Level", Pct, 34, 35),
+ PKnob(pre + "oct", Loc.T("device.aurora.oct"), nm + " Octave", Oct, 34, 35),
+ PKnob(pre + "semi", Loc.T("device.aurora.semi"), nm + " Semi", Semi, 34, 35),
+ PKnob(pre + "detune", Loc.T("device.aurora.fine"), nm + " Fine", Cents, 34, 35),
};
- void Cell(Control c, int col) { Grid.SetRow(c, row); Grid.SetColumn(c, col); oscGrid.Children.Add(c); }
- Cell(head, 0);
- // Position is what the modulators reach for on this synth, so it wears teal.
- Cell(PKnob(o == 0 ? "position" : "osc2position", "POSITION", nm + " Position", FrameText, 34, 42, Teal), 1);
- Cell(PKnob(o == 0 ? "warp" : "osc2warp", "WARP", nm + " Warp", Pct, 34, 42), 2);
- Cell(PKnob(pre + "level", "LEVEL", nm + " Level", Pct, 34, 42), 3);
- Cell(PKnob(pre + "oct", "OCT", nm + " Octave", Oct, 34, 42), 4);
- Cell(PKnob(pre + "semi", "SEMI", nm + " Semi", Semi, 34, 42), 5);
- Cell(PKnob(pre + "detune", "FINE", nm + " Fine", Cents, 34, 42, Teal), 6);
- }
- applyOsc = () =>
- {
- for (int o = 0; o < 2; o++)
+ for (int i = 0; i < cells.Length; i++)
{
- oscTableHosts[o].IsVisible = oscWarpHosts[o].IsVisible = o == osel;
- oscNames[o].Foreground = o == osel ? AccentBright : TextPrimary;
+ cells[i].HorizontalAlignment = HorizontalAlignment.Center;
+ Grid.SetColumn(cells[i], i); knobs.Children.Add(cells[i]);
}
- };
+
+ var col = new Grid { RowDefinitions = new RowDefinitions("Auto,*,Auto"), RowSpacing = 3 };
+ Grid.SetRow(window, 1); Grid.SetRow(knobs, 2);
+ col.Children.Add(head); col.Children.Add(window); col.Children.Add(knobs);
+ // Off: everything but the name and the switch takes the unavailable look (the
+ // stack greys itself through Dimmed).
+ oscDimmed[o].AddRange(new Control[] { tableDrop, warpDrop, capRow, knobs });
+ return col;
+ }
// The sub and the unison stack are drag values, as the almanac draws them: a caps
// label over a mono readout, dragged up or down, double-clicked back to default.
@@ -504,38 +568,15 @@ internal sealed class AuroraInstrumentCard : IInstrumentCard
Padding = new Thickness(0, 3, 0, 0), Child = subUni,
};
- // The table window carries its own caption: which bank, which frame, and what is
- // steering the position.
- var tableCap = Mono("", TextTertiary, NotaType.Axis);
- var frameCap = Mono("", TextPrimary, NotaType.Axis);
- var posMod = Mono("", Teal, NotaType.Axis);
- readouts.Add(() =>
- {
- tableCap.Text = $"Table {osel + 1} · {Banks[Sel(osel == 0 ? "table" : "osc2table", 4)]}";
- frameCap.Text = "frame " + FrameText(G(osel == 0 ? "position" : "osc2position"));
- int best = -1; double mag = 0.02;
- for (int s = 0; s < SrcNames.Length; s++)
- {
- double a = Math.Abs(G($"mtx{s}_2") - 0.5) * 2;
- if (a > mag) { mag = a; best = s; }
- }
- posMod.Text = best < 0 ? Loc.T("device.aurora.no_modulation") : SrcNames[best].ToLowerInvariant() + " → pos";
- posMod.Foreground = best < 0 ? TextDisabled : Teal;
- });
- var tableOverlay = new StackPanel
- {
- Margin = new Thickness(7, 5), VerticalAlignment = VerticalAlignment.Top,
- HorizontalAlignment = HorizontalAlignment.Left, Spacing = 0, IsHitTestVisible = false,
- Children = { tableCap, frameCap, posMod },
- };
- stack.TopInset = 26; // the three caption lines the overlay puts in that corner
- var tableWindow = new Panel { Width = 128, Children = { stack, tableOverlay } };
- var oscMid = new Grid { ColumnDefinitions = new ColumnDefinitions("Auto,*"), ColumnSpacing = 6 };
- oscMid.Children.Add(tableWindow);
- Grid.SetColumn(oscGrid, 1); oscMid.Children.Add(oscGrid);
- var oscBodyGrid = new Grid { RowDefinitions = new RowDefinitions("Auto,*,Auto"), RowSpacing = 3 };
- var oscRows = new Control[] { oscStrip, oscMid, subUniRow };
- for (int i = 0; i < oscRows.Length; i++) { Grid.SetRow(oscRows[i], i); oscBodyGrid.Children.Add(oscRows[i]); }
+ var oscPair = new Grid { ColumnDefinitions = new ColumnDefinitions("*,Auto,*"), ColumnSpacing = 5 };
+ var col1 = OscColumn(0);
+ var oscRule = new Border { Width = 1, Background = NotaPalette.GraphBorder, Margin = new Thickness(0, 1) };
+ var col2 = OscColumn(1);
+ Grid.SetColumn(oscRule, 1); Grid.SetColumn(col2, 2);
+ oscPair.Children.Add(col1); oscPair.Children.Add(oscRule); oscPair.Children.Add(col2);
+ var oscBodyGrid = new Grid { RowDefinitions = new RowDefinitions("*,Auto"), RowSpacing = 3 };
+ Grid.SetRow(subUniRow, 1);
+ oscBodyGrid.Children.Add(oscPair); oscBodyGrid.Children.Add(subUniRow);
var oscBody = new Border { Padding = new Thickness(5, 3), Child = oscBodyGrid };
// ---- Filter tab -----------------------------------------------------------
@@ -879,9 +920,6 @@ internal sealed class AuroraInstrumentCard : IInstrumentCard
{
monoRow,
bendRow,
- Slider("POS 1", "position", () => FrameText(G("position")), labelW: 42, valueW: 42),
- Slider("CUTOFF", "cutoff", () => Hz(G("cutoff")), labelW: 42, valueW: 42),
- Slider("UNISON", "unidetune", () => Detune(G("unidetune")), labelW: 42, valueW: 42),
},
};
var globalGrid = new Grid { RowDefinitions = new RowDefinitions("Auto,*") };
diff --git a/src/managed/Nota.Application/Localization/en.json b/src/managed/Nota.Application/Localization/en.json
index 6dafee9f..6cedfff7 100644
--- a/src/managed/Nota.Application/Localization/en.json
+++ b/src/managed/Nota.Application/Localization/en.json
@@ -691,12 +691,18 @@
"device.aurora.8_in_use": "{0} / 8 in use",
"device.aurora.click_for_the_next_macros": "Click for the next macros, right-click for the previous",
"device.aurora.click_for_the_next_target": "Click for the next target, right-click for the previous",
+ "device.aurora.click_to_pick_scroll_to_step": " · click to pick, scroll to step",
"device.aurora.drag_a_cell_up_adds": "drag a cell — up adds, down subtracts · ⌥-click types · double-click clears",
"device.aurora.drag_to_change_double_click": " · drag to change, double-click to reset",
+ "device.aurora.fine": "Fine",
"device.aurora.no_modulation": "no modulation",
+ "device.aurora.oct": "Oct",
+ "device.aurora.osc_n": "Osc {0}",
+ "device.aurora.osc_table": "{0} Table",
+ "device.aurora.osc_warp_mode": "{0} Warp mode",
+ "device.aurora.semi": "Semi",
"device.aurora.shape_lfo": "Shape · LFO {0}",
"device.aurora.shape_lfo_1_caps": "SHAPE · LFO 1",
- "device.aurora.the_oscillator_whose_table_and": "The oscillator whose table and warp mode this strip edits",
"device.aurora.zero_every_route_in_the": "Zero every route in the matrix",
"device.auto_filter.analog_a_gentle_saturation_after": "Analog — a gentle saturation after the filter, like an analog circuit",
"device.auto_filter.cutoff_over_time": "Cutoff over time",
diff --git a/tests/Nota.SmokeTest/LocalizationAllowList.txt b/tests/Nota.SmokeTest/LocalizationAllowList.txt
index b3300aa4..c31d3f15 100644
--- a/tests/Nota.SmokeTest/LocalizationAllowList.txt
+++ b/tests/Nota.SmokeTest/LocalizationAllowList.txt
@@ -967,7 +967,6 @@ Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs Osc 2 # data: device pa
Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs Osc 2 level # data: device parameter, port and value names and live readouts of their values (FR-004)
Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs Osc 2 pitch # data: device parameter, port and value names and live readouts of their values (FR-004)
Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs Out Pan # data: device parameter, port and value names and live readouts of their values (FR-004)
-Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs POS 1 # data: device parameter, port and value names and live readouts of their values (FR-004)
Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs Pan # data: device parameter, port and value names and live readouts of their values (FR-004)
Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs Parallel # data: device parameter, port and value names and live readouts of their values (FR-004)
Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs Pitch # data: device parameter, port and value names and live readouts of their values (FR-004)
@@ -995,7 +994,6 @@ Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs Velocity # data: device
Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs Volume # todo: wrap in Loc.T
Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs Warp # data: device parameter, port and value names and live readouts of their values (FR-004)
Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs Wavetable # data: device parameter, port and value names and live readouts of their values (FR-004)
-Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs frame # data: device parameter, port and value names and live readouts of their values (FR-004)
Nota.App/DeviceCards/Instruments/AuroraInstrumentCard.cs → Amp # data: device parameter, port and value names and live readouts of their values (FR-004)
Nota.App/DeviceCards/Instruments/BassInstrumentCard.cs $"amp · flt · lfo {LfoNames[Sel(" # data: device parameter, port and value names and live readouts of their values (FR-004)
Nota.App/DeviceCards/Instruments/BassInstrumentCard.cs $"{Shape()} · {SubWords[Sel(" # data: device parameter, port and value names and live readouts of their values (FR-004)