@ihabdevteam/core 0.8.0

package/dist/packages/core/src/utils/wordTrainingGenerators.js

@@ -0,0 +1,560 @@
+/**
+ * 단어훈련 문제생성 **공유 코어** (F19 통합).
+ * 편집기 미리보기(WordTrainingTypePreview)와 러너/런타임(wordTrainingRuntime)이
+ * 각자 중복 구현하던 "대립쌍 오답 생성" 규칙을 단일 출처로 모은다.
+ *
+ * 순수 함수만 둔다 — 오디오코드/id/async/이미지체크는 각 소비처 어댑터 책임.
+ * 발음 조회는 pronMap(단어→표준발음)을 인자로 받는다(런타임은 getPronMap(), 편집기는 자체 Map 주입).
+ */
+import { parseSyllable, composeSyllable, CHOSEONG, JUNGSEONG, JONGSEONG } from './koreanSyllable';
+import { finalToPhoneme } from './phonemeConvert';
+import { shuffle as shuffled } from './array';
+import { hasSel } from './wordContrast';
+import { cardGroupOf } from './wordTrainingRuntimeTypes';
+/** 받침 유무로 '와/과' 조사. 한글 아니면 '와'. */
+function josaWaGwa(w) {
+    const code = (w.charCodeAt((w.length || 1) - 1)) || 0;
+    if (code < 0xAC00 || code > 0xD7A3)
+        return '와';
+    return (code - 0xAC00) % 28 === 0 ? '와' : '과';
+}
+/** 받침 유무로 '을/를' 조사. 한글 아니면 '를'. */
+function josaEulReul(w) {
+    const code = (w.charCodeAt((w.length || 1) - 1)) || 0;
+    if (code < 0xAC00 || code > 0xD7A3)
+        return '를';
+    return (code - 0xAC00) % 28 === 0 ? '를' : '을';
+}
+/** 받침에 따라 '으로/로' 조사. 받침 없음 또는 ㄹ받침이면 '로', 그 외 '으로'. 한글 아니면 '로'. */
+function josaEuRo(w) {
+    const code = (w.charCodeAt((w.length || 1) - 1)) || 0;
+    if (code < 0xAC00 || code > 0xD7A3)
+        return '로';
+    const jong = (code - 0xAC00) % 28;
+    return (jong === 0 || jong === 8) ? '로' : '으로';
+}
+/** 받침 유무로 '이/가' 조사. 자음 자모(ㄱ 등)는 낱자 이름이 받침으로 끝나므로 '이'. 그 외 비한글은 '가'. */
+function josaIga(w) {
+    const ch = w.charAt((w.length || 1) - 1);
+    const code = ch.charCodeAt(0) || 0;
+    if (code >= 0xAC00 && code <= 0xD7A3)
+        return (code - 0xAC00) % 28 === 0 ? '가' : '이';
+    return /[ㄱ-ㅎ]/.test(ch) ? '이' : '가';
+}
+/**
+ * 자모 → 낱자 이름(TTS가 음소를 정확히 읽도록). 자음은 명칭(ㄱ→기역), 모음은 소릿값(ㅏ→아).
+ * bare 자모('ㄱ')를 그대로 TTS에 넣으면 엔진이 '그/가'처럼 잘못 읽어, 음소 합치기 문장에서 이름으로 치환한다.
+ */
+const JAMO_NAME = {
+    // 자음(초성·종성 공용 낱자 이름)
+    'ㄱ': '기역', 'ㄲ': '쌍기역', 'ㄴ': '니은', 'ㄷ': '디귿', 'ㄸ': '쌍디귿', 'ㄹ': '리을',
+    'ㅁ': '미음', 'ㅂ': '비읍', 'ㅃ': '쌍비읍', 'ㅅ': '시옷', 'ㅆ': '쌍시옷', 'ㅇ': '이응',
+    'ㅈ': '지읒', 'ㅉ': '쌍지읒', 'ㅊ': '치읓', 'ㅋ': '키읔', 'ㅌ': '티읕', 'ㅍ': '피읖', 'ㅎ': '히읗',
+    // 겹받침(홑받침만 쓰지만 방어적으로 포함)
+    'ㄳ': '기역시옷', 'ㄵ': '니은지읒', 'ㄶ': '니은히읗', 'ㄺ': '리을기역', 'ㄻ': '리을미음',
+    'ㄼ': '리을비읍', 'ㄽ': '리을시옷', 'ㄾ': '리을티읕', 'ㄿ': '리을피읖', 'ㅀ': '리을히읗', 'ㅄ': '비읍시옷',
+    // 모음(소릿값 = 낱자 이름)
+    'ㅏ': '아', 'ㅐ': '애', 'ㅑ': '야', 'ㅒ': '얘', 'ㅓ': '어', 'ㅔ': '에', 'ㅕ': '여', 'ㅖ': '예',
+    'ㅗ': '오', 'ㅘ': '와', 'ㅙ': '왜', 'ㅚ': '외', 'ㅛ': '요', 'ㅜ': '우', 'ㅝ': '워', 'ㅞ': '웨',
+    'ㅟ': '위', 'ㅠ': '유', 'ㅡ': '으', 'ㅢ': '의', 'ㅣ': '이',
+};
+/**
+ * @public 1음절 단어를 합치기용 음소(초성 자음 + 중성 모음 [+ 종성])로 분해. 음소 합치기 문제용.
+ * 예: '가' → ['ㄱ','ㅏ'], '강' → ['ㄱ','ㅏ','ㅇ']. 파싱 실패 시 [word].
+ */
+export function phonemePartsOf(word) {
+    // parseSyllable 은 첫 글자만 본다. 길이를 안 재면 '가방'이 조용히 ['ㄱ','ㅏ'] 가 돼
+    // 둘째 음절이 사라진 채 문제가 만들어진다 — 계약대로 1음절이 아니면 통째로 돌려준다.
+    if ([...word].length !== 1)
+        return [word];
+    const s = parseSyllable(word);
+    if (!s)
+        return [word];
+    const parts = [CHOSEONG[s.cho], JUNGSEONG[s.jung]];
+    if (s.jong !== 0)
+        parts.push(JONGSEONG[s.jong]);
+    return parts;
+}
+/**
+ * @public 합치기 문제 **표시** 문장 — 미리보기·러너 공용. 음절/음소 모두 원문(자모는 자모 그대로: 'ㄱ','ㅏ')로 표시한다.
+ * TTS로 읽을 땐 자모를 낱자 이름으로 바꿔야 하지만(그건 jamoToNamesForSpeech가 합성 경로에서 처리), 화면 표기는 자모 유지.
+ * 예: ['아','냐'] → `"아"와 "냐"를 합치면 어떤 단어가 되나요?` / ['ㄱ','ㅏ'] → `"ㄱ"와 "ㅏ"를 합치면 어떤 소리가 되나요?`
+ */
+export function mergeQuestionText(parts, phoneme = false) {
+    const p = parts.filter(Boolean);
+    if (p.length < 2)
+        return '';
+    // 글자는 자모 그대로 표시하되, 조사는 '읽는 형태'(자모면 낱자 이름)의 받침 기준으로 붙인다.
+    // 예: 'ㄸ'는 화면엔 'ㄸ'로 두되 조사는 '쌍디귿' 기준 → "ㄸ"과. 'ㅇ' → 이응 → "ㅇ"을.
+    const josaBase = (x) => JAMO_NAME[x] ?? x;
+    const head = p.slice(0, -1).map(x => `"${x}"${josaWaGwa(josaBase(x))}`).join(' ');
+    const lastWord = p[p.length - 1];
+    const last = `"${lastWord}"${josaEulReul(josaBase(lastWord))}`;
+    return `${head} ${last} 합치면 어떤 ${phoneme ? '소리' : '단어'}가 되나요?`;
+}
+/**
+ * @public 합치기 카드 질문 문장 — 러너(재생)·프리워밍 공용 단일 출처. typeKey로 음소 여부를 판별해 mergeQuestionText 호출.
+ */
+export function getMergeCardTitle(typeKey, parts) {
+    return mergeQuestionText(parts, typeKey === 'MERGE_2_PHONEMES' || typeKey === 'MERGE_3_PHONEMES');
+}
+/**
+ * @public 바꾸기(대치) 카드 질문 문장 — 러너·프리워밍 공용. item의 word/changedFrom/changedTo로 구성.
+ * 프리워밍이 만든 문장이 러너 재생 문장과 문자 단위로 같아야 캐시 키가 일치하므로 반드시 이 함수를 공유한다.
+ */
+export function getChangeCardTitle(typeKey, item) {
+    const word = String(item?.word ?? item?.original ?? '');
+    const changedFrom = String(item?.changedFrom ?? '');
+    const changedTo = String(item?.changedTo ?? '');
+    if (typeKey === 'CHANGE_1_PHONEME_IN_1SYLL') {
+        // 1음절 단어 전체가 바뀌는 케이스 — "에서 X를" 없이 단순 표현
+        return `"${word}"${josaEulReul(word)} "${changedTo}"${josaEuRo(changedTo)} 바꾸면 무엇이 되나요?`;
+    }
+    return `"${word}"에서 "${changedFrom}"${josaEulReul(changedFrom)} "${changedTo}"${josaEuRo(changedTo)} 바꾸면 무엇이 되나요?`;
+}
+/**
+ * @public 탈락(삭제) 카드 질문 문장 — 러너·프리워밍 공용. item의 word/dropped/missingConsonant로 구성.
+ */
+export function getDropCardTitle(typeKey, item) {
+    const word = String(item?.word ?? item?.original ?? item?.base ?? '');
+    const dropped = String(item?.dropped ?? '');
+    if (typeKey === 'DROP_FINAL_CONSONANT_FROM_1SYLL') {
+        return `"${word}"에서 받침이 없어지면 어떤 말이 되나요?`;
+    }
+    if (typeKey === 'REMOVE_CONSONANT_AND_IDENTIFY_PHONEME') {
+        const consonant = String(item?.missingConsonant ?? '');
+        return `"${word}"에서 "${consonant}"${josaIga(consonant)} 없어지면 어떤 소리가 되나요?`;
+    }
+    return `"${word}"에서 "${dropped}"${josaIga(dropped)} 없어지면 어떤 말이 되나요?`;
+}
+/**
+ * @public 카드형(합치기/바꾸기/탈락) 질문 문장을 반환한다. 카드형이 아니면 '' (빈 문자열).
+ * 러너(WordManipulationTrainingPagePopup.getCardStepMeta)와 프리워밍(앱)의 **단일 출처** — 그룹 판정(cardGroupOf)과
+ * 문장 문구를 한 곳에 모아, 프리워밍이 만든 문장과 러너가 재생하는 문장이 항상 문자 단위로 일치하게 한다.
+ */
+export function cardQuestionTitle(typeKey, item, parts) {
+    switch (cardGroupOf(typeKey)) {
+        case 'synthesis': return getMergeCardTitle(typeKey, parts);
+        case 'substitution': return getChangeCardTitle(typeKey, item);
+        case 'deletion': return getDropCardTitle(typeKey, item);
+        default: return '';
+    }
+}
+/**
+ * @public TTS 전용 변환 — 문장 속 따옴표로 감싼 낱개 자모("ㄱ")를 낱자 이름("기역")으로 치환하고 뒤 조사를 맞춘다.
+ * 표시 텍스트는 자모 그대로 두고(교육용 표기), 합성·캐시 키에만 이 변환을 적용한다. 자음은 명칭(ㄱ→기역),
+ * 모음은 소릿값(ㅏ→아). 음소 합치기뿐 아니라 음소 바꾸기·자음 탈락 등 자모가 든 모든 문장에 공통 적용된다.
+ */
+export function jamoToNamesForSpeech(text) {
+    return text.replace(/"([ㄱ-ㅣ])"(으로|와|과|을|를|이|가|은|는|로)?/g, (m, jamo, josa) => {
+        const name = JAMO_NAME[jamo];
+        if (!name)
+            return m;
+        if (!josa)
+            return `"${name}"`;
+        const jong = (name.charCodeAt(name.length - 1) - 0xAC00) % 28;
+        const hasJong = jong !== 0;
+        let j = josa;
+        if (josa === '와' || josa === '과')
+            j = hasJong ? '과' : '와';
+        else if (josa === '을' || josa === '를')
+            j = hasJong ? '을' : '를';
+        else if (josa === '이' || josa === '가')
+            j = hasJong ? '이' : '가';
+        else if (josa === '은' || josa === '는')
+            j = hasJong ? '은' : '는';
+        else if (josa === '으로' || josa === '로')
+            j = (jong === 0 || jong === 8) ? '로' : '으로';
+        return `"${name}"${j}`;
+    });
+}
+/** 표준발음 조회 — 없으면 단어 자체(발음 데이터 없는 경우의 안전한 폴백). */
+function pronOf(word, pronMap) {
+    return pronMap.get(word) || word;
+}
+const asArr = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+/**
+ * @public 음절 끝소리 규칙 — 종성을 7종성(ㄱㄴㄷㄹㅁㅂㅇ)으로 중화한 '표준발음' 음절.
+ * 합성 음절(대립쌍 오답)은 pronMap에 없어 발음이 비므로 단일 음절 발음을 계산해 채운다.
+ * (초성 그대로, 종성만 중화. 겹받침은 대표음. 단일 음절이 아니면 '' — 다음절 단어를 잘못 자르지 않게.)
+ */
+export function syllablePron(ch) {
+    if ([...ch].length !== 1)
+        return '';
+    const s = parseSyllable(ch);
+    if (!s)
+        return '';
+    const neut = finalToPhoneme(JONGSEONG[s.jong]);
+    const jongIdx = neut === '' ? 0 : JONGSEONG.indexOf(neut);
+    return composeSyllable(s.cho, s.jung, jongIdx < 0 ? 0 : jongIdx);
+}
+/**
+ * @public 음절의 실제 소리(표준발음). pronMap에 있으면 그것, 없으면(합성 음절) 끝소리 규칙 발음, 그래도 없으면 철자.
+ * (예: '밡'·'밖'은 모두 [박] — 소리 기준 중복 판정에 쓴다.)
+ */
+export function soundOf(syll, pronMap) {
+    return pronMap.get(syll) || syllablePron(syll) || syll;
+}
+/** @public comp에서 실제로 선택된 파트 1개(초성 우선)를 반환. 없으면 null. */
+export function primarySelPart(comp) {
+    if (!comp)
+        return null;
+    if (hasSel(comp.cho))
+        return 'cho';
+    if (hasSel(comp.jung))
+        return 'jung';
+    if (hasSel(comp.jong))
+        return 'jong';
+    return null;
+}
+/** @public 음절(분해값 s)이 comp의 선택 파트들과 모두 일치하는지(=선택 음소를 가진 음절). */
+export function syllMatchesComp(s, comp) {
+    const ok = (arr, val) => !hasSel(arr) || asArr(arr).includes(val);
+    return ok(comp.cho, CHOSEONG[s.cho]) && ok(comp.jung, JUNGSEONG[s.jung]) && ok(comp.jong, JONGSEONG[s.jong]);
+}
+/**
+ * @public 발음 모드에서 comp 매칭에 쓸 음절 배열. 표준발음(pronMap)의 음절수가 철자와 같으면 발음 음절로,
+ * 아니면(연음 등으로 정렬 불가) 철자 음절로 매칭한다. 대립 오답 생성은 항상 철자 기준(소리로 중복제거).
+ */
+export function matchSyllables(word, pronMap, phonemeView) {
+    const chars = [...word];
+    if (phonemeView !== 'pron')
+        return chars.map(c => parseSyllable(c));
+    const pronChars = [...(pronMap.get(word) || word)];
+    if (pronChars.length !== chars.length)
+        return chars.map(c => parseSyllable(c));
+    return pronChars.map(c => parseSyllable(c));
+}
+/**
+ * @public 정답 음절(분해 cs)의 지정 파트를 다른 음소로 바꿔 대립쌍 음절 n개 생성.
+ * 중복 배제는 '실제 발음(soundOf)' 기준 — 소리가 같은 오답(밡/밖→박)이 함께 나오지 않게 한다.
+ */
+export function syllableContrasts(cs, part, correct, n, pronMap) {
+    const arr = part === 'cho' ? CHOSEONG : part === 'jung' ? JUNGSEONG : JONGSEONG;
+    const cur = cs[part];
+    const out = [];
+    const usedSound = new Set([soundOf(correct, pronMap)]);
+    const idxs = shuffled(arr.map((_, i) => i).filter(i => i !== cur
+        && (part !== 'cho' || arr[i] !== 'ㅇ') // 초성 대립은 무음(ㅇ) 제외 — 구조가 바뀜
+        && (part !== 'jong' || i !== 0))); // 종성 대립은 '받침 없음'(0) 제외 — 구조가 바뀜
+    for (const idx of idxs) {
+        if (out.length >= n)
+            break;
+        const syll = part === 'cho' ? composeSyllable(idx, cs.jung, cs.jong)
+            : part === 'jung' ? composeSyllable(cs.cho, idx, cs.jong)
+                : composeSyllable(cs.cho, cs.jung, idx);
+        const p = soundOf(syll, pronMap);
+        if (usedSound.has(p))
+            continue;
+        usedSound.add(p);
+        out.push(syll);
+    }
+    return out;
+}
+/**
+ * @public 2음절 단어 → [문제단어, 남는 1음절(정답), 대립쌍 오답 2]. 정답·오답 모두 '실단어'(wordSet)만 인정.
+ * 음소가 든 음절(T)을 남기고 다른 음절 탈락 → 남는 1음절이 실단어이고, 그 음절의 초성/중성/종성 대립 실단어가
+ * 2개 이상인 경우만 채택. 음소 미선택 시 무작위 음절. (편집기 미리보기·런타임 자동생성 공용.)
+ */
+export function buildDropContrastProblem(word, comp, pronMap, phonemeView, wordSet, dropPos = null) {
+    const chars = [...word];
+    if (chars.length !== 2)
+        return null;
+    const spellSS = chars.map(c => parseSyllable(c));
+    if (spellSS.some(p => !p))
+        return null;
+    const matchSS = matchSyllables(word, pronMap, phonemeView);
+    if (matchSS.some(p => !p))
+        return null;
+    const part = primarySelPart(comp);
+    let tCandidates = (part && comp)
+        ? matchSS.map((s, i) => (syllMatchesComp(s, comp) ? i : -1)).filter(i => i >= 0)
+        : [0, 1];
+    // 위치(탈락시킬 음절) 지정 시 남는 음절(T)은 그 자리가 아니어야 한다.
+    if (dropPos != null)
+        tCandidates = tCandidates.filter(i => i !== dropPos);
+    if (!tCandidates.length)
+        return null;
+    for (const tIdx of shuffled(tCandidates)) {
+        const remain = chars[tIdx]; // T가 아닌 음절 탈락 → 남는 1음절 = T
+        if (!wordSet.has(remain))
+            continue;
+        const contrastSylls = syllableContrasts(spellSS[tIdx], part ?? 'cho', remain, 40, pronMap);
+        const wrongs = [];
+        for (const cs of contrastSylls) {
+            if (cs !== remain && wordSet.has(cs) && !wrongs.includes(cs))
+                wrongs.push(cs);
+            if (wrongs.length >= 2)
+                break;
+        }
+        if (wrongs.length < 2)
+            continue;
+        return { question: word, distractors: [remain, ...wrongs] };
+    }
+    return null;
+}
+/**
+ * @public 3음절 단어 → [문제단어, 남는 2음절(정답), 대립쌍 오답 2]. 정답·오답 모두 '실단어'만 인정.
+ * 음소가 든 음절(T)은 남기고 나머지 중 1개를 탈락시켜 2음절 정답을 만든 뒤, 정답 안 T 음절의 지정 파트만
+ * 바꿔 2음절 오답을 만든다. 음소 미선택 시 무작위. (편집기·런타임 공용.)
+ */
+export function buildDropContrast3Problem(word, comp, pronMap, phonemeView, wordSet, dropPos = null) {
+    const chars = [...word];
+    if (chars.length !== 3)
+        return null;
+    const spellSS = chars.map(c => parseSyllable(c));
+    if (spellSS.some(p => !p))
+        return null;
+    const matchSS = matchSyllables(word, pronMap, phonemeView);
+    if (matchSS.some(p => !p))
+        return null;
+    const part = primarySelPart(comp);
+    const tCandidates = (part && comp)
+        ? matchSS.map((s, i) => (syllMatchesComp(s, comp) ? i : -1)).filter(i => i >= 0)
+        : [0, 1, 2];
+    if (!tCandidates.length)
+        return null;
+    for (const tIdx of shuffled(tCandidates)) {
+        for (const dropIdx of shuffled([0, 1, 2].filter(i => i !== tIdx && (dropPos == null || i === dropPos)))) {
+            const answerIdxs = [0, 1, 2].filter(i => i !== dropIdx);
+            const remain = answerIdxs.map(i => chars[i]).join('');
+            if (!wordSet.has(remain))
+                continue;
+            const tPos = answerIdxs.indexOf(tIdx);
+            const contrastSylls = syllableContrasts(spellSS[tIdx], part ?? 'cho', chars[tIdx], 40, pronMap);
+            const wrongs = [];
+            for (const cs of contrastSylls) {
+                const a = answerIdxs.map(i => chars[i]);
+                a[tPos] = cs;
+                const w = a.join('');
+                if (w !== remain && wordSet.has(w) && !wrongs.includes(w))
+                    wrongs.push(w);
+                if (wrongs.length >= 2)
+                    break;
+            }
+            if (wrongs.length < 2)
+                continue;
+            return { question: word, distractors: [remain, ...wrongs] };
+        }
+    }
+    return null;
+}
+/**
+ * @public 합성어 부분 탈락 → [문제단어(합성어), 남는 실단어(정답), 그 단어의 대립쌍 실단어 오답 2].
+ * 합성어 근사: 앞/뒤로 나눈 두 조각이 '둘 다 실단어'(wordSet)인 첫 조합을 채택(예: 손수건=손+수건).
+ * 정답·오답 전부 실단어라 발음이 그대로. comp(훈련음소) 지정 시 남는 단어의 그 자리를 대립, 없으면 전 음절.
+ * dropPos: 0=어두 어근(앞) 탈락, 1=어말 어근(뒤) 탈락. 편집기·런타임 공용.
+ */
+export function buildDropCompoundProblem(word, comp, pronMap, phonemeView, wordSet, dropPos = null) {
+    const chars = [...word];
+    const n = chars.length;
+    if (n < 2)
+        return null;
+    const candidates = [];
+    for (let len = 1; len <= n - 1; len++) {
+        candidates.push({ remain: chars.slice(0, len).join(''), dropped: chars.slice(len).join(''), droppedEnd: 1 }); // 접두 남김, 뒤(어말) 탈락
+        candidates.push({ remain: chars.slice(n - len).join(''), dropped: chars.slice(0, n - len).join(''), droppedEnd: 0 }); // 접미 남김, 앞(어두) 탈락
+    }
+    const part = primarySelPart(comp);
+    for (const { remain, dropped, droppedEnd } of shuffled(candidates)) {
+        if (dropPos != null && droppedEnd !== dropPos)
+            continue; // 위치(삭제할 어근) 지정 시 그 끝만.
+        if (remain === word || !wordSet.has(remain) || !wordSet.has(dropped))
+            continue;
+        const rChars = [...remain];
+        const spellSS = rChars.map(c => parseSyllable(c));
+        if (spellSS.some(p => !p))
+            continue;
+        const matchSS = matchSyllables(remain, pronMap, phonemeView);
+        if (matchSS.some(p => !p))
+            continue;
+        const tCandidates = (part && comp)
+            ? matchSS.map((s, i) => (syllMatchesComp(s, comp) ? i : -1)).filter(i => i >= 0)
+            : rChars.map((_, i) => i);
+        if (!tCandidates.length)
+            continue;
+        for (const tIdx of shuffled(tCandidates)) {
+            const contrastSylls = syllableContrasts(spellSS[tIdx], part ?? 'cho', rChars[tIdx], 40, pronMap);
+            const wrongs = [];
+            for (const cs of contrastSylls) {
+                const a = [...rChars];
+                a[tIdx] = cs;
+                const w = a.join('');
+                if (w !== remain && wordSet.has(w) && !wrongs.includes(w))
+                    wrongs.push(w);
+                if (wrongs.length >= 2)
+                    break;
+            }
+            if (wrongs.length >= 2)
+                return { question: word, distractors: [remain, ...wrongs] };
+        }
+    }
+    return null;
+}
+/**
+ * @public 1음절 받침 탈락 → [문제단어, 받침 뗀 음절(정답), 초성 대립 오답 2]. 받침 있는 1음절만.
+ *
+ * 정답 음절은 표준발음에서 만든다 — '넷(낻)'의 받침을 떼면 들리는 소리는 '네'가 아니라 '내'다.
+ * (1음절 단어는 고립형이라 문맥에 따른 변동이 없어, 표준발음이 곧 실제로 들리는 소리다.
+ *  2음절 이상 탈락훈련은 반대로 철자 기준이 맞다 — '놀이(노리)'에서 '놀'을 빼면 '리'가 아니라 '이'다.)
+ */
+export function buildDropFinalConsonantProblem(word, _comp, pronMap, _pv, _ws, _dropPos = null) {
+    if ([...word].length !== 1)
+        return null;
+    const s = parseSyllable(pronMap.get(word) || word);
+    if (!s || s.jong === 0)
+        return null;
+    const answer = composeSyllable(s.cho, s.jung, 0); // 받침 제거
+    const wrongs = syllableContrasts({ cho: s.cho, jung: s.jung, jong: 0 }, 'cho', answer, 2, pronMap);
+    if (wrongs.length < 2)
+        return null;
+    return { question: word, distractors: [answer, ...wrongs] };
+}
+const _IEUNG_CHO_IDX = CHOSEONG.indexOf('ㅇ');
+/**
+ * @public 1음절 자음(초성) 탈락 → [문제단어(받침 없는 자음 초성 1음절), 초성 뗀 순수 모음(정답), 모음 대립 오답 2].
+ * 자음을 빼면 ㅇ+모음만 남으므로(가→아) 오답도 ㅇ+다른 모음(아→오·우).
+ *
+ * 남는 모음은 표준발음에서 뽑는다 — '게(개)'에서 'ㄱ'을 빼면 들리는 소리는 '에'가 아니라 '애'다.
+ * 이 데이터의 ㅔ→ㅐ·ㅖ→ㅒ·ㅚ/ㅞ→ㅙ 정규화는 문맥과 무관해 고립 음절에도 그대로 적용된다.
+ */
+export function buildRemoveConsonantProblem(word, _comp, pronMap, _pv, _ws, _dropPos = null) {
+    if ([...word].length !== 1)
+        return null;
+    const s = parseSyllable(pronMap.get(word) || word);
+    if (!s || s.jong !== 0 || s.cho === _IEUNG_CHO_IDX)
+        return null;
+    const answer = composeSyllable(_IEUNG_CHO_IDX, s.jung, 0); // 초성(자음) 제거 → 순수 모음
+    const wrongs = syllableContrasts({ cho: _IEUNG_CHO_IDX, jung: s.jung, jong: 0 }, 'jung', answer, 2, pronMap);
+    if (wrongs.length < 2)
+        return null;
+    return { question: word, distractors: [answer, ...wrongs] };
+}
+// ── CHANGE 음절 바꾸기(완전히 다른 음절) 공유 생성기 ─────────────────────────
+// 편집기·런타임 공용. "한 음절만 2음소↑ 다른 실단어"로 교체(최소대립쌍과 구분).
+/** 위치 p를 와일드카드('*')로 마스킹한 "나머지 음절이 같은" 2·3음절 실단어 그룹(O(1) 조회). */
+export function buildSyllableMaskIndex(wordSet) {
+    const index = new Map();
+    for (const w of wordSet) {
+        const chars = [...w];
+        const n = chars.length;
+        if (n < 2 || n > 3)
+            continue;
+        for (let p = 0; p < n; p++) {
+            let k = n + '|' + p + '|';
+            for (let i = 0; i < n; i++)
+                k += (i === p ? '*' : chars[i]);
+            const b = index.get(k);
+            if (b)
+                b.push(w);
+            else
+                index.set(k, [w]);
+        }
+    }
+    return index;
+}
+/**
+ * 음절 바꾸기 — 한 음절을 '완전히 다른 음절'(minDiff=2음소↑ 차이)로 교체한 실단어를 정답으로.
+ * 같은 위치 1음절만, 2음소↑ 차, 발음 상이, 실단어(데이터)만. 합성 없음.
+ * compFrom=원래 음절 필터, compTo=바뀐 음절 필터, targetPos=바꿀 위치.
+ */
+export function buildChangeWholeSyllableProblem(word, compFrom, pronMap, phonemeView, maskIndex, targetPos = null, compTo = null, minDiff = 2) {
+    const chars = [...word];
+    const n = chars.length;
+    if (n < 2 || n > 3)
+        return null;
+    const dW = chars.map(c => parseSyllable(c));
+    if (dW.some(p => !p))
+        return null;
+    const matchSS = matchSyllables(word, pronMap, phonemeView);
+    if (matchSS.some(p => !p))
+        return null;
+    const pw = (w) => pronMap.get(w) ?? w;
+    const wPron = pw(word);
+    const fromSel = !!compFrom && (hasSel(compFrom.cho) || hasSel(compFrom.jung) || hasSel(compFrom.jong));
+    const toSel = !!compTo && (hasSel(compTo.cho) || hasSel(compTo.jung) || hasSel(compTo.jong));
+    const maskKey = (p) => { let k = n + '|' + p + '|'; for (let i = 0; i < n; i++)
+        k += (i === p ? '*' : chars[i]); return k; };
+    let positions;
+    if (targetPos != null) {
+        if (targetPos >= n)
+            return null;
+        if (fromSel && !syllMatchesComp(matchSS[targetPos], compFrom))
+            return null;
+        positions = [targetPos];
+    }
+    else if (fromSel) {
+        positions = matchSS.map((s, i) => (syllMatchesComp(s, compFrom) ? i : -1)).filter(i => i >= 0);
+    }
+    else {
+        positions = Array.from({ length: n }, (_, i) => i);
+    }
+    for (const p of shuffled(positions)) {
+        const group = maskIndex.get(maskKey(p)) ?? [];
+        const swaps = []; // 정답 후보 (toSel이면 바뀐 음절이 compTo 일치, 아니면 전부)
+        const nonMatch = []; // 오답 후보 (toSel일 때 compTo 불일치) — 정답만 유일하게 'TO로 바뀐' 단어가 되게
+        for (const x of group) {
+            if (x === word)
+                continue;
+            const dx = [...x].map(c => parseSyllable(c));
+            const a = dW[p], b = dx[p];
+            if (!a || !b)
+                continue;
+            let d = 0;
+            if (a.cho !== b.cho)
+                d++;
+            if (a.jung !== b.jung)
+                d++;
+            if (a.jong !== b.jong)
+                d++;
+            if (d < minDiff || pw(x) === wPron)
+                continue;
+            if (toSel) {
+                const mx = matchSyllables(x, pronMap, phonemeView)[p];
+                if (mx && syllMatchesComp(mx, compTo))
+                    swaps.push(x);
+                else
+                    nonMatch.push(x); // TO에 맞지 않는 음절교체 → 오답 풀
+            }
+            else {
+                swaps.push(x);
+            }
+        }
+        if (!swaps.length)
+            continue;
+        const answer = shuffled(swaps)[0];
+        const wrongs = [];
+        const usedPron = new Set([wPron, pw(answer)]);
+        // 오답 풀: TO 지정 시 'TO에 맞지 않는' 단어(정답만 유일하게 TO 만족 → '모두 정답' 방지),
+        //          미지정 시 다른 음절교체 단어(카드가 특정 음절 교체를 명시해 유일 정답).
+        const wrongPool = toSel ? nonMatch : swaps.filter(x => x !== answer);
+        for (const x of shuffled(wrongPool)) {
+            const xp = pw(x);
+            if (usedPron.has(xp))
+                continue;
+            usedPron.add(xp);
+            wrongs.push(x);
+            if (wrongs.length >= 2)
+                break;
+        }
+        // TO 미지정(whole-syllable)만 부족 시 group에서 보충(기존 동작 유지). TO 지정은 보충하지 않는다(TO 불일치만 오답).
+        if (!toSel && wrongs.length < 2) {
+            for (const x of shuffled(group)) {
+                if (x === word || x === answer)
+                    continue;
+                const xp = pw(x);
+                if (usedPron.has(xp))
+                    continue;
+                usedPron.add(xp);
+                wrongs.push(x);
+                if (wrongs.length >= 2)
+                    break;
+            }
+        }
+        if (wrongs.length < 2)
+            continue;
+        return { question: word, distractors: [answer, ...wrongs] };
+    }
+    return null;
+}
+export { pronOf as pronFromMap };

