# DeepPluck V0.12.75 Standalone Virtual MIDI Keyboard — Implementation Report

Date: 2026-09-04 (Europe/Berlin)
Branch: `master`
Reference: Windows 11 x64; Visual Studio Community 2026 18.9.2; MSVC
19.51.36256.0 / VCTools 14.51.36231; Windows SDK 10.0.26100.0; CMake 4.4.3;
JUCE 9.0.1; C++20.

## Reconciliation and retained work

The first audit began at `4b4d0e5867799f66b9e3db95eb70cad195b57d33`
(`docs: add V0.11.25 implementation report`) with an empty index, 18 modified
tracked files and 58 untracked top-level entries. `build/` and `Artifacts/` were
ignored, `COPY_PLUGIN_AFTER_BUILD` was false, and `JUCE/` had no diff.

The original tracked changes were classified before any V0.12.75 source edit:

| Tracked path | Retained ownership |
|---|---|
| `ARCHITECTURE.md` | integrated V0.11.5 / V0.12.0 / V0.12.5 documentation |
| `CMakeLists.txt` | integrated V0.11.5 harness, V0.12.0 content, V0.12.5 version |
| `README.md` | integrated V0.11.5 / V0.12.0 / V0.12.5 workflow and status |
| `Source/Effects/DeepPluckEffectsRack.h` | V0.11.5 benchmark inspection seam |
| `Source/GUI/DeepPluckEditorComponents.cpp` | V0.12.5 Welcome/About UX |
| `Source/GUI/DeepPluckEditorComponents.h` | V0.12.5 Welcome/About UX |
| `Source/GUI/DeepPluckGuiSupport.cpp` | V0.12.5 GUI preferences |
| `Source/PluginProcessor.cpp` | integrated V0.11.5 optimization and V0.12.0 Factory library |
| `Source/PluginProcessor.h` | integrated V0.11.5 benchmark seam and V0.12.0 Factory library |
| `Source/Presets/DeepPluckPresetManager.cpp` | V0.12.0 approved Factory browsing |
| `Source/Presets/DeepPluckPresetManager.h` | V0.12.0 approved Factory browsing |
| `Source/Synth/DeepPluckOscillator.h` | V0.11.5 settled waveform-mix optimization |
| `Source/Synth/DeepPluckVoice.h` | V0.11.5 benchmark inspection seam |
| `Tests/SmokeStandalone.ps1` | retained native process-smoke hardening |
| `Tests/TestMain.cpp` | integrated V0.11.5 / V0.12.0 / V0.12.5 regression coverage |
| `Tests/ToneVoicingAudit.cpp` | V0.11.5 null-audio and diagnostic evidence support |
| `Tests/VerifyArtifacts.ps1` | V0.12.0/V0.12.5 artifact and helper validation |
| `Tests/VerifyGeneratedVersion.ps1` | V0.12.0/V0.12.5 seven-target version validation |

Legitimate untracked project work comprised the Factory CMake module, approved
116-preset source/catalog, preset codec/library, benchmark/Factory tools,
workflow documents and V0.11.5/V0.12.0/V0.12.5 implementation reports. Protected
untracked user material comprised `CubaseTest/`, reference/screenshot PNG files
under `Docs/`, historical/user-supplied MasterPrompt files and anything not
unambiguously attributable to project work. The V0.12.75 MasterPrompt was
reserved for this milestone rather than the reconciliation checkpoint.

Comparison used the retained V0.12.5 root
`Artifacts/V0.12.5/20260904T172424Z`: Debug and Release 39/39 CTests, one
696/696 corpus per configuration, finite output, quiet tails, matching local
artifacts, native VST3 factory and Standalone process smokes. These results were
valid for the reconciled pre-keyboard source and were not rerun merely to create
the checkpoint.

The V0.11.5 D96/64 deadline finding remains technically **OPEN/deferred**. The
second confirmation contained 11 candidate deadline misses; the later clean
matrix and practical functional approval do not convert that finding into a
performance PASS. On 2026-09-04 the user answered **“ja”** to the explicit request
to retain it as a documented known limitation and checkpoint the validated
V0.11.5-through-V0.12.5 baseline without claiming that the gate passed.

Reconciliation commit and V0.12.75 Start HEAD:

- `231cbd871fa1da3c44650599cff109ee20ef12de`
- `chore: reconcile V0.11.5 through V0.12.5 working baseline`

No earlier legitimate work was reset, stashed, deleted or overwritten. Protected
files remained present and unstaged.

## Implementation

