@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,22 @@
+export type { WordEntry, PairFilterKeys, SearchPairsDebugReport } from './phonemePairSearchTypes';
+import type { WordSearchResultItem } from '../types/wordSearch';
+import type { WordEntry } from './phonemePairSearchTypes';
+import type { PairFilterKeys } from './phonemePairSearchTypes';
+/** applyFilters/matchesFilters가 공통으로 판정하는 필드 — WordEntry와 WordSearchResultWord
+ *  양쪽 다 이 부분집합을 채워서 넘길 수 있다(검색 전 단어 풀 필터링과, 검색 결과의 특정 단어만
+ *  사후 필터링하는 두 경우 모두 같은 판정 로직을 재사용하기 위함). */
+export interface FilterableWord {
+    grade?: string;
+    syllables?: number;
+    pos?: string;
+    wordType?: string;
+}
+/** 난이도/음절수/품사/유형 필터를 단어 하나에 대해 판정(의미범주 제외 — WordEntry 전용이라 applyFilters에서 별도 처리). */
+export declare function matchesFilters(word: FilterableWord, filterSelected: Record<string, string[]>, keys?: PairFilterKeys): boolean;
+export declare function applyFilters(filterSelected: Record<string, string[]>, words: WordEntry[], keys?: PairFilterKeys): WordEntry[];
+export declare function searchPairs(selectedList: Record<string, string>[], words: WordEntry[], enforcePosition?: number, phonemic?: boolean): WordSearchResultItem[];
+export declare function searchWordsByPhonemes(requiredPhonemes: Record<string, string>[], words: WordEntry[], ordered?: boolean, phonemic?: boolean, phonemeMatchMode?: 'contain' | 'contrast', 
+/** 제공 시, 같은 단어쌍이 두 방향(어느 쪽이 target/1번인지)으로 모두 성립할 때
+ *  이 조건을 만족하는 쪽을 우선한다(예: "검색 단어만" 필터 통과 여부). 지정하지
+ *  않으면 기존 동작(먼저 발견된 방향을 그대로 채택)과 동일하다. */
+preferAsTarget?: (word: FilterableWord) => boolean): WordSearchResultItem[];

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

