@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,654 @@
+/**
+ * 한글 음절 분해/조립/거리 계산 유틸
+ * @public
+ */
+export const CHOSEONG = ['ㄱ', 'ㄲ', 'ㄴ', 'ㄷ', 'ㄸ', 'ㄹ', 'ㅁ', 'ㅂ', 'ㅃ', 'ㅅ', 'ㅆ', 'ㅇ', 'ㅈ', 'ㅉ', 'ㅊ', 'ㅋ', 'ㅌ', 'ㅍ', 'ㅎ'];
+export const JUNGSEONG = ['ㅏ', 'ㅐ', 'ㅑ', 'ㅒ', 'ㅓ', 'ㅔ', 'ㅕ', 'ㅖ', 'ㅗ', 'ㅘ', 'ㅙ', 'ㅚ', 'ㅛ', 'ㅜ', 'ㅝ', 'ㅞ', 'ㅟ', 'ㅠ', 'ㅡ', 'ㅢ', 'ㅣ'];
+/** 종성 0번은 받침 없음 */
+export const JONGSEONG = ['', 'ㄱ', 'ㄲ', 'ㄳ', 'ㄴ', 'ㄵ', 'ㄶ', 'ㄷ', 'ㄹ', 'ㄺ', 'ㄻ', 'ㄼ', 'ㄽ', 'ㄾ', 'ㄿ', 'ㅀ', 'ㅁ', 'ㅂ', 'ㅄ', 'ㅅ', 'ㅆ', 'ㅇ', 'ㅈ', 'ㅊ', 'ㅋ', 'ㅌ', 'ㅍ', 'ㅎ'];
+/** @public 한 글자를 초/중/종성으로 분해. 한글 음절이 아니면 null. */
+export function parseSyllable(ch) {
+    if (!ch)
+        return null;
+    const code = ch.charCodeAt(0) - 0xAC00;
+    if (code < 0 || code >= 11172)
+        return null;
+    return {
+        cho: Math.floor(code / (21 * 28)),
+        jung: Math.floor((code % (21 * 28)) / 28),
+        jong: code % 28,
+    };
+}
+/**
+ * @public 단어→음절 분해 배열 캐시 팩토리. `[...word].map(parseSyllable)`를 단어당 1회만 수행한다.
+ * 캐시 수명은 호출부가 소유한다 — 모듈 레벨에 두면 영속, 함수 안에 두면 호출당 새 캐시.
+ * (프리뷰 편집기와 wordTrainingRuntime이 동일 로직을 중복 정의하던 것을 단일화.)
+ */
+export function createDecompCache() {
+    const cache = new Map();
+    return (word) => {
+        let d = cache.get(word);
+        if (!d) {
+            d = [...word].map(ch => parseSyllable(ch));
+            cache.set(word, d);
+        }
+        return d;
+    };
+}
+/** @public 초/중/종성 index로 한글 음절 조립. */
+export function composeSyllable(cho, jung, jong = 0) {
+    return String.fromCharCode(0xAC00 + (cho * 21 + jung) * 28 + jong);
+}
+export function classifyPairDifficulty(a, b) {
+    if (!a || !b || a === b)
+        return 'random';
+    if (a.length !== b.length)
+        return 'random';
+    let diffSyllableCount = 0;
+    let lastDiff = null;
+    for (let i = 0; i < a.length; i++) {
+        const sa = parseSyllable(a[i]);
+        const sb = parseSyllable(b[i]);
+        if (!sa || !sb)
+            return 'random';
+        if (sa.cho === sb.cho && sa.jung === sb.jung && sa.jong === sb.jong)
+            continue;
+        diffSyllableCount++;
+        const choDiff = sa.cho !== sb.cho;
+        const jungDiff = sa.jung !== sb.jung;
+        const jongDiff = sa.jong !== sb.jong;
+        const cnt = (choDiff ? 1 : 0) + (jungDiff ? 1 : 0) + (jongDiff ? 1 : 0);
+        if (cnt > 1)
+            lastDiff = 'multi';
+        else if (choDiff)
+            lastDiff = 'cho';
+        else if (jungDiff)
+            lastDiff = 'jung';
+        else
+            lastDiff = 'jong';
+    }
+    if (diffSyllableCount !== 1)
+        return 'random';
+    if (lastDiff === 'cho')
+        return 'cho';
+    if (lastDiff === 'jung')
+        return 'jung';
+    if (lastDiff === 'jong')
+        return 'jong';
+    return 'random';
+}
+/** @public 단어의 초성 자모 ('가구' → 'ㄱ') */
+export function firstChoseongOf(word) {
+    const s = parseSyllable(word[0] || '');
+    return s ? CHOSEONG[s.cho] : '';
+}
+/** @public 문자열 전체를 초성으로 변환 ('한지민' → 'ㅎㅈㅁ'). 한글 음절이 아닌 문자는 그대로 유지. */
+export function toChoseong(text) {
+    return [...text].map(ch => {
+        const s = parseSyllable(ch);
+        return s ? CHOSEONG[s.cho] : ch;
+    }).join('');
+}
+/** @public 검색어가 초성으로만 이루어졌는지 (예: 'ㅎㅈ' → true, '한' → false) */
+export function isAllChoseong(search) {
+    return !!search && [...search].every(ch => CHOSEONG.includes(ch));
+}
+/**
+ * @public 초성 검색을 지원하는 부분 일치 매칭 — 검색어가 전부 초성이면 대상 텍스트도
+ * 초성으로 변환해 비교(예: 'ㄷ' → '단어 표' 매칭), 아니면 일반 부분 문자열 매칭.
+ */
+export function matchesChoseongSearch(text, search) {
+    if (!search)
+        return true;
+    if (isAllChoseong(search))
+        return toChoseong(text).includes(search);
+    return text.toLowerCase().includes(search.toLowerCase());
+}
+/**
+ * @public 단어 검색어 매칭(부분 일치=contains) — 검색어의 각 글자가 '완성 음절'이거나 '음소 자모'(초성·중성)인
+ * 혼합 검색을 지원한다. 완성 음절은 그 자리 음절과 정확히 같아야 하고, 자음 자모는 그 자리 음절의 초성과,
+ * 모음 자모는 그 자리 음절의 중성과 같으면 된다 — 위치(앞·중간·뒤) 무관.
+ * 예: 'ㄱ'→'가수'(초성 ㄱ), 'ㅏ'→'가수'(중성 ㅏ), 'ㄱㅅ'→'가수', '가ㄴ'→'가난', 'ㄱ수'→'가수', '가수'→'가수'.
+ * 검색어에 종성 겹자모·비한글 등 위 종류가 아닌 문자가 있으면 일반 부분 문자열로 폴백한다.
+ */
+export function matchesWordQuery(word, query) {
+    if (!query)
+        return true;
+    const q = [...query];
+    const isCho = (ch) => CHOSEONG.includes(ch);
+    const isJung = (ch) => JUNGSEONG.includes(ch);
+    // 각 글자 분류: 'cho'(자음/초성) | 'jung'(모음/중성) | 'syl'(완성 음절) | 'other'(그 외)
+    const kinds = q.map(ch => (isCho(ch) ? 'cho' : isJung(ch) ? 'jung' : parseSyllable(ch) ? 'syl' : 'other'));
+    if (kinds.includes('other'))
+        return word.includes(query);
+    const w = [...word];
+    for (let i = 0; i + q.length <= w.length; i++) {
+        let ok = true;
+        for (let j = 0; j < q.length; j++) {
+            const wc = w[i + j];
+            const k = kinds[j];
+            if (k === 'cho') {
+                if (firstChoseongOf(wc) !== q[j]) {
+                    ok = false;
+                    break;
+                }
+            }
+            else if (k === 'jung') {
+                const s = parseSyllable(wc);
+                if (!s || JUNGSEONG[s.jung] !== q[j]) {
+                    ok = false;
+                    break;
+                }
+            }
+            else { // 'syl' — 완성 음절
+                const qs = parseSyllable(q[j]);
+                if (qs && qs.jong === 0) {
+                    // 받침 없는 글자는 초성+중성만 비교(받침 무관): '수' → 수·술·숙·순 …
+                    const ws = parseSyllable(wc);
+                    if (!ws || ws.cho !== qs.cho || ws.jung !== qs.jung) {
+                        ok = false;
+                        break;
+                    }
+                }
+                else if (wc !== q[j]) {
+                    ok = false;
+                    break;
+                } // 받침 있으면 정확 일치
+            }
+        }
+        if (ok)
+            return true;
+    }
+    return false;
+}
+// 복합 종성 자모 분해 (예: ㄺ → ㄹ+ㄱ)
+/** @public 복합 종성 index → 구성 자모 배열 (예: 9(ㄺ) → ['ㄹ','ㄱ']) */
+export const JONG_DECOMPOSE = {
+    3: ['ㄱ', 'ㅅ'], // ㄳ
+    5: ['ㄴ', 'ㅈ'], // ㄵ
+    6: ['ㄴ', 'ㅎ'], // ㄶ
+    9: ['ㄹ', 'ㄱ'], // ㄺ
+    10: ['ㄹ', 'ㅁ'], // ㄻ
+    11: ['ㄹ', 'ㅂ'], // ㄼ
+    12: ['ㄹ', 'ㅅ'], // ㄽ
+    13: ['ㄹ', 'ㅌ'], // ㄾ
+    14: ['ㄹ', 'ㅍ'], // ㄿ
+    15: ['ㄹ', 'ㅎ'], // ㅀ
+    18: ['ㅂ', 'ㅅ'], // ㅄ
+};
+/** 겹받침 구성 2자모 문자열 → 겹받침 원형 자모. 예: 'ㄹㄱ' → 'ㄺ'. (JONG_DECOMPOSE 역맵) */
+const COMPOUND_JONG = Object.fromEntries(Object.entries(JONG_DECOMPOSE).map(([idx, parts]) => [parts.join(''), JONGSEONG[Number(idx)]]));
+/** @public 단어가 특정 자모(음소)를 어디든 (초성/종성/복합종성) 포함하는지 */
+export function wordContainsPhoneme(word, jamo) {
+    if (!word || !jamo)
+        return false;
+    for (const ch of word) {
+        const s = parseSyllable(ch);
+        if (!s)
+            continue;
+        if (CHOSEONG[s.cho] === jamo)
+            return true;
+        if (s.jong > 0) {
+            if (JONGSEONG[s.jong] === jamo)
+                return true; // 겹받침 원형 정확 매칭
+            const decomp = JONG_DECOMPOSE[s.jong];
+            if (decomp && decomp.includes(jamo))
+                return true; // 겹받침 구성 자모 매칭
+        }
+    }
+    return false;
+}
+/** @public 단어가 특정 자모를 초성(onset)으로 포함하는지 */
+export function wordContainsChoseong(word, jamo) {
+    if (!word || !jamo)
+        return false;
+    for (const ch of word) {
+        const s = parseSyllable(ch);
+        if (s && CHOSEONG[s.cho] === jamo)
+            return true;
+    }
+    return false;
+}
+/** @public 단어가 특정 모음을 중성(vowel)으로 포함하는지 */
+export function wordContainsJungseong(word, jamo) {
+    if (!word || !jamo)
+        return false;
+    for (const ch of word) {
+        const s = parseSyllable(ch);
+        if (s && JUNGSEONG[s.jung] === jamo)
+            return true;
+    }
+    return false;
+}
+/** @public 단어가 특정 자모를 종성(coda)으로 포함하는지.
+ *  글자 입력: 겹받침 '원형'(ㅄ 등) 정확 매칭. 발음 입력: 겹받침을 구성 자모(ㅂ 등)로 분해해 대표음 매칭. */
+export function wordContainsJongseong(word, jamo) {
+    if (!word || !jamo)
+        return false;
+    for (const ch of word) {
+        const s = parseSyllable(ch);
+        if (!s || s.jong <= 0)
+            continue;
+        if (JONGSEONG[s.jong] === jamo)
+            return true; // 겹받침 원형 포함 정확 매칭
+        const decomp = JONG_DECOMPOSE[s.jong];
+        if (decomp && decomp.includes(jamo))
+            return true; // 겹받침 구성 자모(대표음) 매칭
+    }
+    return false;
+}
+/** @public 단어의 한글 음절 개수 (한글 이외 문자는 제외) */
+export function syllableLength(word) {
+    if (!word)
+        return 0;
+    let n = 0;
+    for (const ch of word)
+        if (parseSyllable(ch))
+            n++;
+    return n;
+}
+/** @public 단어의 모든 한글 음절에 종성(받침)이 없는지 (열린 음절로만 구성) */
+export function wordHasNoCoda(word) {
+    if (!word)
+        return false;
+    let sawSyllable = false;
+    for (const ch of word) {
+        const s = parseSyllable(ch);
+        if (!s)
+            continue;
+        sawSyllable = true;
+        if (s.jong > 0)
+            return false;
+    }
+    return sawSyllable;
+}
+/** 한 음절(Syllable)이 주어진 종성 자모 집합 중 하나를 종성으로 갖는지.
+ *  글자 입력: 겹받침 원형 정확 매칭. 발음 입력: 겹받침 구성 자모(대표음)도 매칭. */
+function syllableJongMatches(s, jamos) {
+    if (s.jong <= 0)
+        return false;
+    if (jamos.includes(JONGSEONG[s.jong]))
+        return true;
+    const decomp = JONG_DECOMPOSE[s.jong];
+    return !!decomp && decomp.some(j => jamos.includes(j));
+}
+/**
+ * @public 단어에 '하나의 음절'이 주어진 초성/중성/종성 제약을 **모두** 만족하는지.
+ * 여러 자리를 함께 선택하면 서로 다른 음절에 흩어져 있는 게 아니라 같은 음절에서 결합해야 한다
+ * (예: 초성 ㄱ + 종성 ㅇ → '강'·'공'만 매칭, '코딩'처럼 다른 음절에 흩어진 건 제외).
+ * 각 제약은 배열(OR) — 미지정(null/undefined) 자리는 검사하지 않는다. jongNone은 그 음절이 받침 없음.
+ */
+export function wordHasSyllableMatching(word, parts, 
+// 위치 제약(선택) — 'head'=어두(첫음절), 'tail'=어말(끝음절), 'mid'=어중(가운데, 3음절+). 미지정=모든 음절.
+position) {
+    if (!word)
+        return false;
+    const chars = [...word];
+    const matchAt = (i) => {
+        const s = parseSyllable(chars[i]);
+        if (!s)
+            return false;
+        if (parts.cho && !parts.cho.includes(CHOSEONG[s.cho]))
+            return false;
+        if (parts.jung && !parts.jung.includes(JUNGSEONG[s.jung]))
+            return false;
+        if (parts.jongNone) {
+            if (s.jong > 0)
+                return false;
+        }
+        else if (parts.jong && !syllableJongMatches(s, parts.jong))
+            return false;
+        return true;
+    };
+    if (position === 'head')
+        return matchAt(0);
+    if (position === 'tail')
+        return matchAt(chars.length - 1);
+    if (position === 'mid') {
+        for (let i = 1; i < chars.length - 1; i++)
+            if (matchAt(i))
+                return true;
+        return false;
+    }
+    for (let i = 0; i < chars.length; i++)
+        if (matchAt(i))
+            return true;
+    return false;
+}
+/**
+ * @public 문자열이 음절 패턴 DSL 문법인지 — 쉼표(,) 포함 여부로 판별한다.
+ * 일반 단어 검색어엔 쉼표가 쓰이지 않으므로 충돌 없이 자동 분기할 수 있다.
+ */
+export function isSyllablePattern(query) {
+    // 쉼표(음절 구분) 또는 밑줄(초성·중성·종성 템플릿의 '무관' 자리 '_')이 있으면 패턴 DSL로 라우팅한다.
+    // '_'는 완성 단어에 없는 문자라 일반 부분문자열 검색으로는 늘 0건 — 쉼표 없이 쓴 3자모 템플릿('ㄱ_ㄱ')도
+    // 패턴으로 인식해야 한다(예: 'ㄱ_ㄱ' → 1음절, 초성 ㄱ·종성 ㄱ·중성 무관 = 각/국/곡…).
+    return query.includes(',') || query.includes('_');
+}
+// 쉼표로 나눈 한 조각(청크)을 자리(atom) 목록으로 푼다.
+//  - 빈 청크 → 무관 자리 1개.
+//  - '_'가 하나라도 있으면 → 한 음절 템플릿 1개(초성·중성·종성 순, 1~3자). 생략한 뒤 자리와 '_'는 무관.
+//    예: '__ㄱ'=종성ㄱ, 'ㄱ_'=초성ㄱ(중성·종성 무관), '_ㅏ'=중성ㅏ, 'ㄱ_ㄱ'=초성ㄱ·종성ㄱ.
+//  - '_'가 없으면 → 한 글자씩 잘라 각각 한 자리로(완성 음절/초성/중성). 예: '가ㄴ'→'가' 자리 + 초성 'ㄴ' 자리.
+// 해석 불가한 글자는 invalid 자리 — 항상 매칭 실패해 제약이 조용히 무시되지 않게 한다.
+function parseChunkToAtoms(chunk) {
+    if (chunk === '')
+        return [{ kind: 'any' }];
+    if (chunk.includes('_')) {
+        // 한 음절 템플릿: 초성(1) + 중성(1) + 종성(0~2, 겹받침은 2자모). 최대 4자모.
+        const arr = [...chunk];
+        if (arr.length > 4)
+            return [{ kind: 'invalid' }];
+        const cho = arr[0] ?? '_';
+        const jung = arr[1] ?? '_';
+        let jong = arr.slice(2).join(''); // '', 단일 종성, 또는 겹받침 2자모('ㄹㄱ')
+        if (jong.length === 2) {
+            const combined = COMPOUND_JONG[jong]; // 'ㄹㄱ' → 'ㄺ'
+            if (!combined)
+                return [{ kind: 'invalid' }];
+            jong = combined;
+        }
+        return [{ kind: 'template', cho, jung, jong: jong || '_' }];
+    }
+    return [...chunk].map((ch) => {
+        if (parseSyllable(ch))
+            return { kind: 'syllable', ch };
+        if (CHOSEONG.includes(ch))
+            return { kind: 'cho', jamo: ch };
+        if (JUNGSEONG.includes(ch))
+            return { kind: 'jung', jamo: ch };
+        return { kind: 'invalid' };
+    });
+}
+function matchesPatternAtom(ch, atom) {
+    switch (atom.kind) {
+        case 'any': return true;
+        case 'syllable': {
+            const qs = parseSyllable(atom.ch);
+            if (!qs)
+                return ch === atom.ch;
+            if (qs.jong === 0) {
+                // 받침 없는 완성형은 초성+중성만 비교(받침 무관): '수' → 수·술·숙 …
+                const s = parseSyllable(ch);
+                return !!s && s.cho === qs.cho && s.jung === qs.jung;
+            }
+            return ch === atom.ch; // 받침 있으면 정확 일치
+        }
+        case 'cho': {
+            const s = parseSyllable(ch);
+            return !!s && CHOSEONG[s.cho] === atom.jamo;
+        }
+        case 'jung': {
+            const s = parseSyllable(ch);
+            return !!s && JUNGSEONG[s.jung] === atom.jamo;
+        }
+        case 'template': {
+            const s = parseSyllable(ch);
+            if (!s)
+                return false;
+            if (atom.cho !== '_' && CHOSEONG[s.cho] !== atom.cho)
+                return false;
+            if (atom.jung !== '_' && JUNGSEONG[s.jung] !== atom.jung)
+                return false;
+            if (atom.jong !== '_' && JONGSEONG[s.jong] !== atom.jong)
+                return false;
+            return true;
+        }
+        case 'invalid': return false;
+    }
+}
+/**
+ * @public 음절 패턴 미니 DSL 매칭. 쉼표(,)로 나눈 조각을 자리(음절) 단위로 자동 분해하며,
+ * **분해된 총 자리 수는 반드시 단어의 음절 수와 같아야** 매칭된다. 한 자리는 다음 중 하나:
+ *  - 빈 자리(쉼표 사이가 비어 있음) — 무관(아무 음절이나 허용).
+ *  - 완성 음절 한 글자(예: '가') — 그 자리 음절이 정확히 이 글자와 같아야 함.
+ *  - 자음/모음 한 글자(예: 'ㄴ', 'ㅏ') — 자음이면 그 자리 초성이, 모음이면 그 자리 중성이 정확히 그
+ *    자모여야 함(나머지는 무관).
+ *  - 초성·중성·종성 3자모 템플릿(예: '__ㄱ', 쉼표로 나눈 조각이 정확히 3글자일 때만) — 각 자리가 '_'면
+ *    무관, 자모면 그 위치(초성/중성/종성)가 정확히 그 자모여야 함. 종성 자리 '_'는 받침 유무 모두 허용.
+ * 쉼표 사이에 완성 음절·자음·모음을 이어 붙이면(예: '가ㄴ') 한 글자씩 각각 한 음절 자리로 자동 분해된다
+ * (3글자로 붙이면 템플릿과 구분이 안 되므로 예외 — 그 경우는 쉼표로 나눠 쓴다).
+ * 예: '가,,다' → 3음절, 첫 음절 '가' · 가운데 무관 · 끝 음절 '다'.
+ * 예: '__ㄱ,고' → 2음절, 첫 음절 종성이 'ㄱ'(초성·중성 무관) · 끝 음절 '고'.
+ * 예: '가ㄴ,,다'(= '가,ㄴ,,다'와 동일) → 4음절, 첫 음절 '가' · 둘째 음절 초성 'ㄴ' · 셋째 무관 · 넷째 '다'.
+ * 해석할 수 없는 글자(자음·모음·완성 음절이 아님)가 섞이면 그 자리는 항상 매칭 실패 처리되어 결과가
+ * 0건이 된다(조용히 무관 처리하지 않는다 — 제약이 무시된 채 결과가 나오는 오해를 막기 위해).
+ */
+export function matchesSyllablePattern(word, pattern) {
+    const atoms = pattern.split(',').flatMap(chunk => parseChunkToAtoms(chunk.trim()));
+    if (atoms.length === 0)
+        return true;
+    const chars = [...word];
+    if (chars.length < atoms.length)
+        return false;
+    // '포함' 매칭 — 패턴(연속 음절 자리들)이 단어의 어느 위치에서든 연속으로 맞으면 통과.
+    // (단어 음절수 == 패턴 자리수를 요구하지 않는다. 예: '__ㄱ,고' → 첫음절 종성ㄱ+둘째음절 '고'를
+    //  포함한 모든 단어 = 학교·박고구마… 길이 무관.)
+    for (let i = 0; i + atoms.length <= chars.length; i++) {
+        if (atoms.every((atom, j) => matchesPatternAtom(chars[i + j], atom)))
+            return true;
+    }
+    return false;
+}
+/**
+ * @public 음절 패턴 DSL을 대립쌍 생성용 구성요소(초성/중성/종성) 집합으로 축약한다.
+ * 패턴의 모든 자리(atom)가 지정한 초성/중성/종성 자모를 종류별로 합집합(OR)해 돌려준다 —
+ * 훈련 '글자 입력' 모드에서 이 조합을 buildMultiPartPosContrast에 넣어 (위치 지정과 함께)
+ * "그 자리의 해당 음소만 다른 최소대립쌍"을 오답으로 만든다.
+ * 예: 'ㄱ,ㄱ'(연속 초성 ㄱ) → { cho: ['ㄱ'] } → 위치 음절의 초성만 다른 실단어가 오답.
+ *     'ㄱ_ㄱ'(초성 ㄱ·종성 ㄱ) → { cho: ['ㄱ'], jong: ['ㄱ'] }.
+ * 완성 음절 자리('가')는 그 음절의 초성·중성(·종성)을 모두 제약으로 넣는다.
+ * 지정된 음소가 하나도 없으면(무관/무효 자리뿐) null — 호출부는 무작위 오답으로 폴백한다.
+ */
+export function patternToComposition(pattern) {
+    const atoms = pattern.split(',').flatMap(chunk => parseChunkToAtoms(chunk.trim()));
+    const cho = new Set(), jung = new Set(), jong = new Set();
+    for (const atom of atoms) {
+        switch (atom.kind) {
+            case 'cho':
+                cho.add(atom.jamo);
+                break;
+            case 'jung':
+                jung.add(atom.jamo);
+                break;
+            case 'template':
+                if (atom.cho !== '_')
+                    cho.add(atom.cho);
+                if (atom.jung !== '_')
+                    jung.add(atom.jung);
+                if (atom.jong !== '_')
+                    jong.add(atom.jong);
+                break;
+            case 'syllable': {
+                const s = parseSyllable(atom.ch);
+                if (s) {
+                    cho.add(CHOSEONG[s.cho]);
+                    jung.add(JUNGSEONG[s.jung]);
+                    if (s.jong !== 0)
+                        jong.add(JONGSEONG[s.jong]);
+                }
+                break;
+            }
+            // 'any' / 'invalid' 는 음소 제약 없음 — 무시.
+        }
+    }
+    if (cho.size === 0 && jung.size === 0 && jong.size === 0)
+        return null;
+    return {
+        cho: cho.size ? [...cho] : null,
+        jung: jung.size ? [...jung] : null,
+        jong: jong.size ? [...jong] : null,
+    };
+}
+/** 검색 입력에서 한 자리로 쓸 수 있는 글자: 완성 음절 · 초성 자모 · 중성 자모. */
+function isSearchAtomChar(ch) {
+    return !!parseSyllable(ch)
+        || CHOSEONG.includes(ch)
+        || JUNGSEONG.includes(ch);
+}
+/**
+ * @public 단어 검색 '글자 입력'의 형식 유효성 검사.
+ * 허용: 완성 음절('가'), 초성/중성 자모('ㄱ'·'ㅏ'), 초성·중성·종성 3자모 템플릿('__ㄱ', 정확히 3글자),
+ * 쉼표(,) 구분(빈 자리는 '무관'). 그 외(예: '_' 오용, 라틴 문자, 한 자리에 음소 4개 이상인 '___ㄱ')는 무효.
+ * @returns 유효하면 `{ ok: true }`, 아니면 `{ ok: false }`(호출부가 안내 문구를 표시).
+ */
+export function validateSyllableSearchInput(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return { ok: true };
+    for (const raw of trimmed.split(',')) {
+        const chunk = raw.trim();
+        if (chunk === '')
+            continue; // 쉼표 사이 빈 자리 = '무관'
+        if (chunk.includes('_')) {
+            // '_' 있으면 한 음절 템플릿(초성·중성·종성 순). 종성은 겹받침(2자모)까지 허용 — 최대 4자모.
+            const arr = [...chunk];
+            if (arr.length > 4)
+                return { ok: false };
+            const a = arr[0], b = arr[1], jong = arr.slice(2).join('');
+            const okCho = a === undefined || a === '_' || CHOSEONG.includes(a);
+            const okJung = b === undefined || b === '_' || JUNGSEONG.includes(b);
+            const okJong = jong === '' || jong === '_'
+                || JONGSEONG.filter(Boolean).includes(jong) // 단일(겹받침 원형 포함)
+                || !!COMPOUND_JONG[jong]; // 2자모 겹받침('ㄹㄱ')
+            if (okCho && okJung && okJong)
+                continue;
+            return { ok: false };
+        }
+        // '_' 없으면 각 글자가 완성 음절/초성/중성이어야 한다(기타 문자는 무효).
+        if (![...chunk].every(isSearchAtomChar))
+            return { ok: false };
+    }
+    return { ok: true };
+}
+const PART_DIM = {
+    cho: CHOSEONG.length, // 19
+    jung: JUNGSEONG.length, // 21
+    jong: JONGSEONG.length, // 28
+};
+/**
+ * @public
+ * 정확히 `count`개 음절에서 지정 구성요소(초성/중성/종성)만 다르고 나머지 성분은 완전히 동일한
+ * 실제 단어들을 찾는다. (compose-and-check 방식 — wordSet 멤버십으로 실재 단어만 반환)
+ *
+ * 예: findTypedContrastWords('가수', 'jung', 2, set) → ['개시','고소','기사', …] (모음 2곳 차이)
+ *
+ * @param word     기준 단어
+ * @param type     대립 종류 (cho/jung/jong)
+ * @param count    차이 나는 음절 수 (대립 갯수)
+ * @param wordSet  유효 단어 집합 (여기 포함된 단어만 결과에 포함)
+ * @param limit    최대 결과 수 (조기 종료로 연산량 제한, 기본 Infinity)
+ */
+export function findTypedContrastWords(word, type, count, wordSet, limit = Infinity) {
+    if (!word || count < 1)
+        return [];
+    const parsed = [...word].map(ch => parseSyllable(ch));
+    if (parsed.some(s => !s))
+        return [];
+    const syls = parsed;
+    const k = syls.length;
+    if (count > k)
+        return [];
+    const dim = PART_DIM[type];
+    const results = new Set();
+    // 차이 낼 음절 위치 조합 C(k, count)
+    const positions = [];
+    (function pick(start, acc) {
+        if (acc.length === count) {
+            positions.push([...acc]);
+            return;
+        }
+        for (let i = start; i < k; i++) {
+            acc.push(i);
+            pick(i + 1, acc);
+            acc.pop();
+        }
+    })(0, []);
+    for (const combo of positions) {
+        // combo 위치들의 type 성분을 서로 다른 값으로 변화, 나머지는 원본 유지
+        ;
+        (function vary(idx, cur) {
+            if (results.size >= limit)
+                return;
+            if (idx === combo.length) {
+                const w = cur.map(s => composeSyllable(s.cho, s.jung, s.jong)).join('');
+                if (w !== word && wordSet.has(w))
+                    results.add(w);
+                return;
+            }
+            const p = combo[idx];
+            const orig = syls[p][type];
+            for (let v = 0; v < dim; v++) {
+                if (v === orig)
+                    continue;
+                const next = cur.slice();
+                next[p] = { ...cur[p], [type]: v };
+                vary(idx + 1, next);
+                if (results.size >= limit)
+                    return;
+            }
+        })(0, syls);
+        if (results.size >= limit)
+            break;
+    }
+    return [...results];
+}
+/**
+ * @public
+ * 위치 구분 없이 두 단어의 서로 다른 음소(초성/중성/종성 슬롯) 총 개수를 센다.
+ * 음절 수가 다르거나 한글이 아닌 문자가 있으면 -1.
+ * 예: countPhonemeDiff('독립','독일') → 2 (둘째 음절 초성 ㄹ↔ㅇ, 종성 ㅂ↔ㄹ)
+ */
+export function countPhonemeDiff(a, b) {
+    if (!a || !b || a.length !== b.length)
+        return -1;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        const sa = parseSyllable(a[i]);
+        const sb = parseSyllable(b[i]);
+        if (!sa || !sb)
+            return -1;
+        if (sa.cho !== sb.cho)
+            diff++;
+        if (sa.jung !== sb.jung)
+            diff++;
+        if (sa.jong !== sb.jong)
+            diff++;
+    }
+    return diff;
+}
+/**
+ * 단어 목록을 검색어로 거르고, 앞에서부터 맞는 것을 위로 올린다.
+ *
+ * 회원 앱의 '단어 관리'와 어드민의 '데이터 → 단어'가 이 규칙을 각자 한 벌씩 적고
+ * 있었다. 주석까지 서로를 가리키고 있었는데("회원 앱 '단어 관리'와 같은 매칭 규칙",
+ * "단어표 '글자 입력'과 동일 규약") — 알면서 베낀 것이다. 한쪽만 고치면 두 화면이
+ * 같은 검색어에 다른 결과를 내놓는다.
+ *
+ * 규칙은 셋이다.
+ *  · **의미 없는 입력은 조건으로 보지 않는다.** 공백·쉼표·밑줄만 남은 것은 아직 다
+ *    치지 않은 패턴이라, 그걸로 거르면 목록이 통째로 빈다.
+ *  · **패턴 DSL 이면 자리 맞춤으로 본다**('ㄱ_ㄱ' 처럼). 아니면 초성·완성음절+초성·
+ *    부분문자열을 모두 받는 공용 매칭으로 본다.
+ *  · **앞에서부터 맞는 것을 위로.** '나'로 찾을 때 '가시나무'가 먼저 나오면 '나무'가
+ *    묻힌다. 앞 글자 수만큼 잘라 맞춰 보면 '첫 음절부터 일치'만 남는다(초성도 같다).
+ *    같은 순위 안에서는 원래 순서를 지킨다 — Array.sort 가 안정 정렬이다.
+ *
+ * @param items 거를 목록 — 단어와 발음을 가진 것이면 무엇이든
+ * @param query 사용자가 친 검색어(다듬지 않은 것을 그대로 넘겨도 된다)
+ * @public
+ */
+export function searchAndRankWords(items, query) {
+    const q = query.trim();
+    if (!q || !/[^\s,_]/.test(q))
+        return items;
+    if (isSyllablePattern(q))
+        return items.filter(w => matchesSyllablePattern(w.word, q));
+    const hit = items.filter(w => matchesWordQuery(w.word, q) || matchesWordQuery(w.pronunciation ?? '', q));
+    const headLen = [...q].length;
+    const startsWith = (s) => !!s && matchesWordQuery(s.slice(0, headLen), q);
+    return hit
+        .map(w => ({ w, rank: (startsWith(w.word) || startsWith(w.pronunciation ?? '')) ? 0 : 1 }))
+        .sort((a, b) => a.rank - b.rank)
+        .map(s => s.w);
+}

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

@@ -0,0 +1,16 @@
+import type { ComponentType } from 'react';
+/**
+ * 정적으로 번들되는 아이콘 목록.
+ *
+ * 이 목록은 speechear·kscan 소스의 icon 리터럴(`icon="..."`, `icon: '...'`)을
+ * 훑어 만들었습니다. **여기 없는 이름은 지연 로드됩니다** — 화면에는 결국
+ * 나오지만 첫 렌더에는 잠깐 비어 보입니다. 새 아이콘을 쓰기 시작했는데
+ * 유독 그것만 늦게 뜬다면 이 목록에 추가하세요.
+ *
+ * 왜 이렇게 하는가: 예전에는 `import * as lucide from 'lucide-react'` 로
+ * 통째로 가져와 이름으로 조회했습니다. 그러면 어떤 이름이든 들어올 수 있으니
+ * 번들러가 아이콘을 하나도 떨궈내지 못합니다 — 소비 앱 청크 하나에 아이콘
+ * 모듈 1767개, JS 전송량 6.8MB 가 실렸습니다. 이름을 하나씩 적어 두면
+ * tree-shaking 이 동작합니다.
+ */
+export declare const STATIC_LUCIDE_ICONS: Record<string, ComponentType<Record<string, unknown>>>;