@svta/cml-cmcd 2.6.1 → 2.8.0

package/dist/index.d.ts

@@ -4,109 +4,109 @@ import { DeepReadonly, ExclusiveRecord, HttpRequest, HttpResponse, ValueOf, Valu
 //#region src/CmcdEventType.d.ts
 
 /**
-* CMCD event type for the 'bc' key (bitrate change).
+* CMCD event type 'bc' (bitrate change).
 *
 * @public
 */
 declare const CMCD_EVENT_BITRATE_CHANGE: "bc";
 /**
-* CMCD event type for the 'ps' key (play state change).
+* CMCD event type 'ps' (play state change).
 *
 * @public
 */
 declare const CMCD_EVENT_PLAY_STATE: "ps";
 /**
-* CMCD event type for the 'pr' key (playback rate change).
+* CMCD event type 'pr' (playback rate change).
 *
 * @public
 */
 declare const CMCD_EVENT_PLAYBACK_RATE: "pr";
 /**
-* CMCD event type for the 'e' key (error).
+* CMCD event type 'e' (error).
 *
 * @public
 */
 declare const CMCD_EVENT_ERROR: "e";
 /**
-* CMCD event type for the 't' key (time interval).
+* CMCD event type 't' (time interval).
 *
 * @public
 */
 declare const CMCD_EVENT_TIME_INTERVAL: "t";
 /**
-* CMCD event type for the 'c' key (content ID).
+* CMCD event type 'c' (content ID).
 *
 * @public
 */
 declare const CMCD_EVENT_CONTENT_ID: "c";
 /**
-* CMCD event type for the 'b' key (backgrounded mode).
+* CMCD event type 'b' (backgrounded mode).
 *
 * @public
 */
 declare const CMCD_EVENT_BACKGROUNDED_MODE: "b";
 /**
-* CMCD event type for the 'm' key (mute).
+* CMCD event type 'm' (mute).
 *
 * @public
 */
 declare const CMCD_EVENT_MUTE: "m";
 /**
-* CMCD event type for the 'um' key (unmute).
+* CMCD event type 'um' (unmute).
 *
 * @public
 */
 declare const CMCD_EVENT_UNMUTE: "um";
 /**
-* CMCD event type for the 'pe' key (player expand).
+* CMCD event type 'pe' (player expand).
 *
 * @public
 */
 declare const CMCD_EVENT_PLAYER_EXPAND: "pe";
 /**
-* CMCD event type for the 'pc' key (player collapse).
+* CMCD event type 'pc' (player collapse).
 *
 * @public
 */
 declare const CMCD_EVENT_PLAYER_COLLAPSE: "pc";
 /**
-* CMCD event type for the 'rr' key (response received).
+* CMCD event type 'rr' (response received).
 *
 * @public
 */
 declare const CMCD_EVENT_RESPONSE_RECEIVED: "rr";
 /**
-* CMCD event type for the 'as' key (ad start).
+* CMCD event type 'as' (ad start).
 *
 * @public
 */
 declare const CMCD_EVENT_AD_START: "as";
 /**
-* CMCD event type for the 'ae' key (ad end).
+* CMCD event type 'ae' (ad end).
 *
 * @public
 */
 declare const CMCD_EVENT_AD_END: "ae";
 /**
-* CMCD event type for the 'abs' key (ad break start).
+* CMCD event type 'abs' (ad break start).
 *
 * @public
 */
 declare const CMCD_EVENT_AD_BREAK_START: "abs";
 /**
-* CMCD event type for the 'abe' key (ad break end).
+* CMCD event type 'abe' (ad break end).
 *
 * @public
 */
 declare const CMCD_EVENT_AD_BREAK_END: "abe";
 /**
-* CMCD event type for the 'sk' key (skip).
+* CMCD event type 'sk' (skip).
 *
 * @public
 */
 declare const CMCD_EVENT_SKIP: "sk";
 /**
-* CMCD event type for the 'ce' key (custom event).
+* CMCD event type 'ce' (custom event).
 *
 * @public
 */
@@ -146,7 +146,7 @@ declare const CmcdEventType: {
   */
   readonly CONTENT_ID: typeof CMCD_EVENT_CONTENT_ID;
   /**
-  * A change in the application's backgrounded state.
+  * A change in the player's backgrounded state.
   */
   readonly BACKGROUNDED_MODE: typeof CMCD_EVENT_BACKGROUNDED_MODE;
   /**
@@ -154,7 +154,7 @@ declare const CmcdEventType: {
   */
   readonly MUTE: typeof CMCD_EVENT_MUTE;
   /**
-  * Player unmuted.
+  * The player was unmuted.
   */
   readonly UNMUTE: typeof CMCD_EVENT_UNMUTE;
   /**
@@ -201,17 +201,17 @@ type CmcdEventType = ValueOf<typeof CmcdEventType>;
 //#endregion
 //#region src/CmcdCustomKey.d.ts
 /**
-* A custom key for CMCD. Custom keys MUST carry a hyphenated prefix
+* A custom key for CMCD. Custom keys MUST have a hyphenated prefix
 * to ensure that there will not be a namespace collision with future
 * revisions to this specification. Clients SHOULD use a reverse-DNS
 * syntax when defining their own prefix.
 *
 * The type requires a lowercase hyphenated string. At runtime a key
-* must also satisfy {@link isCmcdCustomKey} — a lowercase first
-* letter, then characters from `a-z 0-9 . -`, with a hyphen that is
-* neither the first nor the last character — the subset of the CMCD
-* custom-key grammar that survives RFC 8941 key serialization. Keys
-* failing it are dropped during preparation. Lowercase reverse-DNS
+* must also satisfy {@link isCmcdCustomKey}: a lowercase first
+* letter, then characters from `a-z 0-9 . -`. The key needs a hyphen
+* that is neither first nor last. The check restricts the CMCD
+* custom-key grammar to names that RFC 8941 key serialization accepts.
+* Preparation drops keys that fail the check. Lowercase reverse-DNS
 * names satisfy all constraints.
 *
 * @public
@@ -289,7 +289,7 @@ type CmcdObjectTypeList = (number | SfItem<number, ExclusiveRecord<CmcdObjectTyp
 //#endregion
 //#region src/CmcdPlayerState.d.ts
 /**
-* CMCD v2 player states for the 'sta' key.
+* CMCD version 2 player states for the 'sta' key.
 *
 *
 * @enum
@@ -336,7 +336,7 @@ declare const CmcdPlayerState: {
   */
   readonly QUIT: "q";
   /**
-  * Preloading: The player is loading assets ahead of starting in order to provide a fast startup. The expectation is that playback will commence at a future time.
+  * Preloading: The player is loading assets ahead of starting to provide a fast startup. The expectation is that playback will commence at a future time.
   */
   readonly PRELOADING: "d";
 };
@@ -357,11 +357,11 @@ type CmcdPlayerState = ValueOf<typeof CmcdPlayerState>;
 */
 declare const CmcdStreamType: {
   /**
-  *  All segments are available – e.g., VOD
+  * All segments are available, for example VOD
   */
   readonly VOD: "v";
   /**
-  * Segments become available over time – e.g., LIVE
+  * Segments become available over time, for example LIVE
   */
   readonly LIVE: "l";
   /**
@@ -420,17 +420,18 @@ type CmcdStreamingFormat = ValueOf<typeof CmcdStreamingFormat>;
 */
 type CmcdRequest = {
   /**
-  * Custom key names may be used, but they MUST carry a hyphenated prefix to ensure that there will not be a namespace collision
-  * with future revisions to this specification. Clients SHOULD use a reverse-DNS syntax when defining their own prefix.
+  * Custom key names may be used, but they MUST have a hyphenated prefix. The prefix ensures that there is no
+  * namespace collision with future CMCD revisions. Clients SHOULD use a reverse-DNS syntax when defining their own
+  * prefix.
   */
   [index: CmcdCustomKey]: CmcdCustomValue | undefined;
   /**
   * Aggregate encoded bitrate
   *
-  * The aggregate encoded bitrate across a playable combination of tracks. This metric SHOULD NOT be used when the individual bitrates
-  * of the tracks are known. This value SHOULD be derived from a playlist/manifest declaration, or it MAY be estimated by the player.
-  * If the playlist declares both peak and average bitrate values, the peak value MUST be transmitted. This value MUST NOT be sent if
-  * the encoded bitrate is known.
+  * The aggregate encoded bitrate across a playable combination of tracks. This key SHOULD NOT be used when the
+  * individual bitrates of the tracks are known. The player SHOULD derive this value from a playlist/manifest
+  * declaration, or MAY estimate it. If the playlist declares both peak and average bitrate values, the peak value
+  * MUST be transmitted. This value MUST NOT be sent if the encoded bitrate is known.
   *
   * Inner list of integer kbps with token identifiers
   *
@@ -441,7 +442,7 @@ type CmcdRequest = {
   * Backgrounded
   *
   * All players in a session are currently in a state that is not visible to the user due to a user interaction. This key SHOULD only
-  * be sent if it is TRUE. If the visibility state of the player is not known this key SHOULD NOT be reported.
+  * be sent if it is TRUE. If the visibility state of the player is not known, this key SHOULD NOT be reported.
   *
   * Boolean
   *
@@ -461,10 +462,10 @@ type CmcdRequest = {
   /**
   * Encoded bitrate
   *
-  * The encoded bitrate. In request mode, this refers to the encoded bitrate of the requested representation.
-  * In event mode this refers to the encoded bitrate of the currently selected representation.
-  * This SHOULD be derived from playlist/manifest declarations, or it MAY be estimated by the player.
-  * If the playlist declares both peak and average bitrate values, the peak value MUST be transmitted.
+  * The encoded bitrate. In request mode, this value is the encoded bitrate of the requested representation. In event
+  * mode, this value is the encoded bitrate of the currently selected representation. The player SHOULD derive this
+  * value from playlist/manifest declarations, or MAY estimate it. If the playlist declares both peak and average
+  * bitrate values, the peak value MUST be transmitted.
   *
   * Inner list of integer kbps with token identifiers
   *
@@ -474,9 +475,10 @@ type CmcdRequest = {
   /**
   * Buffer starvation
   *
-  * TRUE if the player buffer was starved at some point between the prior report and this report per reporting destination, resulting in
-  * the player entering a rebuffering state or remaining in a rebuffering state. Note that if the player begins requesting data from a
-  * new CDN, then this key might initially report buffering caused by the prior CDN. This key SHOULD NOT be reported if it is FALSE.
+  * TRUE if the player buffer was starved at some point between the prior report and this report, per reporting
+  * destination. Starvation results in the player entering a rebuffering state or remaining in a rebuffering state.
+  * If the player begins requesting data from a new CDN, this key might initially report buffering caused by the
+  * prior CDN. This key SHOULD NOT be reported if it is FALSE.
   *
   * Boolean
   *
@@ -498,7 +500,7 @@ type CmcdRequest = {
   * Buffer Starvation Duration
   *
   * A list of durations of each buffer starvation period reported once the rebuffering has completed. This value MUST only be reported
-  * once per reporting mode and report destination. Token identifier MAY be omitted if the cause of the rebuffering is unknown.
+  * once per reporting mode and reporting destination. Token identifier MAY be omitted if the cause of the rebuffering is unknown.
   *
   * Inner list of integer milliseconds with optional token identifiers
   *
@@ -529,8 +531,8 @@ type CmcdRequest = {
   /**
   * Content ID
   *
-  * A unique string identifying the current content. The maximum length is 128 characters. This value is consistent across multiple different
-  * sessions and devices and is defined and updated at the discretion of the service provider.
+  * A unique string identifying the current content. The maximum length is 128 characters. This value is consistent
+  * across different sessions and devices. The service provider defines and updates this value at its discretion.
   *
   * String
   *
@@ -540,8 +542,9 @@ type CmcdRequest = {
   /**
   * Content Signature
   *
-  * A string representing a signature of the content being played. This field SHOULD vary with content ID and be bound by some mechanism
-  * to the content. For example, this field may be used to transmit the C2PA signature associated with the content being viewed.
+  * A string representing a signature of the content being played. This key SHOULD vary with content ID and be bound
+  * by some mechanism to the content. For example, this key may transmit the C2PA signature associated with the
+  * content being viewed.
   *
   * String
   *
@@ -552,7 +555,7 @@ type CmcdRequest = {
   * Object duration
   *
   * The playback duration in milliseconds of the object being requested. If a partial segment is being requested,
-  * then this value MUST indicate the playback duration of that part and not that of its parent segment.
+  * this value MUST indicate the playback duration of that part and not that of its parent segment.
   * This value can be an approximation of the estimated duration if the explicit value is not known.
   * This value MUST NOT be sent for objects which do not have an object type of 'a', 'v', 'av', 'tt', 'c', or 'o'.
   *
@@ -564,9 +567,10 @@ type CmcdRequest = {
   /**
   * Dropped Frames Absolute
   *
-  * An absolute count of dropped frames since session initiation. This key SHOULD only be sent for content types of 'v', 'av' or 'o'.
-  * Note that this value will be driven by the content being rendered rather than the content being retrieved, therefore it is
-  * beneficial if accompanied by the playhead time 'pt' key to allow for correct interpretation.
+  * An absolute count of dropped frames since session initiation. This key SHOULD only be sent for content types of
+  * 'v', 'av' or 'o'. This value depends on the content being rendered, not on the content being retrieved.
+  * Therefore, sending the playhead time 'pt' key with this key is beneficial. The 'pt' key allows correct
+  * interpretation of this value.
   *
   * Integer
   *
@@ -576,9 +580,9 @@ type CmcdRequest = {
   /**
   * Deadline
   *
-  * Deadline from the request time until the first sample of this Segment/Object needs to be available in order to not create a buffer underrun
-  * or any other playback problems. This value MUST be rounded to the nearest 100ms. For a playback rate of 1, this may be equivalent to the
-  * player's remaining buffer length.
+  * Deadline from the request time until the first sample of this Segment/Object needs to be available. Availability
+  * by the deadline avoids a buffer underrun or any other playback problems. This value MUST be rounded to the
+  * nearest 100ms. For a playback rate of 1, this value may be equivalent to the player's remaining buffer length.
   *
   * Integer milliseconds
   *
@@ -588,7 +592,7 @@ type CmcdRequest = {
   /**
   * Player Error Code
   *
-  * A string defining an error code produced by the player. The namespace and formatting of this error code is left to the application.
+  * A string defining an error code produced by the player. The namespace and formatting of this error code are left to the application.
   *
   * Even if only one error code is being specified, the list notation MUST still be used.
   *
@@ -600,10 +604,10 @@ type CmcdRequest = {
   /**
   * Lowest aggregated encoded bitrate
   *
-  * The lowest aggregated bitrate rendition in the manifest or playlist. This SHOULD be derived from playlist/manifest declarations,
-  * or it MAY be estimated by the player. If the playlist declares both peak and average bitrate values, the peak value MUST be
-  * transmitted. The aggregate encoded bitrate is of the complete media object including all object types. This value MUST NOT be
-  * sent if the lowest encoded bitrate is known.
+  * The lowest aggregated bitrate rendition in the manifest or playlist. The player SHOULD derive this value from
+  * playlist/manifest declarations, or MAY estimate it. If the playlist declares both peak and average bitrate
+  * values, the peak value MUST be transmitted. The aggregate encoded bitrate is that of the complete media object,
+  * including all object types. This value MUST NOT be sent if the lowest encoded bitrate is known.
   *
   * Inner list of integer kbps with token identifiers
   *
@@ -613,10 +617,11 @@ type CmcdRequest = {
   /**
   * Lowest encoded bitrate
   *
-  * The lowest bitrate rendition in the manifest or playlist. This SHOULD be derived from playlist/manifest declarations, or it MAY be
-  * estimated by the player. If the playlist declares both peak and average bitrate values, the peak value MUST be transmitted. This
-  * lowest bitrate MUST apply to the object type being requested. Requests for video objects MUST specify the lowest video bitrate and
-  * requests for audio objects MUST specify the lowest audio bitrate.
+  * The lowest bitrate rendition in the manifest or playlist. The player SHOULD derive this value from
+  * playlist/manifest declarations, or MAY estimate it. If the playlist declares both peak and average bitrate
+  * values, the peak value MUST be transmitted. This lowest bitrate MUST apply to the object type being requested.
+  * Requests for video objects MUST specify the lowest video bitrate. Requests for audio objects MUST specify the
+  * lowest audio bitrate.
   *
   * Inner list of integer kbps with token identifiers
   *
@@ -626,8 +631,8 @@ type CmcdRequest = {
   /**
   * Live stream latency
   *
-  * The time delta between when a given media timestamp was made available at the origin and when it was rendered by the player. The
-  * accuracy of this estimate is dependent on synchronization between the packager and the player clocks.
+  * The time delta between when a given media timestamp became available at the origin and when the player rendered
+  * it. The accuracy of this estimate depends on synchronization between the packager and the player clocks.
   *
   * Integer milliseconds
   *
@@ -637,11 +642,12 @@ type CmcdRequest = {
   /**
   * Media Start Delay
   *
-  * Measures the initial delay in wall-clock time from when a player is instructed to play media for a given session to when any media
-  * begins playback, whether it be primary content or interstitial content. This value SHOULD be the time difference between the
-  * "starting" and "playing" states.
+  * The initial delay, in wall-clock time, from when the player is instructed to play media for a given session until
+  * any media begins playback. The media can be primary content or interstitial content. This value SHOULD be the
+  * time difference between the "starting" and "playing" states.
   *
-  * This key MUST only be sent once per Session ID and MUST be sent for each reporting mode which is active within the player.
+  * This key MUST only be sent once per Session ID. This key MUST be sent for each reporting mode active within the
+  * player.
   *
   * Integer milliseconds
   *
@@ -651,14 +657,15 @@ type CmcdRequest = {
   /**
   * Measured throughput
   *
-  * The throughput between player and server, as measured by the player. Throughput MUST be rounded to the nearest 100 kbps. This value, however
-  * derived, SHOULD be the value that the player is using to make its next Adaptive Bitrate switching decision. If the player is requesting
-  * different object types from different providers then it SHOULD take care to match the throughput measured against that provider with each
-  * object type request. It is acceptable to report aggregate information if objects of the same type are requested from different providers.
-  * If the player has multiple concurrent connections to the provider, then the intent is that this value communicates the aggregate throughput
-  * the player sees across all those connections. If this key is sent on an interval report, the value transmitted should be the last throughput
-  * estimate made by the player prior to making the report. There is no requirement for the player to calculate the average measured throughput
-  * since the prior interval report.
+  * The throughput between player and server, as measured by the player. Throughput MUST be rounded to the nearest
+  * 100 kbps. This value, however derived, SHOULD be the value that the player uses for its next Adaptive Bitrate
+  * switching decision. If the player requests different object types from different providers, it SHOULD match each
+  * object type request with the throughput measured against that provider. Reporting aggregate information is
+  * acceptable if objects of the same type are requested from different providers. If the player has multiple
+  * concurrent connections to the provider, this value is intended to communicate the player's aggregate throughput
+  * across all those connections. If this key is sent on an interval report, the value should be the last throughput
+  * estimate that the player made before the report. The player is not required to calculate the average measured
+  * throughput since the prior interval report.
   *
   * Inner list of integer kbps with token identifiers
   *
@@ -668,24 +675,25 @@ type CmcdRequest = {
   /**
   * Next object request
   *
-  * The relative path, as defined by RFC 3986, to one or more objects which can reasonably be expected to be requested by the player making
-  * the current request. Each object SHOULD be fetched in its entirety unless there is a range associated with the future request. Even if
-  * only one object is being specified, the list notation MUST still be used. If there is a range associated with the future request, then
-  * the range is communicated as the parameter 'r' with a String value. The formatting of the String value is similar to the HTTP Range
-  * header, except that the unit MUST be 'byte', the 'Range:' prefix is NOT permitted, specifying multiple ranges is NOT allowed and the
-  * only valid combinations are:
+  * The relative path, as defined by RFC 3986, to one or more objects. The player making the current request can
+  * reasonably be expected to request these objects. Each object SHOULD be fetched in its entirety unless the future
+  * request has an associated range. Even if only one object is being specified, the list notation MUST still be
+  * used. If the future request has a range, the range is communicated as the parameter 'r' with a String value. The
+  * String value has a format similar to the HTTP Range header, with these exceptions. The unit MUST be 'byte'. The
+  * 'Range:' prefix is NOT permitted. Multiple ranges are NOT allowed. The only valid combinations are:
   *
   * - `"<range-start>-"`
   * - `"<range-start>-<range-end>"`
   * - `"-<suffix-length>"`
   *
-  * The player SHOULD NOT depend upon any pre-fetch action being taken - it is merely a request for such a pre-fetch to take place.
+  * The player SHOULD NOT depend upon any pre-fetch action being taken. The key is only a request for such a
+  * pre-fetch.
   *
   * Inner list of strings
   *
   * @remarks
-  * Values may be provided as absolute URLs for convenience; when {@link CmcdEncodeOptions.baseUrl} is set,
-  * same-origin URLs are converted to paths relative to that base. Already-relative values are emitted unchanged.
+  * Values may be provided as absolute URLs for convenience. If {@link CmcdEncodeOptions.baseUrl} is set, same-origin
+  * URLs are converted to paths relative to that base. Already-relative values are emitted unchanged.
   *
   * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#next-object-request | CTA-5004-B Next Object Request}
   */
@@ -716,7 +724,7 @@ type CmcdRequest = {
   * - `k` = cryptographic key, license or certificate.
   * - `o` = other
   *
-  * If the object type being requested is unknown, then this key MUST NOT be used.
+  * If the object type being requested is unknown, this key MUST NOT be used.
   *
   * This key is also used as a token parameter for other keys.
   *
@@ -738,7 +746,7 @@ type CmcdRequest = {
   /**
   * Playback rate
   *
-  * 1.0 if real-time, 2.0 if double speed, 0 if not playing. SHOULD only be sent if not equal to 1.0.
+  * 1.0 if real-time, 2.0 if double speed, 0 if not playing. This value SHOULD only be sent if not equal to 1.0.
   *
   * Decimal
   *
@@ -785,10 +793,10 @@ type CmcdRequest = {
   /**
   * Session ID
   *
-  * A GUID identifying the current playback session. A playback session typically consists of the playback of a single media asset along
-  * with accompanying content such as advertisements. This session may comprise the playback of primary content combined with interstitial
-  * content. This session is being played on a single device. The maximum length is 64 characters. It is RECOMMENDED to conform to the
-  * UUID specification.
+  * A GUID identifying the current playback session. A playback session typically consists of the playback of a
+  * single media asset with accompanying content such as advertisements. This session may comprise the playback of
+  * primary content combined with interstitial content. This session is being played on a single device. The maximum
+  * length is 64 characters. Conformance to the UUID specification is RECOMMENDED.
   *
   * String
   *
@@ -798,8 +806,9 @@ type CmcdRequest = {
   /**
   * Sequence Number
   *
-  * A monotonically increasing integer to identify the sequence of a CMCD report to a target within a session. This MUST be reset to
-  * zero on the start of a new session-id. Sequence numbers increase independently per each combination of mode and target.
+  * A monotonically increasing integer to identify the sequence of a CMCD report to a target within a session. This
+  * value MUST be reset to zero on the start of a new session-id. Sequence numbers increase independently for each
+  * combination of mode and target.
   *
   * Integer
   *
@@ -809,8 +818,8 @@ type CmcdRequest = {
   /**
   * Stream type
   *
-  * - `v` = all segments are available - e.g., VOD
-  * - `l` = segments become available over time - e.g., LIVE
+  * - `v` = all segments are available, for example VOD
+  * - `l` = segments become available over time, for example LIVE
   * - `ll` = low latency LIVE
   *
   * Token
@@ -831,7 +840,7 @@ type CmcdRequest = {
   * - `e` - ended: Rendering has ended due to completion of the media asset playback.
   * - `f` - fatal error: Rendering has ended due to an irrecoverable error.
   * - `q` - quit: User initiated end of playback before media asset completion.
-  * - `d` - preloading: the player is loading, or has loaded, assets ahead of starting in order to provide a fast startup. The expectation is that playback will commence at a future time.
+  * - `d` - preloading: the player is loading, or has loaded, assets ahead of starting to provide a fast startup. The expectation is that playback will commence at a future time.
   *
   * Token - one of [s,p,k,r,a,e,f,q,d]
   *
@@ -841,8 +850,9 @@ type CmcdRequest = {
   /**
   * Startup
   *
-  * Key is included without a value if the object is needed urgently due to startup, seeking or recovery after a buffer-empty event. The player
-  * reports this key as true until its buffer first reaches the target buffer for stable playback.
+  * The key is included without a value if the object is needed urgently due to startup, seeking or recovery after a
+  * buffer-empty event. The player reports this key as true until its buffer first reaches the target buffer for
+  * stable playback.
   *
   * Boolean
   *
@@ -852,10 +862,10 @@ type CmcdRequest = {
   /**
   * Top aggregated encoded bitrate
   *
-  * The highest aggregated bitrate rendition in the manifest or playlist. This SHOULD be derived from playlist/manifest declarations,
-  * or it MAY be estimated by the player. If the playlist declares both peak and average bitrate values, the peak value MUST be
-  * transmitted. The aggregate encoded bitrate is of the complete media object including all object types. This value MUST NOT be
-  * sent if the top encoded bitrate is known.
+  * The highest aggregated bitrate rendition in the manifest or playlist. The player SHOULD derive this value from
+  * playlist/manifest declarations, or MAY estimate it. If the playlist declares both peak and average bitrate
+  * values, the peak value MUST be transmitted. The aggregate encoded bitrate is that of the complete media object,
+  * including all object types. This value MUST NOT be sent if the top encoded bitrate is known.
   *
   * Inner list of integer kbps with token identifiers
   *
@@ -865,10 +875,11 @@ type CmcdRequest = {
   /**
   * Top encoded bitrate
   *
-  * The highest bitrate rendition in the manifest or playlist. This SHOULD be derived from playlist/manifest declarations,
-  * or it MAY be estimated by the player. If the playlist declares both peak and average bitrate values, the peak value
-  * MUST be transmitted. This top bitrate MUST apply to the object type being requested. Requests for video objects MUST
-  * specify the top video bitrate and requests for audio objects MUST specify the top audio bitrate.
+  * The highest bitrate rendition in the manifest or playlist. The player SHOULD derive this value from
+  * playlist/manifest declarations, or MAY estimate it. If the playlist declares both peak and average bitrate
+  * values, the peak value MUST be transmitted. This top bitrate MUST apply to the object type being requested.
+  * Requests for video objects MUST specify the top video bitrate. Requests for audio objects MUST specify the top
+  * audio bitrate.
   *
   * Inner list of integer kbps with token identifiers
   *
@@ -889,17 +900,17 @@ type CmcdRequest = {
   /**
   * Top playable bitrate
   *
-  * The highest bitrate rendition that the player is currently capable of playing for reasons other than bandwidth limitations. This
-  * key captures the cases in which, for example, screen resolution, DRM, or performance constraints limit the player's topmost choice
-  * of bitrate. These constraints are intentionally obfuscated for privacy reasons.
+  * The highest bitrate rendition that the player is currently capable of playing for reasons other than bandwidth
+  * limitations. This key applies to cases in which, for example, screen resolution, DRM, or performance constraints
+  * limit the player's topmost choice of bitrate. These constraints are intentionally obfuscated for privacy reasons.
   *
-  * This key can increase the fingerprinting surface exposed by CMCD transmission and SHOULD NOT be transmitted in a default player
-  * configuration.
+  * This key can increase the fingerprinting surface exposed by CMCD transmission. This key SHOULD NOT be transmitted
+  * in a default player configuration.
   *
-  * If the playlist declares both peak and average bitrate values, the peak value MUST be transmitted. This top playable bitrate MUST
-  * apply to the object type being requested. Requests for video objects MUST specify the top playable video bitrate and requests for
-  * audio objects MUST specify the top playable audio bitrate. This value MUST NOT be sent for objects which do not have an object type
-  * of 'a', 'v', 'av' or 'c'.
+  * If the playlist declares both peak and average bitrate values, the peak value MUST be transmitted. This top
+  * playable bitrate MUST apply to the object type being requested. Requests for video objects MUST specify the top
+  * playable video bitrate. Requests for audio objects MUST specify the top playable audio bitrate. This value MUST
+  * NOT be sent for objects which do not have an object type of 'a', 'v', 'av' or 'c'.
   *
   * Inner list of integer kbps with token identifiers
   *
@@ -909,9 +920,9 @@ type CmcdRequest = {
   /**
   * Version
   *
-  * The version of this specification used for interpreting the defined key names and values. If this key is omitted, the player and server
-  * MUST interpret the values as being defined by version 1. Player SHOULD omit this field if the version is 1 and MUST include this field
-  * if the version is not 1.
+  * The CMCD version used to interpret the defined key names and values. If this key is omitted, the player and
+  * server MUST interpret the values as defined by version 1. The player SHOULD omit this key if the version is 1.
+  * The player MUST include this key if the version is not 1.
   *
   * Integer
   *
@@ -935,9 +946,10 @@ type CmcdEvent = CmcdRequest & {
   /**
   * Custom Event Name
   *
-  * Used to define a custom event name. A maximum length of 64 characters is allowed. This key MUST be sent when the event type is
-  * 'ce' (custom event) and MUST NOT be sent when the event type is any other value. A custom key-value pair MAY be used to transfer
-  * a custom value associated with this event. The names chosen SHOULD associate the custom event name with the custom key name.
+  * Defines a custom event name. Maximum length is 64 characters. This key MUST be sent when the event type is 'ce'
+  * (custom event). This key MUST NOT be sent when the event type is any other value. A custom key-value pair MAY be used to
+  * transfer a custom value associated with this event. The names chosen SHOULD associate the custom event name with the custom
+  * key name.
   *
   * String
   *
@@ -947,7 +959,7 @@ type CmcdEvent = CmcdRequest & {
   /**
   * Event
   *
-  * This key MUST only be used in Event mode and MUST be present on all reports. The minimum recommended set of supported events
+  * This key MUST only be used in Event mode. It MUST be present on all reports. The minimum recommended set of supported events
   * are: `ps`, `e`, `t`, and `rr`.
   *
   * - `abs` - ad break start
@@ -988,8 +1000,8 @@ type CmcdEvent = CmcdRequest & {
   /**
   * Timestamp
   *
-  * The timestamp at which the associated event occurred, expressed as the number of milliseconds that have elapsed since the Unix
-  * Epoch (January 1, 1970, at 00:00:00 UTC), excluding leap seconds. When the event is a request for a media object the time SHOULD
+  * The timestamp at which the associated event occurred. The value is the number of milliseconds elapsed since the Unix Epoch
+  * (January 1, 1970, at 00:00:00 UTC), excluding leap seconds. When the event is a request for a media object, the time SHOULD
   * reference when the request was first initiated.
   *
   * This key MUST be included with all Event reports.
@@ -1016,7 +1028,7 @@ type CmcdResponse = CmcdRequest & {
   /**
   * CMSD Dynamic Header
   *
-  * Holds a Base64 encoded copy of the CMSD data received on the CMSD-Dynamic response header. This key MUST only be reported on
+  * A Base64 encoded copy of the CMSD data received on the CMSD-Dynamic response header. This key MUST only be reported on
   * events of type `rr` (response received).
   *
   * String
@@ -1027,7 +1039,7 @@ type CmcdResponse = CmcdRequest & {
   /**
   * CMSD Static Header
   *
-  * Holds a Base64 encoded copy of the CMSD data received on the CMSD-Static response header. This key MUST only be reported on
+  * A Base64 encoded copy of the CMSD data received on the CMSD-Static response header. This key MUST only be reported on
   * events of type `rr` (response received).
   *
   * String
@@ -1038,7 +1050,7 @@ type CmcdResponse = CmcdRequest & {
   /**
   * Response code
   *
-  * The response code received when requesting a media object. In a redirect scenario, this would be the final response code received.
+  * The response code received when requesting a media object. In a redirect scenario, the value is the final response code received.
   * A value of 0 SHOULD be used to indicate that a response was not received.
   *
   * This key MUST only be reported on events of type `rr` (response received).
@@ -1051,7 +1063,7 @@ type CmcdResponse = CmcdRequest & {
   /**
   * SMRT-Data Header
   *
-  * Holds a Base64 encoded copy of the streaming media response tracing data received on the Request Tracing header. This key MUST
+  * A Base64 encoded copy of the streaming media response tracing data received on the Request Tracing header. This key MUST
   * only be reported on events of type `rr` (response received).
   *
   * String
@@ -1115,7 +1127,8 @@ type CmcdResponse = CmcdRequest & {
 * This type is the intersection of {@link CmcdRequest}, {@link CmcdResponse},
 * and {@link CmcdEvent}, combining all keys from all reporting modes.
 *
-* @see {@link https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf|CMCD v1 Spec}
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html | CTA-5004-B CMCD version 2}
+* @see {@link https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf|CMCD version 1}
 *
 * @public
 */
@@ -1198,7 +1211,7 @@ type CmcdFormatterOptions = {
   /**
   * Base URL (typically the manifest or current request URL) used to convert absolute `nor` values
   * into paths relative to this base, per the CMCD specification. Values that are already relative
-  * paths are passed through unchanged. When omitted, `nor` values are emitted as-is.
+  * paths remain unchanged. If omitted, `nor` values are emitted unchanged.
   */
   baseUrl?: string;
 };
@@ -1234,24 +1247,29 @@ type CmcdV1 = {
   * Buffer length
   *
   * The buffer length associated with the media object being requested. This value MUST be rounded to the nearest 100 ms. This key SHOULD only be
-  * sent with an object type of ‘a’, ‘v’ or ‘av’.
+  * sent with an object type of 'a', 'v' or 'av'.
   *
   * Integer milliseconds
   */
   bl?: number;
   /**
-  * Bitrate
+  * Encoded bitrate
   *
-  * Integer
+  * The encoded bitrate of the audio or video object being requested. The player may not know this value precisely.
+  * However, the player MAY estimate it based upon playlist/manifest declarations. If the playlist declares both peak
+  * and average bitrate values, the peak value should be transmitted.
+  *
+  * Integer kbps
   */
   br?: number;
   /**
-  * Measured mtp CMCD throughput
+  * Measured throughput
   *
-  * The throughput between client and server, as measured by the client and MUST be rounded to the nearest 100 kbps. This value, however derived,
-  * SHOULD be the value that the client is using to make its next Adaptive Bitrate switching decision. If the client is connected to multiple
-  * servers concurrently, it must take care to report only the throughput measured against the receiving server. If the client has multiple concurrent
-  * connections to the server, then the intent is that this value communicates the aggregate throughput the client sees across all those connections.
+  * The throughput between client and server, as measured by the client. Throughput MUST be rounded to the nearest
+  * 100 kbps. This value, however derived, SHOULD be the value that the client uses for its next Adaptive Bitrate
+  * switching decision. If the client is connected to multiple servers concurrently, it must report only the
+  * throughput measured against the receiving server. If the client has multiple concurrent connections to the
+  * server, this value is intended to communicate the client's aggregate throughput across all those connections.
   *
   * Integer kbps
   */
@@ -1259,22 +1277,22 @@ type CmcdV1 = {
   /**
   * Next object request
   *
-  * Relative path of the next object to be requested. This can be used to trigger pre-fetching by the CDN. This MUST be a path relative to the current
-  * request. This string MUST be URLEncoded. The client SHOULD NOT depend upon any pre-fetch action being taken - it is merely a request for such a
-  * pre-fetch to take place.
+  * Relative path of the next object to be requested. The CDN can use this path to trigger pre-fetching. The path
+  * MUST be relative to the current request. The string MUST be URL-encoded. The client SHOULD NOT depend upon any
+  * pre-fetch action being taken. The key is only a request for such a pre-fetch.
   *
   * String
   *
   * @remarks
-  * Values may be provided as absolute URLs for convenience; when `CmcdEncodeOptions.baseUrl` is set,
-  * same-origin URLs are converted to paths relative to that base. Already-relative values are not
-  * converted, but are still URL-encoded on emission as required by CMCD v1.
+  * Values may be provided as absolute URLs for convenience. If `CmcdEncodeOptions.baseUrl` is set, same-origin URLs
+  * are converted to paths relative to that base. Already-relative values are not converted. They are still
+  * URL-encoded when emitted, as CMCD version 1 requires.
   */
   nor?: string;
   /**
   * Next range request
   *
-  * @deprecated Use 'nor' with the 'r' parameter instead.
+  * @deprecated Removed in CMCD version 2. Version 2 sends the range as the 'r' parameter of 'nor'.
   *
   * String
   */
@@ -1285,14 +1303,14 @@ type CmcdV1 = {
   * The highest bitrate rendition in the manifest or playlist that the client is allowed to play, given current codec, licensing and
   * sizing constraints.
   *
-  * Integer Kbps
+  * Integer kbps
   */
   tb?: number;
 };
 //#endregion
 //#region src/CmcdKey.d.ts
 /**
-* A CMCD key including V1-only keys.
+* A CMCD key of any version.
 *
 * @public
 */
@@ -1384,7 +1402,7 @@ type CmcdHeaderMap = Record<CmcdHeaderField, CmcdKey[]>;
 */
 type CmcdEncodeOptions = {
   /**
-  * The version of the CMCD specification to use. If not provided, the version
+  * The version of the CMCD specification to use. If omitted, the version
   * is inferred from the data's `v` key, defaulting to `CMCD_V2`.
   *
   * @defaultValue `CMCD_V2`
@@ -1397,7 +1415,16 @@ type CmcdEncodeOptions = {
   */
   reportingMode?: CmcdReportingMode;
   /**
-  * A map of CMCD keys to custom formatters.
+  * A map of CMCD keys to custom formatters. A formatter replaces the value rule of its key.
+  * The encoder does not apply the type, length, and token rules of the key to the output.
+  * The encoder still applies these rules to the output:
+  *
+  * - It drops an empty value. An empty value is `undefined`, `null`, an empty string, an empty array, or a number that is not finite.
+  * - It drops a default value, with or without parameters. The default value is `false`, or `1` for `pr`. The exceptions are `pr` on a `pr` event and `bg` on a `b` event.
+  * - It wraps a string for `e`, `ot`, `sf`, `st`, and `sta` in `SfToken`.
+  * - It replaces a `ts` that is not a finite number with the current time.
+  *
+  * The encoder does not call a formatter for an empty value, for `false`, or for `v`. It also skips the formatter of a key that it does not send. The formatters of `ot` and `e` still run when a rule needs their value.
   */
   formatters?: Partial<CmcdFormatterMap>;
   /**
@@ -1414,9 +1441,10 @@ type CmcdEncodeOptions = {
   filter?: (key: CmcdKey) => boolean;
   /**
   * Base URL (typically the manifest or current request URL) used to convert absolute `nor` values
-  * into paths relative to this base, per the CMCD specification. Values that are already relative
-  * paths are not modified by this option, though CMCD v1 still URL-encodes them on emission. When
-  * omitted, `nor` values are emitted as-is (subject to the v1 URL-encoding rule).
+  * into paths relative to this base, per the CMCD specification. This option does not modify values
+  * that are already relative paths, but CMCD version 1 still URL-encodes them on emission. If omitted,
+  * `nor` values are emitted unchanged (subject to the version 1 URL-encoding rule).
+  * If `baseUrl` is not a valid URL, the encoder ignores it.
   */
   baseUrl?: string;
   /**
@@ -1427,13 +1455,13 @@ type CmcdEncodeOptions = {
 //#endregion
 //#region src/appendCmcdHeaders.d.ts
 /**
-* Append CMCD query args to a header object.
+* Append CMCD header shards to a header object.
 *
 * @param headers - The headers to append to.
 * @param cmcd - The CMCD object to append.
-* @param options - Encode options.
+* @param options - Options for encoding.
 *
-* @returns The headers with the CMCD header shards appended.
+* @returns The headers with CMCD header shards appended.
 *
 * @public
 *
@@ -1450,7 +1478,7 @@ declare function appendCmcdHeaders(headers: Record<string, string>, cmcd: Cmcd,
 *
 * @param url - The URL to append to.
 * @param cmcd - The CMCD object to append.
-* @param options - Options for encoding the CMCD object.
+* @param options - Options for encoding.
 *
 * @returns The URL with the CMCD query args appended.
 *
@@ -1465,7 +1493,7 @@ declare function appendCmcdQuery(url: string, cmcd: Cmcd, options?: CmcdEncodeOp
 //#endregion
 //#region src/CMCD_DEFAULT_TIME_INTERVAL.d.ts
 /**
-* The default time interval in seconds when using using event mode
+* The default time interval in seconds when using event mode
 *
 * @public
 */
@@ -1481,7 +1509,11 @@ declare const CMCD_EVENT_KEYS: readonly ["cen", "e", "h", "ts"];
 //#endregion
 //#region src/CMCD_FORMATTER_MAP.d.ts
 /**
-* The default formatters for CMCD values.
+* Formatters for CMCD values.
+*
+* The encoder applies the same rounding through its key table, and `nor` is the `nor` rule of the encoder.
+* Use an entry to build a custom formatter for `CmcdEncodeOptions.formatters`.
+* The formatter of a numeric key drops a value or a list element that is not a finite number.
 *
 * @public
 */
@@ -1499,9 +1531,9 @@ type CmcdRequestKey = keyof CmcdRequest | "nrr";
 /**
 * The map of CMCD keys to their appropriate header shard.
 *
-* Note: Event-only keys (e, ts, cen, h) and response-received keys
-* (rc, ttfb, ttlb, url, etc.) are intentionally absent. They are
-* transmitted via the event-mode POST body, not HTTP headers.
+* Event-only keys (e, ts, cen, h) and response-received keys (rc, ttfb,
+* ttlb, url, and others) are intentionally absent. They are transmitted
+* in the event-mode POST body, not HTTP headers.
 *
 * @public
 */
@@ -1541,25 +1573,26 @@ declare const CMCD_REQUEST_KEYS: readonly ["ab", "bg", "bl", "br", "bs", "bsa",
 //#endregion
 //#region src/CMCD_REQUEST_PROVENANCE.d.ts
 /**
-* The `customData` key under which `CmcdReporter.createRequestReport()`
-* stamps session provenance on every request it returns.
+* The `customData` property where `CmcdReporter.createRequestReport()`
+* writes session provenance on every request it returns.
 *
-* The value is a frozen `CmcdRequestProvenance` record: `sid` names the
-* session that issued the request, `cid` is the content id in effect when
-* the request was issued, and `data` carries the request's per-call data
-* as an encoded CMCD string. `CmcdReporter.recordResponseReceived()` reads
-* the record to attribute a late response to its session and to rebuild
-* the request-time report keys.
-* Spread and `Object.assign` carry the record through ordinary request
-* clones, but `JSON.stringify` and structured clone drop symbol-keyed
-* properties: read the value before such a boundary and restore it
-* afterward. The record itself survives JSON, and attribution is by the
-* `sid` value rather than object identity, so a revived plain-object copy
-* attributes exactly. A record naming a `sid` the reporter does not retain
-* drops the response rather than relabeling it.
+* The value is a frozen `CmcdRequestProvenance` record. `sid` names the
+* session that issued the request. `cid` is the content id at the time the
+* request was issued. `data` is the request's per-call data as an encoded
+* CMCD string. `CmcdReporter.recordResponseReceived()` reads the record to
+* attribute a late response to its session and to rebuild the request-time
+* report keys.
+* Spread and `Object.assign` copy the record into ordinary request clones.
+* `JSON.stringify` and structured clone drop symbol-keyed properties. Before
+* either operation, read the value and restore it afterward. JSON preserves
+* the record's fields. Attribution uses the `sid` value rather than object
+* identity, so a parsed plain-object copy attributes correctly. For a record
+* naming a `sid` the reporter does not retain, the reporter drops the
+* response rather than reattributing it.
 *
-* Backed by the symbol registry so duplicated copies of this library in
-* one bundle interoperate. The registry key is stable across versions.
+* The symbol registry provides the symbol, so duplicated copies of this
+* library in one bundle interoperate. The registry key is stable across
+* versions.
 *
 * @public
 */
@@ -1567,7 +1600,7 @@ declare const CMCD_REQUEST_PROVENANCE: unique symbol;
 //#endregion
 //#region src/CMCD_RESPONSE_KEYS.d.ts
 /**
-* CMCD v2 - Response-only and timing keys.
+* Response-only and timing keys for version 2.
 *
 * @public
 */
@@ -1585,8 +1618,8 @@ declare const CMCD_V1_KEYS: readonly ["bl", "br", "bs", "cid", "d", "dl", "mtp",
 /**
 * CMCD version 1 data.
 *
-* Overrides keys whose types differ in version 1 (e.g., `bl` and `br`
-* are plain integers instead of inner lists).
+* Overrides keys whose types differ in version 1. For example, `bl` and
+* `br` are integers instead of inner lists.
 *
 * @public
 */
@@ -1607,7 +1640,7 @@ type CmcdV2Data = Omit<Cmcd, "v"> & {
 /**
 * A CMCD data object that is either version 1 or version 2.
 *
-* The `v` property acts as a discriminator:
+* The `v` property is the discriminator:
 *
 * - When `v` is `2`, the type narrows to {@link CmcdV2Data} with
 *   inner-list values and event/response keys.
@@ -1721,36 +1754,36 @@ type CmcdDataValidationResult = CmcdValidationResult & {
 type CmcdDecodeOptions = {
   /**
   * When `true`, up-converts version 1 data to version 2 format by wrapping
-  * scalar values in arrays for inner-list keys (e.g., `bl`, `br`, `mtp`).
+  * scalar values in arrays for inner-list keys. Examples: `bl`, `br`, `mtp`.
   *
-  * This ensures a consistent data shape regardless of the source version,
-  * mirroring the down-conversion that occurs during encoding.
+  * The result has a consistent structure regardless of the source version.
+  * This conversion corresponds to the down-conversion during encoding.
   *
   * @defaultValue false
   */
   convertToLatest?: boolean;
   /**
-  * Controls how RFC 8941 token values are represented in the decoded
-  * data. When omitted, tokens are reduced to plain strings, which cannot
-  * be told apart from string values on re-encoding. `true` decodes
-  * tokens as registry `Symbol`s and `false` as `SfToken` instances;
-  * either preserved representation re-encodes as a bare token, so a
-  * decode/encode round trip keeps the wire bytes.
+  * Controls how the decoded data represents RFC 8941 token values. If
+  * omitted, tokens decode to plain strings, which re-encoding cannot
+  * distinguish from string values. `true` decodes tokens as registry
+  * `Symbol`s and `false` as `SfToken` instances. Either preserved
+  * representation re-encodes as a bare token, so a decode/encode round
+  * trip reproduces the wire bytes.
   */
   useSymbol?: boolean;
 };
 //#endregion
 //#region src/CmcdTransformRequest.d.ts
 /**
-* The media request handed to a report transform, as a read-only view.
+* The media request passed to a report transform, as a read-only view.
 *
 * The request is context only. A transform reads it to decide what to do with
-* the report and must not mutate it: it belongs to the caller, which may still
-* be using it. Every member is `readonly`, and `customData` is readonly at
-* every depth, so nested values cannot be written either.
+* the report. A transform must not mutate the request, which belongs to the
+* caller and may still be in use. Every member is `readonly`, and `customData`
+* is readonly at every depth, so nested values cannot be written either.
 *
 * By default `customData` values are `unknown` rather than `any`, because the
-* library cannot know the player's shape. Narrow with a cast or bracket access
+* library cannot know the player's fields. Narrow with a cast or bracket access
 * to read player-specific fields:
 *
 * ```ts
@@ -1758,9 +1791,9 @@ type CmcdDecodeOptions = {
 * 	request?.customData?.['requestType'] === 'segment' ? data : null
 * ```
 *
-* Supply `C` to describe the player's own `customData` instead and those reads
-* become typed dot access. Annotating one transform is enough: the reporter
-* infers `C` for every other transform in the same configuration.
+* Supply `C` to describe the player's own `customData` instead, and those
+* reads become typed dot access. Annotating one transform is enough: the
+* reporter infers `C` for every other transform in the same configuration.
 *
 * ```ts
 * type PlayerData = { requestType: string; };
@@ -1769,15 +1802,15 @@ type CmcdDecodeOptions = {
 * 	request?.customData?.requestType === 'segment' ? data : null
 * ```
 *
-* `C` is applied through {@link DeepReadonly}, so describing a nested shape
-* does not trade the no-mutation guarantee for typed reads.
+* This type wraps `C` in {@link DeepReadonly}, so a nested `C` keeps both the
+* read-only guarantee and typed reads.
 *
-* Two limits are worth knowing. A mutable body such as `FormData` or
-* `URLSearchParams` has mutating methods of its own that no type can block, and
-* JavaScript callers get no enforcement at all. Mutating the request through
-* either route is unsupported, and the outgoing report may reflect it.
+* Two limits apply. A mutable body such as `FormData` or `URLSearchParams`
+* has mutating methods of its own that no type can block. JavaScript callers
+* get no enforcement at all. Both kinds of mutation are unsupported, and the
+* outgoing report may reflect them.
 *
-* @typeParam C - The shape of the player's `customData`. Defaults to
+* @typeParam C - The type of the player's `customData`. Defaults to
 *                `Record<string, unknown>`.
 *
 * @public
@@ -1796,28 +1829,26 @@ type CmcdTransformRequest<C = Record<string, unknown>> = Readonly<Omit<HttpReque
 //#endregion
 //#region src/CmcdEventReportTransform.d.ts
 /**
-* Transforms an event-mode CMCD report before it is queued for its
-* target.
+* Transforms an event-mode CMCD report before the reporter queues it for
+* its target.
 *
 * Return the data to continue, or `null` to cancel the report. The
-* `data` argument is a per-target copy, so mutating it in place affects
-* neither the reporter's persistent data nor the reports bound for
-* other targets.
+* `data` argument is a per-target copy, so mutating it affects neither
+* the reporter's persistent data nor the reports for other targets.
 *
 * The `request` argument is the media request that triggered the event
-* when one exists (events recorded via
+* (for events recorded through
 * {@link CmcdReporter.recordResponseReceived}), otherwise `undefined`.
-* It is a read-only view, provided as context only and not to be
-* mutated; see {@link CmcdTransformRequest}.
+* The request is a read-only view for context only. A transform must
+* not mutate it. See {@link CmcdTransformRequest}.
 *
-* The reporter re-stamps `e` and `sid`, and assigns `sn` and `msd`,
-* after this function returns, so values written to those keys are
-* overwritten.
+* The reporter rewrites `e` and `sid` and assigns `sn` and `msd` after this
+* function returns, so values written to those keys are overwritten.
 *
 * Must not throw. Exceptions propagate to the caller that recorded the
-* event, which for time-interval events is the interval timer.
+* event. For time-interval events, that caller is the interval timer.
 *
-* @typeParam C - The shape of the player's `customData` on the request.
+* @typeParam C - The type of the player's `customData` on the request.
 *                Defaults to `Record<string, unknown>`, whose values are
 *                `unknown` and read with bracket access.
 *
@@ -1839,9 +1870,10 @@ type CmcdReportConfig = {
   */
   version?: CmcdVersion;
   /**
-  * The list of CMCD keys to include in the report. If not provided,
-  * no keys will be reported, unless there are other configuration
-  * options that require keys to be reported, specifically in event mode.
+  * The list of CMCD keys to include in the report. If omitted, no keys
+  * are reported. In event mode, this list cannot remove `e`, `ts`, or the
+  * required key of the event type. Examples of required keys: `sta` for a
+  * play state change, `ec` for an error, `url` for a response received.
   *
   * @defaultValue `undefined`
   */
@@ -1852,33 +1884,33 @@ type CmcdReportConfig = {
 /**
 * Configuration for a CMCD event report.
 *
-* @typeParam C - The shape of the player's `customData` on the request that
+* @typeParam C - The type of the player's `customData` on the request that
 *                triggered the event. Defaults to `Record<string, unknown>`.
 *
 * @public
 */
 type CmcdEventReportConfig<C = Record<string, unknown>> = CmcdReportConfig & {
   /**
-  * The version of the CMCD protocol to use. Must be
-  * version 2 or higher for event reporting.
+  * The version of the CMCD protocol to use. Event reporting
+  * requires version 2.
   *
   * @defaultValue `CMCD_V2`
   */
   version?: typeof CMCD_V2;
   /**
-  * The URL to which the CMCD event should be sent.
+  * The URL where the reporter sends CMCD event reports.
   */
   url: string;
   /**
-  * The events to report. If no events are provided,
-  * the event target will be effectively disabled.
+  * The events to report. If the caller provides no events,
+  * the event target is effectively disabled.
   *
   * @defaultValue `undefined`
   */
   events?: CmcdEventType[];
   /**
-  * When the time interval event is sent, the interval at which the
-  * events should be reported as a number of seconds.
+  * When the time interval event is sent, the interval in seconds at
+  * which the reporter sends it.
   *
   * @defaultValue `CMCD_DEFAULT_TIME_INTERVAL`
   *
@@ -1896,9 +1928,9 @@ type CmcdEventReportConfig<C = Record<string, unknown>> = CmcdReportConfig & {
   * it is queued. Return the data to continue, or `null` to cancel
   * the report for this target.
   *
-  * Scoped to this target only: targets that share a collector URL
-  * each run their own transform, and a report cancelled here is
-  * still sent to other targets that accept the event.
+  * The transform is scoped to this target only. Targets that share a
+  * collector URL each run their own transform. Other targets that
+  * accept the event still receive a report cancelled by this transform.
   *
   * @defaultValue `undefined`
   *
@@ -1942,29 +1974,29 @@ type CmcdHeaderValue = CmcdRequest | CmcdV1;
 //#endregion
 //#region src/CmcdRecordedReportMode.d.ts
 /**
-* CMCD query reporting mode — CMCD data carried as a `CMCD=` URL
+* CMCD query reporting mode: CMCD data transmitted as a `CMCD=` URL
 * query parameter.
 *
 * @public
 */
 declare const CMCD_RECORDED_REPORT_MODE_QUERY: "query";
 /**
-* CMCD header reporting mode — CMCD data carried as `Cmcd-*` HTTP
+* CMCD header reporting mode: CMCD data transmitted as `CMCD-*` HTTP
 * headers.
 *
 * @public
 */
 declare const CMCD_RECORDED_REPORT_MODE_HEADER: "header";
 /**
-* CMCD event reporting mode — CMCD data carried as a POST body to an
+* CMCD event reporting mode: CMCD data transmitted as a POST body to an
 * event-target URL.
 *
 * @public
 */
 declare const CMCD_RECORDED_REPORT_MODE_EVENT: "event";
 /**
-* Reporting mode under which a captured report was observed by
-* `CmcdReportRecorder`.
+* Reporting mode in which `CmcdReportRecorder` observed a captured
+* report.
 *
 * @enum
 *
@@ -2001,7 +2033,7 @@ declare const CMCD_RECORDED_REQUEST_TYPE_SEGMENT: "segment";
 */
 declare const CMCD_RECORDED_REQUEST_TYPE_EVENT: "event";
 /**
-* Fallback classification for requests the recorder did not recognize
+* Default classification for requests the recorder did not recognize
 * as manifest, segment, or event.
 *
 * @public
@@ -2035,9 +2067,9 @@ type CmcdRecordedRequestType = ValueOf<typeof CmcdRecordedRequestType>;
 */
 type CmcdRecordedReport = {
   /**
-  * The captured request that carried the CMCD report, normalized to
+  * The captured request that contained the CMCD report, normalized to
   * {@link @svta/cml-utils!HttpRequest | HttpRequest}. Headers are
-  * lowercase-keyed; bodies are eagerly read as strings.
+  * lowercase-keyed. Bodies are eagerly read as strings.
   */
   readonly request: HttpRequest;
   /**
@@ -2045,8 +2077,8 @@ type CmcdRecordedReport = {
   */
   readonly type: CmcdRecordedRequestType;
   /**
-  * Reporting mode under which the CMCD data was carried:
-  * `'query'` for `CMCD=` URL parameter, `'header'` for `Cmcd-*`
+  * Reporting mode under which the CMCD data was transmitted:
+  * `'query'` for `CMCD=` URL parameter, `'header'` for `CMCD-*`
   * HTTP headers, `'event'` for an event-target POST body.
   */
   readonly reportingMode: CmcdRecordedReportMode;
@@ -2059,12 +2091,12 @@ type CmcdRecordedReport = {
 //#region src/CmcdTransportAdapter.d.ts
 /**
 * Callback the recorder supplies to a transport adapter. The adapter
-* calls this once per intercepted request, with the request normalized
+* calls it once per intercepted request, with the request normalized
 * to {@link @svta/cml-utils!HttpRequest | HttpRequest}.
 *
-* If the callback returns a `Response`, the adapter must short-circuit
-* the underlying transport and complete the request with that response
-* (used for event-target POST stubbing).
+* If the callback returns a `Response`, the adapter must bypass the
+* transport. It must complete the request with that response (used for
+* event-target POST stubbing).
 *
 * If the callback returns `undefined`, the adapter forwards the request
 * to the original transport unchanged.
@@ -2074,15 +2106,15 @@ type CmcdRecordedReport = {
 type CmcdRequestDeliver = (request: HttpRequest) => Response | undefined;
 /**
 * Pluggable transport-interception contract for `CmcdReportRecorder`.
-* The default implementations (`createXhrTransport`, `createFetchTransport`)
+* The default implementations, `createXhrTransport` and `createFetchTransport`,
 * patch global `XMLHttpRequest` and `fetch`. Custom adapters can wrap
-* other transports (e.g. `undici`, a player-internal HTTP client).
+* other transports, for example `undici` or a player-internal HTTP client.
 *
 * @public
 */
 type CmcdTransportAdapter = {
   /**
-  * Install the transport's interception hook. Called once per
+  * Install interception on the transport. Called once per
   * recorder `attach()`. The adapter must normalize each outgoing
   * request to `HttpRequest` (reading the body to a synchronous value
   * if necessary) and invoke `deliver`. Returns a detach function that
@@ -2099,27 +2131,27 @@ type CmcdTransportAdapter = {
 */
 type CmcdReportRecorderOptions = {
   /**
-  * URLs whose POST requests are intercepted and stubbed with a
-  * synthetic 204 response, instead of being passed through to the
-  * network. A request matches if its URL starts with any entry.
+  * URLs whose POST requests the recorder intercepts and answers with a
+  * synthetic 204 response instead of sending them to the network. A
+  * request matches if its URL starts with any entry.
   *
-  * Use this to verify CMCD event-mode reports without making real
+  * Use this option to verify CMCD event-mode reports without real
   * network calls to placeholder endpoints.
   */
   eventTargetUrls?: readonly string[];
   /**
-  * Override the default set of transport adapters. Defaults to
+  * Override the default transport adapters. Defaults to
   * `[createXhrTransport(), createFetchTransport()]`, which patches
   * `XMLHttpRequest` and `fetch` on the current realm.
   *
-  * Supply this when the player under test uses a non-standard
-  * transport (e.g. a custom HTTP client).
+  * If the player under test uses a non-standard transport, for example
+  * a custom HTTP client, supply this option.
   */
   transports?: readonly CmcdTransportAdapter[];
   /**
   * Default timeout (in milliseconds) applied to every `waitFor*`
-  * call on this recorder. Individual call sites can still pass
-  * an explicit timeout to override per call.
+  * call on this recorder. Each call can still pass an explicit
+  * timeout to override this default.
   *
   * @defaultValue `15000`
   */
@@ -2128,13 +2160,13 @@ type CmcdReportRecorderOptions = {
   * Called once for each captured CMCD report, immediately after it
   * is appended to the buffer and before any pending `waitFor*`
   * promises resolve. Use for live UI inspection in test harness
-  * pages. Cleared automatically on `detach()`; pass a fresh
-  * callback to a subsequent `attach()` to resume notification.
+  * pages. `detach()` clears the callback. To resume notification,
+  * pass a new callback to a later `attach()`.
   *
   * The callback receives the same {@link CmcdRecordedReport}
-  * shape that `getReports()` returns. Filter by `report.type` or
-  * `report.reportingMode` inside the callback if you only care
-  * about a subset.
+  * type that `getReports()` returns. If you only need a subset,
+  * filter by `report.type` or `report.reportingMode` inside the
+  * callback.
   *
   * @example
   * {@includeCode ../test/CmcdReportRecorder.test.ts#example-on-report}
@@ -2157,8 +2189,8 @@ type CmcdReportRecorderWaitOptions = {
   */
   count?: number;
   /**
-  * Maximum time to wait (in milliseconds) before rejecting. Falls
-  * back to the recorder's `waitTimeout` attach option (15000 ms if
+  * Maximum time to wait (in milliseconds) before rejecting. The
+  * default is the recorder's `waitTimeout` attach option (15000 ms if
   * unset).
   */
   timeout?: number;
@@ -2166,10 +2198,10 @@ type CmcdReportRecorderWaitOptions = {
 //#endregion
 //#region src/CmcdReportRecorder.d.ts
 /**
-* Test helper that records CMCD-bearing reports across XHR and fetch
-* transports for assertion in e2e tests. Each captured request is
-* normalized to {@link @svta/cml-utils!HttpRequest | HttpRequest} so
-* tests are identical regardless of which transport the player uses.
+* Test helper that records CMCD reports from the XHR and fetch
+* transports for assertions in e2e tests. The recorder normalizes each
+* captured request to {@link @svta/cml-utils!HttpRequest | HttpRequest},
+* so tests are identical regardless of which transport the player uses.
 *
 * @example
 * {@includeCode ../test/CmcdReportRecorder.test.ts#example}
@@ -2179,11 +2211,11 @@ type CmcdReportRecorderWaitOptions = {
 declare class CmcdReportRecorder {
   #private;
   /**
-  * Install transport patches and begin recording CMCD reports.
-  * No-op if already attached — the previously supplied options are
-  * retained and the new `options` argument is silently ignored.
-  * Call `detach()` first if you need to re-attach with different
-  * options.
+  * Install transport patches and start recording CMCD reports.
+  * If the recorder is already attached, this call does nothing. The
+  * recorder keeps the previous options and silently ignores the new
+  * `options` argument. To re-attach with different options, call
+  * `detach()` first.
   *
   * @public
   */
@@ -2202,15 +2234,15 @@ declare class CmcdReportRecorder {
   */
   clear(): void;
   /**
-  * Return a defensive copy of all recorded reports.
+  * Return a copy of all recorded reports.
   *
   * @public
   */
   getReports(): CmcdRecordedReport[];
   /**
   * Wait until at least `count` reports of any type are recorded.
-  * Resolves with all matching reports; rejects with a diagnostic error
-  * on timeout. `count` defaults to 1; `timeout` falls back to the
+  * Resolves with all matching reports. Rejects with a diagnostic error
+  * on timeout. `count` defaults to 1. `timeout` defaults to the
   * recorder's `waitTimeout` option (default 15000 ms).
   *
   * @public
@@ -2218,8 +2250,8 @@ declare class CmcdReportRecorder {
   waitForReports(options?: CmcdReportRecorderWaitOptions): Promise<CmcdRecordedReport[]>;
   /**
   * Wait until at least `count` manifest reports are recorded.
-  * Resolves with all matching reports; rejects with a diagnostic error
-  * on timeout. `count` defaults to 1; `timeout` falls back to the
+  * Resolves with all matching reports. Rejects with a diagnostic error
+  * on timeout. `count` defaults to 1. `timeout` defaults to the
   * recorder's `waitTimeout` option (default 15000 ms).
   *
   * @public
@@ -2227,8 +2259,8 @@ declare class CmcdReportRecorder {
   waitForManifest(options?: CmcdReportRecorderWaitOptions): Promise<CmcdRecordedReport[]>;
   /**
   * Wait until at least `count` segment reports are recorded.
-  * Resolves with all matching reports; rejects with a diagnostic error
-  * on timeout. `count` defaults to 1; `timeout` falls back to the
+  * Resolves with all matching reports. Rejects with a diagnostic error
+  * on timeout. `count` defaults to 1. `timeout` defaults to the
   * recorder's `waitTimeout` option (default 15000 ms).
   *
   * @public
@@ -2236,8 +2268,8 @@ declare class CmcdReportRecorder {
   waitForSegments(options?: CmcdReportRecorderWaitOptions): Promise<CmcdRecordedReport[]>;
   /**
   * Wait until at least `count` event-mode reports are recorded.
-  * Resolves with all matching reports; rejects with a diagnostic error
-  * on timeout. `count` defaults to 1; `timeout` falls back to the
+  * Resolves with all matching reports. Rejects with a diagnostic error
+  * on timeout. `count` defaults to 1. `timeout` defaults to the
   * recorder's `waitTimeout` option (default 15000 ms).
   *
   * @public
@@ -2255,15 +2287,15 @@ declare class CmcdReportRecorder {
 * mutating it in place never affects the reporter's persistent data.
 * The `request` argument is the request passed to
 * `createRequestReport()`, as a read-only view. It is context only and
-* must not be mutated; see {@link CmcdTransformRequest}.
+* must not be mutated. See {@link CmcdTransformRequest}.
 *
-* The reporter re-stamps `sid` and assigns `sn` and `msd` after this
+* The reporter rewrites `sid` and assigns `sn` and `msd` after this
 * function returns, so values written to those keys are overwritten.
 *
 * Must not throw. Exceptions propagate to the `createRequestReport()`
 * caller.
 *
-* @typeParam C - The shape of the player's `customData` on the request.
+* @typeParam C - The type of the player's `customData` on the request.
 *                Defaults to `Record<string, unknown>`, whose values are
 *                `unknown` and read with bracket access.
 *
@@ -2324,7 +2356,7 @@ type CmcdTransmissionMode = ValueOf<typeof CmcdTransmissionMode>;
 /**
 * Configuration for a CMCD request report.
 *
-* @typeParam C - The shape of the player's `customData` on the requests
+* @typeParam C - The type of the player's `customData` on the requests
 *                passed to {@link CmcdReporter.createRequestReport}.
 *                Defaults to `Record<string, unknown>`.
 *
@@ -2338,12 +2370,12 @@ type CmcdRequestReportConfig<C = Record<string, unknown>> = CmcdReportConfig & {
   */
   transmissionMode?: CmcdTransmissionMode;
   /**
-  * A map of CMCD header fields to the custom keys that should be
-  * emitted in them when the transmission mode is
+  * A map of CMCD header fields to the custom keys to emit in them.
+  * Applies when the transmission mode is
   * `CmcdTransmissionMode.HEADERS`. Custom keys not listed in any
   * shard are emitted in the `CMCD-Request` header. Standard keys
   * have fixed shards per the CMCD specification and cannot be
-  * re-routed. Has no effect in query transmission mode or on event
+  * moved. Has no effect in query transmission mode or on event
   * reports.
   *
   * @defaultValue `undefined`
@@ -2370,16 +2402,16 @@ type CmcdRequestReportConfig<C = Record<string, unknown>> = CmcdReportConfig & {
 /**
 * Configuration for a CMCD reporting component.
 *
-* @typeParam C - The shape of the player's `customData` on the requests this
-*                reporter sees. Annotating a single `transform` is enough for
-*                the rest of the configuration to infer it. Defaults to
+* @typeParam C - The type of the player's `customData` on the requests this
+*                reporter receives. If one `transform` is annotated, the rest
+*                of the configuration infers the type. Defaults to
 *                `Record<string, unknown>`.
 *
 * @public
 */
 type CmcdReporterConfig<C = Record<string, unknown>> = CmcdRequestReportConfig<C> & {
   /**
-  * The session ID. If not provided, a new random session ID will be generated.
+  * The session ID. If omitted, the reporter generates a new random session ID.
   *
   * @defaultValue `undefined`
   */
@@ -2391,7 +2423,7 @@ type CmcdReporterConfig<C = Record<string, unknown>> = CmcdRequestReportConfig<C
   */
   cid?: string;
   /**
-  * The event configurations. If not provided, no events will be reported.
+  * The event configurations. If omitted, no events are reported.
   *
   * @defaultValue `undefined`
   */
@@ -2400,10 +2432,11 @@ type CmcdReporterConfig<C = Record<string, unknown>> = CmcdRequestReportConfig<C
   * The number of ended sessions the reporter retains state for, in
   * addition to the current one. Retained sessions let a response that
   * completes after a `sid` change report under the session that issued
-  * its request, with that session's data snapshot and sequence numbers.
-  * `0` retains nothing, so stale responses are dropped. `Infinity` never
-  * evicts, which also retains every session's unsent report queues.
-  * Numbers are floored; every other input falls back to the default.
+  * its request. The report uses that session's data snapshot and
+  * sequence numbers. `0` retains nothing, so stale responses are
+  * dropped. `Infinity` never evicts, which also retains every session's
+  * unsent report queues. Numbers are floored. Every other input uses
+  * the default.
   *
   * @defaultValue 2
   */
@@ -2415,11 +2448,11 @@ type CmcdReporterConfig<C = Record<string, unknown>> = CmcdRequestReportConfig<C
 * The `customData` a {@link CmcdReporter} method accepts, for a reporter typed
 * `C`.
 *
-* A reporter left on the default `C` constrains nothing, so requests carrying
-* any `customData` are accepted exactly as they were before `C` existed. A
-* reporter given a concrete `C` requires the request to satisfy it, because its
-* transforms read `customData` as `C` and would otherwise be handed a value
-* their type does not describe.
+* A reporter with the default `C` constrains nothing, so requests with any
+* `customData` are accepted exactly as before `C` existed. A reporter with a
+* concrete `C` requires the request to satisfy it. The reporter's transforms
+* read `customData` as `C` and would otherwise receive a value their type
+* does not describe.
 *
 * @typeParam C - The reporter's `customData` type.
 *
@@ -2429,33 +2462,34 @@ type CmcdReporterCustomData<C> = Record<string, unknown> extends C ? any : C;
 //#endregion
 //#region src/CmcdRequestProvenance.d.ts
 /**
-* The session-provenance record `CmcdReporter.createRequestReport()` stamps
-* on `customData` under `CMCD_REQUEST_PROVENANCE`.
+* The session-provenance record `CmcdReporter.createRequestReport()` writes
+* to `customData` under `CMCD_REQUEST_PROVENANCE`.
 *
-* `sid` names the session that issued the request and is the attribution
-* key: `CmcdReporter.recordResponseReceived()` resolves it against the
-* reporter's retained sessions by value, never by object identity, so a
-* copy of the record that crosses a JSON boundary attributes exactly once
-* restored. Session identity rides on the caller's own `sid` values, which
-* CTA-5004-B expects to be unique per playback session: reusing a `sid`
-* replaces the retained namesake, so late responses of the replaced
-* session relabel onto the replacement.
+* `sid` names the session that issued the request.
+* `CmcdReporter.recordResponseReceived()` matches `sid` against the
+* reporter's retained sessions by value, never by object identity. A record
+* copy restored from JSON attributes the response to the same
+* session. Session identity depends on the caller's own `sid` values, which
+* CTA-5004-B expects to be unique per playback session. Reusing a `sid`
+* replaces the retained session with that `sid`. The reporter then
+* attributes late responses of the replaced session to the replacement.
 *
-* `cid` is the content id that was current when the record was minted. A
-* `RESPONSE_RECEIVED` event reports it in place of the session's current
-* `cid`, so a response that completes after a content change keeps the
-* meaning it had when the request was issued.
+* `cid` is the content id at the time the reporter created the record. A
+* `RESPONSE_RECEIVED` event reports this `cid` instead of the session's
+* current `cid`. A response that completes after a content change
+* keeps the content id of its request.
 *
 * `data` is the per-call data the request was created with, encoded as a
 * CMCD string. The reporter decodes it to rebuild the request-time report
-* keys for a `RESPONSE_RECEIVED` event, so the caller's inputs survive any
-* boundary the record itself is carried across. It is captured before the
-* request `transform` and key filter run, so it also rides requests the
-* reporter does not decorate.
+* keys for a `RESPONSE_RECEIVED` event. Any copy of the record
+* contains the caller's inputs. The reporter captures `data` before the
+* request `transform` and key filter run. `data` is also present
+* on requests the reporter does not decorate.
 *
-* The reporter freezes every record it mints. The record is constructible:
-* a hand-built request may carry `{ sid }` to attribute to that session.
-* A record naming a `sid` the reporter does not retain is dropped.
+* The reporter freezes every record it creates. The record is constructible:
+* a hand-built request may include `{ sid }` to attribute the request to
+* that session. The reporter drops the response when the record names a
+* `sid` it does not retain.
 *
 * @public
 */
@@ -2469,9 +2503,9 @@ type CmcdRequestProvenance = {
 /**
 * A report of a CMCD request.
 *
-* The provenance member is optional so the type stays constructible by
-* consumers that build or mock request reports; every request returned by
-* `CmcdReporter.createRequestReport()` carries it.
+* The provenance member is optional so callers that build or mock request
+* reports can construct the type. Every request returned by
+* `CmcdReporter.createRequestReport()` includes the member.
 *
 * @public
 */
@@ -2487,12 +2521,12 @@ type CmcdRequestReport<D = unknown> = HttpRequest & {
 /**
 * The CMCD reporter.
 *
-* `C` describes the player's own `customData`, which the reporter passes
-* through to each configured `transform`. It is inferred from the
-* configuration, so annotating a single `transform` types the request in every
-* other one; the default leaves `customData` values `unknown`.
+* `C` describes the player's own `customData`, which the reporter passes to
+* each configured `transform`. TypeScript infers `C` from the configuration,
+* so an annotation on one `transform` types the request in every other
+* `transform`. The default leaves `customData` values `unknown`.
 *
-* @typeParam C - The shape of the player's `customData`. Defaults to
+* @typeParam C - The type of the player's `customData`. Defaults to
 *                `Record<string, unknown>`.
 *
 * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#reporting-modes-when-we-send-data | CTA-5004-B Reporting Modes}
@@ -2503,18 +2537,18 @@ declare class CmcdReporter<C = Record<string, unknown>> {
   private timeOrigin;
   private config;
   /**
-  * Retained sessions keyed by `sid`, insertion-ordered oldest first, the
-  * current session last. The ended-session count is capped by
-  * `config.sessionRetention`. CTA-5004-B expects a `sid` to be unique
-  * per playback session; a reused one replaces its retained namesake at
-  * the newest position (see `startSession()`).
+  * Retained sessions keyed by `sid`, in insertion order: oldest first,
+  * current session last. `config.sessionRetention` limits the ended-session
+  * count. CTA-5004-B expects a `sid` to be unique per playback session. A
+  * reused `sid` replaces the earlier session with that `sid` at the newest
+  * position (see `startSession()`).
   */
   private sessions;
   private session;
   /**
-  * Armed time-interval timers by target config. Timers outlive session
-  * changes (their callbacks report into whichever session is current at
-  * fire time), so they live on the reporter rather than the session.
+  * Active time-interval timers by target config. Timers continue across
+  * session changes (their callbacks report into whichever session is
+  * current when they fire), so the reporter owns them, not the session.
   */
   private intervals;
   private started;
@@ -2523,7 +2557,7 @@ declare class CmcdReporter<C = Record<string, unknown>> {
   * Creates a new CMCD reporter.
   *
   * @param config - The configuration for the CMCD reporter.
-  * @param requester - The function to use to send the request.
+  * @param requester - The function that sends the request.
   *                    The default is a simple wrapper around the
   *                    native `fetch` API.
   */
@@ -2531,170 +2565,176 @@ declare class CmcdReporter<C = Record<string, unknown>> {
     status: number;
   }>);
   /**
-  * Creates the state for a new session: fresh counters, gates, queues and
-  * dedup baseline for every configured target.
+  * Creates the state for a new session: initial counters, flags, queues, and
+  * deduplication baseline for every configured target.
   */
   private createSession;
   /**
-  * Starts the CMCD reporter. Called by the player when the reporter is enabled.
+  * Starts the CMCD reporter. The player calls this method when it enables the
+  * reporter.
   *
-  * Note: This fires an initial time-interval event immediately (synchronously)
-  * before the first interval elapses. Ensure CMCD data (sid, cid, etc.) is
-  * populated before calling start().
+  * This method fires an initial time-interval event immediately (synchronously),
+  * before the first interval elapses. Populate the CMCD data (sid, cid, and
+  * others) before calling start().
   */
   start(): void;
   /**
-  * Arms the time-interval timer for an event target when its config calls
-  * for one. Returns whether a timer was armed. The callback reports into
-  * whichever session is current when it fires.
+  * Starts the time-interval timer for an event target when its config
+  * requires one. Returns whether a timer started. The callback reports into
+  * whichever session is current when the timer fires.
   */
   private armInterval;
   /**
-  * Stops the CMCD reporter. Called by the player when the reporter is disabled.
+  * Stops the CMCD reporter. The player calls this method when it disables the
+  * reporter.
   *
   * @param flush - Whether to flush the event targets.
   */
   stop(flush?: boolean): void;
   /**
-  * Forces the sending of all event reports, regardless of the batch size or interval.
-  * Useful for sending outstanding reports when the player is destroyed or a playback
+  * Sends all outstanding event reports, regardless of the batch size or
+  * interval. Use this method when the player is destroyed or a playback
   * session ends.
   */
   flush(): void;
   /**
   * Updates the CMCD data.
   *
-  * Called by the player when data changes. For tracked state fields
-  * (`sta`, `pr`, `cid`, `bg`, `br`), if the new value differs from the
-  * last-reported value (the value most recently emitted on the wire for
-  * that field), the corresponding state-change event is automatically
-  * fired. Comparing against the last-reported value (rather than the
-  * previous persisted value) ensures the first state-change event in a
-  * new session always emits, even when the persisted value didn't change
-  * across the `sid` boundary.
-  *
-  * Multi-field updates fire multiple events in the order: `sta` → `pr` →
-  * `cid` → `bg` → `br`. The order of keys in the input object does not
-  * affect the firing order.
-  *
-  * To attach snapshot context (e.g., `bl`, `mtp`, `pt`, `ltc`) to a
-  * state-change event, ensure those fields are in the reporter's data
-  * before the state field changes. Either include them alongside the
-  * state field in the same `update()` call, or persist them via earlier
-  * `update()` calls — auto-fired events emit whatever is currently in
-  * the persistent data store. This is also how to keep `TIME_INTERVAL`
-  * reports useful — those events draw from the persistent data store
-  * with no caller hook for per-event data, so fields the player wants
-  * in periodic reports must be kept fresh here.
-  *
-  * A `sid` change resets the dedup baseline.
-  *
-  * `sid` and `msd` are session-owned: the reporter tracks them itself and
-  * stamps them onto every outgoing report, so this method is the only way
+  * The player calls this method when data changes. The tracked state fields
+  * are `sta`, `pr`, `cid`, `bg`, and `br`. If a new value for one of them
+  * differs from the last reported value for that field, the reporter fires
+  * the matching state-change event. The comparison uses the last reported
+  * value, not the previous persisted value. The first state-change event in
+  * a new session therefore always fires, even when the persisted value did
+  * not change across the `sid` boundary.
+  *
+  * The `bg` field is an exception. A session that does not start with
+  * `bg: true` begins with `false` as its last reported `bg` value.
+  * `bg: false` therefore fires `BACKGROUNDED_MODE` only if the session
+  * started with `bg: true` or reported `bg: true`. CTA-5004-B defines a
+  * `b` event without `bg` as the exit from backgrounded mode, so the exit
+  * report does not carry `bg`. A target transform can add `bg: false` to
+  * the exit report. The encoder writes that value as `?0`.
+  *
+  * Multi-field updates fire the events in this order: `sta`, `pr`, `cid`,
+  * `bg`, `br`. The order of keys in the input object does not affect the
+  * firing order.
+  *
+  * A state-change event can include context fields, for example `bl`, `mtp`,
+  * `pt`, `ltc`. Those fields must be in the data store before the state field
+  * changes. Either pass them with the state field in the same `update()`
+  * call, or persist them with earlier `update()` calls. An auto-fired event
+  * reports the current content of the data store. `TIME_INTERVAL` events also
+  * read the data store, and the caller cannot add per-call data to them. The
+  * player must therefore update the fields it wants in periodic reports with
+  * this method.
+  *
+  * A `sid` change resets the deduplication baseline.
+  *
+  * `sid` and `msd` are session-owned. The reporter tracks them itself and
+  * writes them into every outgoing report, so this method is the only way
   * to change them. A per-call value on {@link CmcdReporter.recordEvent},
   * {@link CmcdReporter.createRequestReport}, or
-  * {@link CmcdReporter.recordResponseReceived} has no effect; response
-  * attribution is by the provenance record alone.
+  * {@link CmcdReporter.recordResponseReceived} has no effect.
   * `msd` must be a finite number of milliseconds between `0` and
-  * `999_999_999_999_999` (the RFC 8941 integer maximum); it is rounded to
-  * the nearest integer, and invalid values are ignored.
+  * `999_999_999_999_999` (the RFC 8941 integer maximum). The reporter
+  * rounds `msd` to the nearest integer and ignores invalid values.
   *
   * @param data - The data to update.
   */
   update(data: Partial<Cmcd>): void;
   /**
-  * Starts a new session: the current one is archived in place for stale
-  * attribution, a fresh one takes over, ended sessions are drained, and
-  * the oldest are evicted beyond the configured retention.
-  *
-  * The data store is carried over, and the archived snapshot is frozen:
-  * the ended session's value graph is detached first, so nested values
-  * the caller handed to `update()` can no longer mutate it, and the new
-  * session starts from a shallow copy of the detached graph, so `cid`,
-  * `br`, custom keys and the rest survive a `sid` change as they always
-  * have. Sessions are keyed by `sid`, which CTA-5004-B expects to be
-  * unique per playback session: reusing one replaces the retained
-  * namesake, whose remaining state dies as if evicted and whose late
-  * responses relabel onto the replacement.
+  * Starts a new session. The reporter retains the current session for late
+  * responses and creates a new current session. It then sends the ended
+  * sessions' queued reports and removes the oldest sessions beyond the
+  * configured retention.
+  *
+  * The ended session's snapshot is frozen: the reporter detaches its value
+  * graph, so nested values from earlier `update()` calls cannot mutate the
+  * snapshot. The new session starts from a shallow copy of that graph, which
+  * preserves the data store. All fields, including `cid`, `br`, and custom
+  * keys, survive a `sid` change as before. CTA-5004-B expects a `sid` to be
+  * unique per playback session, so a reused `sid` replaces the retained
+  * session with that `sid`. The replaced session's remaining state is lost,
+  * as if removed, and the reporter attributes its late responses to the
+  * replacement.
   */
   private startSession;
   /**
-  * Records an event. Called by the player when an event occurs.
+  * Records an event. The player calls this method when an event occurs.
   *
   * For state-change events (`PLAY_STATE`, `PLAYBACK_RATE`, `CONTENT_ID`,
   * `BACKGROUNDED_MODE`, `BITRATE_CHANGE`), this method:
-  * 1. Persists the dedup field from `data` (if present) into the reporter's
-  *    persistent data store — equivalent to a write-through `update()`.
-  * 2. Drops the event entirely if the dedup field has no value after the
-  *    write-through (never set, or cleared via `update({ field: undefined })`).
-  *    State-change events without their required field would violate CTA-5004-B.
-  * 3. Suppresses the event if the field's current value matches the
-  *    last-emitted value (no state transition).
-  *
-  * For all other event types, the event is always emitted.
-  *
-  * For state-change events, prefer {@link CmcdReporter.update} — including
-  * for snapshot enrichment via a combined call like
-  * `update({ sta: 'p', bl: [3000], mtp: [8500] })`. Calling `recordEvent()`
-  * for a state-change event after `update()` has already auto-fired it
-  * silently drops the second call's `data`, because dedup suppresses the
-  * second emission.
-  *
-  * Use `recordEvent()` directly for events whose payload is intrinsic to
-  * the event call — `CUSTOM_EVENT` with `cen`, `ERROR` with `ec`,
-  * ad-lifecycle events, `MUTE`/`UNMUTE`, `PLAYER_EXPAND`/`PLAYER_COLLAPSE`,
-  * `SKIP`. For `RESPONSE_RECEIVED`, prefer
-  * {@link CmcdReporter.recordResponseReceived}, which derives the
-  * per-response fields automatically.
+  * 1. Writes the state field from `data` (if present) into the reporter's
+  *    data store, as `update()` would.
+  * 2. Discards the event if the state field has no value after that write
+  *    (never set, or cleared with `update({ field: undefined })`).
+  * 3. Suppresses the event if the field's current value equals the
+  *    last reported value (no state transition). {@link CmcdReporter.update}
+  *    describes the `bg` value that a new session starts with.
+  *
+  * The reporter always records all other event types.
+  *
+  * For state-change events, prefer {@link CmcdReporter.update}, also for
+  * context fields in a combined call like
+  * `update({ sta: 'p', bl: [3000], mtp: [8500] })`. After `update()`
+  * auto-fires a state-change event, deduplication suppresses a
+  * `recordEvent()` call for the same event, and that call's `data` is
+  * silently lost.
+  *
+  * Call `recordEvent()` directly for events whose data comes with the event
+  * call. Examples: `CUSTOM_EVENT` with `cen`, `ERROR` with `ec`, ad lifecycle
+  * events, `MUTE`/`UNMUTE`, `PLAYER_EXPAND`/`PLAYER_COLLAPSE`, `SKIP`. For
+  * `RESPONSE_RECEIVED`, prefer {@link CmcdReporter.recordResponseReceived},
+  * which derives the per-response fields automatically.
   *
   * @param type - The type of event to record.
-  * @param data - Additional data to record with the event. This data
-  *               only applies to this event report, except for the dedup
-  *               field of a state-change event, which is also persisted
-  *               into the reporter's data store. Session-owned keys
-  *               (`sid`, `msd`) supplied here are ignored; the reporter
-  *               stamps its own values.
+  * @param data - Additional data to record with the event. This data applies
+  *               only to this event report. The exception is the state field
+  *               of a state-change event, which the reporter also writes into
+  *               its data store. The reporter ignores session-owned keys
+  *               (`sid`, `msd`) supplied here and writes its own values.
   */
   recordEvent(type: CmcdEventType, data?: Partial<Cmcd>): void;
   /**
-  * Records an event across every configured target of a session, applying
-  * state-change dedup once before per-target fan-out.
+  * Records an event for every configured target of a session. State-change
+  * deduplication runs once, before the per-target loop.
   *
   * @param session - The session the event belongs to. Everything the event
-  *                  touches (data store, dedup baseline, counters, queues)
-  *                  is that session's; only `recordResponseReceived()` ever
-  *                  passes an archived one.
+  *                  touches (data store, deduplication baseline, counters,
+  *                  queues) is that session's. Only `recordResponseReceived()`
+  *                  ever passes an ended session.
   * @param type - The type of event to record.
   * @param data - Additional data to record with the event.
   * @param request - The media request that triggered the event, when
-  *                  one exists. Only `recordResponseReceived()`
-  *                  populates this; it is threaded through to each
-  *                  target's `transform`.
+  *                  one exists. Only `recordResponseReceived()` sets this
+  *                  parameter, which the reporter passes to each target's
+  *                  `transform`.
   */
   private emitEvent;
   /**
-  * Records an event for a target. Called by the reporter when an event occurs.
+  * Records an event for a target. The reporter calls this method when an
+  * event occurs.
   *
   * @param target - The target to record the event for.
   * @param config - The configuration for the target.
   * @param type - The type of event to record.
   * @param data - Additional data to record with the event. This data
-  *               only applies to this event report. Persistent data should
-  *               be updated using `update()`.
+  *               only applies to this event report. Use `update()` for
+  *               persistent data.
   * @param request - The media request that triggered the event, when
-  *                  one exists. Passed to the target's `transform`.
+  *                  one exists. The target's `transform` receives it.
   */
   private recordTargetEvent;
   /**
-  * Stamps the reporter-owned fields on a finished event report, encodes it,
-  * and pushes the wire line to the target's queue.
+  * Writes the reporter-owned fields into a finished event report, encodes
+  * the report, and pushes the encoded line to the target's queue.
   *
-  * Called after any transform has run, so a transform cannot bypass the
-  * target's `events` filter via `e`, break `sn` continuity, or substitute
-  * the session identity carried by `sid` and `msd`. Encoding here means a
-  * report that cannot serialize throws inside the recording call that
-  * produced it, instead of rejecting the batch send and re-queueing
-  * forever.
+  * This method runs after any transform. A transform cannot bypass the
+  * target's `events` filter through `e`, break `sn` continuity, or replace
+  * the session identity in `sid` and `msd`. Encoding here makes a report
+  * that cannot serialize throw inside the recording call, instead of failing
+  * the batch send and re-queueing forever.
   *
   * @param target - The target to queue the report for.
   * @param config - The configuration for the target.
@@ -2703,10 +2743,10 @@ declare class CmcdReporter<C = Record<string, unknown>> {
   */
   private queueTargetEvent;
   /**
-  * Records a response-received event. Called by the player when a media
-  * request response has been fully received.
+  * Records a response-received event. The player calls this method when a
+  * media request response has fully arrived.
   *
-  * This method automatically derives the `rr` event keys from the
+  * This method derives these `rr` event keys automatically:
   *
   * - `url` - the original requested URL (before any redirects)
   * - `rc` - the HTTP response status code
@@ -2714,68 +2754,65 @@ declare class CmcdReporter<C = Record<string, unknown>> {
   * - `ttfb` - time to first byte (from `resourceTiming.responseStart`)
   * - `ttlb` - time to last byte (from `resourceTiming.duration`)
   *
-  * Additional keys like `ttfbb`, `cmsdd`, `cmsds`, and `smrt` can be
-  * supplied via the `data` parameter if the player has access to them.
-  *
-  * The request's `customData` is generic, so a player can pass a request
-  * carrying its own taxonomy (e.g. `{ requestType: 'segment' }`) without a
-  * cast. The reporter reads only the provenance record that
-  * {@link CmcdReporter.createRequestReport} writes there; every other key
-  * is left untouched and stays visible to an event target's `transform`
-  * via its `request` argument.
-  *
-  * A reporter given a concrete `C` requires the request to satisfy it, so a
-  * request the configured transforms could not read is rejected here rather
-  * than reaching them; see {@link CmcdReporterCustomData}.
-  *
-  * The event is attributed to the session that issued the request, and to
-  * nothing else: the provenance record that
-  * {@link CmcdReporter.createRequestReport} stored on the request's
-  * `customData` (under {@link CMCD_REQUEST_PROVENANCE}) selects the
-  * session by its `sid`, or the response is dropped rather than
-  * relabeled. There is no other key: a record lost to a serialization
-  * boundary (and not restored; see the bridge notes on
-  * {@link CMCD_REQUEST_PROVENANCE}) and a session no longer retained
-  * (see `CmcdReporterConfig.sessionRetention`) both drop, and a per-call
-  * `data.sid` cannot substitute. The record is honored wherever its
-  * `sid` resolves: a request decorated by another reporter configured
-  * with the same session attributes here, as does a hand-built record.
-  * A response that completes after a `sid` change reports under its own
-  * retained session, with that session's data snapshot and sequence
-  * numbers.
-  *
-  * Request-time report keys come from the record's encoded per-call
-  * `data` snapshot, decoded fresh per response, and the record's `cid`
-  * reports in place of the session's current one, so a response that
-  * completes after a mid-session content change keeps the meaning it
-  * had when its request was issued.
-  *
-  * @typeParam RD - The `customData` this request carries. Defaults to the
+  * If the player has additional keys like `ttfbb`, `cmsdd`, `cmsds`, and
+  * `smrt`, pass them in the `data` parameter.
+  *
+  * The request's `customData` is generic, so a player can pass a request with
+  * its own keys (for example `{ requestType: 'segment' }`) without a cast. The
+  * reporter reads only the provenance record that
+  * {@link CmcdReporter.createRequestReport} writes there. Every other key
+  * stays unchanged and visible to an event target's `transform` through its
+  * `request` argument.
+  *
+  * A reporter with a concrete `C` requires the request to satisfy that type.
+  * TypeScript therefore rejects a call whose request the configured
+  * transforms could not read. See {@link CmcdReporterCustomData}.
+  *
+  * The provenance record that {@link CmcdReporter.createRequestReport}
+  * stored on the request's `customData` (under
+  * {@link CMCD_REQUEST_PROVENANCE}) selects the session by `sid`. A record
+  * that names no retained session drops the response (see
+  * `CmcdReporterConfig.sessionRetention`). A request without a record reports
+  * under the current session, as in version 2.4.0. The request-time data then
+  * comes from `customData.cmcd`. A per-call `data.sid` cannot substitute. The
+  * reporter accepts any record whose `sid` names a retained session. The
+  * record may come from another reporter with the same session attributes,
+  * or be hand-built. If the request has a record, a response that completes
+  * after a `sid` change reports under its own retained session, with that
+  * session's data snapshot and sequence numbers.
+  *
+  * With a record, request-time report keys come from the record's encoded
+  * per-call `data` snapshot, which the reporter decodes for each response.
+  * The record's `cid` replaces the session's current `cid` in the report. A
+  * response that completes after a mid-session content change therefore
+  * reports its request-time values.
+  *
+  * @typeParam RD - The `customData` of this request. Defaults to the
   *                reporter's own `C`.
   *
   * @param response - The HTTP response received.
   * @param data - Additional CMCD data to include with the event.
-  *               Values provided here override any auto-derived values.
-  *               Session-owned keys (`sid`, `msd`) supplied here are
-  *               ignored; attribution is by the provenance record alone.
+  *               Values provided here override the derived values.
+  *               The reporter ignores session-owned keys (`sid`, `msd`)
+  *               supplied here.
   */
   recordResponseReceived<RD extends CmcdReporterCustomData<C> = C>(response: HttpResponse<HttpRequest<RD & {
     cmcd?: Cmcd;
     [CMCD_REQUEST_PROVENANCE]?: CmcdRequestProvenance;
   }>>, data?: Partial<Cmcd>): void;
   /**
-  * Resolves the session a response belongs to: the provenance record's
-  * `sid` names one of this reporter's retained sessions, or the response
-  * is dropped. There is no other key — a record that was lost, or that
-  * names an evicted or never-seen `sid`, resolves nothing, and
-  * attributing it anywhere else would relabel it. The `sid` is read
-  * structurally, so a JSON-revived copy of a record attributes exactly,
-  * and a hand-built record naming a retained session is honored.
+  * Resolves the session that a provenance record names. The record's `sid`
+  * must name one of this reporter's retained sessions, or the reporter
+  * discards the response. A record that names a removed or unknown `sid`
+  * resolves nothing. Any other attribution would be wrong. The reporter reads
+  * the `sid` as a plain property. A record
+  * copied through JSON therefore resolves the same session, and a hand-built
+  * record that names a retained session is accepted.
   */
   private resolveSession;
   /**
-  * Applies the CMCD request report data to the request. Called by the player
-  * before sending the request.
+  * Applies the CMCD request report data to the request. The player calls this
+  * method before sending the request.
   *
   * @param req - The request to apply the CMCD request report to.
   * @returns The request with the CMCD request report applied.
@@ -2784,50 +2821,51 @@ declare class CmcdReporter<C = Record<string, unknown>> {
   */
   applyRequestReport(req: HttpRequest): HttpRequest;
   /**
-  * Checks if the request reporting is enabled.
+  * Checks whether request reporting is enabled.
   *
-  * @returns `true` if the request reporting is enabled, `false` otherwise.
+  * @returns `true` if request reporting is enabled, `false` otherwise.
   */
   isRequestReportingEnabled(): boolean;
   /**
-  * The provenance record to stamp on a returned request: the session's
-  * frozen base record, extended with the caller's per-call data encoded
-  * as a CMCD string when there is any. Requests without per-call data
-  * share the base record, so decoration stays a single property write.
-  * The snapshot never contains reporter-stamped fields, and a value that
-  * cannot encode contributes no snapshot rather than failing the
-  * request; its response still attributes and reports derived keys over
-  * session data, matching `decodeSnapshot()`'s tolerance on the read
-  * side.
+  * The provenance record to write on a returned request. It is the session's
+  * frozen base record, extended with the caller's per-call data encoded as a
+  * CMCD string when there is any. Requests without per-call data share the
+  * base record, so the reporter writes only one property. The snapshot never
+  * contains reporter-written fields. A value that cannot encode contributes
+  * no snapshot and does not fail the request. The response still attributes
+  * and reports derived keys over session data, matching the tolerance of
+  * `decodeSnapshot()` when reading.
   */
   private createRequestProvenance;
   /**
-  * Creates a new request with the CMCD request report data applied. Called by the player
-  * before sending the request.
+  * Creates a new request with the CMCD request report data applied. The
+  * player calls this method before sending the request.
   *
-  * A reporter given a concrete `C` requires the request's `customData` to
-  * satisfy it, so a request the configured transform could not read is
-  * rejected here rather than reaching it; see
+  * A reporter with a concrete `C` requires the request's `customData` to
+  * satisfy that type. TypeScript therefore rejects a call whose request the
+  * configured transform could not read. See
   * {@link CmcdReporterCustomData}.
   *
-  * @typeParam R - The request being decorated. Its `customData` must satisfy
+  * @typeParam R - The type of the request. Its `customData` must satisfy
   *                the reporter's `C`.
   *
   * @param request - The request to apply the CMCD request report to.
   * @param data - The data to apply to the request. This data only
-  *               applies to this request report. Persistent data
-  *               should be updated using `update()`.
+  *               applies to this request report. Use `update()` for
+  *               persistent data.
   * @returns The request with the CMCD request report applied.
   */
   createRequestReport<R extends HttpRequest<CmcdReporterCustomData<C>> = HttpRequest<C>>(request: R, data?: Partial<Cmcd>): R & CmcdRequestReport<R["customData"]>;
   /**
-  * Processes the event targets. Called by the reporter when an event occurs.
+  * Processes the event targets. The reporter calls this method when an event
+  * occurs.
   *
   * @param flush - Whether to flush the event targets.
   */
   private processEventTargets;
   /**
-  * Sends an event report. Called by the reporter when a batch is ready to be sent.
+  * Sends an event report. The reporter calls this method when a batch is
+  * ready.
   *
   * @param config - The target config to send the event report to.
   * @param data - The encoded report lines to send in the event report.
@@ -2835,17 +2873,17 @@ declare class CmcdReporter<C = Record<string, unknown>> {
   private sendEventReport;
   /**
   * Cancels the time-interval timer for an event target config and clears the
-  * stored id. Safe to call when no timer is armed (clearInterval(undefined)
-  * is a no-op).
+  * stored id. Safe to call when no timer is active (clearInterval(undefined)
+  * does nothing).
   */
   private disarmInterval;
   /**
-  * Silences an event target URL for the remainder of its session: drops the
-  * queues and blocks further enqueues for every config in the session that
-  * reports to the URL, per CTA-5004-B's per-target-URL suppression scope,
-  * and cancels their timers when the session is the live one. Used when the
-  * collector signals the target is gone (HTTP 410). A session started after
-  * the disposal is unaffected, since it gets fresh target state.
+  * Silences an event target URL for the remainder of its session after the
+  * collector signals that the target is gone (HTTP 410). The method clears
+  * the queues and blocks further enqueues for every config in the session
+  * that reports to the URL (the CTA-5004-B suppression scope). For the
+  * current session, the method also cancels those configs' timers. A session
+  * started after the disposal gets new target state and is unaffected.
   */
   private disposeEventTarget;
 }
@@ -2858,7 +2896,7 @@ declare class CmcdReporter<C = Record<string, unknown>> {
 */
 type CmcdValidationOptions = {
   /**
-  * Explicit CMCD version override. If not provided, the version is
+  * Explicit CMCD version override. If omitted, the version is
   * inferred from the payload's `v` key, defaulting to 1.
   */
   version?: CmcdVersion;
@@ -2870,17 +2908,17 @@ type CmcdValidationOptions = {
 //#endregion
 //#region src/createFetchTransport.d.ts
 /**
-* Create a transport adapter that patches `globalThis.fetch` to capture
-* CMCD-bearing requests, normalizing each to `HttpRequest` (lowercase
-* headers, body read as UTF-8 string). Returns the adapter object
-* expected by `CmcdReportRecorder`.
-*
-* Bodies are read once via `Request.text()` for inspection. This is
-* safe for the body types CMCD reports use in practice (`string`,
-* `Blob`, `ArrayBuffer`, `FormData`, `URLSearchParams`), which can be
-* read by the wrapper and re-read by the underlying `fetch`. Passing
-* a `ReadableStream` as `init.body` is not supported — the stream is
-* consumed by the wrapper and the underlying `fetch` will receive an
+* Create a transport adapter for `CmcdReportRecorder` that patches
+* `globalThis.fetch` to capture requests with CMCD data. The patched
+* `fetch` normalizes each request to `HttpRequest` (lowercase headers,
+* body read as a UTF-8 string).
+*
+* The patched `fetch` reads each body once with `Request.text()` for
+* inspection. This read is safe for the body types that CMCD reports use
+* in practice: `string`, `Blob`, `ArrayBuffer`, `FormData`, and
+* `URLSearchParams`. The underlying `fetch` can read those bodies again.
+* Do not pass a `ReadableStream` as `init.body`. The patched `fetch`
+* consumes the stream, and the underlying `fetch` receives an
 * already-disturbed stream.
 *
 * @public
@@ -2889,9 +2927,8 @@ declare function createFetchTransport(): CmcdTransportAdapter;
 //#endregion
 //#region src/createXhrTransport.d.ts
 /**
-* Create a transport adapter that patches `XMLHttpRequest.prototype` to
-* capture CMCD-bearing requests. Returns the adapter object expected by
-* `CmcdReportRecorder`.
+* Create a transport adapter for `CmcdReportRecorder` that patches
+* `XMLHttpRequest.prototype` to capture requests with CMCD data.
 *
 * @public
 */
@@ -2980,9 +3017,9 @@ declare function fromCmcdQuery(query: string | URLSearchParams, options?: CmcdDe
 //#endregion
 //#region src/fromCmcdUrl.d.ts
 /**
-* Decode CMCD data from a url encoded string.
+* Decode CMCD data from a URL encoded string.
 *
-* @param url - The url encoded string to decode.
+* @param url - The URL encoded string to decode.
 * @param options - Options for decoding.
 *
 * @returns The decoded CMCD data.
@@ -3001,9 +3038,9 @@ declare function fromCmcdUrl(url: string, options?: CmcdDecodeOptions): CmcdData
 //#endregion
 //#region src/groupCmcdHeaders.d.ts
 /**
-* Group a CMCD data object into header shards
+* Group a CMCD object into header shards
 *
-* @param cmcd - The CMCD data object to convert.
+* @param cmcd - The CMCD object to convert.
 * @param customHeaderMap - A map of CMCD header fields to custom CMCD keys.
 *
 * @returns The CMCD header shards.
@@ -3017,9 +3054,9 @@ declare function groupCmcdHeaders(cmcd: Cmcd, customHeaderMap?: Partial<CmcdHead
 //#region src/isCmcdCustomKey.d.ts
 /**
 * Check if a key is a valid custom key: a lowercase first letter, then
-* characters from `a-z 0-9 . -`, with a hyphen that is neither the first
-* nor the last character. These are the CTA-5004-B custom-key rules
-* restricted to names that survive RFC 8941 key serialization.
+* characters from `a-z 0-9 . -`. The key needs a hyphen, not at the start
+* or end. This check applies the CTA-5004-B custom-key rules, restricted
+* to names that RFC 8941 key serialization accepts.
 *
 * @param key - The key to check.
 *
@@ -3068,7 +3105,7 @@ declare function isCmcdRequestKey(key: string): key is keyof Cmcd;
 *
 * @param key - The key to check.
 *
-* @returns `true` if the key is a valid CMCD request key, `false` otherwise.
+* @returns `true` if the key is a valid CMCD response key, `false` otherwise.
 *
 * @public
 *
@@ -3094,7 +3131,7 @@ declare function isCmcdV1Data(data: CmcdData): data is CmcdV1Data;
 //#endregion
 //#region src/isCmcdV1Key.d.ts
 /**
-* Filter function for CMCD v1 keys.
+* Filter for CMCD version 1 keys.
 *
 * @param key - The CMCD key to filter.
 *
@@ -3138,10 +3175,10 @@ declare function prepareCmcdData(obj: Record<string, any>, options?: CmcdEncodeO
 //#endregion
 //#region src/toCmcdHeaders.d.ts
 /**
-* Convert a CMCD data object to request headers
+* Convert a CMCD object to request headers
 *
-* @param cmcd - The CMCD data object to convert.
-* @param options - Options for encoding the CMCD object.
+* @param cmcd - The CMCD object to convert.
+* @param options - Options for encoding.
 *
 * @returns The CMCD header shards.
 *
@@ -3156,10 +3193,10 @@ declare function toCmcdHeaders(cmcd: Cmcd, options?: CmcdEncodeOptions): Record<
 //#endregion
 //#region src/toCmcdQuery.d.ts
 /**
-* Convert a CMCD data object to a query arg.
+* Convert a CMCD object to a query arg.
 *
 * @param cmcd - The CMCD object to convert.
-* @param options - Options for encoding the CMCD object.
+* @param options - Options for encoding.
 *
 * @returns The CMCD query arg.
 *
@@ -3174,10 +3211,10 @@ declare function toCmcdQuery(cmcd: Cmcd, options?: CmcdEncodeOptions): string;
 //#endregion
 //#region src/toCmcdUrl.d.ts
 /**
-* Convert a CMCD data object to a URL encoded string.
+* Convert a CMCD object to a URL encoded string.
 *
 * @param cmcd - The CMCD object to convert.
-* @param options - Options for encoding the CMCD object.
+* @param options - Options for encoding.
 *
 * @returns The URL encoded CMCD data.
 *
@@ -3192,7 +3229,7 @@ declare function toCmcdUrl(cmcd: Cmcd, options?: CmcdEncodeOptions): string;
 * Convert a value to a CMCD value.
 *
 * @param value - The value to convert to a CMCD value.
-* @param params - The parameters to convert to a CMCD value.
+* @param params - The parameters of the CMCD value.
 * @returns The CMCD value.
 *
 * @public
@@ -3223,8 +3260,8 @@ declare function validateCmcd(data: Record<string, unknown>, options?: CmcdValid
 * Accepts an {@link @svta/cml-utils!HttpRequest | HttpRequest} object.
 *
 * This function validates that the request uses the POST method and has
-* the correct `Content-Type` header (`application/cmcd`) in addition to
-* validating the body content via {@link validateCmcdEvents}.
+* the correct `Content-Type` header (`application/cmcd`). It also
+* validates the body content with {@link validateCmcdEvents}.
 *
 * @param request - An `HttpRequest` to validate.
 * @param options - Validation options (excluding `reportingMode`).
@@ -3244,8 +3281,8 @@ declare function validateCmcdEventReport(request: HttpRequest, options?: Omit<Cm
 *
 * This function decodes the string internally and validates it with
 * `reportingMode` set to `'event'`. The input may contain multiple
-* newline-separated events (e.g. an `application/cmcd` POST body), in which
-* case each line is validated independently and the results are merged.
+* newline-separated events, for example an `application/cmcd` POST body.
+* The function validates each line independently and merges the results.
 *
 * @param cmcd - The raw CMCD-encoded string to validate. May contain
 *   multiple newline-separated event lines.
@@ -3265,15 +3302,15 @@ declare function validateCmcdEvents(cmcd: string, options?: Omit<CmcdValidationO
 /**
 * Validates CMCD HTTP headers by checking shard placement and payload validity.
 *
-* This function accepts raw CMCD header strings, decodes each shard
-* internally, verifies that each key is placed in its correct header shard,
-* then merges all shards and runs full payload validation (keys, values, and
-* structure) on the merged data.
+* This function accepts raw CMCD header strings and decodes each shard
+* internally. It verifies that each key is in its correct header shard.
+* The function then merges all shards and runs payload validation (keys,
+* values, and structure) on the merged data.
 *
 * @example
 * {@includeCode ../test/validateCmcdHeaders.test.ts#example}
 *
-* @param headers - A `Headers` instance or a record of CMCD header fields to their raw encoded string values.
+* @param headers - A `Headers` instance or a record of CMCD header fields to raw encoded strings.
 * @param options - Validation options (excluding `reportingMode`).
 * @returns The validation result including decoded data.
 *
@@ -3308,10 +3345,12 @@ declare function validateCmcdKeys(data: Record<string, unknown>, options?: CmcdV
 * {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request}
 * object or an {@link @svta/cml-utils!HttpRequest | HttpRequest} object.
 *
-* The function checks for CMCD data in the HTTP headers first. If CMCD
-* headers are found, validation includes shard-placement checks via
-* {@link validateCmcdHeaders}. Otherwise, the CMCD query parameter is
-* extracted from the URL and validated.
+* The function checks the HTTP headers for CMCD data first. If the
+* request has CMCD headers, {@link validateCmcdHeaders} validates them,
+* including shard placement. Otherwise, the function validates the CMCD
+* query parameter of the URL. A request with CMCD data in both the
+* headers and the `CMCD` query parameter is an error. The function still
+* validates the headers and returns their data.
 *
 * @param request - A `Request` or `HttpRequest` to validate.
 * @param options - Validation options (excluding `reportingMode`).