@@ -0,0 +1,583 @@
+import { VOWEL_TO_PHONEME } from './phonemeConvert';
+// ── 음절 분해 ──────────────────────────────────────────────
+const CHO = ['ㄱ', 'ㄲ', 'ㄴ', 'ㄷ', 'ㄸ', 'ㄹ', 'ㅁ', 'ㅂ', 'ㅃ', 'ㅅ', 'ㅆ', 'ㅇ', 'ㅈ', 'ㅉ', 'ㅊ', 'ㅋ', 'ㅌ', 'ㅍ', 'ㅎ'];
+const JUNG = ['ㅏ', 'ㅐ', 'ㅑ', 'ㅒ', 'ㅓ', 'ㅔ', 'ㅕ', 'ㅖ', 'ㅗ', 'ㅘ', 'ㅙ', 'ㅚ', 'ㅛ', 'ㅜ', 'ㅝ', 'ㅞ', 'ㅟ', 'ㅠ', 'ㅡ', 'ㅢ', 'ㅣ'];
+const JONG = ['', 'ㄱ', 'ㄲ', 'ㄳ', 'ㄴ', 'ㄵ', 'ㄶ', 'ㄷ', 'ㄹ', 'ㄺ', 'ㄻ', 'ㄼ', 'ㄽ', 'ㄾ', 'ㄿ', 'ㅀ', 'ㅁ', 'ㅂ', 'ㅄ', 'ㅅ', 'ㅆ', 'ㅇ', 'ㅈ', 'ㅊ', 'ㅋ', 'ㅌ', 'ㅍ', 'ㅎ'];
+function decompose(char) {
+    const code = char.charCodeAt(0) - 0xAC00;
+    if (code < 0 || code > 11171)
+        return null;
+    return {
+        초성: CHO[Math.floor(code / 588)],
+        모음: JUNG[Math.floor((code % 588) / 28)],
+        종성: JONG[code % 28] || '',
+    };
+}
+const SECTION_KEYS = ['초성', '모음', '종성', '활음'];
+function isSectionKey(value) {
+    return SECTION_KEYS.includes(value);
+}
+// 발음형 분해: 모음을 활음 + 핵모음으로 분리
+const VOWEL_GLIDE = {
+    ㅑ: 'j', ㅒ: 'j', ㅕ: 'j', ㅖ: 'j', ㅛ: 'j', ㅠ: 'j',
+    ㅘ: 'w', ㅙ: 'w', ㅚ: 'w', ㅝ: 'w', ㅞ: 'w', ㅟ: 'w',
+    ㅢ: 'ɰ',
+};
+// 모음 → 대표 핵모음(활음 제거). phonemeConvert.VOWEL_TO_PHONEME을 단일 출처로 파생한다
+// (ㅐ/ㅔ 계열 합산, ㅚ/ㅙ/ㅞ→ㅔ/ㅐ, ㅘ→ㅏ 등 합산 규칙이 그 맵에 정의돼 있음).
+const VOWEL_NUCLEUS = Object.fromEntries(Object.entries(VOWEL_TO_PHONEME).map(([v, { nucleus }]) => [v, nucleus]));
+// 발음형: 초성 ㅇ → '없음', 종성 없음 → '없음'
+function decomposePhonemicSyllable(char) {
+    const code = char.charCodeAt(0) - 0xAC00;
+    if (code < 0 || code > 11171)
+        return null;
+    const choIdx = Math.floor(code / 588);
+    const jungIdx = Math.floor((code % 588) / 28);
+    const jongIdx = code % 28;
+    const rawCho = CHO[choIdx];
+    const rawJung = JUNG[jungIdx];
+    const rawJong = JONG[jongIdx];
+    return {
+        초성: rawCho === 'ㅇ' ? '없음' : rawCho,
+        활음: VOWEL_GLIDE[rawJung] ?? '없음',
+        모음: VOWEL_NUCLEUS[rawJung] ?? rawJung,
+        종성: rawJong || '없음',
+    };
+}
+function analyzeMinimalPair(word1, word2, phonemic = false) {
+    const chars1 = [...word1];
+    const chars2 = [...word2];
+    if (chars1.length !== chars2.length) {
+        return { ok: false, reason: 'different_length' };
+    }
+    const decomposeFn = phonemic ? decomposePhonemicSyllable : decompose;
+    const syllables1 = [];
+    const syllables2 = [];
+    let diffIdx = -1;
+    const diffs = {};
+    for (let i = 0; i < chars1.length; i++) {
+        const s1 = decomposeFn(chars1[i]);
+        const s2 = decomposeFn(chars2[i]);
+        if (!s1 || !s2) {
+            return { ok: false, reason: 'invalid_pronunciation' };
+        }
+        syllables1.push(s1);
+        syllables2.push(s2);
+        const diffSections = SECTION_KEYS.filter(s => s1[s] !== s2[s]);
+        if (diffSections.length === 0)
+            continue;
+        if (diffSections.length > 1)
+            return { ok: false, reason: 'multiple_differences' };
+        if (diffIdx !== -1 && diffIdx !== i)
+            return { ok: false, reason: 'multiple_positions' };
+        diffIdx = i;
+        const sec = diffSections[0];
+        diffs[sec] = [s1[sec] ?? '', s2[sec] ?? ''];
+    }
+    if (diffIdx === -1) {
+        return { ok: false, reason: 'no_difference' };
+    }
+    return { ok: true, diff: { idx: diffIdx, diffs, syllables1, syllables2 } };
+}
+/**
+ * 두 단어의 (한 자리) 음소 차이가 '음절 구조' 차이인지 — 즉 빈 음소가 낀 대립인지 판정.
+ * 구조 차이로 보는 경우: 받침 없음('' / '없음'), 그리고 초성 ㅇ(영형태/무자음).
+ * (초성 ㅇ은 실제 자음이 아니라 '초성 없음'이므로, wordContrast.hasStructureContrast와 동일하게
+ *  초성 자리에서 ㅇ↔자음은 자음 교체가 아니라 구조 차이로 취급한다. '음소 구조 같은 단어만' 필터용.)
+ */
+function diffHasEmptyPair(section, vals) {
+    if (!vals)
+        return false;
+    // 구조상 '비움'으로 보는 경우만 true:
+    //  - 종성: 받침 없음('없음' / '')
+    //  - 초성: 무자음 ㅇ (글자 분해='ㅇ' / 발음 분해='없음')
+    // 활음 '없음'은 제외한다 — 활음 유무(예: ㅐ↔ㅙ = 없음↔w)는 음절 '구조' 차이가 아니라
+    // 정당한 '모음 대립'이므로(글자 모드도 ㅐ↔ㅙ를 모음 대립으로 인정) 걸러내면 안 된다.
+    const isEmpty = (v) => v === '' ||
+        (section === '종성' && v === '없음') ||
+        (section === '초성' && (v === 'ㅇ' || v === '없음'));
+    if (isEmpty(vals[0]) || isEmpty(vals[1]))
+        return true;
+    // 모음(글자 모드) 활음 구조 차이: 두 모음의 반모음(활음)이 다르면 음절 '구조' 차이로 본다.
+    //  예) ㅓ(단모음) ↔ ㅟ(w+ㅣ), ㅏ ↔ ㅘ(w+ㅏ), ㅐ ↔ ㅙ(w+ㅐ) → 구조 상이 → 제외.
+    //  같은 활음끼리(ㅏ↔ㅓ 둘 다 없음, ㅑ↔ㅕ 둘 다 j)는 정당한 모음 대립 → 유지.
+    //  발음 모드는 모음=핵모음이라 VOWEL_GLIDE에 없어(둘 다 '') 영향 없음. 활음 대립은
+    //  별도 '활음' 섹션에서 처리되므로 여기(모음)에서 걸러도 활음 지정 대립과 충돌하지 않는다.
+    if (section === '모음') {
+        const glideOf = (v) => VOWEL_GLIDE[v] ?? '';
+        if (glideOf(vals[0]) !== glideOf(vals[1]))
+            return true;
+    }
+    return false;
+}
+// ── 필터 적용 ──────────────────────────────────────────────
+const WORD_TYPE_MAP_KO = { '고유어': '고유', '한자어': '한자', '외래어': '외래', '혼종어': '혼종' };
+const POS_GROUP_MAP_KO = {
+    '체언(명사,수사)': ['명', '수'],
+    '용언(동사,형용사)': ['동', '형'],
+    '수식언(부사,관형사)': ['부', '관'],
+};
+const DEFAULT_PAIR_FILTER_KEYS = {
+    difficulty: '난이도 등급',
+    syllables: '음절 수',
+    syllable5plus: '5음절 이상',
+    partOfSpeech: '품사',
+    wordType: '유형',
+    posMap: POS_GROUP_MAP_KO,
+    typeMap: WORD_TYPE_MAP_KO,
+};
+/** 난이도/음절수/품사/유형 필터를 단어 하나에 대해 판정(의미범주 제외 — WordEntry 전용이라 applyFilters에서 별도 처리). */
+export function matchesFilters(word, filterSelected, keys = DEFAULT_PAIR_FILTER_KEYS) {
+    const grades = filterSelected[keys.difficulty];
+    if (grades?.length && !grades.some(g => word.grade === g.replace(/\D/g, '')))
+        return false;
+    const syls = filterSelected[keys.syllables];
+    if (syls?.length) {
+        const len = word.syllables ?? 0;
+        const match = syls.some(syl => {
+            if (syl === keys.syllable5plus)
+                return len >= 5;
+            return len === parseInt(syl);
+        });
+        if (!match)
+            return false;
+    }
+    const poses = filterSelected[keys.partOfSpeech];
+    if (poses?.length) {
+        const targets = poses.flatMap(pos => keys.posMap[pos] ?? [pos]);
+        if (!targets.some(p => (word.pos ?? '').includes(p)))
+            return false;
+    }
+    const types = filterSelected[keys.wordType];
+    if (types?.length && !types.some(t => word.wordType === keys.typeMap[t]))
+        return false;
+    return true;
+}
+export function applyFilters(filterSelected, words, keys = DEFAULT_PAIR_FILTER_KEYS) {
+    return words.filter(entry => {
+        if (!matchesFilters({ grade: entry.grade, syllables: [...entry.word].length, pos: entry.pos, wordType: entry.wordType }, filterSelected, keys))
+            return false;
+        const fields = filterSelected['의미범주'];
+        if (fields?.length) {
+            const normalized = (entry.field ?? '').replace(/전문\(|\)/g, '');
+            if (!fields.some(f => normalized.includes(f)))
+                return false;
+        }
+        return true;
+    });
+}
+// ── 대립쌍 검색 ────────────────────────────────────────────
+const cleanPron = (p) => p.replace(/^\[|\]$/g, '');
+function validateBySelections(diff, bySection, contrastSections, bySectionValueOrder) {
+    const diffedSections = Object.keys(diff.diffs).filter(isSectionKey);
+    const selectedSections = Object.keys(bySection).filter(isSectionKey);
+    // 변화된 섹션이 선택된 섹션에 포함되어야 함
+    for (const section of diffedSections) {
+        if (!bySection[section]) {
+            return { ok: false, reason: 'changed_section_not_selected' };
+        }
+    }
+    // 선택된 섹션 중 contrast(2개+)인데 변화가 없는 섹션은 거부
+    for (const section of contrastSections) {
+        if (!diff.diffs[section]) {
+            return { ok: false, reason: 'changed_section_not_in_contrast' };
+        }
+    }
+    for (const section of selectedSections) {
+        const vals = bySection[section];
+        if (!vals || vals.size === 0)
+            continue;
+        const sectionDiff = diff.diffs[section];
+        const v1 = diff.syllables1[diff.idx][section] ?? '';
+        const v2 = diff.syllables2[diff.idx][section] ?? '';
+        if (sectionDiff) {
+            // 변화가 있는 섹션: 선택값과 대조
+            if (vals.size >= 2) {
+                if (!(vals.has(v1) && vals.has(v2))) {
+                    return { ok: false, reason: 'contrast_section_values_mismatch' };
+                }
+            }
+            else {
+                // 단일 값 선택 시 섹션이 달라지는 쌍은 거부 (ㄱ vs ㄱ 처럼 동일값 선택)
+                return { ok: false, reason: 'single_section_value_mismatch' };
+            }
+        }
+        else {
+            // 변화가 없는 섹션: 두 단어의 값이 선택값과 일치해야 함 (문맥 조건)
+            if (!vals.has(v1)) {
+                return { ok: false, reason: 'context_value_mismatch' };
+            }
+        }
+    }
+    // word1의 대조값이 더 늦은 포지션에서 선택된 값이면 swap
+    // (선택 순서가 곧 결과 쌍의 순서를 결정함)
+    let shouldSwap = false;
+    for (const section of selectedSections) {
+        const sectionDiff = diff.diffs[section];
+        if (!sectionDiff)
+            continue;
+        const [from, to] = sectionDiff;
+        const valueOrder = bySectionValueOrder[section];
+        if (!valueOrder)
+            continue;
+        const orderFrom = valueOrder.get(from) ?? Infinity;
+        const orderTo = valueOrder.get(to) ?? Infinity;
+        if (orderFrom > orderTo) {
+            shouldSwap = true;
+            break;
+        }
+    }
+    return { ok: true, shouldSwap };
+}
+function createRejectCounter() {
+    return {
+        different_length: 0,
+        invalid_pronunciation: 0,
+        no_difference: 0,
+        multiple_differences: 0,
+        multiple_positions: 0,
+        changed_section_not_selected: 0,
+        changed_section_not_in_contrast: 0,
+        contrast_section_values_mismatch: 0,
+        single_section_value_mismatch: 0,
+        context_value_mismatch: 0,
+    };
+}
+function searchPairsCore(selectedList, words, debug, enforcePosition, phonemic = false) {
+    const uniqueWordsCount = new Set(words.map(w => w.word)).size;
+    const bySection = {};
+    const bySectionValueOrder = {};
+    for (let i = 0; i < selectedList.length; i++) {
+        for (const [section, value] of Object.entries(selectedList[i])) {
+            if (!isSectionKey(section))
+                continue;
+            if (!bySection[section])
+                bySection[section] = new Set();
+            if (!bySectionValueOrder[section])
+                bySectionValueOrder[section] = new Map();
+            bySection[section].add(value);
+            if (!bySectionValueOrder[section].has(value))
+                bySectionValueOrder[section].set(value, i);
+        }
+    }
+    const sectionEntries = Object.entries(bySection).filter(([, vals]) => vals.size > 0);
+    if (sectionEntries.length === 0) {
+        return {
+            results: [],
+            ...(debug
+                ? {
+                    report: {
+                        selectedBySection: {},
+                        totalWords: words.length,
+                        uniqueWords: uniqueWordsCount,
+                        groupCount: 0,
+                        comparedPairs: 0,
+                        matchedPairs: 0,
+                        rejectCounts: createRejectCounter(),
+                        rejectSamples: [],
+                        results: [],
+                    },
+                }
+                : {}),
+        };
+    }
+    const targetKeys = new Set(sectionEntries.map(([s]) => s));
+    const contrastSections = new Set(sectionEntries.filter(([, vals]) => vals.size >= 2).map(([s]) => s));
+    const encodeAll = phonemic
+        ? (s) => s.초성 + (s.활음 ?? '') + s.모음 + s.종성
+        : (s) => s.초성 + s.모음 + s.종성;
+    const encodeWild = phonemic
+        ? (s) => (targetKeys.has('초성') ? '*' : s.초성) +
+            (targetKeys.has('활음') ? '*' : (s.활음 ?? '')) +
+            (targetKeys.has('모음') ? '*' : s.모음) +
+            (targetKeys.has('종성') ? '*' : s.종성)
+        : (s) => (targetKeys.has('초성') ? '*' : s.초성) +
+            (targetKeys.has('모음') ? '*' : s.모음) +
+            (targetKeys.has('종성') ? '*' : s.종성);
+    const makeKeyForPosition = (syllables, diffPos) => syllables.map((s, i) => (i === diffPos ? encodeWild(s) : encodeAll(s))).join('|');
+    const gradeOrder = (g) => {
+        const parsed = Number.parseInt(g ?? '', 10);
+        return Number.isFinite(parsed) ? parsed : 99;
+    };
+    const groups = new Map();
+    const seenWords = new Set();
+    for (const entry of words) {
+        if (seenWords.has(entry.word))
+            continue;
+        seenWords.add(entry.word);
+        const decomposeFn = phonemic ? decomposePhonemicSyllable : decompose;
+        const syllables = [...cleanPron(entry.pronunciation)].map(decomposeFn);
+        if (syllables.some(s => s === null))
+            continue;
+        const syls = syllables;
+        for (let p = 0; p < syls.length; p++) {
+            const key = makeKeyForPosition(syls, p);
+            if (!groups.has(key))
+                groups.set(key, []);
+            groups.get(key).push(entry);
+        }
+    }
+    const results = [];
+    const seenPairs = new Set();
+    const rejectCounts = createRejectCounter();
+    const rejectSamples = [];
+    let comparedPairs = 0;
+    for (const group of groups.values()) {
+        if (group.length < 2)
+            continue;
+        for (let i = 0; i < group.length; i++) {
+            for (let j = i + 1; j < group.length; j++) {
+                const w1 = group[i];
+                const w2 = group[j];
+                const dedupKey = w1.word < w2.word ? `${w1.word}|${w2.word}` : `${w2.word}|${w1.word}`;
+                if (seenPairs.has(dedupKey))
+                    continue;
+                seenPairs.add(dedupKey);
+                comparedPairs += 1;
+                const pairId = `${w1.word}|${w2.word}`;
+                const analysis = analyzeMinimalPair(cleanPron(w1.pronunciation), cleanPron(w2.pronunciation), phonemic);
+                if (analysis.ok && enforcePosition !== undefined && analysis.diff.idx !== enforcePosition)
+                    continue;
+                if (!analysis.ok) {
+                    rejectCounts[analysis.reason] += 1;
+                    if (debug && rejectSamples.length < 20) {
+                        rejectSamples.push({ id: pairId, reason: analysis.reason });
+                    }
+                    continue;
+                }
+                const matched = validateBySelections(analysis.diff, bySection, contrastSections, bySectionValueOrder);
+                if (!matched.ok) {
+                    rejectCounts[matched.reason] += 1;
+                    if (debug && rejectSamples.length < 20) {
+                        rejectSamples.push({ id: pairId, reason: matched.reason });
+                    }
+                    continue;
+                }
+                const [first, second] = matched.shouldSwap ? [w2, w1] : [w1, w2];
+                const sDiffSection = Object.keys(analysis.diff.diffs)[0];
+                const sDiffVals = analysis.diff.diffs[sDiffSection];
+                const sDiffHasEmpty = diffHasEmptyPair(sDiffSection, sDiffVals);
+                results.push({
+                    id: `${first.word}|${second.word}`,
+                    diffSection: sDiffSection,
+                    diffHasEmpty: sDiffHasEmpty,
+                    words: [
+                        { label: first.word, subLabel: first.pronunciation, colloquialLabel: first.colloquialPronunciation, homonum: first.homonum, grade: first.grade, syllables: [...first.word].length, pos: first.pos, wordType: first.wordType, isCustom: first.isCustom },
+                        { label: second.word, subLabel: second.pronunciation, colloquialLabel: second.colloquialPronunciation, homonum: second.homonum, grade: second.grade, syllables: [...second.word].length, pos: second.pos, wordType: second.wordType, isCustom: second.isCustom },
+                    ],
+                });
+            }
+        }
+    }
+    // 결과에 이미 담긴 등급으로 정렬한다. 같은 단어가 등급만 다르게 여러 번 들어온 풀에서
+    // (현재 풀에 중복 엔트리가 있다) 단어→등급 맵을 따로 만들면 '마지막' 엔트리가 이기는 반면
+    // 결과에 표시되는 등급은 그룹핑에 쓴 '첫' 엔트리라, 화면엔 등급 1로 보이는 쌍이 등급 9로
+    // 정렬돼 뒤로 밀렸다.
+    results.sort((a, b) => {
+        const gradeA = Math.min(...a.words.map(w => gradeOrder(w.grade)));
+        const gradeB = Math.min(...b.words.map(w => gradeOrder(w.grade)));
+        return gradeA - gradeB;
+    });
+    if (!debug) {
+        return { results };
+    }
+    const selectedBySection = Object.fromEntries(Object.entries(bySection).map(([section, values]) => [section, [...values]]));
+    return {
+        results,
+        report: {
+            selectedBySection,
+            totalWords: words.length,
+            uniqueWords: seenWords.size,
+            groupCount: groups.size,
+            comparedPairs,
+            matchedPairs: results.length,
+            rejectCounts,
+            rejectSamples,
+            results,
+        },
+    };
+}
+export function searchPairs(selectedList, words, enforcePosition, phonemic = false) {
+    return searchPairsCore(selectedList, words, false, enforcePosition, phonemic).results;
+}
+// ── 포함 검색: 음소를 모두 포함하는 단어의 대립쌍 ─────────────
+// 슬롯 i → 단어의 i번째 음절에 조건 매칭 (순서 보장)
+function wordContainsAllPhonemes(syllables, requirements) {
+    for (let i = 0; i < requirements.length; i++) {
+        const entries = Object.entries(requirements[i]).filter(([k]) => isSectionKey(k));
+        if (entries.length === 0)
+            continue;
+        const syl = syllables[i];
+        if (!syl)
+            return false;
+        if (!entries.every(([section, value]) => (syl[section] ?? '') === value))
+            return false;
+    }
+    return true;
+}
+// 순서 무관: 각 조건을 서로 다른 음절에 매칭 (한 음절이 두 조건을 중복 충족하지 않도록)
+function wordContainsAllPhonemesUnordered(syllables, requirements) {
+    const used = new Set();
+    for (const req of requirements) {
+        const entries = Object.entries(req).filter(([k]) => isSectionKey(k));
+        if (entries.length === 0)
+            continue;
+        const idx = syllables.findIndex((syl, i) => !used.has(i) && entries.every(([section, value]) => (syl[section] ?? '') === value));
+        if (idx === -1)
+            return false;
+        used.add(idx);
+    }
+    return true;
+}
+export function searchWordsByPhonemes(requiredPhonemes, words, ordered = true, phonemic = false, phonemeMatchMode = 'contain', 
+/** 제공 시, 같은 단어쌍이 두 방향(어느 쪽이 target/1번인지)으로 모두 성립할 때
+ *  이 조건을 만족하는 쪽을 우선한다(예: "검색 단어만" 필터 통과 여부). 지정하지
+ *  않으면 기존 동작(먼저 발견된 방향을 그대로 채택)과 동일하다. */
+preferAsTarget) {
+    const reqs = requiredPhonemes.filter(r => Object.keys(r).some(k => isSectionKey(k)));
+    if (reqs.length === 0)
+        return [];
+    const encodeAll = phonemic
+        ? (s) => s.초성 + (s.활음 ?? '') + s.모음 + s.종성
+        : (s) => s.초성 + s.모음 + s.종성;
+    const makeKey = (syls, pos) => syls.map((s, i) => (i === pos ? '*' : encodeAll(s))).join('|');
+    const decomposeFn = phonemic ? decomposePhonemicSyllable : decompose;
+    const allWords = [];
+    const seenWords = new Set();
+    for (const entry of words) {
+        if (seenWords.has(entry.word))
+            continue;
+        seenWords.add(entry.word);
+        const syls = [...cleanPron(entry.pronunciation)].map(decomposeFn);
+        if (syls.some(s => s === null))
+            continue;
+        // 글자 선택 모드: 대상 필터링은 실제 철자(entry.word) 기준으로
+        const wordSyls = !phonemic
+            ? ([...entry.word].map(decompose).every(s => s !== null)
+                ? [...entry.word].map(decompose)
+                : null)
+            : null;
+        allWords.push({ entry, syls: syls, wordSyls });
+    }
+    const targetWords = allWords.filter(({ syls, wordSyls }) => {
+        const filterSyls = !phonemic && wordSyls ? wordSyls : syls;
+        return ordered
+            ? wordContainsAllPhonemes(filterSyls, reqs)
+            : wordContainsAllPhonemesUnordered(filterSyls, reqs);
+    });
+    const groups = new Map();
+    for (const w of allWords) {
+        for (let p = 0; p < w.syls.length; p++) {
+            const key = makeKey(w.syls, p);
+            if (!groups.has(key))
+                groups.set(key, []);
+            groups.get(key).push(w);
+        }
+    }
+    const results = [];
+    // dedupKey → results 배열 내 인덱스. 같은 두 단어가 서로 minimal pair이면서
+    // 둘 다 독립적으로 targetWords에 속할 수 있어(예: 다른 음절에 요구 음소가 하나 더 있는 경우),
+    // 어느 쪽을 target(1번/words[0])으로 채택할지가 순회 순서에 좌우될 수 있다.
+    // preferAsTarget이 주어지면(예: "검색 단어만" 필터) 그 조건을 만족하는 방향을 우선한다.
+    const seenPairs = new Map();
+    for (const target of targetWords) {
+        for (let p = 0; p < target.syls.length; p++) {
+            const key = makeKey(target.syls, p);
+            const candidates = groups.get(key) ?? [];
+            for (const candidate of candidates) {
+                if (candidate.entry.word === target.entry.word)
+                    continue;
+                const dedupKey = target.entry.word < candidate.entry.word
+                    ? `${target.entry.word}|${candidate.entry.word}`
+                    : `${candidate.entry.word}|${target.entry.word}`;
+                const existingIdx = seenPairs.get(dedupKey);
+                if (existingIdx !== undefined) {
+                    if (!preferAsTarget)
+                        continue;
+                    if (preferAsTarget(results[existingIdx].words[0]))
+                        continue;
+                    if (!preferAsTarget({ grade: target.entry.grade, syllables: [...target.entry.word].length, pos: target.entry.pos, wordType: target.entry.wordType }))
+                        continue;
+                    // existing은 선호 조건 미충족, 새 방향(target)은 충족 — 교체
+                }
+                const analysis = analyzeMinimalPair(cleanPron(target.entry.pronunciation), cleanPron(candidate.entry.pronunciation), phonemic);
+                if (!analysis.ok)
+                    continue;
+                // 대비 모드: 선택한 음소가 실제로 대비되는 쌍만 허용
+                if (phonemeMatchMode === 'contrast') {
+                    const diffSection = Object.keys(analysis.diff.diffs)[0];
+                    let diffValues = analysis.diff.diffs[diffSection];
+                    // 글자 선택 모드: 사용자는 '철자'로 음소를 골랐으므로, 발음 분해값이 아니라 철자 분해값으로
+                    // 대비 관련성을 판정한다. 표준발음 데이터가 ㅔ/ㅐ를 병합(예: 게→발음 ㅐ)하는 탓에, 철자 ㅔ를
+                    // 고른 사용자에게 발음값 ㅐ로 비교하면 모두 탈락해 0건이 되던 문제를 바로잡는다.
+                    if (!phonemic && target.wordSyls && candidate.wordSyls) {
+                        const idx = analysis.diff.idx;
+                        const tv = target.wordSyls[idx]?.[diffSection] ?? '';
+                        const cv = candidate.wordSyls[idx]?.[diffSection] ?? '';
+                        if (tv !== cv)
+                            diffValues = [tv, cv];
+                    }
+                    const isRelevant = reqs.some(req => {
+                        const reqVal = req[diffSection];
+                        return reqVal !== undefined && (diffValues[0] === reqVal || diffValues[1] === reqVal);
+                    });
+                    if (!isRelevant)
+                        continue;
+                }
+                const diffSection = Object.keys(analysis.diff.diffs)[0];
+                const diffVals = analysis.diff.diffs[diffSection];
+                const diffHasEmpty = diffHasEmptyPair(diffSection, diffVals);
+                const item = {
+                    id: dedupKey,
+                    diffSection,
+                    diffHasEmpty,
+                    words: [
+                        {
+                            label: target.entry.word,
+                            subLabel: target.entry.pronunciation,
+                            colloquialLabel: target.entry.colloquialPronunciation,
+                            homonum: target.entry.homonum,
+                            grade: target.entry.grade,
+                            syllables: [...target.entry.word].length,
+                            pos: target.entry.pos,
+                            wordType: target.entry.wordType,
+                            isCustom: target.entry.isCustom,
+                        },
+                        {
+                            label: candidate.entry.word,
+                            subLabel: candidate.entry.pronunciation,
+                            colloquialLabel: candidate.entry.colloquialPronunciation,
+                            homonum: candidate.entry.homonum,
+                            grade: candidate.entry.grade,
+                            syllables: [...candidate.entry.word].length,
+                            pos: candidate.entry.pos,
+                            wordType: candidate.entry.wordType,
+                            isCustom: candidate.entry.isCustom,
+                        },
+                    ],
+                };
+                if (existingIdx !== undefined) {
+                    results[existingIdx] = item;
+                }
+                else {
+                    seenPairs.set(dedupKey, results.length);
+                    results.push(item);
+                }
+            }
+        }
+    }
+    const gradeOrder = (g) => {
+        const parsed = Number.parseInt(g ?? '', 10);
+        return Number.isFinite(parsed) ? parsed : 99;
+    };
+    // 결과에 이미 담긴 등급으로 정렬한다. 같은 단어가 등급만 다르게 여러 번 들어온 풀에서
+    // (현재 풀에 중복 엔트리가 있다) 단어→등급 맵을 따로 만들면 '마지막' 엔트리가 이기는 반면
+    // 결과에 표시되는 등급은 그룹핑에 쓴 '첫' 엔트리라, 화면엔 등급 1로 보이는 쌍이 등급 9로
+    // 정렬돼 뒤로 밀렸다.
+    results.sort((a, b) => {
+        const gradeA = Math.min(...a.words.map(w => gradeOrder(w.grade)));
+        const gradeB = Math.min(...b.words.map(w => gradeOrder(w.grade)));
+        return gradeA - gradeB;
+    });
+    return results;
+}

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

