Make MIDI Studio V2 note edits persist and drive playback from canonical song data - PR_26146_047-midi-studio-v2-note-edit-persistence-and-playback-truth

Author: ToolboxAid

docs/dev/reports/PR_26146_047-midi-studio-v2-note-edit-persistence-and-playback-truth_validation.md

@@ -0,0 +1,72 @@
+# PR_26146_047 MIDI Studio V2 Note Edit Persistence And Playback Truth Validation
+
+Status: PASS
+
+## Scope
+- Continued from PR_26146_046.
+- Kept octave timeline edits as the source of truth for the canonical selected song model.
+- Added visible project dirty state for edited note data.
+- Added Save Project behavior that serializes the canonical tool payload, updates JSON Details, clears dirty state, and reports saved song/note counts.
+- Added Reset Song Edits behavior that restores the selected song from the imported manifest baseline.
+- Preserved one Studio Octave Timeline, MIDI Import tab ownership, piano-style keyboard grid, GM instrument controls, Play/Stop, section behavior, export Type + Save, and no SoundFont/export-rendering scope.
+
+## Changed-File Syntax Checks
+PASS:
+
+```text
+node --check tools/midi-studio-v2/js/MidiStudioV2App.js
+node --check tools/midi-studio-v2/js/bootstrap.js
+node --check tools/midi-studio-v2/js/controls/ActionNavControl.js
+node --check tests/playwright/tools/MidiStudioV2.spec.mjs
+```
+
+Additional guards:
+
+```text
+HTML external-only guard passed
+CSS brace check passed
+```
+
+## Targeted Playwright Validation
+PASS:
+
+```text
+npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs -g "persists octave note edits into canonical song data, playback, save, and reset|fast octave note editing supports drag painting keyboard shortcuts selection and timeline scroll sync|derives primary song, instrument, grid, playback, and diagnostics views from the canonical selected song|imports a local MIDI source from the MIDI Import tab without default HTTP 404 noise|renders timing ruler, section navigation, and loop region visualization" --config=codex_playwright_system_chrome.config.cjs --reporter=list --workers=1 --timeout=60000
+```
+
+Result:
+
+```text
+Running 5 tests using 1 worker
+ok 1 fast octave note editing supports drag painting keyboard shortcuts selection and timeline scroll sync
+ok 2 persists octave note edits into canonical song data, playback, save, and reset
+ok 3 imports a local MIDI source from the MIDI Import tab without default HTTP 404 noise
+ok 4 derives primary song, instrument, grid, playback, and diagnostics views from the canonical selected song
+ok 5 renders timing ruler, section navigation, and loop region visualization
+5 passed
+```
+
+## Required Assertions Covered
+- PASS: editing a note updates canonical `song.studioArrangement.lanes`.
+- PASS: playback uses the edited grid passed into Preview Synth.
+- PASS: JSON Details reflects edited notes immediately after edit and after Save Project.
+- PASS: visible dirty state appears after edit.
+- PASS: switching songs and returning preserves edited notes during the current session.
+- PASS: Save Project reports saved song count and editable note event count.
+- PASS: Reset Song Edits restores the imported song state.
+- PASS: Play and Stop still work through targeted playback tests.
+
+## Diff Hygiene
+PASS:
+
+```text
+git diff --check
+```
+
+Git reported line-ending normalization warnings for touched files, but no whitespace errors.
+
+## Not Run
+- Full samples smoke test was not run, per PR instructions.
+
+## Result
+PR_26146_047 is marked PASS. Playback did not ignore edited grid state in targeted validation.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -960,6 +960,74 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("persists octave note edits into canonical song data, playback, save, and reset", async ({ page }) => {
+    const server = await openMidiStudioForImport(page);
+    try {
+      await page.locator("#toolImportManifestInput").setInputFiles(uatManifestPath);
+      await selectInstrumentRow(page, "lead");
+      await expect(page.locator("#projectDirtyState")).toHaveText("Saved");
+      await expect(page.locator("body")).toHaveAttribute("data-midi-studio-dirty", "false");
+      const originalLeadLane = await page.evaluate(() => window.__midiStudioV2App.selectedSong().studioArrangement.lanes.lead);
+      await expect(octaveCell(page, "C6", 2)).not.toHaveAttribute("data-note-lanes", /lead/);
+
+      await octaveCell(page, "C6", 2).click();
+      await expect(octaveCell(page, "C6", 2)).toHaveAttribute("data-note-lanes", /lead/);
+      await expect(page.locator("#projectDirtyState")).toHaveText("Unsaved changes");
+      await expect(page.locator("body")).toHaveAttribute("data-midi-studio-dirty", "true");
+      const editedState = await page.evaluate(() => {
+        const app = window.__midiStudioV2App;
+        return {
+          currentGridHasEdit: app.lastInstrumentGridResult.timeline.some((event) => event.lane === "lead" && event.stepIndex === 2 && event.value === "C6"),
+          json: document.querySelector("#inspectorOutput").textContent,
+          leadLane: app.selectedSong().studioArrangement.lanes.lead
+        };
+      });
+      expect(editedState.currentGridHasEdit).toBe(true);
+      expect(editedState.leadLane).toContain("C6");
+      expect(editedState.json).toContain('"lead"');
+      expect(editedState.json).toContain("C6");
+
+      await page.locator('[data-song-id="frog-hop-nursery-rhyme"]').click();
+      await page.locator('[data-song-id="camptown-races-uat-reel"]').click();
+      await selectInstrumentRow(page, "lead");
+      await expect(octaveCell(page, "C6", 2)).toHaveAttribute("data-note-lanes", /lead/);
+      expect(await page.evaluate(() => window.__midiStudioV2App.selectedSong().studioArrangement.lanes.lead)).toContain("C6");
+
+      await page.evaluate(() => {
+        const app = window.__midiStudioV2App;
+        const originalPlayGridRange = app.previewSynth.playGridRange.bind(app.previewSynth);
+        app.__lastPreviewGridValues = [];
+        app.previewSynth.playGridRange = async (options) => {
+          app.__lastPreviewGridValues = options.grid.timeline
+            .filter((event) => event.lane === "lead" && event.stepIndex === 2)
+            .map((event) => event.value);
+          return originalPlayGridRange(options);
+        };
+      });
+      await page.locator("#playButton").click();
+      await expect(page.locator("#stopButton")).toBeEnabled();
+      expect(await page.evaluate(() => window.__midiStudioV2App.__lastPreviewGridValues)).toContain("C6");
+      await page.locator("#stopButton").click();
+      await expect(page.locator("#playButton")).toBeEnabled();
+
+      await page.locator("#saveProjectButton").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Save Project completed: 3 songs saved with \d+ editable note events\./);
+      await expect(page.locator("#projectDirtyState")).toHaveText("Saved");
+      await expect(page.locator("body")).toHaveAttribute("data-midi-studio-dirty", "false");
+      await expect(page.locator("#inspectorOutput")).toContainText('"schema": "html-js-gaming.tool-state"');
+      await expect(page.locator("#inspectorOutput")).toContainText("C6");
+
+      await page.locator("#resetSongEditsButton").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Reset Song Edits restored Camptown Races UAT Reel to imported manifest state\./);
+      await expect(octaveCell(page, "C6", 2)).not.toHaveAttribute("data-note-lanes", /lead/);
+      await expect(page.locator("#projectDirtyState")).toHaveText("Saved");
+      expect(await page.evaluate(() => window.__midiStudioV2App.selectedSong().studioArrangement.lanes.lead)).toBe(originalLeadLane);
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("octave timeline freezes compact headers and note labels while active cells stay textless", async ({ page }) => {
     const server = await openMidiStudioForImport(page);
     try {

tools/midi-studio-v2/index.html

@@ -44,6 +44,9 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
       <button id="playButton" type="button" disabled>Play</button>
       <button id="stopButton" type="button" disabled>Stop</button>
       <button id="stopAllAudioButton" type="button">Stop All Audio</button>
+      <button id="saveProjectButton" type="button" disabled>Save Project</button>
+      <button id="resetSongEditsButton" type="button" disabled>Reset Song Edits</button>
+      <span id="projectDirtyState" class="midi-studio-v2__dirty-state" data-midi-studio-dirty-state="clean">Saved</span>
       <div class="midi-studio-v2__export-save-controls">
         <label class="midi-studio-v2__compact-field" for="renderedExportTargetTypeSelect">
           <span>Type</span>

tools/midi-studio-v2/js/MidiStudioV2App.js

@@ -1,4 +1,6 @@
 import { readFileText } from "../../../src/engine/persistence/FilePersistenceService.js";
+import { deepClone } from "../../../src/shared/json/clone.js";
+import { notifyWorkspaceToolDirty } from "../../../src/tools/common/WorkspaceDirtyNotifier.js";
 
 const TOOL_ID = "midi-studio-v2";
 const NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
@@ -36,6 +38,9 @@ export class MidiStudioV2App {
     this.instrumentGrid = instrumentGrid;
     this.instrumentGridParser = instrumentGridParser;
     this.instrumentGridResults = new WeakMap();
+    this.importedSongBaselines = new Map();
+    this.isDirty = false;
+    this.lastSavedToolState = null;
     this.manifestLoader = manifestLoader;
     this.midiSourceDetails = midiSourceDetails;
     this.midiSourceInspection = midiSourceInspection;
@@ -85,6 +90,8 @@ export class MidiStudioV2App {
       onToolCopyJson: () => this.copyJson(),
       onToolExportToolState: () => this.exportToolState(),
       onToolImportManifest: (file) => this.importManifestFile(file),
+      onResetSongEdits: () => this.resetSelectedSongEdits(),
+      onSaveProject: () => this.saveProject(),
       onWorkspaceCopyManifest: () => this.statusLog.info("Workspace copy is owned by Workspace Manager V2."),
       onWorkspaceExportManifest: () => this.statusLog.info("Workspace export is owned by Workspace Manager V2."),
       onWorkspaceImportManifest: () => this.statusLog.info("Workspace import is owned by Workspace Manager V2.")
@@ -141,6 +148,9 @@ export class MidiStudioV2App {
 
   renderEmpty() {
     this.payload = null;
+    this.importedSongBaselines = new Map();
+    this.lastSavedToolState = null;
+    this.setDirtyState(false);
     this.songList.render([], "");
     this.details.render(null, null);
     this.directorPanel.render(null, {});
@@ -171,6 +181,9 @@ export class MidiStudioV2App {
       return false;
     }
     this.payload = normalized.payload;
+    this.importedSongBaselines = new Map(this.payload.songs.map((song) => [song.id, deepClone(song)]));
+    this.lastSavedToolState = null;
+    this.setDirtyState(false);
     this.render();
     this.applySelectedSongArrangement("active manifest song");
     this.statusLog.ok(`Loaded ${this.payload.songs.length} MIDI song${this.payload.songs.length === 1 ? "" : "s"} from ${sourceLabel} via ${normalized.sourceKind}.`);
@@ -259,6 +272,27 @@ export class MidiStudioV2App {
     };
   }
 
+  setDirtyState(isDirty) {
+    this.isDirty = isDirty === true;
+    this.actionNav.setDirtyState(this.isDirty);
+    this.window.document.body.dataset.midiStudioDirty = this.isDirty ? "true" : "false";
+  }
+
+  markDirty({ changedKeys = ["data.songs"], reason = "midi-studio-song-updated" } = {}) {
+    this.setDirtyState(true);
+    const result = notifyWorkspaceToolDirty({
+      changedKeys,
+      payload: this.payload,
+      reason,
+      toolId: TOOL_ID,
+      windowRef: this.window
+    });
+    if (!result.ok) {
+      this.statusLog.warn(`Workspace dirty state not updated: ${result.message}`);
+    }
+    return result;
+  }
+
   get selectedSongId() {
     return this.payload?.activeSongId || "";
   }
@@ -420,6 +454,7 @@ export class MidiStudioV2App {
       this.payload.songs.push(song);
       this.payload.activeSongId = song.id;
     }
+    this.importedSongBaselines.set(song.id, deepClone(song));
     this.render();
     this.midiSourceDetails.render(result);
     this.applySelectedSongArrangement("local MIDI import");
@@ -655,6 +690,7 @@ export class MidiStudioV2App {
       this.instrumentGrid.syncEditedGridResult(result);
     }
     this.syncSelectedArrangementFromGridInput(input);
+    this.markDirty({ changedKeys: ["data.songs.studioArrangement"], reason: "midi-studio-note-grid-edited" });
     if (detail.action === "add-lane") {
       this.statusLog.ok(`Added instrument row ${detail.laneLabel || detail.lane}; playback data updated.`);
     } else if (detail.action === "delete-lane") {
@@ -686,6 +722,31 @@ export class MidiStudioV2App {
     this.details.showJson(song);
   }
 
+  gridInputFromArrangement(arrangement) {
+    return {
+      bass: arrangement.lanes?.bass || "",
+      beatsPerBar: arrangement.beatsPerBar,
+      chords: arrangement.lanes?.chords || "",
+      drums: arrangement.lanes?.drums || "",
+      lanes: arrangement.lanes || {},
+      lead: arrangement.lanes?.lead || "",
+      pad: arrangement.lanes?.pad || "",
+      previewInstruments: arrangement.previewInstruments || {},
+      sections: arrangement.sections,
+      subdivision: arrangement.subdivision
+    };
+  }
+
+  editableNoteCount(payload = this.payload) {
+    return (payload?.songs || []).reduce((count, song) => {
+      if (!song.studioArrangement) {
+        return count;
+      }
+      const result = this.instrumentGridParser.parse(this.gridInputFromArrangement(song.studioArrangement));
+      return result.ok ? count + result.timeline.length : count;
+    }, 0);
+  }
+
   syncSelectedArrangementFromSongSheetResult(result) {
     const song = this.selectedSong();
     if (!song?.studioArrangement || !result?.ok) {
@@ -1026,6 +1087,48 @@ export class MidiStudioV2App {
     this.statusLog.ok("MIDI Studio V2 toolState preview written to JSON Details.");
   }
 
+  saveProject() {
+    if (!this.payload) {
+      this.statusLog.fail("Save Project failed: no MIDI Studio V2 payload is loaded.");
+      return;
+    }
+    try {
+      const toolState = this.serializer.createToolState(this.payload);
+      JSON.stringify(toolState);
+      this.lastSavedToolState = toolState;
+      this.details.showJson(toolState);
+      this.setDirtyState(false);
+      const noteCount = this.editableNoteCount();
+      this.statusLog.ok(`Save Project completed: ${this.payload.songs.length} song${this.payload.songs.length === 1 ? "" : "s"} saved with ${noteCount} editable note event${noteCount === 1 ? "" : "s"}.`);
+    } catch (error) {
+      this.statusLog.fail(`Save Project failed: ${error.message}`);
+    }
+  }
+
+  resetSelectedSongEdits() {
+    const song = this.selectedSong();
+    if (!song) {
+      this.statusLog.fail("Reset Song Edits failed: no MIDI song is selected.");
+      return;
+    }
+    const baseline = this.importedSongBaselines.get(song.id);
+    if (!baseline) {
+      this.statusLog.fail(`Reset Song Edits failed: imported state is unavailable for ${song.name || song.id}.`);
+      return;
+    }
+    const index = this.payload.songs.findIndex((candidate) => candidate.id === song.id);
+    if (index < 0) {
+      this.statusLog.fail(`Reset Song Edits failed: ${song.id} is not in the active MIDI payload.`);
+      return;
+    }
+    this.stopPlayback({ log: false });
+    this.payload.songs[index] = deepClone(baseline);
+    this.render();
+    this.applySelectedSongArrangement("Reset Song Edits");
+    this.setDirtyState(false);
+    this.statusLog.ok(`Reset Song Edits restored ${baseline.name || baseline.id} to imported manifest state.`);
+  }
+
   async copyJson() {
     if (!this.payload) {
       this.statusLog.fail("Copy blocked: no MIDI Studio V2 payload is loaded.");

tools/midi-studio-v2/js/bootstrap.js

@@ -42,7 +42,10 @@ window.addEventListener("DOMContentLoaded", () => {
     accordions: Array.from(document.querySelectorAll(".accordion-v2"), (section) => new AccordionSection(section)),
     actionNav: new ActionNavControl({
       nowPlayingLabel: requireElement("#nowPlayingLabel"),
+      projectDirtyState: requireElement("#projectDirtyState"),
       returnToWorkspaceButton: requireElement("#returnToWorkspaceButton"),
+      resetSongEditsButton: requireElement("#resetSongEditsButton"),
+      saveProjectButton: requireElement("#saveProjectButton"),
       stopAllAudioButton: requireElement("#stopAllAudioButton"),
       toolCopyJsonButton: requireElement("#toolCopyJsonButton"),
       toolExportToolStateButton: requireElement("#toolExportToolStateButton"),

tools/midi-studio-v2/js/controls/ActionNavControl.js

@@ -2,7 +2,10 @@ export class ActionNavControl {
   constructor({
     locationRef = window.location,
     nowPlayingLabel,
+    projectDirtyState,
     returnToWorkspaceButton,
+    resetSongEditsButton,
+    saveProjectButton,
     stopAllAudioButton,
     toolCopyJsonButton,
     toolExportToolStateButton,
@@ -17,7 +20,10 @@ export class ActionNavControl {
   }) {
     this.location = locationRef;
     this.nowPlayingLabel = nowPlayingLabel;
+    this.projectDirtyState = projectDirtyState;
     this.returnToWorkspaceButton = returnToWorkspaceButton;
+    this.resetSongEditsButton = resetSongEditsButton;
+    this.saveProjectButton = saveProjectButton;
     this.stopAllAudioButton = stopAllAudioButton;
     this.toolCopyJsonButton = toolCopyJsonButton;
     this.toolExportToolStateButton = toolExportToolStateButton;
@@ -35,6 +41,8 @@ export class ActionNavControl {
     onToolCopyJson,
     onToolExportToolState,
     onToolImportManifest,
+    onResetSongEdits,
+    onSaveProject,
     onStopAllAudio,
     onWorkspaceCopyManifest,
     onWorkspaceExportManifest,
@@ -43,6 +51,8 @@ export class ActionNavControl {
     this.applyLaunchMode();
     this.toolImportManifestButton.addEventListener("click", () => this.toolImportManifestInput.click());
     this.toolImportManifestInput.addEventListener("change", () => onToolImportManifest(this.toolImportManifestInput.files?.[0] || null));
+    this.saveProjectButton.addEventListener("click", onSaveProject);
+    this.resetSongEditsButton.addEventListener("click", onResetSongEdits);
     this.stopAllAudioButton.addEventListener("click", onStopAllAudio);
     this.toolCopyJsonButton.addEventListener("click", onToolCopyJson);
     this.toolExportToolStateButton.addEventListener("click", onToolExportToolState);
@@ -69,6 +79,16 @@ export class ActionNavControl {
   setToolActionsEnabled(isEnabled) {
     this.toolCopyJsonButton.disabled = !isEnabled;
     this.toolExportToolStateButton.disabled = !isEnabled;
+    this.saveProjectButton.disabled = !isEnabled;
+    this.resetSongEditsButton.disabled = !isEnabled;
+  }
+
+  setDirtyState(isDirty) {
+    if (!this.projectDirtyState) {
+      return;
+    }
+    this.projectDirtyState.dataset.midiStudioDirtyState = isDirty ? "dirty" : "clean";
+    this.projectDirtyState.textContent = isDirty ? "Unsaved changes" : "Saved";
   }
 
   setNowPlaying(song, { playing = false } = {}) {