@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,51 @@
+/**
+ * 단어훈련 문제를 만들 **재료**를 고르는 곳.
+ *
+ * 23,000개 낱말 데이터에서 조건에 맞는 것을 추려 내고(이미지 있는 것만·음절수·음소 위치),
+ * 그 결과를 캐시하고, 오답을 소리가 겹치지 않게 뽑는다. 실제로 문제를 **만드는** 일은
+ * wordTrainingRuntime 이 한다.
+ *
+ * 1,077줄 한 파일에 재료 고르기와 문제 만들기가 섞여 있었다. 둘은 성질이 다르다 —
+ * 재료 고르기는 성능이 전부고(캐시·부분 셔플·병렬 이미지 확인), 문제 만들기는 훈련 타입마다
+ * 규칙이 다르다. 한쪽을 볼 때 다른 쪽이 끼어들지 않게 갈라 둔다.
+ */
+import type { GenOptions } from './wordTrainingRuntimeTypes';
+export declare const _EMPTY_SET: Set<string>;
+export interface MvpWord {
+    w: string;
+    s: number;
+    p: string[];
+    /** 표준발음 — 스펠링은 다르지만 소리가 같은 동음이의어를 오답에서 배제하는 데 사용. 데이터 없으면 w로 폴백. */
+    pron: string;
+    /** 난이도 등급('1'~'4'). 데이터 없으면 undefined — 난이도 등급 필터 미적용 시 무시된다. */
+    grade?: string;
+}
+export declare const MVP: MvpWord[];
+export declare function pickOne<T>(arr: T[]): T | undefined;
+/** 부분 Fisher-Yates: n개만 선택 — arr.length 전체를 교환하지 않고 n번만 교환(대용량 풀 성능용, 공용 sample과 별개). */
+export declare function sample<T>(arr: T[], n: number): T[];
+export declare function getPronMap(): Map<string, string>;
+/**
+ * 후보군에서 n개를 뽑되, 이미 선택된 것들(또는 usedPron으로 미리 배제한 것들)과
+ * 발음이 겹치지 않도록 그리디하게 샘플링한다.
+ * '오답끼리도 서로 다른 소리여야 한다' 요구를 만족하기 위함 — 단순 sample()은 후보 각각을
+ * 정답과만 비교해 걸러진 풀이라도, 그 안에서 서로 발음이 같은 오답 2개가 함께 뽑힐 수 있다.
+ */
+export declare function sampleDistinctPron(pool: string[], n: number, usedPron?: Set<string>): string[];
+export declare function nextId(prefix: string): string;
+/** 단어 풀에서 이미지 있는 단어만 (병렬 HEAD 요청 — 캐시 미스 단어 포함) */
+/**
+ * 이미지 존재 여부를 localStorage 캐시만으로 동기 판정.
+ * prewarm 완료 후에는 HEAD 요청 없이 즉시 처리 가능.
+ * 캐시에 없는 단어(미확인)는 이미지 없음으로 처리한다.
+ */
+export declare function filterByCachedImage(words: Iterable<string>): Set<string>;
+export declare function _poolCacheKey(opts: GenOptions): string;
+/**
+ * 기준 글자/난이도/이미지 조건을 모두 통과한 (본 단어 + 유효 distractor) 풀을 만든다.
+ * @returns [{ word: 본단어, usable: 이미지 OK + 난이도 매칭 distractor 배열 }]
+ */
+export declare function buildUsablePool(opts: GenOptions): Promise<Array<{
+    word: MvpWord;
+    usable: string[];
+}>>;

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