`DeepPluckStandaloneKeyboardPanel` owns a JUCE `MidiKeyboardState`, horizontal
`MidiKeyboardComponent`, `Oct -` / `Oct +`, the non-persisted octave view and an
idempotent listener lifecycle. It uses channel 1, MIDI range 0..127, 38-pixel
keys, conventional MIDI-60-is-C4 labels and starts at MIDI 36 (C2). The visible
low key moves by 12 and clamps to 0..60. Internal JUCE scroll arrows have zero
width, wheel scrolling is ignored, computer key mappings are cleared and the
piano does not request or grab keyboard focus. QWERTZ is deliberately deferred.

The editor uses only `AudioProcessor::wrapperType`. VST3, Undefined and other
wrappers do not create a panel, reserve space or query a Standalone holder. The
VST3 remains exactly 1536 x 900. Standalone becomes 1536 x 980 while every
existing child keeps its bounds inside the unchanged (0,0,1536,900) main region;
the keyboard strip is exactly (0,900,1536,80). Welcome covers the complete
Standalone editor and remains above the strip for hit testing.

Production Standalone construction obtains JUCE's existing
`StandalonePluginHolder` only after the wrapper check, verifies that it owns the
same processor and registers the holder player's `MidiMessageCollector` as the
keyboard-state listener. Tests inject a fake listener at this boundary and use
the real collector without a device. External and virtual notes therefore enter
one timestamped stream before the unchanged sample-accurate processor path.
Same-channel/same-note input retains the existing retrigger then matching
Note-Off semantics; no source reference count or second merge was added.

Cleanup disables new panel interaction, sends state-owned Note-Off events via
`allNotesOff(1)` while connected, then detaches the listener. It is idempotent
and does not send a global controller command that would cut external notes.
Showing Welcome from SETTINGS calls the same state-owned release before the
overlay blocks the keyboard, so an active virtual gesture cannot be hidden.
`releaseResources()` remains the final hard device/shutdown reset. No Processor,
Synthesiser, Voice, DSP, parameter, preset, Factory content or state code changed.
The audio callback performs no new keyboard/GUI work; the panel adds no timer or
idle polling.

Changed project documentation: `README.md`, `ARCHITECTURE.md`,
`Tests/FactoryPresets.md`, `Tests/StandaloneVirtualMidiKeyboard.md`, this report,
and the binding V0.12.75 MasterPrompt. Evidence wrappers were extended narrowly
to `Artifacts/V0.12.75`; the native Standalone smoke now records and bounds the
JUCE window client area around the exact editor size.

## Verification

Final evidence root: `Artifacts/V0.12.75/20260904T182415Z/`

| Gate | Result | Evidence |
|---|---|---|
| Confirmed toolchain and fresh configure | PASS; MSVC 19.51.36256, VCTools 14.51.36231, SDK 10.0.26100.0, CMake 4.4.3, VS18 2026 x64; 4.22 s | `final/configure-Release-20260904T182529496Z-*` |
| Debug warning-free build | PASS; fresh full build 150.05 s, final post-cleanup rebuild 30.77 s; 0 compiler warning/error diagnostics in both | `final/build-Debug-20260904T182544644Z-*`, `final/build-Debug-20260904T193425563Z-*` |
| Release warning-free build | PASS; fresh full build 245.70 s, final post-cleanup rebuild 19.77 s; 0 compiler warning/error diagnostics in both | `final/build-Release-20260904T185354713Z-*`, `final/build-Release-20260904T195748039Z-*` |
| Debug 40 CTests | PASS 40/40 on final source; 1342.59 s (the earlier pre-cleanup 40/40 run took 1501.45 s) | `final/test-Debug-20260904T193512340Z-*` |
| Release 40 CTests | PASS 40/40 on final source; 186.87 s (the earlier pre-cleanup 40/40 run took 273.55 s) | `final/test-Release-20260904T195817863Z-*` |
| Debug final Factory corpus | PASS 696/696; one run; 0 failures; 1386.90 s; max peak 0.583521; content finite/tails quiet | `audio-debug/summary.json` |
| Release final Factory corpus | PASS 696/696; one run; 0 failures; 240.28 s; max peak 0.583521; content finite/tails quiet | `audio-release/summary.json` |
| Debug artifact versions and local-copy identity | PASS on final binaries; 0.12.75 plus stale/missing/class negative probes; 0.60 s | `final/versions-Debug-20260904T200208443Z-*` |
| Release artifact versions and local-copy identity | PASS on final binaries; 0.12.75 plus stale/missing/class negative probes; 0.51 s | `final/versions-Release-20260904T200210834Z-*` |
| Release Standalone native process smoke | PASS on final binary; JUCE client 1538 x 1008 around exact 1536 x 980 editor; normal close; exit 0; no owned process | `verification/standalone-release-final.json` |
| Debug/Release native VST3 factory smokes | PASS on final binaries; exactly two classes; clean unload | `verification/vst3-debug-final.json`, `verification/vst3-release-final.json` |

