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.

83.0 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
//
// M7-6a/b/c: read/write the `.nota` project bundle. C# owns serialization; the
// engine never touches the file (see ARCHITECTURE.md § Project format). Save queries
// live engine state into a ProjectDocument, dumps referenced samples into
// `samples/` and plugin state blobs into `plugin-states/`, and writes
// project.json atomically (temp + rename) with an auto-backup; Load replays the
// document through the existing structural-edit ops. Covered: transport,
// tracks/mixer, sends+return buses, built-in Synth + Sampler, built-in devices
// (params+bypass), hosted AU/VST3 instruments + effects (by stable identifier +
// state blob), MIDI clips/notes, arrangement audio clips, session MIDI/audio
// slots. A plugin missing on the opening machine is reported as a warning and
// downgraded (instrument -> empty Synth; effect -> skipped), never crashing.

using System;
using System.Collections.Generic;
using System.IO;
using System.Text.Json;
using System.Text.Json.Nodes;
using Nota.Application;

namespace Nota.Infrastructure;

public sealed class ProjectService
{
    /// <summary>On-disk format version. Files with a higher version are refused; older
    /// files are upgraded on Load via <see cref="ProjectMigrations"/>. v2 (M9-A4) adds
    /// automation lanes; v3 (M9-B4) adds hosted-plugin-param lanes (PluginParamId). To
    /// change the schema, bump this and append a migration (M7-9). v4 (M9-D) adds
    /// per-segment curvature (automationPoint.curve). v5 adds audio-clip pitch + warp
    /// (pitchSemitones / warpEnabled / warpMode / warpBeats). v6 adds warp markers.</summary>
    /// v18 (Phase 3) adds CV modulation: per-track LFO modulators + CV links to device params.
    /// v22 (specs/020) adds MIDI controller curves on MIDI clips and Session slot clips.
    /// v23 (specs/022) adds the Devices-panel fold on devices, MIDI effects and instruments.
    /// v25 (specs/044) adds references into rack chains (lanes, CV links, Arp CC targets) and
    /// chain children's sidechain keys / CC targets.
    /// v26 (specs/048) adds Preset on instruments, devices and MIDI effects.
    /// v27 (specs/046) adds Preview on hosted plug-ins: the picture of their window.
    /// v28 (specs/050) lets a sidechain key name one pad, chain or voice of its source.
    /// v29 (specs/067) adds Takes on audio tracks and TakeId on audio clips.
    /// v30 (specs/085) adds MidiOffsetMs and ArticulationMap on tracks and Articulation on notes.
    /// v31 (specs/053) adds Wavetables on Nota Aurora: its imported tables, as samples.
    /// v32 (specs/089) adds Cue on tracks and CueVolume on the mixer.
    public const int CurrentFormatVersion = 32;

    /// <summary>Manifest file name inside the bundle folder.</summary>
    public const string ManifestName = "project.json";

    private static readonly JsonSerializerOptions JsonOpts = new()
    {
        WriteIndented = true,
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
        DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull,
    };

    // --- capture (engine -> document) --------------------------------------

