Skip to content

Commit 93fc336

Browse files
qbytesdq-jpgqbytesdq-jpg
committed
Implement MIDI Studio V2 song architecture lane with classification, musical sections, sequence builder, timeline colors, export ownership, and unwired roadmap visibility - PR_26146_072-080-midi-studio-v2-song-architecture-lane
1 parent 6f84a1b commit 93fc336

11 files changed

Lines changed: 441 additions & 8 deletions

‎docs/dev/reports/PR_26146_072_080_control_ownership_matrix.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# PR_26146_072_080 Control Ownership Matrix
2+
3+
| Control | Owner | Canonical field | Status |
4+
| --- | --- | --- | --- |
5+
| Name | Song Setup | `music.songs[].name` | Wired |
6+
| Classification | Song Setup | `music.songs[].classification` | Wired |
7+
| Generated ID | Song Setup | `music.songs[].id` | Wired read-only |
8+
| Tags | None in Song Details | Preserved payload data only | No editable ownership |
9+
| Usage | None in Song Details | Preserved director data only | No editable ownership |
10+
| Tempo/BPM | Song Setup | `studioArrangement.tempo` | Wired |
11+
| Key | Song Setup | `studioArrangement.key` | Wired |
12+
| Style | Song Setup | `studioArrangement.style` | Wired |
13+
| Notes | Song Setup | `music.songs[].director.notes` | Wired |
14+
| Intro/Verse/Chorus/Bridge/Outro | Song Setup | `studioArrangement.songSheet.sections` | Wired |
15+
| Add Custom Section | Song Setup | `studioArrangement.songSheet.sections` | Wired |
16+
| Custom sections text | Song Setup | `studioArrangement.songSheet.sections` | Wired |
17+
| Available Sections | Song Setup | Derived from populated sections | Wired read-only |
18+
| Song Sequence | Song Setup | `studioArrangement.songSheet.sequence` | Wired |
19+
| Add/Duplicate/Move Up/Move Down/Remove sequence | Song Setup | `studioArrangement.songSheet.sequence` | Wired |
20+
| Drag/drop sequence | Song Setup | Future sequence gesture | Red/unwired |
21+
| Apply Chords/Pad | Song Setup | `songSheet.applyTargets.chordsPad` | Wired |
22+
| Apply Bass | Song Setup | `songSheet.applyTargets.bass` | Wired |
23+
| Apply Drums | Song Setup | `songSheet.applyTargets.drums` | Wired |
24+
| Apply Lead | Song Setup | `songSheet.applyTargets.lead` | Wired, default off |
25+
| Parse Guided Song Sheet | Song Setup | `studioArrangement` | Wired |
26+
| Octave Timeline canvas | Octave Timeline | `studioArrangement.lanes` | Wired |
27+
| Section buttons | Octave Timeline | parsed section labels | Wired when section exists |
28+
| Missing section buttons | Octave Timeline | no canonical section | Red/unwired incomplete |
29+
| Timeline quick instrument select | Octave Timeline | `selectedInstrumentId` | Wired |
30+
| Mute/Solo/Show quick controls | Octave Timeline | `previewLaneSettings` | Wired |
31+
| GM Type, GM Instrument, display name | Instruments | `previewLaneSettings` | Wired |
32+
| Volume, Pan/Balance, Octave Range, Transpose | Instruments | `previewLaneSettings` | Wired |
33+
| Effects and advanced MIDI controls | Instruments | Future settings | Red/unwired |
34+
| Audition keyboard | Instruments | Preview Synth from selected instrument settings | Wired |
35+
| Import JSON Manifest | Global NAV | active manifest/toolState payload | Wired |
36+
| Manifest MIDI import/inspect | MIDI Import | `studioArrangement` import normalization | Wired |
37+
| Export target paths | Export | `music.songs[].rendered` | Wired |
38+
| Save WAV/MP3/OGG | Export | Future rendered-audio renderer | Red/unwired |
39+
| SoundFont/render pipeline controls | Export | Future renderer settings | Red/unwired |
40+
| Undo/Redo/Snapshots/Revision History/Revert To Saved/Autosave | Song Setup | Future history state | Red/unwired |
41+
| Warnings accordion | Right column | Song Sheet diagnostics | Wired read-only |
42+
| JSON Details | Diagnostics | selected canonical song/toolState | Wired read-only |
43+
44+
No duplicate editable owners were added for song metadata, section sequence, instruments, export targets, or warnings.