@@ -0,0 +1,436 @@
+/**
+ * 단어훈련 문제를 만들 **재료**를 고르는 곳.
+ *
+ * 23,000개 낱말 데이터에서 조건에 맞는 것을 추려 내고(이미지 있는 것만·음절수·음소 위치),
+ * 그 결과를 캐시하고, 오답을 소리가 겹치지 않게 뽑는다. 실제로 문제를 **만드는** 일은
+ * wordTrainingRuntime 이 한다.
+ *
+ * 1,077줄 한 파일에 재료 고르기와 문제 만들기가 섞여 있었다. 둘은 성질이 다르다 —
+ * 재료 고르기는 성능이 전부고(캐시·부분 셔플·병렬 이미지 확인), 문제 만들기는 훈련 타입마다
+ * 규칙이 다르다. 한쪽을 볼 때 다른 쪽이 끼어들지 않게 갈라 둔다.
+ */
+import { getImageExistsCached, getImageExistenceStats } from './imageConfig';
+import { getWordPool } from './wordPool';
+import { shuffle } from './array';
+import { getPairIndex } from './wordPairIndex';
+import { classifyPairDifficulty, wordContainsPhoneme, wordHasNoCoda, wordHasSyllableMatching, syllableLength, findTypedContrastWords, countPhonemeDiff, createDecompCache } from './koreanSyllable';
+import { hasSel as _hasSel, hasStructureContrast, buildMultiPartPosContrast, minimalPairDistractors } from './wordContrast';
+export const _EMPTY_SET = new Set(); // wordSet 미사용 생성기용 placeholder
+/**
+ * 동적 단어 풀 뷰 (memoized).
+ * useWordData → setWordPool 이 호출된 뒤 최신 풀 + 대립쌍 인덱스를 MvpWord 형태로 변환.
+ * 풀이 아직 없으면 빈 배열 반환 (훈련 카드가 비활성 상태로 표시됨).
+ */
+let _cachedView = null;
+let _cachedPool = null;
+let _cachedIdx = null;
+function getMvpView() {
+    const pool = getWordPool();
+    if (pool && pool.entries.length > 0) {
+        const idx = getPairIndex();
+        // pool/index 참조가 같으면 캐시 재사용 (매 접근마다 map 생성 방지)
+        if (_cachedView && _cachedPool === pool && _cachedIdx === idx)
+            return _cachedView;
+        // 단어(철자) 기준 중복 제거 — 첫 엔트리 유지. 풀에 중복 엔트리가 있으면(현재 ~1014개)
+        // 후보 이중계산·생성 중복이 생기고, pronOfWord(마지막)와 pairIndex(첫) 발음이 어긋난다.
+        // 첫 엔트리로 통일해 카운트를 정확히 하고 발음 기준을 pairIndex와 일치시킨다.
+        const seen = new Set();
+        const view = [];
+        for (const e of pool.entries) {
+            if (!e.word || seen.has(e.word))
+                continue;
+            seen.add(e.word);
+            view.push({
+                w: e.word,
+                s: e.syllables,
+                p: idx?.[e.word]
+                    ? [...(idx[e.word].cho ?? []), ...(idx[e.word].jung ?? []), ...(idx[e.word].jong ?? [])]
+                    : [],
+                pron: e.pronunciation || e.word,
+                grade: e.grade,
+            });
+        }
+        _cachedView = view;
+        _cachedPool = pool;
+        _cachedIdx = idx;
+        return _cachedView;
+    }
+    return [];
+}
+export const MVP = new Proxy([], {
+    get(_t, prop) {
+        const view = getMvpView();
+        const val = view[prop];
+        // Array 메서드(filter/map 등) 호출 시 view를 this로 bind — 그렇지 않으면 receiver=Proxy를 this로 사용해서
+        // 다시 this.length/this[i] 가 트랩 호출되며 매번 새 view 생성/메모이즈 깨짐 가능
+        if (typeof val === 'function')
+            return val.bind(view);
+        return val;
+    },
+});
+// ────────────────────────────────────────────────────────────────────────────
+// 공통 유틸
+// ────────────────────────────────────────────────────────────────────────────
+export function pickOne(arr) { return arr.length ? arr[Math.floor(Math.random() * arr.length)] : undefined; }
+/** 부분 Fisher-Yates: n개만 선택 — arr.length 전체를 교환하지 않고 n번만 교환(대용량 풀 성능용, 공용 sample과 별개). */
+export function sample(arr, n) {
+    if (n >= arr.length)
+        return shuffle(arr);
+    if (n === 0)
+        return [];
+    const a = arr.slice();
+    for (let i = 0; i < n; i++) {
+        const j = i + Math.floor(Math.random() * (a.length - i));
+        const tmp = a[i];
+        a[i] = a[j];
+        a[j] = tmp;
+    }
+    return a.slice(0, n);
+}
+// ─── 표준발음 조회 (memoized) ───────────────────────────────────────────────
+// 단어 → 표준발음. 스펠링은 다르지만 소리가 같은 동음이의어를 오답에서 배제하는 데 쓴다.
+let _cachedPronMap = null;
+let _cachedPronMapPool = null;
+export function getPronMap() {
+    const pool = getWordPool();
+    if (_cachedPronMap && _cachedPronMapPool === pool)
+        return _cachedPronMap;
+    const m = new Map();
+    for (const w of MVP)
+        if (w.w)
+            m.set(w.w, w.pron);
+    _cachedPronMap = m;
+    _cachedPronMapPool = pool;
+    return m;
+}
+function pronOfWord(word) {
+    return getPronMap().get(word) || word;
+}
+/**
+ * 후보군에서 n개를 뽑되, 이미 선택된 것들(또는 usedPron으로 미리 배제한 것들)과
+ * 발음이 겹치지 않도록 그리디하게 샘플링한다.
+ * '오답끼리도 서로 다른 소리여야 한다' 요구를 만족하기 위함 — 단순 sample()은 후보 각각을
+ * 정답과만 비교해 걸러진 풀이라도, 그 안에서 서로 발음이 같은 오답 2개가 함께 뽑힐 수 있다.
+ */
+export function sampleDistinctPron(pool, n, usedPron = new Set()) {
+    const result = [];
+    for (const w of shuffle(pool)) {
+        if (result.length >= n)
+            break;
+        const p = pronOfWord(w);
+        if (usedPron.has(p))
+            continue;
+        usedPron.add(p);
+        result.push(w);
+    }
+    return result;
+}
+let _idCounter = 0;
+export function nextId(prefix) { return `${prefix}-rt-${++_idCounter}`; }
+/** 단어 풀에서 이미지 있는 단어만 (병렬 HEAD 요청 — 캐시 미스 단어 포함) */
+/**
+ * 이미지 존재 여부를 localStorage 캐시만으로 동기 판정.
+ * prewarm 완료 후에는 HEAD 요청 없이 즉시 처리 가능.
+ * 캐시에 없는 단어(미확인)는 이미지 없음으로 처리한다.
+ */
+export function filterByCachedImage(words) {
+    // prewarm 미완료(캐시 비어있음) → 필터 의미없음, 전체 반환
+    const stats = getImageExistenceStats();
+    if (!stats || stats.total === 0) {
+        const all = new Set();
+        for (const w of words)
+            all.add(w);
+        return all;
+    }
+    // prewarm 완료 → 이미지 확인된 단어만 허용
+    const result = new Set();
+    for (const w of words) {
+        if (getImageExistsCached(w) === true)
+            result.add(w);
+    }
+    return result;
+}
+// ─── buildUsablePool 캐시 ──────────────────────────────────────────────────
+// 동일 opts로 18개 카테고리가 병렬 호출되므로, Promise 자체를 캐싱해 한 번만 계산한다.
+// wordPool / pairIndex 참조가 바뀌면 자동 무효화.
+const _poolCache = new Map();
+let _cachePoolRef = null;
+let _cacheIdxRef = null;
+function _jamoKey(v) {
+    if (v == null)
+        return '';
+    return Array.isArray(v) ? v.slice().sort().join(',') : v;
+}
+export function _poolCacheKey(opts) {
+    const chStr = _jamoKey(opts.choseong);
+    const c = opts.composition;
+    const sylKey = c?.syllable == null ? '' : (Array.isArray(c.syllable) ? c.syllable.slice().sort().join(',') : String(c.syllable));
+    const compStr = c ? `${_jamoKey(c.cho)}/${_jamoKey(c.jung)}/${_jamoKey(c.jong)}/${c.jongNone ? 'N' : ''}/${sylKey}` : '';
+    const gradeStr = _jamoKey(opts.grade);
+    // targetSyllable(후보 필터)·choicesPerItem(보기 수)도 결과를 바꾼다. 키에서 빠져 있으면
+    // 보기 수만 다른 두 호출이 _resultCache 에서 같은 배열을 그대로 돌려받아, 나중 호출이
+    // 요청한 보기 수를 무시한다(공개 API 라 앱 밖 호출자가 무엇을 넘길지 알 수 없다).
+    return `${opts.difficulty ?? ''}|${chStr}|${compStr}|${opts.excludeNoImage ? '1' : '0'}|${opts.count ?? ''}|x${opts.contrastCount ?? 1}|${opts.fullCount ? 'F' : ''}|s${opts.sameStructureOnly === false ? '0' : '1'}|v${opts.phonemeView === 'pron' ? 'p' : 'c'}|g${gradeStr}|t${opts.targetSyllable ?? ''}|c${opts.choicesPerItem ?? ''}`;
+}
+/**
+ * 기준 글자/난이도/이미지 조건을 모두 통과한 (본 단어 + 유효 distractor) 풀을 만든다.
+ * @returns [{ word: 본단어, usable: 이미지 OK + 난이도 매칭 distractor 배열 }]
+ */
+export async function buildUsablePool(opts) {
+    // wordPool/pairIndex가 교체되면 캐시 전체 무효화
+    const pool = getWordPool();
+    const idx = getPairIndex();
+    if (pool !== _cachePoolRef || idx !== _cacheIdxRef) {
+        _poolCache.clear();
+        _cachePoolRef = pool;
+        _cacheIdxRef = idx;
+    }
+    const key = _poolCacheKey(opts);
+    if (!_poolCache.has(key))
+        _poolCache.set(key, _buildUsablePool(opts));
+    return _poolCache.get(key);
+}
+/**
+ * 초성/중성/종성/받침없음의 "같은 음절" 매칭 predicate — 빌더(TrainingSetPage.filteredWords)와 동일 규칙.
+ * 여러 파트를 선택하면 서로 다른 음절에 흩어진 게 아니라 "하나의 음절"이 그 조건을 모두 만족해야 한다.
+ * 예: 초성 ㄱ + 종성 ㅇ → '강/공'처럼 한 음절에 둘 다 있는 단어만(‘코딩’ 같이 흩어진 건 제외).
+ * - 받침없음만 단독 선택: 단어 전체가 열린 음절
+ * - 그 외 조합: 하나의 음절이 지정된 초성·중성·종성(·받침없음)을 모두 만족
+ * 지정된 위치 파트가 없으면 null.
+ */
+function _positionalPredicate(composition) {
+    if (!composition)
+        return null;
+    const toList = (v) => v == null ? null : (Array.isArray(v) ? (v.length ? v : null) : [v]);
+    const cho = toList(composition.cho);
+    const jung = toList(composition.jung);
+    const jongNone = !!composition.jongNone;
+    const jong = jongNone ? null : toList(composition.jong);
+    const hasPositional = !!(cho || jung || jong || jongNone);
+    if (!hasPositional)
+        return null;
+    const jongNoneAlone = jongNone && !cho && !jung && !jong;
+    if (jongNoneAlone)
+        return (word) => wordHasNoCoda(word);
+    return (word) => wordHasSyllableMatching(word, { cho, jung, jong, jongNone });
+}
+// 대립(오답) 엔진은 공용 모듈 wordContrast.ts 로 분리 — hasStructureContrast, buildMultiPartPosContrast,
+// minimalPairDistractors 등은 거기서 import 한다(런타임과 훈련/단어표 만들기가 공유).
+async function _buildUsablePool(opts) {
+    const { difficulty = null, choseong = null, composition = null, targetSyllable = null, excludeNoImage = false } = opts;
+    // 난이도 등급('1'~'4') 필터 — 정답(후보) 단어에만 적용(구성 필터와 동일 원칙, 오답 풀은 무관)
+    const gradeSet = opts.grade && opts.grade.length > 0 ? new Set(opts.grade) : null;
+    // 음소 구조 같은 단어만(초성 ㅇ 유무·받침 유무 대립 제외) — 기본 true
+    const sameStructureOnly = opts.sameStructureOnly ?? true;
+    // 음소 선택 방식 — 정답 검색 기준(글자입력=철자 / 발음입력=발음). 대립 비교는 두 모드 모두 발음.
+    const phonemeView = opts.phonemeView === 'pron' ? 'pron' : 'char';
+    // 대립 갯수 — cho/jung/jong 대립 종류일 때만 의미. 2개 이상은 전용 경로(compose-and-check).
+    const contrastCount = Math.max(1, opts.contrastCount ?? 1);
+    const isTyped = difficulty === 'cho' || difficulty === 'jung' || difficulty === 'jong';
+    const typedMulti = isTyped && contrastCount >= 2;
+    // count 모드 — 위치 구분 없이 서로 다른 음소 총 개수가 contrastCount개인 단어를 오답으로 사용.
+    const isCount = difficulty === 'count';
+    const choseongSet = choseong
+        ? new Set(Array.isArray(choseong) ? choseong : [choseong])
+        : null;
+    // 단어 구성요소(초성/중성/종성) 필터 — 파트별 AND. 각 파트는 배열 OR.
+    const syllableSet = composition?.syllable != null
+        ? new Set(Array.isArray(composition.syllable) ? composition.syllable : [composition.syllable])
+        : null;
+    const compPredicates = composition
+        ? [
+            // 초성/중성/종성/받침없음 — "같은 음절" 매칭(빌더와 동일). 흩어진 매칭 방지.
+            _positionalPredicate(composition),
+            // 음절 수 필터
+            syllableSet ? (word) => syllableSet.has(syllableLength(word)) : null,
+        ].filter((p) => p != null)
+        : [];
+    // 1) 후보 본 단어 추리기
+    //    - random 난이도: 대립쌍(p) 없어도 OK — 무관한 단어를 distractor로 사용
+    //    - 그 외: 대립쌍 필요
+    // difficulty=null 은 difficulty:false 타입에서 전달됨 (대립쌍 불필요) → 'random' 과 동일하게 전체 단어를 후보로 사용
+    const useRandomPool = difficulty === 'random' || difficulty === null;
+    // count 모드도 최소대립쌍(w.p) 없이 성립 → random 처럼 전체 단어를 후보로, 오답도 전체 풀에서 탐색
+    const useBroadDistractors = useRandomPool || isCount;
+    // 대립 2개 이상은 최소대립쌍(w.p) 없이도 성립 → random 처럼 전체 단어를 후보로
+    const useAllCandidates = useRandomPool || typedMulti || isCount;
+    let candidates = MVP.filter(w => {
+        if (!w.w)
+            return false;
+        if (gradeSet && (!w.grade || !gradeSet.has(w.grade)))
+            return false;
+        if (useAllCandidates)
+            return true;
+        return Array.isArray(w.p) && w.p.length > 0;
+    });
+    // 초성 필터(레거시): 단어 어디든 (초성/종성/복합종성) 해당 자모를 포함하면 매칭
+    if (choseongSet) {
+        candidates = candidates.filter(w => {
+            for (const jamo of choseongSet)
+                if (wordContainsPhoneme(w.w, jamo))
+                    return true;
+            return false;
+        });
+    }
+    // 정답 단어 구성 필터: 정답(후보) 단어가 지정된 모든 파트(초성/중성/종성/음절수)를 만족해야 매칭 (AND).
+    // 글자입력=철자로, 발음입력=표준발음으로 검색(사용자가 고른 음소를 그 기준으로 포함하는 단어).
+    // 오답(대립어)은 이 필터가 아니라 difficulty(대립 종류·갯수) 관계로 결정된다.
+    if (compPredicates.length > 0) {
+        candidates = candidates.filter(w => {
+            const target = phonemeView === 'pron' ? pronOfWord(w.w) : w.w;
+            return compPredicates.every(pred => pred(target));
+        });
+    }
+    if (targetSyllable)
+        candidates = candidates.filter(w => w.w[0] === targetSyllable);
+    // 2) 이미지 필터 적용
+    //    excludeNoImage=true: prewarm 캐시 기반 동기 판정 (HEAD 요청 없음, 즉시 처리)
+    //    excludeNoImage=false: 전체 단어 허용
+    let okWords;
+    if (excludeNoImage) {
+        // 본 단어 + 대립쌍 + random 전체 풀을 캐시로 동기 필터
+        const allWords = new Set();
+        for (const w of candidates) {
+            allWords.add(w.w);
+            if (Array.isArray(w.p))
+                for (const p of w.p)
+                    allWords.add(p);
+        }
+        if (useBroadDistractors) {
+            for (const w of MVP)
+                if (w.w)
+                    allWords.add(w.w);
+        }
+        okWords = filterByCachedImage(allWords); // 동기, 캐시만 사용
+    }
+    else {
+        // 이미지 제한 없음 — 전체 단어 pool 허용
+        const allWords = new Set();
+        for (const w of candidates) {
+            allWords.add(w.w);
+            if (Array.isArray(w.p))
+                for (const p of w.p)
+                    allWords.add(p);
+        }
+        if (useBroadDistractors) {
+            for (const w of MVP)
+                if (w.w)
+                    allWords.add(w.w);
+        }
+        okWords = allWords;
+    }
+    // 대립 2개 이상: 전체 단어(이미지 필터 적용, 단어 구성 무관)에서 대립어를 탐색해야 하므로 별도 집합 구성
+    let contrastWordSet = null;
+    if (typedMulti) {
+        const all = new Set();
+        for (const w of MVP)
+            if (w.w)
+                all.add(w.w);
+        contrastWordSet = excludeNoImage ? filterByCachedImage(all) : all;
+    }
+    // 3) 이미지 필터 통과한 candidates 만 추림 (샘플링은 그 이후에)
+    const okCandidates = candidates.filter(w => okWords.has(w.w));
+    // distractor 후보: 최대 DISTRACTOR_CAP 개로 샘플링 (연산량 제한)
+    const DISTRACTOR_CAP = 600;
+    const allOkArr = Array.from(okWords);
+    const distractorPool = allOkArr.length > DISTRACTOR_CAP
+        ? sample(allOkArr, DISTRACTOR_CAP)
+        : allOkArr;
+    // 선택 위치 대립 — count 모드에서 초성/모음/종성을 고르면, 오답은 "총 음소 갯수"가 아니라
+    // 선택 음소가 든 그 자리(들)에서만 다른 실단어여야 한다(나머지 자리는 동일).
+    const posContrast = isCount && composition != null &&
+        (_hasSel(composition.cho) || _hasSel(composition.jung) || _hasSel(composition.jong));
+    // cc≥2 전용: 위치 구분 없이 서로 다른 음소 총 개수로 대립어를 찾는 경로에서만 사용하는 음절수별 버킷.
+    // (posContrast는 아래 posContrastMap 으로 완전·고속 처리하므로 버킷 불필요)
+    const BUCKET_CAP = 2500;
+    const distractorByLen = new Map();
+    if (isCount && !posContrast && contrastCount >= 2) {
+        for (const wstr of allOkArr) {
+            const L = syllableLength(wstr);
+            const bucket = distractorByLen.get(L);
+            if (bucket)
+                bucket.push(wstr);
+            else
+                distractorByLen.set(L, [wstr]);
+        }
+        for (const [L, arr] of distractorByLen) {
+            if (arr.length > BUCKET_CAP)
+                distractorByLen.set(L, sample(arr, BUCKET_CAP));
+        }
+    }
+    const decompOf = createDecompCache(); // 호출당 새 캐시(이 생성 함수 스코프에 한정)
+    // 위치 대립: 전체 풀에서 완전 사전계산(마스킹 템플릿 인덱스). 후보당 O(1) 조회.
+    // 단일/다중 파트 모두 이 경로로 처리 — pairIndex 는 겹받침 단어(예: 값)를 누락하므로 의존하지 않는다.
+    const posContrastMap = posContrast
+        ? buildMultiPartPosContrast(composition, allOkArr, decompOf, sameStructureOnly, phonemeView, pronOfWord)
+        : null;
+    // candidates 크기 제한 — 이미지 필터 이후이므로 okCandidates 기반
+    const RANDOM_CAND_CAP = 500; // random: classifyPairDifficulty 없으나 루프 자체 제한
+    const OTHER_CAND_CAP = 1500; // cho/jung/jong: classifyPairDifficulty 호출이 있으므로 더 엄격히
+    // fullCount(카운트 표시용)는 샘플링 캡을 적용하지 않아 실제 가능 단어 수를 그대로 센다.
+    const effectiveCandidates = opts.fullCount
+        ? okCandidates
+        : difficulty === 'random'
+            ? (okCandidates.length > RANDOM_CAND_CAP ? sample(okCandidates, RANDOM_CAND_CAP) : okCandidates)
+            : (okCandidates.length > OTHER_CAND_CAP ? sample(okCandidates, OTHER_CAND_CAP) : okCandidates);
+    // pairIndex를 직접 참조해 난이도별 대립쌍을 조회 — classifyPairDifficulty 호출 최소화
+    const pIdx = getPairIndex();
+    const result = [];
+    for (const w of effectiveCandidates) {
+        let usable;
+        // 표준발음이 정답과 같은 동음이의어는 오답 후보에서 항상 배제
+        // (그대로 두면 '같은 소리 고르기' 류 훈련에서 서로 다른 보기가 실제로는 똑같이 들리는 문제가 생긴다).
+        const wPron = pronOfWord(w.w);
+        if (typedMulti) {
+            // 대립 종류(cho/jung/jong)의 음소가 정확히 contrastCount개 음절에서 다른 단어를 대립어로
+            usable = findTypedContrastWords(w.w, difficulty, contrastCount, contrastWordSet, 24)
+                .filter(p => pronOfWord(p) !== wPron);
+        }
+        else if (isCount) {
+            if (posContrast) {
+                // 선택 위치 대립: 선택 음소가 든 자리에서만 다른 실단어를 오답으로 (사전계산 맵에서 완전 조회).
+                usable = (posContrastMap.get(w.w) ?? []).filter(p => pronOfWord(p) !== wPron);
+            }
+            else if (contrastCount <= 1) {
+                // cc=1 = 최소대립쌍: 발음 기반 pairIndex(전 위치)에서 완전 조회(공용 엔진).
+                // 구조 필터는 아래 후처리에서 일괄 적용하므로 여기선 sameStructureOnly=false.
+                usable = minimalPairDistractors(w.w, pIdx, { okSet: okWords, pronOf: pronOfWord, decompOf, sameStructureOnly: false });
+            }
+            else {
+                // cc≥2: 위치 구분 없이 서로 다른 음소 개수로 오답 선택. 같은 음절수 버킷에서만 탐색.
+                const bucket = distractorByLen.get(syllableLength(w.w)) ?? [];
+                usable = bucket.filter(other => {
+                    if (other === w.w || pronOfWord(other) === wPron)
+                        return false;
+                    const d = countPhonemeDiff(w.w, other);
+                    return contrastCount >= 5 ? d >= 5 : d === contrastCount;
+                });
+            }
+        }
+        else if (useRandomPool) {
+            // 'random' 또는 null(difficulty:false 타입): 음운론적 제약은 없지만,
+            // 정답과 오답의 음절수는 같아야 한다(단어 길이만으로 정답을 짐작하지 못하도록) — 본 단어와 다른 단어 + 음절수(글자수) 동일
+            usable = distractorPool.filter(other => other !== w.w && other.length === w.w.length && pronOfWord(other) !== wPron);
+        }
+        else {
+            // cho/jung/jong: 발음 기반 pairIndex에서 해당 종류 대립쌍 조회(공용 엔진). 구조 필터는 후처리에서 일괄.
+            const diffKey = difficulty;
+            usable = minimalPairDistractors(w.w, pIdx, { kind: diffKey, okSet: okWords, pronOf: pronOfWord, decompOf, sameStructureOnly: false });
+            if (usable.length === 0) {
+                // pairIndex에 없거나 비어 있으면 distractorPool 소규모 샘플에서 fallback
+                const fallbackSample = distractorPool.length > 30 ? sample(distractorPool, 30) : distractorPool;
+                usable = fallbackSample.filter(other => other !== w.w && classifyPairDifficulty(w.w, other) === difficulty && pronOfWord(other) !== wPron);
+            }
+        }
+        // 음절 구조 대립(초성 ㅇ 유무·받침 유무) 제외 — 자음/모음 '교체'가 아닌 구조 차이는 청각 변별 오답으로 부적절.
+        // '음소 구조 같은 단어만'(sameStructureOnly)일 때만. posContrast 는 buildMultiPartPosContrast 안에서 적용. random/null 제외.
+        if (sameStructureOnly && usable.length > 0 && (isTyped || (isCount && !posContrast))) {
+            const wPronDecomp = decompOf(pronOfWord(w.w));
+            usable = usable.filter(p => !hasStructureContrast(wPronDecomp, decompOf(pronOfWord(p))));
+        }
+        if (usable.length === 0)
+            continue;
+        result.push({ word: w, usable });
+    }
+    return result;
+}

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

