@gondola-lyrics/kit 0.5.0 → 0.6.0

package/dist/generator.d.ts

@@ -67,7 +67,7 @@ export declare type LrcGenerateResult = LrcContent;
 /**
  * Values match the lowercase format names stored in `Lyric.format`.
  */
-export declare type LyricFormat = 'lrc' | 'qrc' | 'ttml';
+export declare type LyricFormat = 'lrc' | 'qrc' | 'krc' | 'kwrc' | 'yrc' | 'ttml';
 
 export declare interface TtmlGenerateOptions {
     /**

package/dist/index.d.ts

@@ -92,6 +92,7 @@ export declare interface ExtractBackgroundLinesOptions {
 /**
  * Preserves source labels and name spelling while matching normalized credit labels in normal lead lines.
  * Merges names by role and original label without inferring their language.
+ * Unknown metadata is processed only when matchUnknowns is enabled; consumed entries leave the unknown list.
  *
  * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
  */
@@ -99,8 +100,15 @@ export declare const extractCredits: (lyric: runtime.Lyric, options?: ExtractCre
 
 export declare interface ExtractCreditsOptions {
     /**
-     * Removes extracted source lines unless they carry background vocals, line annotations, or word translations or romanizations.
-     * Ruby annotations alone do not prevent removal.
+     * Matches existing unknown metadata keys as credit labels and consumes fully readable matches.
+     * Values use nameSeparators; unrecognized keys and values with no readable names remain unchanged.
+     *
+     * @default false
+     */
+    matchUnknowns?: boolean;
+    /**
+     * Removes successfully extracted source lines together with their backgrounds and annotations.
+     * Extracted roles and names remain in metadata; attached content is not moved to other lines.
      *
      * Refreshes language usages and falls back to line timing when no word-level content remains.
      *
@@ -255,6 +263,16 @@ export declare const InsertSpacesRules: {
     readonly TRIM_INSIDE_SYMBOLS: "trimInsideSymbols";
 };
 
+declare interface KrcContent {
+    original: string;
+}
+
+export declare type KrcParseInput = KrcContent;
+
+export declare interface KwrcParseInput {
+    original: string;
+}
+
 declare interface LrcContent {
     original: string;
     translations?: string;
@@ -310,7 +328,7 @@ export declare interface LrcParseOptions {
 /**
  * Values match the lowercase format names stored in `Lyric.format`.
  */
-export declare type LyricFormat = 'lrc' | 'qrc' | 'ttml';
+export declare type LyricFormat = 'lrc' | 'qrc' | 'krc' | 'kwrc' | 'yrc' | 'ttml';
 
 /**
  * Categories the bundled filter rules identify, in rule order.
@@ -321,7 +339,33 @@ export declare const NON_LYRIC_CATEGORIES: readonly string[];
  * Unrecognized text returns `null`; a recognized format returns its canonical lyric and diagnostics.
  * Annotation tracks travel with the source and are attached by the format's parser.
  */
-export declare const parse: (input: unknown, options?: LrcParseOptions & QrcParseOptions & TtmlParseOptions) => ParseResult | null;
+export declare const parse: (input: unknown, options?: LrcParseOptions & QrcParseOptions & TtmlParseOptions & YrcParseOptions) => ParseResult | null;
+
+/**
+ * Parses decrypted Kugou lyrics, retaining explicit durations and attaching embedded annotations by source slot.
+ *
+ * A source carrying no KRC row is read as LRC, so a platform fallback keeps its container annotations.
+ * Placeholder slots carry no annotation, so they never keep a credit line in the stream.
+ * Kana supplies whole-word ruby; type 0 language tracks retain complete line romanization.
+ * Incomplete metadata remains available in unknowns, and source timing violations remain visible in diagnostics.
+ *
+ * @param input Decrypted plaintext or an object containing its original text.
+ *
+ * @returns Canonical lyrics and model diagnostics; no readable timed rows yields INVALID status.
+ */
+export declare const parseKrc: (input: string | KrcParseInput) => ParseResult;
+
+/**
+ * Parses decoded KWRC with explicit word durations and structurally verified embedded translations.
+ *
+ * Missing or conflicting parameters and unsafe word calculations retain the complete row as line-level text.
+ * Plain LRC remains readable; offset is stored as metadata without changing source timestamps.
+ *
+ * @param input Decoded plaintext or an object containing its original text.
+ *
+ * @returns Canonical lyrics and model diagnostics; no readable timed rows yields INVALID status.
+ */
+export declare const parseKwrc: (input: string | KwrcParseInput) => ParseResult;
 
 /**
  * Empty timed rows become instrumental lines; source order and missing word times remain for model validation.
@@ -360,6 +404,18 @@ export declare interface ParseResult {
  */
 export declare const parseTtml: (input: TtmlParseInput, options?: TtmlParseOptions) => ParseResult;
 
+/**
+ * Parses native YRC or LRC fallback, keeping JSON display rows separate from annotation matching.
+ * Explicit line and word durations remain unchanged, including zero durations and source timing violations.
+ * JSON credit content becomes separate plain-text unknown entries sharing the source label and is omitted from lyric lines.
+ *
+ * @param input Plaintext tracks on the same timeline: yrc with ytlrc/yromalrc, or lrc with tlyric/romalrc.
+ * @param options Independent line and word tolerances, with optional local roman recovery.
+ *
+ * @returns Canonical lyrics and model diagnostics; no readable timed rows yields INVALID status.
+ */
+export declare const parseYrc: (input: string | YrcParseInput, options?: YrcParseOptions) => ParseResult;
+
 declare interface QrcContent {
     original: string;
     translations?: string;
@@ -457,4 +513,36 @@ export declare interface TtmlParseOptions {
 
 export declare type TtmlProfile = 'amll' | 'itunes';
 
+declare interface YrcContent {
+    original: string;
+    translations?: string;
+    romans?: string;
+}
+
+export declare type YrcParseInput = YrcContent;
+
+export declare interface YrcParseOptions {
+    /**
+     * Extra timestamp drift allowed after exact and source-precision matching, in milliseconds.
+     * Tracks must share the original timeline; equal row counts never enable order matching.
+     *
+     * @default 0
+     */
+    annotationTolerance?: number;
+    /**
+     * Maximum roman token drift outside a matched word, in milliseconds; matched boundaries are adjusted to that word.
+     * Original word timing is preserved, and incomplete matches retain the whole line romanization.
+     *
+     * @default 0
+     */
+    wordAnnotationTolerance?: number;
+    /**
+     * Recovers roman fragments from unique two-kana combination starts or equal-sized gaps between timing anchors.
+     * Recovered token times are clipped to their original word; untimed fragments inherit its range.
+     *
+     * @default false
+     */
+    wordAnnotationFallback?: boolean;
+}
+
 export { }

package/dist/index.js

@@ -1,5 +1,5 @@
-import { detectFormat, generate, generateLrc, generateTtml, parse, parseLrc, parseQrc, parseTtml } from "./formats.js";
+import { detectFormat, generate, generateLrc, generateTtml, parse, parseKrc, parseKwrc, parseLrc, parseQrc, parseTtml, parseYrc } from "./formats.js";
 import { DEFAULT_CREDIT_NAME_SEPARATORS, InsertSpacesRules, NON_LYRIC_CATEGORIES, deriveWordEmphasis, extractAgents, extractBackgroundLines, extractCredits, insertInstrumentalLines, insertSpacesInLines, removeNonLyricLines, stripBackgroundBrackets } from "./transforms.js";
 import "./parser.js";
 import "./generator.js";
-export { DEFAULT_CREDIT_NAME_SEPARATORS, InsertSpacesRules, NON_LYRIC_CATEGORIES, deriveWordEmphasis, detectFormat, extractAgents, extractBackgroundLines, extractCredits, generate, generateLrc, generateTtml, insertInstrumentalLines, insertSpacesInLines, parse, parseLrc, parseQrc, parseTtml, removeNonLyricLines, stripBackgroundBrackets };
+export { DEFAULT_CREDIT_NAME_SEPARATORS, InsertSpacesRules, NON_LYRIC_CATEGORIES, deriveWordEmphasis, detectFormat, extractAgents, extractBackgroundLines, extractCredits, generate, generateLrc, generateTtml, insertInstrumentalLines, insertSpacesInLines, parse, parseKrc, parseKwrc, parseLrc, parseQrc, parseTtml, parseYrc, removeNonLyricLines, stripBackgroundBrackets };

package/dist/parser.d.ts

@@ -92,6 +92,7 @@ export declare interface ExtractBackgroundLinesOptions {
 /**
  * Preserves source labels and name spelling while matching normalized credit labels in normal lead lines.
  * Merges names by role and original label without inferring their language.
+ * Unknown metadata is processed only when matchUnknowns is enabled; consumed entries leave the unknown list.
  *
  * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
  */
@@ -99,8 +100,15 @@ export declare const extractCredits: (lyric: runtime.Lyric, options?: ExtractCre
 
 export declare interface ExtractCreditsOptions {
     /**
-     * Removes extracted source lines unless they carry background vocals, line annotations, or word translations or romanizations.
-     * Ruby annotations alone do not prevent removal.
+     * Matches existing unknown metadata keys as credit labels and consumes fully readable matches.
+     * Values use nameSeparators; unrecognized keys and values with no readable names remain unchanged.
+     *
+     * @default false
+     */
+    matchUnknowns?: boolean;
+    /**
+     * Removes successfully extracted source lines together with their backgrounds and annotations.
+     * Extracted roles and names remain in metadata; attached content is not moved to other lines.
      *
      * Refreshes language usages and falls back to line timing when no word-level content remains.
      *
@@ -218,6 +226,16 @@ export declare const InsertSpacesRules: {
     readonly TRIM_INSIDE_SYMBOLS: "trimInsideSymbols";
 };
 
+declare interface KrcContent {
+    original: string;
+}
+
+export declare type KrcParseInput = KrcContent;
+
+export declare interface KwrcParseInput {
+    original: string;
+}
+
 declare interface LrcContent {
     original: string;
     translations?: string;
@@ -252,7 +270,7 @@ export declare interface LrcParseOptions {
 /**
  * Values match the lowercase format names stored in `Lyric.format`.
  */
-export declare type LyricFormat = 'lrc' | 'qrc' | 'ttml';
+export declare type LyricFormat = 'lrc' | 'qrc' | 'krc' | 'kwrc' | 'yrc' | 'ttml';
 
 /**
  * Categories the bundled filter rules identify, in rule order.
@@ -263,7 +281,33 @@ export declare const NON_LYRIC_CATEGORIES: readonly string[];
  * Unrecognized text returns `null`; a recognized format returns its canonical lyric and diagnostics.
  * Annotation tracks travel with the source and are attached by the format's parser.
  */
-export declare const parse: (input: unknown, options?: LrcParseOptions & QrcParseOptions & TtmlParseOptions) => ParseResult | null;
+export declare const parse: (input: unknown, options?: LrcParseOptions & QrcParseOptions & TtmlParseOptions & YrcParseOptions) => ParseResult | null;
+
+/**
+ * Parses decrypted Kugou lyrics, retaining explicit durations and attaching embedded annotations by source slot.
+ *
+ * A source carrying no KRC row is read as LRC, so a platform fallback keeps its container annotations.
+ * Placeholder slots carry no annotation, so they never keep a credit line in the stream.
+ * Kana supplies whole-word ruby; type 0 language tracks retain complete line romanization.
+ * Incomplete metadata remains available in unknowns, and source timing violations remain visible in diagnostics.
+ *
+ * @param input Decrypted plaintext or an object containing its original text.
+ *
+ * @returns Canonical lyrics and model diagnostics; no readable timed rows yields INVALID status.
+ */
+export declare const parseKrc: (input: string | KrcParseInput) => ParseResult;
+
+/**
+ * Parses decoded KWRC with explicit word durations and structurally verified embedded translations.
+ *
+ * Missing or conflicting parameters and unsafe word calculations retain the complete row as line-level text.
+ * Plain LRC remains readable; offset is stored as metadata without changing source timestamps.
+ *
+ * @param input Decoded plaintext or an object containing its original text.
+ *
+ * @returns Canonical lyrics and model diagnostics; no readable timed rows yields INVALID status.
+ */
+export declare const parseKwrc: (input: string | KwrcParseInput) => ParseResult;
 
 /**
  * Empty timed rows become instrumental lines; source order and missing word times remain for model validation.
@@ -302,6 +346,18 @@ export declare interface ParseResult {
  */
 export declare const parseTtml: (input: TtmlParseInput, options?: TtmlParseOptions) => ParseResult;
 
+/**
+ * Parses native YRC or LRC fallback, keeping JSON display rows separate from annotation matching.
+ * Explicit line and word durations remain unchanged, including zero durations and source timing violations.
+ * JSON credit content becomes separate plain-text unknown entries sharing the source label and is omitted from lyric lines.
+ *
+ * @param input Plaintext tracks on the same timeline: yrc with ytlrc/yromalrc, or lrc with tlyric/romalrc.
+ * @param options Independent line and word tolerances, with optional local roman recovery.
+ *
+ * @returns Canonical lyrics and model diagnostics; no readable timed rows yields INVALID status.
+ */
+export declare const parseYrc: (input: string | YrcParseInput, options?: YrcParseOptions) => ParseResult;
+
 declare interface QrcContent {
     original: string;
     translations?: string;
@@ -380,4 +436,36 @@ export declare interface TtmlParseOptions {
 
 export declare type TtmlProfile = 'amll' | 'itunes';
 
+declare interface YrcContent {
+    original: string;
+    translations?: string;
+    romans?: string;
+}
+
+export declare type YrcParseInput = YrcContent;
+
+export declare interface YrcParseOptions {
+    /**
+     * Extra timestamp drift allowed after exact and source-precision matching, in milliseconds.
+     * Tracks must share the original timeline; equal row counts never enable order matching.
+     *
+     * @default 0
+     */
+    annotationTolerance?: number;
+    /**
+     * Maximum roman token drift outside a matched word, in milliseconds; matched boundaries are adjusted to that word.
+     * Original word timing is preserved, and incomplete matches retain the whole line romanization.
+     *
+     * @default 0
+     */
+    wordAnnotationTolerance?: number;
+    /**
+     * Recovers roman fragments from unique two-kana combination starts or equal-sized gaps between timing anchors.
+     * Recovered token times are clipped to their original word; untimed fragments inherit its range.
+     *
+     * @default false
+     */
+    wordAnnotationFallback?: boolean;
+}
+
 export { }

package/dist/parser.js

@@ -1,3 +1,3 @@
-import { detectFormat, parse, parseLrc, parseQrc, parseTtml } from "./formats.js";
+import { detectFormat, parse, parseKrc, parseKwrc, parseLrc, parseQrc, parseTtml, parseYrc } from "./formats.js";
 import { DEFAULT_CREDIT_NAME_SEPARATORS, InsertSpacesRules, NON_LYRIC_CATEGORIES, deriveWordEmphasis, extractAgents, extractBackgroundLines, extractCredits, insertInstrumentalLines, insertSpacesInLines, removeNonLyricLines, stripBackgroundBrackets } from "./transforms.js";
-export { DEFAULT_CREDIT_NAME_SEPARATORS, InsertSpacesRules, NON_LYRIC_CATEGORIES, deriveWordEmphasis, detectFormat, extractAgents, extractBackgroundLines, extractCredits, insertInstrumentalLines, insertSpacesInLines, parse, parseLrc, parseQrc, parseTtml, removeNonLyricLines, stripBackgroundBrackets };
+export { DEFAULT_CREDIT_NAME_SEPARATORS, InsertSpacesRules, NON_LYRIC_CATEGORIES, deriveWordEmphasis, detectFormat, extractAgents, extractBackgroundLines, extractCredits, insertInstrumentalLines, insertSpacesInLines, parse, parseKrc, parseKwrc, parseLrc, parseQrc, parseTtml, parseYrc, removeNonLyricLines, stripBackgroundBrackets };

package/dist/{language.js → rules.js}

@@ -112,6 +112,55 @@ var lowerTag = (tag) => {
 	return tag ? tag.toLowerCase() : void 0;
 };
 //#endregion
-export { mapShared as i, lowerTag as n, lowerBound as r, findScriptRunEnd as t };
+//#region src/utils/rules.ts
+var RULE_WHITESPACE = /[\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]/g;
+var RULE_EDGE_WHITESPACE = /^[\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]+|[\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]+$/g;
+/**
+* Uses the shared whitespace set and ASCII case folding to keep matching consistent across language kits.
+*/
+var toRuleMatchKey = (text) => {
+	return text.replace(RULE_WHITESPACE, "").replace(/[A-Z]+/g, (run) => run.toLowerCase());
+};
+var RULE_WHITESPACE_CHARACTER = new RegExp(RULE_WHITESPACE.source);
+/**
+* Finds the offsets in toRuleMatchKey(text) where the source allows a cut.
+* A cut sits before the first kept character of a script run and after configured whitespace, so neutral punctuation never splits aliases such as A&R or Co-Producer.
+*
+* @param text A source label with its original spelling.
+*
+* @returns Ascending offsets from 0 to the key length, or undefined when the source has no inner cut.
+*/
+var findRuleMatchCuts = (text) => {
+	if (!RULE_WHITESPACE_CHARACTER.test(text) && findScriptRunEnd(text) === text.length) return;
+	const cuts = [0];
+	let length = 0;
+	let pendingCut = false;
+	let runStart = 0;
+	while (runStart < text.length) {
+		const runEnd = findScriptRunEnd(text, runStart);
+		if (runStart > 0) pendingCut = true;
+		for (const character of text.slice(runStart, runEnd)) {
+			if (RULE_WHITESPACE_CHARACTER.test(character)) {
+				pendingCut = true;
+				continue;
+			}
+			if (pendingCut) {
+				if (length > 0) cuts.push(length);
+				pendingCut = false;
+			}
+			length += character.length;
+		}
+		runStart = runEnd;
+	}
+	if (cuts.length === 1) return;
+	cuts.push(length);
+	return cuts;
+};
+/**
+* Preserves internal whitespace so source labels and credited names retain their spelling.
+*/
+var trimRuleWhitespace = (text) => text.replace(RULE_EDGE_WHITESPACE, "");
+//#endregion
+export { lowerBound as a, lowerTag as i, toRuleMatchKey as n, mapShared as o, trimRuleWhitespace as r, findRuleMatchCuts as t };
 
-//# sourceMappingURL=language.js.map
+//# sourceMappingURL=rules.js.map

package/dist/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","names":[],"sources":["../src/utils/array.ts","../src/utils/language.ts","../src/utils/rules.ts"],"sourcesContent":["/**\n * Preserves the input array when every element keeps its identity, so unchanged parent nodes can also be reused.\n *\n * The callback must leave inputs untouched and return the original element when unchanged.\n */\nexport const mapShared = <T>(items: T[], transform: (item: T) => T): T[] => {\n  let result = items\n  for (const [index, item] of items.entries()) {\n    const transformed = transform(item)\n    if (transformed !== item) {\n      if (result === items) {\n        result = [...items]\n      }\n      result[index] = transformed\n    }\n  }\n  return result\n}\n\n/**\n * Finds the first value meeting a lower bound so range queries can skip earlier candidates.\n *\n * @param values Values sorted in ascending order.\n * @param target Inclusive lower bound.\n *\n * @returns The first matching index, or the array length when every value is smaller.\n */\nexport const lowerBound = (values: readonly number[], target: number): number => {\n  let left = 0\n  let right = values.length\n  while (left < right) {\n    const middle = Math.floor((left + right) / 2)\n    if (values[middle]! < target) {\n      left = middle + 1\n    } else {\n      right = middle\n    }\n  }\n  return left\n}\n","const enum ScriptGroup {\n  NEUTRAL,\n  EAST_ASIAN,\n  LATIN,\n  HANGUL,\n  CYRILLIC,\n  GREEK,\n  ARABIC,\n  HEBREW,\n  DEVANAGARI,\n  THAI,\n}\n\nconst SCRIPT_PATTERNS: readonly (readonly [RegExp, ScriptGroup])[] = [\n  [/[\\p{Script=Han}\\p{Script=Hiragana}\\p{Script=Katakana}]/u, ScriptGroup.EAST_ASIAN],\n  [/\\p{Script=Latin}/u, ScriptGroup.LATIN],\n  [/\\p{Script=Hangul}/u, ScriptGroup.HANGUL],\n  [/\\p{Script=Cyrillic}/u, ScriptGroup.CYRILLIC],\n  [/\\p{Script=Greek}/u, ScriptGroup.GREEK],\n  [/\\p{Script=Arabic}/u, ScriptGroup.ARABIC],\n  [/\\p{Script=Hebrew}/u, ScriptGroup.HEBREW],\n  [/\\p{Script=Devanagari}/u, ScriptGroup.DEVANAGARI],\n  [/\\p{Script=Thai}/u, ScriptGroup.THAI],\n]\n\nconst getOtherScript = (text: string, start: number, width: number): ScriptGroup => {\n  const unit = text.charCodeAt(start)\n  if (unit === 0x30fb || unit === 0x30fc) {\n    return ScriptGroup.NEUTRAL\n  }\n  if ((unit >= 0x0400 && unit <= 0x0481) || (unit >= 0x048a && unit <= 0x052f)) {\n    return ScriptGroup.CYRILLIC\n  }\n  if (unit >= 0x03a3 && unit <= 0x03e1) {\n    return ScriptGroup.GREEK\n  }\n  if ((unit >= 0x0620 && unit <= 0x063f) || (unit >= 0x0641 && unit <= 0x064a)) {\n    return ScriptGroup.ARABIC\n  }\n  if (unit >= 0x05d0 && unit <= 0x05ea) {\n    return ScriptGroup.HEBREW\n  }\n  if ((unit >= 0x0900 && unit <= 0x0950) || (unit >= 0x0955 && unit <= 0x0963) || (unit >= 0x0966 && unit <= 0x097f)) {\n    return ScriptGroup.DEVANAGARI\n  }\n  if ((unit >= 0x0e01 && unit <= 0x0e3a) || (unit >= 0x0e40 && unit <= 0x0e5b)) {\n    return ScriptGroup.THAI\n  }\n\n  const character = text.slice(start, start + width)\n  for (const [pattern, script] of SCRIPT_PATTERNS) {\n    if (pattern.test(character)) {\n      return script\n    }\n  }\n  return ScriptGroup.NEUTRAL\n}\n\n/**\n * Finds a boundary between supported scripts without allocating a segment list.\n * Han and kana share a group so Japanese labels stay intact; Hangul, Latin, Cyrillic, Greek, Arabic, Hebrew, Devanagari and Thai remain separate.\n * Punctuation, digits, inherited marks and unsupported scripts stay in the surrounding run.\n *\n * @param start A UTF-16 offset at a code-point boundary, usually the end returned by the previous call.\n *\n * @returns The exclusive UTF-16 end of the run, or text.length when no later boundary exists.\n */\nexport const findScriptRunEnd = (text: string, start = 0): number => {\n  let script = ScriptGroup.NEUTRAL\n  let index = start\n\n  while (index < text.length) {\n    const unit = text.charCodeAt(index)\n    let nextScript = ScriptGroup.NEUTRAL\n    let width = 1\n\n    if (unit <= 0x7f) {\n      const letter = unit | 0x20\n      if (letter >= 0x61 && letter <= 0x7a) {\n        if (script !== ScriptGroup.NEUTRAL && script !== ScriptGroup.LATIN) {\n          return index\n        }\n        script = ScriptGroup.LATIN\n        do {\n          index += 1\n          const nextLetter = text.charCodeAt(index) | 0x20\n          if (nextLetter < 0x61 || nextLetter > 0x7a) {\n            break\n          }\n        } while (index < text.length)\n        continue\n      }\n    } else if (unit >= 0x4e00 && unit <= 0x9fff) {\n      nextScript = ScriptGroup.EAST_ASIAN\n    } else if ((unit >= 0x3041 && unit <= 0x3096) || (unit >= 0x30a1 && unit <= 0x30fa)) {\n      nextScript = ScriptGroup.EAST_ASIAN\n    } else if (unit >= 0xac00 && unit <= 0xd7a3) {\n      nextScript = ScriptGroup.HANGUL\n    } else {\n      width = unit >= 0xd800 && unit <= 0xdbff && text.codePointAt(index)! > 0xffff ? 2 : 1\n      nextScript = getOtherScript(text, index, width)\n    }\n\n    if (nextScript !== ScriptGroup.NEUTRAL) {\n      if (script !== ScriptGroup.NEUTRAL && script !== nextScript) {\n        return index\n      }\n      script = nextScript\n    }\n    index += width\n  }\n  return text.length\n}\n\n/**\n * Returns a language tag in the canonical form the model stores, which is lower case.\n *\n * This mirrors the model's own helper, which it does not export.\n * Comparing tags stays with the consumer, since BCP 47 matches by subtag prefix rather than by string equality.\n */\nexport const lowerTag = (tag: string | undefined): string | undefined => {\n  return tag ? tag.toLowerCase() : undefined\n}\n","import { findScriptRunEnd } from './language'\n\nconst RULE_WHITESPACE = /[\\u0009-\\u000D\\u0020\\u0085\\u00A0\\u1680\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000\\uFEFF]/g\nconst RULE_EDGE_WHITESPACE =\n  /^[\\u0009-\\u000D\\u0020\\u0085\\u00A0\\u1680\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000\\uFEFF]+|[\\u0009-\\u000D\\u0020\\u0085\\u00A0\\u1680\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000\\uFEFF]+$/g\n\n/**\n * Uses the shared whitespace set and ASCII case folding to keep matching consistent across language kits.\n */\nexport const toRuleMatchKey = (text: string): string => {\n  return text.replace(RULE_WHITESPACE, '').replace(/[A-Z]+/g, (run) => run.toLowerCase())\n}\n\nconst RULE_WHITESPACE_CHARACTER = new RegExp(RULE_WHITESPACE.source)\n\n/**\n * Finds the offsets in toRuleMatchKey(text) where the source allows a cut.\n * A cut sits before the first kept character of a script run and after configured whitespace, so neutral punctuation never splits aliases such as A&R or Co-Producer.\n *\n * @param text A source label with its original spelling.\n *\n * @returns Ascending offsets from 0 to the key length, or undefined when the source has no inner cut.\n */\nexport const findRuleMatchCuts = (text: string): readonly number[] | undefined => {\n  // Most labels are a single script run without inner whitespace, so they skip the character walk.\n  if (!RULE_WHITESPACE_CHARACTER.test(text) && findScriptRunEnd(text) === text.length) {\n    return undefined\n  }\n\n  const cuts: number[] = [0]\n  let length = 0\n  let pendingCut = false\n  let runStart = 0\n  while (runStart < text.length) {\n    const runEnd = findScriptRunEnd(text, runStart)\n    if (runStart > 0) {\n      pendingCut = true\n    }\n    for (const character of text.slice(runStart, runEnd)) {\n      if (RULE_WHITESPACE_CHARACTER.test(character)) {\n        pendingCut = true\n        continue\n      }\n      if (pendingCut) {\n        if (length > 0) {\n          cuts.push(length)\n        }\n        pendingCut = false\n      }\n      length += character.length\n    }\n    runStart = runEnd\n  }\n  if (cuts.length === 1) {\n    return undefined\n  }\n  cuts.push(length)\n  return cuts\n}\n\n/**\n * Preserves internal whitespace so source labels and credited names retain their spelling.\n */\nexport const trimRuleWhitespace = (text: string): string => text.replace(RULE_EDGE_WHITESPACE, '')\n"],"mappings":"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"}

package/dist/transforms.d.ts

@@ -84,6 +84,7 @@ export declare interface ExtractBackgroundLinesOptions {
 /**
  * Preserves source labels and name spelling while matching normalized credit labels in normal lead lines.
  * Merges names by role and original label without inferring their language.
+ * Unknown metadata is processed only when matchUnknowns is enabled; consumed entries leave the unknown list.
  *
  * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
  */
@@ -91,8 +92,15 @@ export declare const extractCredits: (lyric: runtime.Lyric, options?: ExtractCre
 
 export declare interface ExtractCreditsOptions {
     /**
-     * Removes extracted source lines unless they carry background vocals, line annotations, or word translations or romanizations.
-     * Ruby annotations alone do not prevent removal.
+     * Matches existing unknown metadata keys as credit labels and consumes fully readable matches.
+     * Values use nameSeparators; unrecognized keys and values with no readable names remain unchanged.
+     *
+     * @default false
+     */
+    matchUnknowns?: boolean;
+    /**
+     * Removes successfully extracted source lines together with their backgrounds and annotations.
+     * Extracted roles and names remain in metadata; attached content is not moved to other lines.
      *
      * Refreshes language usages and falls back to line timing when no word-level content remains.
      *

package/dist/transforms.js

@@ -1,54 +1,5 @@
-import { i as mapShared, t as findScriptRunEnd } from "./language.js";
+import { n as toRuleMatchKey, o as mapShared, r as trimRuleWhitespace, t as findRuleMatchCuts } from "./rules.js";
 import { AgentType, CreditRole, LineType, Timing, WordType, deriveLanguageUsages, getContentText, isWordLevelLine, makeAgent, makeLineAnnotation, makeLineAnnotationRoman, makeLineAnnotationTranslation, makeLineBackground, makeLineContentText, makeLineContentWords, makeLineInstrumental, makeMeta, makeMetaCredit, makeText, makeTimeRange, makeWordEmphasis, makeWordSpace, validateTimeRange } from "@gondola-lyrics/model/runtime";
-//#region src/utils/rules.ts
-var RULE_WHITESPACE = /[\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]/g;
-var RULE_EDGE_WHITESPACE = /^[\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]+|[\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]+$/g;
-/**
-* Uses the shared whitespace set and ASCII case folding to keep matching consistent across language kits.
-*/
-var toRuleMatchKey = (text) => {
-	return text.replace(RULE_WHITESPACE, "").replace(/[A-Z]+/g, (run) => run.toLowerCase());
-};
-var RULE_WHITESPACE_CHARACTER = new RegExp(RULE_WHITESPACE.source);
-/**
-* Finds the offsets in toRuleMatchKey(text) where the source allows a cut.
-* A cut sits before the first kept character of a script run and after configured whitespace, so neutral punctuation never splits aliases such as A&R or Co-Producer.
-*
-* @param text A source label with its original spelling.
-*
-* @returns Ascending offsets from 0 to the key length, or undefined when the source has no inner cut.
-*/
-var findRuleMatchCuts = (text) => {
-	if (!RULE_WHITESPACE_CHARACTER.test(text) && findScriptRunEnd(text) === text.length) return;
-	const cuts = [0];
-	let length = 0;
-	let pendingCut = false;
-	let runStart = 0;
-	while (runStart < text.length) {
-		const runEnd = findScriptRunEnd(text, runStart);
-		if (runStart > 0) pendingCut = true;
-		for (const character of text.slice(runStart, runEnd)) {
-			if (RULE_WHITESPACE_CHARACTER.test(character)) {
-				pendingCut = true;
-				continue;
-			}
-			if (pendingCut) {
-				if (length > 0) cuts.push(length);
-				pendingCut = false;
-			}
-			length += character.length;
-		}
-		runStart = runEnd;
-	}
-	if (cuts.length === 1) return;
-	cuts.push(length);
-	return cuts;
-};
-/**
-* Preserves internal whitespace so source labels and credited names retain their spelling.
-*/
-var trimRuleWhitespace = (text) => text.replace(RULE_EDGE_WHITESPACE, "");
-//#endregion
 //#region src/transforms/agent/extract.ts
 var hashName = (name) => {
 	let hash = 0;
@@ -2460,19 +2411,13 @@ var readCreditNames = (text, separators) => {
 	}
 	return [...unique];
 };
-var canRemoveSourceLine = (line) => {
-	if (line.backgrounds.length || line.annotation) return false;
-	return !line.content?.words.some(({ annotation }) => {
-		if (!annotation) return false;
-		return !!(annotation.translations.length || annotation.romans.length);
-	});
-};
 var hasCreditColon = (word) => {
 	return word.text.includes(":") || word.text.includes("：");
 };
 /**
 * Preserves source labels and name spelling while matching normalized credit labels in normal lead lines.
 * Merges names by role and original label without inferring their language.
+* Unknown metadata is processed only when matchUnknowns is enabled; consumed entries leave the unknown list.
 *
 * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
 */
@@ -2481,32 +2426,9 @@ var extractCredits = (lyric, options = {}) => {
 	const originalCredits = lyric.meta?.credits ?? [];
 	let credits = originalCredits;
 	let creditIndex;
-	const originalLines = lyric.lines;
-	let remainingLines;
-	for (let index = 0; index < originalLines.length; index += 1) {
-		const line = originalLines[index];
-		if (line.type !== LineType.NORMAL) {
-			remainingLines?.push(line);
-			continue;
-		}
-		const content = line.content;
-		if (!(content?.text !== void 0 || (content?.words.some(hasCreditColon) ?? false))) {
-			remainingLines?.push(line);
-			continue;
-		}
-		const text = getContentText(content);
-		const colon = text.search(/[:：]/);
-		if (colon === -1) {
-			remainingLines?.push(line);
-			continue;
-		}
-		const raw = trimRuleWhitespace(text.slice(0, colon));
+	const appendCredit = (raw, names) => {
 		const roles = matchCreditLabel(raw);
-		const names = roles ? readCreditNames(text.slice(colon + 1), separators) : [];
-		if (!roles || !names.length) {
-			remainingLines?.push(line);
-			continue;
-		}
+		if (!roles || !names.length) return false;
 		creditIndex ??= createCreditIndex(originalCredits);
 		let entries = creditIndex.get(raw);
 		if (!entries) {
@@ -2539,10 +2461,44 @@ var extractCredits = (lyric, options = {}) => {
 			}
 			for (const name of additions) entry.names.add(name);
 		}
-		if (options.removeSourceLines && canRemoveSourceLine(line)) remainingLines ??= originalLines.slice(0, index);
+		return true;
+	};
+	const originalUnknowns = lyric.meta?.unknowns ?? [];
+	let unknowns = originalUnknowns;
+	if (options.matchUnknowns) for (const [index, entry] of originalUnknowns.entries()) {
+		const raw = trimRuleWhitespace(entry.key);
+		if (appendCredit(raw, matchCreditLabel(raw) ? readCreditNames(entry.value, separators) : [])) {
+			if (unknowns === originalUnknowns) unknowns = originalUnknowns.slice(0, index);
+		} else if (unknowns !== originalUnknowns) unknowns.push(entry);
+	}
+	const originalLines = lyric.lines;
+	let remainingLines;
+	for (let index = 0; index < originalLines.length; index += 1) {
+		const line = originalLines[index];
+		if (line.type !== LineType.NORMAL) {
+			remainingLines?.push(line);
+			continue;
+		}
+		const content = line.content;
+		if (!(content?.text !== void 0 || (content?.words.some(hasCreditColon) ?? false))) {
+			remainingLines?.push(line);
+			continue;
+		}
+		const text = getContentText(content);
+		const colon = text.search(/[:：]/);
+		if (colon === -1) {
+			remainingLines?.push(line);
+			continue;
+		}
+		const raw = trimRuleWhitespace(text.slice(0, colon));
+		if (!appendCredit(raw, matchCreditLabel(raw) ? readCreditNames(text.slice(colon + 1), separators) : [])) {
+			remainingLines?.push(line);
+			continue;
+		}
+		if (options.removeSourceLines) remainingLines ??= originalLines.slice(0, index);
 		else remainingLines?.push(line);
 	}
-	if (credits === originalCredits && !remainingLines) return lyric;
+	if (credits === originalCredits && unknowns === originalUnknowns && !remainingLines) return lyric;
 	const removed = !!remainingLines;
 	const lines = remainingLines ?? originalLines;
 	let timing = lyric.timing;
@@ -2551,10 +2507,14 @@ var extractCredits = (lyric, options = {}) => {
 			return isWordLevelLine(line) || line.backgrounds.some(isWordLevelLine);
 		})) timing = Timing.LINE;
 	}
-	const meta = credits === originalCredits ? lyric.meta : lyric.meta ? {
+	const meta = credits === originalCredits && unknowns === originalUnknowns ? lyric.meta : lyric.meta ? {
 		...lyric.meta,
-		credits
-	} : makeMeta({ credits });
+		credits,
+		unknowns
+	} : makeMeta({
+		credits,
+		unknowns
+	});
 	return {
 		...lyric,
 		meta,