‎docs/dev/reports/PR_26146_072_080_sequence_builder_map.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# PR_26146_072_080 Sequence Builder Map
2+
3+
## Available Sections
4+
Source: populated Song Sheet section fields only.
5+
6+
| UI evidence | Canonical source | Rule |
7+
| --- | --- | --- |
8+
| Available Sections option label | populated `songSheet.sections` row | Shows section name plus bar/chord count |
9+
| `data-song-sheet-section-color-index` | derived from sequence/available section label order | Shared color identity |
10+
| `data-song-sheet-section-bar-count` | progression chord token count | One chord token equals one bar in this guided model |
11+
| `data-song-sheet-section-chord-count` | progression chord token count | Empty sections do not render |
12+
13+
Validated example:
14+
- Intro: 4 bars / 4 chords
15+
- Verse: 4 bars / 4 chords
16+
- Chorus: 4 bars / 4 chords
17+
- Custom1: 2 bars / 2 chords
18+
- Bridge: omitted while empty
19+
20+
## Song Sequence Actions
21+
| Action | Behavior | Canonical model |
22+
| --- | --- | --- |
23+
| Add | Appends selected Available Section label | `songSheet.sequence` |
24+
| Duplicate | Duplicates selected sequence item after itself | `songSheet.sequence` |
25+
| Move Up | Moves selected item earlier | `songSheet.sequence` |
26+
| Move Down | Moves selected item later | `songSheet.sequence` |
27+
| Remove | Removes selected item | `songSheet.sequence` |
28+
| Drag/drop sequence | Visible future control, red/unwired | No mutation |
29+
30+
Validated sequence:
31+
`Intro, Verse, Chorus, Custom1, Outro`
32+
33+
Canonical build order after parse:
34+
`music.songs[].studioArrangement.sections = "Intro:4, Verse:4, Chorus:4, Custom1:2, Outro:1"`
35+
36+
## Color Synchronization
37+
| Surface | Color source | Validation |
38+
| --- | --- | --- |
39+
| Available Sections | section label color index | PASS |
40+
| Song Sequence list | section label color index | PASS |
41+
| Octave Timeline canvas bars | parsed canonical section order | PASS |
42+
| Section shortcut buttons | matching parsed section label | PASS |
43+
| Bar header | current section from timeline reference cell | PASS |
44+
45+
Repeated section labels reuse the same color index. Missing section buttons remain disabled and red/unwired with an Incomplete tooltip.