    /// <summary>Snapshots the engine's current state into a document. Content the
    /// format can't represent yet (hosted plugins) is appended to
    /// <paramref name="warnings"/>. Referenced samples are recorded in
    /// <see cref="ProjectDocument.SampleRefs"/> for <see cref="Save"/> to write.
    /// <paramref name="contentNames"/> = false names binaries by session id instead of by
    /// content hash — cheap, for change detection only; such a document must not be saved.</summary>
    public static ProjectDocument Capture(IAudioEngine engine, TransportState transport, List<string> warnings,
                                         bool contentNames = true)
    {
        var doc = new ProjectDocument
        {
            SessionNames = !contentNames,
            SceneCount = engine.SceneCount,
            Session = CaptureSession(engine),
            Transport = new TransportDto
            {
                Bpm = transport.Bpm,
                MasterVolume = transport.MasterVolume,
                MetronomeOn = transport.MetronomeOn,
                LoopOn = transport.LoopOn,
                LoopStart = engine.LoopEnd > engine.LoopStart ? engine.LoopStart : null,
                LoopEnd = engine.LoopEnd > engine.LoopStart ? engine.LoopEnd : null,
                TimeSigNumerator = transport.TimeSigNumerator,
                TimeSigDenominator = transport.TimeSigDenominator,
                Key = Nota.Application.Samples.MusicalKey.FromCode(transport.Key)?.Short,
            },
            Mixer = new MixerDto
            {
                PanLaw = engine.PanLaw == PanLaw.Stereo ? "stereo" : "balance",
                PanLawLegacy = transport.PanLawLegacy,
                CueVolume = Math.Abs(engine.CueVolume - 1f) > 1e-6f ? engine.CueVolume : null,
            },
            // Always written ([] when none), so a load can tell "no sections" from "older file".
            Sections = engine.Sections.Select(s => new SectionDto { Start = s.StartBeat, Length = s.LengthBeats, Name = s.Name }).ToList(),
        };

        int trackCount = engine.TrackCount;
        // Track id -> document index, for resolving cross-track references (sidechain, Phase B).
        var idToIndex = new Dictionary<int, int>();
        for (int i = 0; i < trackCount; i++)
            if (engine.TryGetTrackInfo(i, out var ti0)) idToIndex[ti0.Id] = i;

        for (int i = 0; i < trackCount; i++)
        {
            if (!engine.TryGetTrackInfo(i, out var ti)) continue;
            var t = new TrackDto
            {
                Type = ti.Type,
                Name = engine.GetTrackName(ti.Id) is { Length: > 0 } tn ? tn : null,
                Volume = ti.Volume,
                Pan = ti.Pan,
                Mute = ti.Muted != 0,
                Solo = ti.Soloed != 0,
                Armed = ti.Armed != 0,
                Cue = engine.GetTrackCue(ti.Id) ? true : null,
                ReturnIndex = engine.TrackReturnIndex(ti.Id),
                GroupId = ti.GroupId >= 0 && idToIndex.TryGetValue(ti.GroupId, out var gix) ? gix : -1,   // parent → doc index
                ColorIndex = engine.GetTrackColorIndex(ti.Id),
                PianoFold = engine.GetTrackPianoFold(ti.Id) ? true : null,
                EditLink = ti.IsGroup && engine.GetTrackEditLink(ti.Id) ? true : null,
                RecordInput = engine.GetTrackRecordInput(ti.Id) is var rin && rin > 0
                    ? (idToIndex.TryGetValue(rin, out var rix) ? rix + 2 : 0)   // track source → doc index + 2
                    : rin,                                                       // 0 hardware / -1 master
                Monitor = engine.GetTrackMonitor(ti.Id),
                InputChannels = engine.GetTrackInput(ti.Id).AsChannels is { } oldPick ? (int)oldPick : null,
                InputFirst = engine.GetTrackInput(ti.Id).First + 1,
                InputWidth = engine.GetTrackInput(ti.Id).Width,
                MidiFrom = engine.GetTrackMidiSource(ti.Id) is var mfrom && mfrom > 0
                    && idToIndex.TryGetValue(mfrom, out var mix) ? mix : -1,      // source → doc index, else off
                MidiOffsetMs = engine.GetTrackMidiOffsetMs(ti.Id) is var moff && moff != 0.0 ? moff : null,   // v30; 0 = omitted
                ArticulationMap = ti.IsInstrument ? CaptureArticulationMap(engine, ti.Id, warnings) : null,   // v30
            };
            if (ti.IsInstrument && engine.GetTrackMidiInput(ti.Id) is var midiIn)   // MIDI input (specs/086)
            {
                t.MidiInputUid = midiIn.Uid;
                t.MidiInputChannel = midiIn.Channel > 0 ? midiIn.Channel : null;
            }
            for (int b = 0; b < t.Sends.Length; b++) t.Sends[b] = engine.GetTrackSend(ti.Id, b);

            if (ti.IsInstrument)
            {
                int kind = engine.TrackInstrumentKind(ti.Id);
                var instDto = new InstrumentDto { Kind = kind };
                if (kind == 1 || kind == 10)   // Sampler + Nota Grain both bundle their sample
                {
                    var sd = new SamplerDto();
                    NotaSamplerInfo si;
                    bool ok = kind == 1 ? engine.TryGetSamplerInfo(ti.Id, out si) : engine.TryGetGrainInfo(ti.Id, out si);
                    if (ok)
                    {
                        sd.RootNote = si.RootNote;
                        sd.Loop = si.Loop != 0;
                        if (si.SampleId != 0) sd.Sample = RegisterSample(doc, engine, si.SampleId, warnings) ?? "";
                        if (si.SampleId != 0) sd.Name = engine.SampleName(si.SampleId);
                    }
                    int pc = engine.PluginParamCount(ti.Id, -1);
                    sd.Params = new float[pc];
                    for (int p = 0; p < pc; p++) sd.Params[p] = engine.PluginParamGet(ti.Id, -1, p);
                    instDto.Sampler = sd;
                }
                else if (kind < 0)
                {
                    string pid = engine.TrackInstrumentPluginId(ti.Id);
                    if (pid.Length == 0)
                        warnings.Add($"Track {i + 1}: plugin instrument couldn't be identified and was skipped.");
                    else
                    {
                        instDto.PluginId = pid;
                        instDto.State = RegisterBlob(doc, engine.GetPluginState(ti.Id, -1));
                    }
                }
                else if (kind == 5)   // Nota Aurora: the blob without its tables, which go to samples/
                {
                    instDto.State = RegisterBlob(doc, engine.AuroraState(ti.Id, includeTables: false));
                    instDto.Wavetables = CaptureWavetables(doc, engine, ti.Id);
                }
                else   // every other built-in instrument (Synth/Physical/Volt/Instrument
                {      // Rack/Drum Rack/Flux) persists its state blob — the load path rebuilds from it.
                    instDto.State = RegisterBlob(doc, engine.GetPluginState(ti.Id, -1));
                }
                // Nota Rhythm Phase 2: bundle each sample-source voice's one-shot separately
                // (the state blob holds only the source flags, not the audio).
                if (kind == 12)
                {
                    var vs = new System.Collections.Generic.List<VoiceSampleDto>();
                    for (int v = 0; v < 8; v++)
                    {
                        // A voice keeps its one-shot while it plays the synth, so save it either way.
                        if (!engine.TryGetRhythmVoiceInfo(ti.Id, v, out var vi) || vi.SampleId == 0) continue;
                        string? rel = RegisterSample(doc, engine, vi.SampleId, warnings);
                        if (rel != null) vs.Add(new VoiceSampleDto { Voice = v, Sample = rel, Synth = engine.RhythmVoiceSource(ti.Id, v) != 1 });
                    }
                    if (vs.Count > 0) instDto.VoiceSamples = vs;
                }
                // React source (Nota Flux): store as a doc index, resolved on load.
                // A key whose part is gone (Missing) saves as no key (specs/050).
                var instKey = engine.InstrumentSidechainKey(ti.Id);
                int isi = -1;
                bool instKeyed = instKey.Source >= 0 && instKey.Part != SidechainKey.Missing && idToIndex.TryGetValue(instKey.Source, out isi);
                instDto.SidechainSource = instKeyed ? isi : -1;
                instDto.SidechainPart = instKeyed ? instKey.Part : -1;
                instDto.Folded = engine.DeviceFolded(ti.Id, -1);
                instDto.Bypassed = engine.DeviceBypassed(ti.Id, -1);
                instDto.Preset = CapturePresetTag(engine, ti.Id, PresetSurface.Instrument, -1);
                instDto.Preview = RegisterBlob(doc, engine.GetPluginPreview(ti.Id, -1));   // a plug-in's window picture (specs/046)
                t.Instrument = instDto;
            }

            // MIDI effects (before the instrument): built-in kind + generic params.
            int midiCount = engine.TrackMidiEffectCount(ti.Id);
            for (int m = 0; m < midiCount; m++)
            {
                var mdev = new MidiDeviceDto { Kind = engine.MidiEffectKind(ti.Id, m), Bypassed = engine.MidiEffectBypassed(ti.Id, m), Folded = engine.MidiEffectFolded(ti.Id, m) };
                int pc = engine.MidiEffectParamCount(ti.Id, m);
                mdev.Params = new float[pc];
                for (int p = 0; p < pc; p++) mdev.Params[p] = engine.MidiEffectGetParam(ti.Id, m, p);
                mdev.CcDestDevice = engine.MidiEffectCcDestDevice(ti.Id, m);
                mdev.CcDestParam = engine.MidiEffectCcDestParam(ti.Id, m);
                var (ccChain, ccSlot) = engine.MidiEffectCcDestPath(ti.Id, m);
                if (ccChain >= 0) { mdev.CcDestChain = ccChain; mdev.CcDestSlot = ccSlot; }
                mdev.CcDepth = engine.MidiEffectCcDepth(ti.Id, m);
                var mstate = engine.MidiEffectGetState(ti.Id, m);   // the MIDI Effect Rack's structure
                if (mstate.Length > 0) mdev.State = RegisterBlob(doc, mstate);
                mdev.Preset = CapturePresetTag(engine, ti.Id, PresetSurface.MidiEffect, m);
                t.MidiEffects.Add(mdev);
            }

            // Devices: built-in parameters, or hosted-plugin identity + state.
            t.Devices.AddRange(CaptureDevices(engine, ti.Id, doc, idToIndex, warnings, $"Track {i + 1}"));

            // Freeze (M7): bundle the frozen-audio blob so the track re-opens frozen.
            if (engine.IsTrackFrozen(ti.Id))
                t.FrozenState = RegisterBlob(doc, engine.GetFreezeState(ti.Id));

            // Arrangement clips.
            if (ti.IsInstrument)
            {
                for (int c = 0; c < ti.ClipCount; c++)
                {
                    if (!engine.TryGetClipInfo(ti.Id, c, out var ci) || !ci.IsMidi) continue;
                    var vel = engine.GetMidiClipEnvelope(ti.Id, c, MidiClipEnvelope.Velocity);   // v10
                    var vol = engine.GetMidiClipEnvelope(ti.Id, c, MidiClipEnvelope.Volume);
                    t.MidiClips.Add(new MidiClipDto
                    {
                        Name = engine.GetClipName(ti.Id, c) is { Length: > 0 } mn ? mn : null,
                        Active = ci.IsActive,
                        StartBeat = ci.StartBeat,
                        LengthBeats = ci.LengthBeats,
                        Notes = ToDtos(engine, engine.GetClipNotes(ti.Id, c)),
                        VelocityEnvelope = vel.Length > 0 ? System.Array.ConvertAll(vel, p => new AutomationPointDto(p)) : null,
                        VolumeEnvelope = vol.Length > 0 ? System.Array.ConvertAll(vol, p => new AutomationPointDto(p)) : null,
                        Controllers = CaptureControllers(engine.GetMidiClipControllers(ti.Id, c), ctl => engine.GetMidiClipController(ti.Id, c, ctl)),
                    });
                }
            }
            else if (ti.Type == 0) // audio track
            {
                for (int c = 0; c < ti.ClipCount; c++)
                {
                    if (!engine.TryGetAudioClipInfo(ti.Id, c, out var ac)) continue;
                    string? rel = RegisterSample(doc, engine, ac.SampleId, warnings);
                    if (rel == null) continue;
                    var dto = AudioClipState.Capture(engine, ti.Id, c, ac);
                    dto.Sample = rel;
                    dto.Source = SourceOf(engine, ac.SampleId);
                    int take = engine.ClipTakeId(ti.Id, c);
                    if (take != 0) dto.TakeId = take;
                    int joined = engine.ClipJoinedEdges(ti.Id, c);
                    if (joined != 0) dto.JoinedEdges = joined;
                    t.AudioClips.Add(dto);
                }
                for (int k = 0; k < engine.TakeCount(ti.Id); k++)
                {
                    if (!engine.TryGetTakeInfo(ti.Id, k, out var tk)) continue;
                    string? rel = RegisterSample(doc, engine, tk.SampleId, warnings);
                    if (rel == null) continue;
                    (t.Takes ??= new List<AudioTakeDto>()).Add(new AudioTakeDto
                    {
                        Id = tk.Id, Number = tk.Number, Group = tk.Group, Sample = rel, Source = SourceOf(engine, tk.SampleId),
                        OriginBeat = tk.OriginBeat, SourceOffsetFrames = tk.SourceOffsetFrames, LengthFrames = tk.LengthFrames,
                    });
                }
            }

            // Session slots.
            for (int s = 0; s < engine.SceneCount; s++)
            {
                if (!engine.GetSessionSlotStopButton(ti.Id, s) && engine.SessionSlotState(ti.Id, s) == 0)
                    (t.SessionNoStop ??= new List<int>()).Add(s);
                // Persist any slot that holds a clip — skip only truly empty ones. (A slot
                // that's playing/queued/recording is state 2-4, not 1, but still has content;
                // gating on == 1 dropped it when saving mid-jam.)
                if (engine.SessionSlotState(ti.Id, s) == 0) continue;
                if (ti.IsInstrument)
                {
                    t.SessionSlots.Add(WithClipProps(engine, ti.Id, new SessionSlotDto
                    {
                        Scene = s,
                        LengthBeats = engine.SessionSlotLength(ti.Id, s),
                        Notes = ToDtos(engine, engine.GetSessionNotes(ti.Id, s)),
                        Controllers = CaptureControllers(engine.GetSessionControllers(ti.Id, s), ctl => engine.GetSessionController(ti.Id, s, ctl)),
                    }));
                }
                else if (ti.Type == 0 && engine.TryGetSessionAudioSlot(ti.Id, s, out var sa))
                {
                    string? rel = RegisterSample(doc, engine, sa.SampleId, warnings);
                    if (rel == null) continue;
                    // The take is a full audio clip (region, warp, pitch, envelopes): saved like one.
                    var audio = engine.TryGetAudioClipInfo(ti.Id, SessionClip.Index(s), out var sac)
                        ? AudioClipState.Capture(engine, ti.Id, SessionClip.Index(s), sac)
                        : new AudioClipDto { SourceOffsetFrames = sa.SourceOffsetFrames, LengthFrames = sa.LengthFrames, Gain = sa.Gain };
                    audio.Sample = rel;
                    audio.Source = SourceOf(engine, sa.SampleId);
                    audio.Name = null;   // the slot carries its own name
                    t.SessionSlots.Add(WithClipProps(engine, ti.Id, new SessionSlotDto
                    {
                        Scene = s,
                        LengthBeats = sa.LengthBeats,
                        Audio = audio,
                    }));
                }
            }

            // Automation lanes (M9-A4; plugin-param lanes carry a stable id, M9-B4).
            int laneCount = engine.AutomationLaneCount(ti.Id);
            for (int l = 0; l < laneCount; l++)
            {
                var info = engine.AutomationLaneInfo(ti.Id, l);
                var (laneChain, laneSlot) = engine.AutomationLanePath(ti.Id, l);
                t.Automation.Add(new AutomationLaneDto
                {
                    Chain = laneChain >= 0 ? laneChain : null,
                    Slot = laneChain >= 0 ? laneSlot : null,
                    Target = (int)info.Target,
                    DeviceIndex = info.DeviceIndex,
                    ParamIndex = info.ParamIndex,
                    PluginParamId = info.Target == AutomationTarget.PluginParam
                        ? engine.AutomationLaneParamId(ti.Id, l) : null,
                    Points = System.Array.ConvertAll(engine.GetAutomationPoints(ti.Id, l),
                        p => new AutomationPointDto(p)),
                });
            }

            // CV modulation (Phase 3): LFO sources + links to device params.
            int modCount = engine.ModulatorCount(ti.Id);
            for (int m = 0; m < modCount; m++)
            {
                int id = engine.ModulatorIdAt(ti.Id, m);
                t.Modulators.Add(new ModulatorDto
                {
                    Id = id,
                    Kind = engine.ModulatorKind(ti.Id, id),
                    Waveform = (int)engine.ModulatorGet(ti.Id, id, 0),
                    TempoSync = engine.ModulatorGet(ti.Id, id, 1) > 0.5f,
                    RateHz = engine.ModulatorGet(ti.Id, id, 2),
                    RateSyncBeats = engine.ModulatorGet(ti.Id, id, 3),
                    Depth = engine.ModulatorGet(ti.Id, id, 4),
                    Phase = engine.ModulatorGet(ti.Id, id, 5),
                    Attack = engine.ModulatorGet(ti.Id, id, 6),
                    Release = engine.ModulatorGet(ti.Id, id, 7),
                    Decay = engine.ModulatorGet(ti.Id, id, 8),
                    Sustain = engine.ModulatorGet(ti.Id, id, 9),
                    InputA = (int)engine.ModulatorGet(ti.Id, id, 10),
                    InputB = (int)engine.ModulatorGet(ti.Id, id, 11),
                    MathOffset = engine.ModulatorGet(ti.Id, id, 12),
                    ScopeWindowMs = engine.ModulatorGet(ti.Id, id, 13),
                    ScopeSync = engine.ModulatorGet(ti.Id, id, 14) > 0.5f,
                    ScopeWindowBeats = engine.ModulatorGet(ti.Id, id, 15),
                    ScopeZoom = (int)engine.ModulatorGet(ti.Id, id, 16),
                    ScopeTrigger = (int)engine.ModulatorGet(ti.Id, id, 17),
                    ScopeHeight = engine.ModulatorGet(ti.Id, id, 18),
                });
            }
            int cvCount = engine.CvLinkCount(ti.Id);
            for (int c = 0; c < cvCount; c++)
            {
                int tgtId = engine.CvLinkTargetTrack(ti.Id, c);   // -1 = self
                var path = engine.CvLinkPath(ti.Id, c);
                t.CvLinks.Add(new CvLinkDto
                {
                    SourceChain = path.SourceChain >= 0 ? path.SourceChain : null,
                    SourceSlot = path.SourceChain >= 0 ? path.SourceSlot : null,
                    TargetChain = path.TargetChain >= 0 ? path.TargetChain : null,
                    TargetSlot = path.TargetChain >= 0 ? path.TargetSlot : null,
                    Source = engine.CvLinkSource(ti.Id, c),
                    SourceKind = engine.CvLinkSourceKind(ti.Id, c),
                    SourceDevice = engine.CvLinkSourceDevice(ti.Id, c),
                    SourceParam = engine.CvLinkSourceParam(ti.Id, c),
                    TargetKind = engine.CvLinkTargetKind(ti.Id, c),
                    TargetTrack = tgtId >= 0 && idToIndex.TryGetValue(tgtId, out var tix) ? tix : -1,
                    Device = engine.CvLinkDevice(ti.Id, c),
                    Param = engine.CvLinkParam(ti.Id, c),
                    Depth = engine.CvLinkDepth(ti.Id, c),
                    Mode = engine.CvLinkMode(ti.Id, c),
                    Base = engine.CvLinkBase(ti.Id, c),
                });
            }

            SaveNestedLinks(engine, ti.Id, t, idToIndex);
            doc.Tracks.Add(t);
        }

        // Master-volume automation (graph-level, format v7).
        doc.MasterVolumeAutomation = new List<AutomationPointDto>(
            System.Array.ConvertAll(engine.GetMasterVolumeAutomation(), p => new AutomationPointDto(p)));

        // Master effect chain + its name/colour.
        int masterId = engine.MasterTrackId;
        doc.Master = new MasterDto
        {
            Name = engine.GetTrackName(masterId) is { Length: > 0 } mName ? mName : null,
            ColorIndex = engine.GetTrackColorIndex(masterId),
            Devices = CaptureDevices(engine, masterId, doc, idToIndex, warnings, "Master"),
            NestedSidechains = NestedLinks(engine, masterId, idToIndex).Item1,   // keys inside the master's racks
        };

        return doc;
    }

