@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,641 @@
+/**
+ * 단어훈련용 런타임 문제 생성기.
+ *
+ * - SpeechEar_WordData (~23,000단어) 동적 풀을 사용한다.
+ *   useWordData 훅이 단어 데이터 fetch 후 setWordPool / buildPairIndex 를 호출하면
+ *   자동으로 최신 풀 + 대립쌍 인덱스를 사용한다.
+ * - 이미지 존재 여부(`checkImageExists`)를 사전 검증하여, 본 단어와 보기 모두 이미지가 있는
+ *   단어로만 문제를 구성한다 (Supabase 단어 이미지 버킷 기준).
+ *
+ * @public
+ */
+import { getWordPool } from './wordPool';
+import { shuffle } from './array';
+import { getPairIndex } from './wordPairIndex';
+import { wordContainsPhoneme, syllableLength, parseSyllable, CHOSEONG, JUNGSEONG, JONGSEONG, JONG_DECOMPOSE } from './koreanSyllable';
+export { CAPABILITY, cardGroupOf, isValidQuestionWord, hasQuestionWordConstraint, isManualOnlyType, QUESTION_WORD_RULE, MANUAL_ONLY_TYPES } from './wordTrainingRuntimeTypes';
+import { CAPABILITY, QUESTION_WORD_RULE } from './wordTrainingRuntimeTypes';
+import { buildDropContrastProblem, buildDropContrast3Problem, buildDropCompoundProblem, buildDropFinalConsonantProblem, buildRemoveConsonantProblem, buildChangeWholeSyllableProblem, buildSyllableMaskIndex } from './wordTrainingGenerators';
+/* 재료 고르기(풀 추리기·캐시·오답 샘플링)는 wordTrainingPool 로 갈라 두었다. */
+import { MVP, buildUsablePool, filterByCachedImage, getPronMap, nextId, pickOne, sample, sampleDistinctPron, _poolCacheKey, _EMPTY_SET, } from './wordTrainingPool';
+// ────────────────────────────────────────────────────────────────────────────
+// 카테고리별 generator
+// ────────────────────────────────────────────────────────────────────────────
+/** SAME_SOUND_PICK / HEAR_AND_PICK_SAME (보기 N개, 정답 1개 + 대립쌍 N-1) */
+async function genChoicePick(prefix, opts) {
+    const { choicesPerItem = 3, count = 10 } = opts;
+    const distractCount = choicesPerItem - 1;
+    const pool = (await buildUsablePool(opts)).filter(e => e.usable.length >= distractCount);
+    const results = [];
+    for (const entry of shuffle(pool)) {
+        if (results.length >= count)
+            break;
+        // usable은 이미 정답과 발음이 다른 단어만 남아있지만, 오답끼리는 서로 발음이 겹칠 수 있으므로
+        // sampleDistinctPron으로 오답끼리도 서로 다른 소리이도록 뽑는다. 부족하면 이 항목은 건너뜀.
+        const distractors = sampleDistinctPron(entry.usable, distractCount);
+        if (distractors.length < distractCount)
+            continue;
+        const choices = shuffle([entry.word.w, ...distractors]);
+        results.push({
+            id: nextId(prefix + '-item'),
+            index: results.length + 1,
+            word: entry.word.w,
+            syllables: entry.word.s,
+            choices,
+            answerIndex: choices.indexOf(entry.word.w),
+        });
+    }
+    return results;
+}
+/**
+ * HEAR_AND_PICK_INCLUDED
+ * 한 음절 소리를 듣고, 그 음절이 포함된 단어 카드를 고르는 훈련.
+ * - targetSyllable: 재생할 음절 (정답 단어의 임의 음절)
+ * - word: 정답 단어 (targetSyllable 포함)
+ * - choices: 정답 + 오답 단어 목록 (오답은 targetSyllable 미포함)
+ */
+async function genIncluded(opts) {
+    const { choicesPerItem = 3, count = 10 } = opts;
+    const distractCount = choicesPerItem - 1;
+    const allPool = (await buildUsablePool({ ...opts, difficulty: null }));
+    if (allPool.length < choicesPerItem)
+        return [];
+    const results = [];
+    const candidates = shuffle([...allPool]);
+    for (const entry of candidates) {
+        if (results.length >= count)
+            break;
+        const word = entry.word.w;
+        // 재생되는 건 targetSyllable 하나이고 과제는 "그 소리가 든 단어 고르기"다 — 철자 음절을 뽑으면
+        // '맏이(마지)'에서 '맏'이 나와 실제로는 들리지 않는 소리를 문제로 내게 된다. 표준발음에서 뽑는다.
+        const pron = entry.word.pron || word;
+        const syllables = [...pron]; // 한 글자 = 한 음절
+        const targetSyllable = pickOne(syllables);
+        if (!targetSyllable)
+            continue;
+        // 오답: targetSyllable이 발음에 포함되지 않고, 정답과 음절수(글자수)가 같으며, 발음이 다른 단어.
+        // 철자로 거르면 '같이(가치)'가 타깃 '가'인 문제의 오답으로 뽑혀 정답이 둘이 된다.
+        const distractorPool = allPool.filter(e => e.word.w !== word && e.word.s === entry.word.s
+            && !(e.word.pron || e.word.w).includes(targetSyllable)
+            && e.word.pron !== entry.word.pron);
+        if (distractorPool.length < distractCount)
+            continue;
+        // 오답끼리도 서로 발음이 겹치지 않도록 샘플링
+        const distractors = sampleDistinctPron(distractorPool.map(e => e.word.w), distractCount);
+        if (distractors.length < distractCount)
+            continue;
+        const choices = shuffle([word, ...distractors]);
+        results.push({
+            id: nextId('HPI-item'),
+            index: results.length + 1,
+            targetSyllable,
+            word,
+            choices,
+            answerIndex: choices.indexOf(word),
+        });
+    }
+    return results;
+}
+/** SAME_OR_DIFF (pair: [w,w] or [w,distractor]) */
+async function genSameOrDiff(opts) {
+    const { count = 10 } = opts;
+    const pool = (await buildUsablePool(opts)).filter(e => e.usable.length >= 1);
+    return Array.from({ length: count }, (_, i) => {
+        const entry = pickOne(pool);
+        if (!entry)
+            return null;
+        const isSame = i % 2 === 0;
+        let pair;
+        if (isSame)
+            pair = [entry.word.w, entry.word.w];
+        else {
+            const d = pickOne(entry.usable);
+            pair = Math.random() < 0.5 ? [entry.word.w, d] : [d, entry.word.w];
+        }
+        return {
+            id: nextId('SOD-item'),
+            index: i + 1,
+            word: entry.word.w,
+            pair,
+            same: isSame,
+        };
+    }).filter((x) => Boolean(x));
+}
+/**
+ * STARTS_WITH_SAME_SOUND
+ * sourceWord 의 소리를 듣고, 같은 음절로 시작하는 다른 단어 카드를 고르는 훈련.
+ * - sourceWord: 소리를 재생할 단어 (정답 카드와 첫 음절이 같지만 서로 다른 단어)
+ * - targetSyllable: 공유하는 첫 음절
+ * - choices: 정답(correct) + 오답(distractors, 다른 첫 음절)
+ * - answerIndex: choices 내 정답 인덱스
+ */
+async function genStartsWithSame(opts) {
+    const { choicesPerItem = 3, count = 10 } = opts;
+    const distractCount = choicesPerItem - 1;
+    const pool = await buildUsablePool({ ...opts, difficulty: null });
+    if (pool.length < choicesPerItem + 1)
+        return [];
+    const allWords = pool.map(e => e.word.w);
+    const wordPron = new Map(pool.map(e => [e.word.w, e.word.pron]));
+    // 이 훈련은 "들은 단어와 같은 '소리'로 시작하는 단어"를 고르는 청각 과제다.
+    // 철자 첫 글자로 묶으면 '맏이(마지)/맏딸(맏딸)'처럼 표기만 같고 실제로 들리는 첫 음절은
+    // 다른 짝이 정답이 되어 문제가 성립하지 않는다. 그러므로 표준발음의 첫 음절을 기준으로 묶는다.
+    const pronFirst = (w) => ((wordPron.get(w) || w)[0] ?? '');
+    // 첫 음절(표준발음) 기준 그룹화
+    const sameFirstPool = {};
+    for (const e of pool) {
+        const f = pronFirst(e.word.w);
+        if (!f)
+            continue;
+        if (!sameFirstPool[f])
+            sameFirstPool[f] = [];
+        sameFirstPool[f].push(e.word.w);
+    }
+    // sourceWord 와 correct 가 모두 필요하므로 같은 첫음절 단어 ≥2개인 그룹만 사용
+    const viableFirsts = Object.entries(sameFirstPool)
+        .filter(([, ws]) => ws.length >= 2)
+        .map(([f]) => f);
+    if (viableFirsts.length === 0)
+        return [];
+    const results = [];
+    const shuffledFirsts = shuffle([...viableFirsts]);
+    for (let attempt = 0; results.length < count && attempt < count * 4; attempt++) {
+        const targetSyllable = shuffledFirsts[attempt % shuffledFirsts.length];
+        const group = sameFirstPool[targetSyllable];
+        if (group.length < 2)
+            continue;
+        // sourceWord 와 correct 는 같은 그룹에서 서로 다른 단어
+        const picked = shuffle([...group]);
+        const sourceWord = picked[0];
+        const correct = picked[1];
+        // 명시적 동일 단어 방지. 표기가 달라도 발음이 같으면(깜박/깜빡 → 둘 다 '깜빡') 정답 카드가
+        // 문제 소리와 완전히 똑같이 들려 변별 과제가 성립하지 않으므로 발음 동일도 배제한다.
+        if (!sourceWord || !correct || sourceWord === correct)
+            continue;
+        if ((wordPron.get(sourceWord) || sourceWord) === (wordPron.get(correct) || correct))
+            continue;
+        // 오답: 첫 음절(발음)이 다르고, 정답(correct)과 음절수(글자수)가 같으며, 발음이 다른 단어 (sourceWord, correct 모두 제외)
+        // 철자 첫 글자로 거르면 '학교(학꾜)'가 targetSyllable '하'인 문제의 오답으로 뽑혀
+        // 정답이 둘이 되어 버린다. 그룹화와 동일하게 발음 첫 음절로 배제한다.
+        const correctPron = wordPron.get(correct) || correct;
+        const distractorPool = allWords.filter(w => pronFirst(w) !== targetSyllable && w !== sourceWord && w !== correct && w.length === correct.length
+            && (wordPron.get(w) || w) !== correctPron);
+        if (distractorPool.length < distractCount)
+            continue;
+        // 오답끼리도 서로 발음이 겹치지 않도록 샘플링
+        const distractors = sampleDistinctPron(distractorPool, distractCount);
+        if (distractors.length < distractCount)
+            continue;
+        const choices = shuffle([correct, ...distractors]);
+        results.push({
+            id: nextId('SWS-item'),
+            index: results.length + 1,
+            sourceWord,
+            targetSyllable,
+            word: correct,
+            choices,
+            answerIndex: choices.indexOf(correct),
+        });
+    }
+    return results;
+}
+/** 1음절 바꾸기(N음절) 공통 렌더 — 정답 단어와 바뀐 단어 쌍을 문항으로.
+ *  오답(distractors)은 같은 원단어의 다른 최소대립쌍(e.usable)에서 뽑아 러너가 무관 단어로 채우지 않게 한다
+ *  (genChangeWholeSyll과 동일 철학: 같은-base 대립쌍. e.usable은 buildUsablePool이 이미 1음소 대립쌍만 담음). */
+function renderSyllableSwapItems(pool, count, idPrefix) {
+    return sample(pool, count).map((e, i) => {
+        const changedWord = pickOne(e.usable) ?? '';
+        const origSylls = [...e.word.w];
+        const changedSylls = [...changedWord];
+        const diffIdx = origSylls.findIndex((s, k) => s !== changedSylls[k]);
+        const distractors = shuffle(e.usable.filter(u => u && u !== changedWord)).slice(0, 2);
+        return {
+            id: nextId(idPrefix),
+            index: i + 1,
+            word: e.word.w,
+            original: e.word.w,
+            changed: changedWord,
+            changedFrom: diffIdx >= 0 ? origSylls[diffIdx] : '',
+            changedTo: diffIdx >= 0 ? changedSylls[diffIdx] : '',
+            distractors,
+        };
+    });
+}
+/**
+ * 음절 바꾸기(N음절) — 편집기와 **공유 코어** buildChangeWholeSyllableProblem 사용(단일 출처).
+ * 한 음절을 '완전히 다른 음절'(2음소↑차)로 교체한 실단어 정답 + 같은-base 대립 오답 2개를 item에 심는다.
+ * 러너가 preset distractors를 그대로 쓰므로 자동생성도 편집기 품질(폴백 무관단어 오답 대신 같은-base).
+ */
+async function genChangeWholeSyll(N, opts, idPrefix) {
+    const { count = 10 } = opts;
+    const pronMap = getPronMap();
+    const all = MVP.filter(w => w.w && w.s === N);
+    const okSet = opts.excludeNoImage ? filterByCachedImage(all.map(w => w.w)) : null;
+    const words = okSet ? all.filter(w => okSet.has(w.w)) : all;
+    const wordSet = new Set(words.map(w => w.w));
+    const maskIndex = buildSyllableMaskIndex(wordSet);
+    const phonemeView = opts.phonemeView ?? 'char';
+    const comp = opts.composition ?? null;
+    const out = [];
+    for (const w of shuffle(words)) {
+        if (out.length >= count)
+            break;
+        const prob = buildChangeWholeSyllableProblem(w.w, comp, pronMap, phonemeView, maskIndex, null, null);
+        if (!prob)
+            continue;
+        const changed = prob.distractors[0];
+        const origSylls = [...w.w];
+        const changedSylls = [...changed];
+        const diffIdx = origSylls.findIndex((s, k) => s !== changedSylls[k]);
+        out.push({
+            id: nextId(idPrefix),
+            index: out.length + 1,
+            word: w.w,
+            original: w.w,
+            changed,
+            changedFrom: diffIdx >= 0 ? origSylls[diffIdx] : '',
+            changedTo: diffIdx >= 0 ? changedSylls[diffIdx] : '',
+            distractors: prob.distractors.slice(1),
+        });
+    }
+    return out;
+}
+/** CHANGE_1_SYLL_IN_2SYLL — 2음절 단어의 1음절 바꾸기(완전히 다른 음절) */
+async function genChange1SyllIn2Syll(opts) { return genChangeWholeSyll(2, opts, 'CS2-item'); }
+/** CHANGE_1_SYLL_IN_3SYLL — 3음절 단어의 1음절 바꾸기(완전히 다른 음절) */
+async function genChange1SyllIn3Syll(opts) { return genChangeWholeSyll(3, opts, 'CS3-item'); }
+/** CHANGE_1_PHONEME_IN_1SYLL — 1음절에서 1음소 바꾸기(최소대립쌍, 데이터 기반).
+ *  cap에 difficulty가 없어 opts.difficulty가 null로 오므로 여기서 count 모드로 강제해 최소대립쌍을 얻는다. */
+async function genChange1PhonemeIn1Syll(opts) {
+    const pool = (await buildUsablePool({ ...opts, difficulty: 'count', contrastCount: 1 }))
+        .filter(e => e.word.s === 1 && e.usable.length >= 1);
+    return renderSyllableSwapItems(pool, opts.count ?? 10, 'CP1-item');
+}
+/** CHANGE_1_PHONEME_IN_2SYLL — 2음절 단어에서 1음소 바꾸기(최소대립쌍, 데이터 기반).
+ *  '대치'는 반드시 최소대립쌍이어야 하므로 difficulty가 'random'/null(=useRandomPool: 같은 길이 아무 단어)로
+ *  오면 완전히 무관한 단어가 나온다. 위치 난이도(cho/jung/jong)는 그대로 두되, random/null은 'count'(전위치
+ *  최소대립쌍)로 대체해 항상 1음소 대립쌍을 보장한다. (1SYLL은 cap.difficulty=false라 이미 'count' 강제.) */
+async function genChange1PhonemeIn2Syll(opts) {
+    const diff = opts.difficulty && opts.difficulty !== 'random' ? opts.difficulty : 'count';
+    const pool = (await buildUsablePool({ ...opts, difficulty: diff, contrastCount: 1 }))
+        .filter(e => e.word.s === 2 && e.usable.length >= 1);
+    return renderSyllableSwapItems(pool, opts.count ?? 10, 'CP2-item');
+}
+/** MERGE_2_SYLLABLES — 2음절 단어 → 음절 두 개 합치기 */
+async function genMerge2Syll(opts) {
+    const { count = 10 } = opts;
+    const pool = (await buildUsablePool({ ...opts })).filter(e => e.word.s === 2);
+    return sample(pool, count).map((e, i) => ({
+        id: nextId('M2S-item'),
+        index: i + 1,
+        word: e.word.w,
+        answer: e.word.w,
+        parts: [...e.word.w], // 한글 글자 단위
+    }));
+}
+/** MERGE_3_SYLLABLES */
+async function genMerge3Syll(opts) {
+    const { count = 10 } = opts;
+    const pool = (await buildUsablePool({ ...opts })).filter(e => e.word.s === 3);
+    return sample(pool, count).map((e, i) => ({
+        id: nextId('M3S-item'),
+        index: i + 1,
+        word: e.word.w,
+        answer: e.word.w,
+        parts: [...e.word.w],
+    }));
+}
+/** DROP_1_FROM_2SYLL — 2음절 → 한 음절 탈락 */
+async function genDrop1From2Syll(opts) {
+    const { count = 10 } = opts;
+    const pool = (await buildUsablePool({ ...opts })).filter(e => e.word.s === 2);
+    // 편집기와 동일한 대립쌍 오답을 item에 심는다(공유 코어 buildDropContrastProblem).
+    // 러너(WordManipulationTrainingPagePopup)가 preset distractors를 그대로 쓰므로 자동생성도 편집기 품질이 된다.
+    const pronMap = getPronMap();
+    const wordSet = new Set(MVP.map(w => w.w));
+    const phonemeView = opts.phonemeView ?? 'char';
+    const out = [];
+    for (const e of shuffle(pool)) {
+        if (out.length >= count)
+            break;
+        const prob = buildDropContrastProblem(e.word.w, opts.composition ?? null, pronMap, phonemeView, wordSet);
+        if (!prob)
+            continue;
+        const [remain, ...wrongs] = prob.distractors;
+        const sylls = [...e.word.w];
+        const dropped = sylls[0] === remain ? sylls[1] : sylls[0]; // 남는 음절(remain) 외 나머지 1음절
+        out.push({
+            id: nextId('D2-item'),
+            index: out.length + 1,
+            original: e.word.w,
+            word: e.word.w,
+            dropped,
+            missingResult: remain,
+            distractors: wrongs,
+        });
+    }
+    return out;
+}
+/** DROP_1_FROM_3SYLL */
+async function genDrop1From3Syll(opts) {
+    const { count = 10 } = opts;
+    const pool = (await buildUsablePool({ ...opts })).filter(e => e.word.s === 3);
+    // 편집기와 동일한 대립쌍 오답을 item에 심는다(공유 코어 buildDropContrast3Problem).
+    const pronMap = getPronMap();
+    const wordSet = new Set(MVP.map(w => w.w));
+    const phonemeView = opts.phonemeView ?? 'char';
+    const out = [];
+    for (const e of shuffle(pool)) {
+        if (out.length >= count)
+            break;
+        const prob = buildDropContrast3Problem(e.word.w, opts.composition ?? null, pronMap, phonemeView, wordSet);
+        if (!prob)
+            continue;
+        const [remain, ...wrongs] = prob.distractors;
+        const chars = [...e.word.w];
+        // 탈락 음절 = 그 자리를 빼면 남는 2음절(remain)이 되는 자리
+        let dropped = '';
+        for (let k = 0; k < chars.length; k++) {
+            if (chars.filter((_, j) => j !== k).join('') === remain) {
+                dropped = chars[k];
+                break;
+            }
+        }
+        out.push({
+            id: nextId('D3-item'),
+            index: out.length + 1,
+            original: e.word.w,
+            word: e.word.w,
+            dropped,
+            missingResult: remain,
+            distractors: wrongs,
+        });
+    }
+    return out;
+}
+/** DROP_PART_FROM_COMPOUND — 합성어(앞/뒤 조각이 둘 다 실단어)에서 한 어근 탈락. 편집기와 동일 코어 빌더 사용. */
+async function genDropCompound(opts) {
+    const { count = 10 } = opts;
+    // 합성어 후보 — 2음절 이상. 훈련음소는 선택적(있으면 남는 단어의 그 자리를 대립으로 좁힘).
+    const pool = (await buildUsablePool({ ...opts })).filter(e => e.word.s >= 2);
+    const pronMap = getPronMap();
+    const wordSet = new Set(MVP.map(w => w.w));
+    const phonemeView = opts.phonemeView ?? 'char';
+    const out = [];
+    for (const e of shuffle(pool)) {
+        if (out.length >= count)
+            break;
+        const prob = buildDropCompoundProblem(e.word.w, opts.composition ?? null, pronMap, phonemeView, wordSet);
+        if (!prob)
+            continue;
+        const [remain, ...wrongs] = prob.distractors;
+        // 탈락 어근 = 원본에서 남는 단어(remain)를 뺀 나머지(앞 또는 뒤).
+        const w = e.word.w;
+        const dropped = w.startsWith(remain) ? w.slice(remain.length) : (w.endsWith(remain) ? w.slice(0, w.length - remain.length) : '');
+        out.push({
+            id: nextId('DPC-item'),
+            index: out.length + 1,
+            original: w,
+            word: w,
+            dropped,
+            missingResult: remain,
+            distractors: wrongs,
+        });
+    }
+    return out;
+}
+/** LISTEN_AND_REMEMBER_ORDER — 단어 3개를 듣고 순서대로 기억 */
+async function genListenAndRememberOrder(opts) {
+    const { count = 10 } = opts;
+    const pool = await buildUsablePool({ ...opts });
+    const words = pool.map(e => e.word.w);
+    if (words.length < 3)
+        return [];
+    return Array.from({ length: count }, (_, i) => {
+        const seq = sample(words, 3);
+        return {
+            id: nextId('LRO-item'),
+            index: i + 1,
+            sequence: seq,
+            choices: shuffle(seq),
+        };
+    });
+}
+// ────────────────────────────────────────────────────────────────────────────
+// 음소 단위(합성/탈락) — 실단어 데이터 기반. 이미지 필터 적용.
+// ────────────────────────────────────────────────────────────────────────────
+/** N음절 실단어(이미지 필터 적용) 중 조건(pred: 첫 음절 분해값 기준)을 만족하는 것 */
+function realWordsOfLen(N, excludeNoImage, pred) {
+    const all = MVP.filter(w => w.w && w.s === N);
+    const ok = excludeNoImage ? filterByCachedImage(all.map(w => w.w)) : null;
+    const out = [];
+    for (const mw of all) {
+        if (ok && !ok.has(mw.w))
+            continue;
+        if (pred) {
+            const s = parseSyllable(mw.w);
+            if (!s || !pred(s))
+                continue;
+        }
+        out.push(mw);
+    }
+    return out;
+}
+/** MERGE_2_PHONEMES — 초성+모음 합쳐 1음절(받침 없음). 실단어 데이터 기반 */
+function genMerge2Phonemes(opts) {
+    const pool = realWordsOfLen(1, opts.excludeNoImage ?? false, s => s.jong === 0);
+    return sample(pool, opts.count ?? 10).map((e, i) => {
+        const s = parseSyllable(e.w);
+        return { id: nextId('M2P-item'), index: i + 1, parts: [CHOSEONG[s.cho], JUNGSEONG[s.jung]], answer: e.w, word: e.w };
+    });
+}
+/** MERGE_3_PHONEMES — 초성+모음+종성 합쳐 1음절(홑받침). 실단어 데이터 기반 */
+function genMerge3Phonemes(opts) {
+    // 홑받침만(겹받침은 음소 2개라 '3음소'가 아니게 됨)
+    const pool = realWordsOfLen(1, opts.excludeNoImage ?? false, s => s.jong > 0 && !JONG_DECOMPOSE[s.jong]);
+    return sample(pool, opts.count ?? 10).map((e, i) => {
+        const s = parseSyllable(e.w);
+        return { id: nextId('M3P-item'), index: i + 1, parts: [CHOSEONG[s.cho], JUNGSEONG[s.jung], JONGSEONG[s.jong]], answer: e.w, word: e.w };
+    });
+}
+/** DROP_FINAL_CONSONANT_FROM_1SYLL — 1음절에서 받침 탈락(닭→다). 실단어 데이터 기반.
+ *  풀 조건은 QUESTION_WORD_RULE와 공유 — 편집기 무작위 선택/검증이 이 규칙을 그대로 쓴다. */
+function genDropFinalConsonant(opts) {
+    const rule = QUESTION_WORD_RULE.DROP_FINAL_CONSONANT_FROM_1SYLL;
+    const pool = realWordsOfLen(rule.syllables, opts.excludeNoImage ?? false, rule.syllable);
+    const pronMap = getPronMap();
+    const out = [];
+    for (const e of shuffle(pool)) {
+        if (out.length >= (opts.count ?? 10))
+            break;
+        // 편집기와 동일한 초성 대립 오답을 심는다(공유 코어).
+        const prob = buildDropFinalConsonantProblem(e.w, null, pronMap, 'char', _EMPTY_SET);
+        if (!prob)
+            continue;
+        const [answer, ...wrongs] = prob.distractors;
+        out.push({ id: nextId('DFC-item'), index: out.length + 1, original: e.w, word: e.w, result: answer, distractors: wrongs });
+    }
+    return out;
+}
+/** REMOVE_CONSONANT_AND_IDENTIFY_PHONEME — 1음절 초성(자음) 탈락 → 남는 모음(가→아). 실단어 데이터 기반.
+ *  풀 조건은 QUESTION_WORD_RULE와 공유 — 편집기 무작위 선택/검증이 이 규칙을 그대로 쓴다. */
+function genRemoveConsonant(opts) {
+    // 받침 없는 자음 초성 1음절만 → 자음을 빼면 순수 모음 음절(ㅇ+모음)이 남는다.
+    const rule = QUESTION_WORD_RULE.REMOVE_CONSONANT_AND_IDENTIFY_PHONEME;
+    const pool = realWordsOfLen(rule.syllables, opts.excludeNoImage ?? false, rule.syllable);
+    const pronMap = getPronMap();
+    const out = [];
+    for (const e of shuffle(pool)) {
+        if (out.length >= (opts.count ?? 10))
+            break;
+        const prob = buildRemoveConsonantProblem(e.w, null, pronMap, 'char', _EMPTY_SET); // 모음 대립 오답(공유 코어)
+        if (!prob)
+            continue;
+        // 빼는 자음도 정답과 같은 출처(표준발음)에서 읽는다 — 빌더가 발음 기준으로 정답을 만드는데
+        // 여기만 철자를 파싱하면 둘이 어긋날 수 있다.
+        const s = parseSyllable(pronMap.get(e.w) || e.w);
+        if (!s)
+            continue;
+        const [answer, ...wrongs] = prob.distractors;
+        out.push({
+            id: nextId('RCP-item'),
+            index: out.length + 1,
+            base: e.w,
+            word: e.w,
+            missingConsonant: CHOSEONG[s.cho],
+            remaining: answer,
+            distractors: wrongs,
+        });
+    }
+    return out;
+}
+// ─── 결과 캐시 ─────────────────────────────────────────────────────────────────
+// pool / pairIndex 참조가 바뀌면 자동 무효화.
+// 동일 (typeKey, opts) 조합은 계산 없이 즉시 반환.
+const _resultCache = new Map();
+let _resultCachePoolRef = null;
+let _resultCacheIdxRef = null;
+/** @public 훈련 유형별 문제 item 생성 */
+export async function generateRuntimeItems(typeKey, opts = {}) {
+    const pool = getWordPool();
+    const idx = getPairIndex();
+    if (pool !== _resultCachePoolRef || idx !== _resultCacheIdxRef) {
+        _resultCache.clear();
+        _resultCachePoolRef = pool;
+        _resultCacheIdxRef = idx;
+    }
+    const cacheKey = `${typeKey}:${_poolCacheKey(opts)}`;
+    if (_resultCache.has(cacheKey))
+        return _resultCache.get(cacheKey);
+    const items = await _generateRuntimeItems(typeKey, opts);
+    _resultCache.set(cacheKey, items);
+    return items;
+}
+const GENERATOR_MAP = {
+    SAME_SOUND_PICK: (opts) => genChoicePick('SSP', opts),
+    HEAR_AND_PICK_SAME: (opts) => genChoicePick('HPS', opts),
+    HEAR_AND_PICK_INCLUDED: (opts) => genIncluded(opts),
+    SAME_OR_DIFF: (opts) => genSameOrDiff(opts),
+    STARTS_WITH_SAME_SOUND: (opts) => genStartsWithSame(opts),
+    LISTEN_AND_REMEMBER_ORDER: (opts) => genListenAndRememberOrder(opts),
+    MERGE_2_SYLLABLES: (opts) => genMerge2Syll(opts),
+    MERGE_3_SYLLABLES: (opts) => genMerge3Syll(opts),
+    MERGE_2_PHONEMES: (opts) => genMerge2Phonemes(opts),
+    MERGE_3_PHONEMES: (opts) => genMerge3Phonemes(opts),
+    DROP_1_FROM_2SYLL: (opts) => genDrop1From2Syll(opts),
+    DROP_1_FROM_3SYLL: (opts) => genDrop1From3Syll(opts),
+    DROP_PART_FROM_COMPOUND: (opts) => genDropCompound(opts),
+    DROP_FINAL_CONSONANT_FROM_1SYLL: (opts) => genDropFinalConsonant(opts),
+    REMOVE_CONSONANT_AND_IDENTIFY_PHONEME: (opts) => genRemoveConsonant(opts),
+    CHANGE_1_SYLL_IN_2SYLL: (opts) => genChange1SyllIn2Syll(opts),
+    CHANGE_1_SYLL_IN_3SYLL: (opts) => genChange1SyllIn3Syll(opts),
+    CHANGE_1_PHONEME_IN_1SYLL: (opts) => genChange1PhonemeIn1Syll(opts),
+    CHANGE_1_PHONEME_IN_2SYLL: (opts) => genChange1PhonemeIn2Syll(opts),
+};
+async function _generateRuntimeItems(typeKey, opts = {}) {
+    const gen = GENERATOR_MAP[typeKey];
+    return gen ? await gen(opts) : [];
+}
+/**
+ * @public
+ * 공통 조합을 백그라운드에서 사전 계산해 결과 캐시를 미리 채운다.
+ * 이후 동일 조합으로 generateRuntimeItems 호출 시 즉시(<5ms) 반환.
+ * fire-and-forget — 완료 여부에 관계없이 UI 블로킹 없음.
+ * UI가 실제로 쓰는 difficulty(cap.difficulty→'count', 그 외 null)만 예열한다.
+ * (과거 대립종류 cho/jung/jong 예열은 UI 미사용이고 정작 count는 누락돼 첫 생성이 느렸음)
+ */
+export async function precomputeCommonCombinations(excludeNoImage) {
+    const difficulties = [null, 'count'];
+    const types = Object.keys(CAPABILITY);
+    let tick = 0;
+    for (const diff of difficulties) {
+        for (const t of types) {
+            const cap = CAPABILITY[t];
+            generateRuntimeItems(t, {
+                difficulty: cap.difficulty ? diff : null,
+                choseong: null,
+                count: 10,
+                excludeNoImage,
+            }).catch(() => { });
+            // 6 타입마다 마이크로태스크 양보 → 메인 스레드 프레임 블로킹 방지
+            if (++tick % 6 === 0)
+                await new Promise(r => setTimeout(r, 0));
+        }
+    }
+}
+/** @public 이미지/난이도 조건이 적용된 초성 set — pool 단어 어디든 해당 자모가 있으면 viable */
+export async function getViableChoseongs(opts = {}) {
+    const pool = await buildUsablePool({ difficulty: opts.difficulty ?? null, excludeNoImage: opts.excludeNoImage });
+    const set = new Set();
+    // 모든 19 초성 자모를 단어와 매칭해서 viable 검사
+    const allJamos = ['ㄱ', 'ㄲ', 'ㄴ', 'ㄷ', 'ㄸ', 'ㄹ', 'ㅁ', 'ㅂ', 'ㅃ', 'ㅅ', 'ㅆ', 'ㅇ', 'ㅈ', 'ㅉ', 'ㅊ', 'ㅋ', 'ㅌ', 'ㅍ', 'ㅎ'];
+    for (const jamo of allJamos) {
+        if (pool.some(e => wordContainsPhoneme(e.word.w, jamo)))
+            set.add(jamo);
+    }
+    return set;
+}
+/** @public 현재 필터(GenOptions) 조건으로 만들 수 있는 정답 단어 수.
+ *  fullCount로 샘플링 캡을 우회해 실제 가능 단어 수를 그대로 센다(무작위 왜곡 방지). */
+export async function countUsableWords(opts) {
+    const pool = await buildUsablePool({ ...opts, fullCount: true });
+    return pool.length;
+}
+/** @public 위치별(초성/중성/종성) 선택 가능한 자모 set + 음절 수 set — 실제 단어에 존재하는 값만.
+ *
+ * 존재 기반(presence)으로 판정한다. 대립쌍(최소대립쌍) 유무로 거르지 않는 이유:
+ * 음소를 실제로 선택하면 '위치 대립' 경로로 오답을 찾으므로, 최소대립쌍이 없어도(예: 겹받침 '값'=ㅄ)
+ * 훈련이 성립한다. 대립쌍 유무로 거르면 이런 자모가 잘못 비활성된다.
+ * (특정 조합의 훈련 가능 단어 수는 countUsableWords·카드 비활성으로 별도 안내.) */
+export async function getViableComposition(opts = {}) {
+    const allWords = [];
+    for (const w of MVP)
+        if (w.w)
+            allWords.push(w.w);
+    const words = opts.excludeNoImage ? filterByCachedImage(allWords) : allWords;
+    const cho = new Set();
+    const jung = new Set();
+    const jong = new Set();
+    const syllable = new Set();
+    for (const word of words) {
+        syllable.add(syllableLength(word));
+        for (const ch of word) {
+            const s = parseSyllable(ch);
+            if (!s)
+                continue;
+            // 초성 ㅇ은 무음(빈 초성) — 자음 대립 타깃이 될 수 없으므로 선택 대상에서 제외(발음 입력과 동일).
+            if (CHOSEONG[s.cho] !== 'ㅇ')
+                cho.add(CHOSEONG[s.cho]);
+            jung.add(JUNGSEONG[s.jung]);
+            if (s.jong > 0) {
+                // 글자 입력(정확 매칭): 겹받침 원형(ㄳ 등)을 그대로 viable 로 — 그래야 겹받침 버튼이 활성화된다.
+                jong.add(JONGSEONG[s.jong]);
+                // 발음 입력(대표음): 겹받침을 구성 자모로 분해해 대표음(ㄱ 등) 버튼도 활성화.
+                const decomp = JONG_DECOMPOSE[s.jong];
+                if (decomp)
+                    decomp.forEach(j => jong.add(j));
+            }
+        }
+    }
+    return { cho, jung, jong, syllable };
+}