‎docs/dev/reports/PR_26146_072_080_song_architecture_bundle_validation.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# PR_26146_072_080 Song Architecture Bundle Validation
2+
3+
Status: PASS for targeted MIDI Studio V2 runtime. WARN for required Workspace V2 lane because existing Workspace Manager V2 failures remain outside this PR scope.
4+
5+
## Scope Verified
6+
- Song Details owns editable Name and Classification only, with generated read-only ID from `camelCase(Name) + "-" + Classification` when Classification is populated.
7+
- Tags and Usage remain absent from Song Details editable ownership.
8+
- Song Sheet uses named Intro, Verse, Chorus, Bridge, Outro progression fields plus a wired Add Custom Section action.
9+
- Available Sections lists populated sections only and visibly includes section bar/chord counts plus section color data.
10+
- Song Sequence add, duplicate, move up, move down, and remove actions update canonical sequence order.
11+
- Parse Guided Song Sheet updates the canonical song model, Octave Timeline order/colors, diagnostics, and JSON Details.
12+
- Warnings render only in the right-column Warnings accordion.
13+
- Export ownership, Save WAV/MP3/OGG wording, instrument SSoT, audition keyboard, Play/Stop, selectedInstrumentId sync, and launch NAV behavior were preserved.
14+
15+
## Validation Commands
16+
- PASS: `node --check tools/midi-studio-v2/js/controls/SongSheetControl.js`
17+
- PASS: `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
18+
- PASS: `node --check tools/midi-studio-v2/js/bootstrap.js`
19+
- PASS: `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
20+
- PASS: `node --check tools/midi-studio-v2/js/controls/SongDetailsControl.js`
21+
- PASS: `node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
22+
- PASS: `node --check tools/midi-studio-v2/js/controls/OctaveTimelineCanvasRenderer.js`
23+
- PASS: `node --check tools/midi-studio-v2/js/controls/ExportPanelControl.js`
24+
- PASS: `node --check src/engine/audio/SongSheetParser.js`
25+
- PASS: `rg --pcre2 -n '<style\b|<script\b(?![^>]*\bsrc=)|\son[a-z]+\s=|style\s=' tools/midi-studio-v2/index.html` returned no inline script, style, event-handler, or inline-style matches.
26+
- PASS: `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --grep "PR072-080" --reporter=list` ran 1 test and passed.
27+
- PASS: `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --grep "PR070|PR071|PR072-075|PR076-079|PR072-080" --reporter=list` ran 5 tests and passed.
28+
- FAIL unrelated: `npm run test:workspace-v2` ran 72 Workspace Manager V2 tests: 49 passed, 23 failed.
29+
- PASS: `git diff --check`
30+
31+
## Workspace V2 Lane Classification
32+
The required workspace-contract lane failed outside MIDI Studio V2. Representative failures:
33+
- Workspace Manager V2 helper still expects 11 tool tiles and now receives 12.
34+
- Several repo/game-selection and workspace save/restore tests share the same 11 vs 12 tile-count assertion.
35+
- One Asset Manager V2 session-context test timed out after 120000 ms and then reported closed-page coverage cleanup.
36+
37+
No failing workspace-contract stack referenced the changed MIDI Studio V2 files.
38+
39+
## Playwright Coverage
40+
`docs/dev/reports/playwright_v8_coverage_report.txt` and `docs/dev/reports/coverage_changed_js_guardrail.txt` were regenerated from the targeted MIDI Studio Playwright run. Changed runtime JS files were collected with advisory coverage.
41+
42+
## Samples Decision
43+
SKIP: full samples smoke was not run because this PR only changes MIDI Studio V2 tool behavior and tests use the targeted UAT manifest fixture.

‎docs/dev/reports/PR_26146_072_080_song_sheet_model.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# PR_26146_072_080 Song Sheet Model
2+
3+
## Song Details
4+
| Field | Ownership | Behavior |
5+
| --- | --- | --- |
6+
| Name | Song Setup | Editable canonical `music.songs[].name` |
7+
| Classification | Song Setup | Editable human-typed `music.songs[].classification` |
8+
| Classification help | Song Setup | `?` help icon with examples: Menu, Intro, Loop, Boss, Victory, Game Over, Ambient, Cutscene, Underwater, Flying, Ice, Lava, Space, Castle, Town, Dungeon, Forest, Night, Stealth, Puzzle, Chase |
9+
| ID | Song Setup | Read-only generated `music.songs[].id` |
10+
| Tags | None in Song Details | Not rendered as editable ownership |
11+
| Usage | None in Song Details | Not rendered as editable ownership |
12+
13+
ID generation:
14+
- `Main Theme` + `Loop` -> `mainTheme-Loop`
15+
- `Forest Theme` + `Underwater` -> `forestTheme-Underwater`
16+
- `Sky Battle` + `Flying` -> `skyBattle-Flying`
17+
18+
Duplicate generated IDs receive a numeric suffix to preserve manifest uniqueness.
19+
20+
## Section Model
21+
The Song Sheet owns these named progression fields:
22+
- Intro
23+
- Verse
24+
- Chorus
25+
- Bridge
26+
- Outro
27+
28+
Custom sections are added through `Add Custom Section`, which appends the next valid `CustomN:` label into the custom section editor. A custom section becomes populated only after it has progression text.
29+
30+
Each populated row emits one canonical line in `music.songs[].studioArrangement.songSheet.sections`, for example:
31+
- `Intro: G C G D`
32+
- `Verse: G Em C D`
33+
- `Chorus: C G Am F`
34+
35+
Empty named or custom sections are omitted from Available Sections and omitted from the canonical section text.
36+
37+
## Apply Targets
38+
Defaults:
39+
- Chords/Pad: enabled
40+
- Bass: enabled
41+
- Drums: enabled when a drums lane/instrument exists
42+
- Lead: disabled
43+
44+
Canonical field: `music.songs[].studioArrangement.songSheet.applyTargets`.
45+
46+
## Parse Flow
47+
Parse Guided Song Sheet composes parser input from:
48+
- populated sections
49+
- Song Sequence order
50+
- Apply Song Sheet To selections
51+
52+
Successful parse updates:
53+
- `music.songs[].studioArrangement.songSheet.sections`
54+
- `music.songs[].studioArrangement.songSheet.sequence`
55+
- `music.songs[].studioArrangement.songSheet.applyTargets`
56+
- `music.songs[].studioArrangement.sections`
57+
- generated Octave Timeline lane text for selected apply targets
58+
- diagnostics and JSON Details

‎docs/dev/reports/PR_26146_072_080_unwired_audit.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# PR_26146_072_080 Unwired Audit
2+
3+
## Rule
4+
Any visible feature that is not fully implemented must be red/unwired and expose a tooltip/status explaining the incomplete state.
5+
6+
Central implementation:
7+
- `tools/midi-studio-v2/js/controls/UnwiredControlState.js`
8+
- CSS marker: `.midi-studio-v2__unwired-control`
9+
- Data marker: `data-midi-studio-unwired`
10+
11+
## Red/Unwired Controls Verified
12+
| Control group | Examples | Status text |
13+
| --- | --- | --- |
14+
| Song Sequence future gesture | Drag/drop sequence | Not implemented |
15+
| Missing section shortcuts | Boss, Victory, unavailable section buttons | Incomplete |
16+
| Export renderer | Output Type, Save WAV/MP3/OGG | Not implemented |
17+
| SoundFont/render pipeline | SoundFont, Render Quality, Sample Rate, Normalize Volume, Export Stems, Loop Export | Not implemented |
18+
| Editing History | Undo, Redo, Snapshots, Revision History, Revert To Saved, Autosave | Not implemented |
19+
| MIDI input future controls | Enable MIDI Input, Select MIDI Device, Record MIDI | Not implemented |
20+
| Instrument future controls | Effects, Advanced MIDI settings | Not implemented |
21+
22+
## Wired Controls Verified Not Red/Unwired
23+
| Control group | Examples |
24+
| --- | --- |
25+
| Song Details | Name, Classification, generated ID |
26+
| Song Sheet | named sections, Add Custom Section, Available Sections, Song Sequence actions, Apply targets, Parse Guided Song Sheet |
27+
| Octave Timeline | canvas editing, section buttons for existing sections, Play Section, Play Loop, Stop, quick instrument selection |
28+
| Instruments | GM Type, GM Instrument, display name, volume, pan, octave range, transpose, audition keyboard |
29+
| Export ownership | rendered target path inputs |
30+
| Global NAV | Import JSON Manifest, Play, Stop, Stop All Audio, Save Project, Reset Song Edits |
31+
32+
## Tooltip/Status Evidence
33+
- Future controls expose `title` text beginning with `Not implemented:`.
34+
- Missing section controls expose `title` text beginning with `Incomplete:`.
35+
- Export status reports that rendered audio export is not implemented while preserving Save WAV/MP3/OGG wording.
36+
37+
## Result
38+
PASS: targeted Playwright found no visible unwired controls missing red styling, `data-midi-studio-unwired`, or explanatory tooltip/status text in the audited MIDI Studio V2 surfaces.

0 commit comments

Comments
 (0)