    // Capture a track's device chain (built-in params / plugin identity+state / rack blob,
    // plus sidechain routing as a doc index). Shared by tracks and the master.
    // A device's preset tag (specs/048): what it was loaded from and the values it left.
    private static PresetTagDto? CapturePresetTag(IAudioEngine engine, int trackId, PresetSurface surface, int index)
        => engine.PresetTagInfo(engine.DevicePresetTag(trackId, surface, index)) is { Id.Length: > 0 } tag
            ? new PresetTagDto { Id = tag.Id, Name = tag.Name, Loaded = tag.Loaded } : null;

    private static void ApplyPresetTag(IAudioEngine engine, int trackId, PresetSurface surface, int index, PresetTagDto? tag)
    {
        if (tag is { Id.Length: > 0 })
            engine.SetDevicePresetTag(trackId, surface, index, tag.Id, tag.Name, tag.Loaded.Length > 0 ? tag.Loaded : null);
    }

    private static List<DeviceDto> CaptureDevices(IAudioEngine engine, int trackId, ProjectDocument doc,
                                                  Dictionary<int, int> idToIndex, List<string> warnings, string label)
    {
        var list = new List<DeviceDto>();
        int deviceCount = engine.TrackDeviceCount(trackId);
        for (int d = 0; d < deviceCount; d++)
        {
            int bk = engine.TrackDeviceBuiltinKind(trackId, d);
            var dev = new DeviceDto { BuiltinKind = bk, Bypassed = engine.DeviceBypassed(trackId, d), Folded = engine.DeviceFolded(trackId, d) };
            // Source as a doc index, its part as an index on that track; a key whose part is
            // gone (Missing) saves as no key (specs/050).
            var key = engine.DeviceSidechainKey(trackId, d);
            int si = -1;
            bool keyed = key.Source >= 0 && key.Part != SidechainKey.Missing && idToIndex.TryGetValue(key.Source, out si);
            dev.SidechainSource = keyed ? si : -1;
            dev.SidechainPart = keyed ? key.Part : -1;
            dev.SidechainGain = engine.DeviceSidechainGain(trackId, d);
            dev.SidechainMix = engine.DeviceSidechainMix(trackId, d);
            dev.SidechainTapPre = engine.DeviceSidechainTapPre(trackId, d);
            if (bk < 0) // hosted plugin
            {
                string pid = engine.TrackDevicePluginId(trackId, d);
                if (pid.Length == 0)
                {
                    warnings.Add($"{label}: plugin effect \"{engine.DeviceName(trackId, d)}\" couldn't be identified and was skipped.");
                    continue;
                }
                dev.PluginId = pid;
                dev.State = RegisterBlob(doc, engine.GetPluginState(trackId, d));
            }
            else if (bk == 5) // Audio Effect Rack: structural blob
            {
                dev.State = RegisterBlob(doc, engine.GetPluginState(trackId, d));
            }
            else // built-in: generic params (+ an optional state blob, e.g. the looper's PCM)
            {
                int pc = engine.DeviceParamCount(trackId, d);
                dev.Params = new float[pc];
                for (int p = 0; p < pc; p++) dev.Params[p] = engine.DeviceGetParam(trackId, d, p);
                dev.State = RegisterBlob(doc, engine.DeviceGetState(trackId, d));
            }
            dev.Preset = CapturePresetTag(engine, trackId, PresetSurface.Effect, d);
            dev.Preview = RegisterBlob(doc, engine.GetPluginPreview(trackId, d));   // a plug-in's window picture (specs/046)
            list.Add(dev);
        }
        return list;
    }

    // Recreate a device chain onto a track (or the master). Sidechain sources are deferred
    // (resolved once every track exists).
    // Links on devices inside the track's racks that the rack blob can't hold (specs/044): a
    // chain child's sidechain key (source as a doc index) and a chain MIDI effect's CC target.
    private static void SaveNestedLinks(IAudioEngine engine, int trackId, TrackDto t, Dictionary<int, int> idToIndex)
    {
        var (scs, ccs) = NestedLinks(engine, trackId, idToIndex);
        t.NestedSidechains = scs;
        t.NestedCcRoutes = ccs;
    }

    private static (List<NestedSidechainDto>?, List<NestedCcRouteDto>?) NestedLinks(IAudioEngine engine, int trackId, Dictionary<int, int> idToIndex)
    {
        var scs = new List<NestedSidechainDto>();
        var ccs = new List<NestedCcRouteDto>();
        void Rack(int host, int chains, System.Func<int, int> devCount, System.Func<int, int> midiCount, bool hasInstrument)
        {
            for (int c = 0; c < chains; c++)
            {
                int n = devCount(c);
                for (int slot = hasInstrument ? -1 : 0; slot < n; slot++)
                    if (engine.RackChainSidechain(trackId, host, c, slot) is { SourceTrack: >= 0 } sc
                        && idToIndex.TryGetValue(sc.SourceTrack, out int src)
                        && engine.RackChainSidechainPart(trackId, host, c, slot) is var part && part != SidechainKey.Missing)
                        scs.Add(new NestedSidechainDto { Host = host, Chain = c, Slot = slot, Source = src, Part = part, TapPre = sc.TapPre, GainDb = sc.GainDb, Mix = sc.Mix });
                int mn = midiCount(c);
                for (int i = 0; i < mn; i++)
                    if (engine.RackChainMidiCcDest(trackId, host, c, i) is { } d && (d.Device >= 0 || d.Chain >= 0) && d.Param >= 0)
                        ccs.Add(new NestedCcRouteDto { Host = host, Chain = c, Index = i, DestDevice = d.Device, DestChain = d.Chain, DestSlot = d.Slot, Param = d.Param, Depth = d.Depth });
            }
        }
        if (engine.RackChainCount(trackId) > 0)   // 0 unless the instrument is a rack
            Rack(-1, engine.RackChainCount(trackId), c => engine.RackChainDeviceCount(trackId, c), c => engine.RackChainMidiCount(trackId, c), true);
        int devs = engine.TrackDeviceCount(trackId);
        for (int d = 0; d < devs; d++)
            if (engine.TrackDeviceBuiltinKind(trackId, d) == 5)
                Rack(d, engine.RackDevChainCount(trackId, d), c => engine.RackDevChainDeviceCount(trackId, d, c), _ => 0, false);
        int mids = engine.TrackMidiEffectCount(trackId);
        for (int m = 0; m < mids; m++)
            if (engine.MidiEffectKind(trackId, m) == 6)
                Rack(-1000 - m, engine.MidiRackChainCount(trackId, m), _ => 0, c => engine.MidiRackChainDeviceCount(trackId, m, c), false);
        return (scs.Count > 0 ? scs : null, ccs.Count > 0 ? ccs : null);
    }