@@ -0,0 +1,46 @@
+import type { WordSearchResultItem } from '../types/wordSearch';
+export interface WordEntry {
+    word: string;
+    pronunciation: string;
+    colloquialPronunciation?: string;
+    grade?: string;
+    pos?: string;
+    wordType?: string;
+    field?: string;
+    homonum?: number;
+    /** 뜻(사전 정의). 사전 원본 단어는 useWordMeanings로 온디맨드 조회하므로 보통 비어 있고,
+     *  개인 추가 단어처럼 사전에 없는 항목만 이 필드에 직접 저장한다. */
+    meaning?: string;
+    /**
+     * 사용자가 '단어 관리'에서 직접 추가한 개인 단어인지. 검색 풀에 머지될 때(App) 표시되어
+     * 검색 결과 → 단어표·훈련 저장까지 따라간다. 이 단어가 든 콘텐츠는 공유·발행이 막힌다
+     * (받는 쪽 사전에는 없는 단어라 훈련이 깨지기 때문).
+     */
+    isCustom?: boolean;
+}
+/** Optional i18n key overrides — pass when filter items are displayed with translated labels */
+export interface PairFilterKeys {
+    difficulty: string;
+    syllables: string;
+    syllable5plus: string;
+    partOfSpeech: string;
+    wordType: string;
+    posMap: Record<string, string[]>;
+    typeMap: Record<string, string>;
+}
+export type RejectReason = 'different_length' | 'invalid_pronunciation' | 'no_difference' | 'multiple_differences' | 'multiple_positions' | 'changed_section_not_selected' | 'changed_section_not_in_contrast' | 'contrast_section_values_mismatch' | 'single_section_value_mismatch' | 'context_value_mismatch';
+export interface DebugCandidate {
+    id: string;
+    reason: RejectReason;
+}
+export interface SearchPairsDebugReport {
+    selectedBySection: Record<string, string[]>;
+    totalWords: number;
+    uniqueWords: number;
+    groupCount: number;
+    comparedPairs: number;
+    matchedPairs: number;
+    rejectCounts: Record<RejectReason, number>;
+    rejectSamples: DebugCandidate[];
+    results: WordSearchResultItem[];
+}

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

@@ -0,0 +1 @@
+export {};