# DeepPluck V0.12.5 Welcome / About / Final UX Polish — Implementation Report

Date: 2026-09-04

## Repository and protection boundary

- Start branch: `master`
- Start HEAD: `4b4d0e5867799f66b9e3db95eb70cad195b57d33`
- End HEAD: `4b4d0e5867799f66b9e3db95eb70cad195b57d33`
- Actual baseline: uncommitted V0.11.5/V0.12.0 working copy at project version
  0.12.0, with 16 modified tracked files and 54 top-level untracked entries.
- Start and protected-input inventory:
  `Artifacts/V0.12.5/20260904T172424Z/start-audit.md`
- End status and protected-input verification:
  `Artifacts/V0.12.5/20260904T172424Z/end-audit.md`
- The end status contains 18 modified tracked files and 58 top-level untracked
  entries; the increase consists of the authorized V0.12.5 GUI/test/report work,
  while the pre-existing working-copy baseline remains intact. The index was
  empty at start and remains empty. No reset, checkout, clean,
  system installation, evidence overwrite, or push was performed.
- The pre-existing untracked master prompts, screenshots, Cubase project, Factory
  sources, tooling, and earlier evidence remain protected and unstaged. All 17
  explicit path/size/SHA-256 rows in the start protection table were rechecked at
  the end: 0 missing or changed.
- `JUCE/` is unchanged. `COPY_PLUGIN_AFTER_BUILD` remains `FALSE`; only the
  existing project-local `Artifacts/Debug` and `Artifacts/Release` copies are
  produced.

The working-copy ownership boundary cannot be represented honestly as a new
V0.12.5-only commit because `CMakeLists.txt`, README/architecture, the GUI source,
and the main test executable already contained uncommitted V0.11.5/V0.12.0 work.
No commit was created and no hash is invented. A baseline commit sequence requires
explicit user authorization.

## Implemented UX

The existing single `WelcomeOverlayComponent` was finalized; no second onboarding
system, animation, modal window, fifth tab, GUI scale control, or resizable editor
was added. Its visible content is:

```text
Just A Lil' PluckSynth
A compact pluck synthesizer for deep, emotional house sounds.

Start with a Factory Preset
Shape the sound on MAIN
Add movement and space with MODULATION and FX

Hover over controls for help
Start Playing
Don't show this again

prompted & directed by Tonetrax
coded by ChatGPT/Codex
www.tonetrax-music.de
```

`Start Playing` closes the overlay and marks the first run seen. With the option
selected, it also disables future automatic display. Without the option, Welcome
remains enabled but does not repeat until re-armed. The primary action and option
have explicit logical focus order and the project LookAndFeel draws a visible Teal
focus outline for buttons/toggles.

SETTINGS retains two sibling panels. PREFERENCES contains only:

1. Hover Help
2. Welcome Screen
3. Show Welcome Now

Hover Help changes the existing tooltip window immediately. Welcome Screen On
re-arms the next editor; Off disables automatic display. Show Welcome Now re-arms
the process-shared state but opens only the requesting editor's overlay.

ABOUT is now structured into independently testable labels/components:

```text
Just A Lil' PluckSynth
Version <JucePlugin_VersionString>
Formats: VST3 / Standalone
Platform: 64-bit Windows
Built with JUCE

A focused pluck synthesizer designed for deep, warm and emotional electronic music.

prompted & directed by Tonetrax
coded by ChatGPT/Codex
www.tonetrax-music.de
```

The website is a `HyperlinkButton` with visible text
`www.tonetrax-music.de` and exact target
`https://www.tonetrax-music.de`. It can launch only after a user click. Tests
inspect but never click it; `JUCE_WEB_BROWSER=0` remains, with no embedded browser,
prefetch, telemetry, tracking, or background network action.

Representative workflow controls now have short nonempty help for preset choice,
save actions, Random/Undo/Amount, module locks, FX rack actions, navigation,
Settings, Welcome and the website. Decorative graphics and meters remain without
tooltips.

## Preference and compatibility contract

`DeepPluckGuiPreferences` remains the only preference owner and keeps the regular
path `User Application Data/ToneTrax/DeepPluck/GUI.properties`. Its existing
process-shared owner, lock, process-wide file serialization, `TemporaryFile`
replacement, injectable test backend, and safe defaults were retained. Missing,
corrupt, and wrong-root XML yield Hover Help On, Welcome enabled, and unseen.