    private static void ApplyDevices(IAudioEngine engine, int trackId, IEnumerable<DeviceDto> devices,
                                     string bundleDir, List<(int track, int dev, int srcIndex, int part)> scDeferred, List<string> warnings)
    {
        foreach (var d in devices)
        {
            int di;
            if (d.BuiltinKind < 0) // hosted plugin
            {
                if (d.PluginId is not { Length: > 0 } pid) continue;
                int idx = NotaEngine.PluginIndexOfId(pid);
                di = idx >= 0 ? engine.AddTrackEffectPlugin(trackId, idx) : -1;
                if (di < 0) { warnings.Add($"Plugin effect \"{pid}\" isn't installed and was skipped."); continue; }
                if (d.State is { } stateRel)
                {
                    var blob = ReadBlob(bundleDir, stateRel);
                    if (blob.Length > 0) engine.SetPluginState(trackId, di, blob);
                }
            }
            else
            {
                di = engine.AddBuiltinDevice(trackId, d.BuiltinKind);
                if (di < 0) { warnings.Add($"Couldn't recreate a device (kind {d.BuiltinKind})."); continue; }
                if (d.BuiltinKind == 5)
                {
                    if (d.State is { } rackRel)
                    {
                        var blob = ReadBlob(bundleDir, rackRel);
                        if (blob.Length > 0) engine.SetPluginState(trackId, di, blob);
                    }
                }
                else
                {
                    int pc = engine.DeviceParamCount(trackId, di);
                    for (int p = 0; p < d.Params.Length && p < pc; p++) engine.DeviceSetParam(trackId, di, p, d.Params[p]);
                    // Nota EQ-3 appended Range (the fader law); a save without it was made in the Classic ±15 dB law.
                    if (d.BuiltinKind == 16 && d.Params.Length <= 10 && pc > 10) engine.DeviceSetParam(trackId, di, 10, 0f);
                    if (d.State is { } devRel)
                    {
                        var blob = ReadBlob(bundleDir, devRel);
                        if (blob.Length > 0) engine.DeviceSetState(trackId, di, blob);
                    }
                }
            }
            if (d.Bypassed) engine.SetDeviceBypassed(trackId, di, true);
            if (d.Folded) engine.SetDeviceFolded(trackId, di, true);
            ApplyPresetTag(engine, trackId, PresetSurface.Effect, di, d.Preset);
            if (d.Preview is { } previewRel) engine.SetPluginPreview(trackId, di, ReadPreview(bundleDir, previewRel));
            if (d.SidechainSource >= 0) scDeferred.Add((trackId, di, d.SidechainSource, d.SidechainPart));
            engine.SetDeviceSidechainGain(trackId, di, d.SidechainGain);
            engine.SetDeviceSidechainMix(trackId, di, d.SidechainMix);
            engine.SetDeviceSidechainTapPre(trackId, di, d.SidechainTapPre);
        }
    }

    // --- apply (document -> engine) ----------------------------------------

