@gondola-lyrics/kit 0.1.0 → 0.3.0

package/dist/formats.js

@@ -1,13 +1,13 @@
-import { LineType, LyricStatus, Timing, WordType, deriveLanguageUsages, getWordsText, makeLineAnnotation, makeLineAnnotationRoman, makeLineAnnotationTranslation, makeLineContentText, makeLineContentWords, makeLineNormal, makeLyric, makeMeta, makeText, makeTimeRange, makeUnknownEntry, makeWordNormal, makeWordSpace } from "@gondola-lyrics/model/runtime";
+import { AgentType, CreditRole, LineType, LyricStatus, Timing, WordType, canonicalizeLyric, deriveLanguageUsages, getWordsText, makeAgent, makeLineAnnotation, makeLineAnnotationRoman, makeLineAnnotationTranslation, makeLineBackground, makeLineContentText, makeLineContentWords, makeLineNormal, makeLyric, makeMeta, makeMetaCredit, makeText, makeTimeRange, makeUnknownEntry, makeWordAnnotation, makeWordAnnotationRuby, makeWordAnnotationToken, makeWordNormal, makeWordSpace, removeOffset, resolveAnnotationItemTime, resolveAnnotationTokenTime, validateLyric } from "@gondola-lyrics/model/runtime";
 //#region src/utils/annotation.ts
 /**
 * An annotation line carries its text in either field, depending on whether the track used word tags.
 */
