@svta/cml-cmcd 2.6.1 → 2.7.0

package/dist/index.js

@@ -1,6 +1,23 @@
 import { SfItem, SfToken, decodeSfDict, encodeSfDict, symbolToStr } from "@svta/cml-structured-field-values";
 import { getBaseUrl, urlToRelativePath, uuid } from "@svta/cml-utils";
 
+//#region src/CMCD_AGGREGATE_BITRATE_KEYS.ts
+/**
+* Maps each aggregate bitrate key to the exact bitrate key that supersedes it.
+*
+* Per CTA-5004-B, `ab` MUST NOT be sent when the encoded bitrate `br` is
+* known. `lab` and `tab` follow the same rule for the lowest bitrate `lb`
+* and the top bitrate `tb`.
+*
+* @internal
+*/
+const CMCD_AGGREGATE_BITRATE_KEYS = {
+	ab: "br",
+	lab: "lb",
+	tab: "tb"
+};
+
+//#endregion
 //#region src/CMCD_FORMATTER_MAP.ts
 const roundValue = (value) => {
 	if (value instanceof SfItem) return new SfItem(Math.round(value.value), value.params);
@@ -50,6 +67,34 @@ const CMCD_FORMATTER_MAP = {
 	tb: toRounded
 };
 
+//#endregion
+//#region src/CMCD_KEY_OBJECT_TYPES.ts
+/**
+* Maps a key to the object types (`ot`) for which CTA-5004-B allows the key.
+*
+* A key that is absent from this map is allowed for every object type.
+* `d` (Object duration) and `tpb` (Top playable bitrate) MUST NOT be sent for
+* other object types.
+*
+* @internal
+*/
+const CMCD_KEY_OBJECT_TYPES = {
+	d: [
+		"a",
+		"v",
+		"av",
+		"tt",
+		"c",
+		"o"
+	],
+	tpb: [
+		"a",
+		"v",
+		"av",
+		"c"
+	]
+};
+
 //#endregion
 //#region src/CMCD_V2.ts
 /**
@@ -62,109 +107,109 @@ const CMCD_V2 = 2;
 //#endregion
 //#region src/CmcdEventType.ts
 /**
-* CMCD event type for the 'bc' key (bitrate change).
+* CMCD event type 'bc' (bitrate change).
 *
 * @public
 */
 const CMCD_EVENT_BITRATE_CHANGE = "bc";
 /**
-* CMCD event type for the 'ps' key (play state change).
+* CMCD event type 'ps' (play state change).
 *
 * @public
 */
 const CMCD_EVENT_PLAY_STATE = "ps";
 /**
-* CMCD event type for the 'pr' key (playback rate change).
+* CMCD event type 'pr' (playback rate change).
 *
 * @public
 */
 const CMCD_EVENT_PLAYBACK_RATE = "pr";
 /**
-* CMCD event type for the 'e' key (error).
+* CMCD event type 'e' (error).
 *
 * @public
 */
 const CMCD_EVENT_ERROR = "e";
 /**
-* CMCD event type for the 't' key (time interval).
+* CMCD event type 't' (time interval).
 *
 * @public
 */
 const CMCD_EVENT_TIME_INTERVAL = "t";
 /**
-* CMCD event type for the 'c' key (content ID).
+* CMCD event type 'c' (content ID).
 *
 * @public
 */
 const CMCD_EVENT_CONTENT_ID = "c";
 /**
-* CMCD event type for the 'b' key (backgrounded mode).
+* CMCD event type 'b' (backgrounded mode).
 *
 * @public
 */
 const CMCD_EVENT_BACKGROUNDED_MODE = "b";
 /**
-* CMCD event type for the 'm' key (mute).
+* CMCD event type 'm' (mute).
 *
 * @public
 */
 const CMCD_EVENT_MUTE = "m";
 /**
-* CMCD event type for the 'um' key (unmute).
+* CMCD event type 'um' (unmute).
 *
 * @public
 */
 const CMCD_EVENT_UNMUTE = "um";
 /**
-* CMCD event type for the 'pe' key (player expand).
+* CMCD event type 'pe' (player expand).
 *
 * @public
 */
 const CMCD_EVENT_PLAYER_EXPAND = "pe";
 /**
-* CMCD event type for the 'pc' key (player collapse).
+* CMCD event type 'pc' (player collapse).
 *
 * @public
 */
 const CMCD_EVENT_PLAYER_COLLAPSE = "pc";
 /**
-* CMCD event type for the 'rr' key (response received).
+* CMCD event type 'rr' (response received).
 *
 * @public
 */
 const CMCD_EVENT_RESPONSE_RECEIVED = "rr";
 /**
-* CMCD event type for the 'as' key (ad start).
+* CMCD event type 'as' (ad start).
 *
 * @public
 */
 const CMCD_EVENT_AD_START = "as";
 /**
-* CMCD event type for the 'ae' key (ad end).
+* CMCD event type 'ae' (ad end).
 *
 * @public
 */
 const CMCD_EVENT_AD_END = "ae";
 /**
-* CMCD event type for the 'abs' key (ad break start).
+* CMCD event type 'abs' (ad break start).
 *
 * @public
 */
 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
 */
 const CMCD_EVENT_AD_BREAK_END = "abe";
 /**
-* CMCD event type for the 'sk' key (skip).
+* CMCD event type 'sk' (skip).
 *
 * @public
 */
 const CMCD_EVENT_SKIP = "sk";
 /**
-* CMCD event type for the 'ce' key (custom event).
+* CMCD event type 'ce' (custom event).
 *
 * @public
 */
@@ -206,13 +251,13 @@ const CmcdEventType = {
 * the event signals.
 *
 * Per CTA-5004-B, the state-change events `ps`, `pr`, `c`, `b`, `bc` are
-* state-transition markers and must carry the field whose value they signal.
-* Consumers force-include the field post-filter (`prepareCmcdData`), dedup
-* against its value (`CmcdReporter`), and check its presence in payloads
-* (`validateCmcdStructure`).
+* state-transition markers. Each event must include the field whose value
+* it signals. Callers force-include the field after filtering
+* (`prepareCmcdData`), deduplicate against its value (`CmcdReporter`), and
+* check its presence in payloads (`validateCmcdStructure`).
 *
-* Iteration order is load-bearing: `CmcdReporter.update()` fires state-change
-* events in map order when multiple tracked fields change in a single call.
+* Iteration order matters: `CmcdReporter.update()` records state-change
+* events in map order when several tracked fields change in one call.
 * Do not reorder entries without auditing reporter behavior.
 *
 * @internal
@@ -318,9 +363,9 @@ const CMCD_REQUEST_KEYS = [
 const CUSTOM_KEY_REGEX = /^[a-z][a-z0-9.-]*$/;
 /**
 * 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.
 *
@@ -358,7 +403,7 @@ function isCmcdRequestKey(key) {
 //#endregion
 //#region src/CMCD_RESPONSE_KEYS.ts
 /**
-* CMCD v2 - Response-only and timing keys.
+* Response-only and timing keys for version 2.
 *
 * @public
 */
@@ -381,7 +426,7 @@ const CMCD_RESPONSE_KEY_SET = /* @__PURE__ */ new Set(CMCD_RESPONSE_KEYS);
 *
 * @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
 *
@@ -414,7 +459,7 @@ function isCmcdEventKey(key) {
 //#endregion
 //#region src/CMCD_INNER_LIST_KEYS.ts
 /**
-* Keys that are inner lists in V2 but plain scalars in V1.
+* Inner-list keys in version 2 that are scalars in version 1.
 *
 * Used by both encoding (down-conversion) and decoding (up-conversion).
 *
@@ -469,7 +514,7 @@ const CMCD_V1_KEYS = [
 //#region src/isCmcdV1Key.ts
 const CMCD_V1_KEY_SET$1 = /* @__PURE__ */ new Set(CMCD_V1_KEYS);
 /**
-* Filter function for CMCD v1 keys.
+* Filter for CMCD version 1 keys.
 *
 * @param key - The CMCD key to filter.
 *
@@ -509,16 +554,21 @@ function isTokenField(key) {
 //#endregion
 //#region src/isValid.ts
 /**
-* Checks if the given value is valid
+* Checks if the given value is valid to send as a CMCD value.
+*
+* `undefined`, `null`, an empty string, `false`, an empty array, and a
+* number that is not finite are not valid. CTA-5004-B requires omitting
+* the key when its value is unknown.
 *
 * @param value - The value to check.
 *
-* @returns `true` if the key is a value is valid.
+* @returns `true` if the value is valid.
 *
 * @internal
 */
 function isValid(value) {
 	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.length > 0;
 	return value != null && value !== "" && value !== false;
 }
 
@@ -528,7 +578,7 @@ function isValid(value) {
 * Resolve the text of a token value.
 *
 * A token may be a plain string, a registry `Symbol`, an `SfToken`, or an
-* `SfItem` that wraps one of those.
+* `SfItem` that wraps such a value.
 *
 * @param value - The value to resolve.
 *
@@ -545,11 +595,11 @@ function toTokenString(value) {
 //#endregion
 //#region src/prepareCmcdData.ts
 const filterMap = {
-	[CMCD_EVENT_MODE]: isCmcdEventKey,
-	[CMCD_REQUEST_MODE]: isCmcdRequestKey
+	event: isCmcdEventKey,
+	request: isCmcdRequestKey
 };
 /**
-* Unwrap an inner list or SfItem value to a plain scalar.
+* Unwrap an inner list or SfItem value to a scalar.
 */
 function unwrapValue(value, ot) {
 	if (Array.isArray(value)) {
@@ -563,10 +613,10 @@ function unwrapValue(value, ot) {
 	return value;
 }
 /**
-* Down-convert V2 CMCD data to V1 format.
+* Down-convert version 2 CMCD data to version 1.
 *
-* - Extracts `nrr` from `nor` SfItem `r` parameter.
-* - Unwraps inner-list values to plain scalars.
+* - Extracts `nrr` from the `nor` SfItem's `r` parameter.
+* - Unwraps inner-list values to scalars.
 */
 function downConvertToV1(obj) {
 	const result = {};
@@ -586,6 +636,10 @@ function downConvertToV1(obj) {
 	}
 	return result;
 }
+function formatValue(key, value, options, formatterOptions) {
+	const formatter = options.formatters?.[key] ?? CMCD_FORMATTER_MAP[key];
+	return typeof formatter === "function" && isValid(value) ? formatter(value, formatterOptions) : value;
+}
 /**
 * Convert a generic object to CMCD data.
 *
@@ -627,10 +681,23 @@ function prepareCmcdData(obj, options = {}) {
 		baseUrl: options.baseUrl
 	};
 	keys.sort();
+	let objectType;
+	let objectTypeResolved = false;
 	for (const key of keys) {
 		let value = data[key];
-		const formatter = options.formatters?.[key] ?? CMCD_FORMATTER_MAP[key];
-		if (typeof formatter === "function") value = formatter(value, formatterOptions);
+		const exactKey = CMCD_AGGREGATE_BITRATE_KEYS[key];
+		if (exactKey && keys.includes(exactKey) && isValid(formatValue(exactKey, data[exactKey], options, formatterOptions))) continue;
+		const objectTypes = version > 1 ? CMCD_KEY_OBJECT_TYPES[key] : void 0;
+		if (objectTypes) {
+			if (!objectTypeResolved) {
+				const ot = formatValue("ot", data["ot"], options, formatterOptions);
+				objectType = isValid(ot) ? toTokenString(ot) : void 0;
+				objectTypeResolved = true;
+			}
+			if (objectType !== void 0 && !objectTypes.includes(objectType)) continue;
+		}
+		if (key === "cen" && eventType !== CMCD_EVENT_CUSTOM_EVENT) continue;
+		value = formatValue(key, value, options, formatterOptions);
 		if (key === "v") if (version === 1) continue;
 		else value = version;
 		if (key === "pr" && value === 1 && !(isEventMode && eventType === CMCD_EVENT_PLAYBACK_RATE)) continue;
@@ -703,9 +770,9 @@ const CMCD_HEADER_FIELDS = [
 /**
 * 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
 */
@@ -760,9 +827,9 @@ function createHeaderMap(headerMap) {
 	}, {});
 }
 /**
-* 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.
@@ -808,10 +875,10 @@ function toPreparedCmcdHeaders(data, customHeaderMap) {
 //#endregion
 //#region src/toCmcdHeaders.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.
 *
@@ -830,13 +897,13 @@ function toCmcdHeaders(cmcd, options = {}) {
 //#endregion
 //#region src/appendCmcdHeaders.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
 *
@@ -897,10 +964,10 @@ function encodeCmcd(cmcd, options = {}) {
 //#endregion
 //#region src/toCmcdUrl.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.
 *
@@ -917,10 +984,10 @@ function toCmcdUrl(cmcd, options = {}) {
 //#endregion
 //#region src/toCmcdQuery.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.
 *
@@ -944,7 +1011,7 @@ const REGEX = /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.
 *
@@ -965,7 +1032,7 @@ function appendCmcdQuery(url, cmcd, options) {
 //#endregion
 //#region src/CMCD_DEFAULT_TIME_INTERVAL.ts
 /**
-* The default time interval in seconds when using using event mode
+* The default time interval in seconds when using event mode
 *
 * @public
 */
@@ -997,25 +1064,26 @@ const CMCD_MIME_TYPE = "application/cmcd";
 //#endregion
 //#region src/CMCD_REQUEST_PROVENANCE.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
 */
@@ -1056,7 +1124,7 @@ const CmcdObjectType = {
 //#endregion
 //#region src/CmcdPlayerState.ts
 /**
-* CMCD v2 player states for the 'sta' key.
+* CMCD version 2 player states for the 'sta' key.
 *
 *
 * @enum
@@ -1081,29 +1149,29 @@ const CmcdPlayerState = {
 //#endregion
 //#region src/CmcdRecordedReportMode.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
 */
 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
 */
 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
 */
 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
 *
@@ -1137,7 +1205,7 @@ const CMCD_RECORDED_REQUEST_TYPE_SEGMENT = "segment";
 */
 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
@@ -1179,17 +1247,17 @@ async function toHttpRequest(request) {
 	};
 }
 /**
-* 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
@@ -1255,9 +1323,8 @@ async function completeXhrWith(xhr, response) {
 	});
 }
 /**
-* 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
 */
@@ -1320,10 +1387,10 @@ function detectReportingMode(url, headers, isEventTarget) {
 	return url.includes(`${CMCD_PARAM}=`) ? "query" : null;
 }
 /**
-* 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}
@@ -1391,11 +1458,11 @@ var CmcdReportRecorder = class {
 		});
 	}
 	/**
-	* 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
 	*/
@@ -1436,7 +1503,7 @@ var CmcdReportRecorder = class {
 		this.#reports = [];
 	}
 	/**
-	* Return a defensive copy of all recorded reports.
+	* Return a copy of all recorded reports.
 	*
 	* @public
 	*/
@@ -1445,8 +1512,8 @@ var CmcdReportRecorder = class {
 	}
 	/**
 	* 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
@@ -1456,8 +1523,8 @@ var CmcdReportRecorder = class {
 	}
 	/**
 	* 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
@@ -1467,8 +1534,8 @@ var CmcdReportRecorder = class {
 	}
 	/**
 	* 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
@@ -1478,8 +1545,8 @@ var CmcdReportRecorder = class {
 	}
 	/**
 	* 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
@@ -1527,12 +1594,12 @@ const CmcdTransmissionMode = {
 //#endregion
 //#region src/upConvertToV2.ts
 /**
-* Up-convert V1 CMCD data to V2 format.
+* Up-convert version 1 CMCD data to version 2.
 *
-* - Wraps plain scalar values in arrays for inner-list keys.
+* - Wraps scalar values in arrays for inner-list keys.
 * - Wraps `nor` string in an array.
 *
-* If the data is already V2 (has `v: 2`), it is returned unchanged.
+* The function returns version 2 data (has `v: 2`) unchanged.
 *
 * @internal
 */
@@ -1581,12 +1648,11 @@ function createEncodingOptions(reportingMode, config, baseUrl) {
 	};
 }
 /**
-* Deep equality for CmcdObjectTypeList (used for `br` dedup).
+* Deep equality for CmcdObjectTypeList (used for `br` deduplication).
 *
-* Order-sensitive: arrays with the same elements in different positions
-* are treated as different. Players that construct `br` consistently
-* get correct dedup; shuffling produces spurious emits, which is the
-* safer failure mode.
+* Arrays with the same elements in different positions count as different.
+* Players that construct `br` consistently get correct deduplication.
+* Reordered arrays produce extra events, which is the safer failure.
 */
 function cmcdObjectTypeListEqual(a, b) {
 	if (a === b) return true;
@@ -1627,26 +1693,30 @@ const STATE_FIELDS = /* @__PURE__ */ Array.from(CMCD_STATE_EVENT_FIELDS, ([event
 	};
 });
 const STATE_FIELDS_BY_EVENT = /* @__PURE__ */ new Map(/* @__PURE__ */ STATE_FIELDS.map((e) => [e.event, e]));
+function buildRequiredEventKeys() {
+	return new Map([
+		...CMCD_STATE_EVENT_FIELDS,
+		[CMCD_EVENT_CUSTOM_EVENT, "cen"],
+		[CMCD_EVENT_ERROR, "ec"],
+		[CMCD_EVENT_RESPONSE_RECEIVED, "url"]
+	]);
+}
 /**
 * Maps each event type to the key CTA-5004-B requires beyond `e` and `ts`.
 * Built from the state-change table plus the three event types whose
-* required key rides the caller's per-event data.
+* required key is event data, not player state.
 */
-const CMCD_REQUIRED_EVENT_KEYS = /* @__PURE__ */ new Map([
-	...CMCD_STATE_EVENT_FIELDS,
-	[CMCD_EVENT_CUSTOM_EVENT, "cen"],
-	[CMCD_EVENT_ERROR, "ec"],
-	[CMCD_EVENT_RESPONSE_RECEIVED, "url"]
-]);
+const CMCD_REQUIRED_EVENT_KEYS = /* @__PURE__ */ buildRequiredEventKeys();
 /**
 * Whether a required key's value will survive report preparation.
 *
-* This is `isValid` minus its `false` exclusion, plus an empty-array check.
-* `false` must count as usable because `bg: false` is a legitimate value on a
-* backgrounded-mode event, which the encoder emits as `?0`; treating it as
-* unusable would let restoration silently revert a transform that cleared it.
-* Empty strings, empty lists and non-finite numbers are dropped downstream, so
-* a transform substituting one leaves the report short a required key.
+* This is `isValid` without its `false` exclusion. `false` must count as
+* usable because `bg: false` is a valid value on a backgrounded-mode event,
+* which the encoder writes as `?0`. If `false` counted as unusable,
+* restoration would silently revert a transform that cleared the key.
+* Later processing drops empty strings, empty lists, and non-finite numbers.
+* A transform that substitutes one of them leaves the report without a
+* required key.
 */
 function isUsableRequiredValue(value) {
 	if (value == null || value === "") return false;
@@ -1654,12 +1724,12 @@ function isUsableRequiredValue(value) {
 	return !Array.isArray(value) || value.length > 0;
 }
 /**
-* Copies an `SfItem`-shaped value and its `params` record.
+* Copies a value with the `SfItem` structure, including its `params` record.
 *
-* The prototype is preserved because `prepareCmcdData`, the formatter map,
+* The copy keeps the prototype because `prepareCmcdData`, the formatter map,
 * validation, and the structured-field encoder all branch on
 * `instanceof SfItem`. A plain spread (and `structuredClone`) would return a
-* prototype-less object and silently change what goes on the wire.
+* prototype-less object and silently change the encoded output.
 */
 function copyItemValue(value) {
 	if (value === null || typeof value !== "object") return value;
@@ -1668,16 +1738,16 @@ function copyItemValue(value) {
 	return copy;
 }
 /**
-* Copies the nested values of a report in place so a transform cannot mutate
-* the reporter's persistent data, or another target's report for the same
-* event, by mutating an array or an `SfItem` it was handed.
+* Copies the nested values of a report in place. A transform cannot mutate
+* the reporter's data store, or another target's report for the same event,
+* through an array or an `SfItem` it received.
 *
-* Complete for the CMCD value space rather than best-effort: `CmcdValue` and
+* The copy is complete for the CMCD value space. `CmcdValue` and
 * `CmcdCustomValue` admit only primitives, `SfItem<primitive>`, and arrays of
-* those, and `SfItem.params` is a flat record. Called where a transform is
-* configured, on the ended session's store at archival (detaching the frozen
-* snapshot from caller-held references), and on the request's stored
-* player-facing view.
+* those. `SfItem.params` is a flat record. The reporter calls this function
+* where a transform is configured, at session end on the ended session's
+* store, and on the request's stored player-facing view. The session-end
+* copy detaches the frozen snapshot from caller-held references.
 */
 function copyReportValues(data) {
 	const record = data;
@@ -1692,14 +1762,13 @@ function copyReportValues(data) {
 	return data;
 }
 /**
-* Decodes the per-call data snapshot a provenance record carries into
-* fresh, encodable report data: tokens revive as `SfToken` and
-* params-bearing items as `SfItem` (`useSymbol: false`), so every value
-* keeps its wire type through re-encoding. Only called in
-* `recordResponseReceived()`. Returns an empty object when the record is
-* absent, carries no snapshot, or the snapshot does not parse (a value
-* this reporter did not write); the response then reports its derived keys
-* over the session's data alone.
+* Decodes the per-call data snapshot of a provenance record into new,
+* encodable report data. Tokens decode as `SfToken` and items with params
+* as `SfItem` (`useSymbol: false`), so every value re-encodes with its
+* original type. Only `recordResponseReceived()` calls this function.
+* Returns an empty object when the record is absent, has no snapshot, or
+* the snapshot does not parse (a value this reporter did not write). The
+* response then reports its derived keys over the session's data alone.
 */
 function decodeSnapshot(provenance) {
 	const encoded = provenance !== null && typeof provenance === "object" ? provenance.data : void 0;
@@ -1711,10 +1780,10 @@ function decodeSnapshot(provenance) {
 	}
 }
 /**
-* Mints a session's frozen base provenance record: the issuing `sid`, and
-* the `cid` in effect at mint time. `update()` re-mints on every `cid`
-* change, so requests issued before a mid-session content change keep the
-* `cid` they were issued under while later requests carry the new one.
+* Creates a session's frozen base provenance record: the issuing `sid`, and
+* the `cid` that is current at creation time. `update()` creates a new record
+* on every `cid` change. Requests issued before a mid-session content change
+* keep their original `cid`, while later requests get the new one.
 */
 function mintProvenance(sid, cid) {
 	return Object.freeze(typeof cid === "string" && cid ? {
@@ -1753,12 +1822,12 @@ function createCmcdReporterConfig(config) {
 /**
 * 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}
@@ -1770,7 +1839,7 @@ var CmcdReporter = class {
 	* 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.
 	*/
@@ -1788,8 +1857,8 @@ var CmcdReporter = class {
 		this.requester = requester;
 	}
 	/**
-	* 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.
 	*/
 	createSession(sid, data) {
 		const eventTargets = /* @__PURE__ */ new Map();
@@ -1813,11 +1882,12 @@ var CmcdReporter = class {
 		};
 	}
 	/**
-	* 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() {
 		this.started = true;
@@ -1836,9 +1906,9 @@ var CmcdReporter = class {
 		if (failure) throw failure.error;
 	}
 	/**
-	* 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.
 	*/
 	armInterval(config) {
 		if (config.interval === 0 || !config.events.includes(CMCD_EVENT_TIME_INTERVAL)) return false;
@@ -1853,7 +1923,8 @@ var CmcdReporter = class {
 		return true;
 	}
 	/**
-	* 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.
 	*/
@@ -1863,8 +1934,8 @@ var CmcdReporter = class {
 		for (const config of this.config.eventTargets) this.disarmInterval(config);
 	}
 	/**
-	* 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() {
@@ -1873,40 +1944,38 @@ var CmcdReporter = class {
 	/**
 	* 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.
+	* 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.
 	*
-	* 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.
+	* 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.
 	*
-	* 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 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 dedup baseline.
+	* A `sid` change resets the deduplication 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
+	* `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. Response
+	* attribution uses the provenance record alone.
 	* `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.
 	*/
@@ -1928,19 +1997,20 @@ var CmcdReporter = class {
 		for (const entry of STATE_FIELDS) if (entry.field in data && !entry.equal(session.data[entry.field], session.lastEmitted[entry.field])) this.recordEvent(entry.event);
 	}
 	/**
-	* 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.
+	* 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 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.
+	* 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.
 	*/
 	startSession(sid) {
 		this.session.data = copyReportValues({ ...this.session.data });
@@ -1957,59 +2027,57 @@ var CmcdReporter = class {
 		}
 	}
 	/**
-	* 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).
+	* 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 })`).
+	*    A state-change event without its required field would violate CTA-5004-B.
+	* 3. Suppresses the event if the field's current value equals the
+	*    last reported value (no state transition).
 	*
-	* For all other event types, the event is always emitted.
+	* The reporter always records all other event types.
 	*
-	* 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.
+	* 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.
 	*
-	* 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.
+	* 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, data = {}) {
 		this.emitEvent(this.session, type, data);
 	}
 	/**
-	* 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`.
 	*/
 	emitEvent(session, type, data, request) {
 		const entry = STATE_FIELDS_BY_EVENT.get(type);
@@ -2034,16 +2102,17 @@ var CmcdReporter = class {
 		if (failure) throw failure.error;
 	}
 	/**
-	* 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.
 	*/
 	recordTargetEvent(session, target, config, type, data = {}, request) {
 		if (target.disposed || !config.events.includes(type)) return;
@@ -2070,15 +2139,14 @@ var CmcdReporter = class {
 		this.queueTargetEvent(session, target, config, report, type);
 	}
 	/**
-	* 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.
@@ -2096,10 +2164,10 @@ var CmcdReporter = class {
 		target.queue.push(encodeCmcd(report, createEncodingOptions(CMCD_EVENT_MODE, config)));
 	}
 	/**
-	* 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
@@ -2107,50 +2175,50 @@ var CmcdReporter = class {
 	* - `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.
+	* 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
-	* 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.
+	* 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 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}.
+	* 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 event is attributed to the session that issued the request, and to
-	* nothing else: the provenance record that
+	* The reporter attributes the event only to the session that issued the
+	* request. 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.
+	* `customData` (under {@link CMCD_REQUEST_PROVENANCE}) selects the session
+	* by `sid`. Without a match, the reporter discards the response rather than
+	* attributing it elsewhere. There is no other key. The reporter discards the
+	* response when a serialization boundary lost the record and nothing
+	* restored it (see {@link CMCD_REQUEST_PROVENANCE}). It also discards the
+	* response when the session is no longer retained (see
+	* `CmcdReporterConfig.sessionRetention`). 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. 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.
+	* 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` this request carries. Defaults to the
+	* @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. Attribution uses the provenance record alone.
 	*/
 	recordResponseReceived(response, data = {}) {
 		const { request } = response;
@@ -2183,13 +2251,13 @@ var CmcdReporter = class {
 		}, request);
 	}
 	/**
-	* 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 a response belongs to. The provenance record's `sid`
+	* must name one of this reporter's retained sessions, or the reporter
+	* discards the response. There is no other key. A lost record, or one 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.
 	*/
 	resolveSession(provenance) {
 		if (provenance === null || typeof provenance !== "object") return;
@@ -2197,8 +2265,8 @@ var CmcdReporter = class {
 		return typeof sid === "string" ? this.sessions.get(sid) : void 0;
 	}
 	/**
-	* 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.
@@ -2209,23 +2277,22 @@ var CmcdReporter = class {
 		return this.createRequestReport(req) ?? req;
 	}
 	/**
-	* 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() {
 		return !!this.config.enabledKeys?.length;
 	}
 	/**
-	* 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.
 	*/
 	createRequestProvenance(data, baseUrl) {
 		const base = this.session.provenance;
@@ -2245,21 +2312,21 @@ var CmcdReporter = class {
 		}
 	}
 	/**
-	* 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(request, data) {
@@ -2311,7 +2378,8 @@ var CmcdReporter = class {
 		return report;
 	}
 	/**
-	* 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.
 	*/
@@ -2334,7 +2402,8 @@ var CmcdReporter = class {
 		if (reprocess) this.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.
@@ -2344,27 +2413,27 @@ var CmcdReporter = class {
 			url: config.url,
 			method: "POST",
 			headers: { "Content-Type": CMCD_MIME_TYPE },
-			body: data.join("\n") + "\n"
+			body: data.join("\n")
 		});
 		if (status === 410) this.disposeEventTarget(session, config);
 		else if (status === 429 || status > 499 && status < 600) throw new Error(`Event report failed with status ${status}`);
 	}
 	/**
 	* 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).
 	*/
 	disarmInterval(config) {
 		clearInterval(this.intervals.get(config));
 		this.intervals.delete(config);
 	}
 	/**
-	* 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.
 	*/
 	disposeEventTarget(session, config) {
 		session.eventTargets.forEach((target, sibling) => {
@@ -2517,7 +2586,7 @@ function isCmcdV2Data(data) {
 * 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
@@ -2544,7 +2613,7 @@ function mergeValidationResults(...results) {
 //#endregion
 //#region src/resolveVersion.ts
 /**
-* Resolves the CMCD version from explicit options, the payload's `v` key, or the default (v1).
+* Resolves the CMCD version from options, the payload's `v` key, or the default (version 1).
 *
 * @internal
 */
@@ -2669,6 +2738,23 @@ function validateCmcdStructure(data, options) {
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
 		});
 	}
+	const ot = version > 1 ? toTokenString(data["ot"]) : void 0;
+	if (ot !== void 0) for (const key in CMCD_KEY_OBJECT_TYPES) {
+		const objectTypes = CMCD_KEY_OBJECT_TYPES[key];
+		if (key in data && !objectTypes.includes(ot)) issues.push({
+			key,
+			message: `Key "${key}" must not be present when "ot" is "${ot}". Expected "ot" to be one of: ${objectTypes.join(", ")}.`,
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+	}
+	if (version > 1) for (const key in CMCD_AGGREGATE_BITRATE_KEYS) {
+		const exactKey = CMCD_AGGREGATE_BITRATE_KEYS[key];
+		if (key in data && exactKey in data) issues.push({
+			key,
+			message: `Key "${key}" must not be present when "${exactKey}" is present.`,
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+	}
 	if ("v" in data && data["v"] !== 1 && data["v"] !== 2) issues.push({
 		key: "v",
 		message: `Unsupported CMCD version "${String(data["v"])}". Expected 1 or 2.`,
@@ -2735,8 +2821,8 @@ const CMCD_KEY_TYPE_STRING = "string";
 */
 const CMCD_KEY_TYPE_TOKEN = "token";
 /**
-* Maps each CMCD spec key to its expected value type for v2.
-* Keys that differ between v1 and v2 are handled by CMCD_V1_KEY_TYPE_OVERRIDES.
+* Maps each CMCD key to its value type for version 2.
+* CMCD_V1_KEY_TYPE_OVERRIDES handles the keys that differ between version 1 and version 2.
 *
 * @internal
 */
@@ -2794,7 +2880,7 @@ const CMCD_KEY_TYPES = {
 	sta: CMCD_KEY_TYPE_TOKEN
 };
 /**
-* Maps keys to their v1-specific types when they differ from v2.
+* Version 1 types of the keys that differ from version 2.
 *
 * @internal
 */
@@ -3098,8 +3184,8 @@ function validateCmcd(data, options) {
 *
 * 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.
@@ -3127,6 +3213,11 @@ function validateCmcdEvents(cmcd, options) {
 		}],
 		data: []
 	};
+	const bodyIssues = [];
+	if (cmcd.endsWith("\n")) bodyIssues.push({
+		message: "Event report body must not end with a line feed.",
+		severity: CMCD_VALIDATION_SEVERITY_ERROR
+	});
 	const decodedLines = [];
 	const lineResults = [];
 	for (let i = 0; i < lines.length; i++) try {
@@ -3144,7 +3235,10 @@ function validateCmcdEvents(cmcd, options) {
 		});
 	}
 	return {
-		...mergeValidationResults(...lineResults),
+		...mergeValidationResults({
+			valid: true,
+			issues: bodyIssues
+		}, ...lineResults),
 		data: decodedLines
 	};
 }
@@ -3157,8 +3251,8 @@ function validateCmcdEvents(cmcd, options) {
 * 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`).
@@ -3224,15 +3318,15 @@ function validateCmcdEventReport(request, options) {
 /**
 * 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.
 *
@@ -3292,10 +3386,12 @@ function validateCmcdHeaders(headers, options) {
 * {@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`).
@@ -3310,12 +3406,25 @@ function validateCmcdHeaders(headers, options) {
 */
 function validateCmcdRequest(request, options) {
 	const headers = extractHeaderRecord(request.headers);
-	if (headers) return validateCmcdHeaders(headers, options);
-	const param = new URL(request.url).searchParams.get(CMCD_PARAM);
+	const param = getCmcdQueryParam(request.url);
+	if (headers) {
+		const result = validateCmcdHeaders(headers, options);
+		if (!param) return result;
+		return {
+			...mergeValidationResults({
+				valid: false,
+				issues: [{
+					message: "CMCD data found in both request headers and the \"CMCD\" query parameter. A request must use only one transmission mode.",
+					severity: CMCD_VALIDATION_SEVERITY_ERROR
+				}]
+			}, result),
+			data: result.data
+		};
+	}
 	if (!param) return {
 		valid: false,
 		issues: [{
-			message: "No CMCD data found in request headers or query parameters.",
+			message: hasCmcdInFragment(request.url) ? "No CMCD data found in request headers or query parameters. The URL fragment contains a \"CMCD\" parameter. A server never receives the fragment." : "No CMCD data found in request headers or query parameters.",
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
 		}],
 		data: {}
@@ -3341,6 +3450,18 @@ function validateCmcdRequest(request, options) {
 		data
 	};
 }
+const CMCD_IN_FRAGMENT = /(?:^|[?&])CMCD=/;
+function getCmcdQueryParam(url) {
+	const hash = url.indexOf("#");
+	const path = hash < 0 ? url : url.slice(0, hash);
+	const start = path.indexOf("?");
+	if (start < 0) return null;
+	return new URLSearchParams(path.slice(start + 1)).get(CMCD_PARAM);
+}
+function hasCmcdInFragment(url) {
+	const hash = url.indexOf("#");
+	return hash >= 0 && CMCD_IN_FRAGMENT.test(url.slice(hash + 1));
+}
 function extractHeaderRecord(headers) {
 	if (!headers) return;
 	const h = ensureHeaders(headers);