    /// <summary>Rebuilds the engine from a document. Resets the engine first, so
    /// call after the user confirms discarding the current project. Transport is
    /// NOT applied here (the UI applies it via its view-model so controls update),
    /// except the tempo as a baseline for the clips.
    /// <paramref name="bundleDir"/> resolves sample paths. Returns warnings for
    /// content downgraded on load.</summary>
    public static IReadOnlyList<string> Apply(ProjectDocument doc, IAudioEngine engine, string bundleDir)
    {
        var warnings = new List<string>();
        engine.Reset();

        // The saved tempo before any clip (specs/067): take lanes lay their comp out on it, so a
        // section the user moved isn't mistaken for one still on its take when the UI's tempo lands.
        if (doc.Transport.Bpm > 0) engine.SetBpm(doc.Transport.Bpm);

        // The loop: its region as saved (#455) and whether it's on; the transport bar reads both back.
        if (doc.Transport.LoopStart is double ls && doc.Transport.LoopEnd is double le && le > ls)
            engine.SetLoop(doc.Transport.LoopOn, ls, le);
        else
            engine.SetLoop(doc.Transport.LoopOn, engine.LoopStart, engine.LoopEnd);

        // Pan law (specs/006) first, as the baseline rather than an undo step. A missing mixer
        // is a pre-v21 project: Balance, so the mix sounds as it was saved.
        engine.SetPanLaw(ParsePanLaw(doc.Mixer?.PanLaw, warnings), checkpoint: false);
        // The Cue level (specs/089): a listening level, not part of the mix — no undo step.
        engine.CueVolume = doc.Mixer?.CueVolume is float cv && float.IsFinite(cv) ? Math.Clamp(cv, 0f, 2f) : 1f;

        // Arrangement sections (specs/016), also a baseline. A file from before they moved into
        // the project keeps them in the bundle's sidecar.
        var sections = doc.Sections ?? ReadLegacySections(bundleDir);
        engine.SetSections(sections.Select(d => new SectionInfo(d.Start, d.Length, d.Name ?? "")).ToList(), checkpoint: false);

        // Restore the scene count before tracks so their session slots size to it (the doc may
        // hold more/fewer scenes than the fresh default after add/remove-scene edits).
        while (engine.SceneCount < doc.SceneCount) engine.AddScene();
        while (engine.SceneCount > doc.SceneCount && engine.SceneCount > 1) engine.RemoveScene(engine.SceneCount - 1);
        ApplySession(engine, doc.Session);

        // Doc index -> new live track id, and deferred sidechain wiring (a source may be
        // a track created later), both resolved after every track exists (Phase B).
        var newTrackIds = new List<int>();
        var scDeferred = new List<(int track, int dev, int srcIndex, int part)>();
        var nestedScDeferred = new List<(int track, NestedSidechainDto dto)>();
        var instScDeferred = new List<(int track, int srcIndex, int part)>();   // instrument React source (Nota Flux)
        var recInputDeferred = new List<(int trackId, int encoded)>();
        var monitorDeferred = new List<(int trackId, bool on)>();
        var groupDeferred = new List<(int trackId, int parentDocIndex)>();   // group membership
        var midiFromDeferred = new List<(int trackId, int sourceDocIndex)>();  // MIDI routing source ("MIDI In")
        // CV links resolved after all tracks exist (cross-track targets are doc-indices).
        var cvLinkDeferred = new List<(int owner, CvLinkDto dto, int modId)>();

        foreach (var t in doc.Tracks)
        {
            int id;
            if (t.Type == 2)
            {
                id = engine.AddReturnTrack();
            }
            else if (t.Type == 1)
            {
                if (t.Instrument is { Kind: 1, Sampler: { } sd })
                {
                    id = sd.Sample.Length == 0
                        ? engine.AddSamplerInstrumentTrack()   // empty Sampler
                        : engine.AddSamplerTrack(ResolveInBundle(bundleDir, sd.Sample), sd.RootNote, sd.Loop);
                    if (id <= 0)
                    {
                        warnings.Add($"Couldn't reload sampler \"{sd.Sample}\" — using an empty Volt track.");
                        id = engine.AddVoltSynthTrack();
                    }
                    else
                    {
                        int pc = engine.PluginParamCount(id, -1);
                        for (int p = 0; p < sd.Params.Length && p < pc; p++) engine.PluginParamSet(id, -1, p, sd.Params[p]);
                        if (engine.TryGetSamplerInfo(id, out var nsi))
                        {
                            BundleContent.SeedSample(engine, nsi.SampleId, sd.Sample);
                            if (sd.Name.Length > 0) engine.SetSampleName(nsi.SampleId, sd.Name);
                        }
                    }
                }
                else if (t.Instrument is { Kind: 10, Sampler: { } gd })   // Nota Grain: sample + params
                {
                    id = engine.AddGrainSynthTrack();
                    if (id > 0)
                    {
                        if (gd.Sample.Length > 0 && engine.SetTrackGrainSample(id, ResolveInBundle(bundleDir, gd.Sample), gd.RootNote)
                            && engine.TryGetGrainInfo(id, out var ggi))
                            BundleContent.SeedSample(engine, ggi.SampleId, gd.Sample);
                        int pc = engine.PluginParamCount(id, -1);
                        for (int p = 0; p < gd.Params.Length && p < pc; p++) engine.PluginParamSet(id, -1, p, gd.Params[p]);
                    }
                }
                else if (t.Instrument is { Kind: < 0, PluginId: { Length: > 0 } pid })
                {
                    int idx = NotaEngine.PluginIndexOfId(pid);
                    id = idx >= 0 ? engine.AddPluginInstrumentTrack(idx) : 0;
                    if (id <= 0)
                    {
                        warnings.Add($"Plugin instrument \"{pid}\" isn't installed — using an empty Volt track.");
                        id = engine.AddVoltSynthTrack();
                    }
                    else if (t.Instrument.State is { } stateRel)
                    {
                        var blob = ReadBlob(bundleDir, stateRel);
                        if (blob.Length > 0) engine.SetPluginState(id, -1, blob);
                    }
                }
                else if (t.Instrument is { Kind: 3 or 4 })   // Instrument / Drum Rack: the blob rebuilds every chain/pad
                {
                    id = t.Instrument.Kind == 4 ? engine.AddDrumRackTrack() : engine.AddInstrumentRackTrack();
                    if (t.Instrument.State is { } rackState)
                    {
                        var blob = ReadBlob(bundleDir, rackState);
                        if (blob.Length > 0) engine.SetPluginState(id, -1, blob);
                    }
                }
                else
                {
                    id = t.Instrument switch
                    {
                        { Kind: 2 } => engine.AddPhysicalSynthTrack(),   // Nota Physical
                        { Kind: 5 } => engine.AddWavetableSynthTrack(),  // Nota Aurora
                        { Kind: 6 } => engine.AddVoltSynthTrack(),       // Nota Volt
                        { Kind: 7 } => engine.AddBassSynthTrack(),       // Nota Bass
                        { Kind: 8 } => engine.AddPendulumSynthTrack(),   // Nota Pendulum
                        { Kind: 9 } => engine.AddOperatorSynthTrack(),   // Nota Operator
                        { Kind: 11 } => engine.AddFluxSynthTrack(),      // Nota Flux
                        { Kind: 12 } => engine.AddRhythmTrack(),         // Nota Rhythm
                        { Kind: 13 } => engine.AddMonolithTrack(),       // Nota Monolith
                        { Kind: 14 } => engine.AddPentadTrack(),         // Nota Pentad
                        { Kind: 15 } => engine.AddConsortTrack(),        // Nota Consort
                        { Kind: 16 } => engine.AddKeysTrack(),           // Nota Keys
                        { Kind: 17 } => engine.AddMosaicTrack(),         // Nota Mosaic (its program rides the state blob)
                        { Kind: 18 } => engine.AddTwinTrack(),           // Nota Twin
                        _ => engine.AddInstrumentTrack(),                // Nota Synth
                    };
                    if (t.Instrument?.State is { } synthState)
                    {
                        var blob = ReadBlob(bundleDir, synthState);
                        if (blob.Length > 0) engine.SetPluginState(id, -1, blob);
                    }
                    // Nota Aurora: its imported tables, from samples/ (specs/053).
                    if (id > 0 && t.Instrument is { Kind: 5, Wavetables: { } wts })
                        RestoreWavetables(engine, id, bundleDir, wts, warnings, newTrackIds.Count + 1);
                    // Nota Rhythm Phase 2: reload each voice's one-shot from the bundle.
                    if (id > 0 && t.Instrument is { Kind: 12, VoiceSamples: { } vsl })
                        foreach (var vs in vsl)
                        {
                            if (vs.Sample is not { Length: > 0 }) continue;
                            if (!engine.SetRhythmVoiceSample(id, vs.Voice, ResolveInBundle(bundleDir, vs.Sample)))
                                warnings.Add($"Couldn't reload Rhythm voice sample \"{vs.Sample}\".");
                            else
                            {
                                if (engine.TryGetRhythmVoiceInfo(id, vs.Voice, out var rvi))
                                    BundleContent.SeedSample(engine, rvi.SampleId, vs.Sample);
                                if (vs.Synth)
                                    engine.InstrumentAction(id, RhythmModel.A_SetSource, vs.Voice, 0f);   // loading switches to Sample
                            }
                        }
                }
            }
            else if (t.Type == 3)
            {
                id = engine.AddGroupTrack();
            }
            else
            {
                id = engine.AddAudioTrack();
            }

            if (id > 0 && t.Instrument is { Folded: true }) engine.SetDeviceFolded(id, -1, true);
            if (id > 0) ApplyPresetTag(engine, id, PresetSurface.Instrument, -1, t.Instrument?.Preset);
            // Not onto the stand-in for a plug-in that isn't installed: it's another instrument.
            if (id > 0 && t.Instrument is { Preview: { } instPreview } && engine.TrackInstrumentKind(id) == t.Instrument.Kind)
                engine.SetPluginPreview(id, -1, ReadPreview(bundleDir, instPreview));
            if (id > 0 && t.Instrument is { Bypassed: true })
                engine.SetDeviceBypassed(id, -1, true);           // the instrument card's switch is off (#148)
            if (id > 0 && t.Instrument is { SidechainSource: >= 0 } insc)
                instScDeferred.Add((id, insc.SidechainSource, insc.SidechainPart));   // wire React source once every track exists
            if (id > 0 && t.GroupId >= 0)
                groupDeferred.Add((id, t.GroupId));               // reparent into its group once every track exists
            newTrackIds.Add(id);   // keep index aligned with doc.Tracks even on failure (id <= 0)
            if (id <= 0)
            {
                warnings.Add($"Couldn't recreate a track (type {t.Type}).");
                continue;
            }

            engine.SetTrackVolume(id, t.Volume);
            engine.SetTrackPan(id, t.Pan);
            engine.SetTrackMute(id, t.Mute);
            engine.SetTrackSolo(id, t.Solo);
            engine.SetTrackCue(id, t.Cue == true);
            engine.SetTrackArmed(id, t.Armed);
            if (t.Name is { Length: > 0 } trackName) engine.SetTrackName(id, trackName);
            if (t.ColorIndex >= 0) engine.SetTrackColorIndex(id, t.ColorIndex);
            if (t.PianoFold == true) engine.SetTrackPianoFold(id, true);
            if (t.EditLink == true) engine.SetTrackEditLink(id, true);   // group Link (specs/076)
            if (t.RecordInput != 0) recInputDeferred.Add((id, t.RecordInput));   // resolve after all tracks exist
            if (t.Monitor) monitorDeferred.Add((id, true));                        // after record inputs resolve
            engine.SetTrackInput(id, TrackInputOf(t));
            if (t.MidiFrom >= 0) midiFromDeferred.Add((id, t.MidiFrom));           // resolve after all tracks exist
            if (t.MidiInputUid is { Length: > 0 } || t.MidiInputChannel is > 0)    // MIDI input (specs/086)
                engine.SetTrackMidiInput(id, t.MidiInputUid, t.MidiInputChannel ?? 0);
            if (t.MidiOffsetMs is { } offMs && double.IsFinite(offMs)) engine.SetTrackMidiOffsetMs(id, offMs);   // v30; absent = 0, engine clamps
            if (t.Type == 1 && t.ArticulationMap is { } artMap) ApplyArticulationMap(engine, id, artMap, warnings);   // v30
            for (int b = 0; b < t.Sends.Length && b < 4; b++) engine.SetTrackSend(id, b, t.Sends[b]);

            var ccPaths = new List<(int mi, int chain, int slot)>();   // CC targets inside racks: after the devices
            foreach (var m in t.MidiEffects)
            {
                int mi = engine.AddMidiEffect(id, m.Kind);
                if (mi < 0) { warnings.Add($"Couldn't recreate a MIDI effect (kind {m.Kind})."); continue; }
                int mpc = engine.MidiEffectParamCount(id, mi);
                for (int p = 0; p < m.Params.Length && p < mpc; p++) engine.MidiEffectSetParam(id, mi, p, m.Params[p]);
                if (m.Kind == 1 && m.Params.Length <= 16) PresetService.ChordLegacySwitches(engine, id, mi);   // pre-switch Nota Chord
                if (m.Kind == 3 && m.Params.Length <= 11) PresetService.LengthLegacy(engine, id, mi);          // pre-Division Nota Length
                if (m.Kind == 4 && m.Params.Length <= 7) PresetService.VelocityLegacy(engine, id, mi);         // pre-switch Nota Velocity
                if (m.State is { } ms)
                {
                    var blob = ReadBlob(bundleDir, ms);
                    if (blob.Length > 0) engine.MidiEffectSetState(id, mi, blob, false);
                }
                if (m.Bypassed) engine.SetMidiEffectBypassed(id, mi, true);
                if (m.Folded) engine.SetMidiEffectFolded(id, mi, true);
                ApplyPresetTag(engine, id, PresetSurface.MidiEffect, mi, m.Preset);
                if ((m.CcDestDevice >= 0 || m.CcDestChain is not null) && m.CcDestParam >= 0)
                {
                    engine.SetMidiEffectCcDest(id, mi, m.CcDestDevice, m.CcDestParam);
                    engine.SetMidiEffectCcDepth(id, mi, m.CcDepth);
                    if (m.CcDestChain is int cc) ccPaths.Add((mi, cc, m.CcDestSlot ?? 0));
                }
            }

            ApplyDevices(engine, id, t.Devices, bundleDir, scDeferred, warnings);
            foreach (var (mi, cc, cs) in ccPaths)
                if (!engine.SetMidiEffectCcDestPath(id, mi, cc, cs)) warnings.Add("Couldn't reconnect an Arp's CC lane to a device in a rack.");
            foreach (var r in t.NestedCcRoutes ?? new())
                if (!engine.RackChainMidiSetCcDest(id, r.Host, r.Chain, r.Index, new NestedCcDest(r.DestDevice, r.DestChain, r.DestSlot, r.Param, r.Depth)))
                    warnings.Add("Couldn't reconnect the CC lane of an Arp in a rack.");
            foreach (var n in t.NestedSidechains ?? new())
                if (n.Source >= 0) nestedScDeferred.Add((id, n));

            foreach (var c in t.MidiClips)
            {
                int ci = engine.AddMidiClip(id, c.StartBeat, c.LengthBeats);
                if (ci < 0) continue;
                if (c.Name is { Length: > 0 } mcn) engine.SetClipName(id, ci, mcn);
                if (!c.Active) engine.SetClipActive(id, ci, false);   // clip deactivate (v17)
                if (c.Notes.Length > 0) engine.SetClipNotes(id, ci, ToNotes(engine, c.Notes));
                if (c.VelocityEnvelope is { Length: > 0 } ve)   // MIDI clip envelopes (v10)
                    engine.SetMidiClipEnvelope(id, ci, MidiClipEnvelope.Velocity, System.Array.ConvertAll(ve, p => p.ToPoint()));
                if (c.VolumeEnvelope is { Length: > 0 } vo)
                    engine.SetMidiClipEnvelope(id, ci, MidiClipEnvelope.Volume, System.Array.ConvertAll(vo, p => p.ToPoint()));
                ApplyControllers(c.Controllers, warnings, (ctl, pts) => engine.SetMidiClipController(id, ci, ctl, pts));
            }

            // Takes before clips: a comp section is re-linked to its take (and shares its buffer).
            var takeIds = new Dictionary<int, int>();
            if (t.Takes != null)
                foreach (var tk in t.Takes)
                {
                    int nid = engine.RestoreTake(id, ResolveInBundle(bundleDir, tk.Sample), tk.Number, tk.Group,
                                                 tk.OriginBeat, tk.SourceOffsetFrames, tk.LengthFrames);
                    if (nid <= 0) { warnings.Add($"Couldn't reload take \"{tk.Sample}\"."); continue; }
                    takeIds[tk.Id] = nid;
                    for (int k = engine.TakeCount(id) - 1; k >= 0; k--)
                        if (engine.TryGetTakeInfo(id, k, out var lti) && lti.Id == nid)
                        {
                            BundleContent.SeedSample(engine, lti.SampleId, tk.Sample);
                            if (tk.Source is { Length: > 0 } tsrc) engine.SetSampleSource(lti.SampleId, tsrc);
                            break;
                        }
                }

            var joinedEdges = new List<(int Clip, int Edges)>();
            foreach (var ac in t.AudioClips)
            {
                int ci = AudioClipState.Restore(engine, id, ac, ResolveInBundle(bundleDir, ac.Sample));
                if (ci < 0) { warnings.Add($"Couldn't reload audio clip \"{ac.Sample}\"."); continue; }
                if (ac.TakeId is int oldTake && takeIds.TryGetValue(oldTake, out int newTake))
                    engine.SetClipTakeId(id, ci, newTake);
                if (ac.JoinedEdges is int je && je != 0) joinedEdges.Add((ci, je));
                if (engine.TryGetAudioClipInfo(id, ci, out var lci))
                {
                    BundleContent.SeedSample(engine, lci.SampleId, ac.Sample);
                    if (ac.Source is { Length: > 0 } src) engine.SetSampleSource(lci.SampleId, src);
                }
            }
            // After every clip is in: a join is kept only where both of its clips are there.
            if (joinedEdges.Count > 0)
            {
                var edges = new int[joinedEdges.Max(j => j.Clip) + 1];
                foreach (var (clip, e) in joinedEdges) edges[clip] = e;
                engine.RestoreJoinedEdges(id, edges);
            }

            // Freeze (M7): restore the frozen-audio buffer so the track re-opens frozen
            // (the live chain above is kept intact for a later unfreeze). cloneTrack carries
            // the buffer through the automation/session edits that follow.
            if (t.FrozenState is { } frozenRel)
            {
                var blob = ReadBlob(bundleDir, frozenRel);
                if (blob.Length > 0) engine.SetFreezeState(id, blob);
            }

            foreach (var sl in t.SessionSlots)
            {
                if (sl.Audio is { } sa)
                {
                    if (!engine.AddSessionAudioClip(id, sl.Scene, ResolveInBundle(bundleDir, sa.Sample),
                            sl.LengthBeats, sa.SourceOffsetFrames, sa.LengthFrames, sa.Gain))
                        warnings.Add($"Couldn't reload session take \"{sa.Sample}\".");
                    else
                    {
                        if (engine.TryGetSessionAudioSlot(id, sl.Scene, out var lsa))
                        {
                            BundleContent.SeedSample(engine, lsa.SampleId, sa.Sample);
                            if (sa.Source is { Length: > 0 } ssrc) engine.SetSampleSource(lsa.SampleId, ssrc);
                        }
                        AudioClipState.ApplyShape(engine, id, SessionClip.Index(sl.Scene), sa);
                        engine.SetSessionSlotLength(id, sl.Scene, sl.LengthBeats);   // clip edits resync it; the saved loop wins
                    }
                }
                else
                {
                    engine.AddSessionMidiClip(id, sl.Scene, sl.LengthBeats);
                    if (sl.Notes.Length > 0) engine.SetSessionNotes(id, sl.Scene, ToNotes(engine, sl.Notes));
                    ApplyControllers(sl.Controllers, warnings, (ctl, pts) => engine.SetSessionController(id, sl.Scene, ctl, pts));
                }
                ApplyClipProps(engine, id, sl);
            }
            if (t.SessionNoStop is { } noStop)
                foreach (int sc in noStop) engine.SetSessionSlotStopButton(id, sc, false);

            // Automation lanes (M9-A4). Devices are already rebuilt above, so
            // DeviceParam lanes resolve to the same chain positions; plugin-param
            // lanes resolve by stable id (M9-B4).
            foreach (var lane in t.Automation)
            {
                int li;
                if (lane.Chain is int lc) // a lane on a device grouped into a rack (specs/044)
                {
                    li = engine.AddNestedAutomationLane(id, (AutomationTarget)lane.Target, lane.DeviceIndex, lc, lane.Slot ?? 0,
                                                        lane.ParamIndex, lane.PluginParamId);
                    if (li < 0) { warnings.Add("Couldn't recreate an automation lane on a device in a rack."); continue; }
                }
                else if ((AutomationTarget)lane.Target == AutomationTarget.PluginParam)
                {
                    string pid = lane.PluginParamId ?? "";
                    li = engine.AddPluginAutomationLane(id, lane.DeviceIndex, pid);
                    if (li < 0) { warnings.Add("Couldn't recreate a plugin-param automation lane."); continue; }
                    // Keep the data, but flag if the id no longer maps to a live param
                    // (plugin updated/replaced): the envelope stays saved, just inert.
                    if (!PluginParamExists(engine, id, lane.DeviceIndex, pid))
                        warnings.Add($"Plugin parameter \"{pid}\" not found — its automation was kept but is inactive.");
                }
                else
                {
                    li = engine.AddAutomationLane(id, (AutomationTarget)lane.Target, lane.DeviceIndex, lane.ParamIndex);
                    if (li < 0) { warnings.Add("Couldn't recreate an automation lane."); continue; }
                }
                if (lane.Points.Length > 0)
                    engine.SetAutomationPoints(id, li,
                        System.Array.ConvertAll(lane.Points, p => p.ToPoint()));
            }

            // CV modulation (Phase 3). Devices are rebuilt above, so link device
            // indices resolve. Saved modulator ids are remapped to the fresh ids.
            var modIdMap = new Dictionary<int, int>();
            foreach (var m in t.Modulators)
            {
                int newId = engine.ModulatorAdd(id, m.Kind);
                if (newId < 0) { warnings.Add("Couldn't recreate a modulator."); continue; }
                modIdMap[m.Id] = newId;
                engine.ModulatorSet(id, newId, 0, m.Waveform);
                engine.ModulatorSet(id, newId, 1, m.TempoSync ? 1f : 0f);
                engine.ModulatorSet(id, newId, 2, m.RateHz);
                engine.ModulatorSet(id, newId, 3, m.RateSyncBeats);
                engine.ModulatorSet(id, newId, 4, m.Depth);
                engine.ModulatorSet(id, newId, 5, m.Phase);
                engine.ModulatorSet(id, newId, 6, m.Attack);
                engine.ModulatorSet(id, newId, 7, m.Release);
                engine.ModulatorSet(id, newId, 8, m.Decay);
                engine.ModulatorSet(id, newId, 9, m.Sustain);
                if (m.Kind == 6)   // Scope view settings (specs/047)
                {
                    engine.ModulatorSet(id, newId, 13, m.ScopeWindowMs);
                    engine.ModulatorSet(id, newId, 14, m.ScopeSync ? 1f : 0f);
                    engine.ModulatorSet(id, newId, 15, m.ScopeWindowBeats);
                    engine.ModulatorSet(id, newId, 16, m.ScopeZoom);
                    engine.ModulatorSet(id, newId, 17, m.ScopeTrigger);
                    engine.ModulatorSet(id, newId, 18, m.ScopeHeight);
                }
            }
            // Math/Scope inputs reference other modulators by id → remap after all exist.
            foreach (var m in t.Modulators)
            {
                if (m.Kind == 5 && modIdMap.TryGetValue(m.Id, out int mathId))
                {
                    engine.ModulatorSet(id, mathId, 10, modIdMap.TryGetValue(m.InputA, out var ia) ? ia : -1);
                    engine.ModulatorSet(id, mathId, 11, modIdMap.TryGetValue(m.InputB, out var ib) ? ib : -1);
                    engine.ModulatorSet(id, mathId, 12, m.MathOffset);
                }
                else if (m.Kind == 6 && modIdMap.TryGetValue(m.Id, out int scopeId))
                    engine.ModulatorSet(id, scopeId, 10, modIdMap.TryGetValue(m.InputA, out var sa) ? sa : -1);
            }
            // Links are deferred: a cross-track target may be a track created later. Param
            // sources need no modulator; modulator sources remap the saved id.
            foreach (var l in t.CvLinks)
                if (l.SourceKind == 1) cvLinkDeferred.Add((id, l, -1));
                else if (modIdMap.TryGetValue(l.Source, out int src)) cvLinkDeferred.Add((id, l, src));
        }

        // CV links (Phase 3/5/14) — resolved after every track exists so cross-track
        // targets (a doc-index into the track list) map to their created ids.
        foreach (var (owner, l, modId) in cvLinkDeferred)
        {
            int targetTrack = l.TargetTrack >= 0 && l.TargetTrack < newTrackIds.Count ? newTrackIds[l.TargetTrack] : -1;
            int idx = l.SourceChain is not null || l.TargetChain is not null   // reaching into a rack (specs/044)
                ? engine.CvLinkAddNested(owner, l.SourceKind, modId, l.SourceDevice, l.SourceChain ?? -1, l.SourceSlot ?? -1, l.SourceParam,
                                         l.TargetKind, targetTrack, l.Device, l.TargetChain ?? -1, l.TargetSlot ?? -1, l.Param)
                : l.SourceKind == 1
                ? engine.CvLinkAddFromParamToTarget(owner, l.SourceDevice, l.SourceParam, l.TargetKind, targetTrack, l.Device, l.Param)
                : engine.CvLinkAddToTarget(owner, modId, l.TargetKind, targetTrack, l.Device, l.Param);
            if (idx < 0) { warnings.Add("Couldn't recreate a CV link."); continue; }
            engine.SetCvLinkDepth(owner, idx, l.Depth);
            engine.SetCvLinkMode(owner, idx, l.Mode);
            engine.SetCvLinkBase(owner, idx, l.Base);   // override the auto-captured base with the saved one
        }

        // Master effect chain + its name/colour (before sidechain resolution so master
        // devices' sidechain sources are wired too).
        if (doc.Master is { } md)
        {
            int masterId = engine.MasterTrackId;
            if (md.Name is { Length: > 0 } mnm) engine.SetTrackName(masterId, mnm);
            if (md.ColorIndex >= 0) engine.SetTrackColorIndex(masterId, md.ColorIndex);
            ApplyDevices(engine, masterId, md.Devices, bundleDir, scDeferred, warnings);
            foreach (var n in md.NestedSidechains ?? new())
                if (n.Source >= 0) nestedScDeferred.Add((masterId, n));
        }

        // Sidechain wiring, now that every track exists (Phase B). Source is a doc index.
        // A key may name a part of its source's instrument (specs/050); the route pool is shared,
        // so a key past it is dropped and reported once.
        int unrouted = 0;
        foreach (var (track, dev, srcIndex, part) in scDeferred)
        {
            if (srcIndex < newTrackIds.Count && newTrackIds[srcIndex] > 0)
                if (engine.SetDeviceSidechainKey(track, dev, newTrackIds[srcIndex], part) == -2) unrouted++;
        }
        // Keys of devices inside racks (specs/044), same deferral and the same route check: a key
        // the pool can't take is cleared and counted.
        foreach (var (track, n) in nestedScDeferred)
        {
            if (n.Source >= newTrackIds.Count || newTrackIds[n.Source] <= 0) continue;
            var sc = new NestedSidechain(newTrackIds[n.Source], n.TapPre, n.GainDb, n.Mix);
            // Source and part together: only the saved key itself meets the route check.
            if (engine.RackChainSetSidechainKey(track, n.Host, n.Chain, n.Slot, sc, n.Part) == -2) unrouted++;
        }
        // Instrument React source (Nota Flux), same deferral.
        foreach (var (track, srcIndex, part) in instScDeferred)
        {
            if (srcIndex < newTrackIds.Count && newTrackIds[srcIndex] > 0)
                if (engine.SetInstrumentSidechainKey(track, newTrackIds[srcIndex], part) == -2) unrouted++;
        }
        if (unrouted > 0)
            warnings.Add($"{unrouted} sidechain key{(unrouted == 1 ? " was" : "s were")} cleared: all {engine.SidechainRouteCapacity()} sidechain routes are in use.");
        // Group membership (parent stored as a doc index), now that every track exists.
        foreach (var (trackId, parentDocIndex) in groupDeferred)
        {
            if (parentDocIndex < newTrackIds.Count && newTrackIds[parentDocIndex] > 0)
                engine.SetTrackGroup(trackId, newTrackIds[parentDocIndex]);
        }

        // Record-input routing (internal resampling): decode master / track-source now
        // that every track exists (encoded = -1 master, or doc index + 2 for a track).
        foreach (var (trackId, enc) in recInputDeferred)
        {
            int source = enc == -1 ? -1
                : (enc >= 2 && enc - 2 < newTrackIds.Count && newTrackIds[enc - 2] > 0 ? newTrackIds[enc - 2] : 0);
            if (source != 0) engine.SetTrackRecordInput(trackId, source);
        }
        // Input monitoring last, so a track-source monitor never briefly opens the hardware input.
        foreach (var (trackId, on) in monitorDeferred) if (on) engine.SetTrackMonitor(trackId, true);
        // MIDI routing source ("MIDI In", stored as a doc index), now that every track exists.
        foreach (var (trackId, sourceDocIndex) in midiFromDeferred)
        {
            if (sourceDocIndex < newTrackIds.Count && newTrackIds[sourceDocIndex] > 0)
                engine.SetTrackMidiSource(trackId, newTrackIds[sourceDocIndex]);
        }

        // Master-volume automation (graph-level, format v7).
        if (doc.MasterVolumeAutomation.Count > 0)
            engine.SetMasterVolumeAutomation(
                doc.MasterVolumeAutomation.ConvertAll(p => p.ToPoint()).ToArray());

        return warnings;
    }

