@svta/cml-cmcd 2.7.0 → 2.8.1

package/dist/index.js

@@ -1,462 +1,6 @@
 import { SfItem, SfToken, decodeSfDict, encodeSfDict, symbolToStr } from "@svta/cml-structured-field-values";
 import { getBaseUrl, urlToRelativePath, uuid } from "@svta/cml-utils";
 
-//#region src/CMCD_AGGREGATE_BITRATE_KEYS.ts
-/**
-* Maps each aggregate bitrate key to the exact bitrate key that supersedes it.
-*
-* Per CTA-5004-B, `ab` MUST NOT be sent when the encoded bitrate `br` is
-* known. `lab` and `tab` follow the same rule for the lowest bitrate `lb`
-* and the top bitrate `tb`.
-*
-* @internal
-*/
-const CMCD_AGGREGATE_BITRATE_KEYS = {
-	ab: "br",
-	lab: "lb",
-	tab: "tb"
-};
-
-//#endregion
-//#region src/CMCD_FORMATTER_MAP.ts
-const roundValue = (value) => {
-	if (value instanceof SfItem) return new SfItem(Math.round(value.value), value.params);
-	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);
-};
-/**
-* The default formatters for CMCD values.
-*
-* @public
-*/
-const CMCD_FORMATTER_MAP = {
-	br: toRounded,
-	d: toRounded,
-	bl: toHundred,
-	dl: toHundred,
-	mtp: toHundred,
-	nor,
-	rtp: toHundred,
-	tb: toRounded
-};
-
-//#endregion
-//#region src/CMCD_KEY_OBJECT_TYPES.ts
-/**
-* Maps a key to the object types (`ot`) for which CTA-5004-B allows the key.
-*
-* A key that is absent from this map is allowed for every object type.
-* `d` (Object duration) and `tpb` (Top playable bitrate) MUST NOT be sent for
-* other object types.
-*
-* @internal
-*/
-const CMCD_KEY_OBJECT_TYPES = {
-	d: [
-		"a",
-		"v",
-		"av",
-		"tt",
-		"c",
-		"o"
-	],
-	tpb: [
-		"a",
-		"v",
-		"av",
-		"c"
-	]
-};
-
-//#endregion
-//#region src/CMCD_V2.ts
-/**
-* CMCD Version 2
-*
-* @public
-*/
-const CMCD_V2 = 2;
-
-//#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
-*/
-const CMCD_EVENT_RESPONSE_RECEIVED = "rr";
-/**
-* CMCD event type 'as' (ad start).
-*
-* @public
-*/
-const CMCD_EVENT_AD_START = "as";
-/**
-* CMCD event type 'ae' (ad end).
-*
-* @public
-*/
-const CMCD_EVENT_AD_END = "ae";
-/**
-* CMCD event type 'abs' (ad break start).
-*
-* @public
-*/
-const CMCD_EVENT_AD_BREAK_START = "abs";
-/**
-* CMCD event type 'abe' (ad break end).
-*
-* @public
-*/
-const CMCD_EVENT_AD_BREAK_END = "abe";
-/**
-* CMCD event type 'sk' (skip).
-*
-* @public
-*/
-const CMCD_EVENT_SKIP = "sk";
-/**
-* CMCD event type 'ce' (custom event).
-*
-* @public
-*/
-const CMCD_EVENT_CUSTOM_EVENT = "ce";
-/**
-* 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 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/CMCD_STATE_EVENT_FIELDS.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. Each event must include the field whose value
-* it signals. Callers force-include the field after filtering
-* (`prepareCmcdData`), deduplicate against its value (`CmcdReporter`), and
-* check its presence in payloads (`validateCmcdStructure`).
-*
-* Iteration order 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/CmcdReportingMode.ts
-/**
-* CMCD event mode variable name.
-*
-* @public
-*/
-const CMCD_EVENT_MODE = "event";
-/**
-* CMCD request mode variable name.
-*
-* @public
-*/
-const CMCD_REQUEST_MODE = "request";
-/**
-* CMCD reporting mode types.
-*
-* @enum
-*
-* @public
-*/
-const CmcdReportingMode = {
-	REQUEST: CMCD_REQUEST_MODE,
-	EVENT: CMCD_EVENT_MODE
-};
-
-//#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_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/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 . -`. 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.
-*
-* @returns `true` if the key is a custom key, `false` otherwise.
-*
-* @public
-*
-* @example
-* {@includeCode ../test/isCmcdCustomKey.test.ts#example}
-*/
-function isCmcdCustomKey(key) {
-	const separator = key.indexOf("-", 1);
-	return separator > 0 && separator < key.length - 1 && CUSTOM_KEY_REGEX.test(key);
-}
-
-//#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/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/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/CMCD_INNER_LIST_KEYS.ts
 /**
 * Inner-list keys in version 2 that are scalars in version 1.
@@ -483,72 +27,424 @@ const CMCD_INNER_LIST_KEYS = new Set([
 ]);
 
 //#endregion
-//#region src/CMCD_V1_KEYS.ts
+//#region src/CMCD_KEY_SPECS.ts
+const MEDIA = [
+	"a",
+	"v",
+	"av",
+	"tt",
+	"c",
+	"o"
+];
 /**
-* Defines the keys for CMCD (Common Media Client Data) version 1.
+* 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`.
+*
+* @internal
+*/
+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_V2.ts
+/**
+* CMCD Version 2
 *
 * @public
 */
-const CMCD_V1_KEYS = [
-	"bl",
-	"br",
-	"bs",
-	"cid",
-	"d",
-	"dl",
-	"mtp",
-	"nor",
-	"nrr",
-	"ot",
-	"pr",
-	"rtp",
-	"sf",
-	"sid",
-	"st",
-	"su",
-	"tb",
-	"v"
-];
+const CMCD_V2 = 2;
 
 //#endregion
-//#region src/isCmcdV1Key.ts
-const CMCD_V1_KEY_SET$1 = /* @__PURE__ */ new Set(CMCD_V1_KEYS);
+//#region src/CmcdReportingMode.ts
 /**
-* Filter for CMCD version 1 keys.
+* CMCD event mode variable name.
 *
-* @param key - The CMCD key to filter.
+* @public
+*/
+const CMCD_EVENT_MODE = "event";
+/**
+* CMCD request mode variable name.
 *
-* @returns `true` if the key should be included, `false` otherwise.
+* @public
+*/
+const CMCD_REQUEST_MODE = "request";
+/**
+* CMCD reporting mode types.
+*
+* @enum
 *
 * @public
+*/
+const CmcdReportingMode = {
+	REQUEST: CMCD_REQUEST_MODE,
+	EVENT: CMCD_EVENT_MODE
+};
+
+//#endregion
+//#region src/downConvertToV1.ts
+function hasParams(params) {
+	for (const _ in params) return true;
+	return false;
+}
+/**
+* Unwrap an inner list or SfItem value to a scalar.
 *
-* @example
-* {@includeCode ../test/isCmcdV1Key.test.ts#example}
+* 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`.
 */
-function isCmcdV1Key(key) {
-	return CMCD_V1_KEY_SET$1.has(key) || isCmcdCustomKey(key);
+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;
+}
+/**
+* Down-convert version 2 CMCD data to version 1.
+*
+* - Extracts `nrr` from the `nor` SfItem's `r` parameter.
+* - Unwraps inner-list values to scalars for the object type `ot`.
+*
+* @internal
+*/
+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/isTokenField.ts
-const TOKEN_FIELDS = /* @__PURE__ */ new Set([
-	"ot",
-	"sf",
-	"st",
-	"e",
-	"sta"
-]);
+//#region src/isCmcdCustomKey.ts
+const CUSTOM_KEY_REGEX = /^[a-z][a-z0-9.-]*$/;
 /**
-* Checks if the given key is a token field.
+* Check if a key is a valid custom key: a lowercase first letter, then
+* 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.
 *
-* @returns `true` if the key is a token field.
+* @returns `true` if the key is a custom key, `false` otherwise.
+*
+* @public
+*
+* @example
+* {@includeCode ../test/isCmcdCustomKey.test.ts#example}
+*/
+function isCmcdCustomKey(key) {
+	const separator = key.indexOf("-", 1);
+	return separator > 0 && separator < key.length - 1 && CUSTOM_KEY_REGEX.test(key);
+}
+
+//#endregion
+//#region src/getKeySpec.ts
+const CUSTOM_KEY_SPEC = {
+	type: "custom",
+	omitDefault: false,
+	max: 64,
+	v1Max: Infinity
+};
+/**
+* Returns the row of a key in the key table.
+*
+* @param key - The key to look up.
+*
+* @returns The row of a reserved key, the custom row for a valid custom key, or `undefined`.
 *
 * @internal
 */
-function isTokenField(key) {
-	return TOKEN_FIELDS.has(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
@@ -572,6 +468,60 @@ function isValid(value) {
 	return value != null && value !== "" && value !== false;
 }
 
+//#endregion
+//#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;
+}
+/**
+* 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.
+*
+* @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.
+*
+* @returns The formatted value, or `undefined` when no entry is a non-empty string.
+*
+* @internal
+*/
+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/toTokenString.ts
 /**
@@ -593,52 +543,128 @@ function toTokenString(value) {
 }
 
 //#endregion
-//#region src/prepareCmcdData.ts
-const filterMap = {
-	event: isCmcdEventKey,
-	request: isCmcdRequestKey
-};
+//#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;
+}
 /**
-* Unwrap an inner list or SfItem value to a scalar.
+* Applies the value rule of a key type from the key table.
+*
+* 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 The value to send, or `undefined` when the value fails the rule.
+*
+* @internal
 */
-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 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/toBareValue.ts
 /**
-* Down-convert version 2 CMCD data to version 1.
+* Returns the value inside an `SfItem`, or the value itself.
 *
-* - Extracts `nrr` from the `nor` SfItem's `r` parameter.
-* - Unwraps inner-list values to scalars.
+* `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 read.
+* @returns The value without its parameters.
+*
+* @internal
 */
-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;
-	}
-	return result;
+function toBareValue(value) {
+	return value instanceof SfItem ? value.value : value;
+}
+
+//#endregion
+//#region src/prepareCmcdData.ts
+function hasKey(spec, reportingMode, isV1) {
+	return (spec.mode === void 0 || spec.mode === reportingMode) && (spec.version === void 0 || spec.version === 1 === isV1);
+}
+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 formatValue(key, value, options, formatterOptions) {
-	const formatter = options.formatters?.[key] ?? CMCD_FORMATTER_MAP[key];
-	return typeof formatter === "function" && isValid(value) ? formatter(value, formatterOptions) : value;
+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 formatted;
 }
 /**
 * Convert a generic object to CMCD data.
@@ -654,61 +680,66 @@ function formatValue(key, value, options, formatterOptions) {
 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();
+	const filter = options.filter;
+	let objectTypeValue;
 	let objectType;
-	let objectTypeResolved = false;
-	for (const key of keys) {
-		let value = data[key];
-		const exactKey = CMCD_AGGREGATE_BITRATE_KEYS[key];
-		if (exactKey && keys.includes(exactKey) && isValid(formatValue(exactKey, data[exactKey], options, formatterOptions))) continue;
-		const objectTypes = version > 1 ? CMCD_KEY_OBJECT_TYPES[key] : void 0;
-		if (objectTypes) {
-			if (!objectTypeResolved) {
-				const ot = formatValue("ot", data["ot"], options, formatterOptions);
-				objectType = isValid(ot) ? toTokenString(ot) : void 0;
-				objectTypeResolved = true;
-			}
-			if (objectType !== void 0 && !objectTypes.includes(objectType)) continue;
+	if (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 === "cen" && eventType !== CMCD_EVENT_CUSTOM_EVENT) continue;
-		value = formatValue(key, value, options, formatterOptions);
-		if (key === "v") if (version === 1) continue;
-		else value = version;
-		if (key === "pr" && value === 1 && !(isEventMode && eventType === CMCD_EVENT_PLAYBACK_RATE)) continue;
-		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);
+		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;
 }
@@ -916,15 +947,6 @@ function appendCmcdHeaders(headers, cmcd, options) {
 	return Object.assign(headers, toCmcdHeaders(cmcd, options));
 }
 
-//#endregion
-//#region src/CMCD_PARAM.ts
-/**
-* CMCD parameter name.
-*
-* @public
-*/
-const CMCD_PARAM = "CMCD";
-
 //#endregion
 //#region src/encodePreparedCmcd.ts
 /**
@@ -962,53 +984,99 @@ function encodeCmcd(cmcd, options = {}) {
 }
 
 //#endregion
-//#region src/toCmcdUrl.ts
+//#region src/CMCD_PARAM.ts
 /**
-* Convert a CMCD object to a URL encoded string.
+* CMCD parameter name.
 *
-* @param cmcd - The CMCD object to convert.
-* @param options - Options for encoding.
+* @public
+*/
+const CMCD_PARAM = "CMCD";
+
+//#endregion
+//#region src/percentEncode.ts
+const SUB_DELIMS_REGEX = /[!'()*]/g;
+const SURROGATE_REGEX = /[\uD800-\uDBFF][\uDC00-\uDFFF]|[\uD800-\uDFFF]/g;
+function encodeSubDelim(char) {
+	return `%${char.charCodeAt(0).toString(16).toUpperCase()}`;
+}
+function replaceUnpaired(match) {
+	return match.length === 2 ? match : "�";
+}
+/**
+* Percent-encode a string for the `CMCD` query parameter.
 *
-* @returns The URL encoded CMCD data.
+* Only the unreserved characters of RFC 3986 stay unencoded: letters, digits,
+* `-`, `.`, `_`, and `~`. The query examples of CTA-5004-B use this encoding.
+* An unpaired surrogate becomes U+FFFD.
 *
-* @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}
+* @param value - The string to encode.
+* @returns The encoded string.
 *
-* @public
+* @internal
 */
-function toCmcdUrl(cmcd, options = {}) {
-	if (!cmcd) return "";
-	const params = encodeCmcd(cmcd, options);
-	return encodeURIComponent(params);
+function percentEncode(value) {
+	let encoded;
+	try {
+		encoded = encodeURIComponent(value);
+	} catch {
+		encoded = encodeURIComponent(value.replace(SURROGATE_REGEX, replaceUnpaired));
+	}
+	return encoded.replace(SUB_DELIMS_REGEX, encodeSubDelim);
 }
 
 //#endregion
-//#region src/toCmcdQuery.ts
+//#region src/replaceCmcdParam.ts
+function isCmcdParam(param) {
+	return param === CMCD_PARAM || param.startsWith(`${CMCD_PARAM}=`);
+}
 /**
-* Convert a CMCD object to a query arg.
-*
-* @param cmcd - The CMCD object to convert.
-* @param options - Options for encoding.
-*
-* @returns The CMCD query arg.
+* Replace the `CMCD` query parameter of a URL.
 *
-* @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}
+* The first `CMCD` parameter takes the new value in place. The function
+* removes the other `CMCD` parameters. If the URL has no `CMCD` parameter,
+* the new parameter goes at the end of the query. An empty `value` only
+* removes the parameters. The function does not change the rest of the URL.
+* The URL can be relative.
 *
-* @public
+* @param url - The URL.
+* @param value - The encoded CMCD data, before percent-encoding.
+* @returns The URL with at most one `CMCD` parameter.
 *
-* @example
-* {@includeCode ../test/toCmcdQuery.test.ts#example}
+* @internal
 */
-function toCmcdQuery(cmcd, options = {}) {
-	if (!cmcd) return "";
-	return `${CMCD_PARAM}=${toCmcdUrl(cmcd, options)}`;
+function replaceCmcdParam(url, value) {
+	const hashIndex = url.indexOf("#");
+	const end = hashIndex === -1 ? url.length : hashIndex;
+	const queryIndex = url.indexOf("?");
+	const start = queryIndex === -1 || queryIndex > end ? end : queryIndex;
+	const params = [];
+	let param = value ? `${CMCD_PARAM}=${percentEncode(value)}` : "";
+	let found = false;
+	for (const item of start < end ? url.slice(start + 1, end).split("&") : []) if (!isCmcdParam(item)) params.push(item);
+	else {
+		found = true;
+		if (param) {
+			params.push(param);
+			param = "";
+		}
+	}
+	if (param) {
+		if (params[params.length - 1] === "") params.pop();
+		params.push(param);
+	} else if (!found) return url;
+	const query = params.join("&");
+	return `${url.slice(0, start)}${query ? `?${query}` : ""}${url.slice(end)}`;
 }
 
 //#endregion
 //#region src/appendCmcdQuery.ts
-const REGEX = /CMCD=[^&#]+/;
 /**
 * Append CMCD query args to a URL.
 *
+* If the URL has a `CMCD` parameter, the new value replaces it in place. The
+* other parameters and the fragment stay as they are. If the data has no keys
+* to send, the function returns the URL unchanged.
+*
 * @param url - The URL to append to.
 * @param cmcd - The CMCD object to append.
 * @param options - Options for encoding.
@@ -1023,10 +1091,8 @@ const REGEX = /CMCD=[^&#]+/;
 * @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}`;
+	const value = cmcd ? encodeCmcd(cmcd, options) : "";
+	return value ? replaceCmcdParam(url, value) : url;
 }
 
 //#endregion
@@ -1038,6 +1104,176 @@ function appendCmcdQuery(url, cmcd, options) {
 */
 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
 /**
@@ -1087,16 +1323,156 @@ const CMCD_MIME_TYPE = "application/cmcd";
 *
 * @public
 */
-const CMCD_REQUEST_PROVENANCE = /* @__PURE__ */ Symbol.for("@svta/cml-cmcd/request-provenance");
-
-//#endregion
-//#region src/CMCD_V1.ts
+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
+*/
+const CMCD_EVENT_RESPONSE_RECEIVED = "rr";
+/**
+* CMCD event type 'as' (ad start).
+*
+* @public
+*/
+const CMCD_EVENT_AD_START = "as";
+/**
+* CMCD event type 'ae' (ad end).
+*
+* @public
+*/
+const CMCD_EVENT_AD_END = "ae";
+/**
+* CMCD event type 'abs' (ad break start).
+*
+* @public
+*/
+const CMCD_EVENT_AD_BREAK_START = "abs";
+/**
+* CMCD event type 'abe' (ad break end).
+*
+* @public
+*/
+const CMCD_EVENT_AD_BREAK_END = "abe";
+/**
+* CMCD event type 'sk' (skip).
+*
+* @public
+*/
+const CMCD_EVENT_SKIP = "sk";
+/**
+* CMCD event type 'ce' (custom event).
+*
+* @public
+*/
+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
@@ -1556,6 +1932,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
 /**
@@ -1599,19 +2008,21 @@ const CmcdTransmissionMode = {
 * - Wraps scalar values in arrays for inner-list keys.
 * - Wraps `nor` string in an array.
 *
-* The function returns version 2 data (has `v: 2`) 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;
 	}
@@ -1661,10 +2072,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;
@@ -1672,6 +2082,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;
 /**
@@ -1682,8 +2104,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,
@@ -1702,29 +2124,14 @@ function buildRequiredEventKeys() {
 	]);
 }
 /**
-* 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 is event data, not player state.
+* 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.
 */
 const CMCD_REQUIRED_EVENT_KEYS = /* @__PURE__ */ buildRequiredEventKeys();
 /**
-* Whether a required key's value will survive report preparation.
-*
-* This is `isValid` without its `false` exclusion. `false` must count as
-* usable because `bg: false` is a valid value on a backgrounded-mode event,
-* which the encoder writes as `?0`. If `false` counted as unusable,
-* restoration would silently revert a transform that cleared the key.
-* Later processing drops empty strings, empty lists, and non-finite numbers.
-* A transform that substitutes one of them leaves the report without a
-* required key.
-*/
-function isUsableRequiredValue(value) {
-	if (value == null || value === "") return false;
-	if (typeof value === "number") return Number.isFinite(value);
-	return !Array.isArray(value) || value.length > 0;
-}
-/**
-* Copies a value with the `SfItem` structure, including 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 copy keeps the prototype because `prepareCmcdData`, the formatter map,
 * validation, and the structured-field encoder all branch on
@@ -1735,6 +2142,7 @@ 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;
 }
 /**
@@ -1744,7 +2152,8 @@ function copyItemValue(value) {
 *
 * The copy is complete for the CMCD value space. `CmcdValue` and
 * `CmcdCustomValue` admit only primitives, `SfItem<primitive>`, and arrays of
-* those. `SfItem.params` is a flat record. The reporter calls this function
+* 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.
@@ -1873,7 +2282,7 @@ var CmcdReporter = class {
 			provenance: mintProvenance(sid, data.cid),
 			data,
 			msd: NaN,
-			lastEmitted: {},
+			lastEmitted: toBareValue(data.bg) === true ? {} : { bg: false },
 			eventTargets,
 			requestTarget: {
 				sn: 0,
@@ -1952,6 +2361,14 @@ var CmcdReporter = class {
 	* a new session therefore always fires, even when the persisted value did
 	* not change across the `sid` boundary.
 	*
+	* The `bg` field is an exception. A session that does not start with
+	* `bg: true` begins with `false` as its last reported `bg` value.
+	* `bg: false` therefore fires `BACKGROUNDED_MODE` only if the session
+	* started with `bg: true` or reported `bg: true`. CTA-5004-B defines a
+	* `b` event without `bg` as the exit from backgrounded mode, so the exit
+	* report does not carry `bg`. A target transform can add `bg: false` to
+	* the exit report. The encoder writes that value as `?0`.
+	*
 	* Multi-field updates fire the events in this order: `sta`, `pr`, `cid`,
 	* `bg`, `br`. The order of keys in the input object does not affect the
 	* firing order.
@@ -1971,8 +2388,7 @@ var CmcdReporter = class {
 	* 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 uses 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). The reporter
 	* rounds `msd` to the nearest integer and ignores invalid values.
@@ -2035,9 +2451,9 @@ var CmcdReporter = class {
 	*    data store, as `update()` would.
 	* 2. Discards the event if the state field has no value after that write
 	*    (never set, or cleared with `update({ field: undefined })`).
-	*    A state-change event without its required field would violate CTA-5004-B.
 	* 3. Suppresses the event if the field's current value equals the
-	*    last reported value (no state transition).
+	*    last reported value (no state transition). {@link CmcdReporter.update}
+	*    describes the `bg` value that a new session starts with.
 	*
 	* The reporter always records all other event types.
 	*
@@ -2123,6 +2539,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);
@@ -2134,8 +2551,8 @@ 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);
 	}
 	/**
@@ -2189,27 +2606,24 @@ var CmcdReporter = class {
 	* TypeScript therefore rejects a call whose request the configured
 	* transforms could not read. See {@link CmcdReporterCustomData}.
 	*
-	* The reporter attributes the event only to the session that issued the
-	* request. The provenance record that
-	* {@link CmcdReporter.createRequestReport} stored on the request's
-	* `customData` (under {@link CMCD_REQUEST_PROVENANCE}) selects the session
-	* by `sid`. Without a match, the reporter discards the response rather than
-	* attributing it elsewhere. There is no other key. The reporter discards the
-	* response when a serialization boundary lost the record and nothing
-	* restored it (see {@link CMCD_REQUEST_PROVENANCE}). It also discards the
-	* response when the session is no longer retained (see
-	* `CmcdReporterConfig.sessionRetention`). A per-call `data.sid` cannot
-	* substitute. The reporter accepts any record whose `sid` names a retained
-	* session. The record may come from another reporter with the same session
-	* attributes, or be hand-built. A response that completes after a `sid`
-	* change reports under its own retained session, with that session's data
-	* snapshot and sequence numbers.
+	* 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, 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.
+	* With a record, request-time report keys come from the record's encoded
+	* per-call `data` snapshot, which the reporter decodes for each response.
+	* The record's `cid` replaces the session's current `cid` in the report. A
+	* response that completes after a mid-session content change therefore
+	* reports its request-time values.
 	*
 	* @typeParam RD - The `customData` of this request. Defaults to the
 	*                reporter's own `C`.
@@ -2218,21 +2632,19 @@ var CmcdReporter = class {
 	* @param data - Additional CMCD data to include with the event.
 	*               Values provided here override the derived values.
 	*               The reporter ignores session-owned keys (`sid`, `msd`)
-	*               supplied here. Attribution uses the provenance record alone.
+	*               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 urlObj = new URL(url);
-		urlObj.searchParams.delete(CMCD_PARAM);
+		const cmcd = provenance === void 0 ? { ...request.customData?.cmcd } : decodeSnapshot(provenance);
+		const { cid } = provenance ?? {};
 		const derived = {
-			url: urlObj.toString(),
+			url: replaceCmcdParam(url),
 			rc: response.status
 		};
 		const timing = response.resourceTiming;
@@ -2251,11 +2663,11 @@ var CmcdReporter = class {
 		}, request);
 	}
 	/**
-	* Resolves the session a response belongs to. The provenance record's `sid`
+	* 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. There is no other key. A lost record, or one that
-	* names a removed or unknown `sid`, resolves nothing. Any other attribution
-	* would be wrong. The reporter reads the `sid` as a plain property. A record
+	* 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.
 	*/
@@ -2359,17 +2771,13 @@ var CmcdReporter = class {
 		const sendMsd = !isNaN(session.msd) && !session.requestTarget.msdSent;
 		if (sendMsd) cmcdData.msd = session.msd;
 		else delete cmcdData.msd;
-		const url = new URL(report.url);
 		const options = createEncodingOptions(CMCD_REQUEST_MODE, this.config, report.url);
 		const cmcd = report.customData.cmcd = copyReportValues(prepareCmcdData(cmcdData, options));
 		if (sendMsd && cmcd.msd !== void 0) session.requestTarget.msdSent = true;
 		const encoded = encodePreparedCmcd(cmcd);
 		switch (this.config.transmissionMode) {
 			case CMCD_QUERY:
-				if (encoded) {
-					url.searchParams.set(CMCD_PARAM, encoded);
-					report.url = url.toString();
-				}
+				if (encoded) report.url = replaceCmcdParam(report.url, encoded);
 				break;
 			case CMCD_HEADERS:
 				Object.assign(report.headers, toPreparedCmcdHeaders(cmcd, options.customHeaderMap));
@@ -2541,7 +2949,64 @@ function fromCmcdQuery(query, options) {
 //#endregion
 //#region src/fromCmcdUrl.ts
 function fromCmcdUrl(url, options) {
-	return decodeCmcd(decodeURIComponent(url.replace(/^CMCD=/, "")), options);
+	return decodeCmcd(decodeURIComponent(url.replace(/^CMCD=/, "").replace(/\+/g, " ")), 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
@@ -2562,6 +3027,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
 /**
@@ -2580,6 +3064,50 @@ function isCmcdV2Data(data) {
 	return data.v === CMCD_V2;
 }
 
+//#endregion
+//#region src/toCmcdUrl.ts
+/**
+* Convert a CMCD object to a URL encoded string.
+*
+* Only letters, digits, `-`, `.`, `_`, and `~` stay unencoded, as in the
+* query examples of CTA-5004-B.
+*
+* @param cmcd - The CMCD object to convert.
+* @param options - Options for encoding.
+*
+* @returns The URL encoded CMCD data.
+*
+* @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}
+*
+* @public
+*/
+function toCmcdUrl(cmcd, options = {}) {
+	if (!cmcd) return "";
+	return percentEncode(encodeCmcd(cmcd, options));
+}
+
+//#endregion
+//#region src/toCmcdQuery.ts
+/**
+* Convert a CMCD object to a query arg.
+*
+* @param cmcd - The CMCD object to convert.
+* @param options - Options for encoding.
+*
+* @returns The CMCD query arg.
+*
+* @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}
+*
+* @public
+*
+* @example
+* {@includeCode ../test/toCmcdQuery.test.ts#example}
+*/
+function toCmcdQuery(cmcd, options = {}) {
+	if (!cmcd) return "";
+	return `${CMCD_PARAM}=${toCmcdUrl(cmcd, options)}`;
+}
+
 //#endregion
 //#region src/toCmcdValue.ts
 /**
@@ -2619,7 +3147,7 @@ function mergeValidationResults(...results) {
 */
 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;
 }
@@ -2660,6 +3188,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
 /**
@@ -2727,9 +3300,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({
@@ -2755,9 +3328,10 @@ function validateCmcdStructure(data, options) {
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
 		});
 	}
-	if ("v" in data && data["v"] !== 1 && data["v"] !== 2) issues.push({
+	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({
@@ -2779,7 +3353,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
 */
@@ -2886,9 +3460,9 @@ const CMCD_KEY_TYPES = {
 */
 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
 };
 
@@ -2979,22 +3553,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,
@@ -3004,18 +3587,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) {
@@ -3027,20 +3605,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.
@@ -3059,7 +3628,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,
@@ -3086,16 +3656,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({
@@ -3103,16 +3669,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({
@@ -3144,7 +3700,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);