Tests cover two simultaneous editors sharing one owner, rapid persisted changes,
new-instance behavior after first run/disable/re-arm, and the rule that Show
Welcome Now opens only the requested existing overlay. Test files live only below
`build/TestData`; the real user preference path is not touched.

No host parameter, parameter index/ID/name/type/version hint/range/default/text,
APVTS state, preset schema, Factory sound, processor behavior, DSP source, plugin
identity, bus contract, class ID, or vendor metadata was changed. The host-visible
name remains `DeepPluck`; visible branding is `Just A Lil' PluckSynth`. The active
Factory remains 116/116 plus internal `factory:0..3` Legacy compatibility.

## Version, tests, and evidence tooling

`project(DeepPluck VERSION 0.12.5)` is the sole current version source. Source GUI
code contains no literal `0.12.5`; ABOUT and footer use
`JucePlugin_VersionString`. All seven versioned CMake targets inherit
`PROJECT_VERSION`.

Only the two required final-evidence wrappers were generalized. Normalized output
must remain below repository `Artifacts/V0.12.0` or `Artifacts/V0.12.5`; external
siblings are rejected before creation. `DeepPluck.evidence_paths` is the new 39th
CTest and includes positive compatibility and negative escape cases.

`Tests/SmokeVST3Factory.ps1` formalizes the preserved V0.12.0 method with absolute
binary/evidence parameters, native x64 `LoadLibrary`, `InitDll`,
`GetPluginFactory`, exactly two classes, factory release, `ExitDll`, `FreeLibrary`,
and a non-overwritable JSON receipt. It instantiates no processor, device, or GUI.

The GUI suite adds exact visible text and dynamic-version assertions, HTTPS target
inspection without launch, positive/non-overlapping bounds, focus order, Welcome
lifecycle, preference fallback/persistence, multi-instance behavior, immediate
tooltip suppression/restoration, 62 bindings, and APVTS/audio neutrality. It
retains MAIN/MODULATION/FX/SETTINGS snapshots and adds `Welcome.png`.

During iteration, the selected Debug matrix passed 10/10: evidence paths, Factory
factory/integration/final content, parameters, GUI, effects integration,
randomization, preset files, and preset integration. A first GUI test execution
ended with Windows stack-overflow status because three additional full processor/
editor fixtures were local Debug-stack objects. The test fixtures were moved to
bounded heap-owned `unique_ptr`s; product code was not relaxed. The corrected GUI
test and complete selected matrix pass.

The first native VST3-smoke invocation stopped before loading a module because
the new script used a .NET API absent from Windows PowerShell 5.1. No receipt was
created. Its absolute-path predicate was replaced by an equivalent PowerShell-
5.1-compatible rooted-path check; both actual Debug/Release native probes then
passed. This was a test-tool-only correction before either final 696 run and did
not change source, CMake, Factory content, binaries, or audio.

## Final automated gate

Evidence root: `Artifacts/V0.12.5/20260904T172424Z/`

| Gate | Result | Evidence |
|---|---|---|
| Fresh VS2026 x64 configure | PASS; exit 0; 4.17 s | `final/configure-Debug-20260904T154348923Z-*` |
| Debug full build | PASS; exit 0; 119.71 s; 0 warning/error diagnostics | `final/build-Debug-20260904T154404121Z-*` |
| Release full build | PASS; exit 0; 213.59 s; 0 warning/error diagnostics | `final/build-Release-20260904T154624190Z-*` |
| Debug 39 CTests | PASS 39/39; 1427.59 s | `final/test-Debug-20260904T155025080Z-*` |
| Release 39 CTests | PASS 39/39; 195.64 s | `final/test-Release-20260904T161448549Z-*` |
| Debug versions/artifacts/local copies | PASS; version 0.12.5, byte-identical, negative probes pass | `final/versions-Debug-20260904T161844341Z-*` |
| Release versions/artifacts/local copies | PASS; version 0.12.5, byte-identical, negative probes pass | `final/versions-Release-20260904T161844414Z-*` |
| Debug Standalone smoke | PASS; native window, normal close, exit 0, no remaining owned process | `verification/standalone-debug.json` |
| Release Standalone smoke | PASS; native window, normal close, exit 0, no remaining owned process | `verification/standalone-release.json` |
| Debug native VST3 factory smoke | PASS; x64, version 0.12.5, exactly two classes, clean unload | `verification/vst3-debug.json` |
| Release native VST3 factory smoke | PASS; x64, version 0.12.5, exactly two classes, clean unload | `verification/vst3-release.json` |
| Debug Factory audio corpus | PASS 696/696; 0 failures; max peak 0.583521; all finite/tails quiet | `audio-debug/summary.json` |
| Release Factory audio corpus | PASS 696/696; 0 failures; max peak 0.583521; all finite/tails quiet | `audio-release/summary.json` |