    // --- disk I/O ----------------------------------------------------------

    /// <summary>Writes the document (and its referenced samples) into the `.nota`
    /// bundle folder. Binaries are content-named, so ones already on disk are skipped;
    /// each new one is written temp + rename. Atomic manifest (temp + rename); backs up
    /// any existing manifest into <c>backups/</c> (unless the bundle keeps a version history);
    /// then deletes binaries the manifest no
    /// longer references. Sample data is read from <paramref name="engine"/> (the one
    /// <see cref="Capture"/> read from).</summary>
    public static void Save(ProjectDocument doc, string bundleDir, IAudioEngine engine)
    {
        if (doc.SessionNames)
            throw new InvalidOperationException("A change-detection capture (contentNames: false) can't be saved.");
        Directory.CreateDirectory(bundleDir);

        if (doc.SampleRefs.Count > 0)
        {
            Directory.CreateDirectory(Path.Combine(bundleDir, BundleContent.SamplesDir));
            foreach (var kv in doc.SampleRefs)
                WriteSampleWav(engine, kv.Value, ResolveInBundle(bundleDir, kv.Key));
        }

        if (doc.TableRefs.Count > 0)
        {
            Directory.CreateDirectory(Path.Combine(bundleDir, BundleContent.SamplesDir));
            foreach (var kv in doc.TableRefs)
            {
                string path = ResolveInBundle(bundleDir, kv.Key);
                if (File.Exists(path) && new FileInfo(path).Length >= kv.Value.Length * sizeof(float)) continue;
                BundleContent.WriteAtomic(path, tmp => AuroraTableWav.Write(tmp, kv.Value));
            }
        }

        if (doc.StateBlobs.Count > 0)
        {
            Directory.CreateDirectory(Path.Combine(bundleDir, BundleContent.StatesDir));
            foreach (var kv in doc.StateBlobs)
            {
                string path = ResolveInBundle(bundleDir, kv.Key);
                if (File.Exists(path) && new FileInfo(path).Length == kv.Value.Length) continue;
                BundleContent.WriteAtomic(path, tmp => File.WriteAllBytes(tmp, kv.Value));
            }
        }

        string manifest = Path.Combine(bundleDir, ManifestName);
        if (File.Exists(manifest) && !ProjectHistory.HasHistory(bundleDir))   // the version history supersedes backups/
        {
            string backups = Path.Combine(bundleDir, "backups");
            Directory.CreateDirectory(backups);
            string stamp = DateTime.Now.ToString("yyyyMMdd-HHmmss");
            File.Copy(manifest, Path.Combine(backups, $"project-{stamp}.json"), overwrite: true);
        }

        string tmp = manifest + ".tmp";
        File.WriteAllText(tmp, SerializeManifest(doc));
        File.Move(tmp, manifest, overwrite: true); // atomic replace (NFR-8)

        // Only now that the new manifest is in place: nothing on disk points at these any more.
        BundleContent.PruneUnreferenced(bundleDir, doc);
        // The sections now live in the manifest; a leftover sidecar would only mislead an older build.
        try { File.Delete(Path.Combine(bundleDir, LegacySectionsSidecar)); } catch (IOException) { } catch (UnauthorizedAccessException) { }
    }