package/dist/packages/core/src/utils/wordTrainingGroups.d.ts

@@ -0,0 +1,10 @@
+import { type WordTrainingType } from '../hooks/useWordTrainingDataGeneration';
+export interface TrainingGroup {
+    key: string;
+    label: string;
+    disc: string;
+    icon: string;
+    types: WordTrainingType[];
+}
+/** @public 단어 훈련 그룹/유형 메타(라벨·아이콘·색). 통계 표시 등에서 재사용 */
+export declare const WORD_TRAINING_GROUPS: TrainingGroup[];

package/dist/packages/core/src/utils/wordTrainingGroups.js

@@ -0,0 +1,69 @@
+import { TRAINING_PALETTE } from './trainingPalette';
+// 카테고리별 색상 (파스텔 톤) — 공용 팔레트 단일 소스
+const COLOR_SOUND = TRAINING_PALETTE.blue;
+const COLOR_MERGE = TRAINING_PALETTE.green;
+const COLOR_DROP = TRAINING_PALETTE.amber;
+const COLOR_CHANGE = TRAINING_PALETTE.purple;
+const COLOR_ATTN = TRAINING_PALETTE.pink;
+/** @public 단어 훈련 그룹/유형 메타(라벨·아이콘·색). 통계 표시 등에서 재사용 */
+export const WORD_TRAINING_GROUPS = [
+    {
+        key: 'discrimination',
+        label: '변별훈련',
+        disc: '두 소리가 같은지 다른지, 또는 특정 소리를 구별하는 훈련입니다.',
+        icon: 'ear',
+        types: [
+            { key: 'SAME_SOUND_PICK', label: '같은 소리 고르기', icon: 'volume-2', color: COLOR_SOUND, subTitle: '들은 소리와 같은 단어 카드를 고르세요.' },
+            { key: 'SAME_OR_DIFF', label: '같은지 다른지 맞히기', icon: 'diff', color: COLOR_SOUND, subTitle: '두 소리가 같은지, 다른지 구분하세요.' },
+            { key: 'HEAR_AND_PICK_SAME', label: '일치하는 단어 맞히기', icon: 'headphones', color: COLOR_SOUND, subTitle: '들은 소리의 단어 카드를 고르세요.' },
+            { key: 'HEAR_AND_PICK_INCLUDED', label: '한 음절 포함 단어 맞히기', icon: 'scan-search', color: COLOR_SOUND, subTitle: '들은 음절이 포함된 단어 카드를 고르세요.' },
+            { key: 'STARTS_WITH_SAME_SOUND', label: '첫 음절이 같은 단어 맞히기', icon: 'play-circle', color: COLOR_SOUND, subTitle: '들은 단어와 같은 소리로 시작하는 단어를 고르세요.' },
+        ],
+    },
+    {
+        key: 'synthesis',
+        label: '합성훈련',
+        disc: '두 개 이상의 음절이나 음소를 합쳐 단어를 만드는 훈련입니다.',
+        icon: 'git-merge',
+        types: [
+            { key: 'MERGE_2_SYLLABLES', label: '음절 2개 합치기', icon: 'link-2', color: COLOR_MERGE, subTitle: '두 음절을 합치면 어떤 단어가 될까요?' },
+            { key: 'MERGE_3_SYLLABLES', label: '음절 3개 합치기', icon: 'git-merge', color: COLOR_MERGE, subTitle: '세 음절을 합치면 어떤 단어가 될까요?' },
+            { key: 'MERGE_2_PHONEMES', label: '음소 2개 합치기', icon: 'combine', color: COLOR_MERGE, subTitle: '두 음소를 합치면 어떤 소리가 될까요?' },
+            { key: 'MERGE_3_PHONEMES', label: '음소 3개 합치기', icon: 'braces', color: COLOR_MERGE, subTitle: '세 음소를 합치면 어떤 소리가 될까요?' },
+        ],
+    },
+    {
+        key: 'deletion',
+        label: '탈락훈련',
+        disc: '단어에서 음절이나 음소를 제거했을 때 남는 소리를 인식하는 훈련입니다.',
+        icon: 'scissors',
+        types: [
+            { key: 'DROP_1_FROM_2SYLL', label: '2음절에서 1음절 탈락', icon: 'scissors', color: COLOR_DROP, subTitle: '2음절 단어에서 한 음절을 빼면 어떤 소리가 될까요?' },
+            { key: 'DROP_1_FROM_3SYLL', label: '3음절에서 1음절 탈락', icon: 'minus-circle', color: COLOR_DROP, subTitle: '3음절 단어에서 한 음절을 빼면 어떤 소리가 될까요?' },
+            { key: 'DROP_PART_FROM_COMPOUND', label: '합성어에서 부분탈락', icon: 'unlink', color: COLOR_DROP, subTitle: '합성어의 일부를 빼면 어떤 단어가 될까요?' },
+            { key: 'DROP_FINAL_CONSONANT_FROM_1SYLL', label: '1음절에서 받침 탈락', icon: 'eraser', color: COLOR_DROP, subTitle: '받침을 빼면 어떤 소리가 될까요?' },
+            { key: 'REMOVE_CONSONANT_AND_IDENTIFY_PHONEME', label: '1음절에서 자음 탈락', icon: 'audio-lines', color: COLOR_DROP, subTitle: '자음을 빼면 어떤 소리가 남을까요?' },
+        ],
+    },
+    {
+        key: 'substitution',
+        label: '대치훈련',
+        disc: '단어의 일부 음절이나 음소를 바꾸어 새로운 소리를 만드는 훈련입니다.',
+        icon: 'replace',
+        types: [
+            { key: 'CHANGE_1_SYLL_IN_2SYLL', label: '2음절에서 한 음절 바꾸기', icon: 'replace', color: COLOR_CHANGE, subTitle: '2음절 단어의 한 음절을 바꿔 새 단어를 만드세요.' },
+            { key: 'CHANGE_1_SYLL_IN_3SYLL', label: '3음절에서 한 음절 바꾸기', icon: 'shuffle', color: COLOR_CHANGE, subTitle: '3음절 단어의 한 음절을 바꿔 새 단어를 만드세요.' },
+            { key: 'CHANGE_1_PHONEME_IN_1SYLL', label: '1음절에서 한 음소 바꾸기', icon: 'arrow-right-left', color: COLOR_CHANGE, subTitle: '1음절 단어의 한 음소를 바꿔 새 소리를 만드세요.' },
+            { key: 'CHANGE_1_PHONEME_IN_2SYLL', label: '2음절에서 한 음소 바꾸기', icon: 'flip-horizontal', color: COLOR_CHANGE, subTitle: '2음절 단어의 한 음소를 바꿔 새 단어를 만드세요.' },
+        ],
+    },
+    {
+        key: 'attention',
+        label: '청각적주의력훈련',
+        disc: '여러 소리를 듣고 순서를 기억하는 주의력과 단기 기억 훈련입니다.',
+        icon: 'list-ordered',
+        types: [
+            { key: 'LISTEN_AND_REMEMBER_ORDER', label: '듣고 순서대로 기억하기', icon: 'list-ordered', color: COLOR_ATTN, subTitle: '세 단어를 들은 순서대로 카드를 선택하세요.' },
+        ],
+    },
+];