The 696 corpus is `RunFactoryFinalContentAudit.ps1`, not a CTest: 116 approved
presets x three sample rates x dry/wet, Buffer 128, full scene. Exactly one final
invocation was made per configuration. Both produced 696 unique expected cases,
696 passes, no failures, no nonfinite values, no tail failures, and a peak below
the 0.95 gate. No additional full-corpus run was needed.

Final summary hashes:

- Debug `audio-debug/summary.json`:
  `3228ef4ce92780ef413377c5712968aaf6d2026c1a2d375914bbf631315fe8a4`
- Release `audio-release/summary.json`:
  `99040d39650709a704dddec9ebec17e40483ce507529af690662e8f44b49d046`
- Both use approved catalog SHA-256
  `6bdf7dcdaa2423b6aed6691c0bdf4c0b9a408280905ec9d7b86f5d03c93aa8e2`.

Artifact and local-copy SHA-256 values are identical:

| Artifact | SHA-256 |
|---|---|
| Debug Standalone | `43cd4fada1f95ed5a6bdafe330ce3588f48bc6345621c2402bc7b13e86999551` |
| Debug VST3 binary | `6a1ca3f6fb415f9040a5db3d7497911c63061e4fa6a6c5e696efa8b997f54925` |
| Debug VST3 moduleinfo | `07e8b2a50668e6c5cd72c7738d41ed34cb3169d07152385f54f09973178edc89` |
| Release Standalone | `b25de26cbc63d524eb7d4a01eddca3842f19271d491787184adc6b14f3502804` |
| Release VST3 binary | `8aca37e6e3e8f2722b521e55914c27ebf04760a44588338dba50c9955f960b29` |
| Release VST3 moduleinfo | `07e8b2a50668e6c5cd72c7738d41ed34cb3169d07152385f54f09973178edc89` |

Both Standalone and VST3 PE resources report `0.12.5`; the artifact-version gate
also verifies both VST3 class versions, all seven versioned targets, native x64,
frozen identity, bundle membership, local copies, ABOUT/footer version flow and
synthetic missing/stale/wrong-class rejection.

The generated final `Welcome.png` and `Settings.png` snapshots were inspected at
1536 x 900: the exact three-line Welcome credits, structured ABOUT content,
actions, labels and panel bounds are visible without overlap or clipping. This is
build-local snapshot QA, not a claim for real host/DPI acceptance.

The historical V0.11.5 D96/64 deadline finding remains OPEN/deferred and is not
relabelled as a V0.12.5 failure or technical pass.

The automatable V0.12.5 Definition of Done is complete. Exact 62-parameter and
62-attachment tests, host-state/audio neutrality, audio equivalence, the approved
116-preset catalog and compatibility workflows all pass. V0.12.5 changed no DSP,
processor, parameter, preset, Factory/User/Pack, state, Random/Lock/Undo, plugin
identity, bus, or JUCE source. Build/Artifacts remain ignored and unstaged;
`COPY_PLUGIN_AFTER_BUILD` is `FALSE`, and there was no system install or push.

## Manual acceptance still OPEN

- Visual inspection in real VST3 and Standalone at Windows 100%, 125%, and 150%.
- Keyboard Tab/focus behavior in real native windows.
- Explicit website click/default-browser confirmation.
- Cubase scan, exactly 62 automation parameters, old-project/state recall,
  multiple instances, realtime/offline bounce, and host window lifecycle.
- Standalone audio-device/MIDI operation and listening confirmation.

Automated completion is not manual approval. No automatic Cubase, DPI, link,
audio-device, or listening PASS is claimed.
