@svta/cml-cmcd 2.6.1 → 2.8.0

package/dist/index.js

@@ -1,229 +1,325 @@
 import { SfItem, SfToken, decodeSfDict, encodeSfDict, symbolToStr } from "@svta/cml-structured-field-values";
 import { getBaseUrl, urlToRelativePath, uuid } from "@svta/cml-utils";
 
-//#region src/CMCD_FORMATTER_MAP.ts
-const roundValue = (value) => {
-	if (value instanceof SfItem) return new SfItem(Math.round(value.value), value.params);
-	return Math.round(value);
-};
-const toRounded = (value) => {
-	if (Array.isArray(value)) return value.map(roundValue);
-	return roundValue(value);
-};
-const toUrlSafe = (value, options) => {
-	if (Array.isArray(value)) return value.map((item) => toUrlSafe(item, options));
-	if (value instanceof SfItem && typeof value.value === "string") return new SfItem(toUrlSafe(value.value, options), value.params);
-	else {
-		if (options.baseUrl) value = urlToRelativePath(value, getBaseUrl(options.baseUrl));
-		return options.version === 1 ? encodeURIComponent(value) : value;
-	}
-};
-const hundredValue = (value) => {
-	if (value instanceof SfItem) return new SfItem(Math.round(value.value / 100) * 100, value.params);
-	return Math.round(value / 100) * 100;
-};
-const toHundred = (value) => {
-	if (Array.isArray(value)) return value.map(hundredValue);
-	return hundredValue(value);
-};
-const nor = (value, options) => {
-	let norValue = value;
-	if (options.version >= 2) {
-		if (value instanceof SfItem && typeof value.value === "string") norValue = new SfItem([value]);
-		else if (typeof value === "string") norValue = [value];
-	}
-	return toUrlSafe(norValue, options);
-};
+//#region src/CMCD_INNER_LIST_KEYS.ts
 /**
-* The default formatters for CMCD values.
+* Inner-list keys in version 2 that are scalars in version 1.
 *
-* @public
-*/
-const CMCD_FORMATTER_MAP = {
-	br: toRounded,
-	d: toRounded,
-	bl: toHundred,
-	dl: toHundred,
-	mtp: toHundred,
-	nor,
-	rtp: toHundred,
-	tb: toRounded
-};
-
-//#endregion
-//#region src/CMCD_V2.ts
-/**
-* CMCD Version 2
+* Used by both encoding (down-conversion) and decoding (up-conversion).
 *
-* @public
+* @internal
 */
-const CMCD_V2 = 2;
+const CMCD_INNER_LIST_KEYS = new Set([
+	"ab",
+	"bl",
+	"br",
+	"bsa",
+	"bsd",
+	"bsda",
+	"lab",
+	"lb",
+	"mtp",
+	"pb",
+	"tab",
+	"tb",
+	"tbl",
+	"tpb"
+]);
 
 //#endregion
-//#region src/CmcdEventType.ts
-/**
-* CMCD event type for the 'bc' key (bitrate change).
-*
-* @public
-*/
-const CMCD_EVENT_BITRATE_CHANGE = "bc";
-/**
-* CMCD event type for the 'ps' key (play state change).
-*
-* @public
-*/
-const CMCD_EVENT_PLAY_STATE = "ps";
-/**
-* CMCD event type for the 'pr' key (playback rate change).
-*
-* @public
-*/
-const CMCD_EVENT_PLAYBACK_RATE = "pr";
-/**
-* CMCD event type for the 'e' key (error).
-*
-* @public
-*/
-const CMCD_EVENT_ERROR = "e";
-/**
-* CMCD event type for the 't' key (time interval).
-*
-* @public
-*/
-const CMCD_EVENT_TIME_INTERVAL = "t";
-/**
-* CMCD event type for the 'c' key (content ID).
-*
-* @public
-*/
-const CMCD_EVENT_CONTENT_ID = "c";
-/**
-* CMCD event type for the 'b' key (backgrounded mode).
-*
-* @public
-*/
-const CMCD_EVENT_BACKGROUNDED_MODE = "b";
-/**
-* CMCD event type for the 'm' key (mute).
-*
-* @public
-*/
-const CMCD_EVENT_MUTE = "m";
-/**
-* CMCD event type for the 'um' key (unmute).
-*
-* @public
-*/
-const CMCD_EVENT_UNMUTE = "um";
-/**
-* CMCD event type for the 'pe' key (player expand).
-*
-* @public
-*/
-const CMCD_EVENT_PLAYER_EXPAND = "pe";
-/**
-* CMCD event type for the 'pc' key (player collapse).
-*
-* @public
-*/
-const CMCD_EVENT_PLAYER_COLLAPSE = "pc";
-/**
-* CMCD event type for the 'rr' key (response received).
-*
-* @public
-*/
-const CMCD_EVENT_RESPONSE_RECEIVED = "rr";
-/**
-* CMCD event type for the 'as' key (ad start).
-*
-* @public
-*/
-const CMCD_EVENT_AD_START = "as";
-/**
-* CMCD event type for the 'ae' key (ad end).
-*
-* @public
-*/
-const CMCD_EVENT_AD_END = "ae";
-/**
-* CMCD event type for the 'abs' key (ad break start).
-*
-* @public
-*/
-const CMCD_EVENT_AD_BREAK_START = "abs";
-/**
-* CMCD event type for the 'abe' key (ad break end).
-*
-* @public
-*/
-const CMCD_EVENT_AD_BREAK_END = "abe";
-/**
-* CMCD event type for the 'sk' key (skip).
-*
-* @public
-*/
-const CMCD_EVENT_SKIP = "sk";
-/**
-* CMCD event type for the 'ce' key (custom event).
-*
-* @public
-*/
-const CMCD_EVENT_CUSTOM_EVENT = "ce";
+//#region src/CMCD_KEY_SPECS.ts
+const MEDIA = [
+	"a",
+	"v",
+	"av",
+	"tt",
+	"c",
+	"o"
+];
 /**
-* CMCD event types for the 'e' key (event mode).
-*
-* @enum
-*
-* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#event | CTA-5004-B Event}
+* The encoder rules of each key. The table has one row for each key of CTA-5004-B Table 1, plus `nrr` of CTA-5004 and `cdn`.
 *
-* @public
+* @internal
 */