-var readText = (line) => {
+var readText$1 = (line) => {
 	return (line.content?.text ?? getWordsText(line.content?.words ?? [])).trim();
 };
 var isReadable = (line) => {
-	return line.time?.start !== void 0 && readText(line) !== "";
+	return line.time?.start !== void 0 && readText$1(line) !== "";
 };
 /**
 * Assigns each annotation line to a lyric line index.
@@ -79,11 +79,11 @@ var attachLineAnnotations = (lines, sources, options = {}) => {
 			...line,
 			annotation: makeLineAnnotation({
 				romans: [...line.annotation?.romans ?? [], ...roman === void 0 ? [] : [makeLineAnnotationRoman({
-					text: readText(roman),
+					text: readText$1(roman),
 					language: roman.languages[0]
 				})]],
 				translations: [...line.annotation?.translations ?? [], ...translation === void 0 ? [] : [makeLineAnnotationTranslation({
-					text: readText(translation),
+					text: readText$1(translation),
 					language: translation.languages[0]
 				})]]
 			})
@@ -91,30 +91,69 @@ var attachLineAnnotations = (lines, sources, options = {}) => {
 	});
 };
 //#endregion
-//#region src/utils/index.ts
-var TIME_PATTERN = /^(?:(?:(\d+):)?(\d+):)?(\d+)(?:\.(\d+))?$/;
+//#region src/utils/language.ts
 /**
-* Bare integers are excluded because formats may use them as millisecond counts or offsets.
+* Returns a language tag in the canonical form the model stores, which is lower case.
+*
+* This mirrors the model's own helper, which it does not export.
+* Comparing tags stays with the consumer, since BCP 47 matches by subtag prefix rather than by string equality.
 */
-var isTime = (body) => {
-	const trimmed = body.trim();
-	return (trimmed.includes(":") || trimmed.includes(".")) && TIME_PATTERN.test(trimmed);
+var lowerTag = (tag) => {
+	return tag ? tag.toLowerCase() : void 0;
 };
+//#endregion
+//#region src/utils/time.ts
+var CLOCK_PATTERN = /^(?:(?:(\d+):)?(\d+):)?(\d+)(?:\.(\d+))?$/;
+var OFFSET_PATTERN = /^(\d+(?:\.\d+)?)(ms|h|m|s)$/iu;
 /**
-* Fractional seconds are padded or truncated to millisecond precision.
+* Reads a clock value, where the fraction is padded or truncated to millisecond precision.
 *
-* Invalid clock syntax returns `undefined`; time bounds are left to model validation.
+* `14.514` is fourteen seconds, not fourteen minutes: a colon, not a dot, introduces the larger units.
 */
-var parseTime = (body) => {
-	if (!isTime(body)) return;
-	const match = TIME_PATTERN.exec(body.trim());
+var parseClock = (value) => {
+	if (!value.includes(":") && !value.includes(".")) return;
+	const match = CLOCK_PATTERN.exec(value);
+	if (!match) return;
 	const hour = Number(match[1] ?? 0);
 	const minute = Number(match[2] ?? 0);
-	const second = Number(match[3]);
+	const second = Number(match[3] ?? 0);
 	const millisecond = Number((match[4] ?? "").padEnd(3, "0").slice(0, 3));
 	return ((hour * 60 + minute) * 60 + second) * 1e3 + millisecond;
 };
 /**
+* Reads an offset such as `1.5s`, `2m`, `500ms`, or `1h`.
+*/
+var parseOffset = (value) => {
+	const match = OFFSET_PATTERN.exec(value);
+	if (!match) return;
+	const amount = Number(match[1]);
+	if (!Number.isFinite(amount)) return;
+	switch ((match[2] ?? "").toLowerCase()) {
+		case "h": return Math.round(amount * 36e5);
+		case "m": return Math.round(amount * 6e4);
+		case "ms": return Math.round(amount);
+		default: return Math.round(amount * 1e3);
+	}
+};
+/**
+* Reports whether a value reads as a time.
+*/
+var isTime = (body) => {
+	return parseTime(body) !== void 0;
+};
+/**
+* Reads a time value into milliseconds.
+*
+* A clock reading accepts `ss.fraction`, `mm:ss.fraction`, and `hh:mm:ss.fraction`.
+* An offset accepts a number with an `h`, `m`, `s`, or `ms` suffix.
+* A bare number returns `undefined`, and so does anything else.
+*/
+var parseTime = (body) => {
+	const trimmed = body.trim();
+	if (trimmed === "") return;
+	return parseOffset(trimmed) ?? parseClock(trimmed);
+};
+/**
 * Tokens `h`, `m`, `s`, and `S` select hours, minutes, seconds, and fractional seconds.
 * Repeated unit tokens set minimum width; `S` tokens select up to three fractional digits.
 *
@@ -139,6 +178,647 @@ var formatTime = (time, format = "mm:ss.SSS") => {
 	});
 };
 //#endregion
+//#region src/utils/xml/utils.ts
+var XmlNodeType = {
+	element: 1,
+	text: 2,
+	cdata: 3
+};
+/**
+* Only prefixed names need their split cached, since an unprefixed one keeps its name as the local part.
+* The cache is bounded, which keeps an adversarial document from growing it without limit.
+*/
+var prefixedNames = /* @__PURE__ */ new Map();
+/**
+* Splits a qualified name into its namespace prefix and local name.
+*/
+var splitXmlName = (name) => {
+	const cached = prefixedNames.get(name);
+	if (cached !== void 0) return cached;
+	const colon = name.indexOf(":");
+	const split = colon === -1 ? {
+		namespacePrefix: "",
+		localName: name
+	} : {
+		namespacePrefix: name.slice(0, colon),
+		localName: name.slice(colon + 1)
+	};
+	if (split.namespacePrefix !== "" && prefixedNames.size < 1024) prefixedNames.set(name, split);
+	return split;
+};
+/**
+* Writes the prefix and local part onto a node that already carries the full name.
+*/
+var applyXmlNameParts = (name, target) => {
+	if (name.indexOf(":") === -1) {
+		target.namespacePrefix = "";
+		target.localName = name;
+		return;
+	}
+	const split = splitXmlName(name);
+	target.namespacePrefix = split.namespacePrefix;
+	target.localName = split.localName;
+};
+/**
+* Creates an attribute from its full name and value.
+*/
+var createXmlAttribute = (qualifiedName, value) => {
+	const attribute = {
+		qualifiedName,
+		value,
+		namespacePrefix: "",
+		localName: qualifiedName
+	};
+	applyXmlNameParts(qualifiedName, attribute);
+	return attribute;
+};
+/**
+* Creates an element from its full name, with attributes and children in the order given.
+*/
+var createXmlElement = (qualifiedName, attributes = [], children = []) => {
+	const element = {
+		nodeType: XmlNodeType.element,
+		qualifiedName,
+		namespacePrefix: "",
+		localName: qualifiedName,
+		attributes: attributes.map(([name, value]) => {
+			return createXmlAttribute(name, value);
+		}),
+		children: [...children]
+	};
+	applyXmlNameParts(qualifiedName, element);
+	return element;
+};
+/**
+* Creates a text node, whose value the writer escapes.
+*/
+var createXmlText = (text) => {
+	return {
+		nodeType: XmlNodeType.text,
+		text
+	};
+};
+/**
+* Returns the value of one attribute, matched by its local name so the prefix never has to be known.
+*/
+var getXmlAttribute = (element, localName) => {
+	const attributes = element.attributes;
+	for (let index = 0; index < attributes.length; index += 1) {
+		const attribute = attributes[index];
+		if (attribute !== void 0 && attribute.localName === localName) return attribute.value;
+	}
+};
+/**
+* Returns the value of one attribute, matched by its full name including the prefix.
+*/
+var getXmlQualifiedAttribute = (element, qualifiedName) => {
+	const attributes = element.attributes;
+	for (let index = 0; index < attributes.length; index += 1) {
+		const attribute = attributes[index];
+		if (attribute !== void 0 && attribute.qualifiedName === qualifiedName) return attribute.value;
+	}
+};
+/**
+* Returns the direct element children carrying one local name.
+*/
+var getXmlChildElements = (element, localName) => {
+	const result = [];
+	const children = element.children;
+	for (let index = 0; index < children.length; index += 1) {
+		const child = children[index];
+		if (child !== void 0 && child.nodeType === XmlNodeType.element && child.localName === localName) result.push(child);
+	}
+	return result;
+};
+/**
+* Reports whether the element has a direct child with one local name.
+*/
+var hasXmlChildElement = (element, localName) => {
+	const children = element.children;
+	for (let index = 0; index < children.length; index += 1) {
+		const child = children[index];
+		if (child !== void 0 && child.nodeType === XmlNodeType.element && child.localName === localName) return true;
+	}
+	return false;
+};
+/**
+* Returns the first element carrying one local name, the element itself included, in document order.
+*/
+var findXmlElement = (element, localName) => {
+	const stack = [element];
+	while (stack.length > 0) {
+		const node = stack.pop();
+		if (node === void 0 || node.nodeType !== XmlNodeType.element) continue;
+		if (node.localName === localName) return node;
+		for (let index = node.children.length - 1; index >= 0; index -= 1) {
+			const child = node.children[index];
+			if (child !== void 0) stack.push(child);
+		}
+	}
+};
+/**
+* Joins the text and CDATA content of a node and its descendants, in document order.
+*/
+var getXmlTextContent = (node) => {
+	if (node.nodeType !== XmlNodeType.element) return node.text;
+	if (node.children.length === 0) return "";
+	const child = node.children[0];
+	if (node.children.length === 1 && child !== void 0 && child.nodeType !== XmlNodeType.element) return child.text;
+	const parts = [];
+	const stack = [node];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (current === void 0) continue;
+		if (current.nodeType === XmlNodeType.element) {
+			for (let index = current.children.length - 1; index >= 0; index -= 1) {
+				const child = current.children[index];
+				if (child !== void 0) stack.push(child);
+			}
+			continue;
+		}
+		parts.push(current.text);
+	}
+	return parts.join("");
+};
+//#endregion
+//#region src/utils/xml/reader.ts
+var LESS_THAN$1 = 60;
+var GREATER_THAN$1 = 62;
+var SLASH = 47;
+var EQUALS = 61;
+var DOUBLE_QUOTE$1 = 34;
+var SINGLE_QUOTE = 39;
+var EXCLAMATION = 33;
+var QUESTION = 63;
+var AMPERSAND$1 = 38;
+var HASH = 35;
+var HYPHEN = 45;
+var LOWER_X = 120;
+var UPPER_X = 88;
+var BYTE_ORDER_MARK = 65279;
+var ROOT_NAME$1 = "#document";
+var DECIMAL_DIGITS = /^\d+$/;
+var HEX_DIGITS = /^[0-9a-fA-F]+$/;
+/**
+* Resolves one entity reference body, leaving anything unrecognized as written.
+*/
+var decodeReference = (body) => {
+	switch (body) {
+		case "lt": return "<";
+		case "gt": return ">";
+		case "amp": return "&";
+		case "quot": return "\"";
+		case "apos": return "'";
+	}
+	if (body.charCodeAt(0) !== HASH) return `&${body};`;
+	const hexadecimal = body.charCodeAt(1) === LOWER_X || body.charCodeAt(1) === UPPER_X;
+	const digits = hexadecimal ? body.slice(2) : body.slice(1);
+	if (!(hexadecimal ? HEX_DIGITS : DECIMAL_DIGITS).test(digits)) return `&${body};`;
+	const code = Number.parseInt(digits, hexadecimal ? 16 : 10);
+	if (!Number.isFinite(code) || code > 1114111) return `&${body};`;
+	return String.fromCodePoint(code);
+};
+/**
+* Replaces entity references in one run of text, leaving bare ampersands alone.
+*/
+var decodeText = (text) => {
+	const parts = [];
+	const length = text.length;
+	let start = 0;
+	let cursor = 0;
+	while (cursor < length) {
+		if (text.charCodeAt(cursor) !== AMPERSAND$1) {
+			cursor += 1;
+			continue;
+		}
+		const end = text.indexOf(";", cursor + 1);
+		if (end === -1) {
+			cursor += 1;
+			continue;
+		}
+		parts.push(text.slice(start, cursor), decodeReference(text.slice(cursor + 1, end)));
+		cursor = end + 1;
+		start = cursor;
+	}
+	if (parts.length === 0) return text;
+	parts.push(text.slice(start));
+	return parts.join("");
+};
+/**
+* Reads a document into a tree, or returns `null` when it is not well formed.
+*/
+var parseXml = (source) => {
+	const length = source.length;
+	let position = length > 0 && source.charCodeAt(0) === BYTE_ORDER_MARK ? 1 : 0;
+	let valid = true;
+	const stack = [];
+	const root = {
+		nodeType: XmlNodeType.element,
+		qualifiedName: ROOT_NAME$1,
+		namespacePrefix: "",
+		localName: ROOT_NAME$1,
+		attributes: [],
+		children: []
+	};
+	stack.push(root);
+	/**
+	* Appends a text node to the element being read.
+	*/
+	const readTextNode = (end) => {
+		const start = position;
+		position = end;
+		if (start === end) return;
+		const parent = stack[stack.length - 1];
+		if (parent === void 0) {
+			valid = false;
+			return;
+		}
+		const raw = source.slice(start, end);
+		parent.children.push({
+			nodeType: XmlNodeType.text,
+			text: raw.indexOf("&") === -1 ? raw : decodeText(raw)
+		});
+	};
+	/**
+	* Reads one quoted value, starting at `position`, and leaves `position` after the closing quote.
+	*/
+	const readQuotedValue = () => {
+		const quote = source.charCodeAt(position);
+		if (quote !== DOUBLE_QUOTE$1 && quote !== SINGLE_QUOTE) {
+			valid = false;
+			return "";
+		}
+		position += 1;
+		const end = source.indexOf(quote === DOUBLE_QUOTE$1 ? "\"" : "'", position);
+		if (end === -1) {
+			valid = false;
+			return "";
+		}
+		const raw = source.slice(position, end);
+		position = end + 1;
+		return raw.indexOf("&") === -1 ? raw : decodeText(raw);
+	};
+	/**
+	* Reads a start tag with its attributes, and opens the element unless it closes itself.
+	*/
+	const readStartTag = () => {
+		let cursor = position + 1;
+		const nameStart = cursor;
+		while (cursor < length) {
+			const code = source.charCodeAt(cursor);
+			if (code <= 32 || code === GREATER_THAN$1 || code === SLASH || code === EQUALS) break;
+			cursor += 1;
+		}
+		if (cursor === nameStart) {
+			valid = false;
+			return;
+		}
+		const qualifiedName = source.slice(nameStart, cursor);
+		const attributes = [];
+		const element = {
+			nodeType: XmlNodeType.element,
+			qualifiedName,
+			namespacePrefix: "",
+			localName: qualifiedName,
+			attributes,
+			children: []
+		};
+		applyXmlNameParts(qualifiedName, element);
+		let closed = false;
+		let selfClosing = false;
+		while (cursor < length) {
+			let code = source.charCodeAt(cursor);
+			while (code <= 32) {
+				cursor += 1;
+				if (cursor >= length) break;
+				code = source.charCodeAt(cursor);
+			}
+			if (cursor >= length) break;
+			if (code === GREATER_THAN$1) {
+				cursor += 1;
+				closed = true;
+				break;
+			}
+			if (code === SLASH) {
+				cursor += 1;
+				if (cursor < length && source.charCodeAt(cursor) === GREATER_THAN$1) {
+					cursor += 1;
+					closed = true;
+					selfClosing = true;
+					break;
+				}
+				valid = false;
+				return;
+			}
+			const attributeStart = cursor;
+			do {
+				cursor += 1;
+				if (cursor >= length) break;
+				code = source.charCodeAt(cursor);
+			} while (code > 32 && code !== GREATER_THAN$1 && code !== SLASH && code !== EQUALS);
+			if (cursor === attributeStart) {
+				valid = false;
+				return;
+			}
+			const attributeName = source.slice(attributeStart, cursor);
+			while (cursor < length && source.charCodeAt(cursor) <= 32) cursor += 1;
+			if (cursor >= length || source.charCodeAt(cursor) !== EQUALS) {
+				valid = false;
+				return;
+			}
+			cursor += 1;
+			while (cursor < length && source.charCodeAt(cursor) <= 32) cursor += 1;
+			position = cursor;
+			const value = readQuotedValue();
+			if (!valid) return;
+			cursor = position;
+			for (let index = 0; index < attributes.length; index += 1) if (attributes[index]?.qualifiedName === attributeName) {
+				valid = false;
+				return;
+			}
+			attributes.push(createXmlAttribute(attributeName, value));
+		}
+		if (!closed) {
+			valid = false;
+			return;
+		}
+		position = cursor;
+		const parent = stack[stack.length - 1];
+		if (parent === void 0) {
+			valid = false;
+			return;
+		}
+		parent.children.push(element);
+		if (!selfClosing) stack.push(element);
+	};
+	/**
+	* Closes the innermost element, which has to be the one the tag names.
+	*/
+	const readEndTag = () => {
+		let cursor = position + 2;
+		const nameStart = cursor;
+		while (cursor < length) {
+			const code = source.charCodeAt(cursor);
+			if (code <= 32 || code === GREATER_THAN$1) break;
+			cursor += 1;
+		}
+		const name = source.slice(nameStart, cursor);
+		const end = source.indexOf(">", cursor);
+		if (end === -1) {
+			valid = false;
+			return;
+		}
+		position = end + 1;
+		if (stack.length <= 1) {
+			valid = false;
+			return;
+		}
+		const top = stack[stack.length - 1];
+		if (top === void 0 || top.qualifiedName !== name) {
+			valid = false;
+			return;
+		}
+		stack.pop();
+	};
+	/**
+	* Skips a comment, CDATA section, or any other declaration such as a DOCTYPE.
+	*/
+	const readMarkupDeclaration = () => {
+		if (source.charCodeAt(position + 2) === HYPHEN && source.charCodeAt(position + 3) === HYPHEN) {
+			const end = source.indexOf("-->", position + 4);
+			if (end === -1) {
+				valid = false;
+				return;
+			}
+			position = end + 3;
+			return;
+		}
+		if (source.startsWith("[CDATA[", position + 2)) {
+			const start = position + 9;
+			const end = source.indexOf("]]>", start);
+			if (end === -1) {
+				valid = false;
+				return;
+			}
+			const parent = stack[stack.length - 1];
+			if (parent === void 0) {
+				valid = false;
+				return;
+			}
+			parent.children.push({
+				nodeType: XmlNodeType.cdata,
+				text: source.slice(start, end)
+			});
+			position = end + 3;
+			return;
+		}
+		let cursor = position + 2;
+		let depth = 1;
+		while (cursor < length && depth > 0) {
+			const code = source.charCodeAt(cursor);
+			if (code === LESS_THAN$1) depth += 1;
+			else if (code === GREATER_THAN$1) depth -= 1;
+			cursor += 1;
+		}
+		if (depth > 0) {
+			valid = false;
+			return;
+		}
+		position = cursor;
+	};
+	/**
+	* Skips a processing instruction, which carries nothing the kit reads.
+	*/
+	const readProcessingInstruction = () => {
+		const end = source.indexOf("?>", position + 2);
+		if (end === -1) {
+			valid = false;
+			return;
+		}
+		position = end + 2;
+	};
+	/**
+	* Reads content until the end of input or the end tag of the innermost element.
+	*/
+	const readNodes = () => {
+		while (position < length) {
+			const open = source.indexOf("<", position);
+			if (open === -1) {
+				readTextNode(length);
+				return;
+			}
+			if (open > position) {
+				readTextNode(open);
+				if (!valid) return;
+			}
+			position = open;
+			const next = source.charCodeAt(open + 1);
+			if (next === SLASH) readEndTag();
+			else if (next === EXCLAMATION) readMarkupDeclaration();
+			else if (next === QUESTION) readProcessingInstruction();
+			else readStartTag();
+			if (!valid) return;
+		}
+	};
+	readNodes();
+	if (!valid || stack.length !== 1) return null;
+	for (let index = 0; index < root.children.length; index += 1) if (root.children[index]?.nodeType === XmlNodeType.element) return root;
+	return null;
+};
+//#endregion
+//#region src/utils/xml/writer.ts
+var AMPERSAND = 38;
+var LESS_THAN = 60;
+var GREATER_THAN = 62;
+var DOUBLE_QUOTE = 34;
+var TAB = 9;
+var LINE_FEED = 10;
+var CARRIAGE_RETURN = 13;
+var ROOT_NAME = "#document";
+var REPLACEMENT_CHARACTER = "�";
+var XML_DECLARATION = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>";
+var DEFAULT_INDENT = "  ";
+/**
+* Reports whether a code point may appear in an XML 1.0 document.
+*/
+var isAllowedCodePoint = (code) => {
+	return code === TAB || code === LINE_FEED || code === CARRIAGE_RETURN || code >= 32 && code <= 55295 || code >= 57344 && code <= 65533 || code >= 65536 && code <= 1114111;
+};
+/**
+* Escapes text content, replacing characters XML cannot carry so corruption stays visible.
+*/
+var escapeXmlText = (text, chunks) => {
+	const length = text.length;
+	let start = 0;
+	for (let index = 0; index < length; index += 1) {
+		const code = text.charCodeAt(index);
+		let escaped = "";
+		if (code === AMPERSAND) escaped = "&amp;";
+		else if (code === LESS_THAN) escaped = "&lt;";
+		else if (code === GREATER_THAN) escaped = "&gt;";
+		else if (code === CARRIAGE_RETURN) escaped = "&#13;";
+		else if (code >= 55296 && code <= 56319) {
+			const low = index + 1 < length ? text.charCodeAt(index + 1) : 0;
+			if (low < 56320 || low > 57343) escaped = REPLACEMENT_CHARACTER;
+			else {
+				index += 1;
+				continue;
+			}
+		} else if (code >= 56320 && code <= 57343) escaped = REPLACEMENT_CHARACTER;
+		else if (!isAllowedCodePoint(code)) escaped = REPLACEMENT_CHARACTER;
+		if (escaped === "") continue;
+		if (start < index) chunks.push(text.slice(start, index));
+		chunks.push(escaped);
+		start = index + 1;
+	}
+	if (start === 0) {
+		chunks.push(text);
+		return;
+	}
+	if (start < length) chunks.push(text.slice(start));
+};
+/**
+* Escapes an attribute value, where whitespace also has to survive normalization.
+*/
+var escapeXmlAttribute = (value, chunks) => {
+	const length = value.length;
+	let start = 0;
+	for (let index = 0; index < length; index += 1) {
+		const code = value.charCodeAt(index);
+		let escaped = "";
+		if (code === AMPERSAND) escaped = "&amp;";
+		else if (code === LESS_THAN) escaped = "&lt;";
+		else if (code === GREATER_THAN) escaped = "&gt;";
+		else if (code === DOUBLE_QUOTE) escaped = "&quot;";
+		else if (code === TAB) escaped = "&#9;";
+		else if (code === LINE_FEED) escaped = "&#10;";
+		else if (code === CARRIAGE_RETURN) escaped = "&#13;";
+		else if (code >= 55296 && code <= 56319) {
+			const low = index + 1 < length ? value.charCodeAt(index + 1) : 0;
+			if (low < 56320 || low > 57343) escaped = REPLACEMENT_CHARACTER;
+			else {
+				index += 1;
+				continue;
+			}
+		} else if (code >= 56320 && code <= 57343) escaped = REPLACEMENT_CHARACTER;
+		else if (!isAllowedCodePoint(code)) escaped = REPLACEMENT_CHARACTER;
+		if (escaped === "") continue;
+		if (start < index) chunks.push(value.slice(start, index));
+		chunks.push(escaped);
+		start = index + 1;
+	}
+	if (start === 0) {
+		chunks.push(value);
+		return;
+	}
+	if (start < length) chunks.push(value.slice(start));
+};
+/**
+* Reports whether every child is an element, which is the only case indentation can add whitespace to.
+*
+* An element holding any character data is mixed content, where the inserted whitespace would join the text.
+*/
+var hasOnlyElements = (element) => {
+	const children = element.children;
+	for (let index = 0; index < children.length; index += 1) {
+		const child = children[index];
+		if (child !== void 0 && child.nodeType !== XmlNodeType.element) return false;
+	}
+	return true;
+};
+/**
+* Serializes one node, appending its pieces to `chunks`.
+*/
+var writeXmlNode = (node, chunks, depth, indent) => {
+	if (node.nodeType === XmlNodeType.text) {
+		escapeXmlText(node.text, chunks);
+		return;
+	}
+	if (node.nodeType === XmlNodeType.cdata) {
+		chunks.push("<![CDATA[", node.text.replaceAll("]]>", "]]]]><![CDATA[>"), "]]>");
+		return;
+	}
+	if (indent !== void 0 && depth > 0) chunks.push("\n", indent.repeat(depth));
+	chunks.push("<", node.qualifiedName);
+	for (let index = 0; index < node.attributes.length; index += 1) {
+		const attribute = node.attributes[index];
+		if (attribute === void 0) continue;
+		chunks.push(" ", attribute.qualifiedName, "=\"");
+		escapeXmlAttribute(attribute.value, chunks);
+		chunks.push("\"");
+	}
+	const children = node.children;
+	if (children.length === 0) {
+		chunks.push("/>");
+		return;
+	}
+	chunks.push(">");
+	const childIndent = indent !== void 0 && hasOnlyElements(node) ? indent : void 0;
+	for (let index = 0; index < children.length; index += 1) {
+		const child = children[index];
+		if (child !== void 0) writeXmlNode(child, chunks, depth + 1, childIndent);
+	}
+	if (childIndent !== void 0) chunks.push("\n", childIndent.repeat(depth));
+	chunks.push("</", node.qualifiedName, ">");
+};
+/**
+* Writes a tree back to text.
+*
+* A `#document` root, as `parseXml` returns, writes its children; any other root writes itself.
+*/
+var serializeXml = (root, options = {}) => {
+	const chunks = [];
+	if (options.declaration ?? true) chunks.push(XML_DECLARATION);
+	const indent = options.indent === true ? options.indentText ?? DEFAULT_INDENT : void 0;
+	if (indent !== void 0) chunks.push("\n");
+	if (root.qualifiedName === ROOT_NAME) for (let index = 0; index < root.children.length; index += 1) {
+		const child = root.children[index];
+		if (child !== void 0) writeXmlNode(child, chunks, 0, indent);
+	}
+	else writeXmlNode(root, chunks, 0, indent);
+	return chunks.join("");
+};
+//#endregion
 //#region src/formats/lrc/common.ts
 var readLrcContent = (input) => {
 	if (typeof input === "string") return { original: input };
@@ -232,7 +912,7 @@ var detectLrc = (input) => {
 };
 //#endregion
 //#region src/formats/lrc/generator.ts
-var resolveOptions = (options = {}) => {
+var resolveOptions$1 = (options = {}) => {
 	return {
 		wordTiming: options.wordTiming ?? "angle",
 		timeFormat: options.timeFormat ?? "mm:ss.SSS",
@@ -315,7 +995,7 @@ var joinBlocks = (header, body) => {
 * Word tags appear only for a word-timed lyric when `wordTiming` is not `none`; otherwise every line stays whole.
 */
 var generateLrc = (lyric, options = {}) => {
-	const resolved = resolveOptions(options);
+	const resolved = resolveOptions$1(options);
 	const header = resolved.includeMeta && lyric.meta ? renderMetaRows(lyric.meta, resolved) : [];
 	const wordLevel = lyric.lines.some((line) => (line.content?.words.length ?? 0) > 0) && resolved.wordTiming !== "none";
 	const result = { original: joinBlocks(header, lyric.lines.map((line) => {
@@ -328,6 +1008,20 @@ var generateLrc = (lyric, options = {}) => {
 	return result;
 };
 //#endregion
+//#region src/formats/result.ts
+/**
+* Canonicalizes and validates one parser's output, so every format hands back the same shape.
+*
+* Canonicalization runs first because validation reports paths against the canonical tree.
+*/
+var finalizeLyric = (input) => {
+	const lyric = canonicalizeLyric(input);
+	return {
+		lyric,
+		diagnostics: validateLyric(lyric)
+	};
+};
+//#endregion
 //#region src/formats/lrc/parser.ts
 var isBareNumber = (value) => {
 	return /^\d+$/.test(value.trim());
@@ -440,7 +1134,7 @@ var readMetaTags = (tags) => {
 * A tag opens a segment; untagged words continue from the previous end so the timeline has no holes.
 * Explicit word ends are kept as written, so duration tags survive unchanged.
 */
-var readWords = (text, lineStart) => {
+var readWords$1 = (text, lineStart) => {
 	const drafts = [];
 	const open = /* @__PURE__ */ new Set();
 	const closeSegment = (boundary) => {
@@ -491,9 +1185,9 @@ var readWords = (text, lineStart) => {
 * A line ends at the next line's start; without one, it ends at its final word's end.
 * An open word is closed by the next timed word, or by the line end, so every sung word stays inside the line.
 */
-var readLine = (text, start, nextStart) => {
+var readLine$1 = (text, start, nextStart) => {
 	const wordTimed = isWordTimed(text);
-	const { drafts, closeSegment } = wordTimed ? readWords(text, start) : {
+	const { drafts, closeSegment } = wordTimed ? readWords$1(text, start) : {
 		drafts: [],
 		closeSegment: () => {}
 	};
@@ -529,7 +1223,7 @@ var readLines = (timed) => {
 	const lines = [];
 	for (const [index, item] of timed.entries()) {
 		const next = timed[index + 1]?.start;
-		lines.push(readLine(item.text, item.start, next));
+		lines.push(readLine$1(item.text, item.start, next));
 	}
 	return lines;
 };
@@ -557,23 +1251,1041 @@ var parseLrcText = (text) => {
 *
 * Annotation tracks are read as lines too and attached by timestamp, and rows that match no line are dropped.
 *
-* `INVALID` means no readable timed lines; `VALID` does not imply model validation has passed.
+* `INVALID` means no readable timed lines; the returned diagnostics carry whatever the canonical tree breaks.
 */
 var parseLrc = (input, options = {}) => {
 	const source = readLrcContent(input) ?? { original: "" };
 	const lyric = parseLrcText(source.original);
-	if (lyric.status === LyricStatus.INVALID) return lyric;
+	if (lyric.status === LyricStatus.INVALID) return finalizeLyric(lyric);
 	const translations = source.translations === void 0 ? [] : readLines(readTimedLines(source.translations).timed);
 	const romans = source.romans === void 0 ? [] : readLines(readTimedLines(source.romans).timed);
-	if (translations.length === 0 && romans.length === 0) return lyric;
+	if (translations.length === 0 && romans.length === 0) return finalizeLyric(lyric);
 	const lines = attachLineAnnotations(lyric.lines, {
 		translations,
 		romans
 	}, { tolerance: options.annotationTolerance });
-	return {
+	return finalizeLyric({
 		...lyric,
 		lines
+	});
+};
+//#endregion
+//#region src/formats/ttml/common.ts
+var FORMAT = "ttml";
+var AMLL_HINT_PATTERN = /xmlns:amll|amll:meta/iu;
+var ITUNES_HINT_PATTERN = /xmlns:itunes|iTunesMetadata|itunes:timing=/iu;
+/**
+* Accepts the text input shared by TTML detection and parsing.
+*/
+var readTtmlContent = (input) => {
+	if (typeof input !== "string") return null;
+	return input;
+};
+//#endregion
+//#region src/formats/ttml/detect.ts
+/**
+* Recognition needs a profile hint, since plain TTML says nothing about which profile wrote it.
+*
+* A bare `tt` root also counts, which is what a hand-written document has.
+* This is a format probe, not a validity check, so an input of another shape is simply not TTML.
+*/
+var detectTtml = (input) => {
+	const content = readTtmlContent(input);
+	if (!content) return false;
+	if (AMLL_HINT_PATTERN.test(content) || ITUNES_HINT_PATTERN.test(content)) return true;
+	const root = parseXml(content);
+	if (!root) return false;
+	for (const child of root.children) if (child.nodeType === XmlNodeType.element && child.localName === "tt") return true;
+	return false;
+};
+//#endregion
+//#region src/formats/ttml/utils.ts
+var ROLE_BACKGROUND = "x-bg";
+var ROLE_TRANSLATION = "x-translation";
+var ROLE_ROMAN = "x-roman";
+var RUBY_CONTAINER = "container";
+var RUBY_BASE = "base";
+var RUBY_TEXT_CONTAINER = "textContainer";
+var RUBY_TEXT = "text";
+var TIMING_WORD = "Word";
+var TIMING_LINE = "Line";
+//#endregion
+//#region src/formats/ttml/generator.ts
+var NAMESPACE_TTML = "http://www.w3.org/ns/ttml";
+var NAMESPACE_TTML_METADATA = "http://www.w3.org/ns/ttml#metadata";
+var NAMESPACE_TTML_STYLING = "http://www.w3.org/ns/ttml#styling";
+var NAMESPACE_ITUNES = "http://itunes.apple.com/lyric-ttml-extensions";
+var NAMESPACE_ITUNES_METADATA = "http://music.apple.com/lyric-ttml-internal";
+var NAMESPACE_AMLL = "http://www.example.com/ns/amll";
+var ANNOTATION_KINDS = ["translations", "romans"];
+var XML_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+var resolveOptions = (lyric, options) => {
+	const profile = options.profile ?? (lyric.format === "ttml" && lyric.extra.profile === "itunes" ? "itunes" : "amll");
+	if (profile !== "amll" && profile !== "itunes") throw new Error("Unsupported TTML profile");
+	return {
+		profile,
+		includeMeta: options.includeMeta ?? true,
+		indent: options.indent ?? false
+	};
+};
+/**
+* Reserves source ids before allocating keys, so unnamed entries cannot take later source ids.
+*/
+var makeIdAllocator = (ids) => {
+	const reserved = new Set(ids.filter((id) => {
+		return XML_ID_PATTERN.test(id);
+	}));
+	const used = /* @__PURE__ */ new Set();
+	const counters = /* @__PURE__ */ new Map();
+	return (preferred, prefix) => {
+		if (XML_ID_PATTERN.test(preferred) && !used.has(preferred)) {
+			used.add(preferred);
+			return preferred;
+		}
+		let count = counters.get(prefix) ?? 0;
+		let id;
+		do {
+			count += 1;
+			id = `${prefix}${count}`;
+		} while (reserved.has(id) || used.has(id));
+		counters.set(prefix, count);
+		used.add(id);
+		return id;
+	};
+};
+/**
+* Shares one mapping between declarations, body lines, and annotation references.
+*/
+var makeContext = (lyric, lines, profile) => {
+	const ids = lyric.agents.map((agent) => {
+		return agent.id;
+	});
+	for (const line of lines) {
+		ids.push(line.id);
+		for (const background of line.backgrounds) ids.push(background.id);
+	}
+	const allocate = makeIdAllocator(ids);
+	const agents = /* @__PURE__ */ new Map();
+	const keys = /* @__PURE__ */ new Map();
+	for (const agent of lyric.agents) {
+		if (agents.has(agent.id)) throw new Error("TTML agent declarations require unique ids");
+		agents.set(agent.id, allocate(agent.id, "v"));
+	}
+	for (const line of lines) {
+		keys.set(line, allocate(line.id, "L"));
+		for (const background of line.backgrounds) keys.set(background, allocate(background.id, "B"));
+	}
+	return {
+		profile,
+		offset: lyric.meta?.offset ?? 0,
+		keys,
+		agents
+	};
+};
+/**
+* Bakes the playback offset into TTML timestamps without clamping negative results.
+*/
+var renderTime = (time, offset) => {
+	const shifted = removeOffset(time, offset);
+	if (!Number.isInteger(shifted) || shifted < 0) throw new RangeError("TTML timestamps must be non-negative integer milliseconds after applying the offset");
+	const seconds = Math.floor(shifted / 1e3);
+	const minutes = Math.floor(seconds / 60);
+	const hours = String(Math.floor(minutes / 60)).padStart(2, "0");
+	const milliseconds = String(shifted % 1e3).padStart(3, "0");
+	return `${hours}:${String(minutes % 60).padStart(2, "0")}:${String(seconds % 60).padStart(2, "0")}.${milliseconds}`;
+};
+/**
+* Writes known bounds without inventing an end.
+*/
+var renderTimeAttributes = (time, offset) => {
+	if (time === void 0) throw new Error("TTML sung lines, words, and ruby tokens require a time range");
+	const attributes = [["begin", renderTime(time.start, offset)]];
+	if (time.end !== void 0) attributes.push(["end", renderTime(time.end, offset)]);
+	return attributes;
+};
+/**
+* Clears inherited language when the model leaves an item's language unspecified.
+*/
+var renderLanguage = (language, inherited) => {
+	if (language !== void 0) return [["xml:lang", language]];
+	return inherited === void 0 ? [] : [["xml:lang", ""]];
+};
+var getLineLanguage = (line) => {
+	return line.languages.length === 1 ? line.languages[0] : void 0;
+};
+/**
+* Writes separators as text and resolves inherited ruby timing through the model.
+*/
+var renderWord = (word, context, language) => {
+	if (word.type === WordType.SPACE) return createXmlText(word.text);
+	const attributes = [...renderTimeAttributes(word.time, context.offset), ...renderLanguage(word.language, language)];
+	const ruby = context.profile === "amll" ? word.annotation?.rubies[0] : void 0;
+	if (ruby === void 0) return createXmlElement("span", attributes, [createXmlText(word.text)]);
+	const tokens = ruby.tokens.map((token) => {
+		return createXmlElement("span", [["tts:ruby", RUBY_TEXT], ...renderTimeAttributes(resolveAnnotationTokenTime(token, ruby, word), context.offset)], [createXmlText(token.text)]);
+	});
+	return createXmlElement("span", [["tts:ruby", RUBY_CONTAINER], ...attributes], [createXmlElement("span", [["tts:ruby", RUBY_BASE]], [createXmlText(word.text)]), createXmlElement("span", [
+		["tts:ruby", RUBY_TEXT_CONTAINER],
+		...renderTimeAttributes(resolveAnnotationItemTime(ruby, word), context.offset),
+		...renderLanguage(ruby.language, word.language)
+	], tokens)]);
+};
+/**
+* Retains the model's choice between whole text and timed words.
+*/
+var renderContent = (line, context) => {
+	const content = line.content;
+	if (content === void 0) throw new Error("TTML sung lines require content");
+	if (content.text !== void 0) return [createXmlText(content.text)];
+	return content.words.map((word) => {
+		return renderWord(word, context, getLineLanguage(line));
+	});
+};
+/**
+* Keeps annotations outside the sung word stream.
+*/
+var renderInlineAnnotations = (annotation, language) => {
+	const nodes = [];
+	for (const item of annotation?.translations ?? []) nodes.push(createXmlElement("span", [["ttm:role", ROLE_TRANSLATION], ...renderLanguage(item.language, language)], [createXmlText(item.text)]));
+	for (const item of annotation?.romans ?? []) nodes.push(createXmlElement("span", [["ttm:role", ROLE_ROMAN], ...renderLanguage(item.language, language)], [createXmlText(item.text)]));
+	return nodes;
+};
+/**
+* Uses the same allocated keys and agent ids as the document's declarations.
+*/
+var renderLineAttributes = (line, context) => {
+	const attributes = [
+		...renderTimeAttributes(line.time, context.offset),
+		["itunes:key", context.keys.get(line)],
+		["xml:space", "preserve"],
+		["xml:lang", getLineLanguage(line) ?? ""]
+	];
+	const lead = line.agents[0];
+	if (lead !== void 0) {
+		const id = context.agents.get(lead);
+		if (id === void 0) throw new Error("TTML performing agents must have a declaration");
+		attributes.push(["ttm:agent", id]);
+	}
+	return attributes;
+};
+/**
+* An empty text node keeps the XML writer's indentation outside lyric content.
+*/
+var createLyricElement = (name, attributes, children) => {
+	return createXmlElement(name, attributes, [createXmlText(""), ...children]);
+};
+var renderBackground = (line, context) => {
+	const children = renderContent(line, context);
+	if (context.profile === "amll") children.push(...renderInlineAnnotations(line.annotation, getLineLanguage(line)));
+	return createXmlElement("span", [["ttm:role", ROLE_BACKGROUND], ...renderLineAttributes(line, context)], children);
+};
+var renderLine = (line, context) => {
+	const before = [];
+	const after = [];
+	for (const background of line.backgrounds) {
+		const node = renderBackground(background, context);
+		if (background.time !== void 0 && line.time !== void 0 && background.time.start < line.time.start) before.push(node);
+		else after.push(node);
+	}
+	const children = [
+		...before,
+		...renderContent(line, context),
+		...after
+	];
+	if (context.profile === "amll") children.push(...renderInlineAnnotations(line.annotation, getLineLanguage(line)));
+	return createLyricElement("p", renderLineAttributes(line, context), children);
+};
+var renderAgents = (lyric, context) => {
+	return lyric.agents.map((agent) => {
+		const type = agent.type === AgentType.PERSON ? "person" : agent.type === AgentType.GROUP ? "group" : agent.raw ?? "other";
+		const names = agent.names.map((name) => {
+			return createXmlElement("ttm:name", [["type", "full"], ...renderLanguage(name.language)], [createXmlText(name.text)]);
+		});
+		return createXmlElement("ttm:agent", [["type", type], ["xml:id", context.agents.get(agent.id)]], names);
+	});
+};
+var renderAmllMeta = (meta) => {
+	const nodes = [];
+	const groups = [
+		["musicName", meta.titles],
+		["artists", meta.artists],
+		["album", meta.albums],
+		["ttmlAuthorGithubLogin", meta.authors]
+	];
+	for (const [key, items] of groups) for (const item of items) nodes.push(createXmlElement("amll:meta", [
+		["key", key],
+		["value", item.text],
+		...renderLanguage(item.language)
+	]));
+	for (const value of meta.isrcs) nodes.push(createXmlElement("amll:meta", [["key", "isrc"], ["value", value]]));
+	for (const item of meta.unknowns) nodes.push(createXmlElement("amll:meta", [["key", item.key], ["value", item.value]]));
+	return nodes;
+};
+var renderSongwriters = (meta) => {
+	const names = [];
+	for (const credit of meta.credits) {
+		if (credit.role !== CreditRole.LYRICIST) continue;
+		for (const name of credit.names) names.push(createXmlElement("songwriter", renderLanguage(name.language), [createXmlText(name.text)]));
+	}
+	return names.length === 0 ? [] : [createXmlElement("songwriters", [], names)];
+};
+var renderAnnotationTracks = (tracks, kind, context) => {
+	if (tracks.size === 0) return [];
+	const translated = kind === "translations";
+	const blocks = Array.from(tracks, ([language, track]) => {
+		const attributes = translated ? [["type", "subtitle"]] : [];
+		attributes.push(...renderLanguage(language));
+		const texts = Array.from(track, ([line, children]) => {
+			return createLyricElement("text", [["for", context.keys.get(line)], ["xml:space", "preserve"]], children);
+		});
+		return createXmlElement(translated ? "translation" : "transliteration", attributes, texts);
+	});
+	return [createXmlElement(translated ? "translations" : "transliterations", [], blocks)];
+};
+/**
+* A background-only annotation still references its parent paragraph, with a second reference naming the background.
+*/
+var renderHeadAnnotations = (lines, context) => {
+	const tracks = {
+		translations: /* @__PURE__ */ new Map(),
+		romans: /* @__PURE__ */ new Map()
 	};
+	const append = (annotation, line, background) => {
+		if (annotation === void 0) return;
+		for (const kind of ANNOTATION_KINDS) for (const item of annotation[kind]) {
+			const language = item.language?.toLowerCase();
+			let track = tracks[kind].get(language);
+			if (track === void 0) {
+				track = /* @__PURE__ */ new Map();
+				tracks[kind].set(language, track);
+			}
+			let nodes = track.get(line);
+			if (nodes === void 0) {
+				nodes = [];
+				track.set(line, nodes);
+			}
+			nodes.push(background === void 0 ? createXmlText(item.text) : createXmlElement("span", [["ttm:role", ROLE_BACKGROUND], ["for", context.keys.get(background)]], [createXmlText(item.text)]));
+		}
+	};
+	for (const line of lines) {
+		append(line.annotation, line);
+		for (const background of line.backgrounds) append(background.annotation, line, background);
+	}
+	return ANNOTATION_KINDS.flatMap((kind) => {
+		return renderAnnotationTracks(tracks[kind], kind, context);
+	});
+};
+var renderMetadata = (lyric, lines, context, includeMeta) => {
+	const metadata = renderAgents(lyric, context);
+	const itunes = [];
+	if (includeMeta && lyric.meta !== void 0) {
+		if (context.profile === "amll") metadata.push(...renderAmllMeta(lyric.meta));
+		itunes.push(...renderSongwriters(lyric.meta));
+	}
+	if (context.profile === "itunes") itunes.push(...renderHeadAnnotations(lines, context));
+	if (itunes.length > 0) metadata.push(createXmlElement("iTunesMetadata", [["xmlns", NAMESPACE_ITUNES_METADATA]], itunes));
+	return createXmlElement("metadata", renderLanguage(void 0, lyric.meta?.language), metadata);
+};
+var renderRootAttributes = (lyric, profile) => {
+	const attributes = [
+		["xmlns", NAMESPACE_TTML],
+		["xmlns:ttm", NAMESPACE_TTML_METADATA],
+		["xmlns:tts", NAMESPACE_TTML_STYLING],
+		["xmlns:itunes", NAMESPACE_ITUNES]
+	];
+	if (profile === "amll") attributes.push(["xmlns:amll", NAMESPACE_AMLL]);
+	attributes.push(...renderLanguage(lyric.meta?.language), ["itunes:timing", lyric.timing === Timing.WORD ? TIMING_WORD : TIMING_LINE]);
+	return attributes;
+};
+/**
+* Generates one TTML document, retaining the source profile unless explicitly overridden.
+*
+* Offsets are baked into timestamps; a negative result or a missing required time throws.
+* Profile mappings retain the lead agent and first AMLL ruby, omitting unsupported fields and instrumental nodes.
+*/
+var generateTtml = (lyric, options = {}) => {
+	if (lyric.timing !== Timing.LINE && lyric.timing !== Timing.WORD) throw new Error("TTML generation requires line or word timing");
+	const resolved = resolveOptions(lyric, options);
+	const lines = lyric.lines.filter((line) => {
+		return line.type !== LineType.INSTRUMENTAL;
+	});
+	const context = makeContext(lyric, lines, resolved.profile);
+	const metadata = renderMetadata(lyric, lines, context, resolved.includeMeta);
+	const paragraphs = lines.map((line) => {
+		return renderLine(line, context);
+	});
+	return serializeXml(createXmlElement("tt", renderRootAttributes(lyric, resolved.profile), [createXmlElement("head", [], [metadata]), createXmlElement("body", [], [createXmlElement("div", [], paragraphs)])]), { indent: resolved.indent });
+};
+//#endregion
+//#region src/formats/ttml/parser.ts
+var METADATA_NAMES = [
+	"agent",
+	"songwriter",
+	"meta",
+	"translation",
+	"transliteration"
+];
+var WORD_SEPARATOR_PATTERN = /\p{White_Space}/u;
+var readTtmlProfile = (source) => {
+	return AMLL_HINT_PATTERN.test(source) ? "amll" : "itunes";
+};
+var readSpanTime = (element) => {
+	const begin = getXmlAttribute(element, "begin");
+	if (!begin) return;
+	const start = parseTime(begin);
+	if (start === void 0) return;
+	const end = getXmlAttribute(element, "end");
+	return {
+		start,
+		end: end ? parseTime(end) : void 0
+	};
+};
+var readLineTime = (element) => {
+	return readSpanTime(element);
+};
+var readAgentType = (raw) => {
+	switch (raw) {
+		case "person": return {
+			type: AgentType.PERSON,
+			raw: void 0
+		};
+		case "group": return {
+			type: AgentType.GROUP,
+			raw: void 0
+		};
+		default: return {
+			type: AgentType.OTHER,
+			raw: raw ?? "other"
+		};
+	}
+};
+var readDeclaredTiming = (root) => {
+	switch (getXmlQualifiedAttribute(root, "itunes:timing")) {
+		case TIMING_WORD: return Timing.WORD;
+		case TIMING_LINE: return Timing.LINE;
+		default: return;
+	}
+};
+var readPreserveSpace = (element, inherited) => {
+	switch (getXmlQualifiedAttribute(element, "xml:space")) {
+		case "preserve": return true;
+		case "default": return false;
+		default: return inherited;
+	}
+};
+var readLanguage = (element, inherited) => {
+	const language = getXmlQualifiedAttribute(element, "xml:lang") ?? getXmlAttribute(element, "lang");
+	return language === void 0 ? inherited : lowerTag(language);
+};
+var readText = (element, inherited) => {
+	const text = getXmlTextContent(element);
+	return readPreserveSpace(element, inherited) ? text : text.trim();
+};
+/**
+* Preserves the parser's whitespace segmentation when turning text into word drafts.
+*/
+var splitWords = (text, language) => {
+	if (text === "") return [];
+	if (!WORD_SEPARATOR_PATTERN.test(text)) return [{
+		text,
+		space: false,
+		language,
+		rubies: []
+	}];
+	const words = [];
+	for (const run of text.split(/(\p{White_Space}+)/u)) if (run !== "") {
+		const space = /^\p{White_Space}+$/u.test(run);
+		words.push({
+			text: run,
+			space,
+			language: space ? void 0 : language,
+			rubies: []
+		});
+	}
+	return words;
+};
+/**
+* Distinguishes indentation runs from separators using the parser's existing rule.
+*/
+var isFormattingWhitespace = (text) => {
+	return text.trim() === "" && text.includes("\n");
+};
+/**
+* Builds words from source drafts without deriving missing timestamps.
+*/
+var buildWords = (draft) => {
+	const words = [];
+	for (const word of draft.words) {
+		if (word.space) {
+			words.push(makeWordSpace({ text: word.text }));
+			continue;
+		}
+		const time = word.start === void 0 ? void 0 : makeTimeRange({
+			start: word.start,
+			end: word.end
+		});
+		if (word.rubies.length === 0) {
+			words.push(makeWordNormal({
+				text: word.text,
+				time,
+				language: word.language
+			}));
+			continue;
+		}
+		const rubies = word.rubies.map((ruby) => {
+			return makeWordAnnotationRuby({
+				time: ruby.start === void 0 ? void 0 : makeTimeRange({
+					start: ruby.start,
+					end: ruby.end
+				}),
+				language: ruby.language,
+				tokens: ruby.tokens.map((token) => {
+					return makeWordAnnotationToken({
+						text: token.text,
+						time: token.start === void 0 ? void 0 : makeTimeRange({
+							start: token.start,
+							end: token.end
+						})
+					});
+				})
+			});
+		});
+		words.push(makeWordNormal({
+			text: word.text,
+			time,
+			language: word.language,
+			annotation: makeWordAnnotation({ rubies })
+		}));
+	}
+	return words;
+};
+/**
+* Builds only annotations explicitly present in the source drafts.
+*/
+var buildLineAnnotation = (draft) => {
+	if (draft.translations.length === 0 && draft.romans.length === 0) return;
+	return makeLineAnnotation({
+		translations: draft.translations.map((item) => {
+			return makeLineAnnotationTranslation({
+				text: item.text,
+				language: item.language
+			});
+		}),
+		romans: draft.romans.map((item) => {
+			return makeLineAnnotationRoman({
+				text: item.text,
+				language: item.language
+			});
+		})
+	});
+};
+/**
+* Separates head annotation text from its background references.
+*/
+var splitBackgroundText = (element, preserveSpace, language) => {
+	preserveSpace = readPreserveSpace(element, preserveSpace);
+	language = readLanguage(element, language);
+	let main = "";
+	const backgrounds = [];
+	for (const child of element.children) {
+		if (child.nodeType === XmlNodeType.element && child.localName === "span" && getXmlAttribute(child, "role") === "x-bg") {
+			backgrounds.push({
+				text: readText(child, preserveSpace),
+				key: getXmlAttribute(child, "for"),
+				language: readLanguage(child, language)
+			});
+			continue;
+		}
+		main += getXmlTextContent(child);
+	}
+	return {
+		main: preserveSpace ? main : main.trim(),
+		backgrounds
+	};
+};
+/**
+* Carries language and whitespace declarations through wrappers to the elements they govern.
+*/
+var groupElements = (root, names, preserveSpace, stopAtMatch = false, language) => {
+	const wanted = new Set(names);
+	const result = /* @__PURE__ */ new Map();
+	const stack = [{
+		element: root,
+		preserveSpace,
+		language
+	}];
+	while (stack.length > 0) {
+		const entry = stack.pop();
+		if (entry === void 0) continue;
+		const element = entry.element;
+		const currentSpace = readPreserveSpace(element, entry.preserveSpace);
+		const currentLanguage = readLanguage(element, entry.language);
+		if (wanted.has(element.localName)) {
+			const group = result.get(element.localName);
+			const context = {
+				element,
+				preserveSpace: currentSpace,
+				language: currentLanguage
+			};
+			if (group === void 0) result.set(element.localName, [context]);
+			else group.push(context);
+			if (stopAtMatch) continue;
+		}
+		const children = element.children;
+		for (let index = children.length - 1; index >= 0; index -= 1) {
+			const child = children[index];
+			if (child && child.nodeType === XmlNodeType.element) stack.push({
+				element: child,
+				preserveSpace: currentSpace,
+				language: currentLanguage
+			});
+		}
+	}
+	return result;
+};
+var findElements = (root, name, preserveSpace, stopAtMatch = false, language) => {
+	return groupElements(root, [name], preserveSpace, stopAtMatch, language).get(name) ?? [];
+};
+/**
+* Reads an AMLL ruby container into one word plus its per-syllable annotation.
+*/
+var readRuby = (container, preserveSpace, language) => {
+	preserveSpace = readPreserveSpace(container, preserveSpace);
+	language = readLanguage(container, language);
+	let base = "";
+	let baseLanguage = language;
+	let rubyTime;
+	let rubyLanguage = language;
+	const tokens = [];
+	for (const child of getXmlChildElements(container, "span")) {
+		const kind = getXmlAttribute(child, "ruby");
+		if (kind === "base") {
+			base = readText(child, preserveSpace);
+			baseLanguage = readLanguage(child, language);
+			continue;
+		}
+		if (kind !== "textContainer") continue;
+		rubyTime ??= readSpanTime(child);
+		rubyLanguage = readLanguage(child, language);
+		const rubySpace = readPreserveSpace(child, preserveSpace);
+		for (const text of getXmlChildElements(child, "span")) {
+			if (getXmlAttribute(text, "ruby") !== "text") continue;
+			const time = readSpanTime(text);
+			const content = readText(text, rubySpace);
+			if (!content) continue;
+			tokens.push({
+				start: time?.start,
+				end: time?.end,
+				text: content
+			});
+		}
+	}
+	if (!base) return;
+	const first = tokens.find((token) => {
+		return token.start !== void 0;
+	});
+	const last = tokens.findLast((token) => {
+		return token.start !== void 0;
+	});
+	const time = readSpanTime(container) ?? rubyTime ?? (first === void 0 ? void 0 : {
+		start: first.start,
+		end: last?.end
+	});
+	return {
+		text: base,
+		space: false,
+		start: time?.start,
+		end: time?.end,
+		language: baseLanguage,
+		rubies: tokens.length === 0 ? [] : [{
+			start: rubyTime?.start,
+			end: rubyTime?.end,
+			language: rubyLanguage,
+			tokens
+		}]
+	};
+};
+/**
+* Collects the words of one span-bearing element.
+*
+* Text between spans carries the separators, and a span without a readable begin contributes its text untimed.
+* A span carrying a role is annotation rather than a word, so it is skipped here.
+* Whitespace inside a span remains a separator; indentation is dropped only without a preserve declaration.
+*/
+var readWords = (element, preserveSpace, language) => {
+	preserveSpace = readPreserveSpace(element, preserveSpace);
+	language = readLanguage(element, language);
+	const words = [];
+	let wordLevel = false;
+	for (const child of element.children) {
+		if (child.nodeType !== XmlNodeType.element) {
+			if (preserveSpace || !isFormattingWhitespace(child.text)) words.push(...splitWords(child.text, language));
+			continue;
+		}
+		if (child.localName !== "span") continue;
+		if (getXmlAttribute(child, "role") !== void 0) continue;
+		if (getXmlAttribute(child, "ruby") === "container") {
+			const ruby = readRuby(child, preserveSpace, language);
+			if (ruby !== void 0) {
+				for (const part of splitWords(ruby.text)) words.push(part.space ? part : {
+					...ruby,
+					text: part.text
+				});
+				wordLevel ||= ruby.start !== void 0;
+			}
+			continue;
+		}
+		const text = getXmlTextContent(child);
+		const childSpace = readPreserveSpace(child, preserveSpace);
+		if (!text || !childSpace && isFormattingWhitespace(text)) continue;
+		const time = readSpanTime(child);
+		for (const part of splitWords(text, readLanguage(child, language))) {
+			if (!part.space && time !== void 0) {
+				part.start = time.start;
+				part.end = time.end;
+				wordLevel = true;
+			}
+			words.push(part);
+		}
+	}
+	return {
+		words,
+		wordLevel
+	};
+};
+var readInlineAnnotations = (element, preserveSpace, language) => {
+	const translations = [];
+	const romans = [];
+	for (const span of getXmlChildElements(element, "span")) {
+		const role = getXmlAttribute(span, "role");
+		if (role !== "x-translation" && role !== "x-roman") continue;
+		const text = readText(span, preserveSpace);
+		if (!text) continue;
+		const item = {
+			language: readLanguage(span, language),
+			text
+		};
+		if (role === "x-translation") translations.push(item);
+		else romans.push(item);
+	}
+	return {
+		translations,
+		romans
+	};
+};
+/**
+* Reads one paragraph, pulling its inline annotations and background lines out of the word stream.
+*/
+var readLine = (element, preserveSpace, language) => {
+	preserveSpace = readPreserveSpace(element, preserveSpace);
+	language = readLanguage(element, language);
+	const time = readLineTime(element);
+	if (time === void 0) return;
+	const draft = {
+		start: time.start,
+		end: time.end,
+		agentId: getXmlAttribute(element, "agent"),
+		key: getXmlAttribute(element, "key"),
+		words: [],
+		translations: [],
+		romans: [],
+		backgrounds: [],
+		wordLevel: false,
+		preserveSpace,
+		language
+	};
+	if (!hasXmlChildElement(element, "span")) {
+		const plain = readText(element, preserveSpace);
+		if (!plain) return;
+		draft.words = splitWords(plain, language);
+		return draft;
+	}
+	const read = readWords(element, preserveSpace, language);
+	draft.words = read.words;
+	draft.wordLevel = read.wordLevel;
+	const annotations = readInlineAnnotations(element, preserveSpace, language);
+	draft.translations = annotations.translations;
+	draft.romans = annotations.romans;
+	for (const span of getXmlChildElements(element, "span")) if (getXmlAttribute(span, "role") === "x-bg") {
+		const background = readBackground(span, preserveSpace, language);
+		if (background) draft.backgrounds.push(background);
+	}
+	return draft;
+};
+/**
+* Reads a background line, whose end may stay open because its parent's end covers it.
+*
+* A background line states no time of its own in AMLL files, so its range comes from its words.
+*/
+var readBackground = (element, preserveSpace, language) => {
+	preserveSpace = readPreserveSpace(element, preserveSpace);
+	language = readLanguage(element, language);
+	const read = readWords(element, preserveSpace, language);
+	if (read.words.length === 0) return;
+	const begin = getXmlAttribute(element, "begin");
+	const end = getXmlAttribute(element, "end");
+	const first = read.words.find((word) => {
+		return !word.space && word.start !== void 0;
+	});
+	const last = read.words.findLast((word) => {
+		return !word.space && word.start !== void 0;
+	});
+	const start = begin === void 0 ? first?.start ?? 0 : parseTime(begin);
+	if (start === void 0) return;
+	return {
+		start,
+		end: end === void 0 ? last?.end : parseTime(end),
+		agentId: getXmlAttribute(element, "agent"),
+		key: getXmlAttribute(element, "key"),
+		words: read.words,
+		...readInlineAnnotations(element, preserveSpace, language),
+		backgrounds: [],
+		wordLevel: read.wordLevel,
+		preserveSpace,
+		language
+	};
+};
+var buildContent = (draft) => {
+	if (draft.wordLevel) return makeLineContentWords(buildWords(draft));
+	const text = draft.words.map((word) => {
+		return word.text;
+	}).join("");
+	return makeLineContentText(draft.preserveSpace ? text : text.trim());
+};
+/**
+* Builds one background line.
+*/
+var buildBackground = (draft) => {
+	return makeLineBackground({
+		id: draft.key,
+		time: makeTimeRange({
+			start: draft.start,
+			end: draft.end
+		}),
+		agents: draft.agentId === void 0 ? [] : [draft.agentId],
+		languages: draft.language === void 0 ? [] : [draft.language],
+		content: buildContent(draft),
+		annotation: buildLineAnnotation(draft)
+	});
+};
+/**
+* Builds one normal line, keeping plain text whole unless the source timed its words.
+*/
+var buildLine = (draft) => {
+	return makeLineNormal({
+		id: draft.key,
+		time: makeTimeRange({
+			start: draft.start,
+			end: draft.end
+		}),
+		agents: draft.agentId === void 0 ? [] : [draft.agentId],
+		languages: draft.language === void 0 ? [] : [draft.language],
+		content: buildContent(draft),
+		annotation: buildLineAnnotation(draft),
+		backgrounds: draft.backgrounds.map(buildBackground)
+	});
+};
+/**
+* Reads the head's agents, which lines reference by id.
+*/
+var readAgents = (elements) => {
+	const agents = [];
+	for (const { element, preserveSpace, language } of elements) {
+		const id = getXmlQualifiedAttribute(element, "xml:id") ?? getXmlAttribute(element, "id");
+		if (!id) continue;
+		const names = getXmlChildElements(element, "name").map((name) => {
+			return makeText({
+				text: readText(name, preserveSpace),
+				language: readLanguage(name, language)
+			});
+		}).filter((name) => {
+			return name.text !== "";
+		});
+		const kind = readAgentType(getXmlAttribute(element, "type"));
+		agents.push(makeAgent({
+			id,
+			type: kind.type,
+			raw: kind.raw,
+			names
+		}));
+	}
+	return agents;
+};
+/**
+* Reads the head's songwriters as one lyricist credit, since TTML does not split the role further.
+*
+* AMLL wraps these in `iTunesMetadata`, so the whole head is searched rather than its direct children.
+*/
+var readCredits = (elements, meta) => {
+	const names = elements.map(({ element, preserveSpace, language }) => {
+		return makeText({
+			text: readText(element, preserveSpace),
+			language
+		});
+	}).filter((name) => {
+		return name.text !== "";
+	});
+	if (names.length === 0) return;
+	meta.credits.push(makeMetaCredit({
+		role: CreditRole.LYRICIST,
+		names
+	}));
+};
+/**
+* Reads one `amll:meta` entry, keeping an unknown key as written so a round trip loses nothing.
+*/
+var applyAmllMeta = (meta, element, language) => {
+	const key = getXmlAttribute(element, "key");
+	const value = getXmlAttribute(element, "value")?.trim();
+	if (!key || !value) return;
+	language = readLanguage(element, language);
+	switch (key) {
+		case "musicName":
+			meta.titles.push(makeText({
+				text: value,
+				language
+			}));
+			return;
+		case "artists":
+			meta.artists.push(makeText({
+				text: value,
+				language
+			}));
+			return;
+		case "album":
+			meta.albums.push(makeText({
+				text: value,
+				language
+			}));
+			return;
+		case "isrc":
+			meta.isrcs.push(value);
+			return;
+		case "ttmlAuthorGithubLogin":
+			meta.authors.push(makeText({
+				text: value,
+				language
+			}));
+			return;
+		default: meta.unknowns.push(makeUnknownEntry({
+			key,
+			value
+		}));
+	}
+};
+/**
+* Attaches head translations and transliterations to the lines they name by `itunes:key`.
+*
+* A replacement translation rewrites the line's text, which is how a source swaps one script for another.
+*/
+var attachHeadAnnotations = (metadata, lineMap, backgroundMap) => {
+	if (lineMap.size === 0) return;
+	const attach = (blocks, kind) => {
+		for (const { element: block, preserveSpace, language } of blocks) {
+			const type = getXmlQualifiedAttribute(block, "type") ?? getXmlAttribute(block, "type");
+			for (const text of getXmlChildElements(block, "text")) {
+				const key = getXmlAttribute(text, "for");
+				const line = key ? lineMap.get(key) : void 0;
+				if (!line) continue;
+				const textLanguage = readLanguage(text, language);
+				const { main, backgrounds } = splitBackgroundText(text, preserveSpace, textLanguage);
+				if (kind === "translation" && type === "replacement") {
+					if (main) {
+						line.words = splitWords(main, textLanguage);
+						line.wordLevel = false;
+						line.preserveSpace = readPreserveSpace(text, preserveSpace);
+						line.language = textLanguage;
+					}
+					continue;
+				}
+				if (main) {
+					const item = {
+						language: textLanguage,
+						text: main
+					};
+					if (kind === "translation") line.translations.push(item);
+					else line.romans.push(item);
+				}
+				for (const background of backgrounds) {
+					if (!background.text) continue;
+					const target = background.key ? backgroundMap.get(background.key) : void 0;
+					if (!target) continue;
+					const item = {
+						language: background.language,
+						text: background.text
+					};
+					if (kind === "translation") target.translations.push(item);
+					else target.romans.push(item);
+				}
+			}
+		}
+	};
+	attach(metadata.get("translation") ?? [], "translation");
+	attach(metadata.get("transliteration") ?? [], "roman");
+};
+/**
+* Reads a TTML document into the model.
+*
+* The profile only changes where metadata comes from, so one reader serves both.
+* A document that parses but holds no timed paragraph is `INVALID` rather than an error.
+*/
+var parseTtml = (input, options = {}) => {
+	const content = readTtmlContent(input);
+	if (!content) return finalizeLyric(makeLyric({
+		format: FORMAT,
+		status: LyricStatus.INVALID,
+		meta: makeMeta()
+	}));
+	const extra = { profile: readTtmlProfile(content) };
+	const document = parseXml(content);
+	const root = document ? findXmlElement(document, "tt") : void 0;
+	if (!root) return finalizeLyric(makeLyric({
+		format: FORMAT,
+		status: LyricStatus.INVALID,
+		meta: makeMeta(),
+		extra
+	}));
+	const language = readLanguage(root, lowerTag(options.language));
+	const body = findElements(root, "body", false, true, language)[0];
+	const metadata = findElements(root, "metadata", false, true, language)[0];
+	const metadataElements = metadata === void 0 ? /* @__PURE__ */ new Map() : groupElements(metadata.element, METADATA_NAMES, metadata.preserveSpace, false, metadata.language);
+	const meta = makeMeta();
+	if (language !== void 0) meta.language = language;
+	readCredits(metadataElements.get("songwriter") ?? [], meta);
+	for (const { element, language: itemLanguage } of metadataElements.get("meta") ?? []) applyAmllMeta(meta, element, itemLanguage);
+	const drafts = [];
+	const lineMap = /* @__PURE__ */ new Map();
+	const backgroundMap = /* @__PURE__ */ new Map();
+	for (const { element, preserveSpace, language: lineLanguage } of body ? findElements(body.element, "p", body.preserveSpace, true, body.language) : []) {
+		const draft = readLine(element, preserveSpace, lineLanguage);
+		if (!draft) continue;
+		drafts.push(draft);
+		if (draft.key) lineMap.set(draft.key, draft);
+		for (const background of draft.backgrounds) if (background.key) backgroundMap.set(background.key, background);
+	}
+	attachHeadAnnotations(metadataElements, lineMap, backgroundMap);
+	if (drafts.length === 0) return finalizeLyric(makeLyric({
+		format: FORMAT,
+		status: LyricStatus.INVALID,
+		meta,
+		extra
+	}));
+	const lines = drafts.map(buildLine);
+	const wordLevel = drafts.some((draft) => {
+		return draft.wordLevel || draft.backgrounds.some((background) => {
+			return background.wordLevel;
+		});
+	});
+	return finalizeLyric(makeLyric({
+		format: FORMAT,
+		status: LyricStatus.VALID,
+		timing: readDeclaredTiming(root) ?? (wordLevel ? Timing.WORD : Timing.LINE),
+		meta,
+		extra,
+		agents: readAgents(metadataElements.get("agent") ?? []),
+		languages: deriveLanguageUsages(lines),
+		lines
+	}));
 };
 //#endregion
 //#region src/formats/index.ts
@@ -584,9 +2296,10 @@ var parseLrc = (input, options = {}) => {
 */
 var detectFormat = (input) => {
 	if (detectLrc(input)) return "lrc";
+	if (detectTtml(input)) return "ttml";
 };
 /**
-* Unrecognized text returns `null`; a recognized format returns a lyric with its parser-assigned status.
+* Unrecognized text returns `null`; a recognized format returns its canonical lyric and diagnostics.
 * Annotation tracks travel with the source and are attached by the format's parser.
 */
 var parse = (input, options = {}) => {
@@ -594,17 +2307,24 @@ var parse = (input, options = {}) => {
 	if (!format) return null;
 	switch (format) {
 		case "lrc": return parseLrc(input, options);
+		case "ttml": return parseTtml(input, options);
 	}
 };
+var GENERATORS = {
+	lrc: generateLrc,
+	ttml: generateTtml
+};
 /**
 * Generates text in the requested format, which need not match `lyric.format`.
+*
+* The writer map pairs each format's options with its result and requires a writer for every supported format.
+* An unknown target returns `null`.
 */
 var generate = (lyric, target, options = {}) => {
-	switch (target) {
-		case "lrc": return generateLrc(lyric, options);
-	}
+	if (!Object.hasOwn(GENERATORS, target)) return null;
+	return GENERATORS[target](lyric, options);
 };
 //#endregion
-export { detectFormat, detectLrc, generate, generateLrc, parse, parseLrc };
+export { detectFormat, detectLrc, detectTtml, generate, generateLrc, generateTtml, parse, parseLrc, parseTtml };
 
 //# sourceMappingURL=formats.js.map