    /// <summary>Where builds before specs/016 kept the arrangement sections, next to the manifest.</summary>
    public const string LegacySectionsSidecar = "sections.json";

    // Sections of a project saved before they moved into the manifest (absent / corrupt → none).
    private static List<SectionDto> ReadLegacySections(string bundleDir)
    {
        string path = Path.Combine(bundleDir, LegacySectionsSidecar);
        if (!File.Exists(path)) return new();
        try { return JsonSerializer.Deserialize<List<SectionDto>>(File.ReadAllText(path)) ?? new(); }
        catch (Exception e) when (e is JsonException or IOException or UnauthorizedAccessException) { return new(); }
    }

    /// <summary>Serializes just the manifest JSON (same options Save uses). Used by
    /// autosave to detect whether the project changed since the last snapshot (M7-7).</summary>
    public static string SerializeManifest(ProjectDocument doc) => JsonSerializer.Serialize(doc, JsonOpts);

    /// <summary>Reads and validates the document from a `.nota` bundle folder.</summary>
    public static ProjectDocument Load(string bundleDir)
    {
        string manifest = Path.Combine(bundleDir, ManifestName);
        if (!File.Exists(manifest))
            throw new FileNotFoundException($"No {ManifestName} in {bundleDir}", manifest);

        // Parse to the raw JSON tree first: the version gate + migrations (M7-9)
        // run before deserialization, since an older shape may not map onto the
        // current DTOs. Unknown fields still survive via [JsonExtensionData].
        var root = JsonNode.Parse(File.ReadAllText(manifest)) as JsonObject
                   ?? throw new InvalidDataException("Empty or invalid project.json.");
        int version = root["formatVersion"]?.GetValue<int>() ?? 1;
        if (version > CurrentFormatVersion)
            throw new NotSupportedException(
                $"This project uses format v{version}, but this build supports up to v{CurrentFormatVersion}. Update Nota to open it.");
        root = ProjectMigrations.Migrate(root); // no-op at v1; upgrades older files in future
        return root.Deserialize<ProjectDocument>(JsonOpts)
               ?? throw new InvalidDataException("Empty or invalid project.json.");
    }

    // --- helpers -----------------------------------------------------------

    private static PanLaw ParsePanLaw(string? value, List<string> warnings)
    {
        switch (value)
        {
            case null or "balance": return PanLaw.Balance;
            case "stereo": return PanLaw.Stereo;
            default:
                warnings.Add($"Unknown pan law '{value}' — using Balance.");
                return PanLaw.Balance;
        }
    }

    // Records `sampleId` under a bundle-relative path named by its content hash
    // (identical audio shares one file) and returns that path, or null if the sample
    // is missing from the live graph.
    // The file a clip's audio came from (spec 092, #581), or null when unknown.
    private static string? SourceOf(IAudioEngine engine, long sampleId)
        => sampleId > 0 && engine.SampleSource(sampleId) is { Length: > 0 } p ? p : null;

    private static string? RegisterSample(ProjectDocument doc, IAudioEngine engine, long sampleId, List<string> warnings)
    {
        if (sampleId <= 0) return null;
        if (!engine.TryGetSampleInfo(sampleId, out var info))
        {
            warnings.Add("A referenced sample was missing and was skipped.");
            return null;
        }
        string rel;
        if (doc.SessionNames) rel = $"{BundleContent.SamplesDir}/sample-{sampleId}.wav";
        else if (BundleContent.SampleHash(engine, sampleId, info) is { } hash) rel = BundleContent.SampleRel(hash);
        else
        {
            warnings.Add("A referenced sample was empty and was skipped.");
            return null;
        }
        doc.SampleRefs.TryAdd(rel, sampleId);
        return rel;
    }

    // Nota Aurora's imported tables (specs/053): each one a content-named float32 WAV, so two
    // Auroras with the same table share one file. A table a project could not restore stays
    // listed as missing, so the next save keeps its name.
    private static List<WavetableDto>? CaptureWavetables(ProjectDocument doc, IAudioEngine engine, int trackId)
    {
        List<WavetableDto>? list = null;
        for (int o = 0; o < 2; o++)
        {
            if (!engine.TryGetAuroraTableInfo(trackId, o, out var info)) return null;
            if (info.HasTable)
            {
                string rel;
                if (doc.SessionNames) rel = $"{BundleContent.SamplesDir}/table-{trackId}-{o}-{info.Serial}.wav";
                else
                {
                    var frames = engine.AuroraTableRead(trackId, o);
                    if (frames.Length == 0) continue;
                    var bytes = new byte[frames.Length * sizeof(float)];
                    Buffer.BlockCopy(frames, 0, bytes, 0, bytes.Length);
                    rel = BundleContent.SampleRel(BundleContent.BlobHash(bytes));
                    doc.TableRefs.TryAdd(rel, frames);
                }
                (list ??= new()).Add(new WavetableDto
                {
                    Osc = o, Sample = rel, Name = info.Name, Origin = info.Origin, Frames = info.Frames,
                    UseCustom = info.UseCustom,
                });
            }
            else if (info.Missing)
                (list ??= new()).Add(new WavetableDto { Osc = o, Name = info.Name, Missing = true, UseCustom = false });
        }
        return list;
    }

    // Puts each saved table back (no undo step: this is a load). A table that cannot be read
    // leaves its oscillator on the built-in bank, marked missing under the name it had.
    private static void RestoreWavetables(IAudioEngine engine, int id, string bundleDir, List<WavetableDto> tables,
        List<string> warnings, int trackNo)
    {
        foreach (var w in tables)
        {
            if (w.Osc is < 0 or > 1) continue;
            bool ok = false;
            if (!w.Missing && w.Sample.Length > 0 && w.Frames is > 0 and <= 256)
            {
                string path = ResolveInBundle(bundleDir, w.Sample);
                float[]? mono = File.Exists(path) ? NotaEngine.DecodeMono(path, 60.0, out _) : null;
                if (mono is not null && mono.Length == w.Frames * 2048
                    && engine.AuroraTableFromFrames(mono, w.Frames, w.Name, w.Origin, out var h) == AuroraTableResult.Ok)
                {
                    try { ok = engine.AuroraSetTable(id, w.Osc, h, undoable: false); }
                    finally { engine.AuroraTableFree(h); }
                    if (ok) engine.AuroraSetSource(id, w.Osc, w.UseCustom);
                }
            }
            if (ok) continue;
            warnings.Add($"Track {trackNo}: Aurora Osc {w.Osc + 1} table \"{w.Name}\" is missing — it plays its built-in table.");
            engine.AuroraSetMissing(id, w.Osc, w.Name.Length > 0 ? w.Name : "table");
            engine.AuroraSetSource(id, w.Osc, false);
        }
    }

