docs(envelope): add Trigger frames<->fraction seam note + zero-delta guard on fade nodes

src/vst/envelope_overlay.h

@@ -67,9 +67,26 @@ enum class EnvNode {
 // zone's stored AdsrSeconds / TriggerParams. Engine-free by design (no sampler_core include).
 //
 // Gate fields (SECONDS, wall-clock):   attack / hold / decay / release; sustain is a LEVEL 0..1.
+//   These map 1-to-1 with the stored AdsrSeconds fields — no conversion required.
+//
 // Trigger fields (FRACTIONS of play):  fadeIn / fadeOut as a fraction of the played span;
 //                                       lengthFraction is the played span as a fraction of the
 //                                       post-start sample length (matching TriggerParams).
+//
+// TRIGGER SEAM — CONVERSION REQUIRED ON BOTH PATHS (Wave 2 shell author, read this):
+//   TriggerParams (sampler_core.h) stores Trigger fades as SOURCE FRAMES:
+//     fadeInFrames  (int64_t) — 0->1 ramp length in source frames
+//     fadeOutFrames (int64_t) — 1->0 ramp length in source frames
+//   AmpEnvelope stores them as FRACTIONS of the played span:
+//     fadeInFraction  = fadeInFrames  / playLengthFrames
+//     fadeOutFraction = fadeOutFrames / playLengthFrames
+//   where playLengthFrames = round(lengthFraction * (frameCount - startFrame)).
+//   This is a NON-TRIVIAL derived view — NOT a direct field copy. The shell owes a
+//   converter on BOTH directions:
+//     PACK   (draw):   frames -> fraction  (TriggerParams -> AmpEnvelope, needs frameCount + rate)
+//     UNPACK (commit): fraction -> frames  (AmpEnvelope  -> TriggerParams, same inputs)
+//   lengthFraction maps 1-to-1 with TriggerParams::lengthFraction and needs no conversion.
+//
 // Unused fields for the active mode are ignored.
 struct AmpEnvelope {
     EnvMode mode = EnvMode::Gate;
@@ -82,9 +99,12 @@ struct AmpEnvelope {
     double releaseSeconds = 0.060;
 
     // Trigger, fractions of the play span (fadeIn/fadeOut) and of the post-start length.
-    double lengthFraction = 1.0;   // (0,1] of the post-start span that plays
-    double fadeInFraction  = 0.0;  // 0->1 ramp as a fraction of the played span
-    double fadeOutFraction = 0.0;  // 1->0 ramp as a fraction of the played span
+    // NOTE: fadeInFraction/fadeOutFraction are DERIVED from TriggerParams::fadeInFrames/
+    // fadeOutFrames — see the TRIGGER SEAM note above. A converter is owed on both the
+    // pack (draw) and unpack (commit) paths; these fields are NOT a direct TriggerParams copy.
+    double lengthFraction  = 1.0;   // (0,1] of the post-start span that plays (1-to-1 with TriggerParams)
+    double fadeInFraction  = 0.0;   // 0->1 ramp as a fraction of the played span (DERIVED — see above)
+    double fadeOutFraction = 0.0;   // 1->0 ramp as a fraction of the played span (DERIVED — see above)
 };
 
 // One polyline vertex: a pixel point plus which node it is. The shell draws a line through the