Before the full gate, focused Debug and Release selection passed 6/6
(`evidence_paths`, `parameters`, `sample_accuracy`, `gui`,
`standalone_keyboard`, `preset_integration`). The focused Standalone suite also
renders `build/TestData/StandaloneKeyboard/StandaloneKeyboard.png`; visual
inspection confirmed the unchanged main UI, the complete strip, readable C2
labels and both octave buttons. A native Release iteration smoke opened a JUCE
client area of 1538 x 1008 around the exact 1536 x 980 editor, closed normally,
exited 0 and left no owned process. Native Release VST3 factory load reported
exactly two classes and unloaded cleanly.

The full `standalone_keyboard` result proves VST3/Undefined have no panel or
reserved area, all five representative existing main-child bounds match
Standalone exactly, parameter count remains 62, serialized APVTS state is
unchanged, and the unused VST3/Standalone audio comparison is bit-identical.
Channel-1 white/black state gestures, drag-like ordering, rapid retrigger,
four-note chord, bounds, collector merge, same-note retrigger/offs, destructor
cleanup, idempotent disconnect, finite 17th-note stealing and hard release reset
all pass. Existing `preset_files`, `preset_integration`, `sample_accuracy`,
Factory and state/migration suites pass in both complete configurations.

Final physical outputs exist at the normal Debug/Release VST3 and Standalone
build paths and at `Artifacts/Debug` / `Artifacts/Release`. The version gate
reads 0.12.75 from VST3 classes, Standalone resources, all local copies and all
versioned helper executables, and verifies complete VST3 bundle/local-copy byte
identity. `COPY_PLUGIN_AFTER_BUILD` remained false; only project-local copies
were created and no system plugin/application directory was touched.

After both first full suites and both one-time corpora had passed, final lifecycle
review identified one GUI-only edge: opening Welcome had to release a held
virtual note before the overlay blocked the keyboard. The fix changes only the
keyboard panel, editor callback, focused test and documentation; Processor,
Synthesiser, Voice, effects and every audio/DSP source remained untouched. Both
complete builds, both 40-test suites, versions and native smokes were therefore
rerun and passed on the final source. In accordance with the binding corpus rule,
the 696-case runs were not repeated because there was no later production audio
or DSP change. Their plan hashes identify the pre-cleanup PresetAudit link; the
later relink changed the executable hash, while the final full `tone_voicing`,
`audio_equivalence`, `sample_accuracy`, DSP, preset and artifact suites prove the
unchanged production audio behavior. Exactly two corpus runs were performed in
total: one Debug and one Release.

One in-sandbox iteration build encountered the known MSBuild FileTracker
`E_ACCESSDENIED`; it was rerun in the authorized confirmed developer environment.
Earlier incremental linking also encountered transient `.ilk` file locks while
targets were being refreshed. Neither was a source compiler diagnostic. The
fresh and final post-cleanup Debug and Release build logs contain zero
warning/error diagnostics.
No new performance work was inferred from the passing CTests: the historical
D96/64 deadline gate remains OPEN/deferred exactly as authorized.

Final Git policy checks require `build/` and `Artifacts/` to remain ignored and
unstaged, `JUCE/` to remain unchanged, protected untracked files to remain
unstaged, and explicit milestone staging only. The V0.12.75 commit containing
this report cannot embed its own hash; its exact hash and the post-commit status
are recorded in the final handoff.

## Manual acceptance — OPEN

Every item below remains OPEN until the user performs and confirms it:

- Standalone opens correctly and reopens correctly.
- The keyboard is visible at the bottom and nothing is clipped.
- White and black keys produce correct Mouse Note-On/Note-Off.
- Dragging across keys is musically sensible.
- Chords and rapid repeated notes work without stuck notes.
- `Oct -` and `Oct +` work and the lowest/highest views stay in MIDI range.
- External MIDI works alone and simultaneously with virtual MIDI.
- Preset changes while playing are safe.
- Closing the window while a virtual note is held is safe.
- Audio-device stop/start is safe.
- Keyboard styling fits DeepPluck and focus/text-entry behavior is unobtrusive.
- VST3 has no keyboard, retains the exact previous layout and accepts external MIDI.
- Cubase loads the unchanged VST3 identity; automation, recall, realtime and
  offline bounce remain correct.
- Manual listening confirms sound neutrality when the keyboard is unused.

Computer-key/QWERTZ operation is not implemented and is not an acceptance item.