-const CmcdEventType = {
-	BITRATE_CHANGE: CMCD_EVENT_BITRATE_CHANGE,
-	PLAY_STATE: CMCD_EVENT_PLAY_STATE,
-	PLAYBACK_RATE: CMCD_EVENT_PLAYBACK_RATE,
-	ERROR: CMCD_EVENT_ERROR,
-	TIME_INTERVAL: CMCD_EVENT_TIME_INTERVAL,
-	CONTENT_ID: CMCD_EVENT_CONTENT_ID,
-	BACKGROUNDED_MODE: CMCD_EVENT_BACKGROUNDED_MODE,
-	MUTE: CMCD_EVENT_MUTE,
-	UNMUTE: CMCD_EVENT_UNMUTE,
-	PLAYER_EXPAND: CMCD_EVENT_PLAYER_EXPAND,
-	PLAYER_COLLAPSE: CMCD_EVENT_PLAYER_COLLAPSE,
-	RESPONSE_RECEIVED: CMCD_EVENT_RESPONSE_RECEIVED,
-	AD_START: CMCD_EVENT_AD_START,
-	AD_END: CMCD_EVENT_AD_END,
-	AD_BREAK_START: CMCD_EVENT_AD_BREAK_START,
-	AD_BREAK_END: CMCD_EVENT_AD_BREAK_END,
-	SKIP: CMCD_EVENT_SKIP,
-	CUSTOM_EVENT: CMCD_EVENT_CUSTOM_EVENT
+const CMCD_KEY_SPECS = {
+	ab: {
+		type: "ot-list",
+		round: 1,
+		supersededBy: "br",
+		version: 2
+	},
+	bg: {
+		type: "boolean",
+		omitDefault: false,
+		requiredOn: "b",
+		version: 2
+	},
+	bl: {
+		type: "ot-list",
+		round: 100
+	},
+	br: {
+		type: "ot-list",
+		round: 1,
+		requiredOn: "bc"
+	},
+	bs: {
+		type: "boolean",
+		omitDefault: false
+	},
+	bsa: {
+		type: "ot-list",
+		round: 1,
+		version: 2
+	},
+	bsd: {
+		type: "ot-list",
+		round: 1,
+		version: 2
+	},
+	bsda: {
+		type: "ot-list",
+		round: 1,
+		version: 2
+	},
+	cdn: {
+		type: "string",
+		max: 128,
+		version: 2
+	},
+	cen: {
+		type: "string",
+		max: 64,
+		mode: "event",
+		onlyOn: "ce",
+		requiredOn: "ce",
+		version: 2
+	},
+	cid: {
+		type: "string",
+		max: 128,
+		v1Max: 64,
+		requiredOn: "c"
+	},
+	cmsdd: {
+		type: "string",
+		mode: "event",
+		onlyOn: "rr",
+		version: 2
+	},
+	cmsds: {
+		type: "string",
+		mode: "event",
+		onlyOn: "rr",
+		version: 2
+	},
+	cs: {
+		type: "string",
+		version: 2
+	},
+	d: {
+		type: "integer",
+		round: 1,
+		ot: MEDIA
+	},
+	dfa: {
+		type: "integer",
+		round: 1,
+		version: 2
+	},
+	dl: {
+		type: "integer",
+		round: 100
+	},
+	e: {
+		type: "token",
+		mode: "event",
+		requiredOn: "always",
+		version: 2
+	},
+	ec: {
+		type: "string-list",
+		requiredOn: "e",
+		version: 2
+	},
+	h: {
+		type: "string",
+		max: 128,
+		mode: "event",
+		requiredOn: "h",
+		version: 2
+	},
+	lab: {
+		type: "ot-list",
+		round: 1,
+		supersededBy: "lb",
+		version: 2
+	},
+	lb: {
+		type: "ot-list",
+		round: 1,
+		version: 2
+	},
+	ltc: {
+		type: "integer",
+		round: 1,
+		version: 2
+	},
+	msd: {
+		type: "integer",
+		round: 1,
+		version: 2
+	},
+	mtp: {
+		type: "ot-list",
+		round: 100
+	},
+	nor: { type: "nor" },
+	nr: {
+		type: "boolean",
+		omitDefault: false,
+		version: 2
+	},
+	nrr: {
+		type: "string",
+		version: 1
+	},
+	ot: { type: "token" },
+	pb: {
+		type: "ot-list",
+		round: 1,
+		version: 2
+	},
+	pr: {
+		type: "decimal",
+		omitDefault: 1,
+		requiredOn: "pr"
+	},
+	pt: {
+		type: "integer",
+		round: 1,
+		version: 2
+	},
+	rc: {
+		type: "integer",
+		round: 1,
+		mode: "event",
+		onlyOn: "rr",
+		version: 2
+	},
+	rtp: {
+		type: "integer",
+		round: 100
+	},
+	sf: {
+		type: "token",
+		v1Map: { e: "o" }
+	},
+	sid: {
+		type: "string",
+		max: 64
+	},
+	smrt: {
+		type: "string",
+		mode: "event",
+		onlyOn: "rr",
+		version: 2
+	},
+	sn: {
+		type: "integer",
+		round: 1,
+		version: 2
+	},
+	st: {
+		type: "token",
+		v1Map: { ll: "l" }
+	},
+	sta: {
+		type: "token",
+		requiredOn: "ps",
+		version: 2
+	},
+	su: {
+		type: "boolean",
+		omitDefault: false
+	},
+	tab: {
+		type: "ot-list",
+		round: 1,
+		supersededBy: "tb",
+		version: 2
+	},
+	tb: {
+		type: "ot-list",
+		round: 1
+	},
+	tbl: {
+		type: "ot-list",
+		round: 100,
+		version: 2
+	},
+	tpb: {
+		type: "ot-list",
+		round: 1,
+		ot: [
+			"a",
+			"v",
+			"av",
+			"c"
+		],
+		version: 2
+	},
+	ts: {
+		type: "integer",
+		round: 1,
+		mode: "event",
+		requiredOn: "always",
+		version: 2
+	},
+	ttfb: {
+		type: "integer",
+		round: 1,
+		mode: "event",
+		onlyOn: "rr",
+		version: 2
+	},
+	ttfbb: {
+		type: "integer",
+		round: 1,
+		mode: "event",
+		onlyOn: "rr",
+		version: 2
+	},
+	ttlb: {
+		type: "integer",
+		round: 1,
+		mode: "event",
+		onlyOn: "rr",
+		version: 2
+	},
+	url: {
+		type: "string",
+		mode: "event",
+		onlyOn: "rr",
+		requiredOn: "rr",
+		version: 2
+	},
+	v: {
+		type: "integer",
+		round: 1,
+		requiredOn: "always",
+		version: 2
+	}
 };
 
 //#endregion
-//#region src/CMCD_STATE_EVENT_FIELDS.ts
+//#region src/CMCD_V2.ts
 /**
-* Maps each state-change event type to the persistent field whose value
-* 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`).
-*
-* Iteration order is load-bearing: `CmcdReporter.update()` fires state-change
-* events in map order when multiple tracked fields change in a single call.
-* Do not reorder entries without auditing reporter behavior.
+* CMCD Version 2
 *
-* @internal
+* @public
 */
-const CMCD_STATE_EVENT_FIELDS = /* @__PURE__ */ new Map([
-	[CMCD_EVENT_PLAY_STATE, "sta"],
-	[CMCD_EVENT_PLAYBACK_RATE, "pr"],
-	[CMCD_EVENT_CONTENT_ID, "cid"],
-	[CMCD_EVENT_BACKGROUNDED_MODE, "bg"],
-	[CMCD_EVENT_BITRATE_CHANGE, "br"]
-]);
+const CMCD_V2 = 2;
 
 //#endregion
 //#region src/CmcdReportingMode.ts
@@ -252,75 +348,68 @@ const CmcdReportingMode = {
 };
 
 //#endregion
-//#region src/CMCD_EVENT_KEYS.ts
+//#region src/downConvertToV1.ts
+function hasParams(params) {
+	for (const _ in params) return true;
+	return false;
+}
 /**
-* Defines the event-specific keys for CMCD (Common Media Client Data) version 2.
+* Unwrap an inner list or SfItem value to a scalar.
 *
-* @public
+* The scalar is the value of the item with the object type flag of `ot`
+* (CTA-5004-B section 4.1, item 14). Without that item, it is the value
+* of the first item without parameters. Otherwise it is `undefined`.
 */
-const CMCD_EVENT_KEYS = [
-	"cen",
-	"e",
-	"h",
-	"ts"
-];
-
-//#endregion
-//#region src/CMCD_REQUEST_KEYS.ts
+function unwrapValue(value, ot) {
+	if (value instanceof SfItem) value = value.value;
+	if (!Array.isArray(value)) return value;
+	let fallback;
+	for (const item of value) {
+		if (!(item instanceof SfItem)) {
+			if (fallback === void 0) fallback = item;
+			continue;
+		}
+		if (ot && item.params?.[ot] === true) return item.value;
+		if (fallback === void 0 && !hasParams(item.params)) fallback = item.value;
+	}
+	return fallback;
+}
 /**
-* Defines the request-specific keys for CMCD (Common Media Client Data) version 2.
+* Down-convert version 2 CMCD data to version 1.
 *
-* @public
+* - Extracts `nrr` from the `nor` SfItem's `r` parameter.
+* - Unwraps inner-list values to scalars for the object type `ot`.
+*
+* @internal
 */
-const CMCD_REQUEST_KEYS = [
-	"ab",
-	"bg",
-	"bl",
-	"br",
-	"bs",
-	"bsa",
-	"bsd",
-	"bsda",
-	"cdn",
-	"cid",
-	"cs",
-	"d",
-	"dfa",
-	"dl",
-	"ec",
-	"lab",
-	"lb",
-	"ltc",
-	"msd",
-	"mtp",
-	"nor",
-	"nr",
-	"ot",
-	"pb",
-	"pr",
-	"pt",
-	"rtp",
-	"sf",
-	"sid",
-	"sn",
-	"st",
-	"sta",
-	"su",
-	"tab",
-	"tb",
-	"tbl",
-	"tpb",
-	"v"
-];
+function downConvertToV1(obj, ot) {
+	const result = {};
+	for (const [key, value] of Object.entries(obj)) {
+		if (value == null) {
+			result[key] = value;
+			continue;
+		}
+		if (key === "nor") {
+			const list = value instanceof SfItem && Array.isArray(value.value) ? value.value : value;
+			const first = Array.isArray(list) ? list[0] : list;
+			if (first instanceof SfItem) {
+				result["nor"] = first.value;
+				if (first.params?.r) result["nrr"] = first.params.r;
+			} else result["nor"] = first;
+		} else if (CMCD_INNER_LIST_KEYS.has(key)) result[key] = unwrapValue(value, ot);
+		else result[key] = value;
+	}
+	return result;
+}
 
 //#endregion
 //#region src/isCmcdCustomKey.ts
 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.
 *
@@ -337,254 +426,245 @@ function isCmcdCustomKey(key) {
 }
 
 //#endregion
-//#region src/isCmcdRequestKey.ts
-const CMCD_REQUEST_KEY_SET = /* @__PURE__ */ new Set(CMCD_REQUEST_KEYS);
+//#region src/getKeySpec.ts
+const CUSTOM_KEY_SPEC = {
+	type: "custom",
+	omitDefault: false,
+	max: 64,
+	v1Max: Infinity
+};
 /**
-* Check if a key is a valid CMCD request key.
+* Returns the row of a key in the key table.
 *
-* @param key - The key to check.
+* @param key - The key to look up.
 *
-* @returns `true` if the key is a valid CMCD request key, `false` otherwise.
+* @returns The row of a reserved key, the custom row for a valid custom key, or `undefined`.
 *
-* @public
-*
-* @example
-* {@includeCode ../test/isCmcdRequestKey.test.ts#example}
+* @internal
 */
-function isCmcdRequestKey(key) {
-	return CMCD_REQUEST_KEY_SET.has(key) || isCmcdCustomKey(key);
+function getKeySpec(key) {
+	if (Object.prototype.hasOwnProperty.call(CMCD_KEY_SPECS, key)) return CMCD_KEY_SPECS[key];
+	return isCmcdCustomKey(key) ? CUSTOM_KEY_SPEC : void 0;
 }
 
 //#endregion
-//#region src/CMCD_RESPONSE_KEYS.ts
-/**
-* CMCD v2 - Response-only and timing keys.
-*
-* @public
-*/
-const CMCD_RESPONSE_KEYS = [
-	"cmsdd",
-	"cmsds",
-	"rc",
-	"smrt",
-	"ttfb",
-	"ttfbb",
-	"ttlb",
-	"url"
-];
-
-//#endregion
-//#region src/isCmcdResponseReceivedKey.ts
-const CMCD_RESPONSE_KEY_SET = /* @__PURE__ */ new Set(CMCD_RESPONSE_KEYS);
+//#region src/isValid.ts
 /**
-* Check if a key is a valid CMCD response key.
+* Checks if the given value is valid to send as a CMCD value.
 *
-* @param key - The key to check.
+* `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.
 *
-* @returns `true` if the key is a valid CMCD request key, `false` otherwise.
+* @param value - The value to check.
 *
-* @public
+* @returns `true` if the value is valid.
 *
-* @example
-* {@includeCode ../test/isCmcdResponseReceivedKey.test.ts#example}
+* @internal
 */
-function isCmcdResponseReceivedKey(key) {
-	return CMCD_RESPONSE_KEY_SET.has(key);
+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;
 }
 
 //#endregion
-//#region src/isCmcdEventKey.ts
-const CMCD_EVENT_KEY_SET = /* @__PURE__ */ new Set(CMCD_EVENT_KEYS);
-/**
-* Check if a key is a valid CMCD event key.
-*
-* @param key - The key to check.
-*
-* @returns `true` if the key is a valid CMCD event key, `false` otherwise.
-*
-* @public
-*
-* @example
-* {@includeCode ../test/isCmcdEventKey.test.ts#example}
-*/
-function isCmcdEventKey(key) {
-	return isCmcdRequestKey(key) || isCmcdResponseReceivedKey(key) || CMCD_EVENT_KEY_SET.has(key);
+//#region src/formatNor.ts
+function toBase(baseUrl) {
+	if (!baseUrl) return;
+	try {
+		return new URL(getBaseUrl(baseUrl)).href;
+	} catch {
+		return;
+	}
+}
+function formatPath(path, base, version) {
+	if (typeof path !== "string" || path === "") return;
+	const relative = base ? urlToRelativePath(path, base) : path;
+	return version === 1 ? encodeURIComponent(relative) : relative;
+}
+function formatEntry(entry, base, version) {
+	if (entry instanceof SfItem) {
+		const path = formatPath(entry.value, base, version);
+		return path === void 0 ? void 0 : new SfItem(path, entry.params);
+	}
+	return formatPath(entry, base, version);
+}
+function formatEntries(entries, base, version) {
+	const list = [];
+	for (const entry of entries) {
+		const formatted = formatEntry(entry, base, version);
+		if (formatted !== void 0) list.push(formatted);
+	}
+	return list.length > 0 ? list : void 0;
 }
-
-//#endregion
-//#region src/CMCD_INNER_LIST_KEYS.ts
-/**
-* Keys that are inner lists in V2 but plain scalars in V1.
-*
-* Used by both encoding (down-conversion) and decoding (up-conversion).
-*
-* @internal
-*/
-const CMCD_INNER_LIST_KEYS = new Set([
-	"ab",
-	"bl",
-	"br",
-	"bsa",
-	"bsd",
-	"bsda",
-	"lab",
-	"lb",
-	"mtp",
-	"pb",
-	"tab",
-	"tb",
-	"tbl",
-	"tpb"
-]);
-
-//#endregion
-//#region src/CMCD_V1_KEYS.ts
-/**
-* Defines the keys for CMCD (Common Media Client Data) version 1.
-*
-* @public
-*/
-const CMCD_V1_KEYS = [
-	"bl",
-	"br",
-	"bs",
-	"cid",
-	"d",
-	"dl",
-	"mtp",
-	"nor",
-	"nrr",
-	"ot",
-	"pr",
-	"rtp",
-	"sf",
-	"sid",
-	"st",
-	"su",
-	"tb",
-	"v"
-];
-
-//#endregion
-//#region src/isCmcdV1Key.ts
-const CMCD_V1_KEY_SET$1 = /* @__PURE__ */ new Set(CMCD_V1_KEYS);
 /**
-* Filter function for CMCD v1 keys.
-*
-* @param key - The CMCD key to filter.
+* Formats a `nor` value. Each path becomes relative to `baseUrl` when `baseUrl` is a valid URL.
+* Version 1 encodes the path with `encodeURIComponent`. Version 2 wraps one path in a list.
+* The parameters of an entry and of an inner list stay on the value.
 *
-* @returns `true` if the key should be included, `false` otherwise.
+* @param value - A path, an `SfItem` of a path, or a list of them. An `SfItem` can also wrap the list.
+* @param options - The version and `baseUrl` of the report.
 *
-* @public
+* @returns The formatted value, or `undefined` when no entry is a non-empty string.
 *
-* @example
-* {@includeCode ../test/isCmcdV1Key.test.ts#example}
+* @internal
 */
-function isCmcdV1Key(key) {
-	return CMCD_V1_KEY_SET$1.has(key) || isCmcdCustomKey(key);
+function formatNor(value, options) {
+	const base = toBase(options.baseUrl);
+	const version = options.version;
+	if (Array.isArray(value)) return formatEntries(value, base, version);
+	if (value instanceof SfItem && Array.isArray(value.value)) {
+		const list = formatEntries(value.value, base, version);
+		return list && new SfItem(list, value.params);
+	}
+	const entry = formatEntry(value, base, version);
+	return version === 1 || entry === void 0 ? entry : [entry];
 }
 
 //#endregion
-//#region src/isTokenField.ts
-const TOKEN_FIELDS = /* @__PURE__ */ new Set([
-	"ot",
-	"sf",
-	"st",
-	"e",
-	"sta"
-]);
+//#region src/toTokenString.ts
 /**
-* Checks if the given key is a token field.
+* Resolve the text of a token value.
 *
-* @param key - The key to check.
+* A token may be a plain string, a registry `Symbol`, an `SfToken`, or an
+* `SfItem` that wraps such a value.
+*
+* @param value - The value to resolve.
 *
-* @returns `true` if the key is a token field.
+* @returns The token text, or `undefined` when the value is not a token.
 *
 * @internal
 */
-function isTokenField(key) {
-	return TOKEN_FIELDS.has(key);
+function toTokenString(value) {
+	if (value instanceof SfItem) return toTokenString(value.value);
+	if (typeof value === "string") return value;
+	if (typeof value === "symbol" || value instanceof SfToken) return symbolToStr(value);
 }
 
 //#endregion
-//#region src/isValid.ts
+//#region src/normalizeValue.ts
+function toText(value, spec, version) {
+	const max = (version === 1 ? spec.v1Max : void 0) ?? spec.max ?? Infinity;
+	return typeof value === "string" && value !== "" && value.length <= max ? value : void 0;
+}
+function normalizeBare(value, spec, version) {
+	switch (spec.type) {
+		case "boolean": return typeof value === "boolean" ? value : void 0;
+		case "integer":
+		case "ot-list": return typeof value === "number" && Number.isFinite(value) ? Math.round(value / spec.round) * spec.round : void 0;
+		case "decimal": return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+		case "string": return toText(value, spec, version);
+		case "string-list": return typeof value === "string" && value !== "" ? value : void 0;
+		case "token": {
+			const text = toTokenString(value);
+			const v1Map = version === 1 ? spec.v1Map : void 0;
+			const token = text !== void 0 && v1Map !== void 0 && Object.prototype.hasOwnProperty.call(v1Map, text) ? v1Map[text] : text;
+			return token ? new SfToken(token) : void 0;
+		}
+		case "custom":
+			if (typeof value === "string") return toText(value, spec, version);
+			if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+			if (Array.isArray(value)) return value.length > 0 ? value : void 0;
+			return typeof value === "boolean" || typeof value === "symbol" || value instanceof SfToken ? value : void 0;
+		default: return;
+	}
+}
+function normalizeItem(value, spec, version) {
+	if (value instanceof SfItem) {
+		const bare = normalizeBare(value.value, spec, version);
+		return bare === void 0 ? void 0 : new SfItem(bare, value.params);
+	}
+	return normalizeBare(value, spec, version);
+}
+function normalizeList(value, spec, version) {
+	const wrapper = value instanceof SfItem && Array.isArray(value.value) ? value : void 0;
+	const items = wrapper ? wrapper.value : Array.isArray(value) ? value : [value];
+	const list = [];
+	for (const item of items) {
+		const normalized = normalizeItem(item, spec, version);
+		if (normalized !== void 0) list.push(normalized);
+	}
+	if (list.length === 0) return;
+	return wrapper ? new SfItem(list, wrapper.params) : list;
+}
 /**
-* Checks if the given value is valid
+* Applies the value rule of a key type from the key table.
 *
-* @param value - The value to check.
+* An `SfItem` keeps its parameters, and the rule applies to the value inside it.
+* In version 2, a list key wraps one value in a list.
+* The rules do not check the limits of RFC 8941, such as the integer range.
+*
+* @param value - The value to prepare.
+* @param spec - The row of the key in the key table.
+* @param options - The version and `baseUrl` of the report.
 *
-* @returns `true` if the key is a value is valid.
+* @returns The value to send, or `undefined` when the value fails the rule.
 *
 * @internal
 */
-function isValid(value) {
-	if (typeof value === "number") return Number.isFinite(value);
-	return value != null && value !== "" && value !== false;
+function normalizeValue(value, spec, options) {
+	if (spec.type === "nor") return formatNor(value, options);
+	if (spec.type === "string-list" || spec.type === "ot-list" && options.version !== 1) return normalizeList(value, spec, options.version);
+	return normalizeItem(value, spec, options.version);
 }
 
 //#endregion
-//#region src/toTokenString.ts
+//#region src/toBareValue.ts
 /**
-* Resolve the text of a token value.
+* Returns the value inside an `SfItem`, or the value itself.
 *
-* A token may be a plain string, a registry `Symbol`, an `SfToken`, or an
-* `SfItem` that wraps one of those.
+* `decodeCmcd` returns a member with parameters as an `SfItem`. For an
+* inner list with parameters, the value of the `SfItem` is the list.
 *
-* @param value - The value to resolve.
-*
-* @returns The token text, or `undefined` when the value is not a token.
+* @param value - The value to read.
+* @returns The value without its parameters.
 *
 * @internal
 */
-function toTokenString(value) {
-	if (value instanceof SfItem) return toTokenString(value.value);
-	if (typeof value === "string") return value;
-	if (typeof value === "symbol" || value instanceof SfToken) return symbolToStr(value);
+function toBareValue(value) {
+	return value instanceof SfItem ? value.value : value;
 }
 
 //#endregion
 //#region src/prepareCmcdData.ts
-const filterMap = {
-	[CMCD_EVENT_MODE]: isCmcdEventKey,
-	[CMCD_REQUEST_MODE]: isCmcdRequestKey
-};
-/**
-* Unwrap an inner list or SfItem value to a plain scalar.
-*/
-function unwrapValue(value, ot) {
-	if (Array.isArray(value)) {
-		let item;
-		const otText = toTokenString(ot);
-		if (otText) item = value.find((item$1) => toTokenString(item$1.params?.ot) === otText);
-		if (!item) item = value[0];
-		return unwrapValue(item);
-	}
-	if (value instanceof SfItem) return value.value;
-	return value;
+function hasKey(spec, reportingMode, isV1) {
+	return (spec.mode === void 0 || spec.mode === reportingMode) && (spec.version === void 0 || spec.version === 1 === isV1);
 }
-/**
-* Down-convert V2 CMCD data to V1 format.
-*
-* - Extracts `nrr` from `nor` SfItem `r` parameter.
-* - Unwraps inner-list values to plain scalars.
-*/
-function downConvertToV1(obj) {
-	const result = {};
-	for (const [key, value] of Object.entries(obj)) {
-		if (value == null) {
-			result[key] = value;
-			continue;
-		}
-		if (key === "nor") {
-			const first = (Array.isArray(value) ? value : [value])[0];
-			if (first instanceof SfItem) {
-				result["nor"] = first.value;
-				if (first.params?.r) result["nrr"] = first.params.r;
-			} else result["nor"] = first;
-		} else if (CMCD_INNER_LIST_KEYS.has(key)) result[key] = unwrapValue(value, obj["ot"]);
-		else result[key] = value;
+function isRequired(spec, event) {
+	return spec.requiredOn === "always" || event !== void 0 && spec.requiredOn === event;
+}
+function hasObjectTypes(spec) {
+	return (spec.type === "integer" || spec.type === "ot-list") && spec.ot !== void 0;
+}
+function needsV1ObjectType(obj, filter) {
+	if (typeof filter !== "function" || filter("ot")) return true;
+	for (const key of CMCD_INNER_LIST_KEYS) if (Array.isArray(toBareValue(obj[key])) && filter(key)) return true;
+	return false;
+}
+function allowsObjectType(spec, objectType) {
+	if (objectType === void 0 || spec.type !== "integer" && spec.type !== "ot-list" || spec.ot === void 0) return true;
+	return spec.ot.includes(objectType);
+}
+function isDefaultValue(spec, value) {
+	return "omitDefault" in spec && toBareValue(value) === spec.omitDefault;
+}
+function insertKey(keys, specs, key) {
+	let index = 0;
+	while (index < keys.length && keys[index] < key) index++;
+	keys.splice(index, 0, key);
+	specs.splice(index, 0, CMCD_KEY_SPECS[key]);
+}
+function prepareValue(key, value, spec, options, formatterOptions) {
+	const formatter = options.formatters?.[key];
+	if (typeof formatter !== "function") return value == null ? void 0 : normalizeValue(value, spec, formatterOptions);
+	const formatted = isValid(value) ? formatter(value, formatterOptions) : value;
+	if (!isValid(formatted) && !(formatted === false && spec.type === "boolean")) return;
+	if (spec.type === "token") {
+		if (typeof formatted === "string") return new SfToken(formatted);
+		if (formatted instanceof SfItem && typeof formatted.value === "string") return new SfItem(new SfToken(formatted.value), formatted.params);
 	}
-	return result;
+	return formatted;
 }
 /**
 * Convert a generic object to CMCD data.
@@ -600,48 +680,66 @@ function downConvertToV1(obj) {
 function prepareCmcdData(obj, options = {}) {
 	const results = {};
 	if (obj == null || typeof obj !== "object") return results;
-	const version = options.version || obj["v"] || CMCD_V2;
+	const version = options.version || toBareValue(obj["v"]) || CMCD_V2;
 	const reportingMode = options.reportingMode || CMCD_REQUEST_MODE;
-	const data = version === 1 ? downConvertToV1(obj) : obj;
-	const eventType = toTokenString(data["e"]);
-	const keyFilter = version === 1 ? isCmcdV1Key : filterMap[reportingMode];
-	let keys = Object.keys(data).filter(keyFilter);
-	if (data["e"] && eventType !== CMCD_EVENT_RESPONSE_RECEIVED) keys = keys.filter((key) => !isCmcdResponseReceivedKey(key));
-	const filter = options.filter;
-	if (typeof filter === "function") keys = keys.filter(filter);
-	const isEventMode = reportingMode === CMCD_EVENT_MODE;
-	if (isEventMode) {
-		if (!keys.includes("e") && data["e"] != null) keys.push("e");
-		if (!keys.includes("ts")) keys.push("ts");
-		if (!keys.includes("cen") && data["cen"] != null && eventType === CMCD_EVENT_CUSTOM_EVENT) keys.push("cen");
-		if (!keys.includes("ec") && data["ec"] != null && eventType === CMCD_EVENT_ERROR) keys.push("ec");
-		if (!keys.includes("url") && data["url"] != null && eventType === CMCD_EVENT_RESPONSE_RECEIVED) keys.push("url");
-		const requiredField = eventType ? CMCD_STATE_EVENT_FIELDS.get(eventType) : void 0;
-		if (requiredField && data[requiredField] != null && !keys.includes(requiredField)) keys.push(requiredField);
-	}
-	if (keys.length === 0) return results;
-	if (version > 1 && !keys.includes("v")) keys.push("v");
+	const isV1 = version === 1;
+	const isEventReport = !isV1 && reportingMode === CMCD_EVENT_MODE;
 	const formatterOptions = {
 		version,
 		reportingMode,
 		baseUrl: options.baseUrl
 	};
-	keys.sort();
-	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);
-		if (key === "v") if (version === 1) continue;
-		else value = version;
-		if (key === "pr" && value === 1 && !(isEventMode && eventType === CMCD_EVENT_PLAYBACK_RATE)) continue;
-		if (isEventMode && key === "ts" && !Number.isFinite(value)) value = Date.now();
-		const isBgFalseTransition = isEventMode && value === false && key === "bg" && eventType === CMCD_EVENT_BACKGROUNDED_MODE;
-		if (!isValid(value) && !isBgFalseTransition) continue;
-		if (isTokenField(key)) {
-			if (typeof value === "string") value = new SfToken(value);
-			else if (value instanceof SfItem && typeof value.value === "string") value = new SfItem(new SfToken(value.value), value.params);
+	const filter = options.filter;
+	let objectTypeValue;
+	let objectType;
+	if (isV1 && needsV1ObjectType(obj, filter)) {
+		objectTypeValue = prepareValue("ot", obj["ot"], CMCD_KEY_SPECS["ot"], options, formatterOptions);
+		objectType = toTokenString(objectTypeValue);
+	}
+	const data = isV1 ? downConvertToV1(obj, objectType) : obj;
+	const eventValue = isEventReport ? prepareValue("e", data["e"], CMCD_KEY_SPECS["e"], options, formatterOptions) : void 0;
+	const event = toTokenString(eventValue);
+	const keys = [];
+	const specs = [];
+	let passed = false;
+	let needsObjectType = false;
+	for (const key of Object.keys(data).sort()) {
+		const spec = getKeySpec(key);
+		if (spec === void 0 || !hasKey(spec, reportingMode, isV1)) continue;
+		if (typeof filter !== "function" || filter(key)) passed = true;
+		else if (!isRequired(spec, event)) continue;
+		if (spec.onlyOn !== void 0 && spec.onlyOn !== event) continue;
+		if (key === "ot" || hasObjectTypes(spec)) needsObjectType = true;
+		keys.push(key);
+		specs.push(spec);
+	}
+	if (!passed && !isEventReport) return results;
+	if (needsObjectType && !isV1) {
+		objectTypeValue = prepareValue("ot", data["ot"], CMCD_KEY_SPECS["ot"], options, formatterOptions);
+		objectType = toTokenString(objectTypeValue);
+	}
+	if (isEventReport && !keys.includes("ts")) insertKey(keys, specs, "ts");
+	if (!isV1 && !keys.includes("v")) insertKey(keys, specs, "v");
+	const values = new Array(keys.length);
+	for (let i = keys.length - 1; i >= 0; i--) {
+		const key = keys[i];
+		const spec = specs[i];
+		if (spec.type === "ot-list" && spec.supersededBy !== void 0) {
+			const exact = keys.indexOf(spec.supersededBy, i + 1);
+			if (exact !== -1 && values[exact] !== void 0) continue;
+		}
+		if (key === "v") values[i] = version;
+		else if (key === "ot") values[i] = objectTypeValue;
+		else if (key === "e") values[i] = eventValue;
+		else if (isV1 || allowsObjectType(spec, objectType)) values[i] = prepareValue(key, data[key], spec, options, formatterOptions);
+		if (key === "ts") {
+			const timestamp = toBareValue(values[i]);
+			if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) values[i] = Date.now();
 		}
-		results[key] = value;
+	}
+	for (let i = 0; i < keys.length; i++) {
+		const value = values[i];
+		if (value !== void 0 && (!isDefaultValue(specs[i], value) || isRequired(specs[i], event))) results[keys[i]] = value;
 	}
 	return results;
 }
@@ -703,9 +801,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 +858,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 +906,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 +928,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 +995,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 +1015,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,91 +1042,402 @@ 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.
 *
 * @public
-*
-* @example
-* {@includeCode ../test/appendCmcdQuery.test.ts#example}
-*
-* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#query-argument-definition | CTA-5004-B Query Argument Definition}
+*
+* @example
+* {@includeCode ../test/appendCmcdQuery.test.ts#example}
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#query-argument-definition | CTA-5004-B Query Argument Definition}
+*/
+function appendCmcdQuery(url, cmcd, options) {
+	const query = toCmcdQuery(cmcd, options);
+	if (!query) return url;
+	if (REGEX.test(url)) return url.replace(REGEX, query);
+	return `${url}${url.includes("?") ? "&" : "?"}${query}`;
+}
+
+//#endregion
+//#region src/CMCD_DEFAULT_TIME_INTERVAL.ts
+/**
+* The default time interval in seconds when using event mode
+*
+* @public
+*/
+const CMCD_DEFAULT_TIME_INTERVAL = 30;
+
+//#endregion
+//#region src/CMCD_EVENT_KEYS.ts
+/**
+* Defines the event-specific keys for CMCD (Common Media Client Data) version 2.
+*
+* @public
+*/
+const CMCD_EVENT_KEYS = [
+	"cen",
+	"e",
+	"h",
+	"ts"
+];
+
+//#endregion
+//#region src/CMCD_FORMATTER_MAP.ts
+const formatNumbers = (value, format) => {
+	if (Array.isArray(value)) {
+		const list = [];
+		for (const item of value) {
+			const formatted = formatNumbers(item, format);
+			if (Number.isFinite(formatted instanceof SfItem ? formatted.value : formatted)) list.push(formatted);
+		}
+		return list;
+	}
+	if (value instanceof SfItem) {
+		const formatted = formatNumbers(value.value, format);
+		return isValid(formatted) ? new SfItem(formatted, value.params) : NaN;
+	}
+	return typeof value === "number" ? format(value) : NaN;
+};
+const toRounded = (value) => formatNumbers(value, Math.round);
+const toNumber = (value) => formatNumbers(value, Number);
+const roundToHundred = (value) => Math.round(value / 100) * 100;
+const toHundred = (value) => formatNumbers(value, roundToHundred);
+/**
+* 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
+*/
+const CMCD_FORMATTER_MAP = {
+	br: toRounded,
+	d: toRounded,
+	bl: toHundred,
+	dl: toHundred,
+	mtp: toHundred,
+	nor: (value, options) => formatNor(value, options) ?? "",
+	rtp: toHundred,
+	tb: toRounded,
+	tbl: toHundred,
+	ab: toRounded,
+	bsa: toRounded,
+	bsd: toRounded,
+	bsda: toRounded,
+	dfa: toRounded,
+	lab: toRounded,
+	lb: toRounded,
+	ltc: toRounded,
+	msd: toRounded,
+	pb: toRounded,
+	pr: toNumber,
+	pt: toRounded,
+	rc: toRounded,
+	sn: toRounded,
+	tab: toRounded,
+	tpb: toRounded,
+	ts: toRounded,
+	ttfb: toRounded,
+	ttfbb: toRounded,
+	ttlb: toRounded
+};
+
+//#endregion
+//#region src/CMCD_REQUEST_KEYS.ts
+/**
+* Defines the request-specific keys for CMCD (Common Media Client Data) version 2.
+*
+* @public
+*/
+const CMCD_REQUEST_KEYS = [
+	"ab",
+	"bg",
+	"bl",
+	"br",
+	"bs",
+	"bsa",
+	"bsd",
+	"bsda",
+	"cdn",
+	"cid",
+	"cs",
+	"d",
+	"dfa",
+	"dl",
+	"ec",
+	"lab",
+	"lb",
+	"ltc",
+	"msd",
+	"mtp",
+	"nor",
+	"nr",
+	"ot",
+	"pb",
+	"pr",
+	"pt",
+	"rtp",
+	"sf",
+	"sid",
+	"sn",
+	"st",
+	"sta",
+	"su",
+	"tab",
+	"tb",
+	"tbl",
+	"tpb",
+	"v"
+];
+
+//#endregion
+//#region src/CMCD_RESPONSE_KEYS.ts
+/**
+* Response-only and timing keys for version 2.
+*
+* @public
+*/
+const CMCD_RESPONSE_KEYS = [
+	"cmsdd",
+	"cmsds",
+	"rc",
+	"smrt",
+	"ttfb",
+	"ttfbb",
+	"ttlb",
+	"url"
+];
+
+//#endregion
+//#region src/CMCD_V1_KEYS.ts
+/**
+* Defines the keys for CMCD (Common Media Client Data) version 1.
+*
+* @public
+*/
+const CMCD_V1_KEYS = [
+	"bl",
+	"br",
+	"bs",
+	"cid",
+	"d",
+	"dl",
+	"mtp",
+	"nor",
+	"nrr",
+	"ot",
+	"pr",
+	"rtp",
+	"sf",
+	"sid",
+	"st",
+	"su",
+	"tb",
+	"v"
+];
+
+//#endregion
+//#region src/CMCD_KEYS.ts
+/**
+* A list of all CMCD keys.
+*
+* @public
+*/
+const CMCD_KEYS = /* @__PURE__ */ [
+	...CMCD_V1_KEYS,
+	...CMCD_REQUEST_KEYS,
+	...CMCD_RESPONSE_KEYS,
+	...CMCD_EVENT_KEYS
+].filter((key, index, arr) => arr.indexOf(key) === index);
+
+//#endregion
+//#region src/CMCD_MIME_TYPE.ts
+/**
+* CMCD MIME type for event report payloads.
+*
+* @public
+*/
+const CMCD_MIME_TYPE = "application/cmcd";
+
+//#endregion
+//#region src/CMCD_REQUEST_PROVENANCE.ts
+/**
+* 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 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.
+*
+* The symbol registry provides the symbol, so duplicated copies of this
+* library in one bundle interoperate. The registry key is stable across
+* versions.
+*
+* @public
+*/
+const CMCD_REQUEST_PROVENANCE = /* @__PURE__ */ Symbol.for("@svta/cml-cmcd/request-provenance");
+
+//#endregion
+//#region src/CMCD_V1.ts
+/**
+* CMCD Version 1
+*
+* @public
+*/
+const CMCD_V1 = 1;
+
+//#endregion
+//#region src/CmcdEventType.ts
+/**
+* CMCD event type 'bc' (bitrate change).
+*
+* @public
+*/
+const CMCD_EVENT_BITRATE_CHANGE = "bc";
+/**
+* CMCD event type 'ps' (play state change).
+*
+* @public
+*/
+const CMCD_EVENT_PLAY_STATE = "ps";
+/**
+* CMCD event type 'pr' (playback rate change).
+*
+* @public
+*/
+const CMCD_EVENT_PLAYBACK_RATE = "pr";
+/**
+* CMCD event type 'e' (error).
+*
+* @public
+*/
+const CMCD_EVENT_ERROR = "e";
+/**
+* CMCD event type 't' (time interval).
+*
+* @public
+*/
+const CMCD_EVENT_TIME_INTERVAL = "t";
+/**
+* CMCD event type 'c' (content ID).
+*
+* @public
+*/
+const CMCD_EVENT_CONTENT_ID = "c";
+/**
+* CMCD event type 'b' (backgrounded mode).
+*
+* @public
+*/
+const CMCD_EVENT_BACKGROUNDED_MODE = "b";
+/**
+* CMCD event type 'm' (mute).
+*
+* @public
+*/
+const CMCD_EVENT_MUTE = "m";
+/**
+* CMCD event type 'um' (unmute).
+*
+* @public
+*/
+const CMCD_EVENT_UNMUTE = "um";
+/**
+* CMCD event type 'pe' (player expand).
+*
+* @public
+*/
+const CMCD_EVENT_PLAYER_EXPAND = "pe";
+/**
+* CMCD event type 'pc' (player collapse).
+*
+* @public
+*/
+const CMCD_EVENT_PLAYER_COLLAPSE = "pc";
+/**
+* CMCD event type 'rr' (response received).
+*
+* @public
 */
-function appendCmcdQuery(url, cmcd, options) {
-	const query = toCmcdQuery(cmcd, options);
-	if (!query) return url;
-	if (REGEX.test(url)) return url.replace(REGEX, query);
-	return `${url}${url.includes("?") ? "&" : "?"}${query}`;
-}
-
-//#endregion
-//#region src/CMCD_DEFAULT_TIME_INTERVAL.ts
+const CMCD_EVENT_RESPONSE_RECEIVED = "rr";
 /**
-* The default time interval in seconds when using using event mode
+* CMCD event type 'as' (ad start).
 *
 * @public
 */
-const CMCD_DEFAULT_TIME_INTERVAL = 30;
-
-//#endregion
-//#region src/CMCD_KEYS.ts
+const CMCD_EVENT_AD_START = "as";
 /**
-* A list of all CMCD keys.
+* CMCD event type 'ae' (ad end).
 *
 * @public
 */
-const CMCD_KEYS = /* @__PURE__ */ [
-	...CMCD_V1_KEYS,
-	...CMCD_REQUEST_KEYS,
-	...CMCD_RESPONSE_KEYS,
-	...CMCD_EVENT_KEYS
-].filter((key, index, arr) => arr.indexOf(key) === index);
-
-//#endregion
-//#region src/CMCD_MIME_TYPE.ts
+const CMCD_EVENT_AD_END = "ae";
 /**
-* CMCD MIME type for event report payloads.
+* CMCD event type 'abs' (ad break start).
 *
 * @public
 */
-const CMCD_MIME_TYPE = "application/cmcd";
-
-//#endregion
-//#region src/CMCD_REQUEST_PROVENANCE.ts
+const CMCD_EVENT_AD_BREAK_START = "abs";
 /**
-* The `customData` key under which `CmcdReporter.createRequestReport()`
-* stamps session provenance on every request it returns.
+* CMCD event type 'abe' (ad break end).
 *
-* 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.
+* @public
+*/
+const CMCD_EVENT_AD_BREAK_END = "abe";
+/**
+* CMCD event type 'sk' (skip).
 *
-* Backed by the symbol registry so duplicated copies of this library in
-* one bundle interoperate. The registry key is stable across versions.
+* @public
+*/
+const CMCD_EVENT_SKIP = "sk";
+/**
+* CMCD event type 'ce' (custom event).
 *
 * @public
 */
-const CMCD_REQUEST_PROVENANCE = /* @__PURE__ */ Symbol.for("@svta/cml-cmcd/request-provenance");
-
-//#endregion
-//#region src/CMCD_V1.ts
+const CMCD_EVENT_CUSTOM_EVENT = "ce";
 /**
-* CMCD Version 1
+* CMCD event types for the 'e' key (event mode).
+*
+* @enum
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#event | CTA-5004-B Event}
 *
 * @public
 */
-const CMCD_V1 = 1;
+const CmcdEventType = {
+	BITRATE_CHANGE: CMCD_EVENT_BITRATE_CHANGE,
+	PLAY_STATE: CMCD_EVENT_PLAY_STATE,
+	PLAYBACK_RATE: CMCD_EVENT_PLAYBACK_RATE,
+	ERROR: CMCD_EVENT_ERROR,
+	TIME_INTERVAL: CMCD_EVENT_TIME_INTERVAL,
+	CONTENT_ID: CMCD_EVENT_CONTENT_ID,
+	BACKGROUNDED_MODE: CMCD_EVENT_BACKGROUNDED_MODE,
+	MUTE: CMCD_EVENT_MUTE,
+	UNMUTE: CMCD_EVENT_UNMUTE,
+	PLAYER_EXPAND: CMCD_EVENT_PLAYER_EXPAND,
+	PLAYER_COLLAPSE: CMCD_EVENT_PLAYER_COLLAPSE,
+	RESPONSE_RECEIVED: CMCD_EVENT_RESPONSE_RECEIVED,
+	AD_START: CMCD_EVENT_AD_START,
+	AD_END: CMCD_EVENT_AD_END,
+	AD_BREAK_START: CMCD_EVENT_AD_BREAK_START,
+	AD_BREAK_END: CMCD_EVENT_AD_BREAK_END,
+	SKIP: CMCD_EVENT_SKIP,
+	CUSTOM_EVENT: CMCD_EVENT_CUSTOM_EVENT
+};
 
 //#endregion
 //#region src/CmcdObjectType.ts
@@ -1056,7 +1465,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 +1490,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 +1546,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 +1588,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 +1664,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 +1728,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 +1799,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 +1844,7 @@ var CmcdReportRecorder = class {
 		this.#reports = [];
 	}
 	/**
-	* Return a defensive copy of all recorded reports.
+	* Return a copy of all recorded reports.
 	*
 	* @public
 	*/
@@ -1445,8 +1853,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 +1864,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 +1875,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 +1886,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
@@ -1489,6 +1897,39 @@ var CmcdReportRecorder = class {
 	}
 };
 
+//#endregion
+//#region src/CMCD_STATE_EVENT_FIELDS.ts
+/**
+* Maps each state-change event type to the persistent field whose value
+* the event signals.
+*
+* The key table (`CMCD_KEY_SPECS`) marks the field as always sent on its
+* event, so the key filter of `prepareCmcdData` does not remove it.
+* `CmcdReporter` deduplicates events against the field value. It drops an
+* event whose field has no value and restores the field if a transform
+* removes it.
+*
+* Sending the field with each state-change event is a library choice.
+* The exception is the exit from backgrounded mode, which CTA-5004-B
+* defines as a `b` event without `bg`. CTA-5004-B requires the field only
+* on the `ps` event, which MUST carry `sta`. CTA-5004-B states no such rule
+* for `pr`, `c`, or `bc`. `validateCmcdStructure` follows CTA-5004-B and
+* does not read this map.
+*
+* 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
+*/
+const CMCD_STATE_EVENT_FIELDS = /* @__PURE__ */ new Map([
+	[CMCD_EVENT_PLAY_STATE, "sta"],
+	[CMCD_EVENT_PLAYBACK_RATE, "pr"],
+	[CMCD_EVENT_CONTENT_ID, "cid"],
+	[CMCD_EVENT_BACKGROUNDED_MODE, "bg"],
+	[CMCD_EVENT_BITRATE_CHANGE, "br"]
+]);
+
 //#endregion
 //#region src/CmcdTransmissionMode.ts
 /**
@@ -1527,24 +1968,26 @@ 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. An inner list
+* with parameters, which `decodeCmcd` returns as an `SfItem` that wraps the
+* list, also stays unchanged.
 *
 * @internal
 */
 function upConvertToV2(obj) {
-	if (obj["v"] === CMCD_V2) return obj;
+	if (toBareValue(obj["v"]) === CMCD_V2) return obj;
 	const result = {};
 	for (const [key, value] of Object.entries(obj)) {
 		if (value == null) {
 			result[key] = value;
 			continue;
 		}
-		if (CMCD_INNER_LIST_KEYS.has(key) && !Array.isArray(value)) result[key] = [value];
+		if (CMCD_INNER_LIST_KEYS.has(key) && !Array.isArray(toBareValue(value))) result[key] = [value];
 		else if (key === "nor" && typeof value === "string") result[key] = [value];
 		else result[key] = value;
 	}
@@ -1581,12 +2024,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;
@@ -1595,10 +2037,9 @@ function cmcdObjectTypeListEqual(a, b) {
 		const ai = a[i];
 		const bi = b[i];
 		if (ai === bi) continue;
-		if (typeof ai === "number" || typeof bi === "number") return false;
-		if (ai.value !== bi.value) return false;
-		const ap = ai.params;
-		const bp = bi.params;
+		if ((typeof ai === "number" ? ai : ai.value) !== (typeof bi === "number" ? bi : bi.value)) return false;
+		const ap = typeof ai === "number" ? void 0 : ai.params;
+		const bp = typeof bi === "number" ? void 0 : bi.params;
 		const ak = ap && Object.keys(ap)[0];
 		const bk = bp && Object.keys(bp)[0];
 		if (ak !== bk) return false;
@@ -1606,6 +2047,18 @@ function cmcdObjectTypeListEqual(a, b) {
 	}
 	return true;
 }
+/**
+* Equality for `br` deduplication. A `br` value can be an `SfItem` that
+* wraps the list, as `decodeCmcd` returns for an inner list with
+* parameters. Two values are equal when their lists are equal. The
+* parameters of the list are not compared.
+*/
+function brEqual(a, b) {
+	const listA = toBareValue(a);
+	const listB = toBareValue(b);
+	if (!Array.isArray(listA) || !Array.isArray(listB)) return Object.is(a, b);
+	return cmcdObjectTypeListEqual(listA, listB);
+}
 const equal = Object.is;
 const identity = (v) => v;
 /**
@@ -1616,8 +2069,8 @@ const STATE_FIELDS = /* @__PURE__ */ Array.from(CMCD_STATE_EVENT_FIELDS, ([event
 	if (field === "br") return {
 		event,
 		field,
-		equal: (a, b) => a === void 0 || b === void 0 ? a === b : cmcdObjectTypeListEqual(a, b),
-		snapshot: (v) => v.slice()
+		equal: brEqual,
+		snapshot: (v) => Array.isArray(v) ? v.slice() : copyItemValue(v)
 	};
 	return {
 		event,
@@ -1627,57 +2080,48 @@ 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.
-*/
-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"]
-]);
-/**
-* 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.
+* Maps each event type to the key that a report of that type must keep,
+* beyond `e` and `ts`. Built from the state-change table plus the three
+* event types whose required key is event data, not player state.
 */
-function isUsableRequiredValue(value) {
-	if (value == null || value === "") return false;
-	if (typeof value === "number") return Number.isFinite(value);
-	return !Array.isArray(value) || value.length > 0;
-}
+const CMCD_REQUIRED_EVENT_KEYS = /* @__PURE__ */ buildRequiredEventKeys();
 /**
-* Copies an `SfItem`-shaped value and its `params` record.
+* Copies a value with the `SfItem` structure, including its `params` record
+* and the list of an `SfItem` that wraps a list.
 *
-* 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;
 	const copy = Object.assign(Object.create(Object.getPrototypeOf(value)), value);
 	if (copy.params !== null && typeof copy.params === "object") copy.params = { ...copy.params };
+	if (Array.isArray(copy.value)) copy.value = copy.value.map(copyItemValue);
 	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. `decodeCmcd` also returns an `SfItem` that wraps a list, and the
+* copy includes that list. `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 +2136,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 +2154,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 +2196,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 +2213,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 +2231,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();
@@ -1804,7 +2247,7 @@ var CmcdReporter = class {
 			provenance: mintProvenance(sid, data.cid),
 			data,
 			msd: NaN,
-			lastEmitted: {},
+			lastEmitted: toBareValue(data.bg) === true ? {} : { bg: false },
 			eventTargets,
 			requestTarget: {
 				sn: 0,
@@ -1813,11 +2256,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 +2280,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 +2297,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 +2308,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 +2318,45 @@ 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.
+	* 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`.
 	*
-	* 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.
+	* 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 `sid` change resets the dedup baseline.
+	* 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.
 	*
-	* `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
+	* 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.
 	*/
@@ -1928,19 +2378,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 +2408,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 })`).
+	* 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.
 	*
-	* 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 +2483,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;
@@ -2054,6 +2504,7 @@ var CmcdReporter = class {
 			e: type,
 			ts: data.ts ?? Date.now()
 		};
+		if (type === CMCD_EVENT_BACKGROUNDED_MODE && toBareValue(item.bg) === false) delete item.bg;
 		const { transform } = config;
 		if (!transform) {
 			this.queueTargetEvent(session, target, config, item, type);
@@ -2065,20 +2516,19 @@ var CmcdReporter = class {
 		const ts = item.ts;
 		const report = transform(item, request);
 		if (report == null) return;
-		if (!isUsableRequiredValue(report.ts)) report.ts = ts;
-		if (requiredKey && isUsableRequiredValue(requiredValue) && !isUsableRequiredValue(report[requiredKey])) Object.assign(report, { [requiredKey]: requiredValue });
+		if (!isValid(report.ts)) report.ts = ts;
+		if (requiredKey && isValid(requiredValue) && !isValid(report[requiredKey])) Object.assign(report, { [requiredKey]: requiredValue });
 		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 +2546,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,60 +2557,57 @@ 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
-	* {@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.
+	* 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.
 	*
-	* 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.
+	* 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` 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.
 	*/
 	recordResponseReceived(response, data = {}) {
 		const { request } = response;
 		const url = data.url ?? request?.url;
 		if (!url) return;
 		const provenance = request.customData?.[CMCD_REQUEST_PROVENANCE];
-		const session = this.resolveSession(provenance);
+		const session = provenance === void 0 ? this.session : this.resolveSession(provenance);
 		if (!session) return;
-		const cmcd = decodeSnapshot(provenance);
-		const { cid } = provenance;
+		const cmcd = provenance === void 0 ? { ...request.customData?.cmcd } : decodeSnapshot(provenance);
+		const { cid } = provenance ?? {};
 		const urlObj = new URL(url);
 		urlObj.searchParams.delete(CMCD_PARAM);
 		const derived = {
@@ -2183,13 +2630,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 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.
 	*/
 	resolveSession(provenance) {
 		if (provenance === null || typeof provenance !== "object") return;
@@ -2197,8 +2644,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 +2656,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 +2691,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 +2757,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 +2781,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 +2792,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) => {
@@ -2475,6 +2923,63 @@ function fromCmcdUrl(url, options) {
 	return decodeCmcd(decodeURIComponent(url.replace(/^CMCD=/, "")), options);
 }
 
+//#endregion
+//#region src/isCmcdRequestKey.ts
+const CMCD_REQUEST_KEY_SET = /* @__PURE__ */ new Set(CMCD_REQUEST_KEYS);
+/**
+* Check if a key is a valid CMCD request key.
+*
+* @param key - The key to check.
+*
+* @returns `true` if the key is a valid CMCD request key, `false` otherwise.
+*
+* @public
+*
+* @example
+* {@includeCode ../test/isCmcdRequestKey.test.ts#example}
+*/
+function isCmcdRequestKey(key) {
+	return CMCD_REQUEST_KEY_SET.has(key) || isCmcdCustomKey(key);
+}
+
+//#endregion
+//#region src/isCmcdResponseReceivedKey.ts
+const CMCD_RESPONSE_KEY_SET = /* @__PURE__ */ new Set(CMCD_RESPONSE_KEYS);
+/**
+* Check if a key is a valid CMCD response key.
+*
+* @param key - The key to check.
+*
+* @returns `true` if the key is a valid CMCD response key, `false` otherwise.
+*
+* @public
+*
+* @example
+* {@includeCode ../test/isCmcdResponseReceivedKey.test.ts#example}
+*/
+function isCmcdResponseReceivedKey(key) {
+	return CMCD_RESPONSE_KEY_SET.has(key);
+}
+
+//#endregion
+//#region src/isCmcdEventKey.ts
+const CMCD_EVENT_KEY_SET = /* @__PURE__ */ new Set(CMCD_EVENT_KEYS);
+/**
+* Check if a key is a valid CMCD event key.
+*
+* @param key - The key to check.
+*
+* @returns `true` if the key is a valid CMCD event key, `false` otherwise.
+*
+* @public
+*
+* @example
+* {@includeCode ../test/isCmcdEventKey.test.ts#example}
+*/
+function isCmcdEventKey(key) {
+	return isCmcdRequestKey(key) || isCmcdResponseReceivedKey(key) || CMCD_EVENT_KEY_SET.has(key);
+}
+
 //#endregion
 //#region src/isCmcdV1Data.ts
 /**
@@ -2493,6 +2998,25 @@ function isCmcdV1Data(data) {
 	return data.v !== CMCD_V2;
 }
 
+//#endregion
+//#region src/isCmcdV1Key.ts
+const CMCD_V1_KEY_SET$1 = /* @__PURE__ */ new Set(CMCD_V1_KEYS);
+/**
+* Filter for CMCD version 1 keys.
+*
+* @param key - The CMCD key to filter.
+*
+* @returns `true` if the key should be included, `false` otherwise.
+*
+* @public
+*
+* @example
+* {@includeCode ../test/isCmcdV1Key.test.ts#example}
+*/
+function isCmcdV1Key(key) {
+	return CMCD_V1_KEY_SET$1.has(key) || isCmcdCustomKey(key);
+}
+
 //#endregion
 //#region src/isCmcdV2Data.ts
 /**
@@ -2517,7 +3041,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,13 +3068,13 @@ 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
 */
 function resolveVersion(data, options) {
 	if (options?.version === 1 || options?.version === 2) return options.version;
-	const payloadVersion = data["v"];
+	const payloadVersion = toBareValue(data["v"]);
 	if (payloadVersion === 1 || payloadVersion === 2) return payloadVersion;
 	return CMCD_V1;
 }
@@ -2591,6 +3115,51 @@ function validateCmcdKeys(data, options) {
 	};
 }
 
+//#endregion
+//#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_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/validateCmcdStructure.ts
 /**
@@ -2658,9 +3227,9 @@ function validateCmcdStructure(data, options) {
 			message: `Response key "${key}" must only be present when e="rr".`,
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
 		});
-		for (const [stateEventType, requiredField] of CMCD_STATE_EVENT_FIELDS) if (eventType === stateEventType && !(requiredField in data)) issues.push({
-			key: requiredField,
-			message: `State-change event (e="${stateEventType}") requires the "${requiredField}" key to be present.`,
+		if (eventType === CMCD_EVENT_PLAY_STATE && !("sta" in data)) issues.push({
+			key: "sta",
+			message: "Play state change event (e=\"ps\") requires the \"sta\" key to be present.",
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
 		});
 		if (eventType === CMCD_EVENT_ERROR && !("ec" in data)) issues.push({
@@ -2669,9 +3238,27 @@ function validateCmcdStructure(data, options) {
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
 		});
 	}
-	if ("v" in data && data["v"] !== 1 && data["v"] !== 2) issues.push({
+	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
+		});
+	}
+	const v = toBareValue(data["v"]);
+	if ("v" in data && v !== 1 && v !== 2) issues.push({
 		key: "v",
-		message: `Unsupported CMCD version "${String(data["v"])}". Expected 1 or 2.`,
+		message: `Unsupported CMCD version "${String(v)}". Expected 1 or 2.`,
 		severity: CMCD_VALIDATION_SEVERITY_ERROR
 	});
 	else if (version > 1 && !("v" in data)) issues.push({
@@ -2693,7 +3280,7 @@ function validateCmcdStructure(data, options) {
 //#endregion
 //#region src/CMCD_KEY_TYPES.ts
 /**
-* CMCD key value type: inner list of numbers with token identifiers.
+* CMCD key value type: inner list of integers with token identifiers.
 *
 * @internal
 */
@@ -2735,8 +3322,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,15 +3381,15 @@ 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
 */
 const CMCD_V1_KEY_TYPE_OVERRIDES = {
 	bl: CMCD_KEY_TYPE_INTEGER,
-	br: CMCD_KEY_TYPE_NUMBER,
+	br: CMCD_KEY_TYPE_INTEGER,
 	mtp: CMCD_KEY_TYPE_INTEGER,
-	tb: CMCD_KEY_TYPE_NUMBER,
+	tb: CMCD_KEY_TYPE_INTEGER,
 	nor: CMCD_KEY_TYPE_STRING
 };
 
@@ -2893,22 +3480,31 @@ const CMCD_TOKEN_VALUES = {
 
 //#endregion
 //#region src/validateCmcdValues.ts
-const HUNDRED_ROUNDING_KEYS = /* @__PURE__ */ new Set([
-	"bl",
-	"dl",
-	"mtp",
-	"rtp",
-	"tbl"
-]);
-const INTEGER_ROUNDING_KEYS = /* @__PURE__ */ new Set([
-	"br",
-	"d",
-	"tb"
-]);
+const HUNDRED_ROUNDING_UNITS = {
+	bl: "ms",
+	dl: "ms",
+	mtp: "kbps",
+	rtp: "kbps",
+	tbl: "ms"
+};
 function isFiniteNumber(value) {
 	return typeof value === "number" && Number.isFinite(value);
 }
-function validateListValue(key, value, issues) {
+function isInteger(value) {
+	return Number.isInteger(value);
+}
+function validateRounding(key, value, version, issues, index) {
+	const unit = HUNDRED_ROUNDING_UNITS[key];
+	if (!unit || value % 100 === 0) return;
+	const should = key === "tbl" || key === "bl" && version !== CMCD_V1;
+	const target = index === void 0 ? `Key "${key}"` : `Key "${key}" array element [${index}]`;
+	issues.push({
+		key,
+		message: `${target} ${should ? "should" : "must"} be rounded to the nearest 100 ${unit}. Received ${value}.`,
+		severity: should ? CMCD_VALIDATION_SEVERITY_WARNING : CMCD_VALIDATION_SEVERITY_ERROR
+	});
+}
+function validateListValue(key, value, version, issues) {
 	if (!Array.isArray(value)) {
 		issues.push({
 			key,
@@ -2918,18 +3514,13 @@ function validateListValue(key, value, issues) {
 		return;
 	}
 	for (let i = 0; i < value.length; i++) {
-		const element = value[i];
-		if (element instanceof SfItem) {
-			if (!isFiniteNumber(element.value)) issues.push({
-				key,
-				message: `Key "${key}" array element [${i}] must be a finite number.`,
-				severity: CMCD_VALIDATION_SEVERITY_ERROR
-			});
-		} else if (!isFiniteNumber(element)) issues.push({
+		const element = toBareValue(value[i]);
+		if (!isInteger(element)) issues.push({
 			key,
-			message: `Key "${key}" array element [${i}] must be a finite number.`,
+			message: `Key "${key}" array element [${i}] must be a finite integer.`,
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
 		});
+		else validateRounding(key, element, version, issues, i);
 	}
 }
 function validateStringArrayValue(key, value, issues) {
@@ -2941,20 +3532,11 @@ function validateStringArrayValue(key, value, issues) {
 		});
 		return;
 	}
-	for (let i = 0; i < value.length; i++) {
-		const element = value[i];
-		if (element instanceof SfItem) {
-			if (typeof element.value !== "string") issues.push({
-				key,
-				message: `Key "${key}" array element [${i}] must be a string.`,
-				severity: CMCD_VALIDATION_SEVERITY_ERROR
-			});
-		} else if (typeof element !== "string") issues.push({
-			key,
-			message: `Key "${key}" array element [${i}] must be a string.`,
-			severity: CMCD_VALIDATION_SEVERITY_ERROR
-		});
-	}
+	for (let i = 0; i < value.length; i++) if (typeof toBareValue(value[i]) !== "string") issues.push({
+		key,
+		message: `Key "${key}" array element [${i}] must be a string.`,
+		severity: CMCD_VALIDATION_SEVERITY_ERROR
+	});
 }
 /**
 * Validates that all values in a CMCD payload conform to the expected types and constraints.
@@ -2973,7 +3555,8 @@ function validateStringArrayValue(key, value, issues) {
 function validateCmcdValues(data, options) {
 	const version = resolveVersion(data, options);
 	const issues = [];
-	for (const [key, value] of Object.entries(data)) {
+	for (const [key, entry] of Object.entries(data)) {
+		const value = toBareValue(entry);
 		if (isCmcdCustomKey(key)) {
 			if (typeof value !== "string") issues.push({
 				key,
@@ -3000,16 +3583,12 @@ function validateCmcdValues(data, options) {
 		if (version === CMCD_V1 && key in CMCD_V1_KEY_TYPE_OVERRIDES) expectedType = CMCD_V1_KEY_TYPE_OVERRIDES[key];
 		switch (expectedType) {
 			case CMCD_KEY_TYPE_INTEGER:
-				if (!isFiniteNumber(value) || !Number.isInteger(value)) issues.push({
+				if (!isInteger(value)) issues.push({
 					key,
 					message: `Key "${key}" must be a finite integer.`,
 					severity: CMCD_VALIDATION_SEVERITY_ERROR
 				});
-				else if (HUNDRED_ROUNDING_KEYS.has(key) && value % 100 !== 0) issues.push({
-					key,
-					message: `Key "${key}" should be rounded to the nearest 100.`,
-					severity: CMCD_VALIDATION_SEVERITY_WARNING
-				});
+				else validateRounding(key, value, version, issues);
 				break;
 			case CMCD_KEY_TYPE_NUMBER:
 				if (!isFiniteNumber(value)) issues.push({
@@ -3017,16 +3596,6 @@ function validateCmcdValues(data, options) {
 					message: `Key "${key}" must be a finite number.`,
 					severity: CMCD_VALIDATION_SEVERITY_ERROR
 				});
-				else if (HUNDRED_ROUNDING_KEYS.has(key) && value % 100 !== 0) issues.push({
-					key,
-					message: `Key "${key}" should be rounded to the nearest 100.`,
-					severity: CMCD_VALIDATION_SEVERITY_WARNING
-				});
-				else if (INTEGER_ROUNDING_KEYS.has(key) && !Number.isInteger(value)) issues.push({
-					key,
-					message: `Key "${key}" should be rounded to an integer.`,
-					severity: CMCD_VALIDATION_SEVERITY_WARNING
-				});
 				break;
 			case CMCD_KEY_TYPE_BOOLEAN:
 				if (typeof value !== "boolean") issues.push({
@@ -3058,7 +3627,7 @@ function validateCmcdValues(data, options) {
 				break;
 			}
 			case CMCD_KEY_TYPE_NUMBER_LIST:
-				validateListValue(key, value, issues);
+				validateListValue(key, value, version, issues);
 				break;
 			case CMCD_KEY_TYPE_STRING_LIST:
 				validateStringArrayValue(key, value, issues);
@@ -3098,8 +3667,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 +3696,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 +3718,10 @@ function validateCmcdEvents(cmcd, options) {
 		});
 	}
 	return {
-		...mergeValidationResults(...lineResults),
+		...mergeValidationResults({
+			valid: true,
+			issues: bodyIssues
+		}, ...lineResults),
 		data: decodedLines
 	};
 }
@@ -3157,8 +3734,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 +3801,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 +3869,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 +3889,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 +3933,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);