@gondola-lyrics/kit 0.2.0 → 0.4.0

package/dist/formats.js

@@ -1,13 +1,13 @@
-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, validateLyric } from "@gondola-lyrics/model/runtime";
+import { AgentType, CreditRole, LineType, LyricStatus, Timing, WordType, canonicalizeLyric, deriveLanguageUsages, getWordsText, makeAgent, makeLineAnnotation, makeLineAnnotationRoman, makeLineAnnotationTranslation, makeLineBackground, makeLineContentText, makeLineContentWords, makeLineInstrumental, 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]
 				})]]
 			})
@@ -233,6 +233,32 @@ var createXmlAttribute = (qualifiedName, value) => {
 	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) => {
@@ -291,27 +317,13 @@ var findXmlElement = (element, localName) => {
 	}
 };
 /**
-* Returns every element carrying one local name, the element itself included, in document order.
-*/
-var findXmlElements = (element, localName) => {
-	const result = [];
-	const stack = [element];
-	while (stack.length > 0) {
-		const node = stack.pop();
-		if (node === void 0 || node.nodeType !== XmlNodeType.element) continue;
-		if (node.localName === localName) result.push(node);
-		for (let index = node.children.length - 1; index >= 0; index -= 1) {
-			const child = node.children[index];
-			if (child !== void 0) stack.push(child);
-		}
-	}
-	return result;
-};
-/**
 * 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) {
@@ -330,21 +342,21 @@ var getXmlTextContent = (node) => {
 };
 //#endregion
 //#region src/utils/xml/reader.ts
-var LESS_THAN = 60;
-var GREATER_THAN = 62;
+var LESS_THAN$1 = 60;
+var GREATER_THAN$1 = 62;
 var SLASH = 47;
 var EQUALS = 61;
-var DOUBLE_QUOTE = 34;
+var DOUBLE_QUOTE$1 = 34;
 var SINGLE_QUOTE = 39;
 var EXCLAMATION = 33;
 var QUESTION = 63;
-var AMPERSAND = 38;
+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 = "#document";
+var ROOT_NAME$1 = "#document";
 var DECIMAL_DIGITS = /^\d+$/;
 var HEX_DIGITS = /^[0-9a-fA-F]+$/;
 /**
@@ -375,7 +387,7 @@ var decodeText = (text) => {
 	let start = 0;
 	let cursor = 0;
 	while (cursor < length) {
-		if (text.charCodeAt(cursor) !== AMPERSAND) {
+		if (text.charCodeAt(cursor) !== AMPERSAND$1) {
 			cursor += 1;
 			continue;
 		}
@@ -402,9 +414,9 @@ var parseXml = (source) => {
 	const stack = [];
 	const root = {
 		nodeType: XmlNodeType.element,
-		qualifiedName: ROOT_NAME,
+		qualifiedName: ROOT_NAME$1,
 		namespacePrefix: "",
-		localName: ROOT_NAME,
+		localName: ROOT_NAME$1,
 		attributes: [],
 		children: []
 	};
@@ -432,12 +444,12 @@ var parseXml = (source) => {
 	*/
 	const readQuotedValue = () => {
 		const quote = source.charCodeAt(position);
-		if (quote !== DOUBLE_QUOTE && quote !== SINGLE_QUOTE) {
+		if (quote !== DOUBLE_QUOTE$1 && quote !== SINGLE_QUOTE) {
 			valid = false;
 			return "";
 		}
 		position += 1;
-		const end = source.indexOf(quote === DOUBLE_QUOTE ? "\"" : "'", position);
+		const end = source.indexOf(quote === DOUBLE_QUOTE$1 ? "\"" : "'", position);
 		if (end === -1) {
 			valid = false;
 			return "";
@@ -454,7 +466,7 @@ var parseXml = (source) => {
 		const nameStart = cursor;
 		while (cursor < length) {
 			const code = source.charCodeAt(cursor);
-			if (code <= 32 || code === GREATER_THAN || code === SLASH || code === EQUALS) break;
+			if (code <= 32 || code === GREATER_THAN$1 || code === SLASH || code === EQUALS) break;
 			cursor += 1;
 		}
 		if (cursor === nameStart) {
@@ -482,14 +494,14 @@ var parseXml = (source) => {
 				code = source.charCodeAt(cursor);
 			}
 			if (cursor >= length) break;
-			if (code === GREATER_THAN) {
+			if (code === GREATER_THAN$1) {
 				cursor += 1;
 				closed = true;
 				break;
 			}
 			if (code === SLASH) {
 				cursor += 1;
-				if (cursor < length && source.charCodeAt(cursor) === GREATER_THAN) {
+				if (cursor < length && source.charCodeAt(cursor) === GREATER_THAN$1) {
 					cursor += 1;
 					closed = true;
 					selfClosing = true;
@@ -503,7 +515,7 @@ var parseXml = (source) => {
 				cursor += 1;
 				if (cursor >= length) break;
 				code = source.charCodeAt(cursor);
-			} while (code > 32 && code !== GREATER_THAN && code !== SLASH && code !== EQUALS);
+			} while (code > 32 && code !== GREATER_THAN$1 && code !== SLASH && code !== EQUALS);
 			if (cursor === attributeStart) {
 				valid = false;
 				return;
@@ -547,7 +559,7 @@ var parseXml = (source) => {
 		const nameStart = cursor;
 		while (cursor < length) {
 			const code = source.charCodeAt(cursor);
-			if (code <= 32 || code === GREATER_THAN) break;
+			if (code <= 32 || code === GREATER_THAN$1) break;
 			cursor += 1;
 		}
 		const name = source.slice(nameStart, cursor);
@@ -604,8 +616,8 @@ var parseXml = (source) => {
 		let depth = 1;
 		while (cursor < length && depth > 0) {
 			const code = source.charCodeAt(cursor);
-			if (code === LESS_THAN) depth += 1;
-			else if (code === GREATER_THAN) depth -= 1;
+			if (code === LESS_THAN$1) depth += 1;
+			else if (code === GREATER_THAN$1) depth -= 1;
 			cursor += 1;
 		}
 		if (depth > 0) {
@@ -654,6 +666,159 @@ var parseXml = (source) => {
 	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 };
@@ -747,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",
@@ -830,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) => {
@@ -1019,14 +1184,20 @@ var readWords$1 = (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.
+* Empty timed rows represent instrumental time rather than sung content.
 */
 var readLine$1 = (text, start, nextStart) => {
+	const trimmed = text.trim();
+	let end = nextStart !== void 0 && nextStart >= start ? nextStart : void 0;
+	if (trimmed === "") return makeLineInstrumental({ time: makeTimeRange({
+		start,
+		end
+	}) });
 	const wordTimed = isWordTimed(text);
 	const { drafts, closeSegment } = wordTimed ? readWords$1(text, start) : {
 		drafts: [],
 		closeSegment: () => {}
 	};
-	let end = nextStart !== void 0 && nextStart >= start ? nextStart : void 0;
 	if (end === void 0) end = [...drafts].reverse().find((draft) => !draft.space && draft.start !== void 0)?.end;
 	closeSegment(end);
 	const words = drafts.map((draft) => {
@@ -1044,7 +1215,7 @@ var readLine$1 = (text, start, nextStart) => {
 		start,
 		end
 	});
-	const content = wordTimed ? makeLineContentWords(words) : makeLineContentText(text.trim());
+	const content = wordTimed ? makeLineContentWords(words) : makeLineContentText(trimmed);
 	return makeLineNormal({
 		time,
 		content
@@ -1052,7 +1223,7 @@ var readLine$1 = (text, start, nextStart) => {
 };
 /**
 * Builds one line per timed row, so an annotation track reuses the original text's reading unchanged.
-* An empty timed row still yields a line, since it marks a gap rather than a parse failure.
+* Empty timed rows become instrumental lines bounded by the next timestamp when one is usable.
 */
 var readLines = (timed) => {
 	const lines = [];
@@ -1082,7 +1253,7 @@ var parseLrcText = (text) => {
 	});
 };
 /**
-* Source order, empty timed lines, and missing word times are preserved for model validation.
+* Empty timed rows become instrumental lines; source order and missing word times remain for model validation.
 *
 * Annotation tracks are read as lines too and attached by timestamp, and rows that match no line are dropped.
 *
@@ -1109,15 +1280,12 @@ var parseLrc = (input, options = {}) => {
 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 { original: input };
-	if (!input || typeof input !== "object") return null;
-	const source = input;
-	if (typeof source.original !== "string") return null;
-	return { original: source.original };
-};
-var readTtmlProfile = (source) => {
-	return AMLL_HINT_PATTERN.test(source) ? "amll" : "itunes";
+	if (typeof input !== "string") return null;
+	return input;
 };
 //#endregion
 //#region src/formats/ttml/detect.ts
@@ -1130,35 +1298,344 @@ var readTtmlProfile = (source) => {
 var detectTtml = (input) => {
 	const content = readTtmlContent(input);
 	if (!content) return false;
-	if (AMLL_HINT_PATTERN.test(content.original) || ITUNES_HINT_PATTERN.test(content.original)) return true;
-	const root = parseXml(content.original);
+	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/parser.ts
+//#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
+	};
+};
 /**
-* Reads the span time range, which a word needs both ends of to be sung.
+* Reserves source ids before allocating keys, so unnamed entries cannot take later source ids.
 */
-var readSpanTime = (element) => {
-	const begin = getXmlAttribute(element, "begin");
-	const end = getXmlAttribute(element, "end");
-	if (!begin || !end) return;
-	const start = parseTime(begin);
-	const finish = parseTime(end);
-	if (start === void 0 || finish === void 0) return;
+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 {
-		start,
-		end: finish
+		profile,
+		offset: lyric.meta?.offset ?? 0,
+		keys,
+		agents
 	};
 };
 /**
-* Reads the line time range, which may leave its end open for the next line to supply.
+* Bakes the playback offset into TTML timestamps without clamping negative results.
 */
-var readLineTime = (element) => {
+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);
@@ -1169,120 +1646,345 @@ var readLineTime = (element) => {
 		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();
+};
 /**
-* Turns a run of text into drafts, keeping the separators as space words.
-*
-* A span's own trailing space is part of the word it follows, so leading and trailing runs both survive.
+* Preserves the parser's whitespace segmentation when turning text into word drafts.
 */
-var splitWords = (text) => {
-	const words = [];
-	for (const run of text.split(/(\s+)/)) if (run !== "") words.push({
-		text: run,
-		space: !run.trim(),
+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) => {
+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 = getXmlTextContent(child).trim();
+			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 = getXmlTextContent(text).trim();
-			if (time === void 0 || !content) continue;
+			const content = readText(text, rubySpace);
+			if (!content) continue;
 			tokens.push({
-				start: time.start,
-				end: time.end,
+				start: time?.start,
+				end: time?.end,
 				text: content
 			});
 		}
 	}
-	const first = tokens[0];
-	const last = tokens[tokens.length - 1];
-	if (!base || first === void 0 || last === void 0) return;
+	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: first.start,
-		end: last.end,
-		rubies: [{
-			start: first.start,
-			end: last.end,
+		start: time?.start,
+		end: time?.end,
+		language: baseLanguage,
+		rubies: tokens.length === 0 ? [] : [{
+			start: rubyTime?.start,
+			end: rubyTime?.end,
+			language: rubyLanguage,
 			tokens
 		}]
 	};
 };
 /**
-* Reports whether a text run holds nothing but formatting whitespace, which only a pretty-printed source produces.
-*/
-var isFormattingWhitespace = (text) => {
-	return text.trim() === "" && text.includes("\n");
-};
-/**
 * Collects the words of one span-bearing element.
 *
-* Text between spans carries the separators, and a span without both ends contributes its text untimed.
+* 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.
-* Indentation between tags is dropped, since the words themselves keep their own trailing spaces.
+* Whitespace inside a span remains a separator; indentation is dropped only without a preserve declaration.
 */
-var readWords = (element) => {
+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.text) {
-			if (!isFormattingWhitespace(child.text)) words.push(...splitWords(child.text));
+		if (child.nodeType !== XmlNodeType.element) {
+			if (preserveSpace || !isFormattingWhitespace(child.text)) words.push(...splitWords(child.text, language));
 			continue;
 		}
-		if (child.nodeType !== XmlNodeType.element || child.localName !== "span") continue;
+		if (child.localName !== "span") continue;
 		if (getXmlAttribute(child, "role") !== void 0) continue;
 		if (getXmlAttribute(child, "ruby") === "container") {
-			const ruby = readRuby(child);
+			const ruby = readRuby(child, preserveSpace, language);
 			if (ruby !== void 0) {
-				words.push(ruby);
-				wordLevel = true;
+				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).trim();
-		if (!text) continue;
+		const text = getXmlTextContent(child);
+		const childSpace = readPreserveSpace(child, preserveSpace);
+		if (!text || !childSpace && isFormattingWhitespace(text)) continue;
 		const time = readSpanTime(child);
-		if (time === void 0) {
-			words.push({
-				text,
-				space: false,
-				rubies: []
-			});
-			continue;
+		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);
 		}
-		wordLevel = true;
-		words.push({
-			text,
-			space: false,
-			start: time.start,
-			end: time.end,
-			rubies: []
-		});
 	}
 	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) => {
+var readLine = (element, preserveSpace, language) => {
+	preserveSpace = readPreserveSpace(element, preserveSpace);
+	language = readLanguage(element, language);
 	const time = readLineTime(element);
 	if (time === void 0) return;
 	const draft = {
@@ -1294,33 +1996,25 @@ var readLine = (element) => {
 		translations: [],
 		romans: [],
 		backgrounds: [],
-		wordLevel: false
+		wordLevel: false,
+		preserveSpace,
+		language
 	};
 	if (!hasXmlChildElement(element, "span")) {
-		const plain = getXmlTextContent(element).trim();
+		const plain = readText(element, preserveSpace);
 		if (!plain) return;
-		draft.words = splitWords(plain);
+		draft.words = splitWords(plain, language);
 		return draft;
 	}
-	const read = readWords(element);
+	const read = readWords(element, preserveSpace, language);
 	draft.words = read.words;
 	draft.wordLevel = read.wordLevel;
-	for (const span of getXmlChildElements(element, "span")) {
-		const role = getXmlAttribute(span, "role");
-		if (!role) continue;
-		if (role === "x-bg") {
-			const background = readBackground(span);
-			if (background) draft.backgrounds.push(background);
-			continue;
-		}
-		const text = getXmlTextContent(span).trim();
-		if (!text) continue;
-		const item = {
-			language: lowerTag(getXmlAttribute(span, "lang")),
-			text
-		};
-		if (role === "x-translation") draft.translations.push(item);
-		else if (role === "x-roman") draft.romans.push(item);
+	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;
 };
@@ -1329,8 +2023,10 @@ var readLine = (element) => {
 *
 * A background line states no time of its own in AMLL files, so its range comes from its words.
 */
-var readBackground = (element) => {
-	const read = readWords(element);
+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");
@@ -1348,77 +2044,19 @@ var readBackground = (element) => {
 		agentId: getXmlAttribute(element, "agent"),
 		key: getXmlAttribute(element, "key"),
 		words: read.words,
-		translations: [],
-		romans: [],
+		...readInlineAnnotations(element, preserveSpace, language),
 		backgrounds: [],
-		wordLevel: read.wordLevel
+		wordLevel: read.wordLevel,
+		preserveSpace,
+		language
 	};
 };
-/**
-* Builds the model words of one draft line.
-*/
-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
-			}));
-			continue;
-		}
-		const rubies = word.rubies.map((ruby) => {
-			return makeWordAnnotationRuby({
-				time: makeTimeRange({
-					start: ruby.start,
-					end: ruby.end
-				}),
-				tokens: ruby.tokens.map((token) => {
-					return makeWordAnnotationToken({
-						text: token.text,
-						time: makeTimeRange({
-							start: token.start,
-							end: token.end
-						})
-					});
-				})
-			});
-		});
-		words.push(makeWordNormal({
-			text: word.text,
-			time,
-			annotation: makeWordAnnotation({ rubies })
-		}));
-	}
-	return words;
-};
-/**
-* Builds a line's annotation container, which the model only keeps when it holds something.
-*/
-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
-			});
-		})
-	});
+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.
@@ -1431,7 +2069,8 @@ var buildBackground = (draft) => {
 			end: draft.end
 		}),
 		agents: draft.agentId === void 0 ? [] : [draft.agentId],
-		content: makeLineContentWords(buildWords(draft)),
+		languages: draft.language === void 0 ? [] : [draft.language],
+		content: buildContent(draft),
 		annotation: buildLineAnnotation(draft)
 	});
 };
@@ -1439,9 +2078,6 @@ var buildBackground = (draft) => {
 * Builds one normal line, keeping plain text whole unless the source timed its words.
 */
 var buildLine = (draft) => {
-	const content = draft.wordLevel ? makeLineContentWords(buildWords(draft)) : makeLineContentText(draft.words.map((word) => {
-		return word.text;
-	}).join("").trim());
 	return makeLineNormal({
 		id: draft.key,
 		time: makeTimeRange({
@@ -1449,54 +2085,34 @@ var buildLine = (draft) => {
 			end: draft.end
 		}),
 		agents: draft.agentId === void 0 ? [] : [draft.agentId],
-		content,
+		languages: draft.language === void 0 ? [] : [draft.language],
+		content: buildContent(draft),
 		annotation: buildLineAnnotation(draft),
 		backgrounds: draft.backgrounds.map(buildBackground)
 	});
 };
 /**
-* Maps one iTunes agent type onto the model's.
-*
-* The model requires `raw` on `OTHER`, since it cannot tell whether the source stated that word or the reader gave up.
-*/
-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"
-		};
-	}
-};
-/**
 * Reads the head's agents, which lines reference by id.
 */
-var readAgents = (metadata) => {
-	if (!metadata) return [];
+var readAgents = (elements) => {
 	const agents = [];
-	for (const element of findXmlElements(metadata, "agent")) {
+	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 getXmlTextContent(name).trim();
+			return makeText({
+				text: readText(name, preserveSpace),
+				language: readLanguage(name, language)
+			});
 		}).filter((name) => {
-			return name !== "";
+			return name.text !== "";
 		});
 		const kind = readAgentType(getXmlAttribute(element, "type"));
 		agents.push(makeAgent({
 			id,
 			type: kind.type,
 			raw: kind.raw,
-			names: names.map((name) => {
-				return makeText({ text: name });
-			})
+			names
 		}));
 	}
 	return agents;
@@ -1506,43 +2122,56 @@ var readAgents = (metadata) => {
 *
 * AMLL wraps these in `iTunesMetadata`, so the whole head is searched rather than its direct children.
 */
-var readCredits = (metadata, meta) => {
-	if (!metadata) return;
-	const names = findXmlElements(metadata, "songwriter").map((element) => {
-		return getXmlTextContent(element).trim();
+var readCredits = (elements, meta) => {
+	const names = elements.map(({ element, preserveSpace, language }) => {
+		return makeText({
+			text: readText(element, preserveSpace),
+			language
+		});
 	}).filter((name) => {
-		return name !== "";
+		return name.text !== "";
 	});
 	if (names.length === 0) return;
 	meta.credits.push(makeMetaCredit({
 		role: CreditRole.LYRICIST,
-		names: names.map((name) => {
-			return makeText({ text: name });
-		})
+		names
 	}));
 };
 /**
 * Reads one `amll:meta` entry, keeping an unknown key as written so a round trip loses nothing.
 */
-var applyAmllMeta = (meta, element) => {
+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 }));
+			meta.titles.push(makeText({
+				text: value,
+				language
+			}));
 			return;
 		case "artists":
-			meta.artists.push(makeText({ text: value }));
+			meta.artists.push(makeText({
+				text: value,
+				language
+			}));
 			return;
 		case "album":
-			meta.albums.push(makeText({ text: value }));
+			meta.albums.push(makeText({
+				text: value,
+				language
+			}));
 			return;
 		case "isrc":
 			meta.isrcs.push(value);
 			return;
 		case "ttmlAuthorGithubLogin":
-			meta.authors.push(makeText({ text: value }));
+			meta.authors.push(makeText({
+				text: value,
+				language
+			}));
 			return;
 		default: meta.unknowns.push(makeUnknownEntry({
 			key,
@@ -1551,52 +2180,33 @@ var applyAmllMeta = (meta, element) => {
 	}
 };
 /**
-* Splits one annotation text into its main part and any background pieces it embeds.
-*/
-var splitBackgroundText = (element) => {
-	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: getXmlTextContent(child).trim(),
-				key: getXmlAttribute(child, "for")
-			});
-			continue;
-		}
-		main += getXmlTextContent(child);
-	}
-	return {
-		main: main.trim(),
-		backgrounds
-	};
-};
-/**
 * 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 (!metadata || lineMap.size === 0) return;
+	if (lineMap.size === 0) return;
 	const attach = (blocks, kind) => {
-		for (const block of blocks) {
-			const language = lowerTag(getXmlAttribute(block, "lang"));
+		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 { main, backgrounds } = splitBackgroundText(text);
+				const textLanguage = readLanguage(text, language);
+				const { main, backgrounds } = splitBackgroundText(text, preserveSpace, textLanguage);
 				if (kind === "translation" && type === "replacement") {
 					if (main) {
-						line.words = splitWords(main);
+						line.words = splitWords(main, textLanguage);
 						line.wordLevel = false;
+						line.preserveSpace = readPreserveSpace(text, preserveSpace);
+						line.language = textLanguage;
 					}
 					continue;
 				}
 				if (main) {
 					const item = {
-						language,
+						language: textLanguage,
 						text: main
 					};
 					if (kind === "translation") line.translations.push(item);
@@ -1607,7 +2217,7 @@ var attachHeadAnnotations = (metadata, lineMap, backgroundMap) => {
 					const target = background.key ? backgroundMap.get(background.key) : void 0;
 					if (!target) continue;
 					const item = {
-						language,
+						language: background.language,
 						text: background.text
 					};
 					if (kind === "translation") target.translations.push(item);
@@ -1616,36 +2226,8 @@ var attachHeadAnnotations = (metadata, lineMap, backgroundMap) => {
 			}
 		}
 	};
-	attach(findXmlElements(metadata, "translation"), "translation");
-	attach(findXmlElements(metadata, "transliteration"), "roman");
-};
-/**
-* Returns the paragraphs of a body, including any nested inside a div.
-*/
-var findParagraphs = (body) => {
-	const result = [];
-	const stack = [body];
-	while (stack.length > 0) {
-		const element = stack.pop();
-		if (!element) continue;
-		if (element.localName === "p") {
-			result.push(element);
-			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(child);
-		}
-	}
-	return result;
-};
-var readDeclaredTiming = (root) => {
-	switch (getXmlQualifiedAttribute(root, "itunes:timing")) {
-		case TIMING_WORD: return Timing.WORD;
-		case TIMING_LINE: return Timing.LINE;
-		default: return;
-	}
+	attach(metadata.get("translation") ?? [], "translation");
+	attach(metadata.get("transliteration") ?? [], "roman");
 };
 /**
 * Reads a TTML document into the model.
@@ -1660,8 +2242,8 @@ var parseTtml = (input, options = {}) => {
 		status: LyricStatus.INVALID,
 		meta: makeMeta()
 	}));
-	const extra = { profile: readTtmlProfile(content.original) };
-	const document = parseXml(content.original);
+	const extra = { profile: readTtmlProfile(content) };
+	const document = parseXml(content);
 	const root = document ? findXmlElement(document, "tt") : void 0;
 	if (!root) return finalizeLyric(makeLyric({
 		format: FORMAT,
@@ -1669,24 +2251,25 @@ var parseTtml = (input, options = {}) => {
 		meta: makeMeta(),
 		extra
 	}));
-	const body = findXmlElement(root, "body");
-	const metadata = findXmlElement(root, "metadata");
+	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();
-	const language = lowerTag(getXmlQualifiedAttribute(root, "xml:lang")) ?? lowerTag(options.language);
 	if (language !== void 0) meta.language = language;
-	readCredits(metadata, meta);
-	for (const element of metadata ? findXmlElements(metadata, "meta") : []) applyAmllMeta(meta, element);
+	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 of body ? findParagraphs(body) : []) {
-		const draft = readLine(element);
+	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(metadata, lineMap, backgroundMap);
+	attachHeadAnnotations(metadataElements, lineMap, backgroundMap);
 	if (drafts.length === 0) return finalizeLyric(makeLyric({
 		format: FORMAT,
 		status: LyricStatus.INVALID,
@@ -1695,7 +2278,9 @@ var parseTtml = (input, options = {}) => {
 	}));
 	const lines = drafts.map(buildLine);
 	const wordLevel = drafts.some((draft) => {
-		return draft.wordLevel;
+		return draft.wordLevel || draft.backgrounds.some((background) => {
+			return background.wordLevel;
+		});
 	});
 	return finalizeLyric(makeLyric({
 		format: FORMAT,
@@ -1703,7 +2288,7 @@ var parseTtml = (input, options = {}) => {
 		timing: readDeclaredTiming(root) ?? (wordLevel ? Timing.WORD : Timing.LINE),
 		meta,
 		extra,
-		agents: readAgents(metadata),
+		agents: readAgents(metadataElements.get("agent") ?? []),
 		languages: deriveLanguageUsages(lines),
 		lines
 	}));
@@ -1731,18 +2316,21 @@ var parse = (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`.
 *
-* A format without a writer has no branch here, so adding one to `LyricFormat` makes this fail to compile.
+* 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);
-		case "ttml": throw new Error("ttml generation is not implemented yet");
-	}
+	if (!Object.hasOwn(GENERATORS, target)) return null;
+	return GENERATORS[target](lyric, options);
 };
 //#endregion
-export { AMLL_HINT_PATTERN, FORMAT, ITUNES_HINT_PATTERN, detectFormat, detectLrc, detectTtml, generate, generateLrc, parse, parseLrc, parseTtml, readTtmlContent, readTtmlProfile };
+export { detectFormat, detectLrc, detectTtml, generate, generateLrc, generateTtml, parse, parseLrc, parseTtml };
 
 //# sourceMappingURL=formats.js.map