@@ -0,0 +1,38 @@
+import { type DifficultyLevel } from './koreanSyllable';
+export type { GenOptions, WordTrainingTypeKey, WordTrainingGroup } from './wordTrainingRuntimeTypes';
+export { CAPABILITY, cardGroupOf, isValidQuestionWord, hasQuestionWordConstraint, isManualOnlyType, QUESTION_WORD_RULE, MANUAL_ONLY_TYPES } from './wordTrainingRuntimeTypes';
+import type { GenOptions, WordTrainingTypeKey } from './wordTrainingRuntimeTypes';
+/** @public 훈련 유형별 문제 item 생성 */
+export declare function generateRuntimeItems(typeKey: WordTrainingTypeKey, opts?: GenOptions): Promise<unknown[]>;
+/**
+ * @public
+ * 공통 조합을 백그라운드에서 사전 계산해 결과 캐시를 미리 채운다.
+ * 이후 동일 조합으로 generateRuntimeItems 호출 시 즉시(<5ms) 반환.
+ * fire-and-forget — 완료 여부에 관계없이 UI 블로킹 없음.
+ * UI가 실제로 쓰는 difficulty(cap.difficulty→'count', 그 외 null)만 예열한다.
+ * (과거 대립종류 cho/jung/jong 예열은 UI 미사용이고 정작 count는 누락돼 첫 생성이 느렸음)
+ */
+export declare function precomputeCommonCombinations(excludeNoImage: boolean): Promise<void>;
+/** @public 이미지/난이도 조건이 적용된 초성 set — pool 단어 어디든 해당 자모가 있으면 viable */
+export declare function getViableChoseongs(opts?: {
+    difficulty?: DifficultyLevel | null;
+    excludeNoImage?: boolean;
+}): Promise<Set<string>>;
+/** @public 현재 필터(GenOptions) 조건으로 만들 수 있는 정답 단어 수.
+ *  fullCount로 샘플링 캡을 우회해 실제 가능 단어 수를 그대로 센다(무작위 왜곡 방지). */
+export declare function countUsableWords(opts: GenOptions): Promise<number>;
+/** @public 위치별(초성/중성/종성) 선택 가능한 자모 set + 음절 수 set — 실제 단어에 존재하는 값만.
+ *
+ * 존재 기반(presence)으로 판정한다. 대립쌍(최소대립쌍) 유무로 거르지 않는 이유:
+ * 음소를 실제로 선택하면 '위치 대립' 경로로 오답을 찾으므로, 최소대립쌍이 없어도(예: 겹받침 '값'=ㅄ)
+ * 훈련이 성립한다. 대립쌍 유무로 거르면 이런 자모가 잘못 비활성된다.
+ * (특정 조합의 훈련 가능 단어 수는 countUsableWords·카드 비활성으로 별도 안내.) */
+export declare function getViableComposition(opts?: {
+    difficulty?: DifficultyLevel | null;
+    excludeNoImage?: boolean;
+}): Promise<{
+    cho: Set<string>;
+    jung: Set<string>;
+    jong: Set<string>;
+    syllable: Set<number>;
+}>;