feat(charts): add note editing and local audio binding

Author: Codewriter90x

docs/development/chart-creator.md

@@ -17,8 +17,11 @@ timeline.
    current chart only as a playback reference.
 4. Play during the normal count-in and backing track. Hits before song time zero
    or beyond the declared song duration are ignored.
-5. At the result screen, review the captured-hit count and save the raw timing,
-   or quantize non-destructively to an eighth- or sixteenth-note grid.
+5. At the result screen, review the captured notes in the visual editor. Select
+   a note to change its time or drum pad, add missing notes, or delete unwanted
+   notes. The original recorded take remains unchanged in memory.
+6. Save the edited timing as recorded, or quantize the edited draft
+   non-destructively to an eighth- or sixteenth-note grid.
 
 Keyboard and MIDI events reach the recorder through `HitMatchingPrototype`'s
 `InputProcessed` boundary. Consequently, the existing per-source timing offset
@@ -44,7 +47,10 @@ entries:
 To transfer a take, copy only the `.htksong` file into
 `Documents/HTKSongs` on the other computer and refresh the Song Library. The
 game validates and atomically imports it. Existing song folders are never
-overwritten.
+overwritten. Select the imported entry, choose **Bind local audio**, select
+your own authorized WAV/OGG copy, and confirm the local-only binding. The game
+copies that audio into the imported song folder and makes the entry playable;
+the source file and portable package are not modified.
 
 The publish is atomic and both documents are parsed by the production loaders
 before the folder or package becomes visible. When the recording used a local
@@ -65,13 +71,14 @@ not a claim of authoritative transcription.
 
 ## Current foundation limits
 
-- Editing individual notes is not yet available. Raw/1/8/1/16 save choices are
-  the initial review tools.
+- The visual editor supports individual note time/pad changes, additions and
+  deletions. Waveform scrubbing and articulation/velocity authoring are future
+  editing tools.
 - The schema currently stores pad and time. Velocity and articulation remain in
   the in-memory take but schema v1 does not serialize them.
 - The native picker currently targets macOS. WAV and OGG are supported; MP3 is
   intentionally rejected by the production loader.
 - The author must enter BPM, bars and meter explicitly. Unknown timing never
   receives a hidden default.
-- Portable packages remain chart-only; imported packages require an authorized
-  local audio binding on the receiving computer.
+- Portable packages remain chart-only; the receiving computer must explicitly
+  bind an authorized local WAV/OGG copy before the imported chart is playable.

docs/development/song-library.md

@@ -121,6 +121,12 @@ copied to another computer; subsequent refreshes are idempotent.
 Package schema version 1 contains no audio and rejects any audio declaration or
 extra archive entry. Imports are bounded to 5 MiB, reject links, duplicate or
 case-colliding names, malformed ZIP/JSON/chart data, unsupported versions and
-path traversal, and never replace an existing song folder. An imported chart is
-therefore visible but unavailable until the player explicitly supplies audio
-they are entitled to use through the ordinary local song binding.
+path traversal, and never replace an existing song folder.
+
+An imported chart is therefore visible but unavailable until the player
+selects **Bind local audio** and supplies a WAV/OGG file they are entitled to
+use. The confirmation panel identifies the selected song and local filename;
+on confirmation the game copies the audio into that song's direct user-library
+folder, atomically updates its manifest, and refreshes the entry as playable.
+The source audio and `.htksong` package are never modified, and no absolute
+machine path is persisted.

src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs

