@gondola-lyrics/kit 0.3.0 → 0.4.0

package/dist/transforms.js

@@ -0,0 +1,1048 @@
+import { LineType, Timing, WordType, deriveLanguageUsages, makeLineAnnotation, makeLineAnnotationRoman, makeLineAnnotationTranslation, makeLineBackground, makeLineContentText, makeLineContentWords, makeLineInstrumental, makeTimeRange, makeWordEmphasis, makeWordSpace, validateTimeRange } from "@gondola-lyrics/model/runtime";
+//#region src/utils/array.ts
+/**
+* Preserves the input array when every element keeps its identity, so unchanged parent nodes can also be reused.
+*
+* The callback must leave inputs untouched and return the original element when unchanged.
+*/
+var mapShared = (items, transform) => {
+	let result = items;
+	for (const [index, item] of items.entries()) {
+		const transformed = transform(item);
+		if (transformed !== item) {
+			if (result === items) result = [...items];
+			result[index] = transformed;
+		}
+	}
+	return result;
+};
+//#endregion
+//#region src/transforms/background/utils.ts
+var OPEN_BRACKETS = /* @__PURE__ */ new Set(["(", "（"]);
+var CLOSE_BRACKETS = /* @__PURE__ */ new Set([")", "）"]);
+var isOpenBracket = (char) => {
+	return OPEN_BRACKETS.has(char);
+};
+var isCloseBracket = (char) => {
+	return CLOSE_BRACKETS.has(char);
+};
+var isNormalWord = (word) => {
+	return word.type === WordType.NORMAL;
+};
+/**
+* Content carries plain text or words, never both, so exactly one of the two is read.
+*/
+var readLineText = (line) => {
+	return line.content?.text ?? (line.content?.words ?? []).map((word) => word.text).join("");
+};
+var readTimeRange = (line) => {
+	return line.time ? makeTimeRange({
+		start: line.time.start,
+		end: line.time.end
+	}) : void 0;
+};
+//#endregion
+//#region src/transforms/background/brackets.ts
+/**
+* Removes one leading bracket from the first sung word and one trailing bracket from the last, so an inner pair stays as written.
+*
+* Space words at the same edge go with the bracket, and a word left with no text goes too, since a sung word must carry something.
+*/
+var stripWordEdges = (words) => {
+	const firstIndex = words.findIndex(isNormalWord);
+	const first = words[firstIndex];
+	const last = words[words.findLastIndex(isNormalWord)];
+	const stripStart = first ? isOpenBracket(first.text.charAt(0)) : false;
+	const stripEnd = last ? isCloseBracket(last.text.charAt(last.text.length - 1)) : false;
+	if (!stripStart && !stripEnd) return words;
+	const result = [...words];
+	if (stripStart && first) {
+		const text = first.text.slice(1);
+		if (text) result[firstIndex] = {
+			...first,
+			text
+		};
+		else result.splice(firstIndex, 1);
+		while (result[0]?.type === WordType.SPACE) result.shift();
+	}
+	const endIndex = result.findLastIndex(isNormalWord);
+	const end = result[endIndex];
+	if (stripEnd && end) {
+		const text = end.text.slice(0, -1);
+		if (text) result[endIndex] = {
+			...end,
+			text
+		};
+		else result.splice(endIndex, 1);
+		while (result.at(-1)?.type === WordType.SPACE) result.pop();
+	}
+	return result;
+};
+/**
+* Plain text is read literally, so a source that padded it with spaces keeps them; only word content
+* treats space words as the structural separators they are.
+*/
+var stripContentBrackets = (content) => {
+	if (!content) return content;
+	if (!content.words.length) {
+		const text = content.text;
+		if (!text) return content;
+		const start = isOpenBracket(text.charAt(0)) ? 1 : 0;
+		const end = isCloseBracket(text.charAt(text.length - 1)) ? -1 : 0;
+		if (!start && !end) return content;
+		const stripped = text.slice(start, end === 0 ? void 0 : end);
+		return stripped ? makeLineContentText(stripped) : void 0;
+	}
+	const words = stripWordEdges(content.words);
+	if (words === content.words) return content;
+	return words.length ? makeLineContentWords(words) : void 0;
+};
+var stripLineBackgrounds = (line) => {
+	if (!line.backgrounds.length) return line;
+	let changed = false;
+	const kept = [];
+	for (const background of line.backgrounds) {
+		const content = stripContentBrackets(background.content);
+		if (content === background.content) {
+			kept.push(background);
+			continue;
+		}
+		changed = true;
+		if (content) kept.push({
+			...background,
+			content
+		});
+	}
+	return changed ? {
+		...line,
+		backgrounds: kept
+	} : line;
+};
+/**
+* Removes the brackets some sources wrap around background vocals.
+*
+* One layer is removed from each edge of every background line, leaving a nested pair as `(x)`.
+* A line left with no content is dropped, since a background line must carry something.
+*
+* @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+*/
+var stripBackgroundBrackets = (lyric) => {
+	const lines = mapShared(lyric.lines, stripLineBackgrounds);
+	return lines === lyric.lines ? lyric : {
+		...lyric,
+		lines
+	};
+};
+//#endregion
+//#region src/transforms/background/extract.ts
+/**
+* An unclosed bracket never became a run, so its text returns to the line it came from.
+* An empty pair yields no run, since a background line must carry text.
+*/
+var splitText = (text) => {
+	const chars = [...text];
+	let main = "";
+	let current = "";
+	let opened = "";
+	let openedAt = 0;
+	let depth = 0;
+	const runs = [];
+	for (const [index, char] of chars.entries()) if (isOpenBracket(char)) {
+		if (depth) current += char;
+		else {
+			opened = char;
+			openedAt = index;
+		}
+		depth += 1;
+	} else if (isCloseBracket(char)) {
+		if (depth === 0) {
+			main += char;
+			continue;
+		}
+		depth -= 1;
+		if (depth) current += char;
+		else {
+			runs.push({
+				text: current,
+				start: openedAt + 1,
+				end: index
+			});
+			current = "";
+		}
+	} else if (depth) current += char;
+	else main += char;
+	if (depth) main += opened + current;
+	return {
+		main: main.trim().replaceAll(/\s{2,}/gu, " "),
+		runs: runs.filter((run) => {
+			return run.text.trim() !== "";
+		}),
+		length: chars.length
+	};
+};
+/**
+* A word straddling a bracket is cut into pieces sharing its time, since the source gave no finer boundary.
+* An unclosed bracket never became a run, so its text returns to the line it came from.
+* An empty pair yields no run, since a background line must carry text.
+*/
+var splitWords = (words) => {
+	const main = [];
+	const runs = [];
+	let current = [];
+	let opened;
+	let depth = 0;
+	for (const word of words) {
+		if (!isNormalWord(word)) {
+			(depth ? current : main).push(word);
+			continue;
+		}
+		let buffer = "";
+		for (const char of word.text) if (isOpenBracket(char)) {
+			if (depth) buffer += char;
+			else {
+				if (buffer) {
+					main.push({
+						...word,
+						text: buffer
+					});
+					buffer = "";
+				}
+				opened = {
+					...word,
+					text: char
+				};
+			}
+			depth += 1;
+		} else if (isCloseBracket(char)) {
+			if (depth === 0) {
+				buffer += char;
+				continue;
+			}
+			depth -= 1;
+			if (depth) buffer += char;
+			else {
+				if (buffer) {
+					current.push({
+						...word,
+						text: buffer
+					});
+					buffer = "";
+				}
+				if (current.length) {
+					runs.push(current);
+					current = [];
+				}
+			}
+		} else buffer += char;
+		if (buffer) (depth ? current : main).push({
+			...word,
+			text: buffer
+		});
+	}
+	if (depth) {
+		if (opened) main.push(opened);
+		main.push(...current);
+	}
+	return {
+		main,
+		runs: runs.filter((run) => {
+			return run.some((word) => {
+				return word.text.trim() !== "";
+			});
+		})
+	};
+};
+var mapSpan = (range, length, run) => {
+	if (range.end === void 0 || length === 0) return makeTimeRange({
+		start: range.start,
+		end: range.end
+	});
+	const span = range.end - range.start;
+	const start = range.start + Math.round(span * run.start / length);
+	const end = range.start + Math.round(span * run.end / length);
+	return makeTimeRange({
+		start,
+		end: Math.max(start, end)
+	});
+};
+/**
+* Falls back to the line's own range when no word carries a time, so a run still gets a range.
+*/
+var readWordRange = (words, fallback) => {
+	const timed = words.filter((word) => {
+		return isNormalWord(word) && word.time !== void 0;
+	});
+	const first = timed[0]?.time;
+	const last = timed.at(-1)?.time;
+	if (!first || !last) return fallback;
+	return makeTimeRange({
+		start: first.start,
+		end: last.end
+	});
+};
+/**
+* A background may start before its line but not finish after it, so the line grows to the furthest stated end.
+*/
+var attach = (line, backgrounds) => {
+	const merged = [...line.backgrounds, ...backgrounds];
+	merged.sort((left, right) => {
+		const leftStart = left.time?.start ?? 0;
+		const rightStart = right.time?.start ?? 0;
+		return leftStart === rightStart ? (left.time?.end ?? 0) - (right.time?.end ?? 0) : leftStart - rightStart;
+	});
+	let end = line.time?.end;
+	for (const background of merged) {
+		const backgroundEnd = background.time?.end;
+		if (backgroundEnd !== void 0 && (end === void 0 || backgroundEnd > end)) end = backgroundEnd;
+	}
+	if (!line.time || end === line.time.end) return {
+		...line,
+		backgrounds: merged
+	};
+	return {
+		...line,
+		time: makeTimeRange({
+			start: line.time.start,
+			end
+		}),
+		backgrounds: merged
+	};
+};
+/**
+* A closed line cannot hold an open background, so it stops where the line does.
+* On the last line the timeline itself ends unknown, so an open background leaves the line open too.
+*/
+var boundOpenBackgrounds = (lines) => {
+	const last = lines.length - 1;
+	return lines.map((line, index) => {
+		if (!line.backgrounds.filter((background) => {
+			return background.time !== void 0 && background.time.end === void 0;
+		}).length) return line;
+		if (index === last) return line.time ? {
+			...line,
+			time: makeTimeRange({ start: line.time.start })
+		} : line;
+		if (!line.time || line.time.end === void 0) return line;
+		const end = line.time.end;
+		return {
+			...line,
+			backgrounds: line.backgrounds.map((background) => {
+				const time = background.time;
+				if (!time || time.end !== void 0) return background;
+				return {
+					...background,
+					time: makeTimeRange({
+						start: time.start,
+						end: Math.max(time.start, end)
+					})
+				};
+			})
+		};
+	});
+};
+/**
+* Words are kept only where the caller says the lyric is word-timed, since the other timings forbid them.
+*/
+var makeBackground = (line, words, text, time, wordLevel) => {
+	return makeLineBackground({
+		time,
+		agents: [...line.agents],
+		languages: [...line.languages],
+		content: wordLevel && words.length ? makeLineContentWords(words) : makeLineContentText(text)
+	});
+};
+var readBackgrounds = (line, wordLevel) => {
+	const content = line.content;
+	if (!content) return [];
+	const range = line.time;
+	if (wordLevel && content.words.length) return splitWords(content.words).runs.map((words) => {
+		const time = range ? readWordRange(words, range) : void 0;
+		return makeBackground(line, words, words.map((word) => word.text).join(""), time, wordLevel);
+	});
+	const text = content.text ?? content.words.map((word) => word.text).join("");
+	if (!text) return [];
+	const { runs, length } = splitText(text);
+	return runs.map((run) => {
+		return makeBackground(line, [], run.text, range ? mapSpan(range, length, run) : void 0, false);
+	});
+};
+/**
+* An entry without brackets stays on the line, since only the bracketed part describes a background.
+* The line's annotation is rebuilt rather than edited, so the input lyric stays untouched.
+*/
+var splitAnnotation = (annotation, backgrounds) => {
+	if (!annotation || !backgrounds.length) return annotation;
+	const move = (items, rebuild, push) => {
+		return items.map((item) => {
+			const { main, runs } = splitText(item.text);
+			if (!runs.length) return item;
+			for (const [index, run] of runs.entries()) {
+				const background = backgrounds[index];
+				if (background) push(background, run.text, item.language);
+			}
+			return rebuild(item, main);
+		});
+	};
+	const romans = move(annotation.romans, (item, text) => makeLineAnnotationRoman({
+		...item,
+		text
+	}), (background, text, language) => {
+		background.annotation ??= makeLineAnnotation();
+		background.annotation.romans.push(makeLineAnnotationRoman({
+			text,
+			language
+		}));
+	});
+	const translations = move(annotation.translations, (item, text) => makeLineAnnotationTranslation({
+		...item,
+		text
+	}), (background, text, language) => {
+		background.annotation ??= makeLineAnnotation();
+		background.annotation.translations.push(makeLineAnnotationTranslation({
+			text,
+			language
+		}));
+	});
+	return makeLineAnnotation({
+		...annotation,
+		romans,
+		translations
+	});
+};
+/**
+* Words survive only where the lyric is word-timed, since the other timings forbid them.
+*/
+var toBackground = (line, time, wordLevel) => {
+	const content = line.content;
+	if (!content) return;
+	const text = content.text ?? content.words.map((word) => word.text).join("");
+	if (!text) return;
+	return makeLineBackground({
+		time,
+		agents: [...line.agents],
+		languages: [...line.languages],
+		content: wordLevel && content.words.length ? content : makeLineContentText(text),
+		annotation: line.annotation
+	});
+};
+var isBracketOnlyLine = (line) => {
+	if (!line || line.type !== LineType.NORMAL) return false;
+	const { main, runs } = splitText(readLineText(line));
+	return runs.length > 0 && !main;
+};
+/**
+* A line that held nothing but brackets has no text of its own to sing, so it cannot be the one a background accompanies.
+*/
+var findParentIndex = (lines) => {
+	for (let index = lines.length - 1; index >= 0; index--) {
+		const line = lines[index];
+		if (line?.type === LineType.NORMAL && !isBracketOnlyLine(line)) return index;
+	}
+	return -1;
+};
+/**
+* Both source lines go, since neither holds anything left to sing, and the joined range spans both.
+*/
+var joinCrossLine = (lines, wordLevel) => {
+	const result = [];
+	let changed = false;
+	let skip = false;
+	for (const [index, line] of lines.entries()) {
+		if (skip) {
+			skip = false;
+			continue;
+		}
+		const next = lines[index + 1];
+		const parentIndex = findParentIndex(result);
+		if (line.type === LineType.NORMAL && next?.type === LineType.NORMAL && parentIndex !== -1) {
+			const opened = splitText(readLineText(line));
+			const closed = splitText(readLineText(next));
+			const opens = opened.runs.length === 0 && isOpenBracket(opened.main.charAt(0));
+			const closes = closed.runs.length === 0 && isCloseBracket(closed.main.charAt(closed.main.length - 1));
+			if (opens && closes) {
+				const start = line.time?.start;
+				const end = next.time?.end ?? next.time?.start;
+				const background = toBackground({
+					...line,
+					content: makeLineContentText(opened.main.slice(1) + closed.main.slice(0, -1))
+				}, start === void 0 ? void 0 : makeTimeRange({
+					start,
+					end
+				}), wordLevel);
+				if (background) {
+					result[parentIndex] = attach(result[parentIndex], [background]);
+					changed = true;
+					skip = true;
+					continue;
+				}
+			}
+		}
+		result.push(line);
+	}
+	return {
+		lines: result,
+		changed
+	};
+};
+var stripRuns = (content) => {
+	if (content.words.length) {
+		const { main } = splitWords(content.words);
+		return main.length ? makeLineContentWords(main) : void 0;
+	}
+	const { main } = splitText(content.text ?? "");
+	return main ? makeLineContentText(main) : void 0;
+};
+/**
+* Pulls bracketed background vocals out of the sung lines and attaches them to the line they accompany.
+*
+* A line holding nothing but brackets becomes a background of the line before it and is removed.
+* A bracket opened on one line and closed on a later one joins the line before the opening, and both source lines go.
+* Text outside brackets stays on its line, and a line left with none keeps its place.
+*
+* @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+*/
+var extractBackgroundLines = (lyric, options = {}) => {
+	const fullLine = options.fullLine ?? true;
+	const inLine = options.inLine ?? true;
+	const crossLine = options.crossLine ?? true;
+	if (!lyric.lines.length) return lyric;
+	const wordLevel = lyric.timing === Timing.WORD;
+	const joined = crossLine ? joinCrossLine(lyric.lines, wordLevel) : {
+		lines: lyric.lines,
+		changed: false
+	};
+	const result = [];
+	let changed = joined.changed;
+	for (const line of joined.lines) {
+		if (line.type !== LineType.NORMAL || !line.content) {
+			result.push(line);
+			continue;
+		}
+		const parentIndex = findParentIndex(result);
+		if (fullLine && parentIndex !== -1) {
+			const { main, runs } = splitText(readLineText(line));
+			if (runs.length && !main) {
+				const backgrounds = runs.map((run) => {
+					return makeBackground(line, [], run.text, readTimeRange(line), false);
+				});
+				result[parentIndex] = attach(result[parentIndex], backgrounds);
+				changed = true;
+				continue;
+			}
+		}
+		const backgrounds = inLine ? readBackgrounds(line, wordLevel) : [];
+		if (!backgrounds.length) {
+			result.push(line);
+			continue;
+		}
+		const nextContent = stripRuns(line.content);
+		if (!nextContent) {
+			result.push(line);
+			continue;
+		}
+		const extracted = {
+			...line,
+			content: nextContent,
+			annotation: splitAnnotation(line.annotation, backgrounds)
+		};
+		result.push(attach(extracted, backgrounds));
+		changed = true;
+	}
+	if (!changed) return lyric;
+	const lines = boundOpenBackgrounds(result);
+	return {
+		...lyric,
+		lines,
+		languages: deriveLanguageUsages(lines)
+	};
+};
+//#endregion
+//#region src/transforms/emphasis/index.ts
+var deriveContentEmphasis = (content, durationThreshold) => {
+	if (content === void 0) return content;
+	const words = mapShared(content.words, (word) => {
+		if (word.type !== WordType.NORMAL || word.emphasis?.derived === false) return word;
+		const time = word.time;
+		if (time !== void 0 && time.end !== void 0 && validateTimeRange(time).length === 0 && time.end - time.start > durationThreshold) {
+			if (word.emphasis?.value === true) return word;
+			return {
+				...word,
+				emphasis: makeWordEmphasis({
+					value: true,
+					derived: true
+				})
+			};
+		}
+		if (word.emphasis === void 0) return word;
+		return {
+			...word,
+			emphasis: void 0
+		};
+	});
+	return words === content.words ? content : {
+		...content,
+		words
+	};
+};
+/**
+* Derives emphasis for normal words in lead and background vocals using complete, valid word ranges.
+* The stored word duration must strictly exceed durationThreshold; metadata offset and duration have no effect.
+*
+* Source emphasis, including an explicit false, is preserved; derived emphasis is cleared when a word no longer qualifies.
+*
+* @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+*
+* @throws {RangeError} If durationThreshold is not a non-negative safe integer in milliseconds.
+*/
+var deriveWordEmphasis = (lyric, options = {}) => {
+	const durationThreshold = options.durationThreshold ?? 3e3;
+	if (!Number.isSafeInteger(durationThreshold) || durationThreshold < 0) throw new RangeError("durationThreshold must be a non-negative safe integer in milliseconds");
+	const lines = mapShared(lyric.lines, (line) => {
+		if (line.type !== LineType.NORMAL) return line;
+		const content = deriveContentEmphasis(line.content, durationThreshold);
+		const backgrounds = mapShared(line.backgrounds, (background) => {
+			const content = deriveContentEmphasis(background.content, durationThreshold);
+			return content === background.content ? background : {
+				...background,
+				content
+			};
+		});
+		return content === line.content && backgrounds === line.backgrounds ? line : {
+			...line,
+			content,
+			backgrounds
+		};
+	});
+	return lines === lyric.lines ? lyric : {
+		...lyric,
+		lines
+	};
+};
+//#endregion
+//#region src/transforms/instrumental/index.ts
+var MAX_TIME = 2 ** 31 - 1;
+var readMinimum = (value, fallback, name) => {
+	const minimum = value ?? fallback;
+	if (!Number.isSafeInteger(minimum) || minimum < 0) throw new RangeError(`${name} must be a non-negative safe integer in milliseconds`);
+	return minimum;
+};
+var readEndTime = (value) => {
+	if (value !== void 0 && (!Number.isInteger(value) || value < 0 || value > MAX_TIME)) throw new RangeError(`endTime must be a non-negative integer in milliseconds no greater than ${MAX_TIME}`);
+	return value;
+};
+var compareTimeRanges = (left, right) => {
+	const leftStart = left?.start ?? Infinity;
+	const rightStart = right?.start ?? Infinity;
+	if (leftStart !== rightStart) return leftStart - rightStart;
+	const leftEnd = left?.end ?? Infinity;
+	const rightEnd = right?.end ?? Infinity;
+	return leftEnd === rightEnd ? 0 : leftEnd - rightEnd;
+};
+var readOccupiedTimeline = (lyric) => {
+	const ranges = [];
+	let firstSungStart = Infinity;
+	const append = (time, sung) => {
+		if (time === void 0 || validateTimeRange(time).length > 0) return false;
+		if (time.end === time.start) return true;
+		ranges.push(time);
+		if (sung) firstSungStart = Math.min(firstSungStart, time.start);
+		return true;
+	};
+	for (const line of lyric.lines) {
+		if (!append(line.time, line.type === LineType.NORMAL)) return;
+		for (const background of line.backgrounds) if (!append(background.time, true)) return;
+	}
+	ranges.sort(compareTimeRanges);
+	return {
+		ranges,
+		firstSungStart
+	};
+};
+var compareLineTimes = (left, right) => {
+	return compareTimeRanges(left.time, right.time);
+};
+var mergeLines = (lines, inserted) => {
+	let source = lines;
+	for (const [index, line] of lines.entries()) {
+		const previous = lines[index - 1];
+		if (previous !== void 0 && compareLineTimes(previous, line) > 0) {
+			source = [...lines].sort(compareLineTimes);
+			break;
+		}
+	}
+	const merged = [];
+	let nextIndex = 0;
+	for (const line of source) {
+		let next = inserted[nextIndex];
+		while (next !== void 0 && compareLineTimes(next, line) < 0) {
+			merged.push(next);
+			nextIndex += 1;
+			next = inserted[nextIndex];
+		}
+		merged.push(line);
+	}
+	merged.push(...inserted.slice(nextIndex));
+	return merged;
+};
+/**
+* Inserts derived instrumental lines into uncovered gaps on the stored timeline, starting at zero.
+* Existing lines and background vocals occupy their full ranges; an unknown end blocks later gaps.
+*
+* An outro requires an explicit endTime; metadata duration and offset do not affect insertion.
+*
+* @returns The input when unchanged, or a new lyric and lines array sharing existing nodes.
+*/
+var insertInstrumentalLines = (lyric, options = {}) => {
+	const minDuration = readMinimum(options.minDuration, 1e4, "minDuration");
+	const minIntroDuration = readMinimum(options.minIntroDuration, 5e3, "minIntroDuration");
+	const endTime = readEndTime(options.endTime);
+	if (lyric.timing !== Timing.LINE && lyric.timing !== Timing.WORD || lyric.lines.length === 0) return lyric;
+	const occupied = readOccupiedTimeline(lyric);
+	if (!occupied || occupied.firstSungStart === Infinity) return lyric;
+	const inserted = [];
+	let coveredEnd = 0;
+	const appendGap = (end, minimum) => {
+		const duration = end - coveredEnd;
+		if (duration > 0 && duration >= minimum) inserted.push(makeLineInstrumental({ time: makeTimeRange({
+			start: coveredEnd,
+			end
+		}) }));
+	};
+	for (const range of occupied.ranges) {
+		appendGap(range.start, range.start <= occupied.firstSungStart ? minIntroDuration : minDuration);
+		coveredEnd = Math.max(coveredEnd, range.end ?? Infinity);
+		if (coveredEnd === Infinity) break;
+	}
+	if (endTime !== void 0) appendGap(endTime, minDuration);
+	if (inserted.length === 0) return lyric;
+	return {
+		...lyric,
+		lines: mergeLines(lyric.lines, inserted)
+	};
+};
+//#endregion
+//#region src/transforms/space/constants.ts
+/**
+* Groups of characters a source may write without a space where one belongs.
+*/
+var InsertSpacesRules = {
+	/**
+	* A CJK character touching a Latin letter, as in `ABC中文`.
+	*/
+	CJK_ENGLISH: "cjkEnglish",
+	/**
+	* A CJK character touching a digit, as in `2026年`.
+	*/
+	CJK_NUMBER: "cjkNumber",
+	/**
+	* A comma, semicolon, exclamation mark, question mark or colon touching a character, as in `a,b`; a clock time or thousands separator such as `10:30` stays as written.
+	*/
+	PUNCTUATION: "punctuation",
+	/**
+	* A quotation mark touching a neighbouring character.
+	*/
+	QUOTE: "quote",
+	/**
+	* A bracket touching the character outside it.
+	*/
+	BRACKET_OUTSIDE: "bracketOutside",
+	/**
+	* A plus, equals or ampersand touching a character, as in `a+b`; a compound operator such as `a+=b` stays as written.
+	*/
+	MATH_OPERATOR: "mathOperator",
+	/**
+	* A hyphen touching a CJK character, as in `中-文`; a compound word such as `well-known` stays as written.
+	*/
+	HYPHEN: "hyphen",
+	/**
+	* A slash touching a character, as in `and/or`; a fraction such as `1/2` stays as written.
+	*/
+	SLASH: "slash",
+	/**
+	* Runs of two or more spaces, collapsed to one.
+	*/
+	COMPRESS_SPACES: "compressSpaces",
+	/**
+	* Spaces just inside a bracket or quotation mark, removed.
+	*/
+	TRIM_INSIDE_SYMBOLS: "trimInsideSymbols"
+};
+var INSERT_SPACES_RULES = Object.values(InsertSpacesRules);
+//#endregion
+//#region src/transforms/space/rules.ts
+var CJK_RANGE = "぀-ヿ㐀-䶿一-鿿豈-﫿";
+var LATIN_RANGE = "A-Za-z";
+var DIGIT_RANGE = "0-9";
+var SYMBOL_RANGE = "!@#$%^&+\\-=/|<>";
+var WORD_RANGE = `${LATIN_RANGE}${DIGIT_RANGE}${CJK_RANGE}`;
+var ALL_RANGE = `${WORD_RANGE}${SYMBOL_RANGE}`;
+var CJK_LATIN = new RegExp(`([${CJK_RANGE}])([${LATIN_RANGE}])`, "gu");
+var LATIN_CJK = new RegExp(`([${LATIN_RANGE}])([${CJK_RANGE}])`, "gu");
+var CJK_DIGIT = new RegExp(`([${CJK_RANGE}])([${DIGIT_RANGE}])`, "gu");
+var DIGIT_CJK = new RegExp(`([${DIGIT_RANGE}])([${CJK_RANGE}])`, "gu");
+var PUNCTUATION = new RegExp(`([${ALL_RANGE}])([!;,\\?:])(?=[${ALL_RANGE}])`, "gu");
+var QUOTE_BEFORE = new RegExp(`([${CJK_RANGE}${LATIN_RANGE}${DIGIT_RANGE}])(["\`“‘])`, "gu");
+var QUOTE_AFTER = new RegExp(`(["”’])([${CJK_RANGE}${LATIN_RANGE}${DIGIT_RANGE}])`, "gu");
+var BRACKET_BEFORE = new RegExp(`([${WORD_RANGE}])([\\[({<])`, "gu");
+var BRACKET_AFTER = new RegExp(`([\\])}>])([${WORD_RANGE}])`, "gu");
+var MATH_OPERATOR = new RegExp(`([${ALL_RANGE}])([+=&])(?=[${ALL_RANGE}])`, "gu");
+var HYPHEN = new RegExp(`(?<=[${WORD_RANGE}])-(?=[${WORD_RANGE}])`, "gu");
+var SLASH = new RegExp(`([${WORD_RANGE}])(/)(?=[${WORD_RANGE}])`, "gu");
+var TRIM_INSIDE_SYMBOLS = /* @__PURE__ */ new RegExp("([<[{\"“‘(])\\s*([^<>[\\]{}()\"“‘”’]*?)\\s*([>\\]}\"”’)])", "gu");
+var REPEATED_SPACES = / {2,}/gu;
+var REPEATED_MARKS = /[!;,\\?:+\-=/&]{2,}/gu;
+var PLACEHOLDER = /\u0001(\d+)\u0001/gu;
+var isDigit = (char) => {
+	return char !== void 0 && char >= "0" && char <= "9";
+};
+var isLatin = (char) => {
+	return char !== void 0 && (char >= "A" && char <= "Z" || char >= "a" && char <= "z");
+};
+/**
+* A comma or colon between two digits belongs to one number or clock time, so it stays tight.
+*/
+var applyPunctuation = (text) => {
+	return text.replace(PUNCTUATION, (match, before, mark, offset, source) => {
+		if ((mark === "," || mark === ":") && isDigit(before) && isDigit(source[offset + match.length])) return match;
+		return `${before}${mark} `;
+	});
+};
+/**
+* A hyphen between two digits is a date, range or phone number, and one between two Latin letters joins a compound word.
+*
+* An edge hyphen is left alone, since it reads as a sign or a list marker rather than a dash.
+*/
+var applyHyphen = (text) => {
+	return text.replace(HYPHEN, (match, offset, source) => {
+		const left = source[offset - 1];
+		const right = source[offset + 1];
+		return isDigit(left) && isDigit(right) || isLatin(left) && isLatin(right) ? match : " - ";
+	});
+};
+/**
+* A slash between two digits is a fraction or date, so it stays tight.
+*/
+var applySlash = (text) => {
+	return text.replace(SLASH, (match, before, slash, offset, source) => {
+		return isDigit(before) && isDigit(source[offset + match.length]) ? match : `${before} ${slash} `;
+	});
+};
+/**
+* Trims the spaces just inside a bracket or quotation mark, without touching a nested pair inside it.
+*/
+var applyTrimInsideSymbols = (text) => {
+	return text.replace(TRIM_INSIDE_SYMBOLS, (match, left, inner, right) => {
+		return `${left}${inner.trim()}${right}`;
+	});
+};
+var APPLIERS = {
+	[InsertSpacesRules.CJK_ENGLISH]: (text) => {
+		return text.replace(CJK_LATIN, "$1 $2").replace(LATIN_CJK, "$1 $2");
+	},
+	[InsertSpacesRules.CJK_NUMBER]: (text) => {
+		return text.replace(CJK_DIGIT, "$1 $2").replace(DIGIT_CJK, "$1 $2");
+	},
+	[InsertSpacesRules.PUNCTUATION]: applyPunctuation,
+	[InsertSpacesRules.QUOTE]: (text) => {
+		return text.replace(QUOTE_BEFORE, "$1 $2").replace(QUOTE_AFTER, "$1 $2");
+	},
+	[InsertSpacesRules.BRACKET_OUTSIDE]: (text) => {
+		return text.replace(BRACKET_BEFORE, "$1 $2").replace(BRACKET_AFTER, "$1 $2");
+	},
+	[InsertSpacesRules.MATH_OPERATOR]: (text) => {
+		return text.replace(MATH_OPERATOR, "$1 $2 ");
+	},
+	[InsertSpacesRules.HYPHEN]: applyHyphen,
+	[InsertSpacesRules.SLASH]: applySlash,
+	[InsertSpacesRules.COMPRESS_SPACES]: (text) => {
+		return text.replace(REPEATED_SPACES, " ");
+	},
+	[InsertSpacesRules.TRIM_INSIDE_SYMBOLS]: applyTrimInsideSymbols
+};
+var APPLY_ORDER = [
+	InsertSpacesRules.CJK_ENGLISH,
+	InsertSpacesRules.CJK_NUMBER,
+	InsertSpacesRules.PUNCTUATION,
+	InsertSpacesRules.QUOTE,
+	InsertSpacesRules.BRACKET_OUTSIDE,
+	InsertSpacesRules.MATH_OPERATOR,
+	InsertSpacesRules.HYPHEN,
+	InsertSpacesRules.SLASH,
+	InsertSpacesRules.TRIM_INSIDE_SYMBOLS,
+	InsertSpacesRules.COMPRESS_SPACES
+];
+/**
+* Falls back to every rule only when no list was given, so an explicit empty list means "apply nothing".
+*/
+var resolveRules = (rules) => {
+	return new Set(rules ?? INSERT_SPACES_RULES);
+};
+/**
+* Applies the selected rules to one text, returning it trimmed.
+*
+* Repeated marks are held aside first, so a rule that widens a single mark never splits a run that belongs together.
+*/
+var insertSpaces = (text, rules) => {
+	if (!text.trim()) return text;
+	const held = [];
+	let result = text.replace(REPEATED_MARKS, (match) => {
+		held.push(match);
+		return `\u0001${held.length - 1}\u0001`;
+	});
+	for (const rule of APPLY_ORDER) if (rules.has(rule)) result = APPLIERS[rule](result);
+	return result.replace(PLACEHOLDER, (match, index) => {
+		return held[Number(index)] ?? match;
+	}).trim();
+};
+//#endregion
+//#region src/transforms/space/insert.ts
+/**
+* Maps the rewritten text back onto the original words.
+*
+* Every non-space character of the original survives in order, so walking both strings keeps each word's time,
+* language and annotation while the inserted spaces become their own words.
+* A word whose characters stay adjacent in the rewrite is kept whole, so only a word the space actually cuts is split.
+*/
+var alignWords = (words, text) => {
+	const source = words.filter(isNormalWord);
+	const result = [];
+	let cursor = 0;
+	const takeSpaces = () => {
+		let spaces = "";
+		while (text[cursor] === " ") {
+			spaces += " ";
+			cursor += 1;
+		}
+		return spaces;
+	};
+	for (const word of source) {
+		const spaces = takeSpaces();
+		if (spaces) result.push(makeWordSpace({ text: spaces }));
+		if (text.startsWith(word.text, cursor)) {
+			result.push(word);
+			cursor += word.text.length;
+			continue;
+		}
+		let remaining = word.text;
+		while (remaining) {
+			let taken = 0;
+			while (taken < remaining.length && text[cursor + taken] === remaining[taken]) taken += 1;
+			if (taken === 0) return;
+			result.push({
+				...word,
+				text: remaining.slice(0, taken)
+			});
+			cursor += taken;
+			remaining = remaining.slice(taken);
+			if (!remaining) break;
+			const split = takeSpaces();
+			if (!split) return;
+			result.push(makeWordSpace({ text: split }));
+		}
+	}
+	const tail = takeSpaces();
+	if (tail) result.push(makeWordSpace({ text: tail }));
+	if (cursor !== text.length) return;
+	return result;
+};
+/**
+* Applies the rules to a word-level content, keeping it unchanged when the alignment fails.
+*/
+var applyToWords = (content, rules) => {
+	const text = content.words.map((word) => word.text).join("");
+	const rewritten = insertSpaces(text, rules);
+	if (rewritten === text) return content;
+	const words = alignWords(content.words, rewritten);
+	if (!words) return content;
+	return words.length ? makeLineContentWords(words) : void 0;
+};
+/**
+* Applies the rules to a plain-text content, dropping a line the rules would leave empty.
+*/
+var applyToText = (content, rules) => {
+	const text = content.text ?? "";
+	const rewritten = insertSpaces(text, rules);
+	if (rewritten === text) return content;
+	return rewritten ? makeLineContentText(rewritten) : void 0;
+};
+/**
+* Applies the rules to one content by the shape it carries.
+*/
+var applyToContent = (content, rules) => {
+	if (!content) return content;
+	return content.words.length ? applyToWords(content, rules) : applyToText(content, rules);
+};
+/**
+* Applies the rules to the line annotation, keeping the entries they leave untouched.
+*/
+var applyToAnnotation = (annotation, rules) => {
+	if (!annotation) return annotation;
+	let changed = false;
+	const romans = annotation.romans.map((item) => {
+		const text = insertSpaces(item.text, rules);
+		if (text === item.text) return item;
+		changed = true;
+		return makeLineAnnotationRoman({
+			...item,
+			text
+		});
+	});
+	const translations = annotation.translations.map((item) => {
+		const text = insertSpaces(item.text, rules);
+		if (text === item.text) return item;
+		changed = true;
+		return makeLineAnnotationTranslation({
+			...item,
+			text
+		});
+	});
+	return changed ? {
+		...annotation,
+		romans,
+		translations
+	} : annotation;
+};
+/**
+* Inserts the spaces a source left out, so CJK text set against Latin letters, digits or punctuation reads evenly.
+*
+* A word-level line keeps every word's time and annotation: an inserted space becomes its own space word,
+* and a word the rules split yields one word per character, all sharing the original range.
+* A plain-text line and the annotation tracks are rewritten as whole strings.
+*
+* @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+*/
+var insertSpacesInLines = (lyric, options = {}) => {
+	const rules = resolveRules(options.rules);
+	const annotations = options.annotations ?? true;
+	const applyToBackground = (background) => {
+		const content = applyToContent(background.content, rules);
+		const annotation = annotations ? applyToAnnotation(background.annotation, rules) : background.annotation;
+		if (content === background.content && annotation === background.annotation) return background;
+		return {
+			...background,
+			content,
+			annotation
+		};
+	};
+	const lines = mapShared(lyric.lines, (line) => {
+		if (line.type !== LineType.NORMAL) return line;
+		const content = applyToContent(line.content, rules);
+		const annotation = annotations ? applyToAnnotation(line.annotation, rules) : line.annotation;
+		const backgrounds = mapShared(line.backgrounds, applyToBackground);
+		if (content === line.content && annotation === line.annotation && backgrounds === line.backgrounds) return line;
+		return {
+			...line,
+			content,
+			annotation,
+			backgrounds
+		};
+	});
+	return lines === lyric.lines ? lyric : {
+		...lyric,
+		lines
+	};
+};
+//#endregion
+export { INSERT_SPACES_RULES, InsertSpacesRules, deriveWordEmphasis, extractBackgroundLines, insertInstrumentalLines, insertSpacesInLines, stripBackgroundBrackets };
+
+//# sourceMappingURL=transforms.js.map