    // A saved track's hardware input (specs/086): the device channel + width, or — in files
    // saved before 0.60 — the old three-value pick (absent before 0.58: the stereo pair).
    internal static InputPick TrackInputOf(TrackDto t)
    {
        if (t.InputFirst is int first && t.InputWidth is int width && new InputPick(first - 1, width) is { IsValid: true } p)
            return p;
        return InputPick.From((InputChannels)(t.InputChannels ?? 0));
    }

    // Writes a sample unless its content-named file is already complete on disk.
    private static void WriteSampleWav(IAudioEngine engine, long sampleId, string path)
    {
        if (!engine.TryGetSampleInfo(sampleId, out var info) || info.Channels <= 0 || info.Frames <= 0) return;
        long dataBytes = info.Frames * info.Channels * sizeof(float);
        if (File.Exists(path) && new FileInfo(path).Length >= dataBytes) return;
        var data = engine.ReadSample(sampleId);
        if (data.Length == 0) return;
        BundleContent.WriteAtomic(path, tmp =>
        {
            using var w = new WavWriter(tmp, BundleContent.WavSampleRate(info), info.Channels, WavBitDepth.Float32);
            w.WriteFrames(data, (int)info.Frames);
        });
    }

    // Records a plugin state blob under a bundle-relative path named by its content hash
    // (identical states share one file), or null if empty.
    private static string? RegisterBlob(ProjectDocument doc, byte[] blob)
    {
        if (blob.Length == 0) return null;
        string rel = doc.SessionNames
            ? $"{BundleContent.StatesDir}/state-{doc.StateBlobs.Count}.bin"
            : BundleContent.StateRel(BundleContent.BlobHash(blob));
        doc.StateBlobs.TryAdd(rel, blob);
        return rel;
    }

    private static byte[] ReadBlob(string bundleDir, string relative)
    {
        string path = ResolveInBundle(bundleDir, relative);
        return File.Exists(path) ? File.ReadAllBytes(path) : Array.Empty<byte>();
    }

    // A plug-in window's picture (specs/046) is decoration: one that can't be read (permissions,
    // a damaged bundle, an odd path) or is larger than the engine takes leaves the card plain
    // instead of stopping the project from opening.
    private const long MaxPreviewBytes = 4 * 1024 * 1024;
    private static byte[] ReadPreview(string bundleDir, string relative)
    {
        try
        {
            var f = new FileInfo(ResolveInBundle(bundleDir, relative));
            return f.Exists && f.Length <= MaxPreviewBytes ? File.ReadAllBytes(f.FullName) : Array.Empty<byte>();
        }
        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or ArgumentException or NotSupportedException)
        {
            return Array.Empty<byte>();
        }
    }

    private static string ResolveInBundle(string bundleDir, string relative)
        => Path.Combine(bundleDir, relative.Replace('/', Path.DirectorySeparatorChar));

    // Does a hosted plugin still expose a parameter with this stable id? (M9-B4)
    private static bool PluginParamExists(IAudioEngine engine, int trackId, int deviceIndex, string paramId)
    {
        int n = engine.PluginParamCount(trackId, deviceIndex);
        for (int i = 0; i < n; i++)
            if (engine.PluginParamId(trackId, deviceIndex, i) == paramId) return true;
        return false;
    }

    // A note's recorded MPE goes inline with it (notes sharing one curve, like a duplicate,
    // each carry a copy).
    // --- articulation maps (specs/085) ------------------------------------------------------

    private static JsonObject? CaptureArticulationMap(IAudioEngine engine, int trackId, List<string> warnings)
    {
        if (engine.GetTrackArticulationMapJson(trackId) is not { Length: > 0 } json) return null;
        try { return JsonNode.Parse(json) as JsonObject; }
        catch (JsonException) { warnings.Add("A track's articulation map couldn't be saved (it isn't valid JSON)."); return null; }
    }

    // A map that can't be read, or that the engine refuses, is a warning: the project still opens.
    private static void ApplyArticulationMap(IAudioEngine engine, int trackId, JsonObject node, List<string> warnings)
    {
        var read = Nota.Application.Articulations.ArticulationMapFile.Read(node.ToJsonString(), "");
        foreach (var m in read.Warnings) warnings.Add(m.Text);
        if (read.Map is not { } map) return;
        if (!Nota.Application.Articulations.ArticulationMapAssignment.Assign(engine, trackId, map))
            warnings.Add($"Couldn't restore the articulation map \"{map.Name}\".");
    }

    private static NoteDto[] ToDtos(IAudioEngine engine, NotaNote[] notes)
    {
        var arr = new NoteDto[notes.Length];
        var cache = new Dictionary<int, NoteMpeDto?>();
        for (int i = 0; i < notes.Length; i++)
        {
            arr[i] = new NoteDto(notes[i]);
            int id = notes[i].ExprId;
            if (id <= 0) continue;
            if (!cache.TryGetValue(id, out var mpe)) cache[id] = mpe = NoteMpeDto.From(engine.GetNoteExpression(id));
            arr[i].Mpe = mpe;
        }
        return arr;
    }

    private static NotaNote[] ToNotes(IAudioEngine engine, NoteDto[] dtos)
    {
        var arr = new NotaNote[dtos.Length];
        var ids = new Dictionary<NoteMpeDto, int>(ReferenceEqualityComparer.Instance);
        for (int i = 0; i < dtos.Length; i++)
        {
            arr[i] = dtos[i].ToNote();
            if (dtos[i].Mpe is not { } mpe) continue;
            if (!ids.TryGetValue(mpe, out int id)) ids[mpe] = id = engine.CreateNoteExpression(mpe.ToPoints());
            arr[i].ExprId = id;
        }
        return arr;
    }

    // --- Session P0: clip + scene properties ------------------------------------

    private static SessionDto CaptureSession(IAudioEngine engine)
    {
        var dto = new SessionDto
        {
            LaunchQuant = engine.LaunchQuant,
            Follow = engine.SessionFollow,
            RecordLength = engine.SessionRecordLength,
        };
        for (int s = 0; s < engine.SceneCount; s++)
        {
            if (!engine.TryGetSceneProps(s, out var p)) continue;
            string name = engine.GetSceneName(s);
            if (name.Length == 0 && p.Color < 0 && p.Tempo <= 0 && p.SigNum <= 0 && p.Follow == 0) continue;
            dto.Scenes.Add(new SceneDto
            {
                Index = s, Name = name.Length > 0 ? name : null, Color = p.Color, Tempo = p.Tempo,
                SigNum = p.SigNum, SigDen = p.SigDen, Follow = p.Follow != 0, FollowBeats = p.FollowBeats,
            });
        }
        return dto;
    }

    private static void ApplySession(IAudioEngine engine, SessionDto? dto)
    {
        if (dto is null) return;
        engine.SetLaunchQuant(Math.Max(0, dto.LaunchQuant));
        engine.SessionFollow = dto.Follow;
        engine.SessionRecordLength = Math.Max(0, dto.RecordLength);
        foreach (var sc in dto.Scenes)
        {
            if (sc.Index < 0 || sc.Index >= engine.SceneCount) continue;
            if (!string.IsNullOrEmpty(sc.Name)) engine.SetSceneName(sc.Index, sc.Name);
            engine.SetSceneProps(sc.Index, new NotaSceneProps
            {
                Color = sc.Color, Tempo = sc.Tempo, SigNum = sc.SigNum, SigDen = sc.SigDen,
                Follow = sc.Follow ? 1 : 0, FollowBeats = sc.FollowBeats,
            });
        }
    }

    // A clip's controller curves (specs/020); null when it has none, so older files stay alike.
    private static ControllerCurveDto[]? CaptureControllers(int[] ctls, Func<int, AutomationPoint[]> get)
    {
        if (ctls.Length == 0) return null;
        var list = new List<ControllerCurveDto>(ctls.Length);
        foreach (int ctl in ctls)
        {
            var pts = get(ctl);
            if (pts.Length > 0) list.Add(ControllerCurveDto.From(ctl, pts));
        }
        return list.Count > 0 ? list.ToArray() : null;
    }

    private static void ApplyControllers(ControllerCurveDto[]? curves, List<string> warnings, Action<int, AutomationPoint[]> set)
    {
        if (curves is null) return;
        foreach (var cc in curves)
        {
            var pts = cc.ToPoints();
            if (MidiController.IsReserved(cc.Ctl) || pts.Length == 0)
            {
                warnings.Add($"Skipped a clip's controller curve for an unsupported controller ({cc.Ctl}).");
                continue;
            }
            set(cc.Ctl, pts);
        }
    }

    private static SessionSlotDto WithClipProps(IAudioEngine engine, int trackId, SessionSlotDto dto)
    {
        string name = engine.GetSessionClipName(trackId, dto.Scene);
        dto.Name = name.Length > 0 ? name : null;
        if (!engine.TryGetSessionClipProps(trackId, dto.Scene, out var p)) return dto;
        dto.Color = p.Color; dto.LaunchMode = p.LaunchMode; dto.Quant = p.QuantBeats;
        dto.Legato = p.Legato != 0; dto.Loop = p.Loop != 0; dto.VelocityAmount = p.VelocityAmount;
        dto.FollowA = p.FollowA; dto.FollowB = p.FollowB; dto.ChanceA = p.ChanceA; dto.ChanceB = p.ChanceB;
        dto.FollowBeats = p.FollowBeats; dto.JumpScene = p.JumpScene;
        return dto;
    }

    private static void ApplyClipProps(IAudioEngine engine, int trackId, SessionSlotDto sl)
    {
        if (!string.IsNullOrEmpty(sl.Name)) engine.SetSessionClipName(trackId, sl.Scene, sl.Name);
        engine.SetSessionClipProps(trackId, sl.Scene, new NotaSessionClipProps
        {
            Color = sl.Color, LaunchMode = sl.LaunchMode, QuantBeats = sl.Quant,
            Legato = sl.Legato ? 1 : 0, Loop = sl.Loop ? 1 : 0, VelocityAmount = sl.VelocityAmount,
            FollowA = sl.FollowA, FollowB = sl.FollowB, ChanceA = sl.ChanceA, ChanceB = sl.ChanceB,
            FollowBeats = sl.FollowBeats, JumpScene = sl.JumpScene,
        });
    }
}