@@ -0,0 +1,120 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using HitTheKit.Core;
+using HitTheKit.Unity.Input;
+
+namespace HitTheKit.Unity.Gameplay
+{
+    public sealed class EditableChartNote
+    {
+        internal EditableChartNote(
+            int identity,
+            DrumPad pad,
+            int velocity,
+            double timeSeconds,
+            DrumInputSource source)
+        {
+            Identity = identity;
+            Pad = pad;
+            Velocity = velocity;
+            TimeSeconds = timeSeconds;
+            Source = source;
+        }
+
+        public int Identity { get; }
+        public DrumPad Pad { get; internal set; }
+        public int Velocity { get; }
+        public double TimeSeconds { get; internal set; }
+        public DrumInputSource Source { get; }
+    }
+
+    public sealed class ChartDraftEditor
+    {
+        private readonly double durationSeconds;
+        private readonly List<EditableChartNote> notes;
+        private readonly ReadOnlyCollection<EditableChartNote> readOnlyNotes;
+        private int nextIdentity;
+
+        public ChartDraftEditor(ChartRecordingDraft draft)
+        {
+            if (draft == null) throw new ArgumentNullException(nameof(draft));
+            durationSeconds = draft.DurationSeconds;
+            notes = new List<EditableChartNote>(draft.Hits.Count);
+            for (int index = 0; index < draft.Hits.Count; index++)
+            {
+                RecordedChartHit hit = draft.Hits[index];
+                notes.Add(new EditableChartNote(nextIdentity++, hit.Pad, hit.Velocity, hit.TimeSeconds, hit.Source));
+            }
+            Sort();
+            readOnlyNotes = notes.AsReadOnly();
+        }
+
+        public double DurationSeconds => durationSeconds;
+        public IReadOnlyList<EditableChartNote> Notes => readOnlyNotes;
+
+        public int Update(int index, double timeSeconds, DrumPad pad)
+        {
+            EditableChartNote note = At(index);
+            ValidateTime(timeSeconds);
+            ValidatePad(pad);
+            note.TimeSeconds = timeSeconds;
+            note.Pad = pad;
+            Sort();
+            return notes.IndexOf(note);
+        }
+
+        public int Add(double timeSeconds, DrumPad pad, int velocity = 100)
+        {
+            ValidateTime(timeSeconds);
+            ValidatePad(pad);
+            if (velocity < 0 || velocity > 127) throw new ArgumentOutOfRangeException(nameof(velocity));
+            if (notes.Count >= ChartRecordingSession.MaximumHits)
+                throw new InvalidOperationException($"A chart cannot exceed {ChartRecordingSession.MaximumHits} notes.");
+            var note = new EditableChartNote(nextIdentity++, pad, velocity, timeSeconds, DrumInputSource.Test);
+            notes.Add(note);
+            Sort();
+            return notes.IndexOf(note);
+        }
+
+        public void Delete(int index) => notes.RemoveAt(ValidatedIndex(index));
+
+        public ChartRecordingDraft BuildDraft()
+        {
+            var hits = new RecordedChartHit[notes.Count];
+            for (int index = 0; index < notes.Count; index++)
+            {
+                EditableChartNote note = notes[index];
+                hits[index] = new RecordedChartHit(
+                    new DrumInputEvent(note.Pad, note.Velocity, note.TimeSeconds, note.Source),
+                    index);
+            }
+            return new ChartRecordingDraft(durationSeconds, hits);
+        }
+
+        private EditableChartNote At(int index) => notes[ValidatedIndex(index)];
+
+        private int ValidatedIndex(int index)
+        {
+            if (index < 0 || index >= notes.Count) throw new ArgumentOutOfRangeException(nameof(index));
+            return index;
+        }
+
+        private void ValidateTime(double value)
+        {
+            if (double.IsNaN(value) || double.IsInfinity(value) || value < 0 || value > durationSeconds)
+                throw new ArgumentOutOfRangeException(nameof(value), $"Note time must be between 0 and {durationSeconds:0.###} seconds.");
+        }
+
+        private static void ValidatePad(DrumPad pad)
+        {
+            if (!Enum.IsDefined(typeof(DrumPad), pad)) throw new ArgumentOutOfRangeException(nameof(pad));
+        }
+
+        private void Sort() => notes.Sort((left, right) =>
+        {
+            int byTime = left.TimeSeconds.CompareTo(right.TimeSeconds);
+            return byTime != 0 ? byTime : left.Identity.CompareTo(right.Identity